vectorvesper 2.7.0 → 2.8.1

package/dist/hooks.json

@@ -1,7 +1,7 @@
 {
   "version": "1.0.0",
-  "engineVersion": "4.0.1",
-  "generatedAt": "2026-09-09T11:54:49.193Z",
+  "engineVersion": "4.2.0",
+  "generatedAt": "2026-09-24T15:22:31.361Z",
   "contractLevel": "full",
   "hooks": [
     {
@@ -608,16 +608,18 @@
         "context restored",
         "canvas recovery",
         "generation counter",
-        "black canvas"
+        "black canvas",
+        "reportHealthy",
+        "builtAt"
       ],
       "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)",
+      "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. Wired by hand it is three calls, and all three are required: preventDefault on the event, reportLost with the generation the renderer was built under, and reportHealthy once the replacement has drawn.",
+      "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\nOne driver reset reaches every canvas on the page within a frame or two, so losses arriving within a quarter of a second of the last one are folded into it: sixteen canvases, one reset, one rebuild. The exception is a canvas the last rebuild itself built, which did not exist when the reset happened. A reporter that passes builtAt, the generation that was current when its renderer was made, is always counted when that equals the current generation, so a replacement lost moments after it was built gets a rebuild of its own instead of staying black. So that a page holding more canvases than the browser keeps contexts for cannot loop, fresh canvases may trigger at most three such rebuilds in a row, after which the runtime warns once and waits for the next separate loss.\n\nreportHealthy is what ends a recovery. While a loss is unresolved every scene gate on the page holds its scene in the recovering state at reduced quality. If nothing reports healthy within five seconds the runtime assumes the rebuild worked, clears the state, and warns once, naming the call to add.\n\nOn the r3f entry, useRenderQuality attaches that listener and reports for you, and on the three entry useThreeScene does the same for a plain three.js scene, so most consumers never touch this and only read the scene gate's generation.",
+      "signature": "getRendererHealth(): RendererHealth  ·  .state: RendererHealthState  ·  .reportLost(options?: { builtAt?: number })  ·  .reportHealthy()  ·  .subscribe(fn)",
       "options": [],
       "returns": [
         {
@@ -628,17 +630,17 @@
         {
           "name": "state.generation",
           "type": "number",
-          "description": "Increments on each loss. Put it on the canvas key."
+          "description": "Increments on each loss. Put it on the canvas key, and read it when you create a renderer so you can pass it back as `builtAt`."
         },
         {
           "name": "reportLost",
-          "type": "() => void",
-          "description": "Call after preventDefault on a webglcontextlost event."
+          "type": "(options?: { builtAt?: number }) => void",
+          "description": "Call after preventDefault on a webglcontextlost event. Pass `builtAt`, the generation that was current when the lost renderer was made: a replacement that dies moments after it was built then counts as a new loss instead of being folded into the last one."
         },
         {
           "name": "reportHealthy",
           "type": "() => void",
-          "description": "Call once a working context exists, which is what ends the recovery state."
+          "description": "Required. Call once the replacement renderer has drawn. Until then every scene gate on the page holds its scene in recovery at reduced quality; after five seconds with no call the runtime gives up waiting and warns."
         },
         {
           "name": "subscribe",
@@ -663,32 +665,39 @@
         "conflictsWith": [],
         "pairsWith": [
           "useSceneGate",
-          "useRenderQuality"
+          "useRenderQuality",
+          "useThreeScene"
         ]
       },
-      "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}",
+      "quickStart": "import { getRendererHealth } from \"@vectorvesper/motion\";\n\n// Call right after creating a renderer. Call the returned function before you\n// release the context, or your own teardown is reported as a GPU failure.\nexport function watchContext(canvas: HTMLCanvasElement) {\n  const health = getRendererHealth();\n  // The generation this renderer belongs to.\n  const builtAt = health.state.generation;\n  const onLost = (event: 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    health.reportLost({ builtAt });\n  };\n  canvas.addEventListener(\"webglcontextlost\", onLost);\n  return () => canvas.removeEventListener(\"webglcontextlost\", onLost);\n}\n\n// And once the replacement renderer has drawn its first frame:\n//   getRendererHealth().reportHealthy();",
       "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});"
+          "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  // After its first frame has drawn:\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."
+        "Read `state.generation` when you create a renderer and pass it to reportLost as `builtAt`.",
+        "Call reportHealthy once the replacement has drawn. It is what ends the recovery; skipping it holds every gated scene at reduced quality.",
+        "Use the generation as a key rather than trying to revive the context that died."
       ],
       "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."
+        "Don't attach your own listener to an r3f canvas that already spreads useRenderQuality's props, or around a useThreeScene scene. Both attach one, and two reports move the generation twice.",
+        "Don't release a context with forceContextLoss while your listener is still attached. Remove it first, or the teardown reads as a GPU failure and rebuilds every other scene."
       ],
       "whenNotToUse": [
         {
           "when": "You are rendering with React Three Fiber.",
           "instead": "useRenderQuality, whose onCreated attaches the listener and reports for you."
         },
+        {
+          "when": "You are rendering a plain three.js scene.",
+          "instead": "useThreeScene, which wires the loss, the rebuild and the healthy report around your scene."
+        },
         {
           "when": "You are not rendering with WebGL.",
           "instead": "Nothing. A 2D canvas has no context to lose this way."
@@ -1054,9 +1063,16 @@
         "quality tier",
         "low end device",
         "gpu detection",
-        "progressive enhancement"
-      ],
-      "tagline": "Device capability fused with live frame health — the complete quality signal.",
+        "progressive enhancement",
+        "reduced motion",
+        "prefers-reduced-motion",
+        "prefers reduced motion",
+        "usePrefersReducedMotion",
+        "useReducedMotion",
+        "reduced motion media query",
+        "motion preference"
+      ],
+      "tagline": "Device capability, live frame health and the reduced-motion preference, fused into one 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, 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.",
@@ -1152,8 +1168,8 @@
           "instead": "Skip it. The device probe creates a throwaway WebGL2 context to read the renderer string, which is not worth paying for on a page of text and CSS transitions."
         },
         {
-          "when": "You only need to respect prefers-reduced-motion.",
-          "instead": "Use `matchMedia(\"(prefers-reduced-motion: reduce)\")` directly."
+          "when": "You only need the reduced-motion preference, on a page with no canvas or heavy effects.",
+          "instead": "`matchMedia(\"(prefers-reduced-motion: reduce)\")`, read through `useSyncExternalStore` rather than `setState` in an effect. On a page already running effects on this runtime, read this hook's `reducedMotion` instead: the preference arrives with everything else, and freezing an effect under it is one branch."
         },
         {
           "when": "You want to react to load only, ignoring the device.",
@@ -2177,7 +2193,7 @@
           "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`."
+          "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`. `dpr` is a ceiling: it never goes above the screen's own ratio, so `dpr: 2` draws a 1x monitor at 1x and a 3x phone at 2."
         }
       ],
       "returns": [
@@ -2365,8 +2381,8 @@
       ],
       "whenNotToUse": [
         {
-          "when": "The component is below the fold or off-screen.",
-          "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": "The component is below the fold, or mounts when it scrolls into view.",
+          "instead": "Use `useSceneGate`, with `content: true` when it is content rather than decoration. It adds viewport proximity and a wait for the scroll to settle. This hook watches spare frame time only, and a smooth scroll has plenty of it, because the compositor does the scrolling while the main thread idles, so it opens mid-scroll. ANDed with an IntersectionObserver it is worse: it latches true while the page sits at the top, and the mount then lands on the very frame the observer fires."
         },
         {
           "when": "You want to keep tuning a scene that is already running.",
@@ -2405,12 +2421,16 @@
         "mount 3d scene",
         "pause offscreen",
         "context lost",
-        "canvas recovery"
+        "canvas recovery",
+        "wait for scroll to stop",
+        "mount after scroll settles",
+        "defer mount below the fold",
+        "heavy chart"
       ],
-      "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.",
+      "tagline": "One policy for a heavy scene or section: when to mount, whether to draw, at what quality, and how to recover.",
       "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.",
+      "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, `useThreeScene` on the three entry, or your own code. It is not only for 3D: `mounted` waits for the element to be near, for the scroll to settle and for frame headroom, which is what any expensive section below the fold needs. Pass `content: true` when what it holds is content, so it is never withheld.",
+      "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\nReduced motion and a device below the floor send a scene straight to the poster state, before position or timing are even considered, because there is no point warming a scene that will never be allowed to run. The content option removes exactly that step: the section still waits to be near, settled and affordable, and then mounts in the constrained state rather than never.\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": [
         {
@@ -2433,6 +2453,13 @@
           "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."
+        },
+        {
+          "name": "content",
+          "type": "boolean",
+          "default": "false",
+          "required": false,
+          "description": "What is behind the gate is content the visitor came for — a chart, a table — rather than decoration. It still waits to be near, for the scroll to settle and for headroom, but it is never withheld: without this, reduced motion and a device below the floor keep `mounted` false for good."
         }
       ],
       "returns": [
@@ -2493,6 +2520,7 @@
         "conflictsWith": [],
         "pairsWith": [
           "useRenderQuality",
+          "useThreeScene",
           "useSafeToMount",
           "useAdaptiveQuality"
         ]
@@ -2502,7 +2530,12 @@
         {
           "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}"
+          "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  // dpr is a ceiling: never above the screen's own ratio.\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": "A heavy chart below the fold",
+          "blurb": "Not only for 3D. The chart mounts once it is near, the scroll has settled and the frame has room, and `content: true` keeps reduced motion and a weak device from withholding it.",
+          "code": "\"use client\";\nimport { useSceneGate } from \"@vectorvesper/motion/react\";\n\nexport function Metrics() {\n  const { ref, mounted } = useSceneGate<HTMLElement>({\n    label: \"metrics\",\n    cost: \"normal\",\n    content: true,\n  });\n\n  return (\n    <section ref={ref}>\n      {mounted ? <RevenueChart /> : <div style={{ height: 320 }} />}\n    </section>\n  );\n}"
         },
         {
           "name": "Reacting to the reason",
@@ -2511,7 +2544,7 @@
         },
         {
           "name": "A plain canvas, no r3f",
-          "blurb": "The gate knows nothing about three. Stop your own loop when it says idle.",
+          "blurb": "The gate knows nothing about three. Stop your own loop when it says idle. A three.js scene has a hook of its own, `useThreeScene`, that does all of this for you.",
           "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}"
         }
       ],
@@ -2520,13 +2553,14 @@
         "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."
+        "Give the trailing section more height than `preload`, or the scene never gets far enough away to idle.",
+        "Pass `content: true` for a chart, a table or anything else a reader came for."
       ],
       "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."
