vectorvesper 2.5.0 → 2.7.0

package/README.md

@@ -1,113 +1,113 @@
-<!--
-  BANNER: host a wide image (≈1280×640) at an ABSOLUTE url — relative paths do
-  NOT render on npmjs.com — then uncomment this block:
-
-  <p align="center">
-    <a href="https://vectorvesper.dev">
-      <img src="https://vectorvesper.dev/banner.png" alt="Vector Vesper" width="100%" />
-    </a>
-  </p>
--->
-
-<h1 align="center">Vector Vesper</h1>
-
-<p align="center">
-  Production-grade WebGL, 3D, and motion components for React. Copy directly into your codebase and own the code.
-</p>
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/vectorvesper"><img src="https://img.shields.io/npm/v/vectorvesper?color=7EACB5&label=npm" alt="npm version" /></a>
-  <a href="https://github.com/vectorvesper/vv-components/blob/main/LICENSE"><img src="https://img.shields.io/github/license/vectorvesper/vv-components?color=7EACB5&label=license" alt="license" /></a>
-  <a href="https://vectorvesper.dev"><img src="https://img.shields.io/badge/docs-vectorvesper.dev-7EACB5" alt="docs" /></a>
-</p>
-
----
-
-> Vector Vesper is a CLI you run with `npx`, not a package you install. Start with `npx vectorvesper init` below.
-
-**Vector Vesper** is a motion toolkit for React consisting of 3D animations, shaders, and advanced motion components. 
-
-The CLI writes the component code directly into your repository. You have full control over the math, the shaders, and the styles.
-
-## Quick Start
-
-```bash
-# Initialize project configuration
-npx vectorvesper init
-
-# Add a visual component
-npx vectorvesper add video-card
-```
-
-The CLI auto-detects your workspace, installs required animation dependencies (such as `three`, `@react-three/fiber`, or `gsap`), and writes the code to `@/components/vv/`.
-
-```tsx
-import { VideoCard } from "@/components/vv/video-card";
-
-export default function Page() {
-  return (
-    <div className="h-screen w-full">
-      <VideoCard src="/clip.mp4" />
-    </div>
-  );
-}
-```
-
-## MCP server — motion advice for your coding agent
-
-The same CLI runs as an [MCP](https://modelcontextprotocol.io) server, so Claude Code, Cursor, Copilot and friends can ask about motion before they write it.
-
-```bash
-npx vectorvesper mcp install
-```
-
-That configures every supported editor it finds. Restart the editor and run `npx vectorvesper mcp status` to confirm. No account or token is needed — the runtime, its contracts and the linter are free.
-
-**Why bother.** Bad motion code does not error. TypeScript passes, the build is green, and the page janks on a mid-range phone six weeks later with nothing connecting the two. An agent has no feedback signal for the one quality dimension that matters here, so this server gives it three:
-
-- **`plan_motion`** — describe what you are building and get told whether it needs a primitive **at all**, which ones, in what order, and when that advice would be wrong. It says "use CSS, not this" for a hover state, a fade on mount, a spinner or a one-time scroll reveal, because those are compositor features that cost no main-thread time. Roughly a fifth of its answers recommend the platform over this library.
-- **`get_hook` / `get_pattern` / `get_component`** — the contract, not the source. Does this need a client boundary, does it own the element's transform, what does it conflict with, which frame lane does it run in, and when should you not use it.
-- **`check_motion`** — a static linter for the failure class that ships silently: a private `requestAnimationFrame` loop outside the shared budget, a discarded unsubscribe, `setState` in a frame callback, layout read in the write lane, one transform with two owners, a `<Canvas>` prop that quietly overrules the adapter that set it, a WebGL scene with nothing watching for a lost context, motion with no reduced-motion guard.
-
-Prefer to wire it by hand? Add this to your client's MCP config:
-
-```json
-{
-  "mcpServers": {
-    "vectorvesper": {
-      "command": "npx",
-      "args": ["-y", "vectorvesper", "mcp"]
-    }
-  }
-}
-```
-
-Full setup notes and the per-client config paths: [vectorvesper.dev/docs/mcp](https://vectorvesper.dev/docs/mcp).
-
-## CLI Command Reference
-
-| Command | Description |
-| --- | --- |
-| `init` | Detect project setup and write `vv.config.json` |
-| `add <slug>` | Add a component and auto-install its dependencies |
-| `list` | List all available components in the registry |
-| `update [slug]` | Update installed components to the latest version |
-| `diff [slug]` | Check local files against registry updates |
-| `remove <slug>` | Safely remove a component's files from the project |
-| `mcp install [client]` | Configure the MCP server for your editor(s) |
-| `mcp status` | Check which clients are wired up |
-| `mcp` | Run the MCP server on stdio (what the editor invokes) |
-| `info` | Output workspace diagnostics for troubleshooting |
-
-Works out of the box with **npm, pnpm, yarn, and bun** by checking your lockfile.
-
-## Links
-
-* **Documentation & Guides:** [vectorvesper.dev/docs](https://vectorvesper.dev/docs)
-* **Visual Component Catalog:** [vectorvesper.dev/components](https://vectorvesper.dev/components)
-* **GitHub Repository:** [github.com/vectorvesper/vv-components](https://github.com/vectorvesper/vv-components)
-* **Report Issues:** [github.com/vectorvesper/vv-components/issues](https://github.com/vectorvesper/vv-components/issues)
-
----
-
-Licensed under the MIT License for open-source components. Premium/commercial components are subject to the Vector Vesper terms of service.
+<!--
+  BANNER: host a wide image (≈1280×640) at an ABSOLUTE url — relative paths do
+  NOT render on npmjs.com — then uncomment this block:
+
+  <p align="center">
+    <a href="https://vectorvesper.dev">
+      <img src="https://vectorvesper.dev/banner.png" alt="Vector Vesper" width="100%" />
+    </a>
+  </p>
+-->
+
+<h1 align="center">Vector Vesper</h1>
+
+<p align="center">
+  Production-grade WebGL, 3D, and motion components for React. Copy directly into your codebase and own the code.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/vectorvesper"><img src="https://img.shields.io/npm/v/vectorvesper?color=7EACB5&label=npm" alt="npm version" /></a>
+  <a href="https://github.com/vectorvesper/vv-components/blob/main/LICENSE"><img src="https://img.shields.io/github/license/vectorvesper/vv-components?color=7EACB5&label=license" alt="license" /></a>
+  <a href="https://vectorvesper.dev"><img src="https://img.shields.io/badge/docs-vectorvesper.dev-7EACB5" alt="docs" /></a>
+</p>
+
+---
+
+> Vector Vesper is a CLI you run with `npx`, not a package you install. Start with `npx vectorvesper init` below.
+
+**Vector Vesper** is a motion toolkit for React consisting of 3D animations, shaders, and advanced motion components. 
+
+The CLI writes the component code directly into your repository. You have full control over the math, the shaders, and the styles.
+
+## Quick Start
+
+```bash
+# Initialize project configuration
+npx vectorvesper init
+
+# Add a visual component
+npx vectorvesper add video-card
+```
+
+The CLI auto-detects your workspace, installs required animation dependencies (such as `three`, `@react-three/fiber`, or `gsap`), and writes the code to `@/components/vv/`.
+
+```tsx
+import { VideoCard } from "@/components/vv/video-card";
+
+export default function Page() {
+  return (
+    <div className="h-screen w-full">
+      <VideoCard src="/clip.mp4" />
+    </div>
+  );
+}
+```
+
+## MCP server — motion advice for your coding agent
+
+The same CLI runs as an [MCP](https://modelcontextprotocol.io) server, so Claude Code, Cursor, Copilot and friends can ask about motion before they write it.
+
+```bash
+npx vectorvesper mcp install
+```
+
+That configures every supported editor it finds. Restart the editor and run `npx vectorvesper mcp status` to confirm. No account or token is needed — the runtime, its contracts and the linter are free.
+
+**Why bother.** Bad motion code does not error. TypeScript passes, the build is green, and the page janks on a mid-range phone six weeks later with nothing connecting the two. An agent has no feedback signal for the one quality dimension that matters here, so this server gives it three:
+
+- **`plan_motion`** — describe what you are building and get told whether it needs a primitive **at all**, which ones, in what order, and when that advice would be wrong. It says "use CSS, not this" for a hover state, a fade on mount, a spinner or a one-time scroll reveal, because those are compositor features that cost no main-thread time. Roughly a fifth of its answers recommend the platform over this library.
+- **`get_hook` / `get_pattern` / `get_component`** — the contract, not the source. Does this need a client boundary, does it own the element's transform, what does it conflict with, which frame lane does it run in, and when should you not use it.
+- **`check_motion`** — a static linter for the failure class that ships silently: a private `requestAnimationFrame` loop outside the shared budget, a discarded unsubscribe, `setState` in a frame callback, layout read in the write lane, one transform with two owners, a `<Canvas>` prop that quietly overrules the adapter that set it, a WebGL scene with nothing watching for a lost context, motion with no reduced-motion guard.
+
+Prefer to wire it by hand? Add this to your client's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "vectorvesper": {
+      "command": "npx",
+      "args": ["-y", "vectorvesper", "mcp"]
+    }
+  }
+}
+```
+
+Full setup notes and the per-client config paths: [vectorvesper.dev/docs/mcp](https://vectorvesper.dev/docs/mcp).
+
+## CLI Command Reference
+
+| Command | Description |
+| --- | --- |
+| `init` | Detect project setup and write `vv.config.json` |
+| `add <slug>` | Add a component and auto-install its dependencies |
+| `list` | List all available components in the registry |
+| `update [slug]` | Update installed components to the latest version |
+| `diff [slug]` | Check local files against registry updates |
+| `remove <slug>` | Safely remove a component's files from the project |
+| `mcp install [client]` | Configure the MCP server for your editor(s) |
+| `mcp status` | Check which clients are wired up |
+| `mcp` | Run the MCP server on stdio (what the editor invokes) |
+| `info` | Output workspace diagnostics for troubleshooting |
+
+Works out of the box with **npm, pnpm, yarn, and bun** by checking your lockfile.
+
+## Links
+
+* **Documentation & Guides:** [vectorvesper.dev/docs](https://vectorvesper.dev/docs)
+* **Visual Component Catalog:** [vectorvesper.dev/components](https://vectorvesper.dev/components)
+* **GitHub Repository:** [github.com/vectorvesper/vv-components](https://github.com/vectorvesper/vv-components)
+* **Report Issues:** [github.com/vectorvesper/vv-components/issues](https://github.com/vectorvesper/vv-components/issues)
+
+---
+
+Licensed under the MIT License for open-source components. Premium/commercial components are subject to the Vector Vesper terms of service.

package/dist/{chunk-5YSVDVLK.js → chunk-BI3LEGXE.js}

@@ -4,7 +4,7 @@ import {
   getAuthToken,
   logger,
   validateSlug
-} from "./chunk-SFP5K3ZO.js";
+} from "./chunk-ZFHVMCR6.js";
 
 // src/utils/project.ts
 import fs from "fs";

package/dist/{chunk-SFP5K3ZO.js → chunk-ZFHVMCR6.js}

@@ -130,7 +130,7 @@ var VVConfigSchema = z.object({
   })
 });
 var VVGlobalConfigSchema = z.object({
-  // Auth — license key for paid components
+  // Auth — access token for paid components
   auth: z.object({
     token: z.string().optional(),
     email: z.string().optional(),

package/dist/hooks.json

@@ -1,7 +1,7 @@
 {
   "version": "1.0.0",
-  "engineVersion": "4.0.0",
-  "generatedAt": "2026-08-29T13:09:19.680Z",
+  "engineVersion": "4.0.1",
+  "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

@@ -3,7 +3,7 @@ import {
   detectProject,
   fetchComponent,
   fetchRegistryIndex
-} from "./chunk-5YSVDVLK.js";
+} from "./chunk-BI3LEGXE.js";
 import {
   getAuthToken,
   getGlobalConfigPath,
@@ -15,7 +15,7 @@ import {
   setVerbose,
   validateSlug,
   writeConfig
-} from "./chunk-SFP5K3ZO.js";
+} from "./chunk-ZFHVMCR6.js";
 
 // src/index.ts
 import { Command } from "commander";
@@ -295,7 +295,7 @@ async function listCommand() {
     console.log(`
   ${pc2.green(String(freeCount))} free components${proCount > 0 ? ` \xB7 ${pc2.magenta(String(proCount))} pro components` : ""}`);
     if (proCount > 0 && !hasAuth) {
-      console.log(`  \u{1F511} ${pc2.dim("Unlock pro components:")} ${pc2.cyan("npx vectorvesper login <key>")} ${pc2.dim("\xB7")} ${pc2.cyan("https://vectorvesper.dev/pricing")}`);
+      console.log(`  \u{1F511} ${pc2.dim("Unlock pro components:")} ${pc2.cyan("npx vectorvesper login <token>")} ${pc2.dim("\xB7")} ${pc2.cyan("https://vectorvesper.dev/pricing")}`);
     }
     console.log(`
 \u{1F449} Run ${pc2.bold(pc2.cyan("npx vectorvesper add <slug>"))} to add a component to your project.
@@ -303,7 +303,8 @@ async function listCommand() {
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     spinner.fail(pc2.red(`Failed to fetch components list: ${message}`));
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
 }
 
@@ -758,7 +759,7 @@ async function addCommand(slug, options = {}) {
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     spinner.fail(pc5.red(`Failed to resolve component "${slug}": ${message}`));
-    process.exit(1);
+    process.exitCode = 1;
     return;
   }
   let transpileWarnings = [];
@@ -780,7 +781,7 @@ async function addCommand(slug, options = {}) {
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     spinner.fail(pc5.red(message));
-    process.exit(1);
+    process.exitCode = 1;
     return;
   }
   const filesToWrite = [];
@@ -856,7 +857,7 @@ async function addCommand(slug, options = {}) {
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     spinner.fail(pc5.red(`Failed to write files: ${message}`));
-    process.exit(1);
+    process.exitCode = 1;
     return;
   }
   try {
@@ -1018,7 +1019,7 @@ async function updateCommand(slug, options = {}) {
   if (updatedComponents.length > 0) {
     await handleDependencies(updatedComponents, projectRoot, projectInfo, options);
   }
-  if (failed.length > 0) process.exit(1);
+  if (failed.length > 0) process.exitCode = 1;
 }
 
 // src/commands/remove.ts
@@ -1122,7 +1123,7 @@ Remove ${slug}
 import fs7 from "fs";
 import path7 from "path";
 import pc8 from "picocolors";
-var CLI_VERSION = true ? "2.5.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();
@@ -1255,7 +1256,8 @@ Component Diff: ${slug}`)));
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       spinner.fail(pc9.red(`Failed to fetch remote component details: ${message}`));
-      process.exit(1);
+      process.exitCode = 1;
+      return;
     }
   } else {
     const spinner = ora4({
@@ -1320,7 +1322,8 @@ ${pc9.green("\u2714")} All components are up to date!
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       spinner.fail(pc9.red(`Failed to check updates: ${message}`));
-      process.exit(1);
+      process.exitCode = 1;
+      return;
     }
   }
 }
@@ -1420,7 +1423,7 @@ async function whoamiCommand() {
 }
 
 // src/index.ts
-var version = true ? "2.5.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();
@@ -1449,20 +1452,20 @@ program.command("info").description("Show project diagnostics and list installed
 program.command("diff [slug]").description("Check for updates against the component registry").action(async (slug) => {
   await diffCommand(slug);
 });
-program.command("login <key>", { hidden: true }).description("Authenticate with a license key for pro components").action(async (key) => {
+program.command("login <token>").description("Authenticate with an access token for pro components").action(async (key) => {
   await loginCommand(key);
 });
-program.command("logout", { hidden: true }).description("Clear stored license credentials").action(async () => {
+program.command("logout").description("Clear the stored access token").action(async () => {
   await logoutCommand();
 });
-program.command("whoami", { hidden: true }).description("Show current authentication status").action(async () => {
+program.command("whoami").description("Show current authentication status").action(async () => {
   await whoamiCommand();
 });
 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-QHRDHAME.js");
+    const { mcpCommand } = await import("./mcp-RHYAXOSU.js");
     await mcpCommand(action, { ...options, client });
   }
 );

package/dist/{mcp-QHRDHAME.js → mcp-RHYAXOSU.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-CPZKZO3A.js";
 import {
   getAuthToken
-} from "./chunk-SFP5K3ZO.js";
+} from "./chunk-ZFHVMCR6.js";
 
 // src/commands/mcp.ts
 import pc from "picocolors";
@@ -146,7 +146,7 @@ function detectClients(cwd = process.cwd()) {
 }
 
 // src/commands/mcp.ts
-var VERSION = true ? "2.5.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-ENS44LZV.js");
+  const { startMcpServer } = await import("./server-DVFJRSZW.js");
   try {
     await startMcpServer();
   } catch (error) {

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

@@ -1,7 +1,7 @@
 import {
   detectProject,
   fetchRegistryIndex
-} from "./chunk-5YSVDVLK.js";
+} from "./chunk-BI3LEGXE.js";
 import {
   findHook,
   findPattern,
@@ -9,7 +9,7 @@ import {
 } from "./chunk-CPZKZO3A.js";
 import {
   getAuthToken
-} from "./chunk-SFP5K3ZO.js";
+} from "./chunk-ZFHVMCR6.js";
 
 // src/mcp/server.ts
 import { z } from "zod";
@@ -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.5.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,81 +1,81 @@
-{
-  "name": "vectorvesper",
-  "version": "2.5.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",
-  "main": "./dist/index.js",
-  "bin": {
-    "vectorvesper": "dist/index.js",
-    "vv": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "package.json"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/vectorvesper/vv-components.git"
-  },
-  "bugs": {
-    "url": "https://github.com/vectorvesper/vv-components/issues"
-  },
-  "homepage": "https://vectorvesper.dev",
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "mcp-server",
-    "ai",
-    "agent",
-    "claude",
-    "cursor",
-    "copilot",
-    "react",
-    "webgl",
-    "three",
-    "threejs",
-    "react-three-fiber",
-    "components",
-    "cli",
-    "ui",
-    "animation",
-    "motion",
-    "gsap",
-    "shader",
-    "interactive",
-    "performance",
-    "requestanimationframe"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "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"
-  },
-  "dependencies": {
-    "@babel/core": "^7.24.0",
-    "@babel/preset-typescript": "^7.24.0",
-    "@clack/prompts": "^0.7.0",
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "commander": "^12.0.0",
-    "ora": "^8.0.1",
-    "picocolors": "^1.0.0",
-    "zod": "^3.22.4"
-  },
-  "devDependencies": {
-    "@types/babel__core": "^7.20.5",
-    "@types/node": "^25.9.2",
-    "tsup": "^8.0.2",
-    "typescript": "^6.0.3",
-    "vitest": "^2.1.8"
-  },
-  "mcpName": "dev.vectorvesper/motion"
-}
+{
+  "name": "vectorvesper",
+  "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",
+  "main": "./dist/index.js",
+  "bin": {
+    "vectorvesper": "dist/index.js",
+    "vv": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "package.json"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vectorvesper/vv-components.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vectorvesper/vv-components/issues"
+  },
+  "homepage": "https://vectorvesper.dev",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mcp-server",
+    "ai",
+    "agent",
+    "claude",
+    "cursor",
+    "copilot",
+    "react",
+    "webgl",
+    "three",
+    "threejs",
+    "react-three-fiber",
+    "components",
+    "cli",
+    "ui",
+    "animation",
+    "motion",
+    "gsap",
+    "shader",
+    "interactive",
+    "performance",
+    "requestanimationframe"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "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"
+  },
+  "dependencies": {
+    "@babel/core": "^7.24.0",
+    "@babel/preset-typescript": "^7.24.0",
+    "@clack/prompts": "^0.7.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "commander": "^12.0.0",
+    "ora": "^8.0.1",
+    "picocolors": "^1.0.0",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/babel__core": "^7.20.5",
+    "@types/node": "^25.9.2",
+    "tsup": "^8.0.2",
+    "typescript": "^6.0.3",
+    "vitest": "^2.1.8"
+  },
+  "mcpName": "dev.vectorvesper/motion"
+}