@pixel-point/toolcraft 0.0.16 → 0.0.18

package/templates/runtime/react/controls-panel/__tests__/controls-panel.control-visibility.test.tsx

@@ -136,7 +136,7 @@ describe("ControlsPanel conditional control visibility", () => {
     ).toHaveLength(0);
   });
 
-  it("renders only controls that match the current visibleWhen mode", async () => {
+  it("renders only applicable controls and preserves hidden values", async () => {
     const schema = defineToolcraft({
       canvas: { enabled: true },
       panels: {
@@ -145,6 +145,7 @@ describe("ControlsPanel conditional control visibility", () => {
             {
               controls: {
                 identityMode: {
+                  applicability: { mode: "always" },
                   defaultValue: "text",
                   label: "Identity",
                   options: [
@@ -155,24 +156,30 @@ describe("ControlsPanel conditional control visibility", () => {
                   type: "segmented",
                 },
                 partnerName: {
+                  applicability: {
+                    all: [
+                      { equals: "text", target: "coBrand.identityMode" },
+                      { equals: true, target: "coBrand.partnerEnabled" },
+                    ],
+                    mode: "conditional",
+                  },
                   defaultValue: "tRPC",
                   label: "Partner",
                   target: "coBrand.partnerName",
                   type: "text",
-                  visibleWhen: {
-                    equals: "text",
-                    target: "coBrand.identityMode",
-                  },
                 },
                 partnerLogo: {
+                  applicability: {
+                    all: [
+                      { equals: "logo", target: "coBrand.identityMode" },
+                      { equals: true, target: "coBrand.partnerEnabled" },
+                    ],
+                    mode: "conditional",
+                  },
                   defaultValue: "logo.svg",
                   label: "Partner logo",
                   target: "coBrand.partnerLogo",
                   type: "text",
-                  visibleWhen: {
-                    equals: "logo",
-                    target: "coBrand.identityMode",
-                  },
                 },
               },
               title: "Partner Lockup",
@@ -183,7 +190,9 @@ describe("ControlsPanel conditional control visibility", () => {
       },
     });
 
-    renderControlsPanelWithSchema(schema);
+    renderControlsPanelWithSchema(schema, {}, {
+      values: { "coBrand.partnerEnabled": true },
+    });
 
     const partnerInput = screen.getByDisplayValue("tRPC");
 
@@ -208,7 +217,7 @@ describe("ControlsPanel conditional control visibility", () => {
     });
   });
 
-  it("renders count-dependent controls through numeric visibleWhen conditions", () => {
+  it("renders count-dependent controls through numeric applicability", () => {
     const schema = defineToolcraft({
       canvas: { enabled: true },
       panels: {
@@ -217,6 +226,7 @@ describe("ControlsPanel conditional control visibility", () => {
             {
               controls: {
                 shadeCount: {
+                  applicability: { mode: "always" },
                   defaultValue: 2,
                   label: "Shades",
                   max: 5,
@@ -227,30 +237,41 @@ describe("ControlsPanel conditional control visibility", () => {
                   variant: "discrete",
                 },
                 shade1: {
+                  applicability: { mode: "always" },
                   defaultValue: { hex: "#FFFFFF" },
                   label: "Shade 1",
                   target: "shapes.color1",
                   type: "color",
                 },
                 shade2: {
+                  applicability: {
+                    all: [
+                      {
+                        greaterThanOrEqual: 2,
+                        target: "shapes.shadeCount",
+                      },
+                    ],
+                    mode: "conditional",
+                  },
                   defaultValue: { hex: "#DDDDDD" },
                   label: "Shade 2",
                   target: "shapes.color2",
                   type: "color",
-                  visibleWhen: {
-                    greaterThanOrEqual: 2,
-                    target: "shapes.shadeCount",
-                  },
                 },
                 shade3: {
+                  applicability: {
+                    all: [
+                      {
+                        greaterThanOrEqual: 3,
+                        target: "shapes.shadeCount",
+                      },
+                    ],
+                    mode: "conditional",
+                  },
                   defaultValue: { hex: "#BBBBBB" },
                   label: "Shade 3",
                   target: "shapes.color3",
                   type: "color",
-                  visibleWhen: {
-                    greaterThanOrEqual: 3,
-                    target: "shapes.shadeCount",
-                  },
                 },
               },
               title: "Shapes",

package/templates/runtime/react/controls-panel/__tests__/controls-panel.footer-actions.test.tsx

@@ -66,7 +66,7 @@ describe("ControlsPanel footer actions and settings transfer", () => {
     expect(handledActions).toEqual(["download:Generation Controls"]);
   });
 
-  it("exposes the runtime model compositor to product export actions", async () => {
+  it("keeps runtime export mechanics out of generic product action context", () => {
     const schema = defineToolcraft({
       canvas: { enabled: true },
       panels: {
@@ -93,24 +93,19 @@ describe("ControlsPanel footer actions and settings transfer", () => {
         },
       },
     });
-    const canvas = {
-      getContext: vi.fn(() => ({ drawImage: vi.fn() })),
-      height: 1080,
-      width: 1920,
-    } as unknown as HTMLCanvasElement;
-    let renderedModels: Promise<number> | undefined;
+    let actionContextKeys: string[] = [];
 
     renderControlsPanelWithSchema(schema, {
-      onPanelAction: ({ renderModelsToCanvas }) => {
-        renderedModels = renderModelsToCanvas(canvas);
-        return renderedModels;
+      onPanelAction: (context) => {
+        actionContextKeys = Object.keys(context).sort();
       },
     });
 
     fireEvent.click(screen.getByRole("button", { name: "Export PNG" }));
 
-    await expect(renderedModels).resolves.toBe(0);
-    expect(canvas.getContext).toHaveBeenCalledWith("2d");
+    expect(actionContextKeys).not.toContain("renderModelsToCanvas");
+    expect(actionContextKeys).not.toContain("renderRuntimeSceneToCanvas");
+    expect(actionContextKeys).not.toContain("resolveSceneExportFrame");
   });
 
   it("renders runtime settings transfer as a headerless body section instead of sticky footer actions", () => {

package/templates/runtime/react/controls-panel/__tests__/controls-panel.scene-export-actions.test.tsx

@@ -1,4 +1,4 @@
-import { ToolcraftSceneExportError } from "../../../export";
+import { ToolcraftSceneExportError } from "../../../export/export-frame";
 import { defaultToolcraftRuntimeSceneVisibility } from "../../../scene";
 import type { ToolcraftActionSchema } from "../../../schema/types";
 import {
@@ -39,83 +39,6 @@ function createExportSchema(
 }
 
 describe("ControlsPanel scene export actions", () => {
-  it("skips product bounds for finite export and calls them once for infinite export", () => {
-    const schema = createExportSchema();
-    const provider = vi.fn(() => [
-      { height: 10, width: 10, x: 100, y: 50 },
-    ]);
-    let finiteFrame: unknown;
-    const finite = renderControlsPanelWithSchema(schema, {
-      onPanelAction: ({ resolveSceneExportFrame }) => {
-        finiteFrame = resolveSceneExportFrame();
-      },
-      sceneExport: {
-        boundsProvider: provider,
-        boundsRequired: true,
-        visibility: defaultToolcraftRuntimeSceneVisibility,
-      },
-    });
-
-    fireEvent.click(screen.getByRole("button", { name: "Export PNG" }));
-    expect(finiteFrame).toEqual({
-      frame: { height: 180, width: 320, x: 0, y: 0 },
-      ok: true,
-    });
-    expect(provider).not.toHaveBeenCalled();
-    finite.unmount();
-
-    let infiniteFrame: unknown;
-    renderControlsPanelWithSchema(
-      schema,
-      {
-        onPanelAction: ({ resolveSceneExportFrame }) => {
-          infiniteFrame = resolveSceneExportFrame({
-            timeRange: { endSeconds: 8, startSeconds: 0 },
-          });
-        },
-        sceneExport: {
-          boundsProvider: provider,
-          boundsRequired: true,
-          visibility: defaultToolcraftRuntimeSceneVisibility,
-        },
-      },
-      {
-        canvas: { mode: "infinite" },
-        layers: [
-          {
-            displayName: "Image",
-            id: "image-layer",
-            kind: "layer",
-            name: "image",
-            visible: true,
-          },
-        ],
-        mediaAssets: [
-          {
-            assetKind: "image",
-            dataUrl: "data:image/png;base64,test",
-            fileName: "image.png",
-            id: "image",
-            layerId: "image-layer",
-            mimeType: "image/png",
-            position: { x: 0, y: 0 },
-            size: { height: 20, unit: "px", width: 20 },
-          },
-        ],
-      },
-    );
-
-    fireEvent.click(screen.getByRole("button", { name: "Export PNG" }));
-    expect(provider).toHaveBeenCalledTimes(1);
-    expect(provider).toHaveBeenCalledWith(
-      expect.objectContaining({ timeRange: { endSeconds: 8, startSeconds: 0 } }),
-    );
-    expect(infiniteFrame).toEqual({
-      frame: { height: 70, width: 120, x: -10, y: -10 },
-      ok: true,
-    });
-  });
-
   it("shows only feedback reported by the latest panel action", async () => {
     const schema = createExportSchema([
       { label: "First export", value: "first", variant: "secondary" },
@@ -143,17 +66,27 @@ describe("ControlsPanel scene export actions", () => {
   });
 
   it("presents a missing required bounds provider as typed visible feedback", async () => {
+    const onPanelAction = vi.fn();
     renderControlsPanelWithSchema(
-      createExportSchema(),
-      {
-        onPanelAction: ({ reportFeedback, resolveSceneExportFrame }) => {
-          const result = resolveSceneExportFrame();
-          if (!result.ok) reportFeedback(result);
+      createExportSchema([
+        {
+          command: "controls.apply",
+          label: "Export PNG",
+          role: "export-image",
+          value: "export",
+          variant: "default",
         },
+      ]),
+      {
         sceneExport: {
-          boundsRequired: true,
+          exportRenderer: {
+            baseFileName: "scene",
+            renderFrame: vi.fn(),
+          },
+          productSceneRequired: true,
           visibility: defaultToolcraftRuntimeSceneVisibility,
         },
+        onPanelAction,
       },
       { canvas: { mode: "infinite" } },
     );
@@ -164,6 +97,7 @@ describe("ControlsPanel scene export actions", () => {
       "scene-bounds-unavailable",
     );
     expect(alert.textContent).toContain("does not provide export bounds");
+    expect(onPanelAction).not.toHaveBeenCalled();
   });
 
   it("presents rejected typed export failures as visible feedback", async () => {

package/templates/runtime/react/controls-panel/__tests__/controls-panel.source-collection.test.tsx

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+import {
+  defineToolcraft,
+  fireEvent,
+  renderControlsPanelWithSchema,
+  screen,
+} from "../testing/controls-panel-test-utils";
+
+describe("ControlsPanel source collection", () => {
+  it("renders source-sized built-in color controls without cardinality actions", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: false },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                sections: {
+                  defaultValue: [{ hex: "#DFFF1A" }, { hex: "#8CFF3A" }],
+                  itemControl: {
+                    label: "Section",
+                    type: "color",
+                  },
+                  label: "Sections",
+                  target: "fills.sections",
+                  type: "sourceCollection",
+                },
+              },
+              title: "Fill Sections",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    const { container } = renderControlsPanelWithSchema(schema);
+
+    expect(screen.queryByRole("button", { name: /Add/u })).toBeNull();
+    expect(screen.queryByRole("button", { name: /Remove/u })).toBeNull();
+    expect(screen.getByRole("button", { name: "Pick Section 1" })).toBeTruthy();
+    expect(screen.getByRole("textbox", { name: "Section 2 hex" })).toBeTruthy();
+    expect(
+      container.querySelector('[data-slot="source-collection-items-grid"]')
+        ?.children,
+    ).toHaveLength(2);
+
+    const secondColor = screen.getByRole("textbox", { name: "Section 2 hex" });
+
+    fireEvent.change(secondColor, { target: { value: "#123456" } });
+    fireEvent.blur(secondColor);
+
+    const values = JSON.parse(
+      screen.getByTestId("values-json").textContent ?? "{}",
+    );
+
+    expect(values["fills.sections"]).toEqual([
+      { hex: "#DFFF1A" },
+      { hex: "#123456" },
+    ]);
+  });
+});

package/templates/runtime/react/controls-panel/__tests__/controls-panel.source-color-bank.test.tsx

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import {
+  defineToolcraft,
+  fireEvent,
+  renderControlsPanelWithSchema,
+  screen,
+} from "../testing/controls-panel-test-utils";
+
+const sourceColors = Array.from({ length: 19 }, (_, index) => ({
+  hex: index === 18 ? "#654321" : "#DFFF1A",
+}));
+
+describe("ControlsPanel source color bank", () => {
+  it("keeps a source-sized badge palette on built-in color controls", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: false },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                sections: {
+                  defaultValue: sourceColors,
+                  itemControl: {
+                    label: "Section",
+                    type: "color",
+                  },
+                  label: "Sections",
+                  target: "fills.sections",
+                  type: "sourceCollection",
+                },
+              },
+              title: "Fill Sections",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    const { container } = renderControlsPanelWithSchema(schema);
+
+    expect(
+      screen.getAllByRole("button", { name: /^Pick Section \d+$/u }),
+    ).toHaveLength(19);
+    expect(screen.getByRole("button", { name: "Pick Section 19" })).toBeTruthy();
+    expect(screen.queryByRole("button", { name: "Pick Section 20" })).toBeNull();
+    expect(screen.queryByRole("button", { name: /Add/u })).toBeNull();
+    expect(screen.queryByRole("button", { name: /Remove/u })).toBeNull();
+    expect(
+      container.querySelector('[data-slot="source-collection-items-grid"]')
+        ?.children,
+    ).toHaveLength(19);
+
+    const lastColor = screen.getByRole("textbox", { name: "Section 19 hex" });
+    fireEvent.change(lastColor, { target: { value: "#123456" } });
+    fireEvent.blur(lastColor);
+
+    const values = JSON.parse(
+      screen.getByTestId("values-json").textContent ?? "{}",
+    );
+    expect(values["fills.sections"]).toEqual([
+      ...sourceColors.slice(0, 18),
+      { hex: "#123456" },
+    ]);
+  });
+});

package/templates/runtime/react/controls-panel/actions/controls-panel-actions.ts

@@ -2,19 +2,10 @@
 
 import * as React from "react";
 
-import {
-  resolveToolcraftExportFrame,
-  ToolcraftSceneExportError,
-  type ToolcraftExportFrame,
-  type ToolcraftExportFrameResult,
-} from "../../../export";
+import { ToolcraftArtifactExportError } from "../../../export/export-error";
+import { ToolcraftSceneExportError } from "../../../export/export-frame";
 import type { ToolcraftRendererPipelineClient } from "../../../rendering";
-import {
-  defaultToolcraftRuntimeSceneVisibility,
-  resolveToolcraftSceneBounds,
-  type ToolcraftProductSceneBoundsProvider,
-  type ToolcraftRuntimeSceneVisibility,
-} from "../../../scene";
+import { defaultToolcraftRuntimeSceneVisibility } from "../../../scene";
 import type {
   ToolcraftActionCommand,
   ToolcraftActionSchema,
@@ -25,46 +16,31 @@ import type {
 } from "../../../state/types";
 import { getToolcraftCanvasFrame } from "../../../state/canvas-frame";
 import type { ActionControlRunAction } from "../renderers/controls-panel-action-renderer";
-import {
-  renderToolcraftRuntimeSceneToCanvas,
-  type ToolcraftRuntimeSceneExportResult,
-} from "../../canvas/runtime-scene-export";
+import { renderToolcraftRuntimeSceneToCanvas } from "../../canvas/runtime-scene-export";
 import { useToolcraftPipeline } from "../../app-shell/use-toolcraft-pipeline";
 import { useToolcraftSourceAssetCoordinator } from "../../app-shell/toolcraft-source-asset-context";
-import {
-  renderToolcraftModelsToCanvas,
-  type ToolcraftRenderModelsToCanvas,
-} from "../../model-rendering/model-export";
 import { useOptionalToolcraftModelRenderHost } from "../../model-rendering/model-render-provider";
+import {
+  runToolcraftExportAction,
+  type ToolcraftControlsSceneExport,
+} from "./export-action-runner";
+
+export type { ToolcraftControlsSceneExport } from "./export-action-runner";
 
 export type ToolcraftPanelActionFeedback = Readonly<{
   code: string;
   message: string;
 }>;
 
-export type ToolcraftControlsSceneExport = Readonly<{
-  boundsProvider?: ToolcraftProductSceneBoundsProvider;
-  boundsRequired: boolean;
-  visibility: ToolcraftRuntimeSceneVisibility;
-}>;
-
 export type ToolcraftPanelActionContext = {
   action: ToolcraftActionSchema;
   dispatch: React.Dispatch<ToolcraftCommand>;
-  renderRuntimeSceneToCanvas: (
-    canvas: HTMLCanvasElement,
-    frame: ToolcraftExportFrame,
-  ) => Promise<ToolcraftRuntimeSceneExportResult>;
   reportProgress: (progress: number) => void;
   reportFeedback: (feedback: ToolcraftPanelActionFeedback) => void;
-  renderModelsToCanvas: ToolcraftRenderModelsToCanvas;
   resolveMediaResource: (
     resourceRef: string,
     options: Readonly<{ signal: AbortSignal }>,
   ) => Promise<Uint8Array | null>;
-  resolveSceneExportFrame: (options?: Readonly<{
-    timeRange?: Readonly<{ endSeconds: number; startSeconds: number }>;
-  }>) => ToolcraftExportFrameResult;
   rendererPipeline?: ToolcraftRendererPipelineClient | null;
   state: ToolcraftState;
 };
@@ -90,42 +66,10 @@ function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
 function noopReportProgress(): void {}
 
 const defaultSceneExport: ToolcraftControlsSceneExport = Object.freeze({
-  boundsRequired: false,
+  productSceneRequired: false,
   visibility: defaultToolcraftRuntimeSceneVisibility,
 });
 
-function unavailableProductBounds(message: string): ToolcraftExportFrameResult {
-  return { code: "scene-bounds-unavailable", message, ok: false };
-}
-
-function resolveActionSceneExportFrame(
-  sceneExport: ToolcraftControlsSceneExport,
-  state: ToolcraftState,
-  timeRange?: Readonly<{ endSeconds: number; startSeconds: number }>,
-): ToolcraftExportFrameResult {
-  const finiteFrame = resolveToolcraftExportFrame(state, null);
-  if (finiteFrame.ok) return finiteFrame;
-
-  if (sceneExport.boundsRequired && !sceneExport.boundsProvider) {
-    return unavailableProductBounds(
-      "This infinite product scene does not provide export bounds.",
-    );
-  }
-
-  let productRects: unknown = [];
-  try {
-    productRects = sceneExport.boundsProvider?.({ state, timeRange }) ?? [];
-  } catch {
-    return unavailableProductBounds("Product scene bounds could not be resolved.");
-  }
-  const bounds = resolveToolcraftSceneBounds(
-    state,
-    productRects,
-    sceneExport.visibility,
-  );
-  return resolveToolcraftExportFrame(state, bounds);
-}
-
 function clampFooterActionProgress(progress: number): number {
   if (!Number.isFinite(progress)) {
     return 0;
@@ -228,7 +172,10 @@ export function useControlsPanelActions({
 
       void Promise.resolve(result)
         .catch((error: unknown) => {
-          if (error instanceof ToolcraftSceneExportError) {
+          if (
+            error instanceof ToolcraftSceneExportError ||
+            error instanceof ToolcraftArtifactExportError
+          ) {
             reportFeedback(error.feedback);
           } else {
             console.error("Toolcraft panel action failed.", error);
@@ -257,7 +204,11 @@ export function useControlsPanelActions({
         setPanelActionFeedback(feedback);
       }
     };
-    const command = action.command ?? (onPanelAction ? null : getActionCommand(action));
+    const runtimeOwnsExport =
+      action.role === "export-image" || action.role === "export-video";
+    const command = runtimeOwnsExport
+      ? null
+      : action.command ?? (onPanelAction ? null : getActionCommand(action));
 
     if (command) {
       dispatch({ type: command });
@@ -270,36 +221,41 @@ export function useControlsPanelActions({
     const actionState = getState();
     let result: PromiseLike<unknown> | void;
     try {
-      result = onPanelAction?.({
+      const reportProgress =
+        footerActionProgressTracker?.reportProgress ?? noopReportProgress;
+      const exportResult = runToolcraftExportAction({
         action,
-        dispatch,
-        renderRuntimeSceneToCanvas: (canvas, frame) =>
+        renderRuntimeScene: (canvas, frame, state) =>
           renderToolcraftRuntimeSceneToCanvas({
             canvas,
-            canvasFrame: getToolcraftCanvasFrame(actionState.canvas),
+            canvasFrame: getToolcraftCanvasFrame(state.canvas),
             exportFrame: frame,
             host: modelRenderHost,
             resolveImageResource: sourceAssetCoordinator.resolveResource,
-            state: actionState,
+            state,
             visibility: sceneExport.visibility,
           }),
-        reportFeedback,
-        reportProgress:
-          footerActionProgressTracker?.reportProgress ?? noopReportProgress,
-        renderModelsToCanvas: (canvas) =>
-          renderToolcraftModelsToCanvas(modelRenderHost, actionState, canvas),
-        resolveMediaResource,
-        resolveSceneExportFrame: (resolveOptions) =>
-          resolveActionSceneExportFrame(
-            sceneExport,
-            actionState,
-            resolveOptions?.timeRange,
-          ),
         rendererPipeline,
+        reportProgress,
+        sceneExport,
         state: actionState,
       });
+      result =
+        exportResult ??
+        onPanelAction?.({
+          action,
+          dispatch,
+          reportFeedback,
+          reportProgress,
+          resolveMediaResource,
+          rendererPipeline,
+          state: actionState,
+        });
     } catch (error) {
-      if (error instanceof ToolcraftSceneExportError) {
+      if (
+        error instanceof ToolcraftSceneExportError ||
+        error instanceof ToolcraftArtifactExportError
+      ) {
         reportFeedback(error.feedback);
         result = undefined;
       } else {