sh3-core 0.6.0 → 0.7.1

package/dist/layout/ops.test.js

@@ -0,0 +1,36 @@
+import { describe, it, expect } from 'vitest';
+import { findTabInTree } from './ops';
+describe('findTabInTree', () => {
+    const tree = {
+        docked: {
+            type: 'tabs',
+            tabs: [{ slotId: 'docked-a', viewId: 'v', label: 'A' }],
+            activeTab: 0,
+        },
+        floats: [
+            {
+                id: 'float-1',
+                content: {
+                    type: 'tabs',
+                    tabs: [{ slotId: 'float-a', viewId: 'v', label: 'A' }],
+                    activeTab: 0,
+                },
+                position: { x: 0, y: 0 },
+                size: { w: 600, h: 400 },
+            },
+        ],
+    };
+    it('finds a tab in the docked tree', () => {
+        const hit = findTabInTree(tree, 'docked-a');
+        expect(hit).not.toBeNull();
+        expect(hit.root).toEqual({ kind: 'docked' });
+    });
+    it('finds a tab inside a float and reports the float id', () => {
+        const hit = findTabInTree(tree, 'float-a');
+        expect(hit).not.toBeNull();
+        expect(hit.root).toEqual({ kind: 'float', floatId: 'float-1' });
+    });
+    it('returns null when the slot is not found', () => {
+        expect(findTabInTree(tree, 'nonexistent')).toBeNull();
+    });
+});

package/dist/layout/presets.d.ts

@@ -0,0 +1,2 @@
+import type { LayoutNode, LayoutTree, LayoutPreset, CanonicalPreset } from './types';
+export declare function normalizeInitialLayout(input: LayoutNode | LayoutTree | LayoutPreset[]): CanonicalPreset[];

package/dist/layout/presets.js

@@ -0,0 +1,49 @@
+/*
+ * Initial layout normalization — converts the three accepted input
+ * shapes (bare LayoutNode, LayoutTree, LayoutPreset[]) into a canonical
+ * CanonicalPreset[] the framework operates on. The ergonomic `tree`
+ * field on LayoutPreset is discarded after normalization in favor of
+ * `variants.default`. Non-default variant keys are preserved untouched
+ * for the rescoped DF10 selection policy.
+ */
+function isLayoutNode(x) {
+    if (!x || typeof x !== 'object')
+        return false;
+    const t = x.type;
+    return t === 'split' || t === 'tabs' || t === 'slot';
+}
+function isLayoutTree(x) {
+    if (!x || typeof x !== 'object')
+        return false;
+    const o = x;
+    return isLayoutNode(o.docked) && Array.isArray(o.floats);
+}
+function wrapNodeAsTree(node) {
+    return { docked: node, floats: [] };
+}
+function canonicalizePreset(p) {
+    const variants = {};
+    if (p.tree)
+        variants.default = p.tree;
+    if (p.variants) {
+        for (const key of Object.keys(p.variants)) {
+            variants[key] = p.variants[key];
+        }
+    }
+    if (!variants.default) {
+        throw new Error(`LayoutPreset "${p.name}" must provide either 'tree' or 'variants.default'`);
+    }
+    return { name: p.name, variants };
+}
+export function normalizeInitialLayout(input) {
+    if (Array.isArray(input)) {
+        return input.map(canonicalizePreset);
+    }
+    if (isLayoutTree(input)) {
+        return [{ name: 'default', variants: { default: input } }];
+    }
+    if (isLayoutNode(input)) {
+        return [{ name: 'default', variants: { default: wrapNodeAsTree(input) } }];
+    }
+    throw new Error('normalizeInitialLayout: input is not a LayoutNode, LayoutTree, or LayoutPreset[]');
+}

