sh3-core 0.1.0

package/dist/layout/ops.js

@@ -0,0 +1,281 @@
+/*
+ * Layout ops — pure(-ish) mutations on a LayoutNode tree.
+ *
+ * All drag-reorganize gestures commit through this module. The drag
+ * engine figures out *what* the user meant (which tab, which target,
+ * which drop zone); the ops figure out *how* to edit the tree so the
+ * result is well-formed.
+ *
+ * Mutation style:
+ *   Trees are mutated in place. The root is a Svelte `$state` object
+ *   owned by the module-level `layoutStore` (see layout/store.svelte.ts),
+ *   so in-place edits are observed by the layout renderer automatically.
+ *   Since phase 7, that store is the workspace state-zone proxy, so each
+ *   mutation also triggers a debounced flush to localStorage — no action
+ *   required from op callers. Returning a new
+ *   tree each time would also work but would force callers to reassign
+ *   the root — messier and no upside here.
+ *
+ * Invariants the ops preserve:
+ *   1. No empty TabsNode. A tab group that loses its last tab is
+ *      removed from its parent.
+ *   2. No single-child split. A split whose children collapse to one
+ *      is replaced by that child (direction and proportion of the
+ *      parent reassert themselves naturally).
+ *   3. Sizes array length matches children length. removeAt / insertAt
+ *      splice the size array alongside the children array.
+ *   4. activeTab stays in range after tab removal/insertion. When the
+ *      active tab itself moves, activeTab follows it.
+ *
+ * Not enforced (intentionally):
+ *   - Uniqueness of slotIds across the tree. The slot host pool keys
+ *     by slotId; duplicates would collide. The ops assume upstream
+ *     doesn't produce duplicates; the drag engine only moves existing
+ *     tabs, so no new slotIds are introduced.
+ */
+/**
+ * Find a tab by its slotId anywhere in the tree. Returns null if no
+ * tab carries that slotId. Used by the drag engine to look up the
+ * source tab before any mutation.
+ */
+export function findTabBySlotId(root, slotId) {
+    const walk = (node, path) => {
+        if (node.type === 'tabs') {
+            const idx = node.tabs.findIndex((t) => t.slotId === slotId);
+            if (idx >= 0) {
+                return { tabsNode: node, tabsPath: path, tabIndex: idx, entry: node.tabs[idx] };
+            }
+        }
+        else if (node.type === 'split') {
+            for (let i = 0; i < node.children.length; i++) {
+                const hit = walk(node.children[i], [...path, i]);
+                if (hit)
+                    return hit;
+            }
+        }
+        return null;
+    };
+    return walk(root, []);
+}
+/** Find a standalone slot leaf by its slotId (only leaves, not tab entries). */
+export function findSlotBySlotId(root, slotId) {
+    const walk = (node, parent, index) => {
+        if (node.type === 'slot') {
+            if (node.slotId === slotId)
+                return { node, parent, index };
+            return null;
+        }
+        if (node.type === 'split') {
+            for (let i = 0; i < node.children.length; i++) {
+                const hit = walk(node.children[i], node, i);
+                if (hit)
+                    return hit;
+            }
+        }
+        return null;
+    };
+    return walk(root, null, 0);
+}
+// ---------- Tab removal ----------------------------------------------------
+/**
+ * Remove a tab from its current location, returning the removed entry
+ * (or null if not found). The tabs group it was in may become empty
+ * and is cleaned up by `cleanupTree` after the caller has finished its
+ * reinsertion. The two-phase shape (mutate → cleanup) means the caller
+ * can remove a tab and re-insert it into the SAME tabs group without
+ * the group being collapsed mid-move.
+ */
+export function removeTabBySlotId(root, slotId) {
+    const located = findTabBySlotId(root, slotId);
+    if (!located)
+        return null;
+    const { tabsNode, tabIndex, entry } = located;
+    tabsNode.tabs.splice(tabIndex, 1);
+    // Keep activeTab sensible: clamp, and shift down if we removed an
+    // earlier tab than the active one.
+    if (tabsNode.tabs.length === 0) {
+        tabsNode.activeTab = 0;
+    }
+    else if (tabIndex < tabsNode.activeTab) {
+        tabsNode.activeTab -= 1;
+    }
+    else if (tabsNode.activeTab >= tabsNode.tabs.length) {
+        tabsNode.activeTab = tabsNode.tabs.length - 1;
+    }
+    return entry;
+}
+// ---------- Tab insertion --------------------------------------------------
+/**
+ * Insert a tab entry into an existing tabs group at a specific index.
+ * Clamps the index into range. The inserted tab becomes active — the
+ * user's drag landed there, so they want to see it.
+ */
+export function insertTabIntoTabs(tabsNode, entry, index) {
+    const clamped = Math.max(0, Math.min(index, tabsNode.tabs.length));
+    tabsNode.tabs.splice(clamped, 0, entry);
+    tabsNode.activeTab = clamped;
+}
+/**
+ * Split a slot-leaf (or tabs-leaf) into a new SplitNode, placing a
+ * single-tab group containing `entry` on the requested side and the
+ * existing node on the other side. The existing node is preserved
+ * as-is (it keeps its slotId, viewId, etc. — critical for re-parenting
+ * of the untouched side).
+ *
+ * Sides map to split direction:
+ *   left/right → horizontal split, new tab goes left or right
+ *   top/bottom → vertical split,   new tab goes top or bottom
+ *
+ * The target is identified by a LayoutPath from the root, because
+ * splitting requires rewriting the parent's child array and we need
+ * the parent reference. If the target IS the root, the root itself is
+ * replaced — callers that pass the root by reference need the wrapper
+ * form, so this function returns the new subtree and the caller
+ * reassigns parent.children[i] = returned value (or reassigns root).
+ */
+export function makeSplitWithNewTab(existing, entry, side) {
+    const direction = side === 'left' || side === 'right' ? 'horizontal' : 'vertical';
+    const newGroup = {
+        type: 'tabs',
+        activeTab: 0,
+        tabs: [entry],
+    };
+    const newFirst = side === 'left' || side === 'top';
+    const children = newFirst ? [newGroup, existing] : [existing, newGroup];
+    return {
+        type: 'split',
+        direction,
+        sizes: [1, 1], // 50/50 by default; splitter drag adjusts from there
+        children,
+    };
+}
+/**
+ * Apply a slot-split as a tree mutation: find the target node at the
+ * given path and replace it with a new split. Handles the root case
+ * (path = []) by mutating the root's fields in place. The root object
+ * identity is preserved so Svelte's $state proxy keeps its reactivity.
+ */
+export function splitNodeAtPath(root, path, entry, side) {
+    const target = nodeAtPath(root, path);
+    if (!target)
+        return;
+    const replacement = makeSplitWithNewTab(target, entry, side);
+    if (path.length === 0) {
+        // Replace root contents in place. The root is a discriminated
+        // union; to rewrite it we cast once through `unknown` and then to
+        // a loose record shape, overwrite fields, and clear stale keys
+        // from the previous node kind so the union stays well-formed.
+        const rootAsRecord = root;
+        // Clear stale keys first so Object.assign doesn't leave a hybrid.
+        delete rootAsRecord.tabs;
+        delete rootAsRecord.activeTab;
+        delete rootAsRecord.slotId;
+        delete rootAsRecord.viewId;
+        delete rootAsRecord.direction;
+        delete rootAsRecord.sizes;
+        delete rootAsRecord.pinned;
+        delete rootAsRecord.children;
+        Object.assign(rootAsRecord, replacement);
+        return;
+    }
+    const parentPath = path.slice(0, -1);
+    const indexInParent = path[path.length - 1];
+    const parent = nodeAtPath(root, parentPath);
+    if (!parent || parent.type !== 'split')
+        return;
+    parent.children[indexInParent] = replacement;
+}
+/** Walk a LayoutPath and return the node at its tip, or null. */
+export function nodeAtPath(root, path) {
+    let cur = root;
+    for (const idx of path) {
+        if (cur.type !== 'split')
+            return null;
+        if (idx < 0 || idx >= cur.children.length)
+            return null;
+        cur = cur.children[idx];
+    }
+    return cur;
+}
+// ---------- Cleanup --------------------------------------------------------
+/**
+ * Post-mutation cleanup pass. Removes empty tabs groups from their
+ * parents and collapses single-child splits. Runs until the tree
+ * stabilizes (a collapse can reveal another single-child split one
+ * level up).
+ *
+ * Called once at the end of every drag commit. Called separately from
+ * the mutation primitives so callers can do "remove then insert into
+ * the same group" without the group being collapsed between calls.
+ */
+export function cleanupTree(root) {
+    let changed = true;
+    while (changed) {
+        changed = cleanupPass(root, null, 0);
+    }
+}
+function cleanupPass(node, parent, indexInParent) {
+    if (node.type === 'split') {
+        // Recurse first so we collapse bottom-up.
+        let recursed = false;
+        for (let i = 0; i < node.children.length; i++) {
+            if (cleanupPass(node.children[i], node, i))
+                recursed = true;
+        }
+        // Drop empty tabs children — unless the tabs node is persistent.
+        for (let i = node.children.length - 1; i >= 0; i--) {
+            const child = node.children[i];
+            if (child.type === 'tabs' && child.tabs.length === 0 && !child.persistent) {
+                node.children.splice(i, 1);
+                node.sizes.splice(i, 1);
+                if (node.pinned)
+                    node.pinned.splice(i, 1);
+                if (node.collapsed)
+                    node.collapsed.splice(i, 1);
+                recursed = true;
+            }
+        }
+        // Collapse a split that has one (or zero) children left. With zero
+        // children the split is meaningless; with one child, the split is
+        // redundant and the surviving child should take its place.
+        if (node.children.length <= 1 && parent) {
+            if (node.children.length === 1) {
+                parent.children[indexInParent] = node.children[0];
+            }
+            else {
+                // Zero children — shouldn't normally happen, but remove to keep
+                // the tree well-formed.
+                parent.children.splice(indexInParent, 1);
+                parent.sizes.splice(indexInParent, 1);
+                if (parent.pinned)
+                    parent.pinned.splice(indexInParent, 1);
+                if (parent.collapsed)
+                    parent.collapsed.splice(indexInParent, 1);
+            }
+            return true;
+        }
+        // Root-level split with one child: promote the surviving child to
+        // root by overwriting the root's fields in place (same technique
+        // as splitNodeAtPath's root case — preserves $state proxy identity).
+        if (node.children.length === 1 && !parent) {
+            const survivor = node.children[0];
+            const rootAsRecord = node;
+            // Clear all split-specific keys.
+            delete rootAsRecord.direction;
+            delete rootAsRecord.sizes;
+            delete rootAsRecord.pinned;
+            delete rootAsRecord.collapsed;
+            delete rootAsRecord.children;
+            Object.assign(rootAsRecord, survivor);
+            return true;
+        }
+        return recursed;
+    }
+    if (node.type === 'tabs') {
+        // Empty tabs at the root level has no parent to drop it from; the
+        // caller is expected to handle the "layout is empty" case
+        // elsewhere (phase 7). We do nothing here.
+        return false;
+    }
+    return false;
+}

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

