@astrale-os/shell 0.1.1 → 0.2.0

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

@@ -0,0 +1,27 @@
+import type { ChildrenChannelController } from '../../channel/children';
+import type { TokenRefresher } from '../../kernel/delegation/refresh';
+import type { WindowHandle } from '../embed/adapter';
+import type { LifecycleController } from '../lifecycle/states';
+import type { Window } from '../window';
+import type { CloseResult } from './params';
+/** A mounted window's runtime entry — everything `close()` must tear down. */
+export type MountEntry = {
+    readonly handle: WindowHandle;
+    readonly dispose: () => void;
+    readonly refresher: TokenRefresher;
+    /** Plain (no-handshake) mount: no transport, no token, no close ack. */
+    readonly plain?: boolean;
+};
+export type CloseDeps = {
+    entries: Map<string, MountEntry>;
+    children: ChildrenChannelController;
+    windows: Map<string, Window>;
+    lifecycle: LifecycleController;
+};
+export type Closer = (windowId: string, opts?: {
+    force?: boolean;
+    timeoutMs?: number;
+}) => Promise<CloseResult>;
+/** The close flow: willClose → ack/refuse (unless forced or plain), then ordered teardown. */
+export declare function createCloser(deps: CloseDeps): Closer;
+//# sourceMappingURL=close.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"close.d.ts","sourceRoot":"","sources":["../../../src/window/mount/close.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAA;AACvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAA;AACrE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAM3C,8EAA8E;AAC9E,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAA;IAC5B,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAA;IAClC,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IAChC,QAAQ,EAAE,yBAAyB,CAAA;IACnC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,SAAS,EAAE,mBAAmB,CAAA;CAC/B,CAAA;AAED,MAAM,MAAM,MAAM,GAAG,CACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,KAC3C,OAAO,CAAC,WAAW,CAAC,CAAA;AAEzB,8FAA8F;AAC9F,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAmCpD"}

package/dist/window/mount/close.js

@@ -0,0 +1,74 @@
+const DEFAULT_CLOSE_TIMEOUT = 3_000;
+/** Trusted sender id stamped on the parent's own close-protocol intents. */
+const PARENT_SENDER_ID = '<parent>';
+/** The close flow: willClose → ack/refuse (unless forced or plain), then ordered teardown. */
+export function createCloser(deps) {
+    const { entries, children, windows, lifecycle } = deps;
+    return async (windowId, opts) => {
+        const entry = entries.get(windowId);
+        if (!entry)
+            return { kind: 'noop' };
+        const timeoutMs = opts?.timeoutMs ?? DEFAULT_CLOSE_TIMEOUT;
+        // Plain mounts have no channel to ack a close; always force.
+        if (!opts?.force && !entry.plain) {
+            // Move the window into `closing` so the state machine accepts the
+            // subsequent `closeRefuse`/`forceClose` transition (both are only valid
+            // from `closing`).
+            lifecycle.apply(windowId, { kind: 'requestClose' });
+            const accepted = await requestCloseAck(children, windowId, timeoutMs);
+            if (accepted.kind === 'refused') {
+                lifecycle.apply(windowId, { kind: 'closeRefuse' });
+                return { kind: 'refused', reason: accepted.reason };
+            }
+        }
+        lifecycle.apply(windowId, { kind: 'forceClose' });
+        entry.refresher.stop();
+        // Drop the entry before detaching: `detach` synchronously closes the
+        // transport, whose `onClose` re-enters `close()`. Removing the entry first
+        // makes that re-entrant call's `entries.has(windowId)` guard short-circuit,
+        // so `entry.dispose()` runs exactly once (adapters need not be idempotent).
+        entries.delete(windowId);
+        children.detach(windowId);
+        windows.delete(windowId);
+        entry.dispose();
+        lifecycle.remove(windowId);
+        return { kind: 'closed' };
+    };
+}
+async function requestCloseAck(children, windowId, timeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const off = children.on('intent', (from, message) => {
+            if (from !== windowId)
+                return;
+            if (message.envelope.name === 'closeAck') {
+                settled = true;
+                off();
+                clearTimeout(timer);
+                resolve({ kind: 'ack' });
+            }
+            else if (message.envelope.name === 'closeRefuse') {
+                settled = true;
+                off();
+                clearTimeout(timer);
+                const reason = message.envelope.payload.reason;
+                resolve({ kind: 'refused', reason });
+            }
+        });
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            off();
+            resolve({ kind: 'timeout' });
+        }, timeoutMs);
+        children.send(windowId, {
+            type: 'intent',
+            version: 1,
+            envelope: {
+                name: 'willClose',
+                payload: {},
+                sender: { windowId: PARENT_SENDER_ID },
+            },
+        });
+    });
+}

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

