@astrale-os/shell-react 0.1.0

package/dist/session/kernel-client.hook.d.ts

@@ -0,0 +1,9 @@
+/**
+ * useKernelClient (API §3) — `shell.kernel`, the raw bound kernel view, untouched
+ * (the untyped floor). The TYPED handles `useKernel()`/`useDomain(schema)` live in
+ * the schema module (§6).
+ */
+import type { KernelClient } from '@astrale-os/shell';
+/** `shell.kernel` — the raw bound kernel view, untouched (untyped floor). */
+export declare function useKernelClient(): KernelClient;
+//# sourceMappingURL=kernel-client.hook.d.ts.map

package/dist/session/kernel-client.hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernel-client.hook.d.ts","sourceRoot":"","sources":["../../src/session/kernel-client.hook.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAIrD,6EAA6E;AAC7E,wBAAgB,eAAe,IAAI,YAAY,CAE9C"}

package/dist/session/kernel-client.hook.js

@@ -0,0 +1,5 @@
+import { useShell } from './shell.hook';
+/** `shell.kernel` — the raw bound kernel view, untouched (untyped floor). */
+export function useKernelClient() {
+    return useShell().kernel;
+}

package/dist/session/kernel-instance.hook.d.ts

@@ -0,0 +1,9 @@
+export interface KernelInstance {
+    /** Kernel envelope endpoint this shell is bound to. */
+    readonly url: string;
+    /** Current kernel credential. Never cache; read per request. */
+    token(): string;
+}
+/** Low-level access for direct kernel-envelope calls and token exchange code. */
+export declare function useKernelInstance(): KernelInstance;
+//# sourceMappingURL=kernel-instance.hook.d.ts.map

package/dist/session/kernel-instance.hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernel-instance.hook.d.ts","sourceRoot":"","sources":["../../src/session/kernel-instance.hook.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,gEAAgE;IAChE,KAAK,IAAI,MAAM,CAAA;CAChB;AAED,iFAAiF;AACjF,wBAAgB,iBAAiB,IAAI,cAAc,CASlD"}

package/dist/session/kernel-instance.hook.js

@@ -0,0 +1,10 @@
+import { useMemo } from 'react';
+import { useKernelClient } from './kernel-client.hook';
+/** Low-level access for direct kernel-envelope calls and token exchange code. */
+export function useKernelInstance() {
+    const kernel = useKernelClient();
+    return useMemo(() => ({
+        url: kernel.url,
+        token: () => kernel.authToken(),
+    }), [kernel]);
+}

package/dist/session/provider.d.ts

@@ -0,0 +1,31 @@
+import type { Shell, ShellConfig } from '@astrale-os/shell';
+import type { ReactElement, ReactNode } from 'react';
+/** Global error channel payload (API §2). */
+export type ShellError = {
+    kind: 'refresh';
+    shape: unknown;
+    error: unknown;
+} | {
+    kind: 'mutation';
+    mutationId: string;
+    error: unknown;
+} | {
+    kind: 'connection';
+    error: unknown;
+};
+export interface ShellProviderProps {
+    /**
+     * Shell config — or a prebuilt Shell (tests, storybook). Keyed by identity: a
+     * config change disposes and reboots.
+     */
+    config: ShellConfig | Shell;
+    /** Rendered until status === 'ready'. Default: null. */
+    fallback?: ReactNode;
+    /** Rendered when boot fails; `retry` re-runs init. Default: rethrow to the nearest boundary. */
+    errorFallback?: (error: unknown, retry: () => void) => ReactNode;
+    /** Global error channel: warm-read refresh failures, rolled-back mutations, watch drops. */
+    onError?: (error: ShellError) => void;
+    children: ReactNode;
+}
+export declare function ShellProvider(props: ShellProviderProps): ReactElement | null;
+//# sourceMappingURL=provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/session/provider.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AA0BpD,6CAA6C;AAC7C,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAA;AAE1C,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,MAAM,EAAE,WAAW,GAAG,KAAK,CAAA;IAC3B,wDAAwD;IACxD,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,gGAAgG;IAChG,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,KAAK,SAAS,CAAA;IAChE,4FAA4F;IAC5F,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAA;IACrC,QAAQ,EAAE,SAAS,CAAA;CACpB;AAmBD,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,YAAY,GAAG,IAAI,CA0I5E"}

