@pixel-point/toolcraft 0.0.17 → 0.0.19

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-color-values.ts

@@ -24,15 +24,7 @@ export const defaultChannelMixerValues = {
 } satisfies ChannelMixerValues;
 
 export function asColorValue(value: unknown): { hex: string } {
-  if (typeof value === "string") {
-    return { hex: value };
-  }
-
-  if (isRecord(value)) {
-    return { hex: asString(value.hex, "#C1FF00") };
-  }
-
-  return { hex: "#C1FF00" };
+  return { hex: asString(value, "#C1FF00") };
 }
 
 export function asColorOpacityValue(value: unknown): ColorOpacityValue {

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

@@ -22,9 +22,14 @@ export function asRangeInputValue(value: unknown): { end: string; start: string
 
 export function asVectorValue(value: unknown): { x: string; y: string } {
   if (isRecord(value)) {
+    const asVectorComponent = (component: unknown): string =>
+      typeof component === "number" && Number.isFinite(component)
+        ? String(component)
+        : asString(component, "0.00");
+
     return {
-      x: asString(value.x, "0.00"),
-      y: asString(value.y, "0.00"),
+      x: asVectorComponent(value.x),
+      y: asVectorComponent(value.y),
     };
   }
 

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-math.ts

@@ -10,13 +10,17 @@ import {
   scaleOrientationVector,
   type ToolcraftOrientationVector,
 } from "./orientation-quaternion";
+import {
+  readToolcraftOrientationPose,
+  type ToolcraftOrientationPose,
+} from "../../state/orientation-pose";
 
 export { ToolcraftOrientationQuaternion } from "./orientation-quaternion";
-
-export type ToolcraftOrientationPose = Readonly<{
-  position: readonly [number, number, number];
-  up: readonly [number, number, number];
-}>;
+export {
+  DEFAULT_TOOLCRAFT_ORIENTATION_POSE,
+  readToolcraftOrientationPose,
+  type ToolcraftOrientationPose,
+} from "../../state/orientation-pose";
 
 export type ToolcraftOrientationAxis = "+x" | "-x" | "+y" | "-y" | "+z" | "-z";
 
@@ -28,11 +32,6 @@ export type ToolcraftOrientationAxisProjection = {
   y: number;
 };
 
-export const DEFAULT_TOOLCRAFT_ORIENTATION_POSE: ToolcraftOrientationPose = {
-  position: [0, 0, 5],
-  up: [0, 1, 0],
-};
-
 export const TOOLCRAFT_ORIENTATION_AXES: readonly ToolcraftOrientationAxis[] = [
   "+x",
   "-x",
@@ -46,7 +45,6 @@ export const TOOLCRAFT_TURNTABLE_RADIANS_PER_PIXEL = Math.PI / 450;
 export const TOOLCRAFT_ORIENTATION_SMOOTH_VIEW_MS = 200;
 
 const worldUp: ToolcraftOrientationVector = [0, 1, 0];
-const minimumLengthSquared = 1e-12;
 
 const axisVectors: Record<
   ToolcraftOrientationAxis,
@@ -60,64 +58,6 @@ const axisVectors: Record<
   "-z": [0, 0, -1],
 };
 
-function clonePose(pose: ToolcraftOrientationPose): ToolcraftOrientationPose {
-  return {
-    position: [...pose.position],
-    up: [...pose.up],
-  };
-}
-
-function readFiniteTuple(value: unknown): [number, number, number] | null {
-  if (
-    !Array.isArray(value) ||
-    value.length !== 3 ||
-    !value.every((entry) => typeof entry === "number" && Number.isFinite(entry))
-  ) {
-    return null;
-  }
-
-  return [value[0], value[1], value[2]];
-}
-
-function isUsablePose(pose: ToolcraftOrientationPose): boolean {
-  const positionLength = getOrientationVectorLength(pose.position);
-  const upLength = getOrientationVectorLength(pose.up);
-  const crossLength = getOrientationVectorLength(
-    crossOrientationVectors(pose.up, pose.position),
-  );
-
-  return (
-    positionLength * positionLength > minimumLengthSquared &&
-    upLength * upLength > minimumLengthSquared &&
-    crossLength * crossLength > minimumLengthSquared
-  );
-}
-
-export function readToolcraftOrientationPose(
-  value: unknown,
-  fallback: ToolcraftOrientationPose = DEFAULT_TOOLCRAFT_ORIENTATION_POSE,
-): ToolcraftOrientationPose {
-  const safeFallback = isUsablePose(fallback)
-    ? fallback
-    : DEFAULT_TOOLCRAFT_ORIENTATION_POSE;
-
-  if (!value || typeof value !== "object") {
-    return clonePose(safeFallback);
-  }
-
-  const record = value as Record<string, unknown>;
-  const position = readFiniteTuple(record.position);
-  const up = readFiniteTuple(record.up);
-
-  if (!position || !up) {
-    return clonePose(safeFallback);
-  }
-
-  const pose = { position, up };
-
-  return isUsablePose(pose) ? clonePose(pose) : clonePose(safeFallback);
-}
-
 export function getToolcraftOrientationRadius(
   pose: ToolcraftOrientationPose,
 ): number {

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/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

@@ -48,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 {
@@ -158,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",