@@ -0,0 +1,41 @@
+import type { ChildrenChannelController } from '../../channel/children';
+import type { KernelClient } from '../../kernel/client';
+import type { Window } from '../window';
+import type { MountCredential } from './params';
+import { type TokenRefresher } from '../../kernel/delegation/refresh';
+export type AcquiredCredential = {
+    credential: string;
+    expiresAt: number;
+};
+/** No-op refresher for windows with no token to refresh (plain mounts, no-refresh credentials). */
+export declare const NOOP_REFRESHER: TokenRefresher;
+/**
+ * Pick where the window's credential comes from — and how it refreshes.
+ *
+ * A PROVIDED credential (the app-principal path — e.g. `app::open`'s composed
+ * credential) is used as-is and refreshes through its own callback (re-calling
+ * `app::open`); no callback → no refresh (the window lives at most until
+ * `expiresAt`). Otherwise the shell mints — and re-mints — its own delegation.
+ */
+export declare function credentialSource(opts: {
+    kernel: KernelClient;
+    ttlSeconds: number;
+    provided?: MountCredential;
+}): {
+    acquire: () => Promise<AcquiredCredential>;
+    refreshMint: (() => Promise<AcquiredCredential>) | null;
+};
+/**
+ * Wire the per-window refresher: on each refresh, update the Window store and
+ * push a `ctrl:tokenRefresh` down the child's channel.
+ */
+export declare function wireTokenRefresher(opts: {
+    windowId: string;
+    functionId: string;
+    initial: AcquiredCredential;
+    refreshMint: (() => Promise<AcquiredCredential>) | null;
+    windows: Map<string, Window>;
+    children: ChildrenChannelController;
+    onFailure: () => void;
+}): TokenRefresher;
+//# sourceMappingURL=credential.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"credential.d.ts","sourceRoot":"","sources":["../../../src/window/mount/credential.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAA;AACvE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AACvC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAE/C,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,iCAAiC,CAAA;AAE3F,MAAM,MAAM,kBAAkB,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAA;AAE1E,mGAAmG;AACnG,eAAO,MAAM,cAAc,EAAE,cAI5B,CAAA;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,MAAM,EAAE,YAAY,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,eAAe,CAAA;CAC3B,GAAG;IACF,OAAO,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,CAAA;IAC1C,WAAW,EAAE,CAAC,MAAM,OAAO,CAAC,kBAAkB,CAAC,CAAC,GAAG,IAAI,CAAA;CACxD,CAkBA;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,kBAAkB,CAAA;IAC3B,WAAW,EAAE,CAAC,MAAM,OAAO,CAAC,kBAAkB,CAAC,CAAC,GAAG,IAAI,CAAA;IACvD,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,QAAQ,EAAE,yBAAyB,CAAA;IACnC,SAAS,EAAE,MAAM,IAAI,CAAA;CACtB,GAAG,cAAc,CAqCjB"}

package/dist/window/mount/credential.js

