@pixel-point/toolcraft 0.0.16 → 0.0.17

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

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

@@ -0,0 +1,86 @@
+import type { ToolcraftVideoExportFormat } from "./artifact-export-settings";
+import { ToolcraftArtifactExportError } from "./export-error";
+
+export const TOOLCRAFT_MAX_VIDEO_ARTIFACT_BYTES = 96 * 1024 * 1024;
+
+export type ToolcraftVideoCodec = "avc" | "vp8" | "vp9";
+
+export type ToolcraftVideoEncodingSupport = Readonly<{
+  avc: boolean;
+  vp8: boolean;
+  vp9: boolean;
+}>;
+
+export type ToolcraftVideoEncodingPolicy = Readonly<{
+  bitrate: number;
+  codec: ToolcraftVideoCodec;
+  extension: ".mp4" | ".webm";
+  mediaType: "video/mp4" | "video/webm";
+}>;
+
+type ToolcraftVideoEncodingCandidate = Readonly<{
+  codec: ToolcraftVideoCodec;
+  extension: ".mp4" | ".webm";
+  mediaType: "video/mp4" | "video/webm";
+}>;
+
+const mp4Candidate: ToolcraftVideoEncodingCandidate = Object.freeze({
+  codec: "avc",
+  extension: ".mp4",
+  mediaType: "video/mp4",
+});
+const webmCandidates: readonly ToolcraftVideoEncodingCandidate[] = Object.freeze([
+  Object.freeze({ codec: "vp9", extension: ".webm", mediaType: "video/webm" }),
+  Object.freeze({ codec: "vp8", extension: ".webm", mediaType: "video/webm" }),
+]);
+
+export function getToolcraftVideoExportBitrate(
+  width: number,
+  height: number,
+): number {
+  return Math.max(
+    2_000_000,
+    Math.min(12_000_000, Math.round(width * height * 30 * 0.05)),
+  );
+}
+
+function assertArtifactBudget(bitrate: number, durationSeconds: number): void {
+  const projectedBytes = (bitrate * durationSeconds * 1.1) / 8;
+  if (projectedBytes > TOOLCRAFT_MAX_VIDEO_ARTIFACT_BYTES) {
+    throw new ToolcraftArtifactExportError({
+      code: "video-artifact-too-large",
+      message: "The selected video export exceeds Toolcraft's artifact limit.",
+    });
+  }
+}
+
+export function resolveToolcraftVideoEncodingPolicy({
+  durationSeconds,
+  height,
+  requestedFormat,
+  support,
+  width,
+}: Readonly<{
+  durationSeconds: number;
+  height: number;
+  requestedFormat: ToolcraftVideoExportFormat;
+  support: ToolcraftVideoEncodingSupport;
+  width: number;
+}>): ToolcraftVideoEncodingPolicy {
+  const bitrate = getToolcraftVideoExportBitrate(width, height);
+  assertArtifactBudget(bitrate, durationSeconds);
+  const candidates =
+    requestedFormat === "mp4"
+      ? [mp4Candidate, ...webmCandidates]
+      : [...webmCandidates, mp4Candidate];
+  const candidate = candidates.find((item) => support[item.codec]);
+
+  if (!candidate) {
+    throw new ToolcraftArtifactExportError({
+      code: "video-encoder-unavailable",
+      message: "This browser has no supported timestamped video encoder.",
+    });
+  }
+
+  return Object.freeze({ ...candidate, bitrate });
+}

