@pixel-point/toolcraft 0.0.18 → 0.0.19

package/templates/runtime/state/control-value-normalization.ts

@@ -1,27 +1,32 @@
+import {
+  isToolcraftBuiltInControlType,
+} from "../contracts/component-contracts";
 import {
   getToolcraftCanvasSizeTargetDimension,
+  isToolcraftCanvasAspectRatioTarget,
+  isToolcraftCanvasInfinityTarget,
   isToolcraftTimelinePanelRuntimeTarget,
 } from "../schema/runtime-targets";
 import type {
   ResolvedToolcraftAppSchema,
   ResolvedToolcraftControlSchema,
 } from "../schema/types";
-import { asToolcraftCanvasSizeDimension } from "./canvas-state";
+import {
+  cloneToolcraftJsonValue,
+  decodeToolcraftBuiltInControlDefault,
+  decodeToolcraftBuiltInControlValue,
+  TOOLCRAFT_CONTROL_VALUE_CODEC_REGISTRY,
+  type ToolcraftControlValueDecodeResult,
+} from "./control-value-codecs";
+import {
+  asToolcraftCanvasSizeDimension,
+  decodeToolcraftCanvasAspectRatioValue,
+} from "./canvas-state";
 
 export type ToolcraftNormalizedControlValue =
   | { accepted: true; value: unknown }
   | { accepted: false; fallback: unknown };
 
-function accept(value: unknown): ToolcraftNormalizedControlValue {
-  return { accepted: true, value };
-}
-
-function reject(
-  control: ResolvedToolcraftControlSchema,
-): ToolcraftNormalizedControlValue {
-  return { accepted: false, fallback: control.defaultValue };
-}
-
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -30,17 +35,6 @@ function isFiniteNumber(value: unknown): value is number {
   return typeof value === "number" && Number.isFinite(value);
 }
 
