vectorvesper 2.6.0 → 2.8.0

package/dist/index.js

@@ -1123,7 +1123,7 @@ Remove ${slug}
 import fs7 from "fs";
 import path7 from "path";
 import pc8 from "picocolors";
-var CLI_VERSION = true ? "2.6.0" : "0.0.0-dev";
+var CLI_VERSION = true ? "2.8.0" : "0.0.0-dev";
 async function infoCommand() {
   console.log(pc8.bold(pc8.cyan("\nVector Vesper Diagnostics\n")));
   const projectInfo = detectProject();
@@ -1423,7 +1423,7 @@ async function whoamiCommand() {
 }
 
 // src/index.ts
-var version = true ? "2.6.0" : "0.0.0-dev";
+var version = true ? "2.8.0" : "0.0.0-dev";
 var program = new Command();
 program.name("vv").description("Vector Vesper CLI \u2014 add visual components to your React project").version(version).option("--verbose", "Show detailed debug output").hook("preAction", (thisCommand) => {
   const opts = thisCommand.opts();
@@ -1465,7 +1465,7 @@ program.command("mcp [action] [client]").description(
   "Run as an MCP server (stdio) for AI coding agents. `vv mcp install` wires it into your editor; `vv mcp status` checks the setup."
 ).option("--stdio", "Force server mode even from an interactive terminal").option("-g, --global", "Write user-level config instead of project-level (install)").action(
   async (action, client, options) => {
-    const { mcpCommand } = await import("./mcp-BEM4TVKM.js");
+    const { mcpCommand } = await import("./mcp-LMUWTS3I.js");
     await mcpCommand(action, { ...options, client });
   }
 );

package/dist/{mcp-BEM4TVKM.js → mcp-LMUWTS3I.js}

@@ -146,7 +146,7 @@ function detectClients(cwd = process.cwd()) {
 }
 
 // src/commands/mcp.ts
-var VERSION = true ? "2.6.0" : "0.0.0-dev";
+var VERSION = true ? "2.8.0" : "0.0.0-dev";
 var CONFIG_SNIPPET = `{
   "mcpServers": {
     "vectorvesper": {
@@ -293,7 +293,7 @@ ${pc.red("\u2717")} Unknown argument "${action}" for \`vv mcp\`.
     return;
   }
   protectStdout();
-  const { startMcpServer } = await import("./server-CIFO3HSN.js");
+  const { startMcpServer } = await import("./server-PYIRS3NJ.js");
   try {
     await startMcpServer();
   } catch (error) {

package/dist/{server-CIFO3HSN.js → server-PYIRS3NJ.js}

@@ -146,9 +146,23 @@ function collect(ast, traverse) {
     laneViolations: [],
     orphanSubscriptions: [],
     canvases: [],
+    adapterBindings: /* @__PURE__ */ new Set(),
+    propSpreads: [],
     rawGlContexts: [],
     handlesContextLoss: false,
-    gatingObserver: []
+    gpuDevices: [],
+    gpuLostHandlers: [],
+    mentionsDestroyedReason: false,
+    webgpuClassChecks: [],
+    gatingObserver: [],
+    threeRenderers: [],
+    uncappedPixelRatio: [],
+    animationLoops: [],
+    hasForceContextLoss: false,
+    reportsLost: false,
+    reportsHealthy: false,
+    rendererRebuilds: [],
+    hasIntersectionObserver: false
   };
   const reactSetters = collectReactSetters(ast, traverse);
   const manifest = loadHookManifest();
@@ -194,6 +208,16 @@ function collect(ast, traverse) {
       }
       return false;
     };
+    const memberPath = (n) => {
+      if (!n || typeof n.type !== "string") return null;
+      if (n.type === "Identifier") return n.name;
+      if (n.type === "MemberExpression" && !n.computed) {
+        const obj = memberPath(n.object);
+        const prop = n.property?.type === "Identifier" ? n.property.name : null;
+        return obj && prop ? `${obj}.${prop}` : null;
+      }
+      return null;
+    };
     const isLatched = (setterPath) => {
       let node = setterPath;
       while (node) {
@@ -203,6 +227,10 @@ function collect(ast, traverse) {
           const collect2 = (n) => {
             if (!n || typeof n.type !== "string") return;
             if (n.type === "Identifier") guards.add(n.name);
+            if (n.type === "MemberExpression") {
+              const p = memberPath(n);
+              if (p) guards.add(p);
+            }
             for (const key of Object.keys(n)) {
               const v = n[key];
               if (Array.isArray(v)) v.forEach(collect2);
@@ -213,7 +241,8 @@ function collect(ast, traverse) {
           let latched = false;
           const check = (inner) => {
             const target = inner.node.left ?? inner.node.argument;
-            if (target?.type === "Identifier" && guards.has(target.name)) latched = true;
+            const name = memberPath(target);
+            if (name && guards.has(name)) latched = true;
           };
           if (typeof node.traverse === "function") {
             node.traverse({ AssignmentExpression: check, UpdateExpression: check });
@@ -303,6 +332,25 @@ function collect(ast, traverse) {
     );
     if (lane === "input" || lane === "update" || lane === "render") scanLaneDiscipline(cb, lane, via);
   };
+  const isDetachedProbeCanvas = (p, node) => {
+    const obj = node.callee?.object;
+    if (!obj || obj.type !== "Identifier") return false;
+    const binding = typeof p.scope?.getBinding === "function" ? p.scope.getBinding(obj.name) : null;
+    if (!binding) return false;
+    const decl = binding.path?.node;
+    const init = decl?.type === "VariableDeclarator" ? decl.init : null;
+    if (!init || init.type !== "CallExpression") return false;
+    if (calleeName(init.callee) !== "createElement") return false;
+    const tag = init.arguments?.[0];
+    if (tag?.type !== "StringLiteral" || tag.value !== "canvas") return false;
+    const INERT = /* @__PURE__ */ new Set(["getContext", "width", "height"]);
+    return (binding.referencePaths ?? []).every((ref) => {
+      const parent = ref.parentPath?.node;
+      if (!parent) return false;
+      const isMember = parent.type === "MemberExpression" || parent.type === "OptionalMemberExpression";
+      return isMember && parent.object === ref.node && INERT.has(parent.property?.name);
+    });
+  };
   const handleCall = (p) => {
     const node = p.node;
     const name = calleeName(node.callee);
@@ -320,6 +368,68 @@ function collect(ast, traverse) {
       case "cancelAnimationFrame":
         f.hasCancelRaf = true;
         break;
+      // Telling RendererHealth about a context change IS handling it, and it is
+      // the half `webglcontextlost`-string detection cannot see.
+      //
+      // This is keyed on the call rather than on an import name on purpose.
+      // Projects routinely re-export the runtime through their own barrel — our
+      // own docs site imports `getRendererHealth` from `@/motion`, which is a
+      // file that does `export * from "@vectorvesper/motion/react"`. Every
+      // check that asks "is this name in `vvImports`" is blind to that, so the
+      // scene-gate page reported having no context-loss handling three lines
+      // above the `reportLost()` that handles it. Found 2026-09-09.
+      //
+      // Deliberately loose: only `reportLost`/`reportHealthy`, not
+      // `getRendererHealth`, because reading health for a readout is not
+      // handling. Being loose here can only suppress a finding, and a missed
+      // warning is the failure this file prefers over a false one.
+      case "reportLost":
+        f.handlesContextLoss = true;
+        f.reportsLost = true;
+        break;
+      case "reportHealthy":
+        f.handlesContextLoss = true;
+        f.reportsHealthy = true;
+        break;
+      case "setPixelRatio": {
+        const arg = node.arguments?.[0];
+        const bare = arg?.type === "Identifier" && arg.name === "devicePixelRatio" || arg?.type === "MemberExpression" && !arg.computed && arg.property?.name === "devicePixelRatio" && arg.object?.type === "Identifier" && ["window", "globalThis", "self"].includes(arg.object.name);
+        if (bare) f.uncappedPixelRatio.push(line);
+        break;
+      }
+      case "setAnimationLoop":
+        if (node.arguments?.[0] && node.arguments[0].type !== "NullLiteral") f.animationLoops.push(line);
+        break;
+      case "forceContextLoss":
+        f.hasForceContextLoss = true;
+        break;
+      case "useEffect":
+      case "useLayoutEffect": {
+        const deps = node.arguments?.[1];
+        if (deps?.type !== "ArrayExpression" || deps.elements.length === 0) break;
+        const cb = resolveFunction(argPaths[0]);
+        if (!cb || !callbackBuildsRenderer(cb, traverse)) break;
+        const moving = deps.elements.map((el) => depName(el)).filter((dep) => dep !== null && !isStableDep(dep));
+        if (moving.length > 0) f.rendererRebuilds.push({ line: deps.loc?.start.line ?? line, deps: moving });
+        break;
+      }
+      case "useRenderQuality": {
+        const parent = p.parent;
+        if (parent?.type === "VariableDeclarator" && parent.id?.type === "Identifier") {
+          f.adapterBindings.add(parent.id.name);
+        }
+        break;
+      }
+      case "requestDevice":
+        f.gpuDevices.push(line);
+        break;
+      case "then": {
+        const obj = node.callee?.object;
+        if ((obj?.property?.name ?? obj?.property?.value) === "lost") {
+          f.gpuLostHandlers.push(line);
+        }
+        break;
+      }
       case "setInterval":
         f.setInterval.push(line);
         break;
@@ -350,9 +460,9 @@ function collect(ast, traverse) {
         break;
       case "getContext": {
         const kind = node.arguments?.[0];
-        if (kind?.type === "StringLiteral" && /^(webgl2?|experimental-webgl)$/.test(kind.value)) {
-          f.rawGlContexts.push(line);
-        }
+        if (kind?.type !== "StringLiteral" || isDetachedProbeCanvas(p, node)) break;
+        if (/^(webgl2?|experimental-webgl)$/.test(kind.value)) f.rawGlContexts.push(line);
+        if (kind.value === "webgpu") f.gpuDevices.push(line);
         break;
       }
       case "kill":
@@ -411,6 +521,7 @@ function collect(ast, traverse) {
       const v = p.node.value;
       if (v.includes("prefers-reduced-motion")) f.hasReducedMotionGuard = true;
       if (v === "webglcontextlost" || v === "webglcontextrestored") f.handlesContextLoss = true;
+      if (v === "destroyed") f.mentionsDestroyedReason = true;
       if (/\binfinite\b/.test(v) && /\b\d+(?:\.\d+)?m?s\b/.test(v)) {
         f.looping.push({ line: p.node.loc?.start.line ?? 0, kind: "CSS `infinite` animation" });
       }
@@ -432,7 +543,17 @@ function collect(ast, traverse) {
     // imperatively. Record the shape so the render-quality rules can read it.
     JSXOpeningElement(p) {
       f.isReact = true;
-      if (p.node.name?.name !== "Canvas") return;
+      const element = p.node.name?.name ?? "";
+      for (const attr of p.node.attributes ?? []) {
+        if (attr.type !== "JSXSpreadAttribute") continue;
+        if (attr.argument?.type !== "Identifier") continue;
+        f.propSpreads.push({
+          line: p.node.loc?.start.line ?? 0,
+          element,
+          name: attr.argument.name
+        });
+      }
+      if (element !== "Canvas") return;
       const overrides = [];
       let hasSpread = false;
       for (const attr of p.node.attributes ?? []) {
@@ -473,9 +594,11 @@ function collect(ast, traverse) {
       f.moduleScopeBrowserApi.push({ line: p.node.loc?.start.line ?? 0, api: name });
     },
     NewExpression(p) {
-      const n = p.node.callee?.name;
+      const n = constructorName(p.node.callee);
+      if (n === "WebGLRenderer") f.threeRenderers.push(p.node.loc?.start.line ?? 0);
       if (n && OBSERVERS.has(n)) f.newObserver.push(p.node.loc?.start.line ?? 0);
       if (n === "IntersectionObserver") {
+        f.hasIntersectionObserver = true;
         const argPaths = typeof p.get === "function" ? p.get("arguments") : [];
         if (containsStateSetter(resolveFunction(argPaths[0]))) {
           f.gatingObserver.push(p.node.loc?.start.line ?? 0);
@@ -484,6 +607,22 @@ function collect(ast, traverse) {
       if (n && /(?:Geometry|Material|Texture|RenderTarget)$/.test(n)) {
         f.threeDisposable.push(p.node.loc?.start.line ?? 0);
       }
+      if (n === "WebGPURenderer") f.gpuDevices.push(p.node.loc?.start.line ?? 0);
+    },
+    /**
+     * `x instanceof WebGPURenderer`, which is the wrong question.
+     *
+     * three's `Renderer.init` catches a WebGPU failure and swaps in a WebGL
+     * backend, so the class says WebGPU while the canvas is WebGL. Branching on
+     * it to decide how to notice a lost context leaves the fallback with no
+     * handling at all, silently.
+     */
+    BinaryExpression(p) {
+      if (p.node.operator !== "instanceof") return;
+      const right = p.node.right;
+      if (right?.type === "Identifier" && /^WebGPURenderer$/.test(right.name)) {
+        f.webgpuClassChecks.push(p.node.loc?.start.line ?? 0);
+      }
     },
     CallExpression(p) {
       handleCall(p);
@@ -580,7 +719,7 @@ function checkMissingCleanup(f, file) {
   if (f.newObserver.length && !f.hasObserverDisconnect) push(f.newObserver[0], "An observer", "`.disconnect()`");
   if (f.gsapTimeline.length && !f.usesUseGSAP && !f.hasGsapCleanup)
     push(f.gsapTimeline[0], "A GSAP timeline", "`.kill()` (or drive it from `useGSAP`, which reverts automatically)");
-  if (f.threeDisposable.length && !f.usesR3F && !f.hasThreeDispose)
+  if (f.threeDisposable.length && !f.usesR3F && !f.hasThreeDispose && !f.vvImports.has("useThreeScene"))
     push(f.threeDisposable[0], "A three.js geometry/material/texture", "`.dispose()`");
   return out;
 }
@@ -671,21 +810,105 @@ function checkRenderQualityProps(f, file) {
 function checkContextLoss(f, file) {
   const r3fCanvas = f.usesR3F && f.canvases.length > 0;
   const rawContext = f.rawGlContexts.length > 0;
-  if (!r3fCanvas && !rawContext) return [];
-  const handled = f.handlesContextLoss || f.vvImports.has("useRenderQuality") || f.vvImports.has("getRendererHealth");
+  const handRenderer = !f.usesR3F && f.threeRenderers.length > 0;
+  if (!r3fCanvas && !rawContext && !handRenderer) return [];
+  const adapter = ["useRenderQuality", "useThreeScene", "watchGPUDevice"].some((n) => f.vvImports.has(n));
+  if (adapter) return [];
+  const line = r3fCanvas ? f.canvases[0].line : f.rawGlContexts[0] ?? f.threeRenderers[0];
+  if (f.reportsLost && !f.reportsHealthy) {
+    return [
+      {
+        rule: "webgl-context-loss",
+        severity: "warning",
+        file,
+        line,
+        message: "This file reports a lost context and never reports that the replacement is up. Until `reportHealthy()` is called, every scene gate on the page holds its scene in recovery at reduced quality.",
+        fix: "Call `getRendererHealth().reportHealthy()` once the replacement renderer has drawn its first frame. Pass `builtAt` to `reportLost` as well \u2014 the generation that was current when the renderer was made \u2014 so a replacement lost moments after it was built still gets a rebuild of its own.",
+        ...handRenderer ? { nudge: 'Call `get_pattern("three-scene")`: `useThreeScene` wires all of it.' } : {}
+      }
+    ];
+  }
+  const handled = f.handlesContextLoss || f.vvImports.has("getRendererHealth");
   if (handled) return [];
+  const threeOnly = handRenderer && !r3fCanvas && !rawContext;
   return [
     {
       rule: "webgl-context-loss",
       severity: "warning",
       file,
-      line: r3fCanvas ? f.canvases[0].line : f.rawGlContexts[0],
+      line,
       message: "Nothing in this file notices a lost graphics context. When the browser takes one away the canvas goes black permanently and nothing is logged, so it reads as a rendering bug rather than a recoverable event.",
-      fix: (r3fCanvas ? "Spread `useRenderQuality`'s props onto the canvas and key it on a scene gate's `generation` \u2014 the `onCreated` it returns attaches the listener and reports the loss, and the moving key rebuilds the tree against a fresh context. Failing that, attach a " : "You created this context by hand, so the adapter does not apply. Attach a ") + "`webglcontextlost` listener that calls `preventDefault()` (without it some drivers refuse a replacement context outright) and report to `getRendererHealth()`.",
+      fix: (r3fCanvas ? "Spread `useRenderQuality`'s props onto the canvas and key it on a scene gate's `generation` \u2014 the `onCreated` it returns attaches the listener and reports the loss, and the moving key rebuilds the tree against a fresh context. Failing that, attach a " : threeOnly ? "For a three.js scene, `useThreeScene` from `@vectorvesper/motion/three` listens from the moment the renderer exists and rebuilds the scene on a fresh one. By hand, attach a " : "You created this context by hand, so the adapter does not apply. Attach a ") + "`webglcontextlost` listener that calls `preventDefault()` (without it some drivers refuse a replacement context outright) and report to `getRendererHealth()`.",
+      nudge: threeOnly ? 'Call `get_pattern("three-scene")` for the whole file.' : 'Call `get_pattern("lazy-3d-section")` for the whole wiring.'
+    }
+  ];
+}
+function checkAdapterPropsToWrapper(f, file) {
+  if (f.adapterBindings.size === 0) return [];
+  const strays = f.propSpreads.filter(
+    (s) => f.adapterBindings.has(s.name) && s.element !== "Canvas"
+  );
+  if (strays.length === 0) return [];
+  const first = strays[0];
+  const reachesCanvas = f.propSpreads.some(
+    (s) => f.adapterBindings.has(s.name) && s.element === "Canvas"
+  );
+  return [
+    {
+      rule: "adapter-props-to-wrapper",
+      severity: "info",
+      file,
+      line: first.line,
+      message: `\`useRenderQuality\`'s props are spread onto \`<${first.element}>\`` + (reachesCanvas ? " as well as onto `<Canvas>`" : ", and never onto a `<Canvas>` in this file") + ". If that component builds its own canvas props and forwards the rest elsewhere, all four of the adapter's jobs stop happening: the pixel ratio, the frame loop, the shadow setting, and the `onCreated` that notices a lost graphics context. The spread stays type-valid either way, because the extra props are absorbed by the component's rest parameter.",
+      fix: `Open \`${first.element}\` and confirm it spreads what it receives onto its \`<Canvas>\`, \`onCreated\` included. If it does not, spread the adapter's props onto the \`<Canvas>\` directly instead of onto the wrapper, or have the wrapper accept and forward them explicitly.`,
+      nudge: "A rest spread is not evidence the props arrived. Check the canvas, not the call site."
+    }
+  ];
+}
+function checkGpuDeviceLoss(f, file) {
+  if (f.gpuDevices.length === 0) return [];
+  const handled = f.gpuLostHandlers.length > 0 || f.vvImports.has("watchGPUDevice") || f.vvImports.has("useRenderQuality") || f.vvImports.has("useThreeScene");
+  if (handled) return [];
+  return [
+    {
+      rule: "webgpu-device-loss",
+      severity: "warning",
+      file,
+      line: f.gpuDevices[0],
+      message: "This file takes a WebGPU device and nothing watches `device.lost`. A WebGPU canvas never fires `webglcontextlost`, so a listener written for WebGL will not hear this one. When the device goes the scene stops drawing with nothing logged.",
+      fix: "Pass the device to `watchGPUDevice(device)` from `@vectorvesper/motion`, and key the scene on a scene gate's `generation` so the loss rebuilds it against a device you request fresh. Through React Three Fiber, spreading `useRenderQuality`'s props does both.",
       nudge: 'Call `get_pattern("lazy-3d-section")` for the whole wiring.'
     }
   ];
 }