+        "Don't gate content the visitor came for without `content: true`. Reduced motion and a weak device otherwise keep it unmounted for the whole visit."
       ],
       "whenNotToUse": [
         {
@@ -2540,6 +2574,10 @@
         {
           "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."
+        },
+        {
+          "when": "The scene is plain three.js.",
+          "instead": "`useThreeScene`, which composes this gate and also owns the renderer's pixel ratio, loop, context recovery and disposal."
         }
       ],
       "guardrails": [
@@ -2663,6 +2701,192 @@
         "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": "useThreeScene",
+      "importFrom": "@vectorvesper/motion/three",
+      "packageName": "@vectorvesper/motion",
+      "since": "4.2.0",
+      "category": "gate",
+      "tier": "free",
+      "aliases": [
+        "three.js",
+        "threejs",
+        "plain three.js",
+        "vanilla three.js",
+        "three scene",
+        "three hero",
+        "three.js hero",
+        "webglrenderer",
+        "webgpurenderer",
+        "three.js production",
+        "three.js context lost",
+        "three.js dispose"
+      ],
+      "tagline": "A plain three.js scene in one call: you build the scene, it does the rest.",
+      "problem": "A hand-written three.js hero needs about ten things right besides the scene itself — when to build, when to draw, the pixel ratio, resizing, a lost context, disposal, reduced motion — and generated code gets about half of them.",
+      "summary": "You make the renderer and build the scene; the hook does everything around it. It builds nothing until the element is near the viewport and the page can afford it, draws on the shared frame loop and only while on screen, keeps the pixel ratio at or below the screen's own, follows the element's size, rebuilds after a lost context, frees every GPU resource when the scene goes, and never builds under reduced motion or on a device below the floor.",
+      "mechanism": "It composes the scene gate rather than reimplementing it, so a scene is built only once the gate says the element is near, the page has frame headroom and scrolling has settled, and never under reduced motion or on a device below the floor. Once built, a scene is kept while it is off screen: the gate reports idle, drawing stops, and the renderer, its context and every buffer stay as they are, so coming back costs nothing.\n\nEach build is one renderer on one graphics context. The hook calls your renderer factory, puts its canvas inside the element, sizes it, and attaches the context-loss listener in the same task, so no loss can land before something is listening. Then it calls setup and subscribes one callback to the conductor's render lane. That callback skips the frame while the gate says idle or the context is dead. Otherwise it applies the pixel ratio for the current quality, calls update, draws, and after the first successful draw reports the context healthy, which is what ends a recovery.\n\nThe pixel ratio is the smaller of the screen's own ratio and the cap for the current quality, two at full and one at reduced unless you set others, and it changes on the renderer that already exists: a quality change never rebuilds anything. Size changes are measured by a ResizeObserver and applied at the next drawn frame rather than at once, because resizing clears the canvas and a scene that is off screen would otherwise sit cleared until it drew again. A perspective camera's aspect is kept in step, and resize is called whenever the drawing buffer changes size.\n\nA lost context moves the page's generation, and the hook tears the build down and makes a new one: a new renderer, a new canvas and a fresh call to setup, because nothing made on a dead context works on its replacement. The loss is reported with the generation the renderer was built under, so a replacement that dies moments after it was built still counts as a new failure. The clock handed to update carries on across the rebuild. A WebGPU renderer is waited for until its init resolves, and its device is watched through the same generation counter.\n\nTeardown runs in reverse: the frame subscription stops, the resize observer disconnects, your dispose runs, then every geometry, material and texture reachable from the scene is freed, the loss listener comes off, the renderer is disposed, its context is handed back with forceContextLoss, and the canvas leaves the page. The listener comes off before the context is released, so the hook never hears its own teardown as a failure.",
+      "signature": "useThreeScene<R extends ThreeRendererLike>(options: UseThreeSceneOptions<R>): ThreeScene",
+      "options": [
+        {
+          "name": "renderer",
+          "type": "() => R | Promise<R>",
+          "default": "(required)",
+          "required": true,
+          "description": "Makes the renderer: `() => new THREE.WebGLRenderer({ antialias: true })`. Called each time the scene is built — when it first comes near the viewport, and again after a lost context — so it must return a new renderer every call. A WebGPURenderer works the same way. May return a promise, so three can be imported only when the scene is needed."
+        },
+        {
+          "name": "setup",
+          "type": "(context: { renderer: R; width: number; height: number; quality: \"full\" | \"reduced\" }) => ThreeSceneHandle | Promise<ThreeSceneHandle>",
+          "default": "(required)",
+          "required": true,
+          "description": "Builds the scene: camera, meshes, materials, lights, textures. Called right after `renderer`, every time the scene is built, with the element's size in CSS pixels. Return `{ scene, camera }`, plus any of `update(frame)` to animate before each drawn frame, `render(frame)` to draw it yourself (an EffectComposer), `resize(width, height)` when the drawing buffer changes size, and `dispose()` for anything not in the scene graph. Make every three.js object in here, not outside it."
+        },
+        {
+          "name": "label",
+          "type": "string",
+          "default": "undefined",
+          "required": false,
+          "description": "Shown in devtools and in warnings. No effect on behaviour."
+        },
+        {
+          "name": "cost",
+          "type": "\"light\" | \"normal\" | \"heavy\"",
+          "default": "\"heavy\"",
+          "required": false,
+          "description": "How expensive the scene is to start, passed to the scene gate. A full-screen hero is heavy; a small product turntable is normal."
+        },
+        {
+          "name": "preload",
+          "type": "number",
+          "default": "200",
+          "required": false,
+          "description": "How far before the viewport to start building, in pixels."
+        },
+        {
+          "name": "maxDpr",
+          "type": "{ full?: number; reduced?: number }",
+          "default": "{ full: 2, reduced: 1 }",
+          "required": false,
+          "description": "The highest pixel ratio each quality may draw at. Never above the screen's own, so a 1x monitor is never drawn at 2x."
+        }
+      ],
+      "returns": [
+        {
+          "name": "ref",
+          "type": "RefObject<HTMLDivElement | null>",
+          "description": "Put it on the element the scene fills, and give that element a size. The canvas is added inside it."
+        },
+        {
+          "name": "mounted",
+          "type": "boolean",
+          "description": "Whether the scene exists. While false — before it first comes near, under reduced motion, on a device below the floor — show a still image or a background in the element instead."
+        },
+        {
+          "name": "state",
+          "type": "\"dormant\" | \"warming\" | \"active\" | \"constrained\" | \"idle\" | \"recovering\" | \"poster\"",
+          "description": "Where the scene is in its life, straight from the scene gate."
+        },
+        {
+          "name": "quality",
+          "type": "\"full\" | \"reduced\" | null",
+          "description": "How much scene is drawing, or null when there is none. `frame.quality` in update is the live value."
+        },
+        {
+          "name": "cause",
+          "type": "\"ok\" | \"not-near\" | \"waiting-for-headroom\" | \"off-screen\" | \"render-bound\" | \"frame-rate\" | \"device-floor\" | \"reduced-motion\" | \"context-lost\"",
+          "description": "Why the scene is in its current state, in one word. Branch on this."
+        },
+        {
+          "name": "reason",
+          "type": "string",
+          "description": "The same, in a sentence, for a devtools row or a support thread. The wording may change."
+        }
+      ],
+      "runtime": {
+        "lane": "render",
+        "priority": "enhanced",
+        "requiresClient": true,
+        "ssrSafeImport": true,
+        "respectsReducedMotion": true,
+        "reRendersPerFrame": 0,
+        "usesPointer": false,
+        "usesScroll": true,
+        "usesWebGL": true,
+        "ownsTransform": false,
+        "sharedSingletons": [
+          "FrameConductor",
+          "SensorBus",
+          "AnimationBudget",
+          "AdaptiveQuality",
+          "RendererHealth"
+        ],
+        "conflictsWith": [
+          "A render loop of your own for the same renderer — requestAnimationFrame or renderer.setAnimationLoop. The hook already draws every frame, so the scene draws twice and keeps drawing off screen.",
+          "Setting the renderer's pixel ratio or size yourself. The hook sets both whenever the element or the quality changes, and overwrites yours."
+        ],
+        "pairsWith": [
+          "useInteractionScope",
+          "useSensorBus"
+        ]
+      },
+      "quickStart": "\"use client\";\nimport * as THREE from \"three\";\nimport { useThreeScene } from \"@vectorvesper/motion/three\";\n\nexport default function Hero() {\n  const { ref, mounted } = useThreeScene({\n    label: \"hero\",\n    renderer: () => new THREE.WebGLRenderer({ antialias: true }),\n    setup({ width, height }) {\n      const scene = new THREE.Scene();\n      const camera = new THREE.PerspectiveCamera(50, width / height, 0.1, 100);\n      camera.position.z = 5;\n      const knot = new THREE.Mesh(\n        new THREE.TorusKnotGeometry(1, 0.3, 200, 32),\n        new THREE.MeshNormalMaterial(),\n      );\n      scene.add(knot);\n      return {\n        scene,\n        camera,\n        update({ dt }) {\n          knot.rotation.y += dt * 0.5;\n        },\n      };\n    },\n  });\n\n  // While mounted is false — before the scene is built, under reduced motion,\n  // on a device that cannot draw it — put a still of the scene here instead.\n  return (\n    <div ref={ref} style={{ position: \"relative\", height: \"100vh\", background: \"#05060a\" }}>\n      {!mounted && <div aria-hidden style={{ position: \"absolute\", inset: 0, background: \"#0b1622\" }} />}\n    </div>\n  );\n}",
+      "recipes": [
+        {
+          "name": "Post-processing",
+          "blurb": "Draw through an EffectComposer with `render`, keep it sized with `resize`, and release it in `dispose`. The bloom pass switches off at reduced quality, which is cheap; rebuilding it is not.",
+          "code": "\"use client\";\nimport * as THREE from \"three\";\nimport { EffectComposer } from \"three/examples/jsm/postprocessing/EffectComposer.js\";\nimport { RenderPass } from \"three/examples/jsm/postprocessing/RenderPass.js\";\nimport { UnrealBloomPass } from \"three/examples/jsm/postprocessing/UnrealBloomPass.js\";\nimport { useThreeScene } from \"@vectorvesper/motion/three\";\n\nexport function BloomHero() {\n  const { ref } = useThreeScene({\n    label: \"bloom hero\",\n    renderer: () => new THREE.WebGLRenderer({ antialias: true }),\n    setup({ renderer, width, height }) {\n      const scene = new THREE.Scene();\n      const camera = new THREE.PerspectiveCamera(50, width / height, 0.1, 100);\n      camera.position.z = 6;\n      const orb = new THREE.Mesh(\n        new THREE.IcosahedronGeometry(1.4, 4),\n        new THREE.MeshBasicMaterial({ color: 0x66ccff }),\n      );\n      scene.add(orb);\n\n      const composer = new EffectComposer(renderer);\n      composer.addPass(new RenderPass(scene, camera));\n      const bloom = new UnrealBloomPass(new THREE.Vector2(width, height), 1.1, 0.4, 0.85);\n      composer.addPass(bloom);\n\n      return {\n        scene,\n        camera,\n        update({ dt }) {\n          orb.rotation.y += dt * 0.3;\n        },\n        render({ quality }) {\n          bloom.enabled = quality === \"full\";\n          composer.render();\n        },\n        resize(w, h) {\n          composer.setPixelRatio(renderer.getPixelRatio());\n          composer.setSize(w, h);\n        },\n        dispose() {\n          composer.dispose();\n        },\n      };\n    },\n  });\n\n  return <div ref={ref} style={{ position: \"relative\", height: \"100vh\", background: \"#000\" }} />;\n}"
+        },
+        {
+          "name": "WebGPU",
+          "blurb": "Hand it a WebGPURenderer and nothing else changes. The hook waits for the renderer to connect to its device before drawing, and a lost device rebuilds the scene the way a lost context does.",
+          "code": "\"use client\";\nimport * as THREE from \"three/webgpu\";\nimport { useThreeScene } from \"@vectorvesper/motion/three\";\n\nexport function GpuHero() {\n  const { ref } = useThreeScene({\n    label: \"gpu hero\",\n    renderer: () => new THREE.WebGPURenderer({ antialias: true }),\n    setup({ width, height }) {\n      const scene = new THREE.Scene();\n      const camera = new THREE.PerspectiveCamera(50, width / height, 0.1, 100);\n      camera.position.z = 4;\n      const box = new THREE.Mesh(new THREE.BoxGeometry(1.4, 1.4, 1.4), new THREE.MeshNormalMaterial());\n      scene.add(box);\n      return {\n        scene,\n        camera,\n        update({ dt }) {\n          box.rotation.x += dt * 0.4;\n          box.rotation.y += dt * 0.6;\n        },\n      };\n    },\n  });\n\n  return <div ref={ref} style={{ position: \"relative\", height: \"70vh\" }} />;\n}"
+        },
+        {
+          "name": "Loading three only when the scene is near",
+          "blurb": "`renderer` and `setup` may return promises. Importing three inside them keeps the engine out of the first bundle until the scene is actually about to be built.",
+          "code": "\"use client\";\nimport { useThreeScene } from \"@vectorvesper/motion/three\";\n\nexport function LazyShowcase() {\n  const { ref, mounted } = useThreeScene({\n    label: \"showcase\",\n    cost: \"normal\",\n    renderer: async () => {\n      const THREE = await import(\"three\");\n      return new THREE.WebGLRenderer({ antialias: true });\n    },\n    async setup({ width, height }) {\n      const THREE = await import(\"three\");\n      const scene = new THREE.Scene();\n      const camera = new THREE.PerspectiveCamera(40, width / height, 0.1, 50);\n      camera.position.z = 5;\n      const ring = new THREE.Mesh(new THREE.TorusGeometry(1.2, 0.2, 32, 128), new THREE.MeshNormalMaterial());\n      scene.add(ring);\n      return {\n        scene,\n        camera,\n        update({ time }) {\n          ring.rotation.x = time * 0.4;\n        },\n      };\n    },\n  });\n\n  return (\n    <section ref={ref} style={{ position: \"relative\", height: 480 }}>\n      {!mounted && <p>Loading the showcase…</p>}\n    </section>\n  );\n}"
+        }
+      ],
+      "dos": [
+        "Make every three.js object inside `setup`. A rebuild after a lost context calls it again on a fresh renderer, and objects made elsewhere belong to the dead one.",
+        "Return a new renderer from `renderer()` on every call.",
+        "Give the element a size, and show a still image or a background while `mounted` is false.",
+        "Change cheap things off `frame.quality` in `update` — a draw range, a pass's `enabled` — rather than rebuilding geometry.",
+        "Put render targets, composers and controls in `dispose`. Everything reachable from the scene is freed for you."
+      ],
+      "donts": [
+        "Don't call `renderer.render` or run `requestAnimationFrame` yourself. Return `render(frame)` if you need to draw differently.",
+        "Don't set the renderer's pixel ratio or size. The hook owns both and overwrites yours.",
+        "Don't use it for a scene a reader needs under reduced motion. It never builds one for a visitor who asked for less motion.",
+        "Don't add your own canvas to the element. The hook owns the canvas inside it."
+      ],
+      "whenNotToUse": [
+        {
+          "when": "You render with React Three Fiber.",
+          "instead": "`useSceneGate` with `useRenderQuality` spread onto `<Canvas>`. R3F owns the renderer there, so the adapter works through its props."
+        },
+        {
+          "when": "You draw raw WebGL or a 2D canvas without three.",
+          "instead": "`useSceneGate` for the mount decision, and your own drawing on the shared conductor — the `custom-frame-effect` pattern."
+        },
+        {
+          "when": "The scene carries information a visitor needs even with reduced motion, like a data visualisation.",
+          "instead": "Render it without a scene gate, hold the mount with `useSafeToMount`, and stop its animation under reduced motion rather than hiding it."
+        }
+      ],
+      "guardrails": [
+        "practices/adaptive-performance.md",
+        "practices/webgl-budget-and-failopen.md"
+      ],
+      "docsUrl": "https://vectorvesper.dev/runtime/three-scene",
+      "disclosure": {
+        "exposeImplementation": false,
+        "reason": "Reproducing this hook's implementation makes the consumer run a private requestAnimationFrame loop instead of joining the shared FrameConductor. That silently removes the coordination, scheduling and frame-budget governance the runtime exists to provide, and nothing errors when it happens. Copying is a correctness bug, not just a licensing question.",
+        "correctUsage": "Install @vectorvesper/motion and import the hook. Never inline, reimplement, or paste an equivalent.",
+        "readingSource": "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",
@@ -2973,6 +3197,117 @@
         "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": "watchGPUDevice",
+      "importFrom": "@vectorvesper/motion",
+      "packageName": "@vectorvesper/motion",
+      "since": "4.1.0",
+      "category": "core",
+      "tier": "free",
+      "aliases": [
+        "watchGPUDevice",
+        "webgpu",
+        "device lost",
+        "device.lost",
+        "GPUDevice",
+        "navigator.gpu",
+        "requestDevice",
+        "WebGPURenderer",
+        "gpu device loss"
+      ],
+      "exports": [
+        "watchGPUDevice"
+      ],
+      "tagline": "Reports a WebGPU device's health, which arrives as a promise rather than an event.",
+      "problem": "A WebGPU device is taken away for the same reasons a WebGL context is: a driver reset, a backgrounded tab, an OS reclaiming memory. It reports it in a completely different shape. WebGL fires webglcontextlost; WebGPU resolves a lost promise it handed you at creation. Code written for the event never hears the promise, so the canvas stops producing frames with nothing thrown and a clean console.",
+      "summary": "watchGPUDevice(device) reports the device healthy on receipt and reports a loss when it dies, into the same generation counter the WebGL path uses. A scene gate keyed on that generation rebuilds a WebGPU scene with no change to how it is written. Returns a function that stops the watch.",
+      "mechanism": "It reads one field, device.lost, so the parameter is a structural type and @webgpu/types is not a dependency. A real GPUDevice satisfies it whether or not your project has the types.\n\nA loss whose reason is \"destroyed\" is ignored. That value means your own code called device.destroy(), and treating it as a failure rebuilds the scene that is being torn down, which tears down more devices, which report more losses. The WebGL side of this runtime shipped exactly that bug and reached generation 18 inside a second with nobody touching the page.\n\nCancellation is a flag, not a detachment, because a promise cannot be un-awaited. The handler still runs after stop(); what it no longer does is report. Call stop() in the same cleanup that destroys the device.\n\nThrough React Three Fiber none of this is manual: useRenderQuality resolves the device off the renderer's backend and watches it, as well as attaching the WebGL listener.",
+      "signature": "watchGPUDevice(device: GPUDeviceLike): StopWatchingDevice",
+      "options": [
+        {
+          "name": "device",
+          "type": "GPUDeviceLike",
+          "default": "—",
+          "required": false,
+          "description": "Anything carrying a `lost` promise. A real GPUDevice satisfies this structurally, as does an engine's wrapper around one."
+        }
+      ],
+      "returns": [
+        {
+          "name": "stop",
+          "type": "() => void",
+          "description": "Stops reporting. Idempotent, and safe to call after the device has already been lost."
+        }
+      ],
+      "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": "\"use client\";\nimport { watchGPUDevice } from \"@vectorvesper/motion\";\n\nexport async function startSurface(canvas) {\n  const adapter = await navigator.gpu?.requestAdapter();\n  if (!adapter) return () => {};\n\n  const device = await adapter.requestDevice();\n  const stop = watchGPUDevice(device);\n\n  canvas.getContext(\"webgpu\").configure({\n    device,\n    format: navigator.gpu.getPreferredCanvasFormat(),\n    alphaMode: \"premultiplied\",\n  });\n\n  return () => {\n    // Stop first: destroying resolves `lost`, and a teardown is not a failure.\n    stop();\n    device.destroy();\n  };\n}",
+      "recipes": [
+        {
+          "name": "A WebGPU scene that recovers",
+          "blurb": "The generation is the recovery. A new key means a device requested fresh.",
+          "code": "\"use client\";\nimport { useSceneGate } from \"@vectorvesper/motion/react\";\n\nexport function GPUHero() {\n  const scene = useSceneGate({ label: \"gpu-hero\", cost: \"heavy\" });\n\n  return (\n    <div ref={scene.ref} className=\"h-screen w-full\">\n      {scene.mounted ? (\n        // A lost device increments generation, which rebuilds this subtree\n        // against a device requested fresh. A dead device cannot be revived.\n        <GPUSurface key={scene.generation} quality={scene.quality} />\n      ) : (\n        <img src=\"/hero-poster.webp\" alt=\"\" />\n      )}\n    </div>\n  );\n}"
+        },
+        {
+          "name": "Telling a real WebGPU renderer from three's fallback",
+          "blurb": "Ask the backend, not the class. init() swaps in WebGL and keeps the object.",
+          "code": "// three's Renderer.init catches a WebGPU failure and assigns a WebGL\n// backend in its place, so `instanceof WebGPURenderer` stays true on a\n// canvas that is really WebGL, with nothing logged either way.\nconst backend = renderer.backend;\nconst device = backend?.isWebGPUBackend ? backend.device : null;\n\n// Wiring both paths is better than choosing: the webglcontextlost listener is\n// inert on a real WebGPU canvas, and it is what saves the fallback case.\nconst stop = device ? watchGPUDevice(device) : () => {};\ncanvas.addEventListener(\"webglcontextlost\", onWebGLLoss);"
+        }
+      ],
+      "dos": [
+        "Call stop() in the same cleanup that destroys the device, so a teardown is never reported as a failure.",
+        "Re-request the device on a new generation. A lost device cannot be revived, only replaced.",
+        "Through React Three Fiber, spread useRenderQuality's props and let the adapter do this for you."
+      ],
+      "donts": [
+        "Don't await device.lost in a render path. It resolves only when the device dies, which on a healthy machine is never.",
+        "Don't treat reason \"destroyed\" as a failure. That is your own destroy() call, and rebuilding on it cascades.",
+        "Don't decide the wiring with instanceof WebGPURenderer. three's silent WebGL fallback keeps the class and changes the canvas.",
+        "Don't read navigator.gpu as proof of a working device. A blocklisted driver exposes the API and then refuses the adapter."
+      ],
+      "whenNotToUse": [
+        {
+          "when": "The scene renders through React Three Fiber.",
+          "instead": "useRenderQuality, which resolves the device off the renderer's backend and watches it for you."
+        },
+        {
+          "when": "You hold a raw WebGL context rather than a WebGPU device.",
+          "instead": "A webglcontextlost listener that calls preventDefault, reporting to getRendererHealth()."
+        },
+        {
+          "when": "You only want to know whether the browser exposes WebGPU at all.",
+          "instead": "The webgpu flag on AdaptiveQuality's device signals. It is synchronous and needs no adapter."
+        }
+      ],
+      "guardrails": [
+        "practices/adaptive-performance.md"
+      ],
+      "docsUrl": "https://vectorvesper.dev/runtime/webgpu",
+      "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."
+      }
     }
   ],
   "patterns": [
@@ -3151,12 +3486,13 @@
       "wiring": [
         "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.",
+        "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. A profile's `dpr` is a ceiling: it never goes above the screen's own, so a 1x monitor draws at 1x.",
         "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."
+        "Mount once and keep it mounted. Scrolling past gives you `idle`, which pauses drawing while keeping the context and every texture on it.",
+        "This is the React Three Fiber shape. A scene written with three.js directly, with its own `new THREE.WebGLRenderer()`, is `useThreeScene` and the `three-scene` pattern instead."
       ],
-      "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// }",
+      "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//   // dpr is a ceiling: never above the screen's own, so a 1x monitor stays 1x.\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.",
@@ -3178,6 +3514,10 @@
           "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": "Declaring `cost: \"heavy\"` on a page where another scene never stops drawing.",
+          "consequence": "`heavy` waits for a run of frames with real headroom. Next to a scene that keeps drawing off screen those frames never come, and this section stays unmounted: on vv-site's landing page it took 4.5–7.5 seconds, and on a throttled CPU it never mounted. Manage the other scene too, so it idles off screen, or declare this one `normal`."
+        },
         {
           "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."
@@ -3412,6 +3752,68 @@
         "product film"
       ]
     },
