@astrale-os/shell-react 0.1.0

package/src/auth/can.hook.ts

@@ -0,0 +1,149 @@
+import type { AuthApi, Perms } from '@astrale-os/kernel-client/auth'
+import type { PathLike, Ref } from '@astrale-os/kernel-client/graph'
+
+import { rawOf } from '@astrale-os/kernel-client/graph'
+/**
+ * useCan (API §4) — deduped standing-grant permission checks. `auth.check`-backed:
+ * `undefined` while the first check is in flight (or `on` is idle), then a boolean.
+ * Deduped per (principal, perms, nodeId) across the whole tree via the principal's
+ * check ledger (folded in here as the dedup substrate). Standing-grant semantics:
+ * the dispatched call remains the gatekeeper — this is a UI affordance, not the
+ * enforcement point (SPEC §6.2). A local grant/revoke invalidates the ledger.
+ */
+import { useCallback, useMemo, useSyncExternalStore } from 'react'
+
+import type { NodeValue, SessionView } from './act-as.context'
+
+import { isIdleInput } from '../graph/memory/read/idle'
+import { useIdentityBinding } from './act-as.context'
+
+const NOOP_UNSUB = (): void => undefined
+
+/** A node value carries the id/class/path triple (mirrors the memory's `isNodeValue`). */
+export function isNodeValue(x: unknown): x is NodeValue {
+  return typeof x === 'object' && x !== null && 'id' in x && 'class' in x && 'path' in x
+}
+
+/** Normalize a `useCan` subject to a dispatchable `Ref` plus a stable dedup key. */
+export function toRef(on: NodeValue | PathLike): { ref: Ref; key: string } {
+  if (isNodeValue(on)) return { ref: on.path as Ref, key: `@${on.id}` }
+  return { ref: on, key: rawOf(on) }
+}
+
+// ── check ledger (the dedup substrate) ───────────────────────────────────────
+
+/** One deduped check — its last-known value plus the subscribers watching it. */
+class CheckCell {
+  value: boolean | undefined = undefined
+  private inFlight = false
+  private readonly listeners = new Set<() => void>()
+
+  constructor(
+    private readonly auth: AuthApi,
+    private readonly perms: Perms,
+    private readonly on: Ref,
+  ) {}
+
+  subscribe = (onChange: () => void): (() => void) => {
+    this.listeners.add(onChange)
+    this.ensure()
+    return () => this.listeners.delete(onChange)
+  }
+
+  getSnapshot = (): boolean | undefined => this.value
+
+  /** Run the check once when the value is unknown and nothing is in flight. */
+  ensure(): void {
+    if (this.value !== undefined || this.inFlight) return
+    this.run()
+  }
+
+  /** Force a re-check (local grant/revoke on this principal). */
+  invalidate(): void {
+    if (this.listeners.size === 0) {
+      this.value = undefined // recompute lazily on the next subscribe
+      return
+    }
+    this.run()
+  }
+
+  private run(): void {
+    this.inFlight = true
+    void this.auth
+      .check({ on: this.on, perms: this.perms })
+      .then(
+        (ok) => {
+          this.value = ok
+        },
+        () => {
+          // A failed check leaves the value unknown (undefined) — never a false grant.
+          this.value = undefined
+        },
+      )
+      .finally(() => {
+        this.inFlight = false
+        for (const l of this.listeners) l()
+      })
+  }
+}
+
+/** Per-principal cell registry — dedup across the whole tree for one kernel handle. */
+export class CheckLedger {
+  private readonly cells = new Map<string, CheckCell>()
+
+  constructor(private readonly auth: AuthApi) {}
+
+  cell(key: string, perms: Perms, on: Ref): CheckCell {
+    let cell = this.cells.get(key)
+    if (cell === undefined) {
+      cell = new CheckCell(this.auth, perms, on)
+      this.cells.set(key, cell)
+    }
+    return cell
+  }
+
+  /** Re-check every observed cell — conservative Tier-0 sweep after a local grant/revoke. */
+  invalidateAll(): void {
+    for (const cell of this.cells.values()) cell.invalidate()
+  }
+}
+
+// One ledger per bound kernel object → per principal. `session.as(cred)` mints a
+// fresh view per ActAs, so acted-as principals never share a ledger with the root.
+const ledgers = new WeakMap<SessionView, CheckLedger>()
+
+export function ledgerFor(kernel: SessionView): CheckLedger {
+  let ledger = ledgers.get(kernel)
+  if (ledger === undefined) {
+    ledger = new CheckLedger(kernel.auth)
+    ledgers.set(kernel, ledger)
+  }
+  return ledger
+}
+
+// ── useCan ────────────────────────────────────────────────────────────────────
+
+export function useCan(
+  perms: Perms,
+  on: NodeValue | PathLike | null | undefined,
+): boolean | undefined {
+  const binding = useIdentityBinding()
+  const ref = isIdleInput(on) ? null : toRef(on)
+
+  // The shared cell for (principal, perms, nodeId): identical to every other
+  // useCan reading the same triple, so one check serves the whole tree.
+  const cell = useMemo(
+    () =>
+      ref === null ? null : ledgerFor(binding.kernel).cell(`${perms}\0${ref.key}`, perms, ref.ref),
+    // ref is rebuilt per render; its `key` string is the stable identity.
+    [binding.kernel, perms, ref?.key],
+  )
+
+  const subscribe = useCallback(
+    (onChange: () => void) => (cell === null ? NOOP_UNSUB : cell.subscribe(onChange)),
+    [cell],
+  )
+  const getSnapshot = useCallback((): boolean | undefined => cell?.getSnapshot(), [cell])
+
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+}

