@pixel-point/toolcraft 0.0.3 → 0.0.4

package/templates/runtime/state/reducer.test.ts

@@ -103,13 +103,68 @@ describe("toolcraftReducer", () => {
     const redone = toolcraftReducer(undone, { type: "history.redo" });
 
     expect(changed.canvas.size.width).toBe(640);
+    expect(changed.canvas.size.height).toBe(410);
     expect(changed.values["canvas.size.width"]).toBe(640);
+    expect(changed.values["canvas.size.height"]).toBe(410);
     expect(changed.history.undo.at(-1)?.label).toBe("canvas.size.width");
     expect(reset.canvas.size.width).toBe(1200);
+    expect(reset.canvas.size.height).toBe(768);
     expect(reset.values["canvas.size.width"]).toBe(1200);
+    expect(reset.values["canvas.size.height"]).toBe(768);
     expect(reset.history.undo.at(-1)?.label).toBe("Reset controls");
     expect(undone.canvas.size.width).toBe(1200);
+    expect(undone.canvas.size.height).toBe(768);
     expect(redone.canvas.size.width).toBe(640);
+    expect(redone.canvas.size.height).toBe(410);
+  });
+
+  it("routes canvas aspect ratio presets through canvas runtime state", () => {
+    const state = createState();
+
+    const changed = toolcraftReducer(state, {
+      target: "canvas.aspectRatio",
+      type: "controls.setValue",
+      value: {
+        height: 9,
+        mode: "preset",
+        value: "16:9",
+        width: 16,
+      },
+    });
+
+    expect(changed.canvas.size).toEqual({ height: 1080, unit: "px", width: 1920 });
+    expect(changed.values["canvas.aspectRatio"]).toEqual({
+      height: 9,
+      mode: "preset",
+      value: "16:9",
+      width: 16,
+    });
+    expect(changed.values["canvas.size.width"]).toBe(1920);
+    expect(changed.values["canvas.size.height"]).toBe(1080);
+    expect(changed.history.undo.at(-1)?.label).toBe("canvas.aspectRatio");
+  });
+
+  it("keeps canvas size edits locked to the current aspect ratio", () => {
+    const state = toolcraftReducer(createState(), {
+      target: "canvas.aspectRatio",
+      type: "controls.setValue",
+      value: {
+        height: 9,
+        mode: "preset",
+        value: "16:9",
+        width: 16,
+      },
+    });
+
+    const changed = toolcraftReducer(state, {
+      target: "canvas.size.height",
+      type: "controls.setValue",
+      value: "720",
+    });
+
+    expect(changed.canvas.size).toEqual({ height: 720, unit: "px", width: 1280 });
+    expect(changed.values["canvas.size.height"]).toBe(720);
+    expect(changed.values["canvas.size.width"]).toBe(1280);
   });
 
   it("updates canvas offset without recording history", () => {

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,137 @@ 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 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,6 +553,45 @@ export function toolcraftReducer(
     case "controls.setValue": {
       const canvasSizeDimension = getToolcraftCanvasSizeTargetDimension(command.target);
 
+      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 (
+          state.canvas.size.width === size.width &&
+          state.canvas.size.height === size.height &&
+          Object.is(state.values[command.target], ratio)
+        ) {
+          return state;
+        }
+
+        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);
 
@@ -415,26 +599,47 @@ export function toolcraftReducer(
           return state;
         }
 
+        const hasAspectRatioLock =
+          canvasAspectRatioTarget in state.values ||
+          canvasAspectRatioTarget in state.defaults;
+        const size = hasAspectRatioLock
+          ? applyCanvasAspectRatioToSize({
+              anchor: canvasSizeDimension,
+              ratio: normalizeCanvasAspectRatioValue(
+                state.values[canvasAspectRatioTarget],
+                state.canvas.size,
+              ),
+              size: state.canvas.size,
+              value: dimensionValue,
+            })
+          : {
+              ...state.canvas.size,
+              [canvasSizeDimension]: dimensionValue,
+            };
+        const targetValue = size[canvasSizeDimension];
+        const otherTarget =
+          canvasSizeDimension === "width" ? canvasSizeHeightTarget : canvasSizeWidthTarget;
+        const otherValue = canvasSizeDimension === "width" ? size.height : size.width;
+
         if (
-          state.canvas.size[canvasSizeDimension] === dimensionValue &&
-          state.values[command.target] === dimensionValue
+          state.canvas.size.width === size.width &&
+          state.canvas.size.height === size.height &&
+          state.values[command.target] === targetValue &&
+          state.values[otherTarget] === otherValue
         ) {
           return state;
         }
 
-        const size = {
-          ...state.canvas.size,
-          [canvasSizeDimension]: dimensionValue,
-        };
-
         return commitStatePatch(state, {
           after: {
             "canvas.size": size,
-            [command.target]: dimensionValue,
+            [command.target]: targetValue,
+            [otherTarget]: otherValue,
           },
           before: {
             "canvas.size": state.canvas.size,
             [command.target]: state.values[command.target],
+            [otherTarget]: state.values[otherTarget],
           },
           label: command.label ?? command.target,
         }, {

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`. When settings transfer and editable-output canvas sizing are both enabled, the first technical `Setup` runtime section contains `Export Settings`, `Import Settings`, `Aspect ratio`, `Canvas width`, and `Canvas height` in that order and renders without a visible section heading.
+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.
@@ -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/acceptance-testing.md

@@ -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,19 @@ 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`, and `Canvas height` in that order. Do not split the canvas size fields and settings-transfer actions into app-authored sections.
 
 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 +166,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.
 

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

@@ -124,9 +124,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
 
@@ -215,11 +215,11 @@ For compound controls such as `fontPicker`, `description` must not enumerate own
 
 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,7 +267,7 @@ 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`, and `Canvas height` 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.
 
@@ -277,6 +277,13 @@ 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/schema-reference.md

@@ -45,9 +45,47 @@ export: {
 - `appearance.background` or `scene.background` as a `color` control;
 - `export.includeBackground` as a boolean/options control.
 
-PNG exporters should call `createToolcraftPngExportCanvas({ background, includeBackground, state, render })`, where `background` and `includeBackground` come from runtime state. `includeBackground` controls only PNG alpha; live preview, workspace canvas backing, and video export keep the product background. Video export always includes the product background, uses `getToolcraftRetinaExportSize`, and must prove exported metadata duration matches the runtime timeline duration.
+PNG exporters should call `createToolcraftPngExportCanvas({ background, includeBackground, resolution, state, render })`, where `background`, `includeBackground`, and `resolution` come from runtime state. `includeBackground` controls only PNG alpha; live preview, workspace canvas backing, and video export keep the product background. For every app with `Export PNG`, `resolution` comes from `export.image.resolution`: `2k`, `4k`, and `8k` render actual 2048/4096/8192px long-edge PNGs. `current` or omitted resolution falls back to retina sizing. Video export always includes the product background, uses `getToolcraftRetinaExportSize`, and must prove exported metadata duration matches the runtime timeline duration.
 
-Animated apps with `Export Video` also expose a separate `Video Export` controls section. Do not mix video export settings into renderer/effect sections. Place this section as the final authored controls section directly above sticky footer export buttons. `Format` and `Resolution` are a compact semantic pair, so use an inline two-column layout by default; stack them only when labels or selected values would clip.
+Every app with `Export PNG` exposes a separate `Image Export` controls section. For still-output apps it sits directly above sticky footer actions. For animated apps with both `Export PNG` and `Export Video`, it sits immediately before `Video Export`:
+
+```ts
+{
+  title: "Image Export",
+  controls: {
+    imageFormat: {
+      defaultValue: "png",
+      label: "Format",
+      options: [
+        { label: "PNG", value: "png" },
+        { label: "JPG", value: "jpg" },
+      ],
+      target: "export.image.format",
+      type: "select",
+    },
+    imageResolution: {
+      defaultValue: "4k",
+      label: "Resolution",
+      options: [
+        { label: "2K", value: "2k" },
+        { label: "4K", value: "4k" },
+        { label: "8K", value: "8k" },
+      ],
+      target: "export.image.resolution",
+      type: "select",
+    },
+  },
+  layoutGroups: [
+    {
+      layout: "inline",
+      columns: 2,
+      controls: ["imageFormat", "imageResolution"],
+    },
+  ],
+}
+```
+
+Animated apps with `Export Video` also expose a separate `Video Export` controls section. Do not mix video export settings into renderer/effect sections. Place this section after `Image Export` as the final authored controls section directly above sticky footer export buttons. `Format` and `Resolution` are a compact semantic pair, so use an inline two-column layout by default; stack them only when labels or selected values would clip.
 
 ```ts
 {
@@ -96,9 +134,9 @@ Choose sizing from product context:
 
 For product output, export, copy, download, shader rendering, procedural rendering, or no single intrinsic source image, use `editable-output` unless the product explicitly needs `fixed-output`.
 
-A prompt-provided base/default size is only the initial `canvas.size`. It must not remove the runtime Canvas width and Canvas height controls. Use `fixed-output` only when the reference or product explicitly locks dimensions, and add runtime acceptance with `canvasSizingCoverage: "fixed-output-size"`.
+A prompt-provided base/default size is only the initial `canvas.size`. It must not remove the runtime Aspect ratio, Canvas width, and Canvas height controls. Aspect presets use canonical output sizes (`16:9` is `1920x1080`; the other presets are derived around a 1080px short edge or matching portrait long edge). Use `fixed-output` only when the reference or product explicitly locks dimensions, and add runtime acceptance with `canvasSizingCoverage: "fixed-output-size"`.
 
-Resolved `canvas.size` exists for every canvas app, but visible `Canvas width` and `Canvas height` inputs are mandatory only for `editable-output` sizing. They do not depend on `settingsTransfer`: when settings transfer is off, the runtime prepends a technical `Setup` canvas size section without a visible heading; when settings transfer is on, the controls merge into the first technical `Setup` runtime settings section without a visible heading. Do not hand-build a duplicate size selector.
+Resolved `canvas.size` exists for every canvas app, but visible `Aspect ratio`, `Canvas width`, and `Canvas height` controls are mandatory only for `editable-output` sizing. They do not depend on `settingsTransfer`: when settings transfer is off, the runtime prepends a technical `Setup` canvas size section without a visible heading; when settings transfer is on, the controls merge into the first technical `Setup` runtime settings section without a visible heading. Do not hand-build a duplicate size selector.
 
 ## Panels
 
@@ -203,9 +241,9 @@ Control labels are judged with their nearest visible context. Short property lab
 
 If a target prefix has to be split across sections, the spec must name the workflow reason. Otherwise the acceptance validator treats the split as a sectioning error.
 
-Switch and checkbox labels name the setting context only. Do not prefix them with `Enable` or `Disable`; use `CRT`, `Glow`, `Loop`, or `Guides` instead. If the nearest section title already names the context, do not duplicate it as the visible toggle label. Use `label: false` for a visual-only toggle and keep the product meaning in `target` and `description`.
+Switch and checkbox labels name the setting context only. Do not prefix them with `Enable` or `Disable`; use `CRT`, `Glow`, `Loop`, or `Guides` instead. If the nearest section title already names the context, do not duplicate it as the visible toggle label. Use a short contextual label such as `Include` or, only for icon-only visual toggles, `label: false` with the product meaning in `target` and `description`.
 
-Inline two-column groups are preferred when controls tune one close product meaning and labels/values fit. Short numeric text pairs can be inline. Related short `select` pairs can be inline, especially workflow pairs such as `Format` + `Resolution`, `Codec` + `Profile`, or `Width unit` + `Height unit`. Use stacked one-control rows only as a fit fallback when a label, selected value, or option text would clip, truncate, or lose padding; record that fallback reason in the spec or worklog. A short numeric/text field may also pair with one related plain `color` field when both configure the same entity, such as `Mask size` and `Color` inside `Mask`. `colorOpacity` never renders in inline two-column groups; if either color control has opacity, keep the controls stacked. Color controls show visible field labels in mixed sections that contain any non-color control. Omit visible color labels only in color-only sections or in a section-title-owned toggle + parameter row, such as hidden `export.includeBackground` plus `appearance.background` inside `Background`. Mixed inline rows require visible labels on every field except this hidden-label toggle + parameter pattern. Color fields in other mixed rows must not be unlabeled. Two adjacent `switch` or `checkbox` controls for the same product entity must share one inline row when both visible labels fit without truncation; the runtime auto-pairs safe adjacent toggles by target entity, and schemas should stack them only when either label is too long. A single `switch` or `checkbox` may share an inline row with one related parameter control when the toggle label fits and both controls edit the same entity; hide the toggle label when the section title already supplies the context. Schema `slider` and `rangeSlider` controls always stay stacked at full width; the only built-in exception is the paired letter-spacing and line-height footer sliders inside `fontPicker`. Do not place sibling controls for case, color, opacity, size, weight, letter spacing, or line height when the same text entity already uses `fontPicker`.
+Inline two-column groups are preferred when controls tune one close product meaning and labels/values fit. Short numeric text pairs can be inline. Related short `select` pairs can be inline, especially workflow pairs such as `Format` + `Resolution`, `Codec` + `Profile`, or `Width unit` + `Height unit`. Use stacked one-control rows only as a fit fallback when a label, selected value, or option text would clip, truncate, or lose padding; record that fallback reason in the spec or worklog. A short numeric/text field may also pair with one related plain `color` field when both configure the same entity, such as `Mask size` and `Color` inside `Mask`. `colorOpacity` never renders in inline two-column groups; if either color control has opacity, keep the controls stacked. Color controls show visible field labels in mixed sections that contain any non-color control. Omit visible color labels only in color-only sections. Mixed inline rows require visible labels on every field, except the required Background row where the color control uses `label: false` because the section title owns the context. Color fields in other mixed rows must not be unlabeled. Two adjacent `switch` or `checkbox` controls for the same product entity must share one inline row when both visible labels fit without truncation; the runtime auto-pairs safe adjacent toggles by target entity, and schemas should stack them only when either label is too long. A single `switch` or `checkbox` may share an inline row with one related parameter control when the toggle label fits and both controls edit the same entity; shorten the toggle label when the section title already supplies context. Toggle plus parameter rows are equal-width two-column rows: each control occupies one half, never intrinsic toggle width plus remaining space. The required Background row uses `Include` plus unlabeled background color. Schema `slider` and `rangeSlider` controls always stay stacked at full width; the only built-in exception is the paired letter-spacing and line-height footer sliders inside `fontPicker`. Do not place sibling controls for case, color, opacity, size, weight, letter spacing, or line height when the same text entity already uses `fontPicker`.
 
 `rangeSlider` is always a full-width two-thumb control. Do not include it in `layoutGroups`. Its `defaultValue` must start with different lower and upper values, such as `[20, 80]`, so the two handles do not collapse into one apparent slider. Manual range labels accept built-in separators such as slash, hyphen, spaces, and dashes.
 
@@ -258,7 +296,7 @@ When enabled, the runtime inserts a technical `Setup` settings-transfer section
 
 After adding, removing, or reorganizing controls, sections, timeline, or layers, recalculate settings-transfer eligibility. If the threshold is reached, use `"auto"` / `true` or add an explicit `runtime.settingsTransfer` opt-out acceptance row with product evidence.
 
-When settings transfer is enabled and the canvas uses `editable-output` sizing, 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 sections or recreate them manually.
+When settings transfer is enabled and the canvas uses `editable-output` sizing, the first technical `Setup` runtime section is mandatory and contains `Export Settings`, `Import Settings`, `Aspect ratio`, `Canvas width`, and `Canvas height` in that order. Do not split these into separate sections or recreate them manually.
 
 A settings-transfer section with only `Export Settings` and `Import Settings` means the canvas is not `editable-output` or the app already declares its own `canvas.size.width` / `canvas.size.height` controls. For product-output apps, treat that as a schema decision to review.