@pixel-point/toolcraft 0.0.16 → 0.0.18

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

package/templates/runtime/export/video-encoding-backend.ts

@@ -0,0 +1,124 @@
+import type { ToolcraftVideoExportFormat } from "./artifact-export-settings";
+import { ToolcraftArtifactExportError } from "./export-error";
+import {
+  TOOLCRAFT_MAX_VIDEO_ARTIFACT_BYTES,
+  resolveToolcraftVideoEncodingPolicy,
+  type ToolcraftVideoCodec,
+} from "./video-encoding-policy";
+
+export type ToolcraftVideoEncoderBackend = Readonly<{
+  addFrame: (
+    timeSeconds: number,
+    durationSeconds: number,
+    keyFrame: boolean,
+  ) => Promise<void>;
+  cancel: () => Promise<void>;
+  extension: ".mp4" | ".webm";
+  finalize: () => Promise<Blob>;
+  mediaType: "video/mp4" | "video/webm";
+}>;
+
+export type ToolcraftVideoEncoderBackendFactoryRequest = Readonly<{
+  canvas: HTMLCanvasElement;
+  durationSeconds: number;
+  height: number;
+  requestedFormat: ToolcraftVideoExportFormat;
+  width: number;
+}>;
+
+export type ToolcraftVideoEncoderBackendFactory = (
+  request: ToolcraftVideoEncoderBackendFactoryRequest,
+) => Promise<ToolcraftVideoEncoderBackend>;
+
+export async function createToolcraftVideoEncoderBackend(
+  request: ToolcraftVideoEncoderBackendFactoryRequest,
+): Promise<ToolcraftVideoEncoderBackend> {
+  const mediabunny = await import("mediabunny");
+  const codecs: readonly ToolcraftVideoCodec[] = ["avc", "vp9", "vp8"];
+  const supportResults = await Promise.all(
+    codecs.map((codec) =>
+      mediabunny.canEncodeVideo(codec, {
+        bitrate: 12_000_000,
+        height: request.height,
+        width: request.width,
+      }),
+    ),
+  );
+  const policy = resolveToolcraftVideoEncodingPolicy({
+    durationSeconds: request.durationSeconds,
+    height: request.height,
+    requestedFormat: request.requestedFormat,
+    support: {
+      avc: supportResults[0] === true,
+      vp8: supportResults[2] === true,
+      vp9: supportResults[1] === true,
+    },
+    width: request.width,
+  });
+  const format =
+    policy.mediaType === "video/mp4"
+      ? new mediabunny.Mp4OutputFormat()
+      : new mediabunny.WebMOutputFormat();
+  const target = new mediabunny.BufferTarget();
+  let overflowError: ToolcraftArtifactExportError | null = null;
+  target.on("write", ({ end }) => {
+    if (end > TOOLCRAFT_MAX_VIDEO_ARTIFACT_BYTES && !overflowError) {
+      overflowError = new ToolcraftArtifactExportError({
+        code: "video-artifact-too-large",
+        message: "The encoded video exceeds Toolcraft's artifact limit.",
+      });
+    }
+  });
+  const output = new mediabunny.Output({ format, target });
+  const source = new mediabunny.CanvasSource(request.canvas, {
+    bitrate: policy.bitrate,
+    codec: policy.codec,
+    keyFrameInterval: 2,
+  });
+  output.addVideoTrack(source, { frameRate: 30 });
+  await output.start();
+  let closed = false;
+  let finalized = false;
+
+  function closeSource(): void {
+    if (!closed) {
+      source.close();
+      closed = true;
+    }
+  }
+
+  return Object.freeze({
+    addFrame: async (timeSeconds, durationSeconds, keyFrame) => {
+      await source.add(timeSeconds, durationSeconds, { keyFrame });
+      if (overflowError) throw overflowError;
+    },
+    cancel: async () => {
+      if (finalized || output.state === "canceled") {
+        return;
+      }
+      closeSource();
+      await output.cancel();
+    },
+    extension: policy.extension,
+    finalize: async () => {
+      closeSource();
+      await output.finalize();
+      finalized = true;
+      if (overflowError) throw overflowError;
+      if (!target.buffer) {
+        throw new ToolcraftArtifactExportError({
+          code: "video-encode-failed",
+          message: "Toolcraft video encoding produced no artifact.",
+        });
+      }
+      if (target.buffer.byteLength > TOOLCRAFT_MAX_VIDEO_ARTIFACT_BYTES) {
+        throw new ToolcraftArtifactExportError({
+          code: "video-artifact-too-large",
+          message: "The encoded video exceeds Toolcraft's artifact limit.",
+        });
+      }
+      return new Blob([target.buffer], { type: policy.mediaType });
+    },
+    mediaType: policy.mediaType,
+  });
+}

package/templates/runtime/export/video-encoding-policy.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  TOOLCRAFT_MAX_VIDEO_ARTIFACT_BYTES,
+  getToolcraftVideoExportBitrate,
+  resolveToolcraftVideoEncodingPolicy,
+} from "./video-encoding-policy";
+
+describe("video encoding policy", () => {
+  it("prefers AVC for MP4 and VP9 then VP8 for WebM", () => {
+    const support = { avc: true, vp8: true, vp9: true };
+
+    expect(
+      resolveToolcraftVideoEncodingPolicy({
+        durationSeconds: 1,
+        height: 1080,
+        requestedFormat: "mp4",
+        support,
+        width: 1920,
+      }),
+    ).toMatchObject({ codec: "avc", extension: ".mp4" });
+    expect(
+      resolveToolcraftVideoEncodingPolicy({
+        durationSeconds: 1,
+        height: 1080,
+        requestedFormat: "webm",
+        support,
+        width: 1920,
+      }),
+    ).toMatchObject({ codec: "vp9", extension: ".webm" });
+  });
+
+  it("falls back to the other real container without changing quality", () => {
+    expect(
+      resolveToolcraftVideoEncodingPolicy({
+        durationSeconds: 1,
+        height: 2160,
+        requestedFormat: "mp4",
+        support: { avc: false, vp8: true, vp9: false },
+        width: 3840,
+      }),
+    ).toEqual({
+      bitrate: 12_000_000,
+      codec: "vp8",
+      extension: ".webm",
+      mediaType: "video/webm",
+    });
+  });
+
+  it("bounds bitrate and the maximum supported artifact", () => {
+    expect(getToolcraftVideoExportBitrate(320, 180)).toBe(2_000_000);
+    expect(getToolcraftVideoExportBitrate(3840, 2160)).toBe(12_000_000);
+    const projectedBytes = (12_000_000 * 60 * 1.1) / 8;
+    expect(projectedBytes).toBeLessThan(TOOLCRAFT_MAX_VIDEO_ARTIFACT_BYTES);
+  });
+
+  it("fails visibly when no timestamped codec is supported", () => {
+    expect(() =>
+      resolveToolcraftVideoEncodingPolicy({
+        durationSeconds: 1,
+        height: 1080,
+        requestedFormat: "mp4",
+        support: { avc: false, vp8: false, vp9: false },
+        width: 1920,
+      }),
+    ).toThrow("timestamped video encoder");
+  });
+});