vectorvesper 2.1.1 → 2.3.0

package/dist/hooks.json

@@ -1,7 +1,7 @@
 {
   "version": "1.0.0",
-  "engineVersion": "1.0.2",
-  "generatedAt": "2026-08-09T14:27:32.779Z",
+  "engineVersion": "4.0.0",
+  "generatedAt": "2026-08-27T13:26:41.858Z",
   "contractLevel": "full",
   "hooks": [
     {
@@ -22,11 +22,12 @@
         "quality signal"
       ],
       "exports": [
-        "getAdaptiveQuality"
+        "getAdaptiveQuality",
+        "fuse"
       ],
       "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.",
+      "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 device floor is probed lazily on first use (WebGL2, renderer class, memory, cores) and never changes while the page is open. Every reading carries a `cause` naming why the tier is what it is. `fuse` is the same rule as a pure function, exported so a devtools panel or a docs page explaining a verdict does not have to keep a copy of it. 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": [],
@@ -89,8 +90,8 @@
       "guardrails": [
         "practices/frame-loop-rules.md"
       ],
-      "docsUrl": "https://vectorvesper.dev/docs/adaptive-quality",
-      "labUrl": "https://vectorvesper.dev/docs/adaptive-quality",
+      "docsUrl": "https://vectorvesper.dev/runtime/adaptive-quality",
+      "labUrl": "https://vectorvesper.dev/runtime/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.",
@@ -189,8 +190,160 @@
       "guardrails": [
         "practices/frame-loop-rules.md"
       ],
-      "docsUrl": "https://vectorvesper.dev/docs/animation-budget",
-      "labUrl": "https://vectorvesper.dev/docs/animation-budget",
+      "docsUrl": "https://vectorvesper.dev/runtime/animation-budget",
+      "labUrl": "https://vectorvesper.dev/runtime/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": "EffectEngines",
+      "importFrom": "@vectorvesper/motion",
+      "packageName": "@vectorvesper/motion",
+      "since": "3.0.0",
+      "category": "core",
+      "tier": "free",
+      "aliases": [
+        "PointerIntent",
+        "MagneticElement",
+        "VideoScrubber",
+        "scrollProgress",
+        "vue",
+        "svelte",
+        "vanilla js",
+        "without react",
+        "no framework",
+        "framework agnostic",
+        "effect classes",
+        "imperative effects"
+      ],
+      "exports": [
+        "PointerIntent",
+        "MagneticElement",
+        "VideoScrubber",
+        "POINTER_INTENT_SENSITIVITY",
+        "VIDEO_SCRUBBER_DEFAULTS",
+        "scrollProgress"
+      ],
+      "tagline": "The effect classes, for Vue, Svelte, vanilla JS, and any code without React.",
+      "problem": "The React hooks are the only documented way to use the effects, so a Vue or Svelte project gets the frame conductor, the sensors, the governors and the maths, and then has to rewrite every effect by hand.",
+      "summary": "Three classes with the same shape: construct with an element and options, call update to change options, call destroy to release everything. They ride the same shared conductor and sensor bus the hooks use, so mixing them with React code on one page costs nothing extra. In React, prefer the hooks, which handle construction and teardown for you.",
+      "mechanism": "The engines were always here; until 3.0 they were internal while their option types were public, so a non-React consumer could name the options and had no way to construct the thing they configured.\n\nAll three follow one lifecycle. The constructor takes the element and options, subscribes to the conductor, and retains the sensor bus where it needs pointer or scroll data. `update` accepts a partial set of options and applies them live, so a reactive framework can push prop changes without rebuilding. `destroy` unsubscribes, releases the bus and restores anything it changed on the element. That last part matters for the video scrubber, which records muted, playsInline and preload before overwriting them and puts them back exactly.\n\nMagneticElement composes PointerIntent rather than duplicating the proximity maths, so engagement is the larger of the intent confidence and raw proximity. That is the same arrangement the hooks use, because the hooks are thin wrappers over these.\n\nThe frozen tables are exported for the same reason the rule behind AdaptiveQuality is: a devtools panel or a documentation page explaining why a preset behaves a certain way needs the real numbers, and the alternative is every such surface keeping a copy that drifts.",
+      "signature": "new PointerIntent(el, options?, onChange?)  ·  new MagneticElement(el, options?)  ·  new VideoScrubber(video, options?)  ·  each has .update(options) and .destroy()",
+      "options": [
+        {
+          "name": "PointerIntent",
+          "type": "new (el: HTMLElement, options?: PointerIntentOptions, onChange?: (intent: boolean) => void)",
+          "default": "(class)",
+          "required": false,
+          "description": "Predicts the pointer is heading for an element before it arrives. Exposes a confidence between 0 and 1. See the usePointerIntent entry for what each option does."
+        },
+        {
+          "name": "MagneticElement",
+          "type": "new (el: HTMLElement, options?: MagneticOptions)",
+          "default": "(class)",
+          "required": false,
+          "description": "Pulls an element toward the pointer, owning its transform. See useMagneticIntent for the options and for what it conflicts with."
+        },
+        {
+          "name": "VideoScrubber",
+          "type": "new (video: HTMLVideoElement, options?: VideoScrubberOptions)",
+          "default": "(class)",
+          "required": false,
+          "description": "Drives a video timeline from scroll or pointer with seek discipline. See useVideoScrubber for the options."
+        },
+        {
+          "name": "POINTER_INTENT_SENSITIVITY",
+          "type": "Readonly<Record<PointerIntentSensitivity, PointerIntentTuning>>",
+          "default": "(frozen table)",
+          "required": false,
+          "description": "What each sensitivity preset resolves to, readable so a panel can explain a preset."
+        },
+        {
+          "name": "VIDEO_SCRUBBER_DEFAULTS",
+          "type": "Readonly<VideoScrubberOptions>",
+          "default": "(frozen table)",
+          "required": false,
+          "description": "The scrubber's default driver, mapping, speed and pointer axis."
+        },
+        {
+          "name": "scrollProgress",
+          "type": "(top: number, height: number, viewportHeight: number, mapping: ScrubMapping) => number",
+          "default": "(function)",
+          "required": false,
+          "description": "The pure scroll-to-progress mapping the scrubber uses, for driving something else from the same curve."
+        }
+      ],
+      "returns": [],
+      "runtime": {
+        "lane": "render",
+        "priority": "enhanced",
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": true,
+        "reRendersPerFrame": 0,
+        "usesPointer": true,
+        "usesScroll": true,
+        "usesWebGL": false,
+        "ownsTransform": true,
+        "sharedSingletons": [
+          "FrameConductor",
+          "SensorBus"
+        ],
+        "conflictsWith": [],
+        "pairsWith": [
+          "FrameConductor",
+          "SensorBus",
+          "damp"
+        ]
+      },
+      "quickStart": "import { MagneticElement } from \"@vectorvesper/motion\";\n\n// Take the element rather than looking it up. Module scope runs during server\n// rendering, where there is no document to query.\nexport function attachMagnet(el) {\n  const magnet = new MagneticElement(el, { strength: 30, reach: 220 });\n  return () => magnet.destroy();\n}",
+      "recipes": [
+        {
+          "name": "Vue",
+          "blurb": "Construct on mount, destroy on unmount. The same shape works for every engine.",
+          "code": "<script setup>\nimport { ref, onMounted, onUnmounted } from \"vue\";\nimport { MagneticElement } from \"@vectorvesper/motion\";\n\nconst el = ref(null);\nlet magnet;\n\nonMounted(() => {\n  magnet = new MagneticElement(el.value, { strength: 30, reach: 220 });\n});\n\nonUnmounted(() => magnet?.destroy());\n</script>\n\n<template>\n  <button ref=\"el\">Get started</button>\n</template>"
+        },
+        {
+          "name": "Svelte",
+          "blurb": "onMount returns its own cleanup, so the whole lifecycle is four lines.",
+          "code": "<script>\n  import { onMount } from \"svelte\";\n  import { PointerIntent } from \"@vectorvesper/motion\";\n\n  let el;\n  let warming = false;\n\n  onMount(() => {\n    const intent = new PointerIntent(el, { sensitivity: \"high\" }, (v) => (warming = v));\n    return () => intent.destroy();\n  });\n</script>\n\n<a bind:this={el} href=\"/product\">Product {warming ? \"(prefetching)\" : \"\"}</a>"
+        },
+        {
+          "name": "Reacting to option changes",
+          "blurb": "update applies live, so a reactive framework never has to rebuild the engine.",
+          "code": "import { MagneticElement } from \"@vectorvesper/motion\";\n\nconst magnet = new MagneticElement(el, { strength: 30 });\n\n// later, when a prop changes\nmagnet.update({ strength: 12 });"
+        }
+      ],
+      "dos": [
+        "Call destroy on teardown. It unsubscribes from the conductor, releases the sensor bus and restores anything it changed on the element.",
+        "Use update rather than rebuilding when an option changes.",
+        "Prefer the React hooks inside React. They are thin wrappers over exactly these classes and handle the lifecycle for you.",
+        "Construct on mount, not at module scope. These touch the DOM, and module scope runs during server rendering."
+      ],
+      "donts": [
+        "Don't animate the transform of an element a MagneticElement owns. Two owners of one transform is a fight, and the frame loop wins.",
+        "Don't construct one per pointer move. They are long-lived objects that subscribe once.",
+        "Don't skip destroy because the element is going away. The conductor subscription outlives the element and keeps the loop running."
+      ],
+      "whenNotToUse": [
+        {
+          "when": "You are writing React.",
+          "instead": "usePointerIntent, useMagneticIntent or useVideoScrubber. Same engines, with construction and teardown handled."
+        },
+        {
+          "when": "You want the scene policy, the governors or the sensors rather than an effect.",
+          "instead": "Those are separate core entries and are not classes: getConductor, getSensorBus, getAnimationBudget, getAdaptiveQuality, getFramePressure and getRendererHealth are all accessors on the same core import."
+        }
+      ],
+      "guardrails": [
+        "practices/react-motion-rules.md",
+        "practices/adaptive-performance.md"
+      ],
+      "docsUrl": "https://vectorvesper.dev/runtime",
       "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.",
@@ -225,7 +378,7 @@
       "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.",
+      "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 as `state`, 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": [
         {
@@ -295,8 +448,8 @@
         },
         {
           "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);"
+          "blurb": "configure() and `state` — 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 — reading .state allocates a snapshot, so never do it per frame.\nconst hud = setInterval(() => {\n  const stats = getConductor().state;\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);\n\n// Keep the handle. An interval left running holds every subscriber it names.\nexport const stopHud = () => clearInterval(hud);"
         }
       ],
       "dos": [
@@ -310,7 +463,7 @@
         "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 read `state` inside a frame callback — it allocates a snapshot; poll it a few times a second instead.",
         "Don't mark your effect essential to dodge shedding; essential is for sensors, governors and direct manipulation."
       ],
       "whenNotToUse": [
@@ -336,8 +489,215 @@
         "practices/layout-read-discipline.md",
         "practices/react-motion-rules.md"
       ],
-      "docsUrl": "https://vectorvesper.dev/docs/frame-conductor",
-      "labUrl": "https://vectorvesper.dev/docs/frame-conductor",
+      "docsUrl": "https://vectorvesper.dev/runtime/frame-conductor",
+      "labUrl": "https://vectorvesper.dev/runtime/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": "FramePressure",
+      "importFrom": "@vectorvesper/motion",
+      "packageName": "@vectorvesper/motion",
+      "since": "2.0.0",
+      "category": "core",
+      "tier": "free",
+      "aliases": [
+        "getFramePressure",
+        "frame pressure core",
+        "what is eating the frame",
+        "blame attribution",
+        "jank source"
+      ],
+      "exports": [
+        "getFramePressure"
+      ],
+      "tagline": "The frame-attribution classifier's core accessor.",
+      "problem": "The React hook is state, and state cannot be read inside a frame callback without either holding a snapshot that is stale immediately or re-rendering every frame. Non-React code has no hook to call at all.",
+      "summary": "getFramePressure() returns the classifier singleton. `.state` is safe to read inside a frame callback and is always current. `.subscribe(fn)` delivers each new verdict at most about twice a second and returns an unsubscribe. In React, prefer useFramePressure.",
+      "mechanism": "The same classifier the hook reads, exposed directly. It splits each frame into this runtime's own subscriber time, other main-thread time sampled with a message-channel probe, and an unattributed remainder, then names the largest with a confidence.\n\nThe distinction that matters for the accessor is cost. Subscribing delivers a callback at roughly two hertz, while reading state costs nothing and allocates nothing, so a frame callback should read rather than subscribe. Subscribing exists for code that wants to act when a verdict changes rather than poll for it.",
+      "signature": "getFramePressure(): FramePressure  ·  .state: PressureState  ·  .subscribe(fn): () => void",
+      "options": [],
+      "returns": [
+        {
+          "name": "state",
+          "type": "PressureState",
+          "description": "The current verdict. Safe to read every frame, and allocates nothing."
+        },
+        {
+          "name": "subscribe",
+          "type": "(fn: (state: PressureState) => void) => () => void",
+          "description": "Calls fn with each new verdict, at most about twice a second. Returns a function that unsubscribes."
+        }
+      ],
+      "runtime": {
+        "lane": "input",
+        "priority": "essential",
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": false,
+        "reRendersPerFrame": 0,
+        "usesPointer": false,
+        "usesScroll": false,
+        "usesWebGL": false,
+        "ownsTransform": false,
+        "sharedSingletons": [
+          "FrameConductor",
+          "FramePressure"
+        ],
+        "conflictsWith": [],
+        "pairsWith": [
+          "FrameConductor",
+          "AdaptiveQuality",
+          "mountDevtools"
+        ]
+      },
+      "quickStart": "import { getConductor, getFramePressure } from \"@vectorvesper/motion\";\n\nconst off = getConductor().subscribe(\"render\", () => {\n  const { source, confidence } = getFramePressure().state;\n  if (source === \"render\" && confidence > 0.4) drawCheaply();\n  else drawNormally();\n}, { priority: \"decorative\", label: \"adaptive draw\" });",
+      "recipes": [
+        {
+          "name": "Acting on a verdict change",
+          "blurb": "Subscribe when you want to react to the change rather than read it every frame.",
+          "code": "import { getFramePressure } from \"@vectorvesper/motion\";\n\nconst off = getFramePressure().subscribe(({ source, confidence }) => {\n  if (source === \"main-thread\" && confidence > 0.6) {\n    console.warn(\"Something outside the runtime is blocking the thread.\");\n  }\n});\n\n// later\noff();"
+        }
+      ],
+      "dos": [
+        "Read `.state` inside frame callbacks. It allocates nothing and is always current.",
+        "Check `confidence` before acting on `source`. A verdict at 0.2 is a coin flip with a name on it.",
+        "Prefer useFramePressure inside React components, and this accessor everywhere else."
+      ],
+      "donts": [
+        "Don't reduce quality on a main-thread or runtime verdict. Neither is fixed by drawing less.",
+        "Don't read `unattributedMs` as GPU time. It is a remainder, and measurement error lands in it.",
+        "Don't subscribe from inside a frame callback. Subscribing is for reacting to change, not polling."
+      ],
+      "whenNotToUse": [
+        {
+          "when": "You are in a React component and not inside a frame callback.",
+          "instead": "useFramePressure, which hands you the same object as React state."
+        },
+        {
+          "when": "You want to know which specific effect is expensive.",
+          "instead": "mountDevtools, which lists every subscriber with its own measured cost. This attributes the frame in three broad buckets and never names an effect."
+        }
+      ],
+      "guardrails": [
+        "practices/adaptive-performance.md"
+      ],
+      "docsUrl": "https://vectorvesper.dev/runtime/frame-pressure",
+      "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": "RendererHealth",
+      "importFrom": "@vectorvesper/motion",
+      "packageName": "@vectorvesper/motion",
+      "since": "2.0.0",
+      "category": "core",
+      "tier": "free",
+      "aliases": [
+        "getRendererHealth",
+        "webglcontextlost",
+        "context lost",
+        "context restored",
+        "canvas recovery",
+        "generation counter",
+        "black canvas"
+      ],
+      "exports": [
+        "getRendererHealth"
+      ],
+      "tagline": "Notices a lost graphics context and counts a generation to remount on.",
+      "problem": "A browser can take a WebGL context away at any moment: a driver reset, a backgrounded tab, too many live contexts on one page. React Three Fiber has no handler for it, so what a visitor gets is a permanently black canvas and a completely clean console.",
+      "summary": "getRendererHealth() returns a page-level singleton holding whether a context is currently lost and a generation number that increments on each loss. Put that generation on a canvas key and React throws the dead tree away and builds a working one.",
+      "mechanism": "A counter and a boolean, deliberately small. No context is created or restored here: something that owns a renderer reports a loss, the generation moves, and whatever renders the canvas is expected to rebuild.\n\nIt exposes a generation rather than a restored event because the restore path is not reliable across drivers. Some refuse a replacement context on the page entirely if the loss event was not cancelled, which is why whoever attaches the listener has to call preventDefault before reporting. Rebuilding from a key sidesteps the question: a fresh context, with every texture re-uploaded from the same declarative tree, which is the kind of rebuild React is already good at.\n\nOn the r3f entry, useRenderQuality attaches that listener and reports for you, so most consumers never touch this and only read the scene gate's generation.",
+      "signature": "getRendererHealth(): RendererHealth  ·  .state: RendererHealthState  ·  .reportLost()  ·  .reportHealthy()  ·  .subscribe(fn)",
+      "options": [],
+      "returns": [
+        {
+          "name": "state.lost",
+          "type": "boolean",
+          "description": "Whether a context is currently known to be lost."
+        },
+        {
+          "name": "state.generation",
+          "type": "number",
+          "description": "Increments on each loss. Put it on the canvas key."
+        },
+        {
+          "name": "reportLost",
+          "type": "() => void",
+          "description": "Call after preventDefault on a webglcontextlost event."
+        },
+        {
+          "name": "reportHealthy",
+          "type": "() => void",
+          "description": "Call once a working context exists, which is what ends the recovery state."
+        },
+        {
+          "name": "subscribe",
+          "type": "(fn: (state: RendererHealthState) => void) => () => void",
+          "description": "Notified on every change. Returns a function that unsubscribes."
+        }
+      ],
+      "runtime": {
+        "lane": null,
+        "priority": null,
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": false,
+        "reRendersPerFrame": 0,
+        "usesPointer": false,
+        "usesScroll": false,
+        "usesWebGL": true,
+        "ownsTransform": false,
+        "sharedSingletons": [
+          "RendererHealth"
+        ],
+        "conflictsWith": [],
+        "pairsWith": [
+          "useSceneGate",
+          "useRenderQuality"
+        ]
+      },
+      "quickStart": "import { getRendererHealth } from \"@vectorvesper/motion\";\n\nexport function watchContext(canvas) {\n  const onLost = (event) => {\n    // Without preventDefault the browser will not attempt a restore, and some\n    // drivers then refuse a new context on the page at all.\n    event.preventDefault();\n    getRendererHealth().reportLost();\n  };\n  canvas.addEventListener(\"webglcontextlost\", onLost);\n  return () => canvas.removeEventListener(\"webglcontextlost\", onLost);\n}",
+      "recipes": [
+        {
+          "name": "Rebuilding when the generation moves",
+          "blurb": "The generation is a key, and the key is the recovery.",
+          "code": "import { getRendererHealth } from \"@vectorvesper/motion\";\n\nlet generation = getRendererHealth().state.generation;\n\nconst off = getRendererHealth().subscribe((health) => {\n  if (health.generation === generation) return;\n  generation = health.generation;\n  teardownRenderer();\n  buildRenderer();                      // fresh context, textures re-uploaded\n  getRendererHealth().reportHealthy();  // ends the recovery\n});"
+        }
+      ],
+      "dos": [
+        "Call preventDefault before reportLost, or a replacement context may be refused outright.",
+        "Use the generation as a key rather than trying to revive the context that died.",
+        "Call reportHealthy once a working context exists, which is what ends the recovery state."
+      ],
+      "donts": [
+        "Don't ignore the loss. The failure mode is a black rectangle with no error anywhere.",
+        "Don't tear down on every change. Only a moving generation means the context actually died.",
+        "Don't attach your own listener to an r3f canvas that already spreads useRenderQuality's props. It attaches one, and two reports move the generation twice."
+      ],
+      "whenNotToUse": [
+        {
+          "when": "You are rendering with React Three Fiber.",
+          "instead": "useRenderQuality, whose onCreated attaches the listener and reports for you."
+        },
+        {
+          "when": "You are not rendering with WebGL.",
+          "instead": "Nothing. A 2D canvas has no context to lose this way."
+        }
+      ],
+      "guardrails": [
+        "practices/adaptive-performance.md"
+      ],
+      "docsUrl": "https://vectorvesper.dev/runtime/scene-gate",
       "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.",
@@ -444,8 +804,8 @@
       "guardrails": [
         "practices/frame-loop-rules.md"
       ],
-      "docsUrl": "https://vectorvesper.dev/docs/sensor-bus",
-      "labUrl": "https://vectorvesper.dev/docs/sensor-bus",
+      "docsUrl": "https://vectorvesper.dev/runtime/sensor-bus",
+      "labUrl": "https://vectorvesper.dev/runtime/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.",
@@ -523,7 +883,7 @@
           "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\" });",
+      "quickStart": "import { getConductor, damp } from \"@vectorvesper/motion\";\n\nexport function follow(el) {\n  let x = 0;\n  let targetX = 0;\n\n  const onMove = (e) => { targetX = e.clientX; };\n  window.addEventListener(\"pointermove\", onMove, { passive: true });\n\n  const off = getConductor().subscribe(\"render\", (dt) => {\n    x = damp(x, targetX, 10, dt);\n    el.style.transform = `translate3d(${x}px, 0, 0)`;\n  }, { label: \"Follower\" });\n\n  // Both handles, or the listener and the frame callback outlive the element.\n  return () => { window.removeEventListener(\"pointermove\", onMove); off(); };\n}",
       "recipes": [
         {
           "name": "Approach prediction with rayRectIntersect",
@@ -553,8 +913,8 @@
       "guardrails": [
         "practices/frame-loop-rules.md"
       ],
-      "docsUrl": "https://vectorvesper.dev/docs/frame-conductor",
-      "labUrl": "https://vectorvesper.dev/docs/frame-conductor",
+      "docsUrl": "https://vectorvesper.dev/runtime/math",
+      "labUrl": "https://vectorvesper.dev/runtime/math",
       "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.",
@@ -580,7 +940,8 @@
         "stats panel"
       ],
       "exports": [
-        "mountDevtools"
+        "mountDevtools",
+        "VERSION"
       ],
       "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.",
@@ -671,8 +1032,8 @@
       "guardrails": [
         "practices/frame-loop-rules.md"
       ],
-      "docsUrl": "https://vectorvesper.dev/docs/devtools",
-      "labUrl": "https://vectorvesper.dev/docs/devtools",
+      "docsUrl": "https://vectorvesper.dev/runtime/devtools",
+      "labUrl": "https://vectorvesper.dev/runtime/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.",
@@ -697,7 +1058,7 @@
       ],
       "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.",
+      "summary": "Probes the device once (WebGL2, GPU renderer string, memory, cores, reduced-motion) and fuses that with the live AnimationBudget, the pressure verdict and the motion preference into one tier plus a `cause` explaining it. The device tier is a FLOOR, and that is the whole point: without it, weak devices oscillate forever, degrading, recovering because they degraded, upgrading, janking, degrading. A software renderer stays a software renderer. `reasons` explains the device half of the verdict.",
       "mechanism": "Another thin subscription; the substance is the AdaptiveQuality singleton, which fuses two signals that are each useless alone. The live budget measures truth, but only once frames have accumulated, so the opening seconds of a page are blind. Device heuristics answer instantly but never learn.\n\nThe fusion rule is a maximum, not an average: the device tier is a floor that the live budget can drop quality below but never lift quality above. Without that floor, weak devices oscillate — degrade, frames recover precisely because you degraded, upgrade, jank, degrade again.\n\nDevice tier comes from a single WebGL2 probe taken once and cached. No WebGL2 at all is tier 2 immediately. A software renderer (SwiftShader, llvmpipe) is tier 2. A mobile-class GPU is tier 1 — those run GL perfectly well, but inside a thermal envelope that a sustained effect will find. Four or fewer cores, or four or fewer gigabytes of reported memory, adds one tier on top. The probe releases its GL context immediately rather than holding one open for the page's lifetime, and every branch appends a plain-English string to reasons, so the verdict is explainable instead of a magic number.\n\nThere is no GPU benchmark database anywhere in this, deliberately. The heuristic is conservative and then corrected by real measurement, which ages better than a lookup table of hardware that did not exist when it was written.",
       "signature": "useAdaptiveQuality(): AdaptiveState",
       "options": [],
@@ -705,7 +1066,7 @@
         {
           "name": "tier",
           "type": "0 | 1 | 2",
-          "description": "Effective tier — max(deviceTier, budgetTier). Consume THIS one."
+          "description": "The effective tier, and the one to consume. Fused from the device floor, the live budget, the pressure verdict and the motion preference."
         },
         {
           "name": "label",
@@ -727,10 +1088,15 @@
           "type": "string[]",
           "description": "Why the device tier is what it is, e.g. [\"mobile-class GPU\"]. For HUDs and support."
         },
+        {
+          "name": "cause",
+          "type": "\"ok\" | \"device\" | \"reduced-motion\" | \"render\" | \"frame-rate\" | \"held\"",
+          "description": "Why the tier is what it is. \"held\" is the interesting one: frames are dropping, but something other than drawing is to blame, so quality was deliberately left alone. Branch on this rather than inferring from the tiers."
+        },
         {
           "name": "reducedMotion",
           "type": "boolean",
-          "description": "Whether the user asked for reduced motion."
+          "description": "Whether the visitor asked for reduced motion. When true the effective tier is forced to 2 and `cause` reads reduced-motion, so the tier alone cannot tell a weak device from a stated preference."
         }
       ],
       "runtime": {
@@ -752,7 +1118,7 @@
         "conflictsWith": [],
         "pairsWith": [
           "useAnimationBudget",
-          "useLazyScene",
+          "useSceneGate",
           "useSafeToMount"
         ]
       },
@@ -798,8 +1164,8 @@
         "practices/adaptive-performance.md",
         "practices/webgl-budget-and-failopen.md"
       ],
