@pixel-point/toolcraft 0.0.18 → 0.0.19

package/templates/runtime/state/reducer-controls.test.ts

@@ -11,6 +11,51 @@ import { toolcraftReducer } from "./reducer";
 import { createState } from "./reducer-test-utils";
 
 describe("toolcraftReducer controls", () => {
+  it("canonicalizes Color writes before equality and history", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: false },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                fill: {
+                  defaultValue: "#112233",
+                  target: "shape.fill",
+                  type: "color",
+                },
+              },
+              title: "Appearance",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+    const seeded = createToolcraftState(schema, {
+      values: { "shape.fill": { hex: "#223344" } },
+    });
+    const changed = toolcraftReducer(seeded, {
+      label: "Fill",
+      target: "shape.fill",
+      type: "controls.setValue",
+      value: { hex: "#334455" },
+    });
+
+    expect(changed.values["shape.fill"]).toBe("#334455");
+    expect(changed.history.undo.at(-1)).toMatchObject({
+      after: { "shape.fill": "#334455" },
+      before: { "shape.fill": "#223344" },
+    });
+
+    const invalid = toolcraftReducer(changed, {
+      target: "shape.fill",
+      type: "controls.setValue",
+      value: { hex: "not-a-color" },
+    });
+    expect(invalid).toBe(changed);
+  });
+
   it("resets controls to defaults and records history", () => {
     const changed = toolcraftReducer(createState(), {
       target: "selectedLayer.opacity",

package/templates/runtime/state/reducer-media-reset.test.ts

@@ -42,7 +42,7 @@ describe("toolcraftReducer media reset", () => {
 
     expect(imported.mediaAssets).toHaveLength(1);
     expect(state.mediaAssets).toEqual([]);
-    expect(state.values["media.source"]).toBeNull();
+    expect(state.values["media.source"]).toBeUndefined();
     expect(undone.mediaAssets).toEqual(imported.mediaAssets);
     expect(redone.mediaAssets).toEqual([]);
     expect(state.history.undo.at(-1)).toMatchObject({

package/templates/runtime/state/reducer-timeline.test.ts

@@ -6,6 +6,76 @@ import { toolcraftReducer } from "./reducer";
 import { createState } from "./reducer-test-utils";
 
 describe("toolcraftReducer timeline", () => {
+  it("canonicalizes seeded and live Color keyframes", () => {
+    const app = defineToolcraft({
+      canvas: { enabled: false },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                fill: {
+                  defaultValue: "#112233",
+                  target: "shape.fill",
+                  type: "color",
+                },
+              },
+              title: "Appearance",
+            },
+          ],
+          title: "Controls",
+        },
+        timeline: { mode: "keyframes" },
+      },
+    });
+    const seeded = createToolcraftState(app, {
+      timeline: {
+        keyframeGroups: [
+          {
+            controlId: "shape.fill",
+            keyframes: [
+              {
+                controlId: "shape.fill",
+                controlLabel: "Fill",
+                id: "shape.fill::0",
+                timeSeconds: 0,
+                value: { hex: "#223344" },
+                valueLabel: "#223344",
+              },
+            ],
+            label: "Fill",
+          },
+        ],
+      },
+    });
+
+    expect(
+      seeded.timeline.keyframeGroups[0]?.keyframes[0]?.value,
+    ).toBe("#223344");
+
+    const changed = toolcraftReducer(seeded, {
+      controlId: "shape.fill",
+      controlLabel: "Fill",
+      timeSeconds: 1,
+      type: "timeline.upsertControlKeyframe",
+      value: { hex: "#334455" },
+      valueLabel: "#334455",
+    });
+    expect(
+      changed.timeline.keyframeGroups[0]?.keyframes.at(-1)?.value,
+    ).toBe("#334455");
+
+    const invalid = toolcraftReducer(changed, {
+      controlId: "shape.fill",
+      controlLabel: "Fill",
+      timeSeconds: 2,
+      type: "timeline.upsertControlKeyframe",
+      value: { hex: "invalid" },
+      valueLabel: "invalid",
+    });
+    expect(invalid).toBe(changed);
+  });
+
   it("updates timeline playback state without recording history", () => {
     const paused = toolcraftReducer(createState(), { type: "timeline.togglePlayback" });
     const loopDisabled = toolcraftReducer(paused, { type: "timeline.toggleLoop" });

package/templates/runtime/state/timeline-reducer.ts

@@ -1,4 +1,8 @@
 import { commitToolcraftStatePatch } from "./history-patches";
+import {
+  getToolcraftValueControls,
+  normalizeToolcraftControlValue,
+} from "./control-value-normalization";
 import {
   clampToolcraftTimelineDurationSeconds,
   clampToolcraftTimelineTime,
@@ -66,6 +70,22 @@ function createTimelineControlKeyframe({
   };
 }
 
+function normalizeTimelineControlValue(
+  state: ToolcraftState,
+  controlId: string,
+  value: unknown,
+): { accepted: true; value: unknown } | { accepted: false } {
+  const control = getToolcraftValueControls(state.schema).get(controlId);
+  if (!control) {
+    return { accepted: true, value };
+  }
+
+  const normalized = normalizeToolcraftControlValue(control, value);
+  return normalized.accepted
+    ? { accepted: true, value: normalized.value }
+    : { accepted: false };
+}
+
 function upsertTimelineControlKeyframeGroup({
   controlId,
   controlLabel,
@@ -289,12 +309,21 @@ export function reduceToolcraftTimelineCommand(
         });
       }
 
+      const normalized = normalizeTimelineControlValue(
+        state,
+        command.controlId,
+        command.value,
+      );
+      if (!normalized.accepted) {
+        return state;
+      }
+
       const keyframe = createTimelineControlKeyframe({
         controlId: command.controlId,
         controlLabel: command.controlLabel,
         state,
         timeSeconds: command.timeSeconds,
-        value: command.value,
+        value: normalized.value,
         valueLabel: command.valueLabel,
       });
       const timeline = {
@@ -317,12 +346,21 @@ export function reduceToolcraftTimelineCommand(
     }
 
     case "timeline.upsertControlKeyframe": {
+      const normalized = normalizeTimelineControlValue(
+        state,
+        command.controlId,
+        command.value,
+      );
+      if (!normalized.accepted) {
+        return state;
+      }
+
       const keyframe = createTimelineControlKeyframe({
         controlId: command.controlId,
         controlLabel: command.controlLabel,
         state,
         timeSeconds: command.timeSeconds,
-        value: command.value,
+        value: normalized.value,
         valueLabel: command.valueLabel,
       });
       const timeline = {

package/templates/runtime/testing/performance-schema-queries.ts

@@ -2,6 +2,7 @@ import type {
   ResolvedToolcraftAppSchema,
   ToolcraftControlSchema,
 } from "../schema/types";
+import { TOOLCRAFT_ARTIFACT_EXPORT_ACTION_ROLES } from "../schema/artifact-export-actions";
 import type { ToolcraftPerformanceValueSet } from "./performance-types";
 
 export function getAllSchemaControls(
@@ -122,8 +123,7 @@ function normalizeActionReference(value: string | undefined): string {
 const outputDeliveryActionRoles = new Set([
   "copy-output",
   "download-output",
-  "export-image",
-  "export-video",
+  ...TOOLCRAFT_ARTIFACT_EXPORT_ACTION_ROLES,
 ]);
 
 function isOutputDeliveryAction(

package/templates/starter/AGENTS.md

@@ -1,6 +1,6 @@
 # Toolcraft App Template Assembly Guide
 
-<!-- toolcraft-performance-lifecycle: first-delivery=functional; later-delivery=functional-targeted; complaint=one-authority-targeted-performance-iteration; full-audit=explicit-only -->
+<!-- toolcraft-performance-lifecycle: first-delivery=functional-complete; later-edits=focused-only; complaint=one-authority-targeted-performance-iteration; full-audit=explicit-only -->
 
 This is a standalone Toolcraft template app generated from the base starter.
 
@@ -14,29 +14,29 @@ Treat this `AGENTS.md` as the active project contract. Before planning or editin
 4. Read their Implementation phase immediately before editing code.
 5. Read their Verification phase before writing or running proof.
 
-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 one verification tier for the coherent user-visible delivery batch before implementation. Do not edit implementation files until the Plan and Implementation 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 one verification tier before first product delivery; for later edits record only the focused checks selected for the changed behavior. 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. The signed host owns `ToolcraftApp`, bootstrap, routes, global runtime styles, and the finite/infinite product scene surface; product code supplies only `ToolcraftAppComposition`. Infinite custom raster/WebGL output declares `sceneBoundsProvider` and consumes `useToolcraftProductSceneFrame` instead of dormant finite `canvas.size`. A preview-only environment that must fill the complete Infinity viewport uses `infiniteCanvasContent`; it remains pointer-transparent and outside world transforms, scene bounds, and export. Model upload preserves supported authored appearance from standalone files, folders, and bounded ZIP packages; declare typed `modelPresentation`, using runtime presentation by default and checked consumers for custom presentation. `renderDefaultCanvasMedia={false}` never hides runtime model layers. 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. Use `sourceCollection` when a source/runtime workflow owns array cardinality and users edit existing built-in item values; use `collectionActions` when users own add/remove cardinality. Before controls or canvas interactions, declare typed `interactionOwnership`: user request, inspected reference, or product usability selects one primary surface for each operation; complementary operations may share related state, but canvas and panel must not mirror the same operation. Every product also declares typed `viewInteraction` before renderer code; a visible editable spatial scene defaults to `orbit` and uses schema `orientationGizmo` plus runtime model-orbit interaction. Fixed or timeline-owned cameras require an explicit user request or inspected-reference evidence.
-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. Product code never imports modules below `src/toolcraft/ui/components/controls/**` or substitutes native `color`, `range`, `file`, `checkbox`, `radio`, `select`, or `textarea` value models for schema controls. Product artifact surfaces must correspond exactly to required `productReadiness.exportIntent`; use `docs/toolcraft/core/setup-export.md` for the canonical export decision sequence.
+4. Use built-in Toolcraft controls before custom controls. Built-in values have one canonical runtime representation across defaults, live edits, persistence, settings import, and keyframes; product code consumes that representation and never decodes component callback payloads. Use `sourceCollection` when a source/runtime workflow owns array cardinality and users edit existing built-in item values; use `collectionActions` when users own add/remove cardinality. Before controls or canvas interactions, declare typed `interactionOwnership`: user request, inspected reference, or product usability selects one primary surface for each operation; complementary operations may share related state, but canvas and panel must not mirror the same operation. Property edits declare `selectionScope` as global or selected-entity; selected-entity properties link to their selection owner and prove two-entity isolation. Every product also declares typed `viewInteraction` before renderer code; a visible editable spatial scene defaults to `orbit` and uses schema `orientationGizmo` plus runtime model-orbit interaction. Fixed or timeline-owned cameras require an explicit user request or inspected-reference evidence.
+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. Product code never imports modules below `src/toolcraft/ui/components/controls/**` or substitutes native `color`, `range`, `file`, `checkbox`, `radio`, `select`, or `textarea` value models for schema controls. Product artifact surfaces must correspond exactly to required `productReadiness.exportIntent`; SVG requests mean self-contained editable vectors and use runtime-owned `export-svg` plus `svgExportRenderer`, never raster bytes wrapped in SVG. Use `docs/toolcraft/core/setup-export.md` for the canonical export decision sequence.
 6. Before writing controls, export `starterControlSectionInventory`. Every product section declares stable `entityId`, human-readable `entity`, exact targets, and `groupingReason`. Every product control explicitly declares `applicability` as `always` or `conditional`; inactive branches are absent, and every visible finite sibling branch must prove the control's accepted product outcome. Keep one entity in one section through ten controls; sections with eight to ten controls declare `semanticGroup` on every control. Entities above ten controls split into balanced two-to-ten-control workflow stages that keep the same entity identity and declare unique `workflowStage` plus `splitReason`. Group by product meaning, never by UI component type or target namespace.
 7. Keep control `label` short but semantically sufficient with the nearest visible section/group context, and put product-specific behavior help in schema `description`; runtime renders the label help tooltip only when that description adds meaning beyond the label.
 8. Enable layers and timeline only when product behavior requires them, then test the real UI. Product animation loops are seamless forward-only by default: first and last frames stitch, direction does not reverse, and mirror/yoyo/ping-pong behavior requires explicit user intent.
 9. Animated preview renderers suspend or coalesce non-essential animation work during canvas drag, pan, pinch, zoom, and radar/center interactions, then resume without changing user playback state.
 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.
+11. For every supplied video, GIF, screen recording, contact sheet, or extracted-frame sequence, register one typed `referenceInputs` item and run `pnpm reference:study` before product code. Cover the dense evidence with complete phases, classify every detected event, map each behavior to acceptance plus browser `reference-parity`, and use `docs/toolcraft/core/reference-study.md` for the canonical command and evidence contract. Products without a motion reference declare `referenceInputs: []` and run no preprocessing.
 12. Runtime workspace persistence is enabled locally by default: values, canvas, and panels are the base plan, while enabled timeline, layers, and media add their slices. `{ storage: "none" }` is the only opt-out and requires a recorded reason. Test exact resolved slices through a real reload; product code never writes localStorage or IndexedDB directly.
 13. Generated apps follow the mandatory runtime Setup, Infinity canvas/finite 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. 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. Control applicability derives case-scoped presence/absence and product-outcome evidence from semantic section peers; background output keeps its fixed typed recipe. Raster products with `canvas.renderScale` declare `renderScaleCoverage` for interaction and steady state, plus playback when timeline is enabled, and prove real backing pixels with `canvas-render-scale-backing`; clamping quality is a functional failure without measured performance. Every measured path in a render-scale-enabled raster product proves actual CSS × devicePixelRatio × 2 backing after each measured phase. 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 planning follows one sequence: reachable controls and inputs; workload dimensions and enforced boundaries; pass cost, frequency, lifecycle, and invalidation; render-plan assessment and protected kernel benchmark when required; derived paths and combined fixtures; targeted functional/browser development checks; lifecycle-appropriate delivery proof. Keep `src/app/app-verification-impact.json` complete so later functional changes derive exact verification scope. Only exact request authority may create a measured targeted performance iteration. Details live in `docs/toolcraft/core/performance.md` and `docs/toolcraft/performance.md`.
+17. Performance planning follows one sequence: reachable controls and inputs; workload dimensions and enforced boundaries; pass cost, frequency, lifecycle, and invalidation; render-plan assessment and protected kernel benchmark when required; derived paths and combined fixtures; targeted functional/browser development checks; first-delivery proof or request-authorized performance proof. Only exact request authority may create a measured targeted performance iteration. Details live in `docs/toolcraft/core/performance.md` and `docs/toolcraft/performance.md`.
 18. Custom renderer apps compile one canonical `rendererPipelineRegistration`, supply it through `ToolcraftAppComposition`, reuse that registration as `rendererPipeline` in performance assessment, and derive paths and fixtures from it. The neutral starter has no registration, runtime provider, or fixture adapters.
-19. Classify each coherent user-visible delivery batch with a verification tier before editing. Steering and fixes inside the same request stay in that batch. Use targeted checks for development feedback, then run the protected delivery gate once when the batch is ready.
+19. Classify the first user-visible product delivery with a verification tier before editing and run the protected delivery gate once. After that first proof, ordinary edits use only the smallest feature-focused tests and browser checks; commit, push, deploy, preview, steering, and fixes do not create another aggregate delivery batch.
 
 ## Starter Baseline
 
@@ -75,7 +75,6 @@ Use this `AGENTS.md` as the entry contract. Use local docs for detail; the app m
 - 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.
-- Keep `src/app/app-verification-impact.json` aligned with every product production module, nearest acceptance coverage, and renderer pass. Classify presentation, functional, and performance ownership there; do not infer verification scope from filenames during a later iteration.
 - Use `e2e/app-kernel-benchmarks.ts` only for executable candidates required by `assessToolcraftRenderPlan`, then run protected `pnpm verify:kernel`. Do not put authored timing evidence in product files.
 - Do not paste, restore, or duplicate runtime validators inside `src/app/app-performance.ts`.
 - 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.
@@ -119,13 +118,13 @@ These ids mirror `TOOLCRAFT_DECISION_CONTRACT` in `@/toolcraft/runtime`. Keep th
 
 - Use `defineToolcraft` from `@/toolcraft/runtime`.
 - Export an `appComposition` satisfying `ToolcraftAppComposition` from `src/app/app-composition.tsx`.
-- Keep product composition limited to `schema`, `canvasContent`, `infiniteCanvasContent`, `controlRenderers`, `exportRenderer`, `sceneBoundsProvider`, `modelPresentation`, `onPanelAction`, `renderDefaultCanvasMedia`, and optional `rendererPipelineRegistration`; host `className` and `style` are not product extension points.
+- Keep product composition limited to `schema`, `canvasContent`, `infiniteCanvasContent`, `controlRenderers`, `exportRenderer`, `svgExportRenderer`, `sceneBoundsProvider`, `modelPresentation`, `onPanelAction`, `renderDefaultCanvasMedia`, and optional `rendererPipelineRegistration`; host `className` and `style` are not product extension points.
 - Infinite product output fills the runtime-owned scene surface derived from `sceneBoundsProvider`. Raster/WebGL renderers call `useToolcraftProductSceneFrame` for backing size and coordinate translation; they never position a second bounds wrapper or use dormant finite `canvas.size` while infinite.
 - Custom renderers use one compiled `rendererPipelineRegistration` as the canonical declaration for runtime execution and new-envelope performance assessment. Product code receives only the disposal-free pipeline client through hooks and panel action context.
 - Do not import `ToolcraftApp`, low-level runtime surfaces, built-in controls, or modules below `src/toolcraft/ui/components/controls/**` into product modules. Do not recreate schema control value models with native form elements. The signed host renders the shell; product modules use schema controls and supported composition fields.
 - Use `renderDefaultCanvasMedia={false}` when a custom renderer replaces generic image/file preview. This flag does not suppress runtime model layers; use typed `modelPresentation` custom mode with checked consumers for declared model targets.
-- Use `ToolcraftApp onPanelAction` for non-export sticky footer product actions such as Generate, Apply, Copy, or Download. Typed `export-image` and `export-video` actions are executed by the runtime from the shared `ToolcraftAppComposition.exportRenderer`.
-- Product export renderers draw one deterministic scene-coordinate frame and return/await their real work. Product modules never allocate export canvases, choose encoders, encode blobs, create download URLs, or duplicate image/video composition.
+- Use `ToolcraftApp onPanelAction` for non-export sticky footer product actions such as Generate, Apply, Copy, or Download. Typed `export-image` and `export-video` actions are executed by the runtime from `ToolcraftAppComposition.exportRenderer`; typed `export-svg` is executed from `svgExportRenderer`.
+- Product export renderers draw one deterministic scene-coordinate frame or append namespace-aware vector nodes and return/await their real work. Product modules never allocate export canvases/documents, choose encoders, serialize SVG, encode blobs, create download URLs, or duplicate runtime artifact composition.
 - Keep final app behavior in the schema and runtime command bus, not in isolated local control state.
 - For animated products, write an Animation Intent Inventory before coding: use top playback timeline for product transport, keyframes timeline for editable property animation, and no timeline only for explicitly autonomous decorative output with no video export. Any app with `Export Video` must enable the top Toolcraft timeline.
 - For keyframes timeline apps, renderers read keyframed settings through Toolcraft evaluated-value helpers/hooks. Do not parse timeline `valueLabel` strings or read raw `state.values` for keyframed targets.
@@ -151,7 +150,7 @@ The signed local `AGENTS.md` and `docs/toolcraft/*` files are the mandatory work
 
 ## Verification Tier Classifier
 
-Before editing, write one short verification note for the coherent delivery batch:
+Before first delivery, write one short verification note. For later edits, use the same shape but list only directly relevant focused checks:
 
 ```md
 Verification tier: Tier N
@@ -166,30 +165,30 @@ Choose the tier by blast radius, not by line count. If uncertain, move one tier
 | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Tier 0 — docs/copy                            | Documentation, comments, copy, labels, or titles change without schema targets, values, runtime behavior, renderer output, or layout mechanics.                                                                                                                                                | Targeted docs/typecheck or targeted app test. Browser is not required unless visual text fitting is the risk.                                                                                                                                                                                                                                                          |
 | 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.                                                                                                                                                                | During development run relevant targeted tests and browser acceptance. At delivery, bare `pnpm verify:delivery` derives the required proof.                                                                                                                                                                                                                             |
-| 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.                     | During development run targeted functional and browser acceptance checks. The tier and changed surface do not authorize measured performance. At delivery, `verify:delivery` runs ownership-derived functional proof unless exact request authority creates one performance iteration.                                                                                                                                                                                                 |
-| 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. Run `pnpm verify:delivery` once when the coherent batch is ready, then start `pnpm dev`. Its protected lifecycle selects functional proof or an exact targeted performance iteration from the request and prior receipt state.                                                                                                                     |
+| Tier 2 — schema/product behavior              | Controls, sections, defaults, persistence, panel actions, export actions, acceptance rows, or product behavior mapping changes.                                                                                                                                                                | During development run relevant targeted tests and browser acceptance. Run bare `pnpm verify:delivery` only when this is part of the first product delivery. Later edits stop after the focused checks pass.                                                                                                                                                              |
+| 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.                     | Run targeted functional and browser acceptance checks for the changed behavior. The tier and changed surface do not authorize measured performance. Run the protected delivery gate only for first product delivery or exact request-authorized performance work.                                                                                                      |
+| Tier 4 — first delivery/template architecture | Fresh generated app completion, folder export, dependency changes, runtime/template/contract/CLI changes, or broad first-product implementation.                                                                                                                                              | Fresh folders run `pnpm install` once. Run `pnpm verify:delivery` once when the first product version is ready, then start `pnpm dev`. Later broad edits still use explicit focused checks for the affected features unless the user authorizes performance work or a full audit.                                                                                         |
 
 Do not rerun `pnpm install` after every edit. Run it after fresh export, dependency changes, lockfile changes, or a missing package error.
 
 Do not run the full browser performance suite for Tier 0-2 edits.
 
-The automatic lifecycle is sequential. First product delivery uses bare `pnpm verify:delivery` for complete product contracts, one production build, full functional acceptance, and zero measured performance. Later delivery is functional-targeted: it compares the immediately previous and current semantic functional proof models and derives exact direct-owner, domain, and affected-unit-graph proof. Classifier output establishes complaint authority only, never path localization. For a localized performance complaint, select affected canonical paths and run one targeted iteration without clarification. When localization remains unresolved, regardless of whether classification is high-confidence `performance-iteration` or `needs-agent-judgment`, ask one user-facing question naming visible operations and offering targeted diagnosis or a complete review; unresolved localization creates neither performance-iteration intent nor canonical path authority, and internal path IDs are never user choices. A broad or unlocalizable problem may justify recommending the complete review in that single choice, but the user still chooses; an explicit complete-review request runs `pnpm verify:perf` directly. The canonical selection and evidence rules live in `docs/toolcraft/workflow.md`, `docs/toolcraft/acceptance-testing.md`, and `docs/toolcraft/performance.md`; do not duplicate their algorithm here.
+The automatic lifecycle is sequential. First product delivery uses bare `pnpm verify:delivery` for complete product contracts, one production build, full functional acceptance, and zero measured performance. Once its receipt exists, ordinary edits run only the smallest tests and browser checks for the feature being changed. A repeated bare `verify:delivery` exits before inventory, build, tests, export, and performance work and preserves the initial receipt. Classifier output establishes complaint authority only, never path localization. For a localized performance complaint, select affected canonical paths and run one targeted iteration without clarification. When localization remains unresolved, regardless of whether classification is high-confidence `performance-iteration` or `needs-agent-judgment`, ask one user-facing question naming visible operations and offering targeted diagnosis or a complete review; unresolved localization creates neither performance-iteration intent nor canonical path authority, and internal path IDs are never user choices. A broad or unlocalizable problem may justify recommending the complete review in that single choice, but the user still chooses; an explicit complete-review request runs `pnpm verify:perf` directly. The canonical selection and evidence rules live in `docs/toolcraft/workflow.md`, `docs/toolcraft/acceptance-testing.md`, and `docs/toolcraft/performance.md`; do not duplicate their algorithm here.
 
-Feature loops after the first working version run only the smallest focused functional and browser checks while implementation is changing, then one bare `verify:delivery` at the coherent boundary. Do not rerun aggregate, export, or performance matrices after every edit. An unchanged `sourceHash` uses the protected fast path and does not recollect semantic proof inputs.
+Feature loops after the first working version run the exact unit/component test for the edited implementation, then `pnpm test:feature -- <acceptance-id>` for its product behavior. The command automatically expands finite-selector edits through current schema applicability to affected acceptance peers; leaf edits stay one browser scenario. Use explicit `pnpm test:feature -- --all` only for a genuinely cross-cutting functional edit that cannot be bounded to acceptance IDs. Both paths use the current-source development server and run product acceptance only—never build, delivery, export matrices, framework self-tests, or measured performance. A repeated bare `verify:delivery` proves only that the initial receipt already exists and does not recollect semantic proof inputs.
 
-The app is not complete until bare `pnpm verify:delivery` produces the lifecycle-appropriate protected receipt. An initial functional receipt proves complete functional acceptance without measured performance; later functional receipts prove exact ownership-derived checks. Agent-controlled browser checks remain useful for targeted diagnosis and visual verification, but terminal prose cannot mint or upgrade a receipt. The impact inventory derives the required checks and affected passes from the immediately previous successful delivery. Tier is human diagnostic vocabulary only and never grants execution authority.
+The first product version is not complete until bare `pnpm verify:delivery` produces the protected initial receipt. Later feature work is complete when its directly relevant tests and browser checks pass; it does not mint another functional delivery receipt. Agent-controlled browser checks remain useful for targeted diagnosis and visual verification, but terminal prose cannot mint or upgrade performance evidence. Tier is human diagnostic vocabulary only and never grants performance execution authority.
 
 ## Required Checks
 
-For a coherent delivery batch, run:
+For the first product delivery, run:
 
 ```bash
 pnpm verify:delivery
 pnpm dev
 ```
 
-The protected runner selects first-delivery functional proof, later `functional-targeted` ownership-derived proof, or one localized-or-clarified targeted performance iteration from protected state. Classifier output alone never supplies path localization; unresolved localization creates neither performance-iteration intent nor canonical path authority regardless of classifier result. `pnpm verify:perf` is the separate operator/CI full-audit command; run it only after an explicit user request or accepted agent offer, never as an inferred continuation of a complaint.
+The protected runner selects first-delivery functional proof, one localized-or-clarified targeted performance iteration, or the proven-product no-op. Ordinary later edits do not run it as a final gate. Classifier output alone never supplies path localization; unresolved localization creates neither performance-iteration intent nor canonical path authority regardless of classifier result. `pnpm verify:perf` is the separate operator/CI full-audit command; run it only after an explicit user request or accepted agent offer, never as an inferred continuation of a complaint.
 
 Use `pnpm install` before this final gate when the folder is fresh or dependencies changed.
 
@@ -208,11 +207,11 @@ The app is complete only when:
 - every product control declares explicit applicability, every non-matching finite branch hides it, and every visible finite branch proves product output or the accepted command side effect;
 - reset returns schema controls to `defaultValue`;
 - sticky footer export actions operate on final product output at `state.canvas.size`;
-- artifact actions and settings correspond exactly to `productReadiness.exportIntent`; image export is the product default, video requires explicit user-request evidence, and image removal requires explicit user-removal evidence;
+- artifact actions and settings correspond exactly to `productReadiness.exportIntent`; image export is the product default, SVG/video require explicit user-request evidence, and image removal requires explicit user-removal evidence;
 - PNG export uses the background controls normalized into runtime Setup: `Background` beside `Infinity canvas`, then `Background color`; live preview hides product background when Background is off, and video keeps background;
 - every PNG export includes `Image Export` format/resolution `select` controls; runtime resolves the selected settings and exact output size;
 - products with both PNG and video export place `Image Export` immediately before `Video Export`;
-- one shared `exportRenderer` draws product pixels for both image and video; runtime owns selected settings, scene crop, background, runtime media/model compositing, canvas allocation, encoding, download, progress, and typed errors;
+- one shared `exportRenderer` draws product pixels for image/video and a separate `svgExportRenderer` appends editable vector content for SVG; runtime owns settings, scene crop, background, document/canvas allocation, validation, encoding/serialization, download, progress, and typed errors;
 - layers are absent for single-layer apps and fully working when enabled;
 - timeline is absent, playback, keyframes, or custom reference timeline according to product behavior;
 - performance checks cover workload and responsiveness for all relevant controls;

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

@@ -11,7 +11,7 @@ The starter app itself is intentionally neutral. It should show the Toolcraft ca
 `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/setup-export.md` — required Setup, canvas sizing, render scale, Timeline switch, Background, Image/SVG/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.
@@ -32,14 +32,14 @@ The broad docs below remain supplementary topic references. They do not replace
 9. `agent-worklog.md` — implementation decision trail, evidence, verification, and risks.
 10. `custom-controls.md` — how to register custom controls without editing `src/toolcraft`.
 
-`agent-worklog.md` starts as a neutral starter template. Once the folder becomes a product, change it to `Mode: product`, add one `Decision Trail` entry per coherent user-visible delivery batch, and record concrete renderer, timeline, layers, controls, export, and performance decisions. Each batch keeps human intent: request, user-visible result, source/reference checked, contract rules applied, rejected alternatives, state/output mapping, known risks, and domain-shaped performance authority when applicable. Protected receipts own changed files, the plan, executed checks, reports, measurements, and pass/fail evidence. The delivery gate fails if this worklog is missing, stale, or lacks required decision-trail intent.
+`agent-worklog.md` starts as a neutral starter template. Once the folder becomes a product, change it to `Mode: product`, add one `Decision Trail` entry per coherent user request, and record concrete renderer, timeline, layers, controls, export, and performance decisions. Each entry keeps human intent: request, user-visible result, source/reference checked, contract rules applied, rejected alternatives, state/output mapping, known risks, and domain-shaped performance authority when applicable. The first delivery receipt owns its complete plan and evidence; later entries record the focused checks actually run.
 
-Use focused tests while a coherent user-visible delivery batch is changing. Steering and fixes inside the same request stay in that batch; protected delivery runs once after it stabilizes.
+Use focused tests while implementation is changing. Protected functional delivery runs once for the first product version; steering and later fixes do not create another aggregate gate.
 
 ## Automatic Delivery Lifecycle
 
 - **First product delivery:** bare `pnpm verify:delivery` proves complete product contracts, performs one production build, runs full functional acceptance, and runs no measured performance. It preserves any independent performance baseline.
-- **Later functional delivery:** the same bare command compares with the immediately previous successful delivery and derives exact ownership-required proof.
+- **Later ordinary edits:** run only directly relevant feature tests and browser checks. A repeated bare command is a protected no-op that preserves the initial receipt.
 - **Localized or clarified targeted work:** classifier output establishes complaint authority only and never path localization. Only a localized complaint or a post-clarification targeted choice records an exact request quote and canonical affected path IDs in the worklog, then one bare delivery runs one targeted iteration and returns the verified app for evaluation. Unresolved localization creates neither performance-iteration intent nor canonical path authority regardless of classifier result.
 - **Adaptive complaint route:** a localized complaint lets the agent choose affected paths without a question; an ambiguous complaint gets one visible-operation choice between targeted diagnosis and a complete performance review; a broad problem may receive the same recommendation, while only an explicit request or accepted offer authorizes the full review.
 - **Full audit:** only an explicit operator request or accepted offer authorizes `pnpm verify:perf`, which performs one fresh build and the complete maximum-fixture performance matrix.
@@ -48,9 +48,9 @@ Use the current AI agent's controlled browser for targeted diagnosis and visual
 
 Performance workload limits come from reachable schema and enforced runtime/input boundaries. Targeted development and performance iterations use compiled development fixtures; operator full certification proves the applicable maximum without reducing selected quality or silently narrowing the product range.
 
-The app is not delivered until `pnpm verify:delivery` records a protected delivery receipt. Functional delivery creates no measured performance claim; later deliveries use impact-derived current-source coverage. Filename, diagnostic classification, and touched subsystem never force the full audit. Protected receipts own the plan, executed checks, reports, measurements, and pass/fail evidence.
+The first product version is not delivered until `pnpm verify:delivery` records its protected initial receipt. Later edits complete through directly relevant focused checks and do not mint another functional receipt. Filename, diagnostic classification, and touched subsystem never force the full audit. Protected receipts own initial and performance plans, reports, measurements, and pass/fail evidence.
 
-Fresh folders or dependency changes need `pnpm install` before verification. Final delivery still starts the local app after the gate:
+Fresh folders or dependency changes need `pnpm install` before verification. First delivery starts the local app after the gate:
 
 ```bash
 pnpm verify:delivery

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

@@ -9,7 +9,6 @@ Every visible product entity must prove it works. A control is not accepted beca
 - `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-verification-impact.json` (presentation, functional, and performance ownership with nearest acceptance ids and exact performance pass ids)
 - `src/app/app-performance.test.ts`
 - `docs/toolcraft/agent-worklog.md`
 - `e2e/app-browser-acceptance.spec.ts`
@@ -18,7 +17,7 @@ Every visible product entity must prove it works. A control is not accepted beca
 - `e2e/app-kernel-benchmarks.ts`
 - `e2e/product-observable-helpers.ts`
 
-Use focused checks during edits. First delivery and later delivery run bare `pnpm verify:delivery` per `workflow.md`. Performance complaint authority adds an iteration; explicit full audit authority permits `pnpm verify:perf`.
+First delivery runs bare `pnpm verify:delivery` once. Later edits run an exact unit/component test and `pnpm test:feature -- <acceptance-id>`: finite selectors expand to affected acceptance peers, while leaf IDs stay one browser scenario. Use `pnpm test:feature -- --all` only for a cross-cutting edit; it still runs product acceptance only. Repeated delivery is a protected no-op. Performance complaint authority adds one targeted iteration; explicit full-audit authority permits `pnpm verify:perf`.
 
 ## Product Readiness
 
@@ -30,7 +29,7 @@ The exported starter may keep `appProductReadiness.mode: "starter"` only while i
 - required `exportIntent`;
 - `viewInteraction`.
 
-`productReadiness.exportIntent` is the typed authority for artifact delivery. Acceptance, schema actions, and export settings must correspond exactly to its resolved image and video capabilities. The evidence-bearing modes and decision sequence live in `core/setup-export.md`; do not infer export intent from animation or timeline state.
+`productReadiness.exportIntent` owns artifact delivery. Acceptance, actions, and applicable settings must match its image, SVG, and video capabilities. SVG has no settings section and means self-contained editable vectors. See `core/setup-export.md`; never infer intent from renderer technology, animation, or timeline state.
 
 `viewInteraction` classifies the product as `non-spatial`, `orbit`,
 `fixed-camera`, or `timeline-camera`. Editable spatial scenes default to orbit;
@@ -40,7 +39,7 @@ Product readiness also requires product surface: controls, layers, timeline, `ca
 
 ## Implementation Worklog
 
-Product apps must update `docs/toolcraft/agent-worklog.md` before final delivery. The file records why the app chose its renderer, view interaction mode, timeline mode, layer policy, control grouping, export behavior, and performance strategy.
+Product apps must update `docs/toolcraft/agent-worklog.md` before first delivery and when later decisions materially change. The file records why the app chose its renderer, view interaction mode, timeline mode, layer policy, control grouping, export behavior, and performance strategy.
 
 The worklog must declare `Mode: product`. Every `Decision Trail` records human intent: `Request:`, `Task type:`, `User-visible result:`, `Source/reference checked:`, `Reference inputs:`, `Docs/contracts read:`, `Contract rules applied:`, `View interaction intent:`, `Interaction ownership:`, `Decision:`, `Alternatives rejected:`, `State/output mapping:`, `Performance intent:`, bare-delivery `Verification:`, and `Risks:`. Steering within one request stays in that batch. `Reference inputs:` lists every prompt/reference asset or `None`; `State/output mapping:` connects state to visible output or export.
 
@@ -81,9 +80,9 @@ Protected Vitest and Playwright reporters evaluate passed runner results plus ma
 
 The `e2e/app-browser-*` prefix is reserved for signed framework specs.
 
-## Semantic Proof Ownership
+## Proof Boundaries
 
-Every runtime production module/resource has a direct owner in `src/app/app-verification-impact.json`; proof and test paths cannot own them. Each browser file owns one acceptance domain (the first ID segment). Later delivery compares semantic models and selects changed contracts, owners/domains, and product-unit tests—not filenames or reverse imports. Additive owner deltas select only new IDs; other deltas retain affected IDs.
+First delivery proves the complete acceptance catalog. Later ordinary edits do not derive an aggregate proof model or infer from changed files: run the exact product test, then pass its acceptance ID to `test:feature`. Semantic closure reuses current applicability cases; the existing reporter still requires each selected branch, layout, and product outcome. Invalid IDs, titles, or plans fail before browser startup. The development server tests current source instead of stale build output. A repeated bare `verify:delivery` neither discovers nor runs these checks.
 
 Classifier output establishes complaint authority only; unresolved localization creates no intent/path regardless of result. Only localized/clarified work starts an iteration.
 
@@ -91,7 +90,7 @@ Contract docs are signed except product-owned `agent-worklog.md` and optional `w
 
 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`, `app-verification-impact.json`, product performance path adapters, and the kernel candidate harness when assessment requires it. Do not edit supplied `app-performance.*` meta-tests, protected reporters, receipt writers, or `app-performance-test-utils.ts`; they validate product inputs and own execution evidence.
+For performance work, edit `app-performance.ts`, product performance path adapters, and the kernel candidate harness when assessment requires it. Do not edit supplied `app-performance.*` meta-tests, protected reporters, receipt writers, or `app-performance-test-utils.ts`; they validate product inputs and own execution evidence.
 
 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.
 
@@ -179,7 +178,7 @@ High-confidence wrong-substitution cases:
 
 ## Interaction Ownership Evidence
 
-Product readiness declares `interactionOwnership`. Canvas handles, custom interactions, and panel controls sharing a canvas target bind `interactionId`. Acceptance rejects one id on both surfaces, renamed copies of the same target/capability, bad links, or choices lacking evidence and an alternate-surface reason. Distinct capabilities may share state across surfaces and are proved separately.
+`interactionOwnership` gives each operation one surface; linked canvas/panel operations must be complementary, not renamed copies. Property edits declare global or selected `selectionScope`; selected properties name a selection owner and `selectionScopeCoverage: "two-entity-isolation"`. Protected Canvas/Panel pixels prove selection is inert, editing A changes only A, editing B changes only B, and the control rebinds. `selectedLayer.*` reuses this recipe; whole-canvas/signature/direct-command proof is invalid.
 
 `fileDrop` rows prove upload/admission, clear/remove, reset/default restoration, and binary/model lifecycle. Without Layers ownership they also prove image rotate/flip and `multiple` reorder. With `panels.layers` and typed media-management ownership, omit those claims from `fileDrop`: runtime `layerCoverage: "reorder"` and `"selected-layer-controls"` rows prove order and selected-transform output. Clear-only proof is invalid; Reset restores defaults or removes uploaded media.
 
@@ -203,7 +202,7 @@ Custom controls cannot be justified by icons, layout, styling, compactness, or c
 Valid acceptance evidence includes:
 
 - rendered product pixels;
-- exported image/video bytes;
+- exported image/SVG/video bytes;
 - canvas hash or DOM-visible product result;
 - clipboard, file, or blob payload;
 - cleared media preview and canvas;
@@ -212,7 +211,7 @@ Valid acceptance evidence includes:
 - changed timeline playback state plus rendered frame.
 - restored persisted value or product output after browser reload.
 
-Product apps include artifact acceptance only for the delivery enabled by `productReadiness.exportIntent`. Image-only products prove complete image coverage; image-plus-video products prove both; video-only products prove complete video coverage; explicit no-export products have no image/video artifact rows. Timeline playback, keyframes, or animation never add video acceptance. Clipboard copy can be tested as an additional behavior, but it cannot substitute for the recorded artifact intent.
+Artifact acceptance follows `productReadiness.exportIntent`. Image/video use complete artifact coverage; requested SVG adds `all-required-svg-export-behavior` and protected exact-download vector proof. Explicit no-export products have no artifact rows. Renderer technology never adds SVG, and timeline behavior never adds video. Clipboard proof cannot replace recorded artifact intent.
 
 Export-content proof is distinct from export mechanics: content inspects selected artifact semantics; mechanics proves lifecycle, format, dimensions, transport, and errors. Neither substitutes.
 
@@ -268,16 +267,17 @@ Animated viewport tests must also prove that canvas drag, pan, pinch, zoom, and
 
 ## Video References
 
-When a video, GIF, screen recording, contact sheet, or extracted-frame sequence is used as a reference, acceptance is driven by `starterTransferMode.videoReferenceStudy`.
-
-- `storyboard` records timecoded frames with visible state and behavior observations;
-- `transitionAnalysis` records frame-to-frame deltas, not only isolated frame descriptions;
-- `behaviorDecomposition` states which observed behaviors must be copied;
-- `acceptanceMapping` maps each observed video behavior to a real acceptance row;
-- mapped acceptance rows must be automated, browser-backed, and observable in product output, timeline output, export output, or a real command side effect;
-- `agent-worklog.md` records Video Reference Study evidence when `Reference inputs`, `Source/reference checked`, or `Source reviewed` cites video, GIF, screen recording, contact sheet, or extracted frames.
-
-Do not accept a video reference implementation proved only by a single screenshot, a visual summary, generic canvas hashes, or static style checks.
+When a video, GIF, screen recording, contact sheet, or extracted-frame sequence
+is used as a reference, acceptance is driven by typed
+`starterTransferMode.referenceInputs`. Each authored behavior points to one
+observable acceptance row, and that row owns the exact reverse
+`motionReferenceCoverage` pair plus browser `reference-parity` evidence. The
+semantic validator requires complete phases and exactly one classification for
+every detected event. Follow `core/reference-study.md` for preprocessing,
+sampling, artifacts, timing, worklog records, and the no-reference fast path.
+
+Do not accept a motion-reference implementation proved only by a single
+screenshot, a visual summary, generic canvas hashes, or static style checks.
 
 ## Reference Clone