vectorvesper 2.0.2 → 2.0.4

package/dist/server-OLD3SDPJ.js

@@ -0,0 +1,839 @@
+import {
+  detectProject,
+  fetchRegistryIndex
+} from "./chunk-5YSVDVLK.js";
+import {
+  findHook,
+  loadHookManifest
+} from "./chunk-XN3PPCIM.js";
+import {
+  getAuthToken
+} from "./chunk-SFP5K3ZO.js";
+
+// src/mcp/server.ts
+import { z } from "zod";
+
+// src/mcp/check-motion.ts
+import fs from "fs";
+import path from "path";
+async function loadBabel() {
+  const mod = await import("@babel/core");
+  const parse = mod.parseSync ?? mod.default?.parseSync;
+  const traverseRaw = mod.traverse ?? mod.default?.traverse;
+  const traverse = traverseRaw?.default ?? traverseRaw;
+  if (typeof parse !== "function" || typeof traverse !== "function") {
+    throw new Error("@babel/core parse/traverse unavailable");
+  }
+  return { parse, traverse };
+}
+var HOT_EVENTS = /* @__PURE__ */ new Set(["scroll", "wheel", "pointermove", "mousemove", "touchmove", "pointerdown"]);
+var BROWSER_GLOBALS = /* @__PURE__ */ new Set(["window", "document", "navigator", "localStorage", "sessionStorage"]);
+var OBSERVERS = /* @__PURE__ */ new Set(["IntersectionObserver", "ResizeObserver", "MutationObserver"]);
+function calleeName(callee) {
+  if (!callee) return void 0;
+  if (callee.type === "Identifier") return callee.name;
+  if ((callee.type === "MemberExpression" || callee.type === "OptionalMemberExpression") && callee.property) {
+    return callee.property.name ?? callee.property.value;
+  }
+  return void 0;
+}
+function isSetter(name) {
+  return !!name && /^set[A-Z]/.test(name) && name !== "setInterval" && name !== "setTimeout";
+}
+function collect(ast, traverse) {
+  const f = {
+    hasUseClient: (ast.program.directives ?? []).some((d) => d.value?.value === "use client"),
+    vvHooks: [],
+    importedModules: /* @__PURE__ */ new Set(),
+    usesUseGSAP: false,
+    usesR3F: false,
+    raf: [],
+    hasCancelRaf: false,
+    addEventListener: [],
+    hasRemoveEventListener: false,
+    setInterval: [],
+    hasClearInterval: false,
+    newObserver: [],
+    hasObserverDisconnect: false,
+    gsapTimeline: [],
+    hasGsapCleanup: false,
+    threeDisposable: [],
+    hasThreeDispose: false,
+    moduleScopeBrowserApi: [],
+    setStateInHot: [],
+    transformAuthorities: [],
+    looping: [],
+    hasReducedMotionGuard: false
+  };
+  const manifest = loadHookManifest();
+  const hookByName = /* @__PURE__ */ new Map();
+  for (const h of manifest?.hooks ?? []) hookByName.set(h.name, h);
+  let fnDepth = 0;
+  const scanHotCallback = (cbNode, ctx, fromRaf) => {
+    if (!cbNode || cbNode.type !== "ArrowFunctionExpression" && cbNode.type !== "FunctionExpression") return;
+    traverse(
+      { type: "File", program: { type: "Program", body: [{ type: "ExpressionStatement", expression: cbNode }], directives: [] } },
+      {
+        CallExpression(p) {
+          if (isSetter(calleeName(p.node.callee))) {
+            f.setStateInHot.push({ line: cbNode.loc?.start.line ?? 0, ctx, fromRaf });
+          }
+        },
+        OptionalCallExpression(p) {
+          if (isSetter(calleeName(p.node.callee))) {
+            f.setStateInHot.push({ line: cbNode.loc?.start.line ?? 0, ctx, fromRaf });
+          }
+        }
+      }
+    );
+  };
+  const handleCall = (node) => {
+    const name = calleeName(node.callee);
+    const line = node.loc?.start.line ?? 0;
+    switch (name) {
+      case "requestAnimationFrame":
+        f.raf.push(line);
+        scanHotCallback(node.arguments?.[0], "a requestAnimationFrame loop", true);
+        break;
+      case "cancelAnimationFrame":
+        f.hasCancelRaf = true;
+        break;
+      case "setInterval":
+        f.setInterval.push(line);
+        break;
+      case "clearInterval":
+        f.hasClearInterval = true;
+        break;
+      case "addEventListener": {
+        f.addEventListener.push(line);
+        const ev = node.arguments?.[0];
+        if (ev?.type === "StringLiteral" && HOT_EVENTS.has(ev.value)) {
+          scanHotCallback(node.arguments?.[1], `a "${ev.value}" listener`, false);
+        }
+        break;
+      }
+      case "removeEventListener":
+        f.hasRemoveEventListener = true;
+        break;
+      case "disconnect":
+        f.hasObserverDisconnect = true;
+        break;
+      case "dispose":
+        f.hasThreeDispose = true;
+        break;
+      case "matchMedia":
+        f.hasReducedMotionGuard = true;
+        break;
+      case "kill":
+      case "revert":
+        f.hasGsapCleanup = true;
+        break;
+      case "timeline":
+        if (f.importedModules.has("gsap") || f.importedModules.has("@gsap/react")) {
+          f.gsapTimeline.push(line);
+        }
+        break;
+    }
+  };
+  traverse(ast, {
+    Function: {
+      enter() {
+        fnDepth++;
+      },
+      exit() {
+        fnDepth--;
+      }
+    },
+    ImportDeclaration(p) {
+      const src = p.node.source.value;
+      f.importedModules.add(src);
+      if (src === "@gsap/react") f.usesUseGSAP = true;
+      if (src === "@react-three/fiber") f.usesR3F = true;
+      if (src === "@vectorvesper/motion" || src.startsWith("@vectorvesper/motion/")) {
+        for (const spec of p.node.specifiers ?? []) {
+          const name = spec.imported?.name ?? spec.local?.name;
+          const hook = name && hookByName.get(name);
+          if (hook) f.vvHooks.push({ hook, line: p.node.loc?.start.line ?? 0 });
+        }
+      }
+    },
+    StringLiteral(p) {
+      const v = p.node.value;
+      if (v.includes("prefers-reduced-motion")) f.hasReducedMotionGuard = true;
+      if (/\binfinite\b/.test(v)) f.looping.push({ line: p.node.loc?.start.line ?? 0, kind: "CSS `infinite` animation" });
+      if (/\btransition\b|\banimation\b/.test(v) && /\btransform\b|\ball\b/.test(v)) {
+        f.transformAuthorities.push({ line: p.node.loc?.start.line ?? 0, source: "a CSS transition/animation" });
+      }
+    },
+    // `repeat: Infinity` (framer-motion) / `repeat: -1` (gsap) — looping motion.
+    ObjectProperty(p) {
+      const key = p.node.key?.name ?? p.node.key?.value;
+      if (key !== "repeat") return;
+      const val = p.node.value;
+      const infinite = val?.type === "Identifier" && val.name === "Infinity" || val?.type === "NumericLiteral" && val.value === -1 || val?.type === "UnaryExpression" && val.operator === "-" && val.argument?.value === 1;
+      if (infinite) f.looping.push({ line: p.node.loc?.start.line ?? 0, kind: "an infinite `repeat`" });
+    },
+    // A `transform` in a JSX style object/string means this node's transform is
+    // being animated or set outside any hook.
+    JSXAttribute(p) {
+      if (p.node.name?.name !== "style") return;
+      const line = p.node.loc?.start.line ?? 0;
+      const val = p.node.value;
+      const expr = val?.type === "JSXExpressionContainer" ? val.expression : null;
+      if (expr?.type === "ObjectExpression") {
+        for (const prop of expr.properties ?? []) {
+          const k = prop.key?.name ?? prop.key?.value;
+          if (k === "transform") f.transformAuthorities.push({ line, source: "an inline style `transform`" });
+        }
+      }
+    },
+    Identifier(p) {
+      const name = p.node.name;
+      if (!BROWSER_GLOBALS.has(name)) return;
+      if (fnDepth !== 0) return;
+      const parent = p.parent;
+      if (parent?.type === "UnaryExpression" && parent.operator === "typeof") return;
+      if (parent?.type === "MemberExpression" && parent.property === p.node && !parent.computed) return;
+      if (parent?.type === "VariableDeclarator" && parent.id === p.node) return;
+      f.moduleScopeBrowserApi.push({ line: p.node.loc?.start.line ?? 0, api: name });
+    },
+    NewExpression(p) {
+      const n = p.node.callee?.name;
+      if (n && OBSERVERS.has(n)) f.newObserver.push(p.node.loc?.start.line ?? 0);
+      if (n && /(?:Geometry|Material|Texture|RenderTarget)$/.test(n)) {
+        f.threeDisposable.push(p.node.loc?.start.line ?? 0);
+      }
+    },
+    CallExpression(p) {
+      handleCall(p.node);
+    },
+    OptionalCallExpression(p) {
+      handleCall(p.node);
+    }
+  });
+  return f;
+}
+function checkClientBoundary(f, file, framework) {
+  const out = [];
+  const servery = framework === "next" || framework === "unknown";
+  if (!servery || f.hasUseClient) {
+  }
+  if (servery && !f.hasUseClient) {
+    const clientHook = f.vvHooks.find((v) => v.hook.runtime.requiresClient);
+    if (clientHook) {
+      out.push({
+        rule: "client-boundary",
+        severity: "error",
+        file,
+        line: clientHook.line,
+        message: `\`${clientHook.hook.name}\` is client-only but this file has no \`"use client"\` directive.`,
+        fix: 'Add `"use client";` as the first line of this file.'
+      });
+    }
+  }
+  for (const b of f.moduleScopeBrowserApi) {
+    out.push({
+      rule: "ssr-module-scope",
+      severity: "error",
+      file,
+      line: b.line,
+      message: `\`${b.api}\` is used at module scope; it is undefined during server rendering and will throw at import time.`,
+      fix: `Move the \`${b.api}\` access inside a component, an effect, or an event handler \u2014 anywhere that only runs in the browser.`
+    });
+  }
+  return out;
+}
+function isRafLoop(f) {
+  return f.raf.length >= 2;
+}
+function checkOrphanRaf(f, file) {
+  if (!isRafLoop(f)) return [];
+  return [
+    {
+      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.`,
+      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."
+    }
+  ];
+}
+function checkMissingCleanup(f, file) {
+  const out = [];
+  const push = (line, what, teardown) => out.push({
+    rule: "missing-cleanup",
+    severity: "warning",
+    file,
+    line,
+    message: `${what} is created here but never torn down. On unmount or re-render it leaks, and repeated mounts stack copies that compound into jank.`,
+    fix: `Return a cleanup from the effect that calls ${teardown}.`
+  });
+  if (isRafLoop(f) && !f.hasCancelRaf) push(f.raf[0], "A `requestAnimationFrame` loop", "`cancelAnimationFrame`");
+  if (f.addEventListener.length && !f.hasRemoveEventListener)
+    push(f.addEventListener[0], "An event listener", "`removeEventListener` with the same handler");
+  if (f.setInterval.length && !f.hasClearInterval) push(f.setInterval[0], "A `setInterval`", "`clearInterval`");
+  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)
+    push(f.threeDisposable[0], "A three.js geometry/material/texture", "`.dispose()`");
+  return out;
+}
+function checkSetStatePerFrame(f, file) {
+  const hot = f.setStateInHot.filter((s) => !s.fromRaf || isRafLoop(f));
+  if (hot.length === 0) return [];
+  const zeroReRender = f.vvHooks.find((v) => v.hook.runtime.reRendersPerFrame === 0);
+  const first = hot[0];
+  return [
+    {
+      rule: "setstate-per-frame",
+      severity: "warning",
+      file,
+      line: first.line,
+      message: `A React state setter runs inside ${first.ctx}. Every call re-renders the component \u2014 at up to 60\u2013120\xD7/second this is the most common cause of animation jank.` + (zeroReRender ? ` \`${zeroReRender.hook.name}\` is designed to avoid exactly this.` : ""),
+      fix: "Write the value to a `ref` or straight to the DOM node inside the callback; keep it out of React state."
+    }
+  ];
+}
+function checkTransformConflict(f, file) {
+  const owner = f.vvHooks.find((v) => v.hook.runtime.ownsTransform);
+  if (!owner || f.transformAuthorities.length === 0) return [];
+  const src = f.transformAuthorities[0];
+  return [
+    {
+      rule: "transform-conflict",
+      severity: "warning",
+      file,
+      line: src.line,
+      message: `\`${owner.hook.name}\` owns its element's \`transform\`, but ${src.source} animates a transform in the same file. Two owners of one transform overwrite each other frame to frame.`,
+      fix: `Give the hook its own element, and animate the CSS/library transform on a different node (e.g. a wrapper or child).`
+    }
+  ];
+}
+function checkReducedMotion(f, file) {
+  if (f.looping.length === 0 || f.hasReducedMotionGuard) return [];
+  if (f.vvHooks.some((v) => v.hook.runtime.respectsReducedMotion)) return [];
+  const first = f.looping[0];
+  return [
+    {
+      rule: "no-reduced-motion",
+      severity: "warning",
+      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."
+    }
+  ];
+}
+var SUPPORTED = /\.(tsx|ts|jsx|mjs|cjs|js)$/i;
+async function analyzeSource(file, source, framework) {
+  let ast;
+  try {
+    const { parse, traverse } = await loadBabel();
+    const isJsx = /\.(tsx|jsx|js|mjs|cjs)$/i.test(file);
+    ast = parse(source, {
+      configFile: false,
+      babelrc: false,
+      parserOpts: {
+        sourceType: "module",
+        errorRecovery: true,
+        plugins: isJsx ? ["typescript", "jsx"] : ["typescript"]
+      }
+    });
+    const facts = collect(ast, traverse);
+    const findings = [
+      ...checkClientBoundary(facts, file, framework),
+      ...checkOrphanRaf(facts, file),
+      ...checkMissingCleanup(facts, file),
+      ...checkSetStatePerFrame(facts, file),
+      ...checkTransformConflict(facts, file),
+      ...checkReducedMotion(facts, file)
+    ].sort((a, b) => a.line - b.line);
+    return { file, findings };
+  } catch (err) {
+    return { file, findings: [], error: err instanceof Error ? err.message : String(err) };
+  }
+}
+async function checkMotionFiles(files, cwd) {
+  const project = detectProject(cwd);
+  const results = [];
+  for (const rel of files) {
+    const abs = path.isAbsolute(rel) ? rel : path.join(cwd, rel);
+    if (!SUPPORTED.test(abs)) {
+      results.push({ file: rel, findings: [], error: "unsupported file type (expected .tsx/.ts/.jsx/.js)" });
+      continue;
+    }
+    let source;
+    try {
+      source = fs.readFileSync(abs, "utf-8");
+    } catch {
+      results.push({ file: rel, findings: [], error: `could not read file at ${abs}` });
+      continue;
+    }
+    results.push(await analyzeSource(rel, source, project.framework));
+  }
+  return results;
+}
+
+// src/mcp/server.ts
+var VERSION = true ? "2.0.4" : "0.0.0-dev";
+function text(body) {
+  return { content: [{ type: "text", text: body }] };
+}
+function formatHookSummary(hook) {
+  return `**${hook.name}** (${hook.category}) \u2014 ${hook.tagline}
+  Problem: ${hook.problem}`;
+}
+function formatRuntimeContract(hook) {
+  const r = hook.runtime;
+  const lines = [];
+  lines.push(
+    r.requiresClient ? '- **Client only.** Needs `"use client"`. On Next.js App Router, a parent server component must not render it directly.' : "- Runs anywhere (no browser-only APIs at module scope)."
+  );
+  if (r.ownsTransform) {
+    lines.push(
+      "- **Owns the element's inline `transform`.** Give it its own element; do not also animate that node's transform with CSS, framer-motion or GSAP."
+    );
+  }
+  lines.push(
+    r.respectsReducedMotion ? "- Honours `prefers-reduced-motion` automatically \u2014 no extra work needed." : "- Does **not** self-disable under `prefers-reduced-motion`; gate it yourself if it drives autonomous motion."
+  );
+  const caps = [
+    r.usesPointer && "pointer",
+    r.usesScroll && "scroll",
+    r.usesWebGL && "WebGL"
+  ].filter(Boolean);
+  if (caps.length) lines.push(`- Uses: ${caps.join(", ")}.`);
+  if (r.lane) {
+    lines.push(
+      `- Runs in the conductor's **${r.lane}** lane${r.priority ? ` at \`${r.priority}\` priority` : ""}. Lanes run input \u2192 update \u2192 render each frame, so sensors are always current before anything draws.`
+    );
+  } else if (r.lane === null) {
+    lines.push("- Never joins the frame loop \u2014 no per-frame cost.");
+  }
+  if (typeof r.reRendersPerFrame === "number") {
+    lines.push(
+      r.reRendersPerFrame === 0 ? "- **Zero React re-renders per frame.** Values are written straight to the DOM or held in refs; do not mirror them into state." : `- Causes ${r.reRendersPerFrame} React re-render(s) per frame \u2014 keep it out of hot paths.`
+    );
+  }
+  if (r.sharedSingletons?.length) {
+    lines.push(
+      `- Retains shared singletons: ${r.sharedSingletons.map((s) => `\`${s}\``).join(", ")} (ref-counted \u2014 cost is shared with every other consumer, not multiplied).`
+    );
+  }
+  if (r.conflictsWith.length) {
+    lines.push("- **Conflicts with:**");
+    for (const c of r.conflictsWith) lines.push(`  - ${c}`);
+  }
+  return lines.join("\n");
+}
+function formatHookDetail(hook) {
+  const out = [];
+  out.push(`# ${hook.name}`);
+  out.push(`> ${hook.tagline}`);
+  out.push("");
+  out.push(`**The problem it removes:** ${hook.problem}`);
+  out.push("");
+  out.push(hook.summary);
+  out.push("");
+  out.push(`## Import
+\`\`\`ts
+import { ${hook.name} } from "${hook.importFrom}";
+\`\`\``);
+  out.push(`Install with \`npm i ${hook.packageName}\`. Available since v${hook.since}.`);
+  out.push("");
+  out.push(`## Signature
+\`${hook.signature}\``);
+  if (hook.options.length) {
+    out.push("\n### Options");
+    out.push("| Option | Type | Default | Description |");
+    out.push("| --- | --- | --- | --- |");
+    for (const o of hook.options) {
+      out.push(`| \`${o.name}\`${o.required ? " *(required)*" : ""} | \`${o.type}\` | \`${o.default}\` | ${o.description} |`);
+    }
+  } else {
+    out.push("\n### Options\nNone \u2014 this hook takes no arguments.");
+  }
+  out.push("\n### Returns");
+  out.push("| Field | Type | Description |");
+  out.push("| --- | --- | --- |");
+  for (const r of hook.returns) out.push(`| \`${r.name}\` | \`${r.type}\` | ${r.description} |`);
+  out.push("\n## Runtime contract");
+  out.push(formatRuntimeContract(hook));
+  if (hook.mechanism) {
+    out.push("\n## How it works inside");
+    out.push(hook.mechanism);
+  }
+  out.push("\n## Quick start");
+  out.push("```tsx");
+  out.push(hook.quickStart);
+  out.push("```");
+  if (hook.recipes?.length) {
+    out.push("\n## Recipes");
+    for (const r of hook.recipes) {
+      out.push(`
+### ${r.name}
+${r.blurb}
+
+\`\`\`tsx
+${r.code}
+\`\`\``);
+    }
+  }
+  if (hook.dos?.length) out.push(`
+## Do
+${hook.dos.map((d) => `- ${d}`).join("\n")}`);
+  if (hook.donts?.length) out.push(`
+## Don't
+${hook.donts.map((d) => `- ${d}`).join("\n")}`);
+  out.push("\n## When NOT to use this");
+  for (const w of hook.whenNotToUse) out.push(`- **${w.when}** \u2192 ${w.instead}`);
+  if (hook.guardrails?.length) {
+    out.push(`
+## Required reading before writing motion code
+${hook.guardrails.map((g) => `- ${g}`).join("\n")}`);
+  }
+  out.push(`
+## Docs
+${hook.docsUrl}${hook.labUrl ? `
+Live demo: ${hook.labUrl}` : ""}`);
+  out.push(`
+---
+**Consumption rule.** ${hook.disclosure.correctUsage} ${hook.disclosure.reason}`);
+  if (hook.disclosure.readingSource) {
+    out.push(`
+**Reading the implementation.** ${hook.disclosure.readingSource}`);
+  }
+  if (hook.contractLevel === "lean" && hook.upgrade) {
+    out.push(`
+_${hook.upgrade}_`);
+  }
+  return out.join("\n");
+}
+function formatComponentDetail(c) {
+  const out = [];
+  out.push(`# ${c.title} \`${c.slug}\``);
+  out.push(`> ${c.description}`);
+  out.push("");
+  out.push(`**Tier:** ${c.tier}${c.tier === "pro" ? " \u2014 requires a Vector Vesper membership" : ""}`);
+  out.push(`**Category:** ${c.category} \xB7 **Type:** ${c.type} \xB7 **Version:** ${c.version}`);
+  out.push(`**Frameworks:** ${c.frameworks.join(", ")}`);
+  out.push("\n## Motion contract");
+  const lines = [];
+  lines.push(
+    c.requiresClient ? '- **Client only.** Needs `"use client"`.' : "- No client boundary required."
+  );
+  if (c.usesWebGL) {
+    lines.push(
+      "- **Uses WebGL.** On Next.js, render it through `dynamic(() => import(...), { ssr: false })` or it will fail during server rendering."
+    );
+  }
+  lines.push(
+    c.supportsReducedMotion ? "- Respects `prefers-reduced-motion`." : "- Does **not** self-disable under `prefers-reduced-motion`."
+  );
+  const caps = [c.usesPointer && "pointer", c.usesScroll && "scroll"].filter(Boolean);
+  if (caps.length) lines.push(`- Uses: ${caps.join(", ")}.`);
+  if (c.usesTailwind) lines.push("- Ships hardcoded Tailwind classes \u2014 the project needs Tailwind configured.");
+  if (c.fallbacks?.length) lines.push(`- Fallbacks: ${c.fallbacks.join(", ")}`);
+  out.push(lines.join("\n"));
+  if (c.dependencies.length || c.registryDependencies.length) {
+    out.push("\n## Dependencies");
+    if (c.dependencies.length) out.push(`- npm: ${c.dependencies.map((d) => `\`${d}\``).join(", ")}`);
+    if (c.registryDependencies.length) {
+      out.push(`- other VV components: ${c.registryDependencies.map((d) => `\`${d}\``).join(", ")} (installed automatically)`);
+    }
+  }
+  out.push(`
+## Install
+\`\`\`bash
+npx vectorvesper add ${c.slug}
+\`\`\``);
+  if (c.tier === "pro") {
+    out.push(
+      "Requires an authenticated CLI: `npx vectorvesper login <token>`. Tokens come from https://vectorvesper.dev/account."
+    );
+  }
+  if (c.docsUrl) out.push(`
+## Docs
+${c.docsUrl}`);
+  out.push(
+    "\n---\n**Note.** Component source is delivered by running the install command above, which writes the files into the project. It is deliberately not returned here \u2014 pasting a component out of a discovery response skips dependency resolution, the TypeScript/JavaScript transpile step, and the install manifest that makes `update` and `remove` work later."
+  );
+  return out.join("\n");
+}
+function severityMark(s) {
+  return s === "error" ? "\u2717 error" : s === "warning" ? "\u25B2 warning" : "\xB7 note";
+}
+var CHECK_SCOPE_NOTE = "_Static analysis \u2014 it catches the common silent motion mistakes (unmanaged loops, missing cleanup, state-per-frame, transform conflicts, missing reduced-motion, SSR-unsafe access), not all of them. An **error** breaks at build or runtime; a **warning** compiles and runs but janks, leaks, or excludes users._";
+function formatCheckResults(results) {
+  let errors = 0;
+  let warnings = 0;
+  let filesWithFindings = 0;
+  const blocks = [];
+  for (const r of results) {
+    if (r.error) {
+      blocks.push(`### \`${r.file}\`
+- could not analyze: ${r.error}`);
+      continue;
+    }
+    if (r.findings.length === 0) continue;
+    filesWithFindings++;
+    const lines = [`### \`${r.file}\``];
+    for (const f of r.findings) {
+      if (f.severity === "error") errors++;
+      else if (f.severity === "warning") warnings++;
+      lines.push(`- **${severityMark(f.severity)} \xB7 ${f.rule}** (line ${f.line}) \u2014 ${f.message}`);
+      lines.push(`  - **Fix:** ${f.fix}`);
+      if (f.nudge) lines.push(`  - ${f.nudge}`);
+    }
+    blocks.push(lines.join("\n"));
+  }
+  const total = errors + warnings;
+  if (total === 0) {
+    return `\u2713 No motion issues found in ${results.length} file${results.length === 1 ? "" : "s"}.
+
+` + CHECK_SCOPE_NOTE;
+  }
+  return [
+    "# Motion check",
+    `${total} issue${total === 1 ? "" : "s"} across ${filesWithFindings} file${filesWithFindings === 1 ? "" : "s"} \u2014 ${errors} error${errors === 1 ? "" : "s"}, ${warnings} warning${warnings === 1 ? "" : "s"}.`,
+    "",
+    ...blocks,
+    "",
+    CHECK_SCOPE_NOTE
+  ].join("\n");
+}
+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.",
+      inputSchema: {
+        category: z.enum(["sensor", "governor", "gate", "interaction", "media", "effect"]).optional().describe("Filter to one category.")
+      }
+    },
+    async ({ category }) => {
+      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 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),
+        "",
+        "Call `get_hook` for the full contract of any of these before writing code with it."
+      ].join("\n");
+      return text(body);
+    }
+  );
+  server.registerTool(
+    "get_hook",
+    {
+      title: "Get a motion hook's contract",
+      description: "Full contract for one hook: signature, every option with its default, returns, the runtime contract (client boundary, transform ownership, frame lane, re-render cost, what it conflicts with), how it works internally, a runnable quick start, and when NOT to use it. Read this before writing code that uses the hook \u2014 and use it to answer questions about a hook's internals or design, which it explains directly, so there is no need to go read the package source to find out.",
+      inputSchema: {
+        name: z.string().describe('Hook name, e.g. "useMagneticIntent" or "magnetic-intent".')
+      }
+    },
+    async ({ name }) => {
+      const hook = findHook(name);
+      if (!hook) {
+        const manifest = loadHookManifest();
+        const available = manifest?.hooks.map((h) => h.name).join(", ") ?? "none loaded";
+        return text(`No hook named "${name}". Available: ${available}`);
+      }
+      return text(formatHookDetail(hook));
+    }
+  );
+  server.registerTool(
+    "list_components",
+    {
+      title: "List Vector Vesper components",
+      description: "List installable components from the Vector Vesper registry, with tier and category. Free components install for anyone; Pro components need a membership.",
+      inputSchema: {
+        tier: z.enum(["free", "pro"]).optional().describe("Filter by tier."),
+        category: z.string().optional().describe("Filter by category.")
+      }
+    },
+    async ({ tier, category }) => {
+      let index;
+      try {
+        index = await fetchRegistryIndex();
+      } catch (error) {
+        return text(
+          `Could not reach the component registry: ${error instanceof Error ? error.message : String(error)}
+
+Hook discovery still works offline \u2014 try \`list_hooks\`.`
+        );
+      }
+      let components = index.components;
+      if (tier) components = components.filter((c) => c.tier === tier);
+      if (category) components = components.filter((c) => c.category === category);
+      if (!components.length) return text("No components matched that filter.");
+      const body = [
+        `${components.length} component${components.length === 1 ? "" : "s"} (registry v${index.version})`,
+        "",
+        ...components.map(
+          (c) => `**${c.slug}** [${c.tier}] ${c.category} \u2014 ${c.description}`
+        ),
+        "",
+        "Call `get_component` for a component's motion contract and wiring requirements before installing it."
+      ].join("\n");
+      return text(body);
+    }
+  );
+  server.registerTool(
+    "get_component",
+    {
+      title: "Get a component's motion contract",
+      description: "Metadata and wiring requirements for one component: whether it needs a client boundary, whether it needs dynamic import to survive SSR, what it depends on, and how to install it. Does not return source \u2014 source is written into the project by the install command.",
+      inputSchema: { slug: z.string().describe('Component slug, e.g. "code-rain".') }
+    },
+    async ({ slug }) => {
+      let index;
+      try {
+        index = await fetchRegistryIndex();
+      } catch (error) {
+        return text(
+          `Could not reach the component registry: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+      const component = index.components.find((c) => c.slug === slug);
+      if (!component) {
+        return text(
+          `No component with slug "${slug}". Call \`list_components\` to see what exists.`
+        );
+      }
+      return text(formatComponentDetail(component));
+    }
+  );
+  server.registerTool(
+    "get_setup_guidance",
+    {
+      title: "Inspect the current project",
+      description: "Detect the framework, package manager, TypeScript/JavaScript, Tailwind and Next router of the project in the working directory, plus Vector Vesper auth status. Call this before generating install commands or import paths so they match the project.",
+      inputSchema: {
+        cwd: z.string().optional().describe("Project root. Defaults to the server's working directory.")
+      }
+    },
+    async ({ cwd }) => {
+      const info = detectProject(cwd ?? process.cwd());
+      const authed = Boolean(getAuthToken());
+      const out = [];
+      out.push("# Project");
+      out.push(`- Root: \`${info.rootPath}\``);
+      out.push(`- Framework: **${info.framework}**${info.nextRouter ? ` (${info.nextRouter} router)` : ""}`);
+      out.push(`- Language: **${info.isTypeScript ? "TypeScript" : "JavaScript"}**`);
+      out.push(`- Package manager: **${info.packageManager}**`);
+      out.push(`- Tailwind: ${info.hasTailwind ? "yes" : "no"}`);
+      out.push(`- \`src/\` directory: ${info.hasSrcDir ? "yes" : "no"}`);
+      out.push("\n# Vector Vesper");
+      out.push(`- CLI authenticated: ${authed ? "yes \u2014 Pro components available" : "no \u2014 free components only"}`);
+      if (!authed) {
+        out.push("  - To unlock Pro: `npx vectorvesper login <token>` (tokens at https://vectorvesper.dev/account)");
+      }
+      out.push("\n# What this implies");
+      if (info.framework === "next" && info.nextRouter === "app") {
+        out.push(
+          '- App Router: any component or hook marked **client only** needs `"use client"` at the top of the file that uses it.'
+        );
+        out.push(
+          "- Anything using WebGL should be rendered via `dynamic(() => import(...), { ssr: false })`."
+        );
+      }
+      if (!info.hasTailwind) {
+        out.push("- No Tailwind detected: components that ship Tailwind classes will render unstyled.");
+      }
+      out.push("- Run `npx vectorvesper init` first if `vv.config.json` does not exist yet.");
+      return text(out.join("\n"));
+    }
+  );
+  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.',
+      inputSchema: { query: z.string().describe("What you are trying to build.") }
+    },
+    async ({ query }) => {
+      const q = query.toLowerCase();
+      const terms = q.split(/\s+/).filter((t) => t.length > 2);
+      const score = (haystack) => {
+        const h = haystack.toLowerCase();
+        if (h.includes(q)) return 100;
+        return terms.reduce((n, t) => n + (h.includes(t) ? 1 : 0), 0);
+      };
+      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}` });
+      }
+      try {
+        const index = await fetchRegistryIndex();
+        for (const c of index.components) {
+          const s = score([c.slug, c.title, c.description, c.category, c.type].join(" "));
+          if (s > 0) {
+            results.push({ score: s, line: `**component** \`${c.slug}\` [${c.tier}] \u2014 ${c.description}` });
+          }
+        }
+      } catch {
+      }
+      if (!results.length) {
+        return text(
+          `Nothing matched "${query}". Try \`list_hooks\` or \`list_components\` to browse everything.`
+        );
+      }
+      results.sort((a, b) => b.score - a.score);
+      return text(
+        [
+          `${results.length} result${results.length === 1 ? "" : "s"} for "${query}"`,
+          "",
+          ...results.slice(0, 12).map((r) => r.line),
+          "",
+          "Then call `get_hook` or `get_component` for the full contract before writing code."
+        ].join("\n")
+      );
+    }
+  );
+  server.registerTool(
+    "check_motion",
+    {
+      title: "Check motion code for silent failures",
+      description: "Read the file(s) just written or edited and report the motion mistakes that do NOT show up as type or build errors but surface later as jank, leaks, or accessibility problems: a self-scheduling requestAnimationFrame loop running outside the shared frame budget, a listener/observer/timeline never torn down, a setState fired every frame, one element's transform animated by two owners at once, autonomous motion with no prefers-reduced-motion guard, and browser APIs used at module scope (an SSR crash). Call this after generating any animation, scroll, pointer or WebGL code \u2014 it is the check that the contract from `get_hook` was actually followed. Static analysis; reports severity, line, and the fix.",
+      inputSchema: {
+        files: z.array(z.string()).min(1).describe("Path(s) of the file(s) to check \u2014 relative to the project root, or absolute."),
+        cwd: z.string().optional().describe("Project root. Defaults to the server's working directory.")
+      }
+    },
+    async ({ files, cwd }) => {
+      const results = await checkMotionFiles(files, cwd ?? process.cwd());
+      return text(formatCheckResults(results));
+    }
+  );
+}
+async function startMcpServer() {
+  const [{ McpServer: McpServerCtor }, { StdioServerTransport }] = await Promise.all([
+    import("@modelcontextprotocol/sdk/server/mcp.js"),
+    import("@modelcontextprotocol/sdk/server/stdio.js")
+  ]);
+  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."
+    }
+  );
+  await registerTools(server);
+  await server.connect(new StdioServerTransport());
+}
+export {
+  startMcpServer
+};