@pixel-point/toolcraft 0.0.16 → 0.0.17

package/templates/runtime/react/controls-panel/__tests__/controls-panel.scene-export-actions.test.tsx

@@ -39,83 +39,6 @@ function createExportSchema(
 }
 
 describe("ControlsPanel scene export actions", () => {
-  it("skips product bounds for finite export and calls them once for infinite export", () => {
-    const schema = createExportSchema();
-    const provider = vi.fn(() => [
-      { height: 10, width: 10, x: 100, y: 50 },
-    ]);
-    let finiteFrame: unknown;
-    const finite = renderControlsPanelWithSchema(schema, {
-      onPanelAction: ({ resolveSceneExportFrame }) => {
-        finiteFrame = resolveSceneExportFrame();
-      },
-      sceneExport: {
-        boundsProvider: provider,
-        boundsRequired: true,
-        visibility: defaultToolcraftRuntimeSceneVisibility,
-      },
-    });
-
-    fireEvent.click(screen.getByRole("button", { name: "Export PNG" }));
-    expect(finiteFrame).toEqual({
-      frame: { height: 180, width: 320, x: 0, y: 0 },
-      ok: true,
-    });
-    expect(provider).not.toHaveBeenCalled();
-    finite.unmount();
-
-    let infiniteFrame: unknown;
-    renderControlsPanelWithSchema(
-      schema,
-      {
-        onPanelAction: ({ resolveSceneExportFrame }) => {
-          infiniteFrame = resolveSceneExportFrame({
-            timeRange: { endSeconds: 8, startSeconds: 0 },
-          });
-        },
-        sceneExport: {
-          boundsProvider: provider,
-          boundsRequired: true,
-          visibility: defaultToolcraftRuntimeSceneVisibility,
-        },
-      },
-      {
-        canvas: { mode: "infinite" },
-        layers: [
-          {
-            displayName: "Image",
-            id: "image-layer",
-            kind: "layer",
-            name: "image",
-            visible: true,
-          },
-        ],
-        mediaAssets: [
-          {
-            assetKind: "image",
-            dataUrl: "data:image/png;base64,test",
-            fileName: "image.png",
-            id: "image",
-            layerId: "image-layer",
-            mimeType: "image/png",
-            position: { x: 0, y: 0 },
-            size: { height: 20, unit: "px", width: 20 },
-          },
-        ],
-      },
-    );
-
-    fireEvent.click(screen.getByRole("button", { name: "Export PNG" }));
-    expect(provider).toHaveBeenCalledTimes(1);
-    expect(provider).toHaveBeenCalledWith(
-      expect.objectContaining({ timeRange: { endSeconds: 8, startSeconds: 0 } }),
-    );
-    expect(infiniteFrame).toEqual({
-      frame: { height: 70, width: 120, x: -10, y: -10 },
-      ok: true,
-    });
-  });
-
   it("shows only feedback reported by the latest panel action", async () => {
     const schema = createExportSchema([
       { label: "First export", value: "first", variant: "secondary" },
@@ -143,17 +66,27 @@ describe("ControlsPanel scene export actions", () => {
   });
 
   it("presents a missing required bounds provider as typed visible feedback", async () => {
+    const onPanelAction = vi.fn();
     renderControlsPanelWithSchema(
-      createExportSchema(),
-      {
-        onPanelAction: ({ reportFeedback, resolveSceneExportFrame }) => {
-          const result = resolveSceneExportFrame();
-          if (!result.ok) reportFeedback(result);
+      createExportSchema([
+        {
+          command: "controls.apply",
+          label: "Export PNG",
+          role: "export-image",
+          value: "export",
+          variant: "default",
         },
+      ]),
+      {
         sceneExport: {
-          boundsRequired: true,
+          exportRenderer: {
+            baseFileName: "scene",
+            renderFrame: vi.fn(),
+          },
+          productSceneRequired: true,
           visibility: defaultToolcraftRuntimeSceneVisibility,
         },
+        onPanelAction,
       },
       { canvas: { mode: "infinite" } },
     );
@@ -164,6 +97,7 @@ describe("ControlsPanel scene export actions", () => {
       "scene-bounds-unavailable",
     );
     expect(alert.textContent).toContain("does not provide export bounds");
+    expect(onPanelAction).not.toHaveBeenCalled();
   });
 
   it("presents rejected typed export failures as visible feedback", async () => {

package/templates/runtime/react/controls-panel/actions/controls-panel-actions.ts

@@ -3,18 +3,11 @@
 import * as React from "react";
 
 import {
-  resolveToolcraftExportFrame,
+  ToolcraftArtifactExportError,
   ToolcraftSceneExportError,
-  type ToolcraftExportFrame,
-  type ToolcraftExportFrameResult,
 } from "../../../export";
 import type { ToolcraftRendererPipelineClient } from "../../../rendering";
-import {
-  defaultToolcraftRuntimeSceneVisibility,
-  resolveToolcraftSceneBounds,
-  type ToolcraftProductSceneBoundsProvider,
-  type ToolcraftRuntimeSceneVisibility,
-} from "../../../scene";
+import { defaultToolcraftRuntimeSceneVisibility } from "../../../scene";
 import type {
   ToolcraftActionCommand,
   ToolcraftActionSchema,
@@ -25,46 +18,31 @@ import type {
 } from "../../../state/types";
 import { getToolcraftCanvasFrame } from "../../../state/canvas-frame";
 import type { ActionControlRunAction } from "../renderers/controls-panel-action-renderer";
-import {
-  renderToolcraftRuntimeSceneToCanvas,
-  type ToolcraftRuntimeSceneExportResult,
-} from "../../canvas/runtime-scene-export";
+import { renderToolcraftRuntimeSceneToCanvas } from "../../canvas/runtime-scene-export";
 import { useToolcraftPipeline } from "../../app-shell/use-toolcraft-pipeline";
 import { useToolcraftSourceAssetCoordinator } from "../../app-shell/toolcraft-source-asset-context";
-import {
-  renderToolcraftModelsToCanvas,
-  type ToolcraftRenderModelsToCanvas,
-} from "../../model-rendering/model-export";
 import { useOptionalToolcraftModelRenderHost } from "../../model-rendering/model-render-provider";
+import {
+  runToolcraftExportAction,
+  type ToolcraftControlsSceneExport,
+} from "./export-action-runner";
+
+export type { ToolcraftControlsSceneExport } from "./export-action-runner";
 
 export type ToolcraftPanelActionFeedback = Readonly<{
   code: string;
   message: string;
 }>;
 
-export type ToolcraftControlsSceneExport = Readonly<{
-  boundsProvider?: ToolcraftProductSceneBoundsProvider;
-  boundsRequired: boolean;
-  visibility: ToolcraftRuntimeSceneVisibility;
-}>;
-
 export type ToolcraftPanelActionContext = {
   action: ToolcraftActionSchema;
   dispatch: React.Dispatch<ToolcraftCommand>;
-  renderRuntimeSceneToCanvas: (
-    canvas: HTMLCanvasElement,
-    frame: ToolcraftExportFrame,
-  ) => Promise<ToolcraftRuntimeSceneExportResult>;
   reportProgress: (progress: number) => void;
   reportFeedback: (feedback: ToolcraftPanelActionFeedback) => void;
-  renderModelsToCanvas: ToolcraftRenderModelsToCanvas;
   resolveMediaResource: (
     resourceRef: string,
     options: Readonly<{ signal: AbortSignal }>,
   ) => Promise<Uint8Array | null>;
-  resolveSceneExportFrame: (options?: Readonly<{
-    timeRange?: Readonly<{ endSeconds: number; startSeconds: number }>;
-  }>) => ToolcraftExportFrameResult;
   rendererPipeline?: ToolcraftRendererPipelineClient | null;
   state: ToolcraftState;
 };
@@ -90,42 +68,10 @@ function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
 function noopReportProgress(): void {}
 
 const defaultSceneExport: ToolcraftControlsSceneExport = Object.freeze({
-  boundsRequired: false,
+  productSceneRequired: false,
   visibility: defaultToolcraftRuntimeSceneVisibility,
 });
 
-function unavailableProductBounds(message: string): ToolcraftExportFrameResult {
-  return { code: "scene-bounds-unavailable", message, ok: false };
-}
-
-function resolveActionSceneExportFrame(
-  sceneExport: ToolcraftControlsSceneExport,
-  state: ToolcraftState,
-  timeRange?: Readonly<{ endSeconds: number; startSeconds: number }>,
-): ToolcraftExportFrameResult {
-  const finiteFrame = resolveToolcraftExportFrame(state, null);
-  if (finiteFrame.ok) return finiteFrame;
-
-  if (sceneExport.boundsRequired && !sceneExport.boundsProvider) {
-    return unavailableProductBounds(
-      "This infinite product scene does not provide export bounds.",
-    );
-  }
-
-  let productRects: unknown = [];
-  try {
-    productRects = sceneExport.boundsProvider?.({ state, timeRange }) ?? [];
-  } catch {
-    return unavailableProductBounds("Product scene bounds could not be resolved.");
-  }
-  const bounds = resolveToolcraftSceneBounds(
-    state,
-    productRects,
-    sceneExport.visibility,
-  );
-  return resolveToolcraftExportFrame(state, bounds);
-}
-
 function clampFooterActionProgress(progress: number): number {
   if (!Number.isFinite(progress)) {
     return 0;
@@ -228,7 +174,10 @@ export function useControlsPanelActions({
 
       void Promise.resolve(result)
         .catch((error: unknown) => {
-          if (error instanceof ToolcraftSceneExportError) {
+          if (
+            error instanceof ToolcraftSceneExportError ||
+            error instanceof ToolcraftArtifactExportError
+          ) {
             reportFeedback(error.feedback);
           } else {
             console.error("Toolcraft panel action failed.", error);
@@ -257,7 +206,11 @@ export function useControlsPanelActions({
         setPanelActionFeedback(feedback);
       }
     };
-    const command = action.command ?? (onPanelAction ? null : getActionCommand(action));
+    const runtimeOwnsExport =
+      action.role === "export-image" || action.role === "export-video";
+    const command = runtimeOwnsExport
+      ? null
+      : action.command ?? (onPanelAction ? null : getActionCommand(action));
 
     if (command) {
       dispatch({ type: command });
@@ -270,36 +223,41 @@ export function useControlsPanelActions({
     const actionState = getState();
     let result: PromiseLike<unknown> | void;
     try {
-      result = onPanelAction?.({
+      const reportProgress =
+        footerActionProgressTracker?.reportProgress ?? noopReportProgress;
+      const exportResult = runToolcraftExportAction({
         action,
-        dispatch,
-        renderRuntimeSceneToCanvas: (canvas, frame) =>
+        renderRuntimeScene: (canvas, frame, state) =>
           renderToolcraftRuntimeSceneToCanvas({
             canvas,
-            canvasFrame: getToolcraftCanvasFrame(actionState.canvas),
+            canvasFrame: getToolcraftCanvasFrame(state.canvas),
             exportFrame: frame,
             host: modelRenderHost,
             resolveImageResource: sourceAssetCoordinator.resolveResource,
-            state: actionState,
+            state,
             visibility: sceneExport.visibility,
           }),
-        reportFeedback,
-        reportProgress:
-          footerActionProgressTracker?.reportProgress ?? noopReportProgress,
-        renderModelsToCanvas: (canvas) =>
-          renderToolcraftModelsToCanvas(modelRenderHost, actionState, canvas),
-        resolveMediaResource,
-        resolveSceneExportFrame: (resolveOptions) =>
-          resolveActionSceneExportFrame(
-            sceneExport,
-            actionState,
-            resolveOptions?.timeRange,
-          ),
         rendererPipeline,
+        reportProgress,
+        sceneExport,
         state: actionState,
       });
+      result =
+        exportResult ??
+        onPanelAction?.({
+          action,
+          dispatch,
+          reportFeedback,
+          reportProgress,
+          resolveMediaResource,
+          rendererPipeline,
+          state: actionState,
+        });
     } catch (error) {
-      if (error instanceof ToolcraftSceneExportError) {
+      if (
+        error instanceof ToolcraftSceneExportError ||
+        error instanceof ToolcraftArtifactExportError
+      ) {
         reportFeedback(error.feedback);
         result = undefined;
       } else {

package/templates/runtime/react/controls-panel/actions/export-action-runner.ts

@@ -0,0 +1,62 @@
+import {
+  exportToolcraftImageArtifact,
+  exportToolcraftVideoArtifact,
+  type ToolcraftArtifactExportRequest,
+  type ToolcraftExportFrame,
+  type ToolcraftProductExportRenderer,
+} from "../../../export";
+import type { ToolcraftRendererPipelineClient } from "../../../rendering";
+import type {
+  ToolcraftProductSceneBoundsProvider,
+  ToolcraftRuntimeSceneVisibility,
+} from "../../../scene";
+import type { ToolcraftActionSchema } from "../../../schema/types";
+import type { ToolcraftState } from "../../../state/types";
+
+export type ToolcraftControlsSceneExport = Readonly<{
+  boundsProvider?: ToolcraftProductSceneBoundsProvider;
+  exportRenderer?: ToolcraftProductExportRenderer;
+  productSceneRequired: boolean;
+  visibility: ToolcraftRuntimeSceneVisibility;
+}>;
+
+export type ToolcraftExportActionRequest = Readonly<{
+  action: ToolcraftActionSchema;
+  renderRuntimeScene: (
+    canvas: HTMLCanvasElement,
+    frame: ToolcraftExportFrame,
+    state: ToolcraftState,
+  ) => Promise<unknown>;
+  rendererPipeline: ToolcraftRendererPipelineClient | null;
+  reportProgress: (progress: number) => void;
+  sceneExport: ToolcraftControlsSceneExport;
+  state: ToolcraftState;
+}>;
+
+function createSharedArtifactRequest(
+  request: ToolcraftExportActionRequest,
+): ToolcraftArtifactExportRequest {
+  return {
+    boundsProvider: request.sceneExport.boundsProvider,
+    exportRenderer: request.sceneExport.exportRenderer,
+    productSceneRequired: request.sceneExport.productSceneRequired,
+    renderRuntimeScene: request.renderRuntimeScene,
+    rendererPipeline: request.rendererPipeline,
+    reportProgress: request.reportProgress,
+    state: request.state,
+    visibility: request.sceneExport.visibility,
+  };
+}
+
+export function runToolcraftExportAction(
+  request: ToolcraftExportActionRequest,
+): PromiseLike<unknown> | null {
+  switch (request.action.role) {
+    case "export-image":
+      return exportToolcraftImageArtifact(createSharedArtifactRequest(request));
+    case "export-video":
+      return exportToolcraftVideoArtifact(createSharedArtifactRequest(request));
+    default:
+      return null;
+  }
+}

package/templates/runtime/react/panel-host/panel-host-runtime-placement.test.tsx

@@ -195,4 +195,34 @@ describe("ToolcraftPanelHost runtime placement", () => {
       );
     });
   });
+
+  it("keeps the CSS-anchored default placement during viewport resize", async () => {
+    const { container } = renderToolbar();
+    const host = container.querySelector<HTMLElement>(
+      "[data-slot='toolcraft-runtime-panel-host']",
+    );
+
+    if (!host) {
+      throw new Error("Expected the toolbar panel host to render.");
+    }
+    vi.spyOn(host, "getBoundingClientRect").mockReturnValue({
+      bottom: 900,
+      height: 100,
+      left: 1_500,
+      right: 1_700,
+      top: 800,
+      width: 200,
+      x: 1_500,
+      y: 800,
+      toJSON: () => ({}),
+    });
+
+    fireEvent(window, new Event("resize"));
+
+    await waitFor(() => {
+      expect(screen.getByTestId("toolbar-placement").textContent).toBe(
+        "0,0,free",
+      );
+    });
+  });
 });

package/templates/runtime/react/panel-host/panel-host.tsx

@@ -191,6 +191,10 @@ function usePanelSnapControls({
         return;
       }
 
+      if (x.get() === 0 && y.get() === 0 && snapEdge === undefined) {
+        return;
+      }
+
       const currentPlacement = {
         offset: { x: x.get(), y: y.get() },
         ...(snapEdge ? { snapEdge } : {}),

package/templates/runtime/scene/scene-bounds.ts

@@ -36,8 +36,7 @@ export function createToolcraftRuntimeSceneVisibility(
 
 export type ToolcraftProductSceneBoundsProvider = (
   context: Readonly<{
-    state: ToolcraftState;
-    timeRange?: Readonly<{ endSeconds: number; startSeconds: number }>;
+    state: Readonly<ToolcraftState>;
   }>,
 ) => readonly ToolcraftSceneRect[];
 

package/templates/runtime/schema/canvas-render-scale.ts

@@ -0,0 +1,62 @@
+import type {
+  ResolvedToolcraftCanvasRenderScaleSchema,
+  ToolcraftCanvasRenderScaleSchema,
+} from "./types";
+
+export const TOOLCRAFT_CANVAS_RENDER_SCALE = Object.freeze({
+  defaultValue: 2,
+  max: 2,
+  min: 1,
+  step: 0.25,
+});
+
+const minimumCanvasRenderScaleStep = 0.01;
+const canvasRenderScaleStepTolerance = 1e-9;
+
+function resolveCanvasRenderScaleStep(value: number | undefined): number {
+  if (value === undefined) {
+    return TOOLCRAFT_CANVAS_RENDER_SCALE.step;
+  }
+
+  const maximumCanvasRenderScaleStep =
+    TOOLCRAFT_CANVAS_RENDER_SCALE.max - TOOLCRAFT_CANVAS_RENDER_SCALE.min;
+
+  if (
+    typeof value !== "number" ||
+    !Number.isFinite(value) ||
+    value < minimumCanvasRenderScaleStep ||
+    value > maximumCanvasRenderScaleStep
+  ) {
+    throw new Error(
+      "Canvas render scale step must be a finite value between 0.01 and 1.",
+    );
+  }
+
+  const stepCount = maximumCanvasRenderScaleStep / value;
+
+  if (Math.abs(stepCount - Math.round(stepCount)) > canvasRenderScaleStepTolerance) {
+    throw new Error("Canvas render scale step must divide the canonical range exactly.");
+  }
+
+  return value;
+}
+
+export function resolveToolcraftCanvasRenderScale(
+  renderScale: ToolcraftCanvasRenderScaleSchema | undefined,
+): ResolvedToolcraftCanvasRenderScaleSchema {
+  if (!renderScale) {
+    return {
+      ...TOOLCRAFT_CANVAS_RENDER_SCALE,
+      enabled: false,
+    };
+  }
+
+  return {
+    ...TOOLCRAFT_CANVAS_RENDER_SCALE,
+    enabled: true,
+    step:
+      renderScale === true
+        ? TOOLCRAFT_CANVAS_RENDER_SCALE.step
+        : resolveCanvasRenderScaleStep(renderScale.step),
+  };
+}

package/templates/runtime/schema/controls-panel-section-id.test.ts

@@ -140,7 +140,7 @@ describe("Toolcraft control section identity", () => {
       )?.id,
     ).toBe(legacyId);
     expect(
-      defineToolcraft(resolved as ToolcraftAppSchema).panels.controls?.sections.find(
+      defineToolcraft(resolved as unknown as ToolcraftAppSchema).panels.controls?.sections.find(
         (section) => section.id.startsWith("legacy."),
       )?.id,
     ).toBe(legacyId);

package/templates/runtime/schema/controls-panel-section-roundtrip.test.ts

@@ -38,7 +38,7 @@ describe("Toolcraft control section identity roundtrips", () => {
         },
       },
     });
-    const roundTripped = defineToolcraft(resolved as ToolcraftAppSchema);
+    const roundTripped = defineToolcraft(resolved as unknown as ToolcraftAppSchema);
     const resolvedIds = resolved.panels.controls?.sections.map((section) => section.id);
     const roundTrippedIds = roundTripped.panels.controls?.sections.map(
       (section) => section.id,
@@ -101,7 +101,7 @@ describe("Toolcraft control section identity roundtrips", () => {
     const productIds = resolved.panels.controls?.sections
       .map((section) => section.id)
       .filter((id) => !id.startsWith("runtime."));
-    const roundTripped = defineToolcraft(resolved as ToolcraftAppSchema);
+    const roundTripped = defineToolcraft(resolved as unknown as ToolcraftAppSchema);
     const roundTrippedProductIds = roundTripped.panels.controls?.sections
       .map((section) => section.id)
       .filter((id) => !id.startsWith("runtime."));
@@ -147,7 +147,7 @@ describe("Toolcraft control section identity roundtrips", () => {
       productIds?.every((id) => (id.match(/\.part-/gu) ?? []).length === 2),
     ).toBe(true);
 
-    const roundTripped = defineToolcraft(resolved as ToolcraftAppSchema);
+    const roundTripped = defineToolcraft(resolved as unknown as ToolcraftAppSchema);
     const roundTrippedProductIds = roundTripped.panels.controls?.sections
       .map((section) => section.id)
       .filter((id) => !id.startsWith("runtime."));

package/templates/runtime/schema/define-toolcraft.setup-background.test.ts

@@ -118,7 +118,7 @@ describe("defineToolcraft runtime setup background controls", () => {
 
   it("keeps the normalized background pair when a resolved schema is defined again", () => {
     const first = defineToolcraft(createBackgroundSchema());
-    const second = defineToolcraft(first);
+    const second = defineToolcraft(first as unknown as ToolcraftAppSchema);
     const setupSection = second.panels.controls?.sections[0];
 
     expect(second.panels.controls?.sections.map((section) => section.title)).toEqual([

package/templates/runtime/schema/define-toolcraft.setup-render-scale-timeline.test.ts

@@ -1,6 +1,40 @@
 import { describe, expect, it } from "vitest";
 
 import { defineToolcraft } from "./define-toolcraft";
+import type { ToolcraftCanvasRenderScaleSchema } from "./types";
+
+const authoredRenderScaleStep: ToolcraftCanvasRenderScaleSchema = { step: 0.5 };
+const authoredRenderScaleDefaultValue = { defaultValue: 1, step: 0.5 };
+const authoredRenderScaleEnabled = { enabled: true, step: 0.5 };
+const authoredRenderScaleMax = { max: 1, step: 0.5 };
+const authoredRenderScaleMin = { min: 1, step: 0.5 };
+
+// @ts-expect-error Authored render scale cannot select its resolved default value.
+const authoredRenderScaleDefaultValueAssignment: ToolcraftCanvasRenderScaleSchema =
+  authoredRenderScaleDefaultValue;
+
+// @ts-expect-error Authored render scale is always enabled when provided.
+const authoredRenderScaleEnabledAssignment: ToolcraftCanvasRenderScaleSchema = {
+  ...authoredRenderScaleEnabled,
+};
+
+// @ts-expect-error Authored render scale cannot change the canonical maximum.
+const authoredRenderScaleMaxAssignment: ToolcraftCanvasRenderScaleSchema = authoredRenderScaleMax;
+
+// @ts-expect-error Authored render scale cannot change the canonical minimum.
+const authoredRenderScaleMinAssignment: ToolcraftCanvasRenderScaleSchema = {
+  ...authoredRenderScaleMin,
+};
+
+void authoredRenderScaleStep;
+void authoredRenderScaleDefaultValue;
+void authoredRenderScaleEnabled;
+void authoredRenderScaleMax;
+void authoredRenderScaleMin;
+void authoredRenderScaleDefaultValueAssignment;
+void authoredRenderScaleEnabledAssignment;
+void authoredRenderScaleMaxAssignment;
+void authoredRenderScaleMinAssignment;
 
 describe("defineToolcraft runtime setup render scale and timeline controls", () => {
   it("appends raster render scale to the technical setup controls when enabled", () => {
@@ -95,11 +129,11 @@ describe("defineToolcraft runtime setup render scale and timeline controls", ()
     ]);
   });
 
-  it("keeps timeline standalone with render scale for fixed output sizing", () => {
+  it("uses the canonical authored raster scale with a custom step", () => {
     const app = defineToolcraft({
       canvas: {
         enabled: true,
-        renderScale: { defaultValue: 1.5 },
+        renderScale: { step: 0.5 },
         size: { height: 900, unit: "px", width: 1440 },
         sizing: { mode: "fixed-output" },
       },
@@ -120,10 +154,20 @@ describe("defineToolcraft runtime setup render scale and timeline controls", ()
       "timelineExtended",
     ]);
     expect(setupSection?.controls.canvasRenderScale).toMatchObject({
-      defaultValue: 1.5,
+      defaultValue: 2,
+      max: 2,
+      min: 1,
+      step: 0.5,
       target: "canvas.renderScale",
       type: "slider",
     });
+    expect(app.canvas.renderScale).toEqual({
+      defaultValue: 2,
+      enabled: true,
+      max: 2,
+      min: 1,
+      step: 0.5,
+    });
     expect(setupSection?.controls.timelineExtended).toMatchObject({
       defaultValue: false,
       label: "Timeline",
@@ -133,4 +177,28 @@ describe("defineToolcraft runtime setup render scale and timeline controls", ()
     expect(setupSection?.controls.timelineExtended).not.toHaveProperty("description");
     expect(setupSection?.layoutGroups ?? []).toEqual([]);
   });
+
+  it("rejects an authored step that cannot reach the canonical maximum", () => {
+    expect(() =>
+      defineToolcraft({
+        canvas: {
+          enabled: true,
+          renderScale: { step: 0.3 },
+        },
+        panels: {},
+      }),
+    ).toThrow("Canvas render scale step must divide the canonical range exactly.");
+  });
+
+  it.each([0, Number.NaN])("rejects invalid authored step %s", (step) => {
+    expect(() =>
+      defineToolcraft({
+        canvas: {
+          enabled: true,
+          renderScale: { step },
+        },
+        panels: {},
+      }),
+    ).toThrow("Canvas render scale step must be a finite value between 0.01 and 1.");
+  });
 });

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

@@ -1,12 +1,12 @@
 import { createToolcraftAssemblyContract } from "./assembly-contract";
 import { resolveToolcraftAppCapabilities } from "./app-capabilities";
 import { resolveToolcraftAppIdentity } from "./app-identity";
+import { resolveToolcraftCanvasRenderScale } from "./canvas-render-scale";
 import { normalizeToolcraftPanels } from "./panels-schema-normalization";
 import { resolveToolcraftPersistencePlan } from "./persistence-plan";
 import { resolveToolcraftSettingsTransfer } from "./runtime-setup-section";
 import {
   defaultToolcraftCanvasSize,
-  resolveToolcraftCanvasRenderScale,
   resolveToolcraftCanvasSizing,
   resolveToolcraftExport,
   resolveToolcraftMedia,