@pixel-point/toolcraft 0.0.11 → 0.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixel-point/toolcraft",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "license": "SEE LICENSE IN LICENSE.md",
   "type": "module",
   "bin": {
@@ -24,6 +24,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.6.0",
+    "cross-spawn": "^7.0.6",
     "skills": "^1.5.12"
   }
 }

package/src/cli.mjs

@@ -1,10 +1,10 @@
-import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
 import fs from "node:fs/promises";
 import path from "node:path";
 import readline from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 
+import spawn from "cross-spawn";
 import {
   cancel,
   confirm,
@@ -364,7 +364,7 @@ function runCommand(command, args, options = {}, context = {}) {
     const child = spawn(command, args, {
       cwd: options.cwd,
       env: options.env,
-      shell: process.platform === "win32",
+      shell: options.shell ?? false,
       stdio: options.stdio ?? "inherit",
     });
 
@@ -439,6 +439,7 @@ async function installToolcraftSkills(parsedOptions, targetDir, context = {}) {
         ...process.env,
         ...(context.env ?? {}),
       },
+      shell: false,
       stdio: "inherit",
     },
     context,
@@ -493,6 +494,7 @@ export async function runCreateCommand(parsedOptions, context = {}) {
           ...process.env,
           ...(context.env ?? {}),
         },
+        shell: false,
         stdio: "inherit",
       },
       context,

package/src/cli.test.mjs

@@ -259,7 +259,7 @@ describe("runToolcraftCli", () => {
       throwOnError: true,
       toolcraftSkillsSourceDir: skillsSourceDir,
       async runCommand(command, args, options) {
-        installs.push({ args, command, cwd: options.cwd });
+        installs.push({ args, command, cwd: options.cwd, shell: options.shell });
       },
     });
 
@@ -268,11 +268,13 @@ describe("runToolcraftCli", () => {
         args: ["install"],
         command: "pnpm",
         cwd: path.join(tempRoot, "install-app"),
+        shell: false,
       },
       {
         args: [skillsCliPath, "add", skillsSourceDir, "--skill", "*", "--yes"],
         command: process.execPath,
         cwd: path.join(tempRoot, "install-app"),
+        shell: false,
       },
     ]);
     assert.match(stdout.text, /Installing dependencies with pnpm/);
@@ -308,7 +310,7 @@ describe("runToolcraftCli", () => {
         throwOnError: true,
         toolcraftSkillsSourceDir: skillsSourceDir,
         async runCommand(command, args, options) {
-          skillsCommands.push({ args, command, cwd: options.cwd });
+          skillsCommands.push({ args, command, cwd: options.cwd, shell: options.shell });
         },
       },
     );
@@ -331,6 +333,7 @@ describe("runToolcraftCli", () => {
         ],
         command: process.execPath,
         cwd: path.join(tempRoot, "skills-options-app"),
+        shell: false,
       },
     ]);
   });

package/src/generate.test.mjs

@@ -93,10 +93,13 @@ 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");

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.",
     );

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.",

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.
 

package/templates/starter/docs/toolcraft/performance.md

@@ -167,7 +167,7 @@ Animation checks should sample enough frames to catch jank. Interaction budgets
 
 Use `app-performance.ts` as the single budget and fixture source. Browser performance tests must call `getToolcraftPerformanceStressValue(appPerformance, scenarioId)` for workload values and `expectToolcraftScenarioPerformanceBudget(..., appPerformance, scenarioId)` for budgets.
 
-Run targeted performance scenarios for Tier 3 performance-sensitive edits when they directly exercise the touched workload, viewport, or export path. The full performance checkpoint prefers the current AI agent's controlled browser. `pnpm verify:perf` is the Playwright fallback suite; it runs `e2e/app-performance.spec.ts` and every `browser perf:` scenario with one worker so budget failures are not hidden or created by unrelated parallel browser tests.
+Run targeted performance scenarios for Tier 3 performance-sensitive edits when they directly exercise the touched workload, viewport, or export path. The default `pnpm test:browser` / `pnpm verify:ui` gate excludes every Playwright test whose name contains `browser perf:`, including the performance audit and budget scenarios. The full performance checkpoint prefers the current AI agent's controlled browser. `pnpm verify:perf` is the Playwright fallback suite; it runs every `browser perf:` scenario with one worker so budget failures are not hidden or created by unrelated parallel browser tests.
 
 Run a full performance checkpoint only when:
 

