@syncedco/motion 0.1.0

package/docs/ATTRIBUTE-API.md

@@ -0,0 +1,358 @@
+# Declarative attribute API
+
+Hand-written guide to the most commonly used recipes, with the reasoning behind
+each contract. For the complete generated list of all sixty, see
+[the recipe reference](RECIPE-REFERENCE.md).
+
+Every attribute uses the `data-motion-` prefix.
+
+## Reveal
+
+```html
+<h2 class="sf-text-h2" data-motion-reveal="up">Built for motion</h2>
+```
+
+Values: `fade`, `up`, `down`, `left`, `right`, or `scale`.
+
+Optional attributes: `data-motion-duration`, `data-motion-delay`, `data-motion-ease`, `data-motion-start`, and `data-motion-once`.
+
+### Directional, scale, and clip reveals
+
+```html
+<article data-motion-reveal-directional="left">...</article>
+<figure data-motion-reveal-scale="0.94">...</figure>
+<figure data-motion-reveal-clip="start">
+  <img data-motion-reveal-clip-content src="project.jpg" alt="Project description" />
+</figure>
+```
+
+Directional values are `left`, `right`, `up`, or `down`. Scale values are
+unitless. Clip values are `start` or `end`. Each effect is applied only after
+JavaScript initializes, clears its temporary presentation when complete, and
+leaves the authored final state unchanged for reduced motion.
+
+## Stagger
+
+```html
+<div class="sf-auto-grid" data-motion-stagger="0.08" data-motion-stagger-target=".card">
+  <article class="card">...</article>
+  <article class="card">...</article>
+</div>
+```
+
+## Split text
+
+```html
+<h1
+  data-motion-split="lines"
+  data-motion-stagger="0.08"
+  data-motion-split-mask="true"
+>
+  Editorial motion that follows the layout.
+</h1>
+```
+
+Use `lines`, `words`, `chars`, or a comma-separated combination. Line splits automatically rebuild after font or width changes. Screen readers retain the unsplit accessible label. Masks are opt-in because tight editorial line-height can otherwise clip ascenders, descenders, and punctuation.
+
+### Character, typewriter, and highlight treatments
+
+```html
+<h2 data-motion-chars-shimmer>Character rhythm</h2>
+<p data-motion-typewriter data-motion-typewriter-speed="0.035">System ready</p>
+<p data-motion-text-highlight>
+  Motion follows <span data-motion-text-highlight-mark>meaning</span>.
+</p>
+```
+
+Character and typewriter recipes use SplitText with its automatic accessible
+label and revert the generated wrappers during cleanup. Add
+`data-motion-typewriter-load` when a typewriter should start on load instead of on
+viewport entry. The highlight recipe only scales the marked visual element;
+the text remains present in document order at all times.
+
+## Parallax
+
+```html
+<figure class="sf-frame" data-motion-parallax-scene>
+  <img data-motion-parallax="10" alt="" />
+</figure>
+```
+
+## Scroll progress and depth stack
+
+```html
+<article data-motion-scroll-progress>
+  <span data-motion-scroll-progress-meter aria-hidden="true"></span>
+  <output data-motion-scroll-progress-label aria-label="Reading progress"></output>
+</article>
+
+<section data-motion-scroll-depth-stack>
+  <article data-motion-depth-card>...</article>
+  <article data-motion-depth-card>...</article>
+</section>
+```
+
+The meter uses scale rather than width. The label is optional. Depth cards use
+only opacity and transform and remain fully visible for reduced motion.
+
+## Pinned chapters and product explainers
+
+```html
+<section data-motion-pinned-chapters>
+  <div data-motion-pin-target>...</div>
+  <article data-motion-pinned-chapter>Chapter one</article>
+  <figure data-motion-pinned-visual>...</figure>
+</section>
+
+<section data-motion-product-explainer>
+  <div data-motion-pin-target>...</div>
+  <article data-motion-product-step>Step one</article>
+  <figure data-motion-product-media>...</figure>
+</section>
+```
+
+The runtime synchronizes `data-active` and `aria-current`; consuming CSS owns
+visibility and layout. Without motion, content remains in normal document flow.
+
+## Horizontal galleries and comparison
+
+```html
+<section data-motion-horizontal-gallery>
+  <div data-motion-horizontal-pin>
+    <div data-motion-horizontal-viewport>
+      <div data-motion-horizontal-track>
+        <article data-motion-horizontal-card>...</article>
+      </div>
+    </div>
+  </div>
+</section>
+
+<figure data-motion-comparison>
+  <img src="before.jpg" alt="Before" />
+  <div data-motion-comparison-after><img src="after.jpg" alt="After" /></div>
+  <input data-motion-comparison-range type="range" min="0" max="100" value="50" aria-label="Compare before and after" />
+</figure>
+```
+
+Use `data-motion-horizontal-snap`, `data-motion-horizontal-feature-rail`, or
+`data-motion-horizontal-logo-reel` on the root for the related recipes. Horizontal
+scroll movement is linear and transform-based. The comparison recipe retains a
+native keyboard-operable range input.
+
+## Marquee
+
+```html
+<div data-motion-marquee data-motion-marquee-duration="24">
+  <div data-motion-marquee-track>
+    <div>Semantic motion · Fluid systems ·</div>
+    <div aria-hidden="true">Semantic motion · Fluid systems ·</div>
+  </div>
+</div>
+```
+
+The track contains two identical groups so its transform can loop seamlessly. `data-motion-marquee-duration` sets the loop duration in seconds; add `data-motion-marquee-direction="right"` to reverse it. Marquees pause while off-screen, restore their authored state during cleanup, and remain static when reduced motion is requested.
+
+## Scroll steps
+
+```html
+<section data-motion-scroll-steps data-motion-end="bottom bottom">
+  <div data-motion-pin-target>
+    <nav>
+      <a data-motion-step-link>One</a>
+      <a data-motion-step-link>Two</a>
+    </nav>
+    <div data-motion-step-panel>First panel</div>
+    <div data-motion-step-panel>Second panel</div>
+  </div>
+</section>
+```
+
+The runtime only toggles `data-active` and `aria-current`. Synced Flow or project CSS owns the colors and layout.
+
+## Scroll exit
+
+```html
+<section data-motion-scroll-exit-scene>
+  <div
+    data-motion-scroll-exit="down"
+    data-motion-exit-distance="9rem"
+    data-motion-exit-end="bottom 35%"
+  >
+    ...
+  </div>
+</section>
+```
+
+The element translates `down` or `up` and fades as the scene leaves the viewport. The motion is scrubbed, uses `rem` distances, and is disabled when reduced motion is requested.
+
+## Scroll statement
+
+```html
+<section data-motion-scroll-statement data-motion-scrub="0.8">
+  <div data-motion-statement-pin>
+    <p data-motion-statement-label>A short label</p>
+    <h2 data-motion-statement-heading>
+      <span data-motion-statement-lead>The complete thought </span>
+      <span data-motion-statement-inline-accent>with emphasis.</span>
+    </h2>
+    <span data-motion-statement-hero-accent aria-hidden="true">emphasis</span>
+    <div data-motion-statement-details>
+      <p data-motion-statement-detail>Supporting content</p>
+    </div>
+  </div>
+</section>
+```
+
+The section pins while scrolling and begins with an oversized standalone accent. That accent contracts and crossfades into the full centered statement before the collapsed details expand and reveal in sequence. The markup remains readable without JavaScript and the pinned scrub sequence is disabled for reduced motion.
+
+## Scroll drift
+
+```html
+<section data-motion-scroll-drift data-motion-scrub="0.8">
+  <div data-motion-drift-layer aria-hidden="true">Oversized background mark</div>
+  <div>Readable foreground content</div>
+</section>
+```
+
+The decorative layer moves from `x: 10%` and transparent to its resting position at ten-percent opacity while the section travels from below to above the viewport. Optional `data-motion-drift-from` and `data-motion-drift-opacity` attributes override those defaults. Reduced motion leaves the decorative layer in its authored CSS state.
+
+## Founder statement
+
+```html
+<section data-motion-founder-scene data-motion-scrub="0.8">
+  <div class="sticky-frame">
+    <img src="background.avif" alt="" />
+    <div data-motion-founder-content>
+      <h2 data-motion-founder-heading>A centered statement revealed word by word.</h2>
+    </div>
+  </div>
+</section>
+```
+
+The first content layer fades in while SplitText words rise from below with the measured Union Jack AI timing, holds briefly, then moves down and fades away. The statement background crossfades into a second locally owned background while an oversized metric, label, and three detail columns scale and rise into view. The consuming site owns the sticky frame, content, and background styling. Reduced motion leaves the unsplit heading and authored layout visible.
+
+## Media expansion
+
+```html
+<section data-motion-media-expand data-motion-scrub="0.8">
+  <div class="sticky-frame">
+    <p data-motion-media-expand-prompt>Keep scrolling</p>
+    <span data-motion-media-expand-label="start">©2026</span>
+    <span data-motion-media-expand-label="end">Showreel</span>
+    <figure data-motion-media-expand-frame>
+      <img src="sample.jpg" alt="Sample project artwork" />
+      <figcaption data-motion-media-expand-caption>Play showreel</figcaption>
+    </figure>
+  </div>
+</section>
+```
+
+The image begins as a cropped central pill, expands to the viewport edges through a scrubbed clip-path, and gently scales its contents down. One shared expansion value calculates both the media inset and label anchors on every update, keeping each label immediately outside the true mask edge. When a gutter can no longer contain a label, that label exits the viewport instead of moving behind or over the image. The prompt exits early, the media action appears midway, and the CSS-sticky frame releases to reveal the following footer or section. Reduced motion keeps the authored full media frame readable.
+
+## Hover media
+
+```html
+<div data-motion-hover-group>
+  <a data-motion-hover-key="mission">Mission</a>
+  <a data-motion-hover-key="work">Work</a>
+  <img data-motion-hover-media="mission" alt="" />
+  <img data-motion-hover-media="work" alt="" />
+</div>
+```
+
+Keyboard focus and pointer hover use the same state path.
+
+## Menu
+
+```html
+<nav data-motion-menu>
+  <button data-motion-menu-trigger aria-controls="main-menu">Menu</button>
+  <div id="main-menu" data-motion-menu-panel>
+    <a data-motion-menu-item href="/work">Work</a>
+  </div>
+</nav>
+```
+
+The controller owns `aria-expanded`, `aria-hidden`, Escape handling, focus containment, focus return, and scroll locking.
+
+## Expanding panels
+
+```html
+<div data-motion-expand-group data-motion-expand-default="3">
+  <article tabindex="0" data-motion-expand-panel>...</article>
+  <article tabindex="0" data-motion-expand-panel>...</article>
+  <article tabindex="0" data-motion-expand-panel>...</article>
+  <article tabindex="0" data-motion-expand-panel>...</article>
+</div>
+```
+
+Pointer hover and keyboard focus toggle `data-active` on exactly one panel. The consuming site controls expansion sizes, artwork, and content visibility with CSS.
+
+## Counters, progress, and ambient loops
+
+```html
+<output data-motion-counter data-motion-counter-from="0" data-motion-counter-to="120" data-motion-counter-value>120</output>
+<figure data-motion-progress-ring data-motion-progress="72">
+  <svg viewBox="0 0 120 120"><circle data-motion-progress-ring-value cx="60" cy="60" r="48" /></svg>
+  <output data-motion-progress-ring-label>72%</output>
+</figure>
+<span aria-hidden="true" data-motion-ambient-float></span>
+<div data-motion-logo-belt><div data-motion-logo-belt-track>Two identical logo groups</div></div>
+```
+
+Counters preserve their complete output for assistive technology. Progress
+rings retain a text label. Infinite ambient and logo motion pauses off-screen
+and becomes static under reduced motion.
+
+## FLIP and layout transitions
+
+Use `data-motion-flip-card`, `data-motion-flip-card-trigger`, and
+`data-motion-flip-card-detail` for a controlled card expansion. Filtered grids use
+`data-motion-flip-filter`, `data-motion-filter-control`, and `data-motion-filter-item`.
+Navigation indicators use `data-motion-flip-nav`, `data-motion-flip-nav-item`, and an
+inert `data-motion-flip-nav-indicator`. Accordion grids use
+`data-motion-layout-accordion-grid`, `data-motion-layout-item`, and native
+`data-motion-layout-trigger` buttons.
+
+Application-owned list reorder logic remains outside Motion. Dispatch a scoped
+event after declaring the mutation callback:
+
+```js
+list.dispatchEvent(new CustomEvent('motion:reorder', {
+  detail: { mutate(list, items) { list.append(...items.reverse()) } },
+}))
+```
+
+Synced Motion captures the prior geometry, runs the callback synchronously,
+and animates spatial continuity. Reduced motion runs only the mutation.
+
+## SVG drawing, morphing, and motion paths
+
+```html
+<figure data-motion-svg-line-draw><svg><path data-motion-svg-path d="..." /></svg></figure>
+<figure data-motion-svg-morph>
+  <svg><path data-motion-svg-morph-source d="..." /><path data-motion-svg-morph-target d="..." hidden /></svg>
+  <button data-motion-svg-trigger type="button" aria-pressed="false">Change shape</button>
+</figure>
+<figure data-motion-svg-orbit><svg><path data-motion-svg-orbit-path d="..." /><circle data-motion-svg-orbit-subject /></svg></figure>
+<figure data-motion-svg-signature><svg><path d="..." /></svg></figure>
+```
+
+`data-motion-svg-icon-state` uses the equivalent `data-motion-svg-icon-source` and
+`data-motion-svg-icon-target` slots. Authored paths require visible strokes for
+drawing recipes, and morph source/target paths should have compatible intent.
+
+## Page-load and route motion
+
+Page entrances use `data-motion-page-load-hero` with repeated
+`data-motion-page-load-item` children, or `data-motion-page-load-brand` with an optional
+`data-motion-brand-mark`.
+
+Routers keep ownership of navigation and DOM replacement. A route fade listens
+for `motion:route` on `data-motion-route-fade`; pass optional `outgoing`,
+`incoming`, and `complete` values in `event.detail`. A shared-media root listens
+for `motion:route-shared` and requires a synchronous `detail.mutate`
+callback. `data-motion-route-scroll-restore` listens for
+`motion:route-complete` with `detail.top`, then refreshes ScrollTrigger.
+
+Every route listener is root-scoped and removed by runtime cleanup.

