@pixel-point/toolcraft 0.0.16 → 0.0.17

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,16 @@
-export * from "./export";
+export * from "./artifact-export-settings";
+export * from "./artifact-export-request";
+export * from "./artifact-download";
+export * from "./artifact-frame-renderer";
+export * from "./artifact-scene-frame";
+export * from "./artifact-frame-state";
+export * from "./export-error";
+export * from "./export-background";
 export * from "./export-frame";
 export * from "./export-sizing";
+export * from "./image-artifact-export";
+export * from "./product-export-renderer";
+export * from "./video-artifact-export";
+export * from "./video-encoding-backend";
+export * from "./video-encoding-policy";
+export * from "./video-frame-schedule";

package/templates/runtime/export/product-export-renderer.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { defineToolcraft } from "../schema/define-toolcraft";
+import { getToolcraftExportRendererCoverageErrors } from "./product-export-renderer";
+
+function createSchema(role?: "export-image" | "export-video") {
+  return defineToolcraft({
+    canvas: { enabled: true },
+    panels: role
+      ? {
+          controls: {
+            sections: [
+              {
+                controls: {
+                  actions: {
+                    actions: [{ role, value: role }],
+                    target: "actions.output",
+                    type: "panelActions",
+                  },
+                },
+                id: "actions",
+              },
+            ],
+            title: "Controls",
+          },
+        }
+      : {},
+  });
+}
+
+describe("export renderer coverage", () => {
+  const renderer = { baseFileName: "artifact", renderFrame: vi.fn() };
+
+  it("requires one renderer for any exported product-owned scene", () => {
+    expect(
+      getToolcraftExportRendererCoverageErrors({
+        exportRenderer: undefined,
+        productSceneRequired: true,
+        schema: createSchema("export-image"),
+      }),
+    ).toContain("Product-owned export actions require exportRenderer.");
+  });
+
+  it("allows runtime-only scenes to use runtime composition", () => {
+    expect(
+      getToolcraftExportRendererCoverageErrors({
+        exportRenderer: undefined,
+        productSceneRequired: false,
+        schema: createSchema("export-video"),
+      }),
+    ).toEqual([]);
+  });
+
+  it("rejects dead renderers and blank filenames", () => {
+    expect(
+      getToolcraftExportRendererCoverageErrors({
+        exportRenderer: renderer,
+        productSceneRequired: false,
+        schema: createSchema("export-image"),
+      }),
+    ).toContain("exportRenderer requires a product-owned scene.");
+    expect(
+      getToolcraftExportRendererCoverageErrors({
+        exportRenderer: { ...renderer, baseFileName: "   " },
+        productSceneRequired: true,
+        schema: createSchema("export-image"),
+      }),
+    ).toContain("exportRenderer.baseFileName must not be blank.");
+    expect(
+      getToolcraftExportRendererCoverageErrors({
+        exportRenderer: renderer,
+        productSceneRequired: true,
+        schema: createSchema(),
+      }),
+    ).toContain("exportRenderer requires a typed export action.");
+  });
+});

package/templates/runtime/export/product-export-renderer.ts

@@ -0,0 +1,63 @@
+import type { ToolcraftRendererPipelineClient } from "../rendering";
+import type { ResolvedToolcraftAppSchema } from "../schema/types";
+import type { ToolcraftState } from "../state/types";
+import type { ToolcraftExportFrame } from "./export-frame";
+
+export type ToolcraftProductExportFrameContext = Readonly<{
+  context: CanvasRenderingContext2D;
+  frame: ToolcraftExportFrame;
+  pixelRatio: number;
+  rendererPipeline: ToolcraftRendererPipelineClient | null;
+  state: Readonly<ToolcraftState>;
+  timeSeconds: number;
+  timelineProgress: number;
+}>;
+
+export type ToolcraftProductExportFrameRenderer = (
+  context: ToolcraftProductExportFrameContext,
+) => PromiseLike<void> | void;
+
+export type ToolcraftProductExportRenderer = Readonly<{
+  baseFileName: string;
+  renderFrame: ToolcraftProductExportFrameRenderer;
+}>;
+
+function hasTypedExportAction(schema: ResolvedToolcraftAppSchema): boolean {
+  return (schema.panels.controls?.sections ?? []).some((section) =>
+    Object.values(section.controls).some((control) =>
+      (control.actions ?? []).some(
+        (action) =>
+          typeof action !== "string" &&
+          (action.role === "export-image" || action.role === "export-video"),
+      ),
+    ),
+  );
+}
+
+export function getToolcraftExportRendererCoverageErrors({
+  exportRenderer,
+  productSceneRequired,
+  schema,
+}: Readonly<{
+  exportRenderer: ToolcraftProductExportRenderer | undefined;
+  productSceneRequired: boolean;
+  schema: ResolvedToolcraftAppSchema;
+}>): string[] {
+  const errors: string[] = [];
+  const hasExportAction = hasTypedExportAction(schema);
+
+  if (hasExportAction && productSceneRequired && !exportRenderer) {
+    errors.push("Product-owned export actions require exportRenderer.");
+  }
+  if (exportRenderer && !productSceneRequired) {
+    errors.push("exportRenderer requires a product-owned scene.");
+  }
+  if (exportRenderer && !hasExportAction) {
+    errors.push("exportRenderer requires a typed export action.");
+  }
+  if (exportRenderer && exportRenderer.baseFileName.trim().length === 0) {
+    errors.push("exportRenderer.baseFileName must not be blank.");
+  }
+
+  return errors;
+}

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

