@pixel-point/toolcraft 0.0.3 → 0.0.6

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

@@ -1,4 +1,8 @@
 import { TOOLCRAFT_COMPONENT_CONTRACTS } from "../contracts/component-contracts";
+import {
+  getToolcraftCanvasAspectRatioPreset,
+  getToolcraftCanvasAspectRatioPresetBySize,
+} from "./canvas-aspect-ratio-presets";
 import type {
   ToolcraftAssemblyCapability,
   ToolcraftAssemblyCommand,
@@ -22,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"];
@@ -41,6 +45,15 @@ const canvasSizeControlTargets = {
   height: "canvas.size.height",
   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";
@@ -185,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 {
@@ -259,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");
@@ -553,6 +618,7 @@ function isRuntimeOnlyActionControl(control: ToolcraftControlSchema): boolean {
 function isSettingsTransferEligibilityControl(control: ToolcraftControlSchema): boolean {
   return (
     !isRuntimeOnlyActionControl(control) &&
+    control.target !== canvasAspectRatioTarget &&
     control.target !== canvasSizeControlTargets.width &&
     control.target !== canvasSizeControlTargets.height
   );
@@ -699,25 +765,83 @@ function getCanvasSizeLayoutGroups(
     : undefined;
 }
 
+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 getCanvasAspectRatioDefaultValue(size: ToolcraftCanvasSize): {
+  height: number;
+  mode: "custom" | "preset";
+  value: string;
+  width: number;
+} {
+  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}`;
+  const preset =
+    getToolcraftCanvasAspectRatioPreset(value) ??
+    getToolcraftCanvasAspectRatioPresetBySize(size);
+
+  return {
+    height: preset?.ratioHeight ?? height,
+    mode: preset ? "preset" : "custom",
+    value: preset?.value ?? value,
+    width: preset?.ratioWidth ?? width,
+  };
+}
+
 function createCanvasSizeSection({
+  aspectRatioControl,
+  renderScaleControl,
   sizeControlIds,
   sizeControls,
 }: {
+  aspectRatioControl: ToolcraftControlSchema;
+  renderScaleControl?: ToolcraftControlSchema;
   sizeControlIds: readonly string[];
   sizeControls: ToolcraftControlSectionSchema["controls"];
 }): ToolcraftControlSectionSchema {
   return {
-    controls: sizeControls,
+    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"];
@@ -728,7 +852,9 @@ function mergeCanvasSizeControlsIntoSettingsTransferSection({
     ...settingsTransferSection,
     controls: {
       ...settingsTransferSection.controls,
+      canvasAspectRatio: aspectRatioControl,
       ...sizeControls,
+      ...(renderScaleControl ? { canvasRenderScale: renderScaleControl } : {}),
     },
     layoutGroups:
       canvasSizeLayoutGroups.length > 0 || settingsTransferSection.layoutGroups?.length
@@ -740,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";
 }
@@ -1259,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,
         ],
       }),
@@ -1275,6 +1449,14 @@ function normalizePanels({
 
   const sizeControls: ToolcraftControlSectionSchema["controls"] = {};
   const sizeControlIds: string[] = [];
+  const aspectRatioControl: ToolcraftControlSchema = {
+    defaultValue: getCanvasAspectRatioDefaultValue(canvas.size),
+    label: "Aspect ratio",
+    performanceReason: "Aspect ratio changes output dimensions and renderer workload.",
+    performanceRole: "workload",
+    target: canvasAspectRatioTarget,
+    type: "aspectRatio",
+  };
 
   if (!hasControlTarget(panels, canvasSizeControlTargets.width)) {
     sizeControls.canvasWidth = {
@@ -1300,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({
@@ -1315,11 +1497,18 @@ function normalizePanels({
 
   const runtimeSettingsSection = settingsTransferSection
     ? mergeCanvasSizeControlsIntoSettingsTransferSection({
+        aspectRatioControl,
+        renderScaleControl,
         settingsTransferSection,
         sizeControlIds,
         sizeControls,
       })
-    : createCanvasSizeSection({ sizeControlIds, sizeControls });
+    : createCanvasSizeSection({
+        aspectRatioControl,
+        renderScaleControl,
+        sizeControlIds,
+        sizeControls,
+      });
 
   return {
     ...normalizedPanels,
@@ -1395,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({
@@ -1406,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/keyframe-capability.test.ts

@@ -51,6 +51,13 @@ describe("getToolcraftControlKeyframeCapability", () => {
   });
 
   it("blocks runtime-owned canvas size targets even when the visual type could otherwise animate", () => {
+    expect(
+      getToolcraftControlKeyframeCapability(control("slider", "canvas.aspectRatio")),
+    ).toEqual({
+      capable: false,
+      reason: "runtime-owned-target",
+    });
+
     expect(
       getToolcraftControlKeyframeCapability(control("text", "canvas.size.width")),
     ).toEqual({

package/templates/runtime/schema/keyframe-capability.ts

@@ -1,4 +1,4 @@
-import { getToolcraftCanvasSizeTargetDimension } from "./runtime-targets";
+import { isToolcraftRuntimeOwnedTarget } from "./runtime-targets";
 import type { ToolcraftControlSchema } from "./types";
 
 export type ToolcraftControlKeyframeCapabilityReason =
@@ -30,7 +30,7 @@ const keyframeCapableControlTypes = new Set([
 export function getToolcraftControlKeyframeCapability(
   control: ToolcraftControlSchema,
 ): ToolcraftControlKeyframeCapability {
-  if (getToolcraftCanvasSizeTargetDimension(control.target)) {
+  if (isToolcraftRuntimeOwnedTarget(control.target)) {
     return {
       capable: false,
       reason: "runtime-owned-target",

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

@@ -1,4 +1,6 @@
 export const toolcraftRuntimeOwnedTargets = [
+  "canvas.aspectRatio",
+  "canvas.renderScale",
   "canvas.size.width",
   "canvas.size.height",
 ] as const;
@@ -27,6 +29,10 @@ export function getToolcraftCanvasSizeTargetDimension(
   }
 }
 
+export function isToolcraftCanvasAspectRatioTarget(target: string): boolean {
+  return target === "canvas.aspectRatio";
+}
+
 export function isToolcraftReservedTarget(
   target: string,
 ): target is ToolcraftReservedTarget {

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

@@ -54,8 +54,14 @@ describe("createToolcraftState", () => {
     const state = createToolcraftState(app);
 
     expect(state.values).toMatchObject({
-      "canvas.size.height": 1024,
-      "canvas.size.width": 1024,
+      "canvas.aspectRatio": {
+        height: 9,
+        mode: "preset",
+        value: "16:9",
+        width: 16,
+      },
+      "canvas.size.height": 1080,
+      "canvas.size.width": 1920,
     });
   });
 
@@ -69,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,13 +103,112 @@ describe("toolcraftReducer", () => {
     const redone = toolcraftReducer(undone, { type: "history.redo" });
 
     expect(changed.canvas.size.width).toBe(640);
+    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(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);
     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(768);
+  });
+
+  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("turns manual canvas size edits into a custom 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: 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(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", () => {
@@ -170,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", () => {
@@ -325,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: {