@astrale-os/shell-react 0.1.0

package/src/graph/query/neighbors.hook.ts

@@ -0,0 +1,124 @@
+import type { AnyBoundNode, EdgeNames } from '@astrale-os/kernel-client'
+import type { Schema } from '@astrale-os/kernel-dsl'
+
+/**
+ * useOut / useIn (API §6) — the public typed traversal read hooks. Resolve
+ * endpoints one-shot through `BoundNode.out/in` (`live: false`); become live with
+ * no surface change once edge-endpoint ids land. Deviations tracked in API §6/G6.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+
+import type { EndpointResult } from '../../schema/types'
+import type { ReadState, ReadOptions } from '../memory/read/envelope'
+
+import { schemaOf, tagSchema } from '../../schema/tag'
+import { isIdleInput } from '../memory/read/idle'
+
+export function useOut<S extends Schema, E extends EdgeNames<S>>(
+  node: AnyBoundNode<S> | null | undefined,
+  edge: E,
+  opts?: ReadOptions,
+): EndpointResult<S, E, 'to'> {
+  return useEndpoint(node, edge, 'out', opts) as unknown as EndpointResult<S, E, 'to'>
+}
+
+export function useIn<S extends Schema, E extends EdgeNames<S>>(
+  node: AnyBoundNode<S> | null | undefined,
+  edge: E,
+  opts?: ReadOptions,
+): EndpointResult<S, E, 'from'> {
+  return useEndpoint(node, edge, 'in', opts) as unknown as EndpointResult<S, E, 'from'>
+}
+
+type EndpointEnvelope<S extends Schema> = ReadState & {
+  readonly node?: AnyBoundNode<S> | null
+  readonly nodes?: readonly AnyBoundNode<S>[]
+}
+
+interface Traversal {
+  out(edge: string): Promise<unknown>
+  in(edge: string): Promise<unknown>
+}
+
+function useEndpoint<S extends Schema>(
+  node: AnyBoundNode<S> | null | undefined,
+  edge: string,
+  side: 'out' | 'in',
+  _opts?: ReadOptions,
+): EndpointEnvelope<S> {
+  const schema = isIdleInput(node) ? undefined : schemaOf(node)
+  const run = useCallback(async (): Promise<unknown> => {
+    if (isIdleInput(node)) return null
+    // AnyBoundNode omits traversal at the type level; the runtime node (bindAny
+    // → createBoundNode) carries out/in. The edge name is typed by the caller.
+    const t = node as unknown as Traversal
+    const result = await (side === 'out' ? t.out(edge) : t.in(edge))
+    if (schema !== undefined) tagEndpoints(result, schema)
+    return result
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [node?.id, edge, side])
+
+  const { data, pending, error, refetch } = useAsyncRead(isIdleInput(node) ? null : run, [
+    node?.id ?? null,
+    edge,
+    side,
+  ])
+
+  return useMemo<EndpointEnvelope<S>>(() => {
+    const live: ReadState = { pending, error, live: false, seq: 0, refetch }
+    if (isIdleInput(node)) return { ...live, node: null, nodes: EMPTY }
+    if (Array.isArray(data)) return { ...live, nodes: data as readonly AnyBoundNode<S>[] }
+    return { ...live, node: (data ?? null) as AnyBoundNode<S> | null }
+  }, [node, data, pending, error, refetch])
+}
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+const EMPTY: readonly never[] = Object.freeze([])
+
+function tagEndpoints(result: unknown, schema: Schema): void {
+  if (Array.isArray(result)) for (const r of result) tagSchema(r, schema)
+  else if (result !== null && result !== undefined) tagSchema(result, schema)
+}
+
+interface AsyncState<T> {
+  data?: T
+  pending: boolean
+  error: unknown
+}
+
+/** One-shot async read with pending/error/refetch and stale-response guarding. */
+function useAsyncRead<T>(
+  run: (() => Promise<T>) | null,
+  deps: readonly unknown[],
+): AsyncState<T> & { refetch(): Promise<void> } {
+  const [state, setState] = useState<AsyncState<T>>({ pending: run !== null, error: undefined })
+  const runRef = useRef(run)
+  runRef.current = run
+  const seq = useRef(0)
+
+  const refetch = useCallback((): Promise<void> => {
+    const current = runRef.current
+    if (current === null) {
+      setState({ pending: false, error: undefined, data: undefined })
+      return Promise.resolve()
+    }
+    const my = ++seq.current
+    setState((s) => ({ ...s, pending: true, error: undefined }))
+    return current().then(
+      (data) => {
+        if (my === seq.current) setState({ data, pending: false, error: undefined })
+      },
+      (error: unknown) => {
+        if (my === seq.current) setState((s) => ({ data: s.data, pending: false, error }))
+      },
+    )
+  }, [])
+
+  useEffect(() => {
+    void refetch()
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, deps)
+
+  return { ...state, refetch }
+}

package/src/graph/query/node.hook.ts

@@ -0,0 +1,83 @@
+import type { NodeRefInput, TypeNames } from '@astrale-os/kernel-client'
+import type { PathLike } from '@astrale-os/kernel-client/graph'
+import type { Schema } from '@astrale-os/kernel-dsl'
+
+/**
+ * useNode (API §5 + §6) — ONE public symbol, overloaded: pass a `Schema` (+ type)
+ * for the typed `BoundNode` result, or a bare ref for the untyped `Node` result.
+ * Both forms ride the SAME memory shape — a typed read and its untyped twin are
+ * one cache entry, one liveness, one overlay. The runtime dispatches on the first
+ * argument; a given call site is always one form, so hook order is stable.
+ */
+import { useMemo } from 'react'
+
+import type { TypedNodeResult } from '../../schema/types'
+import type { ReadState, Node, ReadOptions } from '../memory/read/envelope'
+
+import { useNode as useNodeTyped } from '../../schema/bind-read'
+import { useRead } from '../memory/read/read'
+
+export interface NodeResult extends ReadState {
+  /** The node, or `null` when missing ≡ masked (never throws NOT_FOUND). */
+  readonly node: Node | null
+}
+
+/**
+ * A `Schema` (from `defineSchema`) — its shape (`domain`/`classes`/`interfaces`)
+ * is disjoint from a `PathLike` (`string | Path`), so this cleanly routes the
+ * typed vs untyped overload at runtime.
+ */
+function isSchema(value: unknown): value is Schema {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'domain' in value &&
+    'classes' in value &&
+    'interfaces' in value
+  )
+}
+
+/** One node by path — live, suspense-first; `null` ref is idle (§1.3). */
+function useNodeUntyped(ref: PathLike | null | undefined, opts?: ReadOptions): NodeResult {
+  const r = useRead(ref, opts)
+  return useMemo(
+    () => ({
+      pending: r.pending,
+      error: r.error,
+      live: r.live,
+      seq: r.seq,
+      refetch: r.refetch,
+      node: r.first,
+    }),
+    [r],
+  )
+}
+
+/** Typed: one node bound under `schema` as `type`. */
+export function useNode<S extends Schema, T extends TypeNames<S>>(
+  schema: S,
+  type: T,
+  ref: NodeRefInput | null | undefined,
+  opts?: ReadOptions,
+): TypedNodeResult<S, T>
+/** Untyped: one node by ref — `null` ref is idle (§1.3). */
+export function useNode(ref: PathLike | null | undefined, opts?: ReadOptions): NodeResult
+// The implementation signature returns an erased supertype of both result
+// shapes — every overload above is assignable to it regardless of `BoundNode`
+// variance; callers only ever see the precise overload return types.
+export function useNode(
+  a: unknown,
+  b?: unknown,
+  c?: unknown,
+  d?: unknown,
+): ReadState & { readonly node: unknown } {
+  if (isSchema(a)) {
+    return useNodeTyped(
+      a,
+      b as string,
+      c as NodeRefInput | null | undefined,
+      d as ReadOptions | undefined,
+    )
+  }
+  return useNodeUntyped(a as PathLike | null | undefined, b as ReadOptions | undefined)
+}