package/templates/runtime/export/video-frame-schedule.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  TOOLCRAFT_VIDEO_EXPORT_FRAMES_PER_SECOND,
+  createToolcraftVideoFrameSchedule,
+} from "./video-frame-schedule";
+
+describe("createToolcraftVideoFrameSchedule", () => {
+  it("creates exact timeline timestamps without duplicating the endpoint", () => {
+    const schedule = createToolcraftVideoFrameSchedule(4.8);
+
+    expect(TOOLCRAFT_VIDEO_EXPORT_FRAMES_PER_SECOND).toBe(30);
+    expect(schedule).toHaveLength(144);
+    expect(schedule[0]).toEqual({
+      durationSeconds: 1 / 30,
+      index: 0,
+      timeSeconds: 0,
+    });
+    expect(schedule.at(-1)?.timeSeconds).toBe(143 / 30);
+    expect(
+      schedule.reduce(
+        (end, frame) =>
+          Math.max(end, frame.timeSeconds + frame.durationSeconds),
+        0,
+      ),
+    ).toBeCloseTo(4.8, 10);
+  });
+
+  it("shortens only the final frame for a fractional duration", () => {
+    const schedule = createToolcraftVideoFrameSchedule(1.01);
+
+    expect(schedule).toHaveLength(31);
+    expect(schedule.at(-1)).toEqual({
+      durationSeconds: 1.01 - 1,
+      index: 30,
+      timeSeconds: 1,
+    });
+  });
+
+  it.each([0.1, 0.3, 4.8, 4.9, 60])(
+    "avoids a floating-point phantom frame for %s seconds",
+    (durationSeconds) => {
+      const schedule = createToolcraftVideoFrameSchedule(durationSeconds);
+
+      expect(schedule).toHaveLength(Math.round(durationSeconds * 30));
+      expect(schedule.at(-1)?.timeSeconds).toBeLessThan(durationSeconds);
+    },
+  );
+
+  it.each([0, -1, Number.NaN, Number.POSITIVE_INFINITY])(
+    "rejects invalid duration %s",
+    (durationSeconds) => {
+      expect(() => createToolcraftVideoFrameSchedule(durationSeconds)).toThrow(
+        "positive finite duration",
+      );
+    },
+  );
+});

package/templates/runtime/export/video-frame-schedule.ts

@@ -0,0 +1,42 @@
+export const TOOLCRAFT_VIDEO_EXPORT_FRAMES_PER_SECOND = 30;
+
+export type ToolcraftVideoFrameScheduleEntry = Readonly<{
+  durationSeconds: number;
+  index: number;
+  timeSeconds: number;
+}>;
+
+const frameCountTolerance = 1e-9;
+
+export function createToolcraftVideoFrameSchedule(
+  durationSeconds: number,
+): readonly ToolcraftVideoFrameScheduleEntry[] {
+  if (!Number.isFinite(durationSeconds) || durationSeconds <= 0) {
+    throw new RangeError("Video export requires a positive finite duration.");
+  }
+
+  const rawFrameCount =
+    durationSeconds * TOOLCRAFT_VIDEO_EXPORT_FRAMES_PER_SECOND;
+  const nearestFrameCount = Math.round(rawFrameCount);
+  const frameCount =
+    Math.abs(rawFrameCount - nearestFrameCount) <= frameCountTolerance
+      ? nearestFrameCount
+      : Math.ceil(rawFrameCount);
+
+  return Object.freeze(
+    Array.from({ length: frameCount }, (_, index) => {
+      const timeSeconds =
+        index / TOOLCRAFT_VIDEO_EXPORT_FRAMES_PER_SECOND;
+      const endSeconds = Math.min(
+        durationSeconds,
+        (index + 1) / TOOLCRAFT_VIDEO_EXPORT_FRAMES_PER_SECOND,
+      );
+
+      return Object.freeze({
+        durationSeconds: endSeconds - timeSeconds,
+        index,
+        timeSeconds,
+      });
+    }),
+  );
+}

package/templates/runtime/index.ts

@@ -12,6 +12,7 @@ export type {
   ToolcraftModelPresentationMode,
 } from "./react/model-rendering/model-render-binding";
 export * from "./schema/define-toolcraft";
+export { TOOLCRAFT_CANVAS_RENDER_SCALE } from "./schema/canvas-render-scale";
 export * from "./schema/keyframe-capability";
 export * from "./schema/runtime-targets";
 export * from "./schema/types";

package/templates/runtime/react/app-shell/runtime-public-api-runtime.test.tsx

