@pixel-point/toolcraft 0.0.14 → 0.0.15

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

@@ -16,18 +16,21 @@ After the first working version, feature loops do not run the full performance s
 - Tier 0-1: targeted docs/typecheck/unit plus focused browser when visual.
 - Tier 2: `pnpm verify:quick` plus relevant browser acceptance.
 - Tier 3: `pnpm verify:quick`, targeted browser acceptance, and targeted performance scenarios for touched workload/viewport/export paths.
-- Tier 4: `pnpm verify:final`; for the first working product version also run and pass a browser performance checkpoint with the current AI agent's controlled browser when available, using `pnpm verify:perf` only as fallback.
+- Tier 4: for the first working product version, run and receipt the browser performance checkpoint first, then run `pnpm verify:final` against the current receipt.
 
 Record skipped full performance runs and reason in the verification note or worklog.
 
 ## Workload Fixtures
 
 - Performance scenarios declare `stressFixture` for the tested control value.
-- Browser perf tests use `getToolcraftPerformanceStressValue(appPerformance, scenarioId)` so heavy-case tests cannot use toy values.
+- `export-copy` scenarios declare the exact `panelActions` `actionValue`, visible `controlLabel`, and `completionEvidence` (`download` or `clipboard`). Their browser test uses the matching protected output-action helper with `scenarioId`; the helper owns the click and real download/clipboard completion. The signed reporter rejects missing completion evidence, skipped/failed tests, and evidence from failed retries.
+- Browser perf tests apply scalar values with `applyToolcraftPerformanceStressValue` / `applyToolcraftPerformanceWorkloadValue` and object fixtures with `applyToolcraftPerformanceStressFixture` / `applyToolcraftPerformanceWorkloadFixture`. Every fixture mapping supplies `applyValue` plus `observeValue`; evidence attaches only after the observed UI/runtime value exactly matches the declared fixture.
+- Mutating measurements pass a structured-cloneable `observeOutcome`. Generic change evidence first proves that its baseline stays stable before the action, timestamps the first live changed response, then requires the final post-action outcome to remain changed through the stability window. Autonomous or animated output uses `expectedOutcome` with a stable semantic observation, or the test fixes playback to a deterministic phase; an incidental next frame cannot satisfy the interaction. The immutable result stays bound to the same `scenarioId` as its budget. `durationMs` uses a runner monotonic clock from interaction start to the first changed or expected response; required frame sampling survives document navigation, and settle/stability checks still finish before evidence is emitted without replacing product-response latency with action completion or inflating it with the post-change window. Non-mutating measurements end at action completion.
 - When the tested control is not itself the whole heavy source, declare `workloadFixture` and apply it first.
-- Numeric maximums, density, item counts, canvas/media size, and combined heavy states declare `loadProfile` with `hardLimit`, `smoothTarget`, and `smoothTargetRatio`.
+- Numeric control ranges and hard limits come from schema; scenarios may omit duplicated `values`, and any supplied values must match schema exactly. A bounded numeric control cannot switch to `metric: "custom"` to avoid its min/max.
+- Numeric maximums, density, item counts, canvas/media size, and combined heavy states declare `loadProfile` with `hardLimit`, `smoothTarget`, and `smoothTargetRatio`. `many-items` applies at least 10 real items; lowering an authored `minCount` is not evidence.
 - Try the hard limit first.
-- Lower the guaranteed smooth target only in 10 percent steps with failed-measurement and optimization evidence.
+- Lower the guaranteed smooth target only in 10 percent steps with failed-measurement and optimization evidence. Every entry names the exact `attemptedRatio`, schema-reachable `attemptedTarget`, scenario id, and target for that step.
 - Ranges above `smoothTarget` are experimental, not silently guaranteed.
 
 ## Media And Pixel Workloads

package/templates/starter/docs/toolcraft/core/runtime-boundary.md

@@ -8,12 +8,12 @@ Read this module before changing app assembly, routes, runtime surfaces, custom
 - Render through `ToolcraftApp`.
 - Read `appSchema.assembly` before adding custom JSX. It lists the enabled runtime surfaces, capabilities, commands, and assumptions for the current app.
 - Keep app state in the Toolcraft runtime schema and runtime commands.
-- Keep route files thin: routes compose the schema-backed Toolcraft app and product renderers.
+- Keep product assembly in typed `src/app/app-composition.tsx`; the signed route only hosts `ToolcraftApp`.
 - Do not replace Toolcraft with copied reference UI, route-local panels, standalone forms, or hand-built editor chrome.
 
 ## Allowed Extension Points
 
-Use only these app-specific extension points unless you are intentionally changing the shared Toolcraft runtime:
+Use only these app-specific extension points. Shared runtime changes happen upstream and reach generated apps through regeneration:
 
 - schema controls;
 - schema `canvas`, `panels`, `toolbar`, `panelActions`, `persistence`, `media`, `assembly`, and transfer-mode metadata;
@@ -48,6 +48,13 @@ Use only these app-specific extension points unless you are intentionally changi
 
 ## Generated App Source Boundary
 
