@pixel-point/toolcraft 0.0.3 → 0.0.6

package/templates/runtime/state/reducer.ts

@@ -1,4 +1,8 @@
-import { getToolcraftCanvasSizeTargetDimension } from "../schema/runtime-targets";
+import {
+  getToolcraftCanvasSizeTargetDimension,
+  isToolcraftCanvasAspectRatioTarget,
+} from "../schema/runtime-targets";
+import { getToolcraftCanvasAspectRatioPreset } from "../schema/canvas-aspect-ratio-presets";
 import {
   clampToolcraftCanvasZoom,
   toolcraftCanvasZoomDefault,
@@ -18,6 +22,16 @@ import type {
 
 const minTimelineDurationSeconds = 1;
 const maxTimelineDurationSeconds = 60;
+const canvasAspectRatioTarget = "canvas.aspectRatio";
+const canvasSizeWidthTarget = "canvas.size.width";
+const canvasSizeHeightTarget = "canvas.size.height";
+
+type CanvasAspectRatioValue = {
+  height: number;
+  mode: "custom" | "preset";
+  value: string;
+  width: number;
+};
 
 function asCanvasSizeDimension(value: unknown): number | null {
   const numberValue =
@@ -34,6 +48,153 @@ function asCanvasSizeDimension(value: unknown): number | null {
   return Math.max(1, Math.round(numberValue));
 }
 
+function getGreatestCommonDivisor(left: number, right: number): number {
+  let a = Math.abs(Math.round(left));
+  let b = Math.abs(Math.round(right));
+
+  while (b !== 0) {
+    const next = b;
+    b = a % b;
+    a = next;
+  }
+
+  return a || 1;
+}
+
+function getCanvasAspectRatioFromSize(
+  size: ToolcraftState["canvas"]["size"],
+): CanvasAspectRatioValue {
+  const divisor = getGreatestCommonDivisor(size.width, size.height);
+  const width = Math.max(1, Math.round(size.width / divisor));
+  const height = Math.max(1, Math.round(size.height / divisor));
+  const value = `${width}:${height}`;
+
+  return {
+    height,
+    mode: "custom",
+    value,
+    width,
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseCanvasAspectRatioString(value: string): CanvasAspectRatioValue | null {
+  const match = /^\s*(\d+(?:\.\d+)?)\s*:\s*(\d+(?:\.\d+)?)\s*$/u.exec(value);
+
+  if (!match) {
+    return null;
+  }
+
+  const width = asCanvasSizeDimension(match[1]);
+  const height = asCanvasSizeDimension(match[2]);
+
+  if (width === null || height === null) {
+    return null;
+  }
+
+  return {
+    height,
+    mode: getToolcraftCanvasAspectRatioPreset(`${width}:${height}`)
+      ? "preset"
+      : "custom",
+    value: `${width}:${height}`,
+    width,
+  };
+}
+
+function normalizeCanvasAspectRatioValue(
+  value: unknown,
+  fallbackSize: ToolcraftState["canvas"]["size"],
+): CanvasAspectRatioValue {
+  if (typeof value === "string") {
+    return parseCanvasAspectRatioString(value) ?? getCanvasAspectRatioFromSize(fallbackSize);
+  }
+
+  if (isRecord(value)) {
+    const width = asCanvasSizeDimension(value.width);
+    const height = asCanvasSizeDimension(value.height);
+
+    if (width !== null && height !== null) {
+      const rawValue = typeof value.value === "string" ? value.value : `${width}:${height}`;
+      const mode = value.mode === "preset" ? "preset" : "custom";
+
+      return {
+        height,
+        mode,
+        value: mode === "preset" ? rawValue : `${width}:${height}`,
+        width,
+      };
+    }
+  }
+
+  return getCanvasAspectRatioFromSize(fallbackSize);
+}
+
+function canvasAspectRatioValuesEqual(
+  first: unknown,
+  second: CanvasAspectRatioValue,
+): boolean {
+  if (!isRecord(first)) {
+    return false;
+  }
+
+  return (
+    first.height === second.height &&
+    first.mode === second.mode &&
+    first.value === second.value &&
+    first.width === second.width
+  );
+}
+
+function applyCanvasAspectRatioToSize({
+  anchor,
+  ratio,
+  size,
+  value,
+}: {
+  anchor: "height" | "width";
+  ratio: CanvasAspectRatioValue;
+  size: ToolcraftState["canvas"]["size"];
+  value: number;
+}): ToolcraftState["canvas"]["size"] {
+  if (anchor === "width") {
+    return {
+      ...size,
+      height: Math.max(1, Math.round((value * ratio.height) / ratio.width)),
+      width: value,
+    };
+  }
+
+  return {
+    ...size,
+    height: value,
+    width: Math.max(1, Math.round((value * ratio.width) / ratio.height)),
+  };
+}
+
+function getCanvasAspectRatioPresetSize(
+  ratio: CanvasAspectRatioValue,
+): ToolcraftState["canvas"]["size"] | null {
+  if (ratio.mode !== "preset") {
+    return null;
+  }
+
+  const preset = getToolcraftCanvasAspectRatioPreset(ratio.value);
+
+  if (!preset) {
+    return null;
+  }
+
+  return {
+    height: preset.height,
+    unit: "px",
+    width: preset.width,
+  };
+}
+
 function getResetCanvasSize(
   state: ToolcraftState,
 ): ToolcraftState["canvas"]["size"] | null {
@@ -408,33 +569,91 @@ export function toolcraftReducer(
     case "controls.setValue": {
       const canvasSizeDimension = getToolcraftCanvasSizeTargetDimension(command.target);
 
-      if (canvasSizeDimension) {
-        const dimensionValue = asCanvasSizeDimension(command.value);
+      if (isToolcraftCanvasAspectRatioTarget(command.target)) {
+        const ratio = normalizeCanvasAspectRatioValue(command.value, state.canvas.size);
+        const size =
+          getCanvasAspectRatioPresetSize(ratio) ??
+          applyCanvasAspectRatioToSize({
+            anchor: "width",
+            ratio,
+            size: state.canvas.size,
+            value: state.canvas.size.width,
+          });
 
-        if (dimensionValue === null) {
+        if (
+          state.canvas.size.width === size.width &&
+          state.canvas.size.height === size.height &&
+          canvasAspectRatioValuesEqual(state.values[command.target], ratio)
+        ) {
           return state;
         }
 
-        if (
-          state.canvas.size[canvasSizeDimension] === dimensionValue &&
-          state.values[command.target] === dimensionValue
-        ) {
+        return commitStatePatch(state, {
+          after: {
+            [canvasAspectRatioTarget]: ratio,
+            "canvas.size": size,
+            [canvasSizeWidthTarget]: size.width,
+            [canvasSizeHeightTarget]: size.height,
+          },
+          before: {
+            [canvasAspectRatioTarget]: state.values[command.target],
+            "canvas.size": state.canvas.size,
+            [canvasSizeWidthTarget]: state.values[canvasSizeWidthTarget],
+            [canvasSizeHeightTarget]: state.values[canvasSizeHeightTarget],
+          },
+          label: command.label ?? command.target,
+        }, {
+          group: command.historyGroup,
+          mode: command.history,
+        });
+      }
+
+      if (canvasSizeDimension) {
+        const dimensionValue = asCanvasSizeDimension(command.value);
+
+        if (dimensionValue === null) {
           return state;
         }
 
+        const hasAspectRatioControl =
+          canvasAspectRatioTarget in state.values ||
+          canvasAspectRatioTarget in state.defaults;
         const size = {
           ...state.canvas.size,
           [canvasSizeDimension]: dimensionValue,
         };
+        const aspectRatio = getCanvasAspectRatioFromSize(size);
+        const targetValue = size[canvasSizeDimension];
+        const otherTarget =
+          canvasSizeDimension === "width" ? canvasSizeHeightTarget : canvasSizeWidthTarget;
+        const otherValue = canvasSizeDimension === "width" ? size.height : size.width;
+
+        const sizeUnchanged =
+          state.canvas.size.width === size.width &&
+          state.canvas.size.height === size.height &&
+          state.values[command.target] === targetValue &&
+          state.values[otherTarget] === otherValue;
+
+        if (sizeUnchanged) {
+          return state;
+        }
 
         return commitStatePatch(state, {
           after: {
+            ...(hasAspectRatioControl
+              ? { [canvasAspectRatioTarget]: aspectRatio }
+              : {}),
             "canvas.size": size,
-            [command.target]: dimensionValue,
+            [command.target]: targetValue,
+            [otherTarget]: otherValue,
           },
           before: {
+            ...(hasAspectRatioControl
+              ? { [canvasAspectRatioTarget]: state.values[canvasAspectRatioTarget] }
+              : {}),
             "canvas.size": state.canvas.size,
             [command.target]: state.values[command.target],
+            [otherTarget]: state.values[otherTarget],
           },
           label: command.label ?? command.target,
         }, {
@@ -809,13 +1028,18 @@ export function toolcraftReducer(
       };
 
     case "media.import": {
-      const shouldReplaceSingleLayerMedia = !state.schema.panels.layers;
+      const shouldReplaceSingleLayerMedia =
+        !state.schema.panels.layers && command.replaceExisting !== false;
       const shouldResizeCanvas =
         state.schema.canvas.sizing.mode === "intrinsic-media";
       const layerId =
-        command.asset.layerId ?? getSingleLayerImportId(state) ?? getNextLayerId(state);
+        command.asset.layerId ??
+        (shouldReplaceSingleLayerMedia ? getSingleLayerImportId(state) : undefined) ??
+        getNextLayerId(state);
       const mediaId =
-        command.asset.id ?? getSingleMediaImportId(state) ?? getNextMediaId(state);
+        command.asset.id ??
+        (shouldReplaceSingleLayerMedia ? getSingleMediaImportId(state) : undefined) ??
+        getNextMediaId(state);
       const layer = {
         displayName: command.asset.layerName ?? getImportedLayerName(command.asset.fileName),
         id: layerId,

package/templates/runtime/state/types.ts

@@ -39,6 +39,7 @@ export type ToolcraftCommand =
         layerId?: string;
         layerName?: string;
       };
+      replaceExisting?: boolean;
       type: "media.import";
     }
   | { mediaId: string; type: "media.delete" }

package/templates/starter/AGENTS.md

@@ -23,8 +23,8 @@ Then follow `workflow.md` to choose the required contract docs and verification
 9. Animated preview renderers suspend or coalesce non-essential animation work during canvas drag, pan, pinch, zoom, and radar/center interactions, then resume without changing user playback state.
 10. If a Figma URL is provided, inspect the Figma file through MCP and rebuild from its structure; never implement from a screenshot or by eye.
 11. Choose an explicit persistence policy; use schema `persistence` for user-edited app settings that should survive reload, and test real reload restoration when localStorage is enabled.
-12. Use schema `settingsTransfer: "auto"` for complex apps that need import/export of control settings; never implement settings import/export through `panelActions` or route-local file inputs. After adding, removing, or reorganizing controls, sections, timeline, or layers, recalculate settings-transfer eligibility. The runtime threshold is 12 product controls, 5 product sections, or weighted score 18. Visible `Canvas width` and `Canvas height` inputs are owned by `editable-output` canvas sizing, not by settings transfer. 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.
-13. Product apps expose `Background` color and `Include background` controls and wire them into PNG export; live preview, workspace canvas backing, and video export keep the background.
+12. Use schema `settingsTransfer: "auto"` for complex apps that need import/export of control settings; never implement settings import/export through `panelActions` or route-local file inputs. After adding, removing, or reorganizing controls, sections, timeline, or layers, recalculate settings-transfer eligibility. The runtime threshold is 12 product controls, 5 product sections, or weighted score 18. Visible `Aspect ratio`, `Canvas width`, and `Canvas height` controls are owned by `editable-output` canvas sizing, not by settings transfer. Runtime aspect presets apply canonical canvas sizes, with `16:9` equal to `1920x1080`; manual Canvas width/height edits keep the typed dimension, keep the other dimension unchanged, switch Aspect ratio to Custom, and show the reduced current ratio in custom ratio inputs; when no explicit product size is provided, the runtime default canvas size is also `1920x1080`. Non-vector raster, Canvas 2D, WebGL, and WebGPU previews set `canvas.renderScale: true`; the first technical runtime section then appends `Resolution scale` after canvas sizing so backing pixels can increase up to 2x without changing CSS/output size. Performance fixes must preserve the selected render scale and keep canvas preview responsive to sliders/high-frequency controls at that scale; diagnose the bottleneck before reducing quality. Do not pass budgets by silently downsampling, stretching a lower-resolution backing canvas, blurring output, or clamping `canvas.renderScale` below the user's chosen value. 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, for raster outputs, `Resolution scale` in that order and renders without a visible section heading.
+13. Product apps expose a required `Background` section directly before export settings. It contains a Switch labeled `Include` and a background color control with `label: false` in one equal-width inline row; PNG export wires those runtime values into the standard export helper while live preview, workspace canvas backing, and video export keep the background. Every app with `Export PNG` exposes `Image Export` with `export.image.format` and `export.image.resolution` as two `select` controls in one compact two-column inline row, and passes the selected resolution to `createToolcraftPngExportCanvas({ resolution })` so 2K/4K/8K change actual PNG dimensions. Animated apps with both PNG and video export place `Image Export` immediately before `Video Export`.
 14. Keep `docs/toolcraft/agent-worklog.md` current with a decision trail, product decisions, evidence, verification, and risks.
 15. Prove every visible entity through acceptance, browser, and performance coverage.
 16. Workload performance scenarios must declare `stressFixture`; browser perf tests must use `getToolcraftPerformanceStressValue(appPerformance, scenarioId)` so heavy-case tests cannot use toy values.
@@ -146,7 +146,7 @@ Do not rerun `pnpm install` after every edit. Run it after fresh export, depende
 
 Do not run the full browser performance suite for Tier 0-2 edits unless a performance checkpoint trigger applies.
 
-Run a full performance checkpoint with `pnpm verify:perf` 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, or when the user asks to optimize performance, fix lag, remove jank, speed up animation, or stabilize drag/zoom.
+Run a full performance checkpoint with `pnpm verify:perf` 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, or when the user asks to optimize performance, fix lag, remove jank, speed up animation, or stabilize drag/zoom.
 
 Fast feature loops may defer full performance only when none of the checkpoint triggers above apply. Record the deferred check and reason in the verification note or worklog.
 
@@ -176,7 +176,9 @@ The app is complete only when:
 - reset returns schema controls to `defaultValue`;
 - sticky footer export actions operate on final product output at `state.canvas.size`;
 - still products expose Export PNG; animated products expose Export Video plus Export PNG;
-- PNG export uses `Background` and `Include background` runtime controls with the standard export helper, while live preview, workspace canvas backing, and video keep background;
+- PNG export uses the required `Background` section with `Include` plus unlabeled background color runtime controls, while live preview, workspace canvas backing, and video keep background;
+- every PNG export includes `Image Export` format/resolution `select` controls, and passes `export.image.resolution` into `createToolcraftPngExportCanvas`;
+- animated products with both PNG and video export place `Image Export` immediately before `Video Export`;
 - all export paths use retina output dimensions from the standard export helper;
 - layers are absent for single-layer apps and fully working when enabled;
 - timeline is absent, playback, keyframes, or custom reference timeline according to product behavior;

package/templates/starter/docs/toolcraft/README.md

@@ -29,7 +29,7 @@ Every implementation pass must choose a verification tier before editing. Use th
 | Tier 3 | Renderer, canvas, timeline, layers, upload, export, zoom, heavy controls, or a performance checkpoint trigger | `pnpm verify:quick` + targeted browser/perf scenarios |
 | Tier 4 | Final delivery, fresh export, runtime/template/contract changes, broad renderer/product rewrites | `pnpm verify:final` |
 
-Run `pnpm verify:perf` when a performance checkpoint is triggered: first working app version, renderer/canvas/animation/export/timeline/layers changes, a fix for previously broken functionality, any performance optimization, or a user request to optimize performance, fix lag, remove jank, speed up animation, or stabilize drag/zoom.
+Run `pnpm verify:perf` when a performance checkpoint is triggered: first working app version, renderer/canvas/animation/export/timeline/layers changes, adding/enabling `canvas.renderScale` or the `Resolution scale` retina slider, a fix for previously broken functionality, any performance optimization, or a user request to optimize performance, fix lag, remove jank, speed up animation, or stabilize drag/zoom.
 
 Fresh folders or dependency changes need `pnpm install` before verification. Final delivery still starts the local app after the gate:
 

package/templates/starter/docs/toolcraft/acceptance-testing.md

@@ -16,7 +16,7 @@ Every visible product entity must prove it works. A control is not accepted beca
 
 `pnpm verify:final` must pass before final delivery. Incremental edits use the verification tier classifier from `assembly-workflow.md`: run targeted browser acceptance for the changed entity, and add `pnpm verify:perf` whenever a performance checkpoint is triggered.
 
-A performance checkpoint is triggered by the first working app version, renderer/canvas/animation/export/timeline/layers changes, a fix for previously broken functionality, any performance optimization, or a user request to optimize performance, fix lag, remove jank, speed up animation, or stabilize drag/zoom.
+A performance checkpoint is triggered by the first working app version, renderer/canvas/animation/export/timeline/layers changes, adding/enabling `canvas.renderScale` or the `Resolution scale` retina slider, a fix for previously broken functionality, any performance optimization, or a user request to optimize performance, fix lag, remove jank, speed up animation, or stabilize drag/zoom.
 
 ## Product Readiness
 
@@ -58,7 +58,7 @@ Each row should name:
 
 The test gate rejects rows without matching automated and browser test names.
 
-`fixed-output` canvas sizing must be deliberate. Its runtime acceptance row must explain why width and height are non-editable. A default size from the prompt should use `editable-output`, which keeps the runtime Canvas width and Canvas height controls.
+`fixed-output` canvas sizing must be deliberate. Its runtime acceptance row must explain why width, height, and aspect ratio are non-editable. A default size from the prompt should use `editable-output`, which keeps the runtime Aspect ratio, Canvas width, and Canvas height controls.
 
 When localStorage persistence is enabled, add a runtime acceptance row that proves reload behavior. The browser test must change a real user-facing setting, wait for persistence to write, call a real page reload, and verify the restored control value or product output. Importing a settings JSON file is not persistence coverage.
 
@@ -136,6 +136,8 @@ Valid acceptance evidence includes:
 
 Product apps must include output delivery acceptance. Still-output apps need `Export PNG` evidence. Animated apps need both `Export Video` evidence and `Export PNG` evidence. Clipboard copy can be tested as an additional behavior, but it cannot replace export coverage.
 
+Every app with `Export PNG` must exercise the separate `Image Export` section: choose at least two `export.image.format` values, choose at least two `export.image.resolution` values, export the image, and decode the result to prove file type and actual pixel dimensions changed. Animated apps with both `Export PNG` and `Export Video` still need this image-export coverage; `Video Export` does not replace it.
+
 Async Export, Download, Copy, Generate, or Apply acceptance must prove the sticky footer top accent indicator is visible while the returned `onPanelAction` Promise is pending, advances when `reportProgress(0..1)` is called, and hides after it settles. Video export acceptance must prove frame-based progress updates during render/encode instead of only toggling a pending state.
 
 Animated app acceptance must also exercise the separate `Video Export` section: choose at least two `export.video.format` values, choose at least two `export.video.resolution` values, verify unsupported MIME/container choices fall back safely, and assert exported video bytes, dimensions, MIME/container, and duration match runtime timeline state. The duration assertion must load the exported blob as a video, wait for metadata, and compare `video.duration` with the edited timeline duration; `blobSize > 0`, `blobType`, WebM parser fallback, or assigning the expected duration when metadata is missing are not enough.

package/templates/starter/docs/toolcraft/assembly-workflow.md

@@ -138,7 +138,7 @@ Every product app exposes output background controls:
 
 Preview, PNG export, and video export read the background color runtime value. PNG export passes the include-background runtime value to the export helper. Turning `export.includeBackground` off makes only PNG output transparent; live preview, workspace canvas backing, and video output keep the background.
 
-Keep those controls together in one `Background` section. When the section title supplies the full context, prefer an inline row with hidden-label `export.includeBackground` on the left and the background color parameter on the right; do not repeat `Background` as both the section title and switch label.
+Keep those controls together in one required `Background` section directly before the first export settings section. With PNG export that first settings section is `Image Export`; with video-only export it is `Video Export`. Use an equal-width inline row with `export.includeBackground` on the left and the background color parameter on the right; each control occupies half the row. The switch label is `Include`; the color control uses `label: false` because the section title already supplies the background context.
 
 Every product app needs output delivery in sticky footer `panelActions`. Still-output apps expose `Export PNG`. Animated apps expose `Export Video` and `Export PNG`. Clipboard copy is optional and never replaces export. If an odd number of footer actions leaves one action alone in the final row, that final action spans the full row.
 
@@ -146,12 +146,21 @@ Async product actions such as Export, Download, Copy, Generate, or Apply must re
 
 For complex apps, use schema `settingsTransfer: "auto"` or `true` for settings import/export. Recalculate settings-transfer eligibility after adding, removing, or reorganizing controls, sections, timeline, or layers. The runtime threshold is 12 product controls, 5 product sections, or weighted score 18. Do not put Import Settings or Export Settings in sticky footer `panelActions`; runtime inserts the technical `Setup` settings-transfer section first without a visible section heading.
 
-If the app also uses `editable-output` canvas sizing, that first technical `Setup` runtime section is mandatory and contains `Export Settings`, `Import Settings`, `Canvas width`, and `Canvas height` in that order. Do not split the canvas size fields and settings-transfer actions into app-authored sections.
+If the app also uses `editable-output` canvas sizing, that first technical `Setup` runtime section is mandatory and contains `Export Settings`, `Import Settings`, `Aspect ratio`, `Canvas width`, `Canvas height`, and optional `Resolution scale` in that order. Do not split the canvas size fields and settings-transfer actions into app-authored sections.
+
+For non-vector raster, Canvas 2D, WebGL, or WebGPU previews, set `canvas.renderScale: true`. Runtime appends `Resolution scale` to the same first technical section. The slider changes backing resolution from `1x` to `2x` without changing visible canvas size; DOM/SVG/vector-native previews should not use it.
 
 If a controls panel shows only `Export Settings` and `Import Settings` in the first runtime section, check the canvas sizing decision. Product-output apps usually need `editable-output`; intrinsic media and explicitly fixed output are the cases where visible canvas size inputs are absent.
 
 For user-edited settings that should survive reload, use schema `persistence` with a stable app-specific key. When localStorage persistence is enabled, acceptance must prove a user setting restores after a real browser reload. Do not use settings import/export as a workaround for broken persistence.
 
+Every app with `Export PNG` must include a separate `Image Export` controls section with:
+
+- `export.image.format` as `select`, defaulting to `png`, with `png` and `jpg` baseline options;
+- `export.image.resolution` as `select`, defaulting to `4k`, with `2k`, `4k`, and `8k` baseline options.
+
+`Image Export` `Format` and `Resolution` are one compact workflow pair: render them in a two-column inline row by default. For still-output apps, place `Image Export` directly above sticky footer export buttons. For animated apps with both image and video export, place `Image Export` immediately before `Video Export`.
+
 Animated apps with `Export Video` must include a separate `Video Export` controls section with at least:
 
 - `export.video.format` as `select`, defaulting to `mp4`, with `mp4` and `webm` baseline options;
@@ -159,7 +168,7 @@ Animated apps with `Export Video` must include a separate `Video Export` control
 
 Place `Video Export` as the final authored controls section directly above sticky footer export buttons. Treat `Format` and `Resolution` as a compact semantic pair and put them in one two-column inline row by default. Use vertical rows only when the compact row would clip labels or selected values, and record that fallback reason in the worklog.
 
-Use standard export helpers. `createToolcraftPngExportCanvas` applies retina sizing and accepts `includeBackground` for runtime PNG transparency. Do not rely on static `export.png.background` alone when the UI exposes background controls. Video export keeps background and still uses `getToolcraftRetinaExportSize`.
+Use standard export helpers. `createToolcraftPngExportCanvas` accepts `includeBackground` for runtime PNG transparency and `resolution` for image-export output size. Pass the selected `export.image.resolution` into the PNG helper so 2K/4K/8K produce actual 2048/4096/8192px long-edge PNGs. Do not rely on static `export.png.background` alone when the UI exposes background controls. Video export keeps background and still uses `getToolcraftRetinaExportSize`.
 
 Video export must choose the actual MIME/container with `MediaRecorder.isTypeSupported(...)` or an explicit encoder/transcoder capability check. `MOV` and `ProRes` are allowed only when the app provides a custom encoder/transcoder and proves it with acceptance plus performance coverage. Treat `4K` as an export resolution target, not a hardcoded canvas lock. Offline rendered-frame export must encode or mux frame timestamps from runtime timeline time; real-time `canvas.captureStream()` plus `MediaRecorder` records wall-clock export time and is not enough when renderer work can be slower than playback. Browser acceptance must load the exported blob as a video, wait for metadata, and compare `video.duration` with the edited timeline duration; `blobSize > 0`, `blobType`, parser fallback, or assigning the expected duration in `catch` is not enough.
 
@@ -190,7 +199,7 @@ Do not rerun `pnpm install` after every edit. Run it after fresh export, depende
 
 Use `pnpm verify:ui` when a tier calls for the browser acceptance suite without the performance suite. Use a focused named Playwright test instead when only one entity changed and the relevant test is already known.
 
-Run a full performance checkpoint with `pnpm verify:perf` when the first working version of the app exists, when renderer/canvas/animation/export/timeline/layers change, after fixing a bug that previously broke functionality, after any performance optimization, or when the user asks to optimize performance, fix lag, remove jank, speed up animation, or stabilize drag/zoom.
+Run a full performance checkpoint with `pnpm verify:perf` when the first working version of the 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, or when the user asks to optimize performance, fix lag, remove jank, speed up animation, or stabilize drag/zoom.
 
 Fast feature loops may defer full performance only when none of the checkpoint triggers apply. Record the deferred check and reason in the worklog.
 

package/templates/starter/docs/toolcraft/component-rules.md

@@ -50,6 +50,10 @@ Visual discrete sliders must declare `step`; the runtime derives one marker per
 
 Schema sliders always render stacked at full width. Do not put `slider` or `rangeSlider` controls in two-column inline rows. The only built-in exception is `fontPicker`, whose letter-spacing and line-height footer sliders stay paired inside that component.
 
+Use slider `unit` only for measurement or scale suffixes: `%`, `px`, `°`, `x`, `s`, `ms`, `fps`, `rows`, `cols`, or a similarly useful domain unit. Do not use `unit` to repeat the entity already named by the section or label. Avoid `Letters` + `letters`, `Shape Density / Count` + `shapes`, `Words` + `words`, `Symbols` + `symbols`, `Items` + `items`, `Particles` + `particles`, and `Layers` + `layers`. If the numeric value needs an entity noun to make sense, rename the label or section instead of appending the noun to the value. Compact units render tight (`70%`, `24px`, `1.2x`, `8s`); word or acronym units render with a space (`5 cols`, `17 fps`) only when they are truly needed.
+
+Slider value labels are editable only when they contain a numeric value. Textual state labels such as `Normal` are display-only and must not expose hover or click editing affordances.
+
 Range sliders are always full-width two-thumb controls. Do not put a `rangeSlider` in an inline row. Its `defaultValue` must start with different lower and upper values, such as `[20, 80]`, so the control does not collapse into a single-value slider.
 
 Range slider value editing accepts common range separators such as `20/80`, `20-80`, `20 - 80`, `20 80`, and en-dash ranges. Use the built-in parser instead of adding custom label parsing.
@@ -124,9 +128,9 @@ Use `colorOpacity` when one product entity owns both color and opacity, such as
 
 When one short numeric/text field and one plain `color` field configure the same entity, they can share a two-column inline row. Example: `Mask size` and `Color` belong in the same `Mask` row instead of two stacked rows. Do not put `colorOpacity` in inline rows.
 
-Mixed inline rows require label parity: every field in that row has a visible label. The exception is a section-title-owned toggle + parameter row: a hidden-label `switch` or `checkbox` may sit beside one related parameter when the section title supplies the visible context. Color fields in other mixed rows must not be unlabeled.
+Mixed inline rows require label parity: every field in that row has a visible label. The required `Background` section row is the only section-title-owned exception: use the switch label `Include` beside the background color parameter with `label: false`. Color fields in other mixed rows must not be unlabeled.
 
-Renderer-owned output background is a base product control. Use a schema `color` target such as `appearance.background` or `scene.background`, add an `export.includeBackground` control for PNG transparency, and make preview/export read those runtime values. Keep them in one `Background` section. Prefer one inline row with hidden-label `export.includeBackground` on the left and `appearance.background` on the right when no other fit rule is violated. `export.includeBackground` controls only PNG alpha; it must not make live preview, workspace canvas backing, or video output transparent. Do not hardcode a configurable background in CSS, Canvas `fillStyle`, or WebGL clear color.
+Renderer-owned output background is a base product control. Use a schema `color` target such as `appearance.background` or `scene.background`, add an `export.includeBackground` control for PNG transparency, and make preview/export read those runtime values. Keep them in one required `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`. Use one equal-width inline row with `export.includeBackground` on the left and `appearance.background` on the right when no other fit rule is violated. The switch label is `Include`, not `Include background`; the background color control uses `label: false`. Each control occupies one half of the row; do not shrink the toggle column to intrinsic width. `export.includeBackground` controls only PNG alpha; it must not make live preview, workspace canvas backing, or video output transparent. Do not hardcode a configurable background in CSS, Canvas `fillStyle`, or WebGL clear color.
 
 ## File Upload
 
@@ -134,6 +138,8 @@ Use `fileDrop` for source material uploads in the controls panel. Do not place u
 
 In single-layer apps, the runtime shows uploaded image preview and clear button in the file control. Clearing removes source material from the renderer and canvas.
 
+Use `multiple: true` when the app needs several uploaded images as one source set. The runtime appends media, switches to a four-column thumbnail grid when more than one image is present, puts the add-more tile last, and keeps per-image removal inside the file control.
+
 In multi-layer apps, deletion and visibility belong to the Layers panel; `fileDrop` stays an upload target.
 
 ## Image Picker
@@ -211,15 +217,17 @@ Short labels must still be semantically sufficient with nearby context. `Animati
 
 Visible control labels can get a runtime-owned filled Phosphor question tooltip icon. Put a concise product-specific explanation in `description` only when it adds meaning beyond the label. Do not write recaps like `Adjusts Opacity`, and do not build custom help icons beside built-in labels.
 
+Do not add `description` to obvious color clusters. If a section title already names the palette/color context, sequential labels such as `Color 1`, `Color 2`, or simple palette controls such as `Spread` do not need help icons. Keep the whole obvious group clean unless the tooltip explains a non-obvious product behavior.
+
 For compound controls such as `fontPicker`, `description` must not enumerate owned fields like font, weight, size, case, color, opacity, letter spacing, or line height. The component already labels those fields.
 
 If a source label is unavoidably long, keep the visible label concise and rely on native `title` for the full text.
 
-Switch and checkbox labels name the setting context, not the action. Do not prefix them with `Enable` or `Disable`; use `CRT`, `Glow`, `Loop`, or `Guides` instead of `Enable CRT` or `Disable guides`. If the section title already names the setting context, do not repeat that title as the visible toggle label; use `label: false` and keep the meaning in `target` and `description`.
+Switch and checkbox labels name the setting context, not the action. Do not prefix them with `Enable` or `Disable`; use `CRT`, `Glow`, `Loop`, or `Guides` instead of `Enable CRT` or `Disable guides`. If the section title already names the setting context, do not repeat that title as the visible toggle label; use a short contextual label such as `Include` or, only for icon-only visual toggles, `label: false` with the meaning in `target` and `description`.
 
 Two adjacent `switch` or `checkbox` controls for the same product entity must share one inline row when every visible label fits without truncation. Use short one- or two-word labels such as `Snap X` and `Snap Y`, or `Glow` and `Loop`. The runtime auto-pairs safe adjacent toggles by target entity; use explicit layout groups only when pairing a toggle with a non-toggle parameter. If either label would truncate in half-width, remove the inline group and let the toggles stack.
 
-A single `switch` or `checkbox` may share an inline row with one related parameter control when the toggle label fits and the controls edit the same entity. Example: `Loop` plus `Duration`, or hidden-label `export.includeBackground` plus `appearance.background` inside `Background`. If the section title already names the toggle context, hide the toggle label instead of repeating the title.
+A single `switch` or `checkbox` may share an inline row with one related parameter control when the toggle label fits and the controls edit the same entity. This row is always equal-width: each control occupies one half. Example: `Loop` plus `Duration`, or `Include` plus unlabeled background color inside the required `Background` section. If the section title already names the toggle context, shorten the label instead of repeating the title.
 
 ## Layers
 
@@ -267,16 +275,27 @@ Use schema `settingsTransfer` for settings import/export. Do not add Import Sett
 
 Recalculate settings-transfer eligibility after adding, removing, or reorganizing controls, sections, timeline, or layers. The runtime threshold is 12 product controls, 5 product sections, or weighted score 18. If the threshold is reached, use `settingsTransfer: "auto"` / `true` or document a product-specific opt-out through `runtime.settingsTransfer` acceptance evidence.
 
-When settings transfer and editable-output canvas sizing are both enabled, the first technical `Setup` runtime section is mandatory and contains `Export Settings`, `Import Settings`, `Canvas width`, and `Canvas height` in that order. Do not split these into separate app-authored sections, rename the controls, or rebuild the block by hand.
+When settings transfer and editable-output canvas sizing are both enabled, the first technical `Setup` runtime section is mandatory and contains `Export Settings`, `Import Settings`, `Aspect ratio`, `Canvas width`, `Canvas height`, and optional `Resolution scale` in that order. Do not split these into separate app-authored sections, rename the controls, or rebuild the block by hand.
 
 If only `Export Settings` and `Import Settings` appear in that section, the schema is not using `editable-output` canvas sizing or already owns `canvas.size.width` / `canvas.size.height` controls. For product-output apps, prefer fixing the canvas sizing decision over adding hand-built size fields.
 
+Manual `Canvas width` or `Canvas height` edits are exact output-size edits. They keep the other dimension unchanged, switch `Aspect ratio` to `Custom`, and update the custom ratio inputs to the reduced current ratio. Do not recreate the old behavior where typing one size field stays locked to the previous aspect preset.
+
+Enable `canvas.renderScale: true` for non-vector raster previews such as Canvas 2D, WebGL, or WebGPU output. Runtime adds a `Resolution scale` slider after canvas sizing; it defaults to `2x` and lets users trade preview quality/performance without changing output size. Adding or enabling this slider requires a full `pnpm verify:perf` checkpoint. Performance fixes must preserve the selected scale and keep canvas preview responsive while dragging sliders or other high-frequency controls. Diagnose the actual bottleneck before lowering quality; do not silently downsample, stretch a lower-resolution backing canvas, blur output, or clamp `canvas.renderScale` below the user's chosen value. Do not enable it for DOM/SVG/vector-native previews.
+
 Reset belongs to the controls panel header reset button. Do not add a footer action with `label`, `value`, or `command` containing reset; acceptance treats that as a duplicate Reset.
 
 Still-output product apps include one primary `Export PNG` action.
 
 Animated product apps include `Export Video` as the primary action and `Export PNG` as the secondary action.
 
+Every product app with `Export PNG` includes a separate `Image Export` section. That section must contain:
+
+- `export.image.format` as a `select`, with default value `png` and baseline options `png` and `jpg`;
+- `export.image.resolution` as a `select`, with default value `4k` and baseline options `2k`, `4k`, and `8k`.
+
+Place `Image Export` directly above sticky footer export buttons for still-output apps. For animated apps with both PNG and video export, place `Image Export` immediately before `Video Export`. `Format` and `Resolution` are one compact workflow pair: render them in a two-column inline row by default. Do not use `segmented` for this pair; it must visually match the Video Export dropdown structure.
+
 Animated product apps with `Export Video` include a separate `Video Export` section. That section must contain:
 
 - `export.video.format` as a `select`, with default value `mp4` and baseline options `mp4` and `webm`;

package/templates/starter/docs/toolcraft/performance.md

@@ -55,6 +55,8 @@ Ordinary controls still need lightweight responsiveness checks. They should not
 - panel scroll affecting canvas zoom;
 - timeline or layer interactions destabilizing the viewport.
 
+When `canvas.renderScale` / `Resolution scale` is enabled, responsiveness coverage must include slider or other high-frequency control drags at the selected scale. If the canvas lags, diagnose the source before changing quality: renderer technique, React update frequency, decoded media, shader/program setup, buffer uploads, layout work, stale async renders, or animation scheduling.
+
 ## Renderer Performance
 
 Custom renderers should:
@@ -105,8 +107,11 @@ Run a full performance checkpoint with `pnpm verify:perf` when:
 
 - the first working version of the app exists;
 - renderer, canvas, animation, export, timeline, or layers change;
+- `canvas.renderScale` or the `Resolution scale` retina slider is added/enabled;
 - a bug that previously broke functionality is fixed;
 - a performance optimization lands;
 - the user asks to optimize performance, fix lag, remove jank, speed up animation, or stabilize drag/zoom.
 
+Performance fixes must preserve selected output and preview quality. Do not pass budgets by lowering image quality, selected `canvas.renderScale`, export resolution, source media fidelity, or canvas backing pixels unless the user explicitly chooses that lower-quality value through a visible control. Prefer coalescing slider updates, caching expensive inputs, moving work off the React render path, reusing GPU resources, or changing renderer strategy over reducing visual fidelity.
+
 Do not use the full performance suite as the default loop for Tier 0-2 edits. Those edits still need the targeted checks named by the verification tier, but they should not pay for renderer and viewport stress tests unless a checkpoint trigger applies. If a fast feature loop defers full performance, record the deferred check and reason in the worklog.

package/templates/starter/docs/toolcraft/renderer-technique.md

@@ -2,7 +2,7 @@
 
 Choose render technology per product layer. Do not choose a renderer because it is convenient; choose it from product output semantics, reference behavior, fidelity, and workload.
 
-The initial renderer choice is provisional. It becomes accepted only after the app passes performance checks with the largest useful product canvas and the heaviest useful values for its own controls. If those checks show frame gaps, long tasks, viewport shaking, slow export, or interaction jank, revise the renderer strategy from that evidence before delivery.
+The initial renderer choice is provisional. It becomes accepted only after the app passes performance checks with the largest useful product canvas and the heaviest useful values for its own controls. If those checks show frame gaps, long tasks, viewport shaking, slow export, or interaction jank, revise the renderer strategy from that evidence before delivery. Do not make a renderer look fast by silently reducing the selected preview scale, backing pixels, source media quality, or export fidelity.
 
 ## Strategy Guide