@@ -0,0 +1,166 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { createToolcraftRuntimeSceneVisibility } from "../scene";
+import { defineToolcraft } from "../schema/define-toolcraft";
+import { createToolcraftState } from "../state/create-template-state";
+import {
+  toolcraftVideoExportFormatTarget,
+  toolcraftVideoExportResolutionTarget,
+} from "./artifact-export-settings";
+import { exportToolcraftVideoArtifact } from "./video-artifact-export";
+
+function createCanvas() {
+  const context = {
+    clearRect: vi.fn(),
+    fillRect: vi.fn(),
+    fillStyle: "",
+    restore: vi.fn(),
+    save: vi.fn(),
+    scale: vi.fn(),
+    setTransform: vi.fn(),
+    translate: vi.fn(),
+  };
+  return {
+    getContext: vi.fn(() => context),
+    height: 0,
+    width: 0,
+  } as unknown as HTMLCanvasElement;
+}
+
+describe("exportToolcraftVideoArtifact", () => {
+  it("normalizes encoder startup failures and releases the export canvas", async () => {
+    const state = createToolcraftState(
+      defineToolcraft({
+        canvas: { enabled: true },
+        panels: { timeline: { enabled: true, defaultDurationSeconds: 1 } },
+      }),
+    );
+    const canvas = createCanvas();
+
+    await expect(
+      exportToolcraftVideoArtifact({
+        backendFactory: async () => {
+          throw new Error("codec startup failed");
+        },
+        boundsProvider: undefined,
+        canvasFactory: () => canvas,
+        exportRenderer: undefined,
+        productSceneRequired: false,
+        renderRuntimeScene: async () => undefined,
+        rendererPipeline: null,
+        reportProgress: vi.fn(),
+        state,
+        visibility: createToolcraftRuntimeSceneVisibility({
+          renderDefaultImages: true,
+          suppressedModelTargets: [],
+        }),
+      }),
+    ).rejects.toMatchObject({
+      feedback: { code: "video-encode-failed" },
+    });
+    expect(canvas.width).toBe(1);
+    expect(canvas.height).toBe(1);
+  });
+
+  it("renders a slow product once per exact timeline frame", async () => {
+    const state = createToolcraftState(
+      defineToolcraft({
+        canvas: { enabled: true },
+        panels: { timeline: { enabled: true, defaultDurationSeconds: 1 } },
+      }),
+      {
+        timeline: { durationSeconds: 1 },
+        values: {
+          [toolcraftVideoExportFormatTarget]: "mp4",
+          [toolcraftVideoExportResolutionTarget]: "current",
+        },
+      },
+    );
+    const added: Array<{ durationSeconds: number; timeSeconds: number }> = [];
+    const cancel = vi.fn(async () => undefined);
+    const finalize = vi.fn(async () =>
+      new Blob(["video"], { type: "video/mp4" }),
+    );
+    const renderFrame = vi.fn(async () => Promise.resolve());
+
+    const result = await exportToolcraftVideoArtifact({
+      backendFactory: async () => ({
+        addFrame: async (timeSeconds, durationSeconds) => {
+          added.push({ durationSeconds, timeSeconds });
+        },
+        cancel,
+        extension: ".mp4",
+        finalize,
+        mediaType: "video/mp4",
+      }),
+      boundsProvider: undefined,
+      canvasFactory: createCanvas,
+      downloadArtifact: vi.fn(() => ({ fileName: "scene.mp4" })),
+      exportRenderer: { baseFileName: "scene", renderFrame },
+      productSceneRequired: true,
+      renderRuntimeScene: async () => undefined,
+      rendererPipeline: null,
+      reportProgress: vi.fn(),
+      state,
+      visibility: createToolcraftRuntimeSceneVisibility({
+        renderDefaultImages: true,
+        suppressedModelTargets: [],
+      }),
+      yieldToBrowser: async () => undefined,
+    });
+
+    expect(result.frameCount).toBe(30);
+    expect(result.durationSeconds).toBe(1);
+    expect(renderFrame).toHaveBeenCalledTimes(30);
+    expect(added).toHaveLength(30);
+    expect(added[0]).toEqual({ durationSeconds: 1 / 30, timeSeconds: 0 });
+    expect(added.at(-1)?.timeSeconds).toBe(29 / 30);
+    expect(finalize).toHaveBeenCalledOnce();
+    expect(cancel).not.toHaveBeenCalled();
+  });
+
+  it("cancels exactly once when frame rendering fails", async () => {
+    const state = createToolcraftState(
+      defineToolcraft({
+        canvas: { enabled: true },
+        panels: { timeline: { enabled: true, defaultDurationSeconds: 1 } },
+      }),
+      { timeline: { durationSeconds: 1 } },
+    );
+    const cancel = vi.fn(async () => undefined);
+
+    await expect(
+      exportToolcraftVideoArtifact({
+        backendFactory: async () => ({
+          addFrame: async () => undefined,
+          cancel,
+          extension: ".webm",
+          finalize: async () => new Blob(),
+          mediaType: "video/webm",
+        }),
+        boundsProvider: undefined,
+        canvasFactory: createCanvas,
+        downloadArtifact: vi.fn(),
+        exportRenderer: {
+          baseFileName: "scene",
+          renderFrame: () => {
+            throw new Error("broken");
+          },
+        },
+        productSceneRequired: true,
+        renderRuntimeScene: async () => undefined,
+        rendererPipeline: null,
+        reportProgress: vi.fn(),
+        state,
+        visibility: createToolcraftRuntimeSceneVisibility({
+          renderDefaultImages: true,
+          suppressedModelTargets: [],
+        }),
+        yieldToBrowser: async () => undefined,
+      }),
+    ).rejects.toMatchObject({
+      feedback: { code: "product-frame-render-failed" },
+    });
+    expect(cancel).toHaveBeenCalledOnce();
+  });
+});

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

