vectorvesper 2.0.7 → 2.1.1

package/dist/hooks.json

@@ -1,17 +1,700 @@
 {
   "version": "1.0.0",
   "engineVersion": "1.0.2",
-  "generatedAt": "2026-08-01T08:17:45.626Z",
-  "contractLevel": "lean",
+  "generatedAt": "2026-08-09T14:27:32.779Z",
+  "contractLevel": "full",
   "hooks": [
     {
-      "contractLevel": "lean",
+      "name": "AdaptiveQuality",
+      "importFrom": "@vectorvesper/motion",
+      "packageName": "@vectorvesper/motion",
+      "since": "0.2.0",
+      "category": "core",
+      "tier": "free",
+      "aliases": [
+        "getAdaptiveQuality",
+        "device detection",
+        "gpu tier",
+        "low-end device",
+        "device capability",
+        "webgl detection",
+        "reduced motion",
+        "quality signal"
+      ],
+      "exports": [
+        "getAdaptiveQuality"
+      ],
+      "tagline": "Device floor fused with live frame health — the core accessor.",
+      "problem": "Imperative scene code — a three.js renderer, a shader compiler, a Framer code component — needs the complete quality verdict without a React tree to host the hook.",
+      "summary": "getAdaptiveQuality() returns the fusion singleton. subscribe(fn) fires with the current state immediately, then whenever the live budget tier changes; .state answers one-off checks. The effective tier is max(deviceTier, budgetTier) — the device floor is probed lazily on first use (WebGL2, renderer class, memory, cores) and never changes while the page is open; the budget half tracks live frame health. reducedMotion is carried in the same state. In React, prefer the useAdaptiveQuality hook.",
+      "mechanism": "First use runs a one-time probe: create a WebGL2 context, read the unmasked renderer string, release the context, and score it with conservative zero-dependency heuristics — no WebGL2 or a software renderer floors the device at the lowest tier, a mobile-class GPU floors it one below top, and constrained memory or few cores push one tier worse. Every verdict is recorded as a human-readable reason. The floor exists because measurement alone oscillates on weak devices: degrade, frames recover because you degraded, upgrade, jank, forever. Fusion takes the worse of floor and live budget; listeners are notified when the budget side changes tier.",
+      "signature": "getAdaptiveQuality().subscribe(fn: (s: AdaptiveState) => void): () => void  ·  .state: AdaptiveState",
+      "options": [],
+      "returns": [
+        {
+          "name": "state",
+          "type": "AdaptiveState",
+          "description": "{ tier, label, deviceTier, budgetTier, reasons: string[], reducedMotion }. Consume tier — it is already the most restrictive verdict. reasons is for HUDs and support."
+        }
+      ],
+      "runtime": {
+        "lane": null,
+        "priority": null,
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": false,
+        "reRendersPerFrame": 0,
+        "usesPointer": false,
+        "usesScroll": false,
+        "usesWebGL": true,
+        "ownsTransform": false,
+        "sharedSingletons": [
+          "AnimationBudget",
+          "AdaptiveQuality"
+        ],
+        "conflictsWith": [],
+        "pairsWith": [
+          "useAdaptiveQuality",
+          "AnimationBudget",
+          "useSafeToMount"
+        ]
+      },
+      "quickStart": "import { getAdaptiveQuality } from \"@vectorvesper/motion\";\n\nconst stop = getAdaptiveQuality().subscribe((q) => {\n  renderer.setPixelRatio(q.tier === 0 ? window.devicePixelRatio : 1);\n  bloomPass.enabled = q.tier === 0 && !q.reducedMotion;\n});\n\n// stop() on teardown.",
+      "recipes": [
+        {
+          "name": "Sizing a scene before it exists",
+          "blurb": "One .state read at construction time — no subscription needed for a static choice.",
+          "code": "import { getAdaptiveQuality } from \"@vectorvesper/motion\";\n\nexport function particleCountForThisDevice(): number {\n  const { tier, reducedMotion } = getAdaptiveQuality().state;\n  if (reducedMotion) return 0;\n  return tier === 0 ? 5000 : tier === 1 ? 1500 : 300;\n}"
+        }
+      ],
+      "dos": [
+        "Consume the fused tier, not the halves — each half alone is wrong in a known way.",
+        "Honor reducedMotion independently of tier; it is a preference, not a performance state.",
+        "Use reasons in diagnostics HUDs, never in user-facing copy."
+      ],
+      "donts": [
+        "Don't re-derive your own verdict from deviceTier and budgetTier.",
+        "Don't call the probe path in SSR — subscribe and .state are client-only."
+      ],
+      "whenNotToUse": [
+        {
+          "when": "You are in React and want conditional rendering.",
+          "instead": "useAdaptiveQuality — same singleton with lifecycle handled."
+        },
+        {
+          "when": "You only need a reduced-motion check.",
+          "instead": "window.matchMedia(\"(prefers-reduced-motion: reduce)\") — no probe required."
+        }
+      ],
+      "guardrails": [
+        "practices/frame-loop-rules.md"
+      ],
+      "docsUrl": "https://vectorvesper.dev/docs/adaptive-quality",
+      "labUrl": "https://vectorvesper.dev/docs/adaptive-quality",
+      "disclosure": {
+        "exposeImplementation": false,
+        "reason": "Reproducing this hook's implementation makes the consumer run a private requestAnimationFrame loop instead of joining the shared FrameConductor. That silently removes the coordination, scheduling and frame-budget governance the runtime exists to provide, and nothing errors when it happens. Copying is a correctness bug, not just a licensing question.",
+        "correctUsage": "Install @vectorvesper/motion and import the hook. Never inline, reimplement, or paste an equivalent.",
+        "readingSource": "The `mechanism` field above is the answer to almost every 'how does this actually work' question, and it is written for the version you have. Prefer it. The published package is minified and ships no sourcemaps, so node_modules is a poor place to read from — but @vectorvesper/motion is MIT, so the real source is readable in the repository if you want it. Either way it changes nothing about the output: what you write is still an import. A copy compiles, passes review and silently runs its own rAF loop outside the conductor, so 'I read the source and it looked simple' is exactly how that bug gets shipped."
+      }
+    },
+    {
+      "name": "AnimationBudget",
+      "importFrom": "@vectorvesper/motion",
+      "packageName": "@vectorvesper/motion",
+      "since": "0.1.0",
+      "category": "core",
+      "tier": "free",
+      "aliases": [
+        "getAnimationBudget",
+        "fps monitor",
+        "performance tier",
+        "frame health",
+        "degrade quality",
+        "quality tier",
+        "headroom",
+        "budget reset",
+        "route change reset"
+      ],
+      "exports": [
+        "getAnimationBudget"
+      ],
+      "tagline": "The frame-health governor's core accessor — subscribe, poll, and reset.",
+      "problem": "Non-React code needs the live quality tier, frame callbacks need to poll it without React, and SPA navigations need to reset the rolling window — none of which the React hook exposes.",
+      "summary": "getAnimationBudget() returns the governor singleton. subscribe(fn) delivers the current state immediately, then tier changes and a ~2Hz heartbeat; it measures only while at least one subscriber exists. .state is the poll path for frame callbacks. reset() discards the rolling window — call it on SPA route changes so a new scene is not judged by the frames the previous one produced. In React, prefer the useAnimationBudget hook for rendering decisions.",
+      "mechanism": "A pure hysteresis state machine consumes frame intervals measured on the conductor's input lane at essential priority. It keeps a ninety-frame rolling window, makes no verdict before forty samples, and scores frames against thresholds that are multiples of the measured display refresh interval — so a 120Hz panel limping at 70fps is correctly called slow. Degrading is fast, with a cooldown between steps and a panic path that jumps straight to the lowest tier on a burst of very slow frames; upgrading needs eight seconds of near-clean frames, which is what stops quality flapping. Frames longer than 150ms are treated as tab sleep and reset the window rather than trigger a false panic; returning from a hidden tab resets automatically. Headroom is honest about vsync: while frames land on time, the only attributable consumption is the runtime's own measured work, so headroom is budget minus work; once a frame runs slow, the wall clock is the truth and headroom goes negative by the overrun.",
+      "signature": "getAnimationBudget().subscribe(fn: (s: BudgetState) => void): () => void  ·  .state: BudgetState  ·  .reset(): void",
+      "options": [],
+      "returns": [
+        {
+          "name": "state",
+          "type": "BudgetState",
+          "description": "{ tier: 0|1|2, label, avgFrameMs, slowRatio, headroom, workMs, frameBudgetMs }. tier is the verdict; headroom is the leading indicator useSafeToMount gates on."
+        }
+      ],
+      "runtime": {
+        "lane": "input",
+        "priority": "essential",
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": false,
+        "reRendersPerFrame": 0,
+        "usesPointer": false,
+        "usesScroll": false,
+        "usesWebGL": false,
+        "ownsTransform": false,
+        "sharedSingletons": [
+          "FrameConductor",
+          "AnimationBudget"
+        ],
+        "conflictsWith": [],
+        "pairsWith": [
+          "useAnimationBudget",
+          "useSafeToMount",
+          "AdaptiveQuality"
+        ]
+      },
+      "quickStart": "import { getAnimationBudget } from \"@vectorvesper/motion\";\n\nconst stop = getAnimationBudget().subscribe((budget) => {\n  // Fires immediately, then on tier changes and a slow heartbeat.\n  scene.setQuality(budget.tier); // 0 high · 1 medium · 2 low\n});\n\n// stop() when the consumer goes away — the governor only measures while subscribed.",
+      "recipes": [
+        {
+          "name": "SPA route change",
+          "blurb": "A new scene must not inherit the previous scene's frame history.",
+          "code": "import { getAnimationBudget } from \"@vectorvesper/motion\";\n\n// Next.js App Router: call from a top-level effect keyed on pathname.\n\"use client\";\nimport { usePathname } from \"next/navigation\";\nimport { useEffect } from \"react\";\n\nexport function BudgetRouteReset() {\n  const pathname = usePathname();\n  useEffect(() => { getAnimationBudget().reset(); }, [pathname]);\n  return null;\n}"
+        },
+        {
+          "name": "Polling inside frame work",
+          "blurb": "Frame callbacks poll .state — never the React hook, never per-frame subscribe.",
+          "code": "import { getConductor, getAnimationBudget } from \"@vectorvesper/motion\";\n\nconst off = getConductor().subscribe(\"render\", (dt) => {\n  const { tier } = getAnimationBudget().state;\n  drawParticles(tier === 0 ? 4000 : tier === 1 ? 1200 : 200, dt);\n}, { priority: \"decorative\", label: \"Particles\" });"
+        }
+      ],
+      "dos": [
+        "Keep exactly one subscription per consumer and release it — measurement follows subscribers.",
+        "Poll .state inside frame callbacks; subscribe for discrete reactions.",
+        "Call reset() on SPA navigations."
+      ],
+      "donts": [
+        "Don't recreate WebGL contexts on tier changes — adapt the live scene.",
+        "Don't treat one heartbeat emission as a change; compare tiers."
+      ],
+      "whenNotToUse": [
+        {
+          "when": "You are in React and want conditional rendering.",
+          "instead": "useAnimationBudget — same singleton, correct consumption pattern."
+        },
+        {
+          "when": "You need a first-paint decision before any frames exist.",
+          "instead": "AdaptiveQuality — its device floor answers instantly; this governor is blind for ~40 frames."
+        }
+      ],
+      "guardrails": [
+        "practices/frame-loop-rules.md"
+      ],
+      "docsUrl": "https://vectorvesper.dev/docs/animation-budget",
+      "labUrl": "https://vectorvesper.dev/docs/animation-budget",
+      "disclosure": {
+        "exposeImplementation": false,
+        "reason": "Reproducing this hook's implementation makes the consumer run a private requestAnimationFrame loop instead of joining the shared FrameConductor. That silently removes the coordination, scheduling and frame-budget governance the runtime exists to provide, and nothing errors when it happens. Copying is a correctness bug, not just a licensing question.",
+        "correctUsage": "Install @vectorvesper/motion and import the hook. Never inline, reimplement, or paste an equivalent.",
+        "readingSource": "The `mechanism` field above is the answer to almost every 'how does this actually work' question, and it is written for the version you have. Prefer it. The published package is minified and ships no sourcemaps, so node_modules is a poor place to read from — but @vectorvesper/motion is MIT, so the real source is readable in the repository if you want it. Either way it changes nothing about the output: what you write is still an import. A copy compiles, passes review and silently runs its own rAF loop outside the conductor, so 'I read the source and it looked simple' is exactly how that bug gets shipped."
+      }
+    },
+    {
+      "name": "FrameConductor",
+      "importFrom": "@vectorvesper/motion",
+      "packageName": "@vectorvesper/motion",
+      "since": "0.1.0",
+      "category": "core",
+      "tier": "free",
+      "aliases": [
+        "conductor",
+        "getConductor",
+        "frame loop",
+        "raf",
+        "requestAnimationFrame",
+        "animation loop",
+        "scheduler",
+        "ticker",
+        "game loop",
+        "custom effect",
+        "per-frame",
+        "frame budget"
+      ],
+      "exports": [
+        "getConductor"
+      ],
+      "tagline": "The one requestAnimationFrame loop for the page, with a scheduler inside.",
+      "problem": "Every effect that starts its own requestAnimationFrame loop adds another drifting clock, another interleaving of reads and writes, and another callback the browser must run — and ten uncoordinated loops jank where ten coordinated subscribers would not.",
+      "summary": "getConductor() returns the page-wide singleton loop that every Vector Vesper primitive runs on. Custom frame work subscribes to one of three ordered lanes — input (read), update (compute), render (write) — and declares a priority so the scheduler can shed decorative work when a frame runs long. The loop starts with its first subscriber, sleeps after its last, and is the ONLY sanctioned way to run per-frame work in a Vector Vesper project.",
+      "mechanism": "A lazy module-level singleton wraps one requestAnimationFrame chain. Each tick computes dt from the previous timestamp, clamps it to 100ms so a backgrounded tab waking up cannot feed a multi-second delta into damping math, then walks the three lanes in fixed order: input, update, render. Reads therefore always complete before writes, which is what keeps layout from being recomputed more than once per frame however many effects subscribe.\n\nSubscribers declare a priority. Essential work always runs. Enhanced work is skipped for the remainder of a frame once roughly seventy percent of the frame budget is already spent; decorative work yields at roughly forty-five percent. The budget is the measured display refresh interval — a probe watches real frame timings, so a 120Hz panel is held to its own 8.3ms, not an assumed 60Hz. Shedding is per frame and starvation-guarded: a subscriber skipped four consecutive frames is forced through, so heavy pages degrade ambient work to a lower cadence instead of freezing it.\n\nA subscriber may also declare hz to cap its own cadence. Skipped time is banked and handed over as an accumulated dt on the frame it does run, so frame-rate-independent damping stays mathematically correct at any cadence — a 30Hz background looks identical and costs half.\n\nCost attribution is free by construction: the scheduler must read the clock after each subscriber anyway to know how much frame is left, so the same timestamp powers the shed decision and a per-subscriber cost table (exposed via getStats, rendered by the devtools overlay). One broken subscriber cannot kill the heartbeat: exceptions are caught, reported once per subscriber, and the loop continues.",
+      "signature": "getConductor().subscribe(lane: \"input\" | \"update\" | \"render\", fn: (dt: number, time: number) => void, options?: SubscribeOptions): () => void",
+      "options": [
+        {
+          "name": "priority",
+          "type": "\"essential\" | \"enhanced\" | \"decorative\"",
+          "default": "\"enhanced\"",
+          "required": false,
+          "description": "Shed order under load. essential never sheds — reserve it for sensors, governors and direct manipulation (a scrub that stutters is a broken scrub). Ambient garnish is decorative."
+        },
+        {
+          "name": "hz",
+          "type": "number",
+          "default": "— (every frame)",
+          "required": false,
+          "description": "Cadence cap in runs per second. The dt passed in accumulates across skipped frames, so damping math stays correct at any cadence."
+        },
+        {
+          "name": "label",
+          "type": "string",
+          "default": "\"anonymous\"",
+          "required": false,
+          "description": "Name shown in the devtools cost table and slow-subscriber warnings. Always pass one — an unlabeled subscriber is invisible in every diagnostic."
+        }
+      ],
+      "returns": [
+        {
+          "name": "unsubscribe",
+          "type": "() => void",
+          "description": "Removes the subscriber. Safe to call twice. In React, return it from the effect that subscribed — the loop sleeps when its last subscriber leaves."
+        }
+      ],
+      "runtime": {
+        "lane": null,
+        "priority": null,
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": false,
+        "reRendersPerFrame": 0,
+        "usesPointer": false,
+        "usesScroll": false,
+        "usesWebGL": false,
+        "ownsTransform": false,
+        "sharedSingletons": [
+          "FrameConductor"
+        ],
+        "conflictsWith": [
+          "Private requestAnimationFrame loops — they run outside the budget, invisible to shedding and devtools.",
+          "setInterval-driven animation — wrong clock, fights vsync."
+        ],
+        "pairsWith": [
+          "useSensorBus",
+          "damp",
+          "useAnimationBudget"
+        ]
+      },
+      "quickStart": "\"use client\";\nimport { useEffect, useRef } from \"react\";\nimport { getConductor, damp } from \"@vectorvesper/motion\";\n\nexport function Breathe() {\n  const ref = useRef<HTMLDivElement>(null);\n\n  useEffect(() => {\n    let current = 0;\n    return getConductor().subscribe(\"render\", (dt, time) => {\n      const target = Math.sin(time * 1.5) * 12;\n      current = damp(current, target, 8, dt);\n      if (ref.current) ref.current.style.transform = `translate3d(0, ${current}px, 0)`;\n    }, { priority: \"decorative\", label: \"Breathe\" });\n  }, []);\n\n  return <div ref={ref}>V</div>;\n}",
+      "recipes": [
+        {
+          "name": "Read/write split across lanes",
+          "blurb": "Measure in input, write in render. Every subscriber's reads then land before any subscriber's writes — layout is computed at most once per frame, page-wide.",
+          "code": "\"use client\";\nimport { useEffect, useRef } from \"react\";\nimport { getConductor } from \"@vectorvesper/motion\";\n\nexport function ProgressMeter({ value }: { value: number }) {\n  const track = useRef<HTMLDivElement>(null);\n  const bar = useRef<HTMLDivElement>(null);\n  const valueRef = useRef(value);\n  valueRef.current = value;\n\n  useEffect(() => {\n    let width = 1;\n    const offRead = getConductor().subscribe(\"input\", () => {\n      const r = track.current?.getBoundingClientRect();\n      if (r) width = Math.max(r.width, 1);\n    }, { label: \"ProgressMeter(measure)\" });\n\n    const offWrite = getConductor().subscribe(\"render\", () => {\n      if (bar.current) bar.current.style.transform = `scaleX(${valueRef.current / width})`;\n    }, { label: \"ProgressMeter\" });\n\n    return () => { offRead(); offWrite(); };\n  }, []);\n\n  return <div ref={track}><div ref={bar} /></div>;\n}"
+        },
+        {
+          "name": "Ambient background at half cost",
+          "blurb": "Declare hz and decorative priority — the scheduler does the rest.",
+          "code": "import { getConductor } from \"@vectorvesper/motion\";\n\nconst off = getConductor().subscribe(\"render\", (dt) => {\n  drawAurora(dt); // your canvas draw — dt is banked across skipped frames\n}, { priority: \"decorative\", hz: 30, label: \"AuroraBackground\" });\n\n// Later, when the scene unmounts: off();"
+        },
+        {
+          "name": "Development diagnostics",
+          "blurb": "configure() and getStats() — find the subscriber eating the frame.",
+          "code": "import { getConductor } from \"@vectorvesper/motion\";\n\n// Warn once per subscriber that blows past 4ms on a single frame.\ngetConductor().configure({ slowSubscriberMs: 4 });\n\n// A 2Hz HUD — getStats() allocates, so never call it inside a frame callback.\nsetInterval(() => {\n  const stats = getConductor().getStats();\n  console.table(stats.subscribers.map((s) => ({\n    label: s.label, lane: s.lane, ms: s.costMs.toFixed(2), shed: s.shed,\n  })));\n}, 500);"
+        }
+      ],
+      "dos": [
+        "Subscribe inside an effect and return the unsubscribe function as the cleanup.",
+        "Pass a label on every subscription — it is the name in every diagnostic you will ever read.",
+        "Keep per-frame values in refs or locals; write results straight to the DOM.",
+        "Pick the lane by what the callback does: reads in input, math in update, writes in render.",
+        "Declare decorative priority (and an hz cap) for anything the user would not miss for one frame."
+      ],
+      "donts": [
+        "Don't call requestAnimationFrame yourself anywhere in a Vector Vesper project.",
+        "Don't setState inside a frame callback — that is a React render per frame.",
+        "Don't read layout in the render lane; a read after earlier writes forces synchronous layout.",
+        "Don't call getStats() inside a frame callback — it allocates; poll it at a human rate.",
+        "Don't mark your effect essential to dodge shedding; essential is for sensors, governors and direct manipulation."
+      ],
+      "whenNotToUse": [
+        {
+          "when": "A hook already expresses the behaviour (magnetic pull, number tick, video scrub, image trail).",
+          "instead": "Use the hook. The conductor is the floor custom effects are built on, not a replacement for the primitives already built on it."
+        },
+        {
+          "when": "A one-off entrance, exit, or hover transition on a single element.",
+          "instead": "Use a CSS transition or the Web Animations API — the compositor interpolates for free and no frame-loop subscription is needed."
+        },
+        {
+          "when": "Discrete state changes on events — a click that toggles a class, a form update.",
+          "instead": "Use a plain event listener. Per-frame work is for continuous values only."
+        },
+        {
+          "when": "You need pointer or scroll velocity.",
+          "instead": "Read it from useSensorBus / getSensorBus — the bus already computes damped derivatives once per frame on the input lane. Computing your own duplicates the work."
+        }
+      ],
+      "guardrails": [
+        "practices/frame-loop-rules.md",
+        "practices/layout-read-discipline.md",
+        "practices/react-motion-rules.md"
+      ],
+      "docsUrl": "https://vectorvesper.dev/docs/frame-conductor",
+      "labUrl": "https://vectorvesper.dev/docs/frame-conductor",
+      "disclosure": {
+        "exposeImplementation": false,
+        "reason": "Reproducing this hook's implementation makes the consumer run a private requestAnimationFrame loop instead of joining the shared FrameConductor. That silently removes the coordination, scheduling and frame-budget governance the runtime exists to provide, and nothing errors when it happens. Copying is a correctness bug, not just a licensing question.",
+        "correctUsage": "Install @vectorvesper/motion and import the hook. Never inline, reimplement, or paste an equivalent.",
+        "readingSource": "The `mechanism` field above is the answer to almost every 'how does this actually work' question, and it is written for the version you have. Prefer it. The published package is minified and ships no sourcemaps, so node_modules is a poor place to read from — but @vectorvesper/motion is MIT, so the real source is readable in the repository if you want it. Either way it changes nothing about the output: what you write is still an import. A copy compiles, passes review and silently runs its own rAF loop outside the conductor, so 'I read the source and it looked simple' is exactly how that bug gets shipped."
+      }
+    },
+    {
+      "name": "SensorBus",
+      "importFrom": "@vectorvesper/motion",
+      "packageName": "@vectorvesper/motion",
+      "since": "0.1.0",
+      "category": "core",
+      "tier": "free",
+      "aliases": [
+        "getSensorBus",
+        "sensor bus",
+        "mouse position",
+        "pointer position",
+        "pointer velocity",
+        "scroll velocity",
+        "scroll position",
+        "viewport size",
+        "device pixel ratio",
+        "input listeners"
+      ],
+      "exports": [
+        "getSensorBus",
+        "SensorBus"
+      ],
+      "tagline": "The shared input singleton — pointer, scroll and viewport, computed once per frame.",
+      "problem": "Non-React code and custom effects need the same pointer, scroll and viewport state the hooks read — and attaching their own listeners reintroduces exactly the duplication the bus removes.",
+      "summary": "getSensorBus() returns the page-wide input singleton. retain() it (ref-counted — the first consumer attaches the passive listeners, the last release detaches them), then read .state.pointer / .state.scroll / .state.viewport inside conductor frame callbacks. Positions are CSS pixels; velocities are damped, in pixels per second. In React, prefer the useSensorBus hook — it is this accessor plus lifecycle.",
+      "mechanism": "One lazily-created instance for the page. Passive pointer listeners write raw coordinates onto plain fields; scroll and viewport are not listened to at all but sampled inside the frame tick, which catches programmatic scrolls that fire no event. All derivatives are computed once per frame in the conductor's input lane at essential priority, so every consumer in update or render reads values produced this frame. Velocity is an instantaneous delta smoothed with frame-rate-independent exponential damping at k = 14. The state objects are live and mutated in place — the stable reference is why nothing re-renders and why retaining a copy goes stale immediately. Ref-counting means fifty consumers cost one set of listeners, and the last release detaches everything and zeroes velocities.",
+      "signature": "getSensorBus(): SensorBus  ·  bus.retain(): () => void  ·  bus.state: SensorState",
+      "options": [],
+      "returns": [
+        {
+          "name": "state.pointer",
+          "type": "{ x, y, vx, vy, speed, down, seen }",
+          "description": "Client-space position (CSS px), damped velocity (px/s), speed magnitude, primary-button state, and seen — false until the first movement; check it before positioning anything."
+        },
+        {
+          "name": "state.scroll",
+          "type": "{ x, y, vx, vy }",
+          "description": "window scroll position sampled per frame, plus damped velocity in px/s."
+        },
+        {
+          "name": "state.viewport",
+          "type": "{ width, height, dpr }",
+          "description": "innerWidth / innerHeight / devicePixelRatio, resynced every frame."
+        }
+      ],
+      "runtime": {
+        "lane": "input",
+        "priority": "essential",
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": false,
+        "reRendersPerFrame": 0,
+        "usesPointer": true,
+        "usesScroll": true,
+        "usesWebGL": false,
+        "ownsTransform": false,
+        "sharedSingletons": [
+          "FrameConductor",
+          "SensorBus"
+        ],
+        "conflictsWith": [],
+        "pairsWith": [
+          "FrameConductor",
+          "damp",
+          "usePointerIntent"
+        ]
+      },
+      "quickStart": "import { getSensorBus, getConductor } from \"@vectorvesper/motion\";\n\n// Framework-agnostic: works in vanilla JS, Vue, Svelte, or a Framer code component.\nconst release = getSensorBus().retain();\n\nconst off = getConductor().subscribe(\"render\", () => {\n  const { x, y, seen } = getSensorBus().state.pointer;\n  if (seen) document.documentElement.style.setProperty(\"--pointer\", `${x}px ${y}px`);\n}, { label: \"PointerVar\" });\n\n// Teardown when the consumer goes away:\n// off(); release();",
+      "recipes": [
+        {
+          "name": "Vue integration",
+          "blurb": "The hook is only a lifecycle wrapper — any framework's mount/unmount works.",
+          "code": "import { getSensorBus, getConductor, damp } from \"@vectorvesper/motion\";\nimport { onMounted, onUnmounted } from \"vue\";\n\nexport function usePointerGlow(el: () => HTMLElement | null) {\n  let cleanup = () => {};\n  onMounted(() => {\n    const release = getSensorBus().retain();\n    let glow = 0;\n    const off = getConductor().subscribe(\"render\", (dt) => {\n      const { speed } = getSensorBus().state.pointer;\n      glow = damp(glow, Math.min(speed / 1200, 1), 10, dt);\n      el()?.style.setProperty(\"--glow\", glow.toFixed(3));\n    }, { priority: \"decorative\", label: \"PointerGlow\" });\n    cleanup = () => { off(); release(); };\n  });\n  onUnmounted(() => cleanup());\n}"
+        }
+      ],
+      "dos": [
+        "retain() before reading, and keep the release function — listeners follow the last consumer out.",
+        "Read state fields fresh inside each frame callback; the objects are live.",
+        "Check pointer.seen before deriving anything from coordinates."
+      ],
+      "donts": [
+        "Don't spread or store bus.state as a snapshot — a copy goes stale the next frame.",
+        "Don't mutate the state objects.",
+        "Don't attach your own pointermove/scroll listeners alongside the bus."
+      ],
+      "whenNotToUse": [
+        {
+          "when": "You are in React.",
+          "instead": "Use the useSensorBus hook — same singleton, lifecycle handled."
+        },
+        {
+          "when": "One element needs one discrete event.",
+          "instead": "A plain event listener. The bus is for continuous per-frame values."
+        }
+      ],
+      "guardrails": [
+        "practices/frame-loop-rules.md"
+      ],
+      "docsUrl": "https://vectorvesper.dev/docs/sensor-bus",
+      "labUrl": "https://vectorvesper.dev/docs/sensor-bus",
+      "disclosure": {
+        "exposeImplementation": false,
+        "reason": "Reproducing this hook's implementation makes the consumer run a private requestAnimationFrame loop instead of joining the shared FrameConductor. That silently removes the coordination, scheduling and frame-budget governance the runtime exists to provide, and nothing errors when it happens. Copying is a correctness bug, not just a licensing question.",
+        "correctUsage": "Install @vectorvesper/motion and import the hook. Never inline, reimplement, or paste an equivalent.",
+        "readingSource": "The `mechanism` field above is the answer to almost every 'how does this actually work' question, and it is written for the version you have. Prefer it. The published package is minified and ships no sourcemaps, so node_modules is a poor place to read from — but @vectorvesper/motion is MIT, so the real source is readable in the repository if you want it. Either way it changes nothing about the output: what you write is still an import. A copy compiles, passes review and silently runs its own rAF loop outside the conductor, so 'I read the source and it looked simple' is exactly how that bug gets shipped."
+      }
+    },
+    {
+      "name": "damp",
+      "importFrom": "@vectorvesper/motion",
+      "packageName": "@vectorvesper/motion",
+      "since": "0.1.0",
+      "category": "core",
+      "tier": "free",
+      "aliases": [
+        "lerp",
+        "smoothing",
+        "easing",
+        "interpolation",
+        "exponential decay",
+        "smooth follow",
+        "clamp",
+        "clamp01",
+        "rayRectIntersect",
+        "math helpers"
+      ],
+      "exports": [
+        "damp",
+        "clamp01",
+        "rayRectIntersect"
+      ],
+      "tagline": "Frame-rate-independent smoothing, a clamp, and a trajectory-intersection test.",
+      "problem": "The lerp everyone writes — current += (target - current) * 0.1 per frame — runs twice as fast at 120Hz as at 60Hz, so the interaction that felt right on the build machine feels wrong on half the devices that open it.",
+      "summary": "damp(current, target, k, dt) moves a value toward its target with exponential decay that is identical at any frame rate, because dt is part of the math. k is responsiveness per second — higher arrives faster; 6–14 covers most UI feels. clamp01 clamps to [0,1]. rayRectIntersect casts a point and velocity against a rectangle and returns time-to-impact in seconds, or null — the primitive behind pointer-intent prediction, usable for your own.",
+      "mechanism": "damp computes current plus the remaining distance scaled by one minus e to the minus k dt — the closed-form solution of exponential decay over an arbitrary timestep. Because the decay constant is applied through dt, thirty large steps and a hundred and twenty small ones land on the same curve, which is exactly what a fixed-factor lerp gets wrong. It pairs with the conductor's dt, including the banked dt handed to hz-throttled subscribers, which is why a 30Hz decorative effect keeps the same feel. rayRectIntersect is a standard slab test: it returns the earliest positive time at which the ray enters the rectangle, or null when the trajectory misses — inputs are client-space position, velocity in pixels per second, and a rect; the result divided into a horizon gives an approach-confidence curve.",
+      "signature": "damp(current: number, target: number, k: number, dt: number): number  ·  clamp01(v: number): number  ·  rayRectIntersect(x, y, vx, vy, rect: RectLike): number | null",
+      "options": [
+        {
+          "name": "k",
+          "type": "number",
+          "default": "—",
+          "required": true,
+          "description": "Responsiveness per second. 4–6 is languid, 8–12 is standard UI follow, 14+ is snappy. Double k is roughly half the settling time."
+        },
+        {
+          "name": "dt",
+          "type": "number",
+          "default": "—",
+          "required": true,
+          "description": "Seconds since this callback last ran. Always pass the conductor's dt — never a constant."
+        }
+      ],
+      "returns": [
+        {
+          "name": "value",
+          "type": "number",
+          "description": "The smoothed next value. Feed it back as `current` on the next frame."
+        }
+      ],
+      "runtime": {
+        "lane": null,
+        "priority": null,
+        "requiresClient": false,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": false,
+        "reRendersPerFrame": 0,
+        "usesPointer": false,
+        "usesScroll": false,
+        "usesWebGL": false,
+        "ownsTransform": false,
+        "sharedSingletons": [],
+        "conflictsWith": [],
+        "pairsWith": [
+          "FrameConductor",
+          "SensorBus"
+        ]
+      },
+      "quickStart": "import { getConductor, damp } from \"@vectorvesper/motion\";\n\nlet x = 0;\nlet targetX = 0;\n\nwindow.addEventListener(\"pointermove\", (e) => { targetX = e.clientX; }, { passive: true });\n\nconst off = getConductor().subscribe(\"render\", (dt) => {\n  x = damp(x, targetX, 10, dt);\n  el.style.transform = `translate3d(${x}px, 0, 0)`;\n}, { label: \"Follower\" });",
+      "recipes": [
+        {
+          "name": "Approach prediction with rayRectIntersect",
+          "blurb": "The same math usePointerIntent uses, applied to your own target — time-to-impact against a rect, turned into a 0..1 confidence.",
+          "code": "import { getConductor, getSensorBus, rayRectIntersect, clamp01, damp } from \"@vectorvesper/motion\";\n\nconst release = getSensorBus().retain();\nconst HORIZON = 0.5; // seconds of look-ahead\nlet confidence = 0;\n\nconst off = getConductor().subscribe(\"update\", (dt) => {\n  const { pointer } = getSensorBus().state;\n  const rect = target.getBoundingClientRect();\n  const tHit = pointer.seen\n    ? rayRectIntersect(pointer.x, pointer.y, pointer.vx, pointer.vy, rect)\n    : null;\n  const goal = tHit !== null && tHit <= HORIZON ? clamp01(1 - tHit / HORIZON) : 0;\n  confidence = damp(confidence, goal, 10, dt);\n}, { label: \"ApproachConfidence\" });"
+        }
+      ],
+      "dos": [
+        "Always pass the conductor's dt through — that is the whole point.",
+        "Snap to the target when the remaining distance is imperceptible (< ~0.01) to end the decay tail.",
+        "Keep the running value in a local or ref between frames."
+      ],
+      "donts": [
+        "Don't substitute a fixed factor per frame; that reintroduces frame-rate dependence.",
+        "Don't use damp for one-shot transitions with a known end time — that is a tween, use CSS or WAAPI."
+      ],
+      "whenNotToUse": [
+        {
+          "when": "A transition with a fixed duration and easing curve.",
+          "instead": "CSS transitions or the Web Animations API — damp has no duration, only a feel."
+        },
+        {
+          "when": "Physics with overshoot and bounce.",
+          "instead": "damp is pure decay and never overshoots. Use a spring model (or a springy CSS linear() easing) when the design calls for bounce."
+        }
+      ],
+      "guardrails": [
+        "practices/frame-loop-rules.md"
+      ],
+      "docsUrl": "https://vectorvesper.dev/docs/frame-conductor",
+      "labUrl": "https://vectorvesper.dev/docs/frame-conductor",
+      "disclosure": {
+        "exposeImplementation": false,
+        "reason": "Reproducing this hook's implementation makes the consumer run a private requestAnimationFrame loop instead of joining the shared FrameConductor. That silently removes the coordination, scheduling and frame-budget governance the runtime exists to provide, and nothing errors when it happens. Copying is a correctness bug, not just a licensing question.",
+        "correctUsage": "Install @vectorvesper/motion and import the hook. Never inline, reimplement, or paste an equivalent.",
+        "readingSource": "The `mechanism` field above is the answer to almost every 'how does this actually work' question, and it is written for the version you have. Prefer it. The published package is minified and ships no sourcemaps, so node_modules is a poor place to read from — but @vectorvesper/motion is MIT, so the real source is readable in the repository if you want it. Either way it changes nothing about the output: what you write is still an import. A copy compiles, passes review and silently runs its own rAF loop outside the conductor, so 'I read the source and it looked simple' is exactly how that bug gets shipped."
+      }
+    },
+    {
+      "name": "mountDevtools",
+      "importFrom": "@vectorvesper/motion/devtools",
+      "packageName": "@vectorvesper/motion",
+      "since": "0.3.0",
+      "category": "core",
+      "tier": "free",
+      "aliases": [
+        "devtools",
+        "overlay",
+        "fps meter",
+        "profiler",
+        "frame cost",
+        "performance hud",
+        "debug panel",
+        "stats panel"
+      ],
+      "exports": [
+        "mountDevtools"
+      ],
+      "tagline": "A live overlay showing which effect is spending the frame.",
+      "problem": "\"One rAF loop\" and \"decorative work sheds under load\" are claims until you can watch the numbers move — and browser profilers cannot attribute frame cost per effect.",
+      "summary": "mountDevtools() docks a small panel showing the runtime's vitals — fps against the measured display rate, the runtime's own work per frame, headroom, the live tier — and a table of every conductor subscriber with its lane, priority, and smoothed per-frame cost in milliseconds, most expensive first. It is a plain DOM function on a separate entry point: call it from any framework or the console, and it never reaches a bundle that does not explicitly import it.",
+      "mechanism": "The panel renders into a shadow root so page styles cannot reach in and its styles cannot leak out. It refreshes at five hertz by reading the conductor's stats snapshot — the same per-subscriber cost the scheduler already measures for shed decisions, so the overlay adds no per-frame instrumentation of its own. Nodes are built once and updated through textContent, and the panel lists itself in its own table rather than hiding its cost. Subscriber rows show the label each subscription registered with, which is why passing a label is a rule everywhere else in this manifest.",
+      "signature": "mountDevtools(options?: DevtoolsOptions): () => void",
+      "options": [
+        {
+          "name": "position",
+          "type": "\"top-left\" | \"top-right\" | \"bottom-left\" | \"bottom-right\"",
+          "default": "\"bottom-right\"",
+          "required": false,
+          "description": "Which corner to dock in."
+        },
+        {
+          "name": "expanded",
+          "type": "boolean",
+          "default": "true",
+          "required": false,
+          "description": "Start with the subscriber table open; collapsed shows a one-line fps readout."
+        },
+        {
+          "name": "hz",
+          "type": "number",
+          "default": "5",
+          "required": false,
+          "description": "Panel refresh rate — a human cadence, never per frame."
+        },
+        {
+          "name": "container",
+          "type": "HTMLElement",
+          "default": "document.body",
+          "required": false,
+          "description": "Node to attach the host element to."
+        }
+      ],
+      "returns": [
+        {
+          "name": "unmount",
+          "type": "() => void",
+          "description": "Removes the panel and its refresh timer."
+        }
+      ],
+      "runtime": {
+        "lane": null,
+        "priority": null,
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": false,
+        "reRendersPerFrame": 0,
+        "usesPointer": false,
+        "usesScroll": false,
+        "usesWebGL": false,
+        "ownsTransform": false,
+        "sharedSingletons": [
+          "FrameConductor",
+          "AnimationBudget"
+        ],
+        "conflictsWith": [],
+        "pairsWith": [
+          "FrameConductor",
+          "useAnimationBudget"
+        ]
+      },
+      "quickStart": "\"use client\";\nimport { useEffect } from \"react\";\nimport { mountDevtools } from \"@vectorvesper/motion/devtools\";\n\nexport function MotionDevtools() {\n  useEffect(() => {\n    if (process.env.NODE_ENV === \"production\") return;\n    return mountDevtools();\n  }, []);\n  return null;\n}",
+      "recipes": [
+        {
+          "name": "Console spot-check",
+          "blurb": "On any page running the runtime, paste one line to see the table.",
+          "code": "const { mountDevtools } = await import(\"@vectorvesper/motion/devtools\");\nconst off = mountDevtools({ position: \"top-right\" });\n// off() to remove."
+        }
+      ],
+      "dos": [
+        "Gate it behind a development check — it is honest overhead.",
+        "Label every conductor subscription; unlabeled rows all read \"anonymous\".",
+        "Read \"work vs frame\": small work with a large frame means the cost is outside the runtime."
+      ],
+      "donts": [
+        "Don't ship it to production bundles.",
+        "Don't use it as a user-facing fps meter — build a HUD from the stats accessors instead."
+      ],
+      "whenNotToUse": [
+        {
+          "when": "Profiling React commits, layout, or GC.",
+          "instead": "The browser's own performance panel — this overlay attributes conductor subscribers only."
+        }
+      ],
+      "guardrails": [
+        "practices/frame-loop-rules.md"
+      ],
+      "docsUrl": "https://vectorvesper.dev/docs/devtools",
+      "labUrl": "https://vectorvesper.dev/docs/devtools",
+      "disclosure": {
+        "exposeImplementation": false,
+        "reason": "Reproducing this hook's implementation makes the consumer run a private requestAnimationFrame loop instead of joining the shared FrameConductor. That silently removes the coordination, scheduling and frame-budget governance the runtime exists to provide, and nothing errors when it happens. Copying is a correctness bug, not just a licensing question.",
+        "correctUsage": "Install @vectorvesper/motion and import the hook. Never inline, reimplement, or paste an equivalent.",
+        "readingSource": "The `mechanism` field above is the answer to almost every 'how does this actually work' question, and it is written for the version you have. Prefer it. The published package is minified and ships no sourcemaps, so node_modules is a poor place to read from — but @vectorvesper/motion is MIT, so the real source is readable in the repository if you want it. Either way it changes nothing about the output: what you write is still an import. A copy compiles, passes review and silently runs its own rAF loop outside the conductor, so 'I read the source and it looked simple' is exactly how that bug gets shipped."
+      }
+    },
+    {
       "name": "useAdaptiveQuality",
       "importFrom": "@vectorvesper/motion/react",
       "packageName": "@vectorvesper/motion",
       "since": "0.1.0",
       "category": "governor",
       "tier": "free",
+      "aliases": [
+        "adaptive quality",
+        "device tier",
+        "quality tier",
+        "low end device",
+        "gpu detection",
+        "progressive enhancement"
+      ],
       "tagline": "Device capability fused with live frame health — the complete quality signal.",
       "problem": "Measured frame health is the truth but is blind for the first seconds; device signals guess instantly but never learn. Using either alone gets one of those wrong.",
       "summary": "Probes the device once (WebGL2, GPU renderer string, memory, cores, reduced-motion) and fuses that with the live AnimationBudget as `tier = max(deviceTier, budgetTier)`. The device tier is a FLOOR, and that is the whole point: without it, weak devices oscillate forever — degrade, frames recover because you degraded, upgrade, jank, degrade. A software renderer stays a software renderer. `reasons` explains the device verdict.",
@@ -50,7 +733,53 @@
           "description": "Whether the user asked for reduced motion."
         }
       ],
+      "runtime": {
+        "lane": "input",
+        "priority": "essential",
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": true,
+        "reRendersPerFrame": 0,
+        "usesPointer": false,
+        "usesScroll": false,
+        "usesWebGL": true,
+        "ownsTransform": false,
+        "sharedSingletons": [
+          "FrameConductor",
+          "AnimationBudget",
+          "AdaptiveQuality"
+        ],
+        "conflictsWith": [],
+        "pairsWith": [
+          "useAnimationBudget",
+          "useLazyScene",
+          "useSafeToMount"
+        ]
+      },
       "quickStart": "\"use client\";\nimport { useAdaptiveQuality } from \"@vectorvesper/motion/react\";\n\nexport function Scene() {\n  const { tier, reducedMotion } = useAdaptiveQuality();\n  if (reducedMotion) return <Poster />;\n  return tier === 0 ? <FullScene /> : <LightScene />;\n}",
+      "recipes": [
+        {
+          "name": "Hero Background",
+          "blurb": "Resolve tier into a real settings object once, then hand it to the renderer. The settings — not the tier number — are what your canvas actually consumes.",
+          "code": "\"use client\";\nimport { useAdaptiveQuality } from \"@vectorvesper/motion/react\";\n\nconst SETTINGS = {\n  0: { dpr: 2, particles: 220, glow: true,  linkLines: true  },\n  1: { dpr: 1, particles: 90,  glow: false, linkLines: false },\n  2: { dpr: 1, particles: 34,  glow: false, linkLines: false },\n} as const;\n\nexport function AuroraHero() {\n  const { tier, reducedMotion } = useAdaptiveQuality();\n  if (reducedMotion) return <StaticGradient />;\n  return <AuroraCanvas settings={SETTINGS[tier]} />;\n}"
+        },
+        {
+          "name": "Explaining the verdict",
+          "blurb": "Surface `reasons` in a debug panel — it turns support tickets into one screenshot.",
+          "code": "\"use client\";\nimport { useAdaptiveQuality } from \"@vectorvesper/motion/react\";\n\nexport function QualityBadge() {\n  const { label, deviceTier, budgetTier, reasons } = useAdaptiveQuality();\n  const clampedBy = deviceTier > budgetTier ? \"device\" : budgetTier > deviceTier ? \"load\" : \"neither\";\n  return (\n    <div className=\"font-mono text-xs\">\n      {label} · clamped by {clampedBy} · {reasons.join(\", \")}\n    </div>\n  );\n}"
+        }
+      ],
+      "dos": [
+        "Consume `tier`, not `deviceTier` or `budgetTier` — the fused value is the answer.",
+        "Always branch on `reducedMotion` before anything else; it is a user request, not a performance signal.",
+        "Resolve tier into a settings object in one place, so the ladder is auditable.",
+        "Show `reasons` in a dev HUD — it is the fastest way to understand a slow device report."
+      ],
+      "donts": [
+        "Don't expect the device probe to re-run. It happens once per page; a thermally throttled phone will not be re-classified.",
+        "Don't call it inside a frame loop.",
+        "Don't treat tier 2 as broken — it is a working page with the decoration removed."
+      ],
       "whenNotToUse": [
         {
           "when": "You have no WebGL, canvas or heavy effects on the page.",
@@ -65,42 +794,34 @@
           "instead": "Use `useAnimationBudget`. This hook deliberately clamps to a device floor and will not report tier 0 on a machine it judged weak, no matter how clean the frames are."
         }
       ],
+      "guardrails": [
+        "practices/adaptive-performance.md",
+        "practices/webgl-budget-and-failopen.md"
+      ],
       "docsUrl": "https://vectorvesper.dev/docs/adaptive-quality",
       "labUrl": "https://vectorvesper.dev/lab/adaptive-quality",
       "disclosure": {
         "exposeImplementation": false,
         "reason": "Reproducing this hook's implementation makes the consumer run a private requestAnimationFrame loop instead of joining the shared FrameConductor. That silently removes the coordination, scheduling and frame-budget governance the runtime exists to provide, and nothing errors when it happens. Copying is a correctness bug, not just a licensing question.",
         "correctUsage": "Install @vectorvesper/motion and import the hook. Never inline, reimplement, or paste an equivalent.",
-        "readingSource": "If you want to read the real implementation, you can: @vectorvesper/motion is MIT, ships unminified, and its sourcemaps carry the original TypeScript in sourcesContent — so node_modules/@vectorvesper/motion/dist has every line, no reconstruction needed. Read it freely to understand or debug. It changes nothing about the output: what you write is still an import. A copy compiles, passes review and silently runs its own rAF loop outside the conductor, so 'I read the source and it looked simple' is exactly how this bug gets shipped. Start with the `mechanism` field above — it is usually the whole answer, and it is current with the version you have."
-      },
-      "runtime": {
-        "requiresClient": true,
-        "ssrSafeImport": true,
-        "respectsReducedMotion": true,
-        "ownsTransform": false,
-        "conflictsWith": [],
-        "usesPointer": false,
-        "usesScroll": false,
-        "usesWebGL": true,
-        "lane": "input",
-        "priority": "essential",
-        "reRendersPerFrame": 0,
-        "sharedSingletons": [
-          "FrameConductor",
-          "AnimationBudget",
-          "AdaptiveQuality"
-        ]
-      },
-      "upgrade": "This is the lean contract: enough to understand the hook and use it correctly. The full contract adds named real-world recipes with complete code, the accumulated dos and don'ts, and routing into the motion guardrails. Available to Vector Vesper members — authenticate the CLI with `npx vectorvesper login <token>`."
+        "readingSource": "The `mechanism` field above is the answer to almost every 'how does this actually work' question, and it is written for the version you have. Prefer it. The published package is minified and ships no sourcemaps, so node_modules is a poor place to read from — but @vectorvesper/motion is MIT, so the real source is readable in the repository if you want it. Either way it changes nothing about the output: what you write is still an import. A copy compiles, passes review and silently runs its own rAF loop outside the conductor, so 'I read the source and it looked simple' is exactly how that bug gets shipped."
+      }
     },
     {
-      "contractLevel": "lean",
       "name": "useAnimationBudget",
       "importFrom": "@vectorvesper/motion/react",
       "packageName": "@vectorvesper/motion",
       "since": "0.1.0",
       "category": "governor",
       "tier": "free",
+      "aliases": [
+        "frame budget",
+        "fps",
+        "performance tier",
+        "degrade quality",
+        "shed effects",
+        "jank detection"
+      ],
       "tagline": "A live quality tier from measured frame health, so effects can shed themselves.",
       "problem": "A page looks fine on the machine it was built on and janks on the device it ships to, and nothing in the code knows the difference.",
       "summary": "Measures real frame intervals on the shared conductor and collapses them into a coarse tier every effect can consume. Hysteresis is asymmetric on purpose: degrading is fast (users feel jank within a second), recovering takes 8 seconds of clean frames, so quality never flaps. Since v0.3 the thresholds are relative to the measured display refresh rate, so 70fps on a 120Hz panel correctly reads as degraded.",
@@ -144,7 +865,58 @@
           "description": "One presented frame at the detected display rate."
         }
       ],
