@pixel-point/toolcraft 0.0.15 → 0.0.17

package/src/package-manager.test.mjs

@@ -1,12 +1,17 @@
 import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
 import { describe, it } from "node:test";
 
 import {
+  GENERATED_SCRIPT_COMMANDS,
   createExecCommand,
   createInstallCommand,
   createRunScriptCommand,
-  createVerificationScripts,
   detectPackageManager,
+  detectPackageManagerForDirectory,
   replaceGeneratedCommandReferences,
 } from "./package-manager.mjs";
 
@@ -32,22 +37,51 @@ describe("detectPackageManager", () => {
   });
 });
 
+describe("detectPackageManagerForDirectory", () => {
+  it("uses the invoking repository package manager for direct node execution", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "toolcraft-pm-"));
+    await fs.writeFile(
+      path.join(root, "package.json"),
+      JSON.stringify({ packageManager: "pnpm@10.11.0" }),
+    );
+    try {
+      assert.equal(
+        await detectPackageManagerForDirectory({ cwd: root, env: {} }),
+        "pnpm",
+      );
+    } finally {
+      await fs.rm(root, { force: true, recursive: true });
+    }
+  });
+});
+
 describe("package manager commands", () => {
-  it("formats install, run, exec, and verification commands for npm", () => {
+  it("does not recognize the removed performance iteration compatibility command", () => {
+    const source = readFileSync(
+      new URL("./package-manager.mjs", import.meta.url),
+      "utf8",
+    );
+    assert.doesNotMatch(source, /verify:perf:record-iteration/u);
+  });
+
+  it("keeps the generated command rewrite surface intentionally small", () => {
+    assert.deepEqual(GENERATED_SCRIPT_COMMANDS, [
+      "build",
+      "dev",
+      "test",
+      "typecheck",
+      "verify:delivery",
+      "verify:perf",
+    ]);
+  });
+
+  it("formats install, run, and exec commands for npm", () => {
     assert.deepEqual(createInstallCommand("npm"), {
       args: ["install"],
       command: "npm",
     });
     assert.equal(createRunScriptCommand("npm", "dev"), "npm run dev");
     assert.equal(createExecCommand("npm", "vite", ["dev"]), "npm exec -- vite dev");
-    assert.deepEqual(createVerificationScripts("npm"), {
-      "verify:final":
-        "npm run ai:check && npm run test && npm run build && npm run test:browser && npm run verify:receipt",
-      "verify:perf": "npm run test:browser:perf",
-      "verify:perf:playwright": "npm run test:browser:perf",
-      "verify:quick": "npm run ai:check && npm run test",
-      "verify:ui": "npm run test:browser",
-    });
   });
 
   it("formats run and exec commands for pnpm", () => {
@@ -58,12 +92,13 @@ describe("package manager commands", () => {
   it("replaces known generated command references for npm", () => {
     const source = [
       "pnpm install",
-      "pnpm verify:final",
+      "pnpm verify:delivery",
       "pnpm verify:perf",
-      "pnpm verify:perf:record-exemption -- --tier=2",
-      "pnpm verify:receipt",
-      "pnpm test:browser",
+      "pnpm typecheck",
+      "pnpm test",
+      "pnpm build",
       "pnpm dev",
+      "pnpm verify:quick",
       "pnpm exec vite dev --host 127.0.0.1",
     ].join("\n");
 
@@ -71,14 +106,62 @@ describe("package manager commands", () => {
       replaceGeneratedCommandReferences(source, "npm"),
       [
         "npm install",
-        "npm run verify:final",
+        "npm run verify:delivery",
         "npm run verify:perf",
-        "npm run verify:perf:record-exemption -- --tier=2",
-        "npm run verify:receipt",
-        "npm run test:browser",
+        "npm run typecheck",
+        "npm run test",
+        "npm run build",
         "npm run dev",
+        "pnpm verify:quick",
         "npm exec -- vite dev --host 127.0.0.1",
       ].join("\n"),
     );
   });
+
+  it("rewrites only exact script invocation tokens", () => {
+    const source = [
+      "pnpm build --watch",
+      "`pnpm dev`",
+      "(pnpm test)",
+      "pnpm typecheck;",
+      "pnpm verify:delivery.",
+      "pnpm verify:perf,",
+      "pnpm test:browser",
+      "pnpm test:delivery",
+      "pnpm dev:restart",
+      "pnpm verify:perf:record-iteration",
+      "pnpm verify:delivery:legacy",
+      "pnpm testing",
+      "prefix-pnpm test",
+    ].join("\n");
+
+    assert.equal(
+      replaceGeneratedCommandReferences(source, "npm"),
+      [
+        "npm run build --watch",
+        "`npm run dev`",
+        "(npm run test)",
+        "npm run typecheck;",
+        "npm run verify:delivery.",
+        "npm run verify:perf,",
+        "pnpm test:browser",
+        "pnpm test:delivery",
+        "pnpm dev:restart",
+        "pnpm verify:perf:record-iteration",
+        "pnpm verify:delivery:legacy",
+        "pnpm testing",
+        "prefix-pnpm test",
+      ].join("\n"),
+    );
+  });
+
+  it("preserves canonical performance markers while rewriting readable commands", () => {
+    const marker =
+      "<!-- toolcraft-performance-full-authority: automatic=forbidden; recommendation=two-compatible-iterations-or-broad-unlocalizable-problem; command=pnpm verify:perf; authority=explicit-user-request-or-accepted-offer -->";
+
+    assert.equal(
+      replaceGeneratedCommandReferences(`${marker}\nRun pnpm verify:perf.`, "npm"),
+      `${marker}\nRun npm run verify:perf.`,
+    );
+  });
 });

package/src/packaged-template-fallback.test.mjs

@@ -75,6 +75,10 @@ it("packs, executes, and verifies the isolated npm package fallback", async () =
     const packagedFiles = [
       "bin/create-toolcraft-app.mjs",
       "bin/toolcraft.mjs",
+      "src/generate-test-windows-job-native.cs",
+      "src/generate-test-windows-job-wrapper.mjs",
+      "src/generate-test-windows-job.mjs",
+      "src/generate-test-windows-job.ps1",
       "templates/starter/package.json",
       "templates/runtime/index.ts",
       "templates/ui/index.ts",

package/src/rewrite-imports.mjs

@@ -5,6 +5,8 @@ import { TOOLCRAFT_IMPORT_REWRITES } from "./import-map.mjs";
 
 const TEXT_FILE_EXTENSIONS = new Set([
   ".css",
+  ".cjs",
+  ".cts",
   ".html",
   ".json",
   ".js",
@@ -12,6 +14,7 @@ const TEXT_FILE_EXTENSIONS = new Set([
   ".md",
   ".mdx",
   ".mjs",
+  ".mts",
   ".ts",
   ".tsx",
 ]);

package/src/rewrite-imports.test.mjs

@@ -1,7 +1,11 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
 
-import { rewriteGeneratedText, rewriteImportSpecifiers } from "./rewrite-imports.mjs";
+import {
+  isTextFile,
+  rewriteGeneratedText,
+  rewriteImportSpecifiers,
+} from "./rewrite-imports.mjs";
 
 describe("rewriteImportSpecifiers", () => {
   it("rewrites exact workspace package imports to local toolcraft imports", () => {
@@ -13,6 +17,9 @@ import { Tooltip } from "@repo/ui/primitives";
 import { Panel } from "@repo/ui/panel";
 import { Slider } from "@repo/ui/controls";
 import { getToolcraftComponentContract } from "@repo/toolcraft-runtime/contracts";
+import { TOOLCRAFT_PERFORMANCE_PROFILE_MANIFEST } from "@repo/toolcraft-runtime/performance-profile-manifest";
+import { decodeToolcraftPerformancePathId } from "@repo/toolcraft-runtime/performance-path-codec";
+import { validateToolcraftPerformanceRequestEvidenceMatch } from "@repo/toolcraft-runtime/performance-request-evidence-policy";
 import "@repo/ui/styles.css";
 `;
 
@@ -26,6 +33,9 @@ import { Tooltip } from "@/toolcraft/ui/components/primitives";
 import { Panel } from "@/toolcraft/ui/components/panel";
 import { Slider } from "@/toolcraft/ui/components/controls";
 import { getToolcraftComponentContract } from "@/toolcraft/runtime/contracts/component-contracts";
+import { TOOLCRAFT_PERFORMANCE_PROFILE_MANIFEST } from "../src/toolcraft/runtime/performance/profile-catalog-manifest.mjs";
+import { decodeToolcraftPerformancePathId } from "../src/toolcraft/runtime/testing/performance-path-codec.mjs";
+import { validateToolcraftPerformanceRequestEvidenceMatch } from "../src/toolcraft/runtime/contracts/performance-request-evidence-policy.mjs";
 import "@/toolcraft/ui/styles.css";
 `,
     );
@@ -39,6 +49,11 @@ import "@/toolcraft/ui/styles.css";
 });
 
 describe("rewriteGeneratedText", () => {
+  it("includes declaration modules in generated text rewriting", () => {
+    assert.equal(isTextFile("toolcraft-kernel-benchmark-receipt.d.mts"), true);
+    assert.equal(isTextFile("toolcraft-kernel-benchmark-receipt.d.cts"), true);
+  });
+
   it("rewrites starter css package sources", () => {
     const source = `
 @source "../../packages/ui/src";

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

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 
 import { getToolcraftComponentContract } from "./component-contracts";
+import { TOOLCRAFT_SEGMENTED_STATIC_FIT } from "./segmented-control-fit";
 
 describe("Toolcraft template component contracts: choices and actions", () => {
   it("documents select as the fallback for segmented controls that exceed compact limits", () => {
@@ -155,13 +156,55 @@ describe("Toolcraft template component contracts: choices and actions", () => {
 
   it("documents segmented controls as compact selector-only choices", () => {
     const segmented = getToolcraftComponentContract("segmented");
+    const select = getToolcraftComponentContract("select");
+    const { maxOptionLabelLength, maxOptions, maxTotalLabelLength } =
+      TOOLCRAFT_SEGMENTED_STATIC_FIT;
+    const numericRule = `Generated schemas should keep text segmented controls to at most ${maxOptions} options, no option label longer than ${maxOptionLabelLength} characters, and no more than ${maxTotalLabelLength} total option-label characters.`;
 
+    expect(select.decisionCatalog?.acceptableAlternatives).toContain(
+      `Use Segmented for two to ${maxOptions} short closely related options that fit without clipping.`,
+    );
+    expect(segmented.decisionCatalog?.ownsValueModel).toContain(
+      `two to ${maxOptions} short related options`,
+    );
+    expect(segmented.decisionCatalog?.layoutConstraints).toContain(
+      `Keep text segmented controls to at most ${maxOptions} options and compact labels.`,
+    );
     expect(segmented.aiUsageRules).toContain(
       "Use Segmented only for compact mode choices where every cell keeps its internal padding.",
     );
     expect(segmented.aiUsageRules).toContain(
       "If a segmented control is too wide, first shorten option labels; if the compact labels still exceed the width budget, use Select because it has the same selection mechanics without broken cells.",
     );
+    expect(segmented.aiUsageRules).toContain(
+      "defineToolcraft rejects text Segmented schemas above the static fit budget before render; shorten labels or use Select instead of relying on clipping or runtime conversion.",
+    );
+    expect(segmented.aiUsageRules).toContain(numericRule);
+  });
+
+  it("documents tabs as label-free responsive content-view choices", () => {
+    const tabs = getToolcraftComponentContract("tabs");
+
+    expect(tabs.visualComponent).toBe("TabsControl");
+    expect(tabs.labelPolicy).toBe("hidden");
+    expect(tabs.decisionCatalog?.ownsValueModel).toContain(
+      "finite content-view selection",
+    );
+    expect(tabs.decisionCatalog?.useWhen).toContain(
+      "Use Tabs when the selected option replaces the content or workflow view shown below the control.",
+    );
+    expect(tabs.decisionCatalog?.doNotReplaceWith).toContain(
+      "Do not use Tabs for a compact setting that leaves the surrounding content unchanged; use Segmented.",
+    );
+    expect(tabs.decisionCatalog?.layoutConstraints).toContain(
+      "Tabs are full-width controls and must not be placed in two-column inline or half-width layout groups.",
+    );
+    expect(tabs.decisionCatalog?.layoutConstraints).toContain(
+      "When tab cells do not preserve text and internal padding on one row, Tabs automatically renders the same options through Select.",
+    );
+    expect(tabs.aiUsageRules).toContain(
+      "Tabs never render a separate visible field label; use the control label as its accessible name and rely on the nearest section context.",
+    );
   });
 
   it("keeps panel actions documented as sticky footer command controls", () => {
@@ -173,10 +216,10 @@ describe("Toolcraft template component contracts: choices and actions", () => {
       "Do not use panelActions for resetting controls; the controls panel header owns Reset controls.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Handle product-specific panelActions through ToolcraftApp onPanelAction.",
+      "Handle product-specific non-export panelActions through ToolcraftApp onPanelAction. Typed export-image and export-video actions are runtime-owned and consume ToolcraftAppComposition.exportRenderer.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Async product actions such as Export, Download, Copy, Generate, or Apply must return the real Promise from onPanelAction and report progress through the onPanelAction reportProgress callback.",
+      "Async non-export product actions such as Download, Copy, Generate, or Apply must return the real Promise from onPanelAction and report progress through the onPanelAction reportProgress callback.",
     );
     expect(contract.aiUsageRules).toContain(
       "The sticky footer top accent indicator is determinate when reportProgress receives 0..1 values and falls back to pending state only when progress is unavailable.",
@@ -206,19 +249,19 @@ describe("Toolcraft template component contracts: choices and actions", () => {
       "Image Export format and resolution render as one compact two-column inline Select pair, matching the Video Export settings structure.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Image Export resolution controls the actual exported image long edge: 2K = 2048px, 4K = 4096px, 8K = 8192px. Pass the selected runtime value to createToolcraftPngExportCanvas resolution and prove decoded image width/height in browser acceptance.",
+      "Image Export resolution controls the actual exported image long edge: 2K = 2048px, 4K = 4096px, 8K = 8192px. Runtime resolves the selected value and protected browser acceptance proves decoded image width and height.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Animated apps include Export Video as the primary footer action and Export PNG as a secondary footer action.",
+      "Apps that deliver animation include Export Video as the primary footer action and Export PNG as a secondary footer action; timeline playback alone does not invent video delivery.",
     );
     expect(contract.aiUsageRules).toContain(
       "Any app with Export Video must enable the top Toolcraft timeline; video duration, loop, and rendered timestamps come from runtime timeline state.",
     );
     expect(contract.aiUsageRules).toContain(
-      'Animated apps with Export Video must expose a separate "Video Export" controls section.',
+      'Apps with Export Video must expose a separate "Video Export" controls section.',
     );
     expect(contract.aiUsageRules).toContain(
-      'Animated apps with both Export PNG and Export Video must expose both "Image Export" and "Video Export"; Image Export sits immediately before Video Export.',
+      'Apps with both Export PNG and Export Video must expose both "Image Export" and "Video Export"; Image Export sits immediately before Video Export.',
     );
     expect(contract.aiUsageRules).toContain(
       'The Video Export section must include format and resolution controls such as targets "export.video.format" and "export.video.resolution".',
@@ -242,16 +285,16 @@ describe("Toolcraft template component contracts: choices and actions", () => {
       'Baseline browser video formats are "mp4" and "webm"; MOV or ProRes require an explicit custom encoder/transcoder and dedicated acceptance plus performance coverage.',
     );
     expect(contract.aiUsageRules).toContain(
-      "Video export code must choose the actual MIME/container through MediaRecorder.isTypeSupported or an equivalent encoder capability check, then fall back safely.",
+      "Runtime video export chooses the actual MIME, container, and codec through the timestamped Mediabunny encoder capability check, then returns the real supported format or a typed visible failure.",
     );
     expect(contract.aiUsageRules).toContain(
       "Video export must use getToolcraftVideoExportSize for current and 4K dimensions. Current video export uses the current canvas/output size with even encoder-safe rounding; 4K video fits inside an encoder-safe 3840x2160 box, preserves canvas aspect ratio, and uses even pixel dimensions. Do not hand-roll 4096px long-edge video sizing.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Video export must set recording canvas dimensions before captureStream, MediaRecorder, VideoEncoder, or equivalent encoder setup, and must reject recorder/encoder errors instead of returning corrupt blobs.",
+      "Runtime video export allocates the selected recording canvas dimensions before timestamped encoder setup and rejects renderer, encoder, muxer, and output-limit errors instead of returning corrupt blobs.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Offline video export duration must be encoded from runtime timeline timestamps. Do not rely on canvas.captureStream plus MediaRecorder wall-clock recording time as the only duration mechanism for rendered-frame export.",
+      "Offline video export duration is encoded from the fixed runtime 30 FPS timeline schedule. Product code must not use canvas.captureStream, MediaRecorder, or wall-clock time as a fallback.",
     );
     expect(contract.aiUsageRules).toContain(
       'Video resolution must control exported dimensions. Use "current" output size by default; "4K" is an export resolution target, not a hardcoded 3840x2160 canvas lock.',
@@ -263,16 +306,19 @@ describe("Toolcraft template component contracts: choices and actions", () => {
       "Video export must report frame-based progress through reportProgress during render/encode steps. PNG export should report phase progress for render, blob, and handoff when those phases are asynchronous.",
     );
     expect(contract.aiUsageRules).toContain(
-      'Product-output apps must expose a dedicated "Background" section directly before the first export settings section. With PNG export that first section is Image Export; with video-only export it is Video Export.',
+      'Product-output apps declare the standard background pair in an authored "Background" source section. Runtime removes that visible section and places Background plus Infinity canvas, then Background color, in Setup; Timeline is the final Setup control.',
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Product-output apps call shouldIncludeToolcraftPreviewBackground(state) for bounded live preview background. Runtime artifact export owns Background semantics: PNG may be transparent, JPEG and video remain opaque, Infinity uses the full-viewport color, and Background off restores finite mode and disables Infinity.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Product-output apps must pass the includeBackground runtime value to createToolcraftPngExportCanvas for PNG alpha and call shouldIncludeToolcraftPreviewBackground(state) for live preview product background.",
+      "ToolcraftAppComposition.exportRenderer draws one deterministic product frame in scene coordinates for both image and video. Runtime owns canvas allocation, background, runtime media/model compositing, selected dimensions, encoding, download, progress, and typed failures.",
     );
     expect(contract.aiUsageRules).toContain(
-      "PNG export must use createToolcraftPngExportCanvas so background transparency and selected image dimensions or retina fallback are applied consistently; turning Include off makes preview product background and PNG alpha transparent without hiding the Toolcraft canvas backing or video background.",
+      "Product modules must not encode or download export canvases directly and must not instantiate MediaRecorder or VideoEncoder; the generated-source boundary rejects those duplicate export paths.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Video export must keep product background and use getToolcraftVideoExportSize for current/4K output dimensions.",
+      "Runtime video export keeps the selected background and uses getToolcraftVideoExportSize for current/4K output dimensions.",
     );
     expect(contract.aiUsageRules).toContain(
       "Copy PNG can be a secondary action when clipboard output is useful, but copy does not replace export.",

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

@@ -1,5 +1,10 @@
 import { control, decisionCatalog } from "./component-contract-builders";
+import { TOOLCRAFT_SEGMENTED_STATIC_FIT } from "./segmented-control-fit";
 import type { ToolcraftComponentContract } from "./types";
+
+const { maxOptionLabelLength, maxOptions, maxTotalLabelLength } =
+  TOOLCRAFT_SEGMENTED_STATIC_FIT;
+
 export const TOOLCRAFT_CHOICE_COMPONENT_CONTRACTS = {
   select: {
     ...control("select", "Select", "grouped", "required"),
@@ -19,7 +24,7 @@ export const TOOLCRAFT_CHOICE_COMPONENT_CONTRACTS = {
         "Do not use Select to recreate FontPicker, Gradient, ImagePicker, FileDrop, Curves, Vector, or Palette value models.",
       ],
       acceptableAlternatives: [
-        "Use Segmented for two to four short closely related options that fit without clipping.",
+        `Use Segmented for two to ${maxOptions} short closely related options that fit without clipping.`,
       ],
       layoutConstraints: [
         "Standalone Select controls render stacked full-width with the label above the dropdown; do not use the compact side-label row with label left and dropdown right.",
@@ -38,7 +43,7 @@ export const TOOLCRAFT_CHOICE_COMPONENT_CONTRACTS = {
       strictness: "best-fit",
       ownsValueModel: [
         "compact finite mode choice",
-        "two to four short related options",
+        `two to ${maxOptions} short related options`,
         "single-row mode toggle",
       ],
       useWhen: [
@@ -53,7 +58,7 @@ export const TOOLCRAFT_CHOICE_COMPONENT_CONTRACTS = {
         "Use Select when options are long, numerous, or break segmented cell padding.",
       ],
       layoutConstraints: [
-        "Keep text segmented controls to at most four options and compact labels.",
+        `Keep text segmented controls to at most ${maxOptions} options and compact labels.`,
         "Segmented controls are full-width controls and must not be placed in two-column inline or half-width layout groups.",
         "Fallback to Select when cells collide, clip, or lose padding.",
       ],
@@ -66,10 +71,48 @@ export const TOOLCRAFT_CHOICE_COMPONENT_CONTRACTS = {
       "Use Segmented only for compact mode choices where every cell keeps its internal padding.",
       "Do not place Segmented beside Switch, Color, Select, or another control in an inline row; use Select when a finite choice must occupy a half-width column.",
       "If a segmented control is too wide, first shorten option labels; if the compact labels still exceed the width budget, use Select because it has the same selection mechanics without broken cells.",
-      "Generated schemas should keep text segmented controls to at most four options, no option label longer than nine characters, and no more than twenty-four total option-label characters.",
+      `Generated schemas should keep text segmented controls to at most ${maxOptions} options, no option label longer than ${maxOptionLabelLength} characters, and no more than ${maxTotalLabelLength} total option-label characters.`,
+      "defineToolcraft rejects text Segmented schemas above the static fit budget before render; shorten labels or use Select instead of relying on clipping or runtime conversion.",
       "Browser verification must treat collided, clipped, or paddingless segmented cells as a broken component and switch to shorter labels or Select.",
     ],
   },
+  tabs: {
+    ...control("tabs", "TabsControl", "grouped", "hidden"),
+    decisionCatalog: decisionCatalog({
+      strictness: "best-fit",
+      ownsValueModel: [
+        "finite content-view selection",
+        "content or workflow view switching",
+        "responsive tab-to-select choice",
+      ],
+      useWhen: [
+        "Use Tabs when the selected option replaces the content or workflow view shown below the control.",
+        "Use Tabs when closely related views benefit from direct side-by-side navigation.",
+      ],
+      doNotReplaceWith: [
+        "Do not use Tabs for a compact setting that leaves the surrounding content unchanged; use Segmented.",
+        "Do not use Tabs for actions; use buttons or panelActions.",
+      ],
+      acceptableAlternatives: [
+        "Use Segmented for a compact mode setting that does not replace the surrounding view.",
+        "Use Select directly when the available panel width cannot present the choices as tabs.",
+      ],
+      layoutConstraints: [
+        "Tabs are full-width controls and must not be placed in two-column inline or half-width layout groups.",
+        "Tabs never render a separate visible field label.",
+        "When tab cells do not preserve text and internal padding on one row, Tabs automatically renders the same options through Select.",
+      ],
+      requiredAcceptance: [
+        "Prove every visible tab changes the relevant content or workflow view.",
+        "Prove overflow switches Tabs to Select without changing the selected value, then restores Tabs when space returns.",
+      ],
+    }),
+    aiUsageRules: [
+      "Tabs never render a separate visible field label; use the control label as its accessible name and rely on the nearest section context.",
+      "Use Tabs for navigation between content or workflow views, not for a compact setting that leaves the surrounding content unchanged.",
+      "Tabs own their responsive fallback: when every cell cannot keep its text and internal padding on one row, render the same options through Select.",
+    ],
+  },
   switch: {
     ...control("switch", "Switch", "grouped", "required"),
     decisionCatalog: decisionCatalog({
@@ -276,8 +319,8 @@ export const TOOLCRAFT_CHOICE_COMPONENT_CONTRACTS = {
     aiUsageRules: [
       "Use panelActions only for sticky footer product actions such as Generate, Export, Copy, or Download.",
       "Do not use panelActions for resetting controls; the controls panel header owns Reset controls.",
-      "Handle product-specific panelActions through ToolcraftApp onPanelAction.",
-      "Async product actions such as Export, Download, Copy, Generate, or Apply must return the real Promise from onPanelAction and report progress through the onPanelAction reportProgress callback.",
+      "Handle product-specific non-export panelActions through ToolcraftApp onPanelAction. Typed export-image and export-video actions are runtime-owned and consume ToolcraftAppComposition.exportRenderer.",
+      "Async non-export product actions such as Download, Copy, Generate, or Apply must return the real Promise from onPanelAction and report progress through the onPanelAction reportProgress callback.",
       "The sticky footer top accent indicator is determinate when reportProgress receives 0..1 values and falls back to pending state only when progress is unavailable.",
       "defineToolcraft hoists panelActions into the controls panel sticky footer automatically.",
       "Product-output apps must always include export in panelActions.",
@@ -287,11 +330,11 @@ export const TOOLCRAFT_CHOICE_COMPONENT_CONTRACTS = {
       'The Image Export section must include "export.image.format" as a Select control with PNG and JPG choices, defaulting to "png".',
       'The Image Export section must include "export.image.resolution" as a Select control with 2K, 4K, and 8K choices, defaulting to "4k".',
       "Image Export format and resolution render as one compact two-column inline Select pair, matching the Video Export settings structure.",
-      "Image Export resolution controls the actual exported image long edge: 2K = 2048px, 4K = 4096px, 8K = 8192px. Pass the selected runtime value to createToolcraftPngExportCanvas resolution and prove decoded image width/height in browser acceptance.",
-      "Animated apps include Export Video as the primary footer action and Export PNG as a secondary footer action.",
+      "Image Export resolution controls the actual exported image long edge: 2K = 2048px, 4K = 4096px, 8K = 8192px. Runtime resolves the selected value and protected browser acceptance proves decoded image width and height.",
+      "Apps that deliver animation include Export Video as the primary footer action and Export PNG as a secondary footer action; timeline playback alone does not invent video delivery.",
       "Any app with Export Video must enable the top Toolcraft timeline; video duration, loop, and rendered timestamps come from runtime timeline state.",
-      'Animated apps with Export Video must expose a separate "Video Export" controls section.',
-      'Animated apps with both Export PNG and Export Video must expose both "Image Export" and "Video Export"; Image Export sits immediately before Video Export.',
+      'Apps with Export Video must expose a separate "Video Export" controls section.',
+      'Apps with both Export PNG and Export Video must expose both "Image Export" and "Video Export"; Image Export sits immediately before Video Export.',
       'The Video Export section must include format and resolution controls such as targets "export.video.format" and "export.video.resolution".',
       "Use Select controls for Video Export format and resolution; do not use Segmented unless the product has a deliberately tiny fixed output menu and browser tests prove every cell keeps padding.",
       'Place the Video Export section as the final controls section directly above sticky footer panelActions.',
@@ -299,17 +342,18 @@ export const TOOLCRAFT_CHOICE_COMPONENT_CONTRACTS = {
       'Video Export resolution defaults to "current"; keep "4k" available as the high-resolution alternate.',
       "Video Export format and resolution are a compact semantic pair and should use a two-column inline layout by default; use stacked rows only when labels or selected values do not fit without clipping.",
       'Baseline browser video formats are "mp4" and "webm"; MOV or ProRes require an explicit custom encoder/transcoder and dedicated acceptance plus performance coverage.',
-      "Video export code must choose the actual MIME/container through MediaRecorder.isTypeSupported or an equivalent encoder capability check, then fall back safely.",
+      "Runtime video export chooses the actual MIME, container, and codec through the timestamped Mediabunny encoder capability check, then returns the real supported format or a typed visible failure.",
       "Video export must use getToolcraftVideoExportSize for current and 4K dimensions. Current video export uses the current canvas/output size with even encoder-safe rounding; 4K video fits inside an encoder-safe 3840x2160 box, preserves canvas aspect ratio, and uses even pixel dimensions. Do not hand-roll 4096px long-edge video sizing.",
-      "Video export must set recording canvas dimensions before captureStream, MediaRecorder, VideoEncoder, or equivalent encoder setup, and must reject recorder/encoder errors instead of returning corrupt blobs.",
-      "Offline video export duration must be encoded from runtime timeline timestamps. Do not rely on canvas.captureStream plus MediaRecorder wall-clock recording time as the only duration mechanism for rendered-frame export.",
+      "Runtime video export allocates the selected recording canvas dimensions before timestamped encoder setup and rejects renderer, encoder, muxer, and output-limit errors instead of returning corrupt blobs.",
+      "Offline video export duration is encoded from the fixed runtime 30 FPS timeline schedule. Product code must not use canvas.captureStream, MediaRecorder, or wall-clock time as a fallback.",
       'Video resolution must control exported dimensions. Use "current" output size by default; "4K" is an export resolution target, not a hardcoded 3840x2160 canvas lock.',
       "Video export browser coverage must load the exported blob metadata and prove video.duration matches the edited runtime timeline duration; blobSize/blobType checks alone are not enough.",
       "Video export must report frame-based progress through reportProgress during render/encode steps. PNG export should report phase progress for render, blob, and handoff when those phases are asynchronous.",
-      'Product-output apps must expose a dedicated "Background" section directly before the first export settings section. With PNG export that first section is Image Export; with video-only export it is Video Export.',
-      "Product-output apps must pass the includeBackground runtime value to createToolcraftPngExportCanvas for PNG alpha and call shouldIncludeToolcraftPreviewBackground(state) for live preview product background.",
-      "PNG export must use createToolcraftPngExportCanvas so background transparency and selected image dimensions or retina fallback are applied consistently; turning Include off makes preview product background and PNG alpha transparent without hiding the Toolcraft canvas backing or video background.",
-      "Video export must keep product background and use getToolcraftVideoExportSize for current/4K output dimensions.",
+      'Product-output apps declare the standard background pair in an authored "Background" source section. Runtime removes that visible section and places Background plus Infinity canvas, then Background color, in Setup; Timeline is the final Setup control.',
+      "Product-output apps call shouldIncludeToolcraftPreviewBackground(state) for bounded live preview background. Runtime artifact export owns Background semantics: PNG may be transparent, JPEG and video remain opaque, Infinity uses the full-viewport color, and Background off restores finite mode and disables Infinity.",
+      "ToolcraftAppComposition.exportRenderer draws one deterministic product frame in scene coordinates for both image and video. Runtime owns canvas allocation, background, runtime media/model compositing, selected dimensions, encoding, download, progress, and typed failures.",
+      "Product modules must not encode or download export canvases directly and must not instantiate MediaRecorder or VideoEncoder; the generated-source boundary rejects those duplicate export paths.",
+      "Runtime video export keeps the selected background and uses getToolcraftVideoExportSize for current/4K output dimensions.",
       "Copy PNG can be a secondary action when clipboard output is useful, but copy does not replace export.",
       "Add Copy PNG as a secondary action only when the prompt/reference includes clipboard output or the product clearly benefits from paste/share workflows.",
       "Footer actions must be one compact horizontal group; do not split them into stacked full-width sections.",

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

@@ -74,7 +74,7 @@ describe("Toolcraft template component contracts: inputs", () => {
       'Browser verification can inspect [data-slot="slider"][data-variant="discrete"] plus slider markers to prove the Toolcraft component variant rendered.',
     );
     expect(slider.aiUsageRules).toContain(
-      "Visual discrete sliders must still drag smoothly; browser performance tests should use expectToolcraftDiscreteSliderDragSmoothness for real pointer drag.",
+      "Visual discrete sliders must still drag smoothly; their canonical performance path adapter should use dragToolcraftSliderByTarget for real pointer drag and let the central path profile own the budget.",
     );
     expect(slider.aiUsageRules).toContain(
       "Use visibleWhen for sliders that are meaningful only in some mode/type/source/include/count states; inactive branches should disappear so the panel shows only controls usable in the current state.",
@@ -137,7 +137,7 @@ describe("Toolcraft template component contracts: inputs", () => {
       "Manual range value editing accepts common separators such as slash, hyphen, spaces, and dashes, including when values include unit suffixes such as 30%-150% or 30% - 90%; do not create custom parsers for RangeSlider labels.",
     );
     expect(rangeSlider.aiUsageRules).toContain(
-      "Visual discrete sliders must still drag smoothly; browser performance tests should use expectToolcraftDiscreteSliderDragSmoothness for real pointer drag.",
+      "Visual discrete sliders must still drag smoothly; their canonical performance path adapter should use dragToolcraftSliderByTarget for real pointer drag and let the central path profile own the budget.",
     );
     expect(rangeSlider.aiUsageRules).toContain(
       "Use visibleWhen for range sliders that are meaningful only in some mode/type/source/include/count states; inactive branches should disappear so the panel shows only controls usable in the current state.",

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

@@ -84,7 +84,7 @@ export const TOOLCRAFT_INPUT_COMPONENT_CONTRACTS = {
       "For a small named option set, prefer Select or Segmented instead of forcing a discrete Slider.",
       'Specs, plans, and app-schema tests must assert explicit discrete sliders render as variant: "discrete" with markers derived from min, max, and step.',
       'Browser verification can inspect [data-slot="slider"][data-variant="discrete"] plus slider markers to prove the Toolcraft component variant rendered.',
-      "Visual discrete sliders must still drag smoothly; browser performance tests should use expectToolcraftDiscreteSliderDragSmoothness for real pointer drag.",
+      "Visual discrete sliders must still drag smoothly; their canonical performance path adapter should use dragToolcraftSliderByTarget for real pointer drag and let the central path profile own the budget.",
       "Use visibleWhen for sliders that are meaningful only in some mode/type/source/include/count states; inactive branches should disappear so the panel shows only controls usable in the current state.",
       "Do not use schema disabled: true or disabledWhen for product sliders; product panels should show only controls usable in the current state. Use visibleWhen for unavailable product states instead of rendering disabled controls.",
       "Do not leave an inactive conditional slider visible while making the renderer ignore it; hide it with visibleWhen.",
@@ -136,7 +136,7 @@ export const TOOLCRAFT_INPUT_COMPONENT_CONTRACTS = {
       "RangeSlider defaultValue must start with different lower and upper values so the two-thumb control does not collapse into a single-value slider.",
       "Manual range value editing accepts common separators such as slash, hyphen, spaces, and dashes, including when values include unit suffixes such as 30%-150% or 30% - 90%; do not create custom parsers for RangeSlider labels.",
       'Specs, plans, and app-schema tests must assert explicit discrete range sliders render as variant: "discrete" with markers derived from min, max, and step.',
-      "Visual discrete sliders must still drag smoothly; browser performance tests should use expectToolcraftDiscreteSliderDragSmoothness for real pointer drag.",
+      "Visual discrete sliders must still drag smoothly; their canonical performance path adapter should use dragToolcraftSliderByTarget for real pointer drag and let the central path profile own the budget.",
       "Use visibleWhen for range sliders that are meaningful only in some mode/type/source/include/count states; inactive branches should disappear so the panel shows only controls usable in the current state.",
       "Do not use schema disabled: true or disabledWhen for product range sliders; product panels should show only controls usable in the current state. Use visibleWhen for unavailable product states instead of rendering disabled controls.",
       "Do not leave an inactive conditional range slider visible while making the renderer ignore it; hide it with visibleWhen.",

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

@@ -58,12 +58,25 @@ describe("Toolcraft template component contracts: media and custom controls", ()
     expect(contract.commands).toEqual([
       "media.delete",
       "media.import",
+      "media.importBatch",
       "media.reorder",
       "media.transform",
     ]);
     expect(contract.aiUsageRules).toContain(
       'Use fileDrop with assetKind: "image" for image-only source media and assetKind: "file" for arbitrary uploaded files.',
     );
+    expect(contract.aiUsageRules).toContain(
+      '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.',
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
     expect(contract.aiUsageRules).toContain(
       "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.",
     );
@@ -94,6 +107,9 @@ describe("Toolcraft template component contracts: media and custom controls", ()
     expect(contract.aiUsageRules).toContain(
       "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.",
     );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
     expect(contract.aiUsageRules).toContain(
       "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.",
     );
@@ -112,5 +128,8 @@ describe("Toolcraft template component contracts: media and custom controls", ()
     expect(contract.aiUsageRules).toContain(
       "In multi-layer apps, deletion and visibility belong to the Layers panel; fileDrop remains an upload target.",
     );
+    expect(contract.aiUsageRules).toContain(
+      '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.',
+    );
   });
 });