@astrale-os/shell 0.1.0

package/dist/application/intent/router.d.ts

@@ -0,0 +1,56 @@
+import type { IntentRegistry } from '../../domain/message/registries';
+import type { IntentMessage } from '../../domain/message/types';
+import type { Window } from '../../domain/window/window';
+import type { ChildrenChannelController } from '../channels/children-channel';
+import type { ParentChannel } from '../channels/parent-channel';
+import type { IntentPipeline } from './pipeline-runner';
+/**
+ * Decision produced by a routing policy: where an inbound intent should go.
+ *
+ *  - `local`: the shell (entry point or sandboxed parent) handles it itself.
+ *  - `parent`: forward upstream (only valid for sandboxed children).
+ *  - `child`: forward to a specific child window.
+ *  - `drop`: discard silently (e.g., handled fully by a middleware).
+ */
+export type IntentDecision<K extends keyof IntentRegistry = keyof IntentRegistry> = {
+    kind: 'local';
+    message: IntentMessage<K>;
+} | {
+    kind: 'parent';
+    message: IntentMessage<K>;
+} | {
+    kind: 'child';
+    windowId: string;
+    message: IntentMessage<K>;
+} | {
+    kind: 'drop';
+};
+export type IntentOrigin = 'parent' | 'child' | 'self';
+export type IntentPolicy = (message: IntentMessage, ctx: IntentContext) => IntentDecision | Promise<IntentDecision>;
+export interface IntentContext {
+    readonly selfWindowId: string;
+    readonly origin: IntentOrigin;
+    readonly windows: ReadonlyMap<string, Window>;
+    readonly hasParent: boolean;
+}
+export type LocalIntentHandler<K extends keyof IntentRegistry = keyof IntentRegistry> = (message: IntentMessage<K>) => void | Promise<void>;
+export interface IntentRouterController {
+    /**
+     * Route an inbound intent. `senderWindowId`, when provided, is the trusted
+     * windowId the channel authenticated; it overrides the (forgeable)
+     * `envelope.sender.windowId` before the pipeline runs.
+     */
+    handleInbound(origin: IntentOrigin, message: IntentMessage, senderWindowId?: string): Promise<void>;
+    dispatchLocal(message: IntentMessage): Promise<void>;
+    setPolicy(policy: IntentPolicy): void;
+    onLocal<K extends keyof IntentRegistry>(name: K, handler: LocalIntentHandler<K>): () => void;
+}
+export type IntentRouterConfig = {
+    selfWindowId: string;
+    pipeline: IntentPipeline;
+    parent: ParentChannel | null;
+    children: ChildrenChannelController;
+    windows: ReadonlyMap<string, Window>;
+};
+export declare function createIntentRouter(config: IntentRouterConfig): IntentRouterController;
+//# sourceMappingURL=router.d.ts.map

package/dist/application/intent/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../../src/application/intent/router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAA;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAC/D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAA;AACxD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAA;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAEvD;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,cAAc,GAAG,MAAM,cAAc,IAC5E;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,CAAA;CAAE,GAC9D;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAEpB,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAA;AAEtD,MAAM,MAAM,YAAY,GAAG,CACzB,OAAO,EAAE,aAAa,EACtB,GAAG,EAAE,aAAa,KACf,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;AAE7C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;IAC7B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B;AAED,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,MAAM,cAAc,GAAG,MAAM,cAAc,IAAI,CACtF,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,KACtB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAEzB,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,aAAa,CACX,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,aAAa,EACtB,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CAAA;IAChB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACpD,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAA;IACrC,OAAO,CAAC,CAAC,SAAS,MAAM,cAAc,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAA;CAC7F;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,EAAE,cAAc,CAAA;IACxB,MAAM,EAAE,aAAa,GAAG,IAAI,CAAA;IAC5B,QAAQ,EAAE,yBAAyB,CAAA;IACnC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACrC,CAAA;AAuBD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,sBAAsB,CA4ErF"}

