@pixel-point/toolcraft 0.0.11 → 0.0.13

package/src/generate.test.mjs

@@ -73,6 +73,7 @@ describe("generateToolcraft", () => {
     assert.equal(packageJson.dependencies["@repo/toolcraft-runtime"], undefined);
     assert.equal(packageJson.dependencies["@tanstack/react-router"], "1.170.6");
     assert.equal(packageJson.dependencies.cmdk, "^1.1.1");
+    assert.equal(packageJson.dependencies["cross-spawn"], "^7.0.6");
     assert.equal(packageJson.dependencies["react-resizable-panels"], "^4.10.0");
     assert.equal(packageJson.dependencies.sonner, "^2.0.7");
     assert.equal(packageJson.devDependencies["@repo/typescript-config"], undefined);
@@ -93,18 +94,21 @@ describe("generateToolcraft", () => {
       packageJson.scripts.test,
       "node scripts/check-toolcraft-docs.mjs && node scripts/check-toolcraft-integrity.mjs && node --test scripts/*.test.mjs && vitest run src --passWithNoTests",
     );
-    assert.equal(packageJson.scripts["test:browser"], "playwright install chromium && playwright test");
+    assert.equal(
+      packageJson.scripts["test:browser"],
+      'playwright install chromium && playwright test --grep-invert "browser perf:"',
+    );
     assert.equal(
       packageJson.scripts["test:browser:perf"],
-      "playwright install chromium && playwright test e2e/app-performance.spec.ts --workers=1 && playwright test --grep \"browser perf:\" --workers=1 --pass-with-no-tests",
+      "playwright install chromium && playwright test --grep \"browser perf:\" --workers=1 --pass-with-no-tests",
     );
-    assert.equal(packageJson.scripts["verify:quick"], "pnpm ai:check && pnpm test");
-    assert.equal(packageJson.scripts["verify:ui"], "pnpm test:browser");
-    assert.equal(packageJson.scripts["verify:perf"], "pnpm test:browser:perf");
-    assert.equal(packageJson.scripts["verify:perf:playwright"], "pnpm test:browser:perf");
+    assert.equal(packageJson.scripts["verify:quick"], "npm run ai:check && npm run test");
+    assert.equal(packageJson.scripts["verify:ui"], "npm run test:browser");
+    assert.equal(packageJson.scripts["verify:perf"], "npm run test:browser:perf");
+    assert.equal(packageJson.scripts["verify:perf:playwright"], "npm run test:browser:perf");
     assert.equal(
       packageJson.scripts["verify:final"],
-      "pnpm ai:check && pnpm test && pnpm build && pnpm test:browser",
+      "npm run ai:check && npm run test && npm run build && npm run test:browser",
     );
 
     const indexHtmlSource = await fs.readFile(path.join(targetDir, "index.html"), "utf8");
@@ -142,6 +146,15 @@ describe("generateToolcraft", () => {
     assert.ok(await fs.stat(path.join(targetDir, "scripts/check-toolcraft-docs.mjs")));
     assert.ok(await fs.stat(path.join(targetDir, "scripts/check-toolcraft-integrity.mjs")));
     assert.ok(await fs.stat(path.join(targetDir, "scripts/run-vite-on-free-port.mjs")));
+    const runViteSource = await fs.readFile(
+      path.join(targetDir, "scripts/run-vite-on-free-port.mjs"),
+      "utf8",
+    );
+    assert.match(runViteSource, /node_modules/);
+    assert.match(runViteSource, /\.bin/);
+    assert.match(runViteSource, /vite\.cmd/);
+    assert.match(runViteSource, /from "cross-spawn"/);
+    assert.doesNotMatch(runViteSource, /pnpmCommand|pnpm\.cmd|pnpm",/);
     assert.ok(await fs.stat(path.join(targetDir, "LICENSE.md")));
     assert.ok(await fs.stat(path.join(targetDir, "NOTICE.md")));
     assert.ok(await fs.stat(path.join(targetDir, "docs/toolcraft/README.md")));
@@ -229,14 +242,14 @@ describe("generateToolcraft", () => {
     assert.match(agentsSource, /Required AI Workflow Skills/);
     assert.match(agentsSource, /Verification Tier Classifier/);
     assert.match(agentsSource, /Verification tier: Tier N/);
-    assert.match(agentsSource, /pnpm verify:quick/);
-    assert.match(agentsSource, /pnpm verify:final/);
-    assert.match(agentsSource, /pnpm ai:check/);
+    assert.match(agentsSource, /npm run verify:quick/);
+    assert.match(agentsSource, /npm run verify:final/);
+    assert.match(agentsSource, /npm run ai:check/);
     assert.match(agentsSource, /use `brainstorming`/);
     assert.match(agentsSource, /use `writing-plans`/);
     assert.match(agentsSource, /use `systematic-debugging`/);
     assert.match(agentsSource, /browser` workflow/);
-    assert.match(agentsSource, /pnpm test:browser/);
+    assert.match(agentsSource, /npm run test:browser/);
     assert.match(agentsSource, /Do not silently skip required workflow skills/);
     assert.match(agentsSource, /Toolcraft app contract overrides generic brainstorming approval/);
     assert.match(agentsSource, /Do not ask the user to confirm decisions already covered/);
@@ -343,6 +356,54 @@ describe("generateToolcraft", () => {
     );
   });
 
+  it("generates package-manager-specific commands for pnpm apps", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "toolcraft-cli-"));
+    tempRoots.push(tempRoot);
+    const targetDir = path.join(tempRoot, "pnpm-app");
+
+    await generateToolcraft({
+      cwd: tempRoot,
+      force: true,
+      name: "Pnpm App",
+      packageManager: "pnpm",
+      targetDir: "pnpm-app",
+    });
+
+    const packageJson = JSON.parse(await fs.readFile(path.join(targetDir, "package.json"), "utf8"));
+    assert.equal(packageJson.scripts["verify:quick"], "pnpm ai:check && pnpm test");
+    assert.equal(packageJson.scripts["verify:ui"], "pnpm test:browser");
+    assert.equal(packageJson.scripts["verify:perf"], "pnpm test:browser:perf");
+    assert.equal(packageJson.scripts["verify:perf:playwright"], "pnpm test:browser:perf");
+    assert.equal(
+      packageJson.scripts["verify:final"],
+      "pnpm ai:check && pnpm test && pnpm build && pnpm test:browser",
+    );
+
+    const playwrightConfigSource = await fs.readFile(
+      path.join(targetDir, "playwright.config.ts"),
+      "utf8",
+    );
+    assert.match(playwrightConfigSource, /pnpm exec vite dev/);
+    assert.doesNotMatch(playwrightConfigSource, /npm exec -- vite/);
+
+    const agentsSource = await fs.readFile(path.join(targetDir, "AGENTS.md"), "utf8");
+    assert.match(agentsSource, /pnpm verify:quick/);
+    assert.match(agentsSource, /pnpm verify:final/);
+    assert.match(agentsSource, /pnpm test:browser/);
+    assert.doesNotMatch(agentsSource, /npm run verify:quick/);
+
+    const worklogSource = await fs.readFile(
+      path.join(targetDir, "docs/toolcraft/agent-worklog.md"),
+      "utf8",
+    );
+    assert.match(worklogSource, /pnpm verify:quick/);
+    assert.match(worklogSource, /pnpm verify:final/);
+
+    await execFileAsync(process.execPath, [path.join(targetDir, "scripts/check-toolcraft-docs.mjs")], {
+      cwd: targetDir,
+    });
+  });
+
   it("writes the app identity marker when the generated title matches the template title", async () => {
     const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "toolcraft-cli-"));
     tempRoots.push(tempRoot);

package/src/package-json.mjs

@@ -1,3 +1,5 @@
+import { DEFAULT_PACKAGE_MANAGER, createVerificationScripts } from "./package-manager.mjs";
+
 export function sanitizePackageName(value) {
   const sanitized = String(value ?? "")
     .trim()
@@ -44,7 +46,11 @@ function addDependencyGroup(packageJson, groupName, dependencies) {
   }
 }
 
-export function createGeneratedPackageJson({ name, starterPackageJson }) {
+export function createGeneratedPackageJson({
+  name,
+  packageManager = DEFAULT_PACKAGE_MANAGER,
+  starterPackageJson,
+}) {
   if (!starterPackageJson || typeof starterPackageJson !== "object") {
     throw new Error("starterPackageJson is required to create a generated package manifest.");
   }
@@ -54,7 +60,10 @@ export function createGeneratedPackageJson({ name, starterPackageJson }) {
     private: true,
     license: starterPackageJson.license,
     type: starterPackageJson.type ?? "module",
-    scripts: starterPackageJson.scripts ?? {},
+    scripts: {
+      ...(starterPackageJson.scripts ?? {}),
+      ...createVerificationScripts(packageManager),
+    },
   };
 
   addDependencyGroup(packageJson, "dependencies", starterPackageJson.dependencies);

package/src/package-json.test.mjs

@@ -58,6 +58,12 @@ describe("createGeneratedPackageJson", () => {
       scripts: {
         dev: "vite dev",
         test: "vitest run",
+        "verify:final":
+          "npm run ai:check && npm run test && npm run build && npm run test:browser",
+        "verify:perf": "npm run test:browser:perf",
+        "verify:perf:playwright": "npm run test:browser:perf",
+        "verify:quick": "npm run ai:check && npm run test",
+        "verify:ui": "npm run test:browser",
       },
       dependencies: {
         "@tanstack/react-router": "1.170.6",
@@ -77,4 +83,25 @@ describe("createGeneratedPackageJson", () => {
       /starterPackageJson is required/,
     );
   });
+
+  it("generates verification scripts for the selected package manager", () => {
+    const packageJson = createGeneratedPackageJson({
+      name: "Generated App",
+      packageManager: "pnpm",
+      starterPackageJson: {
+        scripts: {
+          dev: "vite dev",
+        },
+      },
+    });
+
+    assert.deepEqual(packageJson.scripts, {
+      dev: "vite dev",
+      "verify:final": "pnpm ai:check && pnpm test && pnpm build && pnpm test:browser",
+      "verify:perf": "pnpm test:browser:perf",
+      "verify:perf:playwright": "pnpm test:browser:perf",
+      "verify:quick": "pnpm ai:check && pnpm test",
+      "verify:ui": "pnpm test:browser",
+    });
+  });
 });

package/src/package-manager.mjs

@@ -0,0 +1,123 @@
+export const DEFAULT_PACKAGE_MANAGER = "npm";
+
+const PACKAGE_MANAGER_SPECS = {
+  npm: {
+    installHelp: ["  Install Node.js from https://nodejs.org/"],
+    installArgs: ["install"],
+    runScript(scriptName) {
+      return `npm run ${scriptName}`;
+    },
+    exec(binaryName, args = []) {
+      return ["npm", "exec", "--", binaryName, ...args].join(" ");
+    },
+  },
+  pnpm: {
+    installHelp: ["  corepack enable", "  corepack prepare pnpm@latest --activate"],
+    installArgs: ["install"],
+    runScript(scriptName) {
+      return `pnpm ${scriptName}`;
+    },
+    exec(binaryName, args = []) {
+      return ["pnpm", "exec", binaryName, ...args].join(" ");
+    },
+  },
+};
+
+const PACKAGE_MANAGER_NAMES = new Set(Object.keys(PACKAGE_MANAGER_SPECS));
+
+const GENERATED_SCRIPT_COMMANDS = [
+  "ai:check",
+  "build",
+  "dev",
+  "dev:restart",
+  "preview",
+  "preview:restart",
+  "test",
+  "test:browser",
+  "test:browser:perf",
+  "verify:final",
+  "verify:perf",
+  "verify:perf:playwright",
+  "verify:quick",
+  "verify:ui",
+];
+
+function getSpec(packageManager) {
+  return PACKAGE_MANAGER_SPECS[normalizePackageManager(packageManager)];
+}
+
+function replaceAllExact(source, replacements) {
+  let next = String(source);
+
+  for (const [from, to] of replacements) {
+    next = next.split(from).join(to);
+  }
+
+  return next;
+}
+
+export function normalizePackageManager(value, fallback = DEFAULT_PACKAGE_MANAGER) {
+  return PACKAGE_MANAGER_NAMES.has(value) ? value : fallback;
+}
+
+export function detectPackageManager(env = process.env) {
+  const userAgent = String(env.npm_config_user_agent ?? "");
+  const [packageManager] = userAgent.split("/", 1);
+  return normalizePackageManager(packageManager);
+}
+
+export function createInstallCommand(packageManager) {
+  const spec = getSpec(packageManager);
+
+  return {
+    args: [...spec.installArgs],
+    command: normalizePackageManager(packageManager),
+  };
+}
+
+export function createInstallHelp(packageManager) {
+  return [...getSpec(packageManager).installHelp];
+}
+
+export function createRunScriptCommand(packageManager, scriptName) {
+  return getSpec(packageManager).runScript(scriptName);
+}
+
+export function createExecCommand(packageManager, binaryName, args = []) {
+  return getSpec(packageManager).exec(binaryName, args);
+}
+
+export function createVerificationScripts(packageManager) {
+  return {
+    "verify:quick": [
+      createRunScriptCommand(packageManager, "ai:check"),
+      createRunScriptCommand(packageManager, "test"),
+    ].join(" && "),
+    "verify:ui": createRunScriptCommand(packageManager, "test:browser"),
+    "verify:perf": createRunScriptCommand(packageManager, "test:browser:perf"),
+    "verify:perf:playwright": createRunScriptCommand(packageManager, "test:browser:perf"),
+    "verify:final": [
+      createRunScriptCommand(packageManager, "ai:check"),
+      createRunScriptCommand(packageManager, "test"),
+      createRunScriptCommand(packageManager, "build"),
+      createRunScriptCommand(packageManager, "test:browser"),
+    ].join(" && "),
+  };
+}
+
+export function createGeneratedCommandReplacements(packageManager) {
+  const replacements = [
+    ["pnpm exec vite", createExecCommand(packageManager, "vite")],
+    ["pnpm install", `${normalizePackageManager(packageManager)} install`],
+  ];
+
+  for (const scriptName of GENERATED_SCRIPT_COMMANDS) {
+    replacements.push([`pnpm ${scriptName}`, createRunScriptCommand(packageManager, scriptName)]);
+  }
+
+  return replacements.sort(([left], [right]) => right.length - left.length);
+}
+
+export function replaceGeneratedCommandReferences(source, packageManager) {
+  return replaceAllExact(source, createGeneratedCommandReplacements(packageManager));
+}

package/src/package-manager.test.mjs

@@ -0,0 +1,80 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import {
+  createExecCommand,
+  createInstallCommand,
+  createRunScriptCommand,
+  createVerificationScripts,
+  detectPackageManager,
+  replaceGeneratedCommandReferences,
+} from "./package-manager.mjs";
+
+describe("detectPackageManager", () => {
+  it("uses the npm user agent when the CLI is launched through npx", () => {
+    assert.equal(
+      detectPackageManager({
+        npm_config_user_agent: "npm/10.9.4 node/v24.4.1 darwin arm64 workspaces/false",
+      }),
+      "npm",
+    );
+  });
+
+  it("detects supported package manager launchers", () => {
+    assert.equal(detectPackageManager({ npm_config_user_agent: "pnpm/10.12.4 npm/? node/v24.4.1" }), "pnpm");
+  });
+
+  it("falls back to npm when no supported package manager is detected", () => {
+    assert.equal(detectPackageManager({}), "npm");
+    assert.equal(detectPackageManager({ npm_config_user_agent: "unknown/1.0.0" }), "npm");
+    assert.equal(detectPackageManager({ npm_config_user_agent: "yarn/1.22.22 npm/? node/v24.4.1" }), "npm");
+    assert.equal(detectPackageManager({ npm_config_user_agent: "bun/1.2.0 npm/? node/v24.4.1" }), "npm");
+  });
+});
+
+describe("package manager commands", () => {
+  it("formats install, run, exec, and verification commands for npm", () => {
+    assert.deepEqual(createInstallCommand("npm"), {
+      args: ["install"],
+      command: "npm",
+    });
+    assert.equal(createRunScriptCommand("npm", "dev"), "npm run dev");
+    assert.equal(createExecCommand("npm", "vite", ["dev"]), "npm exec -- vite dev");
+    assert.deepEqual(createVerificationScripts("npm"), {
+      "verify:final":
+        "npm run ai:check && npm run test && npm run build && npm run test:browser",
+      "verify:perf": "npm run test:browser:perf",
+      "verify:perf:playwright": "npm run test:browser:perf",
+      "verify:quick": "npm run ai:check && npm run test",
+      "verify:ui": "npm run test:browser",
+    });
+  });
+
+  it("formats run and exec commands for pnpm", () => {
+    assert.equal(createRunScriptCommand("pnpm", "dev"), "pnpm dev");
+    assert.equal(createExecCommand("pnpm", "vite", ["dev"]), "pnpm exec vite dev");
+  });
+
+  it("replaces known generated command references for npm", () => {
+    const source = [
+      "pnpm install",
+      "pnpm verify:final",
+      "pnpm verify:perf",
+      "pnpm test:browser",
+      "pnpm dev",
+      "pnpm exec vite dev --host 127.0.0.1",
+    ].join("\n");
+
+    assert.equal(
+      replaceGeneratedCommandReferences(source, "npm"),
+      [
+        "npm install",
+        "npm run verify:final",
+        "npm run verify:perf",
+        "npm run test:browser",
+        "npm run dev",
+        "npm exec -- vite dev --host 127.0.0.1",
+      ].join("\n"),
+    );
+  });
+});

package/templates/runtime/contracts/component-contracts.test.ts

@@ -153,6 +153,28 @@ describe("Toolcraft template component contracts", () => {
     expect(contract.aiUsageRules).toContain(
       "Multiple vector controls should live in separate semantic sections unless they intentionally belong to the same entity with other related controls.",
     );
+    expect(contract.decisionCatalog?.ownsValueModel).toEqual(
+      expect.arrayContaining([
+        "user-authored stable position",
+        "user-authored stable offset",
+        "user-authored stable direction",
+      ]),
+    );
+    expect(contract.decisionCatalog?.useWhen).toContain(
+      "Use Vector for paired X/Y values only when the user is meant to manually author a stable two-axis product parameter such as position, offset, direction, focus, anchor, light direction, or color-balance movement.",
+    );
+    expect(contract.decisionCatalog?.doNotReplaceWith).toContain(
+      "Do not replace animation, keyboard input, pointer input, physics, timeline phase, velocity, or simulated pose state with Vector just because the internal value has x/y coordinates.",
+    );
+    expect(contract.decisionCatalog?.acceptableAlternatives).toContain(
+      "Use timeline, keyboard/pointer handlers, motion sliders, path/step controls, or renderer simulation state when movement is generated by animation or user input rather than authored as a stable panel value.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Use Vector only for user-authored stable two-axis product parameters. Do not expose Vector for current animation state, keyboard movement, pointer movement, physics state, timeline phase, velocity, target pose, current pose, or simulated position/direction.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Before adding a Vector control to an animated or interactive product, classify movement ownership as direct-authored, timeline-driven, keyboard/pointer-driven, or simulation-owned. Only direct-authored movement may become a visible Vector control; the other ownership modes stay in renderer/runtime interaction state and use controls such as Speed, Step, Spread, Path, Duration, or Timeline when the user needs tuning.",
+    );
     expect(contract.aiUsageRules).toContain(
       'Use variant: "whiteBalance" for temperature/tint pads: X maps cool blue to warm amber, Y maps green to magenta.',
     );
@@ -178,7 +200,7 @@ describe("Toolcraft template component contracts", () => {
       'Use coordinateMode: "cartesian" only when the product intentionally exposes mathematical Y-up coordinates instead of canvas/screen movement.',
     );
     expect(contract.aiUsageRules).toContain(
-      "Vector is a compound control; acceptance must prove vector.x and vector.y both affect the product output.",
+      "Vector is a compound control; acceptance must prove vector.x and vector.y both affect the product output and that the vector represents a user-authored stable two-axis parameter rather than current animation, input, or simulation state.",
     );
   });
 
@@ -652,7 +674,7 @@ describe("Toolcraft template component contracts", () => {
       "RangeSlider defaultValue must start with different lower and upper values so the two-thumb control does not collapse into a single-value slider.",
     );
     expect(rangeSlider.aiUsageRules).toContain(
-      "Manual range value editing accepts common separators such as slash, hyphen, spaces, and dashes; do not create custom parsers for RangeSlider labels.",
+      "Manual range value editing accepts common separators such as slash, hyphen, spaces, and dashes, including when values include unit suffixes such as 30%-150% or 30% - 90%; do not create custom parsers for RangeSlider labels.",
     );
     expect(rangeSlider.aiUsageRules).toContain(
       "Visual discrete sliders must still drag smoothly; browser performance tests should use expectToolcraftDiscreteSliderDragSmoothness for real pointer drag.",
@@ -794,6 +816,9 @@ describe("Toolcraft template component contracts", () => {
     expect(anchorGrid.aiUsageRules).toContain(
       "AnchorGrid is a position selector; acceptance must prove anchorGrid.position changes product placement, not only selected button state.",
     );
+    expect(anchorGrid.decisionCatalog?.acceptableAlternatives).toContain(
+      "Use Vector only for stable direct-authored continuous position or direction parameters.",
+    );
     expect(channelMixer.aiUsageRules).toContain(
       "ChannelMixer is RGB-specific: it renders R/G/B tabs and Red, Green, Blue sliders for an RGB channel matrix.",
     );
@@ -904,7 +929,7 @@ describe("Toolcraft template component contracts", () => {
       "Performance matrices must declare rendererWorkload as none, simple-composition, text-output, vector-output, or pixel-output.",
     );
     expect(contract.aiUsageRules).toContain(
-      "A full performance checkpoint must run only when the first working app version exists or the user requests performance, lag, jank, animation speed, drag/zoom stabilization work, or otherwise complains about performance; use the agent-controlled browser first and pnpm verify:perf only as the Playwright fallback.",
+      "A full performance checkpoint must run only when the first working app version exists or the user requests performance, lag, jank, animation speed, drag/zoom stabilization work, or otherwise complains about performance; use the agent-controlled browser first and this app's verify:perf script only as the Playwright fallback.",
     );
     expect(contract.aiUsageRules).toContain(
       "Renderer, canvas, animation, export, timeline, layers, canvas.renderScale, bug fixes, and performance-sensitive control changes use targeted functional/browser checks first and targeted performance scenarios only for touched workload, viewport, or export paths.",

package/templates/runtime/contracts/component-contracts.ts

@@ -115,7 +115,7 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       "Compact symbol/CSS units render tight, such as 20% – 80% or 12px – 48px; word units render with a space when truly needed.",
       "RangeSlider is always a full-width two-thumb control; never place it in an inline two-column layout group with another slider or range slider.",
       "RangeSlider defaultValue must start with different lower and upper values so the two-thumb control does not collapse into a single-value slider.",
-      "Manual range value editing accepts common separators such as slash, hyphen, spaces, and dashes; do not create custom parsers for RangeSlider labels.",
+      "Manual range value editing accepts common separators such as slash, hyphen, spaces, and dashes, including when values include unit suffixes such as 30%-150% or 30% - 90%; do not create custom parsers for RangeSlider labels.",
       'Specs, plans, and app-schema tests must assert explicit discrete range sliders render as variant: "discrete" with markers derived from min, max, and step.',
       "Visual discrete sliders must still drag smoothly; browser performance tests should use expectToolcraftDiscreteSliderDragSmoothness for real pointer drag.",
       "Use visibleWhen for range sliders that are meaningful only in some mode/type/source/include/count states; inactive branches should disappear so the panel shows only controls usable in the current state.",
@@ -592,21 +592,23 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       strictness: "exact-owner",
       ownsValueModel: [
         "x/y vector",
-        "position",
-        "offset",
-        "direction",
+        "user-authored stable position",
+        "user-authored stable offset",
+        "user-authored stable direction",
         "focus point",
         "light vector",
         "color balance pad",
       ],
       useWhen: [
-        "Use Vector for paired X/Y values such as position, offset, direction, focus, anchor, light direction, or color-balance movement.",
+        "Use Vector for paired X/Y values only when the user is meant to manually author a stable two-axis product parameter such as position, offset, direction, focus, anchor, light direction, or color-balance movement.",
       ],
       doNotReplaceWith: [
         "Do not replace Vector with two unrelated sliders or text inputs when direct two-axis editing is the product interaction.",
+        "Do not replace animation, keyboard input, pointer input, physics, timeline phase, velocity, or simulated pose state with Vector just because the internal value has x/y coordinates.",
       ],
       acceptableAlternatives: [
         "Use two numeric text fields only when exact numeric entry is the primary product requirement.",
+        "Use timeline, keyboard/pointer handlers, motion sliders, path/step controls, or renderer simulation state when movement is generated by animation or user input rather than authored as a stable panel value.",
       ],
       layoutConstraints: [
         "One vector renders as a square pad; multiple vectors render compact pads.",
@@ -619,6 +621,8 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       "If the controls panel contains exactly one vector control, the runtime renders the vector pad as a square.",
       "If the controls panel contains multiple vector controls, the runtime renders compact vector pads.",
       "Multiple vector controls should live in separate semantic sections unless they intentionally belong to the same entity with other related controls.",
+      "Use Vector only for user-authored stable two-axis product parameters. Do not expose Vector for current animation state, keyboard movement, pointer movement, physics state, timeline phase, velocity, target pose, current pose, or simulated position/direction.",
+      "Before adding a Vector control to an animated or interactive product, classify movement ownership as direct-authored, timeline-driven, keyboard/pointer-driven, or simulation-owned. Only direct-authored movement may become a visible Vector control; the other ownership modes stay in renderer/runtime interaction state and use controls such as Speed, Step, Spread, Path, Duration, or Timeline when the user needs tuning.",
       'Use variant: "whiteBalance" for temperature/tint pads: X maps cool blue to warm amber, Y maps green to magenta.',
       'Use variant: "colorBalance" for paired color-balance axes such as cyan/red and blue/yellow correction.',
       'Use variant: "chromaOffset" for RGB/chromatic offset vectors where the X/Y movement controls channel separation.',
@@ -630,7 +634,7 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       "Holding Shift while dragging a vector pad locks movement to the dominant axis and must not select text or page content; do not build a custom pad just to support axis-constrained movement.",
       'Use coordinateMode: "cartesian" only when the product intentionally exposes mathematical Y-up coordinates instead of canvas/screen movement.',
       "Do not add custom vector sizing props in generated schemas; choose the number, variant, and section grouping from product need and let the runtime size the pads.",
-      "Vector is a compound control; acceptance must prove vector.x and vector.y both affect the product output.",
+      "Vector is a compound control; acceptance must prove vector.x and vector.y both affect the product output and that the vector represents a user-authored stable two-axis parameter rather than current animation, input, or simulation state.",
     ],
   },
   color: {
@@ -832,7 +836,7 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
         "Do not use AnchorGrid for freeform two-axis movement; use Vector.",
       ],
       acceptableAlternatives: [
-        "Use Vector for continuous position or direction.",
+        "Use Vector only for stable direct-authored continuous position or direction parameters.",
       ],
       layoutConstraints: [
         "AnchorGrid is a standalone position selector.",
@@ -1182,7 +1186,7 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       "Expensive renderers must cache decoded media, source pixels, glyph atlases, gradients, and other reusable inputs by media id, canvas size, and stable control keys.",
       "Slider drags and high-frequency controls must debounce or coalesce preview work, cancel stale async renders, and avoid re-decoding media on every control change.",
       "Performance matrices must declare rendererWorkload as none, simple-composition, text-output, vector-output, or pixel-output.",
-      "A full performance checkpoint must run only when the first working app version exists or the user requests performance, lag, jank, animation speed, drag/zoom stabilization work, or otherwise complains about performance; use the agent-controlled browser first and pnpm verify:perf only as the Playwright fallback.",
+      "A full performance checkpoint must run only when the first working app version exists or the user requests performance, lag, jank, animation speed, drag/zoom stabilization work, or otherwise complains about performance; use the agent-controlled browser first and this app's verify:perf script only as the Playwright fallback.",
       "Renderer, canvas, animation, export, timeline, layers, canvas.renderScale, bug fixes, and performance-sensitive control changes use targeted functional/browser checks first and targeted performance scenarios only for touched workload, viewport, or export paths.",
       "Performance fixes must preserve selected output and preview quality; do not reduce image quality, selected renderScale, export resolution, source media fidelity, or canvas backing pixels as the hidden way to pass budgets.",
       "When canvas or slider interactions lag, diagnose where the slowdown comes from before changing output quality: renderer technique, React update frequency, decoded media, shader/program setup, buffer uploads, layout work, async render cancellation, or animation scheduling.",

package/templates/runtime/react/controls-panel.test.tsx

@@ -2782,9 +2782,13 @@ describe("ControlsPanel", () => {
 
     for (const [draftValue, expectedValue, expectedLabel] of [
       ["0/1", '"shape.range":[0,1]', "0% – 1%"],
+      ["3/5", '"shape.range":[3,5]', "3% – 5%"],
       ["1-6", '"shape.range":[1,6]', "1% – 6%"],
       ["2-3", '"shape.range":[2,3]', "2% – 3%"],
       ["4 - 5", '"shape.range":[4,5]', "4% – 5%"],
+      ["30%-150%", '"shape.range":[30,100]', "30% – 100%"],
+      ["30% - 90%", '"shape.range":[30,90]', "30% – 90%"],
+      ["30 % - 90 %", '"shape.range":[30,90]', "30% – 90%"],
       ["6–7", '"shape.range":[6,7]', "6% – 7%"],
       ["7—8", '"shape.range":[7,8]', "7% – 8%"],
       ["8−9", '"shape.range":[8,9]', "8% – 9%"],

package/templates/starter/AGENTS.md

@@ -114,7 +114,7 @@ AI must work on this app through the required workflow skills when the environme
 - Before editing code from an approved spec, use `writing-plans` to produce a deterministic implementation plan focused on app files, tests, build, and browser verification.
 - Before fixing any broken control, failed test, build failure, visual mismatch, export issue, or runtime regression, use `systematic-debugging` to find the root cause first.
 - When the prompt includes a Figma URL, use Figma MCP/design context before implementation. Read the actual node, layer, component, variable, and asset structure; screenshots are only for final visual QA, not the source of truth.
-- After implementation, use the `browser` workflow or equivalent local browser verification to test the running app, not only typecheck/build output. The default browser gate is `pnpm test:browser`; it excludes `browser perf:` budget scenarios and leaves the performance audit disabled unless the perf checkpoint runner sets `TOOLCRAFT_PERF_CHECK=1`. `pnpm test:browser:perf` is reserved for full performance checkpoints.
+- After implementation, use the `browser` workflow or equivalent local browser verification to test the running app, not only typecheck/build output. The default browser gate is `pnpm test:browser`; it excludes every Playwright test whose name contains `browser perf:`, including performance audit and budget scenarios. `pnpm test:browser:perf` is reserved for full performance checkpoints.
 - Run `pnpm ai:check` before app generation or major changes.
 - If a required skill is missing and the environment supports skill installation, install it before implementation and restart or refresh the session if the skill list does not update.
 - If skill installation is not available, stop before implementation and tell the user exactly which required skills are missing.
@@ -168,7 +168,7 @@ For the first working product delivery, run the browser performance checkpoint a
 
 Use `pnpm install` before this final gate when the folder is fresh or dependencies changed.
 
-`pnpm test` must include `node scripts/check-toolcraft-docs.mjs`, `node scripts/check-toolcraft-integrity.mjs`, and app tests. `pnpm verify:ui` / `pnpm test:browser` must run against the real app UI and product output but must not run `browser perf:` budget scenarios or the performance audit. `pnpm verify:perf` / `pnpm test:browser:perf` remains available as the Playwright fallback for the two full-performance triggers and must run the performance audit plus browser budget suite sequentially so budgets are measured without parallel e2e noise.
+`pnpm test` must include `node scripts/check-toolcraft-docs.mjs`, `node scripts/check-toolcraft-integrity.mjs`, and app tests. `pnpm verify:ui` / `pnpm test:browser` must run against the real app UI and product output but must not run any Playwright test whose name contains `browser perf:`. `pnpm verify:perf` / `pnpm test:browser:perf` remains available as the Playwright fallback for the two full-performance triggers and must run the performance audit plus browser budget suite sequentially so budgets are measured without parallel e2e noise.
 
 Do not stop or kill existing local servers to free a port during a first start. `pnpm dev`, `pnpm preview`, and browser verification prefer port `3002`, but automatically move to the next free port only while assigning this app's first saved port. After a saved port exists, normal `pnpm dev` / `pnpm preview` uses that same port; if that port is already serving this app, report that existing URL instead of starting a duplicate. Use `TOOLCRAFT_PORT`, `TOOLCRAFT_DEV_PORT`, or `TOOLCRAFT_TEST_PORT` only to change the preferred starting port before a saved port exists. A dev/preview launch is successful only after the selected port serves this app's Toolcraft server identity endpoint plus the `toolcraft-app-title` marker from `index.html`; never report a URL just because some server is listening there. When deliberately restarting this app server, use `pnpm dev:restart` or `pnpm preview:restart`; restart mode reuses the previously saved app port, stops the listener on that exact port if it is still running, force-stops it if it does not release the port, starts on the same port again, and verifies the identity before saving/reporting the port.
 

package/templates/starter/docs/toolcraft/acceptance-testing.md

@@ -95,6 +95,8 @@ For `curves`, the acceptance row must match the intended variant. Semantic one-d
 
 For `fontPicker`, product output evidence must come from actual rendered/exported product text after changing the font, weight, size, letter spacing, line height, text case, color, and opacity. Runtime value changes, selected labels, or popup font previews are preflight checks, not final acceptance.
 
+For `vector`, acceptance must prove both axes affect output and that the pad represents a user-authored stable two-axis parameter. Do not accept `vector` controls for current animation state, keyboard/pointer movement, physics state, timeline phase, velocity, target pose, current pose, or simulated position/direction; those belong to timeline/input/simulation state plus higher-level tuning controls such as Speed, Step, Spread, Path, Duration, or Timeline.
+
 ## Control Selection Gates
 
 Acceptance must catch wrong-substitution failures. If the prompt, spec, or app behavior needs a value model owned by a built-in control, the schema must use that built-in or include a documented built-in fit check.
@@ -108,7 +110,7 @@ High-confidence wrong-substitution cases:
 - repeatable user-editable item sets without `collectionActions` or another justified collection owner;
 - from/to range without `rangeSlider` or `rangeInput`;
 - curve, remap, easing, or response without `curves`;
-- position, direction, focus, or vector without `vector`;
+- manual stable two-axis position, direction, focus, anchor, light, or vector parameters without `vector`;
 - source upload without `fileDrop`;
 - app-wide transport in the controls panel instead of timeline;
 - segmented choices that clip instead of falling back to `select`;

package/templates/starter/docs/toolcraft/assembly-workflow.md

@@ -247,6 +247,6 @@ pnpm verify:final
 pnpm dev
 ```
 
-Browser verification must use the real Toolcraft shell plus renderer output. `pnpm verify:final` runs the full static, build, and browser functional gate. The browser performance checkpoint is intentionally separate and only runs for the two full-performance triggers; `pnpm verify:perf` is the Playwright fallback command for that checkpoint. `pnpm dev` is intentionally separate because it keeps the local server running.
+Browser verification must use the real Toolcraft shell plus renderer output. `pnpm verify:final` runs the full static, build, and browser functional gate. The default `pnpm test:browser` / `pnpm verify:ui` gate excludes every Playwright test whose name contains `browser perf:`, including performance audit and budget scenarios. The browser performance checkpoint is intentionally separate and only runs for the two full-performance triggers; `pnpm verify:perf` is the Playwright fallback command for that checkpoint. `pnpm dev` is intentionally separate because it keeps the local server running.
 
 Do not stop existing local servers to free `3002` during a first start. `pnpm dev`, `pnpm preview`, and browser verification prefer `3002`, then automatically use the next free port only while assigning the app's first saved port. After that, normal dev/preview starts use the saved port; if that port already serves the same app, report the existing URL instead of creating a second server. A launch is valid only after the selected port serves the current app root through the Toolcraft server identity endpoint and the app title marker from `index.html`; a random listener on that port is not enough. When restarting an app server you already started, use `pnpm dev:restart` or `pnpm preview:restart`; restart mode reuses the previously saved app port, stops the listener on that exact port if needed, force-stops it if the port is still occupied, starts on the same port again, and verifies the same app identity before saving/reporting the port.

package/templates/starter/docs/toolcraft/component-rules.md

@@ -208,13 +208,22 @@ Use variants by product meaning:
 - `chromaOffset`: RGB or chromatic offset;
 - `toneBias`: split-tone, duotone, or color-grading bias.
 
+Use Vector only when the user is meant to manually author a stable two-axis product parameter. Do not expose a pad for current animation state, keyboard movement, pointer movement, physics state, timeline phase, velocity, target pose, current pose, or simulated position/direction just because the internal value has `x` and `y`.
+
+Before adding a Vector control to an animated or interactive product, classify movement ownership:
+
+- `direct-authored`: a stable parameter the user manually edits, such as light direction, focus, anchor, or object offset. This can be Vector.
+- `timeline-driven`: movement comes from playback/keyframes. Use timeline, speed, duration, path, step, or amplitude controls instead.
+- `keyboard/pointer-driven`: movement comes from user input on the canvas/app. Keep position/direction in interaction state and expose only useful tuning controls.
+- `simulation-owned`: movement comes from physics/procedural state. Keep current pose/velocity internal and expose high-level tuning controls.
+
 Default/spatial vector pads use screen-coordinate movement. Dragging the pad left/up lowers `vector.x` and `vector.y`, so an object on the canvas moves left/up without renderer-side Y inversion. Use `coordinateMode: "cartesian"` only when the product intentionally exposes mathematical Y-up coordinates.
 
 Vector pad value labels are compact UI labels, not raw state dumps. They show rounded normalized coordinates and must never expose floating-point tails such as `-0.07070312499999998`.
 
 Double-clicking the vector pad resets both axes to the control default through the normal runtime value update, matching the reset button in the section header. If no default is defined, the fallback is `0,0`. Do not add a separate custom reset button for basic pad reset behavior.
 
-Holding Shift while dragging a vector pad locks movement to the dominant axis and must not select text or page content. Use the built-in `vector` control for constrained two-axis movement instead of creating a custom pad.
+Holding Shift while dragging a vector pad locks movement to the dominant axis and must not select text or page content. Use the built-in `vector` control for constrained two-axis direct-authored parameters instead of creating a custom pad.
 
 Do not add custom vector sizing props. Choose the right number, variant, and section grouping, then let runtime sizing handle the pad.