@pixel-point/toolcraft 0.0.16 → 0.0.18

package/templates/runtime/export/artifact-export-settings.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+
+import { defineToolcraft } from "../schema/define-toolcraft";
+import { createToolcraftState } from "../state/create-template-state";
+import {
+  resolveToolcraftImageExportSettings,
+  resolveToolcraftVideoExportSettings,
+  toolcraftImageExportFormatTarget,
+  toolcraftImageExportResolutionTarget,
+  toolcraftVideoExportFormatTarget,
+  toolcraftVideoExportResolutionTarget,
+} from "./artifact-export-settings";
+import { ToolcraftArtifactExportError } from "./export-error";
+
+function createState() {
+  return createToolcraftState(
+    defineToolcraft({ canvas: { enabled: true }, panels: {} }),
+  );
+}
+
+describe("artifact export settings", () => {
+  it("uses canonical defaults when controls are absent", () => {
+    const state = createState();
+
+    expect(resolveToolcraftImageExportSettings(state)).toEqual({
+      format: "png",
+      resolution: "4k",
+    });
+    expect(resolveToolcraftVideoExportSettings(state)).toEqual({
+      format: "mp4",
+      resolution: "current",
+    });
+  });
+
+  it("prefers current values over normalized defaults", () => {
+    const state = createState();
+    Object.assign(state.defaults, {
+      [toolcraftImageExportFormatTarget]: "png",
+      [toolcraftImageExportResolutionTarget]: "4k",
+      [toolcraftVideoExportFormatTarget]: "mp4",
+      [toolcraftVideoExportResolutionTarget]: "current",
+    });
+    Object.assign(state.values, {
+      [toolcraftImageExportFormatTarget]: "jpg",
+      [toolcraftImageExportResolutionTarget]: "8k",
+      [toolcraftVideoExportFormatTarget]: "webm",
+      [toolcraftVideoExportResolutionTarget]: "4k",
+    });
+
+    expect(resolveToolcraftImageExportSettings(state)).toEqual({
+      format: "jpg",
+      resolution: "8k",
+    });
+    expect(resolveToolcraftVideoExportSettings(state)).toEqual({
+      format: "webm",
+      resolution: "4k",
+    });
+  });
+
+  it("rejects unsupported present values with the exact target", () => {
+    const state = createState();
+    state.values[toolcraftVideoExportFormatTarget] = "mov";
+
+    try {
+      resolveToolcraftVideoExportSettings(state);
+      throw new Error("Expected invalid export setting.");
+    } catch (error) {
+      expect(error).toBeInstanceOf(ToolcraftArtifactExportError);
+      expect((error as ToolcraftArtifactExportError).feedback).toMatchObject({
+        code: "invalid-export-setting",
+        target: toolcraftVideoExportFormatTarget,
+      });
+    }
+  });
+});

package/templates/runtime/export/artifact-export-settings.ts