package/dist/application/intent/router.js

@@ -0,0 +1,94 @@
+/**
+ * Default policy:
+ *  - intent arrives from a child → handle locally
+ *  - intent arrives from the parent → handle locally
+ *  - intent initiated locally (self) → send up to parent if we have one,
+ *    otherwise keep it local
+ */
+function defaultPolicy() {
+    return (message, ctx) => {
+        if (ctx.origin === 'self') {
+            return ctx.hasParent ? { kind: 'parent', message } : { kind: 'local', message };
+        }
+        return { kind: 'local', message };
+    };
+}
+/** Return a copy of `message` with a trusted `sender.windowId`. */
+function withSender(message, windowId) {
+    return { ...message, envelope: { ...message.envelope, sender: { windowId } } };
+}
+export function createIntentRouter(config) {
+    const { pipeline, parent, children, windows, selfWindowId } = config;
+    let policy = defaultPolicy();
+    const localHandlers = new Map();
+    async function forward(decision) {
+        switch (decision.kind) {
+            case 'drop':
+                return;
+            case 'parent':
+                if (!parent)
+                    return;
+                parent.send(decision.message);
+                return;
+            case 'child':
+                if (!children.has(decision.windowId))
+                    return;
+                children.send(decision.windowId, decision.message);
+                return;
+            case 'local': {
+                const bucket = localHandlers.get(decision.message.envelope.name);
+                if (!bucket)
+                    return;
+                for (const handler of bucket) {
+                    try {
+                        await handler(decision.message);
+                    }
+                    catch {
+                        // Handler errors must not interrupt sibling handlers.
+                    }
+                }
+                return;
+            }
+        }
+    }
+    const ctxBase = {
+        selfWindowId,
+        windows,
+        hasParent: parent !== null,
+    };
+    return {
+        async handleInbound(origin, message, senderWindowId) {
+            // `envelope.sender.windowId` is attacker-controlled wire data: a sandboxed
+            // child can claim any id. Overwrite it with the windowId the channel
+            // authenticated so capability/rate-limit middleware can't be bypassed by a
+            // forged sender. The original message object is left untouched for raw
+            // channel listeners; only this routed copy carries the trusted id.
+            const inbound = senderWindowId === undefined ? message : withSender(message, senderWindowId);
+            await pipeline.run(inbound, async () => {
+                const decision = await policy(inbound, { ...ctxBase, origin });
+                await forward(decision);
+            });
+        },
+        async dispatchLocal(message) {
+            const stamped = withSender(message, selfWindowId);
+            await pipeline.run(stamped, async () => {
+                const decision = await policy(stamped, { ...ctxBase, origin: 'self' });
+                await forward(decision);
+            });
+        },
+        setPolicy(next) {
+            policy = next;
+        },
+        onLocal(name, handler) {
+            let bucket = localHandlers.get(name);
+            if (!bucket) {
+                bucket = new Set();
+                localHandlers.set(name, bucket);
+            }
+            bucket.add(handler);
+            return () => {
+                bucket.delete(handler);
+            };
+        },
+    };
+}

package/dist/application/kernel-facade.d.ts