+    {
+      "name": "three-scene",
+      "title": "A plain three.js scene, production-safe",
+      "tagline": "One hook around a hand-written three.js scene. You keep the scene.",
+      "problem": "Generated three.js heroes arrive the same way: a WebGLRenderer in an effect, the device's full pixel ratio, their own requestAnimationFrame loop and a window resize listener. They draw while nobody can see them, go black when the browser takes the context away, ignore reduced motion, and leave their context behind on every navigation.",
+      "uses": [
+        "useThreeScene"
+      ],
+      "wiring": [
+        "Call `useThreeScene` in a client component and put `ref` on the element the scene fills. That element needs a size: a height, or `position: absolute; inset: 0` inside a sized parent.",
+        "`renderer` makes a new three.js renderer every time it is called — once when the scene is first built, and again after a lost context. Pass whatever options your scene needs.",
+        "`setup` builds everything three.js — camera, meshes, materials, textures — and returns `{ scene, camera }`. Moving an existing scene over means moving its body into `setup` and deleting its loop, its resize listener and its cleanup.",
+        "Animate in `update(frame)`. It runs before every drawn frame with `dt` and `time` in seconds, and not at all while the scene is off screen. Set pixel-ratio-dependent uniforms from `frame.pixelRatio`.",
+        "Show a still image or a background while `mounted` is false. Under reduced motion and on devices below the floor the scene is never built.",
+        "Leave the pixel ratio, the size, the loop, context loss and disposal to the hook. Put anything `setup` made outside the scene graph — render targets, composers, controls — in `dispose`."
+      ],
+      "code": "\"use client\";\n\nimport * as THREE from \"three\";\nimport { useThreeScene } from \"@vectorvesper/motion/three\";\n\n/**\n * Everything that is yours lives in setup: the camera, the meshes, the\n * materials. When to build, when to draw, the pixel ratio, resizing, a lost\n * context, cleanup and reduced motion are the hook's.\n */\nexport default function Hero() {\n  const { ref, mounted } = useThreeScene({\n    label: \"hero\",\n    renderer: () => new THREE.WebGLRenderer({ antialias: true, powerPreference: \"high-performance\" }),\n    setup({ renderer, width, height }) {\n      renderer.setClearColor(0x05060a, 1);\n\n      const scene = new THREE.Scene();\n      const camera = new THREE.PerspectiveCamera(45, width / height, 0.1, 100);\n      camera.position.set(0, 0, 6);\n\n      const knot = new THREE.Mesh(\n        new THREE.TorusKnotGeometry(1.2, 0.35, 256, 32),\n        new THREE.MeshStandardMaterial({ color: 0x8fd3ff, roughness: 0.25, metalness: 0.6 }),\n      );\n      scene.add(knot);\n      scene.add(new THREE.AmbientLight(0xffffff, 0.4));\n      const light = new THREE.DirectionalLight(0xffffff, 1.4);\n      light.position.set(3, 4, 5);\n      scene.add(light);\n\n      return {\n        scene,\n        camera,\n        // Runs before each drawn frame. dt is in seconds, and nothing runs\n        // while the hero is off screen.\n        update({ dt }) {\n          knot.rotation.x += dt * 0.2;\n          knot.rotation.y += dt * 0.35;\n        },\n      };\n    },\n  });\n\n  return (\n    // The element needs a size: the canvas fills it. While mounted is false\n    // (before the scene is built, under reduced motion, on a device that\n    // cannot draw it smoothly) the stand-in below shows instead.\n    <div ref={ref} style={{ position: \"relative\", height: \"100vh\", background: \"#05060a\" }}>\n      {!mounted && (\n        // Swap in a still of your scene: <img src=\"/hero-still.jpg\" alt=\"\" />\n        <div\n          aria-hidden\n          style={{ position: \"absolute\", inset: 0, background: \"radial-gradient(ellipse at 50% 40%, #1d3b57, #05060a 70%)\" }}\n        />\n      )}\n    </div>\n  );\n}",
+      "pitfalls": [
+        {
+          "mistake": "Creating three.js objects outside `setup`: at module scope, in a ref, or in another effect.",
+          "consequence": "After a lost context the hook calls `setup` again on a fresh renderer. Objects made elsewhere belong to the dead context, so the rebuilt scene is black or missing pieces. A renderer made at module scope also crashes server rendering.",
+          "rule": "ssr-module-scope"
+        },
+        {
+          "mistake": "Returning the same renderer from `renderer()` every time.",
+          "consequence": "After a lost context that renderer is dead. The rebuild draws into it and the scene stays black."
+        },
+        {
+          "mistake": "Keeping your own requestAnimationFrame loop, or calling `renderer.render` yourself.",
+          "consequence": "The scene draws twice a frame, keeps drawing off screen, and runs outside the page's frame budget, where it cannot be shed under load. Use `update` to animate and `render` to draw differently.",
+          "rule": "orphan-raf"
+        },
+        {
+          "mistake": "Rebuilding the scene, or the renderer, when quality changes.",
+          "consequence": "Every change makes a new context; the lab watched one page go from 3 contexts to 7 in twenty seconds. The hook already changes the pixel ratio on the live renderer. Change cheap things off `frame.quality` in `update` instead.",
+          "rule": "renderer-rebuilt-on-change"
+        },
+        {
+          "mistake": "An element with no size.",
+          "consequence": "The canvas is sized to the element, so there is nothing to draw into, and the gate's visibility check fires at the wrong scroll position. The hook warns in the console."
+        },
+        {
+          "mistake": "Rendering nothing while `mounted` is false.",
+          "consequence": "Under reduced motion, and on devices below the floor, the scene is never built. Without a still image or a background there, those visitors get an empty box."
+        }
+      ],
+      "verify": [
+        "check_motion on the file — expect zero findings.",
+        "Scroll the scene out of view and back: nothing draws while it is away, and it resumes on the same canvas.",
+        "Emulate prefers-reduced-motion and reload: the still image shows and no canvas is ever created.",
+        "In the console, lose the context: `document.querySelector('canvas').getContext('webgl2').getExtension('WEBGL_lose_context').loseContext()`. The scene rebuilds within a second, on a new canvas."
+      ],
+      "aliases": [
+        "three.js scene",
+        "plain three.js",
+        "vanilla three.js",
+        "three.js hero",
+        "webglrenderer",
+        "raw three.js",
+        "three hero"
+      ]
+    },
     {
       "name": "velocity-marquee",
       "title": "Velocity-reactive marquee",
@@ -3487,6 +3889,7 @@
         "useVideoScrubber"
       ],
       "pattern": "scrollytelling-video",
