sh3-core 0.6.0 → 0.7.0

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;

package/dist/overlays/FloatFrame.svelte

@@ -0,0 +1,141 @@
+<!--
+  Single floating panel frame.
+
+  Renders:
+    - Header bar (title + close button, receives pointerdown for drag).
+    - Body that mounts the float's content subtree via LayoutRenderer
+      using rootRef={{ kind: 'float', floatId: entry.id }} so the
+      renderer reads from layoutStore.tree.floats[...].content instead
+      of layoutStore.root.
+
+  Behavior:
+    - Pointer drag on header mutates entry.position in place. The entry
+      is a live reference from layoutStore.tree.floats, so mutation
+      reactivity flows through the workspace-zone proxy.
+    - Click anywhere on the frame raises it (calls floatManager.focus).
+    - Close button calls floatManager.close.
+-->
+<script lang="ts">
+  import LayoutRenderer from '../layout/LayoutRenderer.svelte';
+  import { floatManager } from './float';
+  import type { FloatEntry } from '../layout/types';
+
+  interface Props {
+    entry: FloatEntry;
+  }
+  const { entry }: Props = $props();
+
+  let dragging = $state(false);
+  let dragOffset = { x: 0, y: 0 };
+
+  function onHeaderPointerDown(e: PointerEvent): void {
+    if (e.button !== 0) return;
+    const target = e.currentTarget as HTMLElement;
+    target.setPointerCapture(e.pointerId);
+    dragging = true;
+    dragOffset = { x: e.clientX - entry.position.x, y: e.clientY - entry.position.y };
+    floatManager.focus(entry.id);
+  }
+
+  function onHeaderPointerMove(e: PointerEvent): void {
+    if (!dragging) return;
+    entry.position.x = e.clientX - dragOffset.x;
+    entry.position.y = e.clientY - dragOffset.y;
+  }
+
+  function onHeaderPointerUp(e: PointerEvent): void {
+    if (!dragging) return;
+    dragging = false;
+    const target = e.currentTarget as HTMLElement;
+    if (target.hasPointerCapture(e.pointerId)) {
+      target.releasePointerCapture(e.pointerId);
+    }
+  }
+
+  function onFrameClick(): void {
+    floatManager.focus(entry.id);
+  }
+
+  function onClose(e: MouseEvent): void {
+    e.stopPropagation();
+    floatManager.close(entry.id);
+  }
+</script>
+
+<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+<div
+  class="sh3-float-frame"
+  style:left="{entry.position.x}px"
+  style:top="{entry.position.y}px"
+  style:width="{entry.size.w}px"
+  style:height="{entry.size.h}px"
+  onclick={onFrameClick}
+  role="dialog"
+  aria-label={entry.title ?? 'Float panel'}
+  tabindex="-1"
+>
+  <!-- svelte-ignore a11y_no_static_element_interactions -->
+  <header
+    class="sh3-float-header"
+    onpointerdown={onHeaderPointerDown}
+    onpointermove={onHeaderPointerMove}
+    onpointerup={onHeaderPointerUp}
+    onpointercancel={onHeaderPointerUp}
+  >
+    <span class="sh3-float-title">{entry.title ?? entry.content.type}</span>
+    <button class="sh3-float-close" onclick={onClose} aria-label="Close float">×</button>
+  </header>
+  <div class="sh3-float-body">
+    <LayoutRenderer rootRef={{ kind: 'float', floatId: entry.id }} path={[]} />
+  </div>
+</div>
+
+<style>
+  .sh3-float-frame {
+    position: absolute;
+    display: flex;
+    flex-direction: column;
+    background: var(--shell-grad-bg-elevated, var(--shell-bg-elevated, #1e1e1e));
+    color: var(--shell-fg);
+    border: 1px solid var(--shell-border-strong);
+    border-radius: var(--shell-radius);
+    box-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);
+    pointer-events: auto;
+  }
+  .sh3-float-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 4px 8px;
+    background: var(--shell-bg, #111);
+    cursor: move;
+    user-select: none;
+    border-bottom: 1px solid var(--shell-border-strong);
+    border-top-left-radius: var(--shell-radius);
+    border-top-right-radius: var(--shell-radius);
+    flex-shrink: 0;
+  }
+  .sh3-float-title {
+    font-size: 12px;
+    color: var(--shell-fg);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  .sh3-float-close {
+    background: transparent;
+    border: none;
+    color: var(--shell-fg);
+    font-size: 16px;
+    line-height: 1;
+    cursor: pointer;
+    padding: 0 4px;
+    flex-shrink: 0;
+  }
+  .sh3-float-body {
+    flex: 1;
+    position: relative;
+    overflow: hidden;
+    min-height: 0;
+  }
+</style>

package/dist/overlays/FloatFrame.svelte.d.ts

@@ -0,0 +1,7 @@
+import type { FloatEntry } from '../layout/types';
+interface Props {
+    entry: FloatEntry;
+}
+declare const FloatFrame: import("svelte").Component<Props, {}, "">;
+type FloatFrame = ReturnType<typeof FloatFrame>;
+export default FloatFrame;

package/dist/overlays/FloatLayer.svelte

@@ -0,0 +1,28 @@
+<!--
+  Layer 1 overlay root — iterates the active LayoutTree's floats and
+  renders a FloatFrame for each. Mounted into the layer-1 DOM root by
+  Shell.svelte. Reactivity flows from the workspace-zone proxy through
+  layoutStore.floats into this component, so mutations (open, close,
+  position changes, reorder) re-render automatically.
+-->
+<script lang="ts">
+  import { layoutStore } from '../layout/store.svelte';
+  import FloatFrame from './FloatFrame.svelte';
+
+  const floats = $derived(layoutStore.floats);
+</script>
+
+<div class="sh3-float-layer">
+  {#each floats as entry (entry.id)}
+    <FloatFrame {entry} />
+  {/each}
+</div>
+
+<style>
+  .sh3-float-layer {
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+    /* Children are pointer-events: auto so the layer itself passes through. */
+  }
+</style>

package/dist/overlays/FloatLayer.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const FloatLayer: import("svelte").Component<Record<string, never>, {}, "">;
+type FloatLayer = ReturnType<typeof FloatLayer>;
+export default FloatLayer;

package/dist/overlays/float.d.ts

@@ -0,0 +1,29 @@
+import type { FloatEntry } from '../layout/types';
+import type { Size } from '../layout/floats';
+export interface FloatOptions {
+    title?: string;
+    position?: {
+        x: number;
+        y: number;
+    };
+    size?: Size;
+}
+export interface FloatManager {
+    open(viewId: string, options?: FloatOptions): string;
+    close(floatId: string): void;
+    list(): FloatEntry[];
+    focus(floatId: string): void;
+}
+/**
+ * Bind the manager to the active LayoutTree's `floats` array. Called
+ * from Shell.svelte during boot. `getBounds` returns the current
+ * tree-allocated area for cascade-position wraparound.
+ */
+export declare function bindFloatStore(floats: FloatEntry[], getBounds: () => {
+    w: number;
+    h: number;
+}): void;
+export declare function unbindFloatStore(): void;
+/** Test-only reset. Clears in-memory fallback and unbinds any store. */
+export declare function __resetFloatManagerForTest(): void;
+export declare const floatManager: FloatManager;