package/docs/CAPABILITIES.md

@@ -0,0 +1,82 @@
+# Synced Motion capability blueprint
+
+Synced Motion reproduces the published-page capabilities that make Webflow useful for animated marketing sites, while keeping layout and visual identity in whatever design system the project already uses.
+
+It is not intended to recreate Webflow's hosted visual Designer, billing platform, hosting, or collaborative SaaS interface.
+
+## System ownership
+
+| Concern | Owner |
+|---|---|
+| Fluid layout, typography, spacing, colors | The consuming design system (Synced Flow is one option) |
+| Semantic application state | Consuming application |
+| Timed animation and sequencing | GSAP through Synced Motion |
+| Scroll progress, pinning, scrub and triggers | ScrollTrigger |
+| Optional smooth scrolling | Lenis adapter |
+| Editable content | Static data or a headless CMS |
+| Localization | Application router or CMS |
+| Testing and personalization | Dedicated analytics/experimentation service |
+
+## Webflow capability mapping
+
+| Webflow capability | Synced implementation |
+|---|---|
+| Designer variables | Synced Flow semantic tokens |
+| Global colors | OKLCH `--sf-colour-*` tokens |
+| Responsive breakpoints | Fluid values, intrinsic layout and container queries |
+| Components | Semantic templates or framework components |
+| Interaction timeline | GSAP timelines and reusable patterns |
+| Scroll reveals | `data-motion-reveal` and ScrollTrigger |
+| Stagger sequences | `data-motion-stagger` |
+| Scroll-linked motion | ScrollTrigger scrub patterns |
+| Pinned storytelling | `data-motion-scroll-steps` and `data-motion-pin-target` |
+| Hover-driven imagery | `data-motion-hover-group` |
+| Menus and overlays | Accessible `data-motion-menu` controller |
+| Smooth scrolling | Optional Lenis adapter |
+| Interaction element IDs | Readable semantic `data-motion-*` hooks |
+| CMS Collections | JSON, Markdown or a headless CMS |
+| Collection pages | Reusable application templates |
+| Conditional visibility | Component or template logic |
+| Localize | Locale routing and CMS localization |
+| Optimize | Separate experimentation integration |
+
+## Included first-release patterns
+
+- entrance and viewport reveals;
+- responsive SplitText line, word, and character reveals;
+- staggered child reveals;
+- scroll-linked parallax;
+- scrubbed directional scroll exits for hero and editorial content;
+- two-stage founder narratives with local background crossfades, word reveals, oversized metrics, and staggered detail groups;
+- full-height editorial offer panels with scrubbed horizontal background drift;
+- pinned mission statements that contract a standalone accent into a complete headline before revealing supporting metrics;
+- pinned media expansions that grow a cropped image pill into a full-viewport feature while pushing adjacent labels outward;
+- pinned multi-step narratives with semantic active states;
+- hover/focus-driven media switching;
+- pointer and keyboard-driven expanding panel groups;
+- accessible animated navigation menus;
+- optional Lenis integration with the GSAP ticker;
+- automatic reduced-motion handling;
+- cleanup for page transitions and hot reload;
+- Synced Flow semantic color integration.
+
+## Production 1.0 expansion
+
+- horizontal scroll galleries;
+- clip-path and mask transitions;
+- cursor-follow and magnetic interactions;
+- SVG drawing and morphing recipes;
+- FLIP-powered layout transitions;
+- route transition adapters;
+- framework adapters for React, Vue, Svelte, Astro, and WordPress;
+- a sixty-recipe catalog, project scaffolding CLI, and local stdio MCP server;
+- a local gallery, inspector diagnostics, and performance metadata;
+- CMS and localization integration examples.
+
+## Design rule
+
+Motion changes presentation, not meaning. Synced Motion toggles semantic states and animates transforms or opacity. It does not inject hardcoded brand colors, typography, or layout values. This ensures that changing a Synced Flow theme cannot be undermined by stale animation values.
+
+## Showcase promotion rule
+
+The example is a consumer of the package. Any timeline, scroll controller, SplitText sequence, or interaction-state controller first demonstrated in the showcase must live in `src/patterns`, be initialized by `createSyncedMotion`, be documented in the attribute API, and be exported from the package entry point. The example may own Synced Flow layout, visual tokens, and CSS transitions that present semantic states; it may not contain direct GSAP, ScrollTrigger, SplitText, or Lenis orchestration.

