use-scroll-animate 10.2.0 → 10.4.0

package/docs/ROADMAP.md

@@ -52,11 +52,11 @@ Store 卡片显示 **「Requires: motionary/runtime/<module>」** 徽章（官
   - 主线 B：**scroll 模块**（`motionary/runtime/scroll`）—— pin、scrub、markers、start / end 规则（自研，功能对标 ScrollTrigger，但不复制其代码或 API）。
   - 格式：SVG SMIL 回放、路径变形、CSS 动画 SVG（`motionary/runtime/format-svg`）。
   - 新组件：动效检查器面板、`<usa-scroll-scene>`（Requires: motionary/runtime/scroll）。
-- **v10.3** — View Transitions 2.0：跨文档页面转场、共享元素动画。
+- ✅ **v10.3** — View Transitions 2.0：跨文档页面转场、共享元素动画。
   - 主线 B：**text 模块** —— 逐字 / 逐词 / 逐行拆分（保留可访问文本）。
   - 格式：精灵图（TexturePacker / Aseprite JSON）、图片序列（`motionary/runtime/format-sprite`）。
   - 新组件：路由转场容器、`<usa-text-splitter>`（`<usa-split-text>` 已被 4.x 文本组件占用）。
-- **v10.4** — 滚动驱动 3.0：原生 `animation-timeline` 优先、JS 回退插件化。
+- ✅ **v10.4** — 滚动驱动 3.0：原生 `animation-timeline` 优先、JS 回退插件化。
   - 主线 A：发布 `motionary-mcp` MCP 服务器（`npx motionary-mcp`，stdio）：`list_components`、`search_components`、`get_component`、`get_example`、`scaffold_snippet`（自动带上前置条件）。
   - 主线 B：**smooth 模块** —— 平滑滚动（减少动态效果时停用）。
   - 格式：GIF（自研 LZW）、APNG、动画 WebP 拆帧到 canvas。

package/docs/components/README.md

@@ -1,4 +1,4 @@
-# Motionary components (193)
+# Motionary components (198)
 
 One page per `<usa-*>` element, generated from the source. Machine-readable: `motionary/manifest.json` · Pages `/components.json` · `/llms.txt` · `/llms-full.txt`. How to use these with an AI assistant: [AGENTS.md](../../AGENTS.md) and [the prompt guide](../ai-prompt-guide.md).
 
@@ -8,6 +8,7 @@ One page per `<usa-*>` element, generated from the source. Machine-readable: `mo
 - [`<usa-dialog>`](usa-dialog.md) — Modal & drawer
 - [`<usa-disclosure>`](usa-disclosure.md) — Accordion 2.0
 - [`<usa-modal>`](usa-modal.md) — Modal dialog
+- [`<usa-route-transition>`](usa-route-transition.md) — Route transition container
 - [`<usa-sheet>`](usa-sheet.md) — Drawer / bottom sheet
 - [`<usa-view-switch>`](usa-view-switch.md) — View switch
 
@@ -190,6 +191,7 @@ One page per `<usa-*>` element, generated from the source. Machine-readable: `mo
 - [`<usa-magnetic>`](usa-magnetic.md) — Magnetic button
 - [`<usa-press>`](usa-press.md) — Press feedback
 - [`<usa-ripple>`](usa-ripple.md) — Ripple
+- [`<usa-smooth-scroll>`](usa-smooth-scroll.md) — Smooth scroll · Requires: motionary/runtime/smooth
 - [`<usa-spotlight>`](usa-spotlight.md) — Reveal highlight
 - [`<usa-tilt>`](usa-tilt.md) — 3D tilt card
 - [`<usa-volume-knob>`](usa-volume-knob.md) — Volume knob
@@ -207,6 +209,7 @@ One page per `<usa-*>` element, generated from the source. Machine-readable: `mo
 - [`<usa-shimmer-text>`](usa-shimmer-text.md) — Shimmer text
 - [`<usa-split-text>`](usa-split-text.md) — Split-text reveal
 - [`<usa-text-rotate>`](usa-text-rotate.md) — Rotating words
+- [`<usa-text-splitter>`](usa-text-splitter.md) — Text splitter · Requires: motionary/runtime/text
 - [`<usa-typewriter>`](usa-typewriter.md) — Typewriter
 - [`<usa-wave-text>`](usa-wave-text.md) — Wave text
 
@@ -238,16 +241,18 @@ One page per `<usa-*>` element, generated from the source. Machine-readable: `mo
 
 - [`<usa-pack>`](usa-pack.md) — E-commerce pack
 