package/dist/session/provider.js

@@ -0,0 +1,165 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { createShell } from '@astrale-os/shell';
+/**
+ * ShellProvider — the composition root (API §2, SPEC §5): owns the shell boot
+ * state machine (a config OR a prebuilt Shell; `createShell → init → whoami →
+ * ready`), seats `ShellContext` and `GraphContext`, and registers its boot-retry
+ * into the per-shell connection store. One live shell per mounted provider,
+ * StrictMode/HMR-safe (deferred teardown), keyed on config identity. Children
+ * render only at `ready`, so useShell/useSelf are synchronous below.
+ */
+import { useCallback, useEffect, useMemo, useReducer, useRef, useState } from 'react';
+import { primeUser } from '../application/user/user.store';
+import { GraphContext } from '../graph/graph.context';
+import { baseMemoryFor, setMemoryErrorSink } from '../graph/memory/base';
+import { configIdentity, isShellConfig, resolveSelf } from './boot/boot';
+import { cancelTeardown, disposeShell, scheduleTeardown } from './boot/ownership';
+import { bootReducer, INITIAL_BOOT } from './boot/status';
+import { connectionStore } from './connection/connection.store';
+import { ShellContext } from './session.context';
+/**
+ * Map a memory event to the documented `ShellError` union (API §2). `refresh`
+ * (warm-read revalidation failure) and `mutation` (rolled-back write) are the
+ * two the channel promises; `divergence`/`invariant` are Tier-0/dev tripwires
+ * outside the union and are not bridged here.
+ */
+function toShellError(event) {
+    switch (event.kind) {
+        case 'refresh':
+            return { kind: 'refresh', shape: event.shape, error: event.error };
+        case 'mutation':
+            return { kind: 'mutation', mutationId: event.mutationId, error: event.error };
+        default:
+            return null;
+    }
+}
+export function ShellProvider(props) {
+    const { config, fallback, errorFallback, onError, children } = props;
+    const [state, dispatch] = useReducer(bootReducer, INITIAL_BOOT);
+    const [attempt, setAttempt] = useState(0);
+    const bootRef = useRef({ key: null, shell: null, generation: 0 });
+    const configRef = useRef(config);
+    configRef.current = config;
+    const onErrorRef = useRef(onError);
+    onErrorRef.current = onError;
+    const configKey = configIdentity(config);
+    const startBoot = useCallback((ref) => {
+        const generation = (ref.generation += 1);
+        dispatch({ type: 'connecting' });
+        let shell;
+        const current = configRef.current;
+        try {
+            shell = isShellConfig(current) ? createShell(current) : current;
+        }
+        catch (err) {
+            dispatch({ type: 'error', error: err });
+            onErrorRef.current?.({ kind: 'connection', error: err });
+            return;
+        }
+        ref.shell = shell;
+        void (async () => {
+            try {
+                await shell.init();
+                if (generation !== ref.generation)
+                    return;
+                const self = await resolveSelf(shell);
+                if (generation !== ref.generation)
+                    return;
+                // Pre-resolve the OS-plane user binding (API §2/§12.2) — NON-FATAL: a
+                // missing OS plane marks it unavailable without failing boot (whoami above
+                // stays the fatal gate). Seeds the user store so `useUser` is synchronous.
+                await primeUser(shell);
+                if (generation !== ref.generation)
+                    return;
+                dispatch({ type: 'ready', runtime: { shell, self } });
+            }
+            catch (err) {
+                if (generation !== ref.generation)
+                    return;
+                dispatch({ type: 'error', error: err });
+                onErrorRef.current?.({ kind: 'connection', error: err });
+            }
+        })();
+    }, []);
+    useEffect(() => {
+        const ref = bootRef.current;
+        // The shell this provider will run with once the effect settles: a prebuilt
+        // Shell is the config object itself; a config-built one is whatever this
+        // instance already booted (adopted on a StrictMode/HMR re-setup). Cancel any
+        // pending deferred teardown for it before deciding — this also cancels a
+        // teardown another provider scheduled for the SAME prebuilt Shell.
+        const current = configRef.current;
+        const adopting = isShellConfig(current) ? ref.shell : current;
+        if (adopting !== null)
+            cancelTeardown(adopting);
+        if (ref.key !== configKey) {
+            // First boot, config change, or a retry that cleared the key: reboot fresh.
+            if (ref.shell !== null) {
+                cancelTeardown(ref.shell);
+                disposeShell(ref.shell);
+            }
+            ref.key = configKey;
+            ref.shell = null;
+            startBoot(ref);
+        }
+        // Same key already booting/booted → adopt (StrictMode's second setup).
+        return () => {
+            // Defer teardown one macrotask; a synchronous re-setup (StrictMode/HMR or a
+            // different provider adopting the same prebuilt Shell) cancels it first and
+            // keeps the same live shell.
+            if (ref.shell !== null)
+                scheduleTeardown(ref.shell, ref);
+            else
+                ref.key = null;
+        };
+    }, [configKey, attempt, startBoot]);
+    const retry = useCallback(() => {
+        const ref = bootRef.current;
+        ref.generation += 1;
+        if (ref.shell !== null) {
+            disposeShell(ref.shell);
+            ref.shell = null;
+        }
+        ref.key = null;
+        dispatch({ type: 'connecting' });
+        setAttempt((a) => a + 1);
+    }, []);
+    // The base (default-scope) memory for the booted Shell — the SAME instance
+    // the graph/schema/nav hooks read through `graph/memory/scope.ts`. Seated in
+    // `GraphContext` so selection's liveness has a source; null until ready.
+    const shell = state.runtime?.shell ?? null;
+    const memory = useMemo(() => (shell === null ? null : baseMemoryFor(shell)), [shell]);
+    // Bridge the memory's event channel onto the provider `onError` (API §2/§8):
+    // warm-refresh failures and rolled-back mutations surface here rather than being
+    // swallowed. Registered while the booted shell is live; cleared on teardown.
+    useEffect(() => {
+        if (shell === null)
+            return;
+        setMemoryErrorSink(shell, (event) => {
+            const mapped = toShellError(event);
+            if (mapped !== null)
+                onErrorRef.current?.(mapped);
+        });
+        return () => setMemoryErrorSink(shell, null);
+    }, [shell]);
+    // Register this provider's boot-retry into the shell's connection store (rule 3),
+    // so `useConnection().retry` re-runs boot. Status/seq stay a stub ('ready'/0)
+    // until the transport-status + result-`seq` feed lands, with no surface change.
+    useEffect(() => {
+        if (shell === null)
+            return;
+        connectionStore(shell).setRetry(retry);
+    }, [shell, retry]);
+    if (state.status === 'error') {
+        // Wrapped in a fragment so the component's declared return type stays
+        // `ReactElement | null` — valid JSX under @types/react 18 AND 19 (the react
+        // peer range is >=18), even though `errorFallback`/`fallback` yield ReactNode.
+        if (errorFallback !== undefined)
+            return _jsx(_Fragment, { children: errorFallback(state.error, retry) });
+        throw state.error;
+    }
+    if (state.status !== 'ready' || state.runtime === null) {
+        return fallback !== undefined ? _jsx(_Fragment, { children: fallback }) : null;
+    }
+    return (_jsx(ShellContext.Provider, { value: state.runtime, children: _jsx(GraphContext.Provider, { value: memory, children: children }) }));
+}