package/src/auth/index.ts

@@ -0,0 +1,6 @@
+// auth — API §4 (useSelf, useCan, useAuth, ActAs). See SHELL_REACT_API.md.
+export { ActAs } from './act-as.context'
+export type { ActAsProps } from './act-as.context'
+export { useAuth } from './auth.hook'
+export { useCan } from './can.hook'
+export { useSelf } from './self.hook'

package/src/auth/self.hook.ts

@@ -0,0 +1,14 @@
+import type { NodeValue } from './act-as.context'
+
+/**
+ * useSelf (API §4) — the caller's identity node, resolved at boot and read
+ * synchronously (never suspends). An <ActAs> subtree returns the acted-as
+ * identity. FLAG: today this is the boot-resolved whoami snapshot; it becomes a
+ * live memory shape once the graph plane subscribes the self node — no signature
+ * change.
+ */
+import { useIdentityBinding } from './act-as.context'
+
+export function useSelf(): NodeValue {
+  return useIdentityBinding().self
+}

package/src/auth/session-kernel.ts

@@ -0,0 +1,24 @@
+/**
+ * useSessionKernel (API §4) — the dispatch-floor resolver. Inside an `<ActAs>` it
+ * is the acted-as principal's bound session view; otherwise the root
+ * `shell.kernel`. Every dispatch floor (schema bindings, useCall/useStream, useMove,
+ * typed method dispatch) routes through this so a call runs as the subtree's
+ * principal — not the root — and its scoped memory.
+ */
+import { useContext } from 'react'
+
+import type { SessionView } from './act-as.context'
+
+import { ShellContext } from '../session/session.context'
+import { IdentityContext } from './act-as.context'
+
+/** The EFFECTIVE dispatch kernel for this subtree. Throws outside a provider. */
+export function useSessionKernel(): SessionView {
+  const binding = useContext(IdentityContext)
+  const runtime = useContext(ShellContext)
+  if (binding !== null) return binding.kernel
+  if (runtime === null) {
+    throw new Error('session hooks must be used within a <ShellProvider>')
+  }
+  return runtime.shell.kernel
+}

package/src/graph/action.ts