package/dist/layout/presets.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/layout/presets.test.js

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest';
+import { normalizeInitialLayout } from './presets';
+const leafNode = { type: 'slot', slotId: 's1', viewId: 'v1' };
+describe('normalizeInitialLayout', () => {
+    it('wraps a bare LayoutNode as a single default preset with empty floats', () => {
+        const result = normalizeInitialLayout(leafNode);
+        expect(result).toEqual([
+            {
+                name: 'default',
+                variants: {
+                    default: { docked: leafNode, floats: [] },
+                },
+            },
+        ]);
+    });
+    it('passes a LayoutTree through as a single default preset', () => {
+        const tree = { docked: leafNode, floats: [] };
+        const result = normalizeInitialLayout(tree);
+        expect(result).toEqual([
+            {
+                name: 'default',
+                variants: { default: tree },
+            },
+        ]);
+    });
+    it('canonicalizes a preset list, using tree as default and preserving variants', () => {
+        const authorTree = { docked: leafNode, floats: [] };
+        const companionTree = {
+            docked: { type: 'slot', slotId: 's2', viewId: 'v2' },
+            floats: [],
+        };
+        const presets = [
+            {
+                name: 'author',
+                tree: authorTree,
+                variants: { companion: companionTree },
+            },
+        ];
+        const result = normalizeInitialLayout(presets);
+        expect(result).toEqual([
+            {
+                name: 'author',
+                variants: {
+                    default: authorTree,
+                    companion: companionTree,
+                },
+            },
+        ]);
+    });
+    it('accepts a preset with only variants (no tree shortcut)', () => {
+        const tree = { docked: leafNode, floats: [] };
+        const presets = [{ name: 'x', variants: { default: tree } }];
+        const result = normalizeInitialLayout(presets);
+        expect(result).toEqual([{ name: 'x', variants: { default: tree } }]);
+    });
+    it('throws if a preset has neither tree nor variants.default', () => {
+        const bad = [{ name: 'broken', variants: { companion: { docked: leafNode, floats: [] } } }];
+        expect(() => normalizeInitialLayout(bad)).toThrow(/must provide either 'tree' or 'variants.default'/);
+    });
+    it('when a preset has both tree and variants.default, variants.default wins', () => {
+        const fromTree = { docked: leafNode, floats: [] };
+        const fromVariant = {
+            docked: { type: 'slot', slotId: 's3', viewId: 'v3' },
+            floats: [],
+        };
+        const result = normalizeInitialLayout([
+            { name: 'x', tree: fromTree, variants: { default: fromVariant } },
+        ]);
+        expect(result[0].variants.default).toBe(fromVariant);
+    });
+});

package/dist/layout/store.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { LayoutNode } from './types';
+import type { LayoutNode, LayoutTree, FloatEntry } from './types';
 import type { App } from '../apps/types';
 /**
  * Attach an app: create or hydrate its workspace-zone layout proxy,
@@ -16,24 +16,28 @@ export declare function detachApp(): void;
 export declare function switchToHome(): void;
 export declare function switchToApp(): void;
 /**
- * The currently-rendered root. LayoutRenderer reads this through the
- * `layoutStore` export below. Home uses the framework constant;
- * app uses the workspace-zone proxy's `root` (which is reactive, so
+ * The currently-rendered LayoutTree. LayoutRenderer reads this via
+ * layoutStore.tree. Home uses a framework constant; app reads the
+ * currently-active preset from the workspace-zone proxy (reactive, so
  * mutations from splitter/drag/ops reach the renderer unchanged).
  */
-export declare function activeLayout(): LayoutNode;
+export declare function activeLayout(): LayoutTree;
 export declare function getActiveRoot(): 'home' | 'app';
 export declare function getAttachedAppId(): string | null;
 /**
- * Preserved for callers that still read `layoutStore.root`. The getter
- * delegates to `activeLayout()` so every read walks through the
- * manager. Writes to `layoutStore.root` are disallowed (mutation is
- * expected to happen on the returned tree's nodes in place, as in
- * phase 7 — splitter drags mutate `sizes[i]`, tab clicks mutate
- * `activeTab`, drag-commit calls `ops.ts` functions that mutate
- * children arrays). Nothing in the codebase currently reassigns
- * `layoutStore.root`, so this getter-only shape is sufficient.
+ * Preserved for callers that still read `layoutStore.root`. The `root`
+ * getter is an alias for `tree.docked` so existing callers still compile
+ * without changes. The `tree` getter exposes the full LayoutTree for
+ * new consumers that also need floats. The `floats` getter is a
+ * convenience alias for `tree.floats`.
+ *
+ * Writes to any of these properties are disallowed (mutation happens on
+ * the returned tree's nodes in place — splitter drags mutate `sizes[i]`,
+ * tab clicks mutate `activeTab`, drag-commit calls ops.ts functions that
+ * mutate children arrays).
  */
 export declare const layoutStore: {
     readonly root: LayoutNode;
+    readonly tree: LayoutTree;
+    readonly floats: FloatEntry[];
 };

package/dist/layout/store.svelte.js

@@ -4,9 +4,10 @@
  * them without tearing down the held tree.
  *
  * The manager is the sole owner of "which layout root is being rendered
