vectorvesper 2.0.7 → 2.1.1

package/dist/index.js

@@ -993,7 +993,7 @@ Remove ${slug}
 import fs6 from "fs";
 import path6 from "path";
 import pc8 from "picocolors";
-var CLI_VERSION = true ? "2.0.7" : "0.0.0-dev";
+var CLI_VERSION = true ? "2.1.1" : "0.0.0-dev";
 async function infoCommand() {
   console.log(pc8.bold(pc8.cyan("\nVector Vesper Diagnostics\n")));
   const projectInfo = detectProject();
@@ -1291,7 +1291,7 @@ async function whoamiCommand() {
 }
 
 // src/index.ts
-var version = true ? "2.0.7" : "0.0.0-dev";
+var version = true ? "2.1.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();
@@ -1330,7 +1330,7 @@ program.command("whoami", { hidden: true }).description("Show current authentica
   await whoamiCommand();
 });
 program.command("mcp [action]").description("Run as an MCP server (stdio) for AI coding agents. `vv mcp status` checks the setup.").option("--stdio", "Force server mode even from an interactive terminal").action(async (action, options) => {
-  const { mcpCommand } = await import("./mcp-NVM7DS5P.js");
+  const { mcpCommand } = await import("./mcp-FCM3FZSK.js");
   await mcpCommand(action, options);
 });
 process.on("unhandledRejection", (error) => {

package/dist/{mcp-NVM7DS5P.js → mcp-FCM3FZSK.js}

@@ -1,13 +1,13 @@
 import {
   loadHookManifest
-} from "./chunk-XN3PPCIM.js";
+} from "./chunk-CPZKZO3A.js";
 import {
   getAuthToken
 } from "./chunk-SFP5K3ZO.js";
 
 // src/commands/mcp.ts
 import pc from "picocolors";
-var VERSION = true ? "2.0.7" : "0.0.0-dev";
+var VERSION = true ? "2.1.1" : "0.0.0-dev";
 var CONFIG_SNIPPET = `{
   "mcpServers": {
     "vectorvesper": {
@@ -33,7 +33,14 @@ function printStatus() {
   console.log(pc.bold(pc.cyan("  Vector Vesper MCP\n")));
   console.log(`  ${pc.bold("CLI version:")}   ${VERSION}`);
   if (manifest) {
-    console.log(`  ${ok(`Hook manifest: ${manifest.hooks.length} hooks, engine v${manifest.engineVersion}`)}`);
+    const hookCount = manifest.hooks.filter((h) => h.category !== "core").length;
+    const coreCount = manifest.hooks.length - hookCount;
+    const patternCount = manifest.patterns?.length ?? 0;
+    console.log(
+      `  ${ok(
+        `Hook manifest: ${hookCount} hooks, ${coreCount} core primitives, ${patternCount} patterns, engine v${manifest.engineVersion}`
+      )}`
+    );
     console.log(`  ${pc.dim(`Contract level: ${manifest.contractLevel}`)}`);
   } else {
     console.log(`  ${bad("Hook manifest: MISSING")}`);
@@ -53,7 +60,7 @@ function printStatus() {
   console.log("");
   console.log(
     pc.dim(
-      "  Tools: list_hooks \xB7 get_hook \xB7 list_components \xB7 get_component \xB7 get_setup_guidance \xB7 search \xB7 check_motion"
+      "  Tools: list_hooks \xB7 get_hook \xB7 list_patterns \xB7 get_pattern \xB7 list_components \xB7 get_component \xB7 get_setup_guidance \xB7 search \xB7 check_motion"
     )
   );
   console.log("");
@@ -67,7 +74,7 @@ function printInteractiveHelp() {
   console.log("  started from a terminal it would just wait for a client that never connects.");
   console.log("");
   console.log(`  ${pc.bold("Check your setup:")}  ${pc.cyan("vv mcp status")}`);
-  console.log(`  ${pc.bold("Add to Claude Code:")} ${pc.cyan("claude mcp add vectorvesper -- npx -y vectorvesper mcp")}`);
+  console.log(`  ${pc.bold("Add to Claude Code:")} ${pc.cyan("claude mcp add vectorvesper -- npx -y vectorvesper@latest mcp")}`);
   console.log("");
   console.log(pc.dim("  To run the server here anyway (for debugging): vv mcp --stdio"));
   console.log("");
@@ -94,7 +101,7 @@ ${pc.red("\u2717")} Unknown argument "${action}" for \`vv mcp\`.
     return;
   }
   protectStdout();
-  const { startMcpServer } = await import("./server-LJL6ZBE3.js");
+  const { startMcpServer } = await import("./server-WQ564YNA.js");
   try {
     await startMcpServer();
   } catch (error) {

package/dist/{server-LJL6ZBE3.js → server-WQ564YNA.js}

@@ -4,8 +4,9 @@ import {
 } from "./chunk-5YSVDVLK.js";
 import {
   findHook,
+  findPattern,
   loadHookManifest
-} from "./chunk-XN3PPCIM.js";
+} from "./chunk-CPZKZO3A.js";
 import {
   getAuthToken
 } from "./chunk-SFP5K3ZO.js";
@@ -50,6 +51,8 @@ function collect(ast, traverse) {
     usesUseGSAP: false,
     usesR3F: false,
     raf: [],
+    rafSelfScheduling: [],
+    rafUnresolved: 0,
     hasCancelRaf: false,
     addEventListener: [],
     hasRemoveEventListener: false,
@@ -112,10 +115,14 @@ function collect(ast, traverse) {
     const line = node.loc?.start.line ?? 0;
     const argPaths = typeof p.get === "function" ? p.get("arguments") : [];
     switch (name) {
-      case "requestAnimationFrame":
+      case "requestAnimationFrame": {
         f.raf.push(line);
-        scanHotCallback(resolveFunction(argPaths[0]), "a requestAnimationFrame loop", true);
+        const cb = resolveFunction(argPaths[0]);
+        if (!cb) f.rafUnresolved++;
+        else if (callbackSchedulesAnotherFrame(cb, traverse)) f.rafSelfScheduling.push(line);
+        scanHotCallback(cb, "a requestAnimationFrame loop", true);
         break;
+      }
       case "cancelAnimationFrame":
         f.hasCancelRaf = true;
         break;
@@ -210,6 +217,9 @@ function collect(ast, traverse) {
     },
     Identifier(p) {
       const name = p.node.name;
+      if (/^(reducedMotion|prefersReducedMotion|prefersReduced)$/.test(name)) {
+        f.hasReducedMotionGuard = true;
+      }
       if (!BROWSER_GLOBALS.has(name)) return;
       if (fnDepth !== 0) return;
       const parent = p.parent;
@@ -264,8 +274,27 @@ function checkClientBoundary(f, file, framework) {
   }
   return out;
 }
+function callbackSchedulesAnotherFrame(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: [] } },
+    {
+      CallExpression(p) {
+        if (calleeName(p.node.callee) === "requestAnimationFrame") found = true;
+      },
+      OptionalCallExpression(p) {
+        if (calleeName(p.node.callee) === "requestAnimationFrame") found = true;
+      }
+    }
+  );
+  return found;
+}
 function isRafLoop(f) {
-  return f.raf.length >= 2;
+  return f.rafSelfScheduling.length > 0 || f.rafUnresolved >= 2;
 }
 function checkOrphanRaf(f, file) {
   if (!isRafLoop(f)) return [];
@@ -274,8 +303,10 @@ function checkOrphanRaf(f, file) {
       rule: "orphan-raf",
       severity: "warning",
       file,
-      line: f.raf[0],
-      message: `This file runs its own \`requestAnimationFrame\` loop${f.raf.length > 1 ? ` (\xD7${f.raf.length})` : ""}. Independent loops each schedule their own frame and cannot shed work under load \u2014 the coordination the runtime exists to provide is lost.`,
+      // Point at the self-scheduling call when we found one — that is the loop
+      // itself, not merely the first rAF in the file.
+      line: f.rafSelfScheduling[0] ?? f.raf[0],
+      message: `This file runs its own \`requestAnimationFrame\` loop${f.rafSelfScheduling.length > 1 ? ` (\xD7${f.rafSelfScheduling.length})` : ""}. Independent loops each schedule their own frame and cannot shed work under load \u2014 the coordination the runtime exists to provide is lost.`,
       fix: "Drive the animation from the shared conductor (`getConductor().subscribe(...)` in `@vectorvesper/motion`) or a hook that already joins it, so it shares one frame budget.",
       nudge: "Call `list_hooks` \u2014 a sensor or governor primitive may already cover this without a hand-written loop."
     }