package/docs/INTEGRATIONS.md

@@ -0,0 +1,92 @@
+# Framework and CMS integrations
+
+All adapters mount the production built-in registry after their DOM root is
+available, scope recipe selectors to that root, expose refresh access, and
+destroy every timeline, trigger, listener, and temporary state on disposal.
+They do not own component styling or layout.
+
+## React
+
+Install the optional peers `react` and `@gsap/react`, then pass a component
+root ref. The returned ref points to the active motion controller after mount.
+
+```jsx
+import { useRef } from 'react'
+import { useSyncedMotion } from '@syncedco/motion/react'
+
+export function Page() {
+  const root = useRef(null)
+  const motion = useSyncedMotion(root)
+  return <main ref={root}>{/* semantic recipe markup */}</main>
+}
+```
+
+The hook uses `useGSAP()` with the supplied scope and reverts the controller on
+unmount or watched dependency changes. Pass a third array argument to remount
+after application state changes that replace recipe markup.
+
+## Vue 3
+
+Install the optional `vue` peer and pass a template ref. The composable mounts
+after `nextTick()` and destroys during `onUnmounted()`.
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { useSyncedMotion } from '@syncedco/motion/vue'
+
+const root = ref()
+const motion = useSyncedMotion(root)
+</script>
+
+<template><main ref="root"><!-- semantic recipe markup --></main></template>
+```
+
+## Svelte
+
+The Svelte entry is an action and does not import the Svelte runtime.
+
+```svelte
+<script>
+  import { syncedMotion } from '@syncedco/motion/svelte'
+</script>
+
+<main use:syncedMotion>{/* semantic recipe markup */}</main>
+```
+
+Updating the action options destroys the prior controller before mounting the
+next one. Component destruction performs the final cleanup.
+
+## Astro
+
+Call the adapter from a client script. It mounts at DOM ready, destroys before
+an Astro view-transition swap, and remounts on `astro:page-load`.
+
+```js
+import { createAstroMotion } from '@syncedco/motion/astro'
+
+const motion = createAstroMotion({ root: '#page' })
+```
+
+## WordPress
+
+The WordPress adapter requires no jQuery and no WordPress JavaScript global.
+It mounts at DOM ready and supports block or navigation replacements through
+semantic document events.
+
+```js
+import { createWordPressMotion } from '@syncedco/motion/wordpress'
+
+const motion = createWordPressMotion({ root: '#page' })
+
+// After replacing a dynamic block or page fragment:
+document.dispatchEvent(new CustomEvent('motion:mount', {
+  detail: { root: document.querySelector('#updated-region') },
+}))
+
+// After layout-only changes:
+document.dispatchEvent(new Event('motion:refresh'))
+```
+
+Calling `motion.destroy()` removes these event listeners and destroys the
+active scoped runtime.

package/docs/PERFORMANCE.md

@@ -0,0 +1,150 @@
+# Bundle size and performance
+
+Animation code runs on every page view, so what you ship matters. This page
+explains what each entry point costs, how to ship less, and how the numbers are
+kept honest.
+
+## Measured cost
+
+| Scenario | gzip | GSAP plugins pulled in |
+| --- | --- | --- |
+| `createSyncedMotion()` — all sixty recipes | 16.9 kB | ScrollTrigger |
+| `@syncedco/motion/full` — all sixty plus every plugin | 17.0 kB | ScrollTrigger, SplitText, Flip, DrawSVG, MorphSVG, MotionPath |
+| Three individually imported recipes | 5.8 kB | ScrollTrigger |
+
+GSAP itself is a peer dependency and is excluded from these figures — you
+already ship it. The plugin column matters: those modules come out of the
+`gsap` package and land in your bundle, and they are considerably larger than
+this package.
+
+Run the numbers yourself:
+
+```bash
+npm run size:check
+```
+
+## Entry points
+
+| Import | Use it when |
+| --- | --- |
+| `@syncedco/motion` | The default. Every recipe, GSAP and ScrollTrigger only. |
+| `@syncedco/motion/full` | You want the seventeen plugin-backed recipes and don't want to think about it. |
+| `@syncedco/motion/recipes` | You want to ship only the recipes this page uses. |
+| `@syncedco/motion/plugins` | You want the plugin set to pass through `dependencies`. |
+
+## Shipping only what you use
+
+Every recipe is an individually importable, side-effect-free export. Import the
+ones you need and build a registry from them:
+
+```js
+import { createMotionRuntime, createMotionRegistry } from '@syncedco/motion'
+import { revealRise, revealStaggerCascade, marquee } from '@syncedco/motion/recipes'
+
+const motion = createMotionRuntime({
+  registry: createMotionRegistry(
+    [revealRise, revealStaggerCascade, marquee],
+    { mode: 'runtime' },
+  ),
+})
+```
+
+`mode: 'runtime'` tells the registry to accept lean specs. See
+[the recipe system](RECIPES.md#runtime-specs-and-authoring-metadata) for why
+those are separate.
+
+Recipe export names are the camelCase form of the recipe ID: `reveal-rise`
+becomes `revealRise`, `pinned-steps` becomes `pinnedSteps`. The full list is in
+[the recipe reference](RECIPE-REFERENCE.md).
+
+## Optional GSAP plugins
+
+Forty-three of the sixty recipes need nothing beyond GSAP and ScrollTrigger.
+The other seventeen need one of SplitText, Flip, DrawSVG, MorphSVG or
+MotionPath. Importing all five in the core would put roughly sixty kilobytes of
+GSAP into every consumer's bundle to serve a minority of recipes, so the core
+does not import them.
+
+If a page contains markup for a recipe whose plugin is missing, that recipe is
+skipped and says why:
+
+```js
+motion.inspect().skipped
+// [{
+//   id: 'split-lines-rise',
+//   reason: 'missing-dependency',
+//   dependencies: ['SplitText'],
+//   fix: 'Pass { dependencies: { SplitText } } or import from "@syncedco/motion/full".'
+// }]
+```
+
+Nothing is hidden and no content disappears — the markup stays in its authored
+state, which is the same thing that happens when JavaScript fails entirely.
+
+Two ways to resolve it:
+
+```js
+// Everything, one import.
+import { createSyncedMotion } from '@syncedco/motion/full'
+
+// Or only the plugin you actually need.
+import { SplitText } from 'gsap/SplitText'
+createSyncedMotion({ dependencies: { SplitText } })
+```
+
+The diagnostic is reported per matched root, so you only hear about a missing
+plugin when the page really uses that recipe.
+
+Which recipes need what:
+
+| Plugin | Recipes |
+| --- | --- |
+| SplitText | 5 |
+| Flip | 6 |
+| DrawSVGPlugin | 3 |
+| MorphSVGPlugin | 2 |
+| MotionPathPlugin | 1 |
+
+[The recipe reference](RECIPE-REFERENCE.md) flags each one.
+
+## Runtime cost
+
+- **Transforms and opacity first.** The compiler rejects declarative recipes
+  that animate `width`, `height`, `top`, `left`, `margin` or `padding` unless
+  they set `performance.allowLayout`.
+- **Every recipe declares a performance class** of `low`, `medium` or `high`.
+  `synced-motion compose` warns when a plan contains more than two high-cost
+  recipes.
+- **Mounting is scoped.** Each recipe queries within its own root; nothing
+  scans the document repeatedly at runtime.
+- **Off-screen loops pause.** Marquees and belts observe intersection and stop
+  when they are not visible.
+- **Reduced motion is resolved through `gsap.matchMedia()`**, so switching the
+  preference reverts and remounts cleanly instead of leaving orphaned tweens.
+
+Inspect what mounted, what was skipped and what failed at any time:
+
+```js
+motion.inspect()
+// { active, reduced, registered, mounted, skipped, errors }
+```
+
+## Budgets
+
+`scripts/check-size.mjs` links the built package into a throwaway
+`node_modules`, bundles each scenario with esbuild, and fails if a gzip budget
+regresses. It measures the published package rather than `./src` deliberately:
+bundlers only honour the `sideEffects` field for packages inside
+`node_modules`, so measuring source would overstate how well tree-shaking
+works.
+
+Budgets are part of the contract. Raise them deliberately, in a commit that
+says why.
+
+## Keeping recipes tree-shakeable
+
+Recipe specs are annotated `/* @__PURE__ */` so a bundler may drop the ones you
+never reference. Both the spec call and the nested `setupFactory(...)` call need
+the annotation — without it on the inner call, esbuild cannot prove the
+initialiser is side-effect free and retains all sixty. `npm run size:check`
+catches this.