@astrale-os/shell-react 0.1.0

package/src/window/hooks/views-for.hook.ts

@@ -0,0 +1,82 @@
+import type { PathLike } from '@astrale-os/kernel-client/graph'
+
+import { K } from '@astrale-os/kernel-core'
+/**
+ * useViewsFor (API §10) — "what Views can render this node", as mountable
+ * `ViewDescriptor`s for the open-with menu. Backed one-shot (`live:false`) by the
+ * kernel `View.resolve` syscall, which derives the node's class and returns the
+ * caller-visible Views (USE-visibility enforced kernel-side), each with mount url.
+ */
+import { useMemo } from 'react'
+
+import type { ReadState } from '../../graph/memory/read/envelope'
+import type { Node, ViewDescriptor } from '../lifecycle/mount'
+
+import { useAsyncResource } from '../../graph/async'
+import { useKernelClient } from '../../session/kernel-client.hook'
+
+export interface ViewsForResult extends ReadState {
+  readonly views: readonly ViewDescriptor[]
+}
+
+/** The `View.resolve` wire address — the qualified static-method slug from the schema. */
+const VIEW_RESOLVE_METHOD = K.View.resolve.path.method.raw
+
+/** The kernel `View.resolve` row shape (id/path/url/name?/handshake?/origin). */
+interface ViewOut {
+  readonly id: string
+  readonly path: string
+  readonly url: string
+  readonly name?: string
+  readonly handshake?: 'shell' | 'none'
+  readonly origin: 'self' | 'class'
+}
+
+const NO_VIEWS: readonly ViewDescriptor[] = Object.freeze([])
+
+export function useViewsFor(node: Node | PathLike | null | undefined): ViewsForResult {
+  const kernel = useKernelClient()
+  const target = resolvePath(node)
+
+  const res = useAsyncResource<readonly ViewDescriptor[]>(
+    target === null ? null : () => resolveViews(kernel, target),
+    NO_VIEWS,
+    [kernel, target],
+  )
+
+  return useMemo<ViewsForResult>(
+    () => ({
+      views: res.data,
+      pending: res.pending,
+      error: res.error,
+      live: false,
+      seq: 0,
+      refetch: res.refetch,
+    }),
+    [res.data, res.pending, res.error, res.refetch],
+  )
+}
+
+/** Dispatch `View.resolve` and project its rows to mountable `ViewDescriptor`s. */
+async function resolveViews(
+  kernel: { call(method: string, params: unknown): Promise<unknown> },
+  node: string,
+): Promise<readonly ViewDescriptor[]> {
+  const rows = (await kernel.call(VIEW_RESOLVE_METHOD, { node })) as ViewOut[] | null | undefined
+  if (rows === null || rows === undefined || rows.length === 0) return NO_VIEWS
+  return rows.map((r) => ({ id: r.id, path: r.path, url: r.url, handshake: r.handshake }))
+}
+
+/** A path/`@id` the kernel read surface accepts, or `null` for an idle subject. */
+function resolvePath(node: Node | PathLike | null | undefined): string | null {
+  if (node === null || node === undefined) return null
+  if (typeof node === 'string') {
+    if (node.length === 0) return null
+    return node.startsWith('/') || node.startsWith('@') ? node : `@${node}`
+  }
+  const obj = node as { path?: { raw?: unknown }; id?: unknown; raw?: unknown }
+  if (typeof obj.path?.raw === 'string') return obj.path.raw
+  if (typeof obj.id === 'string') return `@${obj.id}`
+  if (typeof obj.raw === 'string') return obj.raw
+  return null
+}

package/src/window/hooks/window.hook.ts

@@ -0,0 +1,18 @@
+/**
+ * useWindow(id) (API §10) — one window's live phase + shell `Window` (null id /
+ * unknown id → a stable "no window"), reactive over the per-shell hub registry.
+ */
+import { useMemo, useSyncExternalStore } from 'react'
+
+import type { WindowView } from '../hub'
+
+import { useShell } from '../../session/shell.hook'
+import { getStageHub } from '../hub'
+
+/** One window's live phase + shell `Window` (null id / unknown id → no window). */
+export function useWindow(windowId: string | null): WindowView {
+  const shell = useShell()
+  const hub = useMemo(() => getStageHub(shell), [shell])
+  const snapshot = useMemo(() => () => hub.registry.select(windowId), [hub, windowId])
+  return useSyncExternalStore(hub.registry.subscribe, snapshot, snapshot)
+}

package/src/window/hooks/windows.hook.ts

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

package/src/window/host.tsx

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

package/src/window/hub.ts