@@ -0,0 +1,33 @@
+import type { KernelClientAdapter } from '../adapters/kernel-client.adapter';
+import type { DelegationToken } from '../domain/identity/delegation';
+import type { KernelClient } from '../ports/kernel-client';
+export type KernelFacadeConfig = {
+    adapter: KernelClientAdapter;
+    credential?: string;
+    getCredential?: () => string;
+    /** Kernel URL — exposed to consumers via `KernelClient.url`. */
+    url: string;
+    /**
+     * Explicit identity node to use as the mint subject. When omitted, the mint
+     * resolves the AUTHENTICATED caller via `whoami` (so a cookie-fronted GUI mints
+     * as the logged-in user, not the kernel root). Set this only to pin a subject.
+     */
+    mintIdentity?: string;
+};
+export interface KernelFacadeController extends KernelClient {
+    dispose(): void;
+}
+export declare function createKernelFacade(config: KernelFacadeConfig): KernelFacadeController;
+export type DelegationKernelFacadeConfig = {
+    adapter: KernelClientAdapter;
+    initialToken: DelegationToken;
+    url: string;
+    onTokenChange?: (token: DelegationToken) => void;
+    mintIdentity?: string;
+};
+export interface DelegationKernelFacadeController extends KernelFacadeController {
+    token(): DelegationToken;
+    setToken(next: DelegationToken): void;
+}
+export declare function createDelegationKernelFacade(config: DelegationKernelFacadeConfig): DelegationKernelFacadeController;
+//# sourceMappingURL=kernel-facade.d.ts.map

package/dist/application/kernel-facade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernel-facade.d.ts","sourceRoot":"","sources":["../../src/application/kernel-facade.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAA;AAC5E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAA;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAO1D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,mBAAmB,CAAA;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,aAAa,CAAC,EAAE,MAAM,MAAM,CAAA;IAC5B,gEAAgE;IAChE,GAAG,EAAE,MAAM,CAAA;IACX;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AAED,MAAM,WAAW,sBAAuB,SAAQ,YAAY;IAC1D,OAAO,IAAI,IAAI,CAAA;CAChB;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,sBAAsB,CAerF;AAID,MAAM,MAAM,4BAA4B,GAAG;IACzC,OAAO,EAAE,mBAAmB,CAAA;IAC5B,YAAY,EAAE,eAAe,CAAA;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAA;IAChD,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AAED,MAAM,WAAW,gCAAiC,SAAQ,sBAAsB;IAC9E,KAAK,IAAI,eAAe,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,CAAA;CACtC;AAED,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,4BAA4B,GACnC,gCAAgC,CA0BlC"}

package/dist/application/kernel-facade.js

@@ -0,0 +1,77 @@
+import { identityMethod } from '../domain/identity/path';
+import { createSelfResolver, WHOAMI_PATH } from '../domain/identity/resolve-self';
+export function createKernelFacade(config) {
+    const getCredential = config.getCredential ??
+        (() => {
+            if (config.credential === undefined) {
+                throw new Error('KernelFacade requires credential or getCredential');
+            }
+            return config.credential;
+        });
+    return buildCredentialFacade({
+        adapter: config.adapter,
+        getCredential,
+        url: config.url,
+        mintIdentity: config.mintIdentity,
+    });
+}
+export function createDelegationKernelFacade(config) {
+    let token = config.initialToken;
+    const base = buildCredentialFacade({
+        adapter: config.adapter,
+        getCredential: () => token.credential,
+        url: config.url,
+        mintIdentity: config.mintIdentity,
+    });
+    return {
+        ...base,
+        token() {
+            return token;
+        },
+        setToken(next) {
+            if (next.credential === token.credential && next.expiresAt === token.expiresAt)
+                return;
+            token = next;
+            config.onTokenChange?.(next);
+        },
+        // The delegation facade owns its adapter exclusively (created per child in
+        // `performChildInit`), so disposing it must tear the adapter down — unlike
+        // the standalone facade, where the caller owns the adapter's lifetime.
+        dispose() {
+            config.adapter.disconnect();
+        },
+    };
+}
+/**
+ * v1 note: we mint a fresh identity credential (grant-bearing, directly
+ * usable). Proper delegation composition (outer envelope via `Cred(...)`)
+ * requires SDK v2 — tracked in `.dev/todo/shell-sdk-v2-delegation.md`.
+ */
+function buildCredentialFacade(params) {
+    const { adapter, getCredential, mintIdentity, url } = params;
+    const resolveSelf = createSelfResolver();
+    return {
+        url,
+        call(path, callParams) {
+            return adapter.call(path, callParams, getCredential());
+        },
+        async mintDelegation() {
+            const subject = mintIdentity ?? (await resolveSelf(() => adapter.call(WHOAMI_PATH, {}, getCredential())));
+            const result = await adapter.call(identityMethod(subject, 'mintIdentityCredential'), {}, getCredential());
+            if (typeof result === 'string')
+                return result;
+            if (result !== null &&
+                typeof result === 'object' &&
+                typeof result.credential === 'string') {
+                return result.credential;
+            }
+            throw new Error('mintIdentityCredential returned an unexpected shape');
+        },
+        authToken() {
+            return getCredential();
+        },
+        dispose() {
+            // adapter lifetime is owned by the caller
+        },
+    };
+}

