@pixel-point/toolcraft 0.0.2

package/templates/runtime/state/persistence.test.ts

@@ -0,0 +1,217 @@
+import { describe, expect, it } from "vitest";
+
+import { defineToolcraft } from "../schema/define-toolcraft";
+import { createToolcraftState } from "./create-template-state";
+import {
+  createToolcraftPersistenceSnapshot,
+  mergeToolcraftInitialState,
+  parseToolcraftPersistenceSnapshot,
+} from "./persistence";
+
+function createPersistentSchema() {
+  return defineToolcraft({
+    canvas: {
+      enabled: true,
+      size: { height: 720, unit: "px", width: 1280 },
+      upload: true,
+    },
+    panels: {
+      controls: {
+        sections: [
+          {
+            controls: {
+              opacity: {
+                defaultValue: 75,
+                target: "selectedLayer.opacity",
+                type: "slider",
+              },
+              prompt: {
+                defaultValue: "Describe the effect",
+                target: "generation.prompt",
+                type: "text",
+              },
+            },
+          },
+        ],
+        title: "Controls",
+      },
+      layers: true,
+      timeline: { mode: "keyframes" },
+    },
+    persistence: {
+      include: ["values", "canvas", "panels", "timeline", "layers"],
+      key: "toolcraft:persistence-test:state:v1",
+      storage: "localStorage",
+      version: 1,
+    },
+  });
+}
+
+describe("Toolcraft template state persistence", () => {
+  it("serializes only allowed runtime slices and schema control values", () => {
+    const schema = createPersistentSchema();
+    const state = createToolcraftState(schema, {
+      canvas: {
+        offset: { x: 12, y: -8 },
+        zoom: 82,
+      },
+      layers: [
+        {
+          displayName: "Layer 1",
+          id: "layer-1",
+          kind: "layer",
+          name: "layer-1",
+          visible: true,
+        },
+      ],
+      mediaAssets: [
+        {
+          dataUrl: "data:image/png;base64,AAAA",
+          fileName: "source.png",
+          id: "media-1",
+          layerId: "layer-1",
+          mimeType: "image/png",
+          position: { x: 0, y: 0 },
+          size: { height: 64, unit: "px", width: 64 },
+        },
+      ],
+      panels: {
+        controls: { offset: { x: 20, y: 10 } },
+      },
+      selectedLayerId: "layer-1",
+      timeline: {
+        currentTimeSeconds: 2,
+        durationSeconds: 10,
+        expanded: true,
+        keyframeGroups: [
+          {
+            controlId: "selectedLayer.opacity",
+            keyframes: [
+              {
+                controlId: "selectedLayer.opacity",
+                controlLabel: "Opacity",
+                id: "keyframe-1",
+                timeSeconds: 2,
+                value: 75,
+                valueLabel: "75%",
+              },
+            ],
+            label: "Opacity",
+          },
+        ],
+      },
+      values: {
+        "generation.prompt": "Persisted prompt",
+        "legacy.target": "remove me",
+        "selectedLayer.opacity": 42,
+      },
+    });
+
+    const snapshot = createToolcraftPersistenceSnapshot(state, schema.persistence);
+
+    expect(snapshot).toMatchObject({
+      state: {
+        canvas: {
+          offset: { x: 12, y: -8 },
+          size: { height: 720, unit: "px", width: 1280 },
+          zoom: 82,
+        },
+        layers: [
+          {
+            id: "layer-1",
+            name: "layer-1",
+            visible: true,
+          },
+        ],
+        panels: {
+          controls: { offset: { x: 20, y: 10 } },
+        },
+        selectedLayerId: "layer-1",
+        timeline: {
+          currentTimeSeconds: 2,
+          durationSeconds: 10,
+          expanded: true,
+        },
+        values: {
+          "generation.prompt": "Persisted prompt",
+          "selectedLayer.opacity": 42,
+        },
+      },
+      version: 1,
+    });
+    expect(
+      snapshot?.state.timeline?.keyframeGroups?.[0]?.keyframes[0]?.value,
+    ).toBe(75);
+    expect(snapshot?.state).not.toHaveProperty("mediaAssets");
+    expect(snapshot?.state.values).not.toHaveProperty("legacy.target");
+  });
+
+  it("parses matching versions and ignores stale targets or invalid versions", () => {
+    const schema = createPersistentSchema();
+    const rawValue = JSON.stringify({
+      state: {
+        values: {
+          "generation.prompt": "Restored prompt",
+          "legacy.target": "remove me",
+          "selectedLayer.opacity": 55,
+        },
+      },
+      version: 1,
+    });
+
+    expect(parseToolcraftPersistenceSnapshot(schema, rawValue)).toEqual({
+      values: {
+        "generation.prompt": "Restored prompt",
+        "selectedLayer.opacity": 55,
+      },
+    });
+    expect(
+      parseToolcraftPersistenceSnapshot(
+        schema,
+        JSON.stringify({ state: { values: { "generation.prompt": "Old" } }, version: 2 }),
+      ),
+    ).toBeUndefined();
+    expect(parseToolcraftPersistenceSnapshot(schema, "not json")).toBeUndefined();
+  });
+
+  it("lets explicit initial state override persisted state", () => {
+    expect(
+      mergeToolcraftInitialState(
+        {
+          canvas: {
+            offset: { x: 10, y: 20 },
+            zoom: 80,
+          },
+          panels: {
+            controls: { offset: { x: 4, y: 8 } },
+          },
+          values: {
+            "generation.prompt": "Persisted",
+          },
+        },
+        {
+          canvas: {
+            zoom: 95,
+          },
+          panels: {
+            controls: { collapsed: true },
+          },
+          values: {
+            "generation.prompt": "Explicit",
+          },
+        },
+      ),
+    ).toEqual({
+      canvas: {
+        offset: { x: 10, y: 20 },
+        zoom: 95,
+      },
+      panels: {
+        controls: { collapsed: true, offset: { x: 4, y: 8 } },
+      },
+      values: {
+        "generation.prompt": "Explicit",
+      },
+    });
+  });
+});

