@pixel-point/toolcraft 0.0.15 → 0.0.17

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

@@ -2,10 +2,12 @@ import { describe, expect, it } from "vitest";
 
 import { defineToolcraft } from "../schema/define-toolcraft";
 import { createToolcraftState } from "./create-template-state";
+import { readCanvas } from "./persistence-reader-canvas";
 import {
   createToolcraftPersistenceSnapshot,
   mergeToolcraftInitialState,
   parseToolcraftPersistenceSnapshot,
+  parseToolcraftPersistenceSnapshotResult,
 } from "./persistence";
 
 function createPersistentSchema() {
@@ -22,6 +24,8 @@ function createPersistentSchema() {
             controls: {
               opacity: {
                 defaultValue: 75,
+                max: 100,
+                min: 0,
                 target: "selectedLayer.opacity",
                 type: "slider",
               },
@@ -48,6 +52,16 @@ function createPersistentSchema() {
 }
 
 describe("Toolcraft template state persistence", () => {
+  it("hydrates valid canvas modes and leaves invalid legacy modes to the finite default", () => {
+    const size = { height: 720, unit: "px" as const, width: 1280 };
+
+    expect(readCanvas({ mode: "infinite", size })).toMatchObject({
+      mode: "infinite",
+      size,
+    });
+    expect(readCanvas({ mode: "invalid", size })).toEqual({ size });
+  });
+
   it("serializes only allowed runtime slices and schema control values", () => {
     const schema = createPersistentSchema();
     const state = createToolcraftState(schema, {
@@ -76,7 +90,13 @@ describe("Toolcraft template state persistence", () => {
         },
       ],
       panels: {
-        controls: { offset: { x: 20, y: 10 } },
+        controls: {
+          collapsedSections: {
+            [schema.panels.controls?.sections[0]?.id ?? "missing"]: true,
+          },
+          offset: { x: 20, y: 10 },
+          snapEdge: "left",
+        },
         timeline: { hidden: true },
       },
       selectedLayerId: "layer-1",
@@ -113,6 +133,7 @@ describe("Toolcraft template state persistence", () => {
     expect(snapshot).toMatchObject({
       state: {
         canvas: {
+          mode: "finite",
           offset: { x: 12, y: -8 },
           size: { height: 720, unit: "px", width: 1280 },
           zoom: 82,
@@ -124,8 +145,19 @@ describe("Toolcraft template state persistence", () => {
             visible: true,
           },
         ],
+        mediaAssets: [
+          {
+            fileName: "source.png",
+            id: "media-1",
+            layerId: "layer-1",
+          },
+        ],
         panels: {
-          controls: { offset: { x: 20, y: 10 } },
+          controls: {
+            collapsedSections: expect.any(Object),
+            offset: { x: 20, y: 10 },
+            snapEdge: "left",
+          },
           timeline: { hidden: true },
         },
         selectedLayerId: "layer-1",
@@ -144,10 +176,71 @@ describe("Toolcraft template state persistence", () => {
     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("omits state slices for capabilities absent from the resolved plan", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                opacity: {
+                  defaultValue: 75,
+                  target: "selectedLayer.opacity",
+                  type: "slider",
+                },
+              },
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+    const state = createToolcraftState(schema, {
+      layers: [
+        {
+          displayName: "Unpersisted Layer",
+          id: "unpersisted-layer",
+          kind: "layer",
+          name: "unpersisted-layer",
+          visible: true,
+        },
+      ],
+      mediaAssets: [
+        {
+          dataUrl: "data:image/png;base64,AAAA",
+          fileName: "unpersisted.png",
+          id: "unpersisted-media",
+          layerId: "unpersisted-layer",
+          mimeType: "image/png",
+          position: { x: 0, y: 0 },
+          size: { height: 64, unit: "px", width: 64 },
+        },
+      ],
+      selectedLayerId: "unpersisted-layer",
+      timeline: {
+        currentTimeSeconds: 2,
+        durationSeconds: 10,
+        expanded: true,
+      },
+    });
+
+    expect(schema.persistence).toMatchObject({
+      additionalValueTargets: [],
+      include: ["canvas", "panels", "values"],
+    });
+
+    const snapshot = createToolcraftPersistenceSnapshot(state, schema.persistence);
+
+    expect(snapshot?.state).not.toHaveProperty("layers");
+    expect(snapshot?.state).not.toHaveProperty("mediaAssets");
+    expect(snapshot?.state).not.toHaveProperty("selectedLayerId");
+    expect(snapshot?.state).not.toHaveProperty("timeline");
+  });
+
   it("persists media state when the app opts into media persistence", () => {
     const schema = defineToolcraft({
       canvas: { enabled: true, upload: true },
@@ -200,9 +293,21 @@ describe("Toolcraft template state persistence", () => {
 
   it("parses matching versions and ignores stale targets or invalid versions", () => {
     const schema = createPersistentSchema();
+    const persistedSectionId = schema.panels.controls?.sections.find((section) =>
+      Object.values(section.controls).some(
+        (control) => control.target === "selectedLayer.opacity",
+      ),
+    )?.id;
     const rawValue = JSON.stringify({
       state: {
         panels: {
+          controls: {
+            collapsedSections: {
+              [persistedSectionId!]: true,
+              "unknown-section": true,
+            },
+            snapEdge: "left",
+          },
           timeline: { hidden: true },
         },
         values: {
@@ -216,6 +321,10 @@ describe("Toolcraft template state persistence", () => {
 
     expect(parseToolcraftPersistenceSnapshot(schema, rawValue)).toEqual({
       panels: {
+        controls: {
+          collapsedSections: { [persistedSectionId!]: true },
+          snapEdge: "left",
+        },
         timeline: { hidden: true },
       },
       values: {
@@ -232,6 +341,122 @@ describe("Toolcraft template state persistence", () => {
     expect(parseToolcraftPersistenceSnapshot(schema, "not json")).toBeUndefined();
   });
 
+  it("migrates older snapshots and reports newer snapshots without consuming them", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      identity: { id: "migration-test", title: "Migration Test" },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                opacity: {
+                  defaultValue: 75,
+                  max: 100,
+                  min: 0,
+                  target: "appearance.opacity",
+                  type: "slider",
+                },
+              },
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+    const v1 = JSON.stringify({
+      state: { values: { "appearance.opacity": 50 } },
+      version: 1,
+    });
+    const v3 = JSON.stringify({ state: {}, version: 3 });
+
+    expect(parseToolcraftPersistenceSnapshotResult(schema, v1)).toEqual({
+      fromVersion: 1,
+      kind: "migrated",
+      state: { values: { "appearance.opacity": 50 } },
+    });
+    expect(parseToolcraftPersistenceSnapshotResult(schema, v3)).toMatchObject({
+      kind: "newer-version",
+      payload: { state: {}, version: 3 },
+    });
+    expect(parseToolcraftPersistenceSnapshot(schema, v3)).toBeUndefined();
+  });
+
+  it("preserves an explicitly empty controls section collapse record", () => {
+    const schema = createPersistentSchema();
+
+    if (schema.persistence.storage !== "localStorage") {
+      throw new Error("Expected local persistence");
+    }
+
+    const rawValue = JSON.stringify({
+      state: {
+        panels: {
+          controls: { collapsedSections: {} },
+        },
+      },
+      version: schema.persistence.version,
+    });
+
+    expect(parseToolcraftPersistenceSnapshot(schema, rawValue)).toEqual({
+      panels: {
+        controls: { collapsedSections: {} },
+      },
+    });
+  });
+
+  it("accepts only snap edges allowed by each panel contract", () => {
+    const schema = createPersistentSchema();
+
+    if (schema.persistence.storage !== "localStorage") {
+      throw new Error("Expected local persistence");
+    }
+
+    const rawValue = JSON.stringify({
+      state: {
+        panels: {
+          controls: { snapEdge: "top" },
+          layers: { snapEdge: "right" },
+          timeline: { snapEdge: "bottom" },
+          toolbar: { snapEdge: "left" },
+        },
+      },
+      version: schema.persistence.version,
+    });
+
+    expect(parseToolcraftPersistenceSnapshot(schema, rawValue)).toEqual({
+      panels: {
+        layers: { snapEdge: "right" },
+        timeline: { snapEdge: "bottom" },
+      },
+    });
+  });
+
+  it("replaces invalid persisted control values with schema defaults", () => {
+    const schema = createPersistentSchema();
+
+    if (schema.persistence.storage !== "localStorage") {
+      throw new Error("Expected local persistence");
+    }
+
+    const rawValue = JSON.stringify({
+      state: {
+        values: {
+          "generation.prompt": 42,
+          "selectedLayer.opacity": 200,
+        },
+      },
+      version: schema.persistence.version,
+    });
+
+    expect(parseToolcraftPersistenceSnapshot(schema, rawValue)).toEqual({
+      values: {
+        "generation.prompt": "Describe the effect",
+        "selectedLayer.opacity": 75,
+      },
+    });
+  });
+
   it("lets explicit initial state override persisted state", () => {
     expect(
       mergeToolcraftInitialState(

package/templates/runtime/state/persistence.ts

@@ -3,21 +3,40 @@ import type {
   ResolvedToolcraftAppSchema,
 } from "../schema/types";
 import { readToolcraftPersistedInitialState } from "./persistence-readers";
-import { isToolcraftPersistenceRecord } from "./persistence-shared";
+import {
+  migrateToolcraftPersistencePayload,
+  type ToolcraftVersionedPersistencePayload,
+} from "./persistence-migrations";
 import type { ToolcraftInitialState } from "./types";
 
 export type { ToolcraftPersistencePayload } from "./persistence-shared";
 export { mergeToolcraftInitialState } from "./persistence-merge";
 export { createToolcraftPersistenceSnapshot } from "./persistence-snapshot";
 
-export function parseToolcraftPersistenceSnapshot(
+export type ToolcraftPersistenceSnapshotParseResult =
+  | { kind: "absent" | "invalid" | "unsupported-version" }
+  | {
+      kind: "current";
+      state: ToolcraftInitialState;
+    }
+  | {
+      fromVersion: number;
+      kind: "migrated";
+      state: ToolcraftInitialState;
+    }
+  | {
+      kind: "newer-version";
+      payload: ToolcraftVersionedPersistencePayload;
+    };
+
+export function parseToolcraftPersistenceSnapshotResult(
   schema: ResolvedToolcraftAppSchema,
   rawValue: string | null,
-): ToolcraftInitialState | undefined {
+): ToolcraftPersistenceSnapshotParseResult {
   const persistence = schema.persistence;
 
   if (persistence.storage !== "localStorage" || !rawValue) {
-    return undefined;
+    return { kind: "absent" };
   }
 
   let payload: unknown;
@@ -25,22 +44,42 @@ export function parseToolcraftPersistenceSnapshot(
   try {
     payload = JSON.parse(rawValue);
   } catch {
-    return undefined;
+    return { kind: "invalid" };
+  }
+
+  const migration = migrateToolcraftPersistencePayload(
+    payload,
+    persistence.version,
+  );
+
+  if (migration.kind === "newer-version") {
+    return migration;
   }
 
-  if (
-    !isToolcraftPersistenceRecord(payload) ||
-    payload.version !== persistence.version ||
-    !isToolcraftPersistenceRecord(payload.state)
-  ) {
-    return undefined;
+  if (migration.kind === "invalid" || migration.kind === "unsupported-version") {
+    return { kind: migration.kind };
   }
 
-  return readToolcraftPersistedInitialState(
+  const state = readToolcraftPersistedInitialState(
     schema,
-    payload.state,
+    migration.payload.state,
     new Set(persistence.include),
-  );
+  ) ?? {};
+
+  return migration.kind === "migrated"
+    ? { fromVersion: migration.fromVersion, kind: "migrated", state }
+    : { kind: "current", state };
+}
+
+export function parseToolcraftPersistenceSnapshot(
+  schema: ResolvedToolcraftAppSchema,
+  rawValue: string | null,
+): ToolcraftInitialState | undefined {
+  const result = parseToolcraftPersistenceSnapshotResult(schema, rawValue);
+
+  return result.kind === "current" || result.kind === "migrated"
+    ? result.state
+    : undefined;
 }
 
 export function getToolcraftPersistenceKey(

package/templates/runtime/state/reducer-canvas-panels.test.ts

@@ -261,6 +261,69 @@ describe("toolcraftReducer canvas and panels", () => {
     expect(next.values).toBe(state.values);
   });
 
+  it("keeps repeated legacy panel placement commands as no-ops", () => {
+    const state = createState();
+    const sameOffset = toolcraftReducer(state, {
+      offset: { x: 0, y: 0 },
+      panelId: "controls",
+      type: "panels.setOffset",
+    });
+    const sameReset = toolcraftReducer(state, {
+      panelId: "controls",
+      type: "panels.resetOffset",
+    });
+
+    expect(sameOffset).toBe(state);
+    expect(sameReset).toBe(state);
+  });
+
+  it("updates complete panel workspace state without adding history", () => {
+    const state = createState();
+    const next = toolcraftReducer(state, {
+      panelId: "controls",
+      patch: {
+        collapsed: true,
+        hidden: true,
+        offset: { x: 28, y: -14 },
+        snapEdge: "left",
+      },
+      type: "panels.update",
+    });
+
+    expect(next.panels.controls).toMatchObject({
+      collapsed: true,
+      hidden: true,
+      offset: { x: 28, y: -14 },
+      snapEdge: "left",
+    });
+    expect(next.history).toBe(state.history);
+    expect(next.values).toBe(state.values);
+  });
+
+  it("stores section collapse by stable section id and ignores unknown ids", () => {
+    const state = createState();
+    const sectionId = state.schema.panels.controls?.sections[0]?.id;
+
+    expect(sectionId).toBeTruthy();
+
+    const collapsed = toolcraftReducer(state, {
+      collapsed: true,
+      sectionId: sectionId!,
+      type: "panels.setSectionCollapsed",
+    });
+    const ignored = toolcraftReducer(collapsed, {
+      collapsed: true,
+      sectionId: "missing-section",
+      type: "panels.setSectionCollapsed",
+    });
+
+    expect(collapsed.panels.controls.collapsedSections).toEqual({
+      [sectionId!]: true,
+    });
+    expect(collapsed.history).toBe(state.history);
+    expect(ignored).toBe(collapsed);
+  });
+
   it("stores timeline extended presentation outside control values", () => {
     const state = createState();
 

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

@@ -2,6 +2,11 @@ import { describe, expect, it } from "vitest";
 
 import { defineToolcraft } from "../schema/define-toolcraft";
 import { createToolcraftState } from "./create-template-state";
+import {
+  isToolcraftControlsResetHistoryPatch,
+  tagToolcraftControlsResetHistoryPatch,
+} from "./history-patch-metadata";
+import { commitToolcraftValuePatch } from "./history-patches";
 import { toolcraftReducer } from "./reducer";
 import { createState } from "./reducer-test-utils";
 
@@ -17,6 +22,115 @@ describe("toolcraftReducer controls", () => {
 
     expect(state.values["selectedLayer.opacity"]).toBe(75);
     expect(state.history.undo.at(-1)?.label).toBe("Reset controls");
+    expect(
+      isToolcraftControlsResetHistoryPatch(state.history.undo.at(-1)),
+    ).toBe(true);
+  });
+
+  it("keeps reset provenance out of public patch keys and serialization", () => {
+    const changed = toolcraftReducer(createState(), {
+      target: "selectedLayer.opacity",
+      type: "controls.setValue",
+      value: 12,
+    });
+    const state = toolcraftReducer(changed, { type: "controls.reset" });
+    const patch = state.history.undo.at(-1);
+
+    expect(Object.keys(patch ?? {}).sort()).toEqual([
+      "after",
+      "before",
+      "label",
+    ]);
+    expect(Object.prototype.hasOwnProperty.call(patch, "source")).toBe(false);
+    expect(JSON.parse(JSON.stringify(patch))).toEqual({
+      after: patch?.after,
+      before: patch?.before,
+      label: patch?.label,
+    });
+    expect(
+      isToolcraftControlsResetHistoryPatch(patch ? { ...patch } : undefined),
+    ).toBe(true);
+  });
+
+  it("does not infer reset provenance from an ordinary edit label or group", () => {
+    const state = toolcraftReducer(createState(), {
+      history: "merge",
+      historyGroup: "Reset controls",
+      label: "Reset controls",
+      target: "selectedLayer.opacity",
+      type: "controls.setValue",
+      value: 12,
+    });
+
+    expect(state.history.undo.at(-1)).toMatchObject({
+      group: "Reset controls",
+      label: "Reset controls",
+    });
+    expect(
+      isToolcraftControlsResetHistoryPatch(state.history.undo.at(-1)),
+    ).toBe(false);
+  });
+
+  it("preserves typed provenance through history merge, undo, and redo", () => {
+    const base = createState();
+    const first = commitToolcraftValuePatch(
+      base,
+      tagToolcraftControlsResetHistoryPatch({
+        after: { "selectedLayer.opacity": 64 },
+        before: { "selectedLayer.opacity": 75 },
+        label: "First reset update",
+      }),
+      { ...base.values, "selectedLayer.opacity": 64 },
+      { group: "reset-merge", mode: "merge" },
+    );
+    const second = commitToolcraftValuePatch(
+      first,
+      tagToolcraftControlsResetHistoryPatch({
+        after: { "selectedLayer.opacity": 42 },
+        before: { "selectedLayer.opacity": 64 },
+        label: "Second reset update",
+      }),
+      { ...first.values, "selectedLayer.opacity": 42 },
+      { group: "reset-merge", mode: "merge" },
+    );
+    const patch = second.history.undo.at(-1);
+    const undone = toolcraftReducer(second, { type: "history.undo" });
+    const redone = toolcraftReducer(undone, { type: "history.redo" });
+
+    expect(second.history.undo).toHaveLength(1);
+    expect(isToolcraftControlsResetHistoryPatch(patch)).toBe(true);
+    expect(undone.history.redo.at(-1)).toBe(patch);
+    expect(redone.history.undo.at(-1)).toBe(patch);
+  });
+
+  it("does not inherit reset provenance when an ordinary edit reuses its group", () => {
+    const base = createState();
+    const sourced = commitToolcraftValuePatch(
+      base,
+      tagToolcraftControlsResetHistoryPatch({
+        after: { "selectedLayer.opacity": 64 },
+        before: { "selectedLayer.opacity": 75 },
+        label: "Reset update",
+      }),
+      { ...base.values, "selectedLayer.opacity": 64 },
+      { group: "shared-group", mode: "merge" },
+    );
+    const ordinary = toolcraftReducer(sourced, {
+      history: "merge",
+      historyGroup: "shared-group",
+      label: "Reset controls",
+      target: "selectedLayer.opacity",
+      type: "controls.setValue",
+      value: 42,
+    });
+
+    expect(ordinary.history.undo).toHaveLength(2);
+    expect(isToolcraftControlsResetHistoryPatch(ordinary.history.undo[0])).toBe(
+      true,
+    );
+    expect(isToolcraftControlsResetHistoryPatch(ordinary.history.undo[1])).toBe(
+      false,
+    );
   });
 
   it("resets selected control targets to defaults and records one history patch", () => {

package/templates/runtime/state/reducer-media-import-batch.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+
+import { defineToolcraft } from "../schema/define-toolcraft";
+import { createToolcraftState } from "./create-template-state";
+import { toolcraftReducer } from "./reducer";
+
+function schemaWithLayers() {
+  return defineToolcraft({
+    canvas: { enabled: true, upload: true },
+    panels: {
+      controls: {
+        sections: [
+          {
+            controls: {
+              source: {
+                defaultValue: null,
+                multiple: true,
+                target: "source.media",
+                type: "fileDrop",
+              },
+            },
+          },
+        ],
+        title: "Controls",
+      },
+      layers: true,
+    },
+  });
+}
+
+describe("media.importBatch", () => {
+  it("commits a complete logical batch through one history boundary", () => {
+    const state = createToolcraftState(schemaWithLayers());
+    const imported = toolcraftReducer(state, {
+      assets: [
+        {
+          assetKind: "image",
+          fileName: "one.png",
+          lifecycle: "ready",
+          mimeType: "image/png",
+          position: { x: 0, y: 0 },
+          resourceRef: "media:image:one",
+          sourceTarget: "source.media",
+        },
+        {
+          assetKind: "image",
+          fileName: "two.png",
+          lifecycle: "ready",
+          mimeType: "image/png",
+          position: { x: 0, y: 0 },
+          resourceRef: "media:image:two",
+          sourceTarget: "source.media",
+        },
+      ],
+      replaceExisting: false,
+      type: "media.importBatch",
+    });
+
+    expect(imported.mediaAssets).toHaveLength(2);
+    expect(imported.mediaAssets.map((asset) => asset.assetKind)).toEqual([
+      "image",
+      "image",
+    ]);
+    expect(new Set(imported.mediaAssets.map((asset) => asset.id)).size).toBe(2);
+    expect(new Set(imported.mediaAssets.map((asset) => asset.layerId)).size).toBe(2);
+    expect(imported.history.undo).toHaveLength(1);
+    expect(imported.history.undo[0]?.label).toBe("Import media");
+  });
+
+  it("keeps media.import as one-asset compatibility over the batch reducer", () => {
+    const state = createToolcraftState(schemaWithLayers());
+    const imported = toolcraftReducer(state, {
+      asset: {
+        dataUrl: "data:image/png;base64,bGVnYWN5",
+        fileName: "legacy.png",
+        mimeType: "image/png",
+        position: { x: 0, y: 0 },
+      },
+      type: "media.import",
+    });
+
+    expect(imported.mediaAssets).toEqual([
+      expect.objectContaining({
+        assetKind: "image",
+        fileName: "legacy.png",
+      }),
+    ]);
+    expect(imported.history.undo).toHaveLength(1);
+  });
+});