+      "starter": false,
       "components": [
         "playpause"
       ],
@@ -3533,6 +3936,7 @@
         "damp"
       ],
       "pattern": "pointer-parallax-scene",
+      "starter": false,
       "components": [
         "lookbook",
         "glass-gallery"
@@ -3567,6 +3971,7 @@
         "damp"
       ],
       "pattern": "velocity-marquee",
+      "starter": false,
       "components": [
         "image-ticker"
       ],
@@ -3599,6 +4004,7 @@
         "useSafeToMount"
       ],
       "pattern": "dashboard-live-numbers",
+      "starter": false,
       "components": [],
       "instead": "State-driven counters re-rendering the tree, and a chart mounted immediately.",
       "watchFor": [
@@ -3627,6 +4033,7 @@
         "usePointerIntent"
       ],
       "pattern": "predictive-media-card",
+      "starter": false,
       "components": [
         "video-card",
         "lookbook"
@@ -3663,6 +4070,7 @@
         "FrameConductor",
         "SensorBus"
       ],
+      "starter": false,
       "components": [],
       "instead": "Reimplementing the effects for the framework, each with its own frame loop.",
       "watchFor": [
@@ -3705,6 +4113,7 @@
         "damp"
       ],
       "pattern": "custom-frame-effect",
+      "starter": false,
       "components": [],
       "instead": "A `requestAnimationFrame` loop in a `useEffect`, which is what training data suggests by default.",
       "watchFor": [
@@ -3756,6 +4165,7 @@
       "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": [],
+      "starter": false,
       "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": [
@@ -3792,6 +4202,7 @@
       "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": [],
+      "starter": false,
       "components": [],
       "instead": "`:hover` with a `transition` on the properties that change.",
       "watchFor": [],
@@ -3822,6 +4233,7 @@
       "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": [],
+      "starter": false,
       "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": [
@@ -3867,7 +4279,13 @@
         "smooth",
         "progress",
         "continuous",
-        "video"
+        "video",
+        "expensive",
+        "heavy",
+        "long task",
+        "main thread",
+        "headroom",
+        "synchronous"
       ],
       "minHits": 1,
       "priority": 920,
@@ -3875,6 +4293,7 @@
       "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": [],
+      "starter": false,
       "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": [
@@ -3908,6 +4327,7 @@
       "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": [],
+      "starter": false,
       "components": [],
       "instead": "`document.startViewTransition()`, or your framework's layout animation (Framer Motion's `layout` prop, Next's view transitions).",
       "watchFor": [
@@ -3939,6 +4359,7 @@
       "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": [],
+      "starter": false,
       "components": [],
       "instead": "`<video autoPlay muted loop playsInline />`, with `poster` for the first paint.",
       "watchFor": [],
@@ -3962,6 +4383,7 @@
       "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": [],
+      "starter": false,
       "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": [
@@ -4000,6 +4422,7 @@
       "headline": "A clock is not a frame loop. Use a timer.",
       "because": "A value that changes once a second needs one update a second. Subscribing it to the frame loop runs the callback sixty to a hundred and twenty times to produce the same digit, and every one of those wakes the scheduler, occupies the budget, and shows up in devtools as work with nothing to show for it. Frame loops are for values that change every frame.",
       "use": [],
+      "starter": false,
       "components": [],
       "instead": "`setInterval`, or a `setTimeout` chain when the cadence has to drift-correct. Compute the displayed value from `Date.now()` against a fixed start rather than by counting ticks — intervals are throttled in background tabs, so a counter that adds one per tick silently runs slow while a computed one stays right.",
       "watchFor": [],
@@ -4023,6 +4446,7 @@
       "headline": "It brings its own renderer and its own frame loop. Do not wrap it in ours.",
       "because": "These players own their playback clock end to end. Driving one from a frame callback gives the page two schedulers arguing over the same animation: ours decides the work should shed under load, theirs keeps advancing regardless, and the result is worse than either alone. There is no per-frame work of yours here to coordinate.",
       "use": [],
+      "starter": false,
       "components": [],
       "instead": "Let the player drive itself, and use its own API to pause it when it is off screen. What is worth governing is the mount, not the loop: these bundles are large and their first parse lands wherever you put it.",
       "watchFor": [
@@ -4052,6 +4476,7 @@
       "headline": "That is a windowing problem, not a motion one.",
       "because": "The cost is the number of mounted DOM nodes and the reconciliation over them, which is React work rather than frame work. Nothing here reduces a node count, and a frame budget cannot govern a render that has already been committed. Reaching for a scheduler because a list feels slow treats the symptom furthest from the cause.",
       "use": [],
+      "starter": false,
       "components": [],
       "instead": "A windowing library — TanStack Virtual or react-window — so only the visible rows exist. Measure with the browser profiler first: an unmemoised row component is more often the cause than the row count.",
       "watchFor": [],
@@ -4075,7 +4500,12 @@
         "frame by frame"
       ],
       "allOf": [],
-      "unless": [],
+      "unless": [
+        "count up",
+        "counter",
+        "odometer",
+        "animated number"
+      ],
       "minHits": 1,
       "priority": 480,
       "verdict": "single",
@@ -4084,6 +4514,7 @@
       "use": [
         "useTick"
       ],
+      "starter": false,
       "components": [],
       "instead": "A `requestAnimationFrame` loop inside a `useEffect`, plus the cancel you have to remember.",
       "watchFor": [
@@ -4135,6 +4566,7 @@
         "useSensorBus",
         "useTick"
       ],
+      "starter": false,
       "components": [],
       "instead": "A `pointermove` or `scroll` listener per component, each with its own state and its own removal.",
       "watchFor": [
@@ -4165,11 +4597,81 @@
       "use": [
         "damp"
       ],
+      "starter": false,
       "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-content-until-scroll-settles",
+      "when": [
+        "scroll has settled",
+        "scroll settles",
+        "scroll to stop",
+        "scroll stops",
+        "mid-scroll",
+        "during the scroll",
+        "while scrolling",
+        "main thread has room",
+        "spare headroom"
+      ],
+      "allOf": [
+        [
+          "mount",
+          "mounting",
+          "render",
+          "build",
+          "load"
+        ],
+        [
+          "heavy",
+          "expensive",
+          "costly",
+          "long task",
+          "jank",
+          "dropped frames",
+          "synchronous"
+        ],
+        [
+          "scroll",
+          "into view",
+          "in view",
+          "intersectionobserver",
+          "intersection observer",
+          "below the fold",
+          "viewport",
+          "main thread"
+        ]
+      ],
+      "unless": [
+        "3d",
+        "webgl",
+        "shader",
+        "three.js",
+        "threejs",
+        "r3f",
+        "react three fiber",
+        "canvas",
+        "video"
+      ],
+      "minHits": 1,
+      "priority": 455,
+      "verdict": "single",
+      "headline": "`useSceneGate({ content: true })` — mounts once the section is near, the scroll has settled and the frame has room.",
+      "because": "The mount is the long task, so where it lands is the whole question. An IntersectionObserver fires on the frame the section crosses the line — mid-scroll, exactly where a reader feels a long task. `useSafeToMount` does not fix that: it watches spare frame time, and a smooth scroll has plenty, because the compositor does the scrolling while the main thread idles. ANDed with the observer it is worse, since it latches true while the page sits at the top, and the mount then lands on the very frame the observer fires.\n\n`useSceneGate` waits for all three: the section near the viewport, the scroll settled, and frame headroom. It is named for 3D, and `content: true` is what makes it right for a chart or a table: the section still waits for the right moment, but it is never withheld. Without it, reduced motion and a device below the 3D floor keep `mounted` false for good, and those visitors never see the content. Render a placeholder of the same height until `mounted` is true.",
+      "use": [
+        "useSceneGate"
+      ],
+      "starter": false,
+      "components": [],
+      "instead": "An IntersectionObserver flipping a boolean that mounts the component on the frame it fires, or that boolean ANDed with `useSafeToMount`, which latched while the page sat at the top.",
+      "watchFor": [
+        "client-boundary",
+        "hand-rolled-scene-gate"
+      ],
+      "notWhen": "The component is above the fold and its cost lands during hydration: `useSafeToMount({ cost })` alone is the gate there. Or it is cheap: something that mounts in a few milliseconds needs no gate at all."
+    },
     {
       "id": "defer-an-expensive-mount",
       "when": [
@@ -4199,6 +4701,7 @@
       "use": [
         "useSafeToMount"
       ],
+      "starter": false,
       "components": [
         "heart-stream",
         "jigsaw-puzzle"
@@ -4236,6 +4739,7 @@
       "use": [
         "useAdaptiveQuality"
       ],
+      "starter": false,
       "components": [],
       "instead": "Sniffing the user agent, or branching on `navigator.hardwareConcurrency` alone.",
       "watchFor": [
@@ -4262,6 +4766,7 @@
       "use": [
         "useAnimationBudget"
       ],
+      "starter": false,
       "components": [],
       "instead": "Timing frames by hand and picking a threshold that is wrong on half of all displays.",
       "watchFor": [],
@@ -4277,7 +4782,11 @@
         "profile",
         "stutter",
         "find the bottleneck",
-        "what is eating the frame"
+        "what is eating the frame",
+        "devtools",
+        "mountdevtools",
+        "per-subscriber",
+        "frame cost"
       ],
       "allOf": [],
       "unless": [],
@@ -4290,6 +4799,7 @@
         "useFramePressure",
         "mountDevtools"
       ],
+      "starter": false,
       "components": [],
       "instead": "Commenting things out until it gets faster.",
       "watchFor": [],
@@ -4319,6 +4829,7 @@
         "usePointerIntent"
       ],
       "pattern": "magnetic-prefetch-cta",
+      "starter": false,
       "components": [
         "video-card"
       ],
@@ -4348,6 +4859,7 @@
         "useMagneticIntent"
       ],
       "pattern": "magnetic-prefetch-cta",
+      "starter": false,
       "components": [
         "physics-buttons"
       ],
@@ -4392,6 +4904,7 @@
         "useVideoScrubber"
       ],
       "pattern": "scrollytelling-video",
+      "starter": false,
       "components": [
         "playpause"
       ],
@@ -4423,6 +4936,7 @@
         "useNumberTicker"
       ],
       "pattern": "dashboard-live-numbers",
+      "starter": false,
       "components": [],
       "instead": "A `setInterval` stepping a state value toward a target.",
       "watchFor": [
@@ -4436,9 +4950,23 @@
         "image trail",
         "trailing images",
         "cursor trail",
-        "images follow the cursor"
+        "images follow the cursor",
+        "trail of images"
+      ],
+      "allOf": [
+        [
+          "trail",
+          "trailing"
+        ],
+        [
+          "image",
+          "images",
+          "photo",
+          "photos",
+          "picture",
+          "pictures"
+        ]
       ],
-      "allOf": [],
       "unless": [],
       "minHits": 1,
       "priority": 370,
@@ -4448,6 +4976,7 @@
       "use": [
         "useImageTrail"
       ],
+      "starter": false,
       "components": [
         "trail-collector",
         "text-trail"
@@ -4492,7 +5021,13 @@
           "keep up"
         ]
       ],
-      "unless": [],
+      "unless": [
+        "mount",
+        "mounting",
+        "mounts",
+        "video",
+        "currenttime"
+      ],
       "minHits": 1,
       "priority": 425,
       "verdict": "single",
@@ -4502,6 +5037,7 @@
         "useInteractionScope",
         "useTick"
       ],
+      "starter": false,
       "components": [],
       "instead": "Pausing every other animation by hand when a drag starts, and forgetting to resume one.",
       "watchFor": [
@@ -4509,13 +5045,79 @@
       ],
       "notWhen": "There is only one interactive region on the page. With nothing to yield, the scope is bookkeeping that changes no decision."
     },