-- Generated applications keep their public editing surface in `src/app/app-schema.ts` and app-specific files under `src/app` and `src/routes`.
-- Do not edit `src/toolcraft` in one generated app unless the task is intentionally changing the local copied runtime. Prefer fixing the monorepo runtime and regenerating or syncing.
+- Generated applications keep their public entry surface in `src/app/app-composition.tsx` and `src/app/app-schema.ts`. Supporting product modules may live anywhere under `src`; every product production module is discovered by the same source inventory and checked by the same AST boundary.
+- The signed framework bootstrap includes `index.html`, `src/main.tsx`, `src/router.tsx`, `src/routes/index.tsx`, `src/routes/root.tsx`, and `src/styles.css`. Do not edit or replace those host files in a generated app.
+- Product styling is local by construction: use locally imported `*.module.css` files only. Every selector starts with a compound containing a local class. A first-compound `:is()` or `:where()` remains local only when every branch is locally anchored; `:not()` and `:has()` do not create a local anchor. Descendants may style product-owned children, but `:global`, bare/root selectors, host-attribute selectors, sibling escapes, CSS `@import`, package CSS imports, and product-created global `<style>`/`CSSStyleSheet` injection are rejected because they cross the product/runtime boundary.
+- Product `import()` and `require()` specifiers must be statically resolvable from literals, same-file constants, templates, or string concatenation. Production and test source share this rule, so computed module loading cannot hide a runtime/control import or a protected evidence channel.
+- Product production modules must not import product tests, test-support modules, or protected browser-evidence internals, directly or through a product bridge. Runtime evidence is emitted only by the protected public acceptance/performance helpers after their assertions pass; product-owned source must not import, re-export, assemble, or forge the reserved evidence module names and payload identifiers.
+- Product production modules must form an acyclic dependency graph. The code-health gate resolves relative imports, directory `index.*` modules, configured TypeScript path aliases, and local package exports. Type-only imports, external packages, tests, and copied Toolcraft framework internals do not create product dependency edges. When a cycle exists, the gate prints the complete shortest cycle so the ownership boundary can be corrected directly.
+- Imported product source remains under `src`. Code health and product-boundary analysis consume the same canonical source-inventory semantics instead of maintaining independent recursive walkers. The signed Vitest reporter uses the canonical framework-ownership policy to distinguish product-owned runner results, while acceptance and performance requirements derive from typed app configuration.
+- Do not edit `src/toolcraft` in a generated app. It is an immutable signed copy of the shared runtime. Fix the monorepo runtime and regenerate the app.
+- Generated integrity protects the copied runtime, signed host/bootstrap, framework validators/tests, `AGENTS.md`, local contract docs under `docs/toolcraft`, `LICENSE.md`, `NOTICE.md`, TypeScript/Vite/Vitest/Playwright root configuration, and the commands of the original package scripts. Alternate root config files in those verification families are rejected instead of silently creating a second test path. `docs/toolcraft/agent-worklog.md` is the explicit editable documentation exception; every other file added under `docs/toolcraft` is rejected as unrecorded contract input. Product dependencies, unrelated product scripts, product source, and the worklog remain editable, but all product production modules are AST-checked for host-surface and built-in-control bypasses. Added `pre*` or `post*` lifecycle hooks for a protected script are rejected because they can execute across a verification boundary. Run the checker directly before the final gate; `pnpm test` must fail when any protected file changes, or when the copied runtime tree or its signed integrity manifest is missing, changed, or contains unrecorded source.
 - Generated apps must not contain monorepo app/package folders, workspace-protocol dependencies, or workspace package imports.

package/templates/starter/docs/toolcraft/core/timeline-animation.md

@@ -37,6 +37,7 @@ Use no timeline only when the motion is explicitly autonomous decoration with no
 - Use `getToolcraftTimelineLoopTime` or `getToolcraftTimelineLoopProgress` in playback renderers instead of local wall-clock or fixed-duration phase math.
 - When the loop period is known or product-derived, set `panels.timeline.defaultDurationSeconds` to that period and record the evidence in animation or reference timeline metadata.
 - Runtime/template fallback `8s` is not evidence for loop duration.
+- Playback acceptance with loop coverage declares typed `timelineLoopProof`: forward-only direction, reverse playback forbidden, first/last frame seam match, and reproof after a duration edit. This declaration never replaces browser sampling of the real renderer.
 
 ## Duration Changes
 

package/templates/starter/docs/toolcraft/custom-controls.md

@@ -33,6 +33,13 @@ Custom control schemas still need:
 
 ```ts
 builtInFitCheck: {
+  capabilities: [
+    "collection",
+    "reorder",
+    "selection",
+    "commands",
+    "custom-value-model",
+  ],
   checkedBuiltIns: ["fileDrop", "collectionActions", "imagePicker"],
   closestBuiltIn: "fileDrop",
   whyInsufficient:
@@ -42,7 +49,7 @@ builtInFitCheck: {
 }
 ```
 
-`checkedBuiltIns` must name real Toolcraft built-in controls. `closestBuiltIn` must be one of those checked controls or `"none"` when no built-in is meaningfully close. `whyInsufficient` explains the missing interaction. `productObservable` names the output or side effect that proves the custom control is necessary.
+`capabilities` is required and uses broad behavior facts: `collection`, `reorder`, `selection`, `commands`, `custom-interaction`, `custom-value-model`, or `custom-visualization`. At least one of the three `custom-*` capabilities must explain why built-ins cannot own the interaction. `checkedBuiltIns` must name real Toolcraft built-in controls. `closestBuiltIn` must be one of those checked controls or `"none"` when no built-in is meaningfully close. `whyInsufficient` explains the missing interaction. `productObservable` names the output or side effect that proves the custom control is necessary.
 
 If the custom control owns a growable, removable, selectable, or reorderable runtime item set, `checkedBuiltIns` must include both `collectionActions` and `actions`. Decide this from the value model and workflow, such as arrays, `{ items: [...] }` objects, selected-item state, or add/remove/reorder behavior, not from entity names like masks or glyphs. This applies even when the empty state visually looks like a few icon buttons: the fit check must prove why `collectionActions` cannot own the runtime list and why `actions` alone cannot represent the collection state.
 

package/templates/starter/docs/toolcraft/decision-contract.md

@@ -16,7 +16,7 @@ Use this before writing a schema, spec, or implementation plan. It separates har
 
 | Area | Decision Type | Summary |
 | --- | --- | --- |
-| Runtime shell | Invariant | Use `defineToolcraft` and `ToolcraftApp` |
+| Runtime shell | Invariant | Use `defineToolcraft` and `ToolcraftAppComposition`; the signed host renders `ToolcraftApp` |
 | Canvas | Mixed | No app UI in `canvasContent`; handles are product-dependent |
 | Panels | Mixed | Panel mechanics are hard; panel presence is product-dependent |
 | Layers | Heuristic, then invariant | Enable only for real layer behavior; fully test when enabled |