@@ -0,0 +1,164 @@
+import { getToolcraftRuntimeBackgroundColor } from "../state/canvas-background-state";
+import {
+  downloadToolcraftArtifact,
+  type ToolcraftArtifactDownloadRequest,
+  type ToolcraftArtifactDownloadResult,
+} from "./artifact-download";
+import type { ToolcraftArtifactExportRequest } from "./artifact-export-request";
+import { resolveToolcraftVideoExportSettings } from "./artifact-export-settings";
+import { renderToolcraftArtifactFrame } from "./artifact-frame-renderer";
+import { resolveToolcraftVideoArtifactFrame } from "./artifact-scene-frame";
+import { createToolcraftVideoArtifactFramePlan } from "./artifact-frame-state";
+import {
+  ToolcraftSceneExportError,
+  validateToolcraftArtifactSize,
+} from "./export-frame";
+import {
+  normalizeToolcraftExportError,
+  ToolcraftArtifactExportError,
+} from "./export-error";
+import { getToolcraftVideoExportSize } from "./export-sizing";
+import {
+  createToolcraftVideoEncoderBackend,
+  type ToolcraftVideoEncoderBackend,
+  type ToolcraftVideoEncoderBackendFactory,
+} from "./video-encoding-backend";
+import { TOOLCRAFT_MAX_VIDEO_ARTIFACT_BYTES } from "./video-encoding-policy";
+import { createToolcraftVideoFrameSchedule } from "./video-frame-schedule";
+
+export type ToolcraftVideoArtifactExportResult = Readonly<{
+  byteLength: number;
+  durationSeconds: number;
+  extension: ".mp4" | ".webm";
+  frameCount: number;
+  height: number;
+  mediaType: "video/mp4" | "video/webm";
+  width: number;
+}>;
+
+export type ToolcraftVideoArtifactExportRequest = ToolcraftArtifactExportRequest &
+  Readonly<{
+    backendFactory?: ToolcraftVideoEncoderBackendFactory;
+    canvasFactory?: () => HTMLCanvasElement;
+    downloadArtifact?: (
+      request: ToolcraftArtifactDownloadRequest,
+    ) => ToolcraftArtifactDownloadResult;
+    yieldToBrowser?: () => Promise<void>;
+  }>;
+
+async function yieldToBrowser(): Promise<void> {
+  const scheduler = (globalThis as typeof globalThis & {
+    scheduler?: { yield?: () => Promise<void> };
+  }).scheduler;
+  if (scheduler?.yield) {
+    await scheduler.yield();
+    return;
+  }
+
+  await new Promise<void>((resolve) => globalThis.setTimeout(resolve, 0));
+}
+
+export async function exportToolcraftVideoArtifact(
+  request: ToolcraftVideoArtifactExportRequest,
+): Promise<ToolcraftVideoArtifactExportResult> {
+  const settings = resolveToolcraftVideoExportSettings(request.state);
+  const durationSeconds = request.state.timeline.durationSeconds;
+  const schedule = createToolcraftVideoFrameSchedule(durationSeconds);
+  const framePlan = createToolcraftVideoArtifactFramePlan(request.state, schedule);
+  const frame = resolveToolcraftVideoArtifactFrame({
+    boundsProvider: request.boundsProvider,
+    framePlan,
+    productSceneRequired: request.productSceneRequired,
+    visibility: request.visibility,
+  });
+  const size = getToolcraftVideoExportSize({
+    frame,
+    resolution: settings.resolution,
+    state: request.state,
+  });
+  const sizeValidation = validateToolcraftArtifactSize(size);
+  if (!sizeValidation.ok) {
+    throw new ToolcraftSceneExportError(sizeValidation);
+  }
+
+  const canvas = (request.canvasFactory ?? (() => document.createElement("canvas")))();
+  let backend: ToolcraftVideoEncoderBackend | null = null;
+  let finalized = false;
+
+  try {
+    canvas.width = size.width;
+    canvas.height = size.height;
+    backend = await (request.backendFactory ??
+      createToolcraftVideoEncoderBackend)({
+      canvas,
+      durationSeconds,
+      height: size.height,
+      requestedFormat: settings.format,
+      width: size.width,
+    });
+    for (const entry of framePlan) {
+      await renderToolcraftArtifactFrame({
+        backgroundColor:
+          getToolcraftRuntimeBackgroundColor(entry.state) ?? "#000000",
+        canvas,
+        frame,
+        includeBackground: true,
+        pixelRatio: size.pixelRatio,
+        renderProductFrame: request.exportRenderer?.renderFrame ?? null,
+        renderRuntimeScene: request.renderRuntimeScene,
+        rendererPipeline: request.rendererPipeline,
+        state: entry.state,
+      });
+      await backend.addFrame(
+        entry.scheduleEntry.timeSeconds,
+        entry.scheduleEntry.durationSeconds,
+        entry.scheduleEntry.index === 0 || entry.scheduleEntry.index % 60 === 0,
+      );
+      request.reportProgress(
+        ((entry.scheduleEntry.index + 1) / framePlan.length) * 0.95,
+      );
+      await (request.yieldToBrowser ?? yieldToBrowser)();
+    }
+
+    request.reportProgress(0.98);
+    const blob = await backend.finalize();
+    finalized = true;
+    if (blob.size > TOOLCRAFT_MAX_VIDEO_ARTIFACT_BYTES) {
+      throw new ToolcraftArtifactExportError({
+        code: "video-artifact-too-large",
+        message: "The encoded video exceeds Toolcraft's artifact limit.",
+      });
+    }
+    (request.downloadArtifact ?? downloadToolcraftArtifact)({
+      blob,
+      extension: backend.extension,
+      rawBaseFileName: request.exportRenderer?.baseFileName ?? "toolcraft-export",
+    });
+    request.reportProgress(1);
+
+    return {
+      byteLength: blob.size,
+      durationSeconds,
+      extension: backend.extension,
+      frameCount: framePlan.length,
+      height: size.height,
+      mediaType: backend.mediaType,
+      width: size.width,
+    };
+  } catch (error) {
+    if (!finalized && backend) {
+      try {
+        await backend.cancel();
+      } catch {
+        // Preserve the actionable render/encode error.
+      }
+    }
+    throw normalizeToolcraftExportError(error, {
+      code: "video-encode-failed",
+      message: "Toolcraft could not encode the video export.",
+    });
+  } finally {
+    canvas.width = 1;
+    canvas.height = 1;
+  }
+}