@astrale-os/shell-react 0.1.0

package/dist/schema/write.js

@@ -0,0 +1,45 @@
+const writableCache = new WeakMap();
+export function writableFor(kernel, memory) {
+    let entry = writableCache.get(kernel);
+    if (entry === undefined) {
+        const pathIndex = new Map();
+        entry = { writable: withMemoryWrites(kernel, memory, pathIndex), pathIndex };
+        writableCache.set(kernel, entry);
+    }
+    return entry;
+}
+/**
+ * Wrap a session view so `updateNode`/`createNode` route through the memory's
+ * optimistic write shorthands. `BoundNode.update` addresses a node by `@<id>`,
+ * but the memory indexes entities by tree path — so an `@<id>` ref is translated
+ * through `pathIndex` (populated at bind time). A ref that is NOT indexed (a node
+ * that was never read through a hook) falls back to the raw kernel-client floor:
+ * it still dispatches, just without the overlay — matching the imperative floor.
+ */
+function withMemoryWrites(kernel, memory, pathIndex) {
+    const base = kernel;
+    const rawUpdate = base.updateNode.bind(base);
+    return {
+        ...kernel,
+        updateNode: (cls, ref, props) => {
+            const path = treePathFor(pathIndex, ref);
+            return path !== null ? memory.update(path, props) : rawUpdate(cls, ref, props);
+        },
+        createNode: (cls, at, props) => memory.create(cls, at, props),
+        // Credential rebind stays on the raw kernel-client floor (§6 note).
+        as: (cred) => base.as(cred),
+    };
+}
+/** The tree path an `@<id>` write ref maps to, via the bind-time index; else null. */
+function treePathFor(pathIndex, ref) {
+    if (typeof ref !== 'string' || !ref.startsWith('@'))
+        return null;
+    return pathIndex.get(ref.slice(1)) ?? null;
+}
+/** Record a bound node's `id → tree path` so the write cap can address it. */
+export function recordPath(pathIndex, node) {
+    const n = node;
+    if (n !== null && typeof n.id === 'string' && typeof n.path?.raw === 'string') {
+        pathIndex.set(n.id, n.path.raw);
+    }
+}

package/dist/selection/index.d.ts

@@ -0,0 +1,4 @@
+export { SelectionScope } from './scope.context';
+export type { Selection, SelectionScopeProps } from './scope.context';
+export { useSelection } from './selection.hook';
+//# sourceMappingURL=index.d.ts.map

package/dist/selection/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/selection/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAChD,YAAY,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/selection/index.js

@@ -0,0 +1,4 @@
+// selection — API §9. SelectionScope + useSelection: an insertion-ordered id set
+// with an anchor, projected to LIVE memory nodes.
+export { SelectionScope } from './scope.context';
+export { useSelection } from './selection.hook';

package/dist/selection/live.d.ts

@@ -0,0 +1,21 @@
+import type { GraphMemory } from '@astrale-os/kernel-client/store';
+/** A live memory node — the non-null projection of a point read. */
+export type SelectionNode = NonNullable<ReturnType<GraphMemory['getSnapshot']>['node']>;
+export type NodeId = SelectionNode['id'];
+/**
+ * The in-scope graph memory, structurally narrowed. Reads the base memory the
+ * provider seats in `GraphContext`, defensively so selection also works under a
+ * bare/fake context (tests) or before one is mounted.
+ */
+export declare function useMemory(): GraphMemory | null;
+export interface LiveSnapshot {
+    readonly aliveIds: readonly NodeId[];
+    readonly nodes: readonly SelectionNode[];
+}
+/**
+ * Subscribe to each id's node shape and project the surviving nodes. The result
+ * keeps a stable reference across renders when membership and node identities
+ * are unchanged (useSyncExternalStore contract).
+ */
+export declare function useLiveNodes(orderedIds: readonly NodeId[], memory: GraphMemory | null): LiveSnapshot;
+//# sourceMappingURL=live.d.ts.map

package/dist/selection/live.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live.d.ts","sourceRoot":"","sources":["../../src/selection/live.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAA2B,MAAM,iCAAiC,CAAA;AAc3F,oEAAoE;AACpE,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC,UAAU,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAA;AACvF,MAAM,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAA;AAyBxC;;;;GAIG;AACH,wBAAgB,SAAS,IAAI,WAAW,GAAG,IAAI,CAO9C;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAA;CACzC;AAeD;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,MAAM,EAAE,WAAW,GAAG,IAAI,GACzB,YAAY,CA4Dd"}

