@pixel-point/toolcraft 0.0.4 → 0.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixel-point/toolcraft",
-  "version": "0.0.4",
+  "version": "0.0.7",
   "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

@@ -95,7 +95,7 @@ describe("generateToolcraft", () => {
     assert.equal(packageJson.scripts["verify:perf"], "pnpm test:browser:perf");
     assert.equal(
       packageJson.scripts["verify:final"],
-      "pnpm ai:check && pnpm test && pnpm build && pnpm test:browser && pnpm test:browser:perf",
+      "pnpm ai:check && pnpm test && pnpm build && pnpm test:browser",
     );
 
     assert.ok(await fs.stat(path.join(targetDir, "playwright.config.ts")));
@@ -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

@@ -30,6 +30,7 @@ describe("Toolcraft template component contracts", () => {
       "imagePicker",
       "palette",
       "actions",
+      "collectionActions",
       "panelActions",
       "customControl",
     ] as const) {
@@ -221,7 +222,7 @@ describe("Toolcraft template component contracts", () => {
       "Every visible custom-control element must justify its space by enabling selection, ordering, preview, removal, upload, editing, or status that affects the product.",
     );
     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, Curves, AnchorGrid, ChannelMixer, Vector, or PanelActions control.",
+      "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(
       "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.",
@@ -258,6 +259,35 @@ describe("Toolcraft template component contracts", () => {
     );
   });
 
+  it("documents CollectionActions as canvas-backed add/remove controls", () => {
+    const contract = getToolcraftComponentContract("collectionActions");
+
+    expect(contract.stateMode).toBe("controlled");
+    expect(contract.decisionCatalog?.strictness).toBe("exact-owner");
+    expect(contract.decisionCatalog?.ownsValueModel).toContain(
+      "repeatable product entity collection",
+    );
+    expect(contract.decisionCatalog?.useWhen).toContain(
+      "Use CollectionActions instead of a count Slider when the user edits the actual set of items rather than only a numeric amount.",
+    );
+    expect(contract.decisionCatalog?.doNotReplaceWith).toContain(
+      "Do not use Slider to add or remove real collection items.",
+    );
+    expect(contract.decisionCatalog?.layoutConstraints).toContain(
+      "recommendedMaxItems is an agent/layout/performance hint, not a hard add limit; hardMaxItems is allowed only for real algorithm, format, API, export, or proven performance limits.",
+    );
+    expect(contract.decisionCatalog?.requiredAcceptance.join(" ")).toMatch(
+      /canvas preview and export/i,
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Adding or removing collection items must update the runtime target array consumed by the renderer and export; do not add panel-only items.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "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/);
+  });
+
   it("documents Palette as a constrained design-token color control", () => {
     const contract = getToolcraftComponentContract("palette");
 
@@ -345,6 +375,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 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.",
+    );
+    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 +440,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 +463,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 +514,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 +758,16 @@ 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 only when the first working app version exists or the user requests performance, lag, jank, animation speed, drag/zoom stabilization work, or otherwise complains about performance.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Renderer, canvas, animation, export, timeline, layers, canvas.renderScale, bug fixes, and performance-sensitive control changes use targeted functional/browser checks first and targeted performance scenarios only for touched workload, viewport, or export paths.",
+    );
+    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.",
@@ -828,6 +909,9 @@ describe("Toolcraft template component contracts", () => {
     expect(contract.aiUsageRules).toContain(
       "Ordinary controls-panel section collapsed/expanded state persists as a runtime UI preference per app. It is not undo/redo state, not settings import/export state, and Reset controls must not clear it. Runtime technical Setup/settings sections and sticky footer Export sections are not collapsible.",
     );
+    expect(contract.aiUsageRules).toContain(
+      "Ordinary controls-panel section headers expose the runtime section reset action before the collapse button; it dispatches controls.resetTargets and restores only that section's control targets to their schema defaultValue.",
+    );
     expect(contract.aiUsageRules).toContain(
       "Ordinary controls-panel body sections use 8px top spacing and 24px bottom spacing for their control content. Runtime technical Setup/settings sections use 12px top and bottom spacing to match side padding. Sticky footer action sections keep their dedicated spacing.",
     );
@@ -849,6 +933,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 +1188,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.",
@@ -384,6 +392,55 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       "Acceptance and browser tests must click each Actions button and prove the product output or runtime state for the nearby entity changed.",
     ],
   },
+  collectionActions: {
+    ...control("collectionActions", "CollectionActions", "standalone", "component-owned"),
+    decisionCatalog: decisionCatalog({
+      strictness: "exact-owner",
+      ownsValueModel: [
+        "repeatable product entity collection",
+        "add/remove product items",
+        "dynamic list of visible controls",
+        "canvas-backed collection size",
+      ],
+      useWhen: [
+        "Use CollectionActions when users can add or remove repeated product entities such as colors, glyphs, symbols, points, rules, variants, or object entries.",
+        "Use CollectionActions instead of a count Slider when the user edits the actual set of items rather than only a numeric amount.",
+      ],
+      doNotReplaceWith: [
+        "Do not use Slider to add or remove real collection items.",
+        "Do not use plain Actions for add/remove collection ownership; Actions are local commands, not collection state owners.",
+        "Do not use CollectionActions for panel-only lists that do not affect canvas preview or export.",
+      ],
+      acceptableAlternatives: [
+        "Use fileDrop multiple when the repeated entities are uploaded images.",
+        "Use Gradient when the repeated entities are gradient stops inside an adjustable gradient.",
+        "Use customControl only when the repeated entity needs interactions no built-in collection item control can express.",
+      ],
+      layoutConstraints: [
+        "CollectionActions sits at the start of its section, renders the collection label on the left, and keeps remove/add icon buttons together on the right.",
+        "Homogeneous repeated item controls do not render visible per-item labels when the collection label already names the group.",
+        "Collection item controls follow normal density rules: plain color items use equal 50% columns when they fit, while color+opacity items stay stacked.",
+        "CollectionActions is a compound control and follows content-width compound divider rules when sharing a section with sibling controls.",
+        "recommendedMaxItems is an agent/layout/performance hint, not a hard add limit; hardMaxItems is allowed only for real algorithm, format, API, export, or proven performance limits.",
+      ],
+      requiredAcceptance: [
+        "Prove plus adds a runtime item and that the new item appears in or affects canvas preview and export.",
+        "Prove minus removes a runtime item and that the removed item disappears from or stops affecting canvas preview and export.",
+        "Prove minItems prevents deleting below the minimum and recommendedMaxItems does not silently block adding more items.",
+      ],
+    }),
+    stateMode: "controlled",
+    aiUsageRules: [
+      "Use CollectionActions for repeatable product entities whose actual item list can grow or shrink.",
+      "Adding or removing collection items must update the runtime target array consumed by the renderer and export; do not add panel-only items.",
+      "Do not model add/remove item behavior with a Slider count when users need to edit the actual items.",
+      "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.",
+      "CollectionActions item controls use built-in controls whenever possible, such as Color, ColorOpacity, TextInput, Select, Segmented, Slider, Switch, Checkbox, or RangeInput.",
+      "Do not add visible labels like Color 1, Color 2, Item 1, or Item 2 for homogeneous collection items when the collection label already explains the group.",
+      "Use compact half-width item layout whenever the child control is allowed to fit in a half row; color items without opacity are the default two-column case.",
+      "Acceptance must add and remove items through the browser UI and prove canvas/export output follows the changed collection.",
+    ],
+  },
   panelActions: {
     ...control("panelActions", "PanelActions", "standalone", "component-owned"),
     decisionCatalog: decisionCatalog({
@@ -806,6 +863,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 +872,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"],
@@ -917,7 +977,7 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
     }),
     aiUsageRules: [
       "Use custom controls only for product interactions that built-in controls cannot express.",
-      "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, Curves, AnchorGrid, ChannelMixer, Vector, or PanelActions control.",
+      "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.",
       "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.",
       "Custom controls must render the minimum UI needed to understand the value, context, and available actions; avoid decorative metadata and text that repeats what the section, label, or visible item already explains.",
       "Every visible custom-control element must justify its space by enabling selection, ordering, preview, removal, upload, editing, or status that affects the product.",
@@ -942,11 +1002,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 targeted browser evidence that the canvas stays responsive at the selected scale.",
+      "After enabling canvas.renderScale, verify that canvas preview stays responsive while dragging sliders and other high-frequency controls at the selected scale.",
+      "Performance fixes for canvas.renderScale must preserve the selected visual quality; do not silently downsample, stretch a lower-resolution backing canvas, blur output, or clamp canvas.renderScale below the user's chosen value to pass budgets.",
+      "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 +1060,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 +1107,10 @@ 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 only when the first working app version exists or the user requests performance, lag, jank, animation speed, drag/zoom stabilization work, or otherwise complains about performance.",
+      "Renderer, canvas, animation, export, timeline, layers, canvas.renderScale, bug fixes, and performance-sensitive control changes use targeted functional/browser checks first and targeted performance scenarios only for touched workload, viewport, or export paths.",
+      "Performance fixes must preserve selected output and preview quality; do not reduce image quality, selected renderScale, export resolution, source media fidelity, or canvas backing pixels as the hidden way to pass budgets.",
+      "When canvas or slider interactions lag, diagnose where the slowdown comes from before changing output quality: renderer technique, React update frequency, decoded media, shader/program setup, buffer uploads, layout work, async render cancellation, or animation scheduling.",
       "Renderer specs must include a Renderer Technique Decision Matrix with sourceRepresentation, productRepresentation, previewRenderer, exportRenderer, rendererWorkload, rendererStrategy, whyNotAlternativeStrategies, fidelityRisks, and performanceRisks.",
       "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.",
@@ -1118,6 +1188,7 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       "Every visible controls-panel section title renders through the standard 36px collapsible header row with vertically centered text and the runtime collapse icon; generated apps must not hand-build section headers.",
       "Controls-panel section expand and collapse uses the standard runtime height/opacity animation; generated apps must not replace it with instant custom section visibility.",
       "Ordinary controls-panel section collapsed/expanded state persists as a runtime UI preference per app. It is not undo/redo state, not settings import/export state, and Reset controls must not clear it. Runtime technical Setup/settings sections and sticky footer Export sections are not collapsible.",
+      "Ordinary controls-panel section headers expose the runtime section reset action before the collapse button; it dispatches controls.resetTargets and restores only that section's control targets to their schema defaultValue.",
       "Ordinary controls-panel body sections use 8px top spacing and 24px bottom spacing for their control content. Runtime technical Setup/settings sections use 12px top and bottom spacing to match side padding. Sticky footer action sections keep their dedicated spacing.",
       "Broad section titles such as Flow, Icon, Shapes, Scene, Text, Typography, or Motion are only valid for small cohesive groups; use specific titles such as Flow Motion, Flow Geometry, Letter Burst, Shape Colors, Logo Glow, Logo Plate, or Text Block for larger groups.",
       "Section titles in one controls panel must be unique.",
@@ -1126,6 +1197,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.test.ts

@@ -89,9 +89,10 @@ describe("Toolcraft template decision contract", () => {
     expect(rule?.desiredBehavior).toMatch(/canvas drag, pan, pinch, zoom, and radar\/center/i);
     expect(rule?.desiredBehavior).toMatch(/playback state/i);
     expect(rule?.desiredBehavior).toMatch(/first working version/i);
-    expect(rule?.desiredBehavior).toMatch(/renderer\/canvas\/animation\/export\/timeline\/layers/i);
-    expect(rule?.desiredBehavior).toMatch(/bug that previously broke functionality/i);
     expect(rule?.desiredBehavior).toMatch(/optimize performance/i);
+    expect(rule?.desiredBehavior).toMatch(/otherwise complains about performance/i);
+    expect(rule?.desiredBehavior).toMatch(/targeted functional\/browser checks/i);
+    expect(rule?.desiredBehavior).toMatch(/touched workload\/viewport\/export paths/i);
     expect(rule?.desiredBehavior).toMatch(/full performance checkpoint/i);
   });
 

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 only when the first working version of an app exists, or whenever the user explicitly asks to optimize performance, fix lag, remove jank, speed up animation, stabilize drag/zoom, or otherwise complains about performance. Renderer, canvas, animation, export, timeline, layers, canvas.renderScale, bug fixes, and performance-sensitive controls need targeted functional/browser checks first and targeted performance scenarios only for touched workload/viewport/export paths. 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");
   });