sh3-core 0.16.1 → 0.17.2

package/dist/layout/compact/drawerStore.svelte.js

@@ -0,0 +1,75 @@
+/*
+ * drawerStore — backing store for Sh3.drawers.
+ *
+ * In-memory state mirror; persistence integration (read/write
+ * AppLayoutBlob.drawers) lives in layout/store.svelte.ts and is wired
+ * via __setWriteThrough(...). When no blob is bound (home layout, satellite
+ * mode, tests), mutations stay in-memory only.
+ *
+ * The state object is keyed by anchor only; the per-(preset, viewport)
+ * dimension lives in the blob, not here. The bind helper in layoutStore
+ * rehydrates this store when the active preset or viewport class changes.
+ *
+ * File is .svelte.ts so the Svelte compiler processes the runes.
+ */
+function initial() {
+    return {
+        left: { open: false, activeSlotId: null },
+        right: { open: false, activeSlotId: null },
+        top: { open: false, activeSlotId: null },
+    };
+}
+const state = $state(initial());
+let writeThrough = null;
+function flush() {
+    if (writeThrough)
+        writeThrough(state);
+}
+export const drawerStore = {
+    get state() {
+        return state;
+    },
+    open(anchor) {
+        state[anchor].open = true;
+        flush();
+    },
+    close(anchor) {
+        state[anchor].open = false;
+        flush();
+    },
+    toggle(anchor) {
+        state[anchor].open = !state[anchor].open;
+        flush();
+    },
+    activate(anchor, slotId) {
+        state[anchor].activeSlotId = slotId;
+        flush();
+    },
+    /**
+     * Bind a write-through callback. layoutStore calls this when the active
+     * preset/viewport changes; the callback persists state into the
+     * AppLayoutBlob.drawers field. Pass null to unbind.
+     */
+    __setWriteThrough(cb) {
+        writeThrough = cb;
+    },
+    /**
+     * Replace the current state from a persisted snapshot. Used by
+     * layoutStore on preset/viewport-class change.
+     */
+    __hydrate(snapshot) {
+        for (const anchor of ['left', 'right', 'top']) {
+            state[anchor].open = snapshot[anchor].open;
+            state[anchor].activeSlotId = snapshot[anchor].activeSlotId;
+        }
+    },
+    /** Test-only reset. */
+    __reset() {
+        writeThrough = null;
+        const fresh = initial();
+        for (const anchor of ['left', 'right', 'top']) {
+            state[anchor].open = fresh[anchor].open;
+            state[anchor].activeSlotId = fresh[anchor].activeSlotId;
+        }
+    },
+};

package/dist/layout/compact/drawerStore.svelte.test.d.ts

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

package/dist/layout/compact/drawerStore.svelte.test.js