+    {
+      "id": "three-scene",
+      "when": [
+        "plain three.js",
+        "plain threejs",
+        "vanilla three.js",
+        "raw three.js",
+        "three.js hero",
+        "three.js",
+        "threejs",
+        "webglrenderer",
+        "three.webglrenderer",
+        "setanimationloop",
+        "3d scene",
+        "webgl scene"
+      ],
+      "allOf": [
+        [
+          "three.js",
+          "threejs",
+          "webglrenderer"
+        ],
+        [
+          "scene",
+          "hero",
+          "background",
+          "canvas",
+          "section",
+          "3d",
+          "webgl",
+          "shader",
+          "particle",
+          "terrain",
+          "model",
+          "production"
+        ]
+      ],
+      "unless": [
+        "react three fiber",
+        "r3f",
+        "@react-three",
+        "react-three-fiber",
+        "useframe",
+        "drei",
+        "<canvas>"
+      ],
+      "minHits": 1,
+      "priority": 725,
+      "verdict": "single",
+      "headline": "`useThreeScene` — you build the scene; it does everything else a production scene needs.",
+      "because": "A hand-written three.js scene needs about ten things right besides the scene itself. Build it only when it is near the viewport and the page can afford it. Draw on the shared frame loop, and not at all while it is off screen. Keep the pixel ratio at or below the screen's own, and lower it on the renderer you have instead of rebuilding. Follow the element's size. Listen for a lost context from the moment the renderer exists, rebuild on a fresh one, and report when the replacement has drawn. Free every geometry, material and texture, and the context itself, when the scene goes. And never build it for a visitor who asked for less motion.\n\n`useThreeScene` does all of those. You pass a function that makes the renderer and one that builds the scene and returns it with its camera; moving an existing scene over means moving its body into `setup` and deleting its loop, its resize listener and its cleanup. vv-lab runs the file below through every probe it has, on Chrome and Safari's engine, desktop and mobile.",
+      "use": [
+        "useThreeScene"
+      ],
+      "pattern": "three-scene",
+      "starter": true,
+      "components": [],
+      "instead": "A `useEffect` that creates a WebGLRenderer, runs its own requestAnimationFrame loop, sets the device's full pixel ratio, listens for window resize and disposes the geometry — the shape every generated hero arrives in, and about ten steps short of production.",
+      "watchFor": [
+        "offscreen-render",
+        "webgl-context-loss",
+        "unreleased-context",
+        "uncapped-pixel-ratio",
+        "renderer-rebuilt-on-change",
+        "no-reduced-motion"
+      ],
+      "notWhen": "The scene is React Three Fiber: `<Canvas>` owns the renderer, so the pair is `useSceneGate` and `useRenderQuality`. Or the scene carries information a visitor needs even with reduced motion, such as a data visualisation: this hook never builds a scene for someone who asked for less motion."
+    },
     {
       "id": "r3f-scene",
       "when": [
         "react three fiber",
         "r3f",
-        "three.js",
-        "threejs",
         "3d scene",
         "webgl scene",
         "3d model",
@@ -4526,18 +5128,24 @@
       "unless": [
         "shader",
         "glsl",
-        "uniform"
+        "uniform",
+        "plain three.js",
+        "vanilla three.js",
+        "raw three.js",
+        "webglrenderer",
+        "three.webglrenderer"
       ],
       "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`.",
+      "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`.\n\nThis is the React Three Fiber answer. If the scene is written with three.js directly, with a `new THREE.WebGLRenderer()` of its own, use `useThreeScene` instead: one hook does all of it.",
       "use": [
         "useSceneGate",
         "useRenderQuality"
       ],
       "pattern": "lazy-3d-section",
+      "starter": false,
       "components": [
         "volumetric-light",
         "refractive-gallery"
@@ -4569,12 +5177,13 @@
       "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.",
+      "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. In a `useThreeScene` scene the material already lives in `setup`, so assign it in `update` from `frame.time`.\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",
+      "starter": false,
       "components": [
         "media-shader",
         "acrylic-shader"
@@ -4605,12 +5214,13 @@
       "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.",
+      "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. In a `useThreeScene` scene, read `frame.quality` in `update` and set the geometry's draw range, which costs nothing to change.\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",
+      "starter": false,
       "components": [
         "particle-morph-gallery",
         "magnetic-sand",
@@ -4640,12 +5250,13 @@
       "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.",
+      "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. With `useThreeScene`, draw through the composer in `render`, size it in `resize`, switch passes off `frame.quality`, and release it in `dispose`; its Post-processing recipe has the whole file.",
       "use": [
         "useSceneGate",
         "useRenderQuality"
       ],
       "pattern": "lazy-3d-section",
+      "starter": false,
       "components": [],
       "instead": "A fixed composer stack that ships every pass to every device.",
       "watchFor": [
@@ -4676,24 +5287,32 @@
           "glsl",
           "webgl",
           "3d",
-          "three.js",
-          "threejs",
           "canvas",
           "video loop",
           "particle"
         ]
       ],
-      "unless": [],
+      "unless": [
+        "three.js",
+        "threejs",
+        "webglrenderer",
+        "react three fiber",
+        "r3f",
+        "@react-three",
+        "useframe",
+        "<canvas>"
+      ],
       "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.",
+      "because": "First, what draws the hero. A three.js scene is `useThreeScene`, and a React Three Fiber one is `useSceneGate` with `useRenderQuality`: ask again naming it, or read the component before deciding. What follows is for a hero drawn by a full-screen shader or a video, with no scene graph.\n\nA 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",
+      "starter": false,
       "components": [
         "volumetric-light",
         "media-shader"
@@ -4703,7 +5322,7 @@
         "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."
+      "notWhen": "The hero is a three.js or React Three Fiber scene: those have their own answers above. Or it 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",
@@ -4715,23 +5334,69 @@
         "context restore"
       ],
       "allOf": [],
-      "unless": [],
+      "unless": [
+        "webgpu",
+        "webgpurenderer",
+        "navigator.gpu",
+        "device.lost",
+        "gpudevice"
+      ],
       "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.",
+      "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.\n\nWired by hand the loop is three calls, and the third is the one that gets missed: `preventDefault()`, then `reportLost({ builtAt })` with the generation that was current when the renderer was made, then `reportHealthy()` once the replacement has drawn. Without the last, the page is held in recovery at reduced quality until the runtime gives up waiting. Without `builtAt`, a replacement that dies moments after it was built is taken for the same loss and stays black. A plain three.js scene gets all of it from `useThreeScene`, and an R3F one from `useRenderQuality`.",
       "use": [
         "RendererHealth",
         "useRenderQuality"
       ],
       "pattern": "lazy-3d-section",
+      "starter": false,
       "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."
+      "notWhen": "You already use `useThreeScene`, or spread `useRenderQuality`'s props onto the canvas. Both attach the listener and report for you, and a second listener moves the generation twice per loss."
+    },
+    {
+      "id": "webgpu-device-loss",
+      "when": [
+        "webgpu",
+        "navigator.gpu",
+        "requestadapter",
+        "requestdevice",
+        "webgpurenderer",
+        "device lost",
+        "device.lost",
+        "gpudevice",
+        "webgpu canvas",
+        "webgpu context lost",
+        "webgpu scene",
+        "tsl"
+      ],
+      "allOf": [],
+      "unless": [],
+      "minHits": 1,
+      "priority": 790,
+      "verdict": "single",
+      "headline": "`watchGPUDevice(device)`. WebGPU does not fire an event, it resolves a promise.",
+      "because": "A WebGPU device is taken away for the same reasons a WebGL context is, and reports it in a completely different shape: the device hands you a `lost` promise when you create it, and that promise resolves when it dies. There is no event, so a `webglcontextlost` listener hears nothing and the scene stops drawing with a clean console. Hand the device to `watchGPUDevice`, which reports into the same `generation` counter the WebGL path uses, so `useSceneGate` rebuilds the scene with no change to how it is written. Through React Three Fiber you get this for free: spread `useRenderQuality`'s props and it watches the device as well as listening for the WebGL event. `useThreeScene` does the same for a plain three.js `WebGPURenderer`. Two things that are easy to get wrong on your own. A loss whose `reason` is `\"destroyed\"` is your own `destroy()` call, and reporting it as a failure rebuilds the scene you are tearing down, which tears down more scenes. And three quietly swaps in a WebGL backend when WebGPU init fails, so `instanceof WebGPURenderer` can be true on a canvas that is really WebGL: ask `renderer.backend?.isWebGPUBackend`, or simply wire both paths, which is what the adapter does.",
+      "use": [
+        "watchGPUDevice",
+        "useSceneGate",
+        "useRenderQuality"
+      ],
+      "pattern": "lazy-3d-section",
+      "starter": false,
+      "components": [],
+      "instead": "A `webglcontextlost` listener, which a WebGPU canvas never fires, or `await device.lost` in a render path, which resolves only when the device dies and on a healthy machine never resolves.",
+      "watchFor": [
+        "webgpu-device-loss",
+        "webgpu-destroy-not-a-loss",
+        "webgpu-renderer-class-check"
+      ],
+      "notWhen": "You are drawing with WebGL or Canvas 2D. Neither loses a device this way, and `useRenderQuality` already covers the WebGL event for an R3F canvas."
     }
   ]
 }