+      "runtime": {
+        "lane": "input",
+        "priority": "essential",
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": false,
+        "reRendersPerFrame": 0,
+        "usesPointer": false,
+        "usesScroll": false,
+        "usesWebGL": false,
+        "ownsTransform": false,
+        "sharedSingletons": [
+          "FrameConductor",
+          "AnimationBudget"
+        ],
+        "conflictsWith": [],
+        "pairsWith": [
+          "useAdaptiveQuality",
+          "useSafeToMount",
+          "useLazyScene"
+        ]
+      },
       "quickStart": "\"use client\";\nimport { useAnimationBudget } from \"@vectorvesper/motion/react\";\n\nexport function Hero() {\n  const { tier } = useAnimationBudget();\n  return (\n    <section>\n      {tier === 0 && <ExpensiveParticleLayer />}\n      <HeroContent />\n    </section>\n  );\n}",
+      "recipes": [
+        {
+          "name": "Storefront Grid",
+          "blurb": "Shed decoration in cost order and never touch content. The image, title, price and buy button are not on the list at any tier.",
+          "code": "\"use client\";\nimport { useAnimationBudget } from \"@vectorvesper/motion/react\";\n\nexport function ProductCard({ product }: { product: Product }) {\n  const { tier } = useAnimationBudget();\n  return (\n    <article className={tier < 1 ? \"backdrop-blur-xl\" : \"bg-neutral-900\"}>\n      {tier === 0 && <span className=\"shimmer-sweep\" aria-hidden />}\n      <img src={product.image} alt={product.name} />\n      <h3>{product.name}</h3>\n      <p>{product.price}</p>\n      <button>Add to cart</button>\n    </article>\n  );\n}"
+        },
+        {
+          "name": "Telemetry HUD",
+          "blurb": "Show the numbers during development. Emits on tier change plus a ~2Hz heartbeat.",
+          "code": "\"use client\";\nimport { useAnimationBudget } from \"@vectorvesper/motion/react\";\n\nexport function PerfHud() {\n  const { label, avgFrameMs, workMs, headroom } = useAnimationBudget();\n  return (\n    <div className=\"fixed bottom-3 right-3 font-mono text-xs\">\n      {label} · {avgFrameMs.toFixed(1)}ms frame · {workMs.toFixed(2)}ms ours · {headroom.toFixed(1)}ms free\n    </div>\n  );\n}"
+        },
+        {
+          "name": "Reading it inside a frame loop",
+          "blurb": "Never call the hook per frame — poll the singleton instead.",
+          "code": "import { getAnimationBudget, getConductor } from \"@vectorvesper/motion\";\n\nconst budget = getAnimationBudget();\nconst release = budget.subscribe(() => {});   // keeps it measuring\n\nconst off = getConductor().subscribe(\"render\", () => {\n  const particles = budget.state.tier === 0 ? 220 : 40;\n  draw(particles);\n}, { priority: \"decorative\", label: \"Particles\" });"
+        }
+      ],
+      "dos": [
+        "Use it for conditional rendering of expensive subtrees — that is the intended consumption pattern.",
+        "Treat tier as a ladder: shed the most expensive decoration first.",
+        "Call `getAnimationBudget().reset()` on SPA route changes so a new scene isn't judged by the old one's frames.",
+        "Remember the governor only measures while something is subscribed."
+      ],
+      "donts": [
+        "Don't call this hook inside a rAF callback — poll `getAnimationBudget().state` there.",
+        "Don't degrade content. Text, images, prices and controls are never decoration.",
+        "Don't build your own thresholds off `avgFrameMs`; the tier already has hysteresis you would be fighting.",
+        "Don't expect instant recovery — an upgrade needs 8 seconds of clean frames, deliberately."
+      ],
       "whenNotToUse": [
         {
           "when": "You want to gate a one-time expensive mount.",
@@ -159,41 +931,34 @@
           "instead": "Use a plain `matchMedia(\"(prefers-reduced-motion: reduce)\")` check. Starting a frame-measurement loop for an accessibility preference is disproportionate."
         }
       ],
