@astrale-os/shell-react 0.2.8 → 0.2.10-beta.2

package/dist/window/host.js

@@ -4,12 +4,13 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * 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.
+ * StrictMode double-mount. The complete target-bound View is the sole source
+ * of mount identity, route, target, and handshake behavior.
  */
 import { forwardRef, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, } from 'react';
 import { useShell } from '../session/shell.hook.js';
 import { getStageHub } from './hub.js';
-import { isFallbackableHandshakeError, refToId, resolveSource, sendSetTarget, sourceKey, } from './lifecycle/mount.js';
+import { viewMountKey } from './lifecycle/mount.js';
 import { rectOf, sameRect } from './placement.js';
 const MOUNTING = { phase: 'mounting' };
 export const ViewHost = forwardRef(function ViewHost(props, ref) {
@@ -30,9 +31,7 @@ export const ViewHost = forwardRef(function ViewHost(props, ref) {
     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 mountKey = viewMountKey(props.view);
     const setStateSafe = (next) => {
         if (!aliveRef.current)
             return;
@@ -83,10 +82,9 @@ export const ViewHost = forwardRef(function ViewHost(props, ref) {
         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).
+    // ── Mount lifecycle. Keyed on complete target + route provenance and
+    //    refresh nonce. A same-selection re-key/re-parent can adopt the live
+    //    window; any target or provenance change necessarily remounts.
     useEffect(() => {
         let cancelled = false;
         let controllerWaiter = null;
@@ -123,7 +121,6 @@ export const ViewHost = forwardRef(function ViewHost(props, ref) {
                 window: live.window,
                 slot,
                 state: live.state,
-                targetId: live.targetId,
                 dispose: () => closeAndRelease(live.windowId, slot),
             };
             if (refreshingRef.current)
@@ -131,6 +128,14 @@ export const ViewHost = forwardRef(function ViewHost(props, ref) {
             else
                 hub.stashForAdopt(mountKey, record);
         }
+        /** A pre-ready failure must not leave an empty stage slot over the fallback UI. */
+        function crashAndRelease(error) {
+            const slot = slotRef.current;
+            slotRef.current = null;
+            lastRectRef.current = null;
+            slot?.release();
+            setStateSafe({ phase: 'crashed', windowId: windowIdRef.current ?? undefined, error });
+        }
         // Adopt a live window a just-unmounted same-source host left behind.
         if (!wasRefresh) {
             const adopted = hub.takeAdopt(mountKey);
@@ -141,9 +146,7 @@ export const ViewHost = forwardRef(function ViewHost(props, ref) {
                     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
@@ -151,34 +154,38 @@ export const ViewHost = forwardRef(function ViewHost(props, ref) {
                 return cleanup;
             }
         }
-        async function mountWith(handshake, downgraded) {
+        async function mountView() {
             const p = propsRef.current;
-            let resolved;
+            let sandbox;
             try {
-                resolved = await resolveSource(shell.kernel, sourceOf(p));
+                sandbox = typeof p.sandbox === 'function' ? p.sandbox(p.view) : p.sandbox;
             }
             catch (err) {
-                // No window yet (source resolution failed) — windowId honestly absent.
                 if (!cancelled)
-                    setStateSafe({ phase: 'crashed', error: err });
+                    crashAndRelease(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,
+                view: p.view,
+                capabilities: p.capabilities ?? {
+                    version: 1,
+                    navigation: {},
+                    actions: {},
+                    browser: {},
+                    access: {},
+                },
+                sandbox,
                 credential: p.credential,
+                ...(p.handshakeTimeoutMs === undefined
+                    ? {}
+                    : { handshakeTimeoutMs: p.handshakeTimeoutMs }),
+                ...(p.delegationTtlSeconds === undefined
+                    ? {}
+                    : { delegationTtlSeconds: p.delegationTtlSeconds }),
             };
             try {
-                const win = await shell.mount(params);
+                const win = await shell.openView(params);
                 // A StrictMode cleanup (or refresh) fired before mount resolved: adopt
                 // then immediately close so no orphan window survives.
                 if (cancelled) {
@@ -186,15 +193,11 @@ export const ViewHost = forwardRef(function ViewHost(props, ref) {
                     return;
                 }
                 windowIdRef.current = win.windowId;
-                lastTargetRef.current = deliveredTarget;
-                const ready = downgraded
-                    ? { phase: 'ready', windowId: win.windowId, downgraded: true }
-                    : { phase: 'ready', windowId: win.windowId };
+                const ready = { 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);
@@ -202,11 +205,7 @@ export const ViewHost = forwardRef(function ViewHost(props, ref) {
             catch (err) {
                 if (cancelled)
                     return;
-                if (usedHandshake === 'shell' && isFallbackableHandshakeError(err)) {
-                    await mountWith('none', true);
-                    return;
-                }
-                setStateSafe({ phase: 'crashed', windowId: windowIdRef.current ?? undefined, error: err });
+                crashAndRelease(err);
             }
         }
         function begin(controller) {
@@ -217,7 +216,7 @@ export const ViewHost = forwardRef(function ViewHost(props, ref) {
             lastRectRef.current = null;
             measure();
             setStateSafe(MOUNTING);
-            void mountWith('shell', false);
+            void mountView();
         }
         const existing = hub.getController();
         if (existing !== null)
@@ -231,17 +230,6 @@ export const ViewHost = forwardRef(function ViewHost(props, ref) {
         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();
@@ -264,7 +252,3 @@ export const ViewHost = forwardRef(function ViewHost(props, ref) {
     });
     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

@@ -23,6 +23,8 @@ export interface WindowRegistry {
     upsert(windowId: string, window: Window, state: WindowState): void;
     patch(windowId: string, state: WindowState): void;
     remove(windowId: string): void;
+    /** Shell writes: replace host and imperatively mounted windows from authoritative snapshots. */
+    sync(windows: ReadonlyMap<string, Window>): void;
 }
 export interface StageHub {
     readonly registry: WindowRegistry;

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

@@ -1 +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,YAAY,CAAA;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAYrD,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"}
+{"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,YAAY,CAAA;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAYrD,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;IAC9B,gGAAgG;IAChG,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;CACjD;AAkGD,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,CAoClD"}

package/dist/window/hub.js

@@ -58,8 +58,39 @@ function createWindowRegistry() {
                 return;
             invalidate();
         },
+        sync(windows) {
+            let changed = false;
+            for (const windowId of entries.keys()) {
+                if (!windows.has(windowId)) {
+                    entries.delete(windowId);
+                    changed = true;
+                }
+            }
+            for (const [windowId, window] of windows) {
+                const current = entries.get(windowId);
+                if (current?.window === window)
+                    continue;
+                entries.set(windowId, {
+                    window,
+                    state: current?.state ?? phaseFor(window),
+                });
+                changed = true;
+            }
+            if (changed)
+                invalidate();
+        },
     };
 }
+function phaseFor(window) {
+    if (window.state === 'opening')
+        return { phase: 'mounting' };
+    if (window.state === 'failed') {
+        return { phase: 'crashed', windowId: window.windowId };
+    }
+    if (window.state === 'closed')
+        return { phase: 'closed', windowId: window.windowId };
+    return { phase: 'ready', windowId: window.windowId };
+}
 const HUBS = new WeakMap();
 /** The windows hub for a shell — one per shell object, created on first touch. */
 export function getStageHub(shell) {
@@ -95,6 +126,8 @@ export function getStageHub(shell) {
             return adopt.take(key);
         },
     };
+    registry.sync(shell.windows);
+    shell.onWindowChange(() => registry.sync(shell.windows));
     HUBS.set(shell, hub);
     return hub;
 }

package/dist/window/index.d.ts

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

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/window/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC9D,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AACnE,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAClD,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAA;AACvD,YAAY,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAC3D,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAC3E,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAA;AAC5E,YAAY,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/window/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC7E,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AACnE,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAClD,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAA;AACvD,YAAY,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAC/D,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAC1E,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAC3D,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAC3E,YAAY,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACxD,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/window/index.js

@@ -1,10 +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
+// that projects stage geometry into a slot), the reactive window hooks, the child-side
 // target-node + close-guard, and the (G5) view-resolution hook.
 export { ViewStage } from './stage.js';
 export { ViewHost } from './host.js';
 export { useWindows, useWindowList } from './hooks/windows.hook.js';
 export { useWindow } from './hooks/window.hook.js';
 export { useViewsFor } from './hooks/views-for.hook.js';
-export { useTargetNode } from './hooks/target-node.hook.js';
+export { useTargetNode, useTargetPath } from './hooks/target-node.hook.js';
 export { useCloseGuard } from './hooks/close-guard.hook.js';

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

@@ -1,47 +1,8 @@
-import type { NodeRefInput } from '@astrale-os/kernel-client';
+import type { ResolvedView } from '@astrale-os/shell';
 /**
- * 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.
+ * Stable identity for one target-bound, provenance-complete View route.
+ * A change to any routing or semantic witness forces a fresh mount; an old
+ * iframe and credential can never be adopted under a different route.
  */
-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;
+export declare function viewMountKey(view: ResolvedView): string;
 //# sourceMappingURL=mount.d.ts.map

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

@@ -1 +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;AA2ED,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"}
+{"version":3,"file":"mount.d.ts","sourceRoot":"","sources":["../../../src/window/lifecycle/mount.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAErD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAWvD"}

package/dist/window/lifecycle/mount.js

@@ -1,123 +1,17 @@
-function isViewDescriptor(view) {
-    return typeof view === 'object' && view !== null && 'id' in view && 'path' in view;
-}
-/** Last path segment or host, alnum-only — a stable-ish functionId from a url. */
-function slugOfUrl(url) {
-    const trimmed = url.replace(/[#?].*$/, '').replace(/\/+$/, '');
-    const tail = trimmed.split('/').filter(Boolean).pop() ?? 'view';
-    return tail.replace(/[^a-z0-9]/gi, '').slice(-32) || 'view';
-}
-/** A ref addressable by the kernel read surface (`get`). `@<id>` for bare ids. */
-function toPath(ref) {
-    if (typeof ref === 'string') {
-        return ref.startsWith('/') || ref.startsWith('@') ? ref : `@${ref}`;
-    }
-    const obj = ref;
-    if (obj.path?.raw !== undefined)
-        return obj.path.raw;
-    if (obj.id !== undefined)
-        return `@${obj.id}`;
-    throw new Error('ViewHost: unresolvable view ref');
-}
-async function resolveViewRef(kernel, ref, handshakeHint) {
-    const node = await kernel.get(toPath(ref));
-    if (node === null)
-        throw new Error(`ViewHost: view not found (${toPath(ref)})`);
-    const props = node.props ?? {};
-    const url = viewUrl(props);
-    if (typeof url !== 'string' || url.length === 0) {
-        throw new Error('ViewHost: resolved view has no url');
-    }
-    const handshake = normalizeHandshake(handshakeHint ?? props.handshake);
-    const id = node.id ?? slugOfUrl(url);
-    return { url, handshake, functionId: id };
-}
-/** Resolve both the legacy flat url and the canonical Function binding. */
-function viewUrl(props) {
-    if (typeof props.url === 'string' && props.url.length > 0)
-        return props.url;
-    const direct = remoteUrlOf(props.binding);
-    if (direct !== undefined)
-        return direct;
-    // Raw graph props can be keyed by the property's canonical graph key rather
-    // than its local slug. The binding value remains self-describing.
-    for (const value of Object.values(props)) {
-        const remoteUrl = remoteUrlOf(value);
-        if (remoteUrl !== undefined)
-            return remoteUrl;
-    }
-    return undefined;
-}
-function remoteUrlOf(value) {
-    let binding = value;
-    if (typeof binding === 'string') {
-        try {
-            binding = JSON.parse(binding);
-        }
-        catch {
-            return undefined;
-        }
-    }
-    if (binding === null || typeof binding !== 'object')
-        return undefined;
-    const remoteUrl = binding.remoteUrl;
-    return typeof remoteUrl === 'string' && remoteUrl.length > 0 ? remoteUrl : undefined;
-}
-function normalizeHandshake(value) {
-    return value === 'none' ? 'none' : 'shell';
-}
-/** Resolve a source; may hit the kernel for a bare/urless View ref (G5). */
-export async function resolveSource(kernel, source) {
-    if ('url' in source) {
-        return { url: source.url, handshake: 'none', functionId: slugOfUrl(source.url) };
-    }
-    const view = source.view;
-    if (isViewDescriptor(view)) {
-        if (view.url !== undefined && view.url.length > 0) {
-            return {
-                url: view.url,
-                handshake: normalizeHandshake(view.handshake),
-                functionId: view.id,
-            };
-        }
-        return resolveViewRef(kernel, view.id, view.handshake);
-    }
-    return resolveViewRef(kernel, view);
-}
-/** A stable remount key: the same source identity must not remount. */
-export function sourceKey(source) {
-    if ('url' in source)
-        return `url:${source.url}`;
-    const view = source.view;
-    if (isViewDescriptor(view))
-        return `view:${view.id}:${view.url ?? ''}:${view.handshake ?? ''}`;
-    if (typeof view === 'string')
-        return `ref:${view}`;
-    const obj = view;
-    return `ref:${obj.id ?? obj.path?.raw ?? '?'}`;
-}
-/** The bare node id delivered as `targetNodeId` at mount / retarget. */
-export function refToId(ref) {
-    if (ref === undefined)
-        return undefined;
-    if (typeof ref === 'string')
-        return ref.startsWith('@') ? ref.slice(1) : ref;
-    const obj = ref;
-    return obj.id;
-}
 /**
- * Fallbackable = the view didn't speak the shell protocol (timeout/failed), not a
- * security refusal (origin mismatch) — only the former downgrades to plain.
+ * Stable identity for one target-bound, provenance-complete View route.
+ * A change to any routing or semantic witness forces a fresh mount; an old
+ * iframe and credential can never be adopted under a different route.
  */
-export function isFallbackableHandshakeError(err) {
-    const code = err?.code;
-    return code === 'HANDSHAKE_TIMEOUT' || code === 'HANDSHAKE_FAILED';
-}
-/** Parent → child hot-swap of the target node (no remount) — API §10 setTarget. */
-export function sendSetTarget(shell, windowId, nodeId) {
-    shell.children.send(windowId, {
-        type: 'intent',
-        version: 1,
-        envelope: { name: 'setTarget', payload: { nodeId }, sender: { windowId: '<parent>' } },
-    });
+export function viewMountKey(view) {
+    const { route, target } = view;
+    return [
+        target,
+        route.key,
+        route.href,
+        route.handshake,
+        route.issuer,
+        route.etag,
+        route.revision,
+    ].join('\u0000');
 }

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

@@ -7,10 +7,6 @@
 /**
  * Lifecycle of a hosted view as the React face observes it (API §10).
  *
- * `ready.downgraded` marks a mount that fell back to a plain iframe after a
- * fallbackable handshake error. It rides here (not on the shell `Window`) until
- * the shell `Window` grows a first-class flag — flagged in the module report.
- *
  * `crashed.windowId` is OPTIONAL: a crash before a window exists (a session-open
  * failure, a pre-mount source-resolution failure) has no id to report — the type
  * says so rather than carrying a placeholder `''`.
@@ -20,7 +16,6 @@ export type WindowState = {
 } | {
     readonly phase: 'ready';
     readonly windowId: string;
-    readonly downgraded?: boolean;
 } | {
     readonly phase: 'crashed';
     readonly windowId?: string;

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

@@ -1 +1 @@
-{"version":3,"file":"states.d.ts","sourceRoot":"","sources":["../../../src/window/lifecycle/states.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,GACrF;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GACnF;IAAE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA"}
+{"version":3,"file":"states.d.ts","sourceRoot":"","sources":["../../../src/window/lifecycle/states.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GACnF;IAAE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA"}

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

@@ -1 +1 @@
-{"version":3,"file":"stage.d.ts","sourceRoot":"","sources":["../../src/window/stage.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,YAAY,EAAE,MAAM,OAAO,CAAA;AA4BxD,wBAAgB,SAAS,IAAI,YAAY,CAiBxC"}
+{"version":3,"file":"stage.d.ts","sourceRoot":"","sources":["../../src/window/stage.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,YAAY,EAAE,MAAM,OAAO,CAAA;AA6BxD,wBAAgB,SAAS,IAAI,YAAY,CAiBxC"}

package/dist/window/stage.js

@@ -20,6 +20,7 @@ const STAGE_STYLE = {
     left: 0,
     right: 0,
     bottom: 0,
+    zIndex: 20,
     pointerEvents: 'none',
 };
 export function ViewStage() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/shell-react",
-  "version": "0.2.8",
+  "version": "0.2.10-beta.2",
   "description": "Astrale shell-react — the React face of the shell (provider, hooks, view components)",
   "license": "Apache-2.0",
   "repository": {
@@ -25,10 +25,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@astrale-domains/shell-schema": ">=0.3.2 <1.0.0",
-    "@astrale-os/kernel-client": ">=0.4.7 <1.0.0",
-    "@astrale-os/kernel-core": ">=0.7.5 <1.0.0",
-    "@astrale-os/kernel-dsl": ">=0.1.4 <1.0.0",
+    "@astrale-os/kernel-client": ">=0.6.0-beta.4 <1.0.0",
+    "@astrale-os/sdk": ">=0.5.0-beta.4 <1.0.0",
     "jose": "^6.2.3",
     "zod": "^4.3.6"
   },
@@ -43,14 +41,17 @@
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "typescript": "~6.0.1-rc",
+    "vite": "^7.3.6",
     "vitest": "^3.2.4",
-    "@astrale-os/shell": "0.3.6"
+    "@astrale-os/shell": "0.3.8-beta.2"
   },
   "peerDependencies": {
-    "@astrale-os/shell": ">=0.2.0 <1.0.0",
-    "react": ">=18"
+    "@astrale-os/shell": ">=0.3.8-beta.2 <1.0.0",
+    "react": ">=18",
+    "react-dom": ">=18"
   },
   "scripts": {
+    "prebuild": "pnpm clean",
     "build": "tsgo",
     "clean": "rm -rf dist *.tsbuildinfo",
     "typecheck": "tsgo --noEmit && tsgo --noEmit -p tsconfig.test.json",

package/src/application/apps/app-host.tsx

@@ -1,5 +1,10 @@
-import type { NodeRefInput } from '@astrale-os/kernel-client'
-import type { ApplicationNode, AppSession, IntentRegistry, SandboxProfile } from '@astrale-os/shell'
+import type {
+  ApplicationNode,
+  AppSession,
+  HostCapabilities,
+  NodeTarget,
+  ResolvedView,
+} from '@astrale-os/shell'
 import type { CSSProperties, ReactElement, ReactNode } from 'react'
 
 /**
@@ -11,8 +16,7 @@ import type { CSSProperties, ReactElement, ReactNode } from 'react'
  */
 import { forwardRef, useEffect, useRef, useState } from 'react'
 
-import type { ViewHostHandle } from '../../window/host.js'
-import type { ViewDescriptor } from '../../window/lifecycle/mount.js'
+import type { SandboxPolicy, ViewHostHandle } from '../../window/host.js'
 import type { WindowState } from '../../window/lifecycle/states.js'
 
 import { ViewHost } from '../../window/host.js'
@@ -26,16 +30,11 @@ export type AppHostFallbackState =
   | { readonly phase: 'no-view' }
 
 export interface AppHostProps {
-  app: ApplicationNode | NodeRefInput
-  /**
-   * Default target node delivered to the app's view as `targetNodeId` (API §12.2).
-   * Container-anchored apps need one — the dock passes the current space. A deeper
-   * fix (an install-time app data container + `app::open` returning a default
-   * target) is a tracked domain-modeling question; until then the host supplies it.
-   */
-  node?: NodeRefInput
-  capabilities?: { intents: readonly (keyof IntentRegistry)[] }
-  sandbox?: SandboxProfile | null
+  app: ApplicationNode | NodeTarget
+  /** Override the entry View while keeping the application's delegated session alive. */
+  view?: ResolvedView
+  capabilities?: HostCapabilities
+  sandbox?: SandboxPolicy
   fallback?: (state: AppHostFallbackState) => ReactNode
   onSession?: (session: AppSession) => void
   className?: string
@@ -94,15 +93,15 @@ export const AppHost = forwardRef<ViewHostHandle, AppHostProps>(
     // A session-open failure has no window yet — `windowId` is honestly absent (§10).
     if (error !== undefined) return box(fallback?.({ phase: 'crashed', error }) ?? null)
     if (session === null) return box(fallback?.({ phase: 'opening' }) ?? null)
-    if (session.view === null) return box(fallback?.({ phase: 'no-view' }) ?? null)
+    const view = props.view ?? session.view
+    if (view === null) return box(fallback?.({ phase: 'no-view' }) ?? null)
 
     return (
       <ViewHost
         ref={ref}
-        view={session.view as ViewDescriptor}
-        node={props.node}
+        view={view}
         credential={session.credential}
-        capabilities={props.capabilities ?? { intents: [] }}
+        capabilities={props.capabilities}
         sandbox={props.sandbox}
         fallback={fallback ? (s: WindowState) => fallback(s) : undefined}
         className={className}