-      "docsUrl": "https://vectorvesper.dev/docs/adaptive-quality",
-      "labUrl": "https://vectorvesper.dev/lab/adaptive-quality",
+      "docsUrl": "https://vectorvesper.dev/runtime/adaptive-quality",
+      "labUrl": "https://vectorvesper.dev/runtime/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.",
@@ -884,7 +1250,7 @@
         "pairsWith": [
           "useAdaptiveQuality",
           "useSafeToMount",
-          "useLazyScene"
+          "useSceneGate"
         ]
       },
       "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}",
@@ -935,8 +1301,8 @@
         "practices/adaptive-performance.md",
         "practices/frame-loop-rules.md"
       ],
-      "docsUrl": "https://vectorvesper.dev/docs/animation-budget",
-      "labUrl": "https://vectorvesper.dev/lab/animation-budget",
+      "docsUrl": "https://vectorvesper.dev/runtime/animation-budget",
+      "labUrl": "https://vectorvesper.dev/runtime/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.",
@@ -945,67 +1311,209 @@
       }
     },
     {
-      "name": "useImageTrail",
+      "name": "useFramePressure",
       "importFrom": "@vectorvesper/motion/react",
       "packageName": "@vectorvesper/motion",
-      "since": "0.1.0",
-      "category": "effect",
+      "since": "2.0.0",
+      "category": "governor",
       "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.",
-      "mechanism": "Object pooling plus the Web Animations API, and deliberately no frame loop at all. A fixed set of img elements — 10 by default — is created once on mount, positioned absolutely inside the container, and recycled round-robin. Nothing is allocated per pointer move, which is what separates this from the tutorial version that creates and destroys a node on every spawn and hands the garbage collector a steady stream of work during the exact interaction that needs to stay smooth.\n\nSpawning is distance-gated rather than time-gated: a new image appears only once the pointer has travelled the spacing threshold since the last one, compared as squared distance so the square root is never taken. Time-gating would clump images when the cursor moves slowly and stretch them apart when it moves fast; distance-gating makes the trail read identically at any speed.\n\nEach flight is a single three-keyframe Web Animations call — fade in while rising and scaling up, then fade out while drifting down — with a small randomised drift and tilt so repeated spawns do not look stamped from a template. Handing the animation to the browser's compositor means there is no per-frame JavaScript for the images whatsoever. When the pool wraps around, any animation still running on the reused node is cancelled first, so the oldest flight is stolen rather than layered.\n\nThis hook is intentionally self-contained: a local pointermove listener on the container, no SensorBus, no conductor subscription. It fails open on touch devices and under reduced motion, and it restores the container's original position and overflow on unmount.",
-      "signature": "useImageTrail<T>(options: UseImageTrailOptions): { ref }",
-      "options": [
+        "frame pressure",
+        "what is slow",
+        "why is it janky",
+        "blame the frame",
+        "main thread blocked",
+        "gpu bound",
+        "render bound",
+        "diagnose jank"
+      ],
+      "tagline": "Names which of three unrelated things is eating the frame, and how sure it is.",
+      "problem": "Knowing a page is slow is easy and nearly useless. Reducing quality only helps when drawing is the bottleneck; when a third-party script is blocking the main thread, halving the particle count makes the page uglier and exactly as slow.",
+      "summary": "Splits the frame into this runtime's own subscribers, other main-thread work, and everything left over, then names the largest with a confidence between 0 and 1. Verdicts emit at most twice a second, so this is safe to hold in React state.",
+      "mechanism": "Three numbers per frame, two measured and one inferred.\n\nTotal frame time comes from the interval between presented frames. This runtime's own share comes free, because the scheduler already reads the clock between subscribers to decide what to shed. Other main-thread work is sampled with a message-channel probe at roughly ten times a second: a message posted from the end of the last lane comes back only after the rest of the frame's main-thread work has finished, so the delay is other people's time. What remains after subtracting both is the unattributed remainder.\n\nThat remainder is deliberately not called GPU time. It is evidence consistent with rendering being the cost, and it is also where measurement error goes. Naming it after a thing it cannot see would turn a reasonable inference into a false reading, so it is reported as a remainder and the verdict carries a confidence instead.\n\nConfidence is how clearly the winner beat the others, so a near-tie produces a low number and callers can refuse to act on it. A long-task observer contributes a weak hint where the browser supports it.\n\nThe slow threshold here is deliberately higher than the AnimationBudget's. The budget starts degrading quality at around 54fps, where a page is merely dipping; this classifier stays quiet until roughly 48fps, because attributing blame on a frame that is barely over budget produces confident nonsense. The practical consequence is a window where the tier has already dropped and the source still reads none, which is two signals doing different jobs rather than a contradiction.",
+      "signature": "useFramePressure(): PressureState",
+      "options": [],
+      "returns": [
         {
-          "name": "images",
-          "type": "string[]",
-          "default": "—",
-          "required": true,
-          "description": "Image sources, cycled in order. Preload or serve them small; a cold fetch mid-trail shows as a gap."
+          "name": "source",
+          "type": "\"none\" | \"runtime\" | \"main-thread\" | \"render\" | \"unknown\"",
+          "description": "The largest contributor. `none` means frames are healthy and nothing is being eaten. `unknown` means the frame is over budget and no single cause clearly won."
         },
         {
-          "name": "size",
+          "name": "confidence",
           "type": "number",
-          "default": "160",
-          "required": false,
-          "description": "Rendered width of each trail image in px. Height is automatic."
+          "description": "0 to 1. How clearly the winner beat the others. Set a floor before acting on a verdict; the scene gate uses 0.4."
         },
         {
-          "name": "spacing",
+          "name": "frameMs",
           "type": "number",
-          "default": "90",
-          "required": false,
-          "description": "Pointer distance between spawns in px. Lower is denser and more expensive."
+          "description": "Smoothed wall-clock time between presented frames."
         },
         {
-          "name": "life",
+          "name": "budgetMs",
           "type": "number",
-          "default": "900",
-          "required": false,
-          "description": "Flight duration in ms."
+          "description": "One frame at the display refresh rate this runtime measured, so 8.3 on a 120Hz screen."
         },
         {
-          "name": "maxActive",
+          "name": "runtimeMs",
           "type": "number",
-          "default": "10",
-          "required": false,
-          "description": "Pool size, i.e. maximum simultaneously visible images. This is a hard ceiling on cost."
-        }
-      ],
-      "returns": [
+          "description": "Smoothed time this runtime's own subscribers spent."
+        },
         {
-          "name": "ref",
-          "type": "RefObject<T | null>",
-          "description": "Attach to the container. The hook sets its position and overflow, and restores both on unmount."
+          "name": "mainOtherMs",
+          "type": "number | null",
+          "description": "Sampled non-runtime main-thread time. Null until the probe has enough samples."
+        },
+        {
+          "name": "unattributedMs",
+          "type": "number",
+          "description": "The remainder after the other two. Evidence about rendering, and not a GPU reading."
+        },
+        {
+          "name": "longTasks",
+          "type": "number",
+          "description": "Long tasks seen in the window, where the browser supports the observer."
+        }
+      ],
+      "runtime": {
+        "lane": "input",
+        "priority": "essential",
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": false,
+        "reRendersPerFrame": 0,
+        "usesPointer": false,
+        "usesScroll": false,
+        "usesWebGL": false,
+        "ownsTransform": false,
+        "sharedSingletons": [
+          "FrameConductor",
+          "FramePressure"
+        ],
+        "conflictsWith": [],
+        "pairsWith": [
+          "useSceneGate",
+          "useAdaptiveQuality",
+          "mountDevtools"
+        ]
+      },
+      "quickStart": "\"use client\";\nimport { useFramePressure } from \"@vectorvesper/motion/react\";\n\nexport function Diagnostics() {\n  const p = useFramePressure();\n  return <span>{p.source} at {Math.round(p.confidence * 100)}% confidence</span>;\n}",
+      "recipes": [
+        {
+          "name": "Degrade for the right reason",
+          "blurb": "The whole point. Act on render pressure and ignore the rest.",
+          "code": "\"use client\";\nimport { useFramePressure } from \"@vectorvesper/motion/react\";\n\nexport function Scene() {\n  const { source, confidence } = useFramePressure();\n\n  // A smaller scene does not unblock a blocked main thread, so\n  // \"main-thread\" must never reach this branch.\n  const reduce = source === \"render\" && confidence >= 0.4;\n\n  return <Particles count={reduce ? 12_000 : 40_000} />;\n}"
+        },
+        {
+          "name": "A support-thread readout",
+          "blurb": "Put the decomposition on screen so a bug report arrives with numbers in it.",
+          "code": "\"use client\";\nimport { useFramePressure } from \"@vectorvesper/motion/react\";\n\nexport function PressureReadout() {\n  const p = useFramePressure();\n  return (\n    <pre>\n      {p.source} @ {Math.round(p.confidence * 100)}%\n      frame {p.frameMs.toFixed(1)}ms / budget {p.budgetMs.toFixed(1)}ms\n      runtime {p.runtimeMs.toFixed(1)}  other {p.mainOtherMs?.toFixed(1) ?? \"sampling\"}\n    </pre>\n  );\n}"
+        },
+        {
+          "name": "Reading it inside a frame callback",
+          "blurb": "The hook is React state. Inside a frame, read the singleton instead.",
+          "code": "\"use client\";\nimport { useEffect } from \"react\";\nimport { getConductor, getFramePressure } from \"@vectorvesper/motion\";\n\nuseEffect(() => {\n  return getConductor().subscribe(\"render\", () => {\n    const { source } = getFramePressure().state;\n    if (source === \"render\") drawCheaply();\n    else drawNormally();\n  }, { priority: \"decorative\", label: \"adaptive draw\" });\n}, []);"
+        }
+      ],
+      "dos": [
+        "Check `confidence` before acting. A verdict at 0.2 is a coin flip with a name on it.",
+        "Prefer `useSceneGate` for a scene. It already consumes this verdict through AdaptiveQuality and applies a sensible floor.",
+        "Read `getFramePressure().state` inside frame callbacks. The hook is React state and re-renders.",
+        "Expect `source` to read none while a tier has already dropped. The two signals answer different questions."
+      ],
+      "donts": [
+        "Don't reduce quality on `main-thread` or `runtime`. Neither is fixed by drawing less, and the page ends up uglier at the same frame rate.",
+        "Don't read `unattributedMs` as GPU time. It is a remainder, and measurement error lands in it.",
+        "Don't call this in many components. Verdicts are cheap but re-renders are not; read it near the top and pass the answer down."
+      ],
+      "whenNotToUse": [
+        {
+          "when": "You are deciding how much of a scene to build.",
+          "instead": "`useAdaptiveQuality`, which fuses this verdict with the device floor and the live budget and gives you a tier plus a cause."
+        },
+        {
+          "when": "You want to see which specific effect is expensive.",
+          "instead": "`mountDevtools`, which lists every subscriber with its own measured cost. This hook attributes the frame in three broad buckets and never names an effect."
+        },
+        {
+          "when": "The page is slow and nothing is animating.",
+          "instead": "The browser's own profiler. This measures a running frame loop, so it has nothing to say about a slow network, a slow server render, or a long task before the loop starts."
+        }
+      ],
+      "guardrails": [
+        "practices/adaptive-performance.md"
+      ],
+      "docsUrl": "https://vectorvesper.dev/runtime/frame-pressure",
+      "labUrl": "https://vectorvesper.dev/runtime/frame-pressure",
+      "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": "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.",
+      "mechanism": "Object pooling plus the Web Animations API, and deliberately no frame loop at all. A fixed set of img elements — 10 by default — is created once on mount, positioned absolutely inside the container, and recycled round-robin. Nothing is allocated per pointer move, which is what separates this from the tutorial version that creates and destroys a node on every spawn and hands the garbage collector a steady stream of work during the exact interaction that needs to stay smooth.\n\nSpawning is distance-gated rather than time-gated: a new image appears only once the pointer has travelled the spacing threshold since the last one, compared as squared distance so the square root is never taken. Time-gating would clump images when the cursor moves slowly and stretch them apart when it moves fast; distance-gating makes the trail read identically at any speed.\n\nEach flight is a single three-keyframe Web Animations call — fade in while rising and scaling up, then fade out while drifting down — with a small randomised drift and tilt so repeated spawns do not look stamped from a template. Handing the animation to the browser's compositor means there is no per-frame JavaScript for the images whatsoever. When the pool wraps around, any animation still running on the reused node is cancelled first, so the oldest flight is stolen rather than layered.\n\nThis hook is intentionally self-contained: a local pointermove listener on the container, no SensorBus, no conductor subscription. It fails open on touch devices and under reduced motion, and it restores the container's original position and overflow on unmount.",
+      "signature": "useImageTrail<T>(options: UseImageTrailOptions): { ref }",
+      "options": [
+        {
+          "name": "images",
+          "type": "string[]",
+          "default": "—",
+          "required": true,
+          "description": "Image sources, cycled in order. Preload or serve them small; a cold fetch mid-trail shows as a gap."
+        },
+        {
+          "name": "size",
+          "type": "number",
+          "default": "160",
+          "required": false,
+          "description": "Rendered width of each trail image in px. Height is automatic."
+        },
+        {
+          "name": "spacing",
+          "type": "number",
+          "default": "90",
+          "required": false,
+          "description": "Pointer distance between spawns in px. Lower is denser and more expensive."
+        },
+        {
+          "name": "life",
+          "type": "number",
+          "default": "900",
+          "required": false,
+          "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."
+        }
+      ],
+      "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": {
@@ -1071,8 +1579,8 @@
         "practices/texture-and-media-gotchas.md",
         "practices/adaptive-performance.md"
       ],