+      "guardrails": [
+        "practices/adaptive-performance.md",
+        "practices/frame-loop-rules.md"
+      ],
       "docsUrl": "https://vectorvesper.dev/docs/animation-budget",
       "labUrl": "https://vectorvesper.dev/lab/animation-budget",
       "disclosure": {
         "exposeImplementation": false,
         "reason": "Reproducing this hook's implementation makes the consumer run a private requestAnimationFrame loop instead of joining the shared FrameConductor. That silently removes the coordination, scheduling and frame-budget governance the runtime exists to provide, and nothing errors when it happens. Copying is a correctness bug, not just a licensing question.",
         "correctUsage": "Install @vectorvesper/motion and import the hook. Never inline, reimplement, or paste an equivalent.",
-        "readingSource": "If you want to read the real implementation, you can: @vectorvesper/motion is MIT, ships unminified, and its sourcemaps carry the original TypeScript in sourcesContent — so node_modules/@vectorvesper/motion/dist has every line, no reconstruction needed. Read it freely to understand or debug. It changes nothing about the output: what you write is still an import. A copy compiles, passes review and silently runs its own rAF loop outside the conductor, so 'I read the source and it looked simple' is exactly how this bug gets shipped. Start with the `mechanism` field above — it is usually the whole answer, and it is current with the version you have."
-      },
-      "runtime": {
-        "requiresClient": true,
-        "ssrSafeImport": true,
-        "respectsReducedMotion": false,
-        "ownsTransform": false,
-        "conflictsWith": [],
-        "usesPointer": false,
-        "usesScroll": false,
-        "usesWebGL": false,
-        "lane": "input",
-        "priority": "essential",
-        "reRendersPerFrame": 0,
-        "sharedSingletons": [
-          "FrameConductor",
-          "AnimationBudget"
-        ]
-      },
-      "upgrade": "This is the lean contract: enough to understand the hook and use it correctly. The full contract adds named real-world recipes with complete code, the accumulated dos and don'ts, and routing into the motion guardrails. Available to Vector Vesper members — authenticate the CLI with `npx vectorvesper login <token>`."
+        "readingSource": "The `mechanism` field above is the answer to almost every 'how does this actually work' question, and it is written for the version you have. Prefer it. The published package is minified and ships no sourcemaps, so node_modules is a poor place to read from — but @vectorvesper/motion is MIT, so the real source is readable in the repository if you want it. Either way it changes nothing about the output: what you write is still an import. A copy compiles, passes review and silently runs its own rAF loop outside the conductor, so 'I read the source and it looked simple' is exactly how that bug gets shipped."
+      }
     },
     {
-      "contractLevel": "lean",
       "name": "useImageTrail",
       "importFrom": "@vectorvesper/motion/react",
       "packageName": "@vectorvesper/motion",
       "since": "0.1.0",
       "category": "effect",
       "tier": "free",
+      "aliases": [
+        "image trail",
+        "cursor trail",
+        "mouse trail",
+        "trail effect",
+        "gallery flourish",
+        "images follow cursor"
+      ],
       "tagline": "Images spawn along the pointer's path and fade — the award-site gallery flourish.",
       "problem": "The tutorial version creates a DOM node per pointer move and lets the garbage collector deal with it, which is exactly the allocation pattern that produces stutter.",
       "summary": "A fixed pool of `<img>` nodes is created once and recycled. Each flight is animated with the Web Animations API, so there is no rAF loop and nothing is allocated per move — the oldest flight is simply cancelled and reused. Spawns are distance-gated, not event-gated, so the spacing stays even at any pointer speed. Fails open (does nothing) on touch devices and under reduced motion.",
@@ -229,21 +994,65 @@
           "description": "Flight duration in ms."
         },
         {
-          "name": "maxActive",
-          "type": "number",
-          "default": "10",
-          "required": false,
-          "description": "Pool size, i.e. maximum simultaneously visible images. This is a hard ceiling on cost."
+          "name": "maxActive",
+          "type": "number",
+          "default": "10",
+          "required": false,
+          "description": "Pool size, i.e. maximum simultaneously visible images. This is a hard ceiling on cost."
+        }
+      ],
+      "returns": [
+        {
+          "name": "ref",
+          "type": "RefObject<T | null>",
+          "description": "Attach to the container. The hook sets its position and overflow, and restores both on unmount."
+        }
+      ],
+      "runtime": {
+        "lane": null,
+        "priority": null,
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": true,
+        "reRendersPerFrame": 0,
+        "usesPointer": true,
+        "usesScroll": false,
+        "usesWebGL": false,
+        "ownsTransform": false,
+        "sharedSingletons": [],
+        "conflictsWith": [
+          "A container with `overflow: visible` required — the hook sets overflow hidden to clip the trail."
+        ],
+        "pairsWith": [
+          "useAdaptiveQuality",
+          "usePointerIntent"
+        ]
+      },
+      "quickStart": "\"use client\";\nimport { useImageTrail } from \"@vectorvesper/motion/react\";\n\nexport function Gallery() {\n  const { ref } = useImageTrail<HTMLElement>({\n    images: [\"/a.jpg\", \"/b.jpg\", \"/c.jpg\"],\n  });\n  return <section ref={ref} className=\"relative h-[70vh]\">Move your cursor</section>;\n}",
+      "recipes": [
+        {
+          "name": "Hero Background",
+          "blurb": "A full-bleed hero where the trail sits behind the headline.",
+          "code": "\"use client\";\nimport { useImageTrail } from \"@vectorvesper/motion/react\";\n\nconst SHOTS = [\"/work/1.webp\", \"/work/2.webp\", \"/work/3.webp\", \"/work/4.webp\"];\n\nexport function TrailHero() {\n  const { ref } = useImageTrail<HTMLElement>({ images: SHOTS, size: 220, spacing: 120 });\n  return (\n    <section ref={ref} className=\"relative grid h-screen place-items-center\">\n      <h1 className=\"pointer-events-none relative z-10 text-6xl font-semibold\">Selected work</h1>\n    </section>\n  );\n}"
+        },
+        {
+          "name": "Budget-aware trail",
+          "blurb": "Shrink the pool on weak devices rather than turning the effect off entirely.",
+          "code": "\"use client\";\nimport { useImageTrail, useAdaptiveQuality } from \"@vectorvesper/motion/react\";\n\nexport function AdaptiveTrail({ images }: { images: string[] }) {\n  const { tier } = useAdaptiveQuality();\n  const { ref } = useImageTrail<HTMLDivElement>({\n    images,\n    maxActive: tier === 0 ? 12 : tier === 1 ? 6 : 3,\n    spacing: tier === 0 ? 90 : 140,\n  });\n  return <div ref={ref} className=\"relative h-[60vh]\" />;\n}"
         }
       ],