-## gesture
-
-- [`<usa-pinch-zoom>`](usa-pinch-zoom.md) — Pinch zoom
-- [`<usa-swipe-deck>`](usa-swipe-deck.md) — Swipe cards deck
-- [`<usa-swipeable>`](usa-swipeable.md) — Swipeable
-
 ## reveal
 
+- [`<usa-parallax-layers>`](usa-parallax-layers.md) — Parallax layers
 - [`<usa-reveal>`](usa-reveal.md) — Reveal
 - [`<usa-scroll-progress>`](usa-scroll-progress.md) — Scroll progress bar
+- [`<usa-scroll-ring>`](usa-scroll-ring.md) — Scroll progress ring
 - [`<usa-scroll-scene>`](usa-scroll-scene.md) — Scroll scene · Requires: motionary/runtime/scroll
 - [`<usa-scrolly>`](usa-scrolly.md) — Sticky scrollytelling
 - [`<usa-stagger>`](usa-stagger.md) — Stagger list
+
+## gesture
+
+- [`<usa-pinch-zoom>`](usa-pinch-zoom.md) — Pinch zoom
+- [`<usa-swipe-deck>`](usa-swipe-deck.md) — Swipe cards deck
+- [`<usa-swipeable>`](usa-swipeable.md) — Swipeable

package/docs/components/usa-parallax-layers.md

