@astrale-os/shell 0.1.1 → 0.2.0

package/src/shell/shell.ts

@@ -0,0 +1,37 @@
+import type { AppsNamespace } from '../application/apps'
+import type { SpacesNamespace } from '../application/spaces'
+import type { UserNamespace } from '../application/user'
+import type { ChildrenChannel } from '../channel/children'
+import type { ObserverHandler } from '../channel/observer'
+import type { ParentChannel } from '../channel/parent'
+import type { IntentMiddleware } from '../intent/pipeline'
+import type { LocalIntentHandler } from '../intent/router'
+import type { KernelClient } from '../kernel/client'
+import type { IntentRegistry } from '../message/intent'
+import type { CloseResult, MountedWindow, MountParams } from '../window/mount/params'
+import type { Window } from '../window/window'
+
+export interface Shell {
+  readonly parent: ParentChannel | null
+  readonly children: ChildrenChannel
+  readonly kernel: KernelClient
+  readonly windows: ReadonlyMap<string, Window>
+  readonly targetNodeId?: string
+
+  /** OS plane: the caller as a shell-domain `User` — self, current space, roles. */
+  readonly user: UserNamespace
+  /** OS plane: the caller's readable spaces — list, get, create. */
+  readonly spaces: SpacesNamespace
+  /** OS plane: apps — install, list per space, open (returns an `AppSession`). */
+  readonly apps: AppsNamespace
+
+  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>
+}

package/src/shell/standalone.ts

@@ -0,0 +1,97 @@
+import type { MountController } from '../window/mount/mount'
+import type { Window } from '../window/window'
+import type { StandaloneConfig } from './config'
+import type { Shell } from './shell'
+
+import { createChildrenChannel } from '../channel/children'
+import { createMessageObserver } from '../channel/observer'
+import { createIntentPipeline } from '../intent/pipeline'
+import { createIntentRouter } from '../intent/router'
+import { createKernelFacade } from '../kernel/credential'
+import { createKernelClientAdapter } from '../kernel/session'
+import { createLifecycleController } from '../window/lifecycle/states'
+import { createMountController } from '../window/mount/mount'
+import { buildShellFacade } from './build'
+
+const DEFAULT_ROOT_WINDOW_ID = 'root'
+
+export function createStandaloneShell(config: StandaloneConfig): Shell {
+  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,
+    fetch: config.fetch,
+  })
+  const kernel = createKernelFacade({
+    adapter,
+    getCredential,
+    url: config.kernelUrl,
+    mintIdentity: config.mintIdentity,
+  })
+
+  const lifecycle = createLifecycleController()
+  const windows = new Map<string, Window>()
+
+  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', (fromWindowId, message) => {
+    void router.handleInbound('child', message, fromWindowId)
+  })
+
+  let mountController: MountController | null = null
+  function getMountController(): MountController {
+    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()
+    },
+  })
+}

package/src/{domain/window/config.ts → window/capabilities.ts}