@@ -0,0 +1,127 @@
+/**
+ * The Action envelope (API §1.2) — a graph-plane primitive, not a context (rule
+ * 5). Holds the `Action<A,R>` type (public — it appears in every write/dispatch
+ * hook signature) and the `useAction` stateful-callable factory (internal): a
+ * render-stable callable whose pending/error/result snapshot is re-stamped each
+ * render, safe in deps arrays.
+ */
+import { useCallback, useEffect, useReducer, useRef } from 'react'
+
+/** The stateful callable every write/dispatch hook returns. */
+export interface Action<A extends unknown[], R> {
+  /** Invoke; rejects on failure AND records it on `.error`. */
+  (...args: A): Promise<R>
+  /** ≥1 invocation in flight (the OR across concurrent calls). */
+  readonly pending: boolean
+  /** Last rejection; cleared when the next invocation starts. */
+  readonly error: unknown
+  /** Last successful resolution. */
+  readonly result: R | undefined
+  /** Clears error/result. */
+  reset(): void
+}
+
+/** Same shape, minus `readonly`, so the render step can stamp the snapshot on. */
+interface MutableAction<A extends unknown[], R> {
+  (...args: A): Promise<R>
+  pending: boolean
+  error: unknown
+  result: R | undefined
+  reset(): void
+}
+
+interface ActionSnapshot<R> {
+  readonly pending: boolean
+  readonly error: unknown
+  readonly result: R | undefined
+}
+
+const IDLE_SNAPSHOT: ActionSnapshot<unknown> = {
+  pending: false,
+  error: undefined,
+  result: undefined,
+}
+
+type ActionEvent<R> =
+  | { readonly type: 'start' }
+  | { readonly type: 'resolve'; readonly value: R; readonly inFlight: number }
+  | { readonly type: 'reject'; readonly error: unknown; readonly inFlight: number }
+  | { readonly type: 'reset' }
+
+function actionReducer<R>(state: ActionSnapshot<R>, event: ActionEvent<R>): ActionSnapshot<R> {
+  switch (event.type) {
+    case 'start':
+      // §1.2: a new invocation clears the error and keeps the last result.
+      return { pending: true, error: undefined, result: state.result }
+    case 'resolve':
+      // Latest settlement wins: a success records the result and clears error.
+      return { pending: event.inFlight > 0, error: undefined, result: event.value }
+    case 'reject':
+      return { pending: event.inFlight > 0, error: event.error, result: state.result }
+    case 'reset':
+      return { pending: state.pending, error: undefined, result: undefined }
+  }
+}
+
+/**
+ * Wrap an async function in the Action envelope. Concurrent invocations are
+ * allowed — each returns its own promise; `pending` is the OR of the in-flight
+ * count and `result`/`error` reflect the latest settlement. The callable keeps
+ * ONE identity for the hook's lifetime (safe in deps arrays); its snapshot
+ * fields are re-stamped each render, so reads stay current across settlements.
+ */
+export function useAction<A extends unknown[], R>(fn: (...args: A) => Promise<R>): Action<A, R> {
+  // Latest-closure ref so the stable callable always dispatches the current fn.
+  const fnRef = useRef(fn)
+  fnRef.current = fn
+
+  const [snapshot, dispatch] = useReducer(actionReducer<R>, IDLE_SNAPSHOT as ActionSnapshot<R>)
+  const inFlight = useRef(0)
+  const alive = useRef(true)
+  useEffect(() => {
+    alive.current = true
+    return () => {
+      alive.current = false
+    }
+  }, [])
+
+  const call = useCallback((...args: A): Promise<R> => {
+    inFlight.current += 1
+    dispatch({ type: 'start' })
+    let promise: Promise<R>
+    try {
+      promise = Promise.resolve(fnRef.current(...args))
+    } catch (err) {
+      promise = Promise.reject(err)
+    }
+    void promise.then(
+      (value) => {
+        inFlight.current -= 1
+        if (alive.current) dispatch({ type: 'resolve', value, inFlight: inFlight.current })
+      },
+      (err: unknown) => {
+        inFlight.current -= 1
+        if (alive.current) dispatch({ type: 'reject', error: err, inFlight: inFlight.current })
+      },
+    )
+    return promise
+  }, [])
+
+  const reset = useCallback(() => dispatch({ type: 'reset' }), [])
+
+  // One render-stable callable: built once (call/reset are themselves stable),
+  // then its snapshot fields re-stamped every render. Re-renders are driven by
+  // the reducer, so the stamped pending/error/result stay fresh WITHOUT minting
+  // a new function identity — the documented "safe in deps arrays" guarantee.
+  const actionRef = useRef<MutableAction<A, R> | null>(null)
+  if (actionRef.current === null) {
+    const action = ((...args: A) => call(...args)) as MutableAction<A, R>
+    action.reset = reset
+    actionRef.current = action
+  }
+  const action = actionRef.current
+  action.pending = snapshot.pending
+  action.error = snapshot.error
+  action.result = snapshot.result
+  return action as Action<A, R>
+}