@@ -0,0 +1,74 @@
+import { createTokenRefresher } from '../../kernel/delegation/refresh';
+/** No-op refresher for windows with no token to refresh (plain mounts, no-refresh credentials). */
+export const NOOP_REFRESHER = {
+    start: () => { },
+    stop: () => { },
+    forceRefreshNow: () => Promise.resolve(),
+};
+/**
+ * Pick where the window's credential comes from — and how it refreshes.
+ *
+ * A PROVIDED credential (the app-principal path — e.g. `app::open`'s composed
+ * credential) is used as-is and refreshes through its own callback (re-calling
+ * `app::open`); no callback → no refresh (the window lives at most until
+ * `expiresAt`). Otherwise the shell mints — and re-mints — its own delegation.
+ */
+export function credentialSource(opts) {
+    const mint = async () => {
+        const credential = await opts.kernel.mintDelegation();
+        return { credential, expiresAt: Date.now() + opts.ttlSeconds * 1_000 };
+    };
+    const provided = opts.provided;
+    if (!provided)
+        return { acquire: mint, refreshMint: mint };
+    return {
+        acquire: () => Promise.resolve({ credential: provided.token, expiresAt: provided.expiresAt }),
+        refreshMint: provided.refresh
+            ? async () => {
+                const next = await provided.refresh();
+                return { credential: next.token, expiresAt: next.expiresAt };
+            }
+            : null,
+    };
+}
+/**
+ * Wire the per-window refresher: on each refresh, update the Window store and
+ * push a `ctrl:tokenRefresh` down the child's channel.
+ */
+export function wireTokenRefresher(opts) {
+    const { windowId, refreshMint } = opts;
+    if (!refreshMint)
+        return NOOP_REFRESHER;
+    // The live expiry advances on every refresh. The Window store only keeps
+    // the credential, so track expiry here — otherwise `token()` keeps
+    // returning the original expiry and `schedule()` collapses its lead time
+    // to 0, busy-looping the mint forever after the first refresh.
+    let currentExpiresAt = opts.initial.expiresAt;
+    return createTokenRefresher({
+        functionId: opts.functionId,
+        token: () => {
+            const stored = opts.windows.get(windowId);
+            return {
+                credential: stored?.delegationToken ?? opts.initial.credential,
+                expiresAt: currentExpiresAt,
+                issuedAt: 0,
+                scope: { functionId: opts.functionId },
+            };
+        },
+        setToken: (next) => {
+            currentExpiresAt = next.expiresAt;
+            const stored = opts.windows.get(windowId);
+            if (stored) {
+                opts.windows.set(windowId, { ...stored, delegationToken: next.credential });
+            }
+            opts.children.send(windowId, {
+                type: 'ctrl',
+                version: 1,
+                action: 'tokenRefresh',
+                data: { delegationToken: next.credential, tokenExpiresAt: next.expiresAt },
+            });
+        },
+        mint: refreshMint,
+        onFailure: opts.onFailure,
+    });
+}

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

