@pixel-point/toolcraft 0.0.4 → 0.0.6

package/templates/runtime/schema/define-toolcraft.ts

@@ -26,9 +26,9 @@ import type {
 } from "./types";
 
 const defaultCanvasSize = {
-  height: 1024,
+  height: 1080,
   unit: "px",
-  width: 1024,
+  width: 1920,
 } satisfies ToolcraftCanvasSize;
 
 type ResolvedCanvas = ResolvedToolcraftAppSchema["canvas"];
@@ -46,6 +46,14 @@ const canvasSizeControlTargets = {
   width: "canvas.size.width",
 } as const;
 const canvasAspectRatioTarget = "canvas.aspectRatio";
+const canvasRenderScaleTarget = "canvas.renderScale";
+const defaultCanvasRenderScale = {
+  defaultValue: 2,
+  enabled: false,
+  max: 2,
+  min: 1,
+  step: 0.25,
+} satisfies ResolvedToolcraftAppSchema["canvas"]["renderScale"];
 const maxAutoInlineControlLabelLength = 18;
 const settingsTransferTarget = "runtime.settingsTransfer";
 const runtimeSetupSectionTitle = "Setup";
@@ -190,6 +198,54 @@ function resolveCanvasSizing(
   return { mode: "intrinsic-media" };
 }
 