package/dist/selection/live.js

@@ -0,0 +1,116 @@
+/**
+ * Selection liveness (API §9) — resolve the scope's ids to LIVE memory nodes, and
+ * the node types the selection speaks. Each id is subscribed as an independent
+ * point-read shape; an id drops ONLY once its shape has SETTLED to absence (the
+ * fixed latch) — a cold shape whose point-read has not landed is kept alive with
+ * no node, so a selection made from a children row is never self-cleared before
+ * its fetch resolves. Degrades to no nodes (ids kept) when no memory is in scope.
+ */
+import { useCallback, useContext, useRef, useSyncExternalStore } from 'react';
+import { GraphContext } from '../graph/graph.context';
+const LIVE_OPTS = { live: true };
+const EMPTY_NODES = [];
+const NOOP = () => { };
+/** Point-read shape addressing a node by its graph id. */
+function nodeShape(id) {
+    return `@${id}`;
+}
+/**
+ * A null-node id is a CONFIRMED absence (drop it) only when the shape settled
+ * there: it was seen warm and is now gone (deletion), or a live subscription has
+ * finished fetching and found nothing (mask/never-existed). A never-warm, not-
+ * yet-fetched (cold/pending) shape is NOT absence — the id stays alive, no node.
+ */
+function isConfirmedAbsent(snap, id, everWarm) {
+    if (everWarm.has(id))
+        return true;
+    return snap.live === true && snap.pending === false;
+}
+/**
+ * The in-scope graph memory, structurally narrowed. Reads the base memory the
+ * provider seats in `GraphContext`, defensively so selection also works under a
+ * bare/fake context (tests) or before one is mounted.
+ */
+export function useMemory() {
+    const ctx = useContext(GraphContext);
+    return ctx !== null &&
+        typeof ctx.subscribe === 'function' &&
+        typeof ctx.getSnapshot === 'function'
+        ? ctx
+        : null;
+}
+function unchanged(prev, aliveIds, nodes) {
+    // `aliveIds` and `nodes` can differ in length (a cold id is alive with no node
+    // yet), so compare the two lists independently.
+    if (prev.aliveIds.length !== aliveIds.length || prev.nodes.length !== nodes.length)
+        return false;
+    for (let i = 0; i < aliveIds.length; i += 1)
+        if (prev.aliveIds[i] !== aliveIds[i])
+            return false;
+    for (let i = 0; i < nodes.length; i += 1)
+        if (prev.nodes[i] !== nodes[i])
+            return false;
+    return true;
+}
+/**
+ * Subscribe to each id's node shape and project the surviving nodes. The result
+ * keeps a stable reference across renders when membership and node identities
+ * are unchanged (useSyncExternalStore contract).
+ */
+export function useLiveNodes(orderedIds, memory) {
+    // Stands in for `orderedIds` in the callback deps (a fresh array each render).
+    const idsKey = orderedIds.join(' ');
+    const cache = useRef(null);
+    // Ids whose shape has been seen warm at least once — a later null is a deletion
+    // (confirmed absence), whereas a never-warm null is merely cold. Monotonic, so
+    // re-reading getSnapshot within a render is idempotent (useSyncExternalStore-safe).
+    const everWarm = useRef(new Set());
+    const getSnapshot = useCallback(() => {
+        let aliveIds;
+        let nodes;
+        if (memory === null) {
+            // No liveness source: keep the ids, resolve no nodes.
+            aliveIds = orderedIds;
+            nodes = EMPTY_NODES;
+        }
+        else {
+            const seen = everWarm.current;
+            const a = [];
+            const n = [];
+            for (const id of orderedIds) {
+                const snap = memory.getSnapshot(nodeShape(id), LIVE_OPTS);
+                const node = snap.node;
+                if (node !== null) {
+                    seen.add(id);
+                    a.push(id);
+                    n.push(node);
+                }
+                else if (!isConfirmedAbsent(snap, id, seen)) {
+                    // Cold / not-yet-fetched: keep the id alive, no node yet — never a
+                    // premature drop (the critical self-clear this guards against).
+                    a.push(id);
+                }
+                // else: settled absence (deleted/masked) → drops from ids and nodes.
+            }
+            aliveIds = a;
+            nodes = n;
+        }
+        const prev = cache.current;
+        if (prev !== null && prev.memory === memory && unchanged(prev.snap, aliveIds, nodes)) {
+            return prev.snap;
+        }
+        const snap = { aliveIds, nodes };
+        cache.current = { memory, snap };
+        return snap;
+    }, [memory, idsKey]);
+    const subscribe = useCallback((onStoreChange) => {
+        if (memory === null || orderedIds.length === 0)
+            return NOOP;
+        const unsubs = orderedIds.map((id) => memory.subscribe(nodeShape(id), onStoreChange, LIVE_OPTS));
+        return () => {
+            for (const unsub of unsubs)
+                unsub();
+        };
+    }, [memory, idsKey]);
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}

