@pixel-point/toolcraft 0.0.13 → 0.0.15

package/templates/starter/AGENTS.md

@@ -4,17 +4,21 @@ This is a standalone Toolcraft template app generated from the base starter.
 
 ## Required Preflight
 
-Treat this `AGENTS.md` as the active project contract. Before planning or editing app code, runtime code, controls, canvas, panels, renderer, timeline, layers, export, or tests, you must read:
+Treat this `AGENTS.md` as the active project contract. Before planning or editing app code, runtime code, controls, canvas, panels, renderer, timeline, layers, export, or tests:
 
-1. `docs/toolcraft/workflow.md`
+1. Read `docs/toolcraft/workflow.md` in full.
+2. Select every task route that matches the requested surface.
+3. Read the selected routes' Plan phase before writing the spec or implementation plan.
+4. Read their Implementation phase immediately before editing code.
+5. Read their Verification phase before writing or running proof.
 
-Then follow `workflow.md` to choose the required contract docs and verification tier. Do not edit implementation files until this preflight is complete.
+Process matching routes sequentially within the current phase and skip repeated documents already read in that phase. Open exactly one listed document per terminal or tool read, including documents from the same route and phase. Do not concatenate multiple documents, routes, or phases into one large output, and never continue from truncated output. Choose and record the verification tier before implementation. Do not edit implementation files until the Plan and Implementation preflight is complete.
 
 ## Quick Entry Contract
 
 1. Build through `defineToolcraft` and `ToolcraftApp`.
 2. Keep app state in Toolcraft runtime schema and commands.
-3. Keep product output in `canvasContent`; never render app UI there. If upload/import is part of the source-material flow, do not invent canvas placeholder artwork, CTA copy, helper text, fake sample output, or preset source designs before real content exists.
+3. Keep product output in `canvasContent`; never render app UI there. The signed host owns `ToolcraftApp`, bootstrap, routes, and global runtime styles; product code supplies only `ToolcraftAppComposition`. If upload/import is part of the source-material flow, do not invent canvas placeholder artwork, CTA copy, helper text, fake sample output, or preset source designs before real content exists.
 4. Use built-in Toolcraft controls before custom controls.
 5. Do not hand-compose runtime surfaces or render built-in control components directly in app code; use `ToolcraftApp`, schema controls, `canvasContent`, `controlRenderers`, `onPanelAction`, and runtime commands.
 6. Before writing controls, make and export `starterControlSectionInventory`: each product controls section declares its title, product entity or workflow stage, targets, and grouping reason. Group by product meaning, not UI component type.
@@ -24,11 +28,11 @@ Then follow `workflow.md` to choose the required contract docs and verification
 10. If a Figma URL is provided, inspect the Figma file through MCP and rebuild from its structure; never implement from a screenshot or by eye.
 11. If a video, GIF, screen recording, contact sheet, or extracted-frame sequence is provided as a reference, write a Video Reference Study before implementation: storyboard frames, frame-to-frame transition analysis, behavior decomposition, and acceptance mapping. Do not implement video references from a single screenshot or high-level summary.
 12. Choose an explicit persistence policy; use schema `persistence` for user-edited app settings that should survive reload, and test real reload restoration when localStorage is enabled.
-13. Generated apps keep a controls panel so runtime `Setup` is visible from the first run; product sections are added after it. Runtime `Setup` is the first visible headerless controls block, is not collapsible, and always contains `Export Settings` and `Import Settings`; never implement settings import/export through `panelActions` or route-local file inputs, and never gate this block by app complexity. Visible `Aspect ratio`, `Canvas width`, and `Canvas height` controls are owned by `editable-output` canvas sizing and merge into the same Setup block after settings transfer. App-authored sections must not declare runtime Setup targets such as `runtime.settingsTransfer`, `canvas.aspectRatio`, `canvas.size.width`, `canvas.size.height`, `canvas.renderScale`, or `panels.timeline.extended`; those controls never suppress the mandatory runtime Setup controls. Runtime aspect presets apply canonical canvas sizes, with `16:9` equal to `1920x1080`; manual Canvas width/height edits keep the typed dimension, keep the other dimension unchanged, switch Aspect ratio to Custom, and show the reduced current ratio in custom ratio inputs; when no explicit product size is provided, the runtime default canvas size is also `1920x1080`. Product-output, exportable, shader, procedural, and reference-clone apps use `editable-output`; uploaded background/source images inside product canvases also use `editable-output`, keep the current canvas size, and render as cover/crop inside the current canvas bounds. Fixed/reference/base dimensions are initial `canvas.size` values, not reasons to hide `Aspect ratio`, `Canvas width`, or `Canvas height`. Non-vector raster, Canvas 2D, WebGL, and WebGPU previews set `canvas.renderScale: true`; Setup then appends `Resolution scale` after canvas sizing so backing pixels can increase up to scale 2 without changing CSS/output size. Performance fixes must preserve the selected render scale and keep canvas preview responsive to sliders/high-frequency controls at that scale; diagnose the bottleneck before reducing quality. Do not pass budgets by silently downsampling, stretching a lower-resolution backing canvas, blurring output, or clamping `canvas.renderScale` below the user's chosen value. When `panels.timeline` is enabled, runtime appends a `Timeline` switch as the last Setup control; off shows compact Play-only transport, on shows the extended timeline with scrubber, duration, loop, and keyframe UI, and the switch never changes product values, playback, keyframes, export, or Reset controls. When `panels.timeline` is omitted, the Timeline switch must not appear.
-14. Product apps expose a required `Background` section directly before export settings. It contains a Switch labeled `Include` and a background color control with `label: false` in one equal-width inline row; PNG export wires those runtime values into the standard export helper, live preview uses `shouldIncludeToolcraftPreviewBackground(state)` so Include can hide the product background, and video export keeps the background. Every app with `Export PNG` exposes `Image Export` with `export.image.format` and `export.image.resolution` as two `select` controls in one compact two-column inline row, and passes the selected resolution to `createToolcraftPngExportCanvas({ resolution })` so 2K/4K/8K change actual PNG dimensions. Animated apps with video export enable the top Toolcraft timeline and place `Image Export` immediately before `Video Export`.
+13. Generated apps follow the mandatory runtime Setup, canvas sizing, render scale, Timeline switch, Background, Image Export, Video Export, and sticky action rules in `docs/toolcraft/core/setup-export.md`. Do not duplicate or reinterpret those controls in app-authored sections.
+14. Media uploads, image/file mode, source images, multi-upload sorting, default assets, and image transform actions follow `docs/toolcraft/core/media-upload.md`.
 15. Keep `docs/toolcraft/agent-worklog.md` current with a decision trail, product decisions, explicit reference inputs, evidence, verification, and risks. Reference-runtime-clone apps also declare `referenceStudy` plus `referenceFeatureInventory` so every inspected reference feature has feature-level behavior evidence and maps to Toolcraft implementation and acceptance coverage.