package/templates/runtime/state/persistence.ts

@@ -0,0 +1,511 @@
+import type {
+  ToolcraftLocalStoragePersistenceSchema,
+  ResolvedToolcraftAppSchema,
+} from "../schema/types";
+import type {
+  ToolcraftCanvasState,
+  ToolcraftInitialState,
+  ToolcraftLayer,
+  ToolcraftPanelId,
+  ToolcraftPanelState,
+  ToolcraftState,
+  ToolcraftTimelineBezierControlPoints,
+  ToolcraftTimelineKeyframe,
+  ToolcraftTimelineKeyframeEasing,
+  ToolcraftTimelineKeyframeGroup,
+  ToolcraftTimelineState,
+} from "./types";
+
+export type ToolcraftPersistencePayload = {
+  state: ToolcraftInitialState;
+  version: number;
+};
+
+const panelIds = ["controls", "layers", "timeline", "toolbar"] as const satisfies readonly ToolcraftPanelId[];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+function readPoint(value: unknown): { x: number; y: number } | undefined {
+  if (!isRecord(value) || !isFiniteNumber(value.x) || !isFiniteNumber(value.y)) {
+    return undefined;
+  }
+
+  return { x: value.x, y: value.y };
+}
+
+function readCanvasSize(value: unknown): ToolcraftCanvasState["size"] | undefined {
+  if (
+    !isRecord(value) ||
+    !isFiniteNumber(value.width) ||
+    !isFiniteNumber(value.height) ||
+    value.unit !== "px"
+  ) {
+    return undefined;
+  }
+
+  return { height: value.height, unit: "px", width: value.width };
+}
+
+function readCanvas(value: unknown): Partial<ToolcraftCanvasState> | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+
+  const canvas: Partial<ToolcraftCanvasState> = {};
+  const offset = readPoint(value.offset);
+  const size = readCanvasSize(value.size);
+
+  if (offset) {
+    canvas.offset = offset;
+  }
+
+  if (size) {
+    canvas.size = size;
+  }
+
+  if (isFiniteNumber(value.zoom)) {
+    canvas.zoom = value.zoom;
+  }
+
+  return Object.keys(canvas).length > 0 ? canvas : undefined;
+}
+
+function readPanel(value: unknown): Partial<ToolcraftPanelState> | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+
+  const panel: Partial<ToolcraftPanelState> = {};
+  const offset = readPoint(value.offset);
+
+  if (offset) {
+    panel.offset = offset;
+  }
+
+  if (typeof value.collapsed === "boolean") {
+    panel.collapsed = value.collapsed;
+  }
+
+  return Object.keys(panel).length > 0 ? panel : undefined;
+}
+
+function readPanels(
+  value: unknown,
+): Partial<Record<ToolcraftPanelId, Partial<ToolcraftPanelState>>> | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+
+  const panels: Partial<Record<ToolcraftPanelId, Partial<ToolcraftPanelState>>> = {};
+
+  for (const panelId of panelIds) {
+    const panel = readPanel(value[panelId]);
+
+    if (panel) {
+      panels[panelId] = panel;
+    }
+  }
+
+  return Object.keys(panels).length > 0 ? panels : undefined;
+}
+
+function readLayer(value: unknown): ToolcraftLayer | undefined {
+  if (
+    !isRecord(value) ||
+    typeof value.id !== "string" ||
+    typeof value.name !== "string" ||
+    typeof value.visible !== "boolean"
+  ) {
+    return undefined;
+  }
+
+  const layer: ToolcraftLayer = {
+    id: value.id,
+    name: value.name,
+    visible: value.visible,
+  };
+
+  if (value.kind === "group" || value.kind === "layer") {
+    layer.kind = value.kind;
+  }
+
+  if (typeof value.collapsed === "boolean") {
+    layer.collapsed = value.collapsed;
+  }
+
+  if (typeof value.displayName === "string") {
+    layer.displayName = value.displayName;
+  }
+
+  if (typeof value.parentGroupId === "string") {
+    layer.parentGroupId = value.parentGroupId;
+  }
+
+  return layer;
+}
+
+function readLayers(value: unknown): ToolcraftLayer[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+
+  return value.flatMap((item) => {
+    const layer = readLayer(item);
+    return layer ? [layer] : [];
+  });
+}
+
+function readBezierControlPoints(
+  value: unknown,
+): ToolcraftTimelineBezierControlPoints | undefined {
+  if (
+    !Array.isArray(value) ||
+    value.length !== 4 ||
+    !value.every((item) => isFiniteNumber(item))
+  ) {
+    return undefined;
+  }
+
+  return [
+    value[0] as number,
+    value[1] as number,
+    value[2] as number,
+    value[3] as number,
+  ];
+}
+
+function readKeyframeEasing(value: unknown): ToolcraftTimelineKeyframeEasing | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+
+  if (value.type === "step") {
+    return { type: "step" };
+  }
+
+  if (value.type !== "bezier") {
+    return undefined;
+  }
+
+  const controlPoints = readBezierControlPoints(value.controlPoints);
+
+  return controlPoints ? { controlPoints, type: "bezier" } : undefined;
+}
+
+function readKeyframe(value: unknown): ToolcraftTimelineKeyframe | undefined {
+  if (
+    !isRecord(value) ||
+    typeof value.id !== "string" ||
+    typeof value.controlId !== "string" ||
+    typeof value.controlLabel !== "string" ||
+    typeof value.valueLabel !== "string" ||
+    !isFiniteNumber(value.timeSeconds)
+  ) {
+    return undefined;
+  }
+
+  const keyframe: ToolcraftTimelineKeyframe = {
+    controlId: value.controlId,
+    controlLabel: value.controlLabel,
+    id: value.id,
+    timeSeconds: value.timeSeconds,
+    valueLabel: value.valueLabel,
+  };
+  const easing = readKeyframeEasing(value.easing);
+
+  if ("value" in value) {
+    keyframe.value = value.value;
+  }
+
+  if (easing) {
+    keyframe.easing = easing;
+  }
+
+  return keyframe;
+}
+
+function readKeyframeGroup(value: unknown): ToolcraftTimelineKeyframeGroup | undefined {
+  if (
+    !isRecord(value) ||
+    typeof value.controlId !== "string" ||
+    typeof value.label !== "string" ||
+    !Array.isArray(value.keyframes)
+  ) {
+    return undefined;
+  }
+
+  return {
+    controlId: value.controlId,
+    keyframes: value.keyframes.flatMap((item) => {
+      const keyframe = readKeyframe(item);
+      return keyframe ? [keyframe] : [];
+    }),
+    label: value.label,
+  };
+}
+
+function readTimeline(value: unknown): Partial<ToolcraftTimelineState> | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+
+  const timeline: Partial<ToolcraftTimelineState> = {};
+
+  if (isFiniteNumber(value.currentTimeSeconds)) {
+    timeline.currentTimeSeconds = value.currentTimeSeconds;
+  }
+
+  if (isFiniteNumber(value.durationSeconds)) {
+    timeline.durationSeconds = value.durationSeconds;
+  }
+
+  if (typeof value.expanded === "boolean") {
+    timeline.expanded = value.expanded;
+  }
+
+  if (typeof value.isLooping === "boolean") {
+    timeline.isLooping = value.isLooping;
+  }
+
+  if (typeof value.isPlaying === "boolean") {
+    timeline.isPlaying = value.isPlaying;
+  }
+
+  if (typeof value.selectedKeyframeId === "string" || value.selectedKeyframeId === null) {
+    timeline.selectedKeyframeId = value.selectedKeyframeId;
+  }
+
+  if (Array.isArray(value.keyframeGroups)) {
+    timeline.keyframeGroups = value.keyframeGroups.flatMap((item) => {
+      const group = readKeyframeGroup(item);
+      return group ? [group] : [];
+    });
+  }
+
+  return Object.keys(timeline).length > 0 ? timeline : undefined;
+}
+
+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") {
+        targets.add(control.target);
+      }
+    }
+  }
+
+  return targets;
+}
+
+function readValues(
+  schema: ResolvedToolcraftAppSchema,
+  value: unknown,
+): Record<string, unknown> | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+
+  const targets = getKnownValueTargets(schema);
+  const values: Record<string, unknown> = {};
+
+  for (const target of targets) {
+    if (Object.hasOwn(value, target)) {
+      values[target] = value[target];
+    }
+  }
+
+  return Object.keys(values).length > 0 ? values : undefined;
+}
+
+function pickPersistedValues(state: ToolcraftState): Record<string, unknown> | undefined {
+  const values: Record<string, unknown> = {};
+
+  for (const target of Object.keys(state.defaults)) {
+    if (Object.hasOwn(state.values, target)) {
+      values[target] = state.values[target];
+    }
+  }
+
+  return Object.keys(values).length > 0 ? values : undefined;
+}
+
+export function createToolcraftPersistenceSnapshot(
+  state: ToolcraftState,
+  persistence: ResolvedToolcraftAppSchema["persistence"],
+): ToolcraftPersistencePayload | undefined {
+  if (persistence.storage !== "localStorage") {
+    return undefined;
+  }
+
+  const included = new Set(persistence.include);
+  const initialState: ToolcraftInitialState = {};
+
+  if (included.has("values")) {
+    initialState.values = pickPersistedValues(state);
+  }
+
+  if (included.has("canvas")) {
+    initialState.canvas = state.canvas;
+  }
+
+  if (included.has("panels")) {
+    initialState.panels = state.panels;
+  }
+
+  if (included.has("timeline")) {
+    initialState.timeline = state.timeline;
+  }
+
+  if (included.has("layers")) {
+    initialState.layers = state.layers;
+    initialState.selectedLayerId = state.selectedLayerId;
+  }
+
+  return {
+    state: initialState,
+    version: persistence.version,
+  };
+}
+
+export function parseToolcraftPersistenceSnapshot(
+  schema: ResolvedToolcraftAppSchema,
+  rawValue: string | null,
+): ToolcraftInitialState | undefined {
+  const persistence = schema.persistence;
+
+  if (persistence.storage !== "localStorage" || !rawValue) {
+    return undefined;
+  }
+
+  let payload: unknown;
+
+  try {
+    payload = JSON.parse(rawValue);
+  } catch {
+    return undefined;
+  }
+
+  if (!isRecord(payload) || payload.version !== persistence.version || !isRecord(payload.state)) {
+    return undefined;
+  }
+
+  const persistedState = payload.state;
+  const included = new Set(persistence.include);
+  const initialState: ToolcraftInitialState = {};
+
+  if (included.has("values")) {
+    const values = readValues(schema, persistedState.values);
+
+    if (values) {
+      initialState.values = values;
+    }
+  }
+
+  if (included.has("canvas")) {
+    const canvas = readCanvas(persistedState.canvas);
+
+    if (canvas) {
+      initialState.canvas = canvas;
+    }
+  }
+
+  if (included.has("panels")) {
+    const panels = readPanels(persistedState.panels);
+
+    if (panels) {
+      initialState.panels = panels;
+    }
+  }
+
+  if (included.has("timeline")) {
+    const timeline = readTimeline(persistedState.timeline);
+
+    if (timeline) {
+      initialState.timeline = timeline;
+    }
+  }
+
+  if (included.has("layers")) {
+    const layers = readLayers(persistedState.layers);
+
+    if (layers) {
+      initialState.layers = layers;
+
+      if (
+        typeof persistedState.selectedLayerId === "string" &&
+        layers.some((layer) => layer.id === persistedState.selectedLayerId)
+      ) {
+        initialState.selectedLayerId = persistedState.selectedLayerId;
+      } else if (persistedState.selectedLayerId === null) {
+        initialState.selectedLayerId = null;
+      }
+    }
+  }
+
+  return Object.keys(initialState).length > 0 ? initialState : undefined;
+}
+
+export function mergeToolcraftInitialState(
+  persistedState?: ToolcraftInitialState,
+  explicitState?: ToolcraftInitialState,
+): ToolcraftInitialState {
+  const merged: ToolcraftInitialState = {};
+
+  for (const state of [persistedState, explicitState]) {
+    if (!state) {
+      continue;
+    }
+
+    if (state.canvas) {
+      merged.canvas = { ...merged.canvas, ...state.canvas };
+    }
+
+    if (state.panels) {
+      merged.panels = { ...merged.panels };
+
+      for (const panelId of panelIds) {
+        const panel = state.panels[panelId];
+
+        if (panel) {
+          merged.panels[panelId] = { ...merged.panels[panelId], ...panel };
+        }
+      }
+    }
+
+    if (state.timeline) {
+      merged.timeline = { ...merged.timeline, ...state.timeline };
+    }
+
+    if (state.values) {
+      merged.values = { ...merged.values, ...state.values };
+    }
+
+    if (state.layers) {
+      merged.layers = state.layers;
+    }
+
+    if (Object.hasOwn(state, "mediaAssets")) {
+      merged.mediaAssets = state.mediaAssets;
+    }
+
+    if (Object.hasOwn(state, "selectedLayerId")) {
+      merged.selectedLayerId = state.selectedLayerId;
+    }
+  }
+
+  return merged;
+}
+
+export function getToolcraftPersistenceKey(
+  persistence: ResolvedToolcraftAppSchema["persistence"],
+): ToolcraftLocalStoragePersistenceSchema["key"] | undefined {
+  return persistence.storage === "localStorage" ? persistence.key : undefined;
+}