package/dist/session/session.context.d.ts

@@ -0,0 +1,18 @@
+import type { KernelClient, Shell } from '@astrale-os/shell';
+/**
+ * whoami's node type, derived from the auth surface so shell-react needs no
+ * direct `@astrale-os/kernel-core` dependency (`Node` is not yet re-exported by
+ * kernel-client — API §14 G8). Swap for the blessed re-export when it lands.
+ */
+export type SelfNode = Awaited<ReturnType<KernelClient['auth']['whoami']>>;
+/** The live shell for a provider subtree (and, later, an `<ActAs>` subtree). */
+export interface ShellRuntime {
+    readonly shell: Shell;
+    /**
+     * whoami resolved at boot; the auth module (`useSelf`) reads it. Null when the
+     * bound kernel exposes no auth surface (a bare prebuilt Shell in tests).
+     */
+    readonly self: SelfNode | null;
+}
+export declare const ShellContext: import("react").Context<ShellRuntime | null>;
+//# sourceMappingURL=session.context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session.context.d.ts","sourceRoot":"","sources":["../../src/session/session.context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAS5D;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;AAE1E,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAA;CAC/B;AACD,eAAO,MAAM,YAAY,8CAA2C,CAAA"}

package/dist/session/session.context.js

@@ -0,0 +1,8 @@
+/**
+ * ShellContext — the shell session seat. Holds ONLY the stable `Shell` for a
+ * provider subtree (plus the whoami resolved once at boot). Connection state is
+ * NOT here: it is a provider-owned store read via `useConnection` (rule 3).
+ */
+import { createContext } from 'react';
+export const ShellContext = createContext(null);
+ShellContext.displayName = 'AstraleShellContext';

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