-      "returns": [
-        {
-          "name": "ref",
-          "type": "RefObject<T | null>",
-          "description": "Attach to the container. The hook sets its position and overflow, and restores both on unmount."
-        }
+      "dos": [
+        "Preload the images, or serve them small and cached — a cold fetch mid-trail shows as a hole.",
+        "Give the container real height; it is positioned and clipped by the hook.",
+        "Add `pointer-events: none` to overlaid text so the trail keeps receiving moves.",
+        "Keep `maxActive` low. It is the hard ceiling on how expensive this can get."
+      ],
+      "donts": [
+        "Don't change the options after mount — they are snapshotted, by design.",
+        "Don't use large PNGs. Ten simultaneous full-resolution images is the failure mode.",
+        "Don't put it on a container that needs `overflow: visible`.",
+        "Don't rely on it for anything meaningful; it is inert on touch and under reduced motion."
       ],
-      "quickStart": "\"use client\";\nimport { useImageTrail } from \"@vectorvesper/motion/react\";\n\nexport function Gallery() {\n  const { ref } = useImageTrail<HTMLElement>({\n    images: [\"/a.jpg\", \"/b.jpg\", \"/c.jpg\"],\n  });\n  return <section ref={ref} className=\"relative h-[70vh]\">Move your cursor</section>;\n}",
       "whenNotToUse": [
         {
           "when": "You want a single image that follows the cursor.",
@@ -258,40 +1067,34 @@
           "instead": "Use a real gallery grid. Trail images are decorative, `aria-hidden`, and visible for under a second each."
         }
       ],
+      "guardrails": [
+        "practices/texture-and-media-gotchas.md",
+        "practices/adaptive-performance.md"
+      ],
       "docsUrl": "https://vectorvesper.dev/docs/image-trail",
       "labUrl": "https://vectorvesper.dev/lab/image-trail",
       "disclosure": {
         "exposeImplementation": false,
         "reason": "Reproducing this hook's implementation makes the consumer run a private requestAnimationFrame loop instead of joining the shared FrameConductor. That silently removes the coordination, scheduling and frame-budget governance the runtime exists to provide, and nothing errors when it happens. Copying is a correctness bug, not just a licensing question.",
         "correctUsage": "Install @vectorvesper/motion and import the hook. Never inline, reimplement, or paste an equivalent.",
-        "readingSource": "If you want to read the real implementation, you can: @vectorvesper/motion is MIT, ships unminified, and its sourcemaps carry the original TypeScript in sourcesContent — so node_modules/@vectorvesper/motion/dist has every line, no reconstruction needed. Read it freely to understand or debug. It changes nothing about the output: what you write is still an import. A copy compiles, passes review and silently runs its own rAF loop outside the conductor, so 'I read the source and it looked simple' is exactly how this bug gets shipped. Start with the `mechanism` field above — it is usually the whole answer, and it is current with the version you have."
-      },
-      "runtime": {
-        "requiresClient": true,
-        "ssrSafeImport": true,
-        "respectsReducedMotion": true,
-        "ownsTransform": false,
-        "conflictsWith": [
-          "A container with `overflow: visible` required — the hook sets overflow hidden to clip the trail."
-        ],
-        "usesPointer": true,
-        "usesScroll": false,
-        "usesWebGL": false,
-        "lane": null,
-        "priority": null,
-        "reRendersPerFrame": 0,
-        "sharedSingletons": []
-      },
-      "upgrade": "This is the lean contract: enough to understand the hook and use it correctly. The full contract adds named real-world recipes with complete code, the accumulated dos and don'ts, and routing into the motion guardrails. Available to Vector Vesper members — authenticate the CLI with `npx vectorvesper login <token>`."
+        "readingSource": "The `mechanism` field above is the answer to almost every 'how does this actually work' question, and it is written for the version you have. Prefer it. The published package is minified and ships no sourcemaps, so node_modules is a poor place to read from — but @vectorvesper/motion is MIT, so the real source is readable in the repository if you want it. Either way it changes nothing about the output: what you write is still an import. A copy compiles, passes review and silently runs its own rAF loop outside the conductor, so 'I read the source and it looked simple' is exactly how that bug gets shipped."
+      }
     },
     {
-      "contractLevel": "lean",
       "name": "useLazyScene",
       "importFrom": "@vectorvesper/motion/react",
       "packageName": "@vectorvesper/motion",
       "since": "0.1.0",
       "category": "gate",
       "tier": "free",
+      "aliases": [
+        "lazy load",
+        "defer mount",
+        "below the fold",
+        "intersection observer",
+        "heavy scene",
+        "lazy 3d"
+      ],
       "tagline": "Mount a heavy scene when it's near the viewport, the thread is idle, and frames are healthy.",
       "problem": "A WebGL canvas three screens down initialises during page load, competing with the content the user is actually looking at.",
       "summary": "Three gates in sequence: an IntersectionObserver with a generous rootMargin so the scene is ready just before it is seen; an idle-callback so it doesn't land mid-scroll; and a scroll-velocity check that defers while the user is actively moving. Optionally waits for the frame budget to recover, with a 3-second fail-open so a permanently busy page still eventually renders. Once mounted it stays mounted.",
@@ -332,7 +1135,58 @@
           "description": "False until every gate passes, then true for the rest of the mount."
         }
       ],
+      "runtime": {
+        "lane": "update",
+        "priority": "essential",
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": false,
+        "reRendersPerFrame": 0,
+        "usesPointer": false,
+        "usesScroll": true,
+        "usesWebGL": false,
+        "ownsTransform": false,
+        "sharedSingletons": [
+          "FrameConductor",
+          "SensorBus",
+          "AnimationBudget"
+        ],
+        "conflictsWith": [],
+        "pairsWith": [
+          "useSafeToMount",
+          "useAdaptiveQuality",
+          "useAnimationBudget"
+        ]
+      },
       "quickStart": "\"use client\";\nimport { useLazyScene } from \"@vectorvesper/motion/react\";\n\nexport function SceneSection() {\n  const { ref, ready } = useLazyScene<HTMLDivElement>();\n  return (\n    <div ref={ref} className=\"min-h-[60vh]\">\n      {ready ? <HeavyWebGLCanvas /> : <ScenePoster />}\n    </div>\n  );\n}",
+      "recipes": [
+        {
+          "name": "Below-the-fold WebGL",
+          "blurb": "The common case. Give the placeholder the scene's real height so nothing shifts.",
+          "code": "\"use client\";\nimport { useLazyScene } from \"@vectorvesper/motion/react\";\n\nexport function ProductShowcase() {\n  const { ref, ready } = useLazyScene<HTMLDivElement>({\n    rootMargin: \"400px\",\n    deferWhileLow: true,\n  });\n  return (\n    <section ref={ref} className=\"h-[80vh] w-full\">\n      {ready ? <ProductCanvas /> : <img src=\"/product-poster.webp\" alt=\"\" className=\"size-full object-cover\" />}\n    </section>\n  );\n}"
+        },
+        {
+          "name": "Autoplaying video block",
+          "blurb": "Don't start decoding until it's nearly on screen.",
+          "code": "\"use client\";\nimport { useLazyScene } from \"@vectorvesper/motion/react\";\n\nexport function AmbientVideo({ src, poster }: { src: string; poster: string }) {\n  const { ref, ready } = useLazyScene<HTMLDivElement>({ rootMargin: \"300px\" });\n  return (\n    <div ref={ref} className=\"aspect-video\">\n      {ready\n        ? <video src={src} poster={poster} muted playsInline autoPlay loop className=\"size-full object-cover\" />\n        : <img src={poster} alt=\"\" className=\"size-full object-cover\" />}\n    </div>\n  );\n}"
+        },
+        {
+          "name": "Combined with a code-split bundle",
+          "blurb": "Lazy-mount and lazy-load are different problems; use both.",
+          "code": "\"use client\";\nimport dynamic from \"next/dynamic\";\nimport { useLazyScene } from \"@vectorvesper/motion/react\";\n\nconst HeavyCanvas = dynamic(() => import(\"./HeavyCanvas\"), { ssr: false });\n\nexport function Section() {\n  const { ref, ready } = useLazyScene<HTMLDivElement>();\n  return <div ref={ref} className=\"min-h-[70vh]\">{ready && <HeavyCanvas />}</div>;\n}"
+        }
+      ],
+      "dos": [
+        "Give the placeholder the same dimensions as the real scene, so mounting shifts nothing.",
+        "Render a real poster, not a spinner — most users will only ever see the placeholder.",
+        "Pair with `next/dynamic` or `React.lazy` so the bundle is deferred too, not just the mount.",
+        "Raise `rootMargin` for slow-initialising scenes so they're ready by the time they're seen."
+      ],
+      "donts": [
+        "Don't attach the ref to a zero-height element — the observer will never fire.",
+        "Don't expect options to be live. They are snapshotted on first mount by design.",
+        "Don't use `deferWhileLow` for anything above the fold; a 3-second delay is very visible there."
+      ],
       "whenNotToUse": [
         {
           "when": "The content is above the fold.",
@@ -347,42 +1201,35 @@
           "instead": "Use a bare IntersectionObserver or a CSS scroll-driven animation. This hook is about deferring expensive work, not about revealing things."
         }
       ],
+      "guardrails": [
+        "practices/adaptive-performance.md",
+        "practices/react-motion-rules.md",
+        "practices/webgl-budget-and-failopen.md"
+      ],
       "docsUrl": "https://vectorvesper.dev/docs/lazy-scene",
       "labUrl": "https://vectorvesper.dev/lab/lazy-scene",
       "disclosure": {
         "exposeImplementation": false,
         "reason": "Reproducing this hook's implementation makes the consumer run a private requestAnimationFrame loop instead of joining the shared FrameConductor. That silently removes the coordination, scheduling and frame-budget governance the runtime exists to provide, and nothing errors when it happens. Copying is a correctness bug, not just a licensing question.",
         "correctUsage": "Install @vectorvesper/motion and import the hook. Never inline, reimplement, or paste an equivalent.",
-        "readingSource": "If you want to read the real implementation, you can: @vectorvesper/motion is MIT, ships unminified, and its sourcemaps carry the original TypeScript in sourcesContent — so node_modules/@vectorvesper/motion/dist has every line, no reconstruction needed. Read it freely to understand or debug. It changes nothing about the output: what you write is still an import. A copy compiles, passes review and silently runs its own rAF loop outside the conductor, so 'I read the source and it looked simple' is exactly how this bug gets shipped. Start with the `mechanism` field above — it is usually the whole answer, and it is current with the version you have."
-      },
-      "runtime": {
-        "requiresClient": true,
-        "ssrSafeImport": true,
-        "respectsReducedMotion": false,
-        "ownsTransform": false,
-        "conflictsWith": [],
-        "usesPointer": false,
-        "usesScroll": true,
-        "usesWebGL": false,
-        "lane": "update",
-        "priority": "essential",
-        "reRendersPerFrame": 0,
-        "sharedSingletons": [
-          "FrameConductor",
-          "SensorBus",
-          "AnimationBudget"
-        ]
-      },
-      "upgrade": "This is the lean contract: enough to understand the hook and use it correctly. The full contract adds named real-world recipes with complete code, the accumulated dos and don'ts, and routing into the motion guardrails. Available to Vector Vesper members — authenticate the CLI with `npx vectorvesper login <token>`."
+        "readingSource": "The `mechanism` field above is the answer to almost every 'how does this actually work' question, and it is written for the version you have. Prefer it. The published package is minified and ships no sourcemaps, so node_modules is a poor place to read from — but @vectorvesper/motion is MIT, so the real source is readable in the repository if you want it. Either way it changes nothing about the output: what you write is still an import. A copy compiles, passes review and silently runs its own rAF loop outside the conductor, so 'I read the source and it looked simple' is exactly how that bug gets shipped."
+      }
     },
     {
-      "contractLevel": "lean",
       "name": "useMagneticIntent",
       "importFrom": "@vectorvesper/motion/react",
       "packageName": "@vectorvesper/motion",
       "since": "0.1.0",
       "category": "interaction",
       "tier": "free",
+      "aliases": [
+        "magnetic button",
+        "magnet",
+        "sticky button",
+        "cursor attraction",
+        "button pull",
+        "hover magnet"
+      ],
       "tagline": "A magnetic button that starts reaching before the cursor gets there.",
       "problem": "Every magnetic-button tutorial reacts to hover, so the element only starts moving once the cursor has already arrived — which is exactly too late to feel alive.",
       "summary": "Engagement is max(PointerIntent confidence, proximity falloff), so the element begins reaching while the cursor is still on its way — the pre-touch that makes award-site buttons feel intentional. Writes only `transform`, and restores the previous inline transform exactly on unmount. Fails open to a perfectly normal element on touch-only devices and under reduced motion.",
@@ -437,7 +1284,61 @@
           "description": "Whether the effect actually engaged. False on touch-only devices and under reduced motion."
         }
       ],
+      "runtime": {
+        "lane": "render",
+        "priority": "enhanced",
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": true,
+        "reRendersPerFrame": 0,
+        "usesPointer": true,
+        "usesScroll": false,
+        "usesWebGL": false,
+        "ownsTransform": true,
+        "sharedSingletons": [
+          "FrameConductor",
+          "SensorBus",
+          "PointerIntent"
+        ],
+        "conflictsWith": [
+          "Anything else writing the same element's transform — framer-motion `animate`, GSAP tweens, Tailwind `hover:scale-*`, CSS transitions on transform.",
+          "A parent that also transforms during the same interaction, which compounds the offset."
+        ],
+        "pairsWith": [
+          "usePointerIntent",
+          "useSensorBus"
+        ]
+      },
       "quickStart": "\"use client\";\nimport { useMagneticIntent } from \"@vectorvesper/motion/react\";\n\nexport function Cta() {\n  const { ref } = useMagneticIntent<HTMLButtonElement>();\n  return <button ref={ref}>Get started</button>;\n}",
+      "recipes": [
+        {
+          "name": "CTA Button",
+          "blurb": "Wrap the label in an inner span so text can counter-move slightly.",
+          "code": "\"use client\";\nimport { useMagneticIntent } from \"@vectorvesper/motion/react\";\n\nexport function MagneticCta({ children }: { children: React.ReactNode }) {\n  const { ref } = useMagneticIntent<HTMLButtonElement>({ strength: 16, reach: 120 });\n  return (\n    <button ref={ref} className=\"rounded-full px-6 py-3 bg-white text-black\">\n      <span className=\"pointer-events-none\">{children}</span>\n    </button>\n  );\n}"
+        },
+        {
+          "name": "Icon row",
+          "blurb": "Short reach so neighbours don't all lean at once.",
+          "code": "\"use client\";\nimport { useMagneticIntent } from \"@vectorvesper/motion/react\";\n\nfunction MagneticIcon({ children }: { children: React.ReactNode }) {\n  const { ref } = useMagneticIntent<HTMLAnchorElement>({ strength: 8, reach: 48, scale: 1.15 });\n  return <a ref={ref} className=\"grid size-10 place-items-center\">{children}</a>;\n}"
+        },
+        {
+          "name": "Coexisting with framer-motion",
+          "blurb": "Never let both own the same node. Give framer the wrapper and the magnet the child.",
+          "code": "\"use client\";\nimport { motion } from \"framer-motion\";\nimport { useMagneticIntent } from \"@vectorvesper/motion/react\";\n\nexport function EnteringMagneticCta() {\n  const { ref } = useMagneticIntent<HTMLButtonElement>();\n  return (\n    <motion.div initial={{ opacity: 0, y: 12 }} animate={{ opacity: 1, y: 0 }}>\n      <button ref={ref}>Get started</button>\n    </motion.div>\n  );\n}"
+        }
+      ],
+      "dos": [
+        "Give it its own element. It owns that node's inline transform completely.",
+        "Keep `strength` well under the element's own size, or it detaches from its layout slot.",
+        "Use a wrapper element for entrance animations from another library.",
+        "Check `active` if you need to know whether the effect is running on this device."
+      ],
+      "donts": [
+        "Don't apply Tailwind `hover:scale-*`, a CSS transform transition, or a framer `animate` to the same node — last writer per frame wins and it will look broken.",
+        "Don't put it on large elements; the pull reads as drift rather than magnetism.",
+        "Don't use it on anything inside a scrolling list that moves under the cursor.",
+        "Don't rely on it for affordance — the button must look clickable with the effect off."
+      ],
       "whenNotToUse": [
         {
           "when": "You want a simple hover lift or scale.",
@@ -452,45 +1353,35 @@
           "instead": "Use one shared pointer-driven effect over the container. Each instance retains its own PointerIntent, and dozens of independent predictors is the wrong shape."
         }
       ],