@@ -0,0 +1,96 @@
+import type { ToolcraftState } from "../state/types";
+import { ToolcraftArtifactExportError } from "./export-error";
+
+export const toolcraftImageExportFormatTarget = "export.image.format";
+export const toolcraftImageExportResolutionTarget = "export.image.resolution";
+export const toolcraftVideoExportFormatTarget = "export.video.format";
+export const toolcraftVideoExportResolutionTarget = "export.video.resolution";
+
+export type ToolcraftImageExportFormat = "jpg" | "png";
+export type ToolcraftImageExportPresetResolution = "2k" | "4k" | "8k";
+export type ToolcraftVideoExportFormat = "mp4" | "webm";
+export type ToolcraftVideoExportPresetResolution = "4k" | "current";
+
+export type ToolcraftResolvedImageExportSettings = Readonly<{
+  format: ToolcraftImageExportFormat;
+  resolution: ToolcraftImageExportPresetResolution;
+}>;
+
+export type ToolcraftResolvedVideoExportSettings = Readonly<{
+  format: ToolcraftVideoExportFormat;
+  resolution: ToolcraftVideoExportPresetResolution;
+}>;
+
+function getSettingValue(
+  state: ToolcraftState,
+  target: string,
+  fallback: string,
+): unknown {
+  return state.values[target] ?? state.defaults[target] ?? fallback;
+}
+
+function invalidSetting(target: string): never {
+  throw new ToolcraftArtifactExportError({
+    code: "invalid-export-setting",
+    message: `Toolcraft export setting ${target} is invalid.`,
+    target,
+  });
+}
+
+function resolveImageFormat(state: ToolcraftState): ToolcraftImageExportFormat {
+  const value = getSettingValue(state, toolcraftImageExportFormatTarget, "png");
+  return value === "jpg" || value === "png"
+    ? value
+    : invalidSetting(toolcraftImageExportFormatTarget);
+}
+
+function resolveImageResolution(
+  state: ToolcraftState,
+): ToolcraftImageExportPresetResolution {
+  const value = getSettingValue(
+    state,
+    toolcraftImageExportResolutionTarget,
+    "4k",
+  );
+  return value === "2k" || value === "4k" || value === "8k"
+    ? value
+    : invalidSetting(toolcraftImageExportResolutionTarget);
+}
+
+function resolveVideoFormat(state: ToolcraftState): ToolcraftVideoExportFormat {
+  const value = getSettingValue(state, toolcraftVideoExportFormatTarget, "mp4");
+  return value === "mp4" || value === "webm"
+    ? value
+    : invalidSetting(toolcraftVideoExportFormatTarget);
+}
+
+function resolveVideoResolution(
+  state: ToolcraftState,
+): ToolcraftVideoExportPresetResolution {
+  const value = getSettingValue(
+    state,
+    toolcraftVideoExportResolutionTarget,
+    "current",
+  );
+  return value === "4k" || value === "current"
+    ? value
+    : invalidSetting(toolcraftVideoExportResolutionTarget);
+}
+
+export function resolveToolcraftImageExportSettings(
+  state: ToolcraftState,
+): ToolcraftResolvedImageExportSettings {
+  return Object.freeze({
+    format: resolveImageFormat(state),
+    resolution: resolveImageResolution(state),
+  });
+}
+
+export function resolveToolcraftVideoExportSettings(
+  state: ToolcraftState,
+): ToolcraftResolvedVideoExportSettings {
+  return Object.freeze({
+    format: resolveVideoFormat(state),
+    resolution: resolveVideoResolution(state),
+  });
+}