-16. Prove every visible entity through acceptance, browser, and performance coverage.
-17. Workload performance scenarios must declare `stressFixture` for the tested control value; browser perf tests must use `getToolcraftPerformanceStressValue(appPerformance, scenarioId)` so heavy-case tests cannot use toy values. When the tested control is not itself the whole heavy source, declare `workloadFixture` and apply it first with `getToolcraftPerformanceWorkloadValue` or `applyToolcraftPerformanceWorkloadFixture`; this is the app baseline such as large media, long text, many items, or high render scale, and it must be paired with the measured `stressFixture`. Numeric maximums, density, item counts, canvas/media size, and combined heavy states declare `loadProfile` with `hardLimit`, `smoothTarget`, and `smoothTargetRatio`; try the hard limit first, and lower the guaranteed smooth target only in 10 percent steps with failed-measurement and optimization evidence. Ranges above `smoothTarget` are experimental, not silently guaranteed. Media import and image-processing workloads use `kind: "media"` fixtures at least `1920x1080`-equivalent, and heavy pixel/media Canvas 2D must evaluate WebGL/WebGPU with measured evidence before staying on CPU.
+16. Prove every visible entity through acceptance, browser, and performance coverage. Browser acceptance and performance pass only when protected helpers emit matching runtime evidence after successful assertions; source-code spelling and acceptance prose are not outcome authority. Declare typed conditional-visibility and background-output coverage, then use their fixed protected browser recipes. Generic acceptance outcomes prove command side effects only; use the fixed media, persistence, viewport, compound-control, layer, and timeline semantic recipes for specialized evidence.
+17. Performance workload, render scale, live slider responsiveness, GPU evaluation, and optimization evidence rules live in `docs/toolcraft/core/performance.md` plus `docs/toolcraft/performance.md`.
 18. Custom renderer apps declare a Render Pipeline Inventory in typed `rendererPipeline`: render passes, cache keys, execution location, preview/export quality, and interaction invalidation.
 19. Classify every implementation pass with a verification tier before editing. Use targeted checks for incremental edits and the full final gate only for final delivery, exports, or architecture/runtime/template changes.
 
@@ -36,22 +40,23 @@ Then follow `workflow.md` to choose the required contract docs and verification
 
 The generated folder starts as a neutral Toolcraft shell: canvas upload plus toolbar. It intentionally does not include demo controls, prompt fields, layers, or timeline. Do not treat test fixtures or documentation examples as product requirements. Add controls, timeline, layers, sticky actions, persistence, and custom renderers only after the requested product or reference app requires them.
 
-When the folder becomes a real product, update `src/app/app-acceptance.ts` from `appProductReadiness.mode: "starter"` to `mode: "product"` and fill `productName`, `productSummary`, and `requestedBehavior`. Renamed product folders are not allowed to keep neutral starter readiness.
+When the folder becomes a real product, update `src/app/app-acceptance-data.ts` from `appProductReadiness.mode: "starter"` to `mode: "product"` and fill `productName`, `productSummary`, and `requestedBehavior`. Renamed product folders are not allowed to keep neutral starter readiness.
 
 ## License
 
-This project includes Toolcraft source code governed by the Toolcraft Designer License in `LICENSE.md`. `NOTICE.md` explains that generated apps include Toolcraft runtime, starter, UI component, documentation, and template source code. Designer client work is permitted under the license, and using AI coding assistants or agents such as Codex, Claude, ChatGPT, Cursor, or similar tools to work on generated apps is permitted. Platform, generator, AI software product, app-builder, website-builder, template-marketplace, and resale uses require a separate commercial license from Pixel Point.
+This project includes Toolcraft source code available under the MIT License in `LICENSE.md`. `NOTICE.md` explains that generated apps include Toolcraft runtime, starter, UI component, documentation, and template source code.
 
 ## Local Reference Docs
 
 Use this `AGENTS.md` as the entry contract. Use local docs for detail; the app must remain buildable without the website.
 
 - `docs/toolcraft/workflow.md` — required preflight, task routing, worklog gate, and verification routing.
+- `docs/toolcraft/core/runtime-boundary.md`, `docs/toolcraft/core/setup-export.md`, `docs/toolcraft/core/control-selection.md`, `docs/toolcraft/core/layout.md`, `docs/toolcraft/core/media-upload.md`, `docs/toolcraft/core/timeline-animation.md`, `docs/toolcraft/core/performance.md`, `docs/toolcraft/core/reference-study.md` — focused core modules routed by `workflow.md`.
 - `docs/toolcraft/assembly-workflow.md` — runtime assembly, canvas output, and reference clone path.
 - `docs/toolcraft/decision-contract.md` — rule ids, levels, and enforcement expectations.
 - `docs/toolcraft/schema-reference.md` — schema authoring rules for `src/app/app-schema.ts`.
 - `docs/toolcraft/component-rules.md` — slider, segmented, color, upload, image picker, vector, layers, timeline, and footer action rules.
-- `docs/toolcraft/acceptance-testing.md` — app entity matrix and browser acceptance for `src/app/app-acceptance.ts`.
+- `docs/toolcraft/acceptance-testing.md` — app entity matrix and browser acceptance for `src/app/app-acceptance-data.ts`.
 - `docs/toolcraft/performance.md` — performance roles, scenarios, and workload coverage for `src/app/app-performance.ts`.
 - `docs/toolcraft/renderer-technique.md` — DOM, SVG, Canvas 2D, WebGL, and mixed renderer choices.
 - `docs/toolcraft/agent-worklog.md` — implementation decision trail, evidence, verification, and remaining risks.
@@ -59,12 +64,18 @@ Use this `AGENTS.md` as the entry contract. Use local docs for detail; the app m
 
 ## Edit Surface
 