package/src/graph/query/query.hook.ts

@@ -0,0 +1,42 @@
+import type { GatherBuilder, QueryASTInput, QuerySource } from '@astrale-os/kernel-client/graph'
+
+/**
+ * useQuery (API §5) — a structured read: a builder callback or an AST value;
+ * `null` is idle (§1.3). Rides the §1 envelope over the shared memory, projecting
+ * roots/first/nodes and the gathered-alias arms.
+ */
+import { useMemo } from 'react'
+
+import type { ReadState, Node, ReadOptions, Windowed } from '../memory/read/envelope'
+
+import { useRead } from '../memory/read/read'
+
+export interface QueryResult extends ReadState, Windowed {
+  readonly nodes: readonly Node[]
+  readonly roots: readonly Node[]
+  readonly first: Node | null
+  gathered(alias: string): { readonly nodes: readonly Node[]; readonly first: Node | null }
+}
+
+/** A structured read — builder callback or AST value; `null` is idle (§1.3). */
+export function useQuery(
+  build: ((q: QuerySource) => GatherBuilder) | QueryASTInput | null | undefined,
+  opts?: ReadOptions,
+): QueryResult {
+  const r = useRead(build ?? null, opts)
+  return useMemo(
+    () => ({
+      pending: r.pending,
+      error: r.error,
+      live: r.live,
+      seq: r.seq,
+      refetch: r.refetch,
+      nodes: r.nodes,
+      roots: r.roots,
+      first: r.first,
+      gathered: r.gathered,
+      more: r.more,
+    }),
+    [r],
+  )
+}

