@pixel-point/toolcraft 0.0.16 → 0.0.18

package/templates/runtime/react/controls-panel/renderers/controls-panel-media-renderer.test.tsx

@@ -52,6 +52,7 @@ describe("controls-panel media renderer", () => {
       dispatchCommand,
       id: "source-model",
       mediaAssets: [],
+      name: "Model",
       sourceAssetCoordinator,
     });
 
@@ -102,6 +103,7 @@ describe("controls-panel media renderer", () => {
           dispatchCommand: vi.fn(),
           id: "source-files",
           mediaAssets: [],
+          name: "Source files",
           sourceAssetCoordinator,
         })}
       </>,
@@ -113,7 +115,75 @@ describe("controls-panel media renderer", () => {
       undefined,
     );
     expect(legacyFileDrop.mock.calls[0]?.[0]).toEqual(
-      expect.objectContaining({ onFolderSelect: undefined }),
+      expect.objectContaining({
+        collectionActions: undefined,
+        onFolderSelect: undefined,
+      }),
+    );
+  });
+
+  it("maps the collection-actions variant to compact FileDrop cardinality controls", () => {
+    const control = {
+      assetKind: "file" as const,
+      itemLabel: "bump map",
+      multiple: true,
+      target: "surface.bumpMaps",
+      type: "fileDrop" as const,
+      variant: "collection-actions",
+    };
+    const operation = { phase: "idle" as const, target: control.target };
+    const presentation = {
+      accept: "image/*",
+      allowsFileBatch: true,
+      allowsFolderSelection: false,
+      emptyDescription: "Drop bump maps",
+      emptyTitle: "Upload bump maps",
+      items: [{
+        assetKind: "file" as const,
+        fileName: "grain.png",
+        id: "bump-grain",
+      }],
+      presenter: "file-list" as const,
+      secondaryActions: [],
+    };
+    const sourceAssetCoordinator = {
+      cancelTarget: vi.fn(),
+      clearPresentationFeedback: vi.fn(),
+      dispose: vi.fn(async () => undefined),
+      getOperation: vi.fn(() => operation),
+      getPresentation: vi.fn(() => presentation),
+      hydrateBinaryMedia: vi.fn(async () => undefined),
+      hydrateModels: vi.fn(async () => undefined),
+      importBatch: vi.fn(),
+      repairModel: vi.fn(),
+      reportPresentationFeedback: vi.fn(),
+      subscribe: () => () => undefined,
+    } satisfies ToolcraftSourceAssetCoordinator;
+
+    render(
+      <>
+        {renderFileDropControl({
+          canvasSize: { height: 720, unit: "px", width: 1280 },
+          control,
+          dispatchCommand: vi.fn(),
+          id: "surface-bump-maps",
+          mediaAssets: [],
+          name: "Bump maps",
+          sourceAssetCoordinator,
+        })}
+      </>,
+    );
+
+    expect(legacyFileDrop.mock.calls[0]?.[0]).toEqual(
+      expect.objectContaining({
+        collectionActions: {
+          addLabel: "Add bump map",
+          canAdd: true,
+          itemLabel: "bump map",
+          name: "Bump maps",
+          removeLabel: "Remove bump map",
+        },
+      }),
     );
   });
 
@@ -157,6 +227,7 @@ describe("controls-panel media renderer", () => {
           dispatchCommand: vi.fn(),
           id: "source-model",
           mediaAssets: [],
+          name: "Model",
           sourceAssetCoordinator,
         })}
       </>,
@@ -226,6 +297,7 @@ describe("controls-panel media renderer", () => {
           dispatchCommand: vi.fn(),
           id: "source-model",
           mediaAssets: [],
+          name: "Model",
           sourceAssetCoordinator,
         })}
       </>,

package/templates/runtime/react/controls-panel/renderers/controls-panel-media-renderer.tsx

@@ -1,5 +1,9 @@
 import * as React from "react";
-import { FileDrop } from "@repo/ui";
+import {
+  FileDrop,
+  type ControlChangeMeta,
+  type FileDropPresentationItem,
+} from "@repo/ui";
 
 import type { ToolcraftCanvasSize, ToolcraftControlSchema } from "../../../schema/types";
 import type { ToolcraftSourceAssetCoordinator } from "../../../source-assets/source-asset-coordinator";
