@pixel-point/toolcraft 0.0.15 → 0.0.17

package/templates/runtime/state/persistence-reader-media.ts

@@ -1,73 +1,332 @@
-import { isToolcraftPersistenceRecord } from "./persistence-shared";
+import type {
+  ToolcraftModelAnalysisSummary,
+  ToolcraftModelDiagnostic,
+} from "../model-import/model-import-types";
+import type { ToolcraftSourceAssetFeedback } from "../source-assets/source-asset-types";
+import { createToolcraftDataUrlResourceRef } from "../source-assets/media-resource-ref";
 import { readCanvasSize, readPoint } from "./persistence-reader-primitives";
-import type { ToolcraftMediaAsset } from "./types";
+import {
+  isToolcraftFiniteNumber,
+  isToolcraftPersistenceRecord,
+} from "./persistence-shared";
+import type {
+  ToolcraftFileAsset,
+  ToolcraftImageAsset,
+  ToolcraftMediaAsset,
+  ToolcraftMediaTransform,
+  ToolcraftModelAsset,
+} from "./types";
+import { normalizeToolcraftSceneElementFrame } from "./scene-element-frame";
 
-function readMediaAsset(value: unknown): ToolcraftMediaAsset | undefined {
+type PersistedMediaBase = Pick<
+  ToolcraftMediaAsset,
+  "fileName" | "id" | "layerId" | "mimeType"
+> & {
+  sourceTarget?: string;
+};
+
+const diagnosticSeverities = new Set<ToolcraftModelDiagnostic["severity"]>([
+  "fatal",
+  "info",
+  "repairable",
+  "warning",
+]);
+const feedbackCategories = new Set<ToolcraftSourceAssetFeedback["category"]>([
+  "bundle",
+  "format",
+  "geometry",
+  "repair",
+  "resource-limit",
+  "resource-unavailable",
+  "topology",
+]);
+
+function readMediaBase(value: Record<string, unknown>): PersistedMediaBase | undefined {
   if (
-    !isToolcraftPersistenceRecord(value) ||
     typeof value.id !== "string" ||
     typeof value.layerId !== "string" ||
-    typeof value.dataUrl !== "string" ||
     typeof value.fileName !== "string" ||
     typeof value.mimeType !== "string"
   ) {
     return undefined;
   }
 
+  return {
+    fileName: value.fileName,
+    id: value.id,
+    layerId: value.layerId,
+    mimeType: value.mimeType,
+    ...(typeof value.sourceTarget === "string"
+      ? { sourceTarget: value.sourceTarget }
+      : {}),
+  };
+}
+
+function readMediaTransform(value: unknown): ToolcraftMediaTransform | undefined {
+  if (!isToolcraftPersistenceRecord(value)) {
+    return undefined;
+  }
+
+  const transform: ToolcraftMediaTransform = {};
+
+  if (typeof value.flipHorizontal === "boolean") {
+    transform.flipHorizontal = value.flipHorizontal;
+  }
+
+  if (typeof value.flipVertical === "boolean") {
+    transform.flipVertical = value.flipVertical;
+  }
+
+  if (
+    value.rotationDeg === 0 ||
+    value.rotationDeg === 90 ||
+    value.rotationDeg === 180 ||
+    value.rotationDeg === 270
+  ) {
+    transform.rotationDeg = value.rotationDeg;
+  }
+
+  return Object.keys(transform).length > 0 ? transform : undefined;
+}
+
+function readImageAsset(
+  value: Record<string, unknown>,
+  base: PersistedMediaBase,
+): ToolcraftImageAsset | undefined {
   const position = readPoint(value.position);
 
-  if (!position) {
+  const resourceRef =
+    typeof value.resourceRef === "string"
+      ? value.resourceRef
+      : typeof value.dataUrl === "string"
+        ? createToolcraftDataUrlResourceRef("image", value.dataUrl)
+        : undefined;
+
+  if (!resourceRef || !position) {
     return undefined;
   }
 
-  const mediaAsset: ToolcraftMediaAsset = {
-    dataUrl: value.dataUrl,
-    fileName: value.fileName,
-    id: value.id,
-    layerId: value.layerId,
-    mimeType: value.mimeType,
+  const size = readCanvasSize(value.size);
+  const transform = readMediaTransform(value.transform);
+
+  return {
+    ...base,
+    assetKind: "image",
+    lifecycle: "restoring",
     position,
+    resourceRef,
+    ...(size ? { size } : {}),
+    ...(transform ? { transform } : {}),
   };
-  const size = readCanvasSize(value.size);
+}
+
+function readFileAsset(
+  value: Record<string, unknown>,
+  base: PersistedMediaBase,
+): ToolcraftFileAsset | undefined {
+  const position = readPoint(value.position);
+
+  const resourceRef =
+    typeof value.resourceRef === "string"
+      ? value.resourceRef
+      : typeof value.dataUrl === "string"
+        ? createToolcraftDataUrlResourceRef("file", value.dataUrl)
+        : undefined;
+
+  if (!resourceRef || !position) {
+    return undefined;
+  }
+
+  return {
+    ...base,
+    assetKind: "file",
+    lifecycle: "restoring",
+    position,
+    resourceRef,
+  };
+}
+
+function readNonNegativeInteger(value: unknown): number | undefined {
+  return isToolcraftFiniteNumber(value) && value >= 0 && Number.isInteger(value)
+    ? value
+    : undefined;
+}
 
-  if (value.assetKind === "file" || value.assetKind === "image") {
-    mediaAsset.assetKind = value.assetKind;
+function readModelDiagnostic(value: unknown): ToolcraftModelDiagnostic | undefined {
+  if (!isToolcraftPersistenceRecord(value)) {
+    return undefined;
   }
 
-  if (size) {
-    mediaAsset.size = size;
+  const affectedCount = readNonNegativeInteger(value.affectedCount);
+
+  if (
+    affectedCount === undefined ||
+    typeof value.code !== "string" ||
+    typeof value.explanation !== "string" ||
+    typeof value.severity !== "string" ||
+    !diagnosticSeverities.has(value.severity as ToolcraftModelDiagnostic["severity"])
+  ) {
+    return undefined;
   }
 
-  if (typeof value.sourceTarget === "string") {
-    mediaAsset.sourceTarget = value.sourceTarget;
+  return {
+    affectedCount,
+    code: value.code,
+    explanation: value.explanation,
+    severity: value.severity as ToolcraftModelDiagnostic["severity"],
+    ...(typeof value.primitiveId === "string"
+      ? { primitiveId: value.primitiveId }
+      : {}),
+  };
+}
+
+function readModelAnalysis(value: unknown): ToolcraftModelAnalysisSummary | undefined {
+  if (
+    !isToolcraftPersistenceRecord(value) ||
+    !Array.isArray(value.diagnostics) ||
+    (value.outcome !== "clean" &&
+      value.outcome !== "fatal" &&
+      value.outcome !== "repairable")
+  ) {
+    return undefined;
   }
 
-  if (isToolcraftPersistenceRecord(value.transform)) {
-    mediaAsset.transform = {};
+  const diagnostics = value.diagnostics.map(readModelDiagnostic);
+  const boundaryEdges = readNonNegativeInteger(value.boundaryEdges);
+  const disconnectedComponents = readNonNegativeInteger(value.disconnectedComponents);
+  const nonManifoldEdges = readNonNegativeInteger(value.nonManifoldEdges);
+  const triangles = readNonNegativeInteger(value.triangles);
+  const vertices = readNonNegativeInteger(value.vertices);
 
-    if (typeof value.transform.flipHorizontal === "boolean") {
-      mediaAsset.transform.flipHorizontal = value.transform.flipHorizontal;
-    }
+  if (
+    diagnostics.some((diagnostic) => diagnostic === undefined) ||
+    boundaryEdges === undefined ||
+    disconnectedComponents === undefined ||
+    nonManifoldEdges === undefined ||
+    triangles === undefined ||
+    vertices === undefined
+  ) {
+    return undefined;
+  }
 
-    if (typeof value.transform.flipVertical === "boolean") {
-      mediaAsset.transform.flipVertical = value.transform.flipVertical;
-    }
+  return {
+    boundaryEdges,
+    diagnostics: diagnostics as ToolcraftModelDiagnostic[],
+    disconnectedComponents,
+    nonManifoldEdges,
+    outcome: value.outcome,
+    ...(typeof value.repairPlanRef === "string"
+      ? { repairPlanRef: value.repairPlanRef }
+      : {}),
+    triangles,
+    vertices,
+  };
+}
 
-    if (
-      value.transform.rotationDeg === 0 ||
-      value.transform.rotationDeg === 90 ||
-      value.transform.rotationDeg === 180 ||
-      value.transform.rotationDeg === 270
-    ) {
-      mediaAsset.transform.rotationDeg = value.transform.rotationDeg;
-    }
+function readSourceAssetFeedback(
+  value: unknown,
+): ToolcraftSourceAssetFeedback | undefined {
+  if (
+    !isToolcraftPersistenceRecord(value) ||
+    typeof value.category !== "string" ||
+    !feedbackCategories.has(
+      value.category as ToolcraftSourceAssetFeedback["category"],
+    ) ||
+    typeof value.code !== "string" ||
+    typeof value.message !== "string"
+  ) {
+    return undefined;
+  }
+
+  return {
+    category: value.category as ToolcraftSourceAssetFeedback["category"],
+    code: value.code,
+    message: value.message,
+  };
+}
+
+function readModelAsset(
+  value: Record<string, unknown>,
+  base: PersistedMediaBase,
+): ToolcraftModelAsset | undefined {
+  const analysis = readModelAnalysis(value.analysis);
+  const originalAnalysis =
+    value.originalAnalysis === undefined
+      ? analysis
+      : readModelAnalysis(value.originalAnalysis);
+
+  if (
+    !analysis ||
+    !originalAnalysis ||
+    typeof value.activeDocumentRef !== "string" ||
+    typeof value.originalDocumentRef !== "string" ||
+    typeof value.sourceBundleDigest !== "string" ||
+    typeof value.sourceBundleRef !== "string" ||
+    (value.lifecycle !== "clean" &&
+      value.lifecycle !== "fixed" &&
+      value.lifecycle !== "repairable" &&
+      value.lifecycle !== "restoring" &&
+      value.lifecycle !== "unavailable") ||
+    (value.topologyProfile !== "realtime-mesh" &&
+      value.topologyProfile !== "solid-mesh")
+  ) {
+    return undefined;
+  }
+
+  const lastRepairError = readSourceAssetFeedback(value.lastRepairError);
+  const frame = normalizeToolcraftSceneElementFrame({
+    position: readPoint(value.position),
+    size: readCanvasSize(value.size),
+  });
+
+  return {
+    ...base,
+    activeDocumentRef: value.activeDocumentRef,
+    analysis,
+    assetKind: "model",
+    // Model bytes live in the binary repository, not in localStorage. Every
+    // persisted model therefore re-enters through the asynchronous hydration
+    // boundary before render/export may consume its refs.
+    lifecycle: "restoring",
+    originalAnalysis,
+    originalDocumentRef: value.originalDocumentRef,
+    position: frame.position,
+    size: frame.size,
+    sourceBundleDigest: value.sourceBundleDigest,
+    sourceBundleRef: value.sourceBundleRef,
+    topologyProfile: value.topologyProfile,
+    ...(typeof value.appliedRepairRecipeId === "string"
+      ? { appliedRepairRecipeId: value.appliedRepairRecipeId }
+      : {}),
+    ...(lastRepairError ? { lastRepairError } : {}),
+    ...(typeof value.repairedDocumentRef === "string"
+      ? { repairedDocumentRef: value.repairedDocumentRef }
+      : {}),
+  };
+}
 
-    if (Object.keys(mediaAsset.transform).length === 0) {
-      delete mediaAsset.transform;
-    }
+function readMediaAsset(value: unknown): ToolcraftMediaAsset | undefined {
+  if (!isToolcraftPersistenceRecord(value)) {
+    return undefined;
   }
 
-  return mediaAsset;
+  const base = readMediaBase(value);
+
+  if (!base) {
+    return undefined;
+  }
+
+  switch (value.assetKind) {
+    case "file":
+      return readFileAsset(value, base);
+    case "model":
+      return readModelAsset(value, base);
+    case "image":
+    case undefined:
+      return readImageAsset(value, base);
+    default:
+      return undefined;
+  }
 }
 
 export function readMediaAssets(value: unknown): ToolcraftMediaAsset[] | undefined {

package/templates/runtime/state/persistence-reader-panels.ts

@@ -3,12 +3,27 @@ import {
   toolcraftPersistedPanelIds,
 } from "./persistence-shared";
 import { readPoint } from "./persistence-reader-primitives";
+import type { ToolcraftPanelSnapEdge } from "../contracts/types";
 import type {
-  ToolcraftPanelId,
+  ToolcraftInitialState,
   ToolcraftPanelState,
 } from "./types";
+import type { ResolvedToolcraftAppSchema } from "../schema/types";
 
-function readPanel(value: unknown): Partial<ToolcraftPanelState> | undefined {
+function isAllowedPanelSnapEdge(
+  value: unknown,
+  allowedEdges: readonly ToolcraftPanelSnapEdge[],
+): value is ToolcraftPanelSnapEdge {
+  return (
+    typeof value === "string" &&
+    allowedEdges.some((edge) => edge === value)
+  );
+}
+
+function readPanel(
+  value: unknown,
+  allowedSnapEdges: readonly ToolcraftPanelSnapEdge[],
+): Partial<ToolcraftPanelState> | undefined {
   if (!isToolcraftPersistenceRecord(value)) {
     return undefined;
   }
@@ -32,25 +47,57 @@ function readPanel(value: unknown): Partial<ToolcraftPanelState> | undefined {
     panel.hidden = value.hidden;
   }
 
+  if (isAllowedPanelSnapEdge(value.snapEdge, allowedSnapEdges)) {
+    panel.snapEdge = value.snapEdge;
+  }
+
   return Object.keys(panel).length > 0 ? panel : undefined;
 }
 
 export function readPanels(
+  schema: ResolvedToolcraftAppSchema,
   value: unknown,
-): Partial<Record<ToolcraftPanelId, Partial<ToolcraftPanelState>>> | undefined {
+): ToolcraftInitialState["panels"] | undefined {
   if (!isToolcraftPersistenceRecord(value)) {
     return undefined;
   }
 
-  const panels: Partial<Record<ToolcraftPanelId, Partial<ToolcraftPanelState>>> = {};
+  const panels: NonNullable<ToolcraftInitialState["panels"]> = {};
 
   for (const panelId of toolcraftPersistedPanelIds) {
-    const panel = readPanel(value[panelId]);
+    const panelContract = schema.assembly.surfaces.panels[panelId];
+    const panel = readPanel(value[panelId], panelContract?.snapEdges ?? []);
 
     if (panel) {
       panels[panelId] = panel;
     }
   }
 
+  const controlsValue = value.controls;
+
+  if (isToolcraftPersistenceRecord(controlsValue)) {
+    const collapsedSectionsValue = controlsValue.collapsedSections;
+
+    if (isToolcraftPersistenceRecord(collapsedSectionsValue)) {
+      const validSectionIds = new Set(
+        schema.panels.controls?.sections.map((section) => section.id) ?? [],
+      );
+      const collapsedSections: Record<string, boolean> = {};
+
+      for (const [sectionId, collapsed] of Object.entries(
+        collapsedSectionsValue,
+      )) {
+        if (validSectionIds.has(sectionId) && collapsed === true) {
+          collapsedSections[sectionId] = true;
+        }
+      }
+
+      panels.controls = {
+        ...panels.controls,
+        collapsedSections,
+      };
+    }
+  }
+
   return Object.keys(panels).length > 0 ? panels : undefined;
 }

package/templates/runtime/state/persistence-reader-values.ts

@@ -1,24 +1,10 @@
-import { isToolcraftTimelinePanelRuntimeTarget } from "../schema/runtime-targets";
 import type { ResolvedToolcraftAppSchema } from "../schema/types";
+import {
+  getToolcraftValueControls,
+  normalizeToolcraftControlValue,
+} from "./control-value-normalization";
 import { isToolcraftPersistenceRecord } from "./persistence-shared";
 
-function getKnownValueTargets(schema: ResolvedToolcraftAppSchema): Set<string> {
-  const targets = new Set<string>();
-
-  for (const section of schema.panels.controls?.sections ?? []) {
-    for (const control of Object.values(section.controls)) {
-      if (
-        control.type !== "panelActions" &&
-        !isToolcraftTimelinePanelRuntimeTarget(control.target)
-      ) {
-        targets.add(control.target);
-      }
-    }
-  }
-
-  return targets;
-}
-
 export function readValues(
   schema: ResolvedToolcraftAppSchema,
   value: unknown,
@@ -27,12 +13,24 @@ export function readValues(
     return undefined;
   }
 
-  const targets = getKnownValueTargets(schema);
+  const controls = getToolcraftValueControls(schema);
   const values: Record<string, unknown> = {};
 
-  for (const target of targets) {
+  for (const [target, control] of controls) {
     if (Object.hasOwn(value, target)) {
-      values[target] = value[target];
+      const normalized = normalizeToolcraftControlValue(control, value[target]);
+
+      values[target] = normalized.accepted
+        ? normalized.value
+        : normalized.fallback;
+    }
+  }
+
+  if (schema.persistence.storage === "localStorage") {
+    for (const target of schema.persistence.additionalValueTargets) {
+      if (!controls.has(target) && Object.hasOwn(value, target)) {
+        values[target] = value[target];
+      }
     }
   }
 

package/templates/runtime/state/persistence-readers.ts

@@ -34,7 +34,7 @@ export function readToolcraftPersistedInitialState(
   }
 
   if (included.has("panels")) {
-    const panels = readPanels(persistedState.panels);
+    const panels = readPanels(schema, persistedState.panels);
 
     if (panels) {
       initialState.panels = panels;

package/templates/runtime/state/persistence-snapshot.ts

@@ -1,11 +1,22 @@
 import type { ResolvedToolcraftAppSchema } from "../schema/types";
+import { cloneToolcraftMediaAssets } from "./media-defaults";
 import type { ToolcraftPersistencePayload } from "./persistence-shared";
 import type { ToolcraftInitialState, ToolcraftState } from "./types";
 
-function pickPersistedValues(state: ToolcraftState): Record<string, unknown> | undefined {
+function pickPersistedValues(
+  state: ToolcraftState,
+  persistence: Extract<
+    ResolvedToolcraftAppSchema["persistence"],
+    { storage: "localStorage" }
+  >,
+): Record<string, unknown> | undefined {
   const values: Record<string, unknown> = {};
+  const targets = new Set([
+    ...Object.keys(state.defaults),
+    ...persistence.additionalValueTargets,
+  ]);
 
-  for (const target of Object.keys(state.defaults)) {
+  for (const target of targets) {
     if (Object.hasOwn(state.values, target)) {
       values[target] = state.values[target];
     }
@@ -26,7 +37,7 @@ export function createToolcraftPersistenceSnapshot(
   const initialState: ToolcraftInitialState = {};
 
   if (included.has("values")) {
-    initialState.values = pickPersistedValues(state);
+    initialState.values = pickPersistedValues(state, persistence);
   }
 
   if (included.has("canvas")) {
@@ -47,7 +58,7 @@ export function createToolcraftPersistenceSnapshot(
   }
 
   if (included.has("media")) {
-    initialState.mediaAssets = state.mediaAssets;
+    initialState.mediaAssets = cloneToolcraftMediaAssets(state.mediaAssets);
   }
 
   return {