@@ -0,0 +1,43 @@
+/*
+ * Drawer store unit tests. These exercise the in-memory state machine
+ * only; persistence integration is covered in Task 11's blob
+ * round-trip test.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { drawerStore } from './drawerStore.svelte';
+describe('drawerStore', () => {
+    beforeEach(() => {
+        drawerStore.__reset();
+    });
+    it('starts with all drawers closed', () => {
+        expect(drawerStore.state.left).toEqual({ open: false, activeSlotId: null });
+        expect(drawerStore.state.right).toEqual({ open: false, activeSlotId: null });
+        expect(drawerStore.state.top).toEqual({ open: false, activeSlotId: null });
+    });
+    it('open(anchor) sets open true', () => {
+        drawerStore.open('left');
+        expect(drawerStore.state.left.open).toBe(true);
+    });
+    it('close(anchor) sets open false', () => {
+        drawerStore.open('left');
+        drawerStore.close('left');
+        expect(drawerStore.state.left.open).toBe(false);
+    });
+    it('toggle(anchor) flips open state', () => {
+        drawerStore.toggle('right');
+        expect(drawerStore.state.right.open).toBe(true);
+        drawerStore.toggle('right');
+        expect(drawerStore.state.right.open).toBe(false);
+    });
+    it('activate(anchor, slotId) sets activeSlotId', () => {
+        drawerStore.activate('left', 'sidebar-1');
+        expect(drawerStore.state.left.activeSlotId).toBe('sidebar-1');
+    });
+    it('reset returns to initial state', () => {
+        drawerStore.open('left');
+        drawerStore.activate('right', 'x');
+        drawerStore.__reset();
+        expect(drawerStore.state.left.open).toBe(false);
+        expect(drawerStore.state.right.activeSlotId).toBeNull();
+    });
+});

package/dist/layout/compact/resolveRole.d.ts

@@ -0,0 +1,6 @@
+import type { SlotRole } from '../types';
+interface SlotLike {
+    role?: SlotRole;
+}
+export declare function resolveRole(slot: SlotLike, viewDefault: SlotRole | undefined): SlotRole;
+export {};

package/dist/layout/compact/resolveRole.js

@@ -0,0 +1,13 @@
+/*
+ * Role resolution: slot-level wins, view-level fills in, default 'body'.
+ *
+ * Why this matters: authoring a layout shouldn't require knowing every
+ * view's natural role. The view's author knows best ('graphlive:hierarchy'
+ * is a sidebar by nature), so they declare `defaultRole: 'sidebar'` on
+ * the ViewHandle. The app retains override authority by writing `role`
+ * on the slot itself.
+ */
+export function resolveRole(slot, viewDefault) {
+    var _a, _b;
+    return (_b = (_a = slot.role) !== null && _a !== void 0 ? _a : viewDefault) !== null && _b !== void 0 ? _b : 'body';
+}

package/dist/layout/compact/resolveRole.test.d.ts

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

package/dist/layout/compact/resolveRole.test.js

@@ -0,0 +1,18 @@
+import { describe, it, expect } from 'vitest';
+import { resolveRole } from './resolveRole';
+describe('resolveRole', () => {
+    it('slot-level role wins over view default', () => {
+        expect(resolveRole({ role: 'body' }, 'sidebar')).toBe('body');
+        expect(resolveRole({ role: 'inspector' }, 'sidebar')).toBe('inspector');
+    });
+    it('view default fills in when slot role is unset', () => {
+        expect(resolveRole({}, 'sidebar')).toBe('sidebar');
+        expect(resolveRole({}, 'inspector')).toBe('inspector');
+    });
+    it('defaults to body when both unset', () => {
+        expect(resolveRole({}, undefined)).toBe('body');
+    });
+    it('treats undefined slot role same as missing field', () => {
+        expect(resolveRole({ role: undefined }, 'sidebar')).toBe('sidebar');
+    });
+});

package/dist/layout/compact/types.d.ts

@@ -0,0 +1,27 @@
+import type { LayoutNode, SlotNode, SlotRole } from '../types';
+export type DrawerAnchor = 'left' | 'right' | 'top';
+export interface DrawerSpec {
+    slots: Array<{
+        slotId: string;
+        viewId: string | null;
+        label: string;
+        icon?: string;
+        role: SlotRole;
+    }>;
+}
+export interface CompactRendering {
+    bodyRoot: LayoutNode;
+    drawers: {
+        left: DrawerSpec | null;
+        right: DrawerSpec | null;
+        top: DrawerSpec | null;
+    };
+}
+export interface DrawerState {
+    open: boolean;
+    activeSlotId: string | null;
+}
+export type DrawerStateMap = {
+    [anchor in DrawerAnchor]: DrawerState;
+};
+export declare const EMPTY_BODY: SlotNode;

package/dist/layout/compact/types.js

@@ -0,0 +1,15 @@
+/*
+ * Compact-rendering types. The derivation (./derive.ts) walks the
+ * canonical LayoutNode tree and emits a CompactRendering: a body root
+ * (the body-only sub-tree) plus per-anchor drawer specs.
+ *
+ * EMPTY_BODY is the placeholder used when an input tree has zero body
+ * slots — likely an authoring bug, but we render the chrome correctly
+ * rather than crashing.
+ */
+export const EMPTY_BODY = {
+    type: 'slot',
+    slotId: '__sh3core__:compact:empty',
+    viewId: null,
+    role: 'body',
+};

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

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