+      "guardrails": [
+        "practices/damping-and-inertia.md",
+        "practices/layout-read-discipline.md",
+        "practices/component-api-conventions.md"
+      ],
       "docsUrl": "https://vectorvesper.dev/docs/magnetic-intent",
       "labUrl": "https://vectorvesper.dev/lab/magnetic-element",
       "disclosure": {
         "exposeImplementation": false,
         "reason": "Reproducing this hook's implementation makes the consumer run a private requestAnimationFrame loop instead of joining the shared FrameConductor. That silently removes the coordination, scheduling and frame-budget governance the runtime exists to provide, and nothing errors when it happens. Copying is a correctness bug, not just a licensing question.",
         "correctUsage": "Install @vectorvesper/motion and import the hook. Never inline, reimplement, or paste an equivalent.",
-        "readingSource": "If you want to read the real implementation, you can: @vectorvesper/motion is MIT, ships unminified, and its sourcemaps carry the original TypeScript in sourcesContent — so node_modules/@vectorvesper/motion/dist has every line, no reconstruction needed. Read it freely to understand or debug. It changes nothing about the output: what you write is still an import. A copy compiles, passes review and silently runs its own rAF loop outside the conductor, so 'I read the source and it looked simple' is exactly how this bug gets shipped. Start with the `mechanism` field above — it is usually the whole answer, and it is current with the version you have."
-      },
-      "runtime": {
-        "requiresClient": true,
-        "ssrSafeImport": true,
-        "respectsReducedMotion": true,
-        "ownsTransform": true,
-        "conflictsWith": [
-          "Anything else writing the same element's transform — framer-motion `animate`, GSAP tweens, Tailwind `hover:scale-*`, CSS transitions on transform.",
-          "A parent that also transforms during the same interaction, which compounds the offset."
-        ],
-        "usesPointer": true,
-        "usesScroll": false,
-        "usesWebGL": false,
-        "lane": "render",
-        "priority": "enhanced",
-        "reRendersPerFrame": 0,
-        "sharedSingletons": [
-          "FrameConductor",
-          "SensorBus",
-          "PointerIntent"
-        ]
-      },
-      "upgrade": "This is the lean contract: enough to understand the hook and use it correctly. The full contract adds named real-world recipes with complete code, the accumulated dos and don'ts, and routing into the motion guardrails. Available to Vector Vesper members — authenticate the CLI with `npx vectorvesper login <token>`."
+        "readingSource": "The `mechanism` field above is the answer to almost every 'how does this actually work' question, and it is written for the version you have. Prefer it. The published package is minified and ships no sourcemaps, so node_modules is a poor place to read from — but @vectorvesper/motion is MIT, so the real source is readable in the repository if you want it. Either way it changes nothing about the output: what you write is still an import. A copy compiles, passes review and silently runs its own rAF loop outside the conductor, so 'I read the source and it looked simple' is exactly how that bug gets shipped."
+      }
     },
     {
-      "contractLevel": "lean",
       "name": "useNumberTicker",
       "importFrom": "@vectorvesper/motion/react",
       "packageName": "@vectorvesper/motion",
       "since": "0.1.0",
       "category": "effect",
       "tier": "free",
+      "aliases": [
+        "count up",
+        "counter",
+        "animated number",
+        "number animation",
+        "odometer",
+        "stat ticker"
+      ],
       "tagline": "Animate a number to its target without re-rendering anything.",
       "problem": "The obvious implementation re-renders the component sixty times a second to change one string, dragging every sibling through reconciliation for a counter.",
       "summary": "Writes `textContent` directly on the target node from the shared frame loop, so React renders exactly once regardless of how far the number travels. Damping is frame-rate-independent, so it feels identical at 30 and 120fps, and it snaps and stops when close enough rather than easing forever. Enforces tabular figures so digits don't wobble the layout, and jumps straight to the target under reduced motion.",
@@ -540,7 +1431,57 @@
           "description": "Attach to the element that displays the number. Its text content is owned by the hook."
         }
       ],
+      "runtime": {
+        "lane": "update",
+        "priority": "enhanced",
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": true,
+        "reRendersPerFrame": 0,
+        "usesPointer": false,
+        "usesScroll": false,
+        "usesWebGL": false,
+        "ownsTransform": false,
+        "sharedSingletons": [
+          "FrameConductor"
+        ],
+        "conflictsWith": [
+          "Rendering children into the same element — the hook overwrites its textContent every frame."
+        ],
+        "pairsWith": [
+          "useLazyScene",
+          "useAnimationBudget"
+        ]
+      },
       "quickStart": "\"use client\";\nimport { useNumberTicker } from \"@vectorvesper/motion/react\";\n\nexport function Stat({ value }: { value: number }) {\n  const { ref } = useNumberTicker<HTMLSpanElement>(value);\n  return <span ref={ref} />;\n}",
+      "recipes": [
+        {
+          "name": "Pricing Toggle",
+          "blurb": "Monthly ↔ annual. The number travels instead of cutting, which sells the difference.",
+          "code": "\"use client\";\nimport { useState } from \"react\";\nimport { useNumberTicker } from \"@vectorvesper/motion/react\";\n\nexport function PriceCard({ monthly, annual }: { monthly: number; annual: number }) {\n  const [yearly, setYearly] = useState(false);\n  const { ref } = useNumberTicker<HTMLSpanElement>(yearly ? annual : monthly, {\n    format: { style: \"currency\", currency: \"USD\", maximumFractionDigits: 0 },\n    k: 9,\n  });\n  return (\n    <div>\n      <span ref={ref} className=\"text-5xl font-semibold tabular-nums\" />\n      <button onClick={() => setYearly((v) => !v)}>{yearly ? \"Annual\" : \"Monthly\"}</button>\n    </div>\n  );\n}"
+        },
+        {
+          "name": "Stat Row",
+          "blurb": "Count up when the section scrolls into view, not on page load.",
+          "code": "\"use client\";\nimport { useLazyScene, useNumberTicker } from \"@vectorvesper/motion/react\";\n\nfunction Metric({ target, label, suffix }: { target: number; label: string; suffix?: string }) {\n  const { ref: seen, ready } = useLazyScene<HTMLDivElement>({ rootMargin: \"0px\" });\n  const { ref } = useNumberTicker<HTMLSpanElement>(ready ? target : 0, { suffix });\n  return (\n    <div ref={seen}>\n      <span ref={ref} className=\"text-4xl tabular-nums\" />\n      <p className=\"text-sm text-neutral-400\">{label}</p>\n    </div>\n  );\n}"
+        },
+        {
+          "name": "Live percentage",
+          "blurb": "Fed from real data. One React render per data change, not per frame.",
+          "code": "\"use client\";\nimport { useNumberTicker } from \"@vectorvesper/motion/react\";\n\nexport function Uptime({ ratio }: { ratio: number }) {\n  const { ref } = useNumberTicker<HTMLSpanElement>(ratio, {\n    format: { style: \"percent\", minimumFractionDigits: 2 },\n  });\n  return <span ref={ref} />;\n}"
+        }
+      ],
+      "dos": [
+        "Give it an empty element — the hook owns the text content entirely.",
+        "Use `format` rather than pre-formatting the value yourself, so the animation stays numeric.",
+        "Start from 0 and set the real value when the section becomes visible, for the count-up effect.",
+        "Keep the element's font tabular; the hook enforces it, and fighting that causes width wobble."
+      ],
+      "donts": [
+        "Don't render children inside the element; they are overwritten on the next frame.",
+        "Don't pass a value that changes every frame — the damping already handles the travel.",
+        "Don't use it for anything the user must read exactly while it moves, like a live checkout total."
+      ],
       "whenNotToUse": [
         {
           "when": "The number changes once and the animation is decorative.",
@@ -555,42 +1496,34 @@
           "instead": "Use a `setInterval` and render the formatted string. Those need to be exact at each step, and easing toward a time reads as broken."
         }
       ],
+      "guardrails": [
+        "practices/react-motion-rules.md",
+        "practices/damping-and-inertia.md"
+      ],
       "docsUrl": "https://vectorvesper.dev/docs/number-ticker",
       "labUrl": "https://vectorvesper.dev/lab/number-ticker",
       "disclosure": {
         "exposeImplementation": false,
         "reason": "Reproducing this hook's implementation makes the consumer run a private requestAnimationFrame loop instead of joining the shared FrameConductor. That silently removes the coordination, scheduling and frame-budget governance the runtime exists to provide, and nothing errors when it happens. Copying is a correctness bug, not just a licensing question.",
         "correctUsage": "Install @vectorvesper/motion and import the hook. Never inline, reimplement, or paste an equivalent.",
-        "readingSource": "If you want to read the real implementation, you can: @vectorvesper/motion is MIT, ships unminified, and its sourcemaps carry the original TypeScript in sourcesContent — so node_modules/@vectorvesper/motion/dist has every line, no reconstruction needed. Read it freely to understand or debug. It changes nothing about the output: what you write is still an import. A copy compiles, passes review and silently runs its own rAF loop outside the conductor, so 'I read the source and it looked simple' is exactly how this bug gets shipped. Start with the `mechanism` field above — it is usually the whole answer, and it is current with the version you have."
-      },
-      "runtime": {
-        "requiresClient": true,
-        "ssrSafeImport": true,
-        "respectsReducedMotion": true,
-        "ownsTransform": false,
-        "conflictsWith": [
-          "Rendering children into the same element — the hook overwrites its textContent every frame."
-        ],
-        "usesPointer": false,
-        "usesScroll": false,
-        "usesWebGL": false,
-        "lane": "update",
-        "priority": "enhanced",
-        "reRendersPerFrame": 0,
-        "sharedSingletons": [
-          "FrameConductor"
-        ]
-      },
-      "upgrade": "This is the lean contract: enough to understand the hook and use it correctly. The full contract adds named real-world recipes with complete code, the accumulated dos and don'ts, and routing into the motion guardrails. Available to Vector Vesper members — authenticate the CLI with `npx vectorvesper login <token>`."
+        "readingSource": "The `mechanism` field above is the answer to almost every 'how does this actually work' question, and it is written for the version you have. Prefer it. The published package is minified and ships no sourcemaps, so node_modules is a poor place to read from — but @vectorvesper/motion is MIT, so the real source is readable in the repository if you want it. Either way it changes nothing about the output: what you write is still an import. A copy compiles, passes review and silently runs its own rAF loop outside the conductor, so 'I read the source and it looked simple' is exactly how that bug gets shipped."
+      }
     },
     {
-      "contractLevel": "lean",
       "name": "usePointerIntent",
       "importFrom": "@vectorvesper/motion/react",
       "packageName": "@vectorvesper/motion",
       "since": "0.1.0",
       "category": "interaction",
       "tier": "free",
+      "aliases": [
+        "hover intent",
+        "predict hover",
+        "preload on approach",
+        "cursor prediction",
+        "prefetch hover",
+        "anticipate arrival"
+      ],
       "tagline": "Know the pointer is coming 100–300ms before it arrives, and pre-warm.",
       "problem": "Expensive hover states start their work at the moment of hover, so the first 200ms of every interaction is the user watching something load.",
       "summary": "Casts the pointer's smoothed trajectory forward from the SensorBus and measures time-to-impact against the element's inflated rect. Confidence rises as impact nears; being inside is confidence 1. Enter/exit hysteresis keeps the boolean calm. Use it to start the video, compile the shader or fetch the preview before the cursor lands.",
@@ -664,7 +1597,57 @@
           "description": "Smoothed 0..1, updated per frame with no re-render. Read inside frame callbacks."
         }
       ],
+      "runtime": {
+        "lane": "update",
+        "priority": "enhanced",
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": false,
+        "reRendersPerFrame": 0,
+        "usesPointer": true,
+        "usesScroll": false,
+        "usesWebGL": false,
+        "ownsTransform": false,
+        "sharedSingletons": [
+          "FrameConductor",
+          "SensorBus"
+        ],
+        "conflictsWith": [],
+        "pairsWith": [
+          "useSensorBus",
+          "useMagneticIntent",
+          "useVideoScrubber"
+        ]
+      },
       "quickStart": "\"use client\";\nimport { usePointerIntent } from \"@vectorvesper/motion/react\";\n\nexport function PreviewCard() {\n  const { ref, intent } = usePointerIntent<HTMLDivElement>();\n  return (\n    <article ref={ref}>\n      {intent && <WarmVideoPreview />}   {/* mounts before the cursor arrives */}\n      <CardContent />\n    </article>\n  );\n}",
+      "recipes": [
+        {
+          "name": "CTA Button",
+          "blurb": "Pre-fetch the destination while the cursor is still travelling.",
+          "code": "\"use client\";\nimport { useRouter } from \"next/navigation\";\nimport { usePointerIntent } from \"@vectorvesper/motion/react\";\n\nexport function PrefetchingCta({ href, children }: { href: string; children: React.ReactNode }) {\n  const router = useRouter();\n  const { ref } = usePointerIntent<HTMLAnchorElement>({\n    horizon: 0.4,\n    onChange: (coming) => { if (coming) router.prefetch(href); },\n  });\n  return <a ref={ref} href={href}>{children}</a>;\n}"
+        },
+        {
+          "name": "Card Grid",
+          "blurb": "Warm one preview at a time. Each card predicts independently.",
+          "code": "\"use client\";\nimport { usePointerIntent } from \"@vectorvesper/motion/react\";\n\nexport function VideoCard({ src, poster }: { src: string; poster: string }) {\n  const { ref, intent } = usePointerIntent<HTMLDivElement>({ extend: 24 });\n  return (\n    <div ref={ref} className=\"relative\">\n      <img src={poster} alt=\"\" />\n      {intent && <video src={src} muted playsInline preload=\"auto\" autoPlay loop />}\n    </div>\n  );\n}"
+        },
+        {
+          "name": "Confidence-driven glow",
+          "blurb": "Use the analog value, not the boolean, for anything continuous.",
+          "code": "\"use client\";\nimport { useEffect, useRef } from \"react\";\nimport { usePointerIntent } from \"@vectorvesper/motion/react\";\nimport { getConductor } from \"@vectorvesper/motion\";\n\nexport function GlowCard() {\n  const glowRef = useRef<HTMLDivElement>(null);\n  const { ref, confidenceRef } = usePointerIntent<HTMLDivElement>();\n\n  useEffect(() => getConductor().subscribe(\"render\", () => {\n    if (glowRef.current) glowRef.current.style.opacity = String(confidenceRef.current);\n  }, { priority: \"decorative\", label: \"GlowCard\" }), [confidenceRef]);\n\n  return (\n    <div ref={ref} className=\"relative\">\n      <div ref={glowRef} className=\"absolute inset-0 bg-white/20 blur-2xl opacity-0\" />\n    </div>\n  );\n}"
+        }
+      ],
+      "dos": [
+        "Use `intent` for mounting decisions and `confidenceRef` for anything continuous.",
+        "Keep `exit` below `enter` — that gap is the hysteresis that stops flicker.",
+        "Turn on `dynamic` only for targets that actually move; it costs a layout read per frame while approaching.",
+        "Make the warmed thing idempotent — intent can fire, drop, and fire again."
+      ],
+      "donts": [
+        "Don't do anything irreversible or user-visible on intent. It is a prediction and it will be wrong sometimes.",
+        "Don't use it for anything that costs money or fires analytics.",
+        "Don't stack it on a huge element — a full-width hero is always 'about to be entered'."
+      ],
       "whenNotToUse": [
         {
           "when": "The hover state is cheap — a colour change, an underline, a small transform.",
@@ -679,41 +1662,35 @@
           "instead": "Use `onMouseEnter`. This hook fires on approach by design and will fire for pointers that pass by without landing."
         }
       ],
+      "guardrails": [
+        "practices/damping-and-inertia.md",
+        "practices/layout-read-discipline.md",
+        "practices/frame-loop-rules.md"
+      ],
       "docsUrl": "https://vectorvesper.dev/docs/pointer-intent",
       "labUrl": "https://vectorvesper.dev/lab/pointer-intent",
       "disclosure": {
         "exposeImplementation": false,
         "reason": "Reproducing this hook's implementation makes the consumer run a private requestAnimationFrame loop instead of joining the shared FrameConductor. That silently removes the coordination, scheduling and frame-budget governance the runtime exists to provide, and nothing errors when it happens. Copying is a correctness bug, not just a licensing question.",
         "correctUsage": "Install @vectorvesper/motion and import the hook. Never inline, reimplement, or paste an equivalent.",
-        "readingSource": "If you want to read the real implementation, you can: @vectorvesper/motion is MIT, ships unminified, and its sourcemaps carry the original TypeScript in sourcesContent — so node_modules/@vectorvesper/motion/dist has every line, no reconstruction needed. Read it freely to understand or debug. It changes nothing about the output: what you write is still an import. A copy compiles, passes review and silently runs its own rAF loop outside the conductor, so 'I read the source and it looked simple' is exactly how this bug gets shipped. Start with the `mechanism` field above — it is usually the whole answer, and it is current with the version you have."
-      },
-      "runtime": {
-        "requiresClient": true,
-        "ssrSafeImport": true,
-        "respectsReducedMotion": false,
-        "ownsTransform": false,
-        "conflictsWith": [],
-        "usesPointer": true,
-        "usesScroll": false,
-        "usesWebGL": false,
-        "lane": "update",
-        "priority": "enhanced",
-        "reRendersPerFrame": 0,
-        "sharedSingletons": [
-          "FrameConductor",
-          "SensorBus"
-        ]
-      },
-      "upgrade": "This is the lean contract: enough to understand the hook and use it correctly. The full contract adds named real-world recipes with complete code, the accumulated dos and don'ts, and routing into the motion guardrails. Available to Vector Vesper members — authenticate the CLI with `npx vectorvesper login <token>`."
+        "readingSource": "The `mechanism` field above is the answer to almost every 'how does this actually work' question, and it is written for the version you have. Prefer it. The published package is minified and ships no sourcemaps, so node_modules is a poor place to read from — but @vectorvesper/motion is MIT, so the real source is readable in the repository if you want it. Either way it changes nothing about the output: what you write is still an import. A copy compiles, passes review and silently runs its own rAF loop outside the conductor, so 'I read the source and it looked simple' is exactly how that bug gets shipped."
+      }
     },
     {
-      "contractLevel": "lean",
       "name": "useSafeToMount",
       "importFrom": "@vectorvesper/motion/react",
       "packageName": "@vectorvesper/motion",
       "since": "0.1.0",
       "category": "gate",
       "tier": "free",
+      "aliases": [
+        "defer mount",
+        "headroom gate",
+        "mount gate",
+        "hydration safe",
+        "when to mount",
+        "idle mount"
+      ],
       "tagline": "Hold an expensive mount until the main thread can actually absorb it.",
       "problem": "An expensive component mounts during hydration, when the thread is already saturated, and its cost lands on top of the worst moment of the page's life.",
       "summary": "Watches the frame loop and returns `true` only after a run of frames with real headroom to spare. One-way: once true it never goes back to false, because a component that unmounted itself the moment it made the page slow would oscillate forever. A hardware core-count floor short-circuits the whole check on very weak devices.",
@@ -744,12 +1721,56 @@
       ],
       "returns": [
         {
-          "name": "safe",
-          "type": "boolean",
-          "description": "False until the thread is measurably calm, then true forever within this mount."
+          "name": "safe",
+          "type": "boolean",
+          "description": "False until the thread is measurably calm, then true forever within this mount."
+        }
+      ],
+      "runtime": {
+        "lane": "input",
+        "priority": "essential",
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": false,
+        "reRendersPerFrame": 0,
+        "usesPointer": false,
+        "usesScroll": false,
+        "usesWebGL": false,
+        "ownsTransform": false,
+        "sharedSingletons": [
+          "FrameConductor",
+          "AnimationBudget"
+        ],
+        "conflictsWith": [],
+        "pairsWith": [
+          "useLazyScene",
+          "useAnimationBudget",
+          "useAdaptiveQuality"
+        ]
+      },
+      "quickStart": "\"use client\";\nimport { useSafeToMount } from \"@vectorvesper/motion/react\";\n\nexport function Dashboard() {\n  const canMount = useSafeToMount();\n  return canMount ? <AnalyticsChart /> : <ChartSkeleton />;\n}",
+      "recipes": [
+        {
+          "name": "Dashboard Boot",
+          "blurb": "KPI tiles render instantly; the expensive chart waits out the hydration burst so its mount cost never stacks on top.",
+          "code": "\"use client\";\nimport { useSafeToMount } from \"@vectorvesper/motion/react\";\n\nexport function Overview({ kpis }: { kpis: Kpi[] }) {\n  const canMount = useSafeToMount({ minHeadroomMs: 6, requiredCleanFrames: 3 });\n  return (\n    <>\n      <KpiRow items={kpis} />          {/* always immediate */}\n      {canMount ? <RevenueChart /> : <ChartSkeleton />}\n    </>\n  );\n}"
+        },
+        {
+          "name": "Third-party Widget",
+          "blurb": "Be stricter for a bundle whose cost you don't control.",
+          "code": "\"use client\";\nimport { useSafeToMount } from \"@vectorvesper/motion/react\";\n\nexport function MapPanel() {\n  const canMount = useSafeToMount({\n    minHeadroomMs: 9,         // over half a 60Hz frame still free\n    requiredCleanFrames: 10,  // ~166ms of sustained calm\n    minCores: 8,              // desktop-class only\n  });\n  return canMount ? <InteractiveMap /> : <StaticMapImage />;\n}"
         }
       ],