@@ -0,0 +1,291 @@
+import {
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { defineToolcraft } from "../../schema/define-toolcraft";
+import type { ToolcraftSourceAssetCoordinator } from "../../source-assets/source-asset-coordinator";
+import { ControlsPanel } from "../controls-panel/controls-panel";
+import { useToolcraftStore } from "./toolcraft-store-context";
+import { ToolcraftRoot } from "./toolcraft-root";
+import { ToolcraftSourceAssetCoordinatorContext } from "./toolcraft-source-asset-context";
+import { runtimePublicApiSchema } from "./runtime-public-api-test-support";
+import {
+  useToolcraft,
+  useToolcraftDispatch,
+  useToolcraftSelector,
+} from "./use-toolcraft";
+
+const runtimePublicApiPanelActionSchema = defineToolcraft({
+  canvas: { enabled: true },
+  panels: {
+    controls: {
+      sections: [
+        {
+          actionGroup: "secondary",
+          controls: {
+            action: {
+              actions: [
+                {
+                  label: "Resolve media",
+                  value: "resolve-media",
+                  variant: "default",
+                },
+              ],
+              target: "panel.actions",
+              type: "panelActions",
+            },
+          },
+        },
+      ],
+      title: "Controls",
+    },
+  },
+});
+
+function createRuntimePublicApiSourceAssetCoordinator(
+  resolveResource?: ToolcraftSourceAssetCoordinator["resolveResource"],
+): ToolcraftSourceAssetCoordinator {
+  const idleOperation = Object.freeze({
+    phase: "idle" as const,
+    target: "source",
+  });
+
+  return {
+    cancelTarget: vi.fn(),
+    clearPresentationFeedback: vi.fn(),
+    dispose: vi.fn(async () => undefined),
+    getOperation: () => idleOperation,
+    getPresentation: () => null,
+    hydrateBinaryMedia: vi.fn(async () => undefined),
+    hydrateModels: vi.fn(async () => undefined),
+    importBatch: vi.fn(async () => ({
+      assetIds: [] as const,
+      kind: "committed" as const,
+    })),
+    repairModel: vi.fn(async () => ({ kind: "cancelled" as const })),
+    reportPresentationFeedback: vi.fn(),
+    ...(resolveResource ? { resolveResource } : {}),
+    subscribe: () => () => undefined,
+  };
+}
+
+afterEach(cleanup);
+
+describe("Toolcraft template runtime public API integration", () => {
+  it("binds the source asset resolver into panel action context", async () => {
+    const bytes = new Uint8Array([11, 22, 33]);
+    const resolveResource = vi.fn<
+      NonNullable<ToolcraftSourceAssetCoordinator["resolveResource"]>
+    >(async () => bytes);
+    const coordinator = createRuntimePublicApiSourceAssetCoordinator(
+      resolveResource,
+    );
+    const signal = new AbortController().signal;
+    let resolvedBytes: Uint8Array | null | undefined;
+
+    render(
+      <ToolcraftRoot schema={runtimePublicApiPanelActionSchema}>
+        <ToolcraftSourceAssetCoordinatorContext.Provider value={coordinator}>
+          <ControlsPanel
+            framed={false}
+            onPanelAction={async ({ resolveMediaResource }) => {
+              resolvedBytes = await resolveMediaResource("media:known", {
+                signal,
+              });
+            }}
+          />
+        </ToolcraftSourceAssetCoordinatorContext.Provider>
+      </ToolcraftRoot>,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "Resolve media" }));
+
+    await waitFor(() => expect(resolvedBytes).toEqual(bytes));
+    expect(resolveResource).toHaveBeenCalledWith("media:known", { signal });
+  });
+
+  it("returns null from panel action media resolution when no resolver exists", async () => {
+    const coordinator = createRuntimePublicApiSourceAssetCoordinator();
+    const signal = new AbortController().signal;
+    let resolvedBytes: Uint8Array | null | undefined;
+
+    render(
+      <ToolcraftRoot schema={runtimePublicApiPanelActionSchema}>
+        <ToolcraftSourceAssetCoordinatorContext.Provider value={coordinator}>
+          <ControlsPanel
+            framed={false}
+            onPanelAction={async ({ resolveMediaResource }) => {
+              resolvedBytes = await resolveMediaResource("media:missing", {
+                signal,
+              });
+            }}
+          />
+        </ToolcraftSourceAssetCoordinatorContext.Provider>
+      </ToolcraftRoot>,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "Resolve media" }));
+
+    await waitFor(() => expect(resolvedBytes).toBeNull());
+  });
+
+  it("keeps broad consumers live while isolating selector and dispatch consumers", () => {
+    const renders = {
+      broad: 0,
+      dispatch: 0,
+      playback: 0,
+      value: 0,
+      viewport: 0,
+    };
+
+    function BroadProbe() {
+      const { state } = useToolcraft();
+
+      renders.broad += 1;
+
+      return <output data-testid="broad-time">{state.timeline.currentTimeSeconds}</output>;
+    }
+
+    function DispatchProbe() {
+      const dispatch = useToolcraftDispatch();
+
+      renders.dispatch += 1;
+
+      return (
+        <button
+          type="button"
+          onClick={() =>
+            dispatch({
+              target: "selectedLayer.opacity",
+              type: "controls.setValue",
+              value: 50,
+            })
+          }
+        >
+          Set value
+        </button>
+      );
+    }
+
+    function ValueProbe() {
+      const value = useToolcraftSelector(
+        (state) => state.values["selectedLayer.opacity"],
+      );
+
+      renders.value += 1;
+
+      return <output data-testid="selected-value">{String(value)}</output>;
+    }
+
+    function PlaybackProbe() {
+      const currentTimeSeconds = useToolcraftSelector(
+        (state) => state.timeline.currentTimeSeconds,
+      );
+
+      renders.playback += 1;
+
+      return <output data-testid="playback-time">{currentTimeSeconds}</output>;
+    }
+
+    function ViewportProbe() {
+      const offset = useToolcraftSelector(
+        (state) => ({ ...state.canvas.offset }),
+        (previous, next) => previous.x === next.x && previous.y === next.y,
+      );
+
+      renders.viewport += 1;
+
+      return <output data-testid="viewport-offset">{offset.x},{offset.y}</output>;
+    }
+
+    function TransientProbe() {
+      const store = useToolcraftStore();
+
+      return (
+        <div>
+          <button
+            type="button"
+            onClick={() =>
+              store.dispatchTransient({
+                currentTimeSeconds: 2,
+                type: "timeline.setCurrentTime",
+              })
+            }
+          >
+            Set playback time
+          </button>
+          <button
+            type="button"
+            onClick={() =>
+              store.dispatchTransient({
+                offset: { x: 0, y: 0 },
+                type: "canvas.setViewport",
+                zoom: 150,
+              })
+            }
+          >
+            Set viewport zoom
+          </button>
+        </div>
+      );
+    }
+
+    render(
+      <ToolcraftRoot schema={runtimePublicApiSchema}>
+        <BroadProbe />
+        <DispatchProbe />
+        <ValueProbe />
+        <PlaybackProbe />
+        <ViewportProbe />
+        <TransientProbe />
+      </ToolcraftRoot>,
+    );
+
+    expect(renders).toEqual({
+      broad: 1,
+      dispatch: 1,
+      playback: 1,
+      value: 1,
+      viewport: 1,
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: "Set value" }));
+
+    expect(screen.getByTestId("selected-value").textContent).toBe("50");
+    expect(renders).toEqual({
+      broad: 2,
+      dispatch: 1,
+      playback: 1,
+      value: 2,
+      viewport: 1,
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: "Set playback time" }));
+
+    expect(screen.getByTestId("broad-time").textContent).toBe("2");
+    expect(screen.getByTestId("playback-time").textContent).toBe("2");
+    expect(renders).toEqual({
+      broad: 3,
+      dispatch: 1,
+      playback: 2,
+      value: 2,
+      viewport: 1,
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: "Set viewport zoom" }));
+
+    expect(screen.getByTestId("viewport-offset").textContent).toBe("0,0");
+    expect(renders).toEqual({
+      broad: 4,
+      dispatch: 1,
+      playback: 2,
+      value: 2,
+      viewport: 1,
+    });
+  });
+});

package/templates/runtime/react/app-shell/runtime-public-api-test-support.ts

@@ -0,0 +1,21 @@
+import { defineToolcraft } from "../../schema/define-toolcraft";
+
+export const runtimePublicApiSchema = defineToolcraft({
+  canvas: { enabled: true },
+  panels: {
+    controls: {
+      sections: [
+        {
+          controls: {
+            opacity: {
+              defaultValue: 75,
+              target: "selectedLayer.opacity",
+              type: "slider",
+            },
+          },
+        },
+      ],
+      title: "Controls",
+    },
+  },
+});