package/templates/starter/docs/toolcraft/schema-reference.md

@@ -201,7 +201,7 @@ For `slider` and `rangeSlider`, `unit` is a real measurement suffix, not the ent
 
 `slider` and `rangeSlider` are live controls. Dragging must update runtime state and product output while the drag is in progress, not only on pointer release, blur, Apply, or a final commit. Treat a non-live slider as a broken product mapping unless an extreme measured performance ceiling is documented; even then, keep immediate lightweight canvas feedback and refine the heavy output after coalescing/caching.
 
-For `vector`, the default/spatial variant uses `coordinateMode: "screen"` by default: dragging left/up lowers `x` and `y`, so canvas objects move left/up without renderer-side Y inversion. Use `coordinateMode: "cartesian"` only for intentional mathematical Y-up coordinates. Color variants keep their color-axis semantics by default. Vector pad value labels show compact rounded coordinates; raw floating-point tails must never appear in the controls panel. Double-clicking the pad resets both axes to the control default through the normal runtime value update, matching the section header reset; if no default is defined, the fallback is `0,0`. Holding Shift while dragging locks movement to the dominant axis and must not select text or page content.
+For `vector`, the default/spatial variant uses `coordinateMode: "screen"` by default: dragging left/up lowers `x` and `y`, so canvas objects move left/up without renderer-side Y inversion. Use it only for stable user-authored two-axis 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 just because the internal value has `x` and `y`. Use `coordinateMode: "cartesian"` only for intentional mathematical Y-up coordinates. Color variants keep their color-axis semantics by default. Vector pad value labels show compact rounded coordinates; raw floating-point tails must never appear in the controls panel. Double-clicking the pad resets both axes to the control default through the normal runtime value update, matching the section header reset; if no default is defined, the fallback is `0,0`. Holding Shift while dragging locks movement to the dominant axis and must not select text or page content.
 
 Use `collectionActions` when the product owns a growable/shrinkable item list. `minItems` protects the smallest valid output, `recommendedMaxItems` is only a design recommendation, and `hardMaxItems` is valid only for a real product or technical limit. Adding/removing items must update the runtime array and the renderer/export must consume that same array. Do not pair a count slider with hidden fixed item controls when the user needs to add or remove actual entities. The collection label is on the left and remove/add buttons stay on the right. Homogeneous repeated items do not show visible per-item labels when the collection label already names the group. `itemControl.type` supports normal item built-ins such as `color`, `colorOpacity`, `text`, `select`, `segmented`, `slider`, `switch`, `checkbox`, `rangeInput`, and `fontPicker`; item controls still follow normal density rules, so plain colors use equal 50% columns when they fit. Use `fontPicker` as the item control when each repeated item is a text style or typography entity; do not split its font, weight, size, case, color/opacity, letter spacing, or line height into sibling collection fields.
 

package/templates/starter/e2e/app-performance.spec.ts

@@ -184,7 +184,7 @@ function getFirstMatchIndex(source: string, pattern: RegExp): number {
   return match?.index ?? -1;
 }
 
