@pixel-point/toolcraft 0.0.15 → 0.0.16

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", () => {
@@ -209,16 +252,16 @@ describe("Toolcraft template component contracts: choices and actions", () => {
       "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.",
     );
     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".',
@@ -263,13 +306,13 @@ 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 must pass the includeBackground runtime value to createToolcraftPngExportCanvas for PNG alpha and call shouldIncludeToolcraftPreviewBackground(state) for live preview product background.",
+      "Product-output apps pass the includeBackground runtime value to createToolcraftPngExportCanvas for PNG alpha and call shouldIncludeToolcraftPreviewBackground(state) for bounded live preview background. In Infinity mode CanvasShell owns the selected full-viewport background color, and Background off restores finite mode and disables Infinity.",
     );
     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.",
+      "PNG export must use createToolcraftPngExportCanvas so background transparency and selected image dimensions or retina fallback are applied consistently; turning Background off makes preview product background and PNG alpha transparent without hiding the Toolcraft canvas backing or video background.",
     );
     expect(contract.aiUsageRules).toContain(
       "Video export must keep product background and use getToolcraftVideoExportSize for current/4K output dimensions.",

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({
@@ -288,10 +331,10 @@ export const TOOLCRAFT_CHOICE_COMPONENT_CONTRACTS = {
       '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.",
+      "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.',
@@ -306,9 +349,9 @@ export const TOOLCRAFT_CHOICE_COMPONENT_CONTRACTS = {
       '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.",
+      '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 pass the includeBackground runtime value to createToolcraftPngExportCanvas for PNG alpha and call shouldIncludeToolcraftPreviewBackground(state) for bounded live preview background. In Infinity mode CanvasShell owns the selected full-viewport background color, and Background off restores finite mode and disables Infinity.",
+      "PNG export must use createToolcraftPngExportCanvas so background transparency and selected image dimensions or retina fallback are applied consistently; turning Background 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.",
       "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.",

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.',
+    );
   });
 });

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

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