- * right now". LayoutRenderer reads `layoutStore.root` (a getter on the
- * active tree); drag.svelte.ts and any other mutation site do the same.
- * Neither needs to know whether the active tree is home or an app.
+ * right now". LayoutRenderer reads `layoutStore.root` (an alias for
+ * `tree.docked`) and `layoutStore.tree`; drag.svelte.ts and any other
+ * mutation site do the same. Neither needs to know whether the active
+ * tree is home or an app.
  *
  * Refcount-hold discipline:
  *   The slot host pool is refcount-based with a microtask-deferred
@@ -30,7 +31,9 @@
  */
 import { createStateZones, peekZone, clearZone } from '../state/zones.svelte';
 import { acquireSlotHost, releaseSlotHost } from './slotHostPool.svelte';
-import { collectSlotRefs } from './tree-walk';
+import { normalizeInitialLayout } from './presets';
+import { collectTreeSlotRefs } from './tree-walk';
+import { bindPresetBlob, unbindPresetBlob } from '../overlays/presets';
 // ---------- orphan cleanup of pre-phase-8 shell layout key ----------------
 // Legacy pre-phase-8 orphan cleanup. The literal '__shell__' here is
 // intentional — it clears data written under the old reserved id before
@@ -47,8 +50,50 @@ const HOME_LAYOUT = {
     slotId: 'sh3core.home',
     viewId: 'sh3core:home',
 };
+const HOME_TREE = {
+    docked: HOME_LAYOUT,
+    floats: [],
+};
 let appEntry = $state(null);
 let activeRoot = $state('home');
