vectorvesper 2.6.0 → 2.7.0

package/dist/hooks.json

@@ -1,7 +1,7 @@
 {
   "version": "1.0.0",
   "engineVersion": "4.0.1",
-  "generatedAt": "2026-09-02T08:50:45.096Z",
+  "generatedAt": "2026-09-09T11:54:49.193Z",
   "contractLevel": "full",
   "hooks": [
     {
@@ -3686,7 +3686,14 @@
         "simulation"
       ],
       "allOf": [],
-      "unless": [],
+      "unless": [
+        "lottie",
+        "dotlottie",
+        "rive",
+        "spline",
+        "countdown",
+        "stopwatch"
+      ],
       "minHits": 1,
       "priority": 100,
       "verdict": "custom",
@@ -3962,6 +3969,94 @@
       ],
       "notWhen": "The problem is not memory but frames. If the scene is janky rather than crashing, start with `useFramePressure` to find out what is actually eating the frame before optimising anything."
     },
+    {
+      "id": "clock-and-interval",
+      "when": [
+        "countdown",
+        "count down",
+        "timer",
+        "stopwatch",
+        "every second",
+        "every few seconds",
+        "clock",
+        "poll",
+        "polling",
+        "auto refresh",
+        "refresh every",
+        "elapsed time"
+      ],
+      "allOf": [],
+      "unless": [
+        "scrub",
+        "shader",
+        "canvas",
+        "frame",
+        "particle",
+        "scroll"
+      ],
+      "minHits": 1,
+      "priority": 885,
+      "verdict": "no-runtime",
+      "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": [],
+      "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": [],
+      "notWhen": "The number itself animates rather than stepping. A total easing to a new value on the shared loop is `useNumberTicker`, and that genuinely is per-frame work."
+    },
+    {
+      "id": "third-party-animation-runtime",
+      "when": [
+        "lottie",
+        "dotlottie",
+        "rive",
+        "spline",
+        "vanta",
+        "after effects"
+      ],
+      "allOf": [],
+      "unless": [],
+      "minHits": 1,
+      "priority": 880,
+      "verdict": "no-runtime",
+      "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": [],
+      "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": [
+        "client-boundary",
+        "missing-cleanup"
+      ],
+      "notWhen": "The mount cost is the problem rather than the playback. `useSafeToMount` holds a heavy subtree until the frame can afford it, and `useSceneGate` adds the off-screen and recovery decisions on top. Both govern when the player appears without touching how it animates."
+    },
+    {
+      "id": "list-virtualisation",
+      "when": [
+        "virtualisation",
+        "virtualization",
+        "virtualised list",
+        "virtualized list",
+        "infinite scroll",
+        "windowing",
+        "react-window",
+        "long list",
+        "render thousands of rows"
+      ],
+      "allOf": [],
+      "unless": [],
+      "minHits": 1,
+      "priority": 870,
+      "verdict": "no-runtime",
+      "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": [],
+      "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": [],
+      "notWhen": "Each row runs its own frame-driven effect. A thousand rows each with a private `requestAnimationFrame` loop is a scheduling problem, and one `useTick` per row on the shared conductor is what fixes it."
+    },
     {
       "id": "per-frame-work",
       "when": [
@@ -3973,7 +4068,11 @@
         "game loop",
         "ticker",
         "frame loop",
-        "custom effect"
+        "custom effect",
+        "morph",
+        "tween",
+        "over time",
+        "frame by frame"
       ],
       "allOf": [],
       "unless": [],
@@ -4009,13 +4108,23 @@
         "follow the mouse",
         "track the cursor",
         "track the mouse",
-        "chase the cursor"
+        "chase the cursor",
+        "as you scroll",
+        "on scroll",
+        "scroll down",
+        "scroll progress",
+        "scroll offset",
+        "sticky header",
+        "shrink on scroll",
+        "scroll indicator"
       ],
       "allOf": [],
       "unless": [
         "trail",
         "magnetic",
-        "parallax"
+        "parallax",
+        "reveal",
+        "scrollytelling"
       ],
       "minHits": 1,
       "priority": 470,

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.7.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.7.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-RHYAXOSU.js");
     await mcpCommand(action, { ...options, client });
   }
 );

package/dist/{mcp-BEM4TVKM.js → mcp-RHYAXOSU.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.7.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-DVFJRSZW.js");
   try {
     await startMcpServer();
   } catch (error) {

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

@@ -148,6 +148,10 @@ function collect(ast, traverse) {
     canvases: [],
     rawGlContexts: [],
     handlesContextLoss: false,
+    gpuDevices: [],
+    gpuLostHandlers: [],
+    mentionsDestroyedReason: false,
+    webgpuClassChecks: [],
     gatingObserver: []
   };
   const reactSetters = collectReactSetters(ast, traverse);
@@ -194,6 +198,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 +217,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 +231,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 +322,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 +358,35 @@ 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":
+      case "reportHealthy":
+        f.handlesContextLoss = true;
+        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 +417,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 +478,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" });
       }
@@ -484,6 +552,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);
@@ -686,6 +770,50 @@ function checkContextLoss(f, file) {
     }
   ];
 }
+function checkGpuDeviceLoss(f, file) {
+  if (f.gpuDevices.length === 0) return [];
+  const handled = f.gpuLostHandlers.length > 0 || f.vvImports.has("watchGPUDevice") || f.vvImports.has("useRenderQuality");
+  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 [];
@@ -759,6 +887,9 @@ async function analyzeSource(file, source, framework) {
       ...checkReducedMotion(facts, file),
       ...checkRenderQualityProps(facts, file),
       ...checkContextLoss(facts, file),
+      ...checkGpuDeviceLoss(facts, file),
+      ...checkGpuDestroyReason(facts, file),
+      ...checkWebgpuClassCheck(facts, file),
       ...checkHandRolledGate(facts, file)
     ].sort((a, b) => a.line - b.line);
     return { file, findings };
@@ -975,7 +1106,7 @@ function formatPlan({ building, using }) {
 }
 
 // src/mcp/server.ts
-var VERSION = true ? "2.6.0" : "0.0.0-dev";
+var VERSION = true ? "2.7.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.7.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",