package/dist/application/shell.d.ts

@@ -0,0 +1,100 @@
+import type { FunctionSchema } from '@astrale-os/kernel-client';
+import type { IntentMiddleware } from '../domain/intent/pipeline';
+import type { IntentRegistry } from '../domain/message/registries';
+import type { WindowCapabilities, SandboxProfile } from '../domain/window/config';
+import type { Window } from '../domain/window/window';
+import type { KernelClient } from '../ports/kernel-client';
+import type { ShellAdapter } from '../ports/shell-adapter';
+import type { ChildrenChannel } from './channels/children-channel';
+import type { ObserverHandler } from './channels/observer';
+import type { ParentChannel } from './channels/parent-channel';
+import type { LocalIntentHandler } from './intent/router';
+export type { MessageDirection, ObserverHandler } from './channels/observer';
+export type { ParentChannel } from './channels/parent-channel';
+export type { ChildrenChannel } from './channels/children-channel';
+export type { MessageHandler } from './channels/types';
+export type MountParams = {
+    readonly host: HTMLElement;
+    readonly url: string;
+    readonly functionId: string;
+    readonly capabilities: WindowCapabilities;
+    readonly targetNodeId?: string;
+    /** See `WindowConfig.sandbox` — `null` opts the iframe out of the attribute. */
+    readonly sandbox?: SandboxProfile | null;
+    readonly handshakeTimeoutMs?: number;
+    readonly delegationTtlSeconds?: number;
+    /**
+     * `'shell'` (default) runs the parent-side handshake, opening a MessagePort
+     * transport with delegation tokens and an intent channel. `'none'` mounts a
+     * plain iframe with no transport — used for hosted views that don't speak
+     * the shell protocol (`BlaxelComputer.deployFunction(kind:'view')`), so they
+     * render immediately instead of paying the 5 s handshake timeout. In `'none'`
+     * mode `capabilities` / `targetNodeId` / `delegationTtlSeconds` are inert
+     * (no channel to deliver them).
+     */
+    readonly handshake?: 'shell' | 'none';
+};
+export type CloseResult = {
+    kind: 'closed';
+} | {
+    kind: 'refused';
+    reason?: string;
+} | {
+    kind: 'noop';
+};
+export type MountedWindow = {
+    readonly windowId: string;
+    readonly window: Window;
+    readonly handle: {
+        element: HTMLIFrameElement | HTMLElement;
+    };
+    close(opts?: {
+        force?: boolean;
+        timeoutMs?: number;
+    }): Promise<CloseResult>;
+};
+export interface Shell {
+    readonly parent: ParentChannel | null;
+    readonly children: ChildrenChannel;
+    readonly kernel: KernelClient;
+    readonly windows: ReadonlyMap<string, Window>;
+    readonly targetNodeId?: string;
+    use(middleware: IntentMiddleware): Shell;
+    onMessage(handler: ObserverHandler): () => void;
+    onIntent<K extends keyof IntentRegistry>(name: K, handler: LocalIntentHandler<K>): () => void;
+    mount(params: MountParams): Promise<MountedWindow>;
+    close(windowId: string, opts?: {
+        force?: boolean;
+        timeoutMs?: number;
+    }): Promise<CloseResult>;
+    init(): Promise<Shell>;
+    dispose(): Promise<void>;
+}
+export type StandaloneConfig = {
+    readonly mode: 'standalone';
+    readonly kernelUrl: string;
+    readonly credential?: string;
+    readonly getCredential?: () => string;
+    readonly mintIdentity?: string;
+    readonly schema?: FunctionSchema[];
+    readonly adapter?: ShellAdapter;
+    readonly windowId?: string;
+    /**
+     * Optional wire-layer `fetch` shim for the kernel transport. A cookie-fronted
+     * SPA passes a wrapper adding `credentials:'include'` + refresh-on-401 and an
+     * empty `credential`, so a router unseals the cookie into a Bearer (the SPA
+     * holds no token). Omit it (the default) for token-based callers — including
+     * every sandboxed child view, which authenticates with a delegation token.
+     */
+    readonly fetch?: typeof fetch;
+};
+export type SandboxedConfig = {
+    readonly mode: 'sandboxed';
+    readonly schema?: FunctionSchema[];
+    readonly parentWindow?: WindowProxy;
+    readonly initTimeoutMs?: number;
+    readonly adapter?: ShellAdapter;
+};
+export type ShellConfig = StandaloneConfig | SandboxedConfig;
+export declare function createShell(config: ShellConfig): Shell;
+//# sourceMappingURL=shell.d.ts.map