@@ -0,0 +1,4 @@
+import type { Shell } from '@astrale-os/shell';
+/** The live shell for this subtree. Throws outside a `<ShellProvider>`. */
+export declare function useShell(): Shell;
+//# sourceMappingURL=shell.hook.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shell.hook.d.ts","sourceRoot":"","sources":["../../src/session/shell.hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAW9C,2EAA2E;AAC3E,wBAAgB,QAAQ,IAAI,KAAK,CAMhC"}

package/dist/session/shell.hook.js

@@ -0,0 +1,15 @@
+/**
+ * useShell (API §3) — the live shell for this subtree, read from ShellContext.
+ * Throws outside a `<ShellProvider>`. The imperative floor every other session
+ * hook builds on.
+ */
+import { useContext } from 'react';
+import { ShellContext } from './session.context';
+/** The live shell for this subtree. Throws outside a `<ShellProvider>`. */
+export function useShell() {
+    const runtime = useContext(ShellContext);
+    if (runtime === null) {
+        throw new Error('useShell must be used within a <ShellProvider>');
+    }
+    return runtime.shell;
+}

package/dist/window/adopt.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Stash/adopt across re-key / re-parent (API §10). A live window handed off across
+ * an unmount so a remount can ADOPT it instead of closing + reloading it. Mirrors
+ * ShellProvider's deferred-teardown pattern: the unmounting host stashes the
+ * record, and either the remount takes it (one macrotask) or it disposes.
+ */
+import type { Window } from '@astrale-os/shell';
+import type { WindowState } from './lifecycle/states';
+import type { StageSlot } from './placement';
+export interface AdoptRecord {
+    readonly windowId: string;
+    readonly window: Window;
+    readonly slot: StageSlot;
+    readonly state: WindowState;
+    readonly targetId: string | undefined;
+    /** Close the window, release its slot, drop it from the registry (fired if unadopted). */
+    dispose(): void;
+}
+export interface AdoptStash {
+    /** Stash an unmounting host's live window; disposes after one macrotask if unadopted. */
+    stash(key: string, record: AdoptRecord): void;
+    /** Reclaim a stashed window for a remount of the same source, cancelling its dispose. */
+    take(key: string): AdoptRecord | null;
+}
+/** The pending-adoption registry — one per stage hub. */
+export declare function createAdoptStash(): AdoptStash;
+//# sourceMappingURL=adopt.d.ts.map

package/dist/window/adopt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adopt.d.ts","sourceRoot":"","sources":["../../src/window/adopt.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAE/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE5C,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,0FAA0F;IAC1F,OAAO,IAAI,IAAI,CAAA;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,yFAAyF;IACzF,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CAAA;IAC7C,yFAAyF;IACzF,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAAA;CACtC;AAED,yDAAyD;AACzD,wBAAgB,gBAAgB,IAAI,UAAU,CA2B7C"}

package/dist/window/adopt.js

@@ -0,0 +1,27 @@
+/** The pending-adoption registry — one per stage hub. */
+export function createAdoptStash() {
+    const pendingAdopt = new Map();
+    return {
+        stash(key, record) {
+            // Rapid same-key churn: an unclaimed prior stash disposes now.
+            const prior = pendingAdopt.get(key);
+            if (prior !== undefined) {
+                clearTimeout(prior.timer);
+                prior.record.dispose();
+            }
+            const timer = setTimeout(() => {
+                pendingAdopt.delete(key);
+                record.dispose();
+            }, 0);
+            pendingAdopt.set(key, { record, timer });
+        },
+        take(key) {
+            const entry = pendingAdopt.get(key);
+            if (entry === undefined)
+                return null;
+            clearTimeout(entry.timer);
+            pendingAdopt.delete(key);
+            return entry.record;
+        },
+    };
+}