-      "quickStart": "\"use client\";\nimport { useSafeToMount } from \"@vectorvesper/motion/react\";\n\nexport function Dashboard() {\n  const canMount = useSafeToMount();\n  return canMount ? <AnalyticsChart /> : <ChartSkeleton />;\n}",
+      "dos": [
+        "Always render a sized fallback so the swap doesn't shift layout.",
+        "Use it for cost you control the timing of — charts, maps, editors, 3D canvases.",
+        "Let the options stay constant; they are effect dependencies and changing them restarts the gate from closed."
+      ],
+      "donts": [
+        "Don't gate anything the user needs. Checkout, auth and forms render unconditionally, always.",
+        "Don't expect it to close again. It is one-way by design.",
+        "Don't wrap it around something cheap — the gate costs more than the thing it is protecting."
+      ],
       "whenNotToUse": [
         {
           "when": "The component is below the fold or off-screen.",
@@ -764,41 +1785,34 @@
           "instead": "Use `next/dynamic`, `React.lazy`, or a plain import. This measures CPU headroom, not bandwidth, and will happily mount a 2MB download on a healthy frame."
         }
       ],
+      "guardrails": [
+        "practices/adaptive-performance.md",
+        "practices/react-motion-rules.md"
+      ],
       "docsUrl": "https://vectorvesper.dev/docs/safe-to-mount",
       "labUrl": "https://vectorvesper.dev/lab/safe-to-mount",
       "disclosure": {
         "exposeImplementation": false,
         "reason": "Reproducing this hook's implementation makes the consumer run a private requestAnimationFrame loop instead of joining the shared FrameConductor. That silently removes the coordination, scheduling and frame-budget governance the runtime exists to provide, and nothing errors when it happens. Copying is a correctness bug, not just a licensing question.",
         "correctUsage": "Install @vectorvesper/motion and import the hook. Never inline, reimplement, or paste an equivalent.",
-        "readingSource": "If you want to read the real implementation, you can: @vectorvesper/motion is MIT, ships unminified, and its sourcemaps carry the original TypeScript in sourcesContent — so node_modules/@vectorvesper/motion/dist has every line, no reconstruction needed. Read it freely to understand or debug. It changes nothing about the output: what you write is still an import. A copy compiles, passes review and silently runs its own rAF loop outside the conductor, so 'I read the source and it looked simple' is exactly how this bug gets shipped. Start with the `mechanism` field above — it is usually the whole answer, and it is current with the version you have."
-      },
-      "runtime": {
-        "requiresClient": true,
-        "ssrSafeImport": true,
-        "respectsReducedMotion": false,
-        "ownsTransform": false,
-        "conflictsWith": [],
-        "usesPointer": false,
-        "usesScroll": false,
-        "usesWebGL": false,
-        "lane": "input",
-        "priority": "essential",
-        "reRendersPerFrame": 0,
-        "sharedSingletons": [
-          "FrameConductor",
-          "AnimationBudget"
-        ]
-      },
-      "upgrade": "This is the lean contract: enough to understand the hook and use it correctly. The full contract adds named real-world recipes with complete code, the accumulated dos and don'ts, and routing into the motion guardrails. Available to Vector Vesper members — authenticate the CLI with `npx vectorvesper login <token>`."
+        "readingSource": "The `mechanism` field above is the answer to almost every 'how does this actually work' question, and it is written for the version you have. Prefer it. The published package is minified and ships no sourcemaps, so node_modules is a poor place to read from — but @vectorvesper/motion is MIT, so the real source is readable in the repository if you want it. Either way it changes nothing about the output: what you write is still an import. A copy compiles, passes review and silently runs its own rAF loop outside the conductor, so 'I read the source and it looked simple' is exactly how that bug gets shipped."
+      }
     },
     {
-      "contractLevel": "lean",
       "name": "useSensorBus",
       "importFrom": "@vectorvesper/motion/react",
       "packageName": "@vectorvesper/motion",
       "since": "0.1.0",
       "category": "sensor",
       "tier": "free",
+      "aliases": [
+        "mouse position",
+        "pointer velocity",
+        "scroll velocity",
+        "viewport size",
+        "shared listeners",
+        "input state"
+      ],
       "tagline": "One set of pointer, scroll and viewport listeners for the whole page.",
       "problem": "Ten effects that each attach their own pointermove and scroll listeners, and each compute their own velocity, do ten times the work to answer one question.",
       "summary": "Retains a page-wide singleton that attaches passive listeners once and computes smoothed derivatives once per frame, in the conductor's input lane — before any consumer runs. Consumers READ a live snapshot during their own frame work. There are no per-event callbacks; the frame loop is the delivery mechanism. Lifecycle is ref-counted, so listeners detach when the last consumer unmounts.",
@@ -812,7 +1826,58 @@
           "description": "Stable singleton reference. Read `bus.state.pointer` / `.scroll` / `.viewport` inside a frame callback. The reference never changes, so it is safe in a deps array."
         }
       ],
+      "runtime": {
+        "lane": "input",
+        "priority": "essential",
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": false,
+        "reRendersPerFrame": 0,
+        "usesPointer": true,
+        "usesScroll": true,
+        "usesWebGL": false,
+        "ownsTransform": false,
+        "sharedSingletons": [
+          "FrameConductor",
+          "SensorBus"
+        ],
+        "conflictsWith": [],
+        "pairsWith": [
+          "usePointerIntent",
+          "useMagneticIntent",
+          "useVideoScrubber"
+        ]
+      },
       "quickStart": "\"use client\";\nimport { useEffect, useRef } from \"react\";\nimport { useSensorBus } from \"@vectorvesper/motion/react\";\nimport { getConductor } from \"@vectorvesper/motion\";\n\nexport function Follower() {\n  const ref = useRef<HTMLDivElement>(null);\n  const bus = useSensorBus();\n\n  useEffect(() => getConductor().subscribe(\"render\", () => {\n    const { x, y } = bus.state.pointer;\n    if (ref.current) ref.current.style.transform = `translate3d(${x}px, ${y}px, 0)`;\n  }), [bus]);\n\n  return <div ref={ref} className=\"fixed top-0 left-0 size-4 rounded-full bg-white\" />;\n}",
+      "recipes": [
+        {
+          "name": "Card Grid",
+          "blurb": "Many tiles reacting to one pointer. Listener count stays at 1 no matter how many cards mount, and nothing re-renders.",
+          "code": "\"use client\";\nimport { useEffect, useRef } from \"react\";\nimport { useSensorBus } from \"@vectorvesper/motion/react\";\nimport { getConductor } from \"@vectorvesper/motion\";\n\nexport function TiltCard({ children }: { children: React.ReactNode }) {\n  const ref = useRef<HTMLDivElement>(null);\n  const bus = useSensorBus();\n\n  useEffect(() => {\n    // Cache the centre; re-measure only on resize, never per frame.\n    let cx = 0, cy = 0;\n    const measure = () => {\n      const r = ref.current?.getBoundingClientRect();\n      if (r) { cx = r.left + r.width / 2; cy = r.top + r.height / 2; }\n    };\n    measure();\n    window.addEventListener(\"resize\", measure);\n\n    const off = getConductor().subscribe(\"render\", () => {\n      const { x, y } = bus.state.pointer;\n      const rx = ((y - cy) / 400) * -6;\n      const ry = ((x - cx) / 400) * 6;\n      if (ref.current) {\n        ref.current.style.transform = `perspective(800px) rotateX(${rx}deg) rotateY(${ry}deg)`;\n      }\n    }, { priority: \"decorative\", label: \"TiltCard\" });\n\n    return () => { off(); window.removeEventListener(\"resize\", measure); };\n  }, [bus]);\n\n  return <div ref={ref}>{children}</div>;\n}"
+        },
+        {
+          "name": "Scroll Skew",
+          "blurb": "Skew an element by scroll velocity — the damped value is already computed for you.",
+          "code": "\"use client\";\nimport { useEffect, useRef } from \"react\";\nimport { useSensorBus } from \"@vectorvesper/motion/react\";\nimport { getConductor } from \"@vectorvesper/motion\";\n\nexport function SkewOnScroll({ children }: { children: React.ReactNode }) {\n  const ref = useRef<HTMLDivElement>(null);\n  const bus = useSensorBus();\n\n  useEffect(() => getConductor().subscribe(\"render\", () => {\n    const skew = Math.max(-8, Math.min(8, bus.state.scroll.vy / 180));\n    if (ref.current) ref.current.style.transform = `skewY(${skew.toFixed(2)}deg)`;\n  }, { priority: \"decorative\", label: \"SkewOnScroll\" }), [bus]);\n\n  return <div ref={ref}>{children}</div>;\n}"
+        },
+        {
+          "name": "Non-React consumer",
+          "blurb": "The bus is framework-agnostic; the hook is only a lifecycle wrapper.",
+          "code": "import { getSensorBus, getConductor } from \"@vectorvesper/motion\";\n\nconst release = getSensorBus().retain();\nconst off = getConductor().subscribe(\"render\", () => {\n  const { speed } = getSensorBus().state.pointer;\n  document.body.style.setProperty(\"--pointer-speed\", String(Math.round(speed)));\n});\n\n// Later: off(); release();"
+        }
+      ],
+      "dos": [
+        "Read `bus.state` fresh inside every frame callback — the objects are live and mutated in place.",
+        "Cache element rects yourself and re-measure on resize/scroll, not per frame.",
+        "Check `pointer.seen` before using coordinates, so nothing jumps from (0,0) before first move.",
+        "Let the ref-counting work: mount and unmount freely, listeners follow."
+      ],
+      "donts": [
+        "Don't retain or spread `bus.state` — it is a live object, and a copy goes stale immediately.",
+        "Don't mutate anything on `bus.state`.",
+        "Don't push bus values into React state at frame rate; that is the exact bottleneck this removes.",
+        "Don't attach your own pointermove listener alongside it — that reintroduces the duplication."
+      ],
       "whenNotToUse": [
         {
           "when": "You need a single isolated hover or click on one element.",
@@ -827,41 +1892,35 @@
           "instead": "Attach a dedicated `pointermove` listener and use `getCoalescedEvents()`. The bus is rAF-locked by design and reports one sample per frame."
         }
       ],
+      "guardrails": [
+        "practices/frame-loop-rules.md",
+        "practices/layout-read-discipline.md",
+        "practices/react-motion-rules.md"
+      ],
       "docsUrl": "https://vectorvesper.dev/docs/sensor-bus",
       "labUrl": "https://vectorvesper.dev/lab/sensor-bus",
       "disclosure": {
         "exposeImplementation": false,
         "reason": "Reproducing this hook's implementation makes the consumer run a private requestAnimationFrame loop instead of joining the shared FrameConductor. That silently removes the coordination, scheduling and frame-budget governance the runtime exists to provide, and nothing errors when it happens. Copying is a correctness bug, not just a licensing question.",
         "correctUsage": "Install @vectorvesper/motion and import the hook. Never inline, reimplement, or paste an equivalent.",
-        "readingSource": "If you want to read the real implementation, you can: @vectorvesper/motion is MIT, ships unminified, and its sourcemaps carry the original TypeScript in sourcesContent — so node_modules/@vectorvesper/motion/dist has every line, no reconstruction needed. Read it freely to understand or debug. It changes nothing about the output: what you write is still an import. A copy compiles, passes review and silently runs its own rAF loop outside the conductor, so 'I read the source and it looked simple' is exactly how this bug gets shipped. Start with the `mechanism` field above — it is usually the whole answer, and it is current with the version you have."
-      },
-      "runtime": {
-        "requiresClient": true,
-        "ssrSafeImport": true,
-        "respectsReducedMotion": false,
-        "ownsTransform": false,
-        "conflictsWith": [],
-        "usesPointer": true,
-        "usesScroll": true,
-        "usesWebGL": false,
-        "lane": "input",
-        "priority": "essential",
-        "reRendersPerFrame": 0,
-        "sharedSingletons": [
-          "FrameConductor",
-          "SensorBus"
-        ]
-      },
-      "upgrade": "This is the lean contract: enough to understand the hook and use it correctly. The full contract adds named real-world recipes with complete code, the accumulated dos and don'ts, and routing into the motion guardrails. Available to Vector Vesper members — authenticate the CLI with `npx vectorvesper login <token>`."
+        "readingSource": "The `mechanism` field above is the answer to almost every 'how does this actually work' question, and it is written for the version you have. Prefer it. The published package is minified and ships no sourcemaps, so node_modules is a poor place to read from — but @vectorvesper/motion is MIT, so the real source is readable in the repository if you want it. Either way it changes nothing about the output: what you write is still an import. A copy compiles, passes review and silently runs its own rAF loop outside the conductor, so 'I read the source and it looked simple' is exactly how that bug gets shipped."
+      }
     },
     {
-      "contractLevel": "lean",
       "name": "useVideoScrubber",
       "importFrom": "@vectorvesper/motion/react",
       "packageName": "@vectorvesper/motion",
       "since": "0.1.0",
       "category": "media",
       "tier": "free",
+      "aliases": [
+        "scroll video",
+        "video scrub",
+        "scrollytelling",
+        "scrub timeline",
+        "video on scroll",
+        "smooth seek"
+      ],
       "tagline": "Drive a video timeline from scroll or pointer, without the seek stutter.",
       "problem": "Setting `video.currentTime` on every scroll event queues seeks faster than the decoder can serve them, and the result stutters — worst on Safari, worst on the demo you filmed.",
       "summary": "Seek discipline is the whole product: never issue a seek while one is in flight, skip sub-frame deltas, use `fastSeek` for large jumps, and throttle adaptively when the decoder is measurably struggling. Also handles iOS priming (a muted play/pause round trip so Safari actually buffers), records and restores the video's attributes exactly, and stops seeking entirely when the track is off screen.",
@@ -926,7 +1985,60 @@
           "description": "The controller. Use `.set(progress)` for the manual driver."
         }
       ],
+      "runtime": {
+        "lane": "update",
+        "priority": "essential",
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": true,
+        "reRendersPerFrame": 0,
+        "usesPointer": true,
+        "usesScroll": true,
+        "usesWebGL": false,
+        "ownsTransform": false,
+        "sharedSingletons": [
+          "FrameConductor",
+          "SensorBus"
+        ],
+        "conflictsWith": [
+          "Any other code setting `video.currentTime`, or calling play() on the same element.",
+          "Smooth-scroll libraries that lie about scroll position (verify the mapping if you use one)."
+        ],
+        "pairsWith": [
+          "useLazyScene",
+          "useSensorBus"
+        ]
+      },
       "quickStart": "\"use client\";\nimport { useVideoScrubber } from \"@vectorvesper/motion/react\";\n\nexport function ScrollScrub() {\n  const { videoRef, trackRef } = useVideoScrubber<HTMLDivElement>();\n  return (\n    <div ref={trackRef} style={{ height: \"300vh\" }}>\n      <div style={{ position: \"sticky\", top: 0, height: \"100vh\" }}>\n        <video ref={videoRef} src=\"/clip.mp4\" muted playsInline />\n      </div>\n    </div>\n  );\n}",
+      "recipes": [
+        {
+          "name": "Product Scrollytelling",
+          "blurb": "The Apple pattern: a tall track, sticky content, pinned mapping.",
+          "code": "\"use client\";\nimport { useVideoScrubber } from \"@vectorvesper/motion/react\";\n\nexport function ProductReveal() {\n  const { videoRef, trackRef, progressRef } = useVideoScrubber<HTMLDivElement>({\n    driver: \"scroll\",\n    mapping: \"pin\",\n    smooth: 10,\n  });\n\n  return (\n    <section ref={trackRef} className=\"h-[400vh]\">\n      <div className=\"sticky top-0 grid h-screen place-items-center\">\n        <video ref={videoRef} src=\"/product-allframes.mp4\" muted playsInline className=\"size-full object-cover\" />\n        <Captions progressRef={progressRef} />\n      </div>\n    </section>\n  );\n}"
+        },
+        {
+          "name": "Hover-scrub thumbnail",
+          "blurb": "Pointer driver across the card's width — a 360 spin on hover.",
+          "code": "\"use client\";\nimport { useVideoScrubber } from \"@vectorvesper/motion/react\";\n\nexport function SpinCard({ src }: { src: string }) {\n  const { videoRef, trackRef } = useVideoScrubber<HTMLDivElement>({\n    driver: \"pointer\",\n    pointerAxis: \"x\",\n    smooth: 14,\n  });\n  return (\n    <div ref={trackRef} className=\"aspect-square cursor-ew-resize\">\n      <video ref={videoRef} src={src} muted playsInline className=\"size-full object-cover\" />\n    </div>\n  );\n}"
+        },
+        {
+          "name": "Manual driver",
+          "blurb": "Drive it from your own value — a slider, a timeline, a gesture.",
+          "code": "\"use client\";\nimport { useVideoScrubber } from \"@vectorvesper/motion/react\";\n\nexport function SliderScrub() {\n  const { videoRef, trackRef, scrubberRef } = useVideoScrubber<HTMLDivElement>({ driver: \"manual\" });\n  return (\n    <div ref={trackRef}>\n      <video ref={videoRef} src=\"/clip.mp4\" muted playsInline />\n      <input\n        type=\"range\" min={0} max={1} step={0.001}\n        onChange={(e) => scrubberRef.current?.set(Number(e.target.value))}\n      />\n    </div>\n  );\n}"
+        }
+      ],
+      "dos": [
+        "Encode the video with every frame a keyframe: `ffmpeg -i in.mp4 -g 1 -coder 0 -bf 0 -crf 20 -movflags +faststart out.mp4`. This is not optional — it is the single biggest factor in whether scrubbing feels smooth.",
+        "Give the track real height (300vh+) for the pin mapping, and make the inner content sticky.",
+        "Read `progressRef.current` inside a frame callback to drive captions or overlays.",
+        "Host the file somewhere with range-request support."
+      ],
+      "donts": [
+        "Don't set `currentTime` yourself anywhere else on that element.",
+        "Don't ship a 4K scrub video. Every frame is a keyframe, so the file is already several times larger than a normal encode.",
+        "Don't change `driver` or `track` after mount — both are fixed by design.",
+        "Don't render `progressRef.current` directly in JSX; it updates per frame and React will not see it."
+      ],
       "whenNotToUse": [
         {
           "when": "You want a video that simply plays when it scrolls into view.",
@@ -941,35 +2053,492 @@
           "instead": "Use `requestVideoFrameCallback` directly. This hook smooths and skips sub-frame deltas on purpose, which is the opposite of what frame-exact work needs."
         }
       ],