+function checkGpuDestroyReason(f, file) {
+  if (f.gpuLostHandlers.length === 0) return [];
+  if (f.mentionsDestroyedReason) return [];
+  if (f.vvImports.has("watchGPUDevice")) return [];
+  return [
+    {
+      rule: "webgpu-destroy-not-a-loss",
+      severity: "warning",
+      file,
+      line: f.gpuLostHandlers[0],
+      message: 'This handler treats every `device.lost` resolution as a failure. It also resolves when your own code calls `device.destroy()`, where `reason` is `"destroyed"` \u2014 so unmounting a scene reports a loss, which rebuilds the page, which unmounts more scenes.',
+      fix: 'Return early when `info?.reason === "destroyed"`, or use `watchGPUDevice(device)`, which does it and coalesces simultaneous losses into one rebuild.'
+    }
+  ];
+}
+function checkWebgpuClassCheck(f, file) {
+  if (f.webgpuClassChecks.length === 0) return [];
+  return [
+    {
+      rule: "webgpu-renderer-class-check",
+      severity: "info",
+      file,
+      line: f.webgpuClassChecks[0],
+      message: "`instanceof WebGPURenderer` does not tell you the renderer is drawing with WebGPU. three catches a failed WebGPU init and swaps in a WebGL backend, keeping the same object, so this branch can send a WebGL canvas down the WebGPU path.",
+      fix: "Ask the backend rather than the class: `renderer.backend?.isWebGPUBackend` with the device checked for a `lost` promise. Better still, wire both paths \u2014 the `webglcontextlost` listener is inert on a real WebGPU canvas and is exactly what saves the fallback case."
+    }
+  ];
+}
 function checkHandRolledGate(f, file) {
   const ownsGpu = f.usesR3F && f.canvases.length > 0 || f.rawGlContexts.length > 0;
   if (!ownsGpu) return [];
@@ -717,10 +940,118 @@ function checkTransformConflict(f, file) {
     }
   ];
 }