package/src/index.ts

@@ -0,0 +1,202 @@
+/**
+ * @astrale-os/shell-react — the React face of the shell (SHELL_REACT_API.md §0).
+ * One package, one import surface (SPEC §4.2); the bounded-context directories are
+ * the module structure, not subpaths. This public barrel composes the context
+ * barrels. Settled naming (§0): useKernelClient = the raw handle (session);
+ * useKernel() = the TYPED kernel (schema, no arg); useDomain(schema) = a typed
+ * domain binding. `useNode`/`useChildren` are single overloaded symbols (untyped
+ * floor + typed overloads) exported from the graph plane.
+ */
+
+// ─── session (§2 provider + §3) ──────────────────────────────────────────────
+export { ShellProvider } from './session'
+export type { ShellError, ShellProviderProps } from './session'
+export { useConnection, useKernelClient, useKernelInstance, useShell } from './session'
+export type { KernelInstance } from './session'
+
+// ─── auth (§4) ───────────────────────────────────────────────────────────────
+export { ActAs, useAuth, useCan, useSelf } from './auth'
+export type { ActAsProps } from './auth'
+
+// ─── graph — the untyped floor + writes + dispatch (§5, §7) ──────────────────
+// `useNode`/`useChildren` are single symbols merging the untyped floor + typed
+// overloads.
+export {
+  useCall,
+  useChildren,
+  useGraph,
+  useMove,
+  useMutate,
+  useNode,
+  useQuery,
+  useStream,
+} from './graph'
+export type {
+  ChildrenOptions,
+  ChildrenResult,
+  GraphMemory,
+  MoveAction,
+  Node,
+  NodeResult,
+  QueryResult,
+  ShapeInput,
+  UseMutateOptions,
+} from './graph'
+export type { CallOptions, StreamHandle, StreamOptions } from './graph'
+
+// ─── schema — the typed substrate (§6) ───────────────────────────────────────
+export { useDomain, useFunction, useIn, useKernel, useMethod, useOut } from './schema'
+export type { FunctionOptions } from './schema'
+export type { MethodOptions } from './schema'
+export type {
+  AutoMethodAction,
+  BoundMethodAction,
+  EndpointResult,
+  FunctionNames,
+  FunctionParams,
+  FunctionResult,
+  MethodIsStatic,
+  MethodNames,
+  MethodParams,
+  MethodResult,
+  TargetedMethodAction,
+  TypedChildrenResult,
+  TypedNodeResult,
+} from './schema'
+
+// ─── navigation (§8) ─────────────────────────────────────────────────────────
+export {
+  Link,
+  NavScope,
+  memoryAdapter,
+  urlAdapter,
+  useAncestors,
+  useLocation,
+  useNavScope,
+  useNavigate,
+} from './navigation'
+export type {
+  LinkProps,
+  MissingPolicy,
+  NavAdapter,
+  NavLocation,
+  NavScopeHandle,
+  NavScopeProps,
+  NavSnapshot,
+  NavTarget,
+  Navigate,
+  SerializedLocation,
+} from './navigation'
+
+// ─── selection (§9) ──────────────────────────────────────────────────────────
+export { SelectionScope, useSelection } from './selection'
+export type { Selection, SelectionScopeProps } from './selection'
+
+// ─── window (§10) ────────────────────────────────────────────────────────────
+export {
+  useCloseGuard,
+  useTargetNode,
+  useViewsFor,
+  useWindow,
+  useWindowList,
+  useWindows,
+  ViewHost,
+  ViewStage,
+} from './window'
+export type {
+  CloseGuard,
+  CloseVerdict,
+  ViewDescriptor,
+  ViewHostProps,
+  ViewSource,
+  ViewHostHandle,
+  ViewsForResult,
+  WindowListEntry,
+  WindowState,
+  WindowView,
+} from './window'
+
+// ─── intents (§11) ───────────────────────────────────────────────────────────
+export { useIntent, useSendIntent } from './intents'
+export type { IntentCtx, IntentPayload, IntentReply, SendIntent } from './intents'
+
+// ─── application — the OS plane (§12) ────────────────────────────────────────
+export {
+  AppHost,
+  AppLogo,
+  useApps,
+  useCurrentSpace,
+  useOpenApp,
+  useRoles,
+  useSpace,
+  useSpaces,
+  useUser,
+} from './application'
+export type {
+  AppHostFallbackState,
+  AppHostProps,
+  AppLogoProps,
+  AppsResult,
+  CurrentSpaceResult,
+  RolesResult,
+  SpaceResult,
+  SpacesResult,
+} from './application'
+// OS node/session types (from the shell package, single import surface).
+export type { ApplicationNode, AppSession, RoleNode, SpaceNode, UserNode } from '@astrale-os/shell'
+
+// ─── shared envelopes (§1) ───────────────────────────────────────────────────
+export type { Action, ReadState, ReadOptions, Windowed } from './graph'
+
+// ─── error taxonomy (§1.4) — guards + classes, re-exported from kernel-client ─
+export * from './graph/guards.error'
+
+// ─── re-exported kernel-client types (one import surface, §0 preamble) ───────
+export {
+  DESCRIPTION_KEY,
+  NAME_KEY,
+  STATUS_KEY,
+  descriptionOf,
+  nameOf,
+  normalizeRef,
+  statusOf,
+} from '@astrale-os/kernel-client'
+export type {
+  AnyBoundNode,
+  BoundNode,
+  CreatableClassNames,
+  CreateProps,
+  CredentialInput,
+  DefOf,
+  EdgeNames,
+  EndpointsOf,
+  FnMap,
+  NamedNodeLike,
+  NodeRefInput,
+  SchemaBoundView,
+  TypeNames,
+} from '@astrale-os/kernel-client'
+export type {
+  EdgeIdentity,
+  GatherBuilder,
+  OrderInput,
+  PatchBuilder,
+  PatchInput,
+  PathLike,
+  Properties,
+  QueryASTInput,
+  QuerySource,
+} from '@astrale-os/kernel-client/graph'
+export type { AuthApi, Perms } from '@astrale-os/kernel-client/auth'
+export type { Schema } from '@astrale-os/kernel-dsl'
+
+// ─── re-exported shell types (one import surface, SPEC §4.2) ──────────────────
+export type {
+  CloseResult,
+  KernelClient,
+  MountCredential,
+  Shell,
+  ShellConfig,
+  Window,
+} from '@astrale-os/shell'
+export type { IntentRegistry } from '@astrale-os/shell'