package/dist/selection/scope.context.d.ts

@@ -0,0 +1,26 @@
+import type { ReactElement, ReactNode } from 'react';
+import type { NodeId, SelectionNode } from './live';
+/** The value `useSelection()` returns (API §9). */
+export interface Selection {
+    /** Selected ids, insertion-ordered. A deleted node drops out. */
+    readonly ids: readonly NodeId[];
+    /** LIVE nodes for `ids`, same order — a deleted node drops out here too. */
+    readonly nodes: readonly SelectionNode[];
+    /** Last explicit pick; null when empty or the anchor node is gone. Range math is caller-side. */
+    readonly anchor: NodeId | null;
+    has(id: NodeId): boolean;
+    set(ids: readonly NodeId[]): void;
+    add(id: NodeId): void;
+    toggle(id: NodeId): void;
+    clear(): void;
+}
+export interface SelectionScopeProps {
+    /** Seed selection (deduped); read once at mount. */
+    initial?: readonly NodeId[];
+    /** Fires when the selection changes — explicit ops AND liveness drops. Persist here. */
+    onChange?: (ids: readonly NodeId[]) => void;
+    children: ReactNode;
+}
+export declare const SelectionContext: import("react").Context<Selection | null>;
+export declare function SelectionScope(props: SelectionScopeProps): ReactElement;
+//# sourceMappingURL=scope.context.d.ts.map

package/dist/selection/scope.context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.context.d.ts","sourceRoot":"","sources":["../../src/selection/scope.context.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAUpD,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AAInD,mDAAmD;AACnD,MAAM,WAAW,SAAS;IACxB,iEAAiE;IACjE,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAA;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAA;IACxC,iGAAiG;IACjG,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAA;IACxB,GAAG,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAA;IACjC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,KAAK,IAAI,IAAI,CAAA;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,oDAAoD;IACpD,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3B,wFAAwF;IACxF,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAA;IAC3C,QAAQ,EAAE,SAAS,CAAA;CACpB;AAED,eAAO,MAAM,gBAAgB,2CAAwC,CAAA;AAsErE,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,YAAY,CA2CvE"}

package/dist/selection/scope.context.js

