@pixel-point/toolcraft 0.0.16 → 0.0.17

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

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

@@ -0,0 +1,65 @@
+import type { ResolvedToolcraftAppSchema } from "../schema/types";
+import type { ToolcraftState } from "../state/types";
+
+export type ToolcraftExportFormat = "png" | "video";
+
+export type ToolcraftExportBackgroundOptions = {
+  format: ToolcraftExportFormat;
+  schema: ResolvedToolcraftAppSchema;
+};
+
+export type ToolcraftPreviewBackgroundOptions = {
+  includeBackgroundTarget?: string;
+  state: ToolcraftState;
+};
+
+export function shouldIncludeToolcraftExportBackground({
+  format,
+  schema,
+}: ToolcraftExportBackgroundOptions): boolean {
+  if (format === "video") {
+    return true;
+  }
+
+  return schema.export.png.background !== "transparent";
+}
+
+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,17 @@
-import { describe, expect, it, vi } from "vitest";
+import { describe, expect, it } from "vitest";
 
 import { defineToolcraft } from "../schema/define-toolcraft";
 import type { ToolcraftState } from "../state/types";
 import {
-  createToolcraftPngExportCanvas,
+  shouldIncludeToolcraftExportBackground,
+  shouldIncludeToolcraftPreviewBackground,
+} from "./export-background";
+import {
   getToolcraftImageExportSize,
   getToolcraftRetinaExportPixelRatio,
   getToolcraftRetinaExportSize,
   getToolcraftVideoExportSize,
-  shouldIncludeToolcraftExportBackground,
-  shouldIncludeToolcraftPreviewBackground,
-} from "./export";
+} from "./export-sizing";
 
 function createState(schema = defineToolcraft({ canvas: { enabled: true }, panels: {} })): ToolcraftState {
   return {
@@ -48,25 +49,6 @@ 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({
@@ -266,166 +248,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" },
+    });
+  });
+});