-      "docsUrl": "https://vectorvesper.dev/docs/image-trail",
-      "labUrl": "https://vectorvesper.dev/lab/image-trail",
+      "docsUrl": "https://vectorvesper.dev/runtime/image-trail",
+      "labUrl": "https://vectorvesper.dev/runtime/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.",
@@ -1081,133 +1589,90 @@
       }
     },
     {
-      "name": "useLazyScene",
+      "name": "useInteractionScope",
       "importFrom": "@vectorvesper/motion/react",
       "packageName": "@vectorvesper/motion",
-      "since": "0.1.0",
-      "category": "gate",
+      "since": "2.0.0",
+      "category": "interaction",
       "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.",
-      "mechanism": "Four gates in series, then a latch. An IntersectionObserver with a rootMargin — 200px by default — starts the sequence before the element is actually visible, so the work overlaps the remaining scroll distance instead of beginning when the user has already arrived. Leaving the margin cancels everything cleanly and re-arms.\n\nNext it waits for requestIdleCallback with a 1500ms timeout, so the mount lands in a slot the browser has already declared spare rather than competing with whatever else is running.\n\nThen it reads scroll velocity from the SensorBus, which it retains for exactly this purpose. Above roughly 40 pixels per second the mount is deferred and retried from the update lane every frame until scrolling genuinely settles — mounting a WebGL canvas mid-flick is how a smooth scroll becomes a stutter.\n\nThe optional budget gate then holds off while the animation budget sits at tier 2 and waits for recovery, but with a three-second fail-open timeout, because a permanently slow device would otherwise never see the content at all. Blank is worse than degraded.\n\nOnce it fires, the observer disconnects and ready stays true permanently. Nothing unmounts on scroll-away: the remount cost would exceed whatever the unmount saved, and the flicker would be visible.",
-      "signature": "useLazyScene<T>(options?: UseLazySceneOptions): { ref, ready }",
-      "options": [
-        {
-          "name": "rootMargin",
-          "type": "string",
-          "default": "\"200px\"",
-          "required": false,
-          "description": "IntersectionObserver margin. Larger mounts earlier and wastes more when the user never scrolls there."
-        },
-        {
-          "name": "requireIdle",
-          "type": "boolean",
-          "default": "true",
-          "required": false,
-          "description": "Wait for requestIdleCallback (1500ms timeout) so mounting doesn't land in a busy frame."
-        },
-        {
-          "name": "deferWhileLow",
-          "type": "boolean",
-          "default": "false",
-          "required": false,
-          "description": "Also wait for the AnimationBudget to leave tier 2, capped at 3 seconds so it always fails open."
-        }
-      ],
+        "interaction scope",
+        "foreground region",
+        "protect a drag",
+        "yield background work",
+        "scope id",
+        "priority region"
+      ],
+      "tagline": "Read the id of the surrounding InteractionScope, for work that subscribes by hand.",
+      "problem": "`useTick` picks up the surrounding region automatically, but code that calls the conductor directly has to pass a scope, and there is no way to guess the generated id from outside.",
+      "summary": "Returns the generated id of the nearest InteractionScope, or null outside one. Most components never need it: `useTick` already reads the same context. Reach for it when you subscribe to the conductor by hand from inside a region and want that work protected too.",
+      "mechanism": "A context read, and nothing else. The provider generates its id with React's own id hook, so ids are unique per instance without the caller inventing names. An earlier version required a page-unique name from the caller, which pushed the uniqueness problem outward and meant two regions that happened to share a hand-written name silently shared one claim on the foreground.\n\nThe value is opaque and is not the label. The label exists so a devtools row can say something better than a generated id, and it has no effect on behaviour and no requirement to be unique.\n\nWhat the id is for: the conductor keeps a stack of scopes that have claimed the foreground, and while any claim is held, a subscriber whose scope does not match is tested against a stricter shedding threshold than its priority would normally give it. Essential work is exempt at any threshold. Passing this id when subscribing is what puts your work on the protected side of that comparison.",
+      "signature": "useInteractionScope(): string | null",
+      "options": [],
       "returns": [
         {
-          "name": "ref",
-          "type": "RefObject<T | null>",
-          "description": "Attach to the placeholder element. It must occupy real space or the observer never fires."
-        },
-        {
-          "name": "ready",
-          "type": "boolean",
-          "description": "False until every gate passes, then true for the rest of the mount."
+          "name": "scope",
+          "type": "string | null",
+          "description": "The generated id of the nearest InteractionScope, or null outside one. Opaque, and not the label. Pass it as the `scope` option when subscribing to the conductor directly."
         }
       ],
       "runtime": {
-        "lane": "update",
-        "priority": "essential",
+        "lane": null,
+        "priority": null,
         "requiresClient": true,
         "ssrSafeImport": true,
         "respectsReducedMotion": false,
         "reRendersPerFrame": 0,
         "usesPointer": false,
-        "usesScroll": true,
+        "usesScroll": false,
         "usesWebGL": false,
         "ownsTransform": false,
-        "sharedSingletons": [
-          "FrameConductor",
-          "SensorBus",
-          "AnimationBudget"
-        ],
+        "sharedSingletons": [],
         "conflictsWith": [],
         "pairsWith": [
-          "useSafeToMount",
-          "useAdaptiveQuality",
-          "useAnimationBudget"
+          "InteractionScope",
+          "useTick",
+          "FrameConductor"
         ]
       },
-      "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}",
+      "quickStart": "\"use client\";\nimport { useEffect } from \"react\";\nimport { useInteractionScope, getConductor } from \"@vectorvesper/motion/react\";\n\nexport function HandRolledEffect() {\n  const scope = useInteractionScope();\n\n  useEffect(() => {\n    return getConductor().subscribe(\"render\", draw, {\n      scope: scope ?? undefined,\n      label: \"hand-rolled\",\n    });\n  }, [scope]);\n\n  return null;\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": "Protecting a canvas you drive yourself",
+          "blurb": "A canvas inside a draggable region, drawn from a direct subscription rather than useTick.",
+          "code": "\"use client\";\nimport { useEffect, useRef } from \"react\";\nimport { InteractionScope, useInteractionScope, getConductor } from \"@vectorvesper/motion/react\";\n\nfunction Painter() {\n  const canvas = useRef<HTMLCanvasElement>(null);\n  const scope = useInteractionScope();\n\n  useEffect(() => {\n    return getConductor().subscribe(\"render\", () => paint(canvas.current), {\n      priority: \"enhanced\",\n      scope: scope ?? undefined,   // protected while this region is held\n      label: \"painter\",\n    });\n  }, [scope]);\n\n  return <canvas ref={canvas} />;\n}\n\nexport function Editor() {\n  return (\n    <InteractionScope label=\"editor\">\n      <Painter />\n    </InteractionScope>\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}"
+          "name": "Checking whether you are inside a region",
+          "blurb": "Null outside one, which is enough to branch on.",
+          "code": "\"use client\";\nimport { useInteractionScope } from \"@vectorvesper/motion/react\";\n\nexport function Widget() {\n  const scope = useInteractionScope();\n  if (!scope) console.warn(\"Widget expects an InteractionScope above it\");\n  return null;\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."
+        "Prefer `useTick`, which reads the same context and needs no id. Use this only when subscribing by hand.",
+        "Pass the id straight through as the `scope` option. It is meant to be opaque.",
+        "List it in the effect dependencies, so remounting under a different region resubscribes correctly."
       ],
       "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."
+        "Don't show it to anyone. It is a generated id, and `label` is the human-readable name.",
+        "Don't compare it against a label. They are different values and only one is stable.",
+        "Don't expect it to change during an interaction. It identifies the region, not whether the region is currently active."
       ],
       "whenNotToUse": [
         {
-          "when": "The content is above the fold.",
-          "instead": "Use `useSafeToMount`, which gates purely on frame headroom. Viewport gating is meaningless for something already on screen."
-        },
-        {
-          "when": "You only need to defer the JavaScript bundle.",
-          "instead": "Use `next/dynamic` or `React.lazy` alone. This hook gates the mount, not the download, and adds a runtime for a problem the bundler already solves."
+          "when": "You are using useTick.",
+          "instead": "Nothing. It already joins the surrounding region, and passing a scope by hand adds a way to get it wrong."
         },
         {
-          "when": "You want a simple entrance animation when something scrolls into view.",
-          "instead": "Use a bare IntersectionObserver or a CSS scroll-driven animation. This hook is about deferring expensive work, not about revealing things."
+          "when": "You want to know whether a region is currently being interacted with.",
+          "instead": "`getConductor().state.activeScope`, which reports the region holding the foreground now. This hook returns which region you are in, whether or not it is active."
         }
       ],
       "guardrails": [
-        "practices/adaptive-performance.md",
-        "practices/react-motion-rules.md",
-        "practices/webgl-budget-and-failopen.md"
+        "practices/react-motion-rules.md"
       ],
-      "docsUrl": "https://vectorvesper.dev/docs/lazy-scene",
-      "labUrl": "https://vectorvesper.dev/lab/lazy-scene",
+      "docsUrl": "https://vectorvesper.dev/runtime/interaction-scope",
+      "labUrl": "https://vectorvesper.dev/runtime/interaction-scope",
       "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.",
@@ -1358,8 +1823,8 @@
         "practices/layout-read-discipline.md",
         "practices/component-api-conventions.md"
       ],
-      "docsUrl": "https://vectorvesper.dev/docs/magnetic-intent",
-      "labUrl": "https://vectorvesper.dev/lab/magnetic-element",
+      "docsUrl": "https://vectorvesper.dev/runtime/magnetic-element",
+      "labUrl": "https://vectorvesper.dev/runtime/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.",
@@ -1449,7 +1914,7 @@
           "Rendering children into the same element — the hook overwrites its textContent every frame."
         ],
         "pairsWith": [
-          "useLazyScene",
+          "useSceneGate",
           "useAnimationBudget"
         ]
       },
@@ -1458,12 +1923,12 @@
         {
           "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}"
+          "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    speed: 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}"
+          "code": "\"use client\";\nimport { useEffect, useRef, useState } from \"react\";\nimport { useNumberTicker } from \"@vectorvesper/motion/react\";\n\nfunction Metric({ target, label, suffix }: { target: number; label: string; suffix?: string }) {\n  // A plain observer is the right tool here. The scene gate answers three more\n  // questions than this needs, and none of them apply to a number.\n  const seen = useRef<HTMLDivElement>(null);\n  const [visible, setVisible] = useState(false);\n\n  useEffect(() => {\n    const el = seen.current;\n    if (!el) return;\n    const io = new IntersectionObserver(\n      ([entry]) => entry.isIntersecting && setVisible(true),\n      { rootMargin: \"0px\" },\n    );\n    io.observe(el);\n    return () => io.disconnect();\n  }, []);\n\n  const { ref } = useNumberTicker<HTMLSpanElement>(visible ? 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",
@@ -1500,8 +1965,8 @@
         "practices/react-motion-rules.md",
         "practices/damping-and-inertia.md"
       ],
-      "docsUrl": "https://vectorvesper.dev/docs/number-ticker",
-      "labUrl": "https://vectorvesper.dev/lab/number-ticker",
+      "docsUrl": "https://vectorvesper.dev/runtime/number-ticker",
+      "labUrl": "https://vectorvesper.dev/runtime/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.",
@@ -1624,12 +2089,12 @@
         {
           "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}"
+          "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    sensitivity: \"high\",\n    onIntentChange: (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}"
+          "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>({ sensitivity: \"high\" });\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",
@@ -1655,7 +2120,7 @@
         },
         {
           "when": "You are on a touch device.",
-          "instead": "Use `useLazyScene` or intersection-based warming. There is no pointer trajectory to extrapolate from a tap, so prediction has nothing to work with."
+          "instead": "Use `useSceneGate` or intersection-based warming. There is no pointer trajectory to extrapolate from a tap, so prediction has nothing to work with."
         },
         {
           "when": "You need to know the pointer actually entered.",
@@ -1667,8 +2132,140 @@
         "practices/layout-read-discipline.md",
         "practices/frame-loop-rules.md"
       ],