-function isBoundedNumber(
-  control: ResolvedToolcraftControlSchema,
-  value: unknown,
-): value is number {
-  return (
-    isFiniteNumber(value) &&
-    (control.min === undefined || value >= control.min) &&
-    (control.max === undefined || value <= control.max)
-  );
-}
-
 function isJsonValue(value: unknown): boolean {
   if (
     value === null ||
@@ -65,66 +59,56 @@ function matchesDefaultContainer(
   if (defaultValue === undefined) {
     return isJsonValue(candidate);
   }
-
   if (defaultValue === null || typeof defaultValue !== "object") {
     return typeof candidate === typeof defaultValue && isJsonValue(candidate);
   }
-
   if (Array.isArray(defaultValue)) {
     return Array.isArray(candidate) && candidate.every(isJsonValue);
   }
-
   return isRecord(candidate) && isJsonValue(candidate);
 }
 
-function isOptionValue(
+function decodeToolcraftControlCandidate(
   control: ResolvedToolcraftControlSchema,
-  value: unknown,
-): value is string {
-  return (
-    typeof value === "string" &&
-    (control.options ?? []).some((option) => option.value === value)
-  );
-}
+  candidate: unknown,
+): ToolcraftControlValueDecodeResult {
+  if (getToolcraftCanvasSizeTargetDimension(control.target)) {
+    const value = asToolcraftCanvasSizeDimension(candidate);
+    return value === null ? { accepted: false } : { accepted: true, value };
+  }
 
-function isImagePickerValue(
-  control: ResolvedToolcraftControlSchema,
-  value: unknown,
-): value is string {
-  return (
-    typeof value === "string" &&
-    (control.items ?? []).some((item) => item.value === value)
-  );
-}
+  if (isToolcraftCanvasAspectRatioTarget(control.target)) {
+    const value = decodeToolcraftCanvasAspectRatioValue(candidate);
+    return value === null ? { accepted: false } : { accepted: true, value };
+  }
 
-function isStringPair(
-  value: unknown,
-  first: string,
-  second: string,
-): boolean {
-  return (
-    isRecord(value) &&
-    typeof value[first] === "string" &&
-    typeof value[second] === "string"
-  );
+  const builtIn = decodeToolcraftBuiltInControlValue(control, candidate);
+  if (builtIn !== null) {
+    return builtIn;
+  }
+
+  return matchesDefaultContainer(candidate, control.defaultValue)
+    ? { accepted: true, value: cloneToolcraftJsonValue(candidate) }
+    : { accepted: false };
 }
 
-function isFontPickerValue(value: unknown): boolean {
-  if (typeof value === "string") {
-    return value.length > 0;
+export function getCanonicalToolcraftControlDefault(
+  control: ResolvedToolcraftControlSchema,
+): unknown {
+  if (!isToolcraftBuiltInControlType(control.type)) {
+    return cloneToolcraftJsonValue(control.defaultValue);
   }
 
-  if (!isRecord(value) || typeof value.fontId !== "string") {
-    return false;
+  const decoded = isToolcraftCanvasAspectRatioTarget(control.target) ||
+    getToolcraftCanvasSizeTargetDimension(control.target)
+    ? decodeToolcraftControlCandidate(control, control.defaultValue)
+    : decodeToolcraftBuiltInControlDefault(control);
+  if (decoded?.accepted) {
+    return decoded.value;
   }
 
-  return (
-    (value.color === undefined || typeof value.color === "string") &&
-    (value.fontSize === undefined || isFiniteNumber(value.fontSize)) &&
-    (value.fontWeight === undefined || typeof value.fontWeight === "string") &&
-    (value.opacity === undefined ||
-      (isFiniteNumber(value.opacity) && value.opacity >= 0 && value.opacity <= 100)) &&
-    isJsonValue(value)
+  throw new Error(
+    `Invalid defaultValue for ${control.target} (${control.type}).`,
   );
 }
 
@@ -132,76 +116,21 @@ export function normalizeToolcraftControlValue(
   control: ResolvedToolcraftControlSchema,
   candidate: unknown,
 ): ToolcraftNormalizedControlValue {
-  if (getToolcraftCanvasSizeTargetDimension(control.target)) {
-    const dimension = asToolcraftCanvasSizeDimension(candidate);
-
-    return dimension === null ? reject(control) : accept(dimension);
-  }
-
-  let valid: boolean;
-
-  switch (control.type) {
-    case "slider":
-      valid = isBoundedNumber(control, candidate);
-      break;
-    case "rangeSlider":
-      valid =
-        Array.isArray(candidate) &&
-        candidate.length > 0 &&
-        candidate.every((value) => isBoundedNumber(control, value));
-      break;
-    case "switch":
-      valid = typeof candidate === "boolean";
-      break;
-    case "select":
-    case "segmented":
-    case "tabs":
-      valid = isOptionValue(control, candidate);
-      break;
-    case "imagePicker":
-      valid = isImagePickerValue(control, candidate);
-      break;
-    case "text":
-    case "code":
-    case "anchorGrid":
-      valid = typeof candidate === "string";
-      break;
-    case "rangeInput":
-      valid = isStringPair(candidate, "start", "end");
-      break;
-    case "vector":
-      valid = isStringPair(candidate, "x", "y");
-      break;
-    case "color":
-    case "palette":
-      valid =
-        typeof candidate === "string" ||
-        (isRecord(candidate) && typeof candidate.hex === "string");
-      break;
-    case "colorOpacity":
-      valid =
-        isRecord(candidate) &&
-        typeof candidate.hex === "string" &&
-        isFiniteNumber(candidate.opacity) &&
-        candidate.opacity >= 0 &&
-        candidate.opacity <= 100;
-      break;
-    case "fontPicker":
-      valid = isFontPickerValue(candidate);
-      break;
-    case "panelActions":
-    case "settingsTransfer":
-      valid = false;
-      break;
-    default:
-      valid = matchesDefaultContainer(candidate, control.defaultValue);
-      break;
-  }
-
-  return valid ? accept(candidate) : reject(control);
+  const decoded = decodeToolcraftControlCandidate(control, candidate);
+  return decoded.accepted
+    ? decoded
+    : {
+        accepted: false,
+        fallback: getCanonicalToolcraftControlDefault(control),
+      };
 }
 
-export function getToolcraftValueControls(
+const valueControlsBySchema = new WeakMap<
+  ResolvedToolcraftAppSchema,
+  ReadonlyMap<string, ResolvedToolcraftControlSchema>
+>();
+
+function compileToolcraftValueControls(
   schema: ResolvedToolcraftAppSchema,
 ): ReadonlyMap<string, ResolvedToolcraftControlSchema> {
   const controls = new Map<string, ResolvedToolcraftControlSchema>();
@@ -209,9 +138,21 @@ export function getToolcraftValueControls(
   for (const section of schema.panels.controls?.sections ?? []) {
     for (const control of Object.values(section.controls)) {
       if (
-        control.type !== "panelActions" &&
-        control.type !== "settingsTransfer" &&
-        !isToolcraftTimelinePanelRuntimeTarget(control.target)
+        isToolcraftCanvasInfinityTarget(control.target) ||
+        isToolcraftTimelinePanelRuntimeTarget(control.target)
+      ) {
+        continue;
+      }
+
+      const decision = isToolcraftBuiltInControlType(control.type)
+        ? TOOLCRAFT_CONTROL_VALUE_CODEC_REGISTRY[control.type]
+        : null;
+      if (
+        decision === null ||
+        decision.kind === "codec" ||
+        decision.kind === "runtime-owned" ||
+        (decision.kind === "conditional-codec" &&
+          decision.ownsValue(control))
       ) {
         controls.set(control.target, control);
       }
@@ -220,3 +161,54 @@ export function getToolcraftValueControls(
 
   return controls;
 }
+
+export function getToolcraftValueControls(
+  schema: ResolvedToolcraftAppSchema,
+): ReadonlyMap<string, ResolvedToolcraftControlSchema> {
+  const cached = valueControlsBySchema.get(schema);
+  if (cached) {
+    return cached;
+  }
+
+  const controls = compileToolcraftValueControls(schema);
+  valueControlsBySchema.set(schema, controls);
+  return controls;
+}
+
+export function createCanonicalToolcraftControlDefaults(
+  controls: ReadonlyMap<string, ResolvedToolcraftControlSchema>,
+): Record<string, unknown> {
+  return Object.fromEntries(
+    [...controls].map(([target, control]) => [
+      target,
+      getCanonicalToolcraftControlDefault(control),
+    ]),
+  );
+}
+
+export function mergeCanonicalToolcraftInitialValues({
+  controls,
+  defaults,
+  initialValues = {},
+}: {
+  controls: ReadonlyMap<string, ResolvedToolcraftControlSchema>;
+  defaults: Readonly<Record<string, unknown>>;
+  initialValues?: Readonly<Record<string, unknown>>;
+}): Record<string, unknown> {
+  const values = { ...defaults };
+
+  for (const [target, candidate] of Object.entries(initialValues)) {
+    const control = controls.get(target);
+    if (!control) {
+      values[target] = candidate;
+      continue;
+    }
+
+    const normalized = normalizeToolcraftControlValue(control, candidate);
+    values[target] = normalized.accepted
+      ? normalized.value
+      : normalized.fallback;
+  }
+
+  return values;
+}

package/templates/runtime/state/controls-reducer.ts

@@ -12,6 +12,13 @@ import {
   tagToolcraftControlsResetHistoryPatch,
 } from "./history-patch-metadata";
 import { getToolcraftResetMediaPatch } from "./media-state";
+import {
+  areToolcraftControlValuesEqual,
+} from "./control-value-codecs";
+import {
+  getToolcraftValueControls,
+  normalizeToolcraftControlValue,
+} from "./control-value-normalization";
 import type {
   ToolcraftCommand,
   ToolcraftState,
@@ -74,18 +81,34 @@ export function reduceToolcraftControlsCommand(
         };
       }
 
-      if (Object.is(state.values[command.target], command.value)) {
+      const control = getToolcraftValueControls(state.schema).get(
+        command.target,
+      );
+      const normalized = control
+        ? normalizeToolcraftControlValue(control, command.value)
+        : { accepted: true as const, value: command.value };
+
+      if (!normalized.accepted) {
+        return state;
+      }
+
+      if (
+        areToolcraftControlValuesEqual(
+          state.values[command.target],
+          normalized.value,
+        )
+      ) {
         return state;
       }
 
       return commitToolcraftValuePatch(
         state,
         {
-          after: { [command.target]: command.value },
+          after: { [command.target]: normalized.value },
           before: { [command.target]: state.values[command.target] },
           label: command.label ?? command.target,
         },
-        { ...state.values, [command.target]: command.value },
+        { ...state.values, [command.target]: normalized.value },
         {
           group: command.historyGroup,
           mode: command.history,

package/templates/runtime/state/create-template-state.test.ts

@@ -4,6 +4,36 @@ import { defineToolcraft } from "../schema/define-toolcraft";
 import { createToolcraftState } from "./create-template-state";
 
 describe("createToolcraftState", () => {
+  it("canonicalizes Color defaults and seeded legacy UI payloads", () => {
+    const app = defineToolcraft({
+      canvas: { enabled: false },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                fill: {
+                  defaultValue: { hex: "#abc" },
+                  target: "shape.fill",
+                  type: "color",
+                },
+              },
+              title: "Appearance",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+
+    const state = createToolcraftState(app, {
+      values: { "shape.fill": { hex: "#223344" } },
+    });
+
+    expect(state.defaults["shape.fill"]).toBe("#AABBCC");
+    expect(state.values["shape.fill"]).toBe("#223344");
+  });
+
   it("normalizes restored Infinity canvas to finite when Background is off", () => {
     const app = defineToolcraft({
       canvas: {

package/templates/runtime/state/create-template-state.ts

@@ -1,8 +1,7 @@
-import type { ResolvedToolcraftAppSchema } from "../schema/types";
-import {
-  isToolcraftCanvasInfinityTarget,
-  isToolcraftTimelinePanelRuntimeTarget,
-} from "../schema/runtime-targets";
+import type {
+  ResolvedToolcraftAppSchema,
+  ResolvedToolcraftControlSchema,
+} from "../schema/types";
 import type {
   ToolcraftInitialState,
   ToolcraftState,
@@ -22,29 +21,55 @@ import {
   createToolcraftLayersFromMediaAssets,
 } from "./media-defaults";
 import { getMediaReadyTimelineState } from "./timeline-readiness";
+import {
+  cloneToolcraftJsonValue,
+} from "./control-value-codecs";
+import {
+  createCanonicalToolcraftControlDefaults,
+  getToolcraftValueControls,
+  mergeCanonicalToolcraftInitialValues,
+  normalizeToolcraftControlValue,
+} from "./control-value-normalization";
 
 function cloneTimelineKeyframeGroups(
   keyframeGroups: readonly ToolcraftTimelineKeyframeGroup[],
+  controls: ReadonlyMap<string, ResolvedToolcraftControlSchema>,
 ): ToolcraftTimelineKeyframeGroup[] {
   return keyframeGroups.map((group) => ({
     ...group,
-    keyframes: group.keyframes.map((keyframe) => ({
-      ...keyframe,
-      easing:
-        keyframe.easing?.type === "bezier"
-          ? {
-              controlPoints: [...keyframe.easing.controlPoints],
-              type: "bezier",
-            }
-          : keyframe.easing,
-    })),
+    keyframes: group.keyframes.map((keyframe) => {
+      const control = controls.get(group.controlId);
+      const normalized = control
+        ? normalizeToolcraftControlValue(control, keyframe.value)
+        : { accepted: true as const, value: cloneToolcraftJsonValue(keyframe.value) };
+
+      if (!normalized.accepted) {
+        throw new Error(
+          `Invalid seeded keyframe ${keyframe.id} for ${group.controlId} (${control?.type}).`,
+        );
+      }
+
+      return {
+        ...keyframe,
+        easing:
+          keyframe.easing?.type === "bezier"
+            ? {
+                controlPoints: [...keyframe.easing.controlPoints],
+                type: "bezier" as const,
+              }
+            : keyframe.easing,
+        value: normalized.value,
+      };
+    }),
   }));
 }
 
 function createDefaultTimelineState({
+  controls,
   defaultDurationSeconds,
   timeline,
 }: {
+  controls: ReadonlyMap<string, ResolvedToolcraftControlSchema>;
   defaultDurationSeconds: number;
   timeline?: Partial<ToolcraftTimelineState>;
 }): ToolcraftTimelineState {
@@ -56,7 +81,10 @@ function createDefaultTimelineState({
     isPlaying: true,
     selectedKeyframeId: null,
     ...timeline,
-    keyframeGroups: cloneTimelineKeyframeGroups(timeline?.keyframeGroups ?? []),
+    keyframeGroups: cloneTimelineKeyframeGroups(
+      timeline?.keyframeGroups ?? [],
+      controls,
+    ),
   };
 }
 
@@ -64,7 +92,13 @@ export function createToolcraftState(
   schema: ResolvedToolcraftAppSchema,
   initialState: ToolcraftInitialState = {},
 ): ToolcraftState {
-  const defaults: Record<string, unknown> = {};
+  const valueControls = getToolcraftValueControls(schema);
+  const defaults = createCanonicalToolcraftControlDefaults(valueControls);
+  const values = mergeCanonicalToolcraftInitialValues({
+    controls: valueControls,
+    defaults,
+    initialValues: initialState.values,
+  });
   const defaultMediaState = createToolcraftDefaultMediaState(schema);
   const hasInitialMediaAssets = Object.hasOwn(initialState, "mediaAssets");
   const mediaAssets = hasInitialMediaAssets
@@ -81,25 +115,13 @@ export function createToolcraftState(
   const timeline = getMediaReadyTimelineState(
     schema,
     createDefaultTimelineState({
+      controls: valueControls,
       defaultDurationSeconds: schema.panels.timeline?.defaultDurationSeconds ?? 8,
       timeline: initialState.timeline,
     }),
     mediaAssets,
   );
 
-  for (const section of schema.panels.controls?.sections ?? []) {
-    for (const control of Object.values(section.controls)) {
-      if (
-        isToolcraftCanvasInfinityTarget(control.target) ||
-        isToolcraftTimelinePanelRuntimeTarget(control.target)
-      ) {
-        continue;
-      }
-
-      defaults[control.target] = control.defaultValue;
-    }
-  }
-
   const validSectionIds = new Set(
     schema.panels.controls?.sections.map((section) => section.id) ?? [],
   );
@@ -114,7 +136,6 @@ export function createToolcraftState(
     timeline: { offset: { x: 0, y: 0 } },
     toolbar: { offset: { x: 0, y: 0 } },
   };
-  const values = { ...defaults, ...initialState.values };
   const initialCanvas = {
     offset: { x: 0, y: 0 },
     size: schema.canvas.size,

package/templates/runtime/state/orientation-pose.ts

@@ -0,0 +1,80 @@
+export type ToolcraftOrientationPose = Readonly<{
+  position: readonly [number, number, number];
+  up: readonly [number, number, number];
+}>;
+
+export const DEFAULT_TOOLCRAFT_ORIENTATION_POSE: ToolcraftOrientationPose = {
+  position: [0, 0, 5],
+  up: [0, 1, 0],
+};
+
+const minimumLengthSquared = 1e-12;
+
+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 squaredLength = (value: readonly [number, number, number]) =>
+    value[0] * value[0] + value[1] * value[1] + value[2] * value[2];
+  const cross: [number, number, number] = [
+    pose.up[1] * pose.position[2] - pose.up[2] * pose.position[1],
+    pose.up[2] * pose.position[0] - pose.up[0] * pose.position[2],
+    pose.up[0] * pose.position[1] - pose.up[1] * pose.position[0],
+  ];
+
+  return (
+    squaredLength(pose.position) > minimumLengthSquared &&
+    squaredLength(pose.up) > minimumLengthSquared &&
+    squaredLength(cross) > minimumLengthSquared
+  );
+}
+
+export function decodeToolcraftOrientationPose(
+  value: unknown,
+): ToolcraftOrientationPose | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+
+  const record = value as Record<string, unknown>;
+  const position = readFiniteTuple(record.position);
+  const up = readFiniteTuple(record.up);
+
+  if (!position || !up) {
+    return null;
+  }
+
+  const pose = { position, up };
+  return isUsablePose(pose) ? clonePose(pose) : null;
+}
+
+export function readToolcraftOrientationPose(
+  value: unknown,
+  fallback: ToolcraftOrientationPose = DEFAULT_TOOLCRAFT_ORIENTATION_POSE,
+): ToolcraftOrientationPose {
+  return (
+    decodeToolcraftOrientationPose(value) ??
+    decodeToolcraftOrientationPose(fallback) ??
+    clonePose(DEFAULT_TOOLCRAFT_ORIENTATION_POSE)
+  );
+}

package/templates/runtime/state/persistence-control-values.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+
+import { defineToolcraft } from "../schema/define-toolcraft";
+import { createToolcraftState } from "./create-template-state";
+import {
+  createToolcraftPersistenceSnapshot,
+  parseToolcraftPersistenceSnapshot,
+} from "./persistence";
+
+describe("Toolcraft persisted control values", () => {
+  it("canonicalizes legacy Color payloads during restore", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                fill: {
+                  defaultValue: "#112233",
+                  target: "appearance.fill",
+                  type: "color",
+                },
+              },
+            },
+          ],
+          title: "Controls",
+        },
+      },
+      persistence: {
+        include: ["values"],
+        key: "toolcraft:persistence-control-values-test:state:v1",
+        storage: "localStorage",
+        version: 1,
+      },
+    });
+    const snapshot = createToolcraftPersistenceSnapshot(
+      createToolcraftState(schema),
+      schema.persistence,
+    );
+    const legacySnapshot = {
+      ...snapshot,
+      state: {
+        ...snapshot?.state,
+        values: {
+          ...snapshot?.state.values,
+          "appearance.fill": { hex: "#abc" },
+        },
+      },
+    };
+
+    const restored = parseToolcraftPersistenceSnapshot(
+      schema,
+      JSON.stringify(legacySnapshot),
+    );
+
+    expect(restored?.values?.["appearance.fill"]).toBe("#AABBCC");
+  });
+});