+function constructorName(callee) {
+  if (!callee) return void 0;
+  if (callee.type === "Identifier") return callee.name;
+  if ((callee.type === "MemberExpression" || callee.type === "OptionalMemberExpression") && !callee.computed) {
+    return callee.property?.name;
+  }
+  return void 0;
+}
+var RENDERER_CLASSES = /* @__PURE__ */ new Set(["WebGLRenderer", "WebGPURenderer"]);
+function callbackBuildsRenderer(cbNode, traverse) {
+  const isDeclaration = cbNode.type === "FunctionDeclaration";
+  const isExpression = cbNode.type === "ArrowFunctionExpression" || cbNode.type === "FunctionExpression";
+  if (!isDeclaration && !isExpression) return false;
+  const statement = isDeclaration ? cbNode : { type: "ExpressionStatement", expression: cbNode };
+  let found = false;
+  traverse(
+    { type: "File", program: { type: "Program", body: [statement], directives: [] } },
+    {
+      NewExpression(p) {
+        if (RENDERER_CLASSES.has(constructorName(p.node.callee) ?? "")) found = true;
+      }
+    }
+  );
+  return found;
+}
+function depName(node) {
+  if (!node) return null;
+  if (node.type === "Identifier") return node.name;
+  if ((node.type === "MemberExpression" || node.type === "OptionalMemberExpression") && !node.computed) {
+    const object = depName(node.object);
+    return object ? `${object}.${node.property?.name}` : null;
+  }
+  return null;
+}
+function isStableDep(name) {
+  return /(?:Ref|\.current)$/.test(name) || /generation/i.test(name) || /^(gen|key)$/.test(name) || /^set[A-Z]/.test(name);
+}
+function handDrawnSceneLoop(f) {
+  const ownsGpu = !f.usesR3F && (f.threeRenderers.length > 0 || f.rawGlContexts.length > 0);
+  if (!ownsGpu) return null;
+  if (!isRafLoop(f) && f.animationLoops.length === 0) return null;
+  return f.rafSelfScheduling[0] ?? f.animationLoops[0] ?? f.raf[0] ?? null;
+}
+function gatedByRuntime(f) {
+  return ["useSceneGate", "useThreeScene", "SceneState", "useRenderQuality"].some(
+    (n) => f.vvImports.has(n)
+  );
+}
+function checkOffscreenRender(f, file) {
+  const line = handDrawnSceneLoop(f);
+  if (line === null || gatedByRuntime(f) || f.hasIntersectionObserver) return [];
+  return [
+    {
+      rule: "offscreen-render",
+      severity: "warning",
+      file,
+      line,
+      message: "This scene draws every frame from its own loop, and nothing in the file checks whether it is on screen. Scrolled away, it keeps rendering at full rate for nobody, on the GPU the rest of the page needs.",
+      fix: "For a three.js scene, `useThreeScene` from `@vectorvesper/motion/three` draws only while the scene is on screen and keeps its context while it is away. For anything else, gate it with `useSceneGate` and stop drawing while its state is `idle`.",
+      nudge: 'Call `get_pattern("three-scene")` for the whole file.'
+    }
+  ];
+}
+function checkUncappedPixelRatio(f, file) {
+  if (f.uncappedPixelRatio.length === 0) return [];
+  return [
+    {
+      rule: "uncapped-pixel-ratio",
+      severity: "warning",
+      file,
+      line: f.uncappedPixelRatio[0],
+      message: "The renderer draws at the screen's full pixel ratio with no ceiling. A 3x phone shades nine times the pixels of a 1x screen for a difference nobody can see, and the scene never gives any of it back when the frame rate drops.",
+      fix: "Cap it, `Math.min(window.devicePixelRatio, 2)`, and lower the cap when the frame rate cannot hold. `useThreeScene` from `@vectorvesper/motion/three` does both, on the renderer it already has."
+    }
+  ];
+}
+function checkUnreleasedContext(f, file) {
+  if (f.threeRenderers.length === 0 || f.usesR3F || f.hasForceContextLoss) return [];
+  if (f.vvImports.has("useThreeScene")) return [];
+  return [
+    {
+      rule: "unreleased-context",
+      severity: "warning",
+      file,
+      line: f.threeRenderers[0],
+      message: "This renderer's WebGL context is never handed back. `dispose()` frees three's buffers and textures but not the context, which lives until the garbage collector happens to reach the canvas. Browsers cap live contexts per page and drop the oldest first, which on a landing page is usually the hero: vv-lab counted 9 left behind after six trips to another page and back.",
+      fix: "In the cleanup, remove your `webglcontextlost` listener, then call `renderer.dispose()` and `renderer.forceContextLoss()`. The listener has to come off first, or your own teardown reads as a GPU failure and rebuilds every other scene on the page. `useThreeScene` does all three."
+    }
+  ];
+}
+function checkRendererRebuild(f, file) {
+  if (f.rendererRebuilds.length === 0) return [];
+  const first = f.rendererRebuilds[0];
+  const names = first.deps.map((d) => `\`${d}\``).join(", ");
+  return [
+    {
+      rule: "renderer-rebuilt-on-change",
+      severity: "warning",
+      file,
+      line: first.line,
+      message: `This effect builds a renderer and re-runs whenever ${names} changes, so every change tears the scene down and makes a new WebGL context. Under a quality signal that moves, vv-lab watched one page go from 3 contexts to 7 in twenty seconds.`,
+      fix: "Build the renderer once, in an effect whose dependencies do not change, and apply the change to the renderer you have \u2014 `setPixelRatio`, a draw range, a uniform \u2014 reading the latest value from a ref inside the frame. `useThreeScene` does this and hands the live quality to `update`."
+    }
+  ];
+}
 function checkReducedMotion(f, file) {
-  if (f.looping.length === 0 || f.hasReducedMotionGuard) return [];
+  if (f.hasReducedMotionGuard) return [];
   if (f.vvHooks.some((v) => v.hook.runtime.respectsReducedMotion)) return [];
-  const first = f.looping[0];
+  const sceneLoop = gatedByRuntime(f) ? null : handDrawnSceneLoop(f);
+  const first = f.looping[0] ?? (sceneLoop !== null ? { line: sceneLoop, kind: "a WebGL scene drawn every frame" } : null);
+  if (!first) return [];
+  const sceneOnly = f.looping.length === 0;
   return [
     {
       rule: "no-reduced-motion",
@@ -728,7 +1059,7 @@ function checkReducedMotion(f, file) {
       file,
       line: first.line,
       message: `This file runs autonomous motion (${first.kind}) with no \`prefers-reduced-motion\` guard. Users who set that preference \u2014 often for vestibular reasons \u2014 will still see the full motion.`,
-      fix: "Gate the motion behind `window.matchMedia('(prefers-reduced-motion: reduce)')`, or drive it from a hook that self-disables."
+      fix: sceneOnly ? "For a three.js scene, `useThreeScene` from `@vectorvesper/motion/three` never builds it under reduced motion, and you show a still instead. Otherwise read `window.matchMedia('(prefers-reduced-motion: reduce)')` and draw one frame rather than a loop." : "Gate the motion behind `window.matchMedia('(prefers-reduced-motion: reduce)')`, or drive it from a hook that self-disables."
     }
   ];
 }
@@ -758,8 +1089,16 @@ async function analyzeSource(file, source, framework) {
       ...checkTransformConflict(facts, file),
       ...checkReducedMotion(facts, file),
       ...checkRenderQualityProps(facts, file),
+      ...checkAdapterPropsToWrapper(facts, file),
       ...checkContextLoss(facts, file),
-      ...checkHandRolledGate(facts, file)
+      ...checkGpuDeviceLoss(facts, file),
+      ...checkGpuDestroyReason(facts, file),
+      ...checkWebgpuClassCheck(facts, file),
+      ...checkHandRolledGate(facts, file),
+      ...checkOffscreenRender(facts, file),
+      ...checkUncappedPixelRatio(facts, file),
+      ...checkUnreleasedContext(facts, file),
+      ...checkRendererRebuild(facts, file)
     ].sort((a, b) => a.line - b.line);
     return { file, findings };
   } catch (err) {
@@ -938,6 +1277,19 @@ function formatPlan({ building, using }) {
   } else {
     const [top, ...rest] = matches;
     out.push(...renderRule(top.rule, VERDICT_HEADING[top.rule.verdict]));
+    const starter = top.rule.starter && top.rule.pattern ? manifest?.patterns?.find((p) => p.name === top.rule.pattern) : void 0;
+    if (starter) {
+      out.push(
+        "## Start from this file",
+        "",
+        `It is complete. Keep everything around the scene and replace the scene with yours: every line outside it is one of the steps above. \`get_pattern("${starter.name}")\` has the pitfalls and how to check the result.`,
+        "",
+        "```tsx",
+        starter.code,
+        "```",
+        ""
+      );
+    }
     const also = rest.filter((m) => m.rule.id !== top.rule.id).slice(0, 3);
     if (also.length > 0) {
       out.push("## Also in what you described", "");
@@ -975,7 +1327,7 @@ function formatPlan({ building, using }) {
 }
 
 // src/mcp/server.ts
-var VERSION = true ? "2.6.0" : "0.0.0-dev";
+var VERSION = true ? "2.8.0" : "0.0.0-dev";
 function text(body) {
   return { content: [{ type: "text", text: body }] };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vectorvesper",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "description": "Motion runtime and WebGL/R3F component CLI for React, with an MCP server that tells your coding agent which primitive to use, how to wire it, and when not to.",
   "type": "module",
   "license": "MIT",
@@ -58,7 +58,7 @@
     "test:mcp": "node scripts/mcp-e2e/harness.mjs --local",
     "test:mcp:published": "node scripts/mcp-e2e/harness.mjs",
     "postbuild": "node scripts/bundle-manifest.mjs",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm --prefix ../registry run build:hooks && npm run build"
   },
   "dependencies": {
     "@babel/core": "^7.24.0",