-      "docsUrl": "https://vectorvesper.dev/docs/pointer-intent",
-      "labUrl": "https://vectorvesper.dev/lab/pointer-intent",
+      "docsUrl": "https://vectorvesper.dev/runtime/pointer-intent",
+      "labUrl": "https://vectorvesper.dev/runtime/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": "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": "useRenderQuality",
+      "importFrom": "@vectorvesper/motion/r3f",
+      "packageName": "@vectorvesper/motion",
+      "since": "3.0.0",
+      "category": "gate",
+      "tier": "free",
+      "aliases": [
+        "render quality",
+        "r3f adapter",
+        "react three fiber",
+        "canvas dpr",
+        "pixel ratio",
+        "stop render loop",
+        "frameloop never",
+        "webgl context lost",
+        "three js quality"
+      ],
+      "tagline": "Turns a scene gate's verdict into props for <Canvas>.",
+      "problem": "A scene gate decides whether a scene should run and how much of it. Something still has to translate that into renderer settings, stop the loop when nobody is looking, and notice when the browser takes the graphics context away. React Three Fiber does none of those on your behalf, and has no handler for a lost context at all.",
+      "summary": "Call it beside the gate, outside the canvas, and spread the result onto `<Canvas>`. It returns the pixel ratio, the shadow setting, whether the render loop turns, and an `onCreated` that reports a lost graphics context so the gate can hand back a new generation to remount on.",
+      "mechanism": "A pure function of the scene state, returning props. It imports no React Three Fiber value at all, only React, and renders nothing.\n\nThe profile is chosen by state: the full profile while the scene is active, the reduced one in every other state. The frame loop is set to never only while the state is idle, which stops React Three Fiber rendering entirely without touching the context, the textures or the geometry, so coming back into view costs one frame rather than a full re-upload. The returned object is memoised, so spreading it does not reconfigure the canvas on every parent render.\n\nIt returns props rather than applying settings imperatively, and that is the whole design. Earlier versions ran inside the canvas and called the store's setters for pixel ratio and frame loop, and assigned the shadow map directly. None of it survived. React Three Fiber re-runs its configure pass on every canvas render and resets all three from its props, and v9 defaults the pixel ratio and the frame loop rather than leaving them unset, so every imperative call was undone on the next render. Measured against the old behaviour in a real browser: an idle scene rendered a further 167 frames in three seconds, and a renderer asked for a pixel ratio of 1 sat at 1.25. These are React Three Fiber's settings, so the only way to hold them is to be the thing it reconciles against.\n\nThe same reasoning explains the one warning that matters: passing a pixel ratio, frame loop or shadow prop yourself alongside the spread means your value wins on the next reconcile, silently, with no error.",
+      "signature": "useRenderQuality(state: SceneState, profiles: RenderProfiles): RenderQualityProps",
+      "options": [
+        {
+          "name": "state",
+          "type": "SceneState",
+          "default": "(required)",
+          "required": true,
+          "description": "Pass a scene gate's `state` straight through."
+        },
+        {
+          "name": "profiles",
+          "type": "{ full: RenderProfile; reduced: RenderProfile }",
+          "default": "(required)",
+          "required": true,
+          "description": "What each quality level means to the renderer. The full profile is used while the state is active, and reduced in every other state. A RenderProfile carries an optional `dpr` and an optional `shadows`, and nothing else: particle counts and geometry detail are not renderer settings, so they stay in your component keyed off the gate's `quality`."
+        }
+      ],
+      "returns": [
+        {
+          "name": "dpr",
+          "type": "number | undefined",
+          "description": "Device pixel ratio from the active profile. The single biggest saving on a dense display, because going from 3 to 1.5 quarters the pixels shaded."
+        },
+        {
+          "name": "frameloop",
+          "type": "\"always\" | \"never\"",
+          "description": "Never while the state is idle, which stops rendering entirely while keeping the context and everything uploaded to it."
+        },
+        {
+          "name": "shadows",
+          "type": "boolean | undefined",
+          "description": "Shadow setting from the active profile."
+        },
+        {
+          "name": "onCreated",
+          "type": "(state: { gl: { domElement: HTMLCanvasElement } }) => void",
+          "description": "Attaches a webglcontextlost listener that calls preventDefault, without which the browser will not attempt a restore, and reports the loss so the scene gate can hand back a new generation for the canvas key."
+        }
+      ],
+      "runtime": {
+        "lane": null,
+        "priority": null,
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": false,
+        "reRendersPerFrame": 0,
+        "usesPointer": false,
+        "usesScroll": false,
+        "usesWebGL": true,
+        "ownsTransform": false,
+        "sharedSingletons": [
+          "RendererHealth"
+        ],
+        "conflictsWith": [],
+        "pairsWith": [
+          "useSceneGate",
+          "useAdaptiveQuality"
+        ]
+      },
+      "quickStart": "\"use client\";\nimport { Canvas } from \"@react-three/fiber\";\nimport { useSceneGate } from \"@vectorvesper/motion/react\";\nimport { useRenderQuality } from \"@vectorvesper/motion/r3f\";\n\nexport function Hero() {\n  const scene = useSceneGate<HTMLDivElement>({ label: \"hero\" });\n\n  const canvas = useRenderQuality(scene.state, {\n    full:    { dpr: 2, shadows: true },\n    reduced: { dpr: 1, shadows: false },\n  });\n\n  return (\n    <div ref={scene.ref} className=\"h-screen\">\n      {scene.mounted && (\n        <Canvas key={scene.generation} {...canvas}>\n          <Model detail={scene.quality} />\n        </Canvas>\n      )}\n    </div>\n  );\n}",
+      "recipes": [
+        {
+          "name": "Detail the adapter cannot own",
+          "blurb": "Pixel ratio and shadows are renderer settings. Instance counts are not, so the component keeps those and reads the same verdict.",
+          "code": "\"use client\";\nimport { Canvas } from \"@react-three/fiber\";\nimport { useSceneGate } from \"@vectorvesper/motion/react\";\nimport { useRenderQuality } from \"@vectorvesper/motion/r3f\";\n\nexport function Field() {\n  const scene = useSceneGate<HTMLDivElement>({ label: \"field\", cost: \"heavy\" });\n\n  const canvas = useRenderQuality(scene.state, {\n    full:    { dpr: 2, shadows: true },\n    reduced: { dpr: 1, shadows: false },\n  });\n\n  return (\n    <div ref={scene.ref}>\n      {scene.mounted && (\n        <Canvas key={scene.generation} {...canvas}>\n          <Spires count={scene.quality === \"full\" ? 3000 : 250} />\n        </Canvas>\n      )}\n    </div>\n  );\n}"
+        },
+        {
+          "name": "A poster for devices that will never run it",
+          "blurb": "The gate reports a permanent refusal separately from a temporary one.",
+          "code": "\"use client\";\nimport { Canvas } from \"@react-three/fiber\";\nimport { useSceneGate } from \"@vectorvesper/motion/react\";\nimport { useRenderQuality } from \"@vectorvesper/motion/r3f\";\n\nexport function Showcase() {\n  const scene = useSceneGate<HTMLDivElement>({ label: \"showcase\" });\n  const canvas = useRenderQuality(scene.state, {\n    full:    { dpr: 2, shadows: true },\n    reduced: { dpr: 1, shadows: false },\n  });\n\n  if (scene.state === \"poster\") return <img src=\"/showcase.jpg\" alt=\"\" />;\n\n  return (\n    <div ref={scene.ref}>\n      {scene.mounted && (\n        <Canvas key={scene.generation} {...canvas}>\n          <Model detail={scene.quality} />\n        </Canvas>\n      )}\n    </div>\n  );\n}"
+        }
+      ],
+      "dos": [
+        "Call it outside <Canvas>. It returns props, and props go on the element.",
+        "Spread the whole object. Picking fields out of it means picking which of the four jobs you keep.",
+        "Put the gate's `generation` on the canvas key. Without it a lost context leaves a permanently black rectangle.",
+        "Keep instance counts and geometry detail in your own component, keyed off the gate's `quality`."
+      ],
+      "donts": [
+        "Don't also pass dpr, frameloop or shadows to <Canvas>. React Three Fiber reconciles all three from props on every render, so your value silently wins and the adapter's decision is discarded.",
+        "Don't call it inside a <Canvas> child. It needs no R3F context, and its output has to reach the canvas element itself.",
+        "Don't put post-processing or particle counts in a profile. A RenderProfile is renderer settings only, and an option that looks applied and is not is worse than no option."
+      ],
+      "whenNotToUse": [
+        {
+          "when": "You are not rendering with React Three Fiber.",
+          "instead": "Read the gate's `state` and `quality` directly and apply them to your own renderer. The gate knows nothing about three, which is the point of the split."
+        },
+        {
+          "when": "You want a quality tier for something that is not a scene.",
+          "instead": "`useAdaptiveQuality`. This adapter applies a decision and never makes one."
+        },
+        {
+          "when": "The scene never leaves the viewport and always runs at one quality.",
+          "instead": "Ordinary Canvas props. The adapter earns its place when the answer changes."
+        }
+      ],
+      "guardrails": [
+        "practices/adaptive-performance.md",
+        "practices/react-motion-rules.md"
+      ],
+      "docsUrl": "https://vectorvesper.dev/runtime/render-quality",
+      "labUrl": "https://vectorvesper.dev/runtime/render-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.",
@@ -1689,34 +2286,22 @@
         "mount gate",
         "hydration safe",
         "when to mount",
-        "idle mount"
+        "idle mount",
+        "mount cost",
+        "SAFE_TO_MOUNT_COST"
       ],
       "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.",
-      "mechanism": "A gate that opens once and never closes. It returns false, then true, and stays true for the rest of the mount — an expensive component that unmounted itself the moment it made the page slow would oscillate forever, so the one-way behaviour is deliberate.\n\nThree conditions, in order. A static hardware floor reads logical cores and gives up permanently below the threshold, because core count is the one signal that cannot improve while the page is open. It then holds the AnimationBudget open with an empty subscription: the governor only measures while something is subscribed, so polling an unsubscribed one would read a frozen snapshot forever. Finally it counts consecutive clean frames from the input lane at essential priority, subscribed after the governor's own measure pass so it reads state produced by this very frame. Any frame below the headroom threshold resets the count to zero.\n\nIt polls per frame rather than per budget emission on purpose. The budget only emits on tier changes and a 2Hz heartbeat, which would quietly turn a three-clean-frame requirement into a second and a half of waiting.\n\nThere is deliberately no shortcut for an already-healthy page. Opening immediately would require a synchronous state update inside the effect and a cascading render, and it cannot move into render without breaking hydration — the server has no frame timings, so the first client render must agree with it and start false. Waiting the same three frames everywhere costs roughly 50ms before an expensive mount, which buys one code path instead of two.",
+      "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. You describe how expensive the thing is with a single `cost`, and that picks the thresholds.",
+      "mechanism": "A gate that opens once and never closes. It returns false, then true, and stays true for the rest of the mount — an expensive component that unmounted itself the moment it made the page slow would oscillate forever, so the one-way behaviour is deliberate.\n\nOne option, three thresholds behind it. `cost` resolves to a required headroom in milliseconds, a number of consecutive clean frames, and a CPU core floor. The three used to be separate numeric options, and the catalogue settled the question: of ten call sites, six passed the identical override and four passed nothing. Nobody was tuning, everyone was working around a default, because how much spare frame time a component deserves is not a question the person writing it can answer. How expensive it is, they can. The resolved table is exported as SAFE_TO_MOUNT_COST for anything that has to explain why a gate is still closed.\n\nThree conditions, in order. A static hardware floor reads logical cores and gives up permanently below the threshold, because core count is the one signal that cannot improve while the page is open. It then holds the AnimationBudget open with an empty subscription: the governor only measures while something is subscribed, so polling an unsubscribed one would read a frozen snapshot forever. Finally it counts consecutive clean frames from the input lane at essential priority, subscribed after the governor's own measure pass so it reads state produced by this very frame. Any frame below the headroom threshold resets the count to zero.\n\nIt polls per frame rather than per budget emission on purpose. The budget only emits on tier changes and a 2Hz heartbeat, which would quietly turn a three-clean-frame requirement into a second and a half of waiting.\n\nThere is deliberately no shortcut for an already-healthy page. Opening immediately would require a synchronous state update inside the effect and a cascading render, and it cannot move into render without breaking hydration — the server has no frame timings, so the first client render must agree with it and start false. Waiting the same few frames everywhere buys one code path instead of two.",
       "signature": "useSafeToMount(options?: UseSafeToMountOptions): boolean",
       "options": [
         {
-          "name": "minHeadroomMs",
-          "type": "number",
-          "default": "6",
-          "required": false,
-          "description": "Free time each qualifying frame must have left. Measured against the detected display rate, so 6 is about a third of a 60Hz frame and about three quarters of a 120Hz one — the same threshold means the same thing everywhere."
-        },
-        {
-          "name": "requiredCleanFrames",
-          "type": "number",
-          "default": "3",
-          "required": false,
-          "description": "Consecutive qualifying frames needed before the gate opens."
-        },
-        {
-          "name": "minCores",
-          "type": "number",
-          "default": "4",
+          "name": "cost",
+          "type": "\"light\" | \"normal\" | \"heavy\"",
+          "default": "\"normal\"",
           "required": false,
-          "description": "Logical CPU cores below which the gate never opens at all. Permanent — cores do not improve while the page is open."
+          "description": "How expensive the thing you are about to mount is. The heavier it is, the more spare frame time the page has to show before starting is worth it. `light` is a small canvas or a handful of animated elements and opens after 1 clean frame with 1ms spare. `normal` covers most components: 2 frames at 2ms. `heavy` is a full 3D scene, post-processing or a large particle system, and wants 3 frames at 6ms. `light` also drops the core floor from 4 to 2, so it can open on a weak device where the other two never will. The exact numbers are readable at runtime as `SAFE_TO_MOUNT_COST`."
         }
       ],
       "returns": [
@@ -1743,7 +2328,7 @@
         ],
         "conflictsWith": [],
         "pairsWith": [
-          "useLazyScene",
+          "useSceneGate",
           "useAnimationBudget",
           "useAdaptiveQuality"
         ]
@@ -1753,28 +2338,35 @@
         {
           "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}"
+          "code": "\"use client\";\nimport { useSafeToMount } from \"@vectorvesper/motion/react\";\n\nexport function Overview({ kpis }: { kpis: Kpi[] }) {\n  const canMount = useSafeToMount({ cost: \"heavy\" });\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}"
+          "blurb": "A bundle whose cost you don't control is heavy by definition, whatever its file size suggests.",
+          "code": "\"use client\";\nimport { useSafeToMount } from \"@vectorvesper/motion/react\";\n\nexport function MapPanel() {\n  const canMount = useSafeToMount({ cost: \"heavy\" });\n  return canMount ? <InteractiveMap /> : <StaticMapImage />;\n}"
+        },
+        {
+          "name": "Explaining a closed gate",
+          "blurb": "The thresholds are readable, so a devtools panel or a docs demo can say why it has not opened yet rather than keeping its own copy of the numbers.",
+          "code": "import { SAFE_TO_MOUNT_COST } from \"@vectorvesper/motion/react\";\n\nconst { headroomMs, cleanFrames, minCores } = SAFE_TO_MOUNT_COST.heavy;\n// → 6, 3, 4"
         }
       ],
       "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."
