@pixel-point/toolcraft 0.0.15 → 0.0.17

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

@@ -29,14 +29,22 @@ export const TOOLCRAFT_MEDIA_CUSTOM_COMPONENT_CONTRACTS = {
         "When fileDrop has multiple: true and more than one image is present, the runtime renders a sortable four-column thumbnail grid with the add-more tile last.",
         "When fileDrop has multiple: true and more than one image is present, image transform actions render only after the user selects a thumbnail, and they target only that selected image.",
         "When fileDrop has assetKind: file, the runtime renders a sortable file list with a paperclip icon, filename, remove button, and row separators using --border/5.",
+        "When fileDrop has assetKind: model, standard model preview remains runtime-owned even when renderDefaultCanvasMedia is false; custom presentation is selected only through ToolcraftAppComposition modelPresentation.",
       ],
       requiredAcceptance: [
-        "Prove file import changes media state and product output; prove clear, reorder, rotate, flip, and section/global reset update source material.",
+        "Prove file import changes media state and product output; fileDrop proves source admission, clear/remove, and section/global reset. Without Layers-owned media management it also proves reorder, rotate, and flip; with Layers ownership, fixed layer reorder and selected-layer-control recipes prove those operations.",
       ],
     }),
     aiUsageRules: [
       "Use fileDrop for source material uploads in the controls panel, not on the canvas.",
       'Use fileDrop with assetKind: "image" for image-only source media and assetKind: "file" for arbitrary uploaded files.',
+      'Use fileDrop with assetKind: "model" for one GLB, glTF, FBX, OBJ, STL, or PLY model package. The selected source may be a standalone root, a folder batch, or one bounded ZIP archive.',
+      "Model import preserves the supported authored material, texture, vertex-color, and static appearance subset. It derives a canonical document without rewriting the durable original source package.",
+      "When a model has no authored appearance, runtime presentation uses the Blender-compatible fallback material: linear base color 0.8, metallic 0, roughness 0.5, black emissive, opacity 1.",
+      "Model package root selection is deterministic: normalize and sort supported root paths, then select the first. Missing appearance dependencies produce typed warnings and never expose Fix model; geometry repair is reserved for repairable topology.",
+      "Standard preview and export use ToolcraftAppComposition modelPresentation mode runtime. Custom model output uses mode custom, declares unique checked consumers by source target, and acquires presentation leases through useToolcraftModelPresentationConsumer instead of source loaders or a second cache.",
+      "renderDefaultCanvasMedia controls generic image and file preview only. It does not hide standard runtime model layers; modelPresentation custom mode suppresses only the declared model targets.",
+      "Rotatable models pair their source target with orientationGizmo. Gizmo drag, axis snap, direct model drag, preview, history/reset, and export consume the same pose and presentation lease; a geometry miss remains canvas pan.",
       "If an app ships with predefined source files or background images, declare them as schema media.defaultAssets with sourceTarget matching the fileDrop control. They must render as ordinary attached files in fileDrop, not as hidden renderer constants or canvas placeholder artwork.",
       "Predefined media files are default runtime state: users can remove them to get an empty source/canvas state, persistence may keep that removal with include: [\"media\"], and global or section Reset restores the default attached files.",
       "When uploaded/imported content is part of the source-material flow, the canvas must not show agent-invented artwork, CTA text, fake sample output, decorative placeholders, or preset source designs before real content exists; keep the canvas neutral/runtime-backed and put upload affordance in fileDrop.",
@@ -48,14 +56,22 @@ export const TOOLCRAFT_MEDIA_CUSTOM_COMPONENT_CONTRACTS = {
       "In file mode, the runtime shows uploaded files as a sortable list with paperclip icons, file names, remove buttons, and --border/5 separators.",
       "In single-layer apps, global Reset controls and section reset must restore fileDrop source media to schema media.defaultAssets for that target; when no default asset exists, Reset removes uploaded media and returns the fileDrop target to defaultValue.",
       "Use fileDrop with multiple: true when the app needs several uploaded images as one source set; do not build a custom thumbnail uploader for this.",
+      "fileDrop recommendedMaxItems is advisory and never rejects an import. A finite nonnegative safe-integer hardMaxItems is an actual admission limit: additive imports count existing assets for the same source target plus the incoming logical batch, replacement imports count only the replacement batch, and overflow is rejected before decoding or repository allocation.",
       "When multiple uploaded images are present, the runtime appends media, shows a sortable four-column preview grid, puts the add-more tile last, and exposes per-image removal.",
       "Canvas drops route to the first visible matching fileDrop target by asset kind: image files prefer image uploaders, non-image files prefer file uploaders, and file uploaders accept images only when no image uploader matches.",
       "Dragging thumbnails reorders runtime mediaAssets; preview, export, and renderer mapping must consume that media order instead of maintaining a separate product-only order.",
       "When uploaded images are used as canvas/background source material, draw them with cover/crop behavior: scale proportionally until the current canvas bounds are fully covered, keep the canvas size/settings unchanged, and crop overflow at the canvas bounds.",
       "Do not create custom upload buttons, file lists, or file sorting for generic source uploads when fileDrop can represent the source set.",
       "In multi-layer apps, deletion and visibility belong to the Layers panel; fileDrop remains an upload target.",
+      'When panels.layers is enabled and typed interactionOwnership assigns media management to Layers, fileDrop acceptance proves upload/admission, remove, reset, defaults, and model/binary lifecycle only; fixed layerCoverage "reorder" and "selected-layer-controls" recipes prove order output and selected image rotate/flip transform output without duplicating those claims on the fileDrop row.',
+    ],
+    commands: [
+      "media.delete",
+      "media.import",
+      "media.importBatch",
+      "media.reorder",
+      "media.transform",
     ],
-    commands: ["media.delete", "media.import", "media.reorder", "media.transform"],
   },
   imagePicker: {
     ...control("imagePicker", "ImagePicker", "standalone", "component-owned"),

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

@@ -1,6 +1,10 @@
 import { describe, expect, it } from "vitest";
 
 import { getToolcraftComponentContract } from "./component-contracts";
+import {
+  TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY,
+  TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT,
+} from "./performance-verification-policy";
 
 describe("Toolcraft template component contracts: runtime and composition", () => {
   it("documents app entity acceptance as product-output verification", () => {
@@ -40,7 +44,7 @@ describe("Toolcraft template component contracts: runtime and composition", () =
       "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.",
     );
     expect(contract.aiUsageRules).toContain(
-      "If a switch/select/segmented/imagePicker/checkbox chooses a branch for the same product entity, controls outside the current branch use visibleWhen, not disabledWhen.",
+      "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.",
     );
     expect(contract.aiUsageRules).toContain(
       "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.",
@@ -48,118 +52,106 @@ describe("Toolcraft template component contracts: runtime and composition", () =
     expect(contract.aiUsageRules).toContain(
       "Do not leave inactive conditional controls visible while making the renderer ignore them.",
     );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Allow complementary operations across surfaces when capabilities differ: canvas selection or direct manipulation may coexist with panel properties, modes, constraints, colors, collections, commands, or exact-value editing.",
+    );
   });
 
-  it("documents performance acceptance for custom renderer workload controls", () => {
+  it("requires workload envelopes and render-plan assessment before renderer code", () => {
     const contract = getToolcraftComponentContract("performanceAcceptance");
+    const rules = contract.aiUsageRules.join("\n");
 
     expect(contract.kind).toBe("composition");
     expect(contract.stateMode).toBe("runtime-owned");
     expect(contract.capabilities).toContain("performance-budgets");
     expect(contract.capabilities).toContain("workload-control-tests");
-    expect(contract.aiUsageRules).toContain(
-      "Custom renderers must define performance budgets for media import, preview updates, control drags, and export/copy before implementation.",
+    expect(rules).toContain(
+      TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.functionalInitialDelivery,
     );
-    expect(contract.aiUsageRules).toContain(
-      "Controls that change renderer workload by changing output dimensions, element count, density, sample count, iteration count, blur/filter radius, shader branch cost, media processing, text layout, or export quality must be tested at min, default, and max values.",
-    );
-    expect(contract.aiUsageRules).toContain(
-      "For workload control scenarios, stressFixture is the tested control value. If the app has an independent heavy baseline such as large media, long text, many items, high render scale, or dense source state, declare workloadFixture and apply it before the measured control interaction.",
+    expect(rules).toContain(
+      TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.functionalTargetedDelivery,
     );
-    expect(contract.aiUsageRules).toContain(
-      "Hash differs is not enough for workload controls; tests must assert semantic direction, such as density increasing item count or size changes reducing/increasing rendered cells.",
-    );
-    expect(contract.aiUsageRules).toContain(
-      "Performance tests must use representative fixtures and the same renderer/export path as the running app, not only tiny 32px fixtures or isolated helper state.",
-    );
-    expect(contract.aiUsageRules).toContain(
-      "Every export-copy performance scenario must declare the exact panelActions actionValue, visible controlLabel, and completionEvidence it exercises; selectors, unrelated export actions, and injectable completion callbacks are not output evidence. The named browser scenario must resolve to test or it imported from @playwright/test, be statically registered at module scope or inside an executable test.describe, test.describe.serial, or test.describe.parallel suite, and directly await the matching unshadowed protected output-action helper in its root callback block without focus, skip, condition, or nesting; local test runners, uncalled or conditional test declarations, skipped/fixme suites, and runtime skip/fixme/fail annotations are invalid, and generated integrity protects the focused-test Playwright config.",
-    );
-    expect(contract.aiUsageRules).toContain(
-      'Media-import workload fixtures and media workload baselines must use fixture kind "media" with numeric width and height at least 1920x1080-equivalent; 640x480 preview fixtures cannot satisfy upload, effect-control, or image-processing performance coverage.',
-    );
-    expect(contract.aiUsageRules).toContain(
-      "Slider drags and high-frequency controls must debounce or coalesce preview work, cancel stale async renders, and avoid re-decoding media on every control change.",
+    expect(rules).toContain(
+      "Functional delivery cannot silently invoke targeted performance",
     );
-    expect(contract.aiUsageRules).toContain(
-      "Performance matrices must declare rendererWorkload as none, simple-composition, text-output, vector-output, or pixel-output.",
+    expect(rules).toContain("performance-iteration");
+    expect(rules).toContain(
+      "Only a localized complaint or a post-clarification targeted choice creates performance-iteration intent",
     );
-    expect(contract.aiUsageRules).toContain(
-      "A full performance checkpoint must run only when the first working app version exists or the user requests performance, lag, jank, animation speed, drag/zoom stabilization work, or otherwise complains about performance; use the agent-controlled browser first and this app's verify:perf script only as the Playwright fallback.",
+    expect(rules).toContain(
+      "Classifier output establishes complaint authority only and never path localization",
     );
-    expect(contract.aiUsageRules).toContain(
-      "Renderer, canvas, animation, export, timeline, layers, canvas.renderScale, bug fixes, and performance-sensitive control changes use targeted functional/browser checks first and targeted performance scenarios only for touched workload, viewport, or export paths.",
+    expect(rules).toContain(
+      "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",
     );
-    expect(contract.aiUsageRules).toContain(
-      "Performance fixes must preserve selected output and preview quality; do not reduce image quality, selected renderScale, export resolution, source media fidelity, or canvas backing pixels as the hidden way to pass budgets.",
+    expect(rules).toContain(
+      "repetition alone never expands scope or selects the complete performance matrix",
     );
-    expect(contract.aiUsageRules).toContain(
-      "When canvas or slider interactions lag, diagnose where the slowdown comes from before changing output quality: renderer technique, React update frequency, decoded media, shader/program setup, buffer uploads, layout work, async render cancellation, or animation scheduling.",
+    expect(rules).not.toContain(
+      "One complaint maps to one exact authority-selected targeted performance iteration",
     );
-    expect(contract.aiUsageRules).toContain(
-      "Renderer specs must include a Renderer Technique Decision Matrix with sourceRepresentation, productRepresentation, previewRenderer, exportRenderer, rendererWorkload, rendererStrategy, whyNotAlternativeStrategies, fidelityRisks, and performanceRisks.",
+    expect(rules).not.toContain(
+      "Direct and repeated performance complaints each start one bounded targeted iteration",
     );
-    expect(contract.aiUsageRules).toContain(
-      "Custom renderer apps must mirror the Renderer Technique Decision Matrix in typed rendererTechnique config so validation can reject contradictory renderer choices.",
+    expect(rules).toContain(
+      "After two consecutive compatible protected performance iterations, the agent must offer a slower complete audit",
     );
-    expect(contract.aiUsageRules).toContain(
-      "Custom renderer specs must include a Renderer Layer Inventory and mirror it in typed rendererTechnique.layers so dense raster backgrounds cannot silently rasterize semantic foreground output.",
+    expect(rules).toContain(
+      "explicit acceptance of the agent's offer, authorizes the agent acting as operator to run pnpm verify:perf",
     );
     expect(contract.aiUsageRules).toContain(
-      "Semantic foreground output such as product lines, shapes, icons, text, object bounds, and meaningful markers should use DOM or SVG by default; dense raster backgrounds do not justify rasterizing low-count foreground geometry or text.",
+      "Before renderer code, inventory every reachable control, runtime-state input, and external input, and explicitly mark which ones change workload magnitude; do not infer workload from labels, target names, units, or keywords.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Editing handles must be DOM/SVG overlays, excluded from export, and written through runtime state instead of being drawn into the product raster layer.",
+      "Map every reachable workload role to exactly one numeric workloadEnvelope dimension with a stable id, unit, source, mapping, defaultValue, and every enforced interactiveMax or batchMax boundary.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Product foreground and editing handle renderer layers must declare uiSelector so browser tests can verify the visible layer exists.",
+      "Treat interactiveMax and batchMax as maximum-workload boundaries, not numerical maxima. Every numeric schema source declares workloadBoundary as minimum or maximum, every declared profile boundary equals that schema endpoint, and a batch-only dimension does not invent an interactive boundary.",
     );
     expect(contract.aiUsageRules).toContain(
-      'productRepresentation "mixed" is valid only when rendererTechnique.layers proves at least two different content families.',
+      "Declare only boundary profiles consumed by renderer passes; a control that changes a batch-only dimension keeps targeted control-change coverage without claiming an interactiveMax.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Custom renderer apps must declare rendererPipeline with render passes, cache keys, execution location, preview/export quality, and interaction invalidation before implementation.",
+      "Discrete fixture adapters must declare an exhaustive entries domain that binds every numeric workload value to its applied product value. Schema select/segmented/tabs domains must match every option one-to-one; other finite domains require source-aligned provenance. Development is available only for a reachable combined vector at normalized pressure 0.8 within runtime tolerance; otherwise it is unavailable while maximum remains available. Generic and measured inverse checkpoints are validated against the same exhaustive domain before exact application and observation. Path-level discrete search is deterministic, lazy, and limited by the runtime-owned combination budget; cardinality overflow or an exceeded budget is a planning error, not an unavailable exact vector.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Render Pipeline Inventory must explain which runtime targets invalidate each expensive pass; high-frequency interactions such as animation frames, drag, zoom, pan, timeline playback, and mask movement must not invalidate upstream decode/preprocess/pixel-transform work unless that target truly changes the upstream result.",
+      "Before renderer code, declare rendererPipeline.runtimeId plus every render pass's cost dimensions, relationship, frequency, lifecycle, execution location, quality, cache keys, and exact interaction invalidation.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Cache-sensitive render passes such as decode, preprocess, pixel-transform, text-layout, rasterize, and composite must declare cache keys so tests can reject full recomputation on every control change.",
+      "Run assessToolcraftRenderPlan before implementation. Resolve every required kernel benchmark with measured full-quality candidate evidence; do not choose renderer technology from a hardcoded product category.",
     );
-    expect(contract.aiUsageRules.join("\n")).toMatch(/rendererTechnique/);
-    expect(contract.aiUsageRules.join("\n")).toMatch(/rendererTechnique\.layers/);
-    expect(contract.aiUsageRules.join("\n")).toMatch(/rendererPipeline/);
-    expect(contract.aiUsageRules.join("\n")).toMatch(/Render Pipeline Inventory/);
-    expect(contract.aiUsageRules.join("\n")).toMatch(/sourceRepresentation/);
-    expect(contract.aiUsageRules.join("\n")).toMatch(/productRepresentation/);
-    expect(contract.aiUsageRules.join("\n")).toMatch(/previewRenderer/);
-    expect(contract.aiUsageRules.join("\n")).toMatch(/exportRenderer/);
     expect(contract.aiUsageRules).toContain(
-      "Choose renderer technique from product context, not convenience or novelty. Preserve reference renderer technology in reference-runtime-clone mode unless a concrete blocker and replacement acceptance tests are named.",
+      "Performance iterations require an exact reachable development fixture at normalized pressure 0.8 and fail with a configuration error when it is unavailable; they never fall back to maximum. Explicit full-performance checkpoints run the complete current matrix with maximum fixtures.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Do not switch renderer technology just because it seems more modern or faster. Preview and export may use different renderers only when the decision matrix explains why and export/copy remains product-quality.",
+      "Derive performance paths from rendererPipeline interaction invalidation. Scenarios must reference the canonical pathId and exact coversTargets, and equivalent controls that invalidate the same work share one path.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Choose renderer workload by product fidelity before choosing rendering technology: ASCII, glyph grids, code art, subtitles, typography, or monospace text products are text-output unless the product intentionally rasterizes them into per-pixel effects.",
+      "Compile development and maximum fixtures centrally from each derived path. Combined fixtures contain every path dimension, and measured inverse full-vector evidence is authored only for a custom dimension mapping or benchmark cost relationship.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Text-output and vector-output visible previews must preserve native output fidelity. Do not render a low-resolution offscreen canvas or texture and upscale it to the product size.",
+      "Browser performance proof must apply compiled fixture values through the real UI, observe every dimension after application, exercise the same preview or export path as the running app, and enforce the path's derived interaction profile.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Pixel-output renderers must treat WebGL/WebGPU as the default candidate even when the scene is static; Canvas 2D is allowed only when measured worst-case evidence shows the CPU path preserves quality and remains responsive.",
+      TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT,
     );
-    expect(contract.aiUsageRules).toContain(
-      "Procedural pixel renderers, shader-like effects, animated mesh gradients, and large exportable previews should use WebGL or WebGPU for pixel work instead of main-thread ImageData loops.",
+    expect(rules).toContain(
+      TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.functionalChangeEvidence,
     );
-    expect(contract.aiUsageRules).toContain(
-      "Detail-heavy Canvas 2D pixel/media renderers may stay on CPU only when rendererTechnique records measured stress evidence for rejecting WebGL/WebGPU; if the heavy media stress fails, move pixel work to GPU instead of lowering quality.",
+    expect(rules).toContain(
+      TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.renderScaleFidelity,
     );
-    expect(contract.aiUsageRules).toContain(
-      "WebGL and WebGPU renderers must initialize contexts, programs, shaders, pipelines, textures, and large buffers once, then update uniforms or stable buffers when controls change.",
+    expect(rules).toContain(
+      TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.complaintRouting,
     );
     expect(contract.aiUsageRules).toContain(
-      "For keyframe or playback renderers, texture upload and media decode must be keyed to source media/resource changes, not to timeline time or evaluated settings. Timeline-only updates must reuse decoded media and existing GPU resources.",
+      "Every export performance scenario must declare the exact panelActions actionValue, visible controlLabel, and completionEvidence it exercises; selectors, unrelated export actions, and injectable completion callbacks are not output evidence. The named browser scenario must resolve to test or it imported from @playwright/test, be statically registered at module scope or inside an executable test.describe, test.describe.serial, or test.describe.parallel suite, and directly await the matching unshadowed protected output-action helper in its root callback block without focus, skip, condition, or nesting; local test runners, uncalled or conditional test declarations, skipped/fixme suites, and runtime skip/fixme/fail annotations are invalid, and generated integrity protects the focused-test Playwright config.",
     );
     expect(contract.aiUsageRules).toContain(
       "Do not create WebGL/WebGPU contexts, shader programs, textures, or requestAnimationFrame loops directly in the React render path.",
@@ -167,18 +159,15 @@ describe("Toolcraft template component contracts: runtime and composition", () =
     expect(contract.aiUsageRules).toContain(
       "Animation loops must cancel scheduled frames during cleanup.",
     );
-    expect(contract.aiUsageRules).toContain(
-      "Animated preview renderers must suspend or coalesce non-essential animation work while the user drags, pans, pinches, zooms, or centers the canvas viewport, then resume from the correct timeline or autonomous time without changing the user's play/pause state.",
-    );
-    expect(contract.aiUsageRules).toContain(
-      "If a generated app uses ImageData, getImageData, or putImageData for procedural output, performance validation must fail unless rendererTechnique records measured WebGL/WebGPU comparison evidence that the CPU path preserves quality and responsiveness, or the renderer is moved to GPU.",
-    );
-    expect(contract.aiUsageRules).toContain(
-      "Performance matrices must declare rendererStrategy so tests can distinguish none, dom, svg, canvas-2d, webgl, and webgpu renderer paths.",
-    );
-    expect(contract.aiUsageRules).toContain(
-      "If a renderer cannot meet the budget, first optimize renderer technique, caching, invalidation, scheduling, and critical-path work. Only change exposed product ranges, work units, or controls after recording measured evidence that the requested quality ceiling is impossible; do not silently reduce product quality to pass budgets.",
-    );
+    expect(rules).toMatch(/rendererTechnique/);
+    expect(rules).toMatch(/rendererTechnique\.layers/);
+    expect(rules).toMatch(/rendererPipeline/);
+    expect(rules).toMatch(/sourceRepresentation/);
+    expect(rules).toMatch(/productRepresentation/);
+    expect(rules).toMatch(/previewRenderer/);
+    expect(rules).toMatch(/exportRenderer/);
+    expect(rules).not.toMatch(/1920x1080-equivalent|50_000|1_000\s+lines/);
+    expect(rules).not.toMatch(/rendererWorkload as|stressFixture is|workloadTargets/);
   });
 
   it("documents reference runtime clone mode as a tested composition contract", () => {

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

@@ -42,7 +42,7 @@ describe("Toolcraft template component contracts: runtime and composition", () =
       "Ordinary controls-panel section headers expose the runtime section reset action before the collapse button; it dispatches controls.resetTargets and restores only that section's control targets to their schema defaultValue.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Runtime Setup and ordinary controls-panel body sections use 8px top spacing and 24px bottom spacing for their control content. Sticky footer action sections keep their dedicated spacing.",
+      "Runtime Setup uses 12px top spacing so its first control row has equal top, left, and right insets. Ordinary controls-panel body sections keep 8px top spacing. Both use 24px bottom spacing; sticky footer action sections keep their dedicated spacing.",
     );
     expect(contract.aiUsageRules).toContain(
       "Broad section titles such as Flow, Icon, Shapes, Scene, Text, Typography, or Motion are only valid for small cohesive groups; use specific titles such as Flow Motion, Flow Geometry, Letter Burst, Shape Colors, Logo Glow, Logo Plate, or Text Block for larger groups.",

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

@@ -3,6 +3,17 @@ import { describe, expect, it } from "vitest";
 import { TOOLCRAFT_COMPONENT_CONTRACTS } from "./component-contracts";
 
 describe("Toolcraft template component contracts: runtime and composition", () => {
+  it("defines the runtime-owned controls-panel section navigation", () => {
+    expect(
+      TOOLCRAFT_COMPONENT_CONTRACTS.controlsPanel.capabilities,
+    ).toContain("section-navigation");
+    expect(
+      TOOLCRAFT_COMPONENT_CONTRACTS.controlsPanel.aiUsageRules,
+    ).toContain(
+      "An overflowing controls panel reveals runtime-owned section navigation only after a 300ms pointer dwell within its 12px inner-left padding strip, ending before control content begins. Fast crossings cancel the reveal; while visible, the popup and direct 8px corridor retain it by pointer geometry, remaining outside for 50ms starts a fast 120ms reduced-motion-aware exit before unmount, and reopening requires another dwell. It reuses PanelSurface and the shared ScrollFade, keeps its scrollbar at the right surface edge, shows position-aware top and bottom fades, uses a 12px list inset with zero horizontal item padding, sits 8px to the left centered on the content viewport, enters and exits with opacity and a 2px horizontal offset, renders 13px labels with 8px item gaps at foreground 50%, uses foreground 80% on hover and full foreground for the current item, renders no vertical item markers, jumps immediately to clicked sections, lets focused Arrow Up and Arrow Down wrap, focus, and immediately activate visible sections, includes Setup, and excludes sticky action sections.",
+    );
+  });
+
   it("preserves runtime panel commands for optional layers and timeline panels", () => {
     expect(TOOLCRAFT_COMPONENT_CONTRACTS.layersPanel.commands).toContain("layers.reorder");
     expect(TOOLCRAFT_COMPONENT_CONTRACTS.layersPanel.capabilities).toContain("selection");
@@ -25,7 +36,7 @@ describe("Toolcraft template component contracts: runtime and composition", () =
       "Layer browser coverage must use real LayersPanel rows and buttons, not direct layers.* command dispatch.",
     );
     expect(TOOLCRAFT_COMPONENT_CONTRACTS.layersPanel.aiUsageRules).toContain(
-      "Layer-enabled custom renderers need layers.interactions viewport-stability coverage around real selection, visibility, reorder or grouping, and selected-layer output checks.",
+      "Layer-enabled custom renderers need layers.interactions coverage around real selection, visibility, reorder or grouping, and selected-layer output checks.",
     );
 
     expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.commands).toContain(
@@ -51,7 +62,7 @@ describe("Toolcraft template component contracts: runtime and composition", () =
       '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.',
     );
     expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
-      "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.",
     );
     expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
       "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.",
@@ -123,7 +134,10 @@ describe("Toolcraft template component contracts: runtime and composition", () =
       'Custom timeline UI is allowed only for explicit referenceTimeline.mode "custom-reference-timeline" transfers with browser-backed referenceTimelineCoverage.',
     );
     expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
-      'When panels.timeline is enabled, runtime inserts a Setup switch labeled "Timeline" as the last runtime setup control after Resolution scale.',
+      "Runtime Setup places the standard Background switch beside Infinity canvas immediately after settings transfer, then Background color and finite sizing; Timeline is the final Setup control when enabled.",
+    );
+    expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
+      "Timeline and Infinity canvas are self-explanatory runtime mode switches and do not render help icons.",
     );
     expect(TOOLCRAFT_COMPONENT_CONTRACTS.timelinePanel.aiUsageRules).toContain(
       "The Timeline Setup switch controls only compact versus extended runtime presentation: off shows the compact Play-only transport, on shows the extended timeline with scrubber, duration, loop, and keyframe UI. It must not stop playback, change keyframes, affect export, enter product values, or be reset by Reset controls/settings transfer.",

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

@@ -4,6 +4,7 @@ import {
   TOOLCRAFT_COMPONENT_CONTRACTS,
   getToolcraftComponentContract,
 } from "./component-contracts";
+import { TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY } from "./performance-verification-policy";
 
 describe("Toolcraft template component contracts: runtime and composition", () => {
   it("keeps toolbar and controls panels behind PanelHost with their snap defaults", () => {
@@ -20,7 +21,7 @@ describe("Toolcraft template component contracts: runtime and composition", () =
       "Do not add app-level Cmd/Ctrl+Z, Cmd/Ctrl+Shift+Z, or Ctrl+Y listeners; use toolbar history and runtime commands.",
     );
     expect(TOOLCRAFT_COMPONENT_CONTRACTS.toolbar.aiUsageRules).toContain(
-      "Undo/redo keyboard shortcuts must not fire while the user is typing into inputs, textareas, selects, or contentEditable value labels.",
+      "Undo/redo keyboard shortcuts stay native while the user edits text-entry inputs, textareas, selects, or contentEditable value labels; focused range, checkbox, and other non-text inputs use Toolcraft history.",
     );
 
     expect(TOOLCRAFT_COMPONENT_CONTRACTS.controlsPanel.requiredWrapper).toBe("PanelHost");
@@ -36,11 +37,29 @@ describe("Toolcraft template component contracts: runtime and composition", () =
     expect(contract.historyPolicy).toBe("patch");
     expect(contract.visualComponent).toBe("CanvasShell");
     expect(contract.commands).toContain("canvas.setSize");
+    expect(contract.commands).toContain("canvas.setMode");
     expect(contract.commands).toContain("canvas.panBy");
     expect(contract.commands).toContain("canvas.setOffset");
     expect(contract.commands).toContain("media.import");
+    expect(contract.commands).toContain("media.importBatch");
     expect(contract.commands).toContain("media.transform");
     expect(contract.capabilities).toContain("editable-size");
+    expect(contract.capabilities).toContain("infinity-canvas");
+    expect(contract.aiUsageRules).toContain(
+      "Editable-output apps expose the runtime Infinity canvas switch before finite sizing controls; generated apps do not recreate or shadow that mode in product state.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
     expect(contract.aiUsageRules).toContain(
       "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.",
     );
@@ -78,13 +97,10 @@ describe("Toolcraft template component contracts: runtime and composition", () =
       "Aspect ratio presets are the only interaction that may resize both canvas dimensions from a preset; manual size inputs are exact output dimensions.",
     );
     expect(contract.aiUsageRules).toContain(
-      "For non-vector raster, Canvas 2D, WebGL, and WebGPU previews, set canvas.renderScale: true so the runtime adds Resolution scale after canvas sizing. The scale changes backing pixels from 1 to 2 without changing visible canvas size, and adding/enabling it requires targeted browser evidence that the canvas stays responsive at the selected scale.",
-    );
-    expect(contract.aiUsageRules).toContain(
-      "After enabling canvas.renderScale, verify that canvas preview stays responsive while dragging sliders and other high-frequency controls at the selected scale.",
+      "For non-vector raster, Canvas 2D, WebGL, and WebGPU previews, set canvas.renderScale: true so the runtime adds Resolution scale after canvas sizing. The scale changes backing pixels from 1 to 2 without changing visible canvas size.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Performance fixes for canvas.renderScale must preserve the selected visual quality; do not silently downsample, stretch a lower-resolution backing canvas, blur output, or clamp canvas.renderScale below the user's chosen value to pass budgets.",
+      TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.renderScaleFidelity,
     );
     expect(contract.aiUsageRules).toContain(
       "Do not enable canvas.renderScale for DOM/SVG/vector-native previews; preserve vector fidelity through native vector rendering instead of raster supersampling.",
@@ -139,10 +155,10 @@ describe("Toolcraft template component contracts: runtime and composition", () =
       "App-authored sections must not declare runtime Setup targets such as runtime.settingsTransfer, canvas.aspectRatio, canvas.size.width, canvas.size.height, canvas.renderScale, or panels.timeline.extended; those controls never suppress the mandatory runtime Setup controls.",
     );
     expect(contract.aiUsageRules).toContain(
-      "When editable-output canvas sizing is enabled, the first visible Setup runtime section contains Export Settings, Import Settings, Aspect ratio, Canvas width, Canvas height, and optional Resolution scale in that order.",
+      "Runtime Setup places the standard Background switch beside Infinity canvas immediately after settings transfer, then Background color and finite sizing; Timeline is the final Setup control when enabled.",
     );
     expect(contract.aiUsageRules).toContain(
-      "When panels.timeline is enabled, Setup appends the Timeline switch as the last control; when panels.timeline is omitted, the Timeline switch must not appear.",
+      "Timeline and Infinity canvas are self-explanatory runtime mode switches and do not render help icons.",
     );
   });
 });