-- Build the product by editing `src/app/app-schema.ts` and app-specific files under `src/app` and `src/routes`.
-- Keep route files thin: routes compose schema-backed app screens and product renderers.
-- Keep `src/app/app-acceptance.ts` aligned with every visible product entity.
+- Build the product through `src/app/app-composition.tsx`, `src/app/app-schema.ts`, and any focused product-owned modules imported by that composition. Product module location under `src` is unrestricted; the AST boundary and code-health inventory scan every product production module regardless of folder.
+- Do not edit the signed framework bootstrap: `index.html`, `src/main.tsx`, `src/router.tsx`, `src/routes/index.tsx`, `src/routes/root.tsx`, or `src/styles.css`. The protected route owns the `ToolcraftApp` host and its `className`.
+- Product styles use locally imported `*.module.css` files only. Every selector is anchored by a local class. A first-compound `:is()` or `:where()` is a valid local anchor only when every branch is locally anchored; `:not()` and `:has()` do not create an anchor. Do not add plain product CSS, CSS `@import`, package CSS imports, `:global`, bare/root selectors, sibling escapes, selectors that target Toolcraft host attributes, or global `<style>`/`CSSStyleSheet` injection.
+- Product `import()` and `require()` specifiers are statically resolvable. Computed module loading is rejected in production and product tests. Production modules do not import product tests, test-support modules, or protected browser-evidence internals, directly or through product bridges; use the protected public acceptance/performance helpers instead of emitting reserved evidence.
+- Product production modules form an acyclic dependency graph. Code health resolves relative imports, directory indexes, configured TypeScript aliases, and local package exports; type-only, external-package, test, and copied-framework edges are excluded. A failure reports the complete shortest cycle so ownership can be repaired instead of hidden behind a barrel or alias.
+- Root Vite, Vitest, Playwright, and TypeScript verification configuration is signed platform code. Do not add alternate config files whose names resolve to those protected config families.
+- Keep `src/app/app-acceptance-data.ts` aligned with every visible product entity.
+- Do not edit `src/app/app-acceptance.ts`, `src/app/acceptance`, supplied `app-acceptance.*` meta-tests, or the generic browser acceptance harness. They are framework-owned files covered by the signed integrity manifest; add product-specific Vitest and Playwright tests in separate app-owned files.
 - Keep `src/app/app-performance.ts` as app-specific performance matrix config only.
 - Do not paste, restore, or duplicate runtime validators inside `src/app/app-performance.ts`.
-- Do not edit `src/toolcraft` unless you are intentionally changing the local copied Toolcraft runtime.
+- Do not edit the generated contract files under `docs/toolcraft` or the generated `LICENSE.md` and `NOTICE.md`; they are framework-owned and covered by the signed integrity manifest. `docs/toolcraft/agent-worklog.md` is the explicit editable exception for product decisions and verification evidence.
+- Do not edit `src/toolcraft`. It is an immutable signed copy of the shared Toolcraft runtime; change the monorepo runtime and regenerate the app instead.
 - Before final delivery, replace the starter worklog with `Mode: product`, add `Decision Trail` entries for significant implementation passes, and record concrete decisions for renderer, timeline, layers, controls, export, and performance. Each decision-trail iteration must name the user-visible result, source/reference checked, contract rules applied, rejected alternatives, and state/output mapping. `pnpm test` fails if the worklog is missing, lacks the decision trail, or still describes the neutral starter.
 - `pnpm test` includes Toolcraft source integrity and local docs checks. If a desired control style is missing, fix the schema or regenerate from the upstream template/runtime; do not patch copied `src/toolcraft` files for one app.
 
@@ -72,6 +83,7 @@ Use this `AGENTS.md` as the entry contract. Use local docs for detail; the app m
 
 These ids mirror `TOOLCRAFT_DECISION_CONTRACT` in `@/toolcraft/runtime`. Keep this list synced so standalone instructions do not drift from runtime validators.
 