@@ -11,6 +15,7 @@ import type {
 } from "../../../state/types";
 import { useToolcraftMediaPresentationUrls } from "../../app-shell/toolcraft-source-asset-context";
 import { useToolcraftSelector } from "../../app-shell/use-toolcraft";
+import { ControlsPanelFileDropItemControls } from "./controls-panel-file-drop-item-controls";
 
 export type FileDropControlRenderArgs = {
   canvasSize: ToolcraftCanvasSize;
@@ -19,7 +24,15 @@ export type FileDropControlRenderArgs = {
   id: string;
   layerSelectionEnabled?: boolean;
   mediaAssets: readonly ToolcraftMediaAsset[];
+  name: string;
+  setControlValue?: (
+    target: string,
+    value: unknown,
+    label?: string,
+    meta?: ControlChangeMeta,
+  ) => void;
   sourceAssetCoordinator: ToolcraftSourceAssetCoordinator;
+  value?: unknown;
 };
 
 const IMAGE_TRANSFORM_OPERATIONS = new Set<ToolcraftMediaTransformOperation>([
@@ -43,8 +56,11 @@ function FileDropControlRenderer({
   id,
   layerSelectedImageAsset = null,
   mediaAssets,
+  name,
+  setControlValue = () => undefined,
   sourceAssetCoordinator,
   suppressMediaCollection = false,
+  value,
 }: Omit<
   FileDropControlRenderArgs,
   "canvasSize" | "layerSelectionEnabled"
@@ -112,6 +128,10 @@ function FileDropControlRenderer({
         ? { ...basePresentation, secondaryActions: [] }
         : basePresentation
     : null;
+  const usesCollectionActions = control.variant === "collection-actions";
+  const canAddCollectionItem =
+    typeof control.hardMaxItems !== "number" ||
+    (basePresentation?.items.length ?? 0) < control.hardMaxItems;
 
   React.useEffect(() => {
     if (selectedMediaId && !previewMediaIds.includes(selectedMediaId)) {
@@ -156,6 +176,35 @@ function FileDropControlRenderer({
 
   return (
     <FileDrop
+      collectionActions={
+        usesCollectionActions
+          ? {
+              addLabel: control.addLabel ?? `Add ${control.itemLabel ?? "file"}`,
+              canAdd: canAddCollectionItem,
+              itemLabel: control.itemLabel ?? "file",
+              name,
+              removeLabel:
+                control.removeLabel ?? `Remove ${control.itemLabel ?? "file"}`,
+              ...(control.itemControls
+                ? {
+                    renderItemContent: (
+                      item: FileDropPresentationItem,
+                      index: number,
+                    ) => (
+                      <ControlsPanelFileDropItemControls
+                        control={control}
+                        index={index}
+                        mediaId={item.id}
+                        name={name}
+                        setControlValue={setControlValue}
+                        value={value}
+                      />
+                    ),
+                  }
+                : {}),
+            }
+          : undefined
+      }
       key={id}
       onAction={
         activeImageId

package/templates/runtime/react/controls-panel/renderers/controls-panel-renderer-registry.test.ts

@@ -30,7 +30,7 @@ describe("Toolcraft controls-panel renderer registry", () => {
       "canvas-handle": [],
       collection: ["value"],
       compound: ["value"],
-      media: ["canvas.size", "mediaAssets"],
+      media: ["canvas.size", "mediaAssets", "value"],
       settings: [],
     } as const;
 

package/templates/runtime/react/controls-panel/renderers/controls-panel-renderer-registry.ts

@@ -23,7 +23,7 @@ export const TOOLCRAFT_CONTROL_RENDERER_STATE_DEPENDENCIES = {
   "canvas-handle": [],
   collection: ["value"],
   compound: ["value"],
-  media: ["canvas.size", "mediaAssets"],
+  media: ["canvas.size", "mediaAssets", "value"],
   settings: [],
 } as const satisfies Record<
   ToolcraftControlRendererKind,
@@ -38,6 +38,7 @@ export const TOOLCRAFT_CONTROL_RENDERER_REGISTRY = {
   checkbox: "basic",
   code: "basic",
   collectionActions: "collection",
+  sourceCollection: "collection",
   color: "compound",
   colorOpacity: "compound",
   curves: "compound",

package/templates/runtime/react/controls-panel/values/controls-panel-collection-values.ts

@@ -1,8 +1,18 @@
+import type { ToolcraftCollectionItemControlType } from "../../../schema/collection-item-controls";
 import type { ToolcraftControlSchema } from "../../../schema/types";
 import { asFontPickerValue } from "./controls-panel-font-values";
 import { asNumber } from "./controls-panel-value-primitives";
 
-export function asCollectionItems(value: unknown, fallback: unknown): unknown[] {
+function assertNeverCollectionItemControl(value: never): never {
+  throw new Error(
+    `Unsupported Toolcraft collection item control: ${String(value)}`,
+  );
+}
+
+export function asCollectionItems(
+  value: unknown,
+  fallback: unknown,
+): unknown[] {
   if (Array.isArray(value)) {
     return [...value];
   }
@@ -17,18 +27,25 @@ export function getCollectionMinItems(control: ToolcraftControlSchema): number {
 export function getCollectionHardMaxItems(
   control: ToolcraftControlSchema,
 ): number | null {
-  if (typeof control.hardMaxItems !== "number" || !Number.isFinite(control.hardMaxItems)) {
+  if (
+    typeof control.hardMaxItems !== "number" ||
+    !Number.isFinite(control.hardMaxItems)
+  ) {
     return null;
   }
 
   return Math.max(0, Math.floor(control.hardMaxItems));
 }
 
-export function getCollectionItemType(control: ToolcraftControlSchema): string {
+export function getCollectionItemType(
+  control: ToolcraftControlSchema,
+): ToolcraftCollectionItemControlType {
   return control.itemControl?.type ?? "color";
 }
 
-export function getCollectionItemBaseLabel(control: ToolcraftControlSchema): string {
+export function getCollectionItemBaseLabel(
+  control: ToolcraftControlSchema,
+): string {
   if (control.itemLabel) {
     return control.itemLabel;
   }
@@ -54,6 +71,15 @@ export function getCollectionItemName(
 export function getCollectionItemDefaultValue(
   control: ToolcraftControlSchema,
 ): unknown {
+  if (control.itemControls) {
+    return Object.fromEntries(
+      Object.entries(control.itemControls).map(([id, itemControl]) => [
+        id,
+        itemControl.defaultValue,
+      ]),
+    );
+  }
+
   if ("itemDefaultValue" in control) {
     return control.itemDefaultValue;
   }
@@ -62,7 +88,9 @@ export function getCollectionItemDefaultValue(
     return control.itemControl.defaultValue;
   }
 
-  switch (getCollectionItemType(control)) {
+  const itemType = getCollectionItemType(control);
+
+  switch (itemType) {
     case "color":
       return { hex: "#C1FF00" };
     case "colorOpacity":
@@ -74,6 +102,8 @@ export function getCollectionItemDefaultValue(
       return false;
     case "rangeInput":
       return { end: "100%", start: "0%" };
+    case "rangeSlider":
+      return [control.itemControl?.min ?? 0, control.itemControl?.max ?? 100];
     case "select":
     case "segmented":
       return control.itemControl?.options?.[0]?.value ?? "";
@@ -81,7 +111,9 @@ export function getCollectionItemDefaultValue(
       return control.itemControl?.min ?? 0;
     case "text":
       return "";
+    case "vector":
+      return { x: "0", y: "0" };
     default:
-      return "";
+      return assertNeverCollectionItemControl(itemType);
   }
 }

package/templates/runtime/react/controls-panel/values/controls-panel-value-labels.ts

@@ -38,6 +38,7 @@ export function formatControlValueLabel(
       return `${colorOpacityValue.hex} ${colorOpacityValue.opacity}%`;
     }
     case "collectionActions":
+    case "sourceCollection":
       return `${asCollectionItems(value, control.defaultValue).length} items`;
     case "fontPicker":
       return asFontPickerValue(value).fontId;

package/templates/runtime/react/index.ts

@@ -6,6 +6,10 @@ export { useToolcraftMediaPresentationUrls } from "./app-shell/toolcraft-media-p
 export * from "./app-shell/use-toolcraft-pipeline";
 export * from "./app-shell/use-toolcraft-pipeline-pass";
 export * from "./canvas/canvas-shell";
+export {
+  useToolcraftProductSceneFrame,
+  type ToolcraftProductSceneFrame,
+} from "./canvas/product-scene-surface";
 export * from "./controls-panel/control-renderers";
 export * from "./controls-panel/controls-panel";
 export * from "./layers/layers-panel";

package/templates/runtime/react/model-rendering/model-export.ts

@@ -2,7 +2,7 @@ import {
   resolveToolcraftExportFrame,
   ToolcraftSceneExportError,
   type ToolcraftExportFrame,
-} from "../../export";
+} from "../../export/export-frame";
 import { getToolcraftCanvasFrame, type ToolcraftCanvasFrame } from "../../state/canvas-frame";
 import type { ToolcraftState } from "../../state/types";
 import { getSceneElementPresentationRect } from "../canvas/scene-element-presentation-rect";

package/templates/runtime/react/orientation-gizmo/orientation-gizmo-selection.ts

@@ -1,6 +1,6 @@
 import type {
-  ToolcraftControlSchema,
-  ToolcraftControlSectionSchema,
+  ResolvedToolcraftControlSchema,
+  ResolvedToolcraftControlSectionSchema,
 } from "../../schema/types";
 import type { ToolcraftState } from "../../state/types";
 import {
@@ -9,13 +9,13 @@ import {
 } from "../controls-panel/conditions/control-conditions";
 
 export type ToolcraftOrientationControlEntry = {
-  control: ToolcraftControlSchema;
+  control: ResolvedToolcraftControlSchema;
   id: string;
-  section: ToolcraftControlSectionSchema;
+  section: ResolvedToolcraftControlSectionSchema;
 };
 
 export function getToolcraftOrientationControlEntries(
-  sections: readonly ToolcraftControlSectionSchema[],
+  sections: readonly ResolvedToolcraftControlSectionSchema[],
 ): ToolcraftOrientationControlEntry[] {
   return sections.flatMap((section) =>
     Object.entries(section.controls).flatMap(([id, control]) =>

package/templates/runtime/react/orientation-gizmo/use-toolcraft-orientation-control-selection.ts

@@ -2,7 +2,7 @@
 
 import * as React from "react";
 
-import type { ToolcraftControlSchema } from "../../schema/types";
+import type { ResolvedToolcraftControlSchema } from "../../schema/types";
 import type { ToolcraftStoreDependency } from "../../state/toolcraft-external-store-dependencies";
 import type { ToolcraftState } from "../../state/types";
 import { useToolcraftDependencySelector } from "../app-shell/toolcraft-selectors";
@@ -18,7 +18,7 @@ import {
 } from "./orientation-gizmo-selection";
 
 export type ToolcraftOrientationControlSelection = Readonly<{
-  control: ToolcraftControlSchema | null;
+  control: ResolvedToolcraftControlSchema | null;
   id: string | null;
   value: unknown;
 }>;

package/templates/runtime/react/panel-host/panel-host-runtime-placement.test.tsx

@@ -195,4 +195,34 @@ describe("ToolcraftPanelHost runtime placement", () => {
       );
     });
   });
+
+  it("keeps the CSS-anchored default placement during viewport resize", async () => {
+    const { container } = renderToolbar();
+    const host = container.querySelector<HTMLElement>(
+      "[data-slot='toolcraft-runtime-panel-host']",
+    );
+
+    if (!host) {
+      throw new Error("Expected the toolbar panel host to render.");
+    }
+    vi.spyOn(host, "getBoundingClientRect").mockReturnValue({
+      bottom: 900,
+      height: 100,
+      left: 1_500,
+      right: 1_700,
+      top: 800,
+      width: 200,
+      x: 1_500,
+      y: 800,
+      toJSON: () => ({}),
+    });
+
+    fireEvent(window, new Event("resize"));
+
+    await waitFor(() => {
+      expect(screen.getByTestId("toolbar-placement").textContent).toBe(
+        "0,0,free",
+      );
+    });
+  });
 });

package/templates/runtime/react/panel-host/panel-host.tsx

@@ -191,6 +191,10 @@ function usePanelSnapControls({
         return;
       }
 
+      if (x.get() === 0 && y.get() === 0 && snapEdge === undefined) {
+        return;
+      }
+
       const currentPlacement = {
         offset: { x: x.get(), y: y.get() },
         ...(snapEdge ? { snapEdge } : {}),

package/templates/runtime/scene/scene-bounds.test.ts

@@ -6,6 +6,7 @@ import { createToolcraftState } from "../state/create-template-state";
 import {
   getToolcraftSceneElementRect,
   outwardRoundToolcraftSceneRect,
+  resolveToolcraftProductSceneBounds,
   resolveToolcraftSceneBounds,
   unionToolcraftSceneRects,
 } from "./scene-bounds";
@@ -17,6 +18,28 @@ function emptyState() {
 }
 
 describe("scene bounds", () => {
+  it("resolves one exact product frame before runtime contributors are added", () => {
+    expect(
+      resolveToolcraftProductSceneBounds([
+        { height: 20, width: 40, x: -10, y: -5 },
+        { height: 30, width: 10, x: 35, y: 15 },
+      ]),
+    ).toEqual({
+      bounds: { height: 50, width: 55, x: -10, y: -5 },
+      ok: true,
+    });
+    expect(resolveToolcraftProductSceneBounds([])).toMatchObject({
+      code: "empty-scene",
+      ok: false,
+    });
+    expect(
+      resolveToolcraftProductSceneBounds([
+        { height: 20, width: 40, x: -10, y: -5 },
+        { height: 30, width: Number.NaN, x: 35, y: 15 },
+      ]),
+    ).toMatchObject({ code: "scene-bounds-unavailable", ok: false });
+  });
+
   it("projects center-anchored frames and unions negative coordinates", () => {
     expect(
       getToolcraftSceneElementRect({

package/templates/runtime/scene/scene-bounds.ts

@@ -36,8 +36,7 @@ export function createToolcraftRuntimeSceneVisibility(
 
 export type ToolcraftProductSceneBoundsProvider = (
   context: Readonly<{
-    state: ToolcraftState;
-    timeRange?: Readonly<{ endSeconds: number; startSeconds: number }>;
+    state: Readonly<ToolcraftState>;
   }>,
 ) => readonly ToolcraftSceneRect[];
 
@@ -49,6 +48,18 @@ export type ToolcraftSceneBoundsResult =
       ok: false;
     }>;
 
+const emptySceneBoundsResult: ToolcraftSceneBoundsResult = Object.freeze({
+  code: "empty-scene",
+  message: "The scene has no visible exportable elements.",
+  ok: false,
+});
+
+const unavailableSceneBoundsResult: ToolcraftSceneBoundsResult = Object.freeze({
+  code: "scene-bounds-unavailable",
+  message: "Product scene bounds are unavailable or invalid.",
+  ok: false,
+});
+
 export function getToolcraftSceneElementRect(
   element: ToolcraftSceneElementFrame,
 ): ToolcraftSceneRect {
@@ -159,32 +170,34 @@ export function outwardRoundToolcraftSceneRect(
   };
 }
 
-export function resolveToolcraftSceneBounds(
-  state: ToolcraftState,
-  productRects: unknown = [],
-  visibility: ToolcraftRuntimeSceneVisibility = defaultToolcraftRuntimeSceneVisibility,
+export function resolveToolcraftProductSceneBounds(
+  productRects: unknown,
 ): ToolcraftSceneBoundsResult {
   if (
     !Array.isArray(productRects) ||
     !productRects.every(isFiniteSceneRect)
   ) {
-    return {
-      code: "scene-bounds-unavailable",
-      message: "Product scene bounds are unavailable or invalid.",
-      ok: false,
-    };
+    return unavailableSceneBoundsResult;
+  }
+
+  const bounds = unionToolcraftSceneRects(productRects);
+  return bounds ? { bounds, ok: true } : emptySceneBoundsResult;
+}
+
+export function resolveToolcraftSceneBounds(
+  state: ToolcraftState,
+  productRects: unknown = [],
+  visibility: ToolcraftRuntimeSceneVisibility = defaultToolcraftRuntimeSceneVisibility,
+): ToolcraftSceneBoundsResult {
+  const productBounds = resolveToolcraftProductSceneBounds(productRects);
+  if (!productBounds.ok && productBounds.code === "scene-bounds-unavailable") {
+    return productBounds;
   }
 
   const bounds = unionToolcraftSceneRects([
     ...getRuntimeSceneRects(state, visibility),
-    ...productRects,
+    ...(productBounds.ok ? [productBounds.bounds] : []),
   ]);
 
-  return bounds
-    ? { bounds, ok: true }
-    : {
-        code: "empty-scene",
-        message: "The scene has no visible exportable elements.",
-        ok: false,
-      };
+  return bounds ? { bounds, ok: true } : emptySceneBoundsResult;
 }

package/templates/runtime/schema/app-capabilities.test.ts

@@ -45,6 +45,10 @@ describe("resolveToolcraftAppCapabilities", () => {
               {
                 controls: {
                   source: {
+                    applicability: {
+                      mode: "always",
+                      origin: "implicit",
+                    },
                     assetKind: "file",
                     target: "source.files",
                     type: "fileDrop",

package/templates/runtime/schema/canvas-render-scale.ts

@@ -0,0 +1,62 @@
+import type {
+  ResolvedToolcraftCanvasRenderScaleSchema,
+  ToolcraftCanvasRenderScaleSchema,
+} from "./types";
+
+export const TOOLCRAFT_CANVAS_RENDER_SCALE = Object.freeze({
+  defaultValue: 2,
+  max: 2,
+  min: 1,
+  step: 0.25,
+});
+
+const minimumCanvasRenderScaleStep = 0.01;
+const canvasRenderScaleStepTolerance = 1e-9;
+
+function resolveCanvasRenderScaleStep(value: number | undefined): number {
+  if (value === undefined) {
+    return TOOLCRAFT_CANVAS_RENDER_SCALE.step;
+  }
+
+  const maximumCanvasRenderScaleStep =
+    TOOLCRAFT_CANVAS_RENDER_SCALE.max - TOOLCRAFT_CANVAS_RENDER_SCALE.min;
+
+  if (
+    typeof value !== "number" ||
+    !Number.isFinite(value) ||
+    value < minimumCanvasRenderScaleStep ||
+    value > maximumCanvasRenderScaleStep
+  ) {
+    throw new Error(
+      "Canvas render scale step must be a finite value between 0.01 and 1.",
+    );
+  }
+
+  const stepCount = maximumCanvasRenderScaleStep / value;
+
+  if (Math.abs(stepCount - Math.round(stepCount)) > canvasRenderScaleStepTolerance) {
+    throw new Error("Canvas render scale step must divide the canonical range exactly.");
+  }
+
+  return value;
+}
+
+export function resolveToolcraftCanvasRenderScale(
+  renderScale: ToolcraftCanvasRenderScaleSchema | undefined,
+): ResolvedToolcraftCanvasRenderScaleSchema {
+  if (!renderScale) {
+    return {
+      ...TOOLCRAFT_CANVAS_RENDER_SCALE,
+      enabled: false,
+    };
+  }
+
+  return {
+    ...TOOLCRAFT_CANVAS_RENDER_SCALE,
+    enabled: true,
+    step:
+      renderScale === true
+        ? TOOLCRAFT_CANVAS_RENDER_SCALE.step
+        : resolveCanvasRenderScaleStep(renderScale.step),
+  };
+}

package/templates/runtime/schema/collection-item-controls.ts

@@ -0,0 +1,29 @@
+export const TOOLCRAFT_COLLECTION_ITEM_CONTROL_TYPES = [
+  "checkbox",
+  "color",
+  "colorOpacity",
+  "fontPicker",
+  "rangeInput",
+  "rangeSlider",
+  "segmented",
+  "select",
+  "slider",
+  "switch",
+  "text",
+  "vector",
+] as const;
+
+export type ToolcraftCollectionItemControlType =
+  (typeof TOOLCRAFT_COLLECTION_ITEM_CONTROL_TYPES)[number];
+
+const toolcraftCollectionItemControlTypes = new Set<string>(
+  TOOLCRAFT_COLLECTION_ITEM_CONTROL_TYPES,
+);
+
+export function isToolcraftCollectionItemControlType(
+  value: unknown,
+): value is ToolcraftCollectionItemControlType {
+  return (
+    typeof value === "string" && toolcraftCollectionItemControlTypes.has(value)
+  );
+}