@pixel-point/toolcraft 0.0.17 → 0.0.19

package/templates/runtime/schema/define-toolcraft.segmented-control-fit.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 
+import type { ToolcraftCollectionItemControlType } from "./collection-item-controls";
 import { defineToolcraft } from "./define-toolcraft";
 import type { ToolcraftControlSchema } from "./types";
 
@@ -39,8 +40,9 @@ function createModeControl(
 }
 
 function createCollectionModeControl(
-  type: string,
+  type: ToolcraftCollectionItemControlType,
   labels: readonly string[],
+  parentType = "collectionActions",
 ): ToolcraftControlSchema {
   return {
     defaultValue: ["default"],
@@ -57,7 +59,7 @@ function createCollectionModeControl(
     label: "Modes",
     minItems: 1,
     target: "appearance.modes",
-    type: "collectionActions",
+    type: parentType,
   };
 }
 
@@ -138,6 +140,22 @@ describe("defineToolcraft segmented control fit", () => {
     expect(control).toEqual(inputSnapshot);
   });
 
+  it("applies segmented item fit validation to sourceCollection", () => {
+    expect(() =>
+      defineToolcraft(
+        createAppSchema(
+          createCollectionModeControl(
+            "segmented",
+            SCREENSHOT_LABELS,
+            "sourceCollection",
+          ),
+        ),
+      ),
+    ).toThrow(
+      /Toolcraft control validation \[segmented-control-fit\] for target "appearance\.modes" itemControl: .*select dropdown/u,
+    );
+  });
+
   it.each(["type", "target"] as const)(
     "preserves required %s validation ownership",
     (fieldName) => {

package/templates/runtime/schema/define-toolcraft.setup-canvas.test.ts

@@ -32,6 +32,7 @@ describe("defineToolcraft runtime setup canvas controls", () => {
 
     expect(canvasSection?.title).toBe("Setup");
     expect(canvasSection?.controls.infinityCanvas).toMatchObject({
+      applicability: { mode: "always", origin: "explicit" },
       defaultValue: false,
       label: "Infinity canvas",
       target: "canvas.infinity",
@@ -52,7 +53,11 @@ describe("defineToolcraft runtime setup canvas controls", () => {
       performanceRole: "workload",
       target: "canvas.aspectRatio",
       type: "aspectRatio",
-      visibleWhen: { equals: false, target: "canvas.infinity" },
+      applicability: {
+        all: [{ equals: false, target: "canvas.infinity" }],
+        mode: "conditional",
+        origin: "explicit",
+      },
     });
     expect(canvasSection?.controls.canvasWidth).toMatchObject({
       defaultValue: 1440,
@@ -60,7 +65,11 @@ describe("defineToolcraft runtime setup canvas controls", () => {
       performanceRole: "workload",
       target: "canvas.size.width",
       type: "text",
-      visibleWhen: { equals: false, target: "canvas.infinity" },
+      applicability: {
+        all: [{ equals: false, target: "canvas.infinity" }],
+        mode: "conditional",
+        origin: "explicit",
+      },
     });
     expect(canvasSection?.controls.canvasHeight).toMatchObject({
       defaultValue: 900,
@@ -68,7 +77,11 @@ describe("defineToolcraft runtime setup canvas controls", () => {
       performanceRole: "workload",
       target: "canvas.size.height",
       type: "text",
-      visibleWhen: { equals: false, target: "canvas.infinity" },
+      applicability: {
+        all: [{ equals: false, target: "canvas.infinity" }],
+        mode: "conditional",
+        origin: "explicit",
+      },
     });
     expect(canvasSection?.layoutGroups).toEqual([
       {

package/templates/runtime/schema/define-toolcraft.source-collection.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+
+import { defineToolcraft } from "./define-toolcraft";
+import type { ToolcraftControlSchema } from "./types";
+
+function createAppSchema(control: ToolcraftControlSchema) {
+  return {
+    canvas: { enabled: false },
+    panels: {
+      controls: {
+        sections: [
+          {
+            controls: { sections: control },
+            title: "Fill Sections",
+          },
+        ],
+        title: "Controls",
+      },
+    },
+  };
+}
+
+function createSourceCollection(
+  overrides: Record<string, unknown> = {},
+): ToolcraftControlSchema {
+  return {
+    defaultValue: [{ hex: "#DFFF1A" }],
+    itemControl: { label: false, type: "color" },
+    itemLabel: "Section",
+    label: "Sections",
+    target: "fills.sections",
+    type: "sourceCollection",
+    ...overrides,
+  } as ToolcraftControlSchema;
+}
+
+describe("defineToolcraft source collection", () => {
+  it("accepts a source-owned collection of built-in item controls", () => {
+    const app = defineToolcraft(createAppSchema(createSourceCollection()));
+    const control = app.panels.controls?.sections.find(
+      (section) => section.title === "Fill Sections",
+    )?.controls.sections;
+
+    expect(control?.type).toBe("sourceCollection");
+    expect(control?.itemControl?.type).toBe("color");
+  });
+
+  it("requires source collections to declare their built-in item control", () => {
+    expect(() =>
+      defineToolcraft(
+        createAppSchema(createSourceCollection({ itemControl: undefined })),
+      ),
+    ).toThrow(
+      /Toolcraft control validation \[source-collection-item-control\] for target "fills\.sections": itemControl is required/u,
+    );
+  });
+
+  it("rejects unsupported collection item controls", () => {
+    const control = createSourceCollection({
+      itemControl: { type: "imaginary" },
+    });
+
+    expect(() => defineToolcraft(createAppSchema(control))).toThrow(
+      /Toolcraft control validation \[collection-item-control\] for target "fills\.sections": unsupported collection item control "imaginary"/u,
+    );
+  });
+
+  it("rejects unsupported collectionActions item controls instead of falling back to text", () => {
+    const control = {
+      ...createSourceCollection(),
+      itemControl: { type: "imaginary" },
+      type: "collectionActions",
+    } as unknown as ToolcraftControlSchema;
+
+    expect(() => defineToolcraft(createAppSchema(control))).toThrow(
+      /Toolcraft control validation \[collection-item-control\] for target "fills\.sections": unsupported collection item control "imaginary"/u,
+    );
+  });
+});

package/templates/runtime/schema/runtime-setup-section.ts

@@ -38,6 +38,11 @@ const finiteCanvasCondition = Object.freeze({
   equals: false,
   target: toolcraftCanvasInfinityTarget,
 });
+const alwaysApplicable = Object.freeze({ mode: "always" as const });
+const finiteCanvasApplicability = Object.freeze({
+  all: [finiteCanvasCondition],
+  mode: "conditional" as const,
+});
 
 type RuntimeSetupControlGroup = {
   controls: ToolcraftControlSectionSchema["controls"];
@@ -146,6 +151,7 @@ function createRenderScaleControl(
   }
 
   return {
+    applicability: alwaysApplicable,
     defaultValue: canvas.renderScale.defaultValue,
     description:
       "Increases raster canvas backing resolution without changing the visible output size.",
@@ -175,6 +181,7 @@ function createInfinityCanvasControl(
   }
 
   return {
+    applicability: alwaysApplicable,
     defaultValue: getToolcraftDefaultCanvasMode(canvas) === "infinite",
     ...(background
       ? {
@@ -199,6 +206,7 @@ function createTimelineExtendedControl(
   }
 
   return {
+    applicability: alwaysApplicable,
     defaultValue: false,
     label: "Timeline",
     target: toolcraftTimelinePanelExtendedTarget,
@@ -230,13 +238,23 @@ function createRuntimeSetupBackgroundControls({
   return {
     controls: {
       ...(includeBackgroundControl
-        ? { includeBackground: includeBackgroundControl }
+        ? {
+            includeBackground: {
+              ...includeBackgroundControl,
+              applicability: alwaysApplicable,
+            },
+          }
         : {}),
       ...(infinityCanvasControl
         ? { infinityCanvas: infinityCanvasControl }
         : {}),
       ...(backgroundColorControl
-        ? { background: backgroundColorControl }
+        ? {
+            background: {
+              ...backgroundColorControl,
+              applicability: alwaysApplicable,
+            },
+          }
         : {}),
     },
     layoutGroups:
@@ -262,6 +280,7 @@ function createFiniteCanvasControls(
   return {
     controls: {
       canvasAspectRatio: {
+        applicability: finiteCanvasApplicability,
         defaultValue: getCanvasAspectRatioDefaultValue(canvas.size),
         label: "Aspect ratio",
         orderRole: "input",
@@ -269,9 +288,9 @@ function createFiniteCanvasControls(
         performanceRole: "workload",
         target: canvasAspectRatioTarget,
         type: "aspectRatio",
-        visibleWhen: finiteCanvasCondition,
       },
       canvasWidth: {
+        applicability: finiteCanvasApplicability,
         defaultValue: canvas.size.width,
         label: "Canvas width",
         orderRole: "input",
@@ -279,9 +298,9 @@ function createFiniteCanvasControls(
         performanceRole: "workload",
         target: canvasSizeControlTargets.width,
         type: "text",
-        visibleWhen: finiteCanvasCondition,
       },
       canvasHeight: {
+        applicability: finiteCanvasApplicability,
         defaultValue: canvas.size.height,
         label: "Canvas height",
         orderRole: "input",
@@ -289,7 +308,6 @@ function createFiniteCanvasControls(
         performanceRole: "workload",
         target: canvasSizeControlTargets.height,
         type: "text",
-        visibleWhen: finiteCanvasCondition,
       },
     },
     layoutGroups: [
@@ -325,6 +343,7 @@ export function createToolcraftRuntimeSetupSection({
   const section: ToolcraftControlSectionSchema & { id: string } = {
     controls: {
       settingsTransfer: {
+        applicability: alwaysApplicable,
         label: false,
         target: settingsTransferTarget,
         type: "settingsTransfer",

package/templates/runtime/schema/types.ts

@@ -3,6 +3,7 @@ import type {
   ToolcraftControlLayoutGroupLayout,
   ToolcraftSectionLayout,
 } from "../contracts/types";
+import type { ToolcraftCollectionItemControlType } from "./collection-item-controls";
 
 export type ToolcraftCanvasSize = {
   height: number;
@@ -276,6 +277,7 @@ export type ToolcraftActionRole =
   | "copy-output"
   | "download-output"
   | "export-image"
+  | "export-svg"
   | "export-video";
 
 export type ToolcraftActionSchema = {
@@ -412,7 +414,7 @@ export type ResolvedToolcraftMediaSchema = {
   defaultAssets: readonly ToolcraftDefaultMediaAssetSchema[];
 };
 
-export type ToolcraftControlConditionSchema = {
+export type ToolcraftControlPredicateSchema = Readonly<{
   equals?: unknown;
   greaterThan?: number;
   greaterThanOrEqual?: number;
@@ -422,7 +424,28 @@ export type ToolcraftControlConditionSchema = {
   notEquals?: unknown;
   oneOf?: readonly unknown[];
   target: string;
-};
+}>;
+
+export type ToolcraftControlConditionSchema =
+  ToolcraftControlPredicateSchema;
+
+export type ToolcraftControlApplicabilitySchema =
+  | Readonly<{ mode: "always" }>
+  | Readonly<{
+      all: readonly ToolcraftControlPredicateSchema[];
+      mode: "conditional";
+    }>;
+
+export type ToolcraftResolvedControlApplicabilitySchema =
+  | Readonly<{
+      mode: "always";
+      origin: "explicit" | "implicit";
+    }>
+  | Readonly<{
+      all: readonly ToolcraftControlPredicateSchema[];
+      mode: "conditional";
+      origin: "explicit" | "legacy";
+    }>;
 
 export type ToolcraftControlDisabledConditionSchema =
   ToolcraftControlConditionSchema;
@@ -434,18 +457,29 @@ export type ToolcraftColorOpacityValueSchema = {
 
 export type ToolcraftCollectionItemControlSchema = {
   commitMode?: "content" | "setting";
+  coordinateMode?: ToolcraftVectorCoordinateMode;
   defaultValue?: unknown;
+  description?: string;
   label?: boolean | string;
   markerCount?: number;
   max?: number;
   min?: number;
   options?: readonly { label: string; value: string }[];
+  performanceReason?: string;
+  performanceRole?: ToolcraftControlPerformanceRole;
+  sliderValueKind?: ToolcraftSliderValueKind;
   step?: number;
-  type: string;
+  type: ToolcraftCollectionItemControlType;
   unit?: string;
   variant?: string;
+  xLabel?: string;
+  yLabel?: string;
 };
 
+export type ToolcraftCollectionItemControlsSchema = Readonly<
+  Record<string, ToolcraftCollectionItemControlSchema>
+>;
+
 export type ToolcraftFontPickerValueSchema = {
   color?: string;
   fontId: string;
@@ -461,7 +495,7 @@ export type ToolcraftCurveInterpolation = "monotone" | "smooth";
 
 export type ToolcraftVectorCoordinateMode = "cartesian" | "screen";
 
-export type ToolcraftControlSchemaBase = {
+type ToolcraftControlSchemaFields = {
   accept?: string;
   actions?: readonly (ToolcraftActionSchema | string)[];
   addLabel?: string;
@@ -476,6 +510,7 @@ export type ToolcraftControlSchemaBase = {
   interpolation?: ToolcraftCurveInterpolation;
   items?: readonly ToolcraftImagePickerItemSchema[];
   itemControl?: ToolcraftCollectionItemControlSchema;
+  itemControls?: ToolcraftCollectionItemControlsSchema;
   itemDefaultValue?: unknown;
   itemLabel?: string;
   keyframeable?: boolean;
@@ -498,11 +533,16 @@ export type ToolcraftControlSchemaBase = {
   unit?: string;
   valueLabel?: string;
   variant?: string;
-  visibleWhen?: ToolcraftControlConditionSchema;
   xLabel?: string;
   yLabel?: string;
 };
 
+export type ToolcraftControlSchemaBase = ToolcraftControlSchemaFields & {
+  applicability?: ToolcraftControlApplicabilitySchema;
+  /** @deprecated Product controls use conditional applicability. */
+  visibleWhen?: ToolcraftControlPredicateSchema;
+};
+
 export type ToolcraftNonModelControlSchema = ToolcraftControlSchemaBase & {
   assetKind?: ToolcraftMediaAssetKind;
   modelFormats?: never;
@@ -525,18 +565,34 @@ export type ToolcraftControlSchema =
   | ToolcraftNonModelControlSchema
   | ToolcraftModelFileDropSchema;
 
+type ToolcraftResolvedControlApplicabilityFields = Readonly<{
+  applicability: ToolcraftResolvedControlApplicabilitySchema;
+}>;
+
+export type ResolvedToolcraftNonModelControlSchema = Omit<
+  ToolcraftNonModelControlSchema,
+  "applicability" | "visibleWhen"
+> &
+  ToolcraftResolvedControlApplicabilityFields;
+
 export type ResolvedToolcraftModelFileDropSchema = Omit<
   ToolcraftModelFileDropSchema,
-  "modelFormats" | "modelLimits" | "multiple" | "topologyProfile"
-> & {
-  modelFormats: readonly ToolcraftModelFormat[];
-  modelLimits: ToolcraftModelImportLimits;
-  multiple: false;
-  topologyProfile: ToolcraftModelTopologyProfile;
-};
+  | "applicability"
+  | "modelFormats"
+  | "modelLimits"
+  | "multiple"
+  | "topologyProfile"
+  | "visibleWhen"
+> &
+  ToolcraftResolvedControlApplicabilityFields & {
+    modelFormats: readonly ToolcraftModelFormat[];
+    modelLimits: ToolcraftModelImportLimits;
+    multiple: false;
+    topologyProfile: ToolcraftModelTopologyProfile;
+  };
 
 export type ResolvedToolcraftControlSchema =
-  | ToolcraftNonModelControlSchema
+  | ResolvedToolcraftNonModelControlSchema
   | ResolvedToolcraftModelFileDropSchema;
 
 export type ToolcraftControlLayoutGroupSchema = {

package/templates/runtime/state/canvas-background-state.ts

@@ -5,21 +5,6 @@ import {
 import type { ResolvedToolcraftAppSchema } from "../schema/types";
 import type { ToolcraftState } from "./types";
 
-function getToolcraftColorHex(value: unknown): string | undefined {
-  const candidate =
-    typeof value === "string"
-      ? value
-      : value !== null &&
-          typeof value === "object" &&
-          "hex" in value &&
-          typeof value.hex === "string"
-        ? value.hex
-        : undefined;
-  const normalized = candidate?.trim();
-
-  return normalized ? normalized : undefined;
-}
-
 export function hasToolcraftRuntimeSetupBackground(
   schema: ResolvedToolcraftAppSchema,
 ): boolean {
@@ -75,5 +60,5 @@ export function getToolcraftRuntimeBackgroundColor(
     ? state.values[background.color.target] ?? background.color.defaultValue
     : undefined;
 
-  return getToolcraftColorHex(value);
+  return typeof value === "string" ? value : undefined;
 }

package/templates/runtime/state/canvas-state.ts

@@ -86,32 +86,44 @@ function parseCanvasAspectRatioString(
   };
 }
 
-export function normalizeToolcraftCanvasAspectRatioValue(
+export function decodeToolcraftCanvasAspectRatioValue(
   value: unknown,
-  fallbackSize: ToolcraftState["canvas"]["size"],
-): ToolcraftCanvasAspectRatioValue {
+): ToolcraftCanvasAspectRatioValue | null {
   if (typeof value === "string") {
-    return parseCanvasAspectRatioString(value) ?? getToolcraftCanvasAspectRatioFromSize(fallbackSize);
+    return parseCanvasAspectRatioString(value);
+  }
+
+  if (!isRecord(value)) {
+    return null;
   }
 
-  if (isRecord(value)) {
-    const width = asToolcraftCanvasSizeDimension(value.width);
-    const height = asToolcraftCanvasSizeDimension(value.height);
-
-    if (width !== null && height !== null) {
-      const rawValue = typeof value.value === "string" ? value.value : `${width}:${height}`;
-      const mode = value.mode === "preset" ? "preset" : "custom";
-
-      return {
-        height,
-        mode,
-        value: mode === "preset" ? rawValue : `${width}:${height}`,
-        width,
-      };
-    }
+  const width = asToolcraftCanvasSizeDimension(value.width);
+  const height = asToolcraftCanvasSizeDimension(value.height);
+
+  if (width === null || height === null) {
+    return null;
   }
 
-  return getToolcraftCanvasAspectRatioFromSize(fallbackSize);
+  const rawValue =
+    typeof value.value === "string" ? value.value : `${width}:${height}`;
+  const mode = value.mode === "preset" ? "preset" : "custom";
+
+  return {
+    height,
+    mode,
+    value: mode === "preset" ? rawValue : `${width}:${height}`,
+    width,
+  };
+}
+
+export function normalizeToolcraftCanvasAspectRatioValue(
+  value: unknown,
+  fallbackSize: ToolcraftState["canvas"]["size"],
+): ToolcraftCanvasAspectRatioValue {
+  return (
+    decodeToolcraftCanvasAspectRatioValue(value) ??
+    getToolcraftCanvasAspectRatioFromSize(fallbackSize)
+  );
 }
 
 export function toolcraftCanvasAspectRatioValuesEqual(

package/templates/runtime/state/control-value-codecs.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from "vitest";
+
+import { TOOLCRAFT_BUILT_IN_CONTROL_TYPES } from "../contracts/component-contracts";
+import {
+  areToolcraftControlValuesEqual,
+  decodeToolcraftBuiltInControlValue,
+  TOOLCRAFT_CONTROL_VALUE_CODEC_REGISTRY,
+} from "./control-value-codecs";
+
+describe("Toolcraft built-in control value codecs", () => {
+  it("canonicalizes Color strings and UI payloads to one string shape", () => {
+    const control = {
+      defaultValue: "#112233",
+      target: "shape.fill",
+      type: "color",
+    } as const;
+
+    expect(decodeToolcraftBuiltInControlValue(control, "#445566")).toEqual({
+      accepted: true,
+      value: "#445566",
+    });
+    expect(
+      decodeToolcraftBuiltInControlValue(control, { hex: "#778899" }),
+    ).toEqual({ accepted: true, value: "#778899" });
+    expect(decodeToolcraftBuiltInControlValue(control, "#abc")).toEqual({
+      accepted: true,
+      value: "#AABBCC",
+    });
+  });
+
+  it("recursively canonicalizes source-owned Color items", () => {
+    const control = {
+      defaultValue: ["#111111"],
+      itemControl: { label: false, type: "color" },
+      target: "fills.items",
+      type: "sourceCollection",
+    } as const;
+
+    expect(
+      decodeToolcraftBuiltInControlValue(control, [
+        { hex: "#222222" },
+        "#333333",
+      ]),
+    ).toEqual({ accepted: true, value: ["#222222", "#333333"] });
+  });
+
+  it("keeps Vector numeric regardless of authored or UI ingress shape", () => {
+    const control = {
+      defaultValue: { x: "0.00", y: "0.00" },
+      type: "vector",
+    } as const;
+
+    expect(
+      decodeToolcraftBuiltInControlValue(control, { x: "1.25", y: -2 }),
+    ).toEqual({ accepted: true, value: { x: 1.25, y: -2 } });
+  });
+
+  it("keeps only declared FileDrop item settings beside mediaId", () => {
+    const control = {
+      defaultValue: [],
+      itemControls: {
+        depth: { defaultValue: 0.2, max: 1, min: 0, type: "slider" },
+        tint: { defaultValue: "#112233", type: "color" },
+      },
+      target: "media.bumpMaps",
+      type: "fileDrop",
+    } as const;
+
+    expect(
+      decodeToolcraftBuiltInControlValue(control, [
+        {
+          depth: 0.6,
+          ignoredBinaryMetadata: "must-not-enter-values",
+          mediaId: "bump-a",
+          tint: { hex: "#445566" },
+        },
+      ]),
+    ).toEqual({
+      accepted: true,
+      value: [{ depth: 0.6, mediaId: "bump-a", tint: "#445566" }],
+    });
+  });
+
+  it("classifies every built-in exactly once", () => {
+    expect(Object.keys(TOOLCRAFT_CONTROL_VALUE_CODEC_REGISTRY).sort()).toEqual(
+      [...TOOLCRAFT_BUILT_IN_CONTROL_TYPES].sort(),
+    );
+  });
+
+  it("compares cloned canonical values structurally", () => {
+    const first = { stops: [{ color: "#FFFFFF", position: "0%" }] };
+    const equal = { stops: [{ color: "#FFFFFF", position: "0%" }] };
+    const changed = { stops: [{ color: "#000000", position: "0%" }] };
+
+    expect(areToolcraftControlValuesEqual(first, equal)).toBe(true);
+    expect(areToolcraftControlValuesEqual(first, changed)).toBe(false);
+  });
+});