@pixel-point/toolcraft 0.0.7 → 0.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixel-point/toolcraft",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "license": "SEE LICENSE IN LICENSE.md",
   "type": "module",
   "bin": {

package/src/generate.mjs

@@ -11,7 +11,11 @@ import {
   pathExists,
   removeDirectory,
 } from "./copy-recursive.mjs";
-import { createGeneratedPackageJson, createGeneratedTsConfig } from "./package-json.mjs";
+import {
+  createGeneratedPackageJson,
+  createGeneratedTsConfig,
+  normalizeProjectTitle,
+} from "./package-json.mjs";
 import { rewriteGeneratedText, rewriteTextFiles } from "./rewrite-imports.mjs";
 
 const PACKAGE_ROOT = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
@@ -21,6 +25,13 @@ function writeJson(filePath, value) {
   return fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`);
 }
 
+function escapeHtmlText(value) {
+  return String(value)
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+}
+
 async function readJson(filePath) {
   return JSON.parse(await fs.readFile(filePath, "utf8"));
 }
@@ -100,6 +111,21 @@ async function restoreGeneratedGitignore(targetDir) {
   await fs.rename(npmSafeGitignorePath, gitignorePath);
 }
 
+async function writeGeneratedProjectTitle(targetDir, title) {
+  const indexPath = path.join(targetDir, "index.html");
+  const source = await fs.readFile(indexPath, "utf8");
+  const nextSource = source.replace(
+    /<title>.*?<\/title>/,
+    `<title>${escapeHtmlText(title)}</title>`,
+  );
+
+  if (nextSource === source) {
+    throw new Error(`Unable to update generated app title in ${indexPath}.`);
+  }
+
+  await fs.writeFile(indexPath, nextSource);
+}
+
 async function removeToolcraftTestFiles(toolcraftRoot) {
   async function visit(currentDir) {
     const entries = await fs.readdir(currentDir, { withFileTypes: true });
@@ -190,6 +216,12 @@ export async function generateToolcraft(options = {}) {
   await assertDirectory(sourcePaths.uiSrc, "UI package source");
   await assertDirectory(sourcePaths.toolcraftSrc, "Toolcraft template runtime package source");
   const starterPackageJson = await readJson(path.join(sourcePaths.starterDir, "package.json"));
+  const packageJson = createGeneratedPackageJson({
+    name: options.name ?? path.basename(targetDir),
+    starterPackageJson,
+  });
+  const projectTitle = normalizeProjectTitle(packageJson.name);
+
   await ensureWritableTargetDirectory(targetDir, { force: options.force });
 
   await copyDirectory(sourcePaths.starterDir, targetDir);
@@ -206,11 +238,8 @@ export async function generateToolcraft(options = {}) {
   const changedFiles = await rewriteTextFiles(targetDir, (source) =>
     rewriteGeneratedAppText(source),
   );
+  await writeGeneratedProjectTitle(targetDir, projectTitle);
   await writeToolcraftIntegrityManifest(toolcraftRoot);
-  const packageJson = createGeneratedPackageJson({
-    name: options.name ?? path.basename(targetDir),
-    starterPackageJson,
-  });
 
   await writeJson(path.join(targetDir, "package.json"), packageJson);
   await writeJson(path.join(targetDir, "tsconfig.json"), createGeneratedTsConfig());

package/src/generate.test.mjs

@@ -79,7 +79,15 @@ describe("generateToolcraft", () => {
     assert.equal(packageJson.devDependencies["@playwright/test"], "^1.51.1");
     assert.equal(packageJson.scripts["ai:check"], "node scripts/check-ai-skills.mjs");
     assert.equal(packageJson.scripts.dev, "node scripts/run-vite-on-free-port.mjs dev");
+    assert.equal(
+      packageJson.scripts["dev:restart"],
+      "node scripts/run-vite-on-free-port.mjs dev --toolcraft-restart",
+    );
     assert.equal(packageJson.scripts.preview, "node scripts/run-vite-on-free-port.mjs preview");
+    assert.equal(
+      packageJson.scripts["preview:restart"],
+      "node scripts/run-vite-on-free-port.mjs preview --toolcraft-restart",
+    );
     assert.equal(packageJson.scripts["docs:check"], "node scripts/check-toolcraft-docs.mjs");
     assert.equal(
       packageJson.scripts.test,
@@ -98,6 +106,9 @@ describe("generateToolcraft", () => {
       "pnpm ai:check && pnpm test && pnpm build && pnpm test:browser",
     );
 
+    const indexHtmlSource = await fs.readFile(path.join(targetDir, "index.html"), "utf8");
+    assert.match(indexHtmlSource, /<title>Generated App<\/title>/);
+
     assert.ok(await fs.stat(path.join(targetDir, "playwright.config.ts")));
     const playwrightConfigSource = await fs.readFile(
       path.join(targetDir, "playwright.config.ts"),
@@ -121,6 +132,7 @@ describe("generateToolcraft", () => {
     assert.match(gitignoreSource, /dist/);
     assert.match(gitignoreSource, /playwright-report/);
     assert.match(gitignoreSource, /\.env\.\*/);
+    assert.match(gitignoreSource, /\.toolcraft/);
     await assert.rejects(() => fs.stat(path.join(targetDir, "gitignore")), /ENOENT/);
     assert.ok(await fs.stat(path.join(targetDir, "scripts/check-ai-skills.mjs")));
     assert.ok(await fs.stat(path.join(targetDir, "scripts/toolcraft-port.mjs")));

package/src/package-json.mjs

@@ -9,6 +9,21 @@ export function sanitizePackageName(value) {
   return sanitized || "toolcraft-app";
 }
 
+export function normalizeProjectTitle(value) {
+  const words = String(value ?? "")
+    .trim()
+    .replace(/^@/, "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean);
+
+  const title = words
+    .map((word) => `${word.charAt(0).toUpperCase()}${word.slice(1).toLowerCase()}`)
+    .join(" ");
+
+  return title || "Toolcraft App";
+}
+
 function isWorkspaceDependency(name, specifier) {
   return name.startsWith("@repo/") || String(specifier).startsWith("workspace:");
 }

package/src/package-json.test.mjs

@@ -1,7 +1,11 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
 
-import { createGeneratedPackageJson, sanitizePackageName } from "./package-json.mjs";
+import {
+  createGeneratedPackageJson,
+  normalizeProjectTitle,
+  sanitizePackageName,
+} from "./package-json.mjs";
 
 describe("sanitizePackageName", () => {
   it("normalizes package names for generated apps", () => {
@@ -11,6 +15,15 @@ describe("sanitizePackageName", () => {
   });
 });
 
+describe("normalizeProjectTitle", () => {
+  it("creates a human-readable title from generated project names", () => {
+    assert.equal(normalizeProjectTitle("mesh-gradient"), "Mesh Gradient");
+    assert.equal(normalizeProjectTitle("mesh_gradient.app"), "Mesh Gradient App");
+    assert.equal(normalizeProjectTitle("@pixel-point/mesh-gradient"), "Pixel Point Mesh Gradient");
+    assert.equal(normalizeProjectTitle(""), "Toolcraft App");
+  });
+});
+
 describe("createGeneratedPackageJson", () => {
   it("uses the starter package manifest as source of truth", () => {
     const packageJson = createGeneratedPackageJson({

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

@@ -82,6 +82,12 @@ describe("Toolcraft template component contracts", () => {
 
     expect(segmented?.strictness).toBe("best-fit");
     expect(segmented?.acceptableAlternatives?.join(" ")).toMatch(/Select/i);
+    expect(segmented?.layoutConstraints).toContain(
+      "Segmented controls are full-width controls and must not be placed in two-column inline or half-width layout groups.",
+    );
+    expect(getToolcraftComponentContract("segmented").aiUsageRules).toContain(
+      "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.",
+    );
     expect(select?.useWhen.join(" ")).toMatch(/long labels|many options/i);
     expect(select?.layoutConstraints).toContain(
       "Prefer compact two-column inline layout for related short Select pairs that tune one workflow or entity.",
@@ -150,6 +156,15 @@ describe("Toolcraft template component contracts", () => {
     expect(contract.aiUsageRules).toContain(
       '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.',
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Holding Shift while dragging a vector pad locks movement to the dominant axis; do not build a custom pad just to support axis-constrained movement.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      'Use coordinateMode: "cartesian" only when the product intentionally exposes mathematical Y-up coordinates instead of canvas/screen movement.',
+    );
     expect(contract.aiUsageRules).toContain(
       "Vector is a compound control; acceptance must prove vector.x and vector.y both affect the product output.",
     );
@@ -192,7 +207,7 @@ describe("Toolcraft template component contracts", () => {
       "When the nearest section title already names the switch context, do not duplicate that title as the visible switch label. Use label false for a visual-only toggle and keep the meaning in target/description.",
     );
     expect(switchContract.aiUsageRules).toContain(
-      'A Switch may share an inline row with one related parameter control when the visible switch label is short enough to fit. That row uses equal-width columns; never shrink the switch column to intrinsic width. In section-owned rows, use a short visible label such as "Include" instead of repeating the section title, such as "Include background" inside Background.',
+      'A Switch may share an inline row with one related parameter control when the visible switch label is short enough to fit. That row uses equal-width columns and the same horizontal column gap as paired Select controls; never shrink the switch column to intrinsic width. The non-switch parameter uses label false in that row; if its label is needed, stack the controls instead. In section-owned rows, use a short visible switch label such as "Include" instead of repeating the section title, such as "Include background" inside Background.',
     );
     expect(checkboxContract.aiUsageRules).toContain(
       'Checkbox labels name the setting context only; do not prefix labels with "Enable" or "Disable" because the checkbox already communicates enabled/selected state.',
@@ -207,7 +222,7 @@ describe("Toolcraft template component contracts", () => {
       "Two adjacent Checkbox controls for the same product entity must share one inline row when every visible label fits without truncation. Keep paired labels to short one- or two-word names; the runtime auto-pairs safe adjacent checkboxes by target entity, and generated schemas should stack checkboxes only when any label would truncate.",
     );
     expect(checkboxContract.aiUsageRules).toContain(
-      "A Checkbox may share an inline row with one related parameter control when the visible checkbox label is short enough to fit. That row uses equal-width columns; never shrink the checkbox column to intrinsic width. Hide the checkbox label when the section title provides the visible context.",
+      "A Checkbox may share an inline row with one related parameter control when the visible checkbox label is short enough to fit. That row uses equal-width columns and the same horizontal column gap as paired Select controls; never shrink the checkbox column to intrinsic width. The non-checkbox parameter uses label false in that row; if its label is needed, stack the controls instead. Hide the checkbox label when the section title provides the visible context.",
     );
   });
 
@@ -224,6 +239,12 @@ describe("Toolcraft template component contracts", () => {
     expect(contract.aiUsageRules).toContain(
       "Do not use a custom control to recreate a built-in Slider, RangeSlider, Select, Segmented, Switch, Checkbox, Color, ColorOpacity, Gradient, FontPicker, ImagePicker, FileDrop, TextInput, CodeTextarea, RangeInput, Palette, Actions, CollectionActions, Curves, AnchorGrid, ChannelMixer, Vector, or PanelActions control.",
     );
+    expect(contract.aiUsageRules).toContain(
+      "When a custom control owns a growable, removable, selectable, or reorderable runtime item set, its builtInFitCheck must explicitly check collectionActions and actions before choosing custom; this is based on the value model and user workflow, not on entity names such as masks or glyphs.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Do not justify custom controls with icons, layout, styling, compactness, or custom buttons alone. The fit check must name the product interaction or value model that built-ins cannot express.",
+    );
     expect(contract.aiUsageRules).toContain(
       "Custom controls may use Toolcraft primitives for small app-specific chrome, but must not import or render low-level runtime surfaces or duplicate toolbar, timeline, layers, canvas, panel, or built-in control mechanics.",
     );
@@ -254,6 +275,30 @@ describe("Toolcraft template component contracts", () => {
     expect(contract.aiUsageRules).toContain(
       "Do not use Actions for animation transport; Play, Pause, Resume, Restart, and Scrub belong to the top timeline when timeline behavior exists.",
     );
+    expect(contract.decisionCatalog?.layoutConstraints).toContain(
+      "Do not set an Actions control label to the exact same visible text as its only button; use a short one- or two-word context label such as Ink wash, Palette action, or Current layer while the button keeps the command verb.",
+    );
+    expect(contract.decisionCatalog?.layoutConstraints).toContain(
+      "Actions never use a side-label layout. If a visible label exists, it sits above the buttons.",
+    );
+    expect(contract.decisionCatalog?.layoutConstraints).toContain(
+      "Actions buttons render as a two-column grid. One visible button occupies the left half of the section; two buttons occupy one half each; more than two buttons wrap into additional 50% cells.",
+    );
+    expect(contract.decisionCatalog?.layoutConstraints).toContain(
+      "Do not center or right-align a partial final Actions row; an odd trailing button stays in the left 50% cell.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "For a single visible Actions button, the control label and button label must not be identical; make the control label a concise context and the button label the command.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Render the Actions label above the buttons; do not put the label on the left with buttons on the right.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Render Actions buttons in 50% cells: one button uses the left half, two buttons fill one row, and larger groups continue in two columns.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Do not stretch an odd trailing Actions button full-width.",
+    );
     expect(contract.aiUsageRules).toContain(
       'For local reset-like actions, use product-specific values such as "reset-current-layer" or "reset-palette" and handle them through ToolcraftApp onPanelAction; do not use a bare "reset" value unless the action intentionally runs controls.reset.',
     );
@@ -286,6 +331,10 @@ describe("Toolcraft template component contracts", () => {
       "recommendedMaxItems is advisory only and must not disable the plus button. Use hardMaxItems only when a real product, algorithm, API, export, or measured performance limit requires it.",
     );
     expect(contract.aiUsageRules.join(" ")).toMatch(/TextInput/);
+    expect(contract.aiUsageRules.join(" ")).toMatch(/FontPicker/);
+    expect(contract.aiUsageRules).toContain(
+      "Use FontPicker as the collection item control when each repeated item is a typography/text-style entity; do not split its font, color, opacity, size, case, letter-spacing, or line-height into sibling collection fields.",
+    );
   });
 
   it("documents Palette as a constrained design-token color control", () => {
@@ -358,13 +407,16 @@ describe("Toolcraft template component contracts", () => {
       "Use intrinsic-media for single-layer upload/generation apps so imported media natural size becomes canvas.size.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Use editable-output by default for generated, exportable, shader, poster, badge, wall, banner, thumbnail, and product-output apps where users should see or edit width and height.",
+      "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.",
     );
     expect(contract.aiUsageRules).toContain(
-      "A user-provided base/default size is not a reason to remove size controls; model it as canvas.size plus editable-output unless the prompt or reference explicitly locks output dimensions.",
+      "A user-provided, reference, fixed-format, or base/default size is not a reason to remove size controls; model it as canvas.size plus editable-output so the size is an initial value, not a hidden lock.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Use fixed-output only when the product output size must not be user-editable, and prove that lock with canvasSizingCoverage fixed-output-size acceptance.",
+      "Do not use fixed-output for generated product/output apps with export actions. Reserve fixed-output for non-product internal fixtures where width and height truly must never be user-editable, and prove that lock with canvasSizingCoverage fixed-output-size acceptance.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "A reference or previous app lacking a size editor, or defining a fixed-size baseline, is not a fixed-output reason for a generated product app; product-output clones still use editable-output.",
     );
     expect(contract.aiUsageRules).toContain(
       "Resolved canvas.size exists for every canvas app, but visible Canvas width and Canvas height controls are mandatory only for editable-output sizing and do not depend on settingsTransfer.",
@@ -382,7 +434,7 @@ describe("Toolcraft template component contracts", () => {
       "Aspect ratio presets are the only interaction that may resize both canvas dimensions from a preset; manual size inputs are exact output dimensions.",
     );
     expect(contract.aiUsageRules).toContain(
-      "For non-vector raster, Canvas 2D, WebGL, and WebGPU previews, set canvas.renderScale: true so the runtime adds Resolution scale after canvas sizing. The scale changes backing pixels from 1x to 2x without changing visible canvas size, and adding/enabling it requires targeted browser evidence that the canvas stays responsive at the selected scale.",
+      "For non-vector raster, Canvas 2D, WebGL, and WebGPU previews, set canvas.renderScale: true so the runtime adds Resolution scale after canvas sizing. The scale changes backing pixels from 1 to 2 without changing visible canvas size, and adding/enabling it requires targeted browser evidence that the canvas stays responsive at the selected scale.",
     );
     expect(contract.aiUsageRules).toContain(
       "After enabling canvas.renderScale, verify that canvas preview stays responsive while dragging sliders and other high-frequency controls at the selected scale.",
@@ -448,6 +500,24 @@ describe("Toolcraft template component contracts", () => {
     const slider = getToolcraftComponentContract("slider");
     const rangeSlider = getToolcraftComponentContract("rangeSlider");
 
+    expect(slider.decisionCatalog.requiredAcceptance).toContain(
+      "Prove dragging the slider changes product output or the intended runtime side effect while the drag is in progress, not only after pointer release, blur, Apply, or a final commit.",
+    );
+    expect(slider.aiUsageRules).toContain(
+      "Sliders are live canvas controls: dragging must update runtime state and product output in real time by default.",
+    );
+    expect(slider.aiUsageRules).toContain(
+      "Do not implement slider values as deferred local drafts, Apply-only updates, pointer-up-only commits, or renderer changes that appear only after the user asks again.",
+    );
+    expect(slider.aiUsageRules).toContain(
+      "Slider performance coverage must use a real control-drag scenario; control-change coverage is not enough to prove live canvas feedback or drag smoothness.",
+    );
+    expect(slider.aiUsageRules).toContain(
+      "If a live slider causes jank, optimize the renderer path first: update uniforms or stable buffers, cache expensive inputs, coalesce preview work to requestAnimationFrame, cancel stale async renders, move heavy work off React, or switch renderer strategy.",
+    );
+    expect(slider.aiUsageRules).toContain(
+      "Only in an extreme documented performance ceiling may a slider use a degraded live preview or delayed heavy refinement; the user must still see immediate canvas feedback while dragging and the worklog must record the measured reason.",
+    );
     expect(slider.aiUsageRules).toContain(
       "Slider step means numeric snapping only; it does not make the slider visually discrete by itself.",
     );
@@ -464,16 +534,19 @@ describe("Toolcraft template component contracts", () => {
       "Large or precision stepped ranges such as speed, FPS, rate, duration, density, size, and intensity stay visually continuous even when they declare step.",
     );
     expect(slider.aiUsageRules).toContain(
-      "Use slider unit only for measurement or scale suffixes such as %, px, °, x, s, ms, fps, rows/cols, or similar domain units.",
+      "Use slider unit only for real measurement suffixes such as %, px, °, s, ms, fps, rows/cols, or similar domain units.",
     );
     expect(slider.aiUsageRules).toContain(
       "Do not use unit for repeated entity nouns already named by the section or label, such as Letters + letters, Shape Density / Count + shapes, Words + words, Symbols + symbols, Items + items, Particles + particles, or Layers + layers.",
     );
+    expect(slider.aiUsageRules).toContain(
+      'Do not use unit: "x"; scale, multiplier, intensity, opacity, strength, depth, and shader amount sliders display plain numbers unless a real measurement unit applies.',
+    );
     expect(slider.aiUsageRules).toContain(
       "When the value needs an entity noun to make sense, improve the label or section title instead of appending that noun as the value unit.",
     );
     expect(slider.aiUsageRules).toContain(
-      "Compact symbol/CSS units render tight, such as 70%, 24px, 1.2x, and 8s; word units render with a space, such as 5 cols, when they are truly needed.",
+      "Compact symbol/CSS units render tight, such as 70%, 24px, and 8s; word units render with a space, such as 5 cols, when they are truly needed.",
     );
     expect(slider.aiUsageRules).toContain(
       "Slider valueLabel is editable only when it contains a numeric value; textual state labels such as Normal are display-only and must not expose hover or click editing affordances.",
@@ -499,6 +572,24 @@ describe("Toolcraft template component contracts", () => {
     expect(slider.aiUsageRules).toContain(
       "Do not leave a mode-dependent slider active while making the renderer ignore it; the UI must expose the unavailable state.",
     );
+    expect(rangeSlider.decisionCatalog.requiredAcceptance).toContain(
+      "Prove dragging rangeSlider.lower and rangeSlider.upper both affect product output while the drag is in progress, not only after pointer release, blur, Apply, or a final commit.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "Range sliders are live canvas controls: dragging either thumb must update runtime state and product output in real time by default.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "Do not implement range slider values as deferred local drafts, Apply-only updates, pointer-up-only commits, or renderer changes that appear only after the user asks again.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "Range slider performance coverage must use a real control-drag scenario; control-change coverage is not enough to prove live canvas feedback or drag smoothness.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "If a live range slider causes jank, optimize the renderer path first: update uniforms or stable buffers, cache expensive inputs, coalesce preview work to requestAnimationFrame, cancel stale async renders, move heavy work off React, or switch renderer strategy.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "Only in an extreme documented performance ceiling may a range slider use a degraded live preview or delayed heavy refinement; the user must still see immediate canvas feedback while dragging and the worklog must record the measured reason.",
+    );
     expect(rangeSlider.aiUsageRules).toContain(
       "Range slider step means numeric snapping only; it does not make the range slider visually discrete by itself.",
     );
@@ -515,7 +606,7 @@ describe("Toolcraft template component contracts", () => {
       "Large or precision stepped ranges such as speed, FPS, rate, duration, density, size, and intensity stay visually continuous even when they declare step.",
     );
     expect(rangeSlider.aiUsageRules).toContain(
-      "Use rangeSlider unit only for measurement or scale suffixes; do not use it for repeated entity nouns already named by the section or label.",
+      "Use rangeSlider unit only for real measurement suffixes; do not use it for repeated entity nouns already named by the section or label, and do not use x as a unit.",
     );
     expect(rangeSlider.aiUsageRules).toContain(
       "When a range label needs an entity noun to make sense, improve the label or section title instead of appending that noun as the value unit.",
@@ -568,22 +659,31 @@ describe("Toolcraft template component contracts", () => {
       '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.',
     );
     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 only PNG alpha; it must not make live preview, workspace canvas backing, or video transparent.",
+      "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.",
     );
     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 require visible labels on both controls. The required Background row is the only section-title-owned exception: use the Switch label "Include" and set the background Color control label to false. Color fields in other mixed rows must not be unlabeled.',
+      '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.',
     );
     expect(color.aiUsageRules).toContain(
       "Plain Color popovers must not show opacity controls. If opacity is editable, use ColorOpacity instead.",
     );
     expect(color.aiUsageRules).toContain(
-      "Show visible labels for Color and ColorOpacity controls inside mixed sections that contain any non-color controls.",
+      "Decide color label visibility from the user's point of view. Omit labels for color banks that only add palette variety, such as Accent Shades, Bead Colors, or palette.accent1..5.",
+    );
+    expect(color.aiUsageRules).toContain(
+      "Make color label visibility a group-level decision: do not mix labeled and unlabeled items inside one semantic color bank.",
     );
     expect(color.aiUsageRules).toContain(
-      "Omit visible color field labels only when the section contains color controls and no other control types.",
+      "Keep visible labels when colors edit distinct user-facing entities or roles, such as Fill, Stroke, Background, Connector, Object, or Highlight.",
+    );
+    expect(color.aiUsageRules).toContain(
+      "A color bank can share a section with distribution controls such as Spread, Mix, or Randomness and still keep each color item unlabeled when the section title names the palette context.",
+    );
+    expect(color.aiUsageRules).toContain(
+      "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.",
     );
     expect(gradient.aiUsageRules).toContain(
       "Gradient is a compound control; acceptance must prove gradient.gradientType, gradient.angle, gradient.stops.position, gradient.stops.color, and gradient.stops.opacity all affect the product output when visible.",
@@ -600,6 +700,9 @@ describe("Toolcraft template component contracts", () => {
     expect(fontPicker.aiUsageRules).toContain(
       'Do not recreate FontPicker with a plain Select plus separate sliders; use type: "fontPicker" so the popup mechanics and footer controls stay intact.',
     );
+    expect(fontPicker.aiUsageRules).toContain(
+      "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.",
+    );
     expect(fontPicker.aiUsageRules).toContain(
       "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.",
     );
@@ -743,14 +846,20 @@ describe("Toolcraft template component contracts", () => {
       "Custom renderers must define performance budgets for media import, preview updates, control drags, and export/copy before implementation.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Controls that change renderer workload, such as Char Size, Grid Density, Matrix Scale, Sample Count, Resolution, Blur Radius, Iterations, Particle Count, or Quality, must be tested at min, default, and max values.",
+      "Controls that change renderer workload by changing output dimensions, element count, density, sample count, iteration count, blur/filter radius, shader branch cost, media processing, text layout, or export quality must be tested at min, default, and max values.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Hash differs is not enough for workload controls; tests must assert semantic direction, for example smaller Char Size increases glyph/cell density and larger Char Size decreases it.",
+      "For workload control scenarios, stressFixture is the tested control value. If the app has an independent heavy baseline such as large media, long text, many items, high render scale, or dense source state, declare workloadFixture and apply it before the measured control interaction.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Hash differs is not enough for workload controls; tests must assert semantic direction, such as density increasing item count or size changes reducing/increasing rendered cells.",
     );
     expect(contract.aiUsageRules).toContain(
       "Performance tests must use representative fixtures and the same renderer/export path as the running app, not only tiny 32px fixtures or isolated helper state.",
     );
+    expect(contract.aiUsageRules).toContain(
+      'Media-import workload fixtures and media workload baselines must use fixture kind "media" with numeric width and height at least 1920x1080-equivalent; 640x480 preview fixtures cannot satisfy upload, effect-control, or image-processing performance coverage.',
+    );
     expect(contract.aiUsageRules).toContain(
       "Slider drags and high-frequency controls must debounce or coalesce preview work, cancel stale async renders, and avoid re-decoding media on every control change.",
     );
@@ -790,8 +899,19 @@ describe("Toolcraft template component contracts", () => {
     expect(contract.aiUsageRules).toContain(
       'productRepresentation "mixed" is valid only when rendererTechnique.layers proves at least two different content families.',
     );
+    expect(contract.aiUsageRules).toContain(
+      "Custom renderer apps must declare rendererPipeline with render passes, cache keys, execution location, preview/export quality, and interaction invalidation before implementation.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Render Pipeline Inventory must explain which runtime targets invalidate each expensive pass; high-frequency interactions such as animation frames, drag, zoom, pan, timeline playback, and mask movement must not invalidate upstream decode/preprocess/pixel-transform work unless that target truly changes the upstream result.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Cache-sensitive render passes such as decode, preprocess, pixel-transform, text-layout, rasterize, and composite must declare cache keys so tests can reject full recomputation on every control change.",
+    );
     expect(contract.aiUsageRules.join("\n")).toMatch(/rendererTechnique/);
     expect(contract.aiUsageRules.join("\n")).toMatch(/rendererTechnique\.layers/);
+    expect(contract.aiUsageRules.join("\n")).toMatch(/rendererPipeline/);
+    expect(contract.aiUsageRules.join("\n")).toMatch(/Render Pipeline Inventory/);
     expect(contract.aiUsageRules.join("\n")).toMatch(/sourceRepresentation/);
     expect(contract.aiUsageRules.join("\n")).toMatch(/productRepresentation/);
     expect(contract.aiUsageRules.join("\n")).toMatch(/previewRenderer/);
@@ -809,11 +929,14 @@ describe("Toolcraft template component contracts", () => {
       "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.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Pixel-output renderers must use WebGL or WebGPU even when the scene is static.",
+      "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.",
     );
     expect(contract.aiUsageRules).toContain(
       "Procedural pixel renderers, shader-like effects, animated mesh gradients, and large exportable previews should use WebGL or WebGPU for pixel work instead of main-thread ImageData loops.",
     );
+    expect(contract.aiUsageRules).toContain(
+      "Detail-heavy Canvas 2D pixel/media renderers may stay on CPU only when rendererTechnique records measured stress evidence for rejecting WebGL/WebGPU; if the heavy media stress fails, move pixel work to GPU instead of lowering quality.",
+    );
     expect(contract.aiUsageRules).toContain(
       "WebGL and WebGPU renderers must initialize contexts, programs, shaders, pipelines, textures, and large buffers once, then update uniforms or stable buffers when controls change.",
     );
@@ -830,11 +953,14 @@ describe("Toolcraft template component contracts", () => {
       "Animated preview renderers must suspend or coalesce non-essential animation work while the user drags, pans, pinches, zooms, or centers the canvas viewport, then resume from the correct timeline or autonomous time without changing the user's play/pause state.",
     );
     expect(contract.aiUsageRules).toContain(
-      "If a generated app uses ImageData, getImageData, or putImageData for procedural output, performance validation must fail unless the renderer is converted to GPU rendering or the CPU path is removed.",
+      "If a generated app uses ImageData, getImageData, or putImageData for procedural output, performance validation must fail unless rendererTechnique records measured WebGL/WebGPU comparison evidence that the CPU path preserves quality and responsiveness, or the renderer is moved to GPU.",
     );
     expect(contract.aiUsageRules).toContain(
       "Performance matrices must declare rendererStrategy so tests can distinguish none, dom, svg, canvas-2d, webgl, and webgpu renderer paths.",
     );
+    expect(contract.aiUsageRules).toContain(
+      "If a renderer cannot meet the budget, first optimize renderer technique, caching, invalidation, scheduling, and critical-path work. Only change exposed product ranges, work units, or controls after recording measured evidence that the requested quality ceiling is impossible; do not silently reduce product quality to pass budgets.",
+    );
   });
 
   it("documents reference runtime clone mode as a tested composition contract", () => {
@@ -1156,10 +1282,10 @@ describe("Toolcraft template component contracts", () => {
       '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.',
     );
     expect(contract.aiUsageRules).toContain(
-      "Product-output apps must pass the includeBackground runtime value to createToolcraftPngExportCanvas only for PNG alpha.",
+      "Product-output apps must pass the includeBackground runtime value to createToolcraftPngExportCanvas for PNG alpha and call shouldIncludeToolcraftPreviewBackground(state) for live preview product background.",
     );
     expect(contract.aiUsageRules).toContain(
-      "PNG export must use createToolcraftPngExportCanvas so background transparency and selected image dimensions or retina fallback are applied consistently without making live preview, workspace canvas backing, or video transparent.",
+      "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.",
     );
     expect(contract.aiUsageRules).toContain(
       "Video export must keep product background and use getToolcraftRetinaExportSize for retina dimensions.",
@@ -1184,15 +1310,39 @@ describe("Toolcraft template component contracts", () => {
   it("documents file upload ownership across single-layer and multi-layer apps", () => {
     const contract = getToolcraftComponentContract("fileDrop");
 
-    expect(contract.commands).toEqual(["media.delete", "media.import"]);
+    expect(contract.commands).toEqual(["media.delete", "media.import", "media.reorder"]);
+    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(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Do not add procedural Source Preset modes only to avoid an empty canvas. A default procedural or reference source is allowed only when the prompt/reference explicitly defines it and the worklog records that evidence.",
+    );
     expect(contract.aiUsageRules).toContain(
       "In single-layer apps, the runtime shows the uploaded image as the fileDrop preview and provides the clear action.",
     );
+    expect(contract.aiUsageRules).toContain(
+      "In file mode, the runtime shows uploaded files as a sortable list with paperclip icons, file names, remove buttons, and --border/5 separators.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "In single-layer apps, global Reset controls and section reset must remove uploaded fileDrop source media and return the fileDrop target to defaultValue.",
+    );
     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(
-      "When multiple uploaded images are present, the runtime appends media, shows a four-column preview grid, puts the add-more tile last, and exposes per-image removal.",
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Dragging thumbnails reorders runtime mediaAssets; preview, export, and renderer mapping must consume that media order instead of maintaining a separate product-only order.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Do not create custom upload buttons, file lists, or file sorting for generic source uploads when fileDrop can represent the source set.",
     );
     expect(contract.aiUsageRules).toContain(
       "In multi-layer apps, deletion and visibility belong to the Layers panel; fileDrop remains an upload target.",
@@ -1226,6 +1376,9 @@ describe("Toolcraft template component contracts", () => {
     expect(contract.aiUsageRules).toContain(
       "Render multiple related color fields in one section with at most two colors per row.",
     );
+    expect(contract.aiUsageRules).toContain(
+      "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.",
+    );
   });
 
   it("documents CodeTextarea as generic multiline text input", () => {
@@ -1238,10 +1391,16 @@ describe("Toolcraft template component contracts", () => {
       "CodeTextarea is the multiline text input for any potentially long value, not only source code.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Use text for short single-line strings such as names, small numeric values, compact prompts, titles, and short tokens.",
+      "Do not use CodeTextarea for short single-line canvas text, button labels, names, titles, captions, badges, or short tokens; use TextInput.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Use code when the user may enter long prompts, multiline text, JSON, CSS, shader code, scripts, templates, or other long structured data.",
+      "Use text for short single-line strings such as names, button labels, small numeric values, compact prompts, titles, captions, and short tokens.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Use code only when the user may enter long prompts, multiline text, instructions, JSON, CSS, shader code, scripts, templates, or other long structured data.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "If CodeTextarea has a short single-line default value, the schema description must make the long, multiline, or structured-content reason explicit.",
     );
     expect(contract.aiUsageRules).toContain(
       "CodeTextarea is a content editor and applies values while typing; do not wait for blur, Enter, or Cmd/Ctrl+Enter to update runtime state.",
@@ -1257,6 +1416,9 @@ describe("Toolcraft template component contracts", () => {
     expect(contract.visualComponent).toBe("TextInput");
     expect(contract.defaultSectionLayout).toBe("grouped");
     expect(contract.labelPolicy).toBe("required");
+    expect(contract.aiUsageRules).toContain(
+      "TextInput owns short single-line product text: button labels, labels on the canvas, names, titles, captions, badges, short tokens, and compact prompts.",
+    );
     expect(contract.aiUsageRules).toContain(
       'TextInput commitMode defaults to "content": text content, prompts, names, tokens, titles, and instructions apply while typing.',
     );