@pixel-point/toolcraft 0.0.16 → 0.0.18

package/templates/runtime/export/export-background.ts

@@ -0,0 +1,46 @@
+import type { ToolcraftState } from "../state/types";
+
+export type ToolcraftPreviewBackgroundOptions = {
+  includeBackgroundTarget?: string;
+  state: ToolcraftState;
+};
+
+export function shouldIncludeToolcraftPreviewBackground({
+  includeBackgroundTarget = "export.includeBackground",
+  state,
+}: ToolcraftPreviewBackgroundOptions): boolean {
+  if (state.canvas.mode === "infinite") {
+    return false;
+  }
+
+  const includeBackgroundValue = state.values[includeBackgroundTarget];
+
+  if (typeof includeBackgroundValue === "boolean") {
+    return includeBackgroundValue;
+  }
+
+  if (typeof includeBackgroundValue === "string") {
+    const normalizedValue = includeBackgroundValue.trim().toLowerCase();
+
+    if (
+      normalizedValue === "false" ||
+      normalizedValue === "off" ||
+      normalizedValue === "no" ||
+      normalizedValue === "transparent" ||
+      normalizedValue === "exclude"
+    ) {
+      return false;
+    }
+
+    if (
+      normalizedValue === "true" ||
+      normalizedValue === "on" ||
+      normalizedValue === "yes" ||
+      normalizedValue === "include"
+    ) {
+      return true;
+    }
+  }
+
+  return true;
+}

package/templates/runtime/export/export-error.ts

@@ -0,0 +1,43 @@
+import { ToolcraftSceneExportError } from "./export-frame";
+
+export type ToolcraftArtifactExportFailure = Readonly<{
+  code:
+    | "artifact-download-failed"
+    | "canvas-context-unavailable"
+    | "image-encode-failed"
+    | "invalid-export-setting"
+    | "product-frame-render-failed"
+    | "runtime-scene-render-failed"
+    | "video-artifact-too-large"
+    | "video-encode-failed"
+    | "video-encoder-unavailable";
+  message: string;
+  target?: string;
+}>;
+
+export class ToolcraftArtifactExportError extends Error {
+  readonly feedback: ToolcraftArtifactExportFailure;
+
+  constructor(
+    feedback: ToolcraftArtifactExportFailure,
+    options?: ErrorOptions,
+  ) {
+    super(feedback.message, options);
+    this.name = "ToolcraftArtifactExportError";
+    this.feedback = feedback;
+  }
+}
+
+export function normalizeToolcraftExportError(
+  error: unknown,
+  feedback: ToolcraftArtifactExportFailure,
+): ToolcraftArtifactExportError | ToolcraftSceneExportError {
+  if (
+    error instanceof ToolcraftArtifactExportError ||
+    error instanceof ToolcraftSceneExportError
+  ) {
+    return error;
+  }
+
+  return new ToolcraftArtifactExportError(feedback, { cause: error });
+}

package/templates/runtime/export/export.test.ts

@@ -1,16 +1,26 @@
-import { describe, expect, it, vi } from "vitest";
+import { describe, expect, expectTypeOf, it } from "vitest";
 
+import * as toolcraftRuntimeRoot from "../index";
 import { defineToolcraft } from "../schema/define-toolcraft";
 import type { ToolcraftState } from "../state/types";