package/templates/runtime/export/artifact-frame-renderer.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { defineToolcraft } from "../schema/define-toolcraft";
+import { createToolcraftState } from "../state/create-template-state";
+import { renderToolcraftArtifactFrame } from "./artifact-frame-renderer";
+
+function deferred() {
+  let resolve!: () => void;
+  const promise = new Promise<void>((done) => {
+    resolve = done;
+  });
+  return { promise, resolve };
+}
+
+function createContext(events: string[]) {
+  return {
+    clearRect: vi.fn(() => events.push("clear")),
+    fillRect: vi.fn(() => events.push("background")),
+    fillStyle: "",
+    restore: vi.fn(() => events.push("restore")),
+    save: vi.fn(() => events.push("save")),
+    scale: vi.fn(() => events.push("scale")),
+    setTransform: vi.fn(() => events.push("reset-transform")),
+    translate: vi.fn(() => events.push("translate")),
+  };
+}
+
+describe("renderToolcraftArtifactFrame", () => {
+  it("keeps the scene transform active until async product rendering settles", async () => {
+    const events: string[] = [];
+    const pending = deferred();
+    const context = createContext(events);
+    const canvas = {
+      getContext: vi.fn(() => context),
+      height: 200,
+      width: 400,
+    } as unknown as HTMLCanvasElement;
+    const state = createToolcraftState(
+      defineToolcraft({ canvas: { enabled: true }, panels: {} }),
+    );
+    const rendering = renderToolcraftArtifactFrame({
+      backgroundColor: "#123456",
+      canvas,
+      frame: { height: 100, width: 200, x: -10, y: -20 },
+      includeBackground: true,
+      pixelRatio: 2,
+      renderProductFrame: async () => {
+        events.push("product-start");
+        await pending.promise;
+        events.push("product-end");
+      },
+      renderRuntimeScene: async () => {
+        events.push("runtime-scene");
+      },
+      rendererPipeline: null,
+      state,
+    });
+
+    await Promise.resolve();
+    expect(events).toEqual([
+      "reset-transform",
+      "clear",
+      "background",
+      "runtime-scene",
+      "save",
+      "scale",
+      "translate",
+      "product-start",
+    ]);
+    pending.resolve();
+    await rendering;
+    expect(events.at(-2)).toBe("product-end");
+    expect(events.at(-1)).toBe("restore");
+  });
+
+  it("restores the context and types an unknown renderer failure", async () => {
+    const events: string[] = [];
+    const context = createContext(events);
+    const canvas = {
+      getContext: vi.fn(() => context),
+      height: 100,
+      width: 100,
+    } as unknown as HTMLCanvasElement;
+    const state = createToolcraftState(
+      defineToolcraft({ canvas: { enabled: true }, panels: {} }),
+    );
+
+    await expect(
+      renderToolcraftArtifactFrame({
+        backgroundColor: "#000000",
+        canvas,
+        frame: { height: 100, width: 100, x: 0, y: 0 },
+        includeBackground: false,
+        pixelRatio: 1,
+        renderProductFrame: () => {
+          throw new Error("broken product");
+        },
+        renderRuntimeScene: async () => undefined,
+        rendererPipeline: null,
+        state,
+      }),
+    ).rejects.toMatchObject({
+      feedback: { code: "product-frame-render-failed" },
+    });
+    expect(context.restore).toHaveBeenCalledOnce();
+  });
+});

package/templates/runtime/export/artifact-frame-renderer.ts

@@ -0,0 +1,96 @@
+import type { ToolcraftRendererPipelineClient } from "../rendering";
+import type { ToolcraftState } from "../state/types";
+import type { ToolcraftExportFrame } from "./export-frame";
+import {
+  normalizeToolcraftExportError,
+  ToolcraftArtifactExportError,
+} from "./export-error";
+import type { ToolcraftProductExportFrameRenderer } from "./product-export-renderer";
+
+export type ToolcraftArtifactFrameRenderRequest = Readonly<{
+  backgroundColor: string;
+  canvas: HTMLCanvasElement;
+  frame: ToolcraftExportFrame;
+  includeBackground: boolean;
+  pixelRatio: number;
+  renderProductFrame: ToolcraftProductExportFrameRenderer | null;
+  renderRuntimeScene: (
+    canvas: HTMLCanvasElement,
+    frame: ToolcraftExportFrame,
+    state: ToolcraftState,
+  ) => Promise<unknown>;
+  rendererPipeline: ToolcraftRendererPipelineClient | null;
+  state: ToolcraftState;
+}>;
+
+function getTimelineProgress(state: ToolcraftState): number {
+  if (state.timeline.durationSeconds <= 0) {
+    return 0;
+  }
+
+  return Math.max(
+    0,
+    Math.min(
+      1,
+      state.timeline.currentTimeSeconds / state.timeline.durationSeconds,
+    ),
+  );
+}
+
+export async function renderToolcraftArtifactFrame(
+  request: ToolcraftArtifactFrameRenderRequest,
+): Promise<void> {
+  const context = request.canvas.getContext("2d");
+  if (!context) {
+    throw new ToolcraftArtifactExportError({
+      code: "canvas-context-unavailable",
+      message: "Toolcraft export requires a 2D canvas context.",
+    });
+  }
+
+  context.setTransform(1, 0, 0, 1, 0, 0);
+  context.clearRect(0, 0, request.canvas.width, request.canvas.height);
+  if (request.includeBackground) {
+    context.fillStyle = request.backgroundColor;
+    context.fillRect(0, 0, request.canvas.width, request.canvas.height);
+  }
+
+  try {
+    await request.renderRuntimeScene(
+      request.canvas,
+      request.frame,
+      request.state,
+    );
+  } catch (error) {
+    throw normalizeToolcraftExportError(error, {
+      code: "runtime-scene-render-failed",
+      message: "Toolcraft could not render runtime scene layers for export.",
+    });
+  }
+
+  if (!request.renderProductFrame) {
+    return;
+  }
+
+  context.save();
+  context.scale(request.pixelRatio, request.pixelRatio);
+  context.translate(-request.frame.x, -request.frame.y);
+  try {
+    await request.renderProductFrame({
+      context,
+      frame: request.frame,
+      pixelRatio: request.pixelRatio,
+      rendererPipeline: request.rendererPipeline,
+      state: request.state,
+      timeSeconds: request.state.timeline.currentTimeSeconds,
+      timelineProgress: getTimelineProgress(request.state),
+    });
+  } catch (error) {
+    throw normalizeToolcraftExportError(error, {
+      code: "product-frame-render-failed",
+      message: "Toolcraft could not render product pixels for export.",
+    });
+  } finally {
+    context.restore();
+  }
+}

