@pixel-point/toolcraft 0.0.15 → 0.0.17

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

@@ -1,9 +1,32 @@
 import { panel } from "./component-contract-builders";
+import {
+  TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY,
+  TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT,
+} from "./performance-verification-policy";
 import type { ToolcraftComponentContract } from "./types";
+
+const controlsPanelContract = panel(
+  "controlsPanel",
+  "ControlsPanel",
+  "right",
+  ["left", "right"],
+  "handle",
+);
+
+const runtimeSetupModeRowRule =
+  "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.";
+const runtimeSetupModeHelpRule =
+  "Timeline and Infinity canvas are self-explanatory runtime mode switches and do not render help icons.";
+
 export const TOOLCRAFT_RUNTIME_COMPONENT_CONTRACTS = {
   canvas: {
     aiUsageRules: [
       "Choose canvas.sizing.mode from product context instead of copying a universal 1024px artboard.",
+      "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.",
+      "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 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.",
       "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.",
@@ -17,13 +40,20 @@ export const TOOLCRAFT_RUNTIME_COMPONENT_CONTRACTS = {
       "The runtime Canvas width and Canvas height block uses the mandatory headerless Setup controls block; do not add a separate Canvas section label above these fields.",
       "When the user manually edits Canvas width or Canvas height, the runtime keeps the typed dimension, keeps the other dimension unchanged, switches Aspect ratio to Custom, and shows the reduced current ratio in the custom ratio inputs.",
       "Aspect ratio presets are the only interaction that may resize both canvas dimensions from a preset; manual size inputs are exact output dimensions.",
-      "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.",
-      "After enabling canvas.renderScale, verify that canvas preview stays responsive while dragging sliders and other high-frequency controls at the selected scale.",
-      "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.",
+      "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.",
+      TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY.renderScaleFidelity,
       "Do not enable canvas.renderScale for DOM/SVG/vector-native previews; preserve vector fidelity through native vector rendering instead of raster supersampling.",
     ],
-    capabilities: ["drag", "zoom", "radar", "upload", "editable-size"],
+    capabilities: [
+      "drag",
+      "zoom",
+      "radar",
+      "upload",
+      "editable-size",
+      "infinity-canvas",
+    ],
     commands: [
+      "canvas.setMode",
       "canvas.setSize",
       "canvas.panBy",
       "canvas.setOffset",
@@ -33,6 +63,7 @@ export const TOOLCRAFT_RUNTIME_COMPONENT_CONTRACTS = {
       "canvas.zoomReset",
       "media.delete",
       "media.import",
+      "media.importBatch",
       "media.reorder",
       "media.transform",
     ],
@@ -70,9 +101,10 @@ export const TOOLCRAFT_RUNTIME_COMPONENT_CONTRACTS = {
       "Do not hand-roll settings import/export through app routes, hidden file inputs, or panelActions.",
       "Settings transfer appears in the first visible headerless Setup controls-panel block; it imports and exports control values, canvas size, and timeline state.",
       "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.",
-      "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.",
-      "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.",
+      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"],
@@ -98,9 +130,12 @@ export const TOOLCRAFT_RUNTIME_COMPONENT_CONTRACTS = {
       "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/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.",
       "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.",
       "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.",
+      "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.",
       "If an entity cannot be tested against a product-level observable, remove it from the app schema or ask whether it is required.",
     ],
     capabilities: ["acceptance-tests", "product-output-verification"],
@@ -114,44 +149,40 @@ export const TOOLCRAFT_RUNTIME_COMPONENT_CONTRACTS = {
   },
   performanceAcceptance: {
     aiUsageRules: [
-      "Custom renderers must define performance budgets for media import, preview updates, control drags, and export/copy before implementation.",
-      "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.",
-      "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.",
-      "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.",
-      "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.",
-      "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.",
-      "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.",
-      "Expensive renderers must cache decoded media, source pixels, glyph atlases, gradients, and other reusable inputs by media id, canvas size, and stable control keys.",
-      "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.",
-      "Performance matrices must declare rendererWorkload as none, simple-composition, text-output, vector-output, or pixel-output.",
-      "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.",
-      "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.",
-      "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.",
-      "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.",
-      "Renderer specs must include a Renderer Technique Decision Matrix with sourceRepresentation, productRepresentation, previewRenderer, exportRenderer, rendererWorkload, rendererStrategy, whyNotAlternativeStrategies, fidelityRisks, and performanceRisks.",
+      "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.",
+      "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.",
+      "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.",
+      "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.",
+      "Derive schema-backed boundaries from the schema and derive non-schema boundaries from the product's enforced runtime or input limits; authored performance fixtures must not redefine those limits.",
+      "Declare fixtureAdapters for every workload dimension so compiled numeric values can be applied and observed exactly; interactive boundaries require a fully guaranteed interactive profile and batch boundaries require batch completion and responsiveness profiles.",
+      "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.",
+      "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.",
+      "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.",
+      "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.",
+      "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.",
+      "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.",
+      "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.",
+      "Workload acceptance must assert the intended product result, not only a generic hash difference or an isolated helper-state mutation.",
+      "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.",
+      "High-frequency interactions must coalesce redundant work, cancel stale asynchronous work, and preserve retained resources according to the declared pass lifecycle instead of rebuilding upstream resources on every update.",
+      TOOLCRAFT_PERFORMANCE_VERIFICATION_POLICY_TEXT,
+      "When an interaction misses budget, diagnose the assessed passes, update frequency, invalidation, resource lifecycle, scheduling, and execution location before changing output quality or product boundaries.",
+      "Renderer specs must include a Renderer Technique Decision Matrix with sourceRepresentation, productRepresentation, previewRenderer, exportRenderer, rendererStrategy, whyNotAlternativeStrategies, fidelityRisks, and performanceRisks.",
       "Custom renderer apps must mirror the Renderer Technique Decision Matrix in typed rendererTechnique config so validation can reject contradictory renderer choices.",
-      "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.",
-      "Custom renderer apps must declare rendererPipeline with render passes, cache keys, execution location, preview/export quality, and interaction invalidation before implementation.",
-      "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.",
-      "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.",
-      "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.",
+      "Custom renderer specs must include a Renderer Layer Inventory and mirror it in typed rendererTechnique.layers so output, overlays, and export composition remain independently testable.",
+      "Render Pipeline Inventory must explain which runtime targets invalidate each pass; high-frequency interactions must not invalidate retained upstream work unless the declared input actually changes its result.",
+      "Cache-sensitive passes must declare concrete cache keys so tests can reject full recomputation on unrelated interactions.",
       "Editing handles must be DOM/SVG overlays, excluded from export, and written through runtime state instead of being drawn into the product raster layer.",
       "Product foreground and editing handle renderer layers must declare uiSelector so browser tests can verify the visible layer exists.",
       'productRepresentation "mixed" is valid only when rendererTechnique.layers proves at least two different content families.',
       "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.",
       "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.",
-      "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.",
-      "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.",
-      "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.",
-      "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.",
-      "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.",
       "WebGL and WebGPU renderers must initialize contexts, programs, shaders, pipelines, textures, and large buffers once, then update uniforms or stable buffers when controls change.",
       "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.",
       "Do not create WebGL/WebGPU contexts, shader programs, textures, or requestAnimationFrame loops directly in the React render path.",
       "Animation loops must cancel scheduled frames during cleanup.",
       "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.",
-      "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.",
-      "Performance matrices must declare rendererStrategy so tests can distinguish none, dom, svg, canvas-2d, webgl, and webgpu renderer paths.",
+      "Performance matrices must declare rendererStrategy so assessment and benchmark evidence refer to the implementation that actually runs.",
       "Browser verification must interact with the actual UI, exercise worst-case control values, and fail if the app freezes, creates runaway render loops, drops canvas zoom/offset, or misses the performance budget.",
       "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.",
     ],
@@ -215,7 +246,7 @@ export const TOOLCRAFT_RUNTIME_COMPONENT_CONTRACTS = {
       "Controls-panel section expand and collapse uses the standard runtime height/opacity animation; generated apps must not replace it with instant custom section visibility.",
       "Controls-panel section collapsed/expanded state persists as a runtime UI preference per app. It is not undo/redo state, not settings import/export state, and Reset controls must not clear it. Runtime Setup is not collapsible; sticky footer Export sections are not collapsible.",
       "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.",
-      "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.",
       "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.",
       "Section titles in one controls panel must be unique.",
       "Use section titles, option labels, tests, or renderer/spec prose for details instead of long field labels.",
@@ -237,7 +268,17 @@ export const TOOLCRAFT_RUNTIME_COMPONENT_CONTRACTS = {
     stateMode: "runtime-owned",
     visualComponent: "ControlFieldLabel",
   },
-  controlsPanel: panel("controlsPanel", "ControlsPanel", "right", ["left", "right"], "handle"),
+  controlsPanel: {
+    ...controlsPanelContract,
+    aiUsageRules: [
+      ...controlsPanelContract.aiUsageRules,
+      "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.",
+    ],
+    capabilities: [
+      ...controlsPanelContract.capabilities,
+      "section-navigation",
+    ],
+  },
   layersPanel: {
     ...panel("layersPanel", "LayersPanel", "left", ["left", "right"], "handle"),
     aiUsageRules: [
@@ -249,7 +290,7 @@ export const TOOLCRAFT_RUNTIME_COMPONENT_CONTRACTS = {
       "Layer-enabled apps need layerCoverage acceptance for selection, visibility, reorder, and grouping.",
       "Every selectedLayer.* control needs selected-layer-controls acceptance proving it edits the currently selected layer output.",
       "Layer browser coverage must use real LayersPanel rows and buttons, not direct layers.* command dispatch.",
-      "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.",
     ],
     capabilities: [
       "draggable",
@@ -284,7 +325,7 @@ export const TOOLCRAFT_RUNTIME_COMPONENT_CONTRACTS = {
       "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.",
@@ -304,7 +345,8 @@ export const TOOLCRAFT_RUNTIME_COMPONENT_CONTRACTS = {
       "Do not put Pause or Resume in panelActions; playback belongs to TimelinePanel transport controls.",
       "Do not replace TimelinePanel with an app-level playback, transport, or timeline panel to avoid runtime performance issues; fix the Toolcraft runtime clock/state path instead.",
       'Custom timeline UI is allowed only for explicit referenceTimeline.mode "custom-reference-timeline" transfers with browser-backed referenceTimelineCoverage.',
-      'When panels.timeline is enabled, runtime inserts a Setup switch labeled "Timeline" as the last runtime setup control after Resolution scale.',
+      runtimeSetupModeRowRule,
+      runtimeSetupModeHelpRule,
       "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.",
       "Playback-only timelines stay collapsed and do not show keyframe diamonds or expanded keyframe rows.",
       "If timeline verification fails, wire the renderer to runtime timeline state or remove panels.timeline.",
@@ -337,7 +379,7 @@ export const TOOLCRAFT_RUNTIME_COMPONENT_CONTRACTS = {
     aiUsageRules: [
       "Toolbar history owns Undo and Redo buttons plus runtime keyboard shortcuts.",
       "Do not add app-level Cmd/Ctrl+Z, Cmd/Ctrl+Shift+Z, or Ctrl+Y listeners; use toolbar history and runtime commands.",
-      "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.",
     ],
     capabilities: [
       "draggable",

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

@@ -21,6 +21,7 @@ describe("Toolcraft template component contracts: core", () => {
       "code",
       "select",
       "segmented",
+      "tabs",
       "switch",
       "checkbox",
       "actions",
@@ -29,6 +30,7 @@ describe("Toolcraft template component contracts: core", () => {
       "colorOpacity",
       "palette",
       "vector",
+      "orientationGizmo",
       "color",
       "gradient",
       "fontPicker",
@@ -53,6 +55,7 @@ describe("Toolcraft template component contracts: core", () => {
       "rangeSlider",
       "select",
       "segmented",
+      "tabs",
       "switch",
       "checkbox",
       "text",
@@ -63,6 +66,7 @@ describe("Toolcraft template component contracts: core", () => {
       "fontPicker",
       "curves",
       "vector",
+      "orientationGizmo",
       "fileDrop",
       "imagePicker",
       "palette",
@@ -84,7 +88,8 @@ describe("Toolcraft template component contracts: core", () => {
 
   it("documents high-confidence owner controls and their bad substitutes", () => {
     const gradient = getToolcraftComponentContract("gradient").decisionCatalog;
-    const fontPicker = getToolcraftComponentContract("fontPicker").decisionCatalog;
+    const fontPicker =
+      getToolcraftComponentContract("fontPicker").decisionCatalog;
     const colorOpacity =
       getToolcraftComponentContract("colorOpacity").decisionCatalog;
     const customControl =

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

@@ -62,7 +62,7 @@ describe("Toolcraft template component contracts: visual controls", () => {
       'Use variant: "colorBalance" for paired color-balance axes such as cyan/red and blue/yellow correction.',
     );
     expect(contract.aiUsageRules).toContain(
-      'Use the default vector variant for spatial values such as position, offset, direction, focus, anchor, and light direction.',
+      "Use the default vector variant for spatial values such as position, offset, direction, focus, anchor, and light direction.",
     );
     expect(contract.aiUsageRules).toContain(
       'Default spatial vector pads use coordinateMode: "screen": dragging left/up makes vector.x and vector.y smaller so canvas objects move left/up without renderer-side Y inversion.',
@@ -82,6 +82,43 @@ describe("Toolcraft template component contracts: visual controls", () => {
     expect(contract.aiUsageRules).toContain(
       "Vector is a compound control; acceptance must prove vector.x and vector.y both affect the product output and that the vector represents a user-authored stable two-axis parameter rather than current animation, input, or simulation state.",
     );
+    expect(contract.aiUsageRules).toContain(
+      "Do not use Vector for a camera orbit, object orbit, or a visually flat object that users can rotate through three-dimensional space; use OrientationGizmo and direct model drag instead.",
+    );
+  });
+
+  it("assigns three-dimensional rotation to the runtime orientation gizmo", () => {
+    const contract = getToolcraftComponentContract("orientationGizmo");
+
+    expect(contract.labelPolicy).toBe("hidden");
+    expect(contract.decisionCatalog?.strictness).toBe("exact-owner");
+    expect(contract.decisionCatalog?.useWhen).toContain(
+      "Use OrientationGizmo whenever the user can rotate a visible canvas model through three-dimensional space, including a volumetric 3D object or a visually flat object with a 3D orbit.",
+    );
+    expect(contract.decisionCatalog?.doNotReplaceWith).toContain(
+      "Do not replace OrientationGizmo with Vector, paired sliders, segmented axis buttons, or a product-authored custom gizmo.",
+    );
+    expect(contract.decisionCatalog?.acceptableAlternatives).toContain(
+      'Use viewInteraction mode "fixed-camera" only when an explicit user request or inspected reference requires fixed framing; choosing a fixed camera merely because rotation was not requested is not an accepted alternative.',
+    );
+    expect(contract.aiUsageRules).toContain(
+      'Declare typed product readiness viewInteraction before controls or renderer code. A visible editable spatial scene defaults to mode "orbit"; do not make the scene non-rotatable first and then use that implementation choice to omit OrientationGizmo.',
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Use useToolcraftModelOrbitInteraction in the product renderer. Supply a hitTest callback based on actual visible geometry; runtime must not guess product triangles, alpha, paths, or occlusion.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Interaction priority is fixed at pointer-down: higher-priority product items may claim first, a visible-model hit orbits, and a miss remains untouched so CanvasShell pans the canvas. Modified primary presses and non-primary presses are not claimed.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Multiple orientationGizmo declarations are allowed only for statically provable mutually exclusive modes; runtime rejects any state that makes more than one canvas orientation handle visible.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Gizmo drag, snap animation, and direct model orbit share target-scoped runtime ownership. A newer interaction, reset, undo/redo, or another write to the target cancels stale work before it can overwrite current state.",
+    );
+    expect(contract.decisionCatalog?.requiredAcceptance).toContain(
+      "Use the protected model-drag and canvas-miss-pan recipes to prove a visible-model hit changes the shared pose/output while a miss pans without changing either.",
+    );
   });
 
   it("documents Palette as a constrained design-token color control", () => {
@@ -132,22 +169,24 @@ describe("Toolcraft template component contracts: visual controls", () => {
     const curves = getToolcraftComponentContract("curves");
     const anchorGrid = getToolcraftComponentContract("anchorGrid");
     const channelMixer = getToolcraftComponentContract("channelMixer");
-    const appEntityAcceptance = getToolcraftComponentContract("appEntityAcceptance");
+    const appEntityAcceptance = getToolcraftComponentContract(
+      "appEntityAcceptance",
+    );
 
     expect(color.aiUsageRules).toContain(
       "Product-output apps always expose renderer-owned output background color as a schema color target such as appearance.background or scene.background.",
     );
     expect(color.aiUsageRules).toContain(
-      'Pair renderer-owned output background color with export.includeBackground in one Background section directly before export settings. Use an equal-width inline row with the export.includeBackground Switch labeled "Include" on the left and the background Color parameter with label false on the right; each control occupies one half of the row.',
+      'Declare renderer-owned output background color with export.includeBackground in one authored Background source section. Runtime normalizes them into Setup: a Switch labeled "Background" sits left of Infinity canvas in an equal-width row, Background color renders below, and Timeline remains the final Setup control.',
     );
     expect(color.aiUsageRules).toContain(
-      "Preview, PNG export, and video export must read the runtime background color value instead of hardcoding that background in CSS, Canvas fillStyle, or WebGL clearColor. export.includeBackground controls live preview product background and PNG alpha; it must not make the Toolcraft canvas shell/backing or video output transparent.",
+      "Preview, PNG export, video export, and the infinite runtime viewport must read the runtime background color value instead of hardcoding that background in CSS, Canvas fillStyle, or WebGL clearColor. Product renderers suppress their bounded background in Infinity mode while CanvasShell fills the complete viewport; export.includeBackground controls live preview product background and PNG alpha, and disabling it restores finite mode instead of leaving a transparent infinite workspace.",
     );
     expect(color.aiUsageRules).toContain(
       "When one short numeric/text field and one Color field configure the same entity, keep them in one two-column inline layout group.",
     );
     expect(color.aiUsageRules).toContain(
-      'Mixed inline rows usually require visible labels on both controls. Toggle-plus-parameter rows are the section-owned exception: keep the Switch/Checkbox label visible and set the non-toggle parameter label to false; if the parameter label is needed, stack the controls instead. All 50/50 inline rows use the same horizontal column gap as paired Select controls. The required Background row uses the Switch label "Include" and sets the background Color control label to false. Palette variation color banks are the other exception when the group/section label already names the color bank.',
+      "Mixed inline rows usually require visible labels on both controls. Toggle-plus-parameter rows are the section-owned exception: keep the Switch/Checkbox label visible and set the non-toggle parameter label to false; if the parameter label is needed, stack the controls instead. All 50/50 inline rows use the same horizontal column gap as paired Select controls. Palette variation color banks are the other exception when the group/section label already names the color bank.",
     );
     expect(color.aiUsageRules).toContain(
       "Plain Color popovers must not show opacity controls. If opacity is editable, use ColorOpacity instead.",

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

@@ -28,7 +28,7 @@ export const TOOLCRAFT_VISUAL_COMPONENT_CONTRACTS = {
     }),
     aiUsageRules: [
       "Use ColorOpacity when one product entity needs both a color and an opacity value, such as text color, shadow color, glow color, overlay color, or stroke color.",
-      "Do not split ColorOpacity into a separate Color plus Slider/Input for opacity; use type: \"colorOpacity\" so the color popover and percent input stay visually connected.",
+      'Do not split ColorOpacity into a separate Color plus Slider/Input for opacity; use type: "colorOpacity" so the color popover and percent input stay visually connected.',
       "ColorOpacity is the only color control variant that may expose opacity in the color picker popover; plain Color popovers hide opacity controls.",
       "Use one object value with hex and opacity. Renderers and exports must consume both parts.",
       "Do not place ColorOpacity in inline two-column layout groups. If either color control has opacity, keep the controls stacked.",
@@ -100,10 +100,12 @@ export const TOOLCRAFT_VISUAL_COMPONENT_CONTRACTS = {
       doNotReplaceWith: [
         "Do not replace Vector with two unrelated sliders or text inputs when direct two-axis editing is the product interaction.",
         "Do not replace animation, keyboard input, pointer input, physics, timeline phase, velocity, or simulated pose state with Vector just because the internal value has x/y coordinates.",
+        "Do not use Vector for camera orbit, object orbit, or any user-rotatable three-dimensional view.",
       ],
       acceptableAlternatives: [
         "Use two numeric text fields only when exact numeric entry is the primary product requirement.",
         "Use timeline, keyboard/pointer handlers, motion sliders, path/step controls, or renderer simulation state when movement is generated by animation or user input rather than authored as a stable panel value.",
+        "Use OrientationGizmo when a visible model can be rotated in 3D.",
       ],
       layoutConstraints: [
         "One vector renders as a square pad; multiple vectors render compact pads.",
@@ -122,7 +124,7 @@ export const TOOLCRAFT_VISUAL_COMPONENT_CONTRACTS = {
       'Use variant: "colorBalance" for paired color-balance axes such as cyan/red and blue/yellow correction.',
       'Use variant: "chromaOffset" for RGB/chromatic offset vectors where the X/Y movement controls channel separation.',
       'Use variant: "toneBias" for split-tone, duotone, or color-grading vectors where both axes describe tone or hue bias.',
-      'Use the default vector variant for spatial values such as position, offset, direction, focus, anchor, and light direction.',
+      "Use the default vector variant for spatial values such as position, offset, direction, focus, anchor, and light direction.",
       'Default spatial vector pads use coordinateMode: "screen": dragging left/up makes vector.x and vector.y smaller so canvas objects move left/up without renderer-side Y inversion.',
       "Vector pad value labels render compact rounded coordinates. Do not expose raw floating-point strings such as -0.07070312499999998 in the controls panel.",
       "Double-clicking a vector pad resets both axes to the control default through the normal runtime value update, matching section header reset semantics; if no default is defined, the fallback is 0,0. Do not add a separate custom reset UI for this basic pad reset behavior.",
@@ -130,17 +132,66 @@ export const TOOLCRAFT_VISUAL_COMPONENT_CONTRACTS = {
       'Use coordinateMode: "cartesian" only when the product intentionally exposes mathematical Y-up coordinates instead of canvas/screen movement.',
       "Do not add custom vector sizing props in generated schemas; choose the number, variant, and section grouping from product need and let the runtime size the pads.",
       "Vector is a compound control; acceptance must prove vector.x and vector.y both affect the product output and that the vector represents a user-authored stable two-axis parameter rather than current animation, input, or simulation state.",
+      "Do not use Vector for a camera orbit, object orbit, or a visually flat object that users can rotate through three-dimensional space; use OrientationGizmo and direct model drag instead.",
+    ],
+  },
+  orientationGizmo: {
+    ...control(
+      "orientationGizmo",
+      "ToolcraftOrientationGizmo",
+      "grouped",
+      "hidden",
+    ),
+    decisionCatalog: decisionCatalog({
+      strictness: "exact-owner",
+      ownsValueModel: [
+        "camera orbit pose",
+        "object orbit pose",
+        "user-authored three-dimensional view orientation",
+        "signed-axis orientation snap",
+      ],
+      useWhen: [
+        "Use OrientationGizmo whenever the user can rotate a visible canvas model through three-dimensional space, including a volumetric 3D object or a visually flat object with a 3D orbit.",
+      ],
+      doNotReplaceWith: [
+        "Do not replace OrientationGizmo with Vector, paired sliders, segmented axis buttons, or a product-authored custom gizmo.",
+      ],
+      acceptableAlternatives: [
+        'Use viewInteraction mode "fixed-camera" only when an explicit user request or inspected reference requires fixed framing; choosing a fixed camera merely because rotation was not requested is not an accepted alternative.',
+        'Use viewInteraction mode "timeline-camera" only when an explicit user request or inspected reference owns an authored camera path and Toolcraft timeline intent drives it.',
+        "Use Vector for a stable authored X/Y parameter that does not represent three-dimensional orientation.",
+      ],
+      layoutConstraints: [
+        "OrientationGizmo is a runtime-owned 70px canvas handle fixed 16px from the canvas viewport's left and bottom edges; it does not render duplicate controls in the panel.",
+        "Declare it in the semantic section that owns the model or view so section/global reset includes the orientation target; do not create a panel section containing only the portal control.",
+        "At most one OrientationGizmo may be visible at a time. Multiple schema declarations are valid only when their combined section/control visibility conditions are statically provable as mutually exclusive.",
+      ],
+      requiredAcceptance: [
+        "Use the protected orientation axis-drag and axis-snap recipes to prove the shared pose and visible product output change while canvas viewport offsets stay fixed.",
+        "Use the protected model-drag and canvas-miss-pan recipes to prove a visible-model hit changes the shared pose/output while a miss pans without changing either.",
+        "Prove preview, geometry hit testing, PNG, and video consume the same orientation pose, and use the protected canvas export-clean recipe to prove the gizmo stays out of exported output.",
+        "Use the protected undo/reset recipe to prove one gesture is one history step, redo restores it, and section/global reset restores the declared default pose.",
+      ],
+    }),
+    aiUsageRules: [
+      'Declare typed product readiness viewInteraction before controls or renderer code. A visible editable spatial scene defaults to mode "orbit"; do not make the scene non-rotatable first and then use that implementation choice to omit OrientationGizmo.',
+      'Whenever a visible canvas model can be rotated in 3D, declare type: "orientationGizmo" with one non-keyframeable orientation target for the active model mode. This includes flat artwork or planes when the product exposes three-dimensional rotation.',
+      "Multiple orientationGizmo declarations are allowed only for statically provable mutually exclusive modes; runtime rejects any state that makes more than one canvas orientation handle visible.",
+      "Do not use Vector as a substitute for three-dimensional orientation and do not copy a custom gizmo into product code.",
+      "The orientation value is { position: [x, y, z], up: [x, y, z] }. Use one non-degenerate default pose and read it through readToolcraftOrientationPose.",
+      "Use useToolcraftModelOrbitInteraction in the product renderer. Supply a hitTest callback based on actual visible geometry; runtime must not guess product triangles, alpha, paths, or occlusion.",
+      "Interaction priority is fixed at pointer-down: higher-priority product items may claim first, a visible-model hit orbits, and a miss remains untouched so CanvasShell pans the canvas. Modified primary presses and non-primary presses are not claimed.",
+      "Gizmo drag, snap animation, and direct model orbit share target-scoped runtime ownership. A newer interaction, reset, undo/redo, or another write to the target cancels stale work before it can overwrite current state.",
+      "Gizmo drag, direct model drag, preview, raycasting, reset/history, PNG, and video must all consume the same runtime target. Do not keep a second local Euler or camera pose.",
+      "The gizmo is editor chrome: it stays fixed under canvas pan/zoom/radar and is excluded from every export.",
+      "Orientation invalidation must touch only renderer passes that consume the pose, and direct orbit must remain live and responsive at the declared interactive workload without reducing preview quality.",
     ],
   },
   color: {
     ...control("color", "Color", "standalone", "component-owned"),
     decisionCatalog: decisionCatalog({
       strictness: "best-fit",
-      ownsValueModel: [
-        "single free color",
-        "hex color value",
-        "role color",
-      ],
+      ownsValueModel: ["single free color", "hex color value", "role color"],
       useWhen: [
         "Use Color for one editable free color without opacity or gradient stops.",
       ],
@@ -176,11 +227,11 @@ export const TOOLCRAFT_VISUAL_COMPONENT_CONTRACTS = {
       "Never use generic Color or Colors as a generated section title. If no meaningful color role exists and the colors are just basic colors, use a neutral section title such as Appearance instead of omitting the title.",
       "Do not split a grouped object section into a separate generated Color section; if the color role is unclear, ask the user before implementation.",
       "When one short numeric/text field and one Color field configure the same entity, keep them in one two-column inline layout group.",
-      'Mixed inline rows usually require visible labels on both controls. Toggle-plus-parameter rows are the section-owned exception: keep the Switch/Checkbox label visible and set the non-toggle parameter label to false; if the parameter label is needed, stack the controls instead. All 50/50 inline rows use the same horizontal column gap as paired Select controls. The required Background row uses the Switch label "Include" and sets the background Color control label to false. Palette variation color banks are the other exception when the group/section label already names the color bank.',
+      "Mixed inline rows usually require visible labels on both controls. Toggle-plus-parameter rows are the section-owned exception: keep the Switch/Checkbox label visible and set the non-toggle parameter label to false; if the parameter label is needed, stack the controls instead. All 50/50 inline rows use the same horizontal column gap as paired Select controls. Palette variation color banks are the other exception when the group/section label already names the color bank.",
       "Plain Color popovers must not show opacity controls. If opacity is editable, use ColorOpacity instead.",
       "Product-output apps always expose renderer-owned output background color as a schema color target such as appearance.background or scene.background.",
-      'Pair renderer-owned output background color with export.includeBackground in one Background section directly before export settings. Use an equal-width inline row with the export.includeBackground Switch labeled "Include" on the left and the background Color parameter with label false on the right; each control occupies one half of the row.',
-      "Preview, PNG export, and video export must read the runtime background color value instead of hardcoding that background in CSS, Canvas fillStyle, or WebGL clearColor. export.includeBackground controls live preview product background and PNG alpha; it must not make the Toolcraft canvas shell/backing or video output transparent.",
+      'Declare renderer-owned output background color with export.includeBackground in one authored Background source section. Runtime normalizes them into Setup: a Switch labeled "Background" sits left of Infinity canvas in an equal-width row, Background color renders below, and Timeline remains the final Setup control.',
+      "Preview, PNG export, video export, and the infinite runtime viewport must read the runtime background color value instead of hardcoding that background in CSS, Canvas fillStyle, or WebGL clearColor. Product renderers suppress their bounded background in Infinity mode while CanvasShell fills the complete viewport; export.includeBackground controls live preview product background and PNG alpha, and disabling it restores finite mode instead of leaving a transparent infinite workspace.",
       "Render multiple related color fields in one section with at most two colors per row.",
       "If a multi-color bank has an odd trailing plain Color, keep that last Color at half width; only ColorOpacity or intentionally full-width compound controls occupy a full row.",
     ],
@@ -261,7 +312,7 @@ export const TOOLCRAFT_VISUAL_COMPONENT_CONTRACTS = {
     }),
     aiUsageRules: [
       "FontPicker owns the font preview select, virtualized font popup, category filters, search, preview loading, font-weight select, font-size input, text-case select, text color/opacity control, letter-spacing slider, and line-height slider.",
-      "Do not recreate FontPicker with a plain Select plus separate sliders; use type: \"fontPicker\" so the popup mechanics and footer controls stay intact.",
+      'Do not recreate FontPicker with a plain Select plus separate sliders; use type: "fontPicker" so the popup mechanics and footer controls stay intact.',
       "Use one object value with fontId, fontWeight, fontSize, letterSpacing, lineHeight, textCase, color, and opacity. Keep typography renderers wired to all eight parts.",
       "FontPicker standard/default text color is #FFFFFF with opacity 100; omit color/opacity or use those values unless the prompt or reference explicitly requires a different initial text color.",
       "Any product text controlled by FontPicker must render fontId, fontWeight, fontSize, letterSpacing, lineHeight, textCase, color, and opacity in preview and export; do not leave typography values as panel-only runtime state.",
@@ -335,12 +386,8 @@ export const TOOLCRAFT_VISUAL_COMPONENT_CONTRACTS = {
       acceptableAlternatives: [
         "Use Vector only for stable direct-authored continuous position or direction parameters.",
       ],
-      layoutConstraints: [
-        "AnchorGrid is a standalone position selector.",
-      ],
-      requiredAcceptance: [
-        "Prove selected anchor changes product placement.",
-      ],
+      layoutConstraints: ["AnchorGrid is a standalone position selector."],
+      requiredAcceptance: ["Prove selected anchor changes product placement."],
     }),
     aiUsageRules: [
       "AnchorGrid is a position selector; acceptance must prove anchorGrid.position changes product placement, not only selected button state.",