css-motion-library 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Rico and CSS Motion Library contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
+# CSS Motion Library
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/Andrewrico/css-motion-library/actions/workflows/ci.yml/badge.svg)](https://github.com/Andrewrico/css-motion-library/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/css-motion-library.svg)](https://www.npmjs.com/package/css-motion-library)
+[![License: MIT](https://img.shields.io/badge/license-MIT-black.svg)](LICENSE)
+
+**Copy-paste CSS animations with a tiny, accessible playback controller.**
+No framework, no build step, no runtime dependencies.
+
+**[Live gallery →](https://andrewrico.github.io/css-motion-library/)**
+
+- **Pure CSS motion.** Every visual is HTML, CSS keyframes and inline SVG. No video files,
+  no web fonts, no animation engine.
+- **Video-style controls when you want them.** A 6 KB, dependency-free ES module (`src/player.js`) adds
+  pause, replay, seeking and playback speed to any CSS animation timeline.
+- **Accessible by default.** Each entry has a readable static version for reduced motion
+  and no-JavaScript, pauses when offscreen or in a background tab, and has no flashing.
+- **Copy one thing.** Each entry is self-contained: one HTML snippet, one CSS file.
+
+## The collection
+
+| # | Entry | What it is | Loop |
+|---|---|---|---|
+| 001 | [Commerce Storyboard](examples/001-commerce-storyboard/) | Four illustrated process steps with restrained transitions | 24s |
+| 002 | [Commerce Film](examples/002-commerce-film/) | Six-shot cinematic sequence: kinetic type, wipes, camera moves | 30s |
+| 003 | [Kinetic Headline](examples/003-kinetic-headline/) | Masked word-by-word hero headline with a hand-drawn underline | 8s |
+| 004 | [Loading States](examples/004-loading-states/) | Skeleton shimmer, progress, bouncing dots, spinner → check | 6s |
+| 005 | [Orbit Diagram](examples/005-orbit-diagram/) | Explainer diagram: satellites orbit a core and highlight in turn | 12s |
+
+Each entry folder has a README with its timeline, theme variables and customization notes.
+[`catalog.json`](catalog.json) is the machine-readable index.
+
+## Install
+
+Copy files straight from this repo, or install from npm:
+
+```sh
+npm install css-motion-library
+```
+
+```js
+import {createMotionPlayer} from 'css-motion-library/player.js';
+import 'css-motion-library/examples/003-kinetic-headline/animation.css'; // with a CSS-aware bundler
+```
+
+## Use an animation
+
+1. Copy the entry's component markup (the `<section data-motion-player>` block) from its
+   `index.html`, plus its `animation.css`.
+2. Copy [`src/player.js`](src/player.js) and start it:
+
+```html
+<link rel="stylesheet" href="animation.css">
+<!-- …the entry's <section data-motion-player> markup… -->
+<script type="module">
+  import {createMotionPlayer} from './player.js';
+  document.querySelectorAll('[data-motion-player]').forEach(createMotionPlayer);
+</script>
+```
+
+3. Change the copy in the HTML and the colors through the custom properties listed in the
+   entry README (for example `--ink`, `--accent`).
+
+Entry 001 uses its own small inline script instead of the shared player; see its README.
+
+### Player API
+
+```js
+const player = createMotionPlayer(element); // returns null if the browser lacks support
+player.play();
+player.pause();
+player.seek(4.5);      // seconds
+player.restart();
+player.currentTime;    // seconds
+player.playing;        // boolean
+player.destroy();      // removes listeners and restores the static state
+```
+
+The player reads `data-duration` (seconds) from the root and controls every CSS animation
+inside `[data-motion-stage]` as one timeline. It hides its controls and keeps the static
+overview when the user prefers reduced motion or the host sets
+`data-a11y-reduce-motion="true"` on `<html>`. An embedding page can pause an iframe'd entry
+with `postMessage({type: 'css-motion:visibility', visible: false}, origin)` (same origin only).
+
+## Browser support
+
+Current Chrome, Edge, Firefox and Safari. The layouts use container query units (`cqw`) and
+the player uses the Web Animations API (`element.getAnimations()`). Older browsers get the
+static overview.
+
+## Run locally
+
+Requires Node.js 22+. No install needed to view the gallery:
+
+```sh
+npm run dev            # http://127.0.0.1:8092  (PORT=8093 npm run dev to change)
+```
+
+Use HTTP rather than `file://`, because the player is an ES module.
+
+## Checks
+
+```sh
+npm test               # player state, seeking, preferences, lifecycle (Node test runner)
+npm run check          # catalog, links, local assets, JavaScript syntax
+npm install && npx playwright install chromium
+npm run test:browser   # real Chromium: every entry at 1440×900 and 390×844, seeking,
+                       # reduced motion, no-JS, no console errors, no horizontal scroll
+```
+
+CI runs all three on every push and pull request. The gallery deploys to GitHub Pages
+from `main` after CI passes.
+
+## Contribute
+
+New animations are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the entry checklist and
+[DEPENDENCIES.md](DEPENDENCIES.md) before adding any third-party effect. Releases are listed in
+[CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+[MIT](LICENSE) © 2026 Andrew Rico and CSS Motion Library contributors.

package/catalog.json

@@ -0,0 +1,77 @@
+[
+  {
+    "id": "001-commerce-storyboard",
+    "title": "Commerce Storyboard",
+    "description": "Four illustrated steps, gentle transitions and restrained motion.",
+    "duration": 24,
+    "edition": "Original",
+    "entry": "examples/001-commerce-storyboard/index.html",
+    "styles": "examples/001-commerce-storyboard/animation.css",
+    "tags": [
+      "process",
+      "typography",
+      "cards",
+      "CSS"
+    ]
+  },
+  {
+    "id": "002-commerce-film",
+    "title": "Commerce Film",
+    "description": "Six cinematic shots, kinetic type, camera moves and a seekable player.",
+    "duration": 30,
+    "edition": "New",
+    "entry": "examples/002-commerce-film/index.html",
+    "styles": "examples/002-commerce-film/animation.css",
+    "tags": [
+      "cinematic",
+      "typography",
+      "CSS",
+      "timeline"
+    ]
+  },
+  {
+    "id": "003-kinetic-headline",
+    "title": "Kinetic Headline",
+    "description": "Masked word-by-word headline reveal with a hand-drawn underline and CTA.",
+    "duration": 8,
+    "edition": "New",
+    "entry": "examples/003-kinetic-headline/index.html",
+    "styles": "examples/003-kinetic-headline/animation.css",
+    "tags": [
+      "hero",
+      "typography",
+      "SVG",
+      "CSS"
+    ]
+  },
+  {
+    "id": "004-loading-states",
+    "title": "Loading States",
+    "description": "Skeleton shimmer, progress bar, bouncing dots and a spinner-to-check success state.",
+    "duration": 6,
+    "edition": "New",
+    "entry": "examples/004-loading-states/index.html",
+    "styles": "examples/004-loading-states/animation.css",
+    "tags": [
+      "UI",
+      "loaders",
+      "micro-interaction",
+      "CSS"
+    ]
+  },
+  {
+    "id": "005-orbit-diagram",
+    "title": "Orbit Diagram",
+    "description": "Explainer diagram: satellites orbit a core and highlight one at a time with captions.",
+    "duration": 12,
+    "edition": "New",
+    "entry": "examples/005-orbit-diagram/index.html",
+    "styles": "examples/005-orbit-diagram/animation.css",
+    "tags": [
+      "diagram",
+      "explainer",
+      "SVG",
+      "CSS"
+    ]
+  }
+]

package/examples/001-commerce-storyboard/README.md

@@ -0,0 +1,19 @@
+# 001 — Commerce Storyboard
+
+The original four-step CSS introduction. Preserved as the first library entry.
+
+- Story: Audit → Plan → Build → Measure.
+- Timing: four six-second scenes, 24 seconds per loop.
+- Style: dark canvas, yellow highlights, illustrated cards and subtle movement.
+- Controls: pause/resume; automatic offscreen and background-tab pause.
+- Fallback: static overview without JavaScript or with reduced motion enabled.
+- Source: `source.njk` and `animation.css` preserve the first website component from
+  andrewrico.com, commit `dd35b1d9`. The standalone HTML uses generic “Your studio” branding
+  and system fonts so the demo has no dependency on that website or its assets.
+
+Use `index.html` for a standalone version or `source.njk` in a Nunjucks project. Change the
+copy and labels together. Its CSS expects `--color-primary` and font variables; the demo
+provides fallback values through `../../src/demo.css`.
+
+Keep this edition intact. Add new numbered entries when developing a different direction.
+All original component code is covered by the repository MIT license.

package/examples/001-commerce-storyboard/animation.css

@@ -0,0 +1,167 @@
+/* CSS storyboard: four six-second scenes. JS only handles playback preferences. */
+.commerce-intro {
+  --intro-accent: var(--color-primary, #fffc00);
+  --intro-duration: 24s;
+  color: #f5f5ef;
+  background: #070909;
+  overflow: hidden;
+  border-block: 1px solid #282c28;
+}
+.commerce-intro__inner {
+  max-width: 1440px;
+  margin-inline: auto;
+  padding: 32px clamp(22px, 6vw, 88px);
+}
+.commerce-intro__masthead,
+.commerce-intro__footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 24px;
+}
+.commerce-intro__masthead { font-size: 12px; letter-spacing: .04em; }
+.commerce-intro__masthead p { margin: 0; color: #f5f5ef; }
+.commerce-intro__masthead p span { color: #a7afa8; margin-left: 12px; }
+.commerce-intro__edition { color: #a7afa8; white-space: nowrap; }
+.commerce-intro__stage { position: relative; display: grid; min-height: 350px; }
+.commerce-intro.is-enhanced .commerce-intro__stage { min-height: 470px; }
+.commerce-intro__overview { align-self: center; padding-block: 50px; }
+.commerce-intro__eyebrow { color: var(--intro-accent); text-transform: uppercase; letter-spacing: .15em; font-size: 12px; margin: 0 0 22px; }
+.commerce-intro__headline,
+.commerce-intro__overview h2 {
+  font-family: var(--font-family-2, sans-serif);
+  font-size: clamp(44px, 6.3vw, 88px);
+  font-weight: 900;
+  line-height: 1.02;
+  letter-spacing: -.055em;
+  color: #f5f5ef;
+  margin: 0 0 25px;
+}
+.commerce-intro__overview h2 span,
+.commerce-intro__headline span { color: var(--intro-accent); }
+.commerce-intro__description { color: #aeb7af; font-size: clamp(15px, 1.35vw, 18px); line-height: 1.65; max-width: 380px; margin: 0; }
+.commerce-intro__scene { display: none; }
+.commerce-intro.is-enhanced .commerce-intro__overview { position: absolute; width: 1px; height: 1px; padding: 0; overflow: hidden; clip-path: inset(50%); }
+.commerce-intro.is-enhanced .commerce-intro__scene {
+  display: grid;
+  grid-area: 1 / 1;
+  grid-template-columns: minmax(0, 1.15fr) minmax(0, 1fr);
+  gap: clamp(24px, 4vw, 60px);
+  align-items: center;
+  padding-block: 50px;
+  opacity: 0;
+  visibility: hidden;
+  pointer-events: none;
+  animation: commerce-scene var(--intro-duration) linear infinite;
+  animation-delay: calc(var(--step) * 6s);
+}
+/* The first scene stays visible while waiting to enter the viewport. */
+.commerce-intro.is-enhanced .commerce-intro__scene--1 { opacity: 1; visibility: visible; }
+.commerce-intro__visual { position: relative; min-height: 330px; display: grid; place-items: center; }
+.commerce-intro__orbit { position: absolute; width: 310px; height: 310px; border: 1px solid #383e25; border-radius: 50%; transform: rotate(-25deg) scaleX(1.2); }
+.commerce-intro__orbit::after { content: ''; position: absolute; inset: 30px -25px; border: 1px solid #222820; border-radius: 50%; }
+.commerce-intro__diagram {
+  position: relative;
+  width: 100%;
+  max-width: 350px;
+  padding: 24px;
+  border: 1px solid #555d3a;
+  border-radius: 14px;
+  background: #111610;
+  box-shadow: 0 25px 60px #0006;
+  transform: rotate(-3deg);
+  animation: commerce-float 6s ease-in-out infinite;
+}
+.commerce-intro__diagram-top { display: flex; justify-content: space-between; gap: 10px; color: #e5ebd9; font-size: 12px; padding-bottom: 20px; border-bottom: 1px solid #30392b; }
+.commerce-intro__diagram-top > span:last-child { color: var(--intro-accent); }
+.commerce-intro__audit-row { display: flex; align-items: center; justify-content: space-between; gap: 15px; font-size: 13px; color: #c5ccbf; padding-block: 20px; border-bottom: 1px solid #273024; }
+.commerce-intro__audit-row i { display: block; width: 65px; height: 5px; border-radius: 3px; background: var(--intro-accent); }
+.commerce-intro__audit-row:nth-child(3) i { width: 40px; opacity: .6; }
+.commerce-intro__audit-row:nth-child(4) i { width: 55px; opacity: .8; }
+.commerce-intro__scan { position: absolute; inset: 65px 16px auto; height: 1px; background: var(--intro-accent); box-shadow: 0 0 20px #fffc0066; animation: commerce-scan 6s ease-in-out infinite; }
+.commerce-intro__visual-note { position: absolute; bottom: -10px; color: #8c9789; font-size: 10px; letter-spacing: .1em; text-transform: uppercase; }
+.commerce-intro__map { display: flex; align-items: center; flex-direction: column; padding-top: 20px; }
+.commerce-intro__map span { display: block; padding: 10px 12px; border: 1px solid #69733e; border-radius: 5px; font-size: 11px; color: #dce3cd; text-align: center; }
+.commerce-intro__map > span:first-child { background: var(--intro-accent); color: #111610; border-color: var(--intro-accent); }
+.commerce-intro__map > div { display: flex; justify-content: center; gap: 16px; }
+.commerce-intro__map > i { width: 1px; height: 22px; background: #69733e; }
+.commerce-intro__store { display: grid; grid-template-columns: 1fr 1fr; gap: 20px; padding-block: 24px; }
+.commerce-intro__product { min-height: 135px; border: 1px solid #4a5633; border-radius: 8px; background: radial-gradient(ellipse at center, #818e39 0, #818e39 28%, transparent 29%), #20291b; }
+.commerce-intro__product-copy { display: flex; flex-direction: column; justify-content: center; gap: 12px; }
+.commerce-intro__product-copy i { display: block; height: 5px; background: #788464; border-radius: 3px; }
+.commerce-intro__product-copy i:nth-child(2) { width: 70%; }
+.commerce-intro__product-copy i:nth-child(3) { width: 40%; }
+.commerce-intro__product-copy span { margin-top: 10px; padding: 10px 5px; background: var(--intro-accent); color: #111610; text-align: center; font-size: 10px; border-radius: 4px; }
+.commerce-intro__build-label,
+.commerce-intro__chart-label { font-size: 10px; color: #a9b59a; letter-spacing: .03em; }
+.commerce-intro__bars { display: flex; align-items: flex-end; gap: 12px; height: 170px; margin-block: 24px 16px; border-bottom: 1px solid #69733e; }
+.commerce-intro__bars i { flex: 1; background: #697631; height: 35%; border-radius: 4px 4px 0 0; transform-origin: bottom; animation: commerce-bars 6s ease-in-out infinite; }
+.commerce-intro__bars i:nth-child(2) { height: 52%; }
+.commerce-intro__bars i:nth-child(3) { height: 46%; }
+.commerce-intro__bars i:nth-child(4) { height: 68%; }
+.commerce-intro__bars i:nth-child(5) { height: 60%; }
+.commerce-intro__bars i:nth-child(6) { height: 83%; background: var(--intro-accent); }
+.commerce-intro__footer { padding-top: 22px; border-top: 1px solid #30352c; }
+.commerce-intro__steps { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); flex: 1; gap: 20px; list-style: none; padding: 0; margin: 0; }
+.commerce-intro__steps li { position: relative; padding-top: 12px; font-size: 13px; color: #bbc4b6; border-top: 2px solid #343c2d; }
+.commerce-intro__step-number { color: #818e76; font-size: 10px; margin-right: 6px; }
+.commerce-intro.is-enhanced .commerce-intro__steps li::before { content: ''; position: absolute; inset: -2px 0 auto; height: 2px; background: var(--intro-accent); transform: scaleX(0); transform-origin: left; animation: commerce-progress var(--intro-duration) linear infinite; animation-delay: calc(var(--step) * 6s); }
+.commerce-intro__toggle { display: inline-flex; gap: 10px; align-items: center; justify-content: center; flex-shrink: 0; min-height: 44px; padding: 8px 14px; border: 1px solid #566047; border-radius: 30px; color: #dce3cd; background: transparent; font: inherit; font-size: 11px; cursor: pointer; }
+.commerce-intro__toggle[hidden] { display: none; }
+.commerce-intro__toggle:hover { border-color: var(--intro-accent); color: var(--intro-accent); }
+.commerce-intro__toggle:focus-visible { outline: 2px solid var(--intro-accent); outline-offset: 4px; }
+.commerce-intro__sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
+/* Pause all scenes, decorative loops and progress together. */
+.commerce-intro:not(.is-playing) *,
+.commerce-intro:not(.is-playing) *::before { animation-play-state: paused; }
+@keyframes commerce-scene {
+  0%, 23% { opacity: 1; visibility: visible; transform: translateY(0); }
+  25%, 98% { opacity: 0; visibility: hidden; transform: translateY(-12px); }
+  99.99% { opacity: 0; visibility: hidden; transform: translateY(12px); }
+  100% { opacity: 1; visibility: visible; transform: translateY(0); }
+}
+@keyframes commerce-progress {
+  0% { transform: scaleX(0); }
+  24%, 25% { transform: scaleX(1); }
+  25.01%, 100% { transform: scaleX(0); }
+}
+@keyframes commerce-float { 0%, 100% { transform: translateY(0) rotate(-3deg); } 50% { transform: translateY(-8px) rotate(-1deg); } }
+@keyframes commerce-scan { 0%, 100% { transform: translateY(0); opacity: .2; } 50% { transform: translateY(170px); opacity: .75; } }
+@keyframes commerce-bars { 0%, 100% { transform: scaleY(.85); } 50% { transform: scaleY(1); } }
+@media (max-width: 700px) {
+  .commerce-intro__inner { padding-block: 24px; }
+  .commerce-intro__masthead p span { display: block; margin: 4px 0 0; font-size: 10px; }
+  .commerce-intro__edition { display: none; }
+  .commerce-intro.is-enhanced .commerce-intro__stage { min-height: 590px; }
+  .commerce-intro.is-enhanced .commerce-intro__scene { grid-template-columns: minmax(0, 1fr); gap: 24px; padding-block: 36px; }
+  .commerce-intro__headline,
+  .commerce-intro__overview h2 { font-size: clamp(40px, 10vw, 68px); margin-bottom: 18px; }
+  .commerce-intro__eyebrow { margin-bottom: 16px; }
+  .commerce-intro__description { max-width: 330px; font-size: 14px; }
+  .commerce-intro__visual { min-height: 240px; margin-inline: 20px; }
+  .commerce-intro__diagram { max-width: 275px; padding: 18px; }
+  .commerce-intro__diagram-top { padding-bottom: 12px; }
+  .commerce-intro__audit-row { padding-block: 14px; }
+  .commerce-intro__orbit { width: 230px; height: 230px; }
+  .commerce-intro__scan { top: 46px; }
+  .commerce-intro__bars { height: 115px; margin-block: 16px; }
+  .commerce-intro__store { padding-block: 16px; }
+  .commerce-intro__product { min-height: 110px; }
+  .commerce-intro__map { padding-top: 12px; }
+  .commerce-intro__map > i { height: 14px; }
+  .commerce-intro__map span { padding: 8px; font-size: 10px; }
+  .commerce-intro__footer { flex-wrap: wrap; gap: 20px; }
+  .commerce-intro__steps { flex-basis: 100%; gap: 10px; }
+  .commerce-intro__steps li { font-size: 12px; }
+  .commerce-intro__step-number { display: block; margin: 0 0 5px; }
+  .commerce-intro__toggle { margin-left: auto; }
+  @keyframes commerce-scan { 0%, 100% { transform: translateY(0); opacity: .2; } 50% { transform: translateY(125px); opacity: .75; } }
+}
+/* A readable static overview is also the default without JavaScript. */
+@media (prefers-reduced-motion: reduce) {
+  .commerce-intro .commerce-intro__stage { min-height: 350px; }
+  .commerce-intro .commerce-intro__scene { display: none; }
+  .commerce-intro .commerce-intro__overview { position: static; width: auto; height: auto; padding-block: 50px; clip-path: none; overflow: visible; }
+  .commerce-intro *, .commerce-intro *::before { animation: none !important; }
+  .commerce-intro .commerce-intro__toggle { display: none; }
+}

package/examples/001-commerce-storyboard/index.html

@@ -0,0 +1,146 @@
+<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="color-scheme" content="dark"><title>001 — Commerce Storyboard | CSS Motion Library</title><link rel="stylesheet" href="../../src/demo.css"><link rel="stylesheet" href="animation.css"></head><body><nav class="demo-nav"><a href="../../">← Library</a><span>001 / Commerce Storyboard</span><a href="../002-commerce-film/">Next: Commerce Film ↗</a></nav><main>
+
+<section id="intro-video" class="commerce-intro" aria-labelledby="commerce-intro-title" data-commerce-intro>
+  <div class="commerce-intro__inner">
+    <div class="commerce-intro__masthead">
+      <p>Your studio <span>/ Shopify &amp; AI Commerce</span></p>
+      <span class="commerce-intro__edition" aria-hidden="true">The approach / 01—04</span>
+    </div>
+    <div class="commerce-intro__stage" id="commerce-intro-stage">
+      <div class="commerce-intro__overview">
+        <p class="commerce-intro__eyebrow">A clear path forward</p>
+        <h2 id="commerce-intro-title">Audit. Plan.<br><span>Build. Measure.</span></h2>
+        <p class="commerce-intro__description">A clear plan for your Shopify store, from the first audit to ongoing improvement.</p>
+      </div>
+
+      <div class="commerce-intro__scene commerce-intro__scene--1" style="--step: 0" aria-hidden="true">
+        <div class="commerce-intro__copy">
+          <p class="commerce-intro__eyebrow">01 / Audit</p>
+          <p class="commerce-intro__headline">Find the<br><span>friction.</span></p>
+          <p class="commerce-intro__description">Understand what is holding your Shopify store back.</p>
+        </div>
+        <div class="commerce-intro__visual commerce-intro__visual--audit">
+          <span class="commerce-intro__orbit"></span>
+          <div class="commerce-intro__diagram">
+
+            <div class="commerce-intro__diagram-top"><span>Store audit</span><span>↗</span></div>
+            <div class="commerce-intro__audit-row"><span>Storefront</span><i></i></div>
+            <div class="commerce-intro__audit-row"><span>Checkout</span><i></i></div>
+            <div class="commerce-intro__audit-row"><span>Integrations</span><i></i></div>
+            <div class="commerce-intro__scan"></div>
+
+          </div>
+          <span class="commerce-intro__visual-note">Built around your business</span>
+        </div>
+      </div>
+
+      <div class="commerce-intro__scene commerce-intro__scene--2" style="--step: 1" aria-hidden="true">
+        <div class="commerce-intro__copy">
+          <p class="commerce-intro__eyebrow">02 / Plan</p>
+          <p class="commerce-intro__headline">Map the<br><span>next move.</span></p>
+          <p class="commerce-intro__description">Turn the findings into a clear architecture plan.</p>
+        </div>
+        <div class="commerce-intro__visual commerce-intro__visual--plan">
+          <span class="commerce-intro__orbit"></span>
+          <div class="commerce-intro__diagram">
+
+            <div class="commerce-intro__diagram-top"><span>Architecture plan</span><span>↗</span></div>
+            <div class="commerce-intro__map"><span>Storefront</span><i></i><div><span>Checkout</span><span>Integrations</span></div><i></i><span>Customer experience</span></div>
+
+          </div>
+          <span class="commerce-intro__visual-note">Built around your business</span>
+        </div>
+      </div>
+
+      <div class="commerce-intro__scene commerce-intro__scene--3" style="--step: 2" aria-hidden="true">
+        <div class="commerce-intro__copy">
+          <p class="commerce-intro__eyebrow">03 / Build</p>
+          <p class="commerce-intro__headline">Build with<br><span>purpose.</span></p>
+          <p class="commerce-intro__description">Bring the plan to life across your store and its integrations.</p>
+        </div>
+        <div class="commerce-intro__visual commerce-intro__visual--build">
+          <span class="commerce-intro__orbit"></span>
+          <div class="commerce-intro__diagram">
+
+            <div class="commerce-intro__diagram-top"><span>Store build</span><span>•••</span></div>
+            <div class="commerce-intro__store"><div class="commerce-intro__product"></div><div class="commerce-intro__product-copy"><i></i><i></i><i></i><span>Add to cart +</span></div></div>
+            <div class="commerce-intro__build-label">Design → Development → Launch</div>
+
+          </div>
+          <span class="commerce-intro__visual-note">Built around your business</span>
+        </div>
+      </div>
+
+      <div class="commerce-intro__scene commerce-intro__scene--4" style="--step: 3" aria-hidden="true">
+        <div class="commerce-intro__copy">
+          <p class="commerce-intro__eyebrow">04 / Measure</p>
+          <p class="commerce-intro__headline">Keep getting<br><span>better.</span></p>
+          <p class="commerce-intro__description">Measure what changed. Use the findings to guide what comes next.</p>
+        </div>
+        <div class="commerce-intro__visual commerce-intro__visual--measure">
+          <span class="commerce-intro__orbit"></span>
+          <div class="commerce-intro__diagram">
+
+            <div class="commerce-intro__diagram-top"><span>Measure &amp; improve</span><span>↗</span></div>
+            <div class="commerce-intro__bars"><i></i><i></i><i></i><i></i><i></i><i></i></div>
+            <div class="commerce-intro__chart-label">Observe → Learn → Refine</div>
+
+          </div>
+          <span class="commerce-intro__visual-note">Illustrative process</span>
+        </div>
+      </div>
+
+    </div>
+    <div class="commerce-intro__footer">
+      <ol class="commerce-intro__steps">
+
+        <li style="--step: 0"><span class="commerce-intro__step-number" aria-hidden="true">01</span> Audit<span class="commerce-intro__sr-only">: Understand what is holding your Shopify store back.</span></li>
+
+        <li style="--step: 1"><span class="commerce-intro__step-number" aria-hidden="true">02</span> Plan<span class="commerce-intro__sr-only">: Turn the findings into a clear architecture plan.</span></li>
+
+        <li style="--step: 2"><span class="commerce-intro__step-number" aria-hidden="true">03</span> Build<span class="commerce-intro__sr-only">: Bring the plan to life across your store and its integrations.</span></li>
+
+        <li style="--step: 3"><span class="commerce-intro__step-number" aria-hidden="true">04</span> Measure<span class="commerce-intro__sr-only">: Measure what changed. Use the findings to guide what comes next.</span></li>
+
+      </ol>
+      <button class="commerce-intro__toggle" type="button" aria-controls="commerce-intro-stage" hidden>
+        <span data-intro-toggle-icon aria-hidden="true">Ⅱ</span>
+        <span data-intro-toggle-label>Pause animation</span>
+      </button>
+    </div>
+  </div>
+</section>
+<script>
+  (function () {
+    var intro = document.querySelector('[data-commerce-intro]');
+    if (!intro) return;
+    var button = intro.querySelector('.commerce-intro__toggle');
+    var label = intro.querySelector('[data-intro-toggle-label]');
+    var icon = intro.querySelector('[data-intro-toggle-icon]');
+    var reducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)');
+    var userPaused = false;
+    var inView = !('IntersectionObserver' in window);
+    function update() {
+      var reduce = reducedMotion.matches || document.documentElement.getAttribute('data-a11y-reduce-motion') === 'true';
+      intro.classList.toggle('is-enhanced', !reduce);
+      intro.classList.toggle('is-playing', !reduce && inView && !document.hidden && !userPaused);
+      button.hidden = reduce;
+      label.textContent = userPaused ? 'Resume animation' : 'Pause animation';
+      icon.textContent = userPaused ? '▷' : 'Ⅱ';
+    }
+    button.addEventListener('click', function () { userPaused = !userPaused; update(); });
+    document.addEventListener('visibilitychange', update);
+    if (reducedMotion.addEventListener) reducedMotion.addEventListener('change', update);
+    else reducedMotion.addListener(update);
+    new MutationObserver(update).observe(document.documentElement, { attributes: true, attributeFilter: ['data-a11y-reduce-motion'] });
+    update();
+    if ('IntersectionObserver' in window) {
+      new IntersectionObserver(function (entries) {
+        inView = entries[0].isIntersecting;
+        update();
+      }, { threshold: 0.15 }).observe(intro);
+    }
+  })();
+</script>
+</main><footer class="demo-footer">24-second CSS loop · Original edition · <a href="animation.css">View CSS</a></footer></body></html>

package/examples/002-commerce-film/README.md

@@ -0,0 +1,38 @@
+# 002 — Commerce Film
+
+A thirty-second CSS film designed to feel closer to an edited motion-graphics video.
+All pictures are HTML, CSS or original SVG; there is no rendered video or animation engine.
+
+| Time | Shot | Direction |
+|---|---|---|
+| 0–5s | Commerce in Motion | Masked kinetic typography, lens push and a moving ticker |
+| 5–10s | Audit | Full-frame acid yellow, a tilted diagnostics window and a scanning line |
+| 10–15s | Plan | Blueprint camera drift, drawing SVG wires and staggered nodes |
+| 15–20s | Build | A perspective storefront flies into the frame and the camera pushes in |
+| 20–25s | Measure | Tall typography, an orbit and staggered illustrative chart bars |
+| 25–30s | Better Commerce | Closing title on yellow; short hold before the loop |
+
+The film uses CSS scene cuts, a recurring wipe, slow camera movement and deliberate title
+holds. Desktop is 16:9; smaller screens recompose into a 3:4 frame rather than cropping.
+The chart is a motion illustration and claims no measured result.
+
+## Playback
+
+`../../src/player.js` controls CSSAnimation objects with the browser's native API. Controls
+include pause/play, replay, a keyboard-operable seek bar, time display and 0.5×/1×/1.5× speed.
+The shared controller pauses in hidden tabs and offscreen, remembers manual pause, supports
+multiple instances, handles reduced motion and cleans up listeners on `destroy()`.
+
+No-JS or reduced-motion mode shows “Better commerce. By design.” and the process summary.
+With reduced motion active, playback controls are hidden and automatic motion stays paused.
+
+## Customize
+
+Edit text and SVG in `index.html`. Theme variables are `--ink`, `--acid`, `--paper`.
+All shot and detail animations share a 30-second timeline; shot starts use `--shot * 5s`.
+To change the duration or scene count, update the CSS timeline, delays, percentages,
+`data-duration`, and seek-range maximum together.
+
+For reuse, copy this HTML and CSS plus `src/player.js`. Adapt the short import in `src/auto.js`
+to your file layout, and keep the demo's box-sizing/font defaults or provide your own.
+Use the existing CSS effect as a reference when adding new shots. Avoid overwriting entry 001.