+function clampCanvasRenderScale(value: number | undefined, fallback: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return fallback;
+  }
+
+  return Math.max(1, Math.min(2, value));
+}
+
+function resolveCanvasRenderScale(
+  renderScale: ToolcraftAppSchema["canvas"]["renderScale"],
+): ResolvedToolcraftAppSchema["canvas"]["renderScale"] {
+  if (renderScale === true) {
+    return {
+      ...defaultCanvasRenderScale,
+      enabled: true,
+    };
+  }
+
+  if (!renderScale) {
+    return defaultCanvasRenderScale;
+  }
+
+  const min = clampCanvasRenderScale(renderScale.min, defaultCanvasRenderScale.min);
+  const max = Math.max(
+    min,
+    clampCanvasRenderScale(renderScale.max, defaultCanvasRenderScale.max),
+  );
+  const step =
+    typeof renderScale.step === "number" && Number.isFinite(renderScale.step)
+      ? Math.max(0.01, Math.min(1, renderScale.step))
+      : defaultCanvasRenderScale.step;
+  const defaultValue = Math.max(
+    min,
+    Math.min(
+      max,
+      clampCanvasRenderScale(renderScale.defaultValue, defaultCanvasRenderScale.defaultValue),
+    ),
+  );
+
+  return {
+    defaultValue,
+    enabled: renderScale.enabled ?? true,
+    max,
+    min,
+    step,
+  };
+}
+
 function resolveExport(
   exportSchema: ToolcraftAppSchema["export"],
 ): ResolvedExport {
@@ -264,6 +320,10 @@ function createToolcraftAssembly({
       commands.push("canvas.setSize");
     }
 
+    if (canvas.renderScale.enabled) {
+      capabilities.push("canvas.renderScale");
+    }
+
     if (canvas.draggable) {
       capabilities.push("canvas.draggable");
       commands.push("canvas.panBy", "canvas.setOffset", "canvas.setViewport");
@@ -742,10 +802,12 @@ function getCanvasAspectRatioDefaultValue(size: ToolcraftCanvasSize): {
 
 function createCanvasSizeSection({
   aspectRatioControl,
+  renderScaleControl,
   sizeControlIds,
   sizeControls,
 }: {
   aspectRatioControl: ToolcraftControlSchema;
+  renderScaleControl?: ToolcraftControlSchema;
   sizeControlIds: readonly string[];
   sizeControls: ToolcraftControlSectionSchema["controls"];
 }): ToolcraftControlSectionSchema {
@@ -753,19 +815,33 @@ function createCanvasSizeSection({
     controls: {
       canvasAspectRatio: aspectRatioControl,
       ...sizeControls,
+      ...(renderScaleControl ? { canvasRenderScale: renderScaleControl } : {}),
     },
     layoutGroups: getCanvasSizeLayoutGroups(sizeControlIds),
     title: runtimeSetupSectionTitle,
   };
 }
 
+function createCanvasRenderScaleSection(
+  renderScaleControl: ToolcraftControlSchema,
+): ToolcraftControlSectionSchema {
+  return {
+    controls: {
+      canvasRenderScale: renderScaleControl,
+    },
+    title: runtimeSetupSectionTitle,
+  };
+}
+
 function mergeCanvasSizeControlsIntoSettingsTransferSection({
   aspectRatioControl,
+  renderScaleControl,
   settingsTransferSection,
   sizeControlIds,
   sizeControls,
 }: {
   aspectRatioControl: ToolcraftControlSchema;
+  renderScaleControl?: ToolcraftControlSchema;
   settingsTransferSection: ToolcraftControlSectionSchema;
   sizeControlIds: readonly string[];
   sizeControls: ToolcraftControlSectionSchema["controls"];
@@ -778,6 +854,7 @@ function mergeCanvasSizeControlsIntoSettingsTransferSection({
       ...settingsTransferSection.controls,
       canvasAspectRatio: aspectRatioControl,
       ...sizeControls,
+      ...(renderScaleControl ? { canvasRenderScale: renderScaleControl } : {}),
     },
     layoutGroups:
       canvasSizeLayoutGroups.length > 0 || settingsTransferSection.layoutGroups?.length
@@ -789,6 +866,22 @@ function mergeCanvasSizeControlsIntoSettingsTransferSection({
   };
 }
 
+function mergeCanvasRenderScaleIntoSettingsTransferSection({
+  renderScaleControl,
+  settingsTransferSection,
+}: {
+  renderScaleControl: ToolcraftControlSchema;
+  settingsTransferSection: ToolcraftControlSectionSchema;
+}): ToolcraftControlSectionSchema {
+  return {
+    ...settingsTransferSection,
+    controls: {
+      ...settingsTransferSection.controls,
+      canvasRenderScale: renderScaleControl,
+    },
+  };
+}
+
 function isPrimaryPanelAction(action: ToolcraftControlActionSchema): boolean {
   return typeof action !== "string" && action.variant !== "outline";
 }
@@ -1308,14 +1401,46 @@ function normalizePanels({
 
   const controls = { ...panels.controls };
   const settingsTransferSection = createSettingsTransferSection(settingsTransfer);
+  const renderScaleControl: ToolcraftControlSchema | undefined =
+    canvas.renderScale.enabled && !hasControlTarget(panels, canvasRenderScaleTarget)
+      ? {
+          defaultValue: canvas.renderScale.defaultValue,
+          description:
+            "Increases raster canvas backing resolution without changing the visible output size.",
+          label: "Resolution scale",
+          markerCount:
+            Math.floor(
+              (canvas.renderScale.max - canvas.renderScale.min) / canvas.renderScale.step,
+            ) + 1,
+          max: canvas.renderScale.max,
+          min: canvas.renderScale.min,
+          performanceReason:
+            "Resolution scale changes raster, Canvas, WebGL, or WebGPU backing pixels.",
+          performanceRole: "workload",
+          step: canvas.renderScale.step,
+          target: canvasRenderScaleTarget,
+          type: "slider",
+          unit: "x",
+          variant: "discrete",
+        }
+      : undefined;
 
   if (!canvas.enabled || canvas.sizing.mode !== "editable-output") {
+    const runtimeSetupSection =
+      settingsTransferSection && renderScaleControl
+        ? mergeCanvasRenderScaleIntoSettingsTransferSection({
+            renderScaleControl,
+            settingsTransferSection,
+          })
+        : (settingsTransferSection ??
+          (renderScaleControl ? createCanvasRenderScaleSection(renderScaleControl) : null));
+
     return {
       ...normalizedPanels,
       controls: normalizeControlsPanelLayout({
         ...controls,
         sections: [
-          ...(settingsTransferSection ? [settingsTransferSection] : []),
+          ...(runtimeSetupSection ? [runtimeSetupSection] : []),
           ...controls.sections,
         ],
       }),
@@ -1357,7 +1482,7 @@ function normalizePanels({
     sizeControlIds.push("canvasHeight");
   }
 
-  if (Object.keys(sizeControls).length === 0) {
+  if (Object.keys(sizeControls).length === 0 && !renderScaleControl) {
     return {
       ...normalizedPanels,
       controls: normalizeControlsPanelLayout({
@@ -1373,11 +1498,17 @@ function normalizePanels({
   const runtimeSettingsSection = settingsTransferSection
     ? mergeCanvasSizeControlsIntoSettingsTransferSection({
         aspectRatioControl,
+        renderScaleControl,
         settingsTransferSection,
         sizeControlIds,
         sizeControls,
       })
-    : createCanvasSizeSection({ aspectRatioControl, sizeControlIds, sizeControls });
+    : createCanvasSizeSection({
+        aspectRatioControl,
+        renderScaleControl,
+        sizeControlIds,
+        sizeControls,
+      });
 
   return {
     ...normalizedPanels,
@@ -1453,6 +1584,7 @@ function assertPanelPersistenceContract({
 export function defineToolcraft(schema: ToolcraftAppSchema): ResolvedToolcraftAppSchema {
   const canvasEnabled = schema.canvas.enabled;
   const canvasSize = schema.canvas.size;
+  const canvasRenderScale = resolveCanvasRenderScale(schema.canvas.renderScale);
   const canvasSizing = resolveCanvasSizing(schema.canvas);
   const persistence = resolvePersistence(schema.persistence);
   const settingsTransfer = resolveSettingsTransfer({
@@ -1464,6 +1596,7 @@ export function defineToolcraft(schema: ToolcraftAppSchema): ResolvedToolcraftAp
   const canvas = {
     ...schema.canvas,
     draggable: canvasEnabled ? (schema.canvas.draggable ?? true) : false,
+    renderScale: canvasRenderScale,
     size: canvasSize ?? defaultCanvasSize,
     sizeSource: canvasSize ? ("app" as const) : ("runtime-default" as const),
     sizing: canvasSizing,

package/templates/runtime/schema/runtime-targets.ts

@@ -1,5 +1,6 @@
 export const toolcraftRuntimeOwnedTargets = [
   "canvas.aspectRatio",
+  "canvas.renderScale",
   "canvas.size.width",
   "canvas.size.height",
 ] as const;

package/templates/runtime/schema/types.ts

@@ -21,6 +21,24 @@ export type ToolcraftCanvasSizingSchema = {
   mode: ToolcraftCanvasSizingMode;
 };
 
+export type ToolcraftCanvasRenderScaleSchema =
+  | boolean
+  | {
+      defaultValue?: number;
+      enabled?: boolean;
+      max?: number;
+      min?: number;
+      step?: number;
+    };
+
+export type ResolvedToolcraftCanvasRenderScaleSchema = {
+  defaultValue: number;
+  enabled: boolean;
+  max: number;
+  min: number;
+  step: number;
+};
+
 export type ToolcraftPngExportBackground = "include" | "transparent";
 
 export type ToolcraftPngExportSchema = {
@@ -45,6 +63,7 @@ export type ToolcraftAssemblyComponentId =
 export type ToolcraftAssemblyCapability =
   | "canvas.draggable"
   | "canvas.editableSize"
+  | "canvas.renderScale"
   | "canvas.upload"
   | "controls.defaults"
   | "controls.panel"
@@ -141,6 +160,7 @@ export type ToolcraftAssemblyContract = {
 export type ToolcraftCanvasSchema = {
   draggable?: boolean;
   enabled: boolean;
+  renderScale?: ToolcraftCanvasRenderScaleSchema;
   size?: ToolcraftCanvasSize;
   sizing?: ToolcraftCanvasSizingSchema;
   upload?: boolean;
@@ -300,6 +320,7 @@ export type ToolcraftControlSchema = {
   markerCount?: number;
   max?: number;
   min?: number;
+  multiple?: boolean;
   orderRole?: ToolcraftControlOrderRole;
   performanceReason?: string;
   performanceRole?: ToolcraftControlPerformanceRole;
@@ -358,7 +379,8 @@ export type ToolcraftAppSchema = {
 
 export type ResolvedToolcraftAppSchema = {
   assembly: ToolcraftAssemblyContract;
-  canvas: Required<ToolcraftCanvasSchema> & {
+  canvas: Omit<Required<ToolcraftCanvasSchema>, "renderScale"> & {
+    renderScale: ResolvedToolcraftCanvasRenderScaleSchema;
     size: ToolcraftCanvasSize;
     sizeSource: ToolcraftCanvasSizeSource;
   };

package/templates/runtime/state/canvas-zoom.ts

@@ -1,7 +1,7 @@
 export const toolcraftCanvasZoomMin = 25;
 export const toolcraftCanvasZoomMax = 400;
 export const toolcraftCanvasZoomStep = 10;
-export const toolcraftCanvasZoomDefault = 70;
+export const toolcraftCanvasZoomDefault = 100;
 
 export function clampToolcraftCanvasZoom(zoom: number): number {
   return Math.min(toolcraftCanvasZoomMax, Math.max(toolcraftCanvasZoomMin, zoom));

package/templates/runtime/state/create-template-state.test.ts

@@ -55,13 +55,13 @@ describe("createToolcraftState", () => {
 
     expect(state.values).toMatchObject({
       "canvas.aspectRatio": {
-        height: 1,
+        height: 9,
         mode: "preset",
-        value: "1:1",
-        width: 1,
+        value: "16:9",
+        width: 16,
       },
-      "canvas.size.height": 1024,
-      "canvas.size.width": 1024,
+      "canvas.size.height": 1080,
+      "canvas.size.width": 1920,
     });
   });
 
@@ -75,7 +75,7 @@ describe("createToolcraftState", () => {
     const state = createToolcraftState(app);
 
     expect(state.canvas.size).toEqual(size);
-    expect(state.canvas.zoom).toBe(70);
+    expect(state.canvas.zoom).toBe(100);
   });
 
   it("preserves seeded canvas width", () => {

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

@@ -103,9 +103,15 @@ 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.canvas.size.height).toBe(768);
+    expect(changed.values["canvas.aspectRatio"]).toEqual({
+      height: 6,
+      mode: "custom",
+      value: "5:6",
+      width: 5,
+    });
     expect(changed.values["canvas.size.width"]).toBe(640);
-    expect(changed.values["canvas.size.height"]).toBe(410);
+    expect(changed.values["canvas.size.height"]).toBe(768);
     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);
@@ -115,7 +121,7 @@ describe("toolcraftReducer", () => {
     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);
+    expect(redone.canvas.size.height).toBe(768);
   });
 
   it("routes canvas aspect ratio presets through canvas runtime state", () => {
@@ -144,7 +150,7 @@ describe("toolcraftReducer", () => {
     expect(changed.history.undo.at(-1)?.label).toBe("canvas.aspectRatio");
   });
 
-  it("keeps canvas size edits locked to the current aspect ratio", () => {
+  it("turns manual canvas size edits into a custom aspect ratio", () => {
     const state = toolcraftReducer(createState(), {
       target: "canvas.aspectRatio",
       type: "controls.setValue",
@@ -162,9 +168,47 @@ describe("toolcraftReducer", () => {
       value: "720",
     });
 
-    expect(changed.canvas.size).toEqual({ height: 720, unit: "px", width: 1280 });
+    expect(changed.canvas.size).toEqual({ height: 720, unit: "px", width: 1920 });
+    expect(changed.values["canvas.aspectRatio"]).toEqual({
+      height: 3,
+      mode: "custom",
+      value: "8:3",
+      width: 8,
+    });
     expect(changed.values["canvas.size.height"]).toBe(720);
-    expect(changed.values["canvas.size.width"]).toBe(1280);
+    expect(changed.values["canvas.size.width"]).toBe(1920);
+  });
+
+  it("keeps repeated canvas size values as no-op without changing aspect ratio mode", () => {
+    const app = defineToolcraft({
+      canvas: {
+        enabled: true,
+        size: { height: 1080, unit: "px", width: 1920 },
+        sizing: { mode: "editable-output" },
+      },
+      panels: {
+        controls: {
+          sections: [],
+          title: "Controls",
+        },
+      },
+    });
+    const state = createToolcraftState(app);
+
+    const unchanged = toolcraftReducer(state, {
+      target: "canvas.size.width",
+      type: "controls.setValue",
+      value: "1920",
+    });
+
+    expect(unchanged).toBe(state);
+    expect(unchanged.values["canvas.aspectRatio"]).toEqual({
+      height: 9,
+      mode: "preset",
+      value: "16:9",
+      width: 16,
+    });
+    expect(unchanged.history.undo).toEqual([]);
   });
 
   it("updates canvas offset without recording history", () => {
@@ -225,11 +269,11 @@ describe("toolcraftReducer", () => {
     state = toolcraftReducer(state, { type: "canvas.zoomOut" });
     state = toolcraftReducer(state, { type: "canvas.zoomIn" });
 
-    expect(state.canvas.zoom).toBe(60);
+    expect(state.canvas.zoom).toBe(90);
 
     state = toolcraftReducer(state, { type: "canvas.zoomReset" });
 
-    expect(state.canvas.zoom).toBe(70);
+    expect(state.canvas.zoom).toBe(100);
   });
 
   it("sets viewport zoom and offset for gesture zoom", () => {
@@ -380,6 +424,40 @@ describe("toolcraftReducer", () => {
     });
   });
 
+  it("appends single-layer media when import is explicitly non-replacing", () => {
+    const state = createState();
+    const first = toolcraftReducer(state, {
+      asset: {
+        dataUrl: "data:image/png;base64,first",
+        fileName: "first.png",
+        mimeType: "image/png",
+        position: { x: 0, y: 0 },
+        size: state.canvas.size,
+      },
+      replaceExisting: false,
+      type: "media.import",
+    });
+    const second = toolcraftReducer(first, {
+      asset: {
+        dataUrl: "data:image/png;base64,second",
+        fileName: "second.png",
+        mimeType: "image/png",
+        position: { x: 0, y: 0 },
+        size: state.canvas.size,
+      },
+      replaceExisting: false,
+      type: "media.import",
+    });
+
+    expect(second.layers.map((layer) => layer.id)).toEqual(["layer-1", "layer-2"]);
+    expect(second.mediaAssets.map((asset) => asset.id)).toEqual(["media-1", "media-2"]);
+    expect(second.mediaAssets.map((asset) => asset.fileName)).toEqual([
+      "first.png",
+      "second.png",
+    ]);
+    expect(second.selectedLayerId).toBe("layer-2");
+  });
+
   it("adds and selects runtime layers and groups", () => {
     const withGroup = toolcraftReducer(createState(), {
       layer: {

package/templates/runtime/state/reducer.ts

@@ -133,6 +133,22 @@ function normalizeCanvasAspectRatioValue(
   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,
@@ -567,7 +583,7 @@ export function toolcraftReducer(
         if (
           state.canvas.size.width === size.width &&
           state.canvas.size.height === size.height &&
-          Object.is(state.values[command.target], ratio)
+          canvasAspectRatioValuesEqual(state.values[command.target], ratio)
         ) {
           return state;
         }
@@ -599,44 +615,42 @@ export function toolcraftReducer(
           return state;
         }
 
-        const hasAspectRatioLock =
+        const hasAspectRatioControl =
           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 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;
 
-        if (
+        const sizeUnchanged =
           state.canvas.size.width === size.width &&
           state.canvas.size.height === size.height &&
           state.values[command.target] === targetValue &&
-          state.values[otherTarget] === otherValue
-        ) {
+          state.values[otherTarget] === otherValue;
+
+        if (sizeUnchanged) {
           return state;
         }
 
         return commitStatePatch(state, {
           after: {
+            ...(hasAspectRatioControl
+              ? { [canvasAspectRatioTarget]: aspectRatio }
+              : {}),
             "canvas.size": size,
             [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],
@@ -1014,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,7 +23,7 @@ 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 `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.
+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.
@@ -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.
 

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