@pixel-point/toolcraft 0.0.16 → 0.0.18

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,9 @@ 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/collection-item-controls";
+export * from "./schema/control-applicability";
 export * from "./schema/keyframe-capability";
 export * from "./schema/runtime-targets";
 export * from "./schema/types";

package/templates/runtime/model-import/model-import-limits.ts

@@ -1,5 +1,4 @@
 import type {
-  ResolvedToolcraftModelFileDropSchema,
   ToolcraftModelFormat,
   ToolcraftModelFileDropSchema,
   ToolcraftModelImportLimits,
@@ -143,9 +142,21 @@ function normalizeTopologyProfile(
   return normalizedProfile;
 }
 
-export function normalizeToolcraftModelFileDrop(
-  control: ToolcraftModelFileDropSchema,
-): ResolvedToolcraftModelFileDropSchema {
+type NormalizedToolcraftModelFileDropSchema<
+  TControl extends ToolcraftModelFileDropSchema,
+> = Omit<
+  TControl,
+  "modelFormats" | "modelLimits" | "multiple" | "topologyProfile"
+> & {
+  modelFormats: readonly ToolcraftModelFormat[];
+  modelLimits: ToolcraftModelImportLimits;
+  multiple: false;
+  topologyProfile: ToolcraftModelTopologyProfile;
+};
+
+export function normalizeToolcraftModelFileDrop<
+  TControl extends ToolcraftModelFileDropSchema,
+>(control: TControl): NormalizedToolcraftModelFileDropSchema<TControl> {
   const multiple: unknown = control.multiple;
 
   if (multiple !== undefined && multiple !== false) {

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