@@ -28,35 +28,39 @@ Use this before writing a schema, spec, or implementation plan. It separates har
 | Acceptance | Invariant | Prove product observables, not only runtime mutation |
 | Performance | Mixed | Workload controls need workload budgets; ordinary controls need responsiveness coverage; animated previews yield to viewport interactions |
 | Persistence | Default, then invariant | State persistence must be explicit; localStorage apps must prove reload restoration |
-| Workflow | Invariant | Use required skills and browser verification |
+| Workflow | Invariant | Follow signed local workflow, use available skills, and run browser verification |
 
-The runtime shell invariant means product routes render `ToolcraftApp` directly. Do not hand-compose `ToolcraftRoot`, `CanvasShell`, `ControlsPanel`, `TimelinePanel`, `LayersPanel`, or `ToolbarPanel`; those surfaces are shared runtime design, not app-specific implementation details. App-specific source also must not render built-in control components directly; schema controls and `controlRenderers` are the allowed control extension points.
+The runtime shell invariant means product code exports the typed composition and does not edit the signed route. The host renders `ToolcraftApp`; product modules must not hand-compose `ToolcraftRoot`, `CanvasShell`, `ControlsPanel`, `TimelinePanel`, `LayersPanel`, or `ToolbarPanel`. App-specific source also must not render built-in control components directly; schema controls and `controlRenderers` are the allowed control extension points.
 
 ## Rule Catalog
 
 This catalog mirrors `TOOLCRAFT_DECISION_CONTRACT`. If runtime adds or renames a rule id, this page and `AGENTS.md` must list the same id.
 
