@pixel-point/toolcraft 0.0.3 → 0.0.6

package/package.json

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

@@ -191,7 +191,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. Hide the switch label when the section title provides the visible context, such as Include background plus Background color 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; 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.',
     );
     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.',
@@ -206,7 +206,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. 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; never shrink the checkbox column to intrinsic width. Hide the checkbox label when the section title provides the visible context.",
     );
   });
 
@@ -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, 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.",
     );
@@ -493,7 +535,7 @@ describe("Toolcraft template component contracts", () => {
       "Product-output apps always expose renderer-owned output background color as a schema color target such as appearance.background or scene.background.",
     );
     expect(color.aiUsageRules).toContain(
-      "Pair renderer-owned output background color with export.includeBackground in one Background section. Prefer an inline hidden-label toggle plus color parameter row when the section title supplies the Background context.",
+      '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.",
@@ -502,7 +544,7 @@ describe("Toolcraft template component contracts", () => {
       "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 except for section-title-owned hidden-label toggle plus parameter rows. Color fields in other mixed rows must not be unlabeled.",
+      '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.',
     );
     expect(color.aiUsageRules).toContain(
       "Plain Color popovers must not show opacity controls. If opacity is editable, use ColorOpacity instead.",
@@ -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.",
     );
@@ -1005,12 +1056,30 @@ describe("Toolcraft template component contracts", () => {
     expect(contract.aiUsageRules).toContain(
       "Static or still-output apps include Export PNG as the primary footer action.",
     );
+    expect(contract.aiUsageRules).toContain(
+      'Every app with Export PNG must expose a separate "Image Export" controls section.',
+    );
+    expect(contract.aiUsageRules).toContain(
+      'The Image Export section must include "export.image.format" as a Select control with PNG and JPG choices, defaulting to "png".',
+    );
+    expect(contract.aiUsageRules).toContain(
+      'The Image Export section must include "export.image.resolution" as a Select control with 2K, 4K, and 8K choices, defaulting to "4k".',
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Image Export format and resolution render as one compact two-column inline Select pair, matching the Video Export settings structure.",
+    );
+    expect(contract.aiUsageRules).toContain(
+      "Image Export resolution controls the actual exported image long edge: 2K = 2048px, 4K = 4096px, 8K = 8192px. Pass the selected runtime value to createToolcraftPngExportCanvas resolution and prove decoded image width/height in browser acceptance.",
+    );
     expect(contract.aiUsageRules).toContain(
       "Animated apps include Export Video as the primary footer action and Export PNG as a secondary footer action.",
     );
     expect(contract.aiUsageRules).toContain(
       'Animated apps with Export Video must expose a separate "Video Export" controls section.',
     );
+    expect(contract.aiUsageRules).toContain(
+      'Animated apps with both Export PNG and Export Video must expose both "Image Export" and "Video Export"; Image Export sits immediately before Video Export.',
+    );
     expect(contract.aiUsageRules).toContain(
       'The Video Export section must include format and resolution controls such as targets "export.video.format" and "export.video.resolution".',
     );
@@ -1048,10 +1117,13 @@ describe("Toolcraft template component contracts", () => {
       "Video export must report frame-based progress through reportProgress during render/encode steps. PNG export should report phase progress for render, blob, and handoff when those phases are asynchronous.",
     );
     expect(contract.aiUsageRules).toContain(
-      "Product-output apps must expose user-facing Background color and Include background controls, then pass the includeBackground runtime value to createToolcraftPngExportCanvas only for PNG alpha.",
+      '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(
-      "PNG export must use createToolcraftPngExportCanvas so background transparency and retina sizing are applied consistently without making live preview, workspace canvas backing, or video transparent.",
+      "Product-output apps must pass the includeBackground runtime value to createToolcraftPngExportCanvas only for PNG alpha.",
+    );
+    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.",
     );
     expect(contract.aiUsageRules).toContain(
       "Video export must keep product background and use getToolcraftRetinaExportSize for retina dimensions.",
@@ -1080,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.",
@@ -204,7 +212,7 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       'Use labels such as "CRT", "Background", "Glow", or "Loop" instead of "Enable CRT" or "Disable background".',
       "Two adjacent Switch 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 switches by target entity, and generated schemas should stack switches only when any label would truncate.",
       "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.",
-      "A Switch may share an inline row with one related parameter control when the visible switch label is short enough to fit. Hide the switch label when the section title provides the visible context, such as Include background plus Background color 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; 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.',
     ],
   },
   checkbox: {
@@ -239,7 +247,7 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       'Use labels such as "Transparent background", "Guides", or "Loop" instead of "Enable transparent background".',
       "When the nearest section title already names the checkbox context, do not duplicate that title as the visible checkbox label. Use label false for a visual-only checkbox and keep the meaning in target/description.",
       "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.",
-      "A Checkbox may share an inline row with one related parameter control when the visible checkbox label is short enough to fit. 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; never shrink the checkbox column to intrinsic width. Hide the checkbox label when the section title provides the visible context.",
     ],
   },
   colorOpacity: {
@@ -423,8 +431,14 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       "defineToolcraft hoists panelActions into the controls panel sticky footer automatically.",
       "Product-output apps must always include export in panelActions.",
       "Static or still-output apps include Export PNG as the primary footer action.",
+      'Every app with Export PNG must expose a separate "Image Export" controls section.',
+      'The Image Export section must include "export.image.format" as a Select control with PNG and JPG choices, defaulting to "png".',
+      'The Image Export section must include "export.image.resolution" as a Select control with 2K, 4K, and 8K choices, defaulting to "4k".',
+      "Image Export format and resolution render as one compact two-column inline Select pair, matching the Video Export settings structure.",
+      "Image Export resolution controls the actual exported image long edge: 2K = 2048px, 4K = 4096px, 8K = 8192px. Pass the selected runtime value to createToolcraftPngExportCanvas resolution and prove decoded image width/height in browser acceptance.",
       "Animated apps include Export Video as the primary footer action and Export PNG as a secondary footer action.",
       'Animated apps with Export Video must expose a separate "Video Export" controls section.',
+      'Animated apps with both Export PNG and Export Video must expose both "Image Export" and "Video Export"; Image Export sits immediately before Video Export.',
       'The Video Export section must include format and resolution controls such as targets "export.video.format" and "export.video.resolution".',
       "Use Select controls for Video Export format and resolution; do not use Segmented unless the product has a deliberately tiny fixed output menu and browser tests prove every cell keeps padding.",
       'Place the Video Export section as the final controls section directly above sticky footer panelActions.',
@@ -437,8 +451,9 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       'Video resolution must control exported dimensions. Use "current" output size by default; "4K" is an export resolution target, not a hardcoded 3840x2160 canvas lock.',
       "Video export browser coverage must load the exported blob metadata and prove video.duration matches the edited runtime timeline duration; blobSize/blobType checks alone are not enough.",
       "Video export must report frame-based progress through reportProgress during render/encode steps. PNG export should report phase progress for render, blob, and handoff when those phases are asynchronous.",
-      "Product-output apps must expose user-facing Background color and Include background controls, then pass the includeBackground runtime value to createToolcraftPngExportCanvas only for PNG alpha.",
-      "PNG export must use createToolcraftPngExportCanvas so background transparency and retina sizing are applied consistently without making live preview, workspace canvas backing, or video transparent.",
+      'Product-output apps must expose a dedicated "Background" section directly before the first export settings section. With PNG export that first section is Image Export; with video-only export it is Video Export.',
+      "Product-output apps must pass the includeBackground runtime value to createToolcraftPngExportCanvas only for PNG alpha.",
+      "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.",
       "Video export must keep product background and use getToolcraftRetinaExportSize for retina dimensions.",
       "Copy PNG can be a secondary action when clipboard output is useful, but copy does not replace export.",
       "Add Copy PNG as a secondary action only when the prompt/reference includes clipboard output or the product clearly benefits from paste/share workflows.",
@@ -575,10 +590,10 @@ export const TOOLCRAFT_COMPONENT_CONTRACTS = {
       "Never use generic Color or Colors as a generated section title. If no meaningful color role exists and the colors are just basic colors, use a neutral section title such as Appearance instead of omitting the title.",
       "Do not split a grouped object section into a separate generated Color section; if the color role is unclear, ask the user before implementation.",
       "When one short numeric/text field and one Color field configure the same entity, keep them in one two-column inline layout group.",
-      "Mixed inline rows require visible labels on both controls except for section-title-owned hidden-label toggle plus parameter rows. Color fields in other mixed rows must not be unlabeled.",
+      '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.',
       "Plain Color popovers must not show opacity controls. If opacity is editable, use ColorOpacity instead.",
       "Product-output apps always expose renderer-owned output background color as a schema color target such as appearance.background or scene.background.",
-      "Pair renderer-owned output background color with export.includeBackground in one Background section. Prefer an inline hidden-label toggle plus color parameter row when the section title supplies the Background context.",
+      '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.',
       "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.",
       "Render multiple related color fields in one section with at most two colors per row.",
     ],
@@ -799,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.",
@@ -807,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"],
@@ -935,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: [
@@ -986,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, 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"],
@@ -1033,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.",
@@ -1119,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

@@ -177,7 +177,7 @@ export const TOOLCRAFT_DECISION_CONTRACT = [
     currentConstraint:
       "Product-output apps expose final output delivery through sticky footer panelActions.",
     desiredBehavior:
-      "Static products include Export PNG; animated products include Export Video and Export PNG. Copy can be secondary, but it does not replace export. Product apps expose Background and Include background controls; standard export helpers own runtime PNG transparency and retina dimensions, while live preview, workspace canvas backing, and video keep the background.",
+      'Static products include Export PNG plus an "Image Export" section for format and 2K/4K/8K resolution; animated products include Export Video and Export PNG plus "Video Export" settings. Copy can be secondary, but it does not replace export. Product apps expose a required "Background" section directly before export settings, with a Switch labeled "Include" and a background color control with label false in one equal-width row. Standard export helpers own runtime PNG transparency and selected image dimensions or retina fallback, while live preview, workspace canvas backing, and video keep the background.',
     enforcement: ["acceptance-validator", "performance-validator", "browser-helper", "starter-agents"],
     id: "output-export-required",
     level: "invariant",
@@ -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/export/export.test.ts

@@ -4,6 +4,7 @@ import { defineToolcraft } from "../schema/define-toolcraft";
 import type { ToolcraftState } from "../state/types";
 import {
   createToolcraftPngExportCanvas,
+  getToolcraftImageExportSize,
   getToolcraftRetinaExportPixelRatio,
   getToolcraftRetinaExportSize,
   shouldIncludeToolcraftExportBackground,
@@ -105,6 +106,54 @@ describe("Toolcraft export helpers", () => {
     });
   });
 
+  it("resolves image export resolution presets from canvas aspect ratio", () => {
+    const state = createState();
+
+    expect(getToolcraftImageExportSize({ resolution: "2k", state })).toEqual({
+      height: 1024,
+      pixelRatio: 10.24,
+      width: 2048,
+    });
+    expect(getToolcraftImageExportSize({ resolution: "4k", state })).toEqual({
+      height: 2048,
+      pixelRatio: 20.48,
+      width: 4096,
+    });
+    expect(getToolcraftImageExportSize({ resolution: "8k", state })).toEqual({
+      height: 4096,
+      pixelRatio: 40.96,
+      width: 8192,
+    });
+  });
+
+  it("preserves portrait aspect ratio for image export resolution presets", () => {
+    const state = createState();
+    state.canvas.size = { height: 200, unit: "px", width: 100 };
+
+    expect(getToolcraftImageExportSize({ resolution: "4k", state })).toEqual({
+      height: 4096,
+      pixelRatio: 20.48,
+      width: 2048,
+    });
+  });
+
+  it("falls back to retina sizing for current or unknown image export resolution", () => {
+    const state = createState();
+
+    expect(getToolcraftImageExportSize({ devicePixelRatio: 2, resolution: "current", state }))
+      .toEqual({
+        height: 200,
+        pixelRatio: 2,
+        width: 400,
+      });
+    expect(getToolcraftImageExportSize({ devicePixelRatio: 2, resolution: "source", state }))
+      .toEqual({
+        height: 200,
+        pixelRatio: 2,
+        width: 400,
+      });
+  });
+
   it("creates a transparent retina png canvas when png background is disabled", () => {
     const schema = defineToolcraft({
       canvas: { enabled: true },
@@ -159,6 +208,22 @@ describe("Toolcraft export helpers", () => {
     expect(context.fillRect).toHaveBeenCalledWith(0, 0, 400, 200);
   });
 
+  it("creates a png canvas at the selected image export resolution", () => {
+    const state = createState();
+    const { canvas, context } = createMockCanvas();
+
+    createToolcraftPngExportCanvas({
+      canvasFactory: () => canvas,
+      render: vi.fn(),
+      resolution: "4k",
+      state,
+    });
+
+    expect(canvas.width).toBe(4096);
+    expect(canvas.height).toBe(2048);
+    expect(context.scale).toHaveBeenCalledWith(20.48, 20.48);
+  });
+
   it("allows runtime controls to disable the png background", () => {
     const state = createState();
     const { canvas, context } = createMockCanvas();

package/templates/runtime/export/export.ts

@@ -3,6 +3,8 @@ import type { ToolcraftState } from "../state/types";
 
 export type ToolcraftExportFormat = "png" | "video";
 
+export type ToolcraftImageExportResolution = "current" | "2k" | "4k" | "8k";
+
 export type ToolcraftRetinaExportSize = {
   height: number;
   pixelRatio: number;
@@ -19,6 +21,10 @@ export type ToolcraftExportSizeOptions = {
   state: ToolcraftState;
 };
 
+export type ToolcraftImageExportSizeOptions = ToolcraftExportSizeOptions & {
+  resolution?: ToolcraftImageExportResolution | string;
+};
+
 export type ToolcraftPngRenderContext = {
   canvas: HTMLCanvasElement;
   context: CanvasRenderingContext2D;
@@ -36,9 +42,19 @@ export type ToolcraftPngExportCanvasOptions = {
   devicePixelRatio?: number;
   includeBackground?: boolean;
   render: (context: ToolcraftPngRenderContext) => void;
+  resolution?: ToolcraftImageExportResolution | string;
   state: ToolcraftState;
 };
 
+const toolcraftImageExportLongEdges: Record<
+  Exclude<ToolcraftImageExportResolution, "current">,
+  number
+> = {
+  "2k": 2048,
+  "4k": 4096,
+  "8k": 8192,
+};
+
 export function getToolcraftRetinaExportPixelRatio(devicePixelRatio?: number): number {
   const globalPixelRatio = (globalThis as typeof globalThis & { devicePixelRatio?: number })
     .devicePixelRatio;
@@ -67,6 +83,41 @@ export function getToolcraftRetinaExportSize({
   };
 }
 
+export function getToolcraftImageExportSize({
+  devicePixelRatio,
+  resolution,
+  state,
+}: ToolcraftImageExportSizeOptions): ToolcraftRetinaExportSize {
+  const normalizedResolution = String(resolution ?? "current").toLowerCase();
+  const targetLongEdge =
+    toolcraftImageExportLongEdges[
+      normalizedResolution as Exclude<ToolcraftImageExportResolution, "current">
+    ];
+
+  if (!targetLongEdge) {
+    return getToolcraftRetinaExportSize({ devicePixelRatio, state });
+  }
+
+  const cssWidth = Math.max(1, state.canvas.size.width);
+  const cssHeight = Math.max(1, state.canvas.size.height);
+  const dominantSize = Math.max(cssWidth, cssHeight);
+  const pixelRatio = targetLongEdge / dominantSize;
+
+  if (cssWidth >= cssHeight) {
+    return {
+      height: Math.max(1, Math.round(cssHeight * pixelRatio)),
+      pixelRatio,
+      width: targetLongEdge,
+    };
+  }
+
+  return {
+    height: targetLongEdge,
+    pixelRatio,
+    width: Math.max(1, Math.round(cssWidth * pixelRatio)),
+  };
+}
+
 export function shouldIncludeToolcraftExportBackground({
   format,
   schema,
@@ -84,11 +135,13 @@ export function createToolcraftPngExportCanvas({
   devicePixelRatio,
   includeBackground: includeBackgroundOverride,
   render,
+  resolution,
   state,
 }: ToolcraftPngExportCanvasOptions): HTMLCanvasElement {
   const canvas = canvasFactory();
-  const { height, pixelRatio, width } = getToolcraftRetinaExportSize({
+  const { height, pixelRatio, width } = getToolcraftImageExportSize({
     devicePixelRatio,
+    resolution,
     state,
   });
   const includeBackground =