+[//]: # (toolcraft-contract:decision-rule-list:start)
 - `runtime-shell-required`
 - `canvas-no-app-ui`
 - `canvas-surface-preserved`
@@ -83,21 +95,24 @@ These ids mirror `TOOLCRAFT_DECISION_CONTRACT` in `@/toolcraft/runtime`. Keep th
 - `timeline-enabled-behavior`
 - `controls-product-coverage`
 - `output-export-required`
+- `controls-section-inventory-required`
+- `controls-component-layout-invariants`
 - `controls-layout-heuristics`
 - `renderer-technique-inventory`
-- `video-reference-analysis`
 - `reference-clone-source-of-truth`
+- `video-reference-analysis`
 - `acceptance-product-observable`
 - `performance-coverage-levels`
 - `persistence-policy-explicit`
 - `workflow-required`
+[//]: # (toolcraft-contract:decision-rule-list:end)
 
 ## Runtime Contract
 
 - Use `defineToolcraft` from `@/toolcraft/runtime`.
-- Render the app through `ToolcraftApp` from `@/toolcraft/runtime/react`.
-- Use `<ToolcraftApp schema={appSchema} />` for schema-only apps.
-- Use `<ToolcraftApp schema={appSchema} canvasContent={<ProductRenderer />} />` for custom product renderers.
+- Export an `appComposition` satisfying `ToolcraftAppComposition` from `src/app/app-composition.tsx`.
+- Keep product composition limited to `schema`, `canvasContent`, `controlRenderers`, `onPanelAction`, and `renderDefaultCanvasMedia`; host `className` and `style` are not product extension points.
+- Do not import `ToolcraftApp`, low-level runtime surfaces, or built-in controls into product modules. The signed host renders the shell; product modules use schema controls and supported composition fields.
 - Use `renderDefaultCanvasMedia={false}` when a custom renderer replaces the default media preview.
 - Use `ToolcraftApp onPanelAction` for sticky footer product actions such as Generate, Apply, Export, Copy, or Download.
 - Keep final app behavior in the schema and runtime command bus, not in isolated local control state.
@@ -106,19 +121,18 @@ These ids mirror `TOOLCRAFT_DECISION_CONTRACT` in `@/toolcraft/runtime`. Keep th
 - Use schema `defaultValue` for every resettable control.
 - Route editor-owned actions through runtime commands such as `controls.reset`, `media.import`, `media.delete`, `canvas.center`, `history.undo`, and `history.redo`.
 
-## Required AI Workflow Skills
+## AI Workflow Skills And Local Fallback
 
-AI must work on this app through the required workflow skills when the environment supports Codex skills. These skills are part of the task process, not optional reading.
+The signed local `AGENTS.md` and `docs/toolcraft/*` files are the mandatory workflow authority. Use the named workflow skills when the environment provides them; they improve execution but are not a prerequisite for a standalone generated app to remain buildable and verifiable.
 
 - Before writing or changing an app spec, use `brainstorming` to decide product behavior, canvas sizing mode, panels, media flow, controls, export/copy behavior, renderer technique, timeline/layer choice, and ambiguous requirements.
 - 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 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.
-- Do not silently skip required workflow skills, and do not replace them with an ad hoc plan.
+- Run `pnpm ai:check` before app generation or major changes. It enforces local code health, the product AST boundary, and external skill availability. With an explicit `--no-install` generation the AST pass reports that it is deferred; normal `pnpm test` and every final gate require installed dependencies and run the full boundary.
+- If a workflow skill is missing and installation is available, install it and refresh the session. If installation is unavailable or the app was generated with `--no-skills`, continue through the equivalent signed local workflow instead of stopping or weakening verification.
+- Do not silently ignore a missing workflow capability: follow the matching local requirement in this file and `docs/toolcraft/workflow.md`, and record the fallback in the implementation plan or worklog.
 - The Toolcraft app contract overrides generic brainstorming approval and visual-companion rituals. If the user asks to build or port an app, that request is approval to produce the spec, plan, implementation, tests, build, and local run unless a product-critical ambiguity remains.
 - Do not ask the user to confirm decisions already covered by this contract, the prompt, or the reference app. Record the decision in the spec and continue.
 - Do not ask whether to enable a browser companion during brainstorming. Browser verification is mandatory after the app runs locally.
@@ -143,7 +157,7 @@ Choose the tier by blast radius, not by line count. If uncertain, move one tier
 | Tier 1 — local control presentation | One control or panel visual state changes: spacing, hover, focus, disabled, marker visibility, label fit, or component variant display. Runtime state shape and product renderer are unchanged. | Targeted unit/component test plus one focused browser check for the affected control or panel. |
 | Tier 2 — schema/product behavior | Controls, sections, defaults, persistence, panel actions, export actions, acceptance rows, or product behavior mapping changes. | `pnpm verify:quick` plus relevant browser acceptance. Run perf only when the changed control affects renderer workload or responsiveness. |
 | Tier 3 — renderer/canvas/runtime feature | Custom renderer, animation loop, canvas sizing, upload/media, timeline, layers, toolbar, export bytes, WebGL/Canvas/SVG output, zoom, radar, history, heavy control behavior changes, or a post-generation iteration that touches renderer workload or viewport stability. | `pnpm verify:quick`, targeted browser acceptance, and targeted performance scenarios only for touched workload/viewport/export paths. |
-| Tier 4 — final delivery/template architecture | Fresh generated app completion, folder export, commit-ready delivery, dependency changes, runtime/template/contract/CLI changes, broad refactors, or major post-generation iterations that rewrite renderer, canvas, animation, timeline/keyframes, layers, media, export, or control mapping. | Fresh folders run `pnpm install` once, then `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 the Playwright fallback for CI/non-agent runs or agents without a browser, then start `pnpm dev` to provide the local URL. |
+| Tier 4 — final delivery/template architecture | Fresh generated app completion, folder export, commit-ready delivery, dependency changes, runtime/template/contract/CLI changes, broad refactors, or major post-generation iterations that rewrite renderer, canvas, animation, timeline/keyframes, layers, media, export, or control mapping. | Fresh folders run `pnpm install` once. For the first working product version, run the browser performance checkpoint first and record its current-source receipt, then run `pnpm verify:final`, then start `pnpm dev` to provide the local URL. |
 
 Do not rerun `pnpm install` after every edit. Run it after fresh export, dependency changes, lockfile changes, or a missing package error.
 
@@ -153,22 +167,23 @@ Run a full performance checkpoint only when the first working version of an app
 
 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 workload/viewport/export path. Record any skipped full performance run and reason in the verification note or worklog.
 
-The first working product app version is not complete until `pnpm verify:final` and the required browser performance checkpoint have passed and the worklog records the runner as `agent-browser` or `playwright-fallback`. Do not report final delivery when required checks are failed, incomplete, pending, blocked, or listed as skipped. After the first working version, a skipped full performance run is valid only when the worklog explicitly says the full performance checkpoint is not required for a post-first-working non-performance edit.
+The first working product app version is not complete until `pnpm verify:perf` has produced a current-source structured receipt and `pnpm verify:final` has passed against that receipt. Agent-controlled browser checks remain useful for targeted diagnosis and visual verification, but terminal prose cannot mint the machine receipt. Worklog prose is context, not execution proof. After the first working version, a skipped full performance run is valid only through `pnpm verify:perf:record-exemption -- --tier=<0|1|2>`, backed by a prior passed receipt, for a post-first-working non-performance edit.
 
 ## Required Checks
 
 For final delivery, run:
 
 ```bash
+node scripts/check-toolcraft-integrity.mjs
 pnpm verify:final
 pnpm dev
 ```
 
-For the first working product delivery, run the browser performance checkpoint after `pnpm verify:final` and before `pnpm dev`: use the agent-controlled browser when available, otherwise run `pnpm verify:perf` as the Playwright fallback.
+For the first working product delivery, run `pnpm verify:perf` before `pnpm verify:final`; its protected Playwright runner records the machine-verifiable receipt. Use the agent-controlled browser for targeted diagnosis and visual checks without treating it as a replacement receipt. The final gate rejects missing or stale receipts.
 
 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 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.
+Run `node scripts/check-toolcraft-integrity.mjs` directly before the final gate; do not rely only on a package script to invoke it. `pnpm test` must also 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` is the protected Playwright checkpoint for the two full-performance triggers; it must build and serve the current production bundle, then run the performance audit plus browser budget suite sequentially so budgets exclude dev-server transformation and unrelated 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.
 
@@ -192,4 +207,5 @@ The app is complete only when:
 - performance checks cover workload and responsiveness for all relevant controls;
 - detail-heavy or animated custom renderers pass real viewport drag and zoom stress checks;
 - workload browser perf tests use the declared `stressFixture` value from `app-performance.ts`, and apply `workloadFixture` first whenever the scenario declares an independent heavy app baseline;
+- bounded numeric workload ranges and hard limits are derived from schema; scenario values cannot redefine them, custom metrics cannot bypass them, many-item fixtures apply at least 10 real items, and degraded ceilings prove every exact 10 percent step with matching scenario/target identity;
 - browser tests verify upload/clear, controls, canvas sizing, toolbar, timeline/layers when enabled, sticky actions, output dimensions, and viewport stability.

package/templates/starter/LICENSE.md

@@ -1,98 +1,21 @@
-# Toolcraft Designer License
+# MIT License
 
 Copyright (c) 2026 Pixel Point
 
-This license governs Toolcraft, including the CLI, starter template, runtime,
-UI components, documentation, and any generated application code that includes
-Toolcraft source code.
-
-## 1. Permitted Designer Use
-
-You may use Toolcraft for personal, educational, internal evaluation, and
-designer client work.
-
-Designer client work means using Toolcraft as part of paid design, development,
-consulting, or creative services to create a custom application for a specific
-client.
-
-Designers, freelancers, agencies, and studios may deliver generated
-applications to their clients, and those clients may use the delivered
-application for their own business, website, marketing, internal workflows, or
-product presentation.
-
-## 2. Generated Applications
-
-A generated application may be modified, deployed, and used by the designer or
-the designer's client as a custom client deliverable.
-
-You may not sell, sublicense, redistribute, publish, or offer generated
-applications as standalone products, stock templates, starter kits, theme packs,
-marketplace items, or reusable application templates.
-
-## 3. AI-Assisted Development
-
-You may use AI coding assistants, AI agents, design assistants, large language
-models, editors, IDE assistants, and similar tools to create, inspect, modify,
-refactor, test, document, deploy, or maintain generated applications for any use
-permitted by this license.
-
-This includes tools such as Codex, Claude, ChatGPT, Cursor, and similar
-assistants. Using those tools to work on Toolcraft projects or generated
-applications does not, by itself, make your use a prohibited AI software, AI app
-builder, AI design tool, code generation platform, or competing generator tool.
-
-This section does not allow you to package, embed, host, or provide Toolcraft or
-generated applications as part of a paid AI software product, AI app builder, AI
-design tool, code generation platform, or competing generator service.
-
-## 4. Prohibited Uses
-
-You may not use Toolcraft, generated applications, or any Toolcraft runtime,
-starter, UI, or template code as part of:
-
-- paid AI software;
-- AI app builders;
-- AI design tools;
-- website builders;
-- app builders;
-- design-to-code SaaS products;
-- code generation platforms;
-- template marketplaces;
-- competing generator tools;
-- any product or service whose primary purpose is to let third parties generate,
-  resell, or reuse applications based on Toolcraft.
-
-These uses require a separate commercial license from Pixel Point.
-
-## 5. No Hosted Generator or Resale Rights
-
-You may not provide Toolcraft or substantially similar functionality to third
-parties as a hosted service, API, plugin, marketplace product, or downloadable
-generator without a separate commercial license.
-
-## 6. No Trademark Rights
-
-This license does not grant rights to use the Pixel Point or Toolcraft names,
-logos, branding, or trademarks except to identify Toolcraft as the tool used to
-create a project.
-
-## 7. Ownership
-
-You own the original design, content, configuration, and product-specific code
-that you create.
-
-Pixel Point retains ownership of Toolcraft, including the CLI, starter template,
-runtime, UI components, documentation, and copied Toolcraft source code included
-in generated applications.
-
-## 8. Commercial Licensing
-
-If your intended use is not allowed by this license, you must obtain a separate
-commercial license before using Toolcraft for that purpose.
-
-Contact: licensing@pixel-point.com
-
-## 9. No Warranty
-
-Toolcraft is provided "as is", without warranty of any kind. Pixel Point is not
-liable for damages arising from use of Toolcraft or generated applications.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/templates/starter/NOTICE.md

@@ -3,6 +3,6 @@
 This application was generated with Toolcraft and includes Toolcraft runtime,
 starter, UI component, documentation, and template source code.
 
-Use of that Toolcraft code is governed by `LICENSE.md`. Product-specific design,
-content, configuration, and application code that you create remain yours, but
-the Toolcraft source copied into this project remains owned by Pixel Point.
+Use of that Toolcraft code is governed by the MIT License in `LICENSE.md`.
+Product-specific design, content, configuration, and application code that you
+create remain yours.

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

@@ -6,6 +6,21 @@ Use `../../AGENTS.md` as the entry contract, then read `workflow.md` before plan
 
 The starter app itself is intentionally neutral. It should show the Toolcraft canvas/upload/toolbar baseline only until the product schema is authored. Demo controls, prompt inputs, layers, and timeline belong in tests/docs or in a real generated product that needs them.
 
+## Core modules
+
+`workflow.md` routes agents to these focused modules by Plan, Implementation, and Verification phase. Read each selected route sequentially within the current phase, skip repeated modules already read in that phase, and never rely on truncated terminal output.
+
+- `core/runtime-boundary.md` — Toolcraft shell, allowed extension points, canvas boundary, and generated-app source boundary.
+- `core/setup-export.md` — required Setup, canvas sizing, render scale, Timeline switch, Background, Image Export, Video Export, and sticky export actions.
+- `core/control-selection.md` — built-in control fit, exact owners, compound controls, actions, collection actions, vector ownership, and custom control gate.
+- `core/layout.md` — sections, dependency cohesion, headers, reset, spacing, dividers, labels, inline rows, actions layout, colors, select, and segmented fit.
+- `core/media-upload.md` — file/image upload, multi-upload, sorting, transform actions, canvas source images, default assets, and source material behavior.
+- `core/timeline-animation.md` — animation intent, timeline requirement, compact/extended timeline, seamless forward loops, duration changes, keyframes, and video timing.
+- `core/performance.md` — verification triggers, workload fixtures, media/pixel workloads, render scale, live slider responsiveness, renderer pipeline inventory, and optimization evidence.
+- `core/reference-study.md` — reference-runtime clone, feature inventory, reference study, Figma source, video references, acceptance mapping, and worklog evidence.
+
+The broad docs below remain compatibility and topic references. They do not replace `workflow.md` routing or the `core/*` modules.
+
 1. `workflow.md` — required preflight, task routing, worklog gate, and verification routing.
 2. `assembly-workflow.md` — how the app must be assembled.
 3. `decision-contract.md` — hard rules, defaults, heuristics, and escape hatches.
@@ -27,19 +42,19 @@ Every implementation pass must choose a verification tier before editing. Use th
 | Tier 1 | One control or panel visual state | targeted test + focused browser check |
 | Tier 2 | Schema, defaults, persistence, actions, product mapping | `pnpm verify:quick` + relevant browser acceptance |
 | Tier 3 | Renderer, canvas, timeline, layers, upload, export, zoom, heavy controls, or a touched performance-sensitive path | `pnpm verify:quick` + targeted browser checks, plus targeted perf scenarios only for the touched path |
-| Tier 4 | Final delivery, fresh export, runtime/template/contract changes, broad renderer/product rewrites | `pnpm verify:final`; for the first working product version also run and pass a browser performance checkpoint with the agent-controlled browser when available, using `pnpm verify:perf` only as fallback |
+| Tier 4 | Final delivery, fresh export, runtime/template/contract changes, broad renderer/product rewrites | `pnpm verify:final`; for the first working product version run protected `pnpm verify:perf` first |
 
-Run the full performance checkpoint only when the first working app version exists, or when the user explicitly asks to optimize performance, fix lag, remove jank, speed up animation, stabilize drag/zoom, or otherwise complains about performance. Prefer the current AI agent's controlled browser. Use `pnpm verify:perf` only when no agent browser is available or in CI/non-agent automation.
+Run the full performance checkpoint only when the first working app version exists, or when the user explicitly asks to optimize performance, fix lag, remove jank, speed up animation, stabilize drag/zoom, or otherwise complains about performance. Use the current AI agent's controlled browser for targeted diagnosis and visual checks. Only the protected `pnpm verify:perf` Playwright checkpoint records the passed receipt required by final delivery.
 
 Performance fixtures use `loadProfile` for reasoned workload ceilings: test the product hard limit first, and only lower the guaranteed `smoothTarget` in 10 percent steps with failed-measurement and optimization evidence. Ranges above the smooth target must be treated as experimental, not silently guaranteed.
 
-The first working product app version is not complete until `pnpm verify:final` and the required browser performance checkpoint have passed and the worklog records the runner as `agent-browser` or `playwright-fallback`. Do not report final delivery when required checks are failed, incomplete, pending, blocked, or listed as skipped. After the first working version, a skipped full performance run is valid only when the worklog explicitly says the full performance checkpoint is not required for a post-first-working non-performance edit.
+The first working product app version is not complete until `pnpm verify:perf` has recorded the protected Playwright checkpoint and `pnpm verify:final` has passed against that receipt. Agent-controlled browser checks can supplement diagnosis but cannot replace the receipt. Do not report final delivery when required checks are failed, incomplete, pending, blocked, or listed as skipped. After the first working version, a skipped full performance run is valid only when the worklog explicitly says the full performance checkpoint is not required for a post-first-working non-performance edit.
 
 Fresh folders or dependency changes need `pnpm install` before verification. Final delivery still starts the local app after the gate:
 
 ```bash
+pnpm verify:perf # required first-working performance checkpoint
 pnpm verify:final
-pnpm verify:perf # Playwright fallback when no agent browser is available or in CI/non-agent automation
 pnpm dev
 ```
 

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

@@ -1,11 +1,13 @@
 # Acceptance Testing
 
+> Reading route: start with `workflow.md`. Core generated-app rules live in `core/*`; this file is a focused acceptance reference for the topic below.
+
 Every visible product entity must prove it works. A control is not accepted because it renders; it is accepted only when tests prove user interaction changes runtime state and the final product output, command side effect, timeline frame, layer result, media lifecycle, or canvas viewport.
 
 ## Required Files
 
-- `src/app/app-acceptance.ts`
-- `src/app/app-acceptance.test.ts`
+- `src/app/app-acceptance-data.ts`
+- app-specific tests under `src/app` outside the reserved `app-acceptance.*` framework namespace
 - `src/app/app-performance.ts`
 - `src/app/app-performance.test.ts`
 - `docs/toolcraft/agent-worklog.md`
@@ -14,7 +16,7 @@ Every visible product entity must prove it works. A control is not accepted beca
 - `e2e/app-performance.spec.ts`
 - `e2e/product-observable-helpers.ts`
 
-`pnpm verify:final` must pass before final delivery. Incremental edits use the verification tier classifier from `assembly-workflow.md`: run targeted browser acceptance for the changed entity, and add a full browser performance checkpoint for the first working product version or an explicit performance complaint. Prefer the current AI agent's controlled browser; use `pnpm verify:perf` only as the Playwright fallback when no agent browser is available or in CI/non-agent automation.
+`pnpm verify:final` must pass before final delivery. Incremental edits use the verification tier classifier from `assembly-workflow.md`: run targeted browser acceptance for the changed entity, and add a full browser performance checkpoint for the first working product version or an explicit performance complaint. Run `pnpm verify:perf` before the final gate; its protected Playwright runner records the current-source machine receipt automatically. Agent-controlled browser checks remain useful for targeted diagnosis but cannot replace that receipt. `verify:final` rejects a missing or stale current-source receipt.
 
 A full performance checkpoint is triggered only by the first working app version, or by a user request to optimize performance, fix lag, remove jank, speed up animation, stabilize drag/zoom, or otherwise investigate poor performance.
 
@@ -32,7 +34,7 @@ Product readiness also requires product surface: controls, layers, timeline, `ca
 
 Product apps must update `docs/toolcraft/agent-worklog.md` before final delivery. The file records why the app chose its renderer, timeline mode, layer policy, control grouping, export behavior, and performance strategy.
 
-The worklog must declare `Mode: product`. Every `Decision Trail` iteration must include `Request:`, `Task type:`, `User-visible result:`, `Source/reference checked:`, `Reference inputs:`, `Docs/contracts read:`, `Contract rules applied:`, `Decision:`, `Alternatives rejected:`, `State/output mapping:`, `Files changed:`, `Verification:`, `Skipped checks:`, and `Risks:`. `Reference inputs:` is the explicit inventory of prompt/reference assets for that pass: write `None` only when there were no external references, otherwise list the source apps, URLs, screenshots, videos, GIFs, screen recordings, contact sheets, extracted-frame folders, or media files used. `State/output mapping:` names how controls, commands, timeline, layers, media, or renderer state reaches the visible product or export. Each decision section (`Renderer`, `Timeline`, `Layers`, `Controls`, `Export`, `Performance`) must include `Decision:`, `Reason:`, and `Evidence:` entries. `Evidence` should name files, reference behavior, contract rules, browser checks, performance checks, or exact commands. `Performance` evidence must name the hard limit, smooth target, smooth target ratio, failed higher measurements, and attempted optimizations whenever a load profile lowers the smooth target below the hard limit. `Verification` must list concrete checks such as `pnpm verify:quick`, browser tests, the agent-browser performance checkpoint, or `pnpm verify:perf` as the Playwright fallback. First working product delivery must record `pnpm verify:final` and the browser performance checkpoint as passed, including runner `agent-browser` or `playwright-fallback`; fallback evidence must state why no agent browser was available or why the run was CI/non-agent automation. Failed, incomplete, pending, blocked, or skipped required checks make the app incomplete unless the full performance checkpoint is explicitly not required for a post-first-working non-performance edit. `Risks` must include either `Risk:` entries or `None:` with a reason.
+The worklog must declare `Mode: product`. Every `Decision Trail` iteration must include `Request:`, `Task type:`, `User-visible result:`, `Source/reference checked:`, `Reference inputs:`, `Docs/contracts read:`, `Contract rules applied:`, `Decision:`, `Alternatives rejected:`, `State/output mapping:`, `Files changed:`, `Verification:`, `Skipped checks:`, and `Risks:`. `Reference inputs:` is the explicit inventory of prompt/reference assets for that pass: write `None` only when there were no external references, otherwise list the source apps, URLs, screenshots, videos, GIFs, screen recordings, contact sheets, extracted-frame folders, or media files used. `State/output mapping:` names how controls, commands, timeline, layers, media, or renderer state reaches the visible product or export. Each decision section (`Renderer`, `Timeline`, `Layers`, `Controls`, `Export`, `Performance`) must include `Decision:`, `Reason:`, and `Evidence:` entries. `Evidence` should name files, reference behavior, contract rules, browser checks, performance checks, or exact commands. `Performance` evidence must name the hard limit, smooth target, smooth target ratio, failed higher measurements, and attempted optimizations whenever a load profile lowers the smooth target below the hard limit. `Verification` must list concrete checks such as `pnpm verify:quick`, targeted agent-browser diagnosis, browser tests, and the automated `pnpm verify:perf` checkpoint. First working product delivery must record `pnpm verify:final` and `pnpm verify:perf` as passed. Failed, incomplete, pending, blocked, or skipped required checks make the app incomplete unless the full performance checkpoint is explicitly not required for a post-first-working non-performance edit. `Risks` must include either `Risk:` entries or `None:` with a reason.
 
 The acceptance gate fails if the worklog is missing, still says `Mode: starter`, or lacks concrete decision evidence.
 
@@ -56,8 +58,21 @@ Each row should name:
 - `canvasSizingCoverage: "fixed-output-size"` only for non-product/internal `fixed-output` fixtures.
 - `canvasSizingCoverage: "intrinsic-media-size"` only for explicit media-viewer/source-native upload apps where imported media natural dimensions intentionally own `canvas.size`.
 - `persistenceCoverage: "reload"` when schema `persistence.storage` is `"localStorage"`.
+- `timelineLoopProof` on playback rows whose `timelinePlaybackCoverage` includes `"loop"`. It declares `direction: "forward-only"`, `reversePlayback: "forbidden"`, `seam: "first-last-match"`, and `durationChange: "reproved-after-edit"`; browser evidence still proves the real sampled frames.
+
+The test gate rejects rows unless the real Vitest and Playwright runners select exactly one product-owned test with the declared name and that test finishes passed. A matching name in a comment, string, local fake runner, focused/skipped test, conditional branch, or uncalled registration function is not execution evidence.
+
+The protected Vitest marker publishes the current automated requirements to the signed runner reporter, which evaluates actual selected test results instead of parsing test source. The signed full-test command fails when that marker is missing, duplicated, failed, invalid, or not framework-owned. User-visible browser behavior is proved at runtime: protected Playwright helpers attach versioned evidence after their assertion succeeds, and the signed reporter derives every required evidence id from `app-acceptance-data.ts`. A skipped/failed test, duplicate product test titles, a passed browser test without matching evidence, evidence from a failed retry, or a direct forged attachment fails its runner.
+
+`src/app/app-acceptance.ts`, `src/app/acceptance`, supplied `app-acceptance.*` meta-tests, and the generic browser acceptance harness are framework-owned and covered by the signed integrity manifest. Edit only `app-acceptance-data.ts` for product rows/readiness/inventory/transfer intent. Add product-specific automated tests in separate app-owned files and add browser scenarios to `e2e/app-controls.spec.ts` or new app-owned specs.
+
+The `e2e/app-browser-*` filename prefix is reserved for signed framework specs. Product browser tests use `app-controls.spec.ts` or a product-specific filename that does not start with `app-browser-`.
+
+The local contract docs under `docs/toolcraft` are also signed framework-owned input to this workflow. Do not rewrite them inside a generated app. `docs/toolcraft/agent-worklog.md` remains product-owned so each implementation pass can record current decisions and evidence.
 
-The test gate rejects rows without matching automated and browser test names.
+Framework meta-tests are product-invariant: their synthetic validator cases use protected neutral contract fixtures, never the editable app schema, product acceptance rows, transfer intent, or section inventory. Put exact product targets, defaults, option values, and product-specific expectations in separate app-owned tests. The product gates still read `app-schema.ts`, `app-acceptance-data.ts`, product test names, worklog evidence, and browser scenarios dynamically.
+
+The same ownership split applies to performance: edit `app-performance.ts`, but do not edit supplied `app-performance.*` meta-tests or `app-performance-test-utils.ts`. They are framework-owned and validate the editable product matrix.
 
 Slider and range slider rows must prove live behavior. Browser tests should drag the real thumb and assert the runtime value and product-level canvas observable update during the drag, not only after pointer release, blur, an Apply action, or a final commit. Performance-sensitive sliders still need this live acceptance; jank is handled through renderer optimization and targeted performance coverage, not by making the slider deferred by default.
 
@@ -122,6 +137,13 @@ Rows that use custom controls must include `customControlCoverage` and typed `bu
 
 ```ts
 builtInFitCheck: {
+  capabilities: [
+    "collection",
+    "reorder",
+    "selection",
+    "commands",
+    "custom-value-model",
+  ],
   checkedBuiltIns: ["fileDrop", "collectionActions", "imagePicker"],
   closestBuiltIn: "fileDrop",
   whyInsufficient:
@@ -131,7 +153,7 @@ builtInFitCheck: {
 }
 ```
 
-The fit check names real checked built-ins, the closest built-in or `"none"`, why it is insufficient, and the product-observable evidence that proves the custom control works.
+The fit check declares broad typed capabilities, names real checked built-ins, the closest built-in or `"none"`, why it is insufficient, and the product-observable evidence that proves the custom control works. At least one of `custom-interaction`, `custom-value-model`, or `custom-visualization` is required; collection/command chrome alone does not justify custom UI.
 
 For collection-like custom controls, the fit check must include `collectionActions` and `actions`. Collection-like is decided from the runtime value model and workflow: arrays, `{ items: [...] }` objects, selected-item state, grow/shrink item sets, ordering, add, remove, delete, or reorder behavior. Acceptance should fail if the row compares only unrelated built-ins such as `vector` or `select` while the actual value model is a collection.
 
@@ -167,6 +189,8 @@ Local `actions` acceptance must click every visible action and prove the nearby
 
 PNG export tests must prove runtime background behavior: changing the background color affects preview/export, turning `export.includeBackground` off hides the live preview product background and creates transparent PNG output, video export still keeps the background, turning Include on includes the current background color in PNG, and exported pixel dimensions are retina size, at least `state.canvas.size * 2`.
 
+Hard acceptance semantics are typed, not inferred from English prose. Every `visibleWhen` acceptance row declares `visibilityCoverage` for both `hidden` and `visible`; the protected conditional-visibility recipe must remove the dependent target from the rendered panel and restore it through the same target-scoped gating control. The `export.includeBackground` row declares `backgroundOutputCoverage` for preview exclusion and transparent image alpha, plus preserved video background when the schema exposes video export. Its protected recipe verifies the preview transition, decodes a non-empty image artifact and checks background alpha, and inspects video background behavior when applicable. `expectedObservable` and `userAction` remain human-readable context and may use any language; matching words such as “hidden”, “PNG”, or “video” never satisfy these requirements by themselves.
+
 Invalid final acceptance evidence:
 
 - control exists;
@@ -191,7 +215,13 @@ Every browser test should prove:
 - product output or command side effect changes;
 - canvas zoom, offset, and output dimensions do not jump unexpectedly.
 
-Acceptance rows with `product-output`, `rendered-pixels`, or `timeline-output` evidence must use `expectToolcraftProductObservableToChange` or explicit before/after snapshots from `getToolcraftProductObservableSnapshot` in `e2e/product-observable-helpers.ts`. Runtime state, selected labels, row counts, canvas existence, or generic hashes without the shared product observable helper are not final proof.
+Acceptance rows with `product-output`, `rendered-pixels`, or `timeline-output` evidence use protected `expectToolcraftProductObservableToChange` with the row `id` as `requirementId`. The generic `expectToolcraftAcceptanceOutcome` is intentionally limited to `command-side-effect`; it cannot emit media, persistence, viewport, layer, timeline, or compound-control evidence. Use `expectToolcraftMediaLifecycle`, `expectToolcraftPersistenceState`, and `expectToolcraftViewportSideEffect` for those state semantics. These recipes require an exact expected outcome after the real action and a bounded stability window; persistence additionally requires a real reload, media requires changed item ids plus product-output semantics, and viewport requires changed offset/zoom while output dimensions stay stable. Generic changed-output proof first samples a stable pre-action baseline. If the product output is autonomous or animated, pause/fix its phase or observe a stable expected semantic result; the next unrelated animation frame is not action evidence. A transient or merely different value is not proof. `getToolcraftProductObservableSnapshot` may establish a baseline, but a snapshot read alone is not mutation evidence. Product tests must not import the internal attachment recorder or reserved evidence contract directly or through product-owned bridges.
+
+Specialized state, layer, compound, and timeline recipes begin with `createToolcraftBrowserProofSession(page)`. Create observations with `session.observe(...)`, where the reader executes inside the current visible Toolcraft runtime root, and actions with `session.action(...)`; persistence uses `session.reload()` for the reload step. Raw callbacks, forged objects, stale pages, and observations/actions from different sessions are rejected before evidence is attached. This binds semantic evidence to the current app identity and browser DOM instead of allowing an in-memory object to impersonate product behavior.
+
+Exported-byte rows use `expectToolcraftExportedArtifact`. The action produces a non-empty artifact and the verifier returns a typed inspection with positive integer `byteLength`; decoded `width`, `height`, and `frameCount` are positive integers, `durationMs` is positive and finite, and `mediaType`/`contentHash` are non-empty strings when present. Missing/empty artifacts, void callbacks, `{ ok: true }`, fractional or zero-byte observations, and fractional decoded dimensions cannot emit evidence. Clean-export checks for canvas handles compare decoded product semantics through `contentHash` plus media metadata, not raw encoded bytes or file size, because two valid encoders may produce different bytes for the same output.
+
+Specialized metadata adds evidence for the same row: canvas handles prove drag and a separate clean-export test compares real exported artifacts with handles visible and hidden; segmented/discrete controls use their protected layout helpers; every declared compound-control part uses `expectToolcraftCompoundControlPartOutcome` and gets its own `row-id#part` evidence; layers use the fixed `expectToolcraftLayer*` recipes for selection, visibility, reorder, grouping, selected-layer controls, and media lifecycle; and reference parity uses `expectToolcraftReferenceParity` to compare the inspected result with the reference baseline. Playback uses the fixed `expectToolcraftTimeline*` recipes. Duration binds runtime duration and renderer cycle to the same expected value; scrub binds time to rendered output; pause/resume proves a stable paused window and resumed time/output; keyframes bind keyframe data, evaluated value, and output. Loop evidence requires normalized forward samples with exactly one end-to-start wrap, equal seam signatures, and the same proof again after changing duration. The reporter derives these requirements from acceptance plus schema; naming a helper in source or passing a desired evidence type to a generic helper is never proof.
 
 Animated viewport tests must also prove that canvas drag, pan, pinch, zoom, and radar/center interactions suspend or coalesce non-essential animation preview work without changing the user's play/pause state. After the interaction, the renderer must resume from the correct timeline or autonomous time and keep canvas zoom/offset stable.
 
@@ -243,7 +273,7 @@ Component variants are acceptance requirements.
 - Select, segmented, and image-picker controls should cover every visible option unless options come from separately tested runtime data.
 - Custom controls must declare `customControlCoverage` and `builtInFitCheck`. Coverage proves the custom control is not a built-in replacement, uses kit chrome, keeps only necessary UI, writes through runtime state, and changes product output; the fit check proves which built-ins were considered and why the custom interaction is necessary.
 
-Performance browser tests must assert budgets through `expectToolcraftScenarioPerformanceBudget(..., appPerformance, scenarioId)`. Workload browser tests must apply values from `getToolcraftPerformanceStressValue(appPerformance, scenarioId)`. If the scenario declares `workloadFixture`, apply it first with `getToolcraftPerformanceWorkloadValue` or `applyToolcraftPerformanceWorkloadFixture`. Do not hardcode budget numbers, toy control values, or toy baseline app states in e2e tests; `app-performance.ts` is the single source of truth.
+Performance browser tests pass `scenarioId` to protected measurement/interaction helpers and await `expectToolcraftScenarioPerformanceBudget(..., appPerformance, scenarioId)`. Every mutating measurement supplies `observeOutcome`; generic change evidence first proves a stable baseline and then requires the product outcome to remain different through the stability window. Autonomous products use `expectedOutcome` with a stable semantic observation or measure at a deterministic fixed phase. Latency ends at that expected result, never at an incidental animation frame. Scalar fixtures provide both `applyValue` and `observeValue`; object fixtures provide both functions for every exact fixture key, and the observed value must equal the declared fixture before measurement. Measurement results are immutable and branded to one scenario, so another scenario or a mutable literal cannot satisfy the gate. The reporter requires matching measurement, budget, fixture, interaction/completion, and product-outcome evidence for each typed scenario. Do not hardcode budget numbers, toy values, or toy baseline app states; `app-performance.ts` is the single source of truth.
 
 ## Fixtures