@@ -0,0 +1,36 @@
+import type { ViewHandle } from '../shards/types';
+/**
+ * Acquire (or create) the pooled host for a slot. The caller is
+ * expected to `appendChild` the returned host into its own wrapper —
+ * the pool does not know which wrapper owns the host at any given time,
+ * and that is intentional. The same host may be passed around.
+ */
+export declare function acquireSlotHost(slotId: string, viewId: string | null, label: string): HTMLDivElement;
+/**
+ * Release the pooled host. If this was the last reference, a
+ * destruction is queued to run in a microtask; a later acquire before
+ * that microtask cancels the destroy (the re-parent case).
+ */
+export declare function releaseSlotHost(slotId: string): void;
+/**
+ * Test / teardown helper — destroys every pooled host immediately. Used
+ * by HMR boundaries and tests; not part of normal runtime flow.
+ */
+export declare function resetSlotHostPool(): void;
+/**
+ * Read the current ViewHandle for a slot. Returns undefined if the slot
+ * is not in the pool or hasn't finished mounting yet. Used by the close
+ * protocol to check closable and call canClose().
+ */
+export declare function getSlotHandle(slotId: string): ViewHandle | undefined;
+/**
+ * Read the dirty state for a slot. Returns false if the slot is not in
+ * the pool. Used by the tab strip to render the dirty indicator.
+ */
+export declare function isSlotDirty(slotId: string): boolean;
+/**
+ * Read the closable state for a slot. Returns false if the slot is not
+ * in the pool or hasn't finished mounting yet. Reactive — Svelte will
+ * re-render when the deferred mount sets the flag.
+ */
+export declare function isSlotClosable(slotId: string): boolean;