package/src/intents/envelope.ts

@@ -0,0 +1,52 @@
+/**
+ * Intent envelope construction (API §11). The typed payload/reply projections of
+ * a registry entry, the wire constants, and `intentMessage` — the single builder
+ * both directions (send + reply) share.
+ */
+import type { IntentMessage, IntentRegistry } from '@astrale-os/shell'
+
+/**
+ * Payload of a registry entry: the `{ payload }` field for the wrapped shape,
+ * else the whole entry (a legacy bare-payload augmentation). Robust to both, so
+ * bare augmentations keep compiling unchanged.
+ */
+export type IntentPayload<K extends keyof IntentRegistry> = IntentRegistry[K] extends {
+  payload: infer P
+}
+  ? P
+  : IntentRegistry[K]
+
+/**
+ * Reply of a registry entry: the `{ reply }` field when declared, else `void`
+ * (bare-payload and today's reply-less entries — forward-compatible with G4).
+ */
+export type IntentReply<K extends keyof IntentRegistry> = IntentRegistry[K] extends {
+  reply: infer R
+}
+  ? R
+  : void
+
+/** Sentinel `ctx.sender` carries for a parent-delivered intent (the shell stamps it). */
+export const PARENT_SENDER = '<parent>'
+/** Outbound `sender.windowId`; the receiver re-stamps it with the trusted id. */
+const SELF_SENDER = 'self'
+/** Correlated-reply channel name (the shell's fire-and-forget reply protocol). */
+export const INTENT_REPLY = 'intentReply'
+export const NOOP = (): void => {}
+
+/**
+ * Build an intent wire message. Bare-vs-wrapped payload variance (§11 pin) is
+ * erased on the wire — the receiver reads `envelope.payload` verbatim; the cast
+ * bridges the correlated name↔payload the union type cannot express.
+ */
+export function intentMessage(
+  name: string,
+  payload: unknown,
+  correlationId?: string,
+): IntentMessage {
+  return {
+    type: 'intent',
+    version: 1,
+    envelope: { name, payload, sender: { windowId: SELF_SENDER }, correlationId },
+  } as IntentMessage
+}

package/src/intents/index.ts

