From e3ef5b00854e1df63e9d62972c589469152bce3c Mon Sep 17 00:00:00 2001
From: Titouan Mathis <titouan@studiometa.fr>
Date: Thu, 13 Aug 2026 14:44:15 +0000
Subject: [PATCH 1/4] Improve the ambient MotionView stories

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FVXrJ8idMfvt667yJadvB8
---
 .../reference/items/MotionView/examples.md    |  4 +--
 .../stories/ambient-bind-if/app.twig          | 29 ++++++++++---------
 .../stories/ambient-dialog/app.twig           | 23 ++++++++++-----
 3 files changed, 32 insertions(+), 24 deletions(-)

diff --git a/packages/docs/reference/items/MotionView/examples.md b/packages/docs/reference/items/MotionView/examples.md
index 3ef32ace..7188b767 100644
--- a/packages/docs/reference/items/MotionView/examples.md
+++ b/packages/docs/reference/items/MotionView/examples.md
@@ -27,7 +27,7 @@ title: MotionView examples
 
 ## Zero-wiring exit animation for `data-bind:if`
 
-[Ambient wiring](./js-api#ambient-wiring) in action: the `MotionView` has no wiring attribute at all — it wraps the `dom-update` event that [`data-bind:if`](/reference/items/DataBind/js-api#conditional-rendering-with-data-bind-if) announces before changing the DOM, so the template content animates in **and out**, even though the removed nodes are already gone when the exit plays. The `layout` option morphs the container's size with a spring.
+[Ambient wiring](./js-api#ambient-wiring) in action: the `MotionView` has no wiring attribute at all — it wraps the `dom-update` event that [`data-bind:if`](/reference/items/DataBind/js-api#conditional-rendering-with-data-bind-if) announces before changing the DOM, so the template content animates in **and out**, even though the removed nodes are already gone when the exit plays. The `layout` option morphs the container's size with a spring. Because the event bubbles, the `MotionView` only needs to sit just outside the `<template>` instead of around the whole widget: the morph then hugs the panel region alone and leaves the checkbox above it out of the transition.
 
 <llm-exclude>
   <PreviewPlayground
@@ -48,7 +48,7 @@ title: MotionView examples
 
 ## Ambient view transitions in a `Dialog`
 
-The same containment story with [`Dialog`](/reference/items/Dialog/): nested inside it, the `MotionView` joins the bubbling `open`/`close` lifecycle by itself — the dialog calls its `enter()`/`leave()` through `waitUntil()` and stays painted until the spring view transition settles. Compare with the [explicit `Motion` wiring](/reference/items/Motion/examples#spring-entrance-and-exit-for-a-dialog): same result, zero attributes.
+The same containment story with [`Dialog`](/reference/items/Dialog/): nested inside it, a `MotionView` joins the bubbling `open`/`close` lifecycle by itself — the dialog calls its `enter()`/`leave()` through `waitUntil()` and stays painted until the view transition settles. Two instances share the same lifecycle here, the backdrop fading and the box springing in, because `waitUntil()` is additive: every transitioner that registers on the event is awaited, so any number of them can animate one dialog without ever knowing about each other. Compare with the [explicit `Motion` wiring](/reference/items/Motion/examples#spring-entrance-and-exit-for-a-dialog): same result, zero attributes.
 
 <llm-exclude>
   <PreviewPlayground
diff --git a/packages/docs/reference/items/MotionView/stories/ambient-bind-if/app.twig b/packages/docs/reference/items/MotionView/stories/ambient-bind-if/app.twig
index d01dcaf8..40e34fdf 100644
--- a/packages/docs/reference/items/MotionView/stories/ambient-bind-if/app.twig
+++ b/packages/docs/reference/items/MotionView/stories/ambient-bind-if/app.twig
@@ -1,19 +1,20 @@
-{# The MotionView carries no wiring attribute: it ambiently wraps the
-   `dom-update` event that `data-bind:if` announces before changing the DOM,
-   so the insertion AND the removal play as one spring view transition. #}
 <div
-  data-component="MotionView"
-  data-option-transition='{ "type": "spring", "bounce": 0.2 }'
-  data-option-layout
-  class="max-w-sm">
+  data-component="DataScope"
+  data-option-group="ambient-panel"
+  class="grid gap-4 rounded ring p-4 max-w-sm">
+  <label class="flex items-center gap-2">
+    <input type="checkbox" name="details" data-component="DataModel" />
+    <span>Show the details</span>
+  </label>
+  {# The MotionView sits just outside the template, not around the whole
+     widget: the `dom-update` event that `data-bind:if` announces before
+     changing the DOM bubbles up to it, so the insertion AND the removal play
+     as one spring view transition — and the `layout` morph hugs the panel
+     region only, leaving the checkbox above it untouched. #}
   <div
-    data-component="DataScope"
-    data-option-group="ambient-panel"
-    class="grid gap-4 rounded ring p-4">
-    <label class="flex items-center gap-2">
-      <input type="checkbox" name="details" data-component="DataModel" />
-      <span>Show the details</span>
-    </label>
+    data-component="MotionView"
+    data-option-transition='{ "type": "spring", "bounce": 0.2 }'
+    data-option-layout>
     <template data-component="DataBind" data-option-key="details" data-bind:if>
       <p class="p-4 rounded bg-emerald-400/20 ring ring-emerald-400">
         I was inserted inside a view transition — and I animate out too, even
diff --git a/packages/docs/reference/items/MotionView/stories/ambient-dialog/app.twig b/packages/docs/reference/items/MotionView/stories/ambient-dialog/app.twig
index b01d7069..88c95629 100644
--- a/packages/docs/reference/items/MotionView/stories/ambient-dialog/app.twig
+++ b/packages/docs/reference/items/MotionView/stories/ambient-dialog/app.twig
@@ -6,19 +6,24 @@
   Open dialog
 </button>
 
-{# The MotionView box carries no wiring attribute: nested inside the Dialog,
-   it ambiently joins the bubbling `open`/`close` lifecycle — the Dialog calls
-   its `enter()`/`leave()` through `waitUntil()` and stays painted until the
-   view transition finishes. #}
+{# Two MotionView instances, zero wiring attributes: the backdrop and the box
+   both live inside the Dialog, so both ambiently join the bubbling
+   `open`/`close` lifecycle. `waitUntil()` is additive — every transitioner
+   that registers is awaited — so the Dialog calls `enter()`/`leave()` on both
+   and stays painted until the slowest view transition finishes. #}
 <dialog
   id="ambient-modal"
   data-component="Action Dialog"
   data-on:cancel.prevent="Dialog.close()"
   class="fixed inset-0 m-0 p-0 w-full h-full max-w-none max-h-none bg-transparent overflow-y-auto">
   <div
-    data-component="Action"
+    data-component="Action MotionView"
     data-on:click="Dialog(#ambient-modal)->target.close()"
-    class="fixed inset-0 bg-black/50"></div>
+    data-option-view-transition-name="ambient-modal-backdrop"
+    data-option-transition='{ "duration": 0.3 }'
+    data-option-enter-to="opacity-100"
+    data-option-leave-to="opacity-0"
+    class="fixed inset-0 bg-black/50 opacity-0"></div>
 
   <div
     class="pointer-events-none relative flex min-h-full items-center justify-center p-4">
@@ -50,6 +55,8 @@
   dialog::backdrop { background: transparent; }
 
   /* Chromium quirk: a view-transition layer on top-layer content can paint
-  behind the page snapshot mid-transition; lifting the group fixes it. */
-  ::view-transition-group(ambient-modal-box) { z-index: 1; }
+  behind the page snapshot mid-transition; lifting the groups fixes it. Both
+  groups are ordered explicitly so the backdrop stays under the box. */
+  ::view-transition-group(ambient-modal-backdrop) { z-index: 1; }
+  ::view-transition-group(ambient-modal-box) { z-index: 2; }
 </style>

From e5273a5b346b60094ba5dce40757fb4062f87226 Mon Sep 17 00:00:00 2001
From: Titouan Mathis <titouan@studiometa.fr>
Date: Thu, 13 Aug 2026 14:44:15 +0000
Subject: [PATCH 2/4] Add MotionScrollTimeline progress and parallax examples

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FVXrJ8idMfvt667yJadvB8
---
 .../items/MotionScrollTimeline/examples.md    | 42 ++++++++++++++
 .../stories/parallax-layers/app.js            |  4 ++
 .../stories/parallax-layers/app.twig          | 36 ++++++++++++
 .../stories/reading-progress/app.js           |  4 ++
 .../stories/reading-progress/app.twig         | 58 +++++++++++++++++++
 5 files changed, 144 insertions(+)
 create mode 100644 packages/docs/reference/items/MotionScrollTimeline/stories/parallax-layers/app.js
 create mode 100644 packages/docs/reference/items/MotionScrollTimeline/stories/parallax-layers/app.twig
 create mode 100644 packages/docs/reference/items/MotionScrollTimeline/stories/reading-progress/app.js
 create mode 100644 packages/docs/reference/items/MotionScrollTimeline/stories/reading-progress/app.twig

diff --git a/packages/docs/reference/items/MotionScrollTimeline/examples.md b/packages/docs/reference/items/MotionScrollTimeline/examples.md
index f1cccdaa..9e166b6f 100644
--- a/packages/docs/reference/items/MotionScrollTimeline/examples.md
+++ b/packages/docs/reference/items/MotionScrollTimeline/examples.md
@@ -24,3 +24,45 @@ title: MotionScrollTimeline examples
 :::
 
 </llm-only>
+
+## Reading progress bar
+
+The timeline element is the article, and the [`offset`](./js-api#offset) maps progress `0` to its top reaching the top of the viewport and progress `1` to its bottom reaching the bottom — the reading range, rather than the default entering-and-leaving range. The sticky bar holds a single `Motion` child scrubbed from `scaleX: 0` to `scaleX: 1`, which is the cheap way to draw a progress indicator: the browser animates a transform instead of a width, anchored to the left edge by `origin-left`.
+
+<llm-exclude>
+  <PreviewPlayground
+    :html="() => import('./stories/reading-progress/app.twig')"
+    :script="() => import('./stories/reading-progress/app.js?raw')"
+    />
+</llm-exclude>
+<llm-only>
+
+:::code-group
+
+<<< ./stories/reading-progress/app.twig
+<<< ./stories/reading-progress/app.js
+
+:::
+
+</llm-only>
+
+## Parallax layers
+
+One timeline, one scroll range, three `Motion` children: only the travelled distance changes. The far disc moves 80 pixels, the card 180 and the badge 300 over the same progress, and the speed difference alone reads as depth. The timeline scrubs every child with the same progress, so depth is authored entirely in the keyframes — there is no per-layer speed or offset option to set.
+
+<llm-exclude>
+  <PreviewPlayground
+    :html="() => import('./stories/parallax-layers/app.twig')"
+    :script="() => import('./stories/parallax-layers/app.js?raw')"
+    />
+</llm-exclude>
+<llm-only>
+
+:::code-group
+
+<<< ./stories/parallax-layers/app.twig
+<<< ./stories/parallax-layers/app.js
+
+:::
+
+</llm-only>
diff --git a/packages/docs/reference/items/MotionScrollTimeline/stories/parallax-layers/app.js b/packages/docs/reference/items/MotionScrollTimeline/stories/parallax-layers/app.js
new file mode 100644
index 00000000..610d29d1
--- /dev/null
+++ b/packages/docs/reference/items/MotionScrollTimeline/stories/parallax-layers/app.js
@@ -0,0 +1,4 @@
+import { registerComponents } from '@studiometa/js-toolkit';
+import { MotionScrollTimeline } from '@studiometa/ui-motion';
+
+registerComponents(MotionScrollTimeline);
diff --git a/packages/docs/reference/items/MotionScrollTimeline/stories/parallax-layers/app.twig b/packages/docs/reference/items/MotionScrollTimeline/stories/parallax-layers/app.twig
new file mode 100644
index 00000000..a46a7c7a
--- /dev/null
+++ b/packages/docs/reference/items/MotionScrollTimeline/stories/parallax-layers/app.twig
@@ -0,0 +1,36 @@
+<p class="py-8 text-center text-current/60">
+  Scroll down ↓
+</p>
+
+{# One timeline, one scroll range, three Motion children: only the travelled
+   distance differs. The far layer moves the least and the near one the most,
+   so the speed difference alone reads as depth — no per-layer wiring, the
+   timeline scrubs them all with the same progress. #}
+<section data-component="MotionScrollTimeline" class="relative h-[250vh]">
+  <div
+    class="sticky top-0 grid h-screen grid-cols-1 grid-rows-1 place-items-center overflow-hidden">
+    <div
+      data-component="Motion"
+      data-option-animate='{ "y": [80, -80] }'
+      class="col-start-1 row-start-1 size-72 rounded-full bg-blue-400/30 dark:bg-blue-600/30"></div>
+    <div
+      data-component="Motion"
+      data-option-animate='{ "y": [180, -180] }'
+      class="col-start-1 row-start-1 w-64 rounded-lg bg-white p-6 text-black shadow-2xl dark:bg-zinc-100">
+      <h2 class="text-xl font-bold">Parallax layers</h2>
+      <p class="mt-2 text-black/60">
+        Same range, three speeds.
+      </p>
+    </div>
+    <div
+      data-component="Motion"
+      data-option-animate='{ "y": [300, -300] }'
+      class="col-start-1 row-start-1 mt-56 ml-56 rounded-full bg-emerald-400 px-4 py-2 font-bold text-white dark:bg-emerald-600">
+      Closest
+    </div>
+  </div>
+</section>
+
+<p class="py-8 text-center text-current/60">
+  Done ↑
+</p>
diff --git a/packages/docs/reference/items/MotionScrollTimeline/stories/reading-progress/app.js b/packages/docs/reference/items/MotionScrollTimeline/stories/reading-progress/app.js
new file mode 100644
index 00000000..610d29d1
--- /dev/null
+++ b/packages/docs/reference/items/MotionScrollTimeline/stories/reading-progress/app.js
@@ -0,0 +1,4 @@
+import { registerComponents } from '@studiometa/js-toolkit';
+import { MotionScrollTimeline } from '@studiometa/ui-motion';
+
+registerComponents(MotionScrollTimeline);
diff --git a/packages/docs/reference/items/MotionScrollTimeline/stories/reading-progress/app.twig b/packages/docs/reference/items/MotionScrollTimeline/stories/reading-progress/app.twig
new file mode 100644
index 00000000..e6cd2c7e
--- /dev/null
+++ b/packages/docs/reference/items/MotionScrollTimeline/stories/reading-progress/app.twig
@@ -0,0 +1,58 @@
+{# The article itself is the timeline, and the `offset` maps progress 0 to its
+   top reaching the top of the viewport and progress 1 to its bottom reaching
+   the bottom — the reading range. The single Motion child inside the sticky
+   bar is scrubbed by that progress, so its scaleX track reads as the share of
+   the article already scrolled. #}
+<section
+  data-component="MotionScrollTimeline"
+  data-option-offset='["start start", "end end"]'
+  class="relative">
+  <div class="sticky top-0 h-1.5 bg-zinc-200 dark:bg-zinc-800">
+    <div
+      data-component="Motion"
+      data-option-animate='{ "scaleX": [0, 1] }'
+      class="h-full origin-left bg-blue-500 dark:bg-blue-400"></div>
+  </div>
+
+  <article class="mx-auto max-w-xl px-6 py-16 flex flex-col gap-6">
+    <h2 class="text-3xl font-bold">Reading progress</h2>
+    <p>
+      Scroll this article: the bar above sticks to the top of the section and
+      fills from left to right as the content goes by. Nothing listens to the
+      scroll event — the timeline binds the bar to the scroll position once, on
+      mount.
+    </p>
+    <p>
+      The bar is a plain <code>Motion</code> child. It declares a single
+      <code>scaleX</code> track from 0 to 1, keeps its
+      <code>autoplay</code> off, and the timeline takes over its playback: the animation
+      never runs on its own clock, it is scrubbed.
+    </p>
+    <p>
+      Scaling is the cheap way to draw a progress bar: the browser animates a
+      transform instead of a width, and the
+      <code>origin-left</code> class anchors the growth to the left edge.
+    </p>
+    <p>
+      The default <code>offset</code> would start the bar as soon as the section enters
+      the viewport from the bottom, so the bar would already be part-filled on the
+      first paint. The
+      <code>["start start", "end end"]</code> range instead follows the section's
+      own scroll, which is what a reader expects from a progress indicator.
+    </p>
+    <p>
+      Any number of children can share the same timeline. A second
+      <code>Motion</code> could fade a "back to top" button in over the last part
+      of the range, without a single line of JavaScript.
+    </p>
+    <p>
+      Where the browser supports <code>ScrollTimeline</code>, the link is
+      hardware-accelerated and runs off the main thread; elsewhere Motion falls
+      back to a scroll listener with the same result.
+    </p>
+    <p>
+      The link is released when the timeline is destroyed, so a section that
+      leaves the page leaves nothing behind.
+    </p>
+  </article>
+</section>

From 3c34b7a9a4d80dce12bbc59602de20b48c517669 Mon Sep 17 00:00:00 2001
From: Titouan Mathis <titouan@studiometa.fr>
Date: Thu, 13 Aug 2026 14:44:15 +0000
Subject: [PATCH 3/4] Add a MotionSequence hero intro example

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FVXrJ8idMfvt667yJadvB8
---
 .../items/MotionSequence/examples.md          | 21 ++++++++
 .../MotionSequence/stories/hero-intro/app.js  |  4 ++
 .../stories/hero-intro/app.twig               | 48 +++++++++++++++++++
 3 files changed, 73 insertions(+)
 create mode 100644 packages/docs/reference/items/MotionSequence/stories/hero-intro/app.js
 create mode 100644 packages/docs/reference/items/MotionSequence/stories/hero-intro/app.twig

diff --git a/packages/docs/reference/items/MotionSequence/examples.md b/packages/docs/reference/items/MotionSequence/examples.md
index 589c04be..7fdbd55b 100644
--- a/packages/docs/reference/items/MotionSequence/examples.md
+++ b/packages/docs/reference/items/MotionSequence/examples.md
@@ -24,3 +24,24 @@ title: MotionSequence examples
 :::
 
 </llm-only>
+
+## Hero intro on mount
+
+A badge, a heading, a paragraph and a button entering as one choreography: `data-option-autoplay` goes on the sequence, never on the children, because the sequence owns their playback. The three positioning modes are mixed in one timeline — the badge and the heading follow one another in DOM order, the paragraph starts _with_ the heading through [`data-option-at="<"`](./js-api#at-on-the-children), and the button overlaps the end of the paragraph with the relative offset `data-option-at="-0.2"`. Each child keeps its own `initial`/`animate` keyframes and its own spring.
+
+<llm-exclude>
+  <PreviewPlayground
+    :html="() => import('./stories/hero-intro/app.twig')"
+    :script="() => import('./stories/hero-intro/app.js?raw')"
+    />
+</llm-exclude>
+<llm-only>
+
+:::code-group
+
+<<< ./stories/hero-intro/app.twig
+<<< ./stories/hero-intro/app.js
+
+:::
+
+</llm-only>
diff --git a/packages/docs/reference/items/MotionSequence/stories/hero-intro/app.js b/packages/docs/reference/items/MotionSequence/stories/hero-intro/app.js
new file mode 100644
index 00000000..18fa1eea
--- /dev/null
+++ b/packages/docs/reference/items/MotionSequence/stories/hero-intro/app.js
@@ -0,0 +1,4 @@
+import { registerComponents } from '@studiometa/js-toolkit';
+import { MotionSequence } from '@studiometa/ui-motion';
+
+registerComponents(MotionSequence);
diff --git a/packages/docs/reference/items/MotionSequence/stories/hero-intro/app.twig b/packages/docs/reference/items/MotionSequence/stories/hero-intro/app.twig
new file mode 100644
index 00000000..f60f0c4d
--- /dev/null
+++ b/packages/docs/reference/items/MotionSequence/stories/hero-intro/app.twig
@@ -0,0 +1,48 @@
+{# One choreography, played on mount: `data-option-autoplay` belongs to the
+   sequence, never to the children — the sequence owns their playback. The
+   badge and the heading follow one another in DOM order, the paragraph joins
+   the heading with `data-option-at="<"`, and the button overlaps the end of
+   the paragraph with the relative offset `data-option-at="-0.2"`. #}
+<div
+  data-component="MotionSequence"
+  data-option-autoplay
+  class="grid max-w-xl justify-items-start gap-4 rounded-lg p-8 ring">
+  <span
+    data-component="Motion"
+    data-option-initial='{ "opacity": 0, "scale": 0.8 }'
+    data-option-animate='{ "opacity": 1, "scale": 1 }'
+    data-option-transition='{ "type": "spring", "bounce": 0.5 }'
+    class="rounded-full bg-emerald-400/20 px-3 py-1 text-sm font-bold text-emerald-700 ring ring-emerald-400 dark:text-emerald-300">
+    New
+  </span>
+
+  <h2
+    data-component="Motion"
+    data-option-initial='{ "opacity": 0, "y": 24 }'
+    data-option-animate='{ "opacity": 1, "y": 0 }'
+    data-option-transition='{ "type": "spring", "bounce": 0.2 }'
+    class="text-3xl font-bold">
+    Animate the whole hero as one timeline
+  </h2>
+
+  <p
+    data-component="Motion"
+    data-option-initial='{ "opacity": 0, "y": 16 }'
+    data-option-animate='{ "opacity": 1, "y": 0 }'
+    data-option-at="<"
+    class="text-current/70">
+    This paragraph starts with the heading, not after it: <code>"&lt;"</code>
+    positions a segment at the start of the previous one.
+  </p>
+
+  <button
+    type="button"
+    data-component="Motion"
+    data-option-initial='{ "opacity": 0, "y": 12, "scale": 0.9 }'
+    data-option-animate='{ "opacity": 1, "y": 0, "scale": 1 }'
+    data-option-transition='{ "type": "spring", "bounce": 0.4 }'
+    data-option-at="-0.2"
+    class="rounded bg-blue-600 px-4 py-2 font-semibold text-white">
+    Get started
+  </button>
+</div>

From 7c0cebbbbaa708362a280444fbbca64c5a51d123 Mon Sep 17 00:00:00 2001
From: Titouan Mathis <titouan@studiometa.fr>
Date: Thu, 13 Aug 2026 14:53:33 +0000
Subject: [PATCH 4/4] Make the mount animations observable in the doc previews

A preview iframe boots and settles its mount animation before a reader
looks at it, so the basic Motion story and the MotionSequence hero
intro now carry a replay button. Both stories declare their keyframes
as [from, to] arrays: a single target value animates from the current
state, so replaying a settled animation moved nothing. The animate
option documents the distinction.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FVXrJ8idMfvt667yJadvB8
---
 packages/docs/reference/items/Motion/index.md |  2 +-
 .../docs/reference/items/Motion/js-api.md     | 16 ++++++++++
 .../items/Motion/stories/basic/app.js         |  3 +-
 .../items/Motion/stories/basic/app.twig       | 32 ++++++++++++++-----
 .../items/MotionSequence/examples.md          |  2 +-
 .../MotionSequence/stories/hero-intro/app.js  |  3 +-
 .../stories/hero-intro/app.twig               | 20 +++++++++---
 7 files changed, 61 insertions(+), 17 deletions(-)

diff --git a/packages/docs/reference/items/Motion/index.md b/packages/docs/reference/items/Motion/index.md
index c0a4d4b5..8b2d1ccb 100644
--- a/packages/docs/reference/items/Motion/index.md
+++ b/packages/docs/reference/items/Motion/index.md
@@ -14,7 +14,7 @@ The `motion` peer dependency is resolved with a lazy `import()` the first time a
 
 ## Usage
 
-Option values are parsed as JSON, so object keys must be quoted:
+Option values are parsed as JSON, so object keys must be quoted. The animation below plays once on mount, which a preview finishes booting before you look at it — hence the replay button, which calls `play()` to restart it:
 
 <llm-exclude>
 <PreviewPlayground
diff --git a/packages/docs/reference/items/Motion/js-api.md b/packages/docs/reference/items/Motion/js-api.md
index a4fabe63..ceb4c238 100644
--- a/packages/docs/reference/items/Motion/js-api.md
+++ b/packages/docs/reference/items/Motion/js-api.md
@@ -35,6 +35,22 @@ Styles applied to the element on mount, before anything plays. Use it to define
 
 The target keyframes of the animation. They play on mount when [`autoplay`](#autoplay) is enabled.
 
+A single value per property (`{ "opacity": 1 }`) animates from whatever the element currently shows, so replaying a settled animation moves nothing. Write the keyframes as `[from, to]` arrays (`{ "opacity": [0, 1] }`) to pin the starting point, and every [`play()`](#methods) replays the same motion:
+
+<!-- prettier-ignore-start -->
+```html {4}
+<div
+  data-component="Motion"
+  data-option-initial='{ "opacity": 0 }'
+  data-option-animate='{ "opacity": [0, 1] }'
+  data-option-autoplay>
+  …
+</div>
+```
+<!-- prettier-ignore-end -->
+
+Keep [`initial`](#initial) alongside: it paints the starting state before the component mounts, where the keyframes only apply once the animation runs.
+
 ### `transition`
 
 - Type: `AnimationOptions`
diff --git a/packages/docs/reference/items/Motion/stories/basic/app.js b/packages/docs/reference/items/Motion/stories/basic/app.js
index 12443a8b..ddee54e7 100644
--- a/packages/docs/reference/items/Motion/stories/basic/app.js
+++ b/packages/docs/reference/items/Motion/stories/basic/app.js
@@ -1,4 +1,5 @@
 import { registerComponents } from '@studiometa/js-toolkit';
+import { Action } from '@studiometa/ui';
 import { Motion } from '@studiometa/ui-motion';
 
-registerComponents(Motion);
+registerComponents(Action, Motion);
diff --git a/packages/docs/reference/items/Motion/stories/basic/app.twig b/packages/docs/reference/items/Motion/stories/basic/app.twig
index 42dd958a..9b874660 100644
--- a/packages/docs/reference/items/Motion/stories/basic/app.twig
+++ b/packages/docs/reference/items/Motion/stories/basic/app.twig
@@ -1,9 +1,25 @@
-<div
-  data-component="Motion"
-  data-option-initial='{ "opacity": 0, "y": 24, "scale": 0.9 }'
-  data-option-animate='{ "opacity": 1, "y": 0, "scale": 1 }'
-  data-option-transition='{ "type": "spring", "bounce": 0.3, "duration": 0.8 }'
-  data-option-autoplay
-  class="px-6 py-4 rounded-lg bg-blue-400 dark:bg-blue-600 text-white font-bold">
-  Hello, I animate on mount!
+{# The animation plays once, on mount. A preview boots before you look at it,
+   so the story pairs it with a replay button. The keyframes are written as
+   `[from, to]` arrays on purpose: a single target value would animate from
+   whatever the element currently shows, so a replay of a settled animation
+   would have nothing to move. #}
+<div class="grid justify-items-start gap-4">
+  <div
+    id="basic-box"
+    data-component="Motion"
+    data-option-initial='{ "opacity": 0, "y": 24, "scale": 0.9 }'
+    data-option-animate='{ "opacity": [0, 1], "y": [24, 0], "scale": [0.9, 1] }'
+    data-option-transition='{ "type": "spring", "bounce": 0.3, "duration": 0.8 }'
+    data-option-autoplay
+    class="rounded-lg bg-blue-400 px-6 py-4 font-bold text-white dark:bg-blue-600">
+    Hello, I animate on mount!
+  </div>
+
+  <button
+    type="button"
+    data-component="Action"
+    data-on:click="Motion(#basic-box)->target.play()"
+    class="rounded bg-zinc-200 px-4 py-2 dark:bg-zinc-800">
+    Replay
+  </button>
 </div>
diff --git a/packages/docs/reference/items/MotionSequence/examples.md b/packages/docs/reference/items/MotionSequence/examples.md
index 7fdbd55b..d6737e1d 100644
--- a/packages/docs/reference/items/MotionSequence/examples.md
+++ b/packages/docs/reference/items/MotionSequence/examples.md
@@ -27,7 +27,7 @@ title: MotionSequence examples
 
 ## Hero intro on mount
 
-A badge, a heading, a paragraph and a button entering as one choreography: `data-option-autoplay` goes on the sequence, never on the children, because the sequence owns their playback. The three positioning modes are mixed in one timeline — the badge and the heading follow one another in DOM order, the paragraph starts _with_ the heading through [`data-option-at="<"`](./js-api#at-on-the-children), and the button overlaps the end of the paragraph with the relative offset `data-option-at="-0.2"`. Each child keeps its own `initial`/`animate` keyframes and its own spring.
+A badge, a heading, a paragraph and a button entering as one choreography: `data-option-autoplay` goes on the sequence, never on the children, because the sequence owns their playback. The three positioning modes are mixed in one timeline — the badge and the heading follow one another in DOM order, the paragraph starts _with_ the heading through [`data-option-at="<"`](./js-api#at-on-the-children), and the button overlaps the end of the paragraph with the relative offset `data-option-at="-0.2"`. Each child keeps its own `initial`/`animate` keyframes and its own spring. A mount animation is over before a reader reaches the preview, so the replay button restarts the whole choreography with a single `play()` on the sequence.
 
 <llm-exclude>
   <PreviewPlayground
diff --git a/packages/docs/reference/items/MotionSequence/stories/hero-intro/app.js b/packages/docs/reference/items/MotionSequence/stories/hero-intro/app.js
index 18fa1eea..b74d14a1 100644
--- a/packages/docs/reference/items/MotionSequence/stories/hero-intro/app.js
+++ b/packages/docs/reference/items/MotionSequence/stories/hero-intro/app.js
@@ -1,4 +1,5 @@
 import { registerComponents } from '@studiometa/js-toolkit';
+import { Action } from '@studiometa/ui';
 import { MotionSequence } from '@studiometa/ui-motion';
 
-registerComponents(MotionSequence);
+registerComponents(Action, MotionSequence);
diff --git a/packages/docs/reference/items/MotionSequence/stories/hero-intro/app.twig b/packages/docs/reference/items/MotionSequence/stories/hero-intro/app.twig
index f60f0c4d..fbc16e69 100644
--- a/packages/docs/reference/items/MotionSequence/stories/hero-intro/app.twig
+++ b/packages/docs/reference/items/MotionSequence/stories/hero-intro/app.twig
@@ -2,15 +2,17 @@
    sequence, never to the children — the sequence owns their playback. The
    badge and the heading follow one another in DOM order, the paragraph joins
    the heading with `data-option-at="<"`, and the button overlaps the end of
-   the paragraph with the relative offset `data-option-at="-0.2"`. #}
+   the paragraph with the relative offset `data-option-at="-0.2"`. The replay
+   button below drives the whole timeline with a single `play()`. #}
 <div
+  id="hero-sequence"
   data-component="MotionSequence"
   data-option-autoplay
   class="grid max-w-xl justify-items-start gap-4 rounded-lg p-8 ring">
   <span
     data-component="Motion"
     data-option-initial='{ "opacity": 0, "scale": 0.8 }'
-    data-option-animate='{ "opacity": 1, "scale": 1 }'
+    data-option-animate='{ "opacity": [0, 1], "scale": [0.8, 1] }'
     data-option-transition='{ "type": "spring", "bounce": 0.5 }'
     class="rounded-full bg-emerald-400/20 px-3 py-1 text-sm font-bold text-emerald-700 ring ring-emerald-400 dark:text-emerald-300">
     New
@@ -19,7 +21,7 @@
   <h2
     data-component="Motion"
     data-option-initial='{ "opacity": 0, "y": 24 }'
-    data-option-animate='{ "opacity": 1, "y": 0 }'
+    data-option-animate='{ "opacity": [0, 1], "y": [24, 0] }'
     data-option-transition='{ "type": "spring", "bounce": 0.2 }'
     class="text-3xl font-bold">
     Animate the whole hero as one timeline
@@ -28,7 +30,7 @@
   <p
     data-component="Motion"
     data-option-initial='{ "opacity": 0, "y": 16 }'
-    data-option-animate='{ "opacity": 1, "y": 0 }'
+    data-option-animate='{ "opacity": [0, 1], "y": [16, 0] }'
     data-option-at="<"
     class="text-current/70">
     This paragraph starts with the heading, not after it: <code>"&lt;"</code>
@@ -39,10 +41,18 @@
     type="button"
     data-component="Motion"
     data-option-initial='{ "opacity": 0, "y": 12, "scale": 0.9 }'
-    data-option-animate='{ "opacity": 1, "y": 0, "scale": 1 }'
+    data-option-animate='{ "opacity": [0, 1], "y": [12, 0], "scale": [0.9, 1] }'
     data-option-transition='{ "type": "spring", "bounce": 0.4 }'
     data-option-at="-0.2"
     class="rounded bg-blue-600 px-4 py-2 font-semibold text-white">
     Get started
   </button>
 </div>
+
+<button
+  type="button"
+  data-component="Action"
+  data-on:click="MotionSequence(#hero-sequence)->target.play()"
+  class="mt-4 rounded bg-zinc-200 px-4 py-2 dark:bg-zinc-800">
+  Replay the sequence
+</button>