vectorvesper 2.1.1 → 2.4.0

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

@@ -30,6 +30,33 @@ async function loadBabel() {
 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"]);
+var VV_ACCESSORS = /* @__PURE__ */ new Set([
+  "getConductor",
+  "getSensorBus",
+  "getAnimationBudget",
+  "getAdaptiveQuality",
+  "getFramePressure",
+  "getRendererHealth"
+]);
+var TEARDOWN_RETURNING = /* @__PURE__ */ new Set(["subscribe", "retain"]);
+var LAYOUT_READ_PROPS = /* @__PURE__ */ new Set([
+  "offsetWidth",
+  "offsetHeight",
+  "offsetTop",
+  "offsetLeft",
+  "clientWidth",
+  "clientHeight",
+  "clientTop",
+  "clientLeft",
+  "scrollWidth",
+  "scrollHeight",
+  "scrollTop",
+  "scrollLeft"
+]);
+var LAYOUT_READ_CALLS = /* @__PURE__ */ new Set(["getBoundingClientRect", "getComputedStyle", "getClientRects"]);
+var DOM_WRITE_PROPS = /* @__PURE__ */ new Set(["textContent", "innerHTML", "innerText", "className", "cssText"]);
+var DOM_WRITE_CALLS = /* @__PURE__ */ new Set(["setAttribute", "setProperty", "removeAttribute"]);
+var R3F_RECONCILED_PROPS = /* @__PURE__ */ new Set(["dpr", "frameloop", "shadows"]);
 function calleeName(callee) {
   if (!callee) return void 0;
   if (callee.type === "Identifier") return callee.name;
@@ -43,13 +70,28 @@ function isStateSetterCall(callee) {
   const name = callee.name;
   return /^set[A-Z]/.test(name) && name !== "setInterval" && name !== "setTimeout";
 }
+function accessorName(callee) {
+  const obj = callee?.object;
+  if (obj?.type !== "CallExpression" && obj?.type !== "OptionalCallExpression") return void 0;
+  return obj.callee?.type === "Identifier" ? obj.callee.name : void 0;
+}
+function asProgram(cbNode) {
+  if (!cbNode) return null;
+  const isExpression = cbNode.type === "ArrowFunctionExpression" || cbNode.type === "FunctionExpression";
+  const isDeclaration = cbNode.type === "FunctionDeclaration";
+  if (!isExpression && !isDeclaration) return null;
+  const statement = isDeclaration ? cbNode : { type: "ExpressionStatement", expression: cbNode };
+  return { type: "File", program: { type: "Program", body: [statement], directives: [] } };
+}
 function collect(ast, traverse) {
   const f = {
     hasUseClient: (ast.program.directives ?? []).some((d) => d.value?.value === "use client"),
     vvHooks: [],
+    vvImports: /* @__PURE__ */ new Set(),
     importedModules: /* @__PURE__ */ new Set(),
     usesUseGSAP: false,
     usesR3F: false,
+    isReact: false,
     raf: [],
     rafSelfScheduling: [],
     rafUnresolved: 0,
@@ -68,7 +110,13 @@ function collect(ast, traverse) {
     setStateInHot: [],
     transformAuthorities: [],
     looping: [],
-    hasReducedMotionGuard: false
+    hasReducedMotionGuard: false,
+    frameCallbacks: [],
+    laneViolations: [],
+    orphanSubscriptions: [],
+    canvases: [],
+    handlesContextLoss: false,
+    gatingObserver: []
   };
   const manifest = loadHookManifest();
   const hookByName = /* @__PURE__ */ new Map();
@@ -88,26 +136,82 @@ function collect(ast, traverse) {
     return null;
   };
   const scanHotCallback = (cbNode, ctx, fromRaf) => {
-    if (!cbNode) return;
-    const isExpression = cbNode.type === "ArrowFunctionExpression" || cbNode.type === "FunctionExpression";
-    const isDeclaration = cbNode.type === "FunctionDeclaration";
-    if (!isExpression && !isDeclaration) return;
-    const statement = isDeclaration ? cbNode : { type: "ExpressionStatement", expression: cbNode };
-    traverse(
-      { type: "File", program: { type: "Program", body: [statement], directives: [] } },
-      {
-        CallExpression(p) {
-          if (isStateSetterCall(p.node.callee)) {
-            f.setStateInHot.push({ line: cbNode.loc?.start.line ?? 0, ctx, fromRaf });
-          }
-        },
-        OptionalCallExpression(p) {
-          if (isStateSetterCall(p.node.callee)) {
-            f.setStateInHot.push({ line: cbNode.loc?.start.line ?? 0, ctx, fromRaf });
-          }
+    const file = asProgram(cbNode);
+    if (!file) return;
+    traverse(file, {
+      CallExpression(p) {
+        if (isStateSetterCall(p.node.callee)) {
+          f.setStateInHot.push({ line: cbNode.loc?.start.line ?? 0, ctx, fromRaf });
+        }
+      },
+      OptionalCallExpression(p) {
+        if (isStateSetterCall(p.node.callee)) {
+          f.setStateInHot.push({ line: cbNode.loc?.start.line ?? 0, ctx, fromRaf });
         }
       }
-    );
+    });
+  };
+  const containsStateSetter = (cbNode) => {
+    const file = asProgram(cbNode);
+    if (!file) return false;
+    let found = false;
+    const visit = (p) => {
+      if (isStateSetterCall(p.node.callee)) found = true;
+    };
+    traverse(file, { CallExpression: visit, OptionalCallExpression: visit });
+    return found;
+  };
+  const scanLaneDiscipline = (cbNode, lane, via) => {
+    const file = asProgram(cbNode);
+    if (!file) return;
+    const flagsWrites = lane === "input";
+    const flagsReads = lane === "render";
+    const at = (node) => node?.loc?.start.line ?? cbNode.loc?.start.line ?? 0;
+    const onCall = (p) => {
+      const name = calleeName(p.node.callee);
+      if (!name) return;
+      if (flagsReads && LAYOUT_READ_CALLS.has(name)) {
+        f.laneViolations.push({ line: at(p.node), lane, via, kind: "read", what: `${name}()` });
+      }
+      if (flagsWrites && DOM_WRITE_CALLS.has(name)) {
+        f.laneViolations.push({ line: at(p.node), lane, via, kind: "write", what: `${name}()` });
+      }
+    };
+    traverse(file, {
+      CallExpression: onCall,
+      OptionalCallExpression: onCall,
+      MemberExpression(p) {
+        if (!flagsReads || p.node.computed) return;
+        const prop = p.node.property?.name;
+        if (!prop || !LAYOUT_READ_PROPS.has(prop)) return;
+        const parent = p.parent;
+        if (parent?.type === "AssignmentExpression" && parent.left === p.node) return;
+        f.laneViolations.push({ line: at(p.node), lane, via, kind: "read", what: `.${prop}` });
+      },
+      AssignmentExpression(p) {
+        if (!flagsWrites) return;
+        const left = p.node.left;
+        if (left?.type !== "MemberExpression" || left.computed) return;
+        const prop = left.property?.name;
+        const onStyle = left.object?.type === "MemberExpression" && left.object.property?.name === "style";
+        if (!prop) return;
+        if (onStyle) {
+          f.laneViolations.push({ line: at(p.node), lane, via, kind: "write", what: `style.${prop}` });
+        } else if (DOM_WRITE_PROPS.has(prop)) {
+          f.laneViolations.push({ line: at(p.node), lane, via, kind: "write", what: `.${prop}` });
+        }
+      }
+    });
+  };
+  const recordFrameCallback = (p, argPaths, via) => {
+    const laneArg = p.node.arguments?.[0];
+    const lane = laneArg?.type === "StringLiteral" ? laneArg.value : null;
+    const line = p.node.loc?.start.line ?? 0;
+    f.frameCallbacks.push({ line, lane, via });
+    const cb = resolveFunction(argPaths[1]);
+    if (!cb) return;
+    scanHotCallback(cb, lane ? `a \`${via}("${lane}")\` frame callback` : `a \`${via}\` frame callback`, false);
+    if (lane === "input" || lane === "update" || lane === "render") scanLaneDiscipline(cb, lane, via);
   };
   const handleCall = (p) => {
     const node = p.node;
@@ -156,6 +260,21 @@ function collect(ast, traverse) {
       case "revert":
         f.hasGsapCleanup = true;
         break;
+      case "useTick":
+        recordFrameCallback(p, argPaths, "useTick");
+        break;
+      case "subscribe":
+      case "retain": {
+        const accessor = accessorName(node.callee);
+        if (!accessor || !VV_ACCESSORS.has(accessor)) break;
+        if (name === "subscribe" && accessor === "getConductor") {
+          recordFrameCallback(p, argPaths, "getConductor().subscribe");
+        }
+        if (TEARDOWN_RETURNING.has(name) && p.parent?.type === "ExpressionStatement") {
+          f.orphanSubscriptions.push({ line, call: `${accessor}().${name}()` });
+        }
+        break;
+      }
       case "timeline":
         if (f.importedModules.has("gsap") || f.importedModules.has("@gsap/react")) {
           f.gsapTimeline.push(line);
@@ -177,10 +296,14 @@ function collect(ast, traverse) {
       f.importedModules.add(src);
       if (src === "@gsap/react") f.usesUseGSAP = true;
       if (src === "@react-three/fiber") f.usesR3F = true;
+      if (src === "react" || src.startsWith("react/") || src === "react-dom") f.isReact = true;
       if (src === "@vectorvesper/motion" || src.startsWith("@vectorvesper/motion/")) {
+        if (src.endsWith("/react") || src.endsWith("/r3f")) f.isReact = true;
         for (const spec of p.node.specifiers ?? []) {
           const name = spec.imported?.name ?? spec.local?.name;
-          const hook = name && hookByName.get(name);
+          if (!name) continue;
+          f.vvImports.add(name);
+          const hook = hookByName.get(name);
           if (hook) f.vvHooks.push({ hook, line: p.node.loc?.start.line ?? 0 });
         }
       }
@@ -188,6 +311,7 @@ function collect(ast, traverse) {
     StringLiteral(p) {
       const v = p.node.value;
       if (v.includes("prefers-reduced-motion")) f.hasReducedMotionGuard = true;
+      if (v === "webglcontextlost" || v === "webglcontextrestored") f.handlesContextLoss = 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" });
@@ -201,6 +325,25 @@ function collect(ast, traverse) {
       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`" });
     },
+    // React Three Fiber re-runs its configure pass on every render of the
+    // canvas and resets `dpr`, `frameloop` and `shadows` from props, so what is
+    // written here is the last word on all three — whatever anything else set
+    // 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 overrides = [];
+      let hasSpread = false;
+      for (const attr of p.node.attributes ?? []) {
+        if (attr.type === "JSXSpreadAttribute") {
+          hasSpread = true;
+          continue;
+        }
+        const name = attr.name?.name;
+        if (name && R3F_RECONCILED_PROPS.has(name)) overrides.push(name);
+      }
+      f.canvases.push({ line: p.node.loc?.start.line ?? 0, hasSpread, overrides });
+    },
     // A `transform` in a JSX style object/string means this node's transform is
     // being animated or set outside any hook.
     JSXAttribute(p) {
@@ -231,6 +374,12 @@ function collect(ast, traverse) {
     NewExpression(p) {
       const n = p.node.callee?.name;
       if (n && OBSERVERS.has(n)) f.newObserver.push(p.node.loc?.start.line ?? 0);
+      if (n === "IntersectionObserver") {
+        const argPaths = typeof p.get === "function" ? p.get("arguments") : [];
+        if (containsStateSetter(resolveFunction(argPaths[0]))) {
+          f.gatingObserver.push(p.node.loc?.start.line ?? 0);
+        }
+      }
       if (n && /(?:Geometry|Material|Texture|RenderTarget)$/.test(n)) {
         f.threeDisposable.push(p.node.loc?.start.line ?? 0);
       }
@@ -298,6 +447,7 @@ function isRafLoop(f) {
 }
 function checkOrphanRaf(f, file) {
   if (!isRafLoop(f)) return [];
+  const fix = f.isReact ? "Replace the loop with `useTick(lane, fn, { label })` from `@vectorvesper/motion/react`. It subscribes to the shared conductor for the lifetime of the component, unsubscribes on unmount, and joins the surrounding `InteractionScope` so the work yields in the right order under load." : "Drive the animation from the shared conductor \u2014 `getConductor().subscribe(lane, fn, { priority, label })` in `@vectorvesper/motion` \u2014 and call the unsubscribe it returns on teardown, so it shares one frame budget.";
   return [
     {
       rule: "orphan-raf",
@@ -306,9 +456,9 @@ function checkOrphanRaf(f, file) {
       // 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."
+      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. The frame-pressure classifier also bills the time to "main-thread", so the page cannot even tell the loop is its own.`,
+      fix,
+      nudge: 'Call `list_hooks` \u2014 a sensor or governor primitive may already cover this without a hand-written loop. `get_pattern("custom-frame-effect")` is the skeleton when none does.'
     }
   ];
 }
@@ -345,7 +495,106 @@ function checkSetStatePerFrame(f, file) {
       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."
+      fix: "Write the value to a `ref` or straight to the DOM node inside the callback; keep it out of React state. Where the render genuinely has to see it, throttle the state write \u2014 a few times a second, not every frame."
+    }
+  ];
+}
+function checkLaneDiscipline(f, file) {
+  if (f.laneViolations.length === 0) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const v of f.laneViolations) {
+    const key = `${v.lane}:${v.kind}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const same = f.laneViolations.filter((o) => o.lane === v.lane && o.kind === v.kind);
+    const what = [...new Set(same.map((o) => `\`${o.what}\``))].join(", ");
+    const site = `\`${v.via}("${v.lane}")\``;
+    out.push(
+      v.kind === "read" ? {
+        rule: "lane-discipline",
+        severity: "warning",
+        file,
+        line: v.line,
+        message: `A ${site} callback reads layout (${what}). \`render\` is the write lane, so by the time this runs the subscribers before it have already written \u2014 the read forces the browser to recalculate layout synchronously, every frame, and the cost grows with everything else on the page.`,
+        fix: "Measure in the `input` lane and pass the value through a ref, or measure once on mount and on resize and cache it."
+      } : {
+        rule: "lane-discipline",
+        severity: "warning",
+        file,
+        line: v.line,
+        message: `A ${site} callback writes to the DOM (${what}). \`input\` is the read lane: the runtime's own sensors and gates are measuring in it, and a write here dirties layout underneath all of them, so each subsequent read pays for a fresh recalculation.`,
+        fix: "Keep the value on a ref in this callback and do the DOM write from a `render`-lane callback."
+      }
+    );
+  }
+  return out;
+}
+function checkOrphanSubscription(f, file) {
+  return f.orphanSubscriptions.map((s) => ({
+    rule: "orphan-subscription",
+    severity: "error",
+    file,
+    line: s.line,
+    message: `\`${s.call}\` returns the teardown that undoes it, and the return value is discarded here. Nothing can stop it afterwards: it survives unmount, every route change adds another, and the frame budget keeps paying for all of them.`,
+    fix: `Keep the returned function and call it on teardown \u2014 \`const off = ${s.call.replace(/\(\)$/, "(\u2026)")};\` then \`return () => off();\` from the effect.`,
+    nudge: "In React, `useTick` and the other hooks own this lifecycle for you."
+  }));
+}
+function checkRenderQualityProps(f, file) {
+  if (!f.vvImports.has("useRenderQuality") || f.canvases.length === 0) return [];
+  const out = [];
+  const overridden = f.canvases.find((c) => c.hasSpread && c.overrides.length > 0);
+  if (overridden) {
+    out.push({
+      rule: "canvas-prop-override",
+      severity: "error",
+      file,
+      line: overridden.line,
+      message: `\`<Canvas>\` receives the adapter's props and also sets \`${overridden.overrides.join("`, `")}\` directly. React Three Fiber reconciles all three from props on every render, so the later prop wins and the adapter's decision is discarded \u2014 with no error, no warning and no type complaint.`,
+      fix: `Delete the \`${overridden.overrides.join("`, `")}\` prop and let the spread supply it. Quality levels belong in the \`profiles\` argument to \`useRenderQuality\`.`
+    });
+  }
+  if (!f.canvases.some((c) => c.hasSpread)) {
+    out.push({
+      rule: "canvas-partial-spread",
+      severity: "warning",
+      file,
+      line: f.canvases[0].line,
+      message: "`useRenderQuality` is called but its result is not spread onto `<Canvas>`. It returns four things \u2014 the pixel ratio, the frame loop, the shadow setting and an `onCreated` that notices a lost graphics context. Picking fields out of it means picking which of the four jobs the adapter still does.",
+      fix: "Spread the whole object: `<Canvas key={scene.generation} {...canvas}>`."
+    });
+  }
+  return out;
+}
+function checkContextLoss(f, file) {
+  if (!f.usesR3F || f.canvases.length === 0) return [];
+  const handled = f.handlesContextLoss || f.vvImports.has("useRenderQuality") || f.vvImports.has("getRendererHealth");
+  if (handled) return [];
+  return [
+    {
+      rule: "webgl-context-loss",
+      severity: "warning",
+      file,
+      line: f.canvases[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: "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 `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.'
+    }
+  ];
+}
+function checkHandRolledGate(f, file) {
+  if (!f.usesR3F || f.canvases.length === 0) return [];
+  if (f.gatingObserver.length === 0 || f.vvImports.has("useSceneGate")) return [];
+  return [
+    {
+      rule: "hand-rolled-scene-gate",
+      severity: "info",
+      file,
+      line: f.gatingObserver[0],
+      message: "This gates a WebGL canvas on viewport intersection alone. `useSceneGate` is the same observer plus the parts that are easy to leave out: it waits for scrolling to stop, checks there is frame headroom before mounting, returns a quality verdict for the device, hands back a poster state for hardware that will never run the scene, and carries the generation a lost context is recovered from.",
+      fix: "Replace the observer with `useSceneGate({ label, cost })` and render on its `mounted`, keyed on its `generation`.",
+      nudge: 'Call `get_hook("useSceneGate")` for the contract, or `get_pattern("lazy-3d-section")` for the full wiring.'
     }
   ];
 }
@@ -399,9 +648,14 @@ async function analyzeSource(file, source, framework) {
       ...checkClientBoundary(facts, file, framework),
       ...checkOrphanRaf(facts, file),
       ...checkMissingCleanup(facts, file),
+      ...checkOrphanSubscription(facts, file),
       ...checkSetStatePerFrame(facts, file),
+      ...checkLaneDiscipline(facts, file),
       ...checkTransformConflict(facts, file),
-      ...checkReducedMotion(facts, file)
+      ...checkReducedMotion(facts, file),
+      ...checkRenderQualityProps(facts, file),
+      ...checkContextLoss(facts, file),
+      ...checkHandRolledGate(facts, file)
     ].sort((a, b) => a.line - b.line);
     return { file, findings };
   } catch (err) {
@@ -429,8 +683,195 @@ async function checkMotionFiles(files, cwd) {
   return results;
 }
 
+// src/mcp/advisor.ts
+var PHRASE_WEIGHT = 4;
+var WORD_WEIGHT = 1;
+var SUFFIX = "(?:e?s|ing|ed|ly)?";
+function contains(haystack, term) {
+  const body = term.split(/\s+/).map((word) => word.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + SUFFIX).join("\\s+");
+  return new RegExp(`(?:^|[^a-z0-9])${body}(?:[^a-z0-9]|$)`, "i").test(haystack);
+}
+function matchAdvice(request, rules) {
+  const text2 = ` ${request.toLowerCase().replace(/\s+/g, " ")} `;
+  const out = [];
+  for (const rule of rules) {
+    if ((rule.unless ?? []).some((term) => contains(text2, term))) continue;
+    const matched = [];
+    let score = 0;
+    const credit = (term) => {
+      if (matched.includes(term)) return;
+      matched.push(term);
+      score += term.includes(" ") ? PHRASE_WEIGHT : WORD_WEIGHT;
+    };
+    const fromWhen = rule.when.filter((term) => contains(text2, term));
+    const groups = rule.allOf ?? [];
+    const groupHits = groups.map((group) => group.filter((term) => contains(text2, term)));
+    const allGroupsHit = groups.length > 0 && groupHits.every((hits) => hits.length > 0);
+    if (fromWhen.length < (rule.minHits ?? 1) && !allGroupsHit) continue;
+    for (const term of fromWhen) credit(term);
+    if (allGroupsHit) for (const hits of groupHits) for (const term of hits) credit(term);
+    if (matched.length === 0) continue;
+    out.push({ rule, score: score * 1e3 + rule.priority, matched });
+  }
+  return out.sort((a, b) => b.score - a.score);
+}
+function checkCombination(names, hooks) {
+  const byName = new Map(hooks.map((h) => [h.name.toLowerCase(), h]));
+  const notes = [];
+  const resolved = [];
+  for (const raw of names) {
+    const name = raw.trim().replace(/[()]/g, "");
+    const hook = byName.get(name.toLowerCase()) ?? hooks.find((h) => h.exports?.some((e) => e.toLowerCase() === name.toLowerCase()));
+    if (!hook) {
+      notes.push({
+        severity: "error",
+        text: `\`${name}\` is not in the manifest. Call \`list_hooks\` for what exists \u2014 a primitive that was removed is the most likely reason a name looks right and is not.`
+      });
+      continue;
+    }
+    resolved.push(hook);
+  }
+  const owners = resolved.filter((h) => h.runtime.ownsTransform);
+  if (owners.length > 1) {
+    notes.push({
+      severity: "error",
+      text: `${owners.map((h) => `\`${h.name}\``).join(" and ")} each own their element's \`transform\` and write it every frame. On the same element they overwrite each other frame to frame; give each its own node, nesting them if the effects should compose.`
+    });
+  } else if (owners.length === 1) {
+    notes.push({
+      severity: "info",
+      text: `\`${owners[0].name}\` owns its element's \`transform\`. Anything else animating that element's transform \u2014 a CSS transition, a motion library, a hover scale \u2014 belongs on a wrapper or a child.`
+    });
+  }
+  for (const hook of resolved) {
+    for (const conflict of hook.runtime.conflictsWith ?? []) {
+      notes.push({ severity: "warning", text: `\`${hook.name}\`: ${conflict}` });
+    }
+  }
+  const clientOnly = resolved.filter((h) => h.runtime.requiresClient);
+  if (clientOnly.length > 0) {
+    notes.push({
+      severity: "info",
+      text: `${clientOnly.map((h) => `\`${h.name}\``).join(", ")} ${clientOnly.length === 1 ? "is" : "are"} client-only. In an app-router project the file needs \`"use client"\`; \`check_motion\` reports its absence as an error.`
+    });
+  }
+  const rerendering = resolved.filter((h) => (h.runtime.reRendersPerFrame ?? 0) > 0);
+  if (rerendering.length > 0) {
+    notes.push({
+      severity: "warning",
+      text: `${rerendering.map((h) => `\`${h.name}\``).join(", ")} re-render${rerendering.length === 1 ? "s" : ""} during animation. Keep ${rerendering.length === 1 ? "it" : "them"} in a small leaf component so the re-render does not reconcile a subtree that did not change.`
+    });
+  }
+  const shared = /* @__PURE__ */ new Set();
+  for (const hook of resolved) for (const s of hook.runtime.sharedSingletons ?? []) shared.add(s);
+  if (shared.size > 0 && resolved.length > 1) {
+    notes.push({
+      severity: "info",
+      text: `These share ${[...shared].map((s) => `\`${s}\``).join(", ")}. Sharing is the design, not a collision: one frame loop and one set of sensors for the page however many primitives are mounted, so adding another costs a subscriber rather than another loop.`
+    });
+  }
+  return notes;
+}
+var VERDICT_HEADING = {
+  "no-runtime": "You do not need a runtime primitive here",
+  single: "One primitive covers this",
+  composition: "This is a composition \u2014 the order matters",
+  custom: "Nothing covers this directly; build it on the conductor"
+};
+function severityMark(s) {
+  return s === "error" ? "\u2717" : s === "warning" ? "\u25B2" : "\xB7";
+}
+function renderRule(rule, heading) {
+  const lines = [`## ${heading}`, "", `**${rule.headline}**`, "", rule.because, ""];
+  if (rule.verdict === "no-runtime") {
+    if (rule.instead) lines.push(`**Do this instead:** ${rule.instead}`, "");
+  } else {
+    if (rule.use.length > 0) {
+      lines.push(
+        `**Use, in this order:** ${rule.use.map((u) => `\`${u}\``).join(" \u2192 ")}`,
+        ""
+      );
+    }
+    if (rule.pattern) {
+      lines.push(
+        `**Pattern:** \`${rule.pattern}\` \u2014 call \`get_pattern("${rule.pattern}")\` for the wiring order, a complete example, and the pitfalls. Follow it rather than assembling the hooks yourself; the order is the part that is easy to get wrong and hard to notice.`,
+        ""
+      );
+    }
+    if (rule.instead) lines.push(`**This replaces:** ${rule.instead}`, "");
+  }
+  if (rule.components.length > 0) {
+    lines.push(
+      `**Already built:** ${rule.components.map((c) => `\`${c}\``).join(", ")} \u2014 \`get_component\` for the contract if one of these is close enough to install.`,
+      ""
+    );
+  }
+  lines.push(`**When this is the wrong call:** ${rule.notWhen}`, "");
+  return lines;
+}
+function formatPlan({ building, using }) {
+  const manifest = loadHookManifest();
+  const rules = manifest?.advice ?? [];
+  const hooks = manifest?.hooks ?? [];
+  if (rules.length === 0) {
+    return "No advice table is bundled with this build of the server, so this tool cannot answer.\n\nUse `search` to find candidate primitives and `get_pattern` for compositions, then `check_motion` on whatever you write.";
+  }
+  const matches = matchAdvice(building, rules);
+  const out = [`# Plan \u2014 ${building.trim()}`, ""];
+  if (matches.length === 0) {
+    out.push(
+      "## Nothing in the decision table matched this",
+      "",
+      "That is worth taking at face value rather than reaching for the nearest primitive. Two things are usually true when it happens: the effect is a transition between states, which is CSS, or it is genuinely novel, which is a custom effect on the shared conductor.",
+      "",
+      '**If anything about it recomputes every frame**, call `get_pattern("custom-frame-effect")`. That is the skeleton: subscribe to the conductor, read in `input`, compute in `update`, write in `render`, return the unsubscribe. Never start a private `requestAnimationFrame` loop \u2014 it runs outside the frame budget, cannot be shed under load, and is invisible to devtools.',
+      "",
+      "**If it does not**, it is probably a CSS transition or the Web Animations API, and neither costs main-thread time.",
+      "",
+      "`search` with a different wording may also find something this table missed.",
+      ""
+    );
+  } else {
+    const [top, ...rest] = matches;
+    out.push(...renderRule(top.rule, VERDICT_HEADING[top.rule.verdict]));
+    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", "");
+      for (const m of also) {
+        const what = m.rule.verdict === "no-runtime" ? m.rule.instead ?? "the platform equivalent" : m.rule.pattern ? `pattern \`${m.rule.pattern}\`` : m.rule.use.map((u) => `\`${u}\``).join(" + ");
+        out.push(`- **${m.rule.headline}** \u2192 ${what}`);
+      }
+      out.push("", `Ask again with just that part of the request for the full reasoning on any of them.`, "");
+    }
+    const watch = [...new Set(matches.slice(0, 4).flatMap((m) => m.rule.watchFor))];
+    if (watch.length > 0) {
+      out.push(
+        "## After you write it",
+        "",
+        `Run \`check_motion\` on the file. For this shape the findings to expect are ${watch.map((r) => `\`${r}\``).join(", ")} \u2014 each of those is a mistake that compiles, runs, and shows up later as jank, a leak, or an accessibility complaint.`,
+        ""
+      );
+    }
+  }
+  if (using && using.length > 0) {
+    const notes = checkCombination(using, hooks);
+    out.push("## The combination you named", "");
+    if (notes.length === 0) {
+      out.push("Nothing in these contracts conflicts.", "");
+    } else {
+      for (const n of notes) out.push(`- ${severityMark(n.severity)} ${n.text}`);
+      out.push("");
+    }
+  }
+  out.push(
+    "---",
+    "_`plan_motion` matches your description against a hand-written decision table. It is deliberate about recommending nothing when the platform already does the job. Call `get_hook` or `get_pattern` for the contract before writing code, and `check_motion` after._"
+  );
+  return out.join("\n");
+}
+
 // src/mcp/server.ts
-var VERSION = true ? "2.1.1" : "0.0.0-dev";
+var VERSION = true ? "2.4.0" : "0.0.0-dev";
 function text(body) {
   return { content: [{ type: "text", text: body }] };
 }
@@ -650,13 +1091,14 @@ ${p.docsUrl}`);
   );
   return out.join("\n");
 }