@@ -0,0 +1,6 @@
+// intents — API §11 (useIntent, useSendIntent). See SHELL_REACT_API.md.
+export { useIntent } from './listen-intent.hook'
+export type { IntentCtx } from './listen-intent.hook'
+export { useSendIntent } from './send-intent.hook'
+export type { SendIntent } from './send-intent.hook'
+export type { IntentPayload, IntentReply } from './envelope'

package/src/intents/listen-intent.hook.ts

@@ -0,0 +1,92 @@
+import type { IntentMessage, IntentRegistry } from '@astrale-os/shell'
+
+/**
+ * useIntent (API §11) — subscribe ONE handler to inbound intents (post-middleware,
+ * via shell.onIntent) with the REAL sender windowId and an exactly-once,
+ * unmount-safe `ctx.reply`. The subscription identity is independent of the
+ * handler closure (latest-handler ref), so re-renders never re-register. Reply
+ * obligations are tracked per sender window so a child close drops ours before a
+ * late async handler can aim a reply at a gone counterparty.
+ */
+import { useEffect, useRef } from 'react'
+
+import type { IntentPayload, IntentReply } from './envelope'
+
+import { useShell } from '../session/shell.hook'
+import { NOOP } from './envelope'
+import { sendReply } from './reply'
+
+/** Delivery context passed alongside an inbound intent's payload. */
+export interface IntentCtx<K extends keyof IntentRegistry> {
+  /** REAL source windowId; the `'<parent>'` sentinel for a parent-delivered intent. */
+  readonly sender: string
+  /** Reply to the sender's pending request — exactly-once; dropped if it died. */
+  reply(result: IntentReply<K>): void
+}
+
+/**
+ * Subscribe `handler` to inbound `name` intents. `ctx.sender` is the REAL
+ * windowId (the channel-authenticated id, or `'<parent>'` upstream); `ctx.reply`
+ * answers a correlated request once.
+ */
+export function useIntent<K extends keyof IntentRegistry>(
+  name: K,
+  handler: (payload: IntentPayload<K>, ctx: IntentCtx<K>) => void | Promise<void>,
+): void {
+  const shell = useShell()
+  const handlerRef = useRef(handler)
+  handlerRef.current = handler
+
+  useEffect(() => {
+    let alive = true
+    // Open reply obligations by sender window, so a child close drops ours
+    // before a late async handler can aim a reply at a gone counterparty.
+    const bySender = new Map<string, Set<() => void>>()
+    const track = (sender: string, drop: () => void): (() => void) => {
+      let set = bySender.get(sender)
+      if (set === undefined) {
+        set = new Set()
+        bySender.set(sender, set)
+      }
+      set.add(drop)
+      return () => set.delete(drop)
+    }
+    const offClose = shell.children.onClose((windowId) => {
+      const set = bySender.get(windowId)
+      if (set === undefined) return
+      for (const drop of set) drop()
+      bySender.delete(windowId)
+    })
+
+    const off = shell.onIntent(name, (message: IntentMessage<K>) => {
+      const { payload, correlationId } = message.envelope
+      const sender = message.envelope.sender.windowId
+      let settled = false
+      const untrack =
+        correlationId === undefined
+          ? NOOP
+          : track(sender, () => {
+              settled = true
+            })
+      const ctx: IntentCtx<K> = {
+        sender,
+        reply(result) {
+          if (settled || !alive) return
+          settled = true
+          untrack()
+          if (correlationId === undefined) return
+          sendReply(shell, sender, correlationId, result)
+        },
+      }
+      void Promise.resolve(handlerRef.current(payload as IntentPayload<K>, ctx))
+        .catch(NOOP)
+        .finally(untrack)
+    })
+
+    return () => {
+      alive = false
+      off()
+      offClose()
+    }
+  }, [shell, name])
+}

package/src/intents/reply.ts

@@ -0,0 +1,24 @@
+/**
+ * Reply delivery (API §11) — route a correlated reply to whichever channel the
+ * request arrived on (parent vs a child window). Best-effort: a gone counterparty
+ * drops the reply safely (counterparty-death cleanup).
+ */
+import type { Shell } from '@astrale-os/shell'
+
+import { INTENT_REPLY, PARENT_SENDER, intentMessage } from './envelope'
+
+/** Deliver a reply to whichever channel the request arrived on. Best-effort. */
+export function sendReply(
+  shell: Shell,
+  sender: string,
+  correlationId: string,
+  result: unknown,
+): void {
+  const message = intentMessage(INTENT_REPLY, { correlationId, result })
+  try {
+    if (sender === PARENT_SENDER) shell.parent?.send(message)
+    else shell.children.send(sender, message) // no-op if the child has detached
+  } catch {
+    // Counterparty gone — the reply is safely dropped.
+  }
+}