package/dist/window/hooks/close-guard.hook.d.ts

@@ -0,0 +1,6 @@
+export type CloseVerdict = 'ack' | 'refuse' | {
+    readonly refuse: string;
+};
+export type CloseGuard = () => CloseVerdict | Promise<CloseVerdict>;
+export declare function useCloseGuard(guard: CloseGuard): void;
+//# sourceMappingURL=close-guard.hook.d.ts.map

package/dist/window/hooks/close-guard.hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"close-guard.hook.d.ts","sourceRoot":"","sources":["../../../src/window/hooks/close-guard.hook.ts"],"names":[],"mappings":"AAaA,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,QAAQ,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AACzE,MAAM,MAAM,UAAU,GAAG,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;AA0EnE,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAWrD"}

package/dist/window/hooks/close-guard.hook.js

@@ -0,0 +1,90 @@
+/**
+ * useCloseGuard (API §10) — child-side willClose negotiation. The parent sends a
+ * `willClose` intent before closing; the guard answers `closeAck` (allow) or
+ * `closeRefuse` (veto, with reason). Guards stack per shell and the last-mounted
+ * one wins; a single shared subscription owns the reply so a `willClose` is
+ * answered exactly once regardless of how many guards are mounted.
+ */
+import { useEffect, useRef } from 'react';
+import { useShell } from '../../session/shell.hook';
+function sendAck(parent) {
+    parent.send({
+        type: 'intent',
+        version: 1,
+        envelope: { name: 'closeAck', payload: {}, sender: { windowId: 'self' } },
+    });
+}
+function sendRefuse(parent, reason) {
+    parent.send({
+        type: 'intent',
+        version: 1,
+        envelope: { name: 'closeRefuse', payload: { reason }, sender: { windowId: 'self' } },
+    });
+}
+const HUBS = new WeakMap();
+function getCloseGuardHub(shell) {
+    const existing = HUBS.get(shell);
+    if (existing !== undefined)
+        return existing;
+    const stack = [];
+    let off = null;
+    function ensureSubscribed() {
+        if (off !== null)
+            return;
+        const parent = shell.parent;
+        if (parent === null)
+            return;
+        off = parent.on('intent', (message) => {
+            if (message.envelope.name !== 'willClose')
+                return;
+            const guard = stack[stack.length - 1];
+            if (guard === undefined)
+                return;
+            void answer(parent, guard);
+        });
+    }
+    async function answer(parent, guard) {
+        let verdict;
+        try {
+            verdict = await guard();
+        }
+        catch {
+            // A throwing guard must not trap the user in the window — allow the close.
+            verdict = 'ack';
+        }
+        if (verdict === 'ack')
+            sendAck(parent);
+        else if (verdict === 'refuse')
+            sendRefuse(parent, '');
+        else
+            sendRefuse(parent, verdict.refuse);
+    }
+    const hub = {
+        push(guard) {
+            stack.push(guard);
+            ensureSubscribed();
+            return () => {
+                const i = stack.lastIndexOf(guard);
+                if (i >= 0)
+                    stack.splice(i, 1);
+                if (stack.length === 0 && off !== null) {
+                    off();
+                    off = null;
+                }
+            };
+        },
+    };
+    HUBS.set(shell, hub);
+    return hub;
+}
+export function useCloseGuard(guard) {
+    const shell = useShell();
+    const guardRef = useRef(guard);
+    guardRef.current = guard;
+    useEffect(() => {
+        const hub = getCloseGuardHub(shell);
+        // Push a stable wrapper so a changed guard closure never re-registers
+        // (latest-handler semantics; unmount pops this exact entry).
+        return hub.push(() => guardRef.current());
+    }, [shell]);
+}

package/dist/window/hooks/target-node.hook.d.ts