package/templates/runtime/export/artifact-frame-state.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+
+import { defineToolcraft } from "../schema/define-toolcraft";
+import { createToolcraftState } from "../state/create-template-state";
+import { createToolcraftArtifactFrameState } from "./artifact-frame-state";
+
+describe("createToolcraftArtifactFrameState", () => {
+  it("evaluates keyframed values without mutating the base snapshot", () => {
+    const state = createToolcraftState(
+      defineToolcraft({ canvas: { enabled: true }, panels: {} }),
+      {
+        timeline: {
+          currentTimeSeconds: 0,
+          isPlaying: true,
+          keyframeGroups: [
+            {
+              controlId: "shape.opacity",
+              label: "Opacity",
+              keyframes: [
+                {
+                  controlId: "shape.opacity",
+                  controlLabel: "Opacity",
+                  id: "a",
+                  timeSeconds: 0,
+                  value: 0,
+                  valueLabel: "0",
+                },
+                {
+                  controlId: "shape.opacity",
+                  controlLabel: "Opacity",
+                  id: "b",
+                  timeSeconds: 1,
+                  value: 1,
+                  valueLabel: "1",
+                },
+              ],
+            },
+          ],
+        },
+        values: { "shape.opacity": 0 },
+      },
+    );
+
+    const frameState = createToolcraftArtifactFrameState(state, 0.5);
+
+    expect(frameState).not.toBe(state);
+    expect(frameState.timeline.currentTimeSeconds).toBe(0.5);
+    expect(frameState.timeline.isPlaying).toBe(false);
+    expect(frameState.values["shape.opacity"]).toBeCloseTo(0.5, 5);
+    expect(state.timeline.currentTimeSeconds).toBe(0);
+    expect(state.timeline.isPlaying).toBe(true);
+    expect(state.values["shape.opacity"]).toBe(0);
+  });
+});

package/templates/runtime/export/artifact-frame-state.ts

@@ -0,0 +1,44 @@
+import { evaluateToolcraftTimelineValues } from "../state/keyframe-evaluation";
+import type { ToolcraftState } from "../state/types";
+import type { ToolcraftVideoFrameScheduleEntry } from "./video-frame-schedule";
+
+export type ToolcraftArtifactFrameState = Readonly<ToolcraftState>;
+
+export type ToolcraftVideoArtifactFramePlanEntry = Readonly<{
+  scheduleEntry: ToolcraftVideoFrameScheduleEntry;
+  state: ToolcraftArtifactFrameState;
+}>;
+
+export function createToolcraftArtifactFrameState(
+  baseState: ToolcraftState,
+  timeSeconds: number,
+): ToolcraftArtifactFrameState {
+  return Object.freeze({
+    ...baseState,
+    timeline: Object.freeze({
+      ...baseState.timeline,
+      currentTimeSeconds: timeSeconds,
+      isPlaying: false,
+    }),
+    values: Object.freeze(
+      evaluateToolcraftTimelineValues(baseState, timeSeconds),
+    ),
+  });
+}
+
+export function createToolcraftVideoArtifactFramePlan(
+  baseState: ToolcraftState,
+  schedule: readonly ToolcraftVideoFrameScheduleEntry[],
+): readonly ToolcraftVideoArtifactFramePlanEntry[] {
+  return Object.freeze(
+    schedule.map((scheduleEntry) =>
+      Object.freeze({
+        scheduleEntry,
+        state: createToolcraftArtifactFrameState(
+          baseState,
+          scheduleEntry.timeSeconds,
+        ),
+      }),
+    ),
+  );
+}