-test("browser performance matrix points at real fallback browser tests", () => {
+test("browser perf: performance matrix points at real fallback browser tests", () => {
   const browserTestSources = readSiblingBrowserTestSources();
 
   for (const scenario of starterPerformance.scenarios) {
@@ -199,7 +199,7 @@ test("browser performance matrix points at real fallback browser tests", () => {
   }
 });
 
-test("browser performance tests use real Toolcraft interactions", () => {
+test("browser perf: performance tests use real Toolcraft interactions", () => {
   if (starterPerformance.scenarios.length === 0) {
     return;
   }
@@ -493,7 +493,7 @@ test("browser performance tests use real Toolcraft interactions", () => {
   }
 });
 
-test("declared renderer layer selectors are present", async ({ page }) => {
+test("browser perf: declared renderer layer selectors are present", async ({ page }) => {
   if (!starterPerformance.usesCustomRenderer) {
     return;
   }

package/templates/starter/package.json

@@ -12,8 +12,8 @@
     "preview:restart": "node scripts/run-vite-on-free-port.mjs preview --toolcraft-restart",
     "docs:check": "node scripts/check-toolcraft-docs.mjs",
     "test": "node scripts/check-toolcraft-docs.mjs && node scripts/check-toolcraft-integrity.mjs && node --test scripts/*.test.mjs && vitest run src --passWithNoTests",
-    "test:browser": "playwright install chromium && playwright test",
-    "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",
+    "test:browser": "playwright install chromium && playwright test --grep-invert \"browser perf:\"",
+    "test:browser:perf": "playwright install chromium && playwright test --grep \"browser perf:\" --workers=1 --pass-with-no-tests",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "verify:quick": "pnpm ai:check && pnpm test",
     "verify:ui": "pnpm test:browser",

package/templates/starter/src/app/starter-performance.test.ts

@@ -317,16 +317,20 @@ function sourceUsesDirectStorageApi(): boolean {
 }
 
 describe("Toolcraft template app performance coverage", () => {
-  it("publishes a sequential Playwright browser performance fallback", () => {
+  it("publishes separate browser acceptance and performance fallback gates", () => {
     const packageJson = JSON.parse(readFileSync(join(projectDir, "package.json"), "utf8")) as {
       scripts?: Record<string, string>;
     };
 
+    expect(
+      packageJson.scripts?.["test:browser"],
+      "Generated apps must keep full performance scenarios out of the default browser acceptance gate.",
+    ).toBe('playwright install chromium && playwright test --grep-invert "browser perf:"');
     expect(
       packageJson.scripts?.["test:browser:perf"],
       "Generated apps must expose a sequential Playwright fallback so perf budgets can be measured when no agent browser is available.",
     ).toBe(
-      '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',
     );
     expect(packageJson.scripts?.["verify:quick"]).toBe("pnpm ai:check && pnpm test");
     expect(packageJson.scripts?.["verify:ui"]).toBe("pnpm test:browser");
@@ -339,6 +343,20 @@ describe("Toolcraft template app performance coverage", () => {
     );
   });
 
+  it("keeps the Playwright performance audit inside the browser perf tag", () => {
+    const source = readFileSync(join(e2eDir, "app-performance.spec.ts"), "utf8");
+    const testNames = [...source.matchAll(/test\(\s*(["'`])([^"'`]+)\1/g)].map(
+      (match) => match[2],
+    );
+
+    expect(source).not.toContain("TOOLCRAFT_PERF_CHECK");
+    expect(testNames.length).toBeGreaterThan(0);
+    expect(
+      testNames.every((name) => name.includes("browser perf:")),
+      `app-performance.spec.ts tests must all be tagged for the dedicated perf checkpoint: ${testNames.join(", ")}`,
+    ).toBe(true);
+  });
+
   it("declares agent browser as the preferred performance runner", () => {
     expect(starterPerformance.browserCheckPolicy).toEqual({
       fallbackRunner: "playwright",

package/templates/ui/components/controls/range-slider/range-slider-value.ts

@@ -1,6 +1,10 @@
 import { applySliderValueLabelUnit } from "../slider/slider-value";
 
-const rangeSeparatorPattern = /(\d)\s*[-‐‑‒–—−]\s*(?=\d)/g;
+const signedNumberPattern = "[-−]?\\d+(?:[.,]\\d+)?";
+const rangePairPattern = new RegExp(
+  `(${signedNumberPattern})(?:\\s*[\\p{L}%°]+)?\\s*(?:/|[-‐‑‒–—−])\\s*(${signedNumberPattern})`,
+  "u",
+);
 
 export function formatRangeSliderValue(
   value: readonly number[],
@@ -46,11 +50,15 @@ export function parseRangeSliderDraft(
     step: number;
   },
 ): [number, number] | null {
-  const normalizedDraftValue = draftValue.replace(rangeSeparatorPattern, "$1 ");
-  const values = Array.from(
-    normalizedDraftValue.matchAll(/-?\d+(?:[.,]\d+)?/g),
-    ([match]) => Number(match.replace(",", ".")),
-  ).filter(Number.isFinite);
+  const pairMatch = draftValue.match(rangePairPattern);
+  const values = pairMatch
+    ? [pairMatch[1], pairMatch[2]]
+        .map((match) => parseRangeSliderDraftNumber(match))
+        .filter(Number.isFinite)
+    : Array.from(
+        draftValue.matchAll(/[-−]?\d+(?:[.,]\d+)?/g),
+        ([match]) => parseRangeSliderDraftNumber(match),
+      ).filter(Number.isFinite);
 
   if (values.length === 0) {
     return null;
@@ -64,3 +72,7 @@ export function parseRangeSliderDraft(
 
   return sortedValues;
 }
+
+function parseRangeSliderDraftNumber(value: string | undefined): number {
+  return Number(value?.replace("−", "-").replace(",", "."));
+}