@@ -0,0 +1 @@
+{"version":3,"file":"handshake.d.ts","sourceRoot":"","sources":["../../../src/window/mount/handshake.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;IAClC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC9E;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAEjD,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAC3B,CAAA;AAED,qGAAqG;AACrG,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAsEpF"}

package/dist/{application/windowing → window/mount}/handshake.js

@@ -1,4 +1,4 @@
-import { INIT_RESPONSE_TYPE, isInitRequest } from './protocol';
+import { INIT_RESPONSE_TYPE, isInitRequest } from '../../message/init';
 /** Parent-side handshake: wait for INIT_REQUEST, transfer a MessagePort, complete ctrl:handshake. */
 export function runParentHandshake(params) {
     const { iframe, expectedOrigin, timeoutMs } = params;

package/dist/{application/windowing/mount-controller.d.ts → window/mount/mount.d.ts}

@@ -1,9 +1,9 @@
-import type { Window } from '../../domain/window/window';
-import type { KernelClient } from '../../ports/kernel-client';
-import type { ShellAdapter } from '../../ports/shell-adapter';
-import type { ChildrenChannelController } from '../channels/children-channel';
-import type { MountParams, MountedWindow, CloseResult } from '../shell';
-import type { LifecycleController } from './lifecycle-controller';
+import type { ChildrenChannelController } from '../../channel/children';
+import type { KernelClient } from '../../kernel/client';
+import type { ShellAdapter } from '../embed/adapter';
+import type { LifecycleController } from '../lifecycle/states';
+import type { Window } from '../window';
+import type { CloseResult, MountedWindow, MountParams } from './params';
 export type MountControllerConfig = {
     adapter: ShellAdapter;
     kernel: KernelClient;
@@ -22,4 +22,4 @@ export interface MountController {
     dispose(): Promise<void>;
 }
 export declare function createMountController(config: MountControllerConfig): MountController;
-//# sourceMappingURL=mount-controller.d.ts.map
+//# sourceMappingURL=mount.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mount.d.ts","sourceRoot":"","sources":["../../../src/window/mount/mount.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAA;AACvE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAEvC,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAWvE,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,YAAY,CAAA;IACrB,MAAM,EAAE,YAAY,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,eAAe,EAAE,yBAAyB,CAAA;IAC1C,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,SAAS,EAAE,mBAAmB,CAAA;CAC/B,CAAA;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;IAClD,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAC7F,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACzB;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,eAAe,CAuJpF"}

package/dist/window/mount/mount.js

@@ -0,0 +1,143 @@
+import { createMessagePortTransport } from '../../channel/message-port';
+import { createCloser } from './close';
+import { credentialSource, wireTokenRefresher } from './credential';
+import { runParentHandshake } from './handshake';
+import { mountPlain } from './plain';
+const DEFAULT_HANDSHAKE_TIMEOUT = 5_000;
+const DEFAULT_DELEGATION_TTL = 3_600;
+export function createMountController(config) {
+    const { adapter, kernel, kernelUrl, mintIdentity, childrenChannel, windows, lifecycle } = config;
+    // The child iframe is always a DIFFERENT origin from this parent window, so a
+    // relative kernelUrl (e.g. the SPA's same-origin `/api/`) handed across the
+    // handshake would resolve against the iframe's OWN origin and POST to the
+    // wrong host. Absolutize it against the parent's location once so every child
+    // calls THIS origin's kernel. (The parent's own calls keep using the relative
+    // form via its kernel client / fetch.)
+    const childKernelUrl = new URL(kernelUrl, window.location.href).href;
+    const entries = new Map();
+    let seq = 0;
+    let disposed = false;
+    const close = createCloser({ entries, children: childrenChannel, windows, lifecycle });
+    function nextWindowId(functionId) {
+        seq += 1;
+        const slug = functionId.replace(/[^a-z0-9]/gi, '').slice(-8) || 'fn';
+        return `win-${slug}-${seq}`;
+    }
+    function originOf(url) {
+        try {
+            return new URL(url, window.location.href).origin;
+        }
+        catch {
+            throw new Error(`Invalid mount url: ${url}`);
+        }
+    }
+    const controller = {
+        async mount(params) {
+            if (disposed)
+                throw new Error('MountController is disposed');
+            // Plain (no-handshake) path: hosted views that don't speak the shell
+            // protocol. Skip mint/handshake/transport/refresher; the iframe still
+            // renders and `close()` falls through to dispose.
+            if (params.handshake === 'none') {
+                const windowId = nextWindowId(params.functionId);
+                return mountPlain({ adapter, windows, lifecycle, entries, close }, windowId, params);
+            }
+            const ttlSeconds = params.delegationTtlSeconds ?? DEFAULT_DELEGATION_TTL;
+            const handshakeTimeout = params.handshakeTimeoutMs ?? DEFAULT_HANDSHAKE_TIMEOUT;
+            const expectedOrigin = originOf(params.url);
+            const windowId = nextWindowId(params.functionId);
+            const { acquire, refreshMint } = credentialSource({
+                kernel,
+                ttlSeconds,
+                provided: params.credential,
+            });
+            // Mint the token and create the iframe in parallel — the iframe
+            // doesn't need the credential until the handshake fires.
+            const [{ credential, expiresAt }, mounted] = await Promise.all([
+                acquire(),
+                Promise.resolve(adapter.mount({
+                    functionId: params.functionId,
+                    isolation: 'sandboxed',
+                    capabilities: params.capabilities,
+                    sandbox: params.sandbox,
+                })),
+            ]);
+            const { handle, dispose: disposeHandle } = mounted;
+            if (!(handle.element instanceof HTMLIFrameElement)) {
+                disposeHandle();
+                throw new Error('Shell adapter did not produce an HTMLIFrameElement');
+            }
+            params.host.appendChild(handle.element);
+            handle.element.src = params.url;
+            let handshakeResult;
+            try {
+                handshakeResult = await runParentHandshake({
+                    iframe: handle.element,
+                    expectedOrigin,
+                    windowId,
+                    delegationToken: credential,
+                    tokenExpiresAt: expiresAt,
+                    kernelUrl: childKernelUrl,
+                    functionId: params.functionId,
+                    targetNodeId: params.targetNodeId,
+                    mintIdentity,
+                    timeoutMs: handshakeTimeout,
+                });
+            }
+            catch (err) {
+                disposeHandle();
+                throw err;
+            }
+            const transport = createMessagePortTransport({
+                port: handshakeResult.port,
+                onClose: () => {
+                    if (!entries.has(windowId))
+                        return;
+                    lifecycle.markCrashed(windowId);
+                    void close(windowId, { force: true }).catch(() => { });
+                },
+            });
+            childrenChannel.attach(windowId, transport);
+            windows.set(windowId, {
+                windowId,
+                functionId: params.functionId,
+                targetNodeId: params.targetNodeId,
+                isolation: 'sandboxed',
+                state: 'active',
+                delegationToken: credential,
+                capabilities: params.capabilities,
+            });
+            lifecycle.register(windowId, 'active');
+            const refresher = wireTokenRefresher({
+                windowId,
+                functionId: params.functionId,
+                initial: { credential, expiresAt },
+                refreshMint,
+                windows,
+                children: childrenChannel,
+                onFailure: () => {
+                    void close(windowId, { force: false }).catch(() => { });
+                },
+            });
+            refresher.start();
+            entries.set(windowId, { handle, dispose: disposeHandle, refresher });
+            return {
+                windowId,
+                get window() {
+                    return windows.get(windowId);
+                },
+                handle: { element: handle.element },
+                close: (opts) => close(windowId, opts),
+            };
+        },
+        close,
+        async dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            const ids = [...entries.keys()];
+            await Promise.all(ids.map((id) => close(id, { force: true })));
+        },
+    };
+    return controller;
+}

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

@@ -0,0 +1,73 @@
+import type { SandboxProfile, WindowCapabilities } from '../capabilities';
+import type { Window } from '../window';
+/**
+ * A PRE-MINTED credential to hand the mounted iframe instead of the shell's
+ * own delegation mint — the app-principal path. The caller composes it from
+ * `app::open()`'s components: the USER mints a pre-attenuated delegation
+ * (`union(intersect(roles, self), intersect(self, app))` — only the user can
+ * sign it, so the app never holds the raw user token), then the final
+ * envelope is minted AS the app (`session.as(appCredential)`). The iframe
+ * then acts as the application with exactly that authority.
+ */
+export type MountCredential = {
+    /** The token the iframe authenticates with. */
+    readonly token: string;
+    /** Epoch-ms expiry — drives the refresh schedule. */
+    readonly expiresAt: number;
+    /**
+     * Re-mint before expiry (typically re-calling `app::open` and returning its
+     * fresh `credential`/`expiresAt`). Omit to disable refresh — the window then
+     * lives at most until `expiresAt`.
+     */
+    readonly refresh?: () => Promise<{
+        token: string;
+        expiresAt: number;
+    }>;
+};
+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;
+    /**
+     * Mount with THIS credential instead of self-minting one (see
+     * {@link MountCredential}). When present, `delegationTtlSeconds` is inert —
+     * the provided `expiresAt` (and `refresh`) govern the token's lifetime.
+     */
+    readonly credential?: MountCredential;
+    /**
+     * `'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>;
+};
+//# sourceMappingURL=params.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"params.d.ts","sourceRoot":"","sources":["../../../src/window/mount/params.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AACzE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAEvC;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACvE,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAA;IACzC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,gFAAgF;IAChF,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,IAAI,CAAA;IACxC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IACpC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAA;IACtC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAA;IACrC;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;CACtC,CAAA;AAED,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAEpB,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,iBAAiB,GAAG,WAAW,CAAA;KAAE,CAAA;IAC7D,KAAK,CAAC,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;CAC5E,CAAA"}

package/dist/window/mount/params.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,20 @@
+import type { ShellAdapter } from '../embed/adapter';
+import type { LifecycleController } from '../lifecycle/states';
+import type { Window } from '../window';
+import type { Closer, MountEntry } from './close';
+import type { MountedWindow, MountParams } from './params';
+export type PlainMountDeps = {
+    adapter: ShellAdapter;
+    windows: Map<string, Window>;
+    lifecycle: LifecycleController;
+    entries: Map<string, MountEntry>;
+    close: Closer;
+};
+/**
+ * Plain-iframe mount path — for hosted views that don't speak the shell
+ * protocol. No handshake, no transport, no delegation token, no refresher;
+ * the iframe just renders. `close()` skips the ack request (no channel) and
+ * falls straight to dispose.
+ */
+export declare function mountPlain(deps: PlainMountDeps, windowId: string, params: MountParams): Promise<MountedWindow>;
+//# sourceMappingURL=plain.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plain.d.ts","sourceRoot":"","sources":["../../../src/window/mount/plain.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AACvC,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAI1D,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,YAAY,CAAA;IACrB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,SAAS,EAAE,mBAAmB,CAAA;IAC9B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IAChC,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,cAAc,EACpB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,aAAa,CAAC,CAyCxB"}

package/dist/window/mount/plain.js

@@ -0,0 +1,46 @@
+import { NOOP_REFRESHER } from './credential';
+/**
+ * Plain-iframe mount path — for hosted views that don't speak the shell
+ * protocol. No handshake, no transport, no delegation token, no refresher;
+ * the iframe just renders. `close()` skips the ack request (no channel) and
+ * falls straight to dispose.
+ */
+export async function mountPlain(deps, windowId, params) {
+    const { adapter, windows, lifecycle, entries, close } = deps;
+    const { handle, dispose: disposeHandle } = adapter.mount({
+        functionId: params.functionId,
+        isolation: 'sandboxed',
+        capabilities: params.capabilities,
+        sandbox: params.sandbox,
+    });
+    if (!(handle.element instanceof HTMLIFrameElement)) {
+        disposeHandle();
+        throw new Error('Shell adapter did not produce an HTMLIFrameElement');
+    }
+    params.host.appendChild(handle.element);
+    handle.element.src = params.url;
+    windows.set(windowId, {
+        windowId,
+        functionId: params.functionId,
+        targetNodeId: params.targetNodeId,
+        isolation: 'sandboxed',
+        state: 'active',
+        delegationToken: null,
+        capabilities: params.capabilities,
+    });
+    lifecycle.register(windowId, 'active');
+    entries.set(windowId, {
+        handle,
+        dispose: disposeHandle,
+        refresher: NOOP_REFRESHER,
+        plain: true,
+    });
+    return {
+        windowId,
+        get window() {
+            return windows.get(windowId);
+        },
+        handle: { element: handle.element },
+        close: (opts) => close(windowId, opts),
+    };
+}

package/dist/{domain/window → window}/window.d.ts

@@ -1,4 +1,4 @@
-import type { WindowCapabilities } from './config';
+import type { WindowCapabilities } from './capabilities';
 export type WindowState = 'active' | 'hidden' | 'closing' | 'closed';
 export interface Window {
     readonly windowId: string;

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

@@ -0,0 +1 @@
+{"version":3,"file":"window.d.ts","sourceRoot":"","sources":["../../src/window/window.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAExD,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAA;AAEpE,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,SAAS,EAAE,WAAW,GAAG,QAAQ,CAAA;IAC1C,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;IACvC,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAA;CAC1C"}

package/dist/window/window.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@astrale-os/shell",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Astrale Shell SDK — parent/child/kernel communication",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/astrale-os/shell.git",
@@ -21,21 +22,25 @@
     }
   },
   "publishConfig": {
-    "access": "restricted",
-    "registry": "https://npm.pkg.github.com"
+    "access": "public"
   },
   "dependencies": {
-    "@astrale-os/kernel-client": ">=0.1.0 <1.0.0",
+    "@astrale-domains/workspace-schema": ">=0.2.0 <1.0.0",
+    "@astrale-os/kernel-client": ">=0.3.0 <1.0.0",
     "@astrale-os/kernel-core": ">=0.4.1 <1.0.0"
   },
   "devDependencies": {
     "@typescript/native-preview": "latest",
-    "typescript": "~6.0.1-rc"
+    "happy-dom": "^20.0.0",
+    "typescript": "~6.0.1-rc",
+    "vitest": "^3.2.4"
   },
   "scripts": {
     "build": "tsgo",
     "clean": "rm -rf dist *.tsbuildinfo",
-    "typecheck": "tsgo --noEmit",
+    "typecheck": "tsgo --noEmit && tsgo --noEmit -p tsconfig.test.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "preinstall": "node .check-workspace.cjs"
   }
 }