@@ -0,0 +1,7 @@
+import type { ReadState } from '../../graph/memory/read/envelope';
+import type { Node } from '../lifecycle/mount';
+export interface NodeResult extends ReadState {
+    readonly node: Node | null;
+}
+export declare function useTargetNode(): NodeResult;
+//# sourceMappingURL=target-node.hook.d.ts.map

package/dist/window/hooks/target-node.hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"target-node.hook.d.ts","sourceRoot":"","sources":["../../../src/window/hooks/target-node.hook.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAA;AACjE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAA;AAK9C,MAAM,WAAW,UAAW,SAAQ,SAAS;IAC3C,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAA;CAC3B;AAeD,wBAAgB,aAAa,IAAI,UAAU,CAe1C"}

package/dist/window/hooks/target-node.hook.js

@@ -0,0 +1,77 @@
+/**
+ * useTargetNode (API §10) — inside a sandboxed view, the node it was opened on.
+ * The id starts from `shell.targetNodeId` (handshake) and a host `setTarget`
+ * intent retargets it; the id resolves to a live `Node` through the shell kernel.
+ *
+ * Honest subset (flagged): the read is a one-shot `kernel.get` re-run on id
+ * change, not a memory watch, so `live` is false. Once composed with `useNode(id)`
+ * it becomes real stale-while-revalidate liveness with no consumer change.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { idleReadState } from '../../graph/memory/read/idle';
+import { useShell } from '../../session/shell.hook';
+/** Address a bare node id by graph id (`@<id>`); pass paths/anchors through. */
+function toRef(id) {
+    return id.startsWith('/') || id.startsWith('@') ? id : `@${id}`;
+}
+const IDLE_READ = { node: null, pending: false, error: undefined };
+export function useTargetNode() {
+    const shell = useShell();
+    const [id, setId] = useState(() => shell.targetNodeId ?? null);
+    useEffect(() => {
+        const parent = shell.parent;
+        if (parent === null)
+            return;
+        return parent.on('intent', (message) => {
+            if (message.envelope.name !== 'setTarget')
+                return;
+            const nodeId = message.envelope.payload.nodeId;
+            if (typeof nodeId === 'string')
+                setId(nodeId);
+        });
+    }, [shell]);
+    return useNodeRead(shell.kernel, id);
+}
+/** One-shot get + refetch, in the read envelope. The graph-module seam. */
+function useNodeRead(kernel, id) {
+    const [snap, setSnap] = useState(IDLE_READ);
+    const aliveRef = useRef(true);
+    useEffect(() => {
+        aliveRef.current = true;
+        return () => {
+            aliveRef.current = false;
+        };
+    }, []);
+    const load = useCallback(async () => {
+        if (id === null) {
+            if (aliveRef.current)
+                setSnap(IDLE_READ);
+            return;
+        }
+        if (aliveRef.current)
+            setSnap((s) => ({ node: s.node, pending: true, error: undefined }));
+        try {
+            const node = await kernel.get(toRef(id));
+            if (aliveRef.current)
+                setSnap({ node: node ?? null, pending: false, error: undefined });
+        }
+        catch (error) {
+            if (aliveRef.current)
+                setSnap((s) => ({ node: s.node, pending: false, error }));
+        }
+    }, [kernel, id]);
+    useEffect(() => {
+        void load();
+    }, [load]);
+    if (id === null) {
+        return { ...idleReadState(), node: null };
+    }
+    return {
+        node: snap.node,
+        pending: snap.pending,
+        error: snap.error,
+        live: false,
+        seq: 0,
+        refetch: load,
+    };
+}

package/dist/window/hooks/views-for.hook.d.ts

@@ -0,0 +1,8 @@
+import type { PathLike } from '@astrale-os/kernel-client/graph';
+import type { ReadState } from '../../graph/memory/read/envelope';
+import type { Node, ViewDescriptor } from '../lifecycle/mount';
+export interface ViewsForResult extends ReadState {
+    readonly views: readonly ViewDescriptor[];
+}
+export declare function useViewsFor(node: Node | PathLike | null | undefined): ViewsForResult;
+//# sourceMappingURL=views-for.hook.d.ts.map