package/dist/layout/slotHostPool.svelte.js

@@ -0,0 +1,229 @@
+/*
+ * Slot host pool — the re-parenting contract, made operational.
+ *
+ * docs/design/layout.md:70 — "the layout engine moves the existing
+ * container element rather than destroying and recreating it". This
+ * module is where that happens. Views are mounted into detached
+ * `<div.slot-host>` elements owned by the pool, keyed by slotId, and
+ * survive across arbitrary Svelte remounts of their containing
+ * SlotContainer.
+ *
+ * Why a pool, not per-component state:
+ *   When a user drags a tab from one TabbedPanel to another, the slot's
+ *   SlotContainer leaves one Svelte subtree and reappears in another.
+ *   Svelte will tear down the old component instance and mount a new one
+ *   — even though the slot logically hasn't changed. If the view lives
+ *   inside that component's own DOM, it dies with it. Pooling the host
+ *   outside the Svelte tree and letting each SlotContainer instance
+ *   merely *attach* the pooled host to its wrapper decouples the view's
+ *   lifetime from the component's lifetime.
+ *
+ * Refcount + deferred destroy:
+ *   A tab-move produces a teardown/mount pair in the same microtask.
+ *   Naive lifecycle (destroy on refcount 0) would destroy the view
+ *   between those two events. Instead, a 0-refcount schedules a
+ *   destroy in a microtask; if someone re-acquires before the microtask
+ *   runs, the destroy is cancelled. Result: in-tick moves survive,
+ *   genuine removals (tab closed, layout discards the slotId) still
+ *   tear the view down promptly.
+ *
+ * Opt-out:
+ *   ViewHandle.remountOnMove (unused in phase 6) is the GL/Safari
+ *   edge-case escape hatch reserved by the design. Not wired yet —
+ *   phase 6 has no view that needs it.
+ */
+import { getView } from '../shards/registry';
+const pool = new Map();
+const pendingDestroy = new Set();
+/**
+ * Reactive dirty-state map. Keyed by slotId, values are $state so
+ * Svelte tracks reads in `isSlotDirty()` and re-renders the tab strip
+ * when a shard calls `setDirty()`. Separate from PooledHost because
+ * the pool's plain Map is not reactive.
+ */
+const dirtyState = $state({});
+/**
+ * Reactive closable-state map. Same pattern as dirtyState — the pool's
+ * plain Map is not reactive, so closable flags derived from ViewHandle
+ * would never trigger a re-render. This record is $state so Svelte
+ * tracks reads in `isSlotClosable()` and re-renders the tab strip once
+ * the deferred mount completes and sets the flag.
+ */
+const closableState = $state({});
+/*
+ * Detaching the view mount from the caller's effect scope.
+ *
+ * `acquireSlotHost` is called from inside SlotContainer's `$effect`.
+ * Svelte 5 attributes any reactive subscriptions created during that
+ * call to the currently-active effect — and `$effect.root` is NOT
+ * sufficient to escape this, because `active_effect` is still set
+ * when the root scope runs synchronously inline. When the caller's
+ * effect is later torn down (because SlotContainer remounts under a
+ * new branch of the layout tree), those subscriptions are severed.
+ * The pool keeps the view's DOM alive across the remount, but its
+ * `$derived`s and `$effect`s stop firing — the exact symptom we hit.
+ *
+ * Fix: return the host element synchronously, but defer the
+ * `factory.mount(host)` call to a `queueMicrotask`. Microtasks run
+ * with a clean execution stack, so `active_effect` is null when mount
+ * runs — the view's reactive graph is a true top-level root with no
+ * ancestor effect to be destroyed by. The one-microtask delay before
+ * the view appears is invisible to the user: microtasks run before
+ * the browser paints, so the initial frame still shows the view.
+ *
+ * A `cancelled` flag guards against the edge case where the entry
+ * is destroyed before its deferred mount ever runs (e.g. rapid
+ * add-then-remove of a slot during a drag).
+ */
+function createHost(slotId, viewId, label) {
+    const host = document.createElement('div');
+    host.className = 'slot-host';
+    host.dataset.slotId = slotId;
+    // Position:absolute inset:0 so the host fills whichever wrapper it is
+    // attached to. The wrapper is what the layout engine sizes; the host
+    // just tracks it. Styles are set inline (not in a class) so consumers
+    // don't need to import a stylesheet to get correct layout.
+    host.style.position = 'absolute';
+    host.style.inset = '0';
+    host.style.minWidth = '0';
+    host.style.minHeight = '0';
+    let cancelled = false;
+    const entry = {
+        host,
+        handle: undefined,
+        viewId,
+        label,
+        refcount: 0,
+        resizeObserver: undefined,
+        cancelPendingMount: () => {
+            cancelled = true;
+        },
+    };
+    queueMicrotask(() => {
+        var _a, _b;
+        if (cancelled)
+            return;
+        const factory = viewId ? getView(viewId) : undefined;
+        const ctx = {
+            slotId,
+            viewId: viewId !== null && viewId !== void 0 ? viewId : '',
+            label,
+            setDirty(dirty) {
+                dirtyState[slotId] = dirty;
+            },
+        };
+        entry.handle = factory === null || factory === void 0 ? void 0 : factory.mount(host, ctx);
+        if ((_a = entry.handle) === null || _a === void 0 ? void 0 : _a.closable) {
+            closableState[slotId] = true;
+        }
+        // The pool owns the ResizeObserver so its lifetime matches the
+        // view handle's lifetime, not the containing SlotContainer's.
+        // Moving the host between wrappers (drag-reorganize) keeps the
+        // same observer, and the view keeps receiving size updates
+        // through the move.
+        if ((_b = entry.handle) === null || _b === void 0 ? void 0 : _b.onResize) {
+            const onResize = entry.handle.onResize.bind(entry.handle);
+            entry.resizeObserver = new ResizeObserver((entries) => {
+                for (const e of entries) {
+                    const box = e.contentRect;
+                    onResize(Math.round(box.width), Math.round(box.height));
+                }
+            });
+            entry.resizeObserver.observe(host);
+        }
+    });
+    return entry;
+}
+/**
+ * Acquire (or create) the pooled host for a slot. The caller is
+ * expected to `appendChild` the returned host into its own wrapper —
+ * the pool does not know which wrapper owns the host at any given time,
+ * and that is intentional. The same host may be passed around.
+ */
+export function acquireSlotHost(slotId, viewId, label) {
+    // If the slot was about to be destroyed, cancel — this acquire is the
+    // "other half" of a re-parent (teardown was the previous container).
+    pendingDestroy.delete(slotId);
+    let entry = pool.get(slotId);
+    if (!entry) {
+        entry = createHost(slotId, viewId, label);
+        pool.set(slotId, entry);
+    }
+    entry.refcount++;
+    return entry.host;
+}
+/**
+ * Release the pooled host. If this was the last reference, a
+ * destruction is queued to run in a microtask; a later acquire before
+ * that microtask cancels the destroy (the re-parent case).
+ */
+export function releaseSlotHost(slotId) {
+    const entry = pool.get(slotId);
+    if (!entry)
+        return;
+    entry.refcount--;
+    if (entry.refcount > 0)
+        return;
+    pendingDestroy.add(slotId);
+    queueMicrotask(() => {
+        var _a, _b;
+        if (!pendingDestroy.has(slotId))
+            return;
+        pendingDestroy.delete(slotId);
+        const current = pool.get(slotId);
+        if (!current || current.refcount > 0)
+            return; // re-acquired, keep
+        (_a = current.resizeObserver) === null || _a === void 0 ? void 0 : _a.disconnect();
+        (_b = current.handle) === null || _b === void 0 ? void 0 : _b.unmount();
+        current.cancelPendingMount();
+        current.host.remove();
+        pool.delete(slotId);
+        delete dirtyState[slotId];
+        delete closableState[slotId];
+    });
+}
+/**
+ * Test / teardown helper — destroys every pooled host immediately. Used
+ * by HMR boundaries and tests; not part of normal runtime flow.
+ */
+export function resetSlotHostPool() {
+    var _a, _b;
+    pendingDestroy.clear();
+    for (const entry of pool.values()) {
+        (_a = entry.resizeObserver) === null || _a === void 0 ? void 0 : _a.disconnect();
+        (_b = entry.handle) === null || _b === void 0 ? void 0 : _b.unmount();
+        entry.cancelPendingMount();
+        entry.host.remove();
+    }
+    pool.clear();
+    for (const key of Object.keys(dirtyState))
+        delete dirtyState[key];
+    for (const key of Object.keys(closableState))
+        delete closableState[key];
+}
+/**
+ * Read the current ViewHandle for a slot. Returns undefined if the slot
+ * is not in the pool or hasn't finished mounting yet. Used by the close
+ * protocol to check closable and call canClose().
+ */
+export function getSlotHandle(slotId) {
+    var _a;
+    return (_a = pool.get(slotId)) === null || _a === void 0 ? void 0 : _a.handle;
+}
+/**
+ * Read the dirty state for a slot. Returns false if the slot is not in
+ * the pool. Used by the tab strip to render the dirty indicator.
+ */
+export function isSlotDirty(slotId) {
+    var _a;
+    return (_a = dirtyState[slotId]) !== null && _a !== void 0 ? _a : false;
+}
+/**
+ * Read the closable state for a slot. Returns false if the slot is not
+ * in the pool or hasn't finished mounting yet. Reactive — Svelte will
+ * re-render when the deferred mount sets the flag.
+ */
+export function isSlotClosable(slotId) {
+    var _a;
+    return (_a = closableState[slotId]) !== null && _a !== void 0 ? _a : false;
+}

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

@@ -0,0 +1,39 @@
+import type { LayoutNode } from './types';
+import type { App } from '../apps/types';
+/**
+ * Attach an app: create or hydrate its workspace-zone layout proxy,
+ * enforce the blueprint version gate, and take a refcount hold on all
+ * of the app's slot ids so root swaps don't destroy its pooled hosts.
+ * Does NOT switch the active root. Call switchToApp() separately.
+ */
+export declare function attachApp(app: App): void;
+/**
+ * Detach the currently-attached app. Releases its refcount holds; the
+ * pool's microtask cleanup drops the pooled hosts if they also have no
+ * active renderer refs. Must be called before attaching a different app.
+ */
+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
+ * mutations from splitter/drag/ops reach the renderer unchanged).
+ */
+export declare function activeLayout(): LayoutNode;
+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.
+ */
+export declare const layoutStore: {
+    readonly root: LayoutNode;
+};