package/dist/layout/presets.compactVariant.test.js

@@ -0,0 +1,27 @@
+import { describe, it, expect } from 'vitest';
+import { resolveActiveTree } from './presets';
+describe('compact variant selection', () => {
+    const preset = {
+        name: 'main',
+        variants: {
+            default: { docked: { type: 'slot', slotId: 'a', viewId: 'v:a' }, floats: [] },
+            compact: { docked: { type: 'slot', slotId: 'b', viewId: 'v:b' }, floats: [] },
+        },
+    };
+    it('returns default variant when class is desktop', () => {
+        const tree = resolveActiveTree(preset, 'desktop');
+        expect(tree.docked.slotId).toBe('a');
+    });
+    it('returns compact variant when class is compact and present', () => {
+        const tree = resolveActiveTree(preset, 'compact');
+        expect(tree.docked.slotId).toBe('b');
+    });
+    it('falls back to default when compact variant is absent', () => {
+        const onlyDefault = {
+            name: 'main',
+            variants: { default: preset.variants.default },
+        };
+        const tree = resolveActiveTree(onlyDefault, 'compact');
+        expect(tree.docked.slotId).toBe('a');
+    });
+});

package/dist/layout/presets.d.ts

@@ -1,2 +1,14 @@
 import type { LayoutNode, LayoutTree, LayoutPreset, CanonicalPreset } from './types';
+import type { ViewportClass } from '../viewport/types';
+/**
+ * Pick the active LayoutTree for a preset given the current viewport
+ * class. Compact viewport uses `variants.compact` if authored, else
+ * falls back to `variants.default`. Desktop always uses `variants.default`.
+ *
+ * Per spec §4 (Override path): when the compact variant is taken as-is,
+ * any role-tagged sidebar/inspector slots in *it* still get extracted
+ * into drawers by the derive() transform. So an explicit override
+ * doesn't have to author drawer chrome — only the docked structure.
+ */
+export declare function resolveActiveTree(preset: CanonicalPreset, cls: ViewportClass): LayoutTree;
 export declare function normalizeInitialLayout(input: LayoutNode | LayoutTree | LayoutPreset[]): CanonicalPreset[];

package/dist/layout/presets.js

@@ -35,6 +35,22 @@ function canonicalizePreset(p) {
     }
     return { name: p.name, variants };
 }