@@ -0,0 +1,100 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * SelectionScope (API §9) — an insertion-ordered id set with an anchor (the last
+ * explicit pick), projected to LIVE memory nodes. A deleted node drops out of
+ * `ids`/`nodes`, and the scope re-canonicalizes its stored set to match. Range
+ * math stays caller-side (read `anchor`). Seats the selection context.
+ */
+import { createContext, useCallback, useEffect, useMemo, useReducer, useRef } from 'react';
+import { useLiveNodes, useMemory } from './live';
+export const SelectionContext = createContext(null);
+SelectionContext.displayName = 'AstraleSelectionContext';
+function dedupe(ids) {
+    const seen = new Set();
+    const out = [];
+    for (const id of ids) {
+        if (!seen.has(id)) {
+            seen.add(id);
+            out.push(id);
+        }
+    }
+    return out;
+}
+function sameIds(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i += 1)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+function reducer(state, action) {
+    switch (action.t) {
+        case 'set': {
+            const ids = dedupe(action.ids);
+            const anchor = ids.length > 0 ? ids[ids.length - 1] : null;
+            if (sameIds(state.ids, ids) && state.anchor === anchor)
+                return state;
+            return { ids, anchor };
+        }
+        case 'add': {
+            if (state.ids.includes(action.id)) {
+                return state.anchor === action.id ? state : { ids: state.ids, anchor: action.id };
+            }
+            return { ids: [...state.ids, action.id], anchor: action.id };
+        }
+        case 'toggle': {
+            // Toggle-off keeps the anchor (the removed id is no longer a valid pivot).
+            if (state.ids.includes(action.id)) {
+                return { ids: state.ids.filter((x) => x !== action.id), anchor: state.anchor };
+            }
+            return { ids: [...state.ids, action.id], anchor: action.id };
+        }
+        case 'clear':
+            return state.ids.length === 0 && state.anchor === null ? state : { ids: [], anchor: null };
+        case 'prune': {
+            const anchorAlive = state.anchor === null || action.alive.includes(state.anchor);
+            if (sameIds(state.ids, action.alive)) {
+                return anchorAlive ? state : { ids: state.ids, anchor: null };
+            }
+            return { ids: action.alive, anchor: anchorAlive ? state.anchor : null };
+        }
+    }
+}
+function initState(initial) {
+    return { ids: dedupe(initial ?? []), anchor: null };
+}
+export function SelectionScope(props) {
+    const { initial, onChange, children } = props;
+    const [state, dispatch] = useReducer(reducer, initial, initState);
+    const memory = useMemory();
+    const { aliveIds, nodes } = useLiveNodes(state.ids, memory);
+    // Re-canonicalize stored state when liveness drops a node (or its anchor).
+    useEffect(() => {
+        const anchorDead = state.anchor !== null && !aliveIds.includes(state.anchor);
+        if (!sameIds(state.ids, aliveIds) || anchorDead)
+            dispatch({ t: 'prune', alive: aliveIds });
+    }, [aliveIds, state.ids, state.anchor]);
+    // Report changes (explicit ops AND liveness drops), skipping the initial mount.
+    const onChangeRef = useRef(onChange);
+    onChangeRef.current = onChange;
+    const mounted = useRef(false);
+    useEffect(() => {
+        if (!mounted.current) {
+            mounted.current = true;
+            return;
+        }
+        onChangeRef.current?.(aliveIds);
+    }, [aliveIds]);
+    const set = useCallback((ids) => dispatch({ t: 'set', ids }), []);
+    const add = useCallback((id) => dispatch({ t: 'add', id }), []);
+    const toggle = useCallback((id) => dispatch({ t: 'toggle', id }), []);
+    const clear = useCallback(() => dispatch({ t: 'clear' }), []);
+    const aliveSet = useMemo(() => new Set(aliveIds), [aliveIds]);
+    const aliveSetRef = useRef(aliveSet);
+    aliveSetRef.current = aliveSet;
+    const has = useCallback((id) => aliveSetRef.current.has(id), []);
+    const anchor = state.anchor !== null && aliveSet.has(state.anchor) ? state.anchor : null;
+    const value = useMemo(() => ({ ids: aliveIds, nodes, anchor, has, set, add, toggle, clear }), [aliveIds, nodes, anchor, has, set, add, toggle, clear]);
+    return _jsx(SelectionContext.Provider, { value: value, children: children });
+}

package/dist/selection/selection.hook.d.ts

@@ -0,0 +1,4 @@
+import type { Selection } from './scope.context';
+/** The nearest selection scope. Throws outside a `<SelectionScope>`. */
+export declare function useSelection(): Selection;
+//# sourceMappingURL=selection.hook.d.ts.map

package/dist/selection/selection.hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selection.hook.d.ts","sourceRoot":"","sources":["../../src/selection/selection.hook.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAIhD,wEAAwE;AACxE,wBAAgB,YAAY,IAAI,SAAS,CAMxC"}

package/dist/selection/selection.hook.js

@@ -0,0 +1,14 @@
+/**
+ * useSelection (API §9) — the nearest selection scope's value (ids/nodes/anchor +
+ * has/set/add/toggle/clear). Throws outside a `<SelectionScope>`.
+ */
+import { useContext } from 'react';
+import { SelectionContext } from './scope.context';
+/** The nearest selection scope. Throws outside a `<SelectionScope>`. */
+export function useSelection() {
+    const selection = useContext(SelectionContext);
+    if (selection === null) {
+        throw new Error('useSelection must be used within a <SelectionScope>');
+    }
+    return selection;
+}

