@pixel-point/toolcraft 0.0.15 → 0.0.16

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

@@ -31,6 +31,16 @@ describe("defineToolcraft runtime setup canvas controls", () => {
     const [canvasSection, generationSection] = app.panels.controls?.sections ?? [];
 
     expect(canvasSection?.title).toBe("Setup");
+    expect(canvasSection?.controls.infinityCanvas).toMatchObject({
+      defaultValue: false,
+      label: "Infinity canvas",
+      target: "canvas.infinity",
+      type: "switch",
+    });
+    expect(canvasSection?.controls.infinityCanvas).not.toHaveProperty(
+      "disabledWhen",
+    );
+    expect(canvasSection?.controls.infinityCanvas).not.toHaveProperty("description");
     expect(canvasSection?.controls.canvasAspectRatio).toMatchObject({
       defaultValue: {
         height: 5,
@@ -42,6 +52,7 @@ describe("defineToolcraft runtime setup canvas controls", () => {
       performanceRole: "workload",
       target: "canvas.aspectRatio",
       type: "aspectRatio",
+      visibleWhen: { equals: false, target: "canvas.infinity" },
     });
     expect(canvasSection?.controls.canvasWidth).toMatchObject({
       defaultValue: 1440,
@@ -49,6 +60,7 @@ describe("defineToolcraft runtime setup canvas controls", () => {
       performanceRole: "workload",
       target: "canvas.size.width",
       type: "text",
+      visibleWhen: { equals: false, target: "canvas.infinity" },
     });
     expect(canvasSection?.controls.canvasHeight).toMatchObject({
       defaultValue: 900,
@@ -56,6 +68,7 @@ describe("defineToolcraft runtime setup canvas controls", () => {
       performanceRole: "workload",
       target: "canvas.size.height",
       type: "text",
+      visibleWhen: { equals: false, target: "canvas.infinity" },
     });
     expect(canvasSection?.layoutGroups).toEqual([
       {
@@ -66,4 +79,29 @@ describe("defineToolcraft runtime setup canvas controls", () => {
     ]);
     expect(generationSection?.title).toBe("Generation");
   });
+
+  it("publishes an app-selected Infinity canvas default", () => {
+    const app = defineToolcraft({
+      canvas: {
+        enabled: true,
+        size: { height: 900, unit: "px", width: 1440 },
+        sizing: {
+          defaultMode: "infinite",
+          mode: "editable-output",
+        },
+      },
+      panels: {
+        controls: {
+          sections: [],
+          title: "Controls",
+        },
+      },
+    });
+
+    expect(app.panels.controls?.sections[0]?.controls.infinityCanvas).toMatchObject({
+      defaultValue: true,
+      target: "canvas.infinity",
+      type: "switch",
+    });
+  });
 });

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

@@ -3,16 +3,23 @@ import { describe, expect, it } from "vitest";
 import { defineToolcraft } from "./define-toolcraft";
 
 describe("defineToolcraft runtime setup persistence", () => {
-  it("disables app state persistence by default", () => {
+  it("enables canonical app state persistence by default", () => {
     const app = defineToolcraft({
+      identity: { id: "test", title: "Test" },
       canvas: { enabled: true },
       panels: {},
     });
 
-    expect(app.persistence).toEqual({ storage: "none" });
+    expect(app.persistence).toEqual({
+      additionalValueTargets: [],
+      include: ["canvas", "panels", "values"],
+      key: "toolcraft:test:state:v2",
+      storage: "localStorage",
+      version: 2,
+    });
   });
 
-  it("preserves explicit localStorage persistence policy without writing storage", () => {
+  it("preserves explicit localStorage identity while adding mandatory slices", () => {
     const app = defineToolcraft({
       canvas: { enabled: true },
       panels: {},
@@ -25,42 +32,43 @@ describe("defineToolcraft runtime setup persistence", () => {
     });
 
     expect(app.persistence).toEqual({
-      include: ["values", "canvas", "panels"],
+      additionalValueTargets: [],
+      include: ["canvas", "panels", "values"],
       key: "toolcraft:test:state:v1",
       storage: "localStorage",
       version: 1,
     });
   });
 
-  it("requires panel persistence when localStorage apps render draggable runtime panels", () => {
-    expect(() =>
-      defineToolcraft({
-        canvas: { enabled: true },
-        panels: {
-          controls: {
-            sections: [
-              {
-                controls: {
-                  opacity: {
-                    defaultValue: 75,
-                    target: "selectedLayer.opacity",
-                    type: "slider",
-                  },
+  it("adds panel persistence instead of rejecting incomplete explicit policies", () => {
+    const app = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                opacity: {
+                  defaultValue: 75,
+                  target: "selectedLayer.opacity",
+                  type: "slider",
                 },
               },
-            ],
-            title: "Controls",
-          },
-        },
-        persistence: {
-          include: ["values"],
-          key: "toolcraft:panel-test:state:v1",
-          storage: "localStorage",
-          version: 1,
+            },
+          ],
+          title: "Controls",
         },
-      }),
-    ).toThrow(
-      'Toolcraft apps with visible runtime panels and localStorage persistence must include "panels" so dragged panel positions survive reload.',
-    );
+      },
+      persistence: {
+        include: ["values"],
+        key: "toolcraft:panel-test:state:v1",
+        storage: "localStorage",
+        version: 1,
+      },
+    });
+
+    expect(app.persistence).toMatchObject({
+      include: ["canvas", "panels", "values"],
+    });
   });
 });

package/templates/runtime/schema/define-toolcraft.setup-render-scale-timeline.test.ts

@@ -31,6 +31,7 @@ describe("defineToolcraft runtime setup render scale and timeline controls", ()
     expect(app.assembly.capabilities).toContain("canvas.renderScale");
     expect(Object.keys(setupSection?.controls ?? {})).toEqual([
       "settingsTransfer",
+      "infinityCanvas",
       "canvasAspectRatio",
       "canvasWidth",
       "canvasHeight",
@@ -49,7 +50,7 @@ describe("defineToolcraft runtime setup render scale and timeline controls", ()
     });
   });
 
-  it("appends timeline visibility to the bottom of setup controls when timeline is enabled", () => {
+  it("places timeline last when no managed background controls exist", () => {
     const app = defineToolcraft({
       canvas: {
         enabled: true,
@@ -70,6 +71,7 @@ describe("defineToolcraft runtime setup render scale and timeline controls", ()
 
     expect(Object.keys(setupSection?.controls ?? {})).toEqual([
       "settingsTransfer",
+      "infinityCanvas",
       "canvasAspectRatio",
       "canvasWidth",
       "canvasHeight",
@@ -78,15 +80,22 @@ describe("defineToolcraft runtime setup render scale and timeline controls", ()
     ]);
     expect(setupSection?.controls.timelineExtended).toMatchObject({
       defaultValue: false,
-      description:
-        "Shows the extended runtime timeline with scrubber, duration, loop, and keyframe controls; compact mode keeps only Play visible.",
       label: "Timeline",
       target: "panels.timeline.extended",
       type: "switch",
     });
+    expect(setupSection?.controls.timelineExtended).not.toHaveProperty("description");
+    expect(setupSection?.controls.infinityCanvas).not.toHaveProperty("description");
+    expect(setupSection?.layoutGroups).toEqual([
+      {
+        columns: 2,
+        controls: ["canvasWidth", "canvasHeight"],
+        layout: "inline",
+      },
+    ]);
   });
 
-  it("can prepend render scale without editable output sizing", () => {
+  it("keeps timeline standalone with render scale for fixed output sizing", () => {
     const app = defineToolcraft({
       canvas: {
         enabled: true,
@@ -99,18 +108,29 @@ describe("defineToolcraft runtime setup render scale and timeline controls", ()
           sections: [],
           title: "Controls",
         },
+        timeline: { mode: "playback" },
       },
     });
 
-    expect(app.panels.controls?.sections[0]).toMatchObject({
-      controls: {
-        canvasRenderScale: {
-          defaultValue: 1.5,
-          target: "canvas.renderScale",
-          type: "slider",
-        },
-      },
-      title: "Setup",
+    const setupSection = app.panels.controls?.sections[0];
+
+    expect(Object.keys(setupSection?.controls ?? {})).toEqual([
+      "settingsTransfer",
+      "canvasRenderScale",
+      "timelineExtended",
+    ]);
+    expect(setupSection?.controls.canvasRenderScale).toMatchObject({
+      defaultValue: 1.5,
+      target: "canvas.renderScale",
+      type: "slider",
+    });
+    expect(setupSection?.controls.timelineExtended).toMatchObject({
+      defaultValue: false,
+      label: "Timeline",
+      target: "panels.timeline.extended",
+      type: "switch",
     });
+    expect(setupSection?.controls.timelineExtended).not.toHaveProperty("description");
+    expect(setupSection?.layoutGroups ?? []).toEqual([]);
   });
 });

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

@@ -4,6 +4,45 @@ import { defineToolcraft } from "./define-toolcraft";
 import { createSliderControls, getProductSections } from "./define-toolcraft-test-utils";
 
 describe("defineToolcraft runtime setup settings transfer", () => {
+  it("uses canonical identity for settings transfer independently of controls title", () => {
+    const createApp = (controlsTitle: string) =>
+      defineToolcraft({
+        canvas: { enabled: true },
+        identity: {
+          id: "  My Visual Tool  ",
+          title: "My Visual Tool",
+        },
+        panels: {
+          controls: {
+            sections: [],
+            title: controlsTitle,
+          },
+        },
+        persistence: {
+          include: ["values", "panels"],
+          key: "toolcraft:persistence-slug:state:v1",
+          storage: "localStorage",
+          version: 1,
+        },
+        settingsTransfer: {
+          appId: "legacy-settings-id",
+        },
+      });
+
+    const first = createApp("First Controls Title");
+    const renamed = createApp("Renamed Controls Title");
+
+    expect(first.identity).toEqual({
+      id: "my-visual-tool",
+      title: "My Visual Tool",
+    });
+    expect(first.settingsTransfer.appId).toBe(first.identity.id);
+    expect(first.settingsTransfer.appId).not.toBe("persistence-slug");
+    expect(first.settingsTransfer.appId).not.toBe("first-controls-title");
+    expect(renamed.identity).toEqual(first.identity);
+    expect(renamed.settingsTransfer.appId).toBe(first.settingsTransfer.appId);
+  });
+
   it("keeps settings transfer visible for small auto schemas", () => {
     const app = defineToolcraft({
       canvas: { enabled: true, size: { height: 320, unit: "px", width: 320 } },
@@ -141,6 +180,7 @@ describe("defineToolcraft runtime setup settings transfer", () => {
     expect(runtimeSettingsSection?.title).toBe("Setup");
     expect(Object.keys(runtimeSettingsSection?.controls ?? {})).toEqual([
       "settingsTransfer",
+      "infinityCanvas",
       "canvasAspectRatio",
       "canvasWidth",
       "canvasHeight",
@@ -172,7 +212,7 @@ describe("defineToolcraft runtime setup settings transfer", () => {
     expect(firstProductSection?.title).toBe("Text");
   });
 
-  it("uses explicit settings transfer naming while keeping the setup controls mandatory", () => {
+  it("uses legacy settings transfer naming as an identity seed while keeping setup mandatory", () => {
     const forced = defineToolcraft({
       canvas: { enabled: false },
       panels: {
@@ -182,6 +222,12 @@ describe("defineToolcraft runtime setup settings transfer", () => {
         },
       },
       settingsTransfer: {
+        additionalValueTargets: [
+          " composition.layout ",
+          "composition.layout",
+          "",
+          "composition.selection",
+        ],
         appId: "Tiny Tool Presets",
         enabled: true,
         fileName: "tiny-presets",
@@ -213,14 +259,22 @@ describe("defineToolcraft runtime setup settings transfer", () => {
     });
 
     expect(forced.settingsTransfer).toMatchObject({
+      additionalValueTargets: [
+        "composition.layout",
+        "composition.selection",
+      ],
       appId: "tiny-tool-presets",
       enabled: true,
       fileName: "tiny-presets.json",
     });
+    expect(Object.isFrozen(forced.settingsTransfer.additionalValueTargets)).toBe(
+      true,
+    );
     expect(forced.panels.controls?.sections[0]?.controls.settingsTransfer?.type).toBe(
       "settingsTransfer",
     );
     expect(disabled.settingsTransfer).toMatchObject({
+      additionalValueTargets: [],
       enabled: true,
       mode: false,
     });
@@ -276,12 +330,18 @@ describe("defineToolcraft runtime setup settings transfer", () => {
 
     expect(Object.keys(setupSection?.controls ?? {})).toEqual([
       "settingsTransfer",
+      "infinityCanvas",
       "canvasAspectRatio",
       "canvasWidth",
       "canvasHeight",
       "canvasRenderScale",
       "timelineExtended",
     ]);
+    expect(setupSection?.layoutGroups?.[0]).toEqual({
+      columns: 2,
+      controls: ["canvasWidth", "canvasHeight"],
+      layout: "inline",
+    });
     expect(duplicateSection?.controls.manualWidth?.target).toBe("canvas.size.width");
     expect(duplicateSection?.controls.manualRenderScale?.target).toBe("canvas.renderScale");
     expect(duplicateSection?.controls.manualTimeline?.target).toBe(

package/templates/runtime/schema/define-toolcraft.ts

@@ -1,5 +1,8 @@
 import { createToolcraftAssemblyContract } from "./assembly-contract";
+import { resolveToolcraftAppCapabilities } from "./app-capabilities";
+import { resolveToolcraftAppIdentity } from "./app-identity";
 import { normalizeToolcraftPanels } from "./panels-schema-normalization";
+import { resolveToolcraftPersistencePlan } from "./persistence-plan";
 import { resolveToolcraftSettingsTransfer } from "./runtime-setup-section";
 import {
   defaultToolcraftCanvasSize,
@@ -7,67 +10,29 @@ import {
   resolveToolcraftCanvasSizing,
   resolveToolcraftExport,
   resolveToolcraftMedia,
-  resolveToolcraftPersistence,
   resolveToolcraftToolbar,
 } from "./schema-resolvers";
 import type {
-  ToolcraftAppSchema,
-  ToolcraftToolbarSchema,
-  ResolvedToolcraftPanelsSchema,
   ResolvedToolcraftAppSchema,
+  ToolcraftAppSchema,
 } from "./types";
 
-type ResolvedToolbar = Required<ToolcraftToolbarSchema>;
-
-function hasVisibleRuntimePanel({
-  panels,
-  toolbar,
-}: {
-  panels: ResolvedToolcraftPanelsSchema;
-  toolbar: ResolvedToolbar;
-}): boolean {
-  return Boolean(
-    panels.controls ||
-      panels.layers ||
-      panels.timeline ||
-      toolbar.history ||
-      toolbar.radar ||
-      toolbar.theme ||
-      toolbar.zoom,
-  );
-}
-
-function assertPanelPersistenceContract({
-  panels,
-  persistence,
-  toolbar,
-}: {
-  panels: ResolvedToolcraftPanelsSchema;
-  persistence: ResolvedToolcraftAppSchema["persistence"];
-  toolbar: ResolvedToolbar;
-}): void {
-  if (persistence.storage !== "localStorage" || !hasVisibleRuntimePanel({ panels, toolbar })) {
-    return;
-  }
-
-  if (persistence.include.includes("panels")) {
-    return;
-  }
-
-  throw new Error(
-    'Toolcraft apps with visible runtime panels and localStorage persistence must include "panels" so dragged panel positions survive reload.',
-  );
-}
-
 export function defineToolcraft(schema: ToolcraftAppSchema): ResolvedToolcraftAppSchema {
   const canvasEnabled = schema.canvas.enabled;
   const canvasSize = schema.canvas.size;
   const canvasRenderScale = resolveToolcraftCanvasRenderScale(schema.canvas.renderScale);
   const canvasSizing = resolveToolcraftCanvasSizing(schema.canvas);
-  const persistence = resolveToolcraftPersistence(schema.persistence);
+  const identity = resolveToolcraftAppIdentity({
+    controlsTitle: schema.panels.controls?.title,
+    identity: schema.identity,
+    legacyAppId:
+      typeof schema.settingsTransfer === "object" && schema.settingsTransfer !== null
+        ? schema.settingsTransfer.appId
+        : undefined,
+  });
   const settingsTransfer = resolveToolcraftSettingsTransfer({
     controls: schema.panels.controls,
-    persistence,
+    identity,
     settingsTransfer: schema.settingsTransfer,
   });
   const canvas = {
@@ -90,17 +55,29 @@ export function defineToolcraft(schema: ToolcraftAppSchema): ResolvedToolcraftAp
   });
   const exportSchema = resolveToolcraftExport(schema.export);
   const media = resolveToolcraftMedia(schema.media);
-
-  assertPanelPersistenceContract({ panels, persistence, toolbar });
+  const appCapabilities = resolveToolcraftAppCapabilities({
+    canvas,
+    media,
+    panels,
+  });
+  const assembly = createToolcraftAssemblyContract({
+    appCapabilities,
+    canvas,
+    panels,
+    toolbar,
+  });
+  const persistence = resolveToolcraftPersistencePlan({
+    appCapabilities,
+    identity,
+    panels,
+    persistence: schema.persistence,
+  });
 
   return {
-    assembly: createToolcraftAssemblyContract({
-      canvas,
-      panels,
-      toolbar,
-    }),
+    assembly,
     canvas,
     export: exportSchema,
+    identity,
     media,
     panels,
     persistence,

package/templates/runtime/schema/keyframe-capability.test.ts

@@ -1,12 +1,15 @@
 import { describe, expect, it } from "vitest";
 
 import { getToolcraftControlKeyframeCapability } from "./keyframe-capability";
-import type { ToolcraftControlSchema } from "./types";
+import type {
+  ToolcraftControlSchema,
+  ToolcraftNonModelControlSchema,
+} from "./types";
 
 function control(
   type: ToolcraftControlSchema["type"],
   target: string,
-  extra: Partial<ToolcraftControlSchema> = {},
+  extra: Partial<ToolcraftNonModelControlSchema> = {},
 ): ToolcraftControlSchema {
   return {
     defaultValue: 0,
@@ -52,21 +55,27 @@ describe("getToolcraftControlKeyframeCapability", () => {
 
   it("blocks runtime-owned canvas size targets even when the visual type could otherwise animate", () => {
     expect(
-      getToolcraftControlKeyframeCapability(control("slider", "canvas.aspectRatio")),
+      getToolcraftControlKeyframeCapability(
+        control("slider", "canvas.aspectRatio"),
+      ),
     ).toEqual({
       capable: false,
       reason: "runtime-owned-target",
     });
 
     expect(
-      getToolcraftControlKeyframeCapability(control("text", "canvas.size.width")),
+      getToolcraftControlKeyframeCapability(
+        control("text", "canvas.size.width"),
+      ),
     ).toEqual({
       capable: false,
       reason: "runtime-owned-target",
     });
 
     expect(
-      getToolcraftControlKeyframeCapability(control("slider", "canvas.size.height")),
+      getToolcraftControlKeyframeCapability(
+        control("slider", "canvas.size.height"),
+      ),
     ).toEqual({
       capable: false,
       reason: "runtime-owned-target",
@@ -80,10 +89,12 @@ describe("getToolcraftControlKeyframeCapability", () => {
       "code",
       "fileDrop",
       "imagePicker",
+      "orientationGizmo",
       "panelActions",
       "select",
       "segmented",
       "switch",
+      "tabs",
       "text",
     ]) {
       expect(

package/templates/runtime/schema/panels-schema-normalization.ts

@@ -1,7 +1,9 @@
 import {
   createToolcraftRuntimeSetupSection,
 } from "./runtime-setup-section";
+import { extractToolcraftRuntimeSetupBackground } from "./runtime-setup-background";
 import { normalizeControlsPanelLayout } from "./controls-panel-normalization";
+import { resolveToolcraftControlSectionId } from "./controls-panel-section-id";
 import { resolveToolcraftTimelinePanel } from "./schema-resolvers";
 import type {
   ResolvedToolcraftAppSchema,
@@ -20,7 +22,6 @@ export function normalizeToolcraftPanels({
 }): ResolvedToolcraftPanelsSchema {
   const normalizedTimeline = resolveToolcraftTimelinePanel(panels.timeline);
   const normalizedPanels: ResolvedToolcraftPanelsSchema = {
-    ...(panels.controls ? { controls: panels.controls } : {}),
     ...(panels.layers ? { layers: panels.layers } : {}),
     ...(normalizedTimeline ? { timeline: normalizedTimeline } : {}),
   };
@@ -30,11 +31,25 @@ export function normalizeToolcraftPanels({
   }
 
   const controls = { ...panels.controls };
+  const backgroundExtraction = extractToolcraftRuntimeSetupBackground({
+    sections: controls.sections,
+  });
   const runtimeSetupSection = createToolcraftRuntimeSetupSection({
+    background: backgroundExtraction.background,
     canvas,
     settingsTransfer,
     timeline: normalizedTimeline,
   });
+  const authoredSections = backgroundExtraction.sections.filter((section) => {
+    if (section.id !== "runtime.setup") {
+      return true;
+    }
+
+    // A resolved schema may be passed back through defineToolcraft. Validate the
+    // prior generated Setup section before replacing it with the current one.
+    resolveToolcraftControlSectionId(section);
+    return false;
+  });
 
   return {
     ...normalizedPanels,
@@ -42,7 +57,7 @@ export function normalizeToolcraftPanels({
       ...controls,
       sections: [
         runtimeSetupSection,
-        ...controls.sections,
+        ...authoredSections,
       ],
     }),
   };