@@ -1,4 +1,4 @@
-import type { IntentRegistry } from '../message/registries'
+import type { IntentRegistry } from '../message/intent'
 
 export interface SandboxProfile {
   readonly allowScripts: boolean
@@ -18,7 +18,7 @@ export interface WindowConfig {
   readonly capabilities: WindowCapabilities
   /**
    * Sandbox profile for the iframe.
-   * - `undefined` → adapter default (`DEFAULT_SANDBOX` in iframe.shell-adapter).
+   * - `undefined` → adapter default (`DEFAULT_SANDBOX` in embed/iframe).
    * - `SandboxProfile` → explicit flag set, becomes the `sandbox=…` attribute.
    * - `null` → opt out: no `sandbox` attribute on the iframe at all (the
    *   browser's cross-origin policy is the only remaining isolation). Used

package/src/{ports/shell-adapter.ts → window/embed/adapter.ts}

@@ -1,4 +1,4 @@
-import type { WindowConfig } from '../domain/window/config'
+import type { WindowConfig } from '../capabilities'
 
 export interface WindowHandle {
   readonly element: HTMLIFrameElement | HTMLElement
@@ -6,6 +6,7 @@ export interface WindowHandle {
   readonly origin: string
 }
 
+/** How a window's host element gets created — the shell's embedding extension point. */
 export interface ShellAdapter {
   mount(config: WindowConfig): { handle: WindowHandle; dispose: () => void }
 }

package/src/{adapters/iframe.shell-adapter.ts → window/embed/iframe.ts}

@@ -1,5 +1,5 @@
-import type { SandboxProfile } from '../domain/window/config'
-import type { ShellAdapter, WindowHandle } from '../ports/shell-adapter'
+import type { SandboxProfile } from '../capabilities'
+import type { ShellAdapter, WindowHandle } from './adapter'
 
 export type IframeShellAdapterConfig = {
   /**

package/src/{application/windowing/lifecycle-controller.ts → window/lifecycle/states.ts}

@@ -1,7 +1,8 @@
-import type { WindowState } from '../../domain/window/window'
+import type { WindowState } from '../window'
 
-import { transition, type LifecycleEvent } from '../../domain/window/lifecycle'
+import { transition, type LifecycleEvent } from './transition'
 
+/** Live per-window lifecycle states, advanced only through the transition machine. */
 export interface LifecycleController {
   register(windowId: string, initial?: WindowState): void
   apply(windowId: string, event: LifecycleEvent): WindowState | null

package/src/{domain/window/lifecycle.ts → window/lifecycle/transition.ts}

@@ -1,4 +1,4 @@
-import type { WindowState } from './window'
+import type { WindowState } from '../window'
 
 export type LifecycleEvent =
   | { kind: 'hide' }
@@ -11,7 +11,7 @@ export type LifecycleEvent =
 export type TransitionResult = { ok: true; next: WindowState } | { ok: false; reason: string }
 
 /**
- * Pure state-machine transition. Used by the lifecycle controller —
+ * Pure state-machine transition. Used by the lifecycle state map —
  * no timers, no side effects here.
  */
 export function transition(state: WindowState, event: LifecycleEvent): TransitionResult {

package/src/window/mount/close.ts

@@ -0,0 +1,111 @@
+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'
+
+const DEFAULT_CLOSE_TIMEOUT = 3_000
+/** Trusted sender id stamped on the parent's own close-protocol intents. */
+const PARENT_SENDER_ID = '<parent>'
+
+/** 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 function createCloser(deps: CloseDeps): Closer {
+  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' }
+  }
+}
+
+type CloseAck = { kind: 'ack' } | { kind: 'refused'; reason?: string } | { kind: 'timeout' }
+
+async function requestCloseAck(
+  children: ChildrenChannelController,
+  windowId: string,
+  timeoutMs: number,
+): Promise<CloseAck> {
+  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 as { reason?: string }).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/src/window/mount/credential.ts

@@ -0,0 +1,101 @@
+import type { ChildrenChannelController } from '../../channel/children'
+import type { KernelClient } from '../../kernel/client'
+import type { Window } from '../window'
+import type { MountCredential } from './params'
+
+import { createTokenRefresher, 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 const NOOP_REFRESHER: TokenRefresher = {
+  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: {
+  kernel: KernelClient
+  ttlSeconds: number
+  provided?: MountCredential
+}): {
+  acquire: () => Promise<AcquiredCredential>
+  refreshMint: (() => Promise<AcquiredCredential>) | null
+} {
+  const mint = async (): Promise<AcquiredCredential> => {
+    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: {
+  windowId: string
+  functionId: string
+  initial: AcquiredCredential
+  refreshMint: (() => Promise<AcquiredCredential>) | null
+  windows: Map<string, Window>
+  children: ChildrenChannelController
+  onFailure: () => void
+}): TokenRefresher {
+  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/src/{application/windowing → window/mount}/handshake.ts

@@ -1,6 +1,7 @@
-import type { CtrlMessage, ShellMessage } from '../../domain/message/types'
+import type { CtrlMessage } from '../../message/ctrl'
+import type { ShellMessage } from '../../message/message'
 
-import { INIT_RESPONSE_TYPE, isInitRequest } from './protocol'
+import { INIT_RESPONSE_TYPE, isInitRequest } from '../../message/init'
 
 export type HandshakeParams = {
   readonly iframe: HTMLIFrameElement

package/src/window/mount/mount.ts

@@ -0,0 +1,185 @@
+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 { MountEntry } from './close'
+import type { CloseResult, MountedWindow, MountParams } from './params'
+
+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 type MountControllerConfig = {
+  adapter: ShellAdapter
+  kernel: KernelClient
+  kernelUrl: string
+  mintIdentity?: string
+  childrenChannel: ChildrenChannelController
+  windows: Map<string, Window>
+  lifecycle: LifecycleController
+}
+
+export interface MountController {
+  mount(params: MountParams): Promise<MountedWindow>
+  close(windowId: string, opts?: { force?: boolean; timeoutMs?: number }): Promise<CloseResult>
+  dispose(): Promise<void>
+}
+
+export function createMountController(config: MountControllerConfig): MountController {
+  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<string, MountEntry>()
+  let seq = 0
+  let disposed = false
+
+  const close = createCloser({ entries, children: childrenChannel, windows, lifecycle })
+
+  function nextWindowId(functionId: string) {
+    seq += 1
+    const slug = functionId.replace(/[^a-z0-9]/gi, '').slice(-8) || 'fn'
+    return `win-${slug}-${seq}`
+  }
+
+  function originOf(url: string): string {
+    try {
+      return new URL(url, window.location.href).origin
+    } catch {
+      throw new Error(`Invalid mount url: ${url}`)
+    }
+  }
+
+  const controller: MountController = {
+    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/src/window/mount/params.ts

@@ -0,0 +1,64 @@
+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>
+}