+        "Answer the question it actually asks. `cost` describes the component, not the device or the page it lands on.",
+        "Keep `cost` constant. It is an effect dependency, and changing it 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."
+        "Don't wrap it around something cheap — the gate costs more than the thing it is protecting.",
+        "Don't reach for `heavy` to be safe. On a 4-core machine a heavy gate can stay shut for the life of the page, and the fallback is then the only thing anyone sees."
       ],
       "whenNotToUse": [
         {
           "when": "The component is below the fold or off-screen.",
-          "instead": "Use `useLazyScene`, which adds viewport proximity and an idle-callback gate. Frame headroom alone will happily mount something nobody can see."
+          "instead": "Use `useSceneGate`, which adds viewport proximity, a wait for the page to stop scrolling, a quality verdict and graphics-context recovery. Frame headroom alone will happily mount something nobody can see."
         },
         {
           "when": "You want to keep tuning a scene that is already running.",
@@ -1789,8 +2381,8 @@
         "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",
+      "docsUrl": "https://vectorvesper.dev/runtime/safe-to-mount",
+      "labUrl": "https://vectorvesper.dev/runtime/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.",
@@ -1799,11 +2391,176 @@
       }
     },
     {
-      "name": "useSensorBus",
+      "name": "useSceneGate",
       "importFrom": "@vectorvesper/motion/react",
       "packageName": "@vectorvesper/motion",
-      "since": "0.1.0",
-      "category": "sensor",
+      "since": "2.0.0",
+      "category": "gate",
+      "tier": "free",
+      "aliases": [
+        "scene gate",
+        "lazy scene",
+        "lazy 3d",
+        "webgl gate",
+        "mount 3d scene",
+        "pause offscreen",
+        "context lost",
+        "canvas recovery"
+      ],
+      "tagline": "One policy for a heavy scene: when to mount, whether to draw, at what quality, and how to come back from a lost context.",
+      "problem": "A heavy scene needs four separate decisions and most code answers only the first. The result is a WebGL canvas that mounted correctly and is now burning frames for someone who scrolled past it ten seconds ago, or a black rectangle after the browser took the graphics context away and nothing noticed.",
+      "summary": "Returns a ref to attach and a verdict to read: whether the scene should exist, whether it should be drawing, how much of it to build, and a generation counter that changes when the graphics context dies. It decides and reports; applying the verdict to a renderer is `useRenderQuality` on the r3f entry, or your own code.",
+      "mechanism": "A small state machine over four inputs, each of which already has its own owner.\n\nProximity comes from an IntersectionObserver with a preload margin, so the scene starts warming before it is visible. Affordability comes from useSafeToMount, which is called rather than reimplemented, so there is one definition of whether the page can carry an expensive mount and every caller shares it. Stillness comes from the sensor bus: the first mount waits for scroll velocity to drop below a threshold, because mounting a scene mid-scroll is what a reader feels as a stutter whatever the frame numbers say. Only the first mount waits for that; once the scene exists, scrolling past it is free.\n\nQuality comes from AdaptiveQuality's fused tier, which already accounts for the device floor, the live frame budget, the motion preference and the pressure verdict. Earlier versions read the pressure classifier here and applied the only-rendering-is-worth-degrading-for rule themselves, which meant that rule was reachable from this one hook and nowhere else. It lives in the governor now, so the tier arrives already knowing whether reducing quality would help, and the cause travels with it.\n\nTwo behaviours exist to stop it flapping. Once the scene has started it stays started, so scrolling past yields the idle state rather than an unmount: tearing down a scene throws away the graphics context and every texture on it, and coming back pays for all of that again. And once quality drops it holds down for a few seconds even if conditions improve, because a scene that rebuilds its detail level twice a second is worse than one that is simply a little plain for a while.\n\nThe ref is a hybrid: a callback ref that also exposes a current property. A plain ref read once from an effect finds nothing when the element arrives on a later commit, which is what happens behind a spinner, a Suspense fallback or a dynamic import placeholder. That shape shipped once and produced a scene stuck in its dormant state forever with no error to explain it.",
+      "signature": "useSceneGate<T extends HTMLElement>(options?: UseSceneGateOptions): SceneGate<T>",
+      "options": [
+        {
+          "name": "label",
+          "type": "string",
+          "default": "undefined",
+          "required": false,
+          "description": "A human-readable name, prefixed onto `reason` and shown in devtools. No effect on behaviour."
+        },
+        {
+          "name": "cost",
+          "type": "\"light\" | \"normal\" | \"heavy\"",
+          "default": "\"heavy\"",
+          "required": false,
+          "description": "How expensive the scene is. Passed straight to useSafeToMount, so a scene and a chart on the same page share one definition of what the page can afford. Declare what the thing actually is: a 280px wireframe canvas asking for `heavy` will sit unmounted for a very long time on a slow machine, correctly."
+        },
+        {
+          "name": "preload",
+          "type": "number",
+          "default": "200",
+          "required": false,
+          "description": "How far before the viewport to start warming, in pixels. Also the margin the scene must clear before it counts as off screen, which matters for a sticky element: one that comes to rest flush against the viewport edge never gets far enough away to idle."
+        }
+      ],
+      "returns": [
+        {
+          "name": "ref",
+          "type": "RefObject<T | null>",
+          "description": "Attach to the element that holds the scene. Safe to attach on a later commit, behind a spinner or a dynamic import."
+        },
+        {
+          "name": "state",
+          "type": "\"dormant\" | \"warming\" | \"active\" | \"constrained\" | \"idle\" | \"recovering\" | \"poster\"",
+          "description": "Where the scene is in its life."
+        },
+        {
+          "name": "mounted",
+          "type": "boolean",
+          "description": "Whether the scene should exist. True for active, constrained, idle and recovering. Idle is included on purpose: a scene that is merely off screen should be paused, not torn down."
+        },
+        {
+          "name": "quality",
+          "type": "\"full\" | \"reduced\" | null",
+          "description": "How much scene to build, and null whenever there is no scene. You decide what full and reduced mean."
+        },
+        {
+          "name": "generation",
+          "type": "number",
+          "description": "Put this on the canvas key. It changes when the graphics context is lost, which is what makes React throw the dead tree away and build a working one."
+        },
+        {
+          "name": "cause",
+          "type": "\"ok\" | \"not-near\" | \"waiting-for-headroom\" | \"off-screen\" | \"render-bound\" | \"frame-rate\" | \"device-floor\" | \"reduced-motion\" | \"context-lost\"",
+          "description": "The machine-readable reason for the current state. Branch on this one."
+        },
+        {
+          "name": "reason",
+          "type": "string",
+          "description": "The same fact written for a person, for a support thread or a devtools row. The wording is free to change between releases, so branch on cause."
+        }
+      ],
+      "runtime": {
+        "lane": "update",
+        "priority": "essential",
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": true,
+        "reRendersPerFrame": 0,
+        "usesPointer": false,
+        "usesScroll": true,
+        "usesWebGL": false,
+        "ownsTransform": false,
+        "sharedSingletons": [
+          "FrameConductor",
+          "SensorBus",
+          "AnimationBudget",
+          "AdaptiveQuality",
+          "RendererHealth"
+        ],
+        "conflictsWith": [],
+        "pairsWith": [
+          "useRenderQuality",
+          "useSafeToMount",
+          "useAdaptiveQuality"
+        ]
+      },
+      "quickStart": "\"use client\";\nimport { useSceneGate } from \"@vectorvesper/motion/react\";\n\nexport function Hero() {\n  const scene = useSceneGate<HTMLDivElement>({ label: \"hero\" });\n\n  return (\n    <div ref={scene.ref} className=\"h-screen\">\n      {scene.mounted\n        ? <Scene detail={scene.quality} paused={scene.state === \"idle\"} />\n        : <img src=\"/hero-poster.jpg\" alt=\"\" />}\n    </div>\n  );\n}",
+      "recipes": [
+        {
+          "name": "React Three Fiber",
+          "blurb": "The adapter turns the verdict into Canvas props: pixel ratio, shadows, whether the render loop turns, and context-loss reporting.",
+          "code": "\"use client\";\nimport { useSceneGate } from \"@vectorvesper/motion/react\";\nimport { useRenderQuality } from \"@vectorvesper/motion/r3f\";\nimport { Canvas } from \"@react-three/fiber\";\n\nexport function Hero() {\n  const scene = useSceneGate<HTMLDivElement>({ label: \"hero\", cost: \"heavy\" });\n\n  const canvas = useRenderQuality(scene.state, {\n    full:    { dpr: 2, shadows: true },\n    reduced: { dpr: 1, shadows: false },\n  });\n\n  return (\n    <div ref={scene.ref} className=\"h-screen\">\n      {scene.mounted ? (\n        // Do NOT also set dpr, frameloop or shadows here. R3F reconciles all\n        // three from props on every render, so a second owner silently wins.\n        <Canvas key={scene.generation} {...canvas}>\n          <Particles count={scene.quality === \"full\" ? 40_000 : 12_000} />\n        </Canvas>\n      ) : (\n        <img src=\"/hero-poster.jpg\" alt=\"\" />\n      )}\n    </div>\n  );\n}"
+        },
+        {
+          "name": "Reacting to the reason",
+          "blurb": "A device that will never run the scene deserves different copy from a page that is briefly busy.",
+          "code": "\"use client\";\nimport { useSceneGate } from \"@vectorvesper/motion/react\";\n\nexport function Showcase() {\n  const scene = useSceneGate<HTMLDivElement>({ label: \"showcase\" });\n\n  if (scene.cause === \"device-floor\" || scene.cause === \"reduced-motion\") {\n    // Permanent for this visit. Show the poster and stop promising a scene.\n    return <img src=\"/showcase.jpg\" alt=\"\" />;\n  }\n\n  return (\n    <div ref={scene.ref}>\n      {scene.mounted ? <Scene detail={scene.quality} /> : <Skeleton />}\n    </div>\n  );\n}"
+        },
+        {
+          "name": "A plain canvas, no r3f",
+          "blurb": "The gate knows nothing about three. Stop your own loop when it says idle.",
+          "code": "\"use client\";\nimport { useEffect } from \"react\";\nimport { useSceneGate, getConductor } from \"@vectorvesper/motion/react\";\n\nexport function Viz() {\n  const scene = useSceneGate<HTMLDivElement>({ label: \"viz\", cost: \"normal\" });\n  const running = scene.mounted && scene.state !== \"idle\";\n\n  useEffect(() => {\n    if (!running) return;\n    return getConductor().subscribe(\"render\", () => draw(), {\n      priority: \"decorative\",\n      label: \"viz\",\n    });\n  }, [running]);\n\n  return <div ref={scene.ref} />;\n}"
+        }
+      ],
+      "dos": [
+        "Put the ref on the element whose visibility actually decides things. On a pinned sequence that is the sticky child, because the tall scroll track counts as near the viewport for the whole sequence.",
+        "Put `generation` on the canvas key. Without it a lost graphics context leaves a permanently black rectangle.",
+        "Keep the scene mounted while `state` is idle and stop drawing instead. Unmounting throws away the context and every texture on it.",
+        "Branch on `cause` rather than `reason`. The wording of `reason` is free to change.",
+        "Give the trailing section more height than `preload`, or the scene never gets far enough away to idle."
+      ],
+      "donts": [
+        "Don't treat `quality` as meaningful while `mounted` is false. It is null then, which is the point.",
+        "Don't reduce quality for anything except rendering being slow. The gate already applies that rule; if you add your own, apply it to `cause === \"render-bound\"` only.",
+        "Don't declare a small canvas as `heavy`. On a throttled machine the gate will correctly refuse to mount it for a very long time.",
+        "Don't gate content the visitor came for. This is for decoration and spectacle, never for the thing being read."
+      ],
+      "whenNotToUse": [
+        {
+          "when": "You only need to know whether an element is on screen.",
+          "instead": "An IntersectionObserver, directly. The gate earns its place when affordability, quality and context loss matter too."
+        },
+        {
+          "when": "The component is expensive but is not a scene, and is already on screen.",
+          "instead": "`useSafeToMount`, which answers the affordability question alone and returns a boolean."
+        },
+        {
+          "when": "The scene is already running and you only want to scale its detail.",
+          "instead": "`useAdaptiveQuality`. You do not need the mount decision to decide whether to drop a particle layer."
+        }
+      ],
+      "guardrails": [
+        "practices/adaptive-performance.md",
+        "practices/react-motion-rules.md"
+      ],
+      "docsUrl": "https://vectorvesper.dev/runtime/scene-gate",
+      "labUrl": "https://vectorvesper.dev/runtime/scene-gate",
+      "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": "useSensorBus",
+      "importFrom": "@vectorvesper/motion/react",
+      "packageName": "@vectorvesper/motion",
+      "since": "0.1.0",
+      "category": "sensor",
       "tier": "free",
       "aliases": [
         "mouse position",
@@ -1897,8 +2654,158 @@
         "practices/layout-read-discipline.md",
         "practices/react-motion-rules.md"
       ],
-      "docsUrl": "https://vectorvesper.dev/docs/sensor-bus",
-      "labUrl": "https://vectorvesper.dev/lab/sensor-bus",
+      "docsUrl": "https://vectorvesper.dev/runtime/sensor-bus",
+      "labUrl": "https://vectorvesper.dev/runtime/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": "useTick",
+      "importFrom": "@vectorvesper/motion/react",
+      "packageName": "@vectorvesper/motion",
+      "since": "2.0.0",
+      "category": "effect",
+      "tier": "free",
+      "aliases": [
+        "use raf",
+        "animation frame hook",
+        "run every frame",
+        "frame loop react",
+        "requestanimationframe hook",
+        "custom effect",
+        "subscribe to conductor"
+      ],
+      "tagline": "Run a callback every frame from a React component, on the shared loop.",
+      "problem": "The obvious way to animate from a component is a requestAnimationFrame loop inside an effect. Five components doing that is five loops the browser must run, five interleavings of reads and writes, and no way for any of them to yield when the frame is already full.",
+      "summary": "Subscribes a callback to one lane of the shared FrameConductor for the lifetime of the component and unsubscribes on unmount. Automatically joins the nearest InteractionScope, so work inside the region a visitor is using keeps its frames while ambient work outside yields first.",
+      "mechanism": "A thin React binding over the conductor's subscribe, with two details that matter.\n\nThe callback is held in a ref and swapped behind a stable function. Re-subscribing on every render would churn the lane arrays and reset the subscriber's cost average, so the latest closure is installed without the subscription itself changing. That means the callback always sees fresh props without the loop noticing.\n\nScope membership is read from React context rather than passed as an argument. Anything rendered inside an InteractionScope joins it automatically, which is what makes the protection work without per-child configuration: while that region holds the foreground lease, subscribers belonging to other regions or to none are tested against a stricter shedding threshold. Passing `background: true` opts a subscriber out, for work that is ambient even though it happens to be rendered inside a region.\n\nWorth knowing about shedding generally: the threshold is measured against how much of the frame budget this runtime has already spent when a subscriber's turn arrives, and the check happens before it runs. A subscriber that runs first in its lane therefore never sheds, however overloaded the page is. Priority sets the threshold; position decides whether the threshold is ever reached.",
+      "signature": "useTick(lane: ConductorLane, fn: FrameFn, options?: UseTickOptions): void",
+      "options": [
+        {
+          "name": "lane",
+          "type": "\"input\" | \"update\" | \"render\"",
+          "default": "(required)",
+          "required": true,
+          "description": "Which phase to run in. Read the DOM and sensors in `input`, do maths in `update`, write to the DOM or canvas in `render`. Every read across the page finishes before any write begins, which is what keeps layout to one calculation per frame."
+        },
+        {
+          "name": "fn",
+          "type": "(dt: number, time: number) => void",
+          "default": "(required)",
+          "required": true,
+          "description": "Called once per frame. `dt` is seconds since this subscriber last ran, already clamped so a backgrounded tab waking up cannot feed a huge step into spring maths. `time` is the shared clock, also in seconds."
+        },
+        {
+          "name": "priority",
+          "type": "\"essential\" | \"enhanced\" | \"decorative\"",
+          "default": "\"enhanced\"",
+          "required": false,
+          "description": "Shed order when a frame runs long. Reserve `essential` for sensors, governors and direct manipulation, because a scrub that stutters is a broken scrub. `decorative` yields first."
+        },
+        {
+          "name": "hz",
+          "type": "number",
+          "default": "0",
+          "required": false,
+          "description": "Cap the cadence, in runs per second. The accumulated dt is passed through, so damping stays correct. Declare it for any decorative work whose position the eye follows: shedding is regular but lands near 12fps, which reads as broken for tracked motion, while `hz: 30` looks fine and does less total work."
+        },
+        {
+          "name": "label",
+          "type": "string",
+          "default": "\"anonymous\"",
+          "required": false,
+          "description": "Name shown in devtools and in slow-subscriber warnings. Worth setting every time."
+        },
+        {
+          "name": "enabled",
+          "type": "boolean",
+          "default": "true",
+          "required": false,
+          "description": "Set false to unsubscribe without unmounting the component."
+        },
+        {
+          "name": "background",
+          "type": "boolean",
+          "default": "false",
+          "required": false,
+          "description": "Opt out of the surrounding InteractionScope. Use it for ambient work that happens to be rendered inside a region a visitor interacts with."
+        }
+      ],
+      "returns": [],
+      "runtime": {
+        "lane": null,
+        "priority": "enhanced",
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": false,
+        "reRendersPerFrame": 0,
+        "usesPointer": false,
+        "usesScroll": false,
+        "usesWebGL": false,
+        "ownsTransform": false,
+        "sharedSingletons": [
+          "FrameConductor"
+        ],
+        "conflictsWith": [],
+        "pairsWith": [
+          "useSensorBus",
+          "InteractionScope",
+          "damp"
+        ]
+      },
+      "quickStart": "\"use client\";\nimport { useRef } from \"react\";\nimport { useTick } from \"@vectorvesper/motion/react\";\n\nexport function Pulse() {\n  const ref = useRef<HTMLDivElement>(null);\n\n  useTick(\"render\", (_dt, time) => {\n    if (!ref.current) return;\n    ref.current.style.opacity = String(0.5 + Math.sin(time * 2) * 0.5);\n  }, { label: \"pulse\" });\n\n  return <div ref={ref} />;\n}",
+      "recipes": [
+        {
+          "name": "Follow the pointer, smoothly",
+          "blurb": "Read sensors in `input`, write transforms in `render`, and smooth with damp so it feels the same at 60Hz and 120Hz.",
+          "code": "\"use client\";\nimport { useRef } from \"react\";\nimport { useTick, useSensorBus, damp } from \"@vectorvesper/motion/react\";\n\nexport function Follower() {\n  const ref = useRef<HTMLDivElement>(null);\n  const pos = useRef({ x: 0, y: 0 });\n  const bus = useSensorBus();\n\n  useTick(\"render\", (dt) => {\n    const el = ref.current;\n    if (!el) return;\n    const { x, y } = bus.state.pointer;\n    pos.current.x = damp(pos.current.x, x, 8, dt);\n    pos.current.y = damp(pos.current.y, y, 8, dt);\n    el.style.transform = `translate3d(${pos.current.x}px, ${pos.current.y}px, 0)`;\n  }, { label: \"follower\" });\n\n  return <div ref={ref} />;\n}"
+        },
+        {
+          "name": "Ambient work that yields",
+          "blurb": "Decorative, throttled, and marked as background so a drag elsewhere takes priority.",
+          "code": "\"use client\";\nimport { useTick } from \"@vectorvesper/motion/react\";\n\nuseTick(\"render\", (dt) => drift(dt), {\n  priority: \"decorative\",\n  hz: 30,\n  background: true,\n  label: \"ambient drift\",\n});"
+        },
+        {
+          "name": "Turning it off without unmounting",
+          "blurb": "A paused scene should stop costing frames while keeping everything it allocated.",
+          "code": "\"use client\";\nimport { useTick, useSceneGate } from \"@vectorvesper/motion/react\";\n\nexport function Viz() {\n  const scene = useSceneGate<HTMLDivElement>({ label: \"viz\" });\n\n  useTick(\"render\", draw, {\n    enabled: scene.mounted && scene.state !== \"idle\",\n    label: \"viz draw\",\n  });\n\n  return <div ref={scene.ref} />;\n}"
+        }
+      ],
+      "dos": [
+        "Set a `label`. It is the difference between a readable devtools row and `anonymous`.",
+        "Write to the DOM through a ref. Calling setState from a frame callback re-renders sixty times a second, which is the cost this runtime exists to remove.",
+        "Read in `input`, compute in `update`, write in `render`. Mixing them reintroduces the layout thrashing the lanes prevent.",
+        "Use `hz` for decorative motion whose position the eye tracks, rather than leaving it to shedding."
+      ],
+      "donts": [
+        "Don't start a requestAnimationFrame loop next to this. A second loop is invisible to the budget, is billed to main-thread by the pressure classifier, and cannot be shed.",
+        "Don't allocate inside the callback. Sixty allocations a second is a garbage collection pause with a delay on it.",
+        "Don't read `getConductor().state` every frame. It allocates a snapshot; read it a few times a second instead."
+      ],
+      "whenNotToUse": [
+        {
+          "when": "You are animating a single element from A to B on an event.",
+          "instead": "A CSS transition or the Web Animations API. Both run off the main thread and cost you nothing per frame."
+        },
+        {
+          "when": "The work is not per-frame.",
+          "instead": "An ordinary effect, a timer, or an event handler. A frame loop is for things that need to be recomputed continuously."
+        },
+        {
+          "when": "You are outside React.",
+          "instead": "`getConductor().subscribe(lane, fn, options)`, which is what this wraps. It takes an explicit `scope` where this reads one from context."
+        }
+      ],
+      "guardrails": [
+        "practices/react-motion-rules.md",
+        "practices/adaptive-performance.md"
+      ],
+      "docsUrl": "https://vectorvesper.dev/runtime/frame-conductor",
+      "labUrl": "https://vectorvesper.dev/runtime/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.",
@@ -1942,11 +2849,11 @@
           "description": "\"pin\" for tall sticky tracks (the Apple pattern), \"cross\" for a track passing through the viewport, \"auto\" picks pin above ~1.2 viewports."
         },
         {
-          "name": "smooth",
+          "name": "speed",
           "type": "number",
           "default": "8",
           "required": false,
-          "description": "Damping responsiveness. 0 is instant. Forced to 0 under reduced motion."
+          "description": "How quickly the video catches up to the scrub position. Higher arrives sooner, and 0 is instant with no trailing. Forced to 0 under reduced motion. Renamed from `smooth` in 3.0, because that name read backwards: a lower number produced more smoothing."
         },
         {
           "name": "pointerAxis",
@@ -1970,7 +2877,7 @@
           "description": "Attach to the `<video>` element."
         },
         {
-          "name": "trackRef",
+          "name": "ref",
           "type": "RefObject<TTrack | null>",
           "description": "Attach to the element whose geometry defines progress. Defaults to the video's parent."
         },