@@ -399,7 +430,7 @@ async function checkMotionFiles(files, cwd) {
 }
 
 // src/mcp/server.ts
-var VERSION = true ? "2.0.7" : "0.0.0-dev";
+var VERSION = true ? "2.1.1" : "0.0.0-dev";
 function text(body) {
   return { content: [{ type: "text", text: body }] };
 }
@@ -584,6 +615,41 @@ ${c.docsUrl}`);
   );
   return out.join("\n");
 }
+function formatPatternSummary(p) {
+  return `**${p.name}** \u2014 ${p.tagline}
+  Composes: ${p.uses.map((u) => `\`${u}\``).join(" + ")}`;
+}
+function formatPatternDetail(p) {
+  const out = [];
+  out.push(`# ${p.title} \`${p.name}\``);
+  out.push(`> ${p.tagline}`);
+  out.push("");
+  out.push(`**The problem it removes:** ${p.problem}`);
+  out.push("");
+  out.push(
+    `**Composes:** ${p.uses.map((u) => `\`${u}\``).join(" + ")} \u2014 call \`get_hook\` on any of these you have not already read; the pattern assumes their contracts.`
+  );
+  out.push("\n## Wiring order");
+  p.wiring.forEach((step, i) => out.push(`${i + 1}. ${step}`));
+  out.push("\n## Complete example");
+  out.push("```tsx");
+  out.push(p.code);
+  out.push("```");
+  out.push("\n## Pitfalls");
+  for (const pit of p.pitfalls) {
+    const caught = pit.rule ? ` *(caught by \`check_motion\`: ${pit.rule})*` : "";
+    out.push(`- **${pit.mistake}** \u2014 ${pit.consequence}${caught}`);
+  }
+  out.push("\n## Verify");
+  p.verify.forEach((step, i) => out.push(`${i + 1}. ${step}`));
+  if (p.docsUrl) out.push(`
+## Docs
+${p.docsUrl}`);
+  out.push(
+    "\n---\n**After writing your version, run `check_motion` on the file(s).** The pitfalls above are the findings it looks for; a clean report is how you confirm the composition held."
+  );
+  return out.join("\n");
+}
 function severityMark(s) {
   return s === "error" ? "\u2717 error" : s === "warning" ? "\u25B2 warning" : "\xB7 note";
 }