@@ -0,0 +1,38 @@
+# `<usa-parallax-layers>` — Parallax layers
+
+> Generated from the source and the gallery catalog by `scripts/gen-component-docs.mjs` (same data as [components.json](https://harrisoncn.github.io/Motionary/components.json) and [llms-full.txt](https://harrisoncn.github.io/Motionary/llms-full.txt)).
+
+10.4: a parallax container — children with data-depth move at different speeds while it crosses the viewport (native view() scroll timeline first, JS fallback), optional pointer tilt; static under reduced motion.
+
+- **Category:** reveal · **since** 10.4
+- **Import:** `import { defineParallaxLayers } from 'motionary/components/widgets'` then `defineParallaxLayers();`
+- **CDN:** `<script src="https://unpkg.com/motionary@10/dist/widgets.umd.js"></script>`
+- **Attributes:** `range`, `engine`, `horizontal`, `pointer`, `strength`, `preview`
+- **Events:** `usa:progress`
+- **Slots:** —
+- **Methods:** `layers()`
+- **Source:** [src/components/widgets/parallax-layers.ts](../../src/components/widgets/parallax-layers.ts)
+
+## Minimal example
+
+```html
+<usa-parallax-layers range="120">
+  <img data-depth="0.6" src="mountains.webp" alt="">
+  <h2 data-depth="-0.3">Above the clouds</h2>
+</usa-parallax-layers>
+```
+
+## ES module
+
+```js
+import { defineParallaxLayers } from 'motionary/components/widgets';
+
+defineParallaxLayers(); // registers <usa-parallax-layers>
+
+/* then use it in your HTML:
+<usa-parallax-layers range="120">
+  <img data-depth="0.6" src="mountains.webp" alt="">
+  <h2 data-depth="-0.3">Above the clouds</h2>
+</usa-parallax-layers>
+*/
+```

package/docs/components/usa-route-transition.md

@@ -0,0 +1,38 @@
+# `<usa-route-transition>` — Route transition container
+
+> Generated from the source and the gallery catalog by `scripts/gen-component-docs.mjs` (same data as [components.json](https://harrisoncn.github.io/Motionary/components.json) and [llms-full.txt](https://harrisoncn.github.io/Motionary/llms-full.txt)).
+
+10.3: View Transitions 2.0 — link clicks swap the container’s content with the target page (fetched) or an inline <template data-route>, animated with the View Transitions API (Web Animations fallback); data-shared elements morph between routes; cross-document enables native MPA transitions.
+
+- **Category:** transitions · **since** 10.3
+- **Import:** `import { defineRouteTransition } from 'motionary/components/widgets'` then `defineRouteTransition();`
+- **CDN:** `<script src="https://unpkg.com/motionary@10/dist/widgets.umd.js"></script>`
+- **Attributes:** `effect`, `engine`, `cross-document`
+- **Events:** `usa:navigate`, `usa:navigated`
+- **Slots:** —
+- **Methods:** `navigate()`
+- **Source:** [src/components/widgets/route-transition.ts](../../src/components/widgets/route-transition.ts)
+
+## Minimal example
+
+```html
+<usa-route-transition id="app" effect="slide" cross-document>
+  <nav><a href="/">Home</a> <a href="/about">About</a></nav>
+  <h1 data-shared="title">Home</h1>
+</usa-route-transition>
+```
+
+## ES module
+
+```js
+import { defineRouteTransition } from 'motionary/components/widgets';
+
+defineRouteTransition(); // registers <usa-route-transition>
+
+/* then use it in your HTML:
+<usa-route-transition id="app" effect="slide" cross-document>
+  <nav><a href="/">Home</a> <a href="/about">About</a></nav>
+  <h1 data-shared="title">Home</h1>
+</usa-route-transition>
+*/
+```

package/docs/components/usa-scroll-ring.md

@@ -0,0 +1,32 @@
+# `<usa-scroll-ring>` — Scroll progress ring
+
+> Generated from the source and the gallery catalog by `scripts/gen-component-docs.mjs` (same data as [components.json](https://harrisoncn.github.io/Motionary/components.json) and [llms-full.txt](https://harrisoncn.github.io/Motionary/llms-full.txt)).
+
+10.4: a circular scroll-progress indicator for the page or any scroll container (for=".article"), optional percentage label and back-to-top button. Scroll-driven 3.0: native animation-timeline: scroll() first (no script per frame), a small JS loop where scroll timelines are missing.
+
+- **Category:** reveal · **since** 10.4
+- **Import:** `import { defineScrollRing } from 'motionary/components/widgets'` then `defineScrollRing();`
+- **CDN:** `<script src="https://unpkg.com/motionary@10/dist/widgets.umd.js"></script>`
+- **Attributes:** `for`, `engine`, `label`, `back-to-top`, `size`, `thickness`, `horizontal`, `preview`
+- **Events:** `usa:progress`, `usa:top`
+- **Slots:** —
+- **Methods:** —
+- **Source:** [src/components/widgets/scroll-ring.ts](../../src/components/widgets/scroll-ring.ts)
+
+## Minimal example
+
+```html
+<usa-scroll-ring label back-to-top></usa-scroll-ring>
+```
+
+## ES module
+
+```js
+import { defineScrollRing } from 'motionary/components/widgets';
+
+defineScrollRing(); // registers <usa-scroll-ring>
+
+/* then use it in your HTML:
+<usa-scroll-ring label back-to-top></usa-scroll-ring>
+*/
+```

package/docs/components/usa-smooth-scroll.md

@@ -0,0 +1,60 @@
+# `<usa-smooth-scroll>` — Smooth scroll
+
+> Generated from the source and the gallery catalog by `scripts/gen-component-docs.mjs` (same data as [components.json](https://harrisoncn.github.io/Motionary/components.json) and [llms-full.txt](https://harrisoncn.github.io/Motionary/llms-full.txt)).
+
+10.4: smooth, inertial wheel scrolling for the page or a container (wrapper), anchor links glide (with offset for sticky headers); keyboard / scrollbar / touch stay native and it switches off under reduced motion. Requires motionary/runtime/smooth — npm i motionary, then use(smooth) before it mounts.
+
+- **Category:** interaction · **since** 10.4
+- **Import:** `import { defineSmoothScroll } from 'motionary/components/widgets'` then `defineSmoothScroll();`
+- **CDN:** `<script src="https://unpkg.com/motionary@10/dist/widgets.umd.js"></script>`
+- **Attributes:** `lerp`, `duration`, `ease`, `wheel-multiplier`, `horizontal`, `touch`, `anchors`, `offset`, `wrapper`, `preview`
+- **Events:** `usa:scroll`, `usa:ready`, `usa:runtime-missing`
+- **Slots:** —
+- **Methods:** `glideTo()`, `stop()`, `resume()`
+- **Source:** [src/components/widgets/smooth-scroll.ts](../../src/components/widgets/smooth-scroll.ts)
+
+## Prerequisites — Requires: motionary/runtime/smooth
+
+1. **Install:** `npm i motionary`
+2. **Import order & registration:** Register the core first, then the module: use(smooth) also registers the core. CDN: load runtime.iife.js, then runtime/smooth.iife.js (it registers itself).
+
+```js
+import { use } from 'motionary/runtime';
+import { smooth } from 'motionary/runtime/smooth';
+import { defineSmoothScroll } from 'motionary/components/widgets';
+
+use(smooth);
+defineSmoothScroll(); // registers <usa-smooth-scroll> — after the prerequisites
+```
+
+3. **CDN:**
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/motionary@10/dist/runtime.iife.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/motionary@10/dist/runtime/smooth.iife.js"></script>
+<!-- then the component bundles -->
+<script src="https://unpkg.com/motionary@10/dist/components.umd.js"></script>
+<script src="https://unpkg.com/motionary@10/dist/widgets.umd.js"></script>
+```
+
+## Minimal example
+
+```html
+<usa-smooth-scroll lerp="0.1" offset="64"></usa-smooth-scroll>
+```
+
+## ES module
+
+```js
+import { use } from 'motionary/runtime';
+import { smooth } from 'motionary/runtime/smooth';
+
+use(smooth);
+import { defineSmoothScroll } from 'motionary/components/widgets';
+
+defineSmoothScroll(); // registers <usa-smooth-scroll>
+
+/* then use it in your HTML:
+<usa-smooth-scroll lerp="0.1" offset="64"></usa-smooth-scroll>
+*/
+```

package/docs/components/usa-text-splitter.md

@@ -0,0 +1,60 @@
+# `<usa-text-splitter>` — Text splitter
+
+> Generated from the source and the gallery catalog by `scripts/gen-component-docs.mjs` (same data as [components.json](https://harrisoncn.github.io/Motionary/components.json) and [llms-full.txt](https://harrisoncn.github.io/Motionary/llms-full.txt)).
+
+10.3: splits its text into characters, words or lines and animates them in with a stagger (rise, fade, blur, flip, wave) when it scrolls into view — accessible, grapheme-aware. Requires motionary/runtime/text — npm i motionary, then use(text) before it mounts.
+
+- **Category:** text · **since** 10.3
+- **Import:** `import { defineTextSplitter } from 'motionary/components/widgets'` then `defineTextSplitter();`
+- **CDN:** `<script src="https://unpkg.com/motionary@10/dist/widgets.umd.js"></script>`
+- **Attributes:** `split`, `effect`, `stagger`, `duration`, `loop`, `trigger`
+- **Events:** `usa:split`, `usa:done`, `usa:runtime-missing`
+- **Slots:** —
+- **Methods:** `replay()`, `pieces()`
+- **Source:** [src/components/widgets/text-splitter.ts](../../src/components/widgets/text-splitter.ts)
+
+## Prerequisites — Requires: motionary/runtime/text
+
+1. **Install:** `npm i motionary`
+2. **Import order & registration:** Register the core first, then the module: use(text) also registers the core. CDN: load runtime.iife.js, then runtime/text.iife.js (it registers itself).
+
+```js
+import { use } from 'motionary/runtime';
+import { text } from 'motionary/runtime/text';
+import { defineTextSplitter } from 'motionary/components/widgets';
+
+use(text);
+defineTextSplitter(); // registers <usa-text-splitter> — after the prerequisites
+```
+
+3. **CDN:**
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/motionary@10/dist/runtime.iife.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/motionary@10/dist/runtime/text.iife.js"></script>
+<!-- then the component bundles -->
+<script src="https://unpkg.com/motionary@10/dist/components.umd.js"></script>
+<script src="https://unpkg.com/motionary@10/dist/widgets.umd.js"></script>
+```
+
+## Minimal example
+
+```html
+<usa-text-splitter split="chars" effect="rise" stagger="30">Motion, made simple.</usa-text-splitter>
+```
+
+## ES module
+
+```js
+import { use } from 'motionary/runtime';
+import { text } from 'motionary/runtime/text';
+
+use(text);
+import { defineTextSplitter } from 'motionary/components/widgets';
+
+defineTextSplitter(); // registers <usa-text-splitter>
+
+/* then use it in your HTML:
+<usa-text-splitter split="chars" effect="rise" stagger="30">Motion, made simple.</usa-text-splitter>
+*/
+```

package/docs/components.md

@@ -1407,6 +1407,66 @@ defineScrollScene(); // registers <usa-scroll-scene> — after the prerequisites
 </usa-scroll-scene>
 ```
 
+### `<usa-text-splitter>` — Requires: motionary/runtime/text
+
+- **Install:** `npm i motionary`
+- **Import order & registration:** Register the core first, then the module: use(text) also registers the core. CDN: load runtime.iife.js, then runtime/text.iife.js (it registers itself).
+
+```js
+import { use } from 'motionary/runtime';
+import { text } from 'motionary/runtime/text';
+import { defineTextSplitter } from 'motionary/components/widgets';
+
+use(text);
+defineTextSplitter(); // registers <usa-text-splitter> — after the prerequisites
+```
+
+- **CDN:**
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/motionary@10/dist/runtime.iife.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/motionary@10/dist/runtime/text.iife.js"></script>
+<!-- then the component bundles -->
+<script src="https://unpkg.com/motionary@10/dist/components.umd.js"></script>
+<script src="https://unpkg.com/motionary@10/dist/widgets.umd.js"></script>
+```
+
+- **Minimal example:**
+
+```html
+<usa-text-splitter split="chars" effect="rise" stagger="30">Motion, made simple.</usa-text-splitter>
+```
+
+### `<usa-smooth-scroll>` — Requires: motionary/runtime/smooth
+
+- **Install:** `npm i motionary`
+- **Import order & registration:** Register the core first, then the module: use(smooth) also registers the core. CDN: load runtime.iife.js, then runtime/smooth.iife.js (it registers itself).
+
+```js
+import { use } from 'motionary/runtime';
+import { smooth } from 'motionary/runtime/smooth';
+import { defineSmoothScroll } from 'motionary/components/widgets';
+
+use(smooth);
+defineSmoothScroll(); // registers <usa-smooth-scroll> — after the prerequisites
+```
+
+- **CDN:**
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/motionary@10/dist/runtime.iife.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/motionary@10/dist/runtime/smooth.iife.js"></script>
+<!-- then the component bundles -->
+<script src="https://unpkg.com/motionary@10/dist/components.umd.js"></script>
+<script src="https://unpkg.com/motionary@10/dist/widgets.umd.js"></script>
+```
+
+- **Minimal example:**
+
+```html
+<usa-smooth-scroll lerp="0.1" offset="64"></usa-smooth-scroll>
+```
+
 <!-- prereqs:end -->
 
 ### v10.2 Scroll scenes (`motionary/runtime/scroll`) + SVG loader + `data-motion` in core: `<usa-scroll-scene>`, `<usa-motion-inspector>` (`components/widgets`)
@@ -1426,6 +1486,40 @@ defineScrollScene(); // registers <usa-scroll-scene> — after the prerequisites
 
 Declarative motion with just the core: `applyMotionAttributes(createMotion())` + `data-motion="enter: fade-up 600ms"`.
 
+### v10.3 View Transitions 2.0 + text splitting (`motionary/runtime/text`) + sprite sheets: `<usa-route-transition>`, `<usa-text-splitter>` (`components/widgets`)
+
+```html
+<usa-route-transition id="app" effect="slide" cross-document>
+  <nav><a href="/">Home</a> <a href="/about">About</a></nav>
+  <h1 data-shared="title">Home</h1>
+</usa-route-transition>
+<usa-text-splitter split="chars" effect="rise" stagger="30">Motion, made simple.</usa-text-splitter>
+```
+
+| Element | Attributes | Methods / events |
+|---|---|---|
+| `<usa-route-transition>` | `effect` (fade, slide, zoom), `engine` (auto, view-transition, waapi), `selector`, `history` (push, replace, off), `links` (inside, document), `cross-document`; `[data-to]`, `<template data-route>`, `[data-shared]` | `navigate(url)`, `current`; `usa:navigate`, `usa:navigated` |
+| `<usa-text-splitter>` (Requires: motionary/runtime/text) | `split` (chars, words, lines), `effect` (rise, fade, blur, flip, wave), `stagger`, `duration`, `trigger` (view, load, hover), `loop` | `replay()`, `pieces()`; `usa:split`, `usa:done`, `usa:runtime-missing` |
+
+### v10.4 Scroll-driven 3.0 + smooth scrolling (`motionary/runtime/smooth`) + animated images: `<usa-scroll-ring>`, `<usa-parallax-layers>`, `<usa-smooth-scroll>` (`components/widgets`) · `motionary-mcp`
+
+```html
+<usa-scroll-ring label back-to-top></usa-scroll-ring>
+<usa-parallax-layers range="120">
+  <img data-depth="0.6" src="mountains.webp" alt="">
+  <h2 data-depth="-0.3">Above the clouds</h2>
+</usa-parallax-layers>
+<usa-smooth-scroll lerp="0.1" offset="64"></usa-smooth-scroll>
+```
+
+| Element | Attributes | Methods / events |
+|---|---|---|
+| `<usa-scroll-ring>` | `for` (page or a selector), `engine` (auto, native, js), `label`, `back-to-top`, `size`, `thickness`, `horizontal`, `preview` | `progress`, `engine`; `usa:progress`, `usa:top` |
+| `<usa-parallax-layers>` | `range`, `engine` (auto, native, js), `horizontal`, `pointer`, `strength`, `preview`; children `[data-depth]` | `layers()`, `progress`; `usa:progress` |
+| `<usa-smooth-scroll>` (Requires: motionary/runtime/smooth) | `wrapper`, `lerp`, `duration`, `ease`, `wheel-multiplier`, `horizontal`, `touch`, `anchors`, `offset`, `preview` | `glideTo(target)`, `stop()`, `resume()`, `instance`; `usa:ready`, `usa:scroll`, `usa:runtime-missing` |
+
+MCP: `npx -y -p motionary motionary-mcp` — see [docs/mcp.md](docs/mcp.md).
+
 ## Frameworks
 
 Custom elements work in every framework. Register once (e.g. in your entry file), then use the tags.

package/docs/mcp.md

@@ -0,0 +1,50 @@
+# `motionary-mcp` — the component catalog as an MCP server
+
+`motionary-mcp` (10.4+) is a **read-only** [Model Context Protocol](https://modelcontextprotocol.io) server that ships inside the `motionary` package. AI assistants that speak MCP (Claude Desktop / Claude Code, Cursor, VS Code, Windsurf, Zed, …) can ask it which `<usa-*>` component fits a UI need, read the component's API and get a snippet that already installs, imports and registers every prerequisite in the right order.
+
+- **Zero dependencies**, stdio transport (newline-delimited JSON-RPC 2.0), protocol versions `2025-06-18`, `2025-03-26`, `2024-11-05`.
+- **Read-only**: it answers from the AI manifest bundled in the package (`motionary/manifest.json`, the same data as the site's `components.json` / `llms.txt`). It never writes files, executes code or touches the network. Every tool is annotated `readOnlyHint: true`.
+- Tested in CI with the official MCP TypeScript SDK client over stdio.
+
+## Run it
+
+```bash
+npx -y -p motionary motionary-mcp          # any machine with Node 18+
+npx motionary-mcp                          # inside a project that has motionary installed
+MOTIONARY_MANIFEST=./manifest.json npx -p motionary motionary-mcp   # another manifest
+```
+
+Client configuration (the usual `mcpServers` shape):
+
+```json
+{
+  "mcpServers": {
+    "motionary": { "command": "npx", "args": ["-y", "-p", "motionary", "motionary-mcp"] }
+  }
+}
+```
+
+Claude Code: `claude mcp add motionary -- npx -y -p motionary motionary-mcp`.
+
+## Tools
+
+| Tool | Arguments | Returns |
+|---|---|---|
+| `list_components` | `category?`, `requires?` (`scroll`, `motionary/runtime/text`, `none`), `since?` (`10.0`), `limit?` | tag, title, category, import path, prerequisites, version introduced |
+| `search_components` | `query`, `limit?` | best matches for a UI need ("animated counter", "pinned scroll scene") with a score |
+| `get_component` | `tag` (`usa-tilt`, `tilt` or `<usa-tilt>`) | attributes, events, slots, methods, import / define, CDN, prerequisites (install, import + register order, CDN order), example, variants |
+| `get_example` | `tag`, `variant?` (`html` = CDN, `esm`, or a variant id) | a working example |
+| `scaffold_snippet` | `tags[]`, `framework?` (`html`, `esm`, `react`, `vue`, `svelte`) | one snippet for several components, prerequisites first |
+
+Unknown tags come back as tool errors (`isError: true`) with a hint to search first.
+
+## Resources
+
+- `motionary://manifest` — the whole manifest (JSON)
+- `motionary://llms.txt` — the short catalog text
+- `motionary://component/{tag}` — one component (JSON; resource template)
+
+## Notes
+
+- The server version follows its own track (`0.x` until Motionary 11.0 makes it `1.0`); the catalog version is the installed `motionary` version (`initialize` → `instructions`).
+- MCP 2.0 tools (`suggest_motion`, `validate_snippet`) arrive in 10.7.

package/docs/runtime/format-apng.md

@@ -0,0 +1,59 @@
+# motionary/runtime/format-apng — APNG loader
+
+> Generated from `showcase/catalog/prereqs.js` by `scripts/gen-runtime-docs.mjs` — edit the data, not this page.
+
+Split animated PNGs into standalone frame PNGs (decoded by the browser), composite them (dispose / blend) and play them on a canvas as a runtime timeline.
+
+Part of Motionary's own zero-dependency runtime. Size budget: **3.0 KB gzip** (enforced in CI).
+
+## Prerequisites
+
+1. **Install:** `npm i motionary`
+2. **Import path:** `motionary/runtime/format-apng`
+3. **CDN:**
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/motionary@10/dist/runtime.iife.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/motionary@10/dist/runtime/format-apng.iife.js"></script>
+```
+
+   ESM from a CDN: `https://cdn.jsdelivr.net/npm/motionary@10/dist/runtime/format-apng.js`
+
+4. **Import order & registration:** Register the core first, then the module: use(formatApng) also registers the core. CDN: load runtime.iife.js, then runtime/format-apng.iife.js (it registers itself).
+
+```js
+import { use } from 'motionary/runtime';
+import { formatApng } from 'motionary/runtime/format-apng';
+use(formatApng);
+```
+
+## Example
+
+```js
+import { use } from 'motionary/runtime';
+import { formatApng, loadApng, animatedImagePlayer } from 'motionary/runtime/format-apng';
+use(formatApng);
+const anim = await loadApng('/sticker.png');
+animatedImagePlayer(document.querySelector('canvas'), anim);
+```
+
+## Exports
+
+`formatApng` · `parseApng` · `apngFramePngs` · `decodeApng` · `loadApng` · `animatedImagePlayer`
+
+## Compatibility
+
+| Feature | Supported | Notes |
+|---|---|---|
+| acTL / fcTL / fdAT, frame offsets and delays | ✅ yes |  |
+| dispose_op none / background / previous | ✅ yes | first-frame previous → background (spec) |
+| blend_op source / over | ✅ yes |  |
+| hidden default image (IDAT not part of the animation) | ✅ yes |  |
+| palette / tRNS / gAMA / iCCP / sRGB / sBIT copied into frames | ✅ yes |  |
+| plain (non-animated) PNG | ✅ yes | one frame |
+| decoding | ✅ yes | the browser's PNG decoder (createImageBitmap), or your own { decode } |
+| SSR / workers | ◐ partial | parsing is pure; decoding needs createImageBitmap (workers OK) or { decode } |
+
+## Components that need it
+
+_None yet._

package/docs/runtime/format-gif.md

@@ -0,0 +1,60 @@
+# motionary/runtime/format-gif — GIF decoder
+
+> Generated from `showcase/catalog/prereqs.js` by `scripts/gen-runtime-docs.mjs` — edit the data, not this page.
+
+Decode animated GIFs (own LZW decoder, no DOM) into composited RGBA frames and play / scrub / reverse them on a canvas as a runtime timeline.
+
+Part of Motionary's own zero-dependency runtime. Size budget: **3.0 KB gzip** (enforced in CI).
+
+## Prerequisites
+
+1. **Install:** `npm i motionary`
+2. **Import path:** `motionary/runtime/format-gif`
+3. **CDN:**
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/motionary@10/dist/runtime.iife.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/motionary@10/dist/runtime/format-gif.iife.js"></script>
+```
+
+   ESM from a CDN: `https://cdn.jsdelivr.net/npm/motionary@10/dist/runtime/format-gif.js`
+
+4. **Import order & registration:** Register the core first, then the module: use(formatGif) also registers the core. CDN: load runtime.iife.js, then runtime/format-gif.iife.js (it registers itself).
+
+```js
+import { use } from 'motionary/runtime';
+import { formatGif } from 'motionary/runtime/format-gif';
+use(formatGif);
+```
+
+## Example
+
+```js
+import { use } from 'motionary/runtime';
+import { formatGif, loadGif, animatedImagePlayer } from 'motionary/runtime/format-gif';
+use(formatGif);
+const gif = await loadGif('/loader.gif');
+const player = animatedImagePlayer(document.querySelector('canvas'), gif);
+player.pause(); player.progress = 0.5; // scrub
+```
+
+## Exports
+
+`formatGif` · `decodeGif` · `loadGif` · `lzwDecode` · `animatedImagePlayer`
+
+## Compatibility
+
+| Feature | Supported | Notes |
+|---|---|---|
+| GIF87a / GIF89a | ✅ yes |  |
+| global + local palettes, transparency | ✅ yes |  |
+| interlaced frames | ✅ yes | 4-pass row order |
+| disposal 0–3 (none / keep / background / previous) | ✅ yes | background clears to transparent, like browsers |
+| frame delays, NETSCAPE2.0 / ANIMEXTS loop count | ✅ yes | delays ≤ 10 ms play at 100 ms, like browsers |
+| truncated files | ◐ partial | decodes what is there |
+| plain-text extension | ✕ no | ignored (browsers ignore it too) |
+| SSR / workers | ✅ yes | decoding is pure; the player needs a (Offscreen)Canvas |
+
+## Components that need it
+
+_None yet._

package/docs/runtime/format-sprite.md

@@ -0,0 +1,60 @@
+# motionary/runtime/format-sprite — Sprite sheets & image sequences
+
+> Generated from `showcase/catalog/prereqs.js` by `scripts/gen-runtime-docs.mjs` — edit the data, not this page.
+
+Play TexturePacker / Aseprite sprite sheets and numbered image sequences on a canvas or an element background, as runtime timelines (scrubbable).
+
+Part of Motionary's own zero-dependency runtime. Size budget: **3.0 KB gzip** (enforced in CI).
+
+## Prerequisites
+
+1. **Install:** `npm i motionary`
+2. **Import path:** `motionary/runtime/format-sprite`
+3. **CDN:**
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/motionary@10/dist/runtime.iife.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/motionary@10/dist/runtime/format-sprite.iife.js"></script>
+```
+
+   ESM from a CDN: `https://cdn.jsdelivr.net/npm/motionary@10/dist/runtime/format-sprite.js`
+
+4. **Import order & registration:** Register the core first, then the module: use(formatSprite) also registers the core. CDN: load runtime.iife.js, then runtime/format-sprite.iife.js (it registers itself).
+
+```js
+import { use } from 'motionary/runtime';
+import { formatSprite } from 'motionary/runtime/format-sprite';
+use(formatSprite);
+```
+
+## Example
+
+```js
+import { use } from 'motionary/runtime';
+import { formatSprite, parseSpriteSheet, spritePlayer } from 'motionary/runtime/format-sprite';
+use(formatSprite);
+const sheet = parseSpriteSheet(await (await fetch('/slime.json')).json());
+const img = new Image(); img.src = '/slime.png'; await img.decode();
+spritePlayer(document.querySelector('canvas'), sheet, img, { tag: 'bounce' });
+```
+
+## Exports
+
+`formatSprite` · `parseSpriteSheet` · `gridSheet` · `frameOrder` · `drawFrame` · `spritePlayer` · `imageSequence` · `preloadImages` · `sequencePlayer`
+
+## Compatibility
+
+| Feature | Supported | Notes |
+|---|---|---|
+| TexturePacker JSON (hash + array) | ✅ yes | trimmed (spriteSourceSize / sourceSize) and rotated frames |
+| Aseprite JSON (hash + array), per-frame duration | ✅ yes |  |
+| Aseprite frameTags: forward / reverse / pingpong / pingpong_reverse | ✅ yes |  |
+| plain grid sheets | ✅ yes | gridSheet(cols, rows, w, h) |
+| image sequences (frame_{0001}.webp) | ✅ yes | preloading, cover-fit drawing, scrub via progress |
+| multipack (several atlas images) | ✕ no | load each sheet separately |
+| Aseprite slices / layers | ✕ no | frames only |
+| SSR / workers | ◐ partial | parsing is pure; players need a canvas (OffscreenCanvas works) |
+
+## Components that need it
+
+_None yet._