package/dist/session/boot/boot.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The boot machine inputs (API §2): config identity (what triggers a reboot) and
+ * whoami resolution (`createShell → init → whoami → OS-user preresolve`). Kept
+ * pure of React so the provider's boot effect composes them.
+ */
+import type { Shell, ShellConfig } from '@astrale-os/shell';
+import type { SelfNode } from '../session.context';
+export declare function isShellConfig(config: ShellConfig | Shell): config is ShellConfig;
+/**
+ * Identity of a config — primitive fields only, so re-passing an inline `fetch`,
+ * `adapter`, `getCredential`, or `parentWindow` each render does not reboot;
+ * changing the kernel/credential does. A principal switch driven by a NEW
+ * `getCredential` closure (rather than a new `credential` string) is therefore
+ * NOT observed here — remount the provider (React `key`) to rebind it.
+ */
+export declare function configIdentity(config: ShellConfig | Shell): string;
+/** Resolve whoami when the bound kernel exposes an auth surface; else null. */
+export declare function resolveSelf(shell: Shell): Promise<SelfNode | null>;
+//# sourceMappingURL=boot.d.ts.map

package/dist/session/boot/boot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boot.d.ts","sourceRoot":"","sources":["../../../src/session/boot/boot.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAElD,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,GAAG,MAAM,IAAI,WAAW,CAEhF;AAeD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,GAAG,MAAM,CAYlE;AAED,+EAA+E;AAC/E,wBAAsB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAQxE"}

package/dist/session/boot/boot.js

@@ -0,0 +1,45 @@
+export function isShellConfig(config) {
+    return 'mode' in config;
+}
+let prebuiltCounter = 0;
+const prebuiltIds = new WeakMap();
+/** Stable id per prebuilt-Shell object reference (a new object reboots). */
+function prebuiltId(shell) {
+    let id = prebuiltIds.get(shell);
+    if (id === undefined) {
+        prebuiltCounter += 1;
+        id = `prebuilt#${prebuiltCounter}`;
+        prebuiltIds.set(shell, id);
+    }
+    return id;
+}
+/**
+ * Identity of a config — primitive fields only, so re-passing an inline `fetch`,
+ * `adapter`, `getCredential`, or `parentWindow` each render does not reboot;
+ * changing the kernel/credential does. A principal switch driven by a NEW
+ * `getCredential` closure (rather than a new `credential` string) is therefore
+ * NOT observed here — remount the provider (React `key`) to rebind it.
+ */
+export function configIdentity(config) {
+    if (!isShellConfig(config))
+        return prebuiltId(config);
+    if (config.mode === 'standalone') {
+        return [
+            'standalone',
+            config.kernelUrl,
+            config.credential ?? '',
+            config.mintIdentity ?? '',
+            config.windowId ?? '',
+        ].join('|');
+    }
+    return `sandboxed|${config.initTimeoutMs ?? ''}`;
+}
+/** Resolve whoami when the bound kernel exposes an auth surface; else null. */
+export async function resolveSelf(shell) {
+    const kernel = shell.kernel;
+    const auth = kernel.auth;
+    const whoami = auth?.whoami;
+    if (typeof whoami !== 'function')
+        return null;
+    return whoami.call(auth);
+}

package/dist/session/boot/ownership.d.ts

@@ -0,0 +1,18 @@
+/**
+ * StrictMode/HMR single-ownership + deferred teardown (API §2). A booted shell's
+ * dispose is deferred one macrotask keyed by the SHELL object, so a synchronous
+ * re-mount (StrictMode/HMR, or a different provider reusing a prebuilt Shell)
+ * adopts the same shell by cancelling the pending dispose before it fires.
+ */
+import type { Shell } from '@astrale-os/shell';
+export interface BootRef {
+    key: string | null;
+    shell: Shell | null;
+    /** Bumped per boot attempt; an in-flight init/whoami whose generation is stale is ignored. */
+    generation: number;
+}
+export declare function cancelTeardown(shell: Shell): void;
+/** Defer a shell's dispose one macrotask, resetting the owning ref when it fires. */
+export declare function scheduleTeardown(shell: Shell, ref: BootRef): void;
+export declare function disposeShell(shell: Shell): void;
+//# sourceMappingURL=ownership.d.ts.map