+// ---------- read-side adapter helpers -------------------------------------
+/**
+ * Read-side adapter from the legacy phase-7/phase-8 blob shape
+ * ({ layoutVersion, root: LayoutNode }) to the new preset-map shape.
+ * Returns a normalized AppLayoutBlob. Used only when loading a stored
+ * blob that lacks the new `presets` field — fresh writes always use the
+ * new shape directly.
+ */
+function adaptLegacyBlob(stored) {
+    if (!stored || typeof stored !== 'object')
+        return null;
+    const obj = stored;
+    // If new shape, pass through unchanged.
+    if (obj.presets && typeof obj.presets === 'object' && typeof obj.activePreset === 'string') {
+        return obj;
+    }
+    // Legacy shape: wrap .root into { default: { default: { docked: root, floats: [] } } }.
+    if (obj.root && typeof obj.layoutVersion === 'number') {
+        const tree = { docked: obj.root, floats: [] };
+        return {
+            layoutVersion: obj.layoutVersion,
+            activePreset: 'default',
+            presets: {
+                default: { default: tree },
+            },
+        };
+    }
+    return null;
+}
+/** Helper: read the active preset's default-variant tree out of a blob. */
+function currentTree(blob) {
+    const preset = blob.presets[blob.activePreset];
+    if (!preset) {
+        throw new Error(`AppLayoutBlob active preset "${blob.activePreset}" not found in presets map`);
+    }
+    // v1 always uses 'default' variant
+    return preset.default;
+}
 // ---------- public (within-framework) API ---------------------------------
 /**
  * Attach an app: create or hydrate its workspace-zone layout proxy,
@@ -61,36 +106,44 @@ export function attachApp(app) {
         throw new Error(`Layout manager cannot attach app "${app.manifest.id}": app "${appEntry.appId}" is still attached`);
     }
     const shardId = `__sh3core__:app:${app.manifest.id}`;
-    // Version gate: if a stored blob's layoutVersion doesn't match the
-    // app's current declaration, discard it so createStateZones falls
-    // back to the defaults (the app's initialLayout).
+    // Normalize the app's initialLayout into canonical presets.
+    const canonical = normalizeInitialLayout(app.initialLayout);
+    if (canonical.length === 0) {
+        throw new Error(`App "${app.manifest.id}" normalized to zero presets`);
+    }
+    // Build the default blob (used as fallback when nothing is stored or
+    // the stored blob's version doesn't match).
+    const defaultBlob = {
+        layoutVersion: app.manifest.layoutVersion,
+        activePreset: canonical[0].name,
+        presets: Object.fromEntries(canonical.map((p) => [p.name, Object.assign({}, p.variants)])),
+    };
+    // Version gate: if a stored blob's layoutVersion doesn't match, clear
+    // and fall back to defaults.
     const stored = peekZone('workspace', shardId);
-    if (stored != null) {
-        const asBlob = stored;
-        if (asBlob.layoutVersion !== app.manifest.layoutVersion) {
-            clearZone('workspace', shardId);
-        }
+    const adapted = adaptLegacyBlob(stored);
+    if (adapted && adapted.layoutVersion !== app.manifest.layoutVersion) {
+        clearZone('workspace', shardId);
+    }
+    else if (stored && !adapted) {
+        // Unknown/corrupt shape — clear it so createStateZones takes defaults.
+        clearZone('workspace', shardId);
     }
     const state = createStateZones(shardId, {
-        workspace: {
-            layoutVersion: app.manifest.layoutVersion,
-            root: app.initialLayout,
-        },
+        workspace: defaultBlob,
     });
     const proxy = state.workspace;
-    // Take a refcount hold on every slot in the app's tree. These holds
-    // keep the pooled hosts alive across home⇄app swaps. They are
-    // acquired without attaching the returned host anywhere — the
-    // LayoutRenderer still acquires its own refs when it mounts the
-    // tree, so the active rendering doesn't double-hold harmfully (the
-    // pool's destroy logic just sees refcount 2, then 1 on release).
-    const refs = collectSlotRefs(proxy.root);
+    // Take refcount holds on every slot in the active preset's tree
+    // (including floats). See the refcount-hold discipline comment at top.
+    const tree = currentTree(proxy);
+    const refs = collectTreeSlotRefs(tree);
     const heldSlotIds = [];
     for (const { slotId, viewId, label } of refs) {
         acquireSlotHost(slotId, viewId, label);
         heldSlotIds.push(slotId);
     }
     appEntry = { appId: app.manifest.id, proxy, heldSlotIds };
+    bindPresetBlob(proxy);
 }
 /**
  * Detach the currently-attached app. Releases its refcount holds; the
@@ -100,6 +153,7 @@ export function attachApp(app) {
 export function detachApp() {
     if (!appEntry)
         return;
+    unbindPresetBlob();
     for (const slotId of appEntry.heldSlotIds) {
         releaseSlotHost(slotId);
     }
@@ -118,15 +172,15 @@ export function switchToApp() {
     activeRoot = 'app';
 }
 /**
- * The currently-rendered root. LayoutRenderer reads this through the
- * `layoutStore` export below. Home uses the framework constant;
- * app uses the workspace-zone proxy's `root` (which is reactive, so
+ * The currently-rendered LayoutTree. LayoutRenderer reads this via
+ * layoutStore.tree. Home uses a framework constant; app reads the
+ * currently-active preset from the workspace-zone proxy (reactive, so
  * mutations from splitter/drag/ops reach the renderer unchanged).
  */
 export function activeLayout() {
     if (activeRoot === 'app' && appEntry)
-        return appEntry.proxy.root;
-    return HOME_LAYOUT;
+        return currentTree(appEntry.proxy);
+    return HOME_TREE;
 }
 export function getActiveRoot() {
     return activeRoot;
@@ -137,17 +191,25 @@ export function getAttachedAppId() {
 }
 // ---------- `layoutStore` back-compat shim -------------------------------
 /**
- * Preserved for callers that still read `layoutStore.root`. The getter
- * delegates to `activeLayout()` so every read walks through the
- * manager. Writes to `layoutStore.root` are disallowed (mutation is
- * expected to happen on the returned tree's nodes in place, as in
- * phase 7 — splitter drags mutate `sizes[i]`, tab clicks mutate
- * `activeTab`, drag-commit calls `ops.ts` functions that mutate
- * children arrays). Nothing in the codebase currently reassigns
- * `layoutStore.root`, so this getter-only shape is sufficient.
+ * Preserved for callers that still read `layoutStore.root`. The `root`
+ * getter is an alias for `tree.docked` so existing callers still compile
+ * without changes. The `tree` getter exposes the full LayoutTree for
+ * new consumers that also need floats. The `floats` getter is a
+ * convenience alias for `tree.floats`.
+ *
+ * Writes to any of these properties are disallowed (mutation happens on
+ * the returned tree's nodes in place — splitter drags mutate `sizes[i]`,
+ * tab clicks mutate `activeTab`, drag-commit calls ops.ts functions that
+ * mutate children arrays).
  */
 export const layoutStore = {
     get root() {
+        return activeLayout().docked;
+    },
+    get tree() {
         return activeLayout();
     },
+    get floats() {
+        return activeLayout().floats;
+    },
 };

package/dist/layout/tree-walk.d.ts

@@ -1,4 +1,4 @@
-import type { LayoutNode } from './types';
+import type { LayoutNode, LayoutTree } from './types';
 /**
  * Collect the slot id / view id pairs of every slot leaf (including the
  * slots embedded inside tabs entries) in a layout tree. Used by the
@@ -13,3 +13,14 @@ export declare function collectSlotRefs(tree: LayoutNode): {
     viewId: string | null;
     label: string;
 }[];
+/**
+ * Multi-root version of `collectSlotRefs`: walks the docked tree first
+ * and then each float's content in order. Used by the layout manager to
+ * take refcount holds on slot ids across every tree-owned view when
+ * attaching an app whose preset includes floats.
+ */
+export declare function collectTreeSlotRefs(tree: LayoutTree): {
+    slotId: string;
+    viewId: string | null;
+    label: string;
+}[];

package/dist/layout/tree-walk.js

@@ -31,3 +31,16 @@ export function collectSlotRefs(tree) {
     walk(tree);
     return out;
 }
+/**
+ * Multi-root version of `collectSlotRefs`: walks the docked tree first
+ * and then each float's content in order. Used by the layout manager to
+ * take refcount holds on slot ids across every tree-owned view when
+ * attaching an app whose preset includes floats.
+ */
+export function collectTreeSlotRefs(tree) {
+    const out = collectSlotRefs(tree.docked);
+    for (const f of tree.floats) {
+        out.push(...collectSlotRefs(f.content));
+    }
+    return out;
+}

package/dist/layout/tree-walk.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/layout/tree-walk.test.js

@@ -0,0 +1,41 @@
+import { describe, it, expect } from 'vitest';
+import { collectSlotRefs, collectTreeSlotRefs } from './tree-walk';
+const slot = (slotId, viewId) => ({
+    type: 'slot',
+    slotId,
+    viewId,
+});
+describe('collectSlotRefs (single LayoutNode — existing behavior)', () => {
+    it('returns a single entry for a lone slot', () => {
+        expect(collectSlotRefs(slot('s1', 'v1'))).toEqual([
+            { slotId: 's1', viewId: 'v1', label: 'v1' },
+        ]);
+    });
+});
+describe('collectTreeSlotRefs (LayoutTree — new)', () => {
+    it('returns docked slots followed by float content slots in order', () => {
+        const tree = {
+            docked: slot('docked1', 'v-docked'),
+            floats: [
+                {
+                    id: 'f1',
+                    content: slot('float1', 'v-float1'),
+                    position: { x: 0, y: 0 },
+                    size: { w: 600, h: 400 },
+                },
+                {
+                    id: 'f2',
+                    content: slot('float2', 'v-float2'),
+                    position: { x: 32, y: 32 },
+                    size: { w: 600, h: 400 },
+                },
+            ],
+        };
+        const refs = collectTreeSlotRefs(tree);
+        expect(refs.map((r) => r.slotId)).toEqual(['docked1', 'float1', 'float2']);
+    });
+    it('returns only docked slots when floats is empty', () => {
+        const tree = { docked: slot('only', 'v'), floats: [] };
+        expect(collectTreeSlotRefs(tree).map((r) => r.slotId)).toEqual(['only']);
+    });
+});

package/dist/layout/types.d.ts

@@ -79,6 +79,80 @@ export interface SlotNode {
  * these three types: `split` → children, `tabs` → slots, `slot` → leaf.
  */
 export type LayoutNode = SplitNode | TabsNode | SlotNode;
+/**
+ * A detached panel that floats above the docked tree. Each float owns a
+ * `LayoutNode` subtree (so it can itself contain splits and tabs) plus
+ * positioning metadata. Floats cannot contain other floats — the type
+ * system enforces this by using `LayoutNode`, not `LayoutNode | FloatEntry`.
+ */
+export interface FloatEntry {
+    /** Stable identifier for this float. Survives re-parents and reloads. */
+    id: string;
+    /** The float's content subtree. Split | tabs | slot — no nested floats. */
+    content: LayoutNode;
+    /** Top-left position of the float frame, relative to the tree-allocated area. */
+    position: {
+        x: number;
+        y: number;
+    };
+    /** Size of the float frame in pixels. */
+    size: {
+        w: number;
+        h: number;
+    };
+    /** Optional human-readable title; defaults to the active view's label. */
+    title?: string;
+}
+/**
+ * Root shape of a workspace layout. The docked tree is the primary
+ * topology; floats are a parallel collection that share the same area
+ * visually but live outside the recursive-tree invariant. Persisted to
+ * the workspace state zone as part of an `AppLayoutBlob` preset entry.
+ */
+export interface LayoutTree {
+    docked: LayoutNode;
+    floats: FloatEntry[];
+}
+/**
+ * A named layout blueprint. Apps ship one or more presets in their
+ * manifest; users switch between them at runtime. The ergonomic `tree`
+ * field is shorthand for `variants.default`; the normalizer canonicalizes
+ * every preset into a variants-only shape on load. v1 always uses the
+ * `default` variant; other variant keys (e.g. `companion`) are reserved
+ * for the rescoped DF10 selection policy and are persisted but inert.
+ */
+export interface LayoutPreset {
+    name: string;
+    /** Ergonomic shortcut — discarded after normalization in favor of `variants.default`. */
+    tree?: LayoutTree;
+    /** Variant map. After normalization always contains at least `default`. */
+    variants?: {
+        [variant: string]: LayoutTree;
+    };
+}
+/**
+ * Canonical form of a preset after normalization. Used internally by
+ * the framework; authors write `LayoutPreset` in their manifests.
+ */
+export interface CanonicalPreset {
+    name: string;
+    variants: {
+        [variant: string]: LayoutTree;
+    };
+}
+/**
+ * Reference to a root within the current `LayoutTree`. Either the
+ * primary docked tree, or the content subtree of a specific float by id.
+ * Used by `LayoutRenderer` to target a subtree without passing a `node`
+ * prop (which would break the ownership-by-path contract — see the
+ * component's header comment for rationale).
+ */
+export type TreeRootRef = {
+    kind: 'docked';
+} | {
+    kind: 'float';
+    floatId: string;
+};
 /**
  * Schema version for persisted layouts. Bump this when the shape of
  * `LayoutNode` (or anything reachable from it) changes incompatibly.
@@ -86,7 +160,7 @@ export type LayoutNode = SplitNode | TabsNode | SlotNode;
  * the default tree takes over — phase 7 deliberately does not ship a
  * migration framework, only the hook for one.
  */
-export declare const LAYOUT_SCHEMA_VERSION = 3;
+export declare const LAYOUT_SCHEMA_VERSION = 4;
 /**
  * The wire shape of a persisted layout in the workspace state zone.
  * One blob per shell (or per program, once per-program layouts exist);
@@ -94,15 +168,31 @@ export declare const LAYOUT_SCHEMA_VERSION = 3;
  */
 export interface PersistedLayout {
     version: typeof LAYOUT_SCHEMA_VERSION;
-    root: LayoutNode;
+    tree: LayoutTree;
 }
 /**
  * Per-app layout blob written to the workspace state zone under
- * `__sh3core__:app:<appId>`. The `layoutVersion` is the app's own
- * `AppManifest.layoutVersion`; on launch a mismatch discards the blob
- * and the app's `initialLayout` is used.
+ * `__sh3core__:app:<appId>`. Holds the full multi-preset, multi-variant
+ * tree collection. On launch, a stored blob whose `layoutVersion` does
+ * not match the app's current `AppManifest.layoutVersion` is discarded
+ * and the app's normalized `initialLayout` is used in its place.
+ *
+ * Legacy phase-7/phase-8 blobs stored `{ layoutVersion, root: LayoutNode }`.
+ * The `attachApp` read path wraps that shape into the new form rather
+ * than discarding it; see `layout/store.svelte.ts`.
  */
 export interface AppLayoutBlob {
     layoutVersion: number;
-    root: LayoutNode;
+    /** Name of the currently-active preset. Must be a key of `presets`. */
+    activePreset: string;
+    /**
+     * Preset map. Each entry holds a variant map; v1 only reads/writes
+     * the `default` variant, other keys are reserved for the rescoped
+     * DF10 selection policy and pass through untouched.
+     */
+    presets: {
+        [presetName: string]: {
+            [variantName: string]: LayoutTree;
+        };
+    };
 }

package/dist/layout/types.js

@@ -22,4 +22,4 @@
  * the default tree takes over — phase 7 deliberately does not ship a
  * migration framework, only the hook for one.
  */
-export const LAYOUT_SCHEMA_VERSION = 3;
+export const LAYOUT_SCHEMA_VERSION = 4;