package/templates/runtime/export/artifact-scene-frame.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { defineToolcraft } from "../schema/define-toolcraft";
+import { createToolcraftState } from "../state/create-template-state";
+import { createToolcraftRuntimeSceneVisibility } from "../scene";
+import { ToolcraftSceneExportError } from "./export-frame";
+import {
+  resolveToolcraftImageArtifactFrame,
+  resolveToolcraftVideoArtifactFrame,
+} from "./artifact-scene-frame";
+import { createToolcraftVideoArtifactFramePlan } from "./artifact-frame-state";
+import { createToolcraftVideoFrameSchedule } from "./video-frame-schedule";
+
+const visibility = createToolcraftRuntimeSceneVisibility({
+  renderDefaultImages: true,
+  suppressedModelTargets: [],
+});
+
+function createState(mode: "finite" | "infinite") {
+  return createToolcraftState(
+    defineToolcraft({ canvas: { enabled: true }, panels: {} }),
+    { canvas: { mode } },
+  );
+}
+
+describe("artifact scene frame", () => {
+  it("returns a finite frame without invoking product bounds", () => {
+    const state = createState("finite");
+    const boundsProvider = vi.fn(() => []);
+
+    expect(
+      resolveToolcraftImageArtifactFrame({
+        boundsProvider,
+        productSceneRequired: true,
+        state,
+        visibility,
+      }),
+    ).toEqual({
+      height: state.canvas.size.height,
+      width: state.canvas.size.width,
+      x: 0,
+      y: 0,
+    });
+    expect(boundsProvider).not.toHaveBeenCalled();
+  });
+
+  it("unions moving infinite-scene bounds across the exact frame plan", () => {
+    const state = createState("infinite");
+    const plan = createToolcraftVideoArtifactFramePlan(
+      state,
+      createToolcraftVideoFrameSchedule(0.1),
+    );
+    const boundsProvider = vi.fn(({ state: frameState }) => [
+      {
+        height: 10,
+        width: 20,
+        x: frameState.timeline.currentTimeSeconds * 300,
+        y: -5,
+      },
+    ]);
+
+    expect(
+      resolveToolcraftVideoArtifactFrame({
+        boundsProvider,
+        framePlan: plan,
+        productSceneRequired: true,
+        visibility,
+      }),
+    ).toEqual({ height: 10, width: 40, x: 0, y: -5 });
+    expect(boundsProvider).toHaveBeenCalledTimes(3);
+    expect(boundsProvider.mock.calls[1]?.[0].state).toBe(plan[1]?.state);
+  });
+
+  it("fails visibly when an infinite product scene has no bounds provider", () => {
+    expect(() =>
+      resolveToolcraftImageArtifactFrame({
+        boundsProvider: undefined,
+        productSceneRequired: true,
+        state: createState("infinite"),
+        visibility,
+      }),
+    ).toThrow(ToolcraftSceneExportError);
+  });
+});

package/templates/runtime/export/artifact-scene-frame.ts