@@ -629,10 +695,10 @@ async function registerTools(server) {
   server.registerTool(
     "list_hooks",
     {
-      title: "List motion hooks",
-      description: "List every React hook in the @vectorvesper/motion runtime, with the problem each one solves. Start here when deciding which primitive fits a motion task.",
+      title: "List motion hooks and core primitives",
+      description: "List every React hook in the @vectorvesper/motion runtime, with the problem each one solves, plus the core primitives (frame conductor, sensor bus, math, devtools) that custom effects are built on. Start here when deciding which primitive fits a motion task.",
       inputSchema: {
-        category: z.enum(["sensor", "governor", "gate", "interaction", "media", "effect"]).optional().describe("Filter to one category.")
+        category: z.enum(["sensor", "governor", "gate", "interaction", "media", "effect", "core"]).optional().describe('Filter to one category. "core" lists the custom-effect primitives.')
       }
     },
     async ({ category }) => {
@@ -642,16 +708,32 @@ async function registerTools(server) {
           "Hook manifest unavailable \u2014 this CLI build is missing dist/hooks.json. Reinstall with `npm i -g vectorvesper@latest`."
         );
       }
-      const hooks = category ? manifest.hooks.filter((h) => h.category === category) : manifest.hooks;
-      if (!hooks.length) return text(`No hooks in category "${category}".`);
-      const body = [
-        `${hooks.length} hook${hooks.length === 1 ? "" : "s"} in @vectorvesper/motion v${manifest.engineVersion}`,
-        "",
-        ...hooks.map(formatHookSummary),
+      const all = category ? manifest.hooks.filter((h) => h.category === category) : manifest.hooks;
+      if (!all.length) return text(`No hooks in category "${category}".`);
+      const reactHooks = all.filter((h) => h.category !== "core");
+      const core = all.filter((h) => h.category === "core");
+      const patternCount = manifest.patterns?.length ?? 0;
+      const lines = [];
+      if (reactHooks.length) {
+        lines.push(
+          `${reactHooks.length} hook${reactHooks.length === 1 ? "" : "s"} in @vectorvesper/motion v${manifest.engineVersion}`,
+          "",
+          ...reactHooks.map(formatHookSummary)
+        );
+      }
+      if (core.length) {
+        if (lines.length) lines.push("");
+        lines.push(
+          `**Core primitives** \u2014 the layer custom effects are built on. Never start a private requestAnimationFrame loop; subscribe to the conductor instead.`,
+          "",
+          ...core.map(formatHookSummary)
+        );
+      }
+      lines.push(
         "",
-        "Call `get_hook` for the full contract of any of these before writing code with it."
-      ].join("\n");
-      return text(body);
+        "Call `get_hook` for the full contract of any of these before writing code with it." + (patternCount > 0 ? ` For compositions \u2014 scrollytelling, predictive cards, custom effects \u2014 call \`list_patterns\` (${patternCount} available).` : "")
+      );
+      return text(lines.join("\n"));
     }
   );
   server.registerTool(
@@ -673,6 +755,53 @@ async function registerTools(server) {
       return text(formatHookDetail(hook));
     }
   );