package/dist/application/shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../../src/application/shell.ts"],"names":[],"mappings":"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"}

package/dist/application/shell.js

@@ -0,0 +1,256 @@
+import { createKernelClientAdapter } from '../adapters/kernel-client.adapter';
+import { createChildrenChannel } from './channels/children-channel';
+import { createMessageObserver } from './channels/observer';
+import { createIntentPipeline } from './intent/pipeline-runner';
+import { createIntentRouter } from './intent/router';
+import { createKernelFacade } from './kernel-facade';
+import { performChildInit } from './windowing/child-init';
+import { createLifecycleController } from './windowing/lifecycle-controller';
+import { createMountController } from './windowing/mount-controller';
+const DEFAULT_ROOT_WINDOW_ID = 'root';
+/** Trusted sender id stamped on intents arriving from the parent channel. */
+const PARENT_SENDER_ID = '<parent>';
+// ─── Factory ────────────────────────────────────────────────────────────────
+export function createShell(config) {
+    return config.mode === 'standalone' ? createStandaloneShell(config) : createSandboxedShell(config);
+}
+// ─── Standalone ─────────────────────────────────────────────────────────────
+function createStandaloneShell(config) {
+    const windowId = config.windowId ?? DEFAULT_ROOT_WINDOW_ID;
+    const observer = createMessageObserver();
+    const getCredential = config.getCredential ??
+        (() => {
+            if (config.credential === undefined) {
+                throw new Error('Standalone shell requires credential or getCredential');
+            }
+            return config.credential;
+        });
+    const adapter = createKernelClientAdapter({
+        url: config.kernelUrl,
+        schema: config.schema,
+        getCredential,
+        mintIdentity: config.mintIdentity,
+        fetch: config.fetch,
+    });
+    const kernel = createKernelFacade({
+        adapter,
+        getCredential,
+        url: config.kernelUrl,
+        mintIdentity: config.mintIdentity,
+    });
+    const lifecycle = createLifecycleController();
+    const windows = new Map();
+    const childrenChannel = createChildrenChannel({
+        observer,
+        onDeliveryFailed: (toWindowId) => lifecycle.markCrashed(toWindowId),
+    });
+    const pipeline = createIntentPipeline();
+    const router = createIntentRouter({
+        selfWindowId: windowId,
+        pipeline,
+        parent: null,
+        children: childrenChannel,
+        windows,
+    });
+    childrenChannel.on('intent', (windowId, message) => {
+        void router.handleInbound('child', message, windowId);
+    });
+    let mountController = null;
+    function getMountController() {
+        if (mountController)
+            return mountController;
+        if (!config.adapter) {
+            throw new Error('Shell.mount() requires a ShellAdapter in the config');
+        }
+        mountController = createMountController({
+            adapter: config.adapter,
+            kernel,
+            kernelUrl: config.kernelUrl,
+            mintIdentity: config.mintIdentity,
+            childrenChannel,
+            windows,
+            lifecycle,
+        });
+        return mountController;
+    }
+    return buildShellFacade({
+        parent: null,
+        childrenChannel,
+        kernel,
+        pipeline,
+        observer,
+        lifecycle,
+        windows,
+        getMountController,
+        onIntent: (name, handler) => router.onLocal(name, handler),
+        onDispose: async () => {
+            if (mountController)
+                await mountController.dispose();
+            childrenChannel.dispose();
+            adapter.disconnect();
+        },
+    });
+}
+function createSandboxedShell(config) {
+    const observer = createMessageObserver();
+    const lifecycle = createLifecycleController();
+    const windows = new Map();
+    const childrenChannel = createChildrenChannel({
+        observer,
+        onDeliveryFailed: (toWindowId) => lifecycle.markCrashed(toWindowId),
+    });
+    const pipeline = createIntentPipeline();
+    let state = null;
+    let router = null;
+    let mountController = null;
+    const pendingIntentSubs = [];
+    function subscribeIntent(name, handler) {
+        if (router)
+            return router.onLocal(name, handler);
+        const entry = {
+            name: name,
+            handler: handler,
+            unsubscribed: false,
+        };
+        pendingIntentSubs.push(entry);
+        return () => {
+            entry.unsubscribed = true;
+            // After init, `off` is the router's real disposer (set during replay);
+            // before init, flipping `unsubscribed` is enough (replay skips it).
+            entry.off?.();
+        };
+    }
+    const requireState = () => {
+        if (!state)
+            throw new Error('Sandboxed shell not initialized — call shell.init() first');
+        return state;
+    };
+    const kernelProxy = {
+        call: (path, params) => requireState().kernel.call(path, params),
+        mintDelegation: () => requireState().kernel.mintDelegation(),
+        authToken: () => requireState().kernel.authToken(),
+        get url() {
+            return requireState().kernel.url;
+        },
+    };
+    const parentProxy = {
+        send: (message) => requireState().parent.send(message),
+        on: (type, handler) => requireState().parent.on(type, handler),
+    };
+    function getMountController() {
+        if (mountController)
+            return mountController;
+        if (!config.adapter) {
+            throw new Error('Shell.mount() requires a ShellAdapter in the config');
+        }
+        const current = requireState();
+        mountController = createMountController({
+            adapter: config.adapter,
+            kernel: kernelProxy,
+            kernelUrl: current.kernelUrl,
+            mintIdentity: current.mintIdentity,
+            childrenChannel,
+            windows,
+            lifecycle,
+        });
+        return mountController;
+    }
+    return buildShellFacade({
+        parent: parentProxy,
+        childrenChannel,
+        kernel: kernelProxy,
+        pipeline,
+        observer,
+        lifecycle,
+        windows,
+        getMountController,
+        targetNodeId: () => state?.targetNodeId,
+        onIntent: subscribeIntent,
+        init: async () => {
+            const result = await performChildInit({
+                parent: config.parentWindow ?? window.parent,
+                timeoutMs: config.initTimeoutMs,
+                schema: config.schema,
+            });
+            state = {
+                windowId: result.windowId,
+                kernelUrl: result.kernelUrl,
+                targetNodeId: result.targetNodeId,
+                mintIdentity: result.mintIdentity,
+                kernel: result.kernel,
+                parent: result.parentChannel(observer),
+            };
+            router = createIntentRouter({
+                selfWindowId: state.windowId,
+                pipeline,
+                parent: state.parent,
+                children: childrenChannel,
+                windows,
+            });
+            childrenChannel.on('intent', (windowId, message) => {
+                void router.handleInbound('child', message, windowId);
+            });
+            state.parent.on('intent', (message) => {
+                void router.handleInbound('parent', message, PARENT_SENDER_ID);
+            });
+            // Replay subscriptions registered before init. Capture each real disposer
+            // so a post-init unsubscribe (via the closure returned at subscribe time)
+            // actually removes the handler from the router instead of no-op'ing.
+            for (const entry of pendingIntentSubs) {
+                if (entry.unsubscribed)
+                    continue;
+                entry.off = router.onLocal(entry.name, entry.handler);
+            }
+            pendingIntentSubs.length = 0;
+        },
+        onDispose: async () => {
+            if (mountController)
+                await mountController.dispose();
+            childrenChannel.dispose();
+            state?.parent.dispose();
+            state?.kernel.dispose();
+        },
+    });
+}
+function buildShellFacade(deps) {
+    let disposed = false;
+    const shell = {
+        get parent() {
+            return deps.parent;
+        },
+        children: deps.childrenChannel,
+        kernel: deps.kernel,
+        windows: deps.windows,
+        get targetNodeId() {
+            return deps.targetNodeId?.();
+        },
+        use(middleware) {
+            deps.pipeline.use(middleware);
+            return shell;
+        },
+        onMessage(handler) {
+            return deps.observer.subscribe(handler);
+        },
+        onIntent(name, handler) {
+            return deps.onIntent(name, handler);
+        },
+        mount(params) {
+            return deps.getMountController().mount(params);
+        },
+        close(windowId, opts) {
+            return deps.getMountController().close(windowId, opts);
+        },
+        async init() {
+            if (deps.init)
+                await deps.init();
+            return shell;
+        },
+        async dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            await deps.onDispose();
+        },
+    };
+    return shell;
+}

