@astrale-os/shell-react 0.1.0

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

@@ -0,0 +1,15 @@
+import type { Window } from '@astrale-os/shell';
+/** Every host-mounted window in this shell's tree, keyed by windowId. Reactive. */
+export declare function useWindows(): ReadonlyMap<string, Window>;
+/** One open window as a list entry. */
+export interface WindowListEntry {
+    readonly windowId: string;
+    readonly window: Window;
+}
+/**
+ * The open windows as a reactive, insertion-ordered list — the array form of
+ * `useWindows()`. The underlying map is referentially stable between mutations,
+ * so the derived array is too (no render churn).
+ */
+export declare function useWindowList(): readonly WindowListEntry[];
+//# sourceMappingURL=windows.hook.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"windows.hook.d.ts","sourceRoot":"","sources":["../../../src/window/hooks/windows.hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAc/C,mFAAmF;AACnF,wBAAgB,UAAU,IAAI,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAQxD;AAED,uCAAuC;AACvC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,SAAS,eAAe,EAAE,CAG1D"}

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

@@ -0,0 +1,25 @@
+/**
+ * useWindows / useWindowList (API §10) — reactive views over the windows a
+ * `ViewHost`/`AppHost` mounts through the per-shell hub. The shell exposes no
+ * window-change feed, so the hub registry (fed by the hosts) is the reactive
+ * source; windows mounted imperatively via `shell.mount` outside React are not
+ * tracked here — flagged in the module report as a shell foundation gap.
+ */
+import { useMemo, useSyncExternalStore } from 'react';
+import { useShell } from '../../session/shell.hook';
+import { getStageHub } from '../hub';
+/** Every host-mounted window in this shell's tree, keyed by windowId. Reactive. */
+export function useWindows() {
+    const shell = useShell();
+    const hub = useMemo(() => getStageHub(shell), [shell]);
+    return useSyncExternalStore(hub.registry.subscribe, hub.registry.getSnapshot, hub.registry.getSnapshot);
+}
+/**
+ * The open windows as a reactive, insertion-ordered list — the array form of
+ * `useWindows()`. The underlying map is referentially stable between mutations,
+ * so the derived array is too (no render churn).
+ */
+export function useWindowList() {
+    const windows = useWindows();
+    return useMemo(() => [...windows].map(([windowId, window]) => ({ windowId, window })), [windows]);
+}

package/dist/window/host.d.ts

@@ -0,0 +1,31 @@
+import type { NodeRefInput } from '@astrale-os/kernel-client';
+import type { CloseResult, IntentRegistry, MountCredential, SandboxProfile } from '@astrale-os/shell';
+import type { CSSProperties, ReactNode } from 'react';
+import type { ViewSource } from './lifecycle/mount';
+import type { WindowState } from './lifecycle/states';
+/** Imperative handle on a mounted `ViewHost` (API §10). */
+export interface ViewHostHandle {
+    readonly windowId: string | null;
+    close(opts?: {
+        force?: boolean;
+        timeoutMs?: number;
+    }): Promise<CloseResult>;
+    /** The one explicit remount. */
+    refresh(): void;
+}
+export type ViewHostProps = ViewSource & {
+    /** Node this view opens on — delivered as `targetNodeId`; a change retargets. */
+    node?: NodeRefInput;
+    capabilities?: {
+        intents: readonly (keyof IntentRegistry)[];
+    };
+    sandbox?: SandboxProfile | null;
+    credential?: MountCredential;
+    /** Rendered inside the anchor while the frame is not `ready`. */
+    fallback?: (state: WindowState) => ReactNode;
+    onStateChange?: (state: WindowState) => void;
+    className?: string;
+    style?: CSSProperties;
+};
+export declare const ViewHost: import("react").ForwardRefExoticComponent<ViewHostProps & import("react").RefAttributes<ViewHostHandle>>;
+//# sourceMappingURL=host.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/window/host.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,eAAe,EAEf,cAAc,EAEf,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EAAE,aAAa,EAAgB,SAAS,EAAE,MAAM,OAAO,CAAA;AAqBnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAcrD,2DAA2D;AAC3D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,KAAK,CAAC,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAC3E,gCAAgC;IAChC,OAAO,IAAI,IAAI,CAAA;CAChB;AAED,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG;IACvC,iFAAiF;IACjF,IAAI,CAAC,EAAE,YAAY,CAAA;IACnB,YAAY,CAAC,EAAE;QAAE,OAAO,EAAE,SAAS,CAAC,MAAM,cAAc,CAAC,EAAE,CAAA;KAAE,CAAA;IAC7D,OAAO,CAAC,EAAE,cAAc,GAAG,IAAI,CAAA;IAC/B,UAAU,CAAC,EAAE,eAAe,CAAA;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,SAAS,CAAA;IAC5C,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAA;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,aAAa,CAAA;CACtB,CAAA;AAYD,eAAO,MAAM,QAAQ,0GAyQpB,CAAA"}