@@ -2005,26 +2912,26 @@
           "Smooth-scroll libraries that lie about scroll position (verify the mapping if you use one)."
         ],
         "pairsWith": [
-          "useLazyScene",
+          "useSceneGate",
           "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}",
+      "quickStart": "\"use client\";\nimport { useVideoScrubber } from \"@vectorvesper/motion/react\";\n\nexport function ScrollScrub() {\n  const { videoRef, ref } = useVideoScrubber<HTMLDivElement>();\n  return (\n    <div ref={ref} 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}"
+          "code": "\"use client\";\nimport { useVideoScrubber } from \"@vectorvesper/motion/react\";\n\nexport function ProductReveal() {\n  const { videoRef, ref, progressRef } = useVideoScrubber<HTMLDivElement>({\n    driver: \"scroll\",\n    mapping: \"pin\",\n    speed: 10,\n  });\n\n  return (\n    <section ref={ref} 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}"
+          "code": "\"use client\";\nimport { useVideoScrubber } from \"@vectorvesper/motion/react\";\n\nexport function SpinCard({ src }: { src: string }) {\n  const { videoRef, ref } = useVideoScrubber<HTMLDivElement>({\n    driver: \"pointer\",\n    pointerAxis: \"x\",\n    speed: 14,\n  });\n  return (\n    <div ref={ref} 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}"
+          "code": "\"use client\";\nimport { useVideoScrubber } from \"@vectorvesper/motion/react\";\n\nexport function SliderScrub() {\n  const { videoRef, ref, scrubberRef } = useVideoScrubber<HTMLDivElement>({ driver: \"manual\" });\n  return (\n    <div ref={ref}>\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": [
@@ -2058,8 +2965,8 @@
         "practices/layout-read-discipline.md",
         "practices/damping-and-inertia.md"
       ],
-      "docsUrl": "https://vectorvesper.dev/docs/video-scrubber",
-      "labUrl": "https://vectorvesper.dev/lab/video-scrubber",
+      "docsUrl": "https://vectorvesper.dev/runtime/video-scrubber",
+      "labUrl": "https://vectorvesper.dev/runtime/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.",
@@ -2085,7 +2992,7 @@
         "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}",
+      "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({ cost: \"heavy\" });\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.",
@@ -2149,9 +3056,9 @@
           "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": "Calling subscribe without keeping the unsubscribe it hands back.",
+          "consequence": "The returned function is the only handle on the subscription. Dropped, the subscriber outlives the component, the loop never sleeps, the closure leaks, and every remount adds another copy.",
+          "rule": "orphan-subscription"
         },
         {
           "mistake": "Mirroring a per-frame value into React state to render it.",
@@ -2160,7 +3067,8 @@
         },
         {
           "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."
+          "consequence": "Forced synchronous layout every frame. Measure in the input lane; write in render.",
+          "rule": "lane-discipline"
         },
         {
           "mistake": "Autonomous motion with no prefers-reduced-motion guard.",
@@ -2235,25 +3143,41 @@
       "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.",
+      "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. Four decisions hide in that sentence: whether to exist, whether to draw, how rich to be, and what to do when the browser takes the graphics context away.",
       "uses": [
-        "useLazyScene",
-        "useAdaptiveQuality"
+        "useSceneGate",
+        "useRenderQuality"
       ],
       "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// }",
+        "useSceneGate answers all four. It reports `mounted` (should the scene exist), `state` (idle means keep it and stop drawing), `quality` (how much to build) and `generation` (bump the canvas key after a lost context).",
+        "Load the scene component via dynamic(..., { ssr: false }) so its code and its DOM both stay deferred. The gate's ref is a hybrid, so attaching it on a later commit is safe.",
+        "Call useRenderQuality beside the gate and spread its result onto <Canvas>. It owns pixel ratio, shadows, whether the render loop turns, and context-loss reporting.",
+        "Instance counts and geometry detail stay yours, keyed off `quality`. Only the component knows what its own detail is made of.",
+        "The placeholder keeps the scene's final dimensions and meaningful content, so nothing shifts and nothing is lost without a heavy render.",
+        "Mount once and keep it mounted. Scrolling past gives you `idle`, which pauses drawing while keeping the context and every texture on it."
+      ],
+      "code": "\"use client\";\n\nimport dynamic from \"next/dynamic\";\nimport { useSceneGate } from \"@vectorvesper/motion/react\";\n\nconst ExplodedProduct = dynamic(() => import(\"./ExplodedProduct\"), { ssr: false });\n\nexport function ProductBreakdown() {\n  const scene = useSceneGate<HTMLDivElement>({\n    label: \"product breakdown\",\n    cost: \"heavy\",\n    preload: 400,\n  });\n\n  return (\n    <div ref={scene.ref} style={{ height: \"100vh\", position: \"relative\" }}>\n      {scene.mounted ? (\n        <ExplodedProduct\n          generation={scene.generation}\n          state={scene.state}\n          quality={scene.quality}\n        />\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 { Canvas } from \"@react-three/fiber\";\n// import { useRenderQuality } from \"@vectorvesper/motion/r3f\";\n// import type { SceneState } from \"@vectorvesper/motion/react\";\n//\n// export default function ExplodedProduct({ generation, state, quality }: {\n//   generation: number; state: SceneState; quality: \"full\" | \"reduced\" | null;\n// }) {\n//   const canvas = useRenderQuality(state, {\n//     full:    { dpr: 2, shadows: true },\n//     reduced: { dpr: 1, shadows: false },\n//   });\n//\n//   // Do NOT also set dpr, frameloop or shadows on <Canvas>. R3F reconciles\n//   // all three from props on every render, so a second owner silently wins.\n//   return (\n//     <Canvas key={generation} {...canvas}>\n//       <Model particles={quality === \"full\" ? 2000 : 500} />\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": "Passing dpr, frameloop or shadows to <Canvas> alongside the adapter's spread.",
+          "consequence": "React Three Fiber reconciles all three from props on every render of the canvas, so the prop written by hand wins and the adapter's decision is discarded. Nothing errors, nothing warns, and the scene simply never adapts.",
+          "rule": "canvas-prop-override"
+        },
+        {
+          "mistake": "Gating the scene on an IntersectionObserver and stopping there.",
+          "consequence": "Viewport proximity alone mounts a heavy scene mid-flick, on a saturated thread, at full quality, on hardware that cannot hold it — and keeps rendering once it leaves the viewport. The gate is the cheap third of the job.",
+          "rule": "hand-rolled-scene-gate"
+        },
+        {
+          "mistake": "Leaving a lost graphics context unhandled.",
+          "consequence": "The browser can take a WebGL context away at any time. Without a listener that calls preventDefault and a key that moves afterwards, the visitor is left with a permanently black rectangle and a completely clean console.",
+          "rule": "webgl-context-loss"
+        },
         {
           "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."
@@ -2297,7 +3221,7 @@
         "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}",
+      "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    sensitivity: \"high\",\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.",
@@ -2402,7 +3326,7 @@
         "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}",
+      "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>({ sensitivity: \"high\" });\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.",
@@ -2443,17 +3367,17 @@
       "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",
+        "useSceneGate",
         "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.",
+        "Outer component: useSceneGate with a generous preload (400 to 600px), so the video element does not exist until the section approaches. Only `mounted` matters here; the quality and generation fields are for scenes that draw.",
+        "Render a poster while it is unmounted with the SAME track height, so mounting the scrubber never shifts layout.",
+        "Inner component, which mounts only once the gate opens: useVideoScrubber with driver \"scroll\" and mapping \"pin\". Its `ref` goes on the tall section and `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}",
+      "code": "\"use client\";\n\nimport { useSceneGate, useVideoScrubber } from \"@vectorvesper/motion/react\";\n\nconst TRACK_HEIGHT = \"300vh\";\n\nexport function FilmSection() {\n  // A video is not a drawing scene, so only \"mounted\" is used here. The gate\n  // still earns its place: it waits for the page to stop scrolling before\n  // mounting, and mounting mid-scroll is what a reader feels as a stutter.\n  const scene = useSceneGate<HTMLDivElement>({ label: \"film\", cost: \"normal\", preload: 500 });\n\n  return (\n    <div ref={scene.ref}>\n      {scene.mounted ? (\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, ref } = useVideoScrubber<HTMLElement>({\n    driver: \"scroll\",\n    mapping: \"pin\",\n    speed: 8,\n  });\n\n  return (\n    <section ref={ref} 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.",
@@ -2540,5 +3464,1151 @@
         "logo wall"
       ]
     }