package/dist/application/windowing/child-init.d.ts

@@ -0,0 +1,23 @@
+import type { FunctionSchema } from '@astrale-os/kernel-client';
+import type { DelegationToken } from '../../domain/identity/delegation';
+import type { MessageObserver } from '../channels/observer';
+import type { ParentChannelController } from '../channels/parent-channel';
+import { type DelegationKernelFacadeController } from '../kernel-facade';
+export type ChildInitParams = {
+    readonly parent: WindowProxy;
+    readonly timeoutMs?: number;
+    readonly schema?: FunctionSchema[];
+};
+export type ChildInitResult = {
+    readonly windowId: string;
+    readonly parentChannel: (observer: MessageObserver) => ParentChannelController;
+    readonly kernel: DelegationKernelFacadeController;
+    readonly initialToken: DelegationToken;
+    readonly functionId: string;
+    readonly kernelUrl: string;
+    readonly targetNodeId?: string;
+    readonly mintIdentity?: string;
+};
+/** Child-side init: post INIT_REQUEST, receive MessagePort + ctrl:handshake, ack. */
+export declare function performChildInit(params: ChildInitParams): Promise<ChildInitResult>;
+//# sourceMappingURL=child-init.d.ts.map

package/dist/application/windowing/child-init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-init.d.ts","sourceRoot":"","sources":["../../../src/application/windowing/child-init.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAE/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAA;AAEvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAA;AAKzE,OAAO,EAEL,KAAK,gCAAgC,EACtC,MAAM,kBAAkB,CAAA;AAGzB,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,EAAE,CAAA;CACnC,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,aAAa,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,uBAAuB,CAAA;IAC9E,QAAQ,CAAC,MAAM,EAAE,gCAAgC,CAAA;IACjD,QAAQ,CAAC,YAAY,EAAE,eAAe,CAAA;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAC/B,CAAA;AAID,qFAAqF;AACrF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAoGlF"}