@pixel-point/toolcraft 0.0.16 → 0.0.17

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

@@ -0,0 +1,71 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { downloadToolcraftArtifact } from "./artifact-download";
+
+describe("downloadToolcraftArtifact", () => {
+  it("sanitizes the filename and revokes the object URL after the click", () => {
+    const events: string[] = [];
+    const anchor = {
+      click: vi.fn(() => events.push("click")),
+      download: "",
+      href: "",
+      remove: vi.fn(() => events.push("remove")),
+    };
+    const schedule = vi.fn((callback: () => void) => {
+      events.push("schedule-revoke");
+      callback();
+      return 1;
+    });
+
+    const result = downloadToolcraftArtifact({
+      appendAnchor: () => events.push("append"),
+      blob: new Blob(["png"], { type: "image/png" }),
+      createAnchor: () => anchor,
+      createObjectUrl: () => "blob:artifact",
+      extension: ".png",
+      rawBaseFileName: "  Unsafe / name  ",
+      revokeObjectUrl: () => events.push("revoke"),
+      schedule,
+    });
+
+    expect(result.fileName).toBe("Unsafe-name.png");
+    expect(anchor.download).toBe("Unsafe-name.png");
+    expect(events).toEqual([
+      "append",
+      "click",
+      "remove",
+      "schedule-revoke",
+      "revoke",
+    ]);
+  });
+
+  it("types click failures and still removes and revokes", () => {
+    const remove = vi.fn();
+    const revoke = vi.fn();
+
+    expect(() =>
+      downloadToolcraftArtifact({
+        appendAnchor: vi.fn(),
+        blob: new Blob(["png"]),
+        createAnchor: () => ({
+          click: () => {
+            throw new Error("blocked");
+          },
+          download: "",
+          href: "",
+          remove,
+        }),
+        createObjectUrl: () => "blob:artifact",
+        extension: ".png",
+        rawBaseFileName: "",
+        revokeObjectUrl: revoke,
+        schedule: (callback) => {
+          callback();
+          return 1;
+        },
+      }),
+    ).toThrow("could not start the artifact download");
+    expect(remove).toHaveBeenCalledOnce();
+    expect(revoke).toHaveBeenCalledWith("blob:artifact");
+  });
+});

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

@@ -0,0 +1,80 @@
+import {
+  normalizeToolcraftExportError,
+  type ToolcraftArtifactExportFailure,
+} from "./export-error";
+
+export type ToolcraftArtifactFileExtension =
+  | ".jpg"
+  | ".mp4"
+  | ".png"
+  | ".webm";
+
+type ToolcraftDownloadAnchor = {
+  click: () => void;
+  download: string;
+  href: string;
+  remove: () => void;
+};
+
+export type ToolcraftArtifactDownloadRequest = Readonly<{
+  appendAnchor?: (anchor: ToolcraftDownloadAnchor) => void;
+  blob: Blob;
+  createAnchor?: () => ToolcraftDownloadAnchor;
+  createObjectUrl?: (blob: Blob) => string;
+  extension: ToolcraftArtifactFileExtension;
+  rawBaseFileName: string;
+  revokeObjectUrl?: (url: string) => void;
+  schedule?: (callback: () => void, delay: number) => unknown;
+}>;
+
+export type ToolcraftArtifactDownloadResult = Readonly<{ fileName: string }>;
+
+export function sanitizeToolcraftArtifactBaseFileName(value: string): string {
+  const sanitized = value
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]+/g, "-")
+    .replace(/^[.-]+|[.-]+$/g, "");
+
+  return sanitized || "toolcraft-export";
+}
+
+const downloadFailure: ToolcraftArtifactExportFailure = Object.freeze({
+  code: "artifact-download-failed",
+  message: "Toolcraft could not start the artifact download.",
+});
+
+export function downloadToolcraftArtifact(
+  request: ToolcraftArtifactDownloadRequest,
+): ToolcraftArtifactDownloadResult {
+  const createAnchor =
+    request.createAnchor ?? (() => document.createElement("a"));
+  const appendAnchor =
+    request.appendAnchor ??
+    ((anchor) => document.body.append(anchor as HTMLAnchorElement));
+  const createObjectUrl = request.createObjectUrl ?? URL.createObjectURL;
+  const revokeObjectUrl = request.revokeObjectUrl ?? URL.revokeObjectURL;
+  const schedule = request.schedule ?? globalThis.setTimeout;
+  const fileName = `${sanitizeToolcraftArtifactBaseFileName(
+    request.rawBaseFileName,
+  )}${request.extension}`;
+  let anchor: ToolcraftDownloadAnchor | null = null;
+  let objectUrl: string | null = null;
+
+  try {
+    objectUrl = createObjectUrl(request.blob);
+    anchor = createAnchor();
+    anchor.download = fileName;
+    anchor.href = objectUrl;
+    appendAnchor(anchor);
+    anchor.click();
+    return { fileName };
+  } catch (error) {
+    throw normalizeToolcraftExportError(error, downloadFailure);
+  } finally {
+    anchor?.remove();
+    if (objectUrl) {
+      const urlToRevoke = objectUrl;
+      schedule(() => revokeObjectUrl(urlToRevoke), 0);
+    }
+  }
+}

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

@@ -0,0 +1,23 @@
+import type { ToolcraftRendererPipelineClient } from "../rendering";
+import type {
+  ToolcraftProductSceneBoundsProvider,
+  ToolcraftRuntimeSceneVisibility,
+} from "../scene";
+import type { ToolcraftState } from "../state/types";
+import type { ToolcraftExportFrame } from "./export-frame";
+import type { ToolcraftProductExportRenderer } from "./product-export-renderer";
+
+export type ToolcraftArtifactExportRequest = Readonly<{
+  boundsProvider: ToolcraftProductSceneBoundsProvider | undefined;
+  exportRenderer: ToolcraftProductExportRenderer | undefined;
+  productSceneRequired: boolean;
+  renderRuntimeScene: (
+    canvas: HTMLCanvasElement,
+    frame: ToolcraftExportFrame,
+    state: ToolcraftState,
+  ) => Promise<unknown>;
+  rendererPipeline: ToolcraftRendererPipelineClient | null;
+  reportProgress: (progress: number) => void;
+  state: ToolcraftState;
+  visibility: ToolcraftRuntimeSceneVisibility;
+}>;

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,
+        ),
+      }),
+    ),
+  );
+}