@astrale-os/shell-react 0.1.0

package/src/window/lifecycle/mount.ts

@@ -0,0 +1,134 @@
+import type { NodeRefInput } from '@astrale-os/kernel-client'
+/**
+ * Mount orchestration (API §10) — resolve a `ViewSource` to something `shell.mount`
+ * accepts (url + handshake + functionId), the stable remount key, the delivered
+ * target id, the handshake-fallback predicate, and the parent→child setTarget
+ * hot-swap. A one-call `View.resolve` kernel contract does not exist yet — the
+ * bare-ref path is the honest subset, G5.
+ */
+import type { KernelClient, Shell } from '@astrale-os/shell'
+
+/** A live graph node, derived from the shell kernel read surface (G8 seam). */
+export type Node = NonNullable<Awaited<ReturnType<KernelClient['get']>>>
+
+/** A View function resolved to something mountable (url + optional handshake). */
+export interface ViewDescriptor {
+  readonly id: string
+  readonly path: string
+  readonly url?: string
+  readonly handshake?: string
+}
+
+/**
+ * What a `ViewHost` mounts:
+ *  - `{ view }` — a View function (descriptor or ref), resolved to url + handshake.
+ *  - `{ url }`  — a handshake-less hosted view; mounts immediately (no 5s wait).
+ */
+export type ViewSource = { readonly view: NodeRefInput | ViewDescriptor } | { readonly url: string }
+
+export interface ResolvedSource {
+  readonly url: string
+  readonly handshake: 'shell' | 'none'
+  readonly functionId: string
+}
+
+function isViewDescriptor(view: NodeRefInput | ViewDescriptor): view is ViewDescriptor {
+  return typeof view === 'object' && view !== null && 'id' in view && 'path' in view
+}
+
+/** Last path segment or host, alnum-only — a stable-ish functionId from a url. */
+function slugOfUrl(url: string): string {
+  const trimmed = url.replace(/[#?].*$/, '').replace(/\/+$/, '')
+  const tail = trimmed.split('/').filter(Boolean).pop() ?? 'view'
+  return tail.replace(/[^a-z0-9]/gi, '').slice(-32) || 'view'
+}
+
+/** A ref addressable by the kernel read surface (`get`). `@<id>` for bare ids. */
+function toPath(ref: NodeRefInput): string {
+  if (typeof ref === 'string') {
+    return ref.startsWith('/') || ref.startsWith('@') ? ref : `@${ref}`
+  }
+  const obj = ref as { id?: string; path?: { raw?: string } }
+  if (obj.path?.raw !== undefined) return obj.path.raw
+  if (obj.id !== undefined) return `@${obj.id}`
+  throw new Error('ViewHost: unresolvable view ref')
+}
+
+async function resolveViewRef(
+  kernel: KernelClient,
+  ref: NodeRefInput,
+  handshakeHint?: string,
+): Promise<ResolvedSource> {
+  const node = await kernel.get(toPath(ref))
+  if (node === null) throw new Error(`ViewHost: view not found (${toPath(ref)})`)
+  const props = (node as { id?: string; props?: Record<string, unknown> }).props ?? {}
+  const url = props.url
+  if (typeof url !== 'string' || url.length === 0) {
+    throw new Error('ViewHost: resolved view has no url')
+  }
+  const handshake = normalizeHandshake(handshakeHint ?? props.handshake)
+  const id = (node as { id?: string }).id ?? slugOfUrl(url)
+  return { url, handshake, functionId: id }
+}
+
+function normalizeHandshake(value: unknown): 'shell' | 'none' {
+  return value === 'none' ? 'none' : 'shell'
+}
+
+/** Resolve a source; may hit the kernel for a bare/urless View ref (G5). */
+export async function resolveSource(
+  kernel: KernelClient,
+  source: ViewSource,
+): Promise<ResolvedSource> {
+  if ('url' in source) {
+    return { url: source.url, handshake: 'none', functionId: slugOfUrl(source.url) }
+  }
+  const view = source.view
+  if (isViewDescriptor(view)) {
+    if (view.url !== undefined && view.url.length > 0) {
+      return {
+        url: view.url,
+        handshake: normalizeHandshake(view.handshake),
+        functionId: view.id,
+      }
+    }
+    return resolveViewRef(kernel, view.id, view.handshake)
+  }
+  return resolveViewRef(kernel, view)
+}
+
+/** A stable remount key: the same source identity must not remount. */
+export function sourceKey(source: ViewSource): string {
+  if ('url' in source) return `url:${source.url}`
+  const view = source.view
+  if (isViewDescriptor(view)) return `view:${view.id}:${view.url ?? ''}:${view.handshake ?? ''}`
+  if (typeof view === 'string') return `ref:${view}`
+  const obj = view as { id?: string; path?: { raw?: string } }
+  return `ref:${obj.id ?? obj.path?.raw ?? '?'}`
+}
+
+/** The bare node id delivered as `targetNodeId` at mount / retarget. */
+export function refToId(ref: NodeRefInput | undefined): string | undefined {
+  if (ref === undefined) return undefined
+  if (typeof ref === 'string') return ref.startsWith('@') ? ref.slice(1) : ref
+  const obj = ref as { id?: string }
+  return obj.id
+}
+
+/**
+ * Fallbackable = the view didn't speak the shell protocol (timeout/failed), not a
+ * security refusal (origin mismatch) — only the former downgrades to plain.
+ */
+export function isFallbackableHandshakeError(err: unknown): boolean {
+  const code = (err as { code?: unknown } | null)?.code
+  return code === 'HANDSHAKE_TIMEOUT' || code === 'HANDSHAKE_FAILED'
+}
+
+/** Parent → child hot-swap of the target node (no remount) — API §10 setTarget. */
+export function sendSetTarget(shell: Shell, windowId: string, nodeId: string): void {
+  shell.children.send(windowId, {
+    type: 'intent',
+    version: 1,
+    envelope: { name: 'setTarget', payload: { nodeId }, sender: { windowId: '<parent>' } },
+  })
+}

package/src/window/lifecycle/states.ts

@@ -0,0 +1,23 @@
+/**
+ * The WindowState phase machine (API §10) — the lifecycle of a hosted view as the
+ * React face observes it. Distinct from the shell's own `WindowState`
+ * (`active|hidden|closing|closed`): this is the phase a `ViewHost`/`AppHost`
+ * renders around.
+ */
+
+/**
+ * Lifecycle of a hosted view as the React face observes it (API §10).
+ *
+ * `ready.downgraded` marks a mount that fell back to a plain iframe after a
+ * fallbackable handshake error. It rides here (not on the shell `Window`) until
+ * the shell `Window` grows a first-class flag — flagged in the module report.
+ *
+ * `crashed.windowId` is OPTIONAL: a crash before a window exists (a session-open
+ * failure, a pre-mount source-resolution failure) has no id to report — the type
+ * says so rather than carrying a placeholder `''`.
+ */
+export type WindowState =
+  | { readonly phase: 'mounting' }
+  | { readonly phase: 'ready'; readonly windowId: string; readonly downgraded?: boolean }
+  | { readonly phase: 'crashed'; readonly windowId?: string; readonly error?: unknown }
+  | { readonly phase: 'closed'; readonly windowId: string; readonly refusal?: string }

package/src/window/placement.ts

@@ -0,0 +1,84 @@
+/**
+ * Slot geometry (API §10) — the physical iframe-slot layer over a stage container
+ * (measure + project). Slots live in the stage (imperative DOM), insulated from
+ * React reconciliation of the hosts; only a slot's box is repositioned, so a
+ * healthy iframe never reloads on reorder/re-key/re-parent.
+ */
+
+/** Viewport-space box a host projects onto its stage slot. */
+export interface SlotRect {
+  readonly top: number
+  readonly left: number
+  readonly width: number
+  readonly height: number
+}
+
+/**
+ * One persistent slot inside the stage. Its `element` is the mount host handed
+ * to `shell.mount`; the element NEVER moves in the DOM while the owning host
+ * reorders/re-keys/re-parents — only its box is repositioned via `place`.
+ */
+export interface StageSlot {
+  readonly element: HTMLElement
+  place(rect: SlotRect): void
+  release(): void
+}
+
+export interface StageController {
+  acquire(): StageSlot
+  dispose(): void
+}
+
+/** Build the slot layer over a stage container element (imperative, no React). */
+export function createStageController(container: HTMLElement): StageController {
+  const slots = new Set<HTMLElement>()
+  let disposed = false
+
+  return {
+    acquire() {
+      const element = container.ownerDocument.createElement('div')
+      element.dataset.astraleViewSlot = ''
+      element.style.position = 'absolute'
+      element.style.top = '0'
+      element.style.left = '0'
+      element.style.pointerEvents = 'auto'
+      container.appendChild(element)
+      slots.add(element)
+
+      let released = false
+      return {
+        element,
+        place(rect) {
+          // translate + explicit box, so a reflow of the container never drifts
+          // the slot off its anchor.
+          element.style.transform = `translate(${rect.left}px, ${rect.top}px)`
+          element.style.width = `${rect.width}px`
+          element.style.height = `${rect.height}px`
+        },
+        release() {
+          if (released) return
+          released = true
+          slots.delete(element)
+          element.remove()
+        },
+      }
+    },
+
+    dispose() {
+      if (disposed) return
+      disposed = true
+      for (const el of slots) el.remove()
+      slots.clear()
+    },
+  }
+}
+
+/** Measure an anchor element's viewport box. */
+export function rectOf(el: HTMLElement): SlotRect {
+  const r = el.getBoundingClientRect()
+  return { top: r.top, left: r.left, width: r.width, height: r.height }
+}
+
+export function sameRect(a: SlotRect, b: SlotRect): boolean {
+  return a.top === b.top && a.left === b.left && a.width === b.width && a.height === b.height
+}

package/src/window/stage.tsx

@@ -0,0 +1,46 @@
+import type { CSSProperties, ReactElement } from 'react'
+
+/**
+ * ViewStage (API §10) — the fixed-positioning layer that physically owns every
+ * iframe for the `ViewHost`/`AppHost`s in the tree. Mount it ONCE near the root.
+ * Reordering / re-parenting / re-keying hosts never reloads a healthy iframe:
+ * each iframe lives in a stage slot (imperative DOM), insulated from React
+ * reconciliation of the hosts; only the slot's box is repositioned.
+ */
+import { useEffect, useMemo, useRef } from 'react'
+
+import { useShell } from '../session/shell.hook'
+import { getStageHub } from './hub'
+import { createStageController } from './placement'
+
+/**
+ * A full-viewport overlay that does not intercept pointer events — individual
+ * slots re-enable them, so only the iframes are interactive, not the gaps.
+ */
+const STAGE_STYLE: CSSProperties = {
+  position: 'fixed',
+  top: 0,
+  left: 0,
+  right: 0,
+  bottom: 0,
+  pointerEvents: 'none',
+}
+
+export function ViewStage(): ReactElement {
+  const shell = useShell()
+  const hub = useMemo(() => getStageHub(shell), [shell])
+  const containerRef = useRef<HTMLDivElement | null>(null)
+
+  useEffect(() => {
+    const container = containerRef.current
+    if (container === null) return
+    const controller = createStageController(container)
+    hub.setController(controller)
+    return () => {
+      hub.setController(null)
+      controller.dispose()
+    }
+  }, [hub])
+
+  return <div ref={containerRef} data-astrale-view-stage="" style={STAGE_STYLE} />
+}