package/dist/session/boot/ownership.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ownership.d.ts","sourceRoot":"","sources":["../../../src/session/boot/ownership.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAE9C,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IACnB,8FAA8F;IAC9F,UAAU,EAAE,MAAM,CAAA;CACnB;AAWD,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAMjD;AAED,qFAAqF;AACrF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,GAAG,IAAI,CAUjE;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAQ/C"}

package/dist/session/boot/ownership.js

@@ -0,0 +1,39 @@
+/**
+ * Pending deferred teardowns keyed by the SHELL object (not the provider): a new
+ * adopter of the same shell — a StrictMode/HMR re-setup, OR a different provider
+ * instance reusing a prebuilt Shell — cancels the pending dispose before it
+ * fires, so the old provider's timer can never dispose a shell the new one just
+ * adopted. Config-built shells are unique per boot, so they never collide here.
+ */
+const pendingTeardowns = new WeakMap();
+export function cancelTeardown(shell) {
+    const timer = pendingTeardowns.get(shell);
+    if (timer !== undefined) {
+        clearTimeout(timer);
+        pendingTeardowns.delete(shell);
+    }
+}
+/** Defer a shell's dispose one macrotask, resetting the owning ref when it fires. */
+export function scheduleTeardown(shell, ref) {
+    cancelTeardown(shell);
+    const timer = setTimeout(() => {
+        pendingTeardowns.delete(shell);
+        ref.generation += 1;
+        disposeShell(shell);
+        if (ref.shell === shell)
+            ref.shell = null;
+        ref.key = null;
+    }, 0);
+    pendingTeardowns.set(shell, timer);
+}
+export function disposeShell(shell) {
+    // Best-effort: dispose never rejects meaningfully for a booted shell.
+    try {
+        const result = shell.dispose();
+        if (result instanceof Promise)
+            result.catch(() => undefined);
+    }
+    catch {
+        /* swallow — teardown must not throw */
+    }
+}

package/dist/session/boot/status.d.ts

@@ -0,0 +1,24 @@
+/**
+ * BootStatus union + transitions (API §2). The provider's boot state machine:
+ * `connecting → ready` (with the resolved runtime) or `connecting → error`. The
+ * reducer is the single transition table children render behind.
+ */
+import type { ShellRuntime } from '../session.context';
+export type BootStatus = 'connecting' | 'ready' | 'error';
+export interface BootState {
+    readonly status: BootStatus;
+    readonly error: unknown;
+    readonly runtime: ShellRuntime | null;
+}
+export type BootAction = {
+    readonly type: 'connecting';
+} | {
+    readonly type: 'ready';
+    readonly runtime: ShellRuntime;
+} | {
+    readonly type: 'error';
+    readonly error: unknown;
+};
+export declare const INITIAL_BOOT: BootState;
+export declare function bootReducer(state: BootState, action: BootAction): BootState;
+//# sourceMappingURL=status.d.ts.map

package/dist/session/boot/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../src/session/boot/status.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEtD,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,OAAO,GAAG,OAAO,CAAA;AAEzD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAAA;CACtC;AAED,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GAC/B;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;CAAE,GAC1D;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAA;AAEvD,eAAO,MAAM,YAAY,EAAE,SAAqE,CAAA;AAEhG,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,GAAG,SAAS,CAS3E"}

package/dist/session/boot/status.js

@@ -0,0 +1,11 @@
+export const INITIAL_BOOT = { status: 'connecting', error: undefined, runtime: null };
+export function bootReducer(state, action) {
+    switch (action.type) {
+        case 'connecting':
+            return state.status === 'connecting' && state.runtime === null ? state : INITIAL_BOOT;
+        case 'ready':
+            return { status: 'ready', error: undefined, runtime: action.runtime };
+        case 'error':
+            return { status: 'error', error: action.error, runtime: null };
+    }
+}

package/dist/session/connection/connection.hook.d.ts

@@ -0,0 +1,3 @@
+import type { ConnectionValue } from './connection.store';
+export declare function useConnection(): ConnectionValue;
+//# sourceMappingURL=connection.hook.d.ts.map

package/dist/session/connection/connection.hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.hook.d.ts","sourceRoot":"","sources":["../../../src/session/connection/connection.hook.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAKzD,wBAAgB,aAAa,IAAI,eAAe,CAG/C"}