package/dist/window/hooks/views-for.hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"views-for.hook.d.ts","sourceRoot":"","sources":["../../../src/window/hooks/views-for.hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAA;AAW/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAA;AACjE,OAAO,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAK9D,MAAM,WAAW,cAAe,SAAQ,SAAS;IAC/C,QAAQ,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAA;CAC1C;AAiBD,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,QAAQ,GAAG,IAAI,GAAG,SAAS,GAAG,cAAc,CAqBpF"}

package/dist/window/hooks/views-for.hook.js

@@ -0,0 +1,51 @@
+import { K } from '@astrale-os/kernel-core';
+/**
+ * useViewsFor (API §10) — "what Views can render this node", as mountable
+ * `ViewDescriptor`s for the open-with menu. Backed one-shot (`live:false`) by the
+ * kernel `View.resolve` syscall, which derives the node's class and returns the
+ * caller-visible Views (USE-visibility enforced kernel-side), each with mount url.
+ */
+import { useMemo } from 'react';
+import { useAsyncResource } from '../../graph/async';
+import { useKernelClient } from '../../session/kernel-client.hook';
+/** The `View.resolve` wire address — the qualified static-method slug from the schema. */
+const VIEW_RESOLVE_METHOD = K.View.resolve.path.method.raw;
+const NO_VIEWS = Object.freeze([]);
+export function useViewsFor(node) {
+    const kernel = useKernelClient();
+    const target = resolvePath(node);
+    const res = useAsyncResource(target === null ? null : () => resolveViews(kernel, target), NO_VIEWS, [kernel, target]);
+    return useMemo(() => ({
+        views: res.data,
+        pending: res.pending,
+        error: res.error,
+        live: false,
+        seq: 0,
+        refetch: res.refetch,
+    }), [res.data, res.pending, res.error, res.refetch]);
+}
+/** Dispatch `View.resolve` and project its rows to mountable `ViewDescriptor`s. */
+async function resolveViews(kernel, node) {
+    const rows = (await kernel.call(VIEW_RESOLVE_METHOD, { node }));
+    if (rows === null || rows === undefined || rows.length === 0)
+        return NO_VIEWS;
+    return rows.map((r) => ({ id: r.id, path: r.path, url: r.url, handshake: r.handshake }));
+}
+/** A path/`@id` the kernel read surface accepts, or `null` for an idle subject. */
+function resolvePath(node) {
+    if (node === null || node === undefined)
+        return null;
+    if (typeof node === 'string') {
+        if (node.length === 0)
+            return null;
+        return node.startsWith('/') || node.startsWith('@') ? node : `@${node}`;
+    }
+    const obj = node;
+    if (typeof obj.path?.raw === 'string')
+        return obj.path.raw;
+    if (typeof obj.id === 'string')
+        return `@${obj.id}`;
+    if (typeof obj.raw === 'string')
+        return obj.raw;
+    return null;
+}

package/dist/window/hooks/window.hook.d.ts

@@ -0,0 +1,4 @@
+import type { WindowView } from '../hub';
+/** One window's live phase + shell `Window` (null id / unknown id → no window). */
+export declare function useWindow(windowId: string | null): WindowView;
+//# sourceMappingURL=window.hook.d.ts.map

package/dist/window/hooks/window.hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"window.hook.d.ts","sourceRoot":"","sources":["../../../src/window/hooks/window.hook.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAA;AAKxC,mFAAmF;AACnF,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,UAAU,CAK7D"}

package/dist/window/hooks/window.hook.js

@@ -0,0 +1,14 @@
+/**
+ * useWindow(id) (API §10) — one window's live phase + shell `Window` (null id /
+ * unknown id → a stable "no window"), reactive over the per-shell hub registry.
+ */
+import { useMemo, useSyncExternalStore } from 'react';
+import { useShell } from '../../session/shell.hook';
+import { getStageHub } from '../hub';
+/** One window's live phase + shell `Window` (null id / unknown id → no window). */
+export function useWindow(windowId) {
+    const shell = useShell();
+    const hub = useMemo(() => getStageHub(shell), [shell]);
+    const snapshot = useMemo(() => () => hub.registry.select(windowId), [hub, windowId]);
+    return useSyncExternalStore(hub.registry.subscribe, snapshot, snapshot);
+}