+import type {
+  ToolcraftArtifactSize,
+  ToolcraftExportFrame,
+  ToolcraftPreviewBackgroundOptions,
+  ToolcraftProductExportFrameContext,
+  ToolcraftProductExportFrameRenderer,
+  ToolcraftProductExportRenderer,
+  ToolcraftRetinaExportSize,
+} from "../index";
+import {
+  shouldIncludeToolcraftPreviewBackground,
+} from "./export-background";
 import {
-  createToolcraftPngExportCanvas,
   getToolcraftImageExportSize,
   getToolcraftRetinaExportPixelRatio,
   getToolcraftRetinaExportSize,
   getToolcraftVideoExportSize,
-  shouldIncludeToolcraftExportBackground,
-  shouldIncludeToolcraftPreviewBackground,
-} from "./export";
+} from "./export-sizing";
 
 function createState(schema = defineToolcraft({ canvas: { enabled: true }, panels: {} })): ToolcraftState {
   return {
@@ -48,49 +58,42 @@ function createState(schema = defineToolcraft({ canvas: { enabled: true }, panel
   };
 }
 
-function createMockCanvas() {
-  const context = {
-    clearRect: vi.fn(),
-    fillRect: vi.fn(),
-    fillStyle: "",
-    restore: vi.fn(),
-    save: vi.fn(),
-    scale: vi.fn(),
-    translate: vi.fn(),
-  };
-  const canvas = {
-    getContext: vi.fn(() => context),
-    height: 0,
-    width: 0,
-  } as unknown as HTMLCanvasElement;
-
-  return { canvas, context };
-}
-
 describe("Toolcraft export helpers", () => {
-  it("normalizes png export background to include by default", () => {
-    const schema = defineToolcraft({
-      canvas: { enabled: true },
-      panels: {},
-    });
-
-    expect(schema.export.png.background).toBe("include");
-  });
-
-  it("preserves transparent png export background option", () => {
-    const schema = defineToolcraft({
-      canvas: { enabled: true },
-      export: {
-        png: {
-          background: "transparent",
-        },
-      },
-      panels: {},
-    });
+  it("keeps the runtime root limited to product-safe export primitives", () => {
+    expect(toolcraftRuntimeRoot).toMatchObject({
+      getToolcraftImageExportSize: expect.any(Function),
+      getToolcraftRetinaExportPixelRatio: expect.any(Function),
+      getToolcraftRetinaExportSize: expect.any(Function),
+      getToolcraftVideoExportSize: expect.any(Function),
+      shouldIncludeToolcraftPreviewBackground: expect.any(Function),
+      TOOLCRAFT_MAX_EXPORT_EDGE_PX: 8192,
+      TOOLCRAFT_MAX_EXPORT_PIXELS: 8192 * 8192,
+      toolcraftImageExportFormatTarget: "export.image.format",
+      toolcraftImageExportResolutionTarget: "export.image.resolution",
+      toolcraftVideoExportFormatTarget: "export.video.format",
+      toolcraftVideoExportResolutionTarget: "export.video.resolution",
+      validateToolcraftArtifactSize: expect.any(Function),
+    });
+    expect(toolcraftRuntimeRoot).not.toHaveProperty("exportToolcraftImageArtifact");
+    expect(toolcraftRuntimeRoot).not.toHaveProperty("exportToolcraftVideoArtifact");
+    expect(toolcraftRuntimeRoot).not.toHaveProperty(
+      "createToolcraftVideoEncoderBackend",
+    );
+    expect(toolcraftRuntimeRoot).not.toHaveProperty(
+      "createToolcraftVideoFrameSchedule",
+    );
 
-    expect(schema.export.png.background).toBe("transparent");
-    expect(shouldIncludeToolcraftExportBackground({ format: "png", schema })).toBe(false);
-    expect(shouldIncludeToolcraftExportBackground({ format: "video", schema })).toBe(true);
+    expectTypeOf<ToolcraftArtifactSize>().toMatchTypeOf<
+      Readonly<{ height: number; width: number }>
+    >();
+    expectTypeOf<ToolcraftExportFrame>().toMatchTypeOf<
+      Readonly<{ height: number; width: number; x: number; y: number }>
+    >();
+    expectTypeOf<ToolcraftPreviewBackgroundOptions>().toHaveProperty("state");
+    expectTypeOf<ToolcraftProductExportFrameContext>().toHaveProperty("frame");
+    expectTypeOf<ToolcraftProductExportFrameRenderer>().toBeFunction();
+    expectTypeOf<ToolcraftProductExportRenderer>().toHaveProperty("renderFrame");
+    expectTypeOf<ToolcraftRetinaExportSize>().toHaveProperty("pixelRatio");
   });
 
   it("uses include-background runtime state for live preview background", () => {
@@ -121,24 +124,6 @@ describe("Toolcraft export helpers", () => {
     expect(shouldIncludeToolcraftPreviewBackground({ state })).toBe(true);
   });
 
-  it("keeps video export background independent from preview include state", () => {
-    const schema = defineToolcraft({
-      canvas: { enabled: true },
-      export: {
-        png: {
-          background: "transparent",
-        },
-      },
-      panels: {},
-    });
-    const state = createState(schema);
-
-    state.values["export.includeBackground"] = false;
-
-    expect(shouldIncludeToolcraftPreviewBackground({ state })).toBe(false);
-    expect(shouldIncludeToolcraftExportBackground({ format: "video", schema })).toBe(true);
-  });
-
   it("uses at least 2x pixel ratio for retina export", () => {
     expect(getToolcraftRetinaExportPixelRatio(1)).toBe(2);
     expect(getToolcraftRetinaExportPixelRatio(1.5)).toBe(2);
@@ -266,166 +251,4 @@ describe("Toolcraft export helpers", () => {
     });
   });
 
-  it("creates a transparent retina png canvas when png background is disabled", () => {
-    const schema = defineToolcraft({
-      canvas: { enabled: true },
-      export: {
-        png: {
-          background: "transparent",
-        },
-      },
-      panels: {},
-    });
-    const state = createState(schema);
-    const { canvas, context } = createMockCanvas();
-    const render = vi.fn();
-
-    const exportedCanvas = createToolcraftPngExportCanvas({
-      canvasFactory: () => canvas,
-      devicePixelRatio: 2,
-      render,
-      state,
-    });
-
-    expect(exportedCanvas.width).toBe(400);
-    expect(exportedCanvas.height).toBe(200);
-    expect(context.clearRect).toHaveBeenCalledWith(0, 0, 400, 200);
-    expect(context.fillRect).not.toHaveBeenCalled();
-    expect(context.scale).toHaveBeenCalledWith(2, 2);
-    expect(render).toHaveBeenCalledWith(
-      expect.objectContaining({
-        cssHeight: 100,
-        cssWidth: 200,
-        includeBackground: false,
-        pixelHeight: 200,
-        pixelRatio: 2,
-        pixelWidth: 400,
-      }),
-    );
-  });
-
-  it("fills the png background when png background is enabled", () => {
-    const state = createState();
-    const { canvas, context } = createMockCanvas();
-
-    createToolcraftPngExportCanvas({
-      background: "#112233",
-      canvasFactory: () => canvas,
-      devicePixelRatio: 2,
-      render: vi.fn(),
-      state,
-    });
-
-    expect(context.fillStyle).toBe("#112233");
-    expect(context.fillRect).toHaveBeenCalledWith(0, 0, 400, 200);
-  });
-
-  it("creates a png canvas at the selected image export resolution", () => {
-    const state = createState();
-    const { canvas, context } = createMockCanvas();
-
-    createToolcraftPngExportCanvas({
-      canvasFactory: () => canvas,
-      render: vi.fn(),
-      resolution: "4k",
-      state,
-    });
-
-    expect(canvas.width).toBe(4096);
-    expect(canvas.height).toBe(2048);
-    expect(context.scale).toHaveBeenCalledWith(20.48, 20.48);
-  });
-
-  it("allows runtime controls to disable the png background", () => {
-    const state = createState();
-    const { canvas, context } = createMockCanvas();
-
-    createToolcraftPngExportCanvas({
-      background: "#112233",
-      canvasFactory: () => canvas,
-      devicePixelRatio: 2,
-      includeBackground: false,
-      render: vi.fn(),
-      state,
-    });
-
-    expect(context.fillRect).not.toHaveBeenCalled();
-  });
-
-  it("allows runtime controls to include the png background for transparent schema defaults", () => {
-    const schema = defineToolcraft({
-      canvas: { enabled: true },
-      export: {
-        png: {
-          background: "transparent",
-        },
-      },
-      panels: {},
-    });
-    const state = createState(schema);
-    const { canvas, context } = createMockCanvas();
-
-    createToolcraftPngExportCanvas({
-      background: "#445566",
-      canvasFactory: () => canvas,
-      devicePixelRatio: 2,
-      includeBackground: true,
-      render: vi.fn(),
-      state,
-    });
-
-    expect(context.fillStyle).toBe("#445566");
-    expect(context.fillRect).toHaveBeenCalledWith(0, 0, 400, 200);
-  });
-
-  it("renders an infinite scene through its resolved world crop", () => {
-    const state = createState();
-    state.canvas.mode = "infinite";
-    const { canvas, context } = createMockCanvas();
-    const render = vi.fn();
-
-    createToolcraftPngExportCanvas({
-      canvasFactory: () => canvas,
-      devicePixelRatio: 2,
-      frame: { height: 40, width: 80, x: -30, y: 10 },
-      render,
-      state,
-    });
-
-    expect(canvas.width).toBe(160);
-    expect(canvas.height).toBe(80);
-    expect(context.scale).toHaveBeenCalledWith(2, 2);
-    expect(context.translate).toHaveBeenCalledWith(30, -10);
-    expect(render).toHaveBeenCalledWith(
-      expect.objectContaining({
-        cssHeight: 40,
-        cssWidth: 80,
-        frame: { height: 40, width: 80, x: -30, y: 10 },
-      }),
-    );
-  });
-
-  it("rejects infinite and oversized exports before canvas allocation", () => {
-    const state = createState();
-    state.canvas.mode = "infinite";
-    const { canvas } = createMockCanvas();
-
-    expect(() =>
-      createToolcraftPngExportCanvas({
-        canvasFactory: () => canvas,
-        render: vi.fn(),
-        state,
-      }),
-    ).toThrow("no visible exportable elements");
-    expect(() =>
-      createToolcraftPngExportCanvas({
-        canvasFactory: () => canvas,
-        frame: { height: 5000, width: 5000, x: 0, y: 0 },
-        render: vi.fn(),
-        state,
-      }),
-    ).toThrow("8192 px per edge");
-    expect(canvas.width).toBe(0);
-    expect(canvas.height).toBe(0);
-  });
 });

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

@@ -0,0 +1,111 @@
+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 {
+  toolcraftImageExportFormatTarget,
+  toolcraftImageExportResolutionTarget,
+} from "./artifact-export-settings";
+import { exportToolcraftImageArtifact } from "./image-artifact-export";
+
+function createState(format: "jpg" | "png" = "png") {
+  return createToolcraftState(
+    defineToolcraft({ canvas: { enabled: true }, panels: {} }),
+    {
+      values: {
+        [toolcraftImageExportFormatTarget]: format,
+        [toolcraftImageExportResolutionTarget]: "2k",
+      },
+    },
+  );
+}
+
+function createCanvas(blob: Blob | null) {
+  const context = {
+    clearRect: vi.fn(),
+    fillRect: vi.fn(),
+    fillStyle: "",
+    restore: vi.fn(),
+    save: vi.fn(),
+    scale: vi.fn(),
+    setTransform: vi.fn(),
+    translate: vi.fn(),
+  };
+  const canvas = {
+    getContext: vi.fn(() => context),
+    height: 0,
+    toBlob: vi.fn((callback: BlobCallback) => callback(blob)),
+    width: 0,
+  } as unknown as HTMLCanvasElement;
+  return { canvas, context };
+}
+
+const visibility = createToolcraftRuntimeSceneVisibility({
+  renderDefaultImages: true,
+  suppressedModelTargets: [],
+});
+
+describe("exportToolcraftImageArtifact", () => {
+  it("renders and downloads the selected real image format and dimensions", async () => {
+    const { canvas } = createCanvas(
+      new Blob(["jpeg"], { type: "image/jpeg" }),
+    );
+    const downloadArtifact = vi.fn(() => ({ fileName: "scene.jpg" }));
+
+    const result = await exportToolcraftImageArtifact({
+      boundsProvider: undefined,
+      canvasFactory: () => canvas,
+      downloadArtifact,
+      exportRenderer: {
+        baseFileName: "scene",
+        renderFrame: vi.fn(),
+      },
+      productSceneRequired: true,
+      renderRuntimeScene: async () => undefined,
+      rendererPipeline: null,
+      reportProgress: vi.fn(),
+      state: createState("jpg"),
+      visibility,
+    });
+
+    expect(result).toEqual({
+      byteLength: 4,
+      extension: ".jpg",
+      height: 1152,
+      mediaType: "image/jpeg",
+      width: 2048,
+    });
+    expect(canvas.width).toBe(1);
+    expect(canvas.height).toBe(1);
+    expect(canvas.toBlob).toHaveBeenCalledWith(
+      expect.any(Function),
+      "image/jpeg",
+      0.95,
+    );
+    expect(downloadArtifact).toHaveBeenCalledWith(
+      expect.objectContaining({ extension: ".jpg", rawBaseFileName: "scene" }),
+    );
+  });
+
+  it("fails visibly when canvas encoding returns no blob", async () => {
+    const { canvas } = createCanvas(null);
+
+    await expect(
+      exportToolcraftImageArtifact({
+        boundsProvider: undefined,
+        canvasFactory: () => canvas,
+        downloadArtifact: vi.fn(),
+        exportRenderer: undefined,
+        productSceneRequired: false,
+        renderRuntimeScene: async () => undefined,
+        rendererPipeline: null,
+        reportProgress: vi.fn(),
+        state: createState(),
+        visibility,
+      }),
+    ).rejects.toMatchObject({
+      feedback: { code: "image-encode-failed" },
+    });
+  });
+});

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

@@ -0,0 +1,145 @@
+import {
+  getToolcraftRuntimeBackgroundColor,
+  isToolcraftRuntimeBackgroundEnabled,
+} from "../state/canvas-background-state";
+import {
+  downloadToolcraftArtifact,
+  type ToolcraftArtifactDownloadRequest,
+  type ToolcraftArtifactDownloadResult,
+  type ToolcraftArtifactFileExtension,
+} from "./artifact-download";
+import type { ToolcraftArtifactExportRequest } from "./artifact-export-request";
+import { resolveToolcraftImageExportSettings } from "./artifact-export-settings";
+import { renderToolcraftArtifactFrame } from "./artifact-frame-renderer";
+import { resolveToolcraftImageArtifactFrame } from "./artifact-scene-frame";
+import { createToolcraftArtifactFrameState } from "./artifact-frame-state";
+import {
+  ToolcraftSceneExportError,
+  validateToolcraftArtifactSize,
+} from "./export-frame";
+import { ToolcraftArtifactExportError } from "./export-error";
+import { getToolcraftImageExportSize } from "./export-sizing";
+
+export type ToolcraftImageArtifactExportResult = Readonly<{
+  byteLength: number;
+  extension: ".jpg" | ".png";
+  height: number;
+  mediaType: "image/jpeg" | "image/png";
+  width: number;
+}>;
+
+export type ToolcraftImageArtifactExportRequest = ToolcraftArtifactExportRequest &
+  Readonly<{
+    canvasFactory?: () => HTMLCanvasElement;
+    downloadArtifact?: (
+      request: ToolcraftArtifactDownloadRequest,
+    ) => ToolcraftArtifactDownloadResult;
+  }>;
+
+function encodeCanvas(
+  canvas: HTMLCanvasElement,
+  mediaType: "image/jpeg" | "image/png",
+): Promise<Blob> {
+  return new Promise((resolve, reject) => {
+    try {
+      canvas.toBlob(
+        (blob) => {
+          if (blob) {
+            resolve(blob);
+          } else {
+            reject(
+              new ToolcraftArtifactExportError({
+                code: "image-encode-failed",
+                message: "Toolcraft could not encode the image export.",
+              }),
+            );
+          }
+        },
+        mediaType,
+        mediaType === "image/jpeg" ? 0.95 : undefined,
+      );
+    } catch (error) {
+      reject(
+        new ToolcraftArtifactExportError(
+          {
+            code: "image-encode-failed",
+            message: "Toolcraft could not encode the image export.",
+          },
+          { cause: error },
+        ),
+      );
+    }
+  });
+}
+
+export async function exportToolcraftImageArtifact(
+  request: ToolcraftImageArtifactExportRequest,
+): Promise<ToolcraftImageArtifactExportResult> {
+  const settings = resolveToolcraftImageExportSettings(request.state);
+  const frameState = createToolcraftArtifactFrameState(
+    request.state,
+    request.state.timeline.currentTimeSeconds,
+  );
+  const frame = resolveToolcraftImageArtifactFrame({
+    boundsProvider: request.boundsProvider,
+    productSceneRequired: request.productSceneRequired,
+    state: frameState,
+    visibility: request.visibility,
+  });
+  const size = getToolcraftImageExportSize({
+    frame,
+    resolution: settings.resolution,
+    state: frameState,
+  });
+  const sizeValidation = validateToolcraftArtifactSize(size);
+  if (!sizeValidation.ok) {
+    throw new ToolcraftSceneExportError(sizeValidation);
+  }
+
+  const canvas = (request.canvasFactory ?? (() => document.createElement("canvas")))();
+  const mediaType = settings.format === "jpg" ? "image/jpeg" : "image/png";
+  const extension: ToolcraftArtifactFileExtension =
+    settings.format === "jpg" ? ".jpg" : ".png";
+  const includeBackground =
+    mediaType === "image/jpeg" || isToolcraftRuntimeBackgroundEnabled(frameState);
+  try {
+    canvas.width = size.width;
+    canvas.height = size.height;
+    request.reportProgress(0.1);
+
+    await renderToolcraftArtifactFrame({
+      backgroundColor:
+        getToolcraftRuntimeBackgroundColor(frameState) ?? "#000000",
+      canvas,
+      frame,
+      includeBackground,
+      pixelRatio: size.pixelRatio,
+      renderProductFrame: request.exportRenderer?.renderFrame ?? null,
+      renderRuntimeScene: request.renderRuntimeScene,
+      rendererPipeline: request.rendererPipeline,
+      state: frameState,
+    });
+    request.reportProgress(0.75);
+
+    const blob = await encodeCanvas(canvas, mediaType);
+    request.reportProgress(0.9);
+    (request.downloadArtifact ?? downloadToolcraftArtifact)({
+      blob,
+      extension,
+      rawBaseFileName:
+        request.exportRenderer?.baseFileName ?? "toolcraft-export",
+    });
+    request.reportProgress(1);
+
+    return {
+      byteLength: blob.size,
+      extension,
+      height: size.height,
+      mediaType,
+      width: size.width,
+    };
+  } finally {
+    canvas.width = 1;
+    canvas.height = 1;
+  }
+}

package/templates/runtime/export/index.ts

@@ -1,3 +1,44 @@
-export * from "./export";
-export * from "./export-frame";
-export * from "./export-sizing";
+export {
+  toolcraftImageExportFormatTarget,
+  toolcraftImageExportResolutionTarget,
+  toolcraftVideoExportFormatTarget,
+  toolcraftVideoExportResolutionTarget,
+} from "./artifact-export-settings";
+export type {
+  ToolcraftImageExportFormat,
+  ToolcraftImageExportPresetResolution,
+  ToolcraftResolvedImageExportSettings,
+  ToolcraftResolvedVideoExportSettings,
+  ToolcraftVideoExportFormat,
+  ToolcraftVideoExportPresetResolution,
+} from "./artifact-export-settings";
+export { shouldIncludeToolcraftPreviewBackground } from "./export-background";
+export type { ToolcraftPreviewBackgroundOptions } from "./export-background";
+export {
+  TOOLCRAFT_MAX_EXPORT_EDGE_PX,
+  TOOLCRAFT_MAX_EXPORT_PIXELS,
+  validateToolcraftArtifactSize,
+} from "./export-frame";
+export type {
+  ToolcraftArtifactSize,
+  ToolcraftExportFrame,
+} from "./export-frame";
+export {
+  getToolcraftImageExportSize,
+  getToolcraftRetinaExportPixelRatio,
+  getToolcraftRetinaExportSize,
+  getToolcraftVideoExportSize,
+} from "./export-sizing";
+export type {
+  ToolcraftExportSizeOptions,
+  ToolcraftImageExportResolution,
+  ToolcraftImageExportSizeOptions,
+  ToolcraftRetinaExportSize,
+  ToolcraftVideoExportResolution,
+  ToolcraftVideoExportSizeOptions,
+} from "./export-sizing";
+export type {
+  ToolcraftProductExportFrameContext,
+  ToolcraftProductExportFrameRenderer,
+  ToolcraftProductExportRenderer,
+} from "./product-export-renderer";