@pixel-point/toolcraft 0.0.16 → 0.0.18

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

@@ -26,7 +26,8 @@ export const TOOLCRAFT_RUNTIME_COMPONENT_CONTRACTS = {
       "Infinity canvas removes finite artboard bounds and clipping, hides Aspect ratio, Canvas width, and Canvas height, and preserves the dormant finite canvas size for exact restoration when disabled.",
       "Infinity canvas suppresses the bounded product-rendered preview background so the dormant finite output does not appear as a second canvas; when the standard Background pair is enabled, CanvasShell fills the complete infinite viewport with the selected Background color.",
       "When the standard Background pair exists, disabling Background atomically restores finite mode and disables Infinity canvas; re-enabling Background restores switch availability without enabling Infinity automatically.",
-      "Infinite exports use canonical world-space scene frames: ToolcraftAppComposition.sceneBoundsProvider contributes product bounds, runtime image and model bounds are unioned once, hidden or suppressed content is excluded, PNG crops tightly, and video uses one time-range envelope.",
+      "Infinite exports use canonical world-space scene frames: ToolcraftAppComposition.sceneBoundsProvider contributes exact-state product bounds, runtime image and model bounds are unioned, hidden or suppressed content is excluded, PNG crops tightly, and runtime video unions every scheduled frame state into one envelope.",
+      "Infinite live preview uses that same exact-state product frame: runtime positions one product scene surface from sceneBoundsProvider, and custom raster/WebGL output consumes useToolcraftProductSceneFrame for backing size and world-to-local translation instead of dormant canvas.size.",
       "Do not let canvas.upload choose intrinsic-media by default. Upload without explicit sizing resolves to editable-output so source/background images do not own product output size.",
       "Use intrinsic-media only for true media-viewer or source-native apps where the natural uploaded/generated media size is the product output; record the reason and prove it with intrinsic-media-size acceptance.",
       "Use editable-output for generated, exportable, shader, poster, badge, wall, banner, thumbnail, procedural, reference-clone, and product-output apps so users always see Aspect ratio, Canvas width, and Canvas height.",
@@ -104,6 +105,7 @@ export const TOOLCRAFT_RUNTIME_COMPONENT_CONTRACTS = {
       runtimeSetupModeRowRule,
       runtimeSetupModeHelpRule,
       "Keep sticky footer panelActions for product delivery actions only, such as Export PNG, Export Video, Copy, Generate, Apply, or Download.",
+      "Typed Export PNG and Export Video actions are runtime-owned and consume one ToolcraftAppComposition.exportRenderer; use onPanelAction only for non-export product actions.",
     ],
     capabilities: ["settings-import-export"],
     commands: ["controls.setValue", "timeline.setCurrentTime", "timeline.setDuration"],
@@ -126,11 +128,12 @@ export const TOOLCRAFT_RUNTIME_COMPONENT_CONTRACTS = {
       "A generic canvas hash difference is not enough for workload or semantic controls; assert the intended direction of the effect.",
       "Component variants are accepted entities too; tests should fail if a non-default Toolcraft control variant falls back to the default variant or custom markup.",
       "Conditional entities require fixtures that make the condition observable.",
-      "Use visibleWhen for mode-, type-, source-, include-, variant-, or count-exclusive sections or controls that do not belong to the current selected state.",
-      "When visibleWhen references a selector for the same product entity or selected branch, keep the selector and its dependent controls in one semantic section. A section that exists only because one selector option is active is not a separate product section just because the branch uses a standalone control.",
-      "When a count/quantity control determines how many sibling controls are available, hide unavailable siblings with visibleWhen; do not render all possible controls while the renderer reads only the first N.",
-      "If a switch/select/segmented/tabs/imagePicker/checkbox chooses a branch for the same product entity, controls outside the current branch use visibleWhen, not disabledWhen.",
-      "Do not use schema disabled: true or disabledWhen for generated product controls; the panel should show only controls usable in the current state. Runtime primitives may still have disabled styling internally, but app schemas should model product availability with visibleWhen.",
+      'Every generated product control declares applicability as mode: "always" or mode: "conditional"; omitted applicability and legacy visibleWhen are runtime compatibility only and fail starter acceptance.',
+      "Conditional applicability combines every predicate with AND, hides controls outside mode/type/source/include/variant/count branches, and preserves their runtime values while hidden.",
+      "A visible product control must prove its existing product outcome in every supported finite sibling-selector branch from its Control Section Inventory, including always controls and selectors omitted from its predicates.",
+      "When applicability references a selector for the same product entity or selected branch, keep the selector and its dependent controls in one semantic section. A section that exists only because one selector option is active is not a separate product section just because the branch uses a standalone control.",
+      "When a count/quantity control determines how many sibling controls are applicable, conditional applicability hides unavailable siblings; do not render all possible controls while the renderer reads only the first N.",
+      "Do not use schema disabled: true or disabledWhen for generated product availability; runtime primitives may use disabled styling internally, but product controls outside the active branch are absent.",
       "Do not leave inactive conditional controls visible while making the renderer ignore them.",
       "Before controls or canvas interactions, declare typed interactionOwnership for every operation that could plausibly live on either surface. User request, inspected reference, or product usability selects one primary owner.",
       "Do not mirror one operation across canvas and panel, even with different labels, ids, styling, or custom chrome. The same target and operation capability has one surface owner.",
@@ -237,9 +240,10 @@ export const TOOLCRAFT_RUNTIME_COMPONENT_CONTRACTS = {
       "A concise property label such as Speed, Color, Size, or Opacity is allowed when the nearest visible section or group clearly names the affected product entity.",
       "When the section is generic, mixed, missing, or otherwise weak context, include the affected entity or role in the label: Pattern color, Background opacity, Wave speed, Stroke width.",
       "Acceptance validators suggest semantic replacement labels for weak generic labels; fix the schema label instead of relying on runtime fallback rewriting.",
-      "Controls-panel sections should stay discrete: two to seven product controls is the normal size, and larger sections must split by product sub-entity or workflow stage.",
-      "Generated product apps must export starterControlSectionInventory beside acceptance. Every product controls section declares title, exact targets, groupingReason, and entity or workflowStage; intentional splits of one target entity require workflowStage and splitReason on every split section.",
-      "Section splitting must preserve dependency cohesion: a selector stays with the visibleWhen controls it gates when they share the same target entity or selected branch. Use internal spacing/dividers or a more specific section title before splitting dependent branch controls away.",
+      "One to seven controls is the normal section size. Eight to ten controls are allowed only for one cohesive entity and require semanticGroup on every control; ten is the hard maximum.",
+      "Every Control Section Inventory entry declares required entityId, entity, exact targets, and groupingReason. One entity with ten or fewer controls stays in one section regardless of control type, visual height, or target namespace.",
+      "An entity above ten controls splits into balanced workflow sections of two to ten controls. Every split section keeps the same entityId and entity and declares a unique workflowStage plus splitReason.",
+      "Section splitting must preserve dependency cohesion: a selector stays with the applicability-gated controls it owns when they share the same target entity or selected branch. Use internal spacing/dividers or a more specific section title before splitting dependent branch controls away.",
       "Every app-authored controls-panel body section must have a short meaningful visible title. Runtime-created Setup renders as the first visible headerless controls block with no title, reset action, collapse button, or collapsed state; sticky footer action sections use the technical title Export but render without a visible heading.",
       "Every visible app-authored controls-panel section title renders through the standard 36px collapsible header row with vertically centered text and the runtime collapse icon; generated apps must not hand-build section headers.",
       "Controls-panel section expand and collapse uses the standard runtime height/opacity animation; generated apps must not replace it with instant custom section visibility.",
@@ -318,13 +322,14 @@ export const TOOLCRAFT_RUNTIME_COMPONENT_CONTRACTS = {
       "Before choosing no timeline for any animated product, write an Animation Intent Inventory: product transport, editable keyframes, or autonomous decorative output, plus the user-facing time behaviors present or intentionally absent.",
       'User-requested product animation defaults to panels.timeline mode "playback" unless the spec explicitly declares autonomous decorative/self-running output with no play, pause, scrub, duration, loop, export-at-time behavior, or video export.',
       'Any product app with Export Video must enable the top Toolcraft timeline: use panels.timeline mode "playback" for product animation transport, or mode "keyframes" when exported animation is driven by keyframes.',
+      'Export Video is valid only when productReadiness.exportIntent.video is "user-requested" with non-empty explicit user-request evidence; animation, playback, keyframes, and timeline presence never authorize video export.',
       'Use panels.timeline: { mode: "playback" } when the product needs user-facing play, pause, scrubbing, duration, loop, restart, time progress, export-at-time controls, or video export.',
       'When panels.timeline is enabled for a new Toolcraft app, appTransferMode.animationIntent must match it: mode "timeline-playback" for playback, or mode "timeline-keyframes" for keyframes.',
       "Playback renderers must consume runtime timeline state; pause freezes output, scrubbing renders a deterministic frame, and the full animation cycle maps to state.timeline.durationSeconds instead of a local fixed duration.",
       "When the product has a known loop duration, declare it as panels.timeline.defaultDurationSeconds; the runtime timeline duration starts from that loop duration instead of an unrelated 8s default.",
       'Timeline animation intent must declare loopDuration with source "reference", "user-request", or "product-derived", plus seconds and evidence; runtime/template fallback 8s is not a valid source.',
       "panels.timeline.defaultDurationSeconds must match animationIntent.loopDuration.seconds for playback/keyframe animation, so the initial timeline UI shows the declared product loop instead of a generic default.",
-      "Video export renderers must render deterministic frames from runtime timeline timestamps and duration; do not treat autonomous wall-clock time or captureStream recording time as the source of product duration.",
+      "Video export frames are rendered deterministically from the runtime-owned 30 FPS timeline schedule; product code must not use autonomous wall-clock time, captureStream, or MediaRecorder as the source or fallback for product duration.",
       "Playback renderers may compute an initial loop duration default during app initialization or reset, but must not watch state.timeline.durationSeconds and dispatch timeline.setDuration back to a computed local duration. User-edited timeline duration becomes the loop duration source of truth after initialization or reset.",
       "Playback renderers should use getToolcraftTimelineLoopTime or getToolcraftTimelineLoopProgress to derive product loop phase from state.timeline.currentTimeSeconds and state.timeline.durationSeconds; do not hand-roll wall-clock, fixed-duration, mirror, yoyo, ping-pong, or reverse phase math.",
       "Product animation loop means a seamless forward-only cycle by default: motion advances in one direction, first and last frames stitch without a visible jump, and mirror/yoyo/ping-pong/reverse loops require explicit user request.",

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

@@ -26,6 +26,7 @@ describe("Toolcraft template component contracts: core", () => {
       "checkbox",
       "actions",
       "collectionActions",
+      "sourceCollection",
       "panelActions",
       "colorOpacity",
       "palette",
@@ -72,6 +73,7 @@ describe("Toolcraft template component contracts: core", () => {
       "palette",
       "actions",
       "collectionActions",
+      "sourceCollection",
       "panelActions",
       "customControl",
     ] as const) {

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

@@ -54,8 +54,10 @@ describe("Toolcraft template decision contract", () => {
 
     expect(rule?.level).toBe("invariant");
     expect(rule?.desiredBehavior).toMatch(/sceneBoundsProvider/i);
-    expect(rule?.desiredBehavior).toMatch(/visible scene elements/i);
-    expect(rule?.desiredBehavior).toMatch(/time-range envelope/i);
+    expect(rule?.desiredBehavior).toMatch(/useToolcraftProductSceneFrame/i);
+    expect(rule?.desiredBehavior).toMatch(/live infinite preview/i);
+    expect(rule?.desiredBehavior).toMatch(/one exact state/i);
+    expect(rule?.desiredBehavior).toMatch(/runtime-owned timestamp schedule/i);
     expect(rule?.desiredBehavior).toMatch(/finite canvas size/i);
     expect(rule?.enforcement).toContain("acceptance-validator");
     expect(rule?.enforcement).toContain("browser-helper");
@@ -116,6 +118,22 @@ describe("Toolcraft template decision contract", () => {
     );
   });
 
+  it("requires artifact delivery to correspond exactly to explicit product export intent", () => {
+    const rule = getToolcraftDecisionRule("output-export-required");
+
+    expect(rule?.level).toBe("invariant");
+    expect(rule?.desiredBehavior).toMatch(/productReadiness\.exportIntent/);
+    expect(rule?.desiredBehavior).toMatch(/image[^.]*Toolcraft default/i);
+    expect(rule?.desiredBehavior).toMatch(/video[^.]*explicit user request[^.]*evidence/i);
+    expect(rule?.desiredBehavior).toMatch(
+      /animation, playback, keyframes, or timeline[^.]*never/i,
+    );
+    expect(rule?.desiredBehavior).toMatch(/image[^.]*removed[^.]*explicit user[^.]*evidence/i);
+    expect(rule?.desiredBehavior).toMatch(
+      /intent[^.]*correspond exactly[^.]*schema actions, settings sections, and acceptance coverage/i,
+    );
+  });
+
   it("makes renderer technology a default with escape hatches", () => {
     const rule = getToolcraftDecisionRule("renderer-technique-inventory");
 
@@ -228,10 +246,28 @@ describe("Toolcraft template decision contract", () => {
     expect(rule?.desiredBehavior).toMatch(/performance-iteration/i);
     expect(rule?.desiredBehavior).toMatch(/bounded targeted iteration/i);
     expect(rule?.desiredBehavior).toMatch(
-      /one complaint maps to one exact authority-selected targeted performance iteration over canonical affected path IDs/i,
+      /only a localized complaint or a post-clarification targeted choice creates performance-iteration intent and one bounded iteration over exact canonical affected paths/iu,
+    );
+    expect(rule?.desiredBehavior).toMatch(
+      /classifier output establishes complaint authority only and never path localization/iu,
     );
     expect(rule?.desiredBehavior).toMatch(
-      /complaint wording and repetition never select the complete performance matrix/i,
+      /regardless of whether the classifier returned high-confidence performance-iteration or needs-agent-judgment, unresolved localization creates neither performance-iteration intent nor canonical path authority/iu,
+    );
+    expect(rule?.desiredBehavior).not.toMatch(
+      /one complaint maps to one exact authority-selected targeted performance iteration/iu,
+    );
+    expect(rule?.desiredBehavior).not.toMatch(
+      /direct and repeated performance complaints each start one bounded targeted iteration/iu,
+    );
+    expect(rule?.desiredBehavior).toMatch(
+      /localized complaint[\s\S]*without asking the user/iu,
+    );
+    expect(rule?.desiredBehavior).toMatch(
+      /ambiguous or unresolved localization[\s\S]*one user-facing clarification[\s\S]*targeted diagnosis or a complete review/iu,
+    );
+    expect(rule?.desiredBehavior).toMatch(
+      /repetition alone never expands scope or selects the complete performance matrix/i,
     );
     expect(rule?.desiredBehavior).toMatch(
       /explicit natural-language request for the complete audit/i,
@@ -244,6 +280,9 @@ describe("Toolcraft template decision contract", () => {
     expect(rule?.desiredBehavior).toMatch(
       /renderScaleCoverage "selected-backing-pixels" for interaction and steady, plus playback when timeline is enabled/i,
     );
+    expect(rule?.desiredBehavior).toMatch(
+      /every measured path[\s\S]*devicePixelRatio × 2[\s\S]*each measured phase/iu,
+    );
     expect(rule?.desiredBehavior).toMatch(
       /never downsample[\s\S]*clamp the selected render scale to pass a performance budget/i,
     );

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

@@ -58,7 +58,7 @@ export const TOOLCRAFT_DECISION_CONTRACT = [
     area: "runtime-shell",
     currentConstraint: "Apps must assemble through defineToolcraft and ToolcraftApp.",
     desiredBehavior:
-      "Generated apps use the Toolcraft runtime shell and keep product-specific rendering inside supported extension points: schema controls, canvasContent product output, controlRenderers for true custom controls, ToolcraftApp onPanelAction, and runtime commands. App-specific code must not import or render low-level runtime surfaces or built-in control components directly.",
+      "Generated apps use the Toolcraft runtime shell and keep product-specific rendering inside supported extension points: schema controls, bounded canvasContent product output, editor-only full-viewport infiniteCanvasContent product output, controlRenderers for true custom controls, one shared ToolcraftAppComposition.exportRenderer for typed image/video actions, ToolcraftApp onPanelAction for non-export product actions, and runtime commands. App-specific code must not import or render low-level runtime surfaces or built-in control components directly, instantiate encoders, or own artifact download mechanics.",
     enforcement: [
       "cli-integrity-check",
       "acceptance-validator",
@@ -87,7 +87,7 @@ export const TOOLCRAFT_DECISION_CONTRACT = [
     currentConstraint:
       "The Toolcraft canvas shell owns the visible workspace backing behind product output.",
     desiredBehavior:
-      "Generated apps preserve the runtime canvas surface and do not replace or hide it when product renderers customize their own background. In infinite mode the shell fills the complete viewport with the selected standard Background color, while bounded product background pixels remain suppressed.",
+      "Generated apps preserve the runtime canvas surface and do not replace or hide it when product renderers customize their own background. In infinite mode the shell fills the complete viewport with the selected standard Background color, while bounded product background pixels remain suppressed. Preview-only product environments may layer through infiniteCanvasContent across the complete viewport under the transformed world; that layer is pointer-transparent and excluded from scene bounds and export.",
     enforcement: ["browser-helper", "starter-agents", "spec-checklist"],
     id: "canvas-surface-preserved",
     level: "invariant",
@@ -99,7 +99,7 @@ export const TOOLCRAFT_DECISION_CONTRACT = [
     currentConstraint:
       "Editable output can switch from a finite artboard to an unbounded workspace, but product renderers and export actions still need one canonical world-space frame contract.",
     desiredBehavior:
-      "Editable-output apps expose one runtime-owned Infinity canvas mode. Enabling it removes finite artboard clipping and size controls while preserving the dormant finite canvas size for exact restoration. When the standard Background pair exists, its selected color fills the complete infinite viewport and Background off atomically resolves finite mode and disables Infinity. Runtime image and model assets retain explicit world-space frames. ToolcraftAppComposition.sceneBoundsProvider supplies product-renderer bounds through one direct composition boundary; image export crops to the union of visible scene elements and video export uses one provider time-range envelope for all rendered frames. Hidden layers, suppressed default consumers, and editor-only UI do not expand output bounds. Finite mode continues to export the full finite canvas size, while empty, unavailable, and unsafe oversized infinite exports return typed visible failures.",
+      "Editable-output apps expose one runtime-owned Infinity canvas mode. Enabling it removes finite artboard clipping and size controls while preserving the dormant finite canvas size for exact restoration. When the standard Background pair exists, its selected color fills the complete infinite viewport and Background off atomically resolves finite mode and disables Infinity. Runtime image and model assets retain explicit world-space frames. ToolcraftAppComposition.sceneBoundsProvider supplies product-renderer bounds for one exact state through one direct composition boundary. Runtime applies that same product frame to the live infinite preview, and custom raster/WebGL renderers consume useToolcraftProductSceneFrame for backing size and world-to-local translation instead of the dormant finite canvas size. ToolcraftAppComposition.infiniteCanvasContent is reserved for preview-only product environments that fill the complete Infinity viewport without world transforms, pointer input, scene-bounds participation, or export inclusion. Image export resolves the current frame and video export unions every state from the runtime-owned timestamp schedule. Hidden layers, suppressed default consumers, viewport environments, and editor-only UI do not expand preview or output bounds. Finite preview and export remain the full finite canvas and do not call the provider, while empty, unavailable, and unsafe oversized infinite exports return typed visible failures.",
     enforcement: [
       "acceptance-validator",
       "browser-helper",
@@ -203,9 +203,9 @@ export const TOOLCRAFT_DECISION_CONTRACT = [
   {
     area: "controls",
     currentConstraint:
-      "Every visible schema control must bind to runtime state, reset from schema defaults, and have acceptance and browser coverage.",
+      "Every product control explicitly declares always or conditional applicability; every visible finite sibling branch binds to runtime state, resets from schema defaults, and passes its accepted browser outcome.",
     desiredBehavior:
-      "Controls are not decorative; each visible control proves its product responsibility through runtime and output observables.",
+      "Non-applicable controls are absent with values preserved, and no always or conditional control remains visible in a finite product branch where its value is ignored.",
     enforcement: ["acceptance-validator", "browser-helper"],
     id: "controls-product-coverage",
     level: "invariant",
@@ -215,13 +215,13 @@ export const TOOLCRAFT_DECISION_CONTRACT = [
   {
     area: "controls",
     currentConstraint:
-      "Product-output apps expose final output delivery through sticky footer panelActions.",
+      "Product artifact delivery must match the required productReadiness.exportIntent declaration.",
     desiredBehavior:
-      'Product apps include Export PNG plus an "Image Export" section for format and 2K/4K/8K resolution. Apps whose requested delivery includes animation also include Export Video plus "Video Export" settings; a playback or keyframe timeline may exist for interactive preview without inventing video delivery. Copy can be secondary, but it does not replace export. Product apps declare the standard background pair and runtime places it in Setup: Background beside Infinity canvas, Color below, and Timeline last. Standard helpers own runtime PNG transparency, live preview product-background visibility, infinite viewport color, the Background-to-Infinity finite fallback, and selected image dimensions or retina fallback, while video keeps the background.',
+      'Every product declares productReadiness.exportIntent. Image export starts as the Toolcraft default and is removed only with explicit user-removal evidence; video export requires explicit user request evidence. Animation, playback, keyframes, or timeline presence never changes artifact delivery intent. Resolved intent capabilities correspond exactly to schema actions, settings sections, and acceptance coverage: image-only, image-plus-video, video-only, and explicit no-export products expose only the runtime-owned artifact surfaces their intent enables. Product apps declare the standard background pair and runtime places it in Setup: Background beside Infinity canvas, Color below, and Timeline last. One shared product exportRenderer draws deterministic scene-coordinate frames for enabled artifact types; runtime owns settings, scene crop, PNG/JPEG/video background semantics, visible runtime media/model composition, exact timestamped encoding, download, progress, and typed failures.',
     enforcement: ["acceptance-validator", "performance-validator", "browser-helper", "starter-agents"],
     id: "output-export-required",
     level: "invariant",
-    title: "Product output always has export",
+    title: "Product output follows artifact export intent",
     verdict: "move-to-validator",
   },
   {
@@ -229,7 +229,7 @@ export const TOOLCRAFT_DECISION_CONTRACT = [
     currentConstraint:
       "Every product controls section must be represented in the exported Control Section Inventory before schema authoring.",
     desiredBehavior:
-      "Generated product apps publish a typed Control Section Inventory with section title, product entity or workflow stage, exact targets, and a concrete grouping reason so section ownership is machine-checkable without prescribing the final product layout.",
+      "Generated product apps publish a typed Control Section Inventory with stable entityId, human-readable entity, exact targets, and a concrete grouping reason. One entity stays in one section through ten controls; larger entities use balanced two-to-ten-control workflow stages with explicit split evidence, so section ownership and reset boundaries are machine-checkable without runtime rewriting.",
     enforcement: ["acceptance-validator", "docs", "starter-agents", "spec-checklist"],
     id: "controls-section-inventory-required",
     level: "invariant",
@@ -253,7 +253,7 @@ export const TOOLCRAFT_DECISION_CONTRACT = [
     currentConstraint:
       "Labels, color placement, section grouping, selector order, and inline density need product-aware decisions.",
     desiredBehavior:
-      "Given a valid Control Section Inventory, ordering, section cohesion, labels, color placement, and compact density remain product-aware recommendations. Validators report questionable grouping without rejecting a coherent product-specific choice solely because it differs from a preferred heuristic.",
+      "Given a valid Control Section Inventory, ordering, labels, color placement, and compact density remain product-aware recommendations. The ten-control maximum and entity cohesion are inventory invariants; heuristics may report questionable presentation without rejecting a coherent product-specific choice solely because it differs from a preferred layout.",
     enforcement: ["acceptance-validator", "schema-normalization", "docs", "starter-agents"],
     id: "controls-layout-heuristics",
     level: "heuristic",

package/templates/runtime/contracts/performance-verification-policy.test.ts

@@ -26,6 +26,8 @@ describe("Toolcraft canonical performance verification policy", () => {
     expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY).toEqual({
       agentBrowser:
         "Agent-controlled browser checks are limited to diagnosis and targeted visual investigation; they do not mint durable performance baselines or receipts.",
+      complaintRouting:
+        "Performance authority and path localization are separate decisions. Classifier output establishes complaint authority only and never path localization. A localized complaint lets the agent select canonical affected paths and run one targeted iteration without asking the user. An ambiguous or unresolved localization requires one user-facing clarification naming visible operations and offering targeted diagnosis or a complete review; never ask the user for internal path ids. Regardless of whether the classifier returned high-confidence performance-iteration or needs-agent-judgment, unresolved localization creates neither performance-iteration intent nor canonical path authority. A broad or honestly unlocalizable problem may justify recommending the complete review immediately, but only the user's explicit request or acceptance authorizes it. A direct request for a complete review runs the full audit without another clarification.",
       deliveryBatch:
         "Classify and verify one coherent user-visible delivery batch instead of treating each internal implementation pass or steering correction as a separate aggregate verification boundary.",
       deliveryCommand:
@@ -37,13 +39,13 @@ describe("Toolcraft canonical performance verification policy", () => {
       fullAuditDiscovery:
         "The complete performance matrix remains outside conversational delivery. Complaints, repetition, tier, filename, and touched subsystem never launch it automatically. After two consecutive compatible protected performance iterations, the agent must offer a slower complete audit if the user remains unsatisfied; a demonstrably broad or unlocalizable cross-system problem may justify the same offer earlier. An explicit natural-language request for the complete audit, or explicit acceptance of the agent's offer, authorizes the agent acting as operator to run pnpm verify:perf; the user does not need to know the command name. After the audit, repair and rerun failed paths with focused checks, then run the complete matrix only once at the requested certification boundary.",
       performanceIterationDelivery:
-        "The runtime request classifier is a tri-state guard, not a replacement for AI semantic judgment: high-confidence runtime complaints, responsiveness optimization, or excessive CPU, GPU, memory, or resource use classify as performance-iteration; high-confidence product motion, speed, freeze, terminology, or locally negated complaint commands classify as ordinary-product-work; ambiguous or unrecognized wording classifies as needs-agent-judgment and the AI decides from the actual user request. Ordinary work is rejected only for a high-confidence performance iteration. Every performance-iteration worklog intent quotes a nontrivial exact raw substring of Request; whitespace and Unicode code units must match before normalized tri-state classification. Invented, whitespace-collapsed, NFKC-equivalent, or mismatched evidence is rejected; high-confidence ordinary evidence is rejected; exact high-confidence performance-iteration or needs-agent-judgment evidence is accepted under agent ownership. Each performance iteration requires an exact reachable development fixture and fails with a configuration error instead of falling back to maximum. One complaint maps to one exact authority-selected targeted performance iteration over canonical affected path IDs. Direct and repeated performance complaints each start one bounded targeted iteration over affected paths. Complaint wording and repetition never select the complete performance matrix, create or refresh a durable baseline, or grant full-performance certification authority.",
+        "The runtime request classifier is a tri-state guard, not a replacement for AI semantic judgment: high-confidence runtime complaints, responsiveness optimization, or excessive CPU, GPU, memory, or resource use classify as performance-iteration; high-confidence product motion, speed, freeze, terminology, or locally negated complaint commands classify as ordinary-product-work; ambiguous or unrecognized wording classifies as needs-agent-judgment and the AI decides from the actual user request. Ordinary work is rejected only for a high-confidence performance iteration. Every performance-iteration worklog intent quotes a nontrivial exact raw substring of Request; whitespace and Unicode code units must match before normalized tri-state classification. Invented, whitespace-collapsed, NFKC-equivalent, or mismatched evidence is rejected; high-confidence ordinary evidence is rejected; exact high-confidence performance-iteration evidence, or needs-agent-judgment evidence after semantic resolution, is accepted under agent ownership. Classifier output establishes complaint authority only and never path localization. Each performance iteration requires an exact reachable development fixture and fails with a configuration error instead of falling back to maximum. Only a localized complaint or a post-clarification targeted choice creates performance-iteration intent and one bounded iteration over exact canonical affected paths. Regardless of whether the classifier returned high-confidence performance-iteration or needs-agent-judgment, unresolved localization creates neither performance-iteration intent nor canonical path authority. Each repeated localized request may create one new bounded targeted iteration over its affected paths; repetition alone never expands scope or selects the complete performance matrix, creates or refreshes a durable baseline, or grants full-performance certification authority.",
       functionalInitialDelivery:
         'A functional delivery plan with basis "initial" runs complete functional proof and no measured performance. It preserves any independent full-performance baseline and cannot claim targeted or full performance evidence.',
       functionalTargetedDelivery:
         'A functional delivery plan with basis "changed" runs exact affected ownership-derived functional proof and no measured performance. Functional delivery cannot silently invoke targeted performance, the full performance matrix, or create or refresh a performance baseline.',
       renderScaleFidelity:
-        'canvas.renderScale is visible functional fidelity. Raster products declare typed renderScaleCoverage "selected-backing-pixels" for interaction and steady, plus playback when timeline is enabled, and prove real canvas backing pixels in every declared state. Never downsample, stretch a lower-resolution backing canvas, blur output, or clamp the selected render scale to pass a performance budget.',
+        'canvas.renderScale is visible functional fidelity. Raster products declare typed renderScaleCoverage "selected-backing-pixels" for interaction and steady, plus playback when timeline is enabled, and prove real canvas backing pixels in every declared state. Every measured path in a render-scale-enabled raster product proves actual CSS × devicePixelRatio × 2 backing after each measured phase. Never downsample, stretch a lower-resolution backing canvas, blur output, or clamp the selected render scale to pass a performance budget.',
     });
     expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_LIFECYCLE).toEqual({
       delivery: {
@@ -87,7 +89,7 @@ describe("Toolcraft canonical performance verification policy", () => {
       /ambiguous or unrecognized wording classifies as needs-agent-judgment/i,
     );
     expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
-      /high-confidence performance-iteration or needs-agent-judgment evidence is accepted under agent ownership/i,
+      /exact high-confidence performance-iteration evidence, or needs-agent-judgment evidence after semantic resolution, is accepted under agent ownership/i,
     );
     expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
       /whitespace and Unicode code units must match/i,
@@ -96,13 +98,31 @@ describe("Toolcraft canonical performance verification policy", () => {
       /performance iteration requires an exact reachable development fixture/i,
     );
     expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
-      /direct and repeated performance complaints each start one bounded targeted iteration/i,
+      /only a localized complaint or a post-clarification targeted choice creates performance-iteration intent and one bounded iteration over exact canonical affected paths/iu,
     );
     expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
-      /one complaint maps to one exact authority-selected targeted performance iteration over canonical affected path IDs/i,
+      /regardless of whether the classifier returned high-confidence performance-iteration or needs-agent-judgment, unresolved localization creates neither performance-iteration intent nor canonical path authority/iu,
     );
     expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
-      /complaint wording and repetition never select the complete performance matrix/i,
+      /each repeated localized request may create one new bounded targeted iteration/iu,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).not.toMatch(
+      /one complaint maps to one exact authority-selected targeted performance iteration/iu,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).not.toMatch(
+      /direct and repeated performance complaints each start one bounded targeted iteration/iu,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /localized complaint[\s\S]*without asking the user/iu,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /ambiguous or unresolved localization[\s\S]*one user-facing clarification[\s\S]*targeted diagnosis or a complete review/iu,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /direct request for a complete review[\s\S]*without another clarification/iu,
+    );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /repetition alone never expands scope or selects the complete performance matrix/i,
     );
     expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
       /two consecutive compatible protected performance iterations[\s\S]*must offer/i,
@@ -122,8 +142,41 @@ describe("Toolcraft canonical performance verification policy", () => {
     expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
       /typed renderScaleCoverage "selected-backing-pixels" for interaction and steady, plus playback when timeline is enabled/i,
     );
+    expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
+      /every measured path[\s\S]*devicePixelRatio × 2[\s\S]*each measured phase/iu,
+    );
     expect(TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT).toMatch(
       /never downsample[\s\S]*clamp the selected render scale to pass a performance budget/i,
     );
   });
+
+  it.each([
+    {
+      axis: "high-confidence but unlocalized complaint",
+      expected:
+        /classifier output establishes complaint authority only and never path localization[\s\S]*regardless of whether the classifier returned high-confidence performance-iteration[\s\S]*unresolved localization creates neither performance-iteration intent nor canonical path authority/iu,
+    },
+    {
+      axis: "localized complaint",
+      expected:
+        /localized complaint[\s\S]*one targeted iteration without asking the user/iu,
+    },
+    {
+      axis: "needs-agent-judgment with unresolved localization",
+      expected:
+        /regardless of whether the classifier returned[\s\S]*needs-agent-judgment[\s\S]*unresolved localization creates neither performance-iteration intent nor canonical path authority/iu,
+    },
+    {
+      axis: "post-clarification targeted choice",
+      expected:
+        /post-clarification targeted choice creates performance-iteration intent and one bounded iteration over exact canonical affected paths/iu,
+    },
+  ])("routes $axis without coupling authority to localization", ({ expected }) => {
+    const canonicalRoutingPolicy = [
+      TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.complaintRouting,
+      TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.performanceIterationDelivery,
+    ].join(" ");
+
+    expect(canonicalRoutingPolicy).toMatch(expected);
+  });
 });

package/templates/runtime/contracts/performance-verification-policy.ts

@@ -3,6 +3,8 @@ export * from "./performance-request-classifier";
 export const TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY = {
   agentBrowser:
     "Agent-controlled browser checks are limited to diagnosis and targeted visual investigation; they do not mint durable performance baselines or receipts.",
+  complaintRouting:
+    "Performance authority and path localization are separate decisions. Classifier output establishes complaint authority only and never path localization. A localized complaint lets the agent select canonical affected paths and run one targeted iteration without asking the user. An ambiguous or unresolved localization requires one user-facing clarification naming visible operations and offering targeted diagnosis or a complete review; never ask the user for internal path ids. Regardless of whether the classifier returned high-confidence performance-iteration or needs-agent-judgment, unresolved localization creates neither performance-iteration intent nor canonical path authority. A broad or honestly unlocalizable problem may justify recommending the complete review immediately, but only the user's explicit request or acceptance authorizes it. A direct request for a complete review runs the full audit without another clarification.",
   deliveryBatch:
     "Classify and verify one coherent user-visible delivery batch instead of treating each internal implementation pass or steering correction as a separate aggregate verification boundary.",
   deliveryCommand:
@@ -14,13 +16,13 @@ export const TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY = {
   fullAuditDiscovery:
     "The complete performance matrix remains outside conversational delivery. Complaints, repetition, tier, filename, and touched subsystem never launch it automatically. After two consecutive compatible protected performance iterations, the agent must offer a slower complete audit if the user remains unsatisfied; a demonstrably broad or unlocalizable cross-system problem may justify the same offer earlier. An explicit natural-language request for the complete audit, or explicit acceptance of the agent's offer, authorizes the agent acting as operator to run pnpm verify:perf; the user does not need to know the command name. After the audit, repair and rerun failed paths with focused checks, then run the complete matrix only once at the requested certification boundary.",
   performanceIterationDelivery:
-    "The runtime request classifier is a tri-state guard, not a replacement for AI semantic judgment: high-confidence runtime complaints, responsiveness optimization, or excessive CPU, GPU, memory, or resource use classify as performance-iteration; high-confidence product motion, speed, freeze, terminology, or locally negated complaint commands classify as ordinary-product-work; ambiguous or unrecognized wording classifies as needs-agent-judgment and the AI decides from the actual user request. Ordinary work is rejected only for a high-confidence performance iteration. Every performance-iteration worklog intent quotes a nontrivial exact raw substring of Request; whitespace and Unicode code units must match before normalized tri-state classification. Invented, whitespace-collapsed, NFKC-equivalent, or mismatched evidence is rejected; high-confidence ordinary evidence is rejected; exact high-confidence performance-iteration or needs-agent-judgment evidence is accepted under agent ownership. Each performance iteration requires an exact reachable development fixture and fails with a configuration error instead of falling back to maximum. One complaint maps to one exact authority-selected targeted performance iteration over canonical affected path IDs. Direct and repeated performance complaints each start one bounded targeted iteration over affected paths. Complaint wording and repetition never select the complete performance matrix, create or refresh a durable baseline, or grant full-performance certification authority.",
+    "The runtime request classifier is a tri-state guard, not a replacement for AI semantic judgment: high-confidence runtime complaints, responsiveness optimization, or excessive CPU, GPU, memory, or resource use classify as performance-iteration; high-confidence product motion, speed, freeze, terminology, or locally negated complaint commands classify as ordinary-product-work; ambiguous or unrecognized wording classifies as needs-agent-judgment and the AI decides from the actual user request. Ordinary work is rejected only for a high-confidence performance iteration. Every performance-iteration worklog intent quotes a nontrivial exact raw substring of Request; whitespace and Unicode code units must match before normalized tri-state classification. Invented, whitespace-collapsed, NFKC-equivalent, or mismatched evidence is rejected; high-confidence ordinary evidence is rejected; exact high-confidence performance-iteration evidence, or needs-agent-judgment evidence after semantic resolution, is accepted under agent ownership. Classifier output establishes complaint authority only and never path localization. Each performance iteration requires an exact reachable development fixture and fails with a configuration error instead of falling back to maximum. Only a localized complaint or a post-clarification targeted choice creates performance-iteration intent and one bounded iteration over exact canonical affected paths. Regardless of whether the classifier returned high-confidence performance-iteration or needs-agent-judgment, unresolved localization creates neither performance-iteration intent nor canonical path authority. Each repeated localized request may create one new bounded targeted iteration over its affected paths; repetition alone never expands scope or selects the complete performance matrix, creates or refreshes a durable baseline, or grants full-performance certification authority.",
   functionalInitialDelivery:
     'A functional delivery plan with basis "initial" runs complete functional proof and no measured performance. It preserves any independent full-performance baseline and cannot claim targeted or full performance evidence.',
   functionalTargetedDelivery:
     'A functional delivery plan with basis "changed" runs exact affected ownership-derived functional proof and no measured performance. Functional delivery cannot silently invoke targeted performance, the full performance matrix, or create or refresh a performance baseline.',
   renderScaleFidelity:
-    'canvas.renderScale is visible functional fidelity. Raster products declare typed renderScaleCoverage "selected-backing-pixels" for interaction and steady, plus playback when timeline is enabled, and prove real canvas backing pixels in every declared state. Never downsample, stretch a lower-resolution backing canvas, blur output, or clamp the selected render scale to pass a performance budget.',
+    'canvas.renderScale is visible functional fidelity. Raster products declare typed renderScaleCoverage "selected-backing-pixels" for interaction and steady, plus playback when timeline is enabled, and prove real canvas backing pixels in every declared state. Every measured path in a render-scale-enabled raster product proves actual CSS × devicePixelRatio × 2 backing after each measured phase. Never downsample, stretch a lower-resolution backing canvas, blur output, or clamp the selected render scale to pass a performance budget.',
 } as const;
 
 export const TOOLCRAFT_PERFORMANCE_VERIFICATION_LIFECYCLE = {
@@ -37,6 +39,7 @@ export const TOOLCRAFT_PERFORMANCE_VERIFICATION_LIFECYCLE = {
 
 export const TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT = [
   TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.agentBrowser,
+  TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.complaintRouting,
   TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.deliveryBatch,
   TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.deliveryCommand,
   TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.demandOnlyPerformance,

package/templates/runtime/export/artifact-download.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { downloadToolcraftArtifact } from "./artifact-download";
+
+describe("downloadToolcraftArtifact", () => {
+  it("sanitizes the filename and revokes the object URL after the click", () => {
+    const events: string[] = [];
+    const anchor = {
+      click: vi.fn(() => events.push("click")),
+      download: "",
+      href: "",
+      remove: vi.fn(() => events.push("remove")),
+    };
+    const schedule = vi.fn((callback: () => void) => {
+      events.push("schedule-revoke");
+      callback();
+      return 1;
+    });
+
+    const result = downloadToolcraftArtifact({
+      appendAnchor: () => events.push("append"),
+      blob: new Blob(["png"], { type: "image/png" }),
+      createAnchor: () => anchor,
+      createObjectUrl: () => "blob:artifact",
+      extension: ".png",
+      rawBaseFileName: "  Unsafe / name  ",
+      revokeObjectUrl: () => events.push("revoke"),
+      schedule,
+    });
+
+    expect(result.fileName).toBe("Unsafe-name.png");
+    expect(anchor.download).toBe("Unsafe-name.png");
+    expect(events).toEqual([
+      "append",
+      "click",
+      "remove",
+      "schedule-revoke",
+      "revoke",
+    ]);
+  });
+
+  it("types click failures and still removes and revokes", () => {
+    const remove = vi.fn();
+    const revoke = vi.fn();
+
+    expect(() =>
+      downloadToolcraftArtifact({
+        appendAnchor: vi.fn(),
+        blob: new Blob(["png"]),
+        createAnchor: () => ({
+          click: () => {
+            throw new Error("blocked");
+          },
+          download: "",
+          href: "",
+          remove,
+        }),
+        createObjectUrl: () => "blob:artifact",
+        extension: ".png",
+        rawBaseFileName: "",
+        revokeObjectUrl: revoke,
+        schedule: (callback) => {
+          callback();
+          return 1;
+        },
+      }),
+    ).toThrow("could not start the artifact download");
+    expect(remove).toHaveBeenCalledOnce();
+    expect(revoke).toHaveBeenCalledWith("blob:artifact");
+  });
+});

package/templates/runtime/export/artifact-download.ts

@@ -0,0 +1,80 @@
+import {
+  normalizeToolcraftExportError,
+  type ToolcraftArtifactExportFailure,
+} from "./export-error";
+
+export type ToolcraftArtifactFileExtension =
+  | ".jpg"
+  | ".mp4"
+  | ".png"
+  | ".webm";
+
+type ToolcraftDownloadAnchor = {
+  click: () => void;
+  download: string;
+  href: string;
+  remove: () => void;
+};
+
+export type ToolcraftArtifactDownloadRequest = Readonly<{
+  appendAnchor?: (anchor: ToolcraftDownloadAnchor) => void;
+  blob: Blob;
+  createAnchor?: () => ToolcraftDownloadAnchor;
+  createObjectUrl?: (blob: Blob) => string;
+  extension: ToolcraftArtifactFileExtension;
+  rawBaseFileName: string;
+  revokeObjectUrl?: (url: string) => void;
+  schedule?: (callback: () => void, delay: number) => unknown;
+}>;
+
+export type ToolcraftArtifactDownloadResult = Readonly<{ fileName: string }>;
+
+export function sanitizeToolcraftArtifactBaseFileName(value: string): string {
+  const sanitized = value
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]+/g, "-")
+    .replace(/^[.-]+|[.-]+$/g, "");
+
+  return sanitized || "toolcraft-export";
+}
+
+const downloadFailure: ToolcraftArtifactExportFailure = Object.freeze({
+  code: "artifact-download-failed",
+  message: "Toolcraft could not start the artifact download.",
+});
+
+export function downloadToolcraftArtifact(
+  request: ToolcraftArtifactDownloadRequest,
+): ToolcraftArtifactDownloadResult {
+  const createAnchor =
+    request.createAnchor ?? (() => document.createElement("a"));
+  const appendAnchor =
+    request.appendAnchor ??
+    ((anchor) => document.body.append(anchor as HTMLAnchorElement));
+  const createObjectUrl = request.createObjectUrl ?? URL.createObjectURL;
+  const revokeObjectUrl = request.revokeObjectUrl ?? URL.revokeObjectURL;
+  const schedule = request.schedule ?? globalThis.setTimeout;
+  const fileName = `${sanitizeToolcraftArtifactBaseFileName(
+    request.rawBaseFileName,
+  )}${request.extension}`;
+  let anchor: ToolcraftDownloadAnchor | null = null;
+  let objectUrl: string | null = null;
+
+  try {
+    objectUrl = createObjectUrl(request.blob);
+    anchor = createAnchor();
+    anchor.download = fileName;
+    anchor.href = objectUrl;
+    appendAnchor(anchor);
+    anchor.click();
+    return { fileName };
+  } catch (error) {
+    throw normalizeToolcraftExportError(error, downloadFailure);
+  } finally {
+    anchor?.remove();
+    if (objectUrl) {
+      const urlToRevoke = objectUrl;
+      schedule(() => revokeObjectUrl(urlToRevoke), 0);
+    }
+  }
+}

package/templates/runtime/export/artifact-export-request.ts

@@ -0,0 +1,23 @@
+import type { ToolcraftRendererPipelineClient } from "../rendering";
+import type {
+  ToolcraftProductSceneBoundsProvider,
+  ToolcraftRuntimeSceneVisibility,
+} from "../scene";
+import type { ToolcraftState } from "../state/types";
+import type { ToolcraftExportFrame } from "./export-frame";
+import type { ToolcraftProductExportRenderer } from "./product-export-renderer";
+
+export type ToolcraftArtifactExportRequest = Readonly<{
+  boundsProvider: ToolcraftProductSceneBoundsProvider | undefined;
+  exportRenderer: ToolcraftProductExportRenderer | undefined;
+  productSceneRequired: boolean;
+  renderRuntimeScene: (
+    canvas: HTMLCanvasElement,
+    frame: ToolcraftExportFrame,
+    state: ToolcraftState,
+  ) => Promise<unknown>;
+  rendererPipeline: ToolcraftRendererPipelineClient | null;
+  reportProgress: (progress: number) => void;
+  state: ToolcraftState;
+  visibility: ToolcraftRuntimeSceneVisibility;
+}>;