@pixel-point/toolcraft 0.0.16 → 0.0.17

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

@@ -1,19 +1,9 @@
 import type * as React from "react";
-import {
-  cleanup,
-  fireEvent,
-  render,
-  screen,
-  waitFor,
-} from "@testing-library/react";
-import { afterEach } from "vitest";
-import { describe, expect, expectTypeOf, it, vi } from "vitest";
+import { describe, expect, expectTypeOf, it } from "vitest";
 
 import * as ToolcraftRuntime from "../../index";
 import type { ToolcraftHistoryPatch } from "../../index";
 import type { ToolcraftRendererPipelineClient } from "../../rendering";
-import { defineToolcraft } from "../../schema/define-toolcraft";
-import type { ToolcraftSourceAssetCoordinator } from "../../source-assets/source-asset-coordinator";
 import type { ToolcraftCommand } from "../../state/types";
 import * as ToolcraftReact from "../index";
 import {
@@ -32,95 +22,18 @@ import {
   ToolcraftRoot,
   type ToolcraftContextValue,
 } from "./toolcraft-root";
-import { ToolcraftSourceAssetCoordinatorContext } from "./toolcraft-source-asset-context";
+import { runtimePublicApiSchema } from "./runtime-public-api-test-support";
 import { LayersPanel } from "../layers/layers-panel";
 import { PanelContainer, PanelHost, PanelStage } from "../panel-host/panel-host";
 import { TimelinePanel } from "../timeline/timeline-panel";
 import { ToolbarPanel } from "./toolbar-panel";
 import {
-  useToolcraft,
   useToolcraftDispatch,
   useToolcraftSelector,
 } from "./use-toolcraft";
 import { useToolcraftPipeline } from "./use-toolcraft-pipeline";
 import { useToolcraftPipelinePass } from "./use-toolcraft-pipeline-pass";
 
-const runtimePublicApiSchema = defineToolcraft({
-  canvas: { enabled: true },
-  panels: {
-    controls: {
-      sections: [
-        {
-          controls: {
-            opacity: {
-              defaultValue: 75,
-              target: "selectedLayer.opacity",
-              type: "slider",
-            },
-          },
-        },
-      ],
-      title: "Controls",
-    },
-  },
-});
-
-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", () => {
   it("exports selector hooks without exposing the internal store context", () => {
     expect(ToolcraftRuntime).not.toHaveProperty(
@@ -157,6 +70,7 @@ describe("Toolcraft template runtime public API", () => {
     expectTypeOf<keyof ToolcraftAppComposition>().toEqualTypeOf<
       | "canvasContent"
       | "controlRenderers"
+      | "exportRenderer"
       | "modelPresentation"
       | "onPanelAction"
       | "renderDefaultCanvasMedia"
@@ -170,6 +84,7 @@ describe("Toolcraft template runtime public API", () => {
       | "canvasContent"
       | "className"
       | "controlRenderers"
+      | "exportRenderer"
       | "modelPresentation"
       | "onPanelAction"
       | "renderDefaultCanvasMedia"
@@ -193,11 +108,8 @@ describe("Toolcraft template runtime public API", () => {
     expectTypeOf<keyof ToolcraftPanelActionContext>().toEqualTypeOf<
       | "action"
       | "dispatch"
-      | "renderRuntimeSceneToCanvas"
       | "reportFeedback"
-      | "renderModelsToCanvas"
       | "resolveMediaResource"
-      | "resolveSceneExportFrame"
       | "rendererPipeline"
       | "reportProgress"
       | "state"
@@ -238,63 +150,6 @@ describe("Toolcraft template runtime public API", () => {
     >().toEqualTypeOf<RuntimePanelKeys | "groupCreation">();
   });
 
-  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 shell and panel host props separate", () => {
     expectTypeOf<
       keyof React.ComponentProps<typeof CanvasShell>
@@ -380,158 +235,4 @@ describe("Toolcraft template runtime public API", () => {
     expect(toolbarWithThemeToggle).toBeTruthy();
   });
 
-  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/toolcraft-app.scene-export.test.tsx

@@ -1,5 +1,5 @@
-import { cleanup, fireEvent, render, screen } from "@testing-library/react";
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { cleanup, render } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
 
 import { defineToolcraft } from "../../schema/define-toolcraft";
 import { ToolcraftApp } from "./toolcraft-app";
@@ -10,7 +10,7 @@ afterEach(() => {
 });
 
 describe("ToolcraftApp scene export boundary", () => {
-  it("connects product scene bounds directly to infinite export actions", () => {
+  it("fails before mount when a typed product export has no shared renderer", () => {
     const schema = defineToolcraft({
       canvas: {
         enabled: true,
@@ -26,6 +26,7 @@ describe("ToolcraftApp scene export boundary", () => {
                   actions: [
                     {
                       label: "Export image",
+                      role: "export-image",
                       value: "export",
                       variant: "default",
                     },
@@ -40,29 +41,13 @@ describe("ToolcraftApp scene export boundary", () => {
         },
       },
     });
-    const sceneBoundsProvider = vi.fn(() => [
-      { height: 40, width: 80, x: -20, y: 10 },
-    ]);
-    let frame: unknown;
-
-    render(
-      <ToolcraftApp
-        canvasContent={<div data-testid="product-scene" />}
-        onPanelAction={({ resolveSceneExportFrame }) => {
-          frame = resolveSceneExportFrame();
-        }}
-        sceneBoundsProvider={sceneBoundsProvider}
-        schema={schema}
-      />,
-    );
-    expect(screen.getByText("Infinity canvas")).toBeTruthy();
-    fireEvent.click(screen.getByRole("switch"));
-    fireEvent.click(screen.getByRole("button", { name: "Export image" }));
-
-    expect(sceneBoundsProvider).toHaveBeenCalledTimes(1);
-    expect(frame).toEqual({
-      frame: { height: 40, width: 80, x: -20, y: 10 },
-      ok: true,
-    });
+    expect(() =>
+      render(
+        <ToolcraftApp
+          canvasContent={<div data-testid="product-scene" />}
+          schema={schema}
+        />,
+      ),
+    ).toThrow("Product-owned export actions require exportRenderer");
   });
 });

package/templates/runtime/react/app-shell/toolcraft-app.tsx

@@ -9,6 +9,10 @@ import {
   type ToolcraftProductSceneBoundsProvider,
 } from "../../scene";
 import type { ToolcraftState } from "../../state/types";
+import {
+  getToolcraftExportRendererCoverageErrors,
+  type ToolcraftProductExportRenderer,
+} from "../../export";
 import { CanvasShell } from "../canvas/canvas-shell";
 import {
   ControlsPanel,
@@ -28,6 +32,7 @@ import { useToolcraftPersistenceStatus } from "./use-toolcraft-persistence";
 export type ToolcraftAppComposition = {
   canvasContent?: React.ReactNode;
   controlRenderers?: ToolcraftControlRendererMap;
+  exportRenderer?: ToolcraftProductExportRenderer;
   modelPresentation?: ToolcraftModelPresentationMode;
   onPanelAction?: ToolcraftPanelActionHandler;
   renderDefaultCanvasMedia?: boolean;
@@ -122,6 +127,7 @@ function ToolcraftAppContent({
 
 export function ToolcraftApp({
   canvasContent,
+  exportRenderer,
   modelPresentation,
   renderDefaultCanvasMedia = true,
   rendererPipelineRegistration,
@@ -132,12 +138,24 @@ export function ToolcraftApp({
   const suppressedModelTargets = modelPresentation?.mode === "custom"
     ? modelPresentation.consumers.map(({ sourceTarget }) => sourceTarget)
     : [];
+  const productSceneRequired =
+    React.Children.count(canvasContent) > 0 ||
+    rendererPipelineRegistration !== undefined ||
+    suppressedModelTargets.length > 0;
+  const exportRendererErrors = getToolcraftExportRendererCoverageErrors({
+    exportRenderer,
+    productSceneRequired,
+    schema,
+  });
+  if (exportRendererErrors.length > 0) {
+    throw new Error(
+      `Toolcraft export renderer configuration is invalid:\n- ${exportRendererErrors.join("\n- ")}`,
+    );
+  }
   const sceneExport: ToolcraftControlsSceneExport = Object.freeze({
     ...(sceneBoundsProvider ? { boundsProvider: sceneBoundsProvider } : {}),
-    boundsRequired:
-      React.Children.count(canvasContent) > 0 ||
-      rendererPipelineRegistration !== undefined ||
-      suppressedModelTargets.length > 0,
+    ...(exportRenderer ? { exportRenderer } : {}),
+    productSceneRequired,
     visibility: createToolcraftRuntimeSceneVisibility({
       renderDefaultImages: renderDefaultCanvasMedia,
       suppressedModelTargets,

package/templates/runtime/react/app-shell/toolcraft-source-asset-context.test.tsx

@@ -10,66 +10,23 @@ import type { ToolcraftSourceAssetCoordinator } from "../../source-assets/source
 import { useOptionalToolcraftModelRenderHost } from "../model-rendering/model-render-provider";
 import { ToolcraftModelPresentationModeContext } from "../model-rendering/model-presentation-mode";
 import { ToolcraftRoot } from "./toolcraft-root";
+import { ToolcraftSourceAssetProvider } from "./toolcraft-source-asset-context";
 import {
-  ToolcraftSourceAssetProvider,
-  useToolcraftSourceAssetCoordinator,
-} from "./toolcraft-source-asset-context";
+  ToolcraftSourceAssetCoordinatorProbe as CoordinatorProbe,
+  createTestSourceAssetCoordinator as createTestCoordinator,
+  createTestSourceAssetStore as createTestStore,
+} from "./toolcraft-source-asset-test-support";
 
 afterEach(() => {
   cleanup();
   vi.unstubAllGlobals();
 });
 
-function CoordinatorProbe({
-  capture,
-}: {
-  capture: (coordinator: ToolcraftSourceAssetCoordinator) => void;
-}) {
-  capture(useToolcraftSourceAssetCoordinator());
-  return null;
-}
-
 function ModelRenderHostProbe(): React.JSX.Element {
   const host = useOptionalToolcraftModelRenderHost();
   return <span data-testid="model-render-host">{host ? "ready" : "missing"}</span>;
 }
 
-function createTestCoordinator(
-  dispose: ToolcraftSourceAssetCoordinator["dispose"] = vi.fn(
-    async () => undefined,
-  ),
-): ToolcraftSourceAssetCoordinator {
-  const idleOperation = Object.freeze({
-    phase: "idle" as const,
-    target: "source.test",
-  });
-
-  return {
-    cancelTarget: vi.fn(),
-    clearPresentationFeedback: vi.fn(),
-    dispose,
-    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(),
-    subscribe: () => () => undefined,
-  };
-}
-
-function createTestStore() {
-  return createToolcraftExternalStore(
-    createToolcraftState(
-      defineToolcraft({ canvas: { enabled: true, upload: true }, panels: {} }),
-    ),
-  );
-}
-
 describe("Toolcraft source asset provider", () => {
   it("shares one app-owned coordinator and disposes it on unmount", async () => {
     const schema = defineToolcraft({
@@ -108,6 +65,7 @@ describe("Toolcraft source asset provider", () => {
           store={store}
         >
           <CoordinatorProbe capture={(value) => coordinators.push(value)} />
+          <span data-testid="strict-source-asset-child" />
         </ToolcraftSourceAssetProvider>
       </React.StrictMode>,
     );
@@ -116,6 +74,7 @@ describe("Toolcraft source asset provider", () => {
     expect(createCoordinator).toHaveBeenCalledWith(store);
     expect(coordinators.length).toBeGreaterThanOrEqual(2);
     expect(coordinators.every((value) => value === coordinator)).toBe(true);
+    expect(rendered.getByTestId("strict-source-asset-child")).toBeDefined();
 
     rendered.unmount();
     await waitFor(() => expect(coordinator.dispose).toHaveBeenCalledTimes(1));
@@ -420,16 +379,16 @@ describe("Toolcraft source asset provider", () => {
       [new Error("rollback failed")],
       "cleanup failed",
     );
-    const coordinator = createTestCoordinator(
-      vi.fn(async () => Promise.reject(failure)),
-    );
-    const onDisposeError = vi.fn();
+    const coordinator = createTestCoordinator({
+      dispose: vi.fn(async () => Promise.reject(failure)),
+    });
+    const onError = vi.fn();
     const onUnhandledRejection = vi.fn();
     window.addEventListener("unhandledrejection", onUnhandledRejection);
     const rendered = render(
       <ToolcraftSourceAssetProvider
         createCoordinator={() => coordinator}
-        onDisposeError={onDisposeError}
+        onError={onError}
         store={store}
       >
         <CoordinatorProbe capture={() => undefined} />
@@ -437,7 +396,7 @@ describe("Toolcraft source asset provider", () => {
     );
 
     rendered.unmount();
-    await waitFor(() => expect(onDisposeError).toHaveBeenCalledWith(failure));
+    await waitFor(() => expect(onError).toHaveBeenCalledWith(failure));
     await Promise.resolve();
     window.removeEventListener("unhandledrejection", onUnhandledRejection);
 
@@ -448,9 +407,9 @@ describe("Toolcraft source asset provider", () => {
     const failure = new Error("repository owner disposal failed");
     const reportError = vi.fn();
     vi.stubGlobal("reportError", reportError);
-    const coordinator = createTestCoordinator(
-      vi.fn(async () => Promise.reject(failure)),
-    );
+    const coordinator = createTestCoordinator({
+      dispose: vi.fn(async () => Promise.reject(failure)),
+    });
     const rendered = render(
       <ToolcraftSourceAssetProvider
         createCoordinator={() => coordinator}