@@ -0,0 +1,118 @@
+import {
+  resolveToolcraftSceneBounds,
+  unionToolcraftSceneRects,
+  type ToolcraftProductSceneBoundsProvider,
+  type ToolcraftRuntimeSceneVisibility,
+  type ToolcraftSceneRect,
+} from "../scene";
+import { getToolcraftCanvasFrame } from "../state/canvas-frame";
+import type { ToolcraftState } from "../state/types";
+import type { ToolcraftVideoArtifactFramePlanEntry } from "./artifact-frame-state";
+import {
+  resolveToolcraftExportFrame,
+  ToolcraftSceneExportError,
+  type ToolcraftExportFrame,
+  type ToolcraftExportFrameResult,
+} from "./export-frame";
+
+type ToolcraftArtifactSceneFrameBaseRequest = Readonly<{
+  boundsProvider: ToolcraftProductSceneBoundsProvider | undefined;
+  productSceneRequired: boolean;
+  visibility: ToolcraftRuntimeSceneVisibility;
+}>;
+
+export type ToolcraftImageArtifactSceneFrameRequest =
+  ToolcraftArtifactSceneFrameBaseRequest &
+    Readonly<{ state: ToolcraftState }>;
+
+export type ToolcraftVideoArtifactSceneFrameRequest =
+  ToolcraftArtifactSceneFrameBaseRequest &
+    Readonly<{ framePlan: readonly ToolcraftVideoArtifactFramePlanEntry[] }>;
+
+function requireFrame(result: ToolcraftExportFrameResult): ToolcraftExportFrame {
+  if (!result.ok) {
+    throw new ToolcraftSceneExportError(result);
+  }
+
+  return result.frame;
+}
+
+function requireProductRects(
+  state: ToolcraftState,
+  request: ToolcraftArtifactSceneFrameBaseRequest,
+): readonly ToolcraftSceneRect[] {
+  if (!request.boundsProvider) {
+    if (request.productSceneRequired) {
+      throw new ToolcraftSceneExportError({
+        code: "scene-bounds-unavailable",
+        message: "This infinite product scene does not provide export bounds.",
+        ok: false,
+      });
+    }
+
+    return [];
+  }
+
+  try {
+    return request.boundsProvider({ state });
+  } catch {
+    throw new ToolcraftSceneExportError({
+      code: "scene-bounds-unavailable",
+      message: "Product scene bounds could not be resolved.",
+      ok: false,
+    });
+  }
+}
+
+function isFiniteCanvas(state: ToolcraftState): boolean {
+  return getToolcraftCanvasFrame(state.canvas).kind === "finite";
+}
+
+export function resolveToolcraftImageArtifactFrame(
+  request: ToolcraftImageArtifactSceneFrameRequest,
+): ToolcraftExportFrame {
+  if (isFiniteCanvas(request.state)) {
+    return requireFrame(resolveToolcraftExportFrame(request.state, null));
+  }
+
+  const bounds = resolveToolcraftSceneBounds(
+    request.state,
+    requireProductRects(request.state, request),
+    request.visibility,
+  );
+  return requireFrame(resolveToolcraftExportFrame(request.state, bounds));
+}
+
+export function resolveToolcraftVideoArtifactFrame(
+  request: ToolcraftVideoArtifactSceneFrameRequest,
+): ToolcraftExportFrame {
+  const firstState = request.framePlan[0]?.state;
+  if (!firstState) {
+    throw new ToolcraftSceneExportError({
+      code: "empty-scene",
+      message: "Video export has no scheduled frames.",
+      ok: false,
+    });
+  }
+  if (isFiniteCanvas(firstState)) {
+    return requireFrame(resolveToolcraftExportFrame(firstState, null));
+  }
+
+  const frameBounds: ToolcraftSceneRect[] = [];
+  for (const entry of request.framePlan) {
+    const result = resolveToolcraftSceneBounds(
+      entry.state,
+      requireProductRects(entry.state, request),
+      request.visibility,
+    );
+    if (result.ok) {
+      frameBounds.push(result.bounds);
+    } else if (result.code !== "empty-scene") {
+      throw new ToolcraftSceneExportError(result);
+    }
+  }
+
+  return requireFrame(
+    resolveToolcraftExportFrame(firstState, unionToolcraftSceneRects(frameBounds)),
+  );
+}