+/**
+ * Pick the active LayoutTree for a preset given the current viewport
+ * class. Compact viewport uses `variants.compact` if authored, else
+ * falls back to `variants.default`. Desktop always uses `variants.default`.
+ *
+ * Per spec §4 (Override path): when the compact variant is taken as-is,
+ * any role-tagged sidebar/inspector slots in *it* still get extracted
+ * into drawers by the derive() transform. So an explicit override
+ * doesn't have to author drawer chrome — only the docked structure.
+ */
+export function resolveActiveTree(preset, cls) {
+    if (cls === 'compact' && preset.variants.compact) {
+        return preset.variants.compact;
+    }
+    return preset.variants.default;
+}
 export function normalizeInitialLayout(input) {
     if (Array.isArray(input)) {
         return input.map(canonicalizePreset);

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

@@ -23,6 +23,14 @@ export declare function releaseSlotHost(slotId: string, fromWrapper?: HTMLElemen
  * by HMR boundaries and tests; not part of normal runtime flow.
  */
 export declare function resetSlotHostPool(): void;
+/**
+ * Read-only peek at a pooled host. Returns the live entry without
+ * affecting refcounts. Used by Sh3Api.fields.walk and friends.
+ */
+export declare function peekSlotHost(slotId: string): {
+    host: HTMLElement;
+    refcount: number;
+} | undefined;
 /**
  * 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

package/dist/layout/slotHostPool.svelte.js

@@ -36,6 +36,7 @@ import { getView, __addViewRegistrationListener } from '../shards/registry';
 import { locateSlotIn } from './ops';
 import { activeLayout } from './store.svelte';
 import { scopeToString } from '../actions/scope-helpers';
+import { __disposeSlotContributions } from '../contributions';
 const pool = new Map();
 const pendingDestroy = new Set();
 /**
@@ -284,6 +285,7 @@ export function releaseSlotHost(slotId, fromWrapper) {
         if (!current || current.refcount > 0)
             return; // re-acquired, keep
         (_a = current.resizeObserver) === null || _a === void 0 ? void 0 : _a.disconnect();
+        __disposeSlotContributions(slotId);
         (_b = current.handle) === null || _b === void 0 ? void 0 : _b.unmount();
         current.cancelPendingMount();
         current.host.remove();
@@ -299,8 +301,9 @@ export function releaseSlotHost(slotId, fromWrapper) {
 export function resetSlotHostPool() {
     var _a, _b;
     pendingDestroy.clear();
-    for (const entry of pool.values()) {
+    for (const [slotId, entry] of pool.entries()) {
         (_a = entry.resizeObserver) === null || _a === void 0 ? void 0 : _a.disconnect();
+        __disposeSlotContributions(slotId);
         (_b = entry.handle) === null || _b === void 0 ? void 0 : _b.unmount();
         entry.cancelPendingMount();
         entry.host.remove();
@@ -312,6 +315,16 @@ export function resetSlotHostPool() {
         delete closableState[key];
     handleOverrides.clear();
 }
+/**
+ * Read-only peek at a pooled host. Returns the live entry without
+ * affecting refcounts. Used by Sh3Api.fields.walk and friends.
+ */
+export function peekSlotHost(slotId) {
+    const entry = pool.get(slotId);
+    if (!entry)
+        return undefined;
+    return { host: entry.host, refcount: entry.refcount };
+}
 /**
  * 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

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

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

package/dist/layout/store.drawers.svelte.test.js

@@ -0,0 +1,49 @@
+/*
+ * Drawer persistence round-trip — open the right drawer, simulate a
+ * remount (call attachApp twice on the same blob), assert the open
+ * state survived.
+ *
+ * The test uses the layoutStore's app-attach machinery directly rather
+ * than going through createShell, since the drawerStore <→ blob binding
+ * is the unit under test.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { flushSync } from 'svelte';
+import { attachApp, detachApp, __resetLayoutStoreForTest } from './store.svelte';
+import { drawerStore } from './compact/drawerStore.svelte';
+function fakeApp() {
+    // Minimal App shape — only fields attachApp reads.
+    return {
+        manifest: { id: 'test-app', layoutVersion: 5 },
+        initialLayout: {
+            type: 'split', direction: 'horizontal', sizes: [0.3, 0.7],
+            children: [
+                { type: 'slot', slotId: 'sb', viewId: 'v:sb', role: 'sidebar' },
+                { type: 'slot', slotId: 'body', viewId: 'v:body', role: 'body' },
+            ],
+        },
+    };
+}
+describe('drawer persistence round-trip', () => {
+    beforeEach(() => {
+        __resetLayoutStoreForTest();
+        drawerStore.__reset();
+    });
+    it('drawer state survives detach + re-attach', async () => {
+        const app = fakeApp();
+        attachApp(app);
+        // Run the proxy's initial $effect so the "first run skip" is consumed
+        // before our mutations. Subsequent mutations will trigger real flushes.
+        flushSync();
+        drawerStore.open('right');
+        drawerStore.activate('right', 'sb');
+        flushSync();
+        await new Promise((r) => queueMicrotask(r));
+        detachApp();
+        drawerStore.__reset();
+        expect(drawerStore.state.right.open).toBe(false);
+        attachApp(app);
+        expect(drawerStore.state.right.open).toBe(true);
+        expect(drawerStore.state.right.activeSlotId).toBe('sb');
+    });
+});

package/dist/layout/store.schemaVersion.test.d.ts

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

package/dist/layout/store.schemaVersion.test.js

@@ -0,0 +1,35 @@
+/*
+ * Schema-version regression — a stored AppLayoutBlob written under
+ * LAYOUT_SCHEMA_VERSION 4 (no role hints, no drawers) must load cleanly
+ * under v5. The bump is purely additive; if this test breaks, the
+ * additive promise is broken.
+ */
+import { describe, it, expect } from 'vitest';
+import { LAYOUT_SCHEMA_VERSION } from './types';
+describe('layout schema v4 → v5 backward compatibility', () => {
+    it('a v4 blob loads with all roles undefined and drawers absent', () => {
+        const tree = {
+            docked: {
+                type: 'split',
+                direction: 'horizontal',
+                sizes: [0.3, 0.7],
+                children: [
+                    { type: 'slot', slotId: 'a', viewId: 'view:a' },
+                    { type: 'slot', slotId: 'b', viewId: 'view:b' },
+                ],
+            },
+            floats: [],
+        };
+        const v4Blob = {
+            layoutVersion: 4,
+            activePreset: 'default',
+            presets: { default: { default: tree } },
+        };
+        const slotA = v4Blob.presets.default.default.docked.children[0];
+        expect(slotA.role).toBeUndefined();
+        expect(v4Blob.drawers).toBeUndefined();
+    });
+    it('LAYOUT_SCHEMA_VERSION is 5', () => {
+        expect(LAYOUT_SCHEMA_VERSION).toBe(5);
+    });
+});

package/dist/layout/store.svelte.js

@@ -31,10 +31,12 @@
  */
 import { createStateZones, peekZone, clearZone } from '../state/zones.svelte';
 import { acquireSlotHost, releaseSlotHost } from './slotHostPool.svelte';
-import { normalizeInitialLayout } from './presets';
+import { normalizeInitialLayout, resolveActiveTree } from './presets';
+import { viewportStore } from '../viewport/store.svelte';
 import { collectTreeSlotRefs } from './tree-walk';
 import { bindPresetBlob, unbindPresetBlob } from '../overlays/presets';
 import { getRegisteredApp } from '../apps/registry.svelte';
+import { drawerStore } from './compact/drawerStore.svelte';
 // ---------- orphan cleanup of pre-phase-8 sh3 layout key ----------------
 // Legacy pre-phase-8 orphan cleanup. The literal '__shell__' here is
 // intentional — it clears data written under the old reserved id before
@@ -140,6 +142,44 @@ export function attachApp(app) {
     // so shards can read/switch presets from their activate() hook.
     appEntry = { appId: app.manifest.id, proxy, heldSlotIds: [] };
     bindPresetBlob(proxy);
+    bindDrawerStoreToBlob(proxy);
+}
+/**
+ * Sync drawerStore <→ AppLayoutBlob.drawers.
+ *
+ * On attach (or preset/viewport change): read the persisted snapshot for
+ * (activePreset, 'compact') and hydrate drawerStore. Bind a
+ * write-through callback so subsequent mutations persist.
+ *
+ * v1 only persists the 'compact' viewport class; future viewport classes
+ * (e.g. 'phone') would extend this map without schema work.
+ */
+function bindDrawerStoreToBlob(blob) {
+    const presetName = blob.activePreset;
+    const ensure = () => {
+        if (!blob.drawers)
+            blob.drawers = {};
+        if (!blob.drawers[presetName])
+            blob.drawers[presetName] = {};
+        if (!blob.drawers[presetName].compact) {
+            blob.drawers[presetName].compact = {
+                left: { open: false, activeSlotId: null },
+                right: { open: false, activeSlotId: null },
+                top: { open: false, activeSlotId: null },
+            };
+        }
+        return blob.drawers;
+    };
+    const persisted = ensure();
+    drawerStore.__hydrate(persisted[presetName].compact);
+    drawerStore.__setWriteThrough((next) => {
+        const drawers = ensure();
+        drawers[presetName].compact = {
+            left: Object.assign({}, next.left),
+            right: Object.assign({}, next.right),
+            top: Object.assign({}, next.top),
+        };
+    });
 }
 /**
  * Second-phase attach: take refcount holds on every slot in the active
@@ -231,6 +271,12 @@ export function detachApp() {
     if (!appEntry)
         return;
     unbindPresetBlob();
+    drawerStore.__setWriteThrough(null);
+    drawerStore.__hydrate({
+        left: { open: false, activeSlotId: null },
+        right: { open: false, activeSlotId: null },
+        top: { open: false, activeSlotId: null },
+    });
     for (const slotId of appEntry.heldSlotIds) {
         releaseSlotHost(slotId);
     }
@@ -271,7 +317,11 @@ const activeTree = $derived.by(() => {
         if (!preset) {
             throw new Error(`AppLayoutBlob active preset "${presetName}" not found in presets map`);
         }
-        return preset.default;
+        // Per ADR-024: when the viewport is compact and the preset declares
+        // a `compact` variant, that variant wins. Otherwise the default
+        // variant is used and the framework derives drawer chrome from
+        // role-tagged slots in it.
+        return resolveActiveTree({ name: presetName, variants: preset }, viewportStore.current.class);
     }
     return HOME_TREE;
 });

package/dist/layout/types.d.ts

@@ -1,5 +1,15 @@
 /** Axis along which a split node divides its children. */
 export type SplitDirection = 'horizontal' | 'vertical';
+/**
+ * Slot role hint. Inert on desktop; the framework reads it on small
+ * viewports to derive a compact rendering (sidebars/inspectors lift into
+ * drawer surfaces, body slots fill the page).
+ *
+ * Default `'body'`. Authored on a slot or tab entry; if unset, falls back
+ * to the view's `defaultRole` (registered via the shard contract). See
+ * `layout/compact/resolveRole.ts`.
+ */
+export type SlotRole = 'body' | 'sidebar' | 'inspector';
 /** How a child of a split node is sized. */
 export type SizeMode = 'fr' | 'px';
 /**
@@ -46,6 +56,11 @@ export interface TabEntry {
     label: string;
     /** Optional icon hint (not yet rendered in phase 8). */
     icon?: string;
+    /**
+     * Slot-role hint for compact rendering. Default `'body'` via
+     * `resolveRole(slot, viewDefault)`. Inert on desktop.
+     */
+    role?: SlotRole;
     /**
      * Caller-supplied instance data, threaded to `MountContext.meta`.
      * Ephemeral — not serialized with the layout tree.
@@ -86,6 +101,11 @@ export interface SlotNode {
     slotId: string;
     /** View id to mount into this slot, or null for an empty slot. */
     viewId: string | null;
+    /**
+     * Slot-role hint for compact rendering. Default `'body'` via
+     * `resolveRole(slot, viewDefault)`. Inert on desktop.
+     */
+    role?: SlotRole;
     /**
      * Caller-supplied instance data, threaded to `MountContext.meta`.
      * Ephemeral — not serialized with the layout tree. Mirrors
@@ -187,7 +207,7 @@ export type TreeRootRef = {
  * 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 = 4;
+export declare const LAYOUT_SCHEMA_VERSION = 5;
 /**
  * The wire shape of a persisted layout in the workspace state zone.
  * One blob per sh3 (or per program, once per-program layouts exist);
@@ -208,6 +228,14 @@ export interface PersistedLayout {
  * The `attachApp` read path wraps that shape into the new form rather
  * than discarding it; see `layout/store.svelte.ts`.
  */
+/**
+ * Persisted per-anchor drawer state — open flag and active slot id.
+ * Lives on `AppLayoutBlob.drawers[presetName][viewportClass][anchor]`.
+ */
+export interface DrawerStateBlob {
+    open: boolean;
+    activeSlotId: string | null;
+}
 export interface AppLayoutBlob {
     layoutVersion: number;
     /** Name of the currently-active preset. Must be a key of `presets`. */
@@ -222,4 +250,18 @@ export interface AppLayoutBlob {
             [variantName: string]: LayoutTree;
         };
     };
+    /**
+     * Drawer state keyed by `(presetName, viewportClass)`. Optional so
+     * legacy blobs without this field still load. v1 only writes the
+     * `'compact'` viewport-class key. See ADR-024.
+     */
+    drawers?: {
+        [presetName: string]: {
+            [viewportClass: string]: {
+                left: DrawerStateBlob;
+                right: DrawerStateBlob;
+                top: DrawerStateBlob;
+            };
+        };
+    };
 }

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 = 4;
+export const LAYOUT_SCHEMA_VERSION = 5;