package/src/graph/async.ts

@@ -0,0 +1,87 @@
+/**
+ * useAsyncResource (API §1.1) — a one-shot async read projected into the §1 read
+ * envelope (`ReadState`): the non-memory sibling of `useRead`, stale-guarded and
+ * `refetch`-able, with a `null` loader as idle. Shared by `application/` and the
+ * window `useViewsFor` dispatch; homed here (below both) to keep rule 9 acyclic.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+
+import type { ReadState } from './memory/read/envelope'
+
+export interface AsyncResource<T> extends ReadState {
+  readonly data: T
+}
+
+interface AsyncState<T> {
+  readonly data: T
+  readonly pending: boolean
+  readonly error: unknown
+}
+
+/**
+ * Subscribe a component to `load()`. `null` loader → idle. The loader runs on
+ * mount and whenever `deps` change (stale responses discarded); last-good data is
+ * retained through a pending refetch or a failure (§1.1).
+ */
+export function useAsyncResource<T>(
+  load: (() => Promise<T>) | null,
+  empty: T,
+  deps: readonly unknown[],
+): AsyncResource<T> {
+  const [state, setState] = useState<AsyncState<T>>({
+    data: empty,
+    pending: load !== null,
+    error: undefined,
+  })
+
+  const loadRef = useRef(load)
+  loadRef.current = load
+  const emptyRef = useRef(empty)
+  emptyRef.current = empty
+  const seq = useRef(0)
+  const alive = useRef(true)
+  useEffect(() => {
+    alive.current = true
+    return () => {
+      alive.current = false
+    }
+  }, [])
+
+  const refetch = useCallback((): Promise<void> => {
+    const run = loadRef.current
+    if (run === null) {
+      setState({ data: emptyRef.current, pending: false, error: undefined })
+      return Promise.resolve()
+    }
+    const my = ++seq.current
+    setState((s) => ({ data: s.data, pending: true, error: undefined }))
+    return run().then(
+      (data) => {
+        if (alive.current && my === seq.current)
+          setState({ data, pending: false, error: undefined })
+      },
+      (error: unknown) => {
+        if (alive.current && my === seq.current) {
+          setState((s) => ({ data: s.data, pending: false, error }))
+        }
+      },
+    )
+  }, [])
+
+  useEffect(() => {
+    void refetch()
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, deps)
+
+  return useMemo(
+    () => ({
+      data: state.data,
+      pending: state.pending,
+      error: state.error,
+      live: false,
+      seq: 0,
+      refetch,
+    }),
+    [state.data, state.pending, state.error, refetch],
+  )
+}

package/src/graph/call/call.hook.ts

@@ -0,0 +1,42 @@
+/**
+ * useCall (API §7) — unary domain-function dispatch over `kernel.call`, in the
+ * Action envelope. No result caching, no liveness — domain function reads are not
+ * structurally invalidatable (FRONTEND §5.7); a consumer that needs freshness
+ * owns its own refetch policy. Dispatch is a graph operation (rule 2).
+ */
+import type { CallFns, FnMap } from '@astrale-os/kernel-client'
+
+import type { Action } from '../action'
+
+import { useSessionKernel } from '../../auth/session-kernel'
+import { useAction } from '../action'
+
+export interface CallOptions {
+  /** Per-call timeout (ms), forwarded to the kernel dispatch. */
+  timeout?: number
+  /** Side-channel notified on rejection (the Action also records `.error`). */
+  onError?(error: unknown): void
+}
+
+/**
+ * Unary domain-function dispatch as an {@link Action}. `method` is a typed FnMap
+ * `call` path or any string (the untyped floor); `null` yields an idle action
+ * that rejects if invoked. Params/result are typed from the FnMap entry.
+ */
+export function useCall<K extends CallFns<FnMap>>(
+  method: K | null,
+  opts?: CallOptions,
+): Action<[FnMap[K]['params']], FnMap[K]['result']> {
+  const kernel = useSessionKernel()
+  // A fresh closure per render captures the current method/opts; `useAction`
+  // keeps ONE stable callable and always dispatches this latest closure.
+  return useAction(async (params: FnMap[K]['params']): Promise<FnMap[K]['result']> => {
+    if (method === null) throw new Error('useCall: method is null (idle action invoked)')
+    try {
+      return await kernel.call(method, params, { timeout: opts?.timeout })
+    } catch (error) {
+      opts?.onError?.(error)
+      throw error
+    }
+  })
+}

package/src/graph/call/stream.hook.ts

@@ -0,0 +1,200 @@
+import type { FnMap, StreamFns } from '@astrale-os/kernel-client'
+
+/**
+ * useStream (API §7) — streaming domain-function dispatch over `kernel.stream`,
+ * an AsyncIterable driven by an explicit start/cancel handle. A superseding
+ * `start` (or unmount) closes the prior run and discards its late chunks/errors;
+ * never live. Dispatch is a graph operation (rule 2).
+ */
+import { useCallback, useEffect, useReducer, useRef } from 'react'
+
+import { useSessionKernel } from '../../auth/session-kernel'
+
+export interface StreamOptions<T> {
+  /** Notified per chunk as it arrives (in addition to `chunks` accumulation). */
+  onChunk?(chunk: T): void
+}
+
+export interface StreamHandle<T> {
+  /** Begin a run: resets chunks, then resolves when the stream ends / rejects on failure. */
+  start(params: unknown): Promise<void>
+  /** Chunks accumulated in the current run; reset on the next `start`. */
+  readonly chunks: readonly T[]
+  /** The most recent chunk, or null before the first. */
+  readonly last: T | null
+  /** A run is in flight. */
+  readonly streaming: boolean
+  /** Last run failure; retained until the next `start`. */
+  readonly error: unknown
+  /** Close the stream (returns the iterator); a later `start` begins fresh. */
+  cancel(): void
+}
+
+interface StreamSnapshot<T> {
+  readonly chunks: readonly T[]
+  readonly last: T | null
+  readonly streaming: boolean
+  readonly error: unknown
+}
+
+const IDLE_STREAM: StreamSnapshot<unknown> = {
+  chunks: [],
+  last: null,
+  streaming: false,
+  error: undefined,
+}
+
+type StreamEvent<T> =
+  | { readonly type: 'start' }
+  | { readonly type: 'chunk'; readonly value: T }
+  | { readonly type: 'end' }
+  | { readonly type: 'error'; readonly error: unknown }
+  | { readonly type: 'cancel' }
+
+function streamReducer<T>(state: StreamSnapshot<T>, event: StreamEvent<T>): StreamSnapshot<T> {
+  switch (event.type) {
+    case 'start':
+      return { chunks: [], last: null, streaming: true, error: undefined }
+    case 'chunk':
+      return {
+        chunks: [...state.chunks, event.value],
+        last: event.value,
+        streaming: true,
+        error: undefined,
+      }
+    case 'end':
+      return { ...state, streaming: false }
+    case 'error':
+      // Chunks accumulated before the failure are preserved.
+      return { ...state, streaming: false, error: event.error }
+    case 'cancel':
+      return { ...state, streaming: false }
+  }
+}
+
+/** Same shape, minus `readonly`, so the render step can re-stamp the snapshot. */
+interface MutableStreamHandle<T> {
+  start(params: unknown): Promise<void>
+  chunks: readonly T[]
+  last: T | null
+  streaming: boolean
+  error: unknown
+  cancel(): void
+}
+
+interface StreamRun<T> {
+  readonly controller: AbortController
+  iterator: AsyncIterator<T> | null
+}
+
+/**
+ * Streaming domain-function dispatch. `start(params)` opens a run over
+ * `kernel.stream`; chunks accumulate on `chunks`; `cancel()` closes the iterator
+ * and a later `start` begins fresh. A superseding `start` (or unmount) closes the
+ * prior run and discards its late chunks/errors — only the current run drives
+ * state. Never live; the handle keeps one identity for the hook's lifetime.
+ */
+export function useStream<K extends StreamFns<FnMap>>(
+  method: K | null,
+  opts?: StreamOptions<FnMap[K]['result']>,
+): StreamHandle<FnMap[K]['result']> {
+  type T = FnMap[K]['result']
+  const kernel = useSessionKernel()
+
+  // Latest-closure refs so the stable start/cancel dispatch the current inputs.
+  const kernelRef = useRef(kernel)
+  kernelRef.current = kernel
+  const methodRef = useRef(method)
+  methodRef.current = method
+  const optsRef = useRef(opts)
+  optsRef.current = opts
+
+  const [snapshot, dispatch] = useReducer(streamReducer<T>, IDLE_STREAM as StreamSnapshot<T>)
+
+  // `runId` supersession token; only the run whose id is still current drives state.
+  const runIdRef = useRef(0)
+  const currentRef = useRef<StreamRun<T> | null>(null)
+  const alive = useRef(true)
+
+  const stop = useCallback(() => {
+    const run = currentRef.current
+    if (run !== null) {
+      run.controller.abort()
+      void run.iterator?.return?.(undefined)
+      currentRef.current = null
+    }
+  }, [])
+
+  useEffect(() => {
+    alive.current = true
+    return () => {
+      alive.current = false
+      stop()
+    }
+  }, [stop])
+
+  const cancel = useCallback(() => {
+    runIdRef.current += 1
+    stop()
+    if (alive.current) dispatch({ type: 'cancel' })
+  }, [stop])
+
+  const start = useCallback(
+    (params: unknown): Promise<void> => {
+      const method_ = methodRef.current
+      if (method_ === null) {
+        return Promise.reject(new Error('useStream: method is null (idle handle started)'))
+      }
+      runIdRef.current += 1
+      const runId = runIdRef.current
+      stop() // close any prior run before opening the new one
+      dispatch({ type: 'start' })
+
+      const controller = new AbortController()
+      const run: StreamRun<T> = { controller, iterator: null }
+      currentRef.current = run
+      const current = (): boolean => runIdRef.current === runId
+
+      return (async () => {
+        try {
+          const iterable = await kernelRef.current.stream(method_, params, {
+            signal: controller.signal,
+          })
+          if (!current()) return
+          const iterator = iterable[Symbol.asyncIterator]()
+          run.iterator = iterator
+          for (;;) {
+            const next = await iterator.next()
+            if (!current()) return
+            if (next.done === true) break
+            if (alive.current) dispatch({ type: 'chunk', value: next.value })
+            optsRef.current?.onChunk?.(next.value)
+          }
+          if (current()) {
+            currentRef.current = null
+            if (alive.current) dispatch({ type: 'end' })
+          }
+        } catch (error) {
+          if (!current()) return // a superseded/cancelled run's failure is discarded
+          currentRef.current = null
+          if (alive.current) dispatch({ type: 'error', error })
+          throw error
+        }
+      })()
+    },
+    [stop],
+  )
+
+  // One render-stable handle: built once (start/cancel are stable), then its
+  // snapshot fields re-stamped each render so reads stay current across chunks.
+  const handleRef = useRef<MutableStreamHandle<T> | null>(null)
+  if (handleRef.current === null) {
+    handleRef.current = { start, cancel } as MutableStreamHandle<T>
+  }
+  const handle = handleRef.current
+  handle.chunks = snapshot.chunks
+  handle.last = snapshot.last
+  handle.streaming = snapshot.streaming
+  handle.error = snapshot.error
+  return handle as StreamHandle<T>
+}

package/src/graph/graph.context.ts

@@ -0,0 +1,14 @@
+import type { GraphMemory } from '@astrale-os/kernel-client/store'
+
+/**
+ * GraphContext (ex MemoryContext) — the root of the graph plane. Seats the base
+ * (default-scope) memory the provider builds; the SAME handle the graph/schema/
+ * nav hooks read through `memory/scope.ts`, and selection's liveness source.
+ * Under `<ActAs>` the read hooks re-scope via `forScope`; selection reads the
+ * base scope here.
+ */
+import { createContext } from 'react'
+
+export type { GraphMemory }
+export const GraphContext = createContext<GraphMemory | null>(null)
+GraphContext.displayName = 'AstraleGraphContext'