+[//]: # (toolcraft-contract:decision-rule-table:start)
 | Rule ID | Level | Area |
 | --- | --- | --- |
-| `runtime-shell-required` | Invariant | Runtime shell |
-| `canvas-no-app-ui` | Invariant | Canvas |
-| `canvas-surface-preserved` | Invariant | Canvas |
-| `canvas-handle-placement` | Heuristic | Canvas |
-| `panel-host-behavior` | Invariant | Panels |
-| `layers-enable-only-when-needed` | Heuristic | Layers |
-| `layers-enabled-behavior` | Invariant | Layers |
-| `timeline-mode-choice` | Heuristic | Timeline |
-| `timeline-enabled-behavior` | Invariant | Timeline |
-| `controls-product-coverage` | Invariant | Controls |
-| `output-export-required` | Invariant | Controls |
-| `controls-layout-heuristics` | Heuristic | Controls |
-| `renderer-technique-inventory` | Default | Renderer |
-| `video-reference-analysis` | Invariant | Reference analysis |
-| `reference-clone-source-of-truth` | Invariant | Reference clone |
-| `acceptance-product-observable` | Invariant | Acceptance |
-| `performance-coverage-levels` | Invariant | Performance |
-| `persistence-policy-explicit` | Default | Persistence |
-| `workflow-required` | Invariant | Workflow |
+| `runtime-shell-required` | invariant | runtime-shell |
+| `canvas-no-app-ui` | invariant | canvas |
+| `canvas-surface-preserved` | invariant | canvas |
+| `canvas-handle-placement` | heuristic | canvas |
+| `panel-host-behavior` | invariant | panels |
+| `layers-enable-only-when-needed` | heuristic | layers |
+| `layers-enabled-behavior` | invariant | layers |
+| `timeline-mode-choice` | heuristic | timeline |
+| `timeline-enabled-behavior` | invariant | timeline |
+| `controls-product-coverage` | invariant | controls |
+| `output-export-required` | invariant | controls |
+| `controls-section-inventory-required` | invariant | controls |
+| `controls-component-layout-invariants` | invariant | controls |
+| `controls-layout-heuristics` | heuristic | controls |
+| `renderer-technique-inventory` | default | renderer |
+| `reference-clone-source-of-truth` | invariant | reference-clone |
+| `video-reference-analysis` | invariant | reference-analysis |
+| `acceptance-product-observable` | invariant | acceptance |
+| `performance-coverage-levels` | invariant | performance |
+| `persistence-policy-explicit` | default | persistence |
+| `workflow-required` | invariant | workflow |
+[//]: # (toolcraft-contract:decision-rule-table:end)
 
 ## Enforcement
 

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

@@ -9,7 +9,9 @@ Performance coverage has two levels:
 - workload coverage for controls that change render cost;
 - responsiveness coverage for ordinary controls that still must not freeze input or break the viewport.
 
-The preferred browser performance runner is the current AI agent's controlled browser. Use `pnpm verify:perf` only as the Playwright fallback when no agent-controlled browser is available or in CI/non-agent automation.
+`maxInteractionMs` measures user action start through the first verified product-output/state response for mutating interactions, not merely pointer completion. Generic change measurements first prove a stable pre-action baseline. A live drag may then cross that baseline while the gesture continues: the first changed response sets latency, then the final post-action outcome must remain different through its stability window before evidence is emitted. Autonomous or animated products use a stable semantic `expectedOutcome` or a deterministic fixed playback phase; the next unrelated frame cannot count as response. Settle/stability time after the first response is not charged as first-response latency. The helper uses one runner monotonic clock and restarts frame sampling after document navigation. Non-mutating interactions use action completion.
+
+The preferred runner for targeted browser diagnosis is the current AI agent's controlled browser. The protected `pnpm verify:perf` Playwright checkpoint is the sole final machine authority that can record a passed current-source performance receipt.
 
 `app-performance.ts` must keep this policy:
 
@@ -21,7 +23,7 @@ browserCheckPolicy: {
 }
 ```
 
-Do not change the preferred runner to Playwright to make local automation easier; that reverses the contract. Playwright is portable fallback evidence, not the primary agent workflow.
+Do not change the preferred runner to Playwright merely to avoid agent-controlled diagnosis; that policy governs targeted investigation. It does not authorize a manual passed receipt: final performance proof comes only from the protected `pnpm verify:perf` checkpoint.
 
 ## Workload Coverage
 
@@ -51,9 +53,9 @@ Both fixture types must include:
 - `reason`: why this value is the heaviest useful product case;
 - `value`: the actual value the browser performance check will apply.
 
-Fixtures that represent numeric maximums, density, item counts, canvas/media size, or custom combined heavy states also declare `loadProfile`. This separates the product `hardLimit` from the `smoothTarget` that the browser performance checkpoint guarantees. `hardLimit` is the largest product range or tier the app exposes; `smoothTarget` is the value the browser performance check applies and must match `stressFixture.value` or `workloadFixture.value`.
+Fixtures that represent numeric maximums, density, item counts, canvas/media size, or custom combined heavy states also declare `loadProfile`. This separates the product `hardLimit` from the `smoothTarget` that the browser performance checkpoint guarantees. For bounded numeric controls, min/default/max and the hard limit are derived from schema; omit duplicated scenario `values`, or use `requireToolcraftSchemaPerformanceValues` when another fixture needs the same range. Supplied values must match schema exactly, and `metric: "custom"` cannot replace a numeric boundary. `smoothTarget` is the value the browser performance check applies and must match `stressFixture.value` or `workloadFixture.value`. A `many-items` fixture must apply at least 10 real items; an authored `minCount` cannot redefine a token fixture as heavy.
 
-Default to `smoothTargetRatio: 1`, which means the full hard limit must pass budgets. If the hard limit cannot pass after reasonable renderer and pipeline optimizations, lower the smooth target only in 10 percent steps (`0.9`, then `0.8`, and so on). Every lower step must include `loadProfile.evidence` with the failed higher target, measured result, optimization attempted, and decision. When `smoothTargetRatio < 1`, set `userFacingRange: "experimental-above-smooth"` so the range above the smooth target is not silently presented as guaranteed.
+Default to `smoothTargetRatio: 1`, which means the full hard limit must pass budgets. If the hard limit cannot pass after reasonable renderer and pipeline optimizations, lower the smooth target only in 10 percent steps (`0.9`, then `0.8`, and so on). Every skipped higher step has exactly one `loadProfile.evidence` entry with the exact `attemptedRatio`, schema-reachable `attemptedTarget`, matching scenario id and target, measured result, optimization attempted, and decision. When `smoothTargetRatio < 1`, set `userFacingRange: "experimental-above-smooth"` so the range above the smooth target is not silently presented as guaranteed.
 
 For multiline text, prompt, code, JSON, CSS, shader, script, or template workload controls, use `kind: "large-text"`. The fixture must contain at least `50_000` characters and `1_000` lines unless the product has a stricter real-world maximum.
 
@@ -61,17 +63,24 @@ For uploaded images, videos, source media, and image-processing workloads, use `
 
 Choose heavy fixtures from this app's real controls, not from generic examples. Derive the workload from four app-specific sources: schema controls and `performanceRole`, `rendererTechnique`, `rendererPipeline`, and real product stress values such as large text, source media dimensions, `canvas.renderScale`, canvas size, export resolution, animation speed, viewport interactions, and effect strength. Try the product hard limit first, then use a documented smooth target only when measured evidence shows the hard limit cannot be made smooth without changing product scope.
 
-Browser performance tests for workload and stress scenarios must read the scenario value through:
+Every `automatedTestName` and `browserTestName` must match exactly one product-owned test selected by the real Vitest or Playwright runner, and that test must finish passed. Comments, strings, local fake runners, focused/skipped tests, runtime skip/fixme/fail annotations, conditional declarations, and uncalled registration functions are not performance evidence.
+
+Browser slider stress tests apply the declared value through the protected helper:
 
 ```ts
-getToolcraftPerformanceStressValue(appPerformance, "scenario-id")
+await dragToolcraftSliderToPerformanceStressValue(
+  page,
+  "Control label",
+  appPerformance,
+  "scenario-id",
+)
 ```
 
-For workload sliders, the fallback Playwright test uses `dragToolcraftSliderToPerformanceStressValue(page, label, appPerformance, "scenario-id")` so the test applies the exact numeric value through the real slider min/max range. Agent-browser checks must apply the same value from `app-performance.ts`. Do not divide a stress value by the slider max, type a separate short value, or hardcode a runner-local ratio. If a browser check uses a toy value while `app-performance.ts` claims a heavy fixture, the performance checkpoint must fail.
+For non-slider scalar values, use `applyToolcraftPerformanceStressValue` with `{ applyValue, observeValue }`. The helper reads the exact scenario value and emits stress evidence only after `observeValue` equals that declared value. Agent-browser checks must apply the same value from `app-performance.ts`. Do not divide a stress value by the slider max, type a separate short value, hardcode a runner-local ratio, or claim application without observing the resulting UI/runtime state.
 
 Slider and range slider performance scenarios must preserve live product feedback. The browser test should drag the real thumb and verify the canvas/product output changes during drag. If that drag misses budget, keep the live control semantics and optimize the renderer path first: cache expensive inputs, update uniforms or stable buffers, coalesce preview work to `requestAnimationFrame`, cancel stale async renders, move work off React renders, reuse GPU resources, or change renderer strategy. Do not pass performance by making the slider update only after pointer release or Apply.
 
-When a scenario declares `workloadFixture`, apply it first with `getToolcraftPerformanceWorkloadValue` or `applyToolcraftPerformanceWorkloadFixture`, then apply `stressFixture`, then measure. A control-drag scenario that only sets its own slider value while leaving the source media, text, item count, render scale, or dense scene at defaults is invalid.
+When a scenario declares `workloadFixture`, apply it first with `applyToolcraftPerformanceWorkloadValue` or `applyToolcraftPerformanceWorkloadFixture`, then apply `stressFixture`, then measure. A control-drag scenario that only sets its own slider value while leaving the source media, text, item count, render scale, or dense scene at defaults is invalid.
 
 For combined worst cases, put every relevant independent baseline value in `workloadFixture.value` for control scenarios, such as `{ sourceMedia: { width: 3840, height: 2160 }, renderScale: 2 }`, and put the tested control value in `stressFixture.value`. For preview, zoom, drag, animation, or export scenarios that stress the entire state instead of one control, use `stressFixture.value`, such as `{ detail: 96, scale: 0.6, renderScale: 2 }`. Testing workload controls one-by-one is not enough when the product exposes combinations that multiply render cost.
 
@@ -79,16 +88,24 @@ Use `kind: "custom"` only for combined object fixtures. Single numeric/string he
 
 ```ts
 await applyToolcraftPerformanceStressFixture(page, appPerformance, "scenario-id", {
-  detail: async (value) => {
-    await dragToolcraftSliderToValue(page, "Detail", Number(value));
+  detail: {
+    applyValue: async (value) => {
+      await dragToolcraftSliderToValue(page, "Detail", Number(value));
+    },
+    observeValue: async () =>
+      Number(await page.getByRole("slider", { name: "Detail" }).getAttribute("aria-valuenow")),
   },
-  scale: async (value) => {
-    await dragToolcraftSliderToValue(page, "Scale", Number(value));
+  scale: {
+    applyValue: async (value) => {
+      await dragToolcraftSliderToValue(page, "Scale", Number(value));
+    },
+    observeValue: async () =>
+      Number(await page.getByRole("slider", { name: "Scale" }).getAttribute("aria-valuenow")),
   },
 });
 ```
 
-The applier object must contain exactly one entry for each key in `stressFixture.value`. Missing keys and stale extra keys are test failures, so every heavy-state part is intentionally mapped through the real UI before measurement.
+The applier object contains exactly one entry for each key in `stressFixture.value`, and each entry provides both `applyValue` and `observeValue`. Missing keys, stale extra keys, or an observed value that differs from the declared fixture are test failures, so every heavy-state part is proved through the real UI before measurement.
 
 For `workloadFixture.value` object fixtures, use `applyToolcraftPerformanceWorkloadFixture` with the same exact-key rule. `workloadFixture` is the app baseline; `stressFixture` is the action under test.
 
@@ -155,6 +172,15 @@ Use real interactions for:
 - `viewport-zoom-stress` for detail-heavy or animated custom renderers;
 - `viewport-stability`.
 
+Every `export-copy` scenario declares `actionValue` with the exact `panelActions`
+value, `controlLabel` for its visible button, and `completionEvidence` set to
+`download` or `clipboard`. Its browser test uses the corresponding protected
+`measureToolcraftDownloadActionByLabel` or
+`measureToolcraftClipboardActionByLabel` helper with `scenarioId`. The helper
+owns the real click and completion event; the signed runtime-evidence reporter
+rejects missing completion, skipped/failed tests, and evidence from failed
+retries.
+
 For `slider` and `rangeSlider`, the required performance scenario is `control-drag`. A `control-change` scenario can cover selects, inputs, toggles, and other non-drag controls, but it does not prove live canvas feedback or drag smoothness for sliders.
 
 Animated custom renderers also need `animation-viewport-drag`. Animation-only frame sampling and viewport-only stability are not enough: the browser test must sample frames while physically dragging or panning the canvas viewport. If SVG/DOM cannot pass that combined budget, choose a different renderer strategy from evidence instead of loosening the budget.
@@ -167,16 +193,16 @@ During canvas drag, pan, pinch, zoom, and radar/center interactions, animated pr
 
 Animation checks should sample enough frames to catch jank. Interaction budgets must match scenario type rather than using one universal number.
 
-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.
+Use `app-performance.ts` as the single budget and fixture source. Mutating measurements pass `scenarioId` and a structured-cloneable `observeOutcome`; generic change mode proves a stable baseline before the action, its first changed response sets latency, and its final post-action outcome must remain different through the stability window. For autonomous output, pass `expectedOutcome` and observe a stable semantic state, or fix playback to a deterministic phase; latency is measured to that expected result. Scalar fixtures are applied and observed through `applyToolcraftPerformanceStressValue` / `applyToolcraftPerformanceWorkloadValue`; object fixtures use `applyToolcraftPerformanceStressFixture` / `applyToolcraftPerformanceWorkloadFixture`, apply every declared key, then re-observe the complete final state before evidence can attach. Budget checks await `expectToolcraftScenarioPerformanceBudget`. Completed measurements are frozen and branded for one scenario, so a mutable literal or another scenario's result cannot satisfy the gate.
 
-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 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. Use the current AI agent's controlled browser for targeted diagnosis. `pnpm verify:perf` is the protected final Playwright checkpoint; it builds the current production bundle, serves it through Vite preview, and runs every `browser perf:` scenario with one worker so budgets measure shipped runtime work instead of dev-server transformation and are not distorted by unrelated parallel browser tests.
 
 Run a full performance checkpoint only when:
 
 - the first working version of the app exists;
 - the user explicitly asks to optimize performance, fix lag, remove jank, speed up animation, stabilize drag/zoom, or otherwise complains about performance.
 
-For the first working product app, this checkpoint is mandatory: the app is not complete until `pnpm verify:final` and the browser performance checkpoint have both passed and the worklog records the runner as `agent-browser` or `playwright-fallback`. Use `pnpm verify:perf` only as the fallback when no agent-controlled browser is available or in CI/non-agent automation.
+For the first working product app, this checkpoint is mandatory and runs before `pnpm verify:final`. Run `pnpm verify:perf`; its protected Playwright runner records the current-source machine receipt automatically. Agent-controlled browser checks remain preferred for quick diagnosis and visual investigation, but they cannot mint or replace the final receipt. The final gate rejects a missing or stale receipt. Worklog prose remains decision context and cannot substitute for the structured receipt. A post-first-working non-performance exemption must use `pnpm verify:perf:record-exemption -- --tier=<0|1|2>` and requires a prior passed receipt.
 
 Performance fixes must preserve selected output and preview quality. Do not pass budgets by lowering image quality, selected `canvas.renderScale`, export resolution, source media fidelity, or canvas backing pixels unless the user explicitly chooses that lower-quality value through a visible control. Prefer coalescing slider updates, caching expensive inputs, moving work off the React render path, reusing GPU resources, or changing renderer strategy over reducing visual fidelity.
 

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

@@ -87,6 +87,10 @@ Common control fields:
 | `description` | Product-specific help text only when it adds meaning beyond the label. |
 | `visibleWhen` | Mode/type/source/include/variant/count visibility. Hidden values are preserved. |
 | `orderRole` | Makes section order testable. |
+| `semanticGroup` | Language-independent product sub-entity/workflow grouping, required on every control in sections larger than seven controls. |
+| `sliderValueKind` | `slider` intent: `"continuous"` or `"discrete"`. |
+| `textValueKind` | `text`/`code` intent: `"single-line"`, `"multiline"`, or `"structured"`. |
+| `curveIntent` | `curves` composition: `"single-value-map"` or `"color-channels"`. |
 | `performanceRole` | `"workload"` or `"responsiveness"` for coverage derivation. |
 | `performanceReason` | Why the role fits this app. |
 | `commitMode` | `text` controls: `"content"` applies while typing, `"setting"` commits on blur/Enter. |
@@ -101,30 +105,35 @@ Reserved runtime targets include `runtime.settingsTransfer`, `canvas.aspectRatio
 
 ## Built-In Control Types
 
-| `type` | Renders |
+[//]: # (toolcraft-contract:built-in-control-table:start)
+| `type` | Runtime visual owner |
 | --- | --- |
-| `actions` | Local section commands in 50% button cells. |
-| `anchorGrid` | Anchor picker. |
-| `channelMixer` | RGB channel mixer. |
-| `checkbox` | Checkbox field. |
-| `collectionActions` | Add/remove controls for growable runtime-backed item lists. |
-| `code` | Multiline editor for long or structured content. |
-| `color` | Hex color picker. |
-| `colorOpacity` | Hex color plus opacity. |
-| `curves` | Single or RGB curve editor. |
-| `fileDrop` | Image/file upload, multiple upload, sorting, and image transforms. |
-| `fontPicker` | Atomic typography block: font, weight, size, case, color/opacity, letter spacing, line height. |
-| `gradient` | Gradient type, angle, track, stops. |
-| `imagePicker` | Visual option picker. |
-| `palette` | Design-token palette family + shade. |
-| `rangeInput` | Two compact text values. |
-| `rangeSlider` | Two-thumb slider. |
-| `segmented` | Full-width compact finite choice. |
-| `select` | Dropdown. |
-| `slider` | Single-value slider. |
-| `switch` | Binary switch. |
-| `text` | Single-line input. |
-| `vector` | X/Y vector pad and fields. |
+| `aspectRatio` | `CanvasAspectRatioControl` |
+| `slider` | `Slider` |
+| `rangeSlider` | `RangeSlider` |
+| `text` | `TextInput` |
+| `rangeInput` | `RangeInput` |
+| `code` | `CodeTextarea` |
+| `select` | `Select` |
+| `segmented` | `Segmented` |
+| `switch` | `Switch` |
+| `checkbox` | `Checkbox` |
+| `actions` | `Actions` |
+| `collectionActions` | `CollectionActions` |
+| `panelActions` | `PanelActions` |
+| `colorOpacity` | `ColorOpacity` |
+| `palette` | `Palette` |
+| `vector` | `Vector` |
+| `color` | `Color` |
+| `gradient` | `Gradient` |
+| `fontPicker` | `FontPicker` |
+| `curves` | `Curves` |
+| `anchorGrid` | `AnchorGrid` |
+| `channelMixer` | `ChannelMixer` |
+| `fileDrop` | `FileDrop` |
+| `imagePicker` | `ImagePicker` |
+| `settingsTransfer` | `SettingsTransfer` |
+[//]: # (toolcraft-contract:built-in-control-table:end)
 
 Use `component-rules.md` for component-specific fit, labels, variants, units, parser behavior, and exceptions. Use `core/control-selection.md` before deciding a custom control is needed.
 
@@ -146,6 +155,8 @@ export const starterControlSectionInventory = [
 
 Every product control target appears exactly once in the inventory. Runtime `Setup`, sticky footer `Export`, settings transfer, and runtime canvas sizing targets do not need entries.
 
+For sections larger than seven controls, each control also declares `semanticGroup`. Controls editing one tightly scoped product sub-entity share the same value; mixed groups make a broad section fail and should be split. This fact is structural and may not be inferred from English labels.
+
 ## Transfer Metadata
 
 Reference and motion metadata lives in `starterTransferMode`.

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

@@ -17,24 +17,30 @@ Before planning or editing app code, runtime code, controls, canvas, panels, ren
 
 Do not edit implementation files until this preflight is complete.
 
-Core modules are required reading when listed by the routing table. Read each listed module fully. Do not rely on a truncated terminal excerpt; reopen the specific module or use a narrower range when a tool output is clipped.
+## Local Contract Authority
+
+The signed local `AGENTS.md` plus `docs/toolcraft/*` are sufficient and mandatory workflow input for a standalone generated app. External workflow skills should be used when available, but missing skills never invalidate `--no-skills` generation and never justify skipping the equivalent local spec, plan, debugging, browser, or verification requirement. `pnpm ai:check` enforces local code health and reports missing external skills as actionable guidance rather than a build failure.
+
+Core modules are required reading when listed by the routing table. Read each listed module fully, one phase at a time. Open exactly one listed document per terminal or tool read, even when several documents belong to the same route and phase. Do not concatenate documents or rely on a truncated excerpt; finish the current phase, then open the next phase when the work reaches it. The signed host and runtime validators enforce platform boundaries, while product organization remains open inside those boundaries.
 
 ## Task Routing
 
-Use the smallest reading set that covers the changed surface. If a task touches multiple surfaces, combine every matching row instead of picking only the closest one.
-
-| Task type | Read before editing |
-| --- | --- |
-| App assembly, route structure, generated app porting | `core/runtime-boundary.md`, `assembly-workflow.md`, `decision-contract.md` |
-| Reference app study, audit, or port | `core/reference-study.md`, `core/runtime-boundary.md`, `assembly-workflow.md`, `schema-reference.md`, `acceptance-testing.md`, `decision-contract.md` |
-| Schema, controls, defaults, persistence, actions | `core/control-selection.md`, `core/layout.md`, `schema-reference.md`, `component-rules.md`, `acceptance-testing.md` |
-| Custom controls | `core/control-selection.md`, `core/layout.md`, `custom-controls.md`, `component-rules.md`, `acceptance-testing.md` |
-| Renderer, canvas output, visual technique | `core/runtime-boundary.md`, `core/performance.md`, `renderer-technique.md`, `performance.md`, `acceptance-testing.md` |
-| Timeline, keyframes, animation transport | `core/timeline-animation.md`, `core/performance.md`, `decision-contract.md`, `component-rules.md`, `acceptance-testing.md` |
-| Layers | `core/runtime-boundary.md`, `core/layout.md`, `decision-contract.md`, `component-rules.md`, `acceptance-testing.md` |
-| Export, copy, media, background | `core/setup-export.md`, `core/media-upload.md`, `schema-reference.md`, `component-rules.md`, `acceptance-testing.md`, `performance.md` |
-| Broken control, visual mismatch, failed build, export bug, performance issue | `decision-contract.md`, the relevant `core/*` module, the relevant component/runtime doc, and the failing test/log first |
-| Figma implementation | Use Figma MCP/design context, then `core/reference-study.md`, `core/runtime-boundary.md`, `assembly-workflow.md`, and the relevant component docs |
+Use the smallest route set that covers the changed surface. When a task matches multiple routes, process them sequentially inside the phase currently in progress and skip documents already read in that phase; open each document separately and never concatenate route documents into one terminal output. Read Plan documents before the spec or implementation plan, Implementation documents immediately before code, and Verification documents immediately before writing or running proof. A broken behavior still starts with the failing test, log, or reproduction before its Plan documents; a Figma task still starts with Figma MCP/design context.
+
+[//]: # (toolcraft-workflow-routes:start)
+| Task route | Plan phase | Implementation phase | Verification phase |
+| --- | --- | --- | --- |
+| App assembly, route structure, generated app porting | `core/runtime-boundary.md`<br>`assembly-workflow.md` | `decision-contract.md` | `acceptance-testing.md` |
+| Reference app study, audit, or port | `core/reference-study.md`<br>`core/runtime-boundary.md`<br>`assembly-workflow.md` | `schema-reference.md`<br>`decision-contract.md` | `acceptance-testing.md` |
+| Schema, controls, defaults, persistence, actions | `core/control-selection.md`<br>`core/layout.md` | `schema-reference.md`<br>`component-rules.md` | `acceptance-testing.md` |
+| Custom controls | `core/control-selection.md`<br>`core/layout.md` | `custom-controls.md`<br>`component-rules.md` | `acceptance-testing.md` |
+| Renderer, canvas output, visual technique | `core/runtime-boundary.md`<br>`core/performance.md` | `renderer-technique.md`<br>`performance.md` | `acceptance-testing.md` |
+| Timeline, keyframes, animation transport | `core/timeline-animation.md`<br>`core/performance.md` | `decision-contract.md`<br>`component-rules.md` | `acceptance-testing.md` |
+| Layers | `core/runtime-boundary.md`<br>`core/layout.md` | `decision-contract.md`<br>`component-rules.md` | `acceptance-testing.md` |
+| Export, copy, media, background | `core/setup-export.md`<br>`core/media-upload.md` | `schema-reference.md`<br>`component-rules.md` | `acceptance-testing.md`<br>`performance.md` |
+| Broken control, visual mismatch, failed build, export bug, performance issue | `decision-contract.md`<br>`core/runtime-boundary.md` | `component-rules.md`<br>`renderer-technique.md` | `acceptance-testing.md`<br>`performance.md` |
+| Figma implementation | `core/reference-study.md`<br>`core/runtime-boundary.md`<br>`assembly-workflow.md` | `schema-reference.md`<br>`component-rules.md` | `acceptance-testing.md` |
+[//]: # (toolcraft-workflow-routes:end)
 
 ## Worklog Gate
 
@@ -70,6 +76,8 @@ Use the runtime extension points described in the current contracts:
 
 Do not recreate controls, panels, toolbar, timeline, layers, canvas shell, or runtime surfaces by hand. If a shared behavior is wrong, fix the shared runtime/template source and regenerate when needed.
 
+Browser verification is outcome-based. Protected helpers attach versioned evidence only after a persistent observable change, an observed fixture application, a decoded non-empty export inspection, a completed output action, an immutable scenario measurement, and its matching budget check. The signed reporter derives required evidence from acceptance and performance config and fails skipped, missing, duplicate, transient, unmeasured, or unbudgeted scenarios.
+
 ## Verification Gate
 
 Choose the tier from `AGENTS.md` before editing. Use the tier to decide checks.
@@ -77,7 +85,7 @@ Choose the tier from `AGENTS.md` before editing. Use the tier to decide checks.
 - Tier 0-1: targeted docs/typecheck/unit plus focused browser when visual.
 - Tier 2: `pnpm verify:quick` plus relevant browser acceptance.
 - Tier 3: `pnpm verify:quick`, targeted browser acceptance, and targeted performance scenarios only for touched workload/viewport/export paths.
-- Tier 4: `pnpm verify:final`; for the first working product version also run and pass a browser performance checkpoint with the current AI agent's controlled browser when available, using `pnpm verify:perf` only as fallback, then start `pnpm dev` for the local URL.
+- Tier 4: run `node scripts/check-toolcraft-integrity.mjs` directly. For the first working product version, run the browser performance checkpoint and record its current-source receipt first, then run `pnpm verify:final`, then start `pnpm dev` for the local URL.
 
 Run a full performance checkpoint only when:
 
@@ -86,4 +94,4 @@ Run a full performance checkpoint only when:
 
 Fast feature loops after the first working version do not run the full performance suite by default. Renderer, canvas, animation, export, timeline, layers, `canvas.renderScale`, bug fixes, and performance-sensitive controls still need targeted functional/browser checks first, plus targeted performance scenarios only when they directly exercise the touched path. Record any skipped full performance run and reason in the worklog.
 
-The app is not complete when required checks are failed, incomplete, pending, blocked, or listed as skipped. First working product delivery must record `pnpm verify:final` and the browser performance checkpoint as passed in the worklog, including runner `agent-browser` or `playwright-fallback`. After the first working version, skipping the full performance suite is valid only when the worklog explicitly says the full performance checkpoint is not required for a post-first-working non-performance edit.
+The app is not complete when required checks are failed, incomplete, pending, blocked, or listed as skipped. Run the integrity checker directly before the final gate so verification does not depend only on mutable package-script dispatch. First working product delivery runs `pnpm verify:perf` before `pnpm verify:final`; the protected Playwright checkpoint records the machine receipt, while agent-controlled browser work remains targeted diagnostic evidence. `verify:final` rejects missing or stale receipts. After the first working version, use the typed `pnpm verify:perf:record-exemption -- --tier=<0|1|2>` path only for a post-first-working non-performance edit backed by a prior passed receipt.

package/templates/starter/e2e/app-browser-acceptance-evidence.spec.ts

@@ -0,0 +1,111 @@
+import { expect, test, type TestInfo } from "@playwright/test";
+
+import { expectToolcraftAcceptanceOutcome, expectToolcraftExportedArtifact } from "./browser-acceptance-outcome-helpers";
+
+test("acceptance outcome rejects a return to its baseline during stability sampling", async () => {
+  let actionStarted = false;
+  let postActionObservations = 0;
+
+  await expect(
+    expectToolcraftAcceptanceOutcome(
+      async () => {
+        if (!actionStarted) return "before";
+        postActionObservations += 1;
+        return postActionObservations === 1 ? "after" : "before";
+      },
+      async () => {
+        actionStarted = true;
+      },
+      {
+        evidenceType: "command-side-effect",
+        requirementId: "command.delayed-transient",
+        stabilityIntervalMs: 0,
+      },
+    ),
+  ).rejects.toThrow(/stability window/i);
+});
+
+test("acceptance outcome snapshots a reused mutable observation", async ({}) => {
+  const outcome = { value: "before" };
+
+  await expect(
+    expectToolcraftAcceptanceOutcome(
+      async () => outcome,
+      async () => {
+        outcome.value = "after";
+      },
+      {
+        evidenceType: "command-side-effect",
+        requirementId: "command.mutable-observation",
+        stabilityIntervalMs: 0,
+      },
+    ),
+  ).resolves.toEqual({ value: "after" });
+});
+
+test("generic acceptance outcomes cannot claim specialized runtime evidence", async ({
+  page,
+}) => {
+  await page.setContent('<div id="outcome">before</div>');
+
+  await expect(
+    expectToolcraftAcceptanceOutcome(
+      () => page.locator("#outcome").textContent(),
+      () =>
+        page.locator("#outcome").evaluate((node) => {
+          node.textContent = "after";
+        }),
+      {
+        evidenceType: "timeline-duration" as never,
+        requirementId: "timeline.duration",
+      },
+    ),
+  ).rejects.toThrow(/specialized evidence/i);
+});
+
+test("export evidence requires a typed positive artifact inspection", async ({}, testInfo: TestInfo) => {
+  const attachmentCount = testInfo.attachments.length;
+
+  await expect(
+    expectToolcraftExportedArtifact(
+      async () => new Uint8Array([1, 2, 3]),
+      async () => ({ ok: true }),
+      { requirementId: "export.nominal-object" },
+    ),
+  ).rejects.toThrow(/byteLength/i);
+  await expect(
+    expectToolcraftExportedArtifact(
+      async () => new Uint8Array([1, 2, 3]),
+      async () => ({ byteLength: 0 }),
+      { requirementId: "export.zero-bytes" },
+    ),
+  ).rejects.toThrow(/positive byteLength/i);
+  await expect(
+    expectToolcraftExportedArtifact(
+      async () => new Uint8Array([1, 2, 3]),
+      async () => ({ byteLength: 2.5 }),
+      { requirementId: "export.fractional-bytes" },
+    ),
+  ).rejects.toThrow(/byteLength integer/i);
+  await expect(
+    expectToolcraftExportedArtifact(
+      async () => new Uint8Array([1, 2, 3]),
+      async () => ({ byteLength: 3, width: 1.5 }),
+      { requirementId: "export.fractional-width" },
+    ),
+  ).rejects.toThrow(/width integer/i);
+  expect(testInfo.attachments).toHaveLength(attachmentCount);
+
+  await expectToolcraftExportedArtifact(
+    async () => new Uint8Array([1, 2, 3]),
+    async (artifact) => ({
+      byteLength: artifact.byteLength,
+      contentHash: "pixel-hash",
+      height: 1,
+      mediaType: "image/png",
+      width: 1,
+    }),
+    { requirementId: "export.valid-inspection" },
+  );
+  expect(testInfo.attachments).toHaveLength(attachmentCount + 1);
+});