-function severityMark(s) {
+function severityMark2(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._";
+var CHECK_SCOPE_NOTE = "_Static analysis \u2014 it catches the common silent motion mistakes (unmanaged loops, missing cleanup, discarded unsubscribes, state-per-frame, work in the wrong frame lane, transform conflicts, canvas props that overrule the adapter, unhandled graphics-context loss, 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; a **note** is a primitive that would do the job better._";
 function formatCheckResults(results) {
   let errors = 0;
   let warnings = 0;
+  let notes = 0;
   let filesWithFindings = 0;
   let unreadable = 0;
   const blocks = [];
@@ -673,20 +1115,26 @@ function formatCheckResults(results) {
     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}`);
+      else notes++;
+      lines.push(`- **${severityMark2(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;
+  const total = errors + warnings + notes;
   const analyzed = results.length - unreadable;
   if (total === 0 && unreadable === 0) {
     return `\u2713 No motion issues found in ${results.length} file${results.length === 1 ? "" : "s"}.
 
 ` + CHECK_SCOPE_NOTE;
   }
-  const headline = total > 0 ? `${total} issue${total === 1 ? "" : "s"} across ${filesWithFindings} file${filesWithFindings === 1 ? "" : "s"} \u2014 ${errors} error${errors === 1 ? "" : "s"}, ${warnings} warning${warnings === 1 ? "" : "s"}.` : `No issues in the ${analyzed} file${analyzed === 1 ? "" : "s"} that could be read.`;
+  const counts = [
+    `${errors} error${errors === 1 ? "" : "s"}`,
+    `${warnings} warning${warnings === 1 ? "" : "s"}`,
+    ...notes > 0 ? [`${notes} note${notes === 1 ? "" : "s"}`] : []
+  ].join(", ");
+  const headline = total > 0 ? `${total} finding${total === 1 ? "" : "s"} across ${filesWithFindings} file${filesWithFindings === 1 ? "" : "s"} \u2014 ${counts}.` : `No issues in the ${analyzed} file${analyzed === 1 ? "" : "s"} that could be read.`;
   const unreadableNote = unreadable > 0 ? `
 \u26A0\uFE0F ${unreadable} file${unreadable === 1 ? "" : "s"} could not be analyzed \u2014 ${unreadable === 1 ? "it was" : "they were"} NOT checked. Fix the path or the syntax and run again.` : "";
   return ["# Motion check", headline + unreadableNote, "", ...blocks, "", CHECK_SCOPE_NOTE].join("\n");
@@ -962,11 +1410,27 @@ Hook discovery still works offline \u2014 try \`list_hooks\`.`
       );
     }
   );
+  server.registerTool(
+    "plan_motion",
+    {
+      title: "Decide whether this needs a motion primitive, and which",
+      description: 'START HERE for any animation, scroll, pointer, video or WebGL work, before `search` and before writing code. Describe what you are building in plain language \u2014 one component or several working together \u2014 and this answers whether it needs a Vector Vesper primitive AT ALL, which ones, in what order, what the combination conflicts with, and when the recommendation would be wrong. It deliberately answers "use CSS, not this runtime" when that is correct, which is often: a hover state, a fade on mount, a spinner and a one-time scroll reveal are all platform features that cost no main-thread time, and wrapping them in a frame loop makes them worse. Pass `using` to have an already-chosen set of primitives checked for transform-ownership collisions and declared conflicts.',
+      inputSchema: {
+        building: z.string().min(3).describe(
+          'What you are building, in plain language. Include the interaction ("follows the cursor", "scrubs with scroll"), the medium (video, canvas, shader, text) and anything about scale ("a grid of 40 cards", "3000 particles") \u2014 each of those changes the answer.'
+        ),
+        using: z.array(z.string()).optional().describe(
+          "Primitives you already intend to use, by name. Returns a combination check: two owners of one transform, declared conflicts, client-boundary requirements, per-frame re-renders."
+        )
+      }
+    },
+    async ({ building, using }) => text(formatPlan({ building, using }))
+  );
   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.",
+      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, black canvases, or accessibility problems: a self-scheduling requestAnimationFrame loop running outside the shared frame budget, a listener/observer/timeline never torn down, a runtime subscription whose unsubscribe was discarded, a setState fired every frame, a frame callback reading layout in the write lane, one element's transform animated by two owners at once, a <Canvas> prop that silently overrules the adapter that set it, a WebGL scene with nothing watching for a lost graphics context, 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.")
@@ -986,7 +1450,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\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.'
+      instructions: 'Vector Vesper\'s motion runtime and component registry.\n\nThe workflow is: decide \u2192 read the contract \u2192 write \u2192 check.\n\n**Decide first.** For any animation, scroll, pointer, video or WebGL task, call `plan_motion` with a plain-language description of what you are building, before `search` and before writing code. It answers whether this needs a primitive AT ALL, which ones, in what order, and when that recommendation would be wrong. Take its refusals seriously: a hover state, a fade on mount, a spinner and a one-time scroll reveal are platform features that run on the compositor and cost no main-thread time, and reimplementing any of them on a frame loop makes the page worse. When `plan_motion` says to use CSS, use CSS \u2014 do not then reach for a hook. Pass `using` to have a set of primitives you have already chosen checked for transform-ownership collisions and declared conflicts.\n\n**Then read the contract.** `get_hook` / `get_pattern` / `get_component` for whatever `plan_motion` named. 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. `search` and `list_hooks` remain the way to browse when you want to see everything rather than be told what to use.\n\nWhen the task COMBINES primitives (scrollytelling, a predictive media card, an adaptive hero, a marquee) follow the pattern `plan_motion` names rather than assembling the hooks yourself: a pattern carries the wiring order, one complete example, the pitfalls with the `check_motion` rule that catches each, and how to verify. When nothing 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\n**Then check.** After 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, a discarded unsubscribe, state written every frame, layout read in the write lane, a transform animated by two owners, a canvas prop that silently overrules the adapter that set it, a WebGL scene with nothing watching for a lost context, 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);