vectorvesper 2.7.0 → 2.8.1

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.7.0" : "0.0.0-dev";
+var CLI_VERSION = true ? "2.8.1" : "0.0.0-dev";
 async function infoCommand() {
   console.log(pc8.bold(pc8.cyan("\nVector Vesper Diagnostics\n")));
   const projectInfo = detectProject();
@@ -1363,8 +1363,9 @@ async function loginCommand(key) {
   console.log(`  ${pc10.green(pc10.bold("\u2714"))} Token saved \u2014 you're logged in.`);
   console.log(`  ${pc10.dim("Stored at:")} ${pc10.cyan(getGlobalConfigPath())}`);
   console.log("");
-  console.log(`  ${pc10.dim("Pro components are now available when you run")} ${pc10.cyan("npx vectorvesper add <slug>")}`);
-  console.log(`  ${pc10.dim("To verify your account:")} ${pc10.cyan("npx vectorvesper whoami")}`);
+  console.log(`  ${pc10.dim("Install a component with")} ${pc10.cyan("npx vectorvesper add <slug>")}`);
+  console.log(`  ${pc10.dim("Pro components install if your membership covers them.")}`);
+  console.log(`  ${pc10.dim("Your membership:")} ${pc10.cyan("https://vectorvesper.dev/account")}`);
   console.log("");
 }
 async function logoutCommand() {
@@ -1392,30 +1393,25 @@ async function logoutCommand() {
 async function whoamiCommand() {
   const config = loadGlobalConfig();
   console.log("");
-  console.log(pc10.bold(pc10.cyan("  Vector Vesper Account Status\n")));
+  console.log(pc10.bold(pc10.cyan("  Vector Vesper CLI\n")));
   if (config.auth?.token) {
     const maskedKey = config.auth.token.slice(0, 6) + "\u2026" + config.auth.token.slice(-4);
-    const tier = config.auth.tier || "pro";
-    console.log(`  ${pc10.bold("Status:")}   ${pc10.green("Authenticated")}`);
+    console.log(`  ${pc10.bold("Status:")}   ${pc10.green("Signed in")}`);
     console.log(`  ${pc10.bold("Token:")}    ${pc10.cyan(maskedKey)}`);
-    console.log(`  ${pc10.bold("Tier:")}     ${pc10.magenta(tier)}`);
     if (config.auth.email) {
       console.log(`  ${pc10.bold("Email:")}    ${pc10.cyan(config.auth.email)}`);
     }
-    if (config.auth.expiresAt) {
-      const expiry = new Date(config.auth.expiresAt);
-      const now = /* @__PURE__ */ new Date();
-      const isExpired = expiry < now;
-      console.log(`  ${pc10.bold("Expires:")}  ${isExpired ? pc10.red("EXPIRED") : pc10.green(expiry.toLocaleDateString())}`);
-    }
+    console.log("");
+    console.log(`  ${pc10.dim("Your membership is checked by the server each time you install.")}`);
+    console.log(`  ${pc10.dim("A Pro component arrives if it covers you, and is refused if not.")}`);
     console.log("");
     console.log(`  ${pc10.dim("Config:")} ${pc10.cyan(getGlobalConfigPath())}`);
-    console.log(`  ${pc10.dim("Manage your account at")} ${pc10.cyan("https://vectorvesper.dev/account")}`);
+    console.log(`  ${pc10.dim("See your membership at")} ${pc10.cyan("https://vectorvesper.dev/account")}`);
   } else {
-    console.log(`  ${pc10.bold("Status:")}   ${pc10.yellow("Anonymous (free tier)")}`);
+    console.log(`  ${pc10.bold("Status:")}   ${pc10.yellow("Not signed in")}`);
     console.log(`  ${pc10.bold("Access:")}   ${pc10.dim("Free components only")}`);
     console.log("");
-    console.log(`  ${pc10.dim("To unlock pro components:")}`);
+    console.log(`  ${pc10.dim("To install Pro components you have a membership for:")}`);
     console.log(`  ${pc10.cyan("npx vectorvesper login <token>")}`);
     console.log(`  \u{1F511} ${pc10.dim("Generate a token at")} ${pc10.cyan("https://vectorvesper.dev/account")}`);
   }
@@ -1423,7 +1419,7 @@ async function whoamiCommand() {
 }
 
 // src/index.ts
-var version = true ? "2.7.0" : "0.0.0-dev";
+var version = true ? "2.8.1" : "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 +1461,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-RHYAXOSU.js");
+    const { mcpCommand } = await import("./mcp-D5QWQ2PC.js");
     await mcpCommand(action, { ...options, client });
   }
 );

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

@@ -146,7 +146,7 @@ function detectClients(cwd = process.cwd()) {
 }
 
 // src/commands/mcp.ts
-var VERSION = true ? "2.7.0" : "0.0.0-dev";
+var VERSION = true ? "2.8.1" : "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-DVFJRSZW.js");
+  const { startMcpServer } = await import("./server-BEBUGQ7F.js");
   try {
     await startMcpServer();
   } catch (error) {

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

@@ -146,13 +146,23 @@ function collect(ast, traverse) {
     laneViolations: [],
     orphanSubscriptions: [],
     canvases: [],
+    adapterBindings: /* @__PURE__ */ new Set(),
+    propSpreads: [],
     rawGlContexts: [],
     handlesContextLoss: false,
     gpuDevices: [],
     gpuLostHandlers: [],
     mentionsDestroyedReason: false,
     webgpuClassChecks: [],
-    gatingObserver: []
+    gatingObserver: [],
+    threeRenderers: [],
+    uncappedPixelRatio: [],
+    animationLoops: [],
+    hasForceContextLoss: false,
+    reportsLost: false,
+    reportsHealthy: false,
+    rendererRebuilds: [],
+    hasIntersectionObserver: false
   };
   const reactSetters = collectReactSetters(ast, traverse);
   const manifest = loadHookManifest();
@@ -374,9 +384,42 @@ function collect(ast, traverse) {
       // 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;
@@ -500,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 ?? []) {
@@ -541,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);
@@ -664,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;
 }
@@ -755,24 +810,64 @@ 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()`.",
-      nudge: 'Call `get_pattern("lazy-3d-section")` for the whole wiring.'
+      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");
+  const handled = f.gpuLostHandlers.length > 0 || f.vvImports.has("watchGPUDevice") || f.vvImports.has("useRenderQuality") || f.vvImports.has("useThreeScene");
   if (handled) return [];
   return [
     {
@@ -845,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",
@@ -856,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."
     }
   ];
 }
@@ -886,11 +1089,16 @@ async function analyzeSource(file, source, framework) {
       ...checkTransformConflict(facts, file),
       ...checkReducedMotion(facts, file),
       ...checkRenderQualityProps(facts, file),
+      ...checkAdapterPropsToWrapper(facts, file),
       ...checkContextLoss(facts, file),
       ...checkGpuDeviceLoss(facts, file),
       ...checkGpuDestroyReason(facts, file),
       ...checkWebgpuClassCheck(facts, file),
-      ...checkHandRolledGate(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) {
@@ -1069,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", "");
@@ -1106,7 +1327,7 @@ function formatPlan({ building, using }) {
 }
 
 // src/mcp/server.ts
-var VERSION = true ? "2.7.0" : "0.0.0-dev";
+var VERSION = true ? "2.8.1" : "0.0.0-dev";
 function text(body) {
   return { content: [{ type: "text", text: body }] };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vectorvesper",
-  "version": "2.7.0",
+  "version": "2.8.1",
   "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",