@pixel-point/toolcraft 0.0.4 → 0.0.6

package/package.json

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

package/scripts/prepare-pack.mjs

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import fs from "node:fs/promises";
 
 import { copyDirectory, removeDirectory } from "../src/copy-recursive.mjs";
 
@@ -27,3 +28,7 @@ await removeDirectory(templatesRoot);
 for (const source of sources) {
   await copyDirectory(source.from, source.to);
 }
+
+const starterGitignorePath = path.join(templatesRoot, "starter/.gitignore");
+const starterPackGitignorePath = path.join(templatesRoot, "starter/gitignore");
+await fs.copyFile(starterGitignorePath, starterPackGitignorePath);

package/src/generate.mjs

@@ -88,6 +88,18 @@ async function renameGeneratedAppFiles(targetDir) {
   }
 }
 
+async function restoreGeneratedGitignore(targetDir) {
+  const npmSafeGitignorePath = path.join(targetDir, "gitignore");
+  const gitignorePath = path.join(targetDir, ".gitignore");
+
+  if (!(await pathExists(npmSafeGitignorePath))) {
+    return;
+  }
+
+  await fs.rm(gitignorePath, { force: true });
+  await fs.rename(npmSafeGitignorePath, gitignorePath);
+}
+
 async function removeToolcraftTestFiles(toolcraftRoot) {
   async function visit(currentDir) {
     const entries = await fs.readdir(currentDir, { withFileTypes: true });
@@ -181,6 +193,7 @@ export async function generateToolcraft(options = {}) {
   await ensureWritableTargetDirectory(targetDir, { force: options.force });
 
   await copyDirectory(sourcePaths.starterDir, targetDir);
+  await restoreGeneratedGitignore(targetDir);
   await renameGeneratedAppFiles(targetDir);
 
   const toolcraftRoot = path.join(targetDir, "src/toolcraft");

package/src/generate.test.mjs

@@ -116,6 +116,12 @@ describe("generateToolcraft", () => {
     assert.ok(await fs.stat(path.join(targetDir, "e2e/performance-helpers.ts")));
     assert.ok(await fs.stat(path.join(targetDir, "e2e/product-observable-helpers.ts")));
     assert.ok(await fs.stat(path.join(targetDir, "e2e/canvas-handle-helpers.ts")));
+    const gitignoreSource = await fs.readFile(path.join(targetDir, ".gitignore"), "utf8");
+    assert.match(gitignoreSource, /node_modules/);
+    assert.match(gitignoreSource, /dist/);
+    assert.match(gitignoreSource, /playwright-report/);
+    assert.match(gitignoreSource, /\.env\.\*/);
+    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")));
     assert.ok(await fs.stat(path.join(targetDir, "scripts/toolcraft-port.test.mjs")));

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

@@ -345,6 +345,24 @@ describe("Toolcraft template component contracts", () => {
     expect(contract.aiUsageRules).toContain(
       "The runtime Canvas width and Canvas height block uses the technical Setup section and renders without a visible section heading; do not add a separate Canvas section label above these fields.",
     );
+    expect(contract.aiUsageRules).toContain(
+      "When the user manually edits Canvas width or Canvas height, the runtime keeps the typed dimension, keeps the other dimension unchanged, switches Aspect ratio to Custom, and shows the reduced current ratio in the custom ratio inputs.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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 a full pnpm verify:perf checkpoint.",
+    );
+    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.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Performance fixes for canvas.renderScale must preserve the selected visual quality; do not silently downsample, stretch a lower-resolution backing canvas, blur output, or clamp canvas.renderScale below the user's chosen value to pass budgets.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Do not enable canvas.renderScale for DOM/SVG/vector-native previews; preserve vector fidelity through native vector rendering instead of raster supersampling.",
+    );
   });
 
   it("documents persistence as a runtime-owned policy instead of ad hoc localStorage", () => {
@@ -392,7 +410,7 @@ describe("Toolcraft template component contracts", () => {
       "A settings-transfer section with only Export Settings and Import Settings means canvas sizing is not editable-output or canvas size controls already exist elsewhere.",
     );
     expect(contract.aiUsageRules).toContain(
-      "When settings transfer and editable-output canvas sizing are both enabled, the first technical Setup runtime section contains Export Settings, Import Settings, Aspect ratio, Canvas width, and Canvas height in that order and renders without a visible section heading.",
+      "When settings transfer and editable-output canvas sizing are both enabled, the first technical Setup runtime section contains Export Settings, Import Settings, Aspect ratio, Canvas width, Canvas height, and optional Resolution scale in that order and renders without a visible section heading.",
     );
   });
 
@@ -415,6 +433,21 @@ describe("Toolcraft template component contracts", () => {
     expect(slider.aiUsageRules).toContain(
       "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.",
+    );
+    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(
+      "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.",
+    );
+    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.",
+    );
     expect(slider.aiUsageRules).toContain(
       "Schema sliders render stacked at full width; do not put sliders in two-column inline layout groups.",
     );
@@ -451,6 +484,15 @@ describe("Toolcraft template component contracts", () => {
     expect(rangeSlider.aiUsageRules).toContain(
       "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.",
+    );
+    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.",
+    );
+    expect(rangeSlider.aiUsageRules).toContain(
+      "Compact symbol/CSS units render tight, such as 20% – 80% or 12px – 48px; word units render with a space when truly needed.",
+    );
     expect(rangeSlider.aiUsageRules).toContain(
       "RangeSlider is always a full-width two-thumb control; never place it in an inline two-column layout group with another slider or range slider.",
     );
@@ -686,7 +728,13 @@ describe("Toolcraft template component contracts", () => {
       "Performance matrices must declare rendererWorkload as none, simple-composition, text-output, vector-output, or pixel-output.",
     );
     expect(contract.aiUsageRules).toContain(
-      "A full performance checkpoint must run with pnpm verify:perf when the first working app version exists, renderer/canvas/animation/export/timeline/layers change, a bug that previously broke functionality is fixed, any performance optimization lands, or the user requests performance, lag, jank, animation speed, or drag/zoom stabilization work.",
+      "A full performance checkpoint must run with pnpm verify:perf when the first working app version exists, renderer/canvas/animation/export/timeline/layers change, canvas.renderScale or the Resolution scale retina slider is added/enabled, a bug that previously broke functionality is fixed, any performance optimization lands, or the user requests performance, lag, jank, animation speed, or drag/zoom stabilization work.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Performance fixes must preserve selected output and preview quality; do not reduce image quality, selected renderScale, export resolution, source media fidelity, or canvas backing pixels as the hidden way to pass budgets.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "When canvas or slider interactions lag, diagnose where the slowdown comes from before changing output quality: renderer technique, React update frequency, decoded media, shader/program setup, buffer uploads, layout work, async render cancellation, or animation scheduling.",
     );
     expect(contract.aiUsageRules).toContain(
       "Renderer specs must include a Renderer Technique Decision Matrix with sourceRepresentation, productRepresentation, previewRenderer, exportRenderer, rendererWorkload, rendererStrategy, whyNotAlternativeStrategies, fidelityRisks, and performanceRisks.",
@@ -849,6 +897,9 @@ describe("Toolcraft template component contracts", () => {
     expect(contract.aiUsageRules).toContain(
       "If there is no useful product-specific explanation, omit control.description; the runtime should not show a help tooltip for that label.",
     );
+    expect(contract.aiUsageRules).toContain(
+      "Do not add control.description to sequential colors such as Color 1, Color 2, or simple palette controls such as Spread when the section title already names the color or palette context.",
+    );
     expect(contract.aiUsageRules).toContain(
       "For compound controls such as FontPicker, do not use control.description to enumerate the control's owned fields. FontPicker descriptions must not recap font family, weight, size, case, color, opacity, letter spacing, or line height; use description only for non-obvious product scope or omit it.",
     );
@@ -1101,6 +1152,12 @@ describe("Toolcraft template component contracts", () => {
     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(
+      "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.",
+    );
     expect(contract.aiUsageRules).toContain(
       "In multi-layer apps, deletion and visibility belong to the Layers panel; fileDrop remains an upload target.",
     );

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

@@ -49,6 +49,11 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       'Small semantic integer domains such as rows, cols, gaps, jitter, counts, levels, bands, passes, points, tiles, and segments must use variant: "discrete".',
       'Finite animation step domains such as flip depth, character count, glyph steps, and frame steps must use variant: "discrete" when the marker count stays within the Toolcraft visual budget.',
       "Large or precision stepped ranges such as speed, FPS, rate, duration, density, size, and intensity stay visually continuous even when they declare step.",
+      "Use slider unit only for measurement or scale suffixes such as %, px, °, x, s, ms, fps, rows/cols, or similar domain units.",
+      "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.",
+      "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.",
+      "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.",
+      "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.",
       "Schema sliders render stacked at full width; do not put sliders in two-column inline layout groups.",
       "The fontPicker component is the only built-in exception with two internal footer sliders for letter spacing and line height.",
       "For a small named option set, prefer Select or Segmented instead of forcing a discrete Slider.",
@@ -94,6 +99,9 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       'Small semantic integer domains such as rows, cols, gaps, jitter, counts, levels, bands, passes, points, tiles, and segments must use variant: "discrete".',
       'Finite animation step domains such as flip depth, character count, glyph steps, and frame steps must use variant: "discrete" when the marker count stays within the Toolcraft visual budget.',
       "Large or precision stepped ranges such as speed, FPS, rate, duration, density, size, and intensity stay visually continuous even when they declare step.",
+      "Use rangeSlider unit only for measurement or scale suffixes; do not use it for repeated entity nouns already named by the section or label.",
+      "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.",
+      "Compact symbol/CSS units render tight, such as 20% – 80% or 12px – 48px; word units render with a space when truly needed.",
       "RangeSlider is always a full-width two-thumb control; never place it in an inline two-column layout group with another slider or range slider.",
       "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; do not create custom parsers for RangeSlider labels.",
@@ -806,6 +814,7 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       ],
       layoutConstraints: [
         "FileDrop lives in the controls panel; single-layer apps use its preview and clear behavior.",
+        "When fileDrop has multiple: true and more than one image is present, the runtime renders a four-column thumbnail grid with the add-more tile last.",
       ],
       requiredAcceptance: [
         "Prove file import changes media state and product output; prove clear removes source material.",
@@ -814,6 +823,8 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
     aiUsageRules: [
       "Use fileDrop for source material uploads in the controls panel, not on the canvas.",
       "In single-layer apps, the runtime shows the uploaded image as the fileDrop preview and provides the clear action.",
+      "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.",
+      "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.",
       "In multi-layer apps, deletion and visibility belong to the Layers panel; fileDrop remains an upload target.",
     ],
     commands: ["media.delete", "media.import"],
@@ -942,11 +953,18 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       "Choose canvas.sizing.mode from product context instead of copying a universal 1024px artboard.",
       "Use intrinsic-media for single-layer upload/generation apps so imported media natural size becomes canvas.size.",
       "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.",
+      "When no explicit product size is provided, the runtime default canvas is 16:9 at 1920x1080; do not reset a new product-output app to 1:1 unless the product meaning requires it.",
       "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.",
       "Use fixed-output only when the product output size must not be user-editable, and prove that lock with canvasSizingCoverage fixed-output-size acceptance.",
       "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.",
       "If canvas.size is provided without an explicit sizing mode, defineToolcraft treats it as editable-output and adds Canvas width and Canvas height controls.",
       "The runtime Canvas width and Canvas height block uses the technical Setup section and renders without a visible section heading; do not add a separate Canvas section label above these fields.",
+      "When the user manually edits Canvas width or Canvas height, the runtime keeps the typed dimension, keeps the other dimension unchanged, switches Aspect ratio to Custom, and shows the reduced current ratio in the custom ratio inputs.",
+      "Aspect ratio presets are the only interaction that may resize both canvas dimensions from a preset; manual size inputs are exact output dimensions.",
+      "For non-vector raster, Canvas 2D, WebGL, and WebGPU previews, set canvas.renderScale: true so the runtime adds Resolution scale after canvas sizing. The scale changes backing pixels from 1x to 2x without changing visible canvas size, and adding/enabling it requires a full pnpm verify:perf checkpoint.",
+      "After enabling canvas.renderScale, verify that canvas preview stays responsive while dragging sliders and other high-frequency controls at the selected scale.",
+      "Performance fixes for canvas.renderScale must preserve the selected visual quality; do not silently downsample, stretch a lower-resolution backing canvas, blur output, or clamp canvas.renderScale below the user's chosen value to pass budgets.",
+      "Do not enable canvas.renderScale for DOM/SVG/vector-native previews; preserve vector fidelity through native vector rendering instead of raster supersampling.",
     ],
     capabilities: ["drag", "zoom", "radar", "upload", "editable-size"],
     commands: [
@@ -993,7 +1011,7 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       "Do not hand-roll settings import/export through app routes, hidden file inputs, or panelActions.",
       "Settings transfer appears as the first technical Setup controls-panel section when enabled and renders without a visible section heading; it imports and exports control values, canvas size, and timeline state.",
       "A settings-transfer section with only Export Settings and Import Settings means canvas sizing is not editable-output or canvas size controls already exist elsewhere.",
-      "When settings transfer and editable-output canvas sizing are both enabled, the first technical Setup runtime section contains Export Settings, Import Settings, Aspect ratio, Canvas width, and Canvas height in that order and renders without a visible section heading.",
+      "When settings transfer and editable-output canvas sizing are both enabled, the first technical Setup runtime section contains Export Settings, Import Settings, Aspect ratio, Canvas width, Canvas height, and optional Resolution scale in that order and renders without a visible section heading.",
       "Keep sticky footer panelActions for product delivery actions only, such as Export PNG, Export Video, Copy, Generate, Apply, or Download.",
     ],
     capabilities: ["settings-import-export"],
@@ -1040,7 +1058,9 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       "Expensive renderers must cache decoded media, source pixels, glyph atlases, gradients, and other reusable inputs by media id, canvas size, and stable control keys.",
       "Slider drags and high-frequency controls must debounce or coalesce preview work, cancel stale async renders, and avoid re-decoding media on every control change.",
       "Performance matrices must declare rendererWorkload as none, simple-composition, text-output, vector-output, or pixel-output.",
-      "A full performance checkpoint must run with pnpm verify:perf when the first working app version exists, renderer/canvas/animation/export/timeline/layers change, a bug that previously broke functionality is fixed, any performance optimization lands, or the user requests performance, lag, jank, animation speed, or drag/zoom stabilization work.",
+      "A full performance checkpoint must run with pnpm verify:perf when the first working app version exists, renderer/canvas/animation/export/timeline/layers change, canvas.renderScale or the Resolution scale retina slider is added/enabled, a bug that previously broke functionality is fixed, any performance optimization lands, or the user requests performance, lag, jank, animation speed, or drag/zoom stabilization work.",
+      "Performance fixes must preserve selected output and preview quality; do not reduce image quality, selected renderScale, export resolution, source media fidelity, or canvas backing pixels as the hidden way to pass budgets.",
+      "When canvas or slider interactions lag, diagnose where the slowdown comes from before changing output quality: renderer technique, React update frequency, decoded media, shader/program setup, buffer uploads, layout work, async render cancellation, or animation scheduling.",
       "Renderer specs must include a Renderer Technique Decision Matrix with sourceRepresentation, productRepresentation, previewRenderer, exportRenderer, rendererWorkload, rendererStrategy, whyNotAlternativeStrategies, fidelityRisks, and performanceRisks.",
       "Custom renderer apps must mirror the Renderer Technique Decision Matrix in typed rendererTechnique config so validation can reject contradictory renderer choices.",
       "Custom renderer specs must include a Renderer Layer Inventory and mirror it in typed rendererTechnique.layers so dense raster backgrounds cannot silently rasterize semantic foreground output.",
@@ -1126,6 +1146,7 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       "Use control.description for the short help tooltip shown beside visible labels. It must describe the product behavior or output affected by the control, not restate the label.",
       "Do not write label-recap descriptions such as Adjusts Opacity, Controls Speed, or Sets Background.",
       "If there is no useful product-specific explanation, omit control.description; the runtime should not show a help tooltip for that label.",
+      "Do not add control.description to sequential colors such as Color 1, Color 2, or simple palette controls such as Spread when the section title already names the color or palette context.",
       "For compound controls such as FontPicker, do not use control.description to enumerate the control's owned fields. FontPicker descriptions must not recap font family, weight, size, case, color, opacity, letter spacing, or line height; use description only for non-obvious product scope or omit it.",
       "The runtime renders a filled Phosphor question icon beside each visible ControlFieldLabel; generated apps must not hand-build their own help icon beside built-in labels.",
       "If a source label is unavoidably long, keep the visible label concise and rely on the native title tooltip for the full text.",

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

@@ -237,7 +237,7 @@ export const TOOLCRAFT_DECISION_CONTRACT = [
     currentConstraint:
       "Performance coverage currently asks every visible non-action control for a performance scenario.",
     desiredBehavior:
-      "Heavy workload controls get min/default/max workload coverage; ordinary controls get lightweight responsiveness coverage so they cannot hang or break input. Animated previews suspend or coalesce non-essential animation work during canvas drag, pan, pinch, zoom, and radar/center interactions without changing user playback state. A full performance checkpoint is required when the first working version of an app exists, when renderer/canvas/animation/export/timeline/layers change, after fixing a bug that previously broke functionality, after any performance optimization, and whenever the user asks to optimize performance, fix lag, remove jank, speed up animation, or stabilize drag/zoom. Browser performance tests read budgets from typed performance config and run sequentially for stable measurements.",
+      "Heavy workload controls get min/default/max workload coverage; ordinary controls get lightweight responsiveness coverage so they cannot hang or break input. Animated previews suspend or coalesce non-essential animation work during canvas drag, pan, pinch, zoom, and radar/center interactions without changing user playback state. A full performance checkpoint is required when the first working version of an app exists, when renderer/canvas/animation/export/timeline/layers change, when canvas.renderScale or the Resolution scale retina slider is added/enabled, after fixing a bug that previously broke functionality, after any performance optimization, and whenever the user asks to optimize performance, fix lag, remove jank, speed up animation, or stabilize drag/zoom. Performance fixes must preserve the selected render scale and must not pass budgets by silently downsampling, stretching a lower-resolution backing canvas, blurring output, or clamping canvas.renderScale below the user's chosen value. Browser performance tests read budgets from typed performance config and run sequentially for stable measurements.",
     enforcement: ["performance-validator", "browser-helper", "starter-agents"],
     id: "performance-coverage-levels",
     level: "invariant",

package/templates/runtime/react/canvas-shell.test.tsx

@@ -226,7 +226,7 @@ describe("CanvasShell", () => {
     await waitFor(() => {
       expect(screen.getByTestId("canvas-offset").textContent).toBe("-8,12");
     });
-    expect(screen.getByTestId("canvas-zoom").textContent).toBe("70");
+    expect(screen.getByTestId("canvas-zoom").textContent).toBe("100");
   });
 
   it("zooms the canvas world from a trackpad pinch around the pointer", async () => {
@@ -243,7 +243,7 @@ describe("CanvasShell", () => {
     const world = canvas.querySelector("[data-toolcraft-canvas-world]") as HTMLElement;
     mockCanvasRect(canvas);
 
-    expect(world.style.transform).toBe("translate(-50%, -50%) translate(0px, 0px) scale(0.7)");
+    expect(world.style.transform).toBe("translate(-50%, -50%) translate(0px, 0px) scale(1)");
 
     const wheelEvent = new WheelEvent("wheel", {
       bubbles: true,
@@ -257,10 +257,10 @@ describe("CanvasShell", () => {
     expect(canvas.dispatchEvent(wheelEvent)).toBe(false);
     expect(wheelEvent.defaultPrevented).toBe(true);
     await waitFor(() => {
-      expect(screen.getByTestId("canvas-zoom").textContent).toBe("120");
+      expect(screen.getByTestId("canvas-zoom").textContent).toBe("150");
     });
-    expect(world.style.transform).toContain("translate(-142.857142857142");
-    expect(world.style.transform).toContain("scale(1.2)");
+    expect(world.style.transform).toContain("translate(-100px");
+    expect(world.style.transform).toContain("scale(1.5)");
   });
 
   it("prevents panel pinch gestures without moving the canvas viewport", async () => {
@@ -294,7 +294,7 @@ describe("CanvasShell", () => {
 
     expect(overlay.dispatchEvent(wheelEvent)).toBe(false);
     expect(wheelEvent.defaultPrevented).toBe(true);
-    expect(screen.getByTestId("canvas-zoom").textContent).toBe("70");
+    expect(screen.getByTestId("canvas-zoom").textContent).toBe("100");
     expect(screen.getByTestId("canvas-offset").textContent).toBe("0,0");
     expect(overlay.closest("[data-toolcraft-canvas-world]")).toBeNull();
 
@@ -306,7 +306,7 @@ describe("CanvasShell", () => {
 
     expect(overlay.dispatchEvent(scrollEvent)).toBe(true);
     expect(scrollEvent.defaultPrevented).toBe(false);
-    expect(screen.getByTestId("canvas-zoom").textContent).toBe("70");
+    expect(screen.getByTestId("canvas-zoom").textContent).toBe("100");
     expect(screen.getByTestId("canvas-offset").textContent).toBe("0,0");
   });
 

package/templates/runtime/react/controls-panel.test.tsx

@@ -436,6 +436,101 @@ describe("ControlsPanel", () => {
     );
   });
 
+  it("suppresses obvious help icons in sequential color sections", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: false },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                color1: {
+                  defaultValue: { hex: "#DFFF1A" },
+                  description: "Sets the first bead color.",
+                  label: "Color 1",
+                  target: "beads.color1",
+                  type: "color",
+                },
+                color2: {
+                  defaultValue: { hex: "#8CFF3A" },
+                  description: "Sets the second bead color.",
+                  label: "Color 2",
+                  target: "beads.color2",
+                  type: "color",
+                },
+                color3: {
+                  defaultValue: { hex: "#F4FF5A" },
+                  description: "Sets the third bead color.",
+                  label: "Color 3",
+                  target: "beads.color3",
+                  type: "color",
+                },
+                color4: {
+                  defaultValue: { hex: "#B8FF2E" },
+                  description: "Sets the fourth bead color.",
+                  label: "Color 4",
+                  target: "beads.color4",
+                  type: "color",
+                },
+                color5: {
+                  defaultValue: { hex: "#ECFF68" },
+                  description: "Sets the fifth bead color.",
+                  label: "Color 5",
+                  target: "beads.color5",
+                  type: "color",
+                },
+                colorSpread: {
+                  defaultValue: 34,
+                  description:
+                    "Controls how often beads use colors 2-5 instead of Color 1.",
+                  label: "Spread",
+                  max: 100,
+                  min: 0,
+                  target: "beads.colorSpread",
+                  type: "slider",
+                  unit: "%",
+                },
+              },
+              layoutGroups: [
+                {
+                  columns: 2,
+                  controls: ["color1", "color2"],
+                  layout: "inline",
+                },
+                {
+                  columns: 2,
+                  controls: ["color3", "color4"],
+                  layout: "inline",
+                },
+              ],
+              title: "Bead Colors",
+            },
+            {
+              controls: {
+                includeBackground: {
+                  defaultValue: true,
+                  description:
+                    "Controls PNG background transparency while preview and video keep the background.",
+                  label: "Include",
+                  target: "export.includeBackground",
+                  type: "switch",
+                },
+              },
+              title: "Background",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    renderControlsPanelWithSchema(schema);
+
+    expect(screen.queryByRole("button", { name: "Color 5 help" })).toBeNull();
+    expect(screen.queryByRole("button", { name: "Spread help" })).toBeNull();
+    expect(screen.getByRole("button", { name: "Include help" })).toBeTruthy();
+  });
+
   it("renders short visible toggle plus parameter rows as equal-width toggle-parameter rows", () => {
     const schema = defineToolcraft({
       canvas: { enabled: false },
@@ -1534,6 +1629,46 @@ describe("ControlsPanel", () => {
       container.querySelector('[data-slot="slider"][data-variant="discrete"]'),
     ).toBeNull();
     expect(container.querySelectorAll('[data-slot="slider-marker"]')).toHaveLength(0);
+    expect(container.textContent).toContain("118 cols/s");
+  });
+
+  it("keeps textual slider value labels non-editable", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                letterSpacing: {
+                  defaultValue: 2,
+                  label: "Letter spacing",
+                  max: 4,
+                  min: 0,
+                  step: 1,
+                  target: "text.letterSpacing",
+                  type: "slider",
+                  valueLabel: "Normal",
+                },
+              },
+              title: "Text",
+            },
+          ],
+          title: "Generation Controls",
+        },
+      },
+    });
+
+    renderControlsPanelWithSchema(schema);
+
+    const valueLabel = screen
+      .getAllByText("Normal")
+      .find((node) => node.getAttribute("aria-hidden") !== "true");
+
+    expect(screen.queryByRole("button", { name: "Edit Letter spacing value" })).toBeNull();
+    expect(valueLabel).toBeTruthy();
+    expect(valueLabel?.className).toContain("cursor-default");
+    expect(valueLabel?.className).not.toContain("cursor-text");
   });
 
   it("keeps schema sliders stacked even when a layout group asks for an inline row", () => {
@@ -1589,6 +1724,8 @@ describe("ControlsPanel", () => {
     expect(container.querySelector('[data-control-layout="inline"]')).toBeNull();
     expect(fpsSlider).toBeTruthy();
     expect(container.querySelectorAll('[data-slot="slider-marker"]').length).toBeGreaterThan(0);
+    expect(container.textContent).toContain("17 fps");
+    expect(container.textContent).toContain("3.7x");
   });
 
   it("passes schema disabled state into slider controls", () => {
@@ -2283,6 +2420,76 @@ describe("ControlsPanel", () => {
     expect(screen.getByTestId("media-count").textContent).toBe("0");
   });
 
+  it("renders multi-image file uploads as an add-last thumbnail grid", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true, upload: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                source: {
+                  accept: "PNG, SVG",
+                  label: "Images",
+                  multiple: true,
+                  target: "input.sources",
+                  type: "fileDrop",
+                },
+              },
+              layout: "standalone",
+              title: "Input",
+            },
+          ],
+          title: "Generation Controls",
+        },
+      },
+    });
+
+    const { container } = renderControlsPanelWithSchema(schema, undefined, {
+      layers: [
+        { id: "layer-1", kind: "layer", name: "one", visible: true },
+        { id: "layer-2", kind: "layer", name: "two", visible: true },
+      ],
+      mediaAssets: [
+        {
+          dataUrl:
+            "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='96' height='96' viewBox='0 0 96 96'%3E%3Crect width='96' height='96' fill='%23777'/%3E%3C/svg%3E",
+          fileName: "one.svg",
+          id: "media-1",
+          layerId: "layer-1",
+          mimeType: "image/svg+xml",
+          position: { x: 0, y: 0 },
+          size: { height: 96, unit: "px", width: 96 },
+        },
+        {
+          dataUrl:
+            "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='96' height='96' viewBox='0 0 96 96'%3E%3Crect width='96' height='96' fill='%23999'/%3E%3C/svg%3E",
+          fileName: "two.svg",
+          id: "media-2",
+          layerId: "layer-2",
+          mimeType: "image/svg+xml",
+          position: { x: 0, y: 0 },
+          size: { height: 96, unit: "px", width: 96 },
+        },
+      ],
+      selectedLayerId: "layer-2",
+    });
+
+    expect(screen.getByRole("button", { name: "Add image files" })).toBeTruthy();
+    const previewGrid = container.querySelector('[data-slot="file-upload-preview-grid"]');
+    expect(previewGrid?.className).toContain("grid-cols-4");
+    expect(previewGrid?.lastElementChild?.getAttribute("data-slot")).toBe(
+      "file-upload-add-preview",
+    );
+    expect(screen.getByRole("img", { name: "one.svg" })).toBeTruthy();
+    expect(screen.getByRole("img", { name: "two.svg" })).toBeTruthy();
+
+    fireEvent.click(screen.getByRole("button", { name: "Remove two.svg" }));
+
+    expect(screen.getByTestId("media-count").textContent).toBe("1");
+    expect(screen.queryByRole("img", { name: "two.svg" })).toBeNull();
+  });
+
   it("keeps file upload deletion in the layers panel for multi-layer apps", () => {
     const schema = defineToolcraft({
       canvas: { enabled: true, upload: true },
@@ -3126,6 +3333,68 @@ describe("ControlsPanel", () => {
     expect(values["canvas.size.height"]).toBe(1080);
   });
 
+  it("switches editable-output aspect ratio to custom after manual size edits", () => {
+    const schema = defineToolcraft({
+      canvas: {
+        enabled: true,
+        size: { height: 1080, unit: "px", width: 1920 },
+        sizing: { mode: "editable-output" },
+      },
+      panels: {
+        controls: {
+          sections: [],
+          title: "Controls",
+        },
+      },
+    });
+
+    renderControlsPanelWithSchema(schema);
+
+    const widthInput = screen.getByDisplayValue("1920") as HTMLInputElement;
+
+    fireEvent.change(widthInput, { target: { value: "1600" } });
+    fireEvent.blur(widthInput);
+
+    expect(screen.getByTestId("canvas-size").textContent).toBe("1600,1080");
+    expect(screen.getAllByText("Custom...").length).toBeGreaterThan(0);
+    expect(screen.getByDisplayValue("40")).toBeTruthy();
+    expect(screen.getByDisplayValue("27")).toBeTruthy();
+    expect(JSON.parse(screen.getByTestId("values-json").textContent ?? "{}")).toMatchObject({
+      "canvas.aspectRatio": {
+        height: 27,
+        mode: "custom",
+        value: "40:27",
+        width: 40,
+      },
+      "canvas.size.height": 1080,
+      "canvas.size.width": 1600,
+    });
+  });
+
+  it("renders raster render scale as the last technical setup control", () => {
+    const schema = defineToolcraft({
+      canvas: {
+        enabled: true,
+        renderScale: true,
+        size: { height: 1080, unit: "px", width: 1920 },
+        sizing: { mode: "editable-output" },
+      },
+      panels: {
+        controls: {
+          sections: [],
+          title: "Controls",
+        },
+      },
+    });
+    renderControlsPanelWithSchema(schema);
+
+    const values = JSON.parse(screen.getByTestId("values-json").textContent ?? "{}");
+
+    expect(screen.getByText("Resolution scale")).toBeTruthy();
+    expect(screen.getByText("2x")).toBeTruthy();
+    expect(values["canvas.renderScale"]).toBe(2);
+  });
+
   it("applies empty text input values while typing and reset restores defaults", () => {
     renderControlsPanel();