@@ -0,0 +1,156 @@
+/**
+ * The per-shell windows hub (API §10). `ViewStage` mounts once near the root while
+ * `ViewHost`s live anywhere, so they rendezvous through a hub keyed by the shared
+ * `Shell` instance (a `WeakMap`), not context. It owns the `WindowRegistry`
+ * (reactive store behind `useWindows`/`useWindow`, fed by the hosts), the stage
+ * controller (the slot layer, published by the stage), and the adopt stash.
+ */
+import type { Shell, Window } from '@astrale-os/shell'
+
+import type { AdoptRecord } from './adopt'
+import type { WindowState } from './lifecycle/states'
+import type { StageController } from './placement'
+
+import { createAdoptStash } from './adopt'
+
+// ── Window registry (reactive store behind useWindows/useWindow) ─────────────
+
+/** A host-tracked window: the shell `Window` plus the phase the host observes. */
+interface WindowEntry {
+  readonly window: Window
+  readonly state: WindowState
+}
+
+/** A `useWindow` projection — a window's phase plus its shell `Window` (or none). */
+export type WindowView = WindowState & { readonly window: Window | null }
+
+export interface WindowRegistry {
+  /** Referentially stable between mutations (useSyncExternalStore contract). */
+  getSnapshot(): ReadonlyMap<string, Window>
+  /** Stable projection for one window id (null id → a stable "no window"). */
+  select(windowId: string | null): WindowView
+  subscribe(onChange: () => void): () => void
+  /** Host writes: register/transition/drop a window. */
+  upsert(windowId: string, window: Window, state: WindowState): void
+  patch(windowId: string, state: WindowState): void
+  remove(windowId: string): void
+}
+
+const NO_WINDOW: WindowView = { phase: 'closed', windowId: '', window: null }
+
+function createWindowRegistry(): WindowRegistry {
+  const entries = new Map<string, WindowEntry>()
+  const listeners = new Set<() => void>()
+
+  // Cached snapshots: rebuilt only on mutation, so repeated getSnapshot/select
+  // calls between changes return identical references (no render loop).
+  let windowsSnapshot: ReadonlyMap<string, Window> | null = null
+  let selectCache = new Map<string, WindowView>()
+
+  function invalidate() {
+    windowsSnapshot = null
+    selectCache = new Map()
+    for (const l of listeners) l()
+  }
+
+  return {
+    getSnapshot() {
+      if (windowsSnapshot === null) {
+        const map = new Map<string, Window>()
+        for (const [id, entry] of entries) map.set(id, entry.window)
+        windowsSnapshot = map
+      }
+      return windowsSnapshot
+    },
+
+    select(windowId) {
+      if (windowId === null) return NO_WINDOW
+      const cached = selectCache.get(windowId)
+      if (cached !== undefined) return cached
+      const entry = entries.get(windowId)
+      const view: WindowView = entry
+        ? { ...entry.state, window: entry.window }
+        : { phase: 'closed', windowId, window: null }
+      selectCache.set(windowId, view)
+      return view
+    },
+
+    subscribe(onChange) {
+      listeners.add(onChange)
+      return () => {
+        listeners.delete(onChange)
+      }
+    },
+
+    upsert(windowId, window, state) {
+      entries.set(windowId, { window, state })
+      invalidate()
+    },
+
+    patch(windowId, state) {
+      const entry = entries.get(windowId)
+      if (entry === undefined) return
+      entries.set(windowId, { window: entry.window, state })
+      invalidate()
+    },
+
+    remove(windowId) {
+      if (!entries.delete(windowId)) return
+      invalidate()
+    },
+  }
+}
+
+// ── Per-shell hub ────────────────────────────────────────────────────────────
+
+export interface StageHub {
+  readonly registry: WindowRegistry
+  getController(): StageController | null
+  /** Publish (stage mount) or retract (stage unmount) the slot layer. */
+  setController(controller: StageController | null): void
+  /** Await the controller — fires immediately if one is already published. */
+  onController(cb: (controller: StageController | null) => void): () => void
+  /** Stash an unmounting host's live window; disposes after one macrotask if unadopted. */
+  stashForAdopt(key: string, record: AdoptRecord): void
+  /** Reclaim a stashed window for a remount of the same source, cancelling its dispose. */
+  takeAdopt(key: string): AdoptRecord | null
+}
+
+const HUBS = new WeakMap<Shell, StageHub>()
+
+/** The windows hub for a shell — one per shell object, created on first touch. */
+export function getStageHub(shell: Shell): StageHub {
+  const existing = HUBS.get(shell)
+  if (existing !== undefined) return existing
+
+  const registry = createWindowRegistry()
+  let controller: StageController | null = null
+  const waiters = new Set<(c: StageController | null) => void>()
+  const adopt = createAdoptStash()
+
+  const hub: StageHub = {
+    registry,
+    getController() {
+      return controller
+    },
+    setController(next) {
+      controller = next
+      for (const w of waiters) w(next)
+    },
+    onController(cb) {
+      waiters.add(cb)
+      if (controller !== null) cb(controller)
+      return () => {
+        waiters.delete(cb)
+      }
+    },
+    stashForAdopt(key, record) {
+      adopt.stash(key, record)
+    },
+    takeAdopt(key) {
+      return adopt.take(key)
+    },
+  }
+  HUBS.set(shell, hub)
+  return hub
+}

package/src/window/index.ts

@@ -0,0 +1,17 @@
+// window — API §10. ViewStage/ViewHost (the physical iframe-slot layer + a host
+// that projects placement into a slot), the reactive window hooks, the child-side
+// target-node + close-guard, and the (G5) view-resolution hook.
+export { ViewStage } from './stage'
+export { ViewHost } from './host'
+export type { ViewHostProps, ViewHostHandle } from './host'
+export { useWindows, useWindowList } from './hooks/windows.hook'
+export type { WindowListEntry } from './hooks/windows.hook'
+export { useWindow } from './hooks/window.hook'
+export type { WindowView } from './hub'
+export { useViewsFor } from './hooks/views-for.hook'
+export type { ViewsForResult } from './hooks/views-for.hook'
+export { useTargetNode } from './hooks/target-node.hook'
+export { useCloseGuard } from './hooks/close-guard.hook'
+export type { CloseGuard, CloseVerdict } from './hooks/close-guard.hook'
+export type { ViewDescriptor, ViewSource, Node } from './lifecycle/mount'
+export type { WindowState } from './lifecycle/states'