package/dist/window/host.js

@@ -0,0 +1,270 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * ViewHost (API §10) — hosts one view. It renders a normal-flow anchor and
+ * projects that box onto a stage slot (ResizeObserver); the iframe lives in the
+ * stage, so reorder/re-key never reloads a healthy frame. It drives the
+ * `WindowState` machine, owns teardown (unmount closes its window), survives
+ * StrictMode double-mount, and downgrades a fallbackable handshake to plain.
+ */
+import { forwardRef, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, } from 'react';
+import { useShell } from '../session/shell.hook';
+import { getStageHub } from './hub';
+import { isFallbackableHandshakeError, refToId, resolveSource, sendSetTarget, sourceKey, } from './lifecycle/mount';
+import { rectOf, sameRect } from './placement';
+const MOUNTING = { phase: 'mounting' };
+export const ViewHost = forwardRef(function ViewHost(props, ref) {
+    const shell = useShell();
+    const hub = useMemo(() => getStageHub(shell), [shell]);
+    const anchorRef = useRef(null);
+    const slotRef = useRef(null);
+    const windowIdRef = useRef(null);
+    const aliveRef = useRef(true);
+    // The live window (set at ready / on adopt, cleared on close) — the unit an
+    // unmount stashes for a re-key/re-parent remount to adopt (§10).
+    const liveRef = useRef(null);
+    // Set by `refresh()`: the next unmount CLOSES (real remount) instead of stashing.
+    const refreshingRef = useRef(false);
+    // Last placed slot rect — reset when the slot changes; guards redundant places.
+    const lastRectRef = useRef(null);
+    const propsRef = useRef(props);
+    propsRef.current = props;
+    const [state, setState] = useState(MOUNTING);
+    const [refreshNonce, setRefreshNonce] = useState(0);
+    const mountKey = sourceKey(props);
+    const targetId = refToId(props.node);
+    const lastTargetRef = useRef(undefined);
+    const setStateSafe = (next) => {
+        if (!aliveRef.current)
+            return;
+        setState(next);
+        propsRef.current.onStateChange?.(next);
+    };
+    useEffect(() => {
+        aliveRef.current = true;
+        return () => {
+            aliveRef.current = false;
+        };
+    }, []);
+    useImperativeHandle(ref, () => ({
+        get windowId() {
+            return windowIdRef.current;
+        },
+        async close(opts) {
+            const id = windowIdRef.current;
+            if (id === null)
+                return { kind: 'noop' };
+            const result = await shell.close(id, opts);
+            if (result.kind === 'closed') {
+                windowIdRef.current = null;
+                liveRef.current = null;
+                hub.registry.remove(id);
+                setStateSafe({ phase: 'closed', windowId: id });
+            }
+            return result;
+        },
+        refresh() {
+            // A real remount: the next unmount closes (not stashes) so the frame reloads.
+            refreshingRef.current = true;
+            setRefreshNonce((n) => n + 1);
+        },
+    }), [shell, hub]);
+    // ── Placement: project the anchor box onto the current stage slot. Guarded by
+    //    rect-equality, so it is cheap to call on every commit (a sibling reorder
+    //    moves the anchor with no resize/scroll event — API §10).
+    const measure = useCallback(() => {
+        const slot = slotRef.current;
+        const anchor = anchorRef.current;
+        if (slot === null || anchor === null)
+            return;
+        const rect = rectOf(anchor);
+        const last = lastRectRef.current;
+        if (last !== null && sameRect(last, rect))
+            return;
+        lastRectRef.current = rect;
+        slot.place(rect);
+    }, []);
+    // ── Mount lifecycle. Keyed on the source identity + refresh nonce only — a
+    //    node (targetNodeId) change retargets via setTarget, never a remount. A
+    //    re-key/re-parent unmount+remount ADOPTS the live window through the hub
+    //    (deferred close), so a healthy iframe is never reloaded (§10).
+    useEffect(() => {
+        let cancelled = false;
+        let controllerWaiter = null;
+        // Consume the refresh flag: this setup is the (real) remount a refresh asked
+        // for, so it must NOT adopt the window its own cleanup just closed.
+        const wasRefresh = refreshingRef.current;
+        refreshingRef.current = false;
+        /** Close the window, release its slot, drop it from the registry (unadopted). */
+        function closeAndRelease(id, slot) {
+            void shell
+                .close(id, { force: false })
+                .then((r) => (r.kind === 'closed' ? undefined : shell.close(id, { force: true })))
+                .catch(() => { })
+                .finally(() => hub.registry.remove(id));
+            slot.release();
+        }
+        /** Stash the live window for adoption, or (on refresh) close it outright. */
+        function cleanup() {
+            cancelled = true;
+            controllerWaiter?.();
+            const live = liveRef.current;
+            const slot = slotRef.current;
+            slotRef.current = null;
+            windowIdRef.current = null;
+            liveRef.current = null;
+            lastRectRef.current = null;
+            if (live === null || slot === null) {
+                // Mount never resolved: release the slot; an in-flight mount self-closes.
+                slot?.release();
+                return;
+            }
+            const record = {
+                windowId: live.windowId,
+                window: live.window,
+                slot,
+                state: live.state,
+                targetId: live.targetId,
+                dispose: () => closeAndRelease(live.windowId, slot),
+            };
+            if (refreshingRef.current)
+                record.dispose();
+            else
+                hub.stashForAdopt(mountKey, record);
+        }
+        // Adopt a live window a just-unmounted same-source host left behind.
+        if (!wasRefresh) {
+            const adopted = hub.takeAdopt(mountKey);
+            if (adopted !== null) {
+                slotRef.current = adopted.slot;
+                windowIdRef.current = adopted.windowId;
+                liveRef.current = {
+                    windowId: adopted.windowId,
+                    window: adopted.window,
+                    state: adopted.state,
+                    targetId: adopted.targetId,
+                };
+                lastTargetRef.current = adopted.targetId;
+                hub.registry.upsert(adopted.windowId, adopted.window, adopted.state);
+                lastRectRef.current = null;
+                measure(); // reposition the surviving slot onto this host's anchor
+                setStateSafe(adopted.state);
+                return cleanup;
+            }
+        }
+        async function mountWith(handshake, downgraded) {
+            const p = propsRef.current;
+            let resolved;
+            try {
+                resolved = await resolveSource(shell.kernel, sourceOf(p));
+            }
+            catch (err) {
+                // No window yet (source resolution failed) — windowId honestly absent.
+                if (!cancelled)
+                    setStateSafe({ phase: 'crashed', error: err });
+                return;
+            }
+            if (cancelled)
+                return;
+            const usedHandshake = handshake === 'none' ? 'none' : resolved.handshake;
+            const deliveredTarget = refToId(p.node);
+            const params = {
+                host: slotRef.current.element,
+                url: resolved.url,
+                functionId: resolved.functionId,
+                capabilities: { intents: p.capabilities?.intents ?? [] },
+                targetNodeId: deliveredTarget,
+                sandbox: p.sandbox,
+                handshake: usedHandshake,
+                credential: p.credential,
+            };
+            try {
+                const win = await shell.mount(params);
+                // A StrictMode cleanup (or refresh) fired before mount resolved: adopt
+                // then immediately close so no orphan window survives.
+                if (cancelled) {
+                    void win.close({ force: true }).catch(() => { });
+                    return;
+                }
+                windowIdRef.current = win.windowId;
+                lastTargetRef.current = deliveredTarget;
+                const ready = downgraded
+                    ? { phase: 'ready', windowId: win.windowId, downgraded: true }
+                    : { phase: 'ready', windowId: win.windowId };
+                liveRef.current = {
+                    windowId: win.windowId,
+                    window: win.window,
+                    state: ready,
+                    targetId: deliveredTarget,
+                };
+                hub.registry.upsert(win.windowId, win.window, ready);
+                setStateSafe(ready);
+            }
+            catch (err) {
+                if (cancelled)
+                    return;
+                if (usedHandshake === 'shell' && isFallbackableHandshakeError(err)) {
+                    await mountWith('none', true);
+                    return;
+                }
+                setStateSafe({ phase: 'crashed', windowId: windowIdRef.current ?? undefined, error: err });
+            }
+        }
+        function begin(controller) {
+            if (cancelled || slotRef.current !== null)
+                return;
+            const slot = controller.acquire();
+            slotRef.current = slot;
+            lastRectRef.current = null;
+            measure();
+            setStateSafe(MOUNTING);
+            void mountWith('shell', false);
+        }
+        const existing = hub.getController();
+        if (existing !== null)
+            begin(existing);
+        else {
+            controllerWaiter = hub.onController((c) => {
+                if (c !== null)
+                    begin(c);
+            });
+        }
+        return cleanup;
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [hub, shell, mountKey, refreshNonce]);
+    // ── Retarget: a node change after ready hot-swaps via setTarget (no remount).
+    useEffect(() => {
+        if (state.phase !== 'ready')
+            return;
+        if (targetId === lastTargetRef.current)
+            return;
+        lastTargetRef.current = targetId;
+        if (targetId === undefined)
+            return;
+        sendSetTarget(shell, state.windowId, targetId);
+    }, [shell, state, targetId]);
+    // ── Placement observers: reposition on resize/scroll/anchor-resize.
+    useLayoutEffect(() => {
+        measure();
+        const anchor = anchorRef.current;
+        const ro = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(measure) : null;
+        if (anchor !== null)
+            ro?.observe(anchor);
+        window.addEventListener('resize', measure);
+        window.addEventListener('scroll', measure, true);
+        return () => {
+            ro?.disconnect();
+            window.removeEventListener('resize', measure);
+            window.removeEventListener('scroll', measure, true);
+        };
+    }, [measure]);
+    // Re-measure on EVERY commit (rect-equality-guarded): a sibling reorder moves
+    // the anchor with no resize/scroll event, so the slot must chase it here (§10).
+    useLayoutEffect(() => {
+        measure();
+    });
+    return (_jsx("div", { ref: anchorRef, className: props.className, style: props.style, children: state.phase !== 'ready' ? props.fallback?.(state) : null }));
+});
+/** Narrow props back to the bare `ViewSource` discriminated union. */
+function sourceOf(props) {
+    return 'url' in props ? { url: props.url } : { view: props.view };
+}

package/dist/window/hub.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The per-shell windows hub (API §10). `ViewStage` mounts once near the root while
+ * `ViewHost`s live anywhere, so they rendezvous through a hub keyed by the shared
+ * `Shell` instance (a `WeakMap`), not context. It owns the `WindowRegistry`
+ * (reactive store behind `useWindows`/`useWindow`, fed by the hosts), the stage
+ * controller (the slot layer, published by the stage), and the adopt stash.
+ */
+import type { Shell, Window } from '@astrale-os/shell';
+import type { AdoptRecord } from './adopt';
+import type { WindowState } from './lifecycle/states';
+import type { StageController } from './placement';
+/** A `useWindow` projection — a window's phase plus its shell `Window` (or none). */
+export type WindowView = WindowState & {
+    readonly window: Window | null;
+};
+export interface WindowRegistry {
+    /** Referentially stable between mutations (useSyncExternalStore contract). */
+    getSnapshot(): ReadonlyMap<string, Window>;
+    /** Stable projection for one window id (null id → a stable "no window"). */
+    select(windowId: string | null): WindowView;
+    subscribe(onChange: () => void): () => void;
+    /** Host writes: register/transition/drop a window. */
+    upsert(windowId: string, window: Window, state: WindowState): void;
+    patch(windowId: string, state: WindowState): void;
+    remove(windowId: string): void;
+}
+export interface StageHub {
+    readonly registry: WindowRegistry;
+    getController(): StageController | null;
+    /** Publish (stage mount) or retract (stage unmount) the slot layer. */
+    setController(controller: StageController | null): void;
+    /** Await the controller — fires immediately if one is already published. */
+    onController(cb: (controller: StageController | null) => void): () => void;
+    /** Stash an unmounting host's live window; disposes after one macrotask if unadopted. */
+    stashForAdopt(key: string, record: AdoptRecord): void;
+    /** Reclaim a stashed window for a remount of the same source, cancelling its dispose. */
+    takeAdopt(key: string): AdoptRecord | null;
+}
+/** The windows hub for a shell — one per shell object, created on first touch. */
+export declare function getStageHub(shell: Shell): StageHub;
+//# sourceMappingURL=hub.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hub.d.ts","sourceRoot":"","sources":["../../src/window/hub.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAEtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAYlD,qFAAqF;AACrF,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAA;AAEzE,MAAM,WAAW,cAAc;IAC7B,8EAA8E;IAC9E,WAAW,IAAI,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC1C,4EAA4E;IAC5E,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,UAAU,CAAA;IAC3C,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;IAC3C,sDAAsD;IACtD,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAAA;IAClE,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAAA;IACjD,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B;AAqED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAA;IACjC,aAAa,IAAI,eAAe,GAAG,IAAI,CAAA;IACvC,uEAAuE;IACvE,aAAa,CAAC,UAAU,EAAE,eAAe,GAAG,IAAI,GAAG,IAAI,CAAA;IACvD,4EAA4E;IAC5E,YAAY,CAAC,EAAE,EAAE,CAAC,UAAU,EAAE,eAAe,GAAG,IAAI,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IAC1E,yFAAyF;IACzF,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CAAA;IACrD,yFAAyF;IACzF,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAAA;CAC3C;AAID,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,QAAQ,CAkClD"}

package/dist/window/hub.js

@@ -0,0 +1,100 @@
+import { createAdoptStash } from './adopt';
+const NO_WINDOW = { phase: 'closed', windowId: '', window: null };
+function createWindowRegistry() {
+    const entries = new Map();
+    const listeners = new Set();
+    // Cached snapshots: rebuilt only on mutation, so repeated getSnapshot/select
+    // calls between changes return identical references (no render loop).
+    let windowsSnapshot = null;
+    let selectCache = new Map();
+    function invalidate() {
+        windowsSnapshot = null;
+        selectCache = new Map();
+        for (const l of listeners)
+            l();
+    }
+    return {
+        getSnapshot() {
+            if (windowsSnapshot === null) {
+                const map = new Map();
+                for (const [id, entry] of entries)
+                    map.set(id, entry.window);
+                windowsSnapshot = map;
+            }
+            return windowsSnapshot;
+        },
+        select(windowId) {
+            if (windowId === null)
+                return NO_WINDOW;
+            const cached = selectCache.get(windowId);
+            if (cached !== undefined)
+                return cached;
+            const entry = entries.get(windowId);
+            const view = entry
+                ? { ...entry.state, window: entry.window }
+                : { phase: 'closed', windowId, window: null };
+            selectCache.set(windowId, view);
+            return view;
+        },
+        subscribe(onChange) {
+            listeners.add(onChange);
+            return () => {
+                listeners.delete(onChange);
+            };
+        },
+        upsert(windowId, window, state) {
+            entries.set(windowId, { window, state });
+            invalidate();
+        },
+        patch(windowId, state) {
+            const entry = entries.get(windowId);
+            if (entry === undefined)
+                return;
+            entries.set(windowId, { window: entry.window, state });
+            invalidate();
+        },
+        remove(windowId) {
+            if (!entries.delete(windowId))
+                return;
+            invalidate();
+        },
+    };
+}
+const HUBS = new WeakMap();
+/** The windows hub for a shell — one per shell object, created on first touch. */
+export function getStageHub(shell) {
+    const existing = HUBS.get(shell);
+    if (existing !== undefined)
+        return existing;
+    const registry = createWindowRegistry();
+    let controller = null;
+    const waiters = new Set();
+    const adopt = createAdoptStash();
+    const hub = {
+        registry,
+        getController() {
+            return controller;
+        },
+        setController(next) {
+            controller = next;
+            for (const w of waiters)
+                w(next);
+        },
+        onController(cb) {
+            waiters.add(cb);
+            if (controller !== null)
+                cb(controller);
+            return () => {
+                waiters.delete(cb);
+            };
+        },
+        stashForAdopt(key, record) {
+            adopt.stash(key, record);
+        },
+        takeAdopt(key) {
+            return adopt.take(key);
+        },
+    };
+    HUBS.set(shell, hub);
+    return hub;
+}

package/dist/window/index.d.ts

@@ -0,0 +1,15 @@
+export { ViewStage } from './stage';
+export { ViewHost } from './host';
+export type { ViewHostProps, ViewHostHandle } from './host';
+export { useWindows, useWindowList } from './hooks/windows.hook';
+export type { WindowListEntry } from './hooks/windows.hook';
+export { useWindow } from './hooks/window.hook';
+export type { WindowView } from './hub';
+export { useViewsFor } from './hooks/views-for.hook';
+export type { ViewsForResult } from './hooks/views-for.hook';
+export { useTargetNode } from './hooks/target-node.hook';
+export { useCloseGuard } from './hooks/close-guard.hook';
+export type { CloseGuard, CloseVerdict } from './hooks/close-guard.hook';
+export type { ViewDescriptor, ViewSource, Node } from './lifecycle/mount';
+export type { WindowState } from './lifecycle/states';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/window/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACnC,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AACjC,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAA;AAC3D,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAChE,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAC/C,YAAY,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AACpD,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AACxD,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AACxE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAA;AACzE,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/window/index.js

@@ -0,0 +1,10 @@
+// window — API §10. ViewStage/ViewHost (the physical iframe-slot layer + a host
+// that projects placement into a slot), the reactive window hooks, the child-side
+// target-node + close-guard, and the (G5) view-resolution hook.
+export { ViewStage } from './stage';
+export { ViewHost } from './host';
+export { useWindows, useWindowList } from './hooks/windows.hook';
+export { useWindow } from './hooks/window.hook';
+export { useViewsFor } from './hooks/views-for.hook';
+export { useTargetNode } from './hooks/target-node.hook';
+export { useCloseGuard } from './hooks/close-guard.hook';

package/dist/window/lifecycle/mount.d.ts

@@ -0,0 +1,47 @@
+import type { NodeRefInput } from '@astrale-os/kernel-client';
+/**
+ * Mount orchestration (API §10) — resolve a `ViewSource` to something `shell.mount`
+ * accepts (url + handshake + functionId), the stable remount key, the delivered
+ * target id, the handshake-fallback predicate, and the parent→child setTarget
+ * hot-swap. A one-call `View.resolve` kernel contract does not exist yet — the
+ * bare-ref path is the honest subset, G5.
+ */
+import type { KernelClient, Shell } from '@astrale-os/shell';
+/** A live graph node, derived from the shell kernel read surface (G8 seam). */
+export type Node = NonNullable<Awaited<ReturnType<KernelClient['get']>>>;
+/** A View function resolved to something mountable (url + optional handshake). */
+export interface ViewDescriptor {
+    readonly id: string;
+    readonly path: string;
+    readonly url?: string;
+    readonly handshake?: string;
+}
+/**
+ * What a `ViewHost` mounts:
+ *  - `{ view }` — a View function (descriptor or ref), resolved to url + handshake.
+ *  - `{ url }`  — a handshake-less hosted view; mounts immediately (no 5s wait).
+ */
+export type ViewSource = {
+    readonly view: NodeRefInput | ViewDescriptor;
+} | {
+    readonly url: string;
+};
+export interface ResolvedSource {
+    readonly url: string;
+    readonly handshake: 'shell' | 'none';
+    readonly functionId: string;
+}
+/** Resolve a source; may hit the kernel for a bare/urless View ref (G5). */
+export declare function resolveSource(kernel: KernelClient, source: ViewSource): Promise<ResolvedSource>;
+/** A stable remount key: the same source identity must not remount. */
+export declare function sourceKey(source: ViewSource): string;
+/** The bare node id delivered as `targetNodeId` at mount / retarget. */
+export declare function refToId(ref: NodeRefInput | undefined): string | undefined;
+/**
+ * Fallbackable = the view didn't speak the shell protocol (timeout/failed), not a
+ * security refusal (origin mismatch) — only the former downgrades to plain.
+ */
+export declare function isFallbackableHandshakeError(err: unknown): boolean;
+/** Parent → child hot-swap of the target node (no remount) — API §10 setTarget. */
+export declare function sendSetTarget(shell: Shell, windowId: string, nodeId: string): void;
+//# sourceMappingURL=mount.d.ts.map

package/dist/window/lifecycle/mount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount.d.ts","sourceRoot":"","sources":["../../../src/window/lifecycle/mount.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAC7D;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAE5D,+EAA+E;AAC/E,MAAM,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;AAExE,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,cAAc,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAA;AAEpG,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,CAAA;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AA6CD,4EAA4E;AAC5E,wBAAsB,aAAa,CACjC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,UAAU,GACjB,OAAO,CAAC,cAAc,CAAC,CAgBzB;AAED,uEAAuE;AACvE,wBAAgB,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAOpD;AAED,wEAAwE;AACxE,wBAAgB,OAAO,CAAC,GAAG,EAAE,YAAY,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAKzE;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAGlE;AAED,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAMlF"}