package/dist/session/connection/connection.hook.js

@@ -0,0 +1,12 @@
+/**
+ * useConnection (API §3) — transport status + memory journal position + retry.
+ * Reads the provider-owned connection store for the subtree's Shell via
+ * `useSyncExternalStore` (rule 3). Throws outside a `<ShellProvider>`.
+ */
+import { useSyncExternalStore } from 'react';
+import { useShell } from '../shell.hook';
+import { connectionStore } from './connection.store';
+export function useConnection() {
+    const store = connectionStore(useShell());
+    return useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+}

package/dist/session/connection/connection.store.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The connection store (API §3, rule 3). ONE per Shell — the provider owns it and
+ * registers its `retry`; `useConnection` reads it via `useSyncExternalStore` so
+ * connection churn re-renders only its subscribers. `status`/`seq` are a pinned
+ * stub ('ready'/0) until the transport-status + result-`seq` feed lands (G6).
+ */
+import type { Shell } from '@astrale-os/shell';
+export type ConnectionStatus = 'connecting' | 'ready' | 'reconnecting' | 'error';
+/** Transport + memory-journal status for the subtree (API §3). */
+export interface ConnectionValue {
+    readonly status: ConnectionStatus;
+    readonly error: unknown;
+    readonly seq: number;
+    retry(): void;
+}
+export interface ConnectionStore {
+    subscribe(cb: () => void): () => void;
+    getSnapshot(): ConnectionValue;
+    /** The provider registers its boot-retry here; a change re-stamps the snapshot. */
+    setRetry(retry: () => void): void;
+}
+/** The one connection store for a Shell (created on first touch). */
+export declare function connectionStore(shell: Shell): ConnectionStore;
+//# sourceMappingURL=connection.store.d.ts.map

package/dist/session/connection/connection.store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.store.d.ts","sourceRoot":"","sources":["../../../src/session/connection/connection.store.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAE9C,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG,OAAO,GAAG,cAAc,GAAG,OAAO,CAAA;AAEhF,kEAAkE;AAClE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;IACjC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,KAAK,IAAI,IAAI,CAAA;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;IACrC,WAAW,IAAI,eAAe,CAAA;IAC9B,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,GAAG,IAAI,CAAA;CAClC;AA0BD,qEAAqE;AACrE,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,eAAe,CAO7D"}

package/dist/session/connection/connection.store.js

@@ -0,0 +1,31 @@
+const NOOP_RETRY = () => { };
+function createConnectionStore() {
+    const listeners = new Set();
+    let retry = NOOP_RETRY;
+    let snapshot = { status: 'ready', error: undefined, seq: 0, retry };
+    return {
+        subscribe(cb) {
+            listeners.add(cb);
+            return () => listeners.delete(cb);
+        },
+        getSnapshot: () => snapshot,
+        setRetry(next) {
+            if (next === retry)
+                return;
+            retry = next;
+            snapshot = { status: snapshot.status, error: snapshot.error, seq: snapshot.seq, retry };
+            for (const l of listeners)
+                l();
+        },
+    };
+}
+const stores = new WeakMap();
+/** The one connection store for a Shell (created on first touch). */
+export function connectionStore(shell) {
+    let s = stores.get(shell);
+    if (s === undefined) {
+        s = createConnectionStore();
+        stores.set(shell, s);
+    }
+    return s;
+}

package/dist/session/index.d.ts

@@ -0,0 +1,8 @@
+export { ShellProvider } from './provider';
+export type { ShellError, ShellProviderProps } from './provider';
+export { useShell } from './shell.hook';
+export { useKernelClient } from './kernel-client.hook';
+export { useKernelInstance } from './kernel-instance.hook';
+export type { KernelInstance } from './kernel-instance.hook';
+export { useConnection } from './connection/connection.hook';
+//# sourceMappingURL=index.d.ts.map

package/dist/session/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC1C,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAChE,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AACvC,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAA"}

package/dist/session/index.js

@@ -0,0 +1,6 @@
+// session — API §2 (provider) + §3 (session hooks). See SHELL_REACT_API.md.
+export { ShellProvider } from './provider';
+export { useShell } from './shell.hook';
+export { useKernelClient } from './kernel-client.hook';
+export { useKernelInstance } from './kernel-instance.hook';
+export { useConnection } from './connection/connection.hook';