+      "guardrails": [
+        "practices/texture-and-media-gotchas.md",
+        "practices/layout-read-discipline.md",
+        "practices/damping-and-inertia.md"
+      ],
       "docsUrl": "https://vectorvesper.dev/docs/video-scrubber",
       "labUrl": "https://vectorvesper.dev/lab/video-scrubber",
       "disclosure": {
         "exposeImplementation": false,
         "reason": "Reproducing this hook's implementation makes the consumer run a private requestAnimationFrame loop instead of joining the shared FrameConductor. That silently removes the coordination, scheduling and frame-budget governance the runtime exists to provide, and nothing errors when it happens. Copying is a correctness bug, not just a licensing question.",
         "correctUsage": "Install @vectorvesper/motion and import the hook. Never inline, reimplement, or paste an equivalent.",
-        "readingSource": "If you want to read the real implementation, you can: @vectorvesper/motion is MIT, ships unminified, and its sourcemaps carry the original TypeScript in sourcesContent — so node_modules/@vectorvesper/motion/dist has every line, no reconstruction needed. Read it freely to understand or debug. It changes nothing about the output: what you write is still an import. A copy compiles, passes review and silently runs its own rAF loop outside the conductor, so 'I read the source and it looked simple' is exactly how this bug gets shipped. Start with the `mechanism` field above — it is usually the whole answer, and it is current with the version you have."
-      },
-      "runtime": {
-        "requiresClient": true,
-        "ssrSafeImport": true,
-        "respectsReducedMotion": true,
-        "ownsTransform": false,
-        "conflictsWith": [
-          "Any other code setting `video.currentTime`, or calling play() on the same element.",
-          "Smooth-scroll libraries that lie about scroll position (verify the mapping if you use one)."
-        ],
-        "usesPointer": true,
-        "usesScroll": true,
-        "usesWebGL": false,
-        "lane": "update",
-        "priority": "essential",
-        "reRendersPerFrame": 0,
-        "sharedSingletons": [
-          "FrameConductor",
-          "SensorBus"
-        ]
-      },
-      "upgrade": "This is the lean contract: enough to understand the hook and use it correctly. The full contract adds named real-world recipes with complete code, the accumulated dos and don'ts, and routing into the motion guardrails. Available to Vector Vesper members — authenticate the CLI with `npx vectorvesper login <token>`."
+        "readingSource": "The `mechanism` field above is the answer to almost every 'how does this actually work' question, and it is written for the version you have. Prefer it. The published package is minified and ships no sourcemaps, so node_modules is a poor place to read from — but @vectorvesper/motion is MIT, so the real source is readable in the repository if you want it. Either way it changes nothing about the output: what you write is still an import. A copy compiles, passes review and silently runs its own rAF loop outside the conductor, so 'I read the source and it looked simple' is exactly how that bug gets shipped."
+      }
+    }
+  ],
+  "patterns": [
+    {
+      "name": "adaptive-shader-hero",
+      "title": "Adaptive shader hero",
+      "tagline": "One hero, three renditions — device floor picks it, headroom times it.",
+      "problem": "A WebGL hero ships one experience to every device: gorgeous on the build machine, a slideshow on a mid-range phone, and a hydration-time mount that lands its cost on the worst moment of the page's life.",
+      "uses": [
+        "useAdaptiveQuality",
+        "useSafeToMount"
+      ],
+      "wiring": [
+        "useAdaptiveQuality picks the rendition: tier 0 → shader, tier 1 → video loop, tier 2 → static image. reducedMotion wins over everything and gets the still.",
+        "useSafeToMount times the expensive mount: the shader (and only the shader) additionally waits for sustained frame headroom, so it lands after hydration settles.",
+        "Load the WebGL component via dynamic(..., { ssr: false }) — shader code must not run during server rendering.",
+        "Every rendition shares the same layout box, so upgrades swap in place without reflow.",
+        "Inside the mounted scene, keep consuming the tier (poll getAdaptiveQuality().state in frame work) to shed internal detail instead of unmounting."
+      ],
+      "code": "\"use client\";\n\nimport dynamic from \"next/dynamic\";\nimport { useAdaptiveQuality, useSafeToMount } from \"@vectorvesper/motion/react\";\n\n// WebGL never renders on the server.\nconst ShaderScene = dynamic(() => import(\"./ShaderScene\"), { ssr: false });\n\nexport function AdaptiveHero() {\n  const { tier, reducedMotion } = useAdaptiveQuality();\n  const canMountShader = useSafeToMount({ minHeadroomMs: 7, requiredCleanFrames: 4 });\n\n  const stillFrame = (\n    <img src=\"/hero/still.webp\" alt=\"Aurora over the product\" style={{ width: \"100%\", height: \"100%\", objectFit: \"cover\" }} />\n  );\n\n  return (\n    <section style={{ position: \"relative\", height: \"90vh\", overflow: \"hidden\" }}>\n      {reducedMotion ? (\n        stillFrame\n      ) : tier === 0 && canMountShader ? (\n        <ShaderScene />\n      ) : tier <= 1 ? (\n        <video src=\"/hero/loop.mp4\" autoPlay muted loop playsInline style={{ width: \"100%\", height: \"100%\", objectFit: \"cover\" }} />\n      ) : (\n        stillFrame\n      )}\n      <div style={{ position: \"absolute\", inset: 0, display: \"grid\", placeItems: \"center\" }}>\n        <h1>Motion that holds the frame.</h1>\n      </div>\n    </section>\n  );\n}",
+      "pitfalls": [
+        {
+          "mistake": "Importing the shader component statically.",
+          "consequence": "WebGL code executes during SSR and crashes the server render — or bloats the first bundle even when tier 2 never mounts it.",
+          "rule": "ssr-module-scope"
+        },
+        {
+          "mistake": "Skipping useSafeToMount because the device probed as capable.",
+          "consequence": "Capable hardware still hydrates: the shader's compile lands on a saturated main thread and the first interaction stutters. The floor says CAN run; headroom says run NOW."
+        },
+        {
+          "mistake": "Unmounting the shader when the live tier degrades after mount.",
+          "consequence": "Degrade → frames recover → upgrade → jank → forever. Mounting latches; adapt DETAIL inside the scene instead."
+        },
+        {
+          "mistake": "Treating reducedMotion as tier 2.",
+          "consequence": "They are different axes: a top-tier machine can request less motion. The preference gets the still frame even at tier 0.",
+          "rule": "no-reduced-motion"
+        }
+      ],
+      "verify": [
+        "check_motion on the file — expect zero findings.",
+        "Chrome sensors → emulate prefers-reduced-motion: the still must render even on a strong machine.",
+        "CPU throttle 6× and reload: the video or still rendition appears instead of the shader (device floor or budget at work).",
+        "On a clean desktop load, the shader appears a few frames AFTER first paint — that delay is useSafeToMount doing its job, not a bug."
+      ],
+      "aliases": [
+        "shader hero",
+        "webgl hero",
+        "adaptive hero",
+        "hero fallback",
+        "three.js hero",
+        "gpu hero",
+        "progressive enhancement hero"
+      ]
+    },
+    {
+      "name": "custom-frame-effect",
+      "title": "Custom frame effect",
+      "tagline": "The canonical skeleton for building your own effect on the runtime.",
+      "problem": "You need an effect none of the hooks provide. The habit from every tutorial — start a private requestAnimationFrame loop, attach your own listeners — compiles, passes review, and silently runs outside the frame budget, invisible to shedding and devtools.",
+      "uses": [
+        "FrameConductor",
+        "useSensorBus",
+        "damp"
+      ],
+      "wiring": [
+        "Mark the component \"use client\" — frame work needs a browser.",
+        "Retain shared input with useSensorBus() instead of attaching your own listeners.",
+        "Subscribe inside useEffect via getConductor().subscribe(lane, fn, { priority, label }) — reads in the input lane, math in update, style writes in render.",
+        "Smooth values with damp(current, target, k, dt) using the dt the conductor passes — never a fixed per-frame factor.",
+        "Keep per-frame values in refs or locals and write results straight to the DOM — never setState per frame.",
+        "Return the unsubscribe function from the effect so the loop can sleep when the component unmounts.",
+        "If the effect is autonomous motion (moves without user input), gate it behind prefers-reduced-motion."
+      ],
+      "code": "\"use client\";\n\nimport { useEffect, useRef } from \"react\";\nimport { getConductor, damp } from \"@vectorvesper/motion\";\nimport { useSensorBus } from \"@vectorvesper/motion/react\";\n\n/**\n * Example custom effect: a spotlight that trails the pointer.\n * The shape is the pattern — swap the math and the write for your own effect.\n */\nexport function SpotlightPanel({ children }: { children: React.ReactNode }) {\n  const ref = useRef<HTMLDivElement>(null);\n  const bus = useSensorBus();\n\n  useEffect(() => {\n    const el = ref.current;\n    if (!el) return;\n\n    // Interaction-following effects keep working under reduced motion (they are\n    // direct manipulation) — but if your effect is AUTONOMOUS, bail here instead.\n    let x = 0;\n    let y = 0;\n\n    return getConductor().subscribe(\"render\", (dt) => {\n      const { pointer } = bus.state;\n      if (!pointer.seen) return;\n      x = damp(x, pointer.x, 10, dt);\n      y = damp(y, pointer.y, 10, dt);\n      el.style.setProperty(\"--spot\", `${x.toFixed(1)}px ${y.toFixed(1)}px`);\n    }, { priority: \"enhanced\", label: \"SpotlightPanel\" });\n  }, [bus]);\n\n  return (\n    <div\n      ref={ref}\n      style={{\n        backgroundImage:\n          \"radial-gradient(240px circle at var(--spot, 50% 50%), rgba(255,255,255,0.08), transparent)\",\n      }}\n    >\n      {children}\n    </div>\n  );\n}",
+      "pitfalls": [
+        {
+          "mistake": "Starting your own requestAnimationFrame loop for the effect.",
+          "consequence": "It runs outside the shared budget — the scheduler cannot shed it, devtools cannot see it, and its reads interleave with other effects' writes into layout thrash.",
+          "rule": "orphan-raf"
+        },
+        {
+          "mistake": "Subscribing in the effect but not returning the unsubscribe function.",
+          "consequence": "The subscriber outlives the component; the loop never sleeps and the closure leaks.",
+          "rule": "missing-cleanup"
+        },
+        {
+          "mistake": "Mirroring a per-frame value into React state to render it.",
+          "consequence": "A React render per frame — the component tree pays reconciliation 60+ times a second.",
+          "rule": "setstate-per-frame"
+        },
+        {
+          "mistake": "Reading getBoundingClientRect inside the render lane after styles were written.",
+          "consequence": "Forced synchronous layout every frame. Measure in the input lane; write in render."
+        },
+        {
+          "mistake": "Autonomous motion with no prefers-reduced-motion guard.",
+          "consequence": "Users who asked for less motion get all of it.",
+          "rule": "no-reduced-motion"
+        }
+      ],
+      "verify": [
+        "Run check_motion on the file — expect zero findings; orphan-raf and missing-cleanup are the ones this shape prevents.",
+        "Mount the devtools overlay (mountDevtools from @vectorvesper/motion/devtools): your label should appear in the table with a per-frame cost, ideally under ~1ms.",
+        "Unmount the component and confirm the subscriber row disappears — that proves cleanup ran."
+      ],
+      "aliases": [
+        "custom effect",
+        "build your own",
+        "skeleton",
+        "boilerplate",
+        "frame work",
+        "new effect"
+      ]
+    },
+    {
+      "name": "dashboard-live-numbers",
+      "title": "Dashboard of live numbers",
+      "tagline": "Dozens of animated stats that shed themselves when the page gets heavy.",
+      "problem": "One animated counter is free. Forty of them on a dashboard are forty frame-loop subscribers — fine on a desktop, real weight on a low-end laptop with the data grid also repainting. The counters are decoration; they should be the first thing to go.",
+      "uses": [
+        "useNumberTicker",
+        "useAnimationBudget"
+      ],
+      "wiring": [
+        "Each stat renders through useNumberTicker — the eased value writes straight to the DOM, so N tickers cause zero React renders per frame.",
+        "One useAnimationBudget at the dashboard root decides how much decoration the page can afford.",
+        "Tier 0: animate everything. Tier 1+: render plain text for secondary stats and keep the hero stats animated. The static branch is just {value} — the ticker hook simply isn't mounted.",
+        "Sample fast-moving data sources (once a second) before feeding value to a ticker; the easing is the presentation, not a stream renderer."
+      ],
+      "code": "\"use client\";\n\nimport { useAnimationBudget, useNumberTicker } from \"@vectorvesper/motion/react\";\n\nfunction Stat({ label, value, format, animate }: {\n  label: string;\n  value: number;\n  format?: Intl.NumberFormatOptions;\n  animate: boolean;\n}) {\n  return (\n    <div>\n      <dt>{label}</dt>\n      <dd>{animate ? <Ticker value={value} format={format} /> : new Intl.NumberFormat(undefined, format).format(value)}</dd>\n    </div>\n  );\n}\n\nfunction Ticker({ value, format }: { value: number; format?: Intl.NumberFormatOptions }) {\n  const { ref } = useNumberTicker(value, { format });\n  return <span ref={ref} />;\n}\n\nexport function StatsBoard({ stats }: { stats: Array<{ id: string; label: string; value: number; hero?: boolean }> }) {\n  const { tier } = useAnimationBudget();\n\n  return (\n    <dl>\n      {stats.map((s) => (\n        <Stat\n          key={s.id}\n          label={s.label}\n          value={s.value}\n          format={{ maximumFractionDigits: 0 }}\n          // Tier 0: everything animates. Under pressure, only hero stats keep the flourish.\n          animate={tier === 0 || Boolean(s.hero)}\n        />\n      ))}\n    </dl>\n  );\n}",
+      "pitfalls": [
+        {
+          "mistake": "Feeding a websocket stream straight into value many times a second.",
+          "consequence": "The easing never settles and every message restarts it — permanent churn that reads as flicker. Sample the stream; let the ticker present the sample."
+        },
+        {
+          "mistake": "Implementing the counter with setState-per-frame instead of the ticker.",
+          "consequence": "Sixty renders a second per stat, multiplied by forty stats — the dashboard drags itself down.",
+          "rule": "setstate-per-frame"
+        },
+        {
+          "mistake": "Animating stats that are offscreen below the fold.",
+          "consequence": "Subscribers doing invisible work. Virtualize or gate by visibility for very long boards."
+        },
+        {
+          "mistake": "Announcing every tick to screen readers with aria-live.",
+          "consequence": "Sixty announcements a second. Announce the final value once from your data layer if it matters."
+        }
+      ],
+      "verify": [
+        "check_motion on the file — expect zero findings.",
+        "React DevTools highlight-updates: numbers visibly counting with zero components flashing.",
+        "Devtools overlay: one subscriber row per animated ticker; CPU-throttle until tier reads 1 and watch secondary stats drop to plain text while hero stats keep animating."
+      ],
+      "aliases": [
+        "animated counter",
+        "count up",
+        "stats dashboard",
+        "kpi tiles",
+        "number animation",
+        "metrics board"
+      ]
+    },
+    {
+      "name": "lazy-3d-section",
+      "title": "Lazy 3D section below the fold",
+      "tagline": "A heavy scene that boots near the viewport, sized for the device it landed on.",
+      "problem": "A three.js section three screens down initialises during page load, competes with the content the user is reading, and then renders at full quality on hardware that cannot hold it. Two decisions — when to exist, how rich to be — need two different signals.",
+      "uses": [
+        "useLazyScene",
+        "useAdaptiveQuality"
+      ],
+      "wiring": [
+        "useLazyScene (with deferWhileLow) decides WHEN: near the viewport, idle slot, scroll settled, budget not critical.",
+        "Load the scene component via dynamic(..., { ssr: false }) so its code and its DOM both stay deferred.",
+        "Inside the mounted scene, useAdaptiveQuality decides HOW RICH: pixel ratio, particle counts, post-processing — from the fused tier.",
+        "The placeholder keeps the scene's final dimensions and meaningful content (a poster, the same heading) so nothing shifts and nothing is lost without JS-heavy rendering.",
+        "Mount once, keep it mounted — adapt detail inside the scene on later tier changes instead of unmounting."
+      ],
+      "code": "\"use client\";\n\nimport dynamic from \"next/dynamic\";\nimport { useLazyScene } from \"@vectorvesper/motion/react\";\n\nconst ExplodedProduct = dynamic(() => import(\"./ExplodedProduct\"), { ssr: false });\n\nexport function ProductBreakdown() {\n  const { ref, ready } = useLazyScene<HTMLDivElement>({\n    rootMargin: \"400px\",\n    deferWhileLow: true,\n  });\n\n  return (\n    <div ref={ref} style={{ height: \"100vh\", position: \"relative\" }}>\n      {ready ? (\n        <ExplodedProduct />\n      ) : (\n        <img src=\"/scenes/breakdown-poster.webp\" alt=\"Exploded view of the chassis\" style={{ width: \"100%\", height: \"100%\", objectFit: \"cover\" }} />\n      )}\n    </div>\n  );\n}\n\n// ─── ExplodedProduct.tsx (separate file, loaded on demand) ───────────\n//\n// \"use client\";\n// import { useAdaptiveQuality } from \"@vectorvesper/motion/react\";\n//\n// export default function ExplodedProduct() {\n//   const { tier, reducedMotion } = useAdaptiveQuality();\n//   return (\n//     <Canvas dpr={tier === 0 ? [1, 2] : 1}>\n//       <Model spin={!reducedMotion} particles={tier === 0 ? 2000 : tier === 1 ? 500 : 0} />\n//     </Canvas>\n//   );\n// }",
+      "pitfalls": [
+        {
+          "mistake": "Importing the scene statically and only gating its render.",
+          "consequence": "The three.js bundle parses during page load even when the user never scrolls down — and WebGL touched at module scope crashes SSR.",
+          "rule": "ssr-module-scope"
+        },
+        {
+          "mistake": "A zero-height placeholder host.",
+          "consequence": "The IntersectionObserver fires on a 0px box, not where the scene will render — the gate opens at the wrong scroll position and the mount shifts the page."
+        },
+        {
+          "mistake": "Unmounting the scene when it scrolls back out of view.",
+          "consequence": "Context creation is the expensive part; recreating it per pass costs more than keeping the scene alive. ready latches by design."
+        },
+        {
+          "mistake": "Reading useAdaptiveQuality once at mount and baking the values in.",
+          "consequence": "A capable device that later struggles keeps rendering full detail. Consume the tier live (it re-renders rarely) or poll state in frame work."
+        }
+      ],
+      "verify": [
+        "check_motion on both files — expect zero findings.",
+        "Network tab: the scene chunk must not load until you scroll within ~400px.",
+        "Scroll down fast in one flick: the mount waits for the scroll to settle (that pause is the gate, not lag).",
+        "CPU-throttle before scrolling down: with deferWhileLow the mount waits up to 3s for recovery, then fails open."
+      ],
+      "aliases": [
+        "lazy 3d",
+        "three.js section",
+        "webgl below fold",
+        "deferred scene",
+        "r3f lazy",
+        "heavy scene"
+      ]
+    },
+    {
+      "name": "magnetic-prefetch-cta",
+      "title": "Magnetic CTA that prefetches",
+      "tagline": "The button reaches for the cursor while the route it leads to loads.",
+      "problem": "The primary CTA is where feel and speed both matter most — yet the magnetic pull usually starts at hover (too late to feel alive) and the route fetch starts at click (too late to feel instant). Both have the same fix: act on approach.",
+      "uses": [
+        "useMagneticIntent",
+        "usePointerIntent"
+      ],
+      "wiring": [
+        "useMagneticIntent on the button element — it owns that element's transform and starts pulling on predicted approach.",
+        "usePointerIntent on a WRAPPER element (not the button — the magnet owns the button's transform and, with dynamic tracking, its own prediction).",
+        "In onIntentChange, prefetch the route (router.prefetch) — idempotent and cheap, so overlapping zones on nearby CTAs are fine.",
+        "Keep the pull modest (strength 12–18): the button must remain easy to acquire, and focus/keyboard behavior must not depend on the effect."
+      ],
+      "code": "\"use client\";\n\nimport { useRouter } from \"next/navigation\";\nimport { useMagneticIntent, usePointerIntent } from \"@vectorvesper/motion/react\";\n\nexport function MagneticPrefetchCta({ href, children }: { href: string; children: React.ReactNode }) {\n  const router = useRouter();\n\n  // Wrapper predicts the approach and warms the route.\n  const { ref: zoneRef } = usePointerIntent<HTMLDivElement>({\n    extend: 32,\n    onIntentChange: (coming) => { if (coming) router.prefetch(href); },\n  });\n\n  // Button reaches for the cursor. It owns this element's transform.\n  const { ref: magnetRef } = useMagneticIntent<HTMLButtonElement>({\n    strength: 16,\n    reach: 110,\n    scale: 1.04,\n  });\n\n  return (\n    <div ref={zoneRef} style={{ display: \"inline-block\", padding: 12 }}>\n      <button ref={magnetRef} onClick={() => router.push(href)}>\n        {children}\n      </button>\n    </div>\n  );\n}",
+      "pitfalls": [
+        {
+          "mistake": "Putting both refs on the same element.",
+          "consequence": "It works — but the magnet already runs its own intent prediction internally, and the wrapper split gives the prefetch a larger catchment than the pull, which is the feel you want: warm early, move late."
+        },
+        {
+          "mistake": "Also styling the button with a CSS transition on transform for hover.",
+          "consequence": "Two transform owners — the pull turns syrupy or jitters. Use color/shadow for hover styling.",
+          "rule": "transform-conflict"
+        },
+        {
+          "mistake": "Doing non-idempotent work in onIntentChange (posting analytics, mutating state).",
+          "consequence": "Intent can flip several times on a near-miss. Prefetch is safe because it caches; anything else needs its own latch."
+        },
+        {
+          "mistake": "Scaling strength up until the button visibly chases the cursor.",
+          "consequence": "A control that moves away from where the user aimed — harder to click, the opposite of the point."
+        }
+      ],
+      "verify": [
+        "check_motion on the file — expect zero findings.",
+        "Network tab: approach the button without touching it — the route's prefetch request fires while the cursor is still outside the wrapper padding.",
+        "Tab to the button with the keyboard: focus ring appears, Enter navigates, no motion required.",
+        "Toggle reduced motion: the button stays static and everything else still works."
+      ],
+      "aliases": [
+        "magnetic button",
+        "cta button",
+        "prefetch on hover",
+        "instant navigation",
+        "hero button",
+        "sticky cursor button"
+      ]
+    },
+    {
+      "name": "pointer-parallax-scene",
+      "title": "Pointer parallax scene",
+      "tagline": "Layered depth that follows the pointer — many layers, one loop, zero re-renders.",
+      "problem": "A hero with three to six layers drifting at different depths is the classic award-site opener — and the classic way to ship six pointermove listeners, six rAF loops, and a transform fight with whatever else animates the layers.",
+      "uses": [
+        "useSensorBus",
+        "FrameConductor",
+        "damp"
+      ],
+      "wiring": [
+        "One parent component retains the bus and owns ONE conductor subscription for all layers.",
+        "Collect layer elements via a ref map keyed by depth — not one subscription per layer.",
+        "In the render lane, damp a single normalized pointer offset, then write each layer's transform as offset × depth.",
+        "Each layer element belongs to this effect alone — nothing else may animate its transform.",
+        "Depth values stay small (2–20px of travel); parallax reads as depth, not as chase."
+      ],
+      "code": "\"use client\";\n\nimport { useEffect, useRef } from \"react\";\nimport { getConductor, damp } from \"@vectorvesper/motion\";\nimport { useSensorBus } from \"@vectorvesper/motion/react\";\n\nconst LAYERS = [\n  { depth: 4, src: \"/hero/sky.webp\" },\n  { depth: 9, src: \"/hero/ridge.webp\" },\n  { depth: 16, src: \"/hero/subject.webp\" },\n] as const;\n\nexport function ParallaxHero() {\n  const layerRefs = useRef<(HTMLImageElement | null)[]>([]);\n  const bus = useSensorBus();\n\n  useEffect(() => {\n    let nx = 0; // normalized -0.5..0.5\n    let ny = 0;\n\n    return getConductor().subscribe(\"render\", (dt) => {\n      const { pointer, viewport } = bus.state;\n      if (!pointer.seen || viewport.width === 0) return;\n\n      nx = damp(nx, pointer.x / viewport.width - 0.5, 8, dt);\n      ny = damp(ny, pointer.y / viewport.height - 0.5, 8, dt);\n\n      for (let i = 0; i < LAYERS.length; i++) {\n        const el = layerRefs.current[i];\n        if (!el) continue;\n        const d = LAYERS[i].depth;\n        el.style.transform = `translate3d(${(-nx * d).toFixed(2)}px, ${(-ny * d).toFixed(2)}px, 0)`;\n      }\n    }, { priority: \"decorative\", label: \"ParallaxHero\" });\n  }, [bus]);\n\n  return (\n    <section style={{ position: \"relative\", overflow: \"hidden\", height: \"80vh\" }}>\n      {LAYERS.map((layer, i) => (\n        <img\n          key={layer.src}\n          ref={(el) => { layerRefs.current[i] = el; }}\n          src={layer.src}\n          alt=\"\"\n          aria-hidden\n          style={{ position: \"absolute\", inset: \"-24px\", width: \"calc(100% + 48px)\", objectFit: \"cover\" }}\n        />\n      ))}\n    </section>\n  );\n}",
+      "pitfalls": [
+        {
+          "mistake": "One conductor subscription (or worse, one rAF loop) per layer.",
+          "consequence": "N subscriptions doing identical math. One subscription writing N transforms is the shape.",
+          "rule": "orphan-raf"
+        },
+        {
+          "mistake": "Also giving the layer images a CSS transition or animation on transform.",
+          "consequence": "Two owners write the same transform once per frame — visible jitter, no error.",
+          "rule": "transform-conflict"
+        },
+        {
+          "mistake": "Storing the pointer offset in React state so layers re-render into place.",
+          "consequence": "Full-tree reconciliation at frame rate for a purely visual drift.",
+          "rule": "setstate-per-frame"
+        },
+        {
+          "mistake": "Skipping the pointer.seen check.",
+          "consequence": "Every layer jumps when the first real pointer event arrives, because (0,0) was treated as a position."
+        }
+      ],
+      "verify": [
+        "check_motion on the file — expect zero findings.",
+        "Devtools overlay: exactly ONE subscriber row (ParallaxHero) regardless of layer count, cost well under 1ms.",
+        "Under CPU throttling, the layers may pause (decorative sheds) while the rest of the page stays smooth — that is the priority system working."
+      ],
+      "aliases": [
+        "parallax",
+        "mouse parallax",
+        "layered hero",
+        "depth effect",
+        "3d hero",
+        "tilt scene"
+      ]
+    },
+    {
+      "name": "predictive-media-card",
+      "title": "Predictive media card",
+      "tagline": "Decode the full-res image before the pointer arrives; drive the lift without renders.",
+      "problem": "Hover reveals that decode on hover spend their first 200ms as a blur-to-sharp pop — the user watches the asset load. Prediction hides that latency, but only if the warm-up starts before arrival and the per-frame styling never touches React state.",
+      "uses": [
+        "usePointerIntent",
+        "FrameConductor",
+        "damp"
+      ],
+      "wiring": [
+        "usePointerIntent on the card: `intent` (React state, rare) triggers the warm-up; `confidenceRef` (per-frame, no renders) drives the visual.",
+        "On intent: create an Image, set src to the full-res asset, await decode(), cache the result — idempotent, so a veer-away-and-return costs nothing.",
+        "In the render lane, damp a lift value toward confidenceRef.current and write transform + a CSS variable on the card.",
+        "The card element's transform belongs to this subscription alone.",
+        "Show the decoded full-res only once ready — the reveal is then a cache hit, not a decode."
+      ],
+      "code": "\"use client\";\n\nimport { useEffect, useRef, useState } from \"react\";\nimport { getConductor, damp } from \"@vectorvesper/motion\";\nimport { usePointerIntent } from \"@vectorvesper/motion/react\";\n\nexport function PredictiveCard({ thumb, full, title }: { thumb: string; full: string; title: string }) {\n  const { ref, intent, confidenceRef } = usePointerIntent<HTMLDivElement>({ extend: 24, horizon: 0.45 });\n  const [ready, setReady] = useState(false);\n  const warmed = useRef(false);\n\n  // Warm-up: fires ~100–300ms before a normal hover would.\n  useEffect(() => {\n    if (!intent || warmed.current) return;\n    warmed.current = true; // idempotent — veer away and come back for free\n    const img = new Image();\n    img.src = full;\n    img.decode().then(() => setReady(true)).catch(() => {});\n  }, [intent, full]);\n\n  // Per-frame lift from confidence — zero React renders.\n  useEffect(() => {\n    let lift = 0;\n    return getConductor().subscribe(\"render\", (dt) => {\n      const el = ref.current;\n      if (!el) return;\n      lift = damp(lift, confidenceRef.current, 12, dt);\n      el.style.transform = `translate3d(0, ${(-6 * lift).toFixed(2)}px, 0) scale(${(1 + 0.02 * lift).toFixed(4)})`;\n      el.style.setProperty(\"--glow\", lift.toFixed(3));\n    }, { priority: \"enhanced\", label: \"PredictiveCard\" });\n  }, [ref, confidenceRef]);\n\n  return (\n    <div ref={ref} style={{ position: \"relative\", borderRadius: 12, overflow: \"hidden\" }}>\n      <img src={thumb} alt={title} style={{ width: \"100%\", display: \"block\" }} />\n      {ready && (\n        <img\n          src={full}\n          alt=\"\"\n          aria-hidden\n          style={{ position: \"absolute\", inset: 0, width: \"100%\", height: \"100%\", objectFit: \"cover\" }}\n        />\n      )}\n      <span style={{ boxShadow: \"0 0 calc(var(--glow, 0) * 32px) rgba(255,255,255,0.25)\" }} />\n    </div>\n  );\n}",
+      "pitfalls": [
+        {
+          "mistake": "Rendering confidence into JSX ({confidenceRef.current}) or mirroring it into state.",
+          "consequence": "Either it never updates (refs don't re-render) or it re-renders per frame. Confidence is a frame value: consume it inside the conductor.",
+          "rule": "setstate-per-frame"
+        },
+        {
+          "mistake": "Re-running the decode on every intent flip.",
+          "consequence": "Approach, veer away, return = three decodes of the same asset. Latch the warm-up with a ref."
+        },
+        {
+          "mistake": "Animating the card's transform with CSS :hover as well.",
+          "consequence": "Two transform owners fight once per frame — jitter with no error.",
+          "rule": "transform-conflict"
+        },
+        {
+          "mistake": "Using this on a dense grid of small cards with default extend.",
+          "consequence": "Neighbouring prediction zones overlap and several cards warm at once. Cheap prefetches can absorb that; heavy decodes cannot — shrink extend or gate on proximity."
+        }
+      ],
+      "verify": [
+        "check_motion on the file — expect zero findings.",
+        "Network/decode proof: approach the card slowly from a distance — the full-res request must fire before the cursor crosses the card edge.",
+        "Devtools: PredictiveCard row present; cost under ~0.5ms; zero React renders while moving the pointer around the card (React DevTools highlight updates stays quiet)."
+      ],
+      "aliases": [
+        "hover preview",
+        "preload on hover",
+        "image preview card",
+        "predictive hover",
+        "prefetch card",
+        "gallery card"
+      ]
+    },
+    {
+      "name": "scrollytelling-video",
+      "title": "Scrollytelling video section",
+      "tagline": "A sticky film scrubbed by scroll, deferred until it approaches the viewport.",
+      "problem": "The Apple-style scroll film has two failure modes: the video initialises during page load three screens before anyone sees it, and the scrub stutters because seeks queue faster than the decoder serves them. Each hook solves one half; the pattern is the order.",
+      "uses": [
+        "useLazyScene",
+        "useVideoScrubber"
+      ],
+      "wiring": [
+        "Outer component: useLazyScene with a generous rootMargin (400–600px) — the video element does not exist until the section approaches.",
+        "Render a poster in the not-ready state with the SAME track height, so mounting the scrubber never shifts layout.",
+        "Inner component (mounts only when ready): useVideoScrubber with driver \"scroll\" and mapping \"pin\"; trackRef on the tall section, videoRef on the video inside a sticky container.",
+        "Track height 250–400vh — that is the scrub resolution; each second of film needs scroll distance.",
+        "Encode a dedicated scrub asset with a keyframe every frame (ffmpeg -g 1) — the hook throttles slow seeks but cannot make a long-GOP decode cheap."
+      ],
+      "code": "\"use client\";\n\nimport { useLazyScene, useVideoScrubber } from \"@vectorvesper/motion/react\";\n\nconst TRACK_HEIGHT = \"300vh\";\n\nexport function FilmSection() {\n  const { ref, ready } = useLazyScene<HTMLDivElement>({ rootMargin: \"500px\" });\n\n  return (\n    <div ref={ref}>\n      {ready ? (\n        <ScrubbedFilm />\n      ) : (\n        // Same height as the live track: mounting must not shift layout.\n        <section style={{ height: TRACK_HEIGHT }}>\n          <div style={{ position: \"sticky\", top: 0, height: \"100vh\" }}>\n            <img src=\"/film/poster.webp\" alt=\"Product film\" style={{ width: \"100%\", height: \"100%\", objectFit: \"cover\" }} />\n          </div>\n        </section>\n      )}\n    </div>\n  );\n}\n\nfunction ScrubbedFilm() {\n  const { videoRef, trackRef } = useVideoScrubber<HTMLElement>({\n    driver: \"scroll\",\n    mapping: \"pin\",\n    smooth: 8,\n  });\n\n  return (\n    <section ref={trackRef} style={{ height: TRACK_HEIGHT }}>\n      <div style={{ position: \"sticky\", top: 0, height: \"100vh\" }}>\n        {/* Dedicated scrub encode: ffmpeg -i in.mp4 -g 1 -coder 0 -bf 0 -crf 20 -movflags +faststart scrub.mp4 */}\n        <video\n          ref={videoRef}\n          src=\"/film/scrub.mp4\"\n          muted\n          playsInline\n          preload=\"auto\"\n          style={{ width: \"100%\", height: \"100%\", objectFit: \"cover\" }}\n        />\n      </div>\n    </section>\n  );\n}",
+      "pitfalls": [
+        {
+          "mistake": "Mounting the video unconditionally and only lazy-loading the src.",
+          "consequence": "The element, its buffer, and the iOS priming all initialise during page load, competing with the content the user is actually reading."
+        },
+        {
+          "mistake": "Shipping the marketing hero encode as the scrub asset.",
+          "consequence": "Long-GOP video forces the decoder to reconstruct dozens of frames per seek — smooth on the build machine, a slideshow on mid-range hardware. The hook will console-warn with the exact ffmpeg line when it measures slow seeks."
+        },
+        {
+          "mistake": "Setting video.currentTime yourself from a scroll listener alongside the hook.",
+          "consequence": "Two seek issuers — the queueing stutter the scrubber exists to prevent, reintroduced.",
+          "rule": "transform-conflict"
+        },
+        {
+          "mistake": "A poster whose height differs from the live track.",
+          "consequence": "The whole page reflows the moment the scrubber mounts, usually mid-scroll."
+        }
+      ],
+      "verify": [
+        "check_motion on both files — expect zero findings.",
+        "Network tab: scrub.mp4 must not load until you scroll within ~500px of the section.",
+        "Scrub up and down fast: no console slow-seek warning means the encode is right.",
+        "Devtools overlay: VideoScrubber runs at essential priority — under load, ambient effects shed while the scrub stays glued to the finger."
+      ],
+      "aliases": [
+        "scrollytelling",
+        "scroll video",
+        "sticky video",
+        "apple scroll",
+        "video scrub section",
+        "product film"
+      ]
+    },
+    {
+      "name": "velocity-marquee",
+      "title": "Velocity-reactive marquee",
+      "tagline": "A marquee that speeds up and skews with scroll velocity.",
+      "problem": "A constant CSS marquee reads as a GIF. The award-site version reacts to how hard the user is scrolling — speed and skew ride scroll velocity — which needs a damped velocity signal and a frame loop, the two things a naive implementation builds badly twice.",
+      "uses": [
+        "useSensorBus",
+        "FrameConductor",
+        "damp"
+      ],
+      "wiring": [
+        "Render the strip content twice inside an overflow-hidden track so the wrap is seamless.",
+        "Read the damped scroll velocity from the bus — never attach a scroll listener or compute deltas yourself.",
+        "In the render lane, advance a position by baseSpeed + |velocity| × gain each frame, wrap with modulo, and write one transform.",
+        "Skew by a clamped fraction of velocity for the ink-drag feel; both writes go on the same element from this one owner.",
+        "Under prefers-reduced-motion, do not autoplay: render the strip static (this is autonomous motion)."
+      ],
+      "code": "\"use client\";\n\nimport { useEffect, useRef } from \"react\";\nimport { getConductor, damp } from \"@vectorvesper/motion\";\nimport { useSensorBus } from \"@vectorvesper/motion/react\";\n\nexport function VelocityMarquee({ children }: { children: React.ReactNode }) {\n  const stripRef = useRef<HTMLDivElement>(null);\n  const bus = useSensorBus();\n\n  useEffect(() => {\n    const strip = stripRef.current;\n    if (!strip) return;\n    // Autonomous motion: honor the preference by not animating at all.\n    if (window.matchMedia(\"(prefers-reduced-motion: reduce)\").matches) return;\n\n    let x = 0;\n    let skew = 0;\n    let half = 0;\n\n    // Measure the strip in the input lane; write transforms in render.\n    const offMeasure = getConductor().subscribe(\"input\", () => {\n      half = strip.scrollWidth / 2 || 1;\n    }, { hz: 2, label: \"VelocityMarquee(measure)\" });\n\n    const offRender = getConductor().subscribe(\"render\", (dt) => {\n      const vy = bus.state.scroll.vy; // damped px/s, precomputed by the bus\n      const speed = 90 + Math.min(Math.abs(vy) * 0.35, 600); // px/s\n      x = (x + speed * dt) % half;\n      skew = damp(skew, Math.max(-10, Math.min(10, vy / 220)), 10, dt);\n      strip.style.transform = `translate3d(${(-x).toFixed(1)}px, 0, 0) skewX(${skew.toFixed(2)}deg)`;\n    }, { priority: \"decorative\", label: \"VelocityMarquee\" });\n\n    return () => { offMeasure(); offRender(); };\n  }, [bus]);\n\n  return (\n    <div style={{ overflow: \"hidden\", whiteSpace: \"nowrap\" }}>\n      <div ref={stripRef} style={{ display: \"inline-flex\", gap: \"3rem\", willChange: \"transform\" }}>\n        <span>{children}</span>\n        <span aria-hidden>{children}</span>\n      </div>\n    </div>\n  );\n}",
+      "pitfalls": [
+        {
+          "mistake": "Attaching a scroll listener and differencing scrollY yourself.",
+          "consequence": "Raw scroll deltas are spiky and browser-throttled differently; the bus's damped velocity is computed once per frame for everyone — duplicating it is wasted work with worse feel."
+        },
+        {
+          "mistake": "Running the advance in a private requestAnimationFrame loop.",
+          "consequence": "Invisible to the scheduler and devtools; drifts against every other effect's clock.",
+          "rule": "orphan-raf"
+        },
+        {
+          "mistake": "Autoplaying under prefers-reduced-motion.",
+          "consequence": "A permanently moving strip for users who explicitly asked for less motion.",
+          "rule": "no-reduced-motion"
+        },
+        {
+          "mistake": "Measuring scrollWidth in the render callback each frame.",
+          "consequence": "A layout read after style writes — forced synchronous layout at frame rate."
+        }
+      ],
+      "verify": [
+        "check_motion on the file — expect zero findings.",
+        "Devtools: VelocityMarquee at decorative priority; flick-scroll and watch its cost stay put while the strip accelerates.",
+        "Toggle OS reduced-motion and reload: the strip must render static."
+      ],
+      "aliases": [
+        "marquee",
+        "ticker tape",
+        "scrolling text",
+        "infinite scroll strip",
+        "scroll skew",
+        "logo wall"
+      ]
     }
   ]
 }