+  server.registerTool(
+    "list_patterns",
+    {
+      title: "List composition patterns",
+      description: "List the composition patterns \u2014 hooks and core primitives wired together into things people build: scrollytelling video, predictive media cards, adaptive shader heroes, custom frame effects. Use these when a task combines primitives, or when no single hook covers it; a pattern carries the wiring order, complete code, the pitfalls (each mapped to the check_motion rule that catches it), and how to verify the result.",
+      inputSchema: {}
+    },
+    async () => {
+      const manifest = loadHookManifest();
+      if (!manifest) {
+        return text(
+          "Hook manifest unavailable \u2014 this CLI build is missing dist/hooks.json. Reinstall with `npm i -g vectorvesper@latest`."
+        );
+      }
+      const patterns = manifest.patterns ?? [];
+      if (!patterns.length) {
+        return text("This manifest carries no patterns. Reinstall with `npm i -g vectorvesper@latest`.");
+      }
+      const body = [
+        `${patterns.length} composition pattern${patterns.length === 1 ? "" : "s"} (engine v${manifest.engineVersion})`,
+        "",
+        ...patterns.map(formatPatternSummary),
+        "",
+        "Call `get_pattern` for the wiring order, complete code, pitfalls, and verification steps. Building something none of these cover? Start from `custom-frame-effect` \u2014 it is the canonical skeleton every custom effect follows."
+      ].join("\n");
+      return text(body);
+    }
+  );
+  server.registerTool(
+    "get_pattern",
+    {
+      title: "Get a composition pattern",
+      description: "Full recipe for one composition: the primitives it combines, the wiring order, one complete runnable example, the pitfalls (each naming the check_motion rule that catches it), and the verification steps. Read this BEFORE writing a multi-primitive feature \u2014 and read `custom-frame-effect` before building any effect the hooks do not cover.",
+      inputSchema: {
+        name: z.string().describe('Pattern name, e.g. "scrollytelling-video" or "custom-frame-effect".')
+      }
+    },
+    async ({ name }) => {
+      const pattern = findPattern(name);
+      if (!pattern) {
+        const manifest = loadHookManifest();
+        const available = manifest?.patterns?.map((p) => p.name).join(", ") ?? "none loaded";
+        return text(`No pattern named "${name}". Available: ${available}`);
+      }
+      return text(formatPatternDetail(pattern));
+    }
+  );
   server.registerTool(
     "list_components",
     {
@@ -779,8 +908,8 @@ Hook discovery still works offline \u2014 try \`list_hooks\`.`
   server.registerTool(
     "search",
     {
-      title: "Search hooks and components",
-      description: 'Keyword search across both motion hooks and installable components. Use this when you know the effect you want ("magnetic button", "scroll video", "lazy 3d scene") but not which primitive provides it.',
+      title: "Search primitives, patterns and components",
+      description: 'Keyword search across everything: React hooks, the core primitives, multi-hook composition patterns, and installable components. Use this when you know the effect you want ("magnetic button", "scroll video", "lazy 3d scene") but not which primitive provides it. A **pattern** result is usually the one to follow for anything combining two or more primitives \u2014 it carries the wiring order and the failure modes that using each hook correctly in isolation still gets wrong.',
       inputSchema: { query: z.string().describe("What you are trying to build.") }
     },
     async ({ query }) => {
@@ -794,8 +923,17 @@ Hook discovery still works offline \u2014 try \`list_hooks\`.`
       const results = [];
       const manifest = loadHookManifest();
       for (const h of manifest?.hooks ?? []) {
-        const s = score([h.name, h.tagline, h.problem, h.summary, h.category].join(" "));
-        if (s > 0) results.push({ score: s, line: `**hook** \`${h.name}\` \u2014 ${h.tagline}` });
+        const kind = h.category === "core" ? "core" : "hook";
+        const s = score(
+          [h.name, h.tagline, h.problem, h.summary, h.category, ...h.aliases ?? [], ...h.exports ?? []].join(" ")
+        );
+        if (s > 0) results.push({ score: s, line: `**${kind}** \`${h.name}\` \u2014 ${h.tagline}` });
+      }
+      for (const p of manifest?.patterns ?? []) {
+        const s = score(
+          [p.name, p.title, p.tagline, p.problem, ...p.aliases ?? [], ...p.uses].join(" ")
+        );
+        if (s > 0) results.push({ score: s, line: `**pattern** \`${p.name}\` \u2014 ${p.tagline}` });
       }
       try {
         const index = await fetchRegistryIndex();
@@ -819,7 +957,7 @@ Hook discovery still works offline \u2014 try \`list_hooks\`.`
           "",
           ...results.slice(0, 12).map((r) => r.line),
           "",
-          "Then call `get_hook` or `get_component` for the full contract before writing code."
+          "Then call `get_hook`, `get_pattern`, or `get_component` for the full contract before writing code."
         ].join("\n")
       );
     }
@@ -848,7 +986,7 @@ async function startMcpServer() {
   const server = new McpServerCtor(
     { name: "vectorvesper", version: VERSION },
     {
-      instructions: "Vector Vesper's motion runtime and component registry.\n\nBefore writing any animation, scroll, pointer or WebGL code in this project, call `search` or `list_hooks` to check whether a Vector Vesper primitive already covers it, then `get_hook` / `get_component` for the contract. The contract states whether something needs a client boundary, whether it owns an element's transform, and what it conflicts with \u2014 details that do not surface as compile errors but do surface as jank.\n\nAfter writing animation, scroll, pointer or WebGL code, call `check_motion` on the file(s) you changed. It reports the same failure class the contracts warn about \u2014 an unmanaged frame loop, missing cleanup, state written every frame, a transform animated by two owners, motion with no reduced-motion guard, a browser API at module scope \u2014 checked against what you actually wrote. This is how you confirm the contract was followed; none of it shows up as a type or build error.\n\nHooks are consumed by importing `@vectorvesper/motion`. Never reimplement or inline a hook: a copy runs its own requestAnimationFrame loop instead of joining the shared frame conductor, which removes the coordination the runtime exists to provide, and nothing errors when that happens.\n\nIf asked how a hook works internally, call `get_hook` \u2014 its `How it works inside` section explains the architecture, the frame lane, and the smoothing constants directly. Prefer that over reading `node_modules/@vectorvesper/motion`: it is the same design stated at the level the question is actually about, and it stays correct as the package is bundled and rebundled."
+      instructions: 'Vector Vesper\'s motion runtime and component registry.\n\nBefore writing any animation, scroll, pointer or WebGL code in this project, call `search` or `list_hooks` to check whether a Vector Vesper primitive already covers it, then `get_hook` / `get_component` for the contract. The contract states whether something needs a client boundary, whether it owns an element\'s transform, and what it conflicts with \u2014 details that do not surface as compile errors but do surface as jank.\n\nWhen the task COMBINES primitives (scrollytelling, a predictive media card, an adaptive hero, a marquee) call `list_patterns` / `get_pattern` first: a pattern carries the wiring order, one complete example, the pitfalls with the `check_motion` rule that catches each, and how to verify. When no hook or pattern covers the task, build a custom effect on the runtime: `get_pattern("custom-frame-effect")` is the canonical skeleton, and `get_hook("FrameConductor")`, `get_hook("SensorBus")` and `get_hook("damp")` are the core primitives it rides on. Never start a private requestAnimationFrame loop \u2014 subscribing to the shared conductor is always the answer.\n\nAfter writing animation, scroll, pointer or WebGL code, call `check_motion` on the file(s) you changed. It reports the same failure class the contracts warn about \u2014 an unmanaged frame loop, missing cleanup, state written every frame, a transform animated by two owners, motion with no reduced-motion guard, a browser API at module scope \u2014 checked against what you actually wrote. This is how you confirm the contract was followed; none of it shows up as a type or build error.\n\nHooks are consumed by importing `@vectorvesper/motion`. Never reimplement or inline a hook: a copy runs its own requestAnimationFrame loop instead of joining the shared frame conductor, which removes the coordination the runtime exists to provide, and nothing errors when that happens.\n\nIf asked how a hook works internally, call `get_hook` \u2014 its `How it works inside` section explains the architecture, the frame lane, and the smoothing constants directly. Prefer that over reading `node_modules/@vectorvesper/motion`: it is the same design stated at the level the question is actually about, and it stays correct as the package is bundled and rebundled.'
     }
   );
   await registerTools(server);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vectorvesper",
-  "version": "2.0.7",
+  "version": "2.1.1",
   "description": "Add WebGL, React Three Fiber & advanced motion components to your project via CLI.",
   "type": "module",
   "license": "MIT",
@@ -44,6 +44,8 @@
     "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"
   },