+  ],
+  "advice": [
+    {
+      "id": "scrollytelling",
+      "when": [
+        "scrollytelling",
+        "scroll story",
+        "scroll narrative",
+        "story scroll",
+        "scroll driven story"
+      ],
+      "allOf": [],
+      "unless": [],
+      "minHits": 1,
+      "priority": 640,
+      "verdict": "composition",
+      "headline": "A scrubbed video under pinned copy, gated so it only decodes when it is on screen.",
+      "because": "The three parts fail in different ways alone. The scrubber without a gate decodes video for a section nobody has scrolled to. The gate without seek discipline issues a seek per frame and the decoder falls behind. And the copy pinned over it must not animate the same transform the scrubber's host owns, or the two fight every frame.",
+      "use": [
+        "useSceneGate",
+        "useVideoScrubber"
+      ],
+      "pattern": "scrollytelling-video",
+      "components": [
+        "playpause"
+      ],
+      "instead": "A scroll listener assigning `currentTime`, with the video always mounted.",
+      "watchFor": [
+        "transform-conflict",
+        "setstate-per-frame"
+      ],
+      "notWhen": "The story is a sequence of discrete steps rather than a continuous timeline. Steps are IntersectionObserver crossings and CSS, with no per-frame work at all."
+    },
+    {
+      "id": "pointer-parallax",
+      "when": [
+        "parallax",
+        "layers move with the mouse",
+        "depth effect",
+        "tilt with cursor",
+        "parallax scene"
+      ],
+      "allOf": [],
+      "unless": [],
+      "minHits": 1,
+      "priority": 630,
+      "verdict": "composition",
+      "headline": "One sensor read, one damped value per layer, all written in the render lane.",
+      "because": "The naive version attaches a `pointermove` listener per layer and writes a transform inside each — so a five-layer scene does five listener invocations and five interleaved reads and writes per pointer event. Reading the bus once per frame and writing every layer in one pass makes the cost independent of the layer count, and damping is what turns raw pointer values into motion that does not judder on a busy frame.",
+      "use": [
+        "useSensorBus",
+        "useTick",
+        "damp"
+      ],
+      "pattern": "pointer-parallax-scene",
+      "components": [
+        "lookbook",
+        "glass-gallery"
+      ],
+      "instead": "A `pointermove` handler per layer, each writing its own inline transform.",
+      "watchFor": [
+        "transform-conflict",
+        "setstate-per-frame",
+        "lane-discipline"
+      ],
+      "notWhen": "There is no pointer. Parallax keyed to the pointer is inert on touch, so either drive it from scroll instead or accept that half your visitors see a static scene and design for that."
+    },
+    {
+      "id": "velocity-marquee",
+      "when": [
+        "marquee",
+        "ticker tape",
+        "logo strip",
+        "infinite scroll text",
+        "scrolling banner"
+      ],
+      "allOf": [],
+      "unless": [],
+      "minHits": 1,
+      "priority": 620,
+      "verdict": "composition",
+      "headline": "A conductor-driven strip whose speed reads scroll velocity, with a reduced-motion stop.",
+      "because": "A marquee is autonomous motion, which makes it the clearest case in the catalogue for a reduced-motion guard — continuous horizontal drift is exactly what the preference exists to stop. Driving it from the conductor rather than a CSS animation buys the thing CSS cannot do: the strip reacts to scroll velocity, which is what makes it feel connected to the page rather than pasted on top.",
+      "use": [
+        "useSensorBus",
+        "useTick",
+        "damp"
+      ],
+      "pattern": "velocity-marquee",
+      "components": [
+        "image-ticker"
+      ],
+      "instead": "A CSS `animation: scroll linear infinite`, which cannot react to anything.",
+      "watchFor": [
+        "no-reduced-motion",
+        "orphan-raf"
+      ],
+      "notWhen": "The strip does not need to react. A plain CSS animation with a reduced-motion guard runs on the compositor and costs no main-thread time at all — take it."
+    },
+    {
+      "id": "live-dashboard-numbers",
+      "when": [
+        "dashboard",
+        "live numbers",
+        "realtime metrics",
+        "kpi",
+        "stat cards",
+        "updating figures"
+      ],
+      "allOf": [],
+      "unless": [],
+      "minHits": 1,
+      "priority": 610,
+      "verdict": "composition",
+      "headline": "Tickers writing text nodes directly, with the expensive chart held behind a mount gate.",
+      "because": "A dashboard's problem is that everything arrives at once: hydration, a chart mount, and a stream of figures each wanting to animate. Tickers write to DOM nodes so React is not re-rendering per frame for a string, and the chart waits for measured headroom so its mount does not land on top of hydration.",
+      "use": [
+        "useNumberTicker",
+        "useSafeToMount"
+      ],
+      "pattern": "dashboard-live-numbers",
+      "components": [],
+      "instead": "State-driven counters re-rendering the tree, and a chart mounted immediately.",
+      "watchFor": [
+        "setstate-per-frame",
+        "client-boundary"
+      ],
+      "notWhen": "The figures change rarely. A number that updates once a minute should just change — animating it draws the eye to noise, and the roll costs a re-layout of everything on the same line."
+    },
+    {
+      "id": "predictive-media-card",
+      "when": [
+        "hover preview",
+        "video preview on hover",
+        "media card",
+        "card grid preview",
+        "preview on hover"
+      ],
+      "allOf": [],
+      "unless": [],
+      "minHits": 1,
+      "priority": 600,
+      "verdict": "composition",
+      "headline": "Predict the approach, warm the media, and let the poster stay until it can actually play.",
+      "because": "Starting a decode on hover means the first frames arrive after the visitor is already looking, so the card flashes. Predicting the approach moves the work earlier by the time it takes the pointer to arrive, which is usually enough. The discipline that makes it feel right is holding the poster until playback is genuinely ready rather than swapping on the intent signal.",
+      "use": [
+        "usePointerIntent"
+      ],
+      "pattern": "predictive-media-card",
+      "components": [
+        "video-card",
+        "lookbook"
+      ],
+      "instead": "`onMouseEnter` starting a decode the visitor waits through.",
+      "watchFor": [
+        "setstate-per-frame",
+        "transform-conflict"
+      ],
+      "notWhen": "The grid is dense and the media is heavy. Prediction fires on approach, and on a tight grid that means warming several neighbours at once — lower the sensitivity or gate on proximity."
+    },
+    {
+      "id": "not-react",
+      "when": [
+        "vue",
+        "svelte",
+        "solid",
+        "angular",
+        "astro",
+        "vanilla",
+        "no react",
+        "without react",
+        "plain js"
+      ],
+      "allOf": [],
+      "unless": [],
+      "minHits": 1,
+      "priority": 820,
+      "verdict": "single",
+      "headline": "The engine classes and the `get*` accessors. Everything works; only the binding is React-specific.",
+      "because": "The conductor, the sensor bus, the governors and the maths are framework-agnostic singletons reached through accessors — nothing about them needs React. The effects are classes with one lifecycle: construct with an element and options, `update` to change options live, `destroy` to release. The React hooks are thin wrappers over exactly those, so mixing a Vue page with a React island costs nothing extra: both retain the same page-wide loop.",
+      "use": [
+        "EffectEngines",
+        "FrameConductor",
+        "SensorBus"
+      ],
+      "components": [],
+      "instead": "Reimplementing the effects for the framework, each with its own frame loop.",
+      "watchFor": [
+        "orphan-subscription",
+        "ssr-module-scope"
+      ],
+      "notWhen": "You are in React after all. The hooks handle construction, the ref swap and teardown, and `useTick` additionally joins the surrounding interaction scope, which the raw subscribe does not do on its own."
+    },
+    {
+      "id": "custom-effect-fallback",
+      "when": [
+        "animate",
+        "animation",
+        "motion",
+        "effect",
+        "interactive",
+        "canvas",
+        "transform",
+        "follow",
+        "physics",
+        "simulation"
+      ],
+      "allOf": [],
+      "unless": [],
+      "minHits": 1,
+      "priority": 100,
+      "verdict": "custom",
+      "headline": "Nothing here covers it exactly. Build it on the conductor, not on your own loop.",
+      "because": "No primitive matches what you described closely enough to name one honestly. That is a normal outcome and it does not change the scheduling answer: the effect still has to share the page's frame budget, still has to read before it writes, and still has to be visible to the shedding scheduler and to devtools. `custom-frame-effect` is the skeleton for exactly this — subscribe, read in `input`, compute in `update`, write in `render`, return the unsubscribe.",
+      "use": [
+        "useTick",
+        "useSensorBus",
+        "damp"
+      ],
+      "pattern": "custom-frame-effect",
+      "components": [],
+      "instead": "A `requestAnimationFrame` loop in a `useEffect`, which is what training data suggests by default.",
+      "watchFor": [
+        "orphan-raf",
+        "orphan-subscription",
+        "lane-discipline",
+        "setstate-per-frame",
+        "no-reduced-motion"
+      ],
+      "notWhen": "The effect is a transition between two states, a hover, or a one-time reveal. Those are CSS, and a frame subscription for them is main-thread time spent reproducing something the compositor does for free."
+    },
+    {
+      "id": "css-enter-exit",
+      "when": [
+        "fade in",
+        "fade out",
+        "slide in",
+        "slide up",
+        "entrance",
+        "enter animation",
+        "exit animation",
+        "appear",
+        "on mount",
+        "mount animation",
+        "transition in",
+        "fade",
+        "slide",
+        "dissolve",
+        "modal",
+        "dropdown",
+        "tooltip",
+        "accordion"
+      ],
+      "allOf": [],
+      "unless": [
+        "every frame",
+        "per frame",
+        "scroll",
+        "pointer",
+        "cursor",
+        "3d",
+        "shader",
+        "webgl",
+        "scrub"
+      ],
+      "minHits": 1,
+      "priority": 950,
+      "verdict": "no-runtime",
+      "headline": "This is a CSS transition. No runtime primitive belongs here.",
+      "because": "An element moving from one state to another on mount or on a class change is what CSS transitions and the Web Animations API were built for. Both run on the compositor, off the main thread, so they keep animating while JavaScript is busy — which is exactly when a frame-loop version starts stuttering. A per-frame implementation of a fade costs main-thread time to produce a worse result.",
+      "use": [],
+      "components": [],
+      "instead": "A CSS transition, a keyframe animation, or `element.animate()`. Wrap the state change in `startViewTransition()` when the element also moves between layouts.",
+      "watchFor": [
+        "no-reduced-motion"
+      ],
+      "notWhen": "The motion has to keep tracking something that changes continuously — the pointer, scroll position, a physics value. A transition runs from A to B on its own clock and cannot follow a moving target; that is when a frame subscription starts earning its cost."
+    },
+    {
+      "id": "css-hover",
+      "when": [
+        "hover",
+        "hover state",
+        "hover effect",
+        "mouse over",
+        "on hover"
+      ],
+      "allOf": [],
+      "unless": [
+        "magnetic",
+        "predict",
+        "prefetch",
+        "before the cursor",
+        "trail",
+        "follow the cursor",
+        "proximity",
+        "3d",
+        "shader",
+        "webgl",
+        "warm"
+      ],
+      "minHits": 1,
+      "priority": 940,
+      "verdict": "no-runtime",
+      "headline": "`:hover` already does this, and it does it while the thread is blocked.",
+      "because": "A colour, scale, shadow or opacity change on hover is a pseudo-class and a transition. There is no measurement to do and nothing to recompute per frame, so a JavaScript version adds a listener, a state write and a re-render to reproduce two lines of CSS.",
+      "use": [],
+      "components": [],
+      "instead": "`:hover` with a `transition` on the properties that change.",
+      "watchFor": [],
+      "notWhen": "You need to know the pointer is coming BEFORE it arrives — to prefetch a route, warm a video, or compile a shader. `:hover` fires on contact, which is already too late for work that takes time. That is `usePointerIntent`."
+    },
+    {
+      "id": "css-loading-state",
+      "when": [
+        "spinner",
+        "loading indicator",
+        "loading animation",
+        "skeleton",
+        "shimmer",
+        "progress bar"
+      ],
+      "allOf": [],
+      "unless": [
+        "scroll",
+        "3d",
+        "shader",
+        "webgl",
+        "reading progress",
+        "pointer"
+      ],
+      "minHits": 1,
+      "priority": 930,
+      "verdict": "no-runtime",
+      "headline": "A CSS keyframe animation, plus a reduced-motion guard.",
+      "because": "A spinner or shimmer repeats forever on a fixed clock with no input. That is the one case where `animation: … infinite` is exactly right, and it keeps spinning during the very main-thread work the spinner exists to cover — which a frame-loop version, by definition, would not.",
+      "use": [],
+      "components": [],
+      "instead": "`@keyframes` with `animation: spin 1s linear infinite`, inside a `@media (prefers-reduced-motion: no-preference)` block so the motion is opt-out by default.",
+      "watchFor": [
+        "no-reduced-motion"
+      ],
+      "notWhen": "The indicator reflects real progress that something else is measuring. Then it is driven by a value, not a clock, and `damp` is worth having so the bar eases toward each new reading instead of jumping."
+    },
+    {
+      "id": "reveal-on-scroll-once",
+      "when": [
+        "reveal on scroll",
+        "scroll reveal",
+        "animate on scroll",
+        "scroll into view"
+      ],
+      "allOf": [
+        [
+          "reveal",
+          "fade in",
+          "fade",
+          "appear",
+          "animate",
+          "slide in",
+          "slide up",
+          "show up"
+        ],
+        [
+          "scroll",
+          "into view",
+          "in view",
+          "viewport",
+          "visible",
+          "on screen",
+          "below the fold"
+        ]
+      ],
+      "unless": [
+        "parallax",
+        "scrub",
+        "3d",
+        "webgl",
+        "shader",
+        "smooth",
+        "progress",
+        "continuous",
+        "video"
+      ],
+      "minHits": 1,
+      "priority": 920,
+      "verdict": "no-runtime",
+      "headline": "One IntersectionObserver and one class. No frame loop, no scroll listener.",
+      "because": "A reveal fires once, at a threshold, and then never again. IntersectionObserver was added to the platform precisely so this would stop being a scroll handler: it is asynchronous, it does not force layout, and it costs nothing between crossings. Reading scroll position every frame to decide whether an element has crossed a line is the expensive way to ask a question the browser answers for free.",
+      "use": [],
+      "components": [],
+      "instead": "`new IntersectionObserver(([e]) => e.isIntersecting && el.classList.add('in-view'))`, with the animation itself in CSS. Disconnect after the first crossing if it should not repeat.",
+      "watchFor": [
+        "missing-cleanup",
+        "no-reduced-motion"
+      ],
+      "notWhen": "The motion is continuous across the scroll rather than triggered by it — a parallax offset, a scrubbed video, a progress value. Those need a position every frame, which is `useSensorBus` with `useTick`."
+    },
+    {
+      "id": "layout-and-route-transitions",
+      "when": [
+        "layout animation",
+        "shared element",
+        "page transition",
+        "route transition",
+        "reorder",
+        "list animation",
+        "view transition"
+      ],
+      "allOf": [],
+      "unless": [
+        "3d",
+        "shader",
+        "webgl",
+        "scroll",
+        "pointer"
+      ],
+      "minHits": 1,
+      "priority": 910,
+      "verdict": "no-runtime",
+      "headline": "View Transitions, or whatever layout engine your framework already ships.",
+      "because": "Animating between two layouts means knowing where every element was and where it landed. The browser knows both, and `startViewTransition()` hands you the crossfade without any measurement at all. Reimplementing FLIP over a frame loop means reading layout for every participating element, which is the single most expensive thing you can do per frame.",
+      "use": [],
+      "components": [],
+      "instead": "`document.startViewTransition()`, or your framework's layout animation (Framer Motion's `layout` prop, Next's view transitions).",
+      "watchFor": [
+        "lane-discipline"
+      ],
+      "notWhen": "The thing being transitioned is a WebGL scene. Contexts do not crossfade, and the answer there is a scene gate holding the old one alive until the new one has drawn a frame."
+    },
+    {
+      "id": "native-video-playback",
+      "when": [
+        "video player",
+        "video controls",
+        "play button",
+        "autoplay",
+        "background video"
+      ],
+      "allOf": [],
+      "unless": [
+        "scrub",
+        "scroll",
+        "timeline",
+        "frame by frame",
+        "scrollytelling",
+        "shader"
+      ],
+      "minHits": 1,
+      "priority": 900,
+      "verdict": "no-runtime",
+      "headline": "The `<video>` element. Nothing here improves on it.",
+      "because": "Playback, buffering, codec selection and picture-in-picture are the element's job, and it does them on a media thread you cannot reach from JavaScript. There is no per-frame work to coordinate, so there is nothing for a frame budget to govern.",
+      "use": [],
+      "components": [],
+      "instead": "`<video autoPlay muted loop playsInline />`, with `poster` for the first paint.",
+      "watchFor": [],
+      "notWhen": "The timeline is driven by something other than the clock — scroll position, a drag, a progress value. Seeking a video every frame needs seek discipline that the element does not provide, and that is `useVideoScrubber`."
+    },
+    {
+      "id": "gpu-resource-disposal",
+      "when": [
+        "dispose",
+        "texture leak",
+        "gpu memory",
+        "memory leak",
+        "out of memory",
+        "leaking textures"
+      ],
+      "allOf": [],
+      "unless": [],
+      "minHits": 1,
+      "priority": 890,
+      "verdict": "no-runtime",
+      "headline": "No primitive owns this. It is disposal discipline, and it has to be yours.",
+      "because": "Geometries, materials, textures and render targets hold GPU memory that garbage collection cannot reclaim — the JavaScript object is small and the allocation behind it is not. Nothing in this runtime allocates them, so nothing in it can free them. React Three Fiber disposes what it created declaratively; anything constructed by hand in an effect is yours to release.",
+      "use": [],
+      "components": [],
+      "instead": "Dispose every hand-constructed resource in the same effect's cleanup, and never dispose one created at module scope — that is shared across every instance on the page, and freeing it breaks the second copy rather than the first.",
+      "watchFor": [
+        "missing-cleanup"
+      ],
+      "notWhen": "The problem is not memory but frames. If the scene is janky rather than crashing, start with `useFramePressure` to find out what is actually eating the frame before optimising anything."
+    },
+    {
+      "id": "per-frame-work",
+      "when": [
+        "every frame",
+        "per frame",
+        "requestanimationframe",
+        "raf loop",
+        "animation loop",
+        "game loop",
+        "ticker",
+        "frame loop",
+        "custom effect"
+      ],
+      "allOf": [],
+      "unless": [],
+      "minHits": 1,
+      "priority": 480,
+      "verdict": "single",
+      "headline": "`useTick` — the shared frame loop, with the subscription lifecycle handled.",
+      "because": "Per-frame work is the thing this runtime exists to coordinate. One loop for the page means the scheduler can order reads before writes, measure what each subscriber costs, and shed decorative work when a frame runs long. A second loop is invisible to all three: it cannot be shed, it does not appear in devtools, and the pressure classifier bills its time to \"main-thread\" — so the page cannot even tell the cost is its own.",
+      "use": [
+        "useTick"
+      ],
+      "components": [],
+      "instead": "A `requestAnimationFrame` loop inside a `useEffect`, plus the cancel you have to remember.",
+      "watchFor": [
+        "orphan-raf",
+        "lane-discipline",
+        "setstate-per-frame"
+      ],
+      "notWhen": "The work is not actually per-frame. Something that recomputes on an event, on a timer, or once on mount belongs in a handler or an effect; a frame subscription for it runs sixty times a second to discover nothing changed."
+    },
+    {
+      "id": "pointer-and-scroll-telemetry",
+      "when": [
+        "pointer position",
+        "mouse position",
+        "cursor position",
+        "scroll position",
+        "scroll velocity",
+        "pointer velocity",
+        "viewport size",
+        "where is the cursor",
+        "follow the cursor",
+        "follow the mouse",
+        "track the cursor",
+        "track the mouse",
+        "chase the cursor"
+      ],
+      "allOf": [],
+      "unless": [
+        "trail",
+        "magnetic",
+        "parallax"
+      ],
+      "minHits": 1,
+      "priority": 470,
+      "verdict": "single",
+      "headline": "`useSensorBus` — one set of listeners for the page, read as plain fields.",
+      "because": "Pointer, scroll and viewport are read by almost every effect, and the naive version attaches a listener per consumer. Ten components tracking the pointer means ten `pointermove` handlers firing on one event. The bus attaches once, is reference-counted, and exposes live fields you read inside a frame callback — no subscription per reader, no allocation per frame.",
+      "use": [
+        "useSensorBus",
+        "useTick"
+      ],
+      "components": [],
+      "instead": "A `pointermove` or `scroll` listener per component, each with its own state and its own removal.",
+      "watchFor": [
+        "setstate-per-frame",
+        "missing-cleanup"
+      ],
+      "notWhen": "You need one value, once, on one event — a click coordinate, say. An ordinary handler is cheaper than retaining a page-wide sensor for a single reading."
+    },
+    {
+      "id": "smoothing-a-value",
+      "when": [
+        "smooth",
+        "damping",
+        "lerp",
+        "ease toward",
+        "inertia",
+        "spring",
+        "follow smoothly",
+        "easing"
+      ],
+      "allOf": [],
+      "unless": [],
+      "minHits": 1,
+      "priority": 460,
+      "verdict": "single",
+      "headline": "`damp` — frame-rate-independent smoothing, one line inside your frame callback.",
+      "because": "The usual `current += (target - current) * 0.1` is a lie about time: it moves ten percent per FRAME, so the same code is twice as fast on a 120Hz display and slows to a crawl when the page is busy. `damp` takes `dt` and converges at a rate per SECOND, which is why motion written with it feels identical everywhere.",
+      "use": [
+        "damp"
+      ],
+      "components": [],
+      "instead": "A hand-written lerp with a magic constant that behaves differently on every display.",
+      "watchFor": [],
+      "notWhen": "The value should arrive at a fixed time — a 300ms transition. Damping is asymptotic and never quite lands; use an eased transition when the duration is the requirement."
+    },
+    {
+      "id": "defer-an-expensive-mount",
+      "when": [
+        "defer mount",
+        "mount later",
+        "expensive component",
+        "heavy component",
+        "wait until idle",
+        "hydration",
+        "slow first load",
+        "mount when calm"
+      ],
+      "allOf": [],
+      "unless": [
+        "3d",
+        "webgl",
+        "shader",
+        "scroll",
+        "in view",
+        "below the fold"
+      ],
+      "minHits": 1,
+      "priority": 450,
+      "verdict": "single",
+      "headline": "`useSafeToMount({ cost })` — hold the mount until the thread can absorb it.",
+      "because": "An expensive component mounting during hydration lands its cost on the busiest moment of the page's life, which is also the moment a visitor is most likely to try to interact. The gate watches real frame headroom and opens once the page has some to spare. You describe how expensive the thing is and the thresholds follow from that.",
+      "use": [
+        "useSafeToMount"
+      ],
+      "components": [
+        "heart-stream",
+        "jigsaw-puzzle"
+      ],
+      "instead": "A `setTimeout` guess, or mounting immediately and hoping.",
+      "watchFor": [
+        "client-boundary"
+      ],
+      "notWhen": "The component is below the fold. Frame headroom alone will happily mount something nobody can see — `useSceneGate` adds viewport proximity, a quality verdict and context recovery on top."
+    },
+    {
+      "id": "device-capability-tier",
+      "when": [
+        "device tier",
+        "low end device",
+        "weak device",
+        "capability",
+        "quality setting",
+        "detect gpu",
+        "how powerful",
+        "adapt quality"
+      ],
+      "allOf": [],
+      "unless": [
+        "scene",
+        "canvas",
+        "r3f",
+        "react three fiber"
+      ],
+      "minHits": 1,
+      "priority": 440,
+      "verdict": "single",
+      "headline": "`useAdaptiveQuality` — one tier, fused from hardware, live frames and the motion preference.",
+      "because": "Hardware probing alone dates instantly and reads badly on the devices that matter; frame measurement alone cannot tell you anything before the first frame. The hook fuses both, plus `prefers-reduced-motion`, and tells you WHY it landed where it did — so a scene can explain itself instead of silently rendering at a third of its detail.",
+      "use": [
+        "useAdaptiveQuality"
+      ],
+      "components": [],
+      "instead": "Sniffing the user agent, or branching on `navigator.hardwareConcurrency` alone.",
+      "watchFor": [
+        "no-reduced-motion"
+      ],
+      "notWhen": "You are picking renderer settings for a `<Canvas>`. Then the tier is an input to `useSceneGate`, which already consumes it, and `useRenderQuality` turns the verdict into props."
+    },
+    {
+      "id": "is-the-page-struggling",
+      "when": [
+        "frame budget",
+        "dropping frames",
+        "degrade gracefully",
+        "is the page struggling",
+        "under load"
+      ],
+      "allOf": [],
+      "unless": [],
+      "minHits": 1,
+      "priority": 430,
+      "verdict": "single",
+      "headline": "`useAnimationBudget` — the live health of the frame, as a tier you can branch on.",
+      "because": "It reports what the page is actually managing right now, measured against the display's real refresh interval rather than an assumed sixty. That distinction matters: a 120Hz panel has half the frame to work with, and a threshold expressed in milliseconds means something different on each.",
+      "use": [
+        "useAnimationBudget"
+      ],
+      "components": [],
+      "instead": "Timing frames by hand and picking a threshold that is wrong on half of all displays.",
+      "watchFor": [],
+      "notWhen": "You want to know what is CAUSING the trouble rather than that there is trouble. The budget says the frame is full; `useFramePressure` says what filled it."
+    },
+    {
+      "id": "diagnose-jank",
+      "when": [
+        "why is it janky",
+        "what is slow",
+        "diagnose",
+        "debug performance",
+        "profile",
+        "stutter",
+        "find the bottleneck",
+        "what is eating the frame"
+      ],
+      "allOf": [],
+      "unless": [],
+      "minHits": 1,
+      "priority": 420,
+      "verdict": "composition",
+      "headline": "`useFramePressure` to name the culprit, then `mountDevtools` to name the subscriber.",
+      "because": "They answer different questions and the order matters. The pressure classifier splits the frame into this runtime's own subscribers, other main-thread work, and an unattributed remainder — which tells you whether the problem is even yours. Only if it is does the devtools overlay help, and then it names the exact subscriber and what it costs.",
+      "use": [
+        "useFramePressure",
+        "mountDevtools"
+      ],
+      "components": [],
+      "instead": "Commenting things out until it gets faster.",
+      "watchFor": [],
+      "notWhen": "Nothing is subscribed yet. Neither can see a private `requestAnimationFrame` loop as anything but anonymous main-thread time, so move the work onto the conductor first and the attribution arrives with it."
+    },
+    {
+      "id": "prefetch-on-approach",
+      "when": [
+        "prefetch",
+        "preload on hover",
+        "predict",
+        "before the cursor arrives",
+        "warm",
+        "anticipate",
+        "intent"
+      ],
+      "allOf": [],
+      "unless": [
+        "magnetic"
+      ],
+      "minHits": 1,
+      "priority": 410,
+      "verdict": "single",
+      "headline": "`usePointerIntent` — fires while the pointer is still on its way.",
+      "because": "Hover fires on contact, which is already too late for anything that takes time: a route fetch, a video decode, a shader compile. Casting the pointer's velocity forward buys the hundred or so milliseconds that turn a visible wait into an instant response.",
+      "use": [
+        "usePointerIntent"
+      ],
+      "pattern": "magnetic-prefetch-cta",
+      "components": [
+        "video-card"
+      ],
+      "instead": "An `onMouseEnter` handler that starts the work a visitor is already waiting on.",
+      "watchFor": [
+        "setstate-per-frame"
+      ],
+      "notWhen": "The device has no pointer. On touch there is no approach to predict, so treat the prediction as an optimisation and make sure the ordinary path still works without it."
+    },
+    {
+      "id": "magnetic-attraction",
+      "when": [
+        "magnetic",
+        "attract the cursor",
+        "pulls toward",
+        "snap to cursor",
+        "sticky button"
+      ],
+      "allOf": [],
+      "unless": [],
+      "minHits": 1,
+      "priority": 400,
+      "verdict": "single",
+      "headline": "`useMagneticIntent` — it owns the element's transform, which is the thing to know.",
+      "because": "The effect is proximity plus prediction plus damping, and the hook composes the same pointer intent engine rather than duplicating the maths. The contract that matters is ownership: it writes `transform` every frame, so anything else animating the transform of the same element is a fight the frame loop wins.",
+      "use": [
+        "useMagneticIntent"
+      ],
+      "pattern": "magnetic-prefetch-cta",
+      "components": [
+        "physics-buttons"
+      ],
+      "instead": "A `mousemove` handler doing trigonometry and writing inline styles per event.",
+      "watchFor": [
+        "transform-conflict"
+      ],
+      "notWhen": "The element also needs a CSS transform for layout or a hover scale. Give the hook its own node and put the other transform on a wrapper or a child."
+    },
+    {
+      "id": "scrub-a-video",
+      "when": [
+        "scrub",
+        "scroll video",
+        "video timeline",
+        "frame by frame",
+        "scroll through video"
+      ],
+      "allOf": [
+        [
+          "scroll",
+          "scrub",
+          "drag",
+          "timeline",
+          "progress"
+        ],
+        [
+          "video",
+          "footage",
+          "clip",
+          "playback",
+          "currenttime"
+        ]
+      ],
+      "unless": [],
+      "minHits": 1,
+      "priority": 390,
+      "verdict": "single",
+      "headline": "`useVideoScrubber` — seeking a video from a driver, with the seek discipline built in.",
+      "because": "Naive scrubbing issues a seek per frame and the decoder falls behind, which reads as the video freezing and then jumping. The scrubber coalesces seeks against the decoder's actual readiness, and it restores `muted`, `playsInline` and `preload` on teardown because it had to overwrite them to work at all.",
+      "use": [
+        "useVideoScrubber"
+      ],
+      "pattern": "scrollytelling-video",
+      "components": [
+        "playpause"
+      ],
+      "instead": "Assigning `video.currentTime` inside a scroll handler.",
+      "watchFor": [
+        "setstate-per-frame",
+        "missing-cleanup"
+      ],
+      "notWhen": "You want ordinary playback. Nothing here improves on the `<video>` element's own clock."
+    },
+    {
+      "id": "animated-number",
+      "when": [
+        "count up",
+        "counter",
+        "animated number",
+        "odometer",
+        "rolling number",
+        "animate a stat"
+      ],
+      "allOf": [],
+      "unless": [],
+      "minHits": 1,
+      "priority": 380,
+      "verdict": "single",
+      "headline": "`useNumberTicker` — writes the text node directly, so React never re-renders for it.",
+      "because": "The obvious version puts the number in state and re-renders the component sixty times a second to change a string. The hook writes to the DOM node through a ref instead, formats with `Intl.NumberFormat`, and chases whatever value you hand it rather than running a fixed animation — so a number that changes mid-flight redirects rather than restarting.",
+      "use": [
+        "useNumberTicker"
+      ],
+      "pattern": "dashboard-live-numbers",
+      "components": [],
+      "instead": "A `setInterval` stepping a state value toward a target.",
+      "watchFor": [
+        "setstate-per-frame"
+      ],
+      "notWhen": "The number is not worth animating. A value that changes once on load reads as noise when it rolls, and every rolled digit is a re-layout of everything beside it unless the font is tabular."
+    },
+    {
+      "id": "cursor-image-trail",
+      "when": [
+        "image trail",
+        "trailing images",
+        "cursor trail",
+        "images follow the cursor"
+      ],
+      "allOf": [],
+      "unless": [],
+      "minHits": 1,
+      "priority": 370,
+      "verdict": "single",
+      "headline": "`useImageTrail` — a fixed pool of nodes, recycled.",
+      "because": "The naive version appends an element per pointer move and removes it on a timer, which means unbounded DOM growth exactly while the visitor is moving fastest. A recycled pool has a known ceiling and never allocates during the effect.",
+      "use": [
+        "useImageTrail"
+      ],
+      "components": [
+        "trail-collector",
+        "text-trail"
+      ],
+      "instead": "Appending and removing nodes per pointer event.",
+      "watchFor": [
+        "no-reduced-motion"
+      ],
+      "notWhen": "The page is content-first. This is ambient decoration over an image field; on a text page it costs frames a reader will notice and gives nothing back."
+    },
+    {
+      "id": "protect-an-interactive-region",
+      "when": [
+        "keep this smooth",
+        "prioritise",
+        "prioritize",
+        "interactive region",
+        "protect the interaction"
+      ],
+      "allOf": [
+        [
+          "drag",
+          "resize",
+          "scrub",
+          "editor",
+          "canvas",
+          "panel",
+          "region",
+          "section",
+          "interact",
+          "manipulat"
+        ],
+        [
+          "smooth",
+          "stutter",
+          "responsive",
+          "priority",
+          "never drop",
+          "jank",
+          "lag",
+          "must not",
+          "keep up"
+        ]
+      ],
+      "unless": [],
+      "minHits": 1,
+      "priority": 425,
+      "verdict": "single",
+      "headline": "`useInteractionScope` — the region a visitor is using keeps its frames; ambient work yields.",
+      "because": "Priority alone is page-wide, so a decorative background and a decorative flourish inside the thing being dragged are treated identically. A scope adds the missing axis: while the region holds the foreground lease, subscribers belonging elsewhere are tested against a stricter shedding threshold. Anything rendered inside joins automatically.",
+      "use": [
+        "useInteractionScope",
+        "useTick"
+      ],
+      "components": [],
+      "instead": "Pausing every other animation by hand when a drag starts, and forgetting to resume one.",
+      "watchFor": [
+        "lane-discipline"
+      ],
+      "notWhen": "There is only one interactive region on the page. With nothing to yield, the scope is bookkeeping that changes no decision."
+    },
+    {
+      "id": "r3f-scene",
+      "when": [
+        "react three fiber",
+        "r3f",
+        "three.js",
+        "threejs",
+        "3d scene",
+        "webgl scene",
+        "3d model",
+        "gltf",
+        "canvas 3d"
+      ],
+      "allOf": [],
+      "unless": [
+        "shader",
+        "glsl",
+        "uniform"
+      ],
+      "minHits": 1,
+      "priority": 760,
+      "verdict": "composition",
+      "headline": "`useSceneGate` decides, `useRenderQuality` applies, your component owns the detail.",
+      "because": "A `<Canvas>` mounted plainly renders whether or not anyone is looking at it, at whatever pixel ratio the display reports, on every device, forever — and goes permanently black the first time the browser reclaims its context. The three-part split fixes each of those in the one place it can be fixed. The gate holds the mount until the scene is near the viewport, scrolling has settled and there is frame headroom, and it hands back a `generation` to key on. The adapter turns its verdict into `<Canvas>` props, including the `onCreated` that notices a lost context. Instance counts and geometry detail are not renderer settings, so they stay in your component, keyed off the gate's `quality`.",
+      "use": [
+        "useSceneGate",
+        "useRenderQuality"
+      ],
+      "pattern": "lazy-3d-section",
+      "components": [
+        "volumetric-light",
+        "refractive-gallery"
+      ],
+      "instead": "A `<Canvas>` rendered directly, with a dynamic import and no gate — which defers the bundle and nothing else.",
+      "watchFor": [
+        "canvas-prop-override",
+        "webgl-context-loss",
+        "hand-rolled-scene-gate",
+        "ssr-module-scope"
+      ],
+      "notWhen": "The scene is above the fold, always visible, and runs at one quality on every device. Then the gate has no decision to make, and ordinary `<Canvas>` props are honest. Attach a `webglcontextlost` listener even so."
+    },
+    {
+      "id": "shader-uniforms-per-frame",
+      "when": [
+        "shader",
+        "glsl",
+        "uniform",
+        "fragment shader",
+        "vertex shader",
+        "shadermaterial",
+        "raymarch",
+        "noise shader"
+      ],
+      "allOf": [],
+      "unless": [],
+      "minHits": 1,
+      "priority": 750,
+      "verdict": "composition",
+      "headline": "Write uniforms from a `useTick` callback through a ref. Never through React state.",
+      "because": "A uniform is a value on a GPU program, not application state. Putting it in `useState` means a React render, a reconciliation pass and a commit for every frame of a smooth animation — to change one float that React never reads. Hold the material in a ref and assign `material.uniforms.uTime.value` inside the callback; React is then uninvolved in the animation entirely, which is the point.\n\nTwo details that decide whether the scene is smooth. Use the `time` the conductor passes rather than `performance.now()`, so every effect on the page shares one clock and nothing drifts apart. And take shader compilation seriously: it is a synchronous multi-hundred-millisecond stall on some drivers, which is why the mount belongs behind a gate rather than in the hydration burst.",
+      "use": [
+        "useTick",
+        "useSceneGate"
+      ],
+      "pattern": "custom-frame-effect",
+      "components": [
+        "media-shader",
+        "acrylic-shader"
+      ],
+      "instead": "A `useFrame` writing to state, or a private `requestAnimationFrame` incrementing a time uniform.",
+      "watchFor": [
+        "setstate-per-frame",
+        "orphan-raf",
+        "lane-discipline"
+      ],
+      "notWhen": "The uniform changes on an event rather than per frame — a colour from a picker, a mode from a toggle. Assign it in the handler; a frame subscription to copy an unchanged value is sixty wasted assignments a second."
+    },
+    {
+      "id": "particles-and-instancing",
+      "when": [
+        "particle",
+        "particles",
+        "instanced",
+        "instancing",
+        "instancedmesh",
+        "point cloud",
+        "gpgpu",
+        "thousands of"
+      ],
+      "allOf": [],
+      "unless": [],
+      "minHits": 1,
+      "priority": 740,
+      "verdict": "composition",
+      "headline": "One instanced draw, and the count comes from the gate's `quality`.",
+      "because": "Particle counts are the largest single lever on whether a scene holds its frame, and they are the one thing the render adapter deliberately does not own — a count is not a renderer setting, so putting it in a `RenderProfile` would be an option that looks applied and is not. Read `scene.quality` in your component and pick the count from it.\n\nThe other half is the draw itself: one `InstancedMesh` with a per-instance matrix, not a mesh per particle. A thousand meshes is a thousand draw calls, and no amount of frame scheduling rescues that. Update the instance matrices in a `useTick` callback and set `needsUpdate` once at the end, never per instance.",
+      "use": [
+        "useSceneGate",
+        "useTick"
+      ],
+      "pattern": "lazy-3d-section",
+      "components": [
+        "particle-morph-gallery",
+        "magnetic-sand",
+        "wind-scatter"
+      ],
+      "instead": "A fixed particle count chosen on the machine it was authored on.",
+      "watchFor": [
+        "canvas-prop-override",
+        "setstate-per-frame"
+      ],
+      "notWhen": "The count is small enough that the cost is elsewhere. Below a few hundred instances the draw is not the bottleneck, and `useFramePressure` will tell you what is before you tune anything."
+    },
+    {
+      "id": "postprocessing",
+      "when": [
+        "postprocessing",
+        "post processing",
+        "effectcomposer",
+        "bloom",
+        "depth of field",
+        "ssao",
+        "render pass"
+      ],
+      "allOf": [],
+      "unless": [],
+      "minHits": 1,
+      "priority": 730,
+      "verdict": "composition",
+      "headline": "Gate the passes on `quality`, and lower the pixel ratio before you drop an effect.",
+      "because": "Every pass is another full-screen draw at the current resolution, so post-processing multiplies whatever the pixel ratio costs. That ordering is the useful part: going from a device pixel ratio of 3 to 1.5 quarters the pixels shaded and usually reads as softer, while removing bloom changes what the scene IS. Let the adapter lower the ratio first and drop passes only at the bottom.\n\nPasses are not renderer settings either, so they do not belong in a `RenderProfile`. Compose them in your scene from the gate's `quality`, the same way instance counts are chosen.",
+      "use": [
+        "useSceneGate",
+        "useRenderQuality"
+      ],
+      "pattern": "lazy-3d-section",
+      "components": [],
+      "instead": "A fixed composer stack that ships every pass to every device.",
+      "watchFor": [
+        "canvas-prop-override",
+        "webgl-context-loss"
+      ],
+      "notWhen": "The effect is achievable in CSS over the canvas — a vignette, a colour grade, a blur on a static overlay. A CSS filter on a sibling element costs no render passes at all."
+    },
+    {
+      "id": "webgl-hero",
+      "when": [
+        "shader hero",
+        "webgl hero",
+        "3d hero",
+        "hero background"
+      ],
+      "allOf": [
+        [
+          "hero",
+          "landing",
+          "above the fold",
+          "banner",
+          "masthead",
+          "splash"
+        ],
+        [
+          "shader",
+          "glsl",
+          "webgl",
+          "3d",
+          "three.js",
+          "threejs",
+          "canvas",
+          "video loop",
+          "particle"
+        ]
+      ],
+      "unless": [],
+      "minHits": 1,
+      "priority": 780,
+      "verdict": "composition",
+      "headline": "Three renditions behind one layout box: shader, video loop, still.",
+      "because": "A hero is the first thing rendered and the worst possible place for an unconditional WebGL mount — it competes with hydration on the slowest devices, and the visitors who suffer most are the ones deciding whether to stay. The rendition ladder gives every device something that looks deliberate. The device floor picks WHICH rendition; frame headroom decides WHEN the expensive one starts; `prefers-reduced-motion` overrides both and gets the still, because a capable machine can still be asking for less motion.",
+      "use": [
+        "useAdaptiveQuality",
+        "useSafeToMount"
+      ],
+      "pattern": "adaptive-shader-hero",
+      "components": [
+        "volumetric-light",
+        "media-shader"
+      ],
+      "instead": "One shader for everyone, dynamically imported, mounted as soon as the bundle lands.",
+      "watchFor": [
+        "ssr-module-scope",
+        "no-reduced-motion"
+      ],
+      "notWhen": "The hero is below the fold on most viewports, in which case it is an ordinary lazy scene and `useSceneGate` is the better gate — it adds viewport proximity, which the hero ladder does not need and a lower section does."
+    },
+    {
+      "id": "lost-context",
+      "when": [
+        "context lost",
+        "webglcontextlost",
+        "canvas goes black",
+        "canvas is black",
+        "context restore"
+      ],
+      "allOf": [],
+      "unless": [],
+      "minHits": 1,
+      "priority": 710,
+      "verdict": "single",
+      "headline": "`getRendererHealth()` and a generation on the canvas key. Rebuild, do not revive.",
+      "because": "The browser can take a context away at any moment — a driver reset, a backgrounded tab, too many live contexts on one page — and React Three Fiber has no handler for it, so the result is a permanently black rectangle and a completely clean console. Recovery works by rebuilding rather than restoring: the restore path is unreliable across drivers, and some refuse a replacement context on the page entirely if the loss event was not cancelled. So call `preventDefault()` on the loss, report it, and let a moving key throw the dead tree away and build a working one from the same declarative description.",
+      "use": [
+        "RendererHealth",
+        "useRenderQuality"
+      ],
+      "pattern": "lazy-3d-section",
+      "components": [],
+      "instead": "Nothing, which is what React Three Fiber does by default.",
+      "watchFor": [
+        "webgl-context-loss"
+      ],
+      "notWhen": "You already spread `useRenderQuality`'s props onto the canvas. Its `onCreated` attaches the listener and reports for you, and a second listener moves the generation twice per loss."
+    }
   ]
 }