@astrale-os/shell-react 0.2.9 → 0.2.10-beta.3

package/src/components/astrale.tsx

@@ -0,0 +1,40 @@
+import type { Shell, ShellConfig } from '@astrale-os/shell'
+import type { ReactElement, ReactNode } from 'react'
+
+import { Suspense } from 'react'
+
+import type { ShellProviderProps } from '../session/provider.js'
+
+import { ShellProvider } from '../session/provider.js'
+import { ViewStage } from '../window/stage.js'
+import { defaultViewError, defaultViewLoading, ViewErrorBoundary } from './boundaries.js'
+
+const SANDBOXED_SHELL = Object.freeze({ mode: 'sandboxed' as const })
+
+export interface AstraleProps {
+  /** Defaults to the child-side sandbox handshake; pass a Shell for an embedded host or test. */
+  readonly config?: ShellConfig | Shell
+  readonly fallback?: ReactNode
+  readonly errorFallback?: ShellProviderProps['errorFallback']
+  readonly onError?: (error: unknown) => void
+  readonly children: ReactNode
+}
+
+/** Complete Astrale runtime root without taking ownership of application routing. */
+export function Astrale(props: AstraleProps): ReactElement {
+  const loading = props.fallback ?? defaultViewLoading()
+  const errorFallback = props.errorFallback ?? defaultViewError
+  return (
+    <ShellProvider
+      config={props.config ?? SANDBOXED_SHELL}
+      fallback={loading}
+      errorFallback={errorFallback}
+      onError={({ error }) => props.onError?.(error)}
+    >
+      <ViewErrorBoundary fallback={errorFallback} onError={props.onError}>
+        <Suspense fallback={loading}>{props.children}</Suspense>
+      </ViewErrorBoundary>
+      <ViewStage />
+    </ShellProvider>
+  )
+}

package/src/components/boundaries.tsx

@@ -0,0 +1,113 @@
+import type { CredentialSnapshot } from '@astrale-os/shell'
+import type { ReactElement, ReactNode } from 'react'
+
+import { Component, Fragment } from 'react'
+
+import type { GraphResource } from '../graph/resource.js'
+
+import { useConnection } from '../session/connection/connection.hook.js'
+
+export function ViewBoundary<T>(props: {
+  readonly resource: GraphResource<T>
+  readonly children: (value: T) => ReactNode
+  readonly loading?: ReactNode
+  readonly empty?: ReactNode
+  readonly error?: (error: unknown) => ReactNode
+}): ReactElement {
+  const { resource } = props
+  if (resource.state === 'failed') {
+    if (props.error !== undefined) return <>{props.error(resource.error)}</>
+    throw resource.error
+  }
+  if (resource.data === undefined) return <>{props.loading ?? null}</>
+  if (resource.data === null) return <>{props.empty ?? null}</>
+  return <>{props.children(resource.data)}</>
+}
+
+export const GraphBoundary = ViewBoundary
+
+export interface ViewErrorBoundaryProps {
+  /** A render function receives the retry generation and can recreate rejected lazy resources. */
+  readonly children: ReactNode | ((generation: number) => ReactNode)
+  readonly fallback?: (error: unknown, retry: () => void) => ReactNode
+  readonly onError?: (error: unknown) => void
+}
+
+/** Catch Shell View render/lazy failures and remount the failed subtree on explicit retry. */
+export class ViewErrorBoundary extends Component<
+  ViewErrorBoundaryProps,
+  { readonly error: unknown; readonly generation: number }
+> {
+  override state = { error: undefined as unknown, generation: 0 }
+
+  static getDerivedStateFromError(error: unknown) {
+    return { error }
+  }
+
+  override componentDidCatch(error: unknown): void {
+    this.props.onError?.(error)
+  }
+
+  private readonly retry = (): void => {
+    this.setState((state) => ({ error: undefined, generation: state.generation + 1 }))
+  }
+
+  override render(): ReactNode {
+    if (this.state.error !== undefined) {
+      return (
+        this.props.fallback?.(this.state.error, this.retry) ??
+        defaultViewError(this.state.error, this.retry)
+      )
+    }
+    const content =
+      typeof this.props.children === 'function'
+        ? this.props.children(this.state.generation)
+        : this.props.children
+    return <Fragment key={this.state.generation}>{content}</Fragment>
+  }
+}
+
+export function defaultViewLoading(): ReactElement {
+  return (
+    <div role="status" aria-live="polite">
+      Loading view…
+    </div>
+  )
+}
+
+export function defaultViewError(_error: unknown, retry: () => void): ReactElement {
+  return (
+    <section role="alert">
+      <p>View could not load.</p>
+      <button type="button" onClick={retry}>
+        Retry
+      </button>
+    </section>
+  )
+}
+
+export function ConnectionBoundary(props: {
+  readonly children: ReactNode
+  readonly fallback?: (status: ReturnType<typeof useConnection>) => ReactNode
+}): ReactElement {
+  const connection = useConnection()
+  return connection.status === 'ready' ? (
+    <>{props.children}</>
+  ) : (
+    <>{props.fallback?.(connection) ?? null}</>
+  )
+}
+
+export function CredentialBoundary(props: {
+  readonly credential: CredentialSnapshot
+  readonly children: ReactNode
+  readonly fallback?: (credential: CredentialSnapshot) => ReactNode
+}): ReactElement {
+  return props.credential.state === 'valid' ||
+    props.credential.state === 'refreshing' ||
+    props.credential.state === 'degraded' ? (
+    <>{props.children}</>
+  ) : (
+    <>{props.fallback?.(props.credential) ?? null}</>
+  )
+}

package/src/components/can.tsx

@@ -0,0 +1,16 @@
+import type { PathLike } from '@astrale-os/sdk/graph/path'
+import type { schema } from '@astrale-os/sdk/schema'
+import type { ReactElement, ReactNode } from 'react'
+
+import type { PolicyObject } from '../auth/can.hook.js'
+
+import { useCan } from '../auth/can.hook.js'
+
+export function Can(props: {
+  readonly policy: PathLike | schema.PolicyRef
+  readonly object: PolicyObject
+  readonly children: ReactNode
+  readonly fallback?: ReactNode
+}): ReactElement {
+  return <>{useCan(props.policy, props.object) === true ? props.children : props.fallback}</>
+}

package/src/components/index.ts

@@ -0,0 +1,13 @@
+export { Can } from './can.js'
+export {
+  ConnectionBoundary,
+  CredentialBoundary,
+  defaultViewError,
+  defaultViewLoading,
+  GraphBoundary,
+  ViewErrorBoundary,
+  ViewBoundary,
+} from './boundaries.js'
+export type { ViewErrorBoundaryProps } from './boundaries.js'
+export { Astrale } from './astrale.js'
+export type { AstraleProps } from './astrale.js'

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

@@ -1,41 +1,36 @@
-/**
- * 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 { Call } from '@astrale-os/kernel-client'
+import type { SessionRequestOptions } from '@astrale-os/kernel-client/session'
+import type { Value } from '@astrale-os/sdk/value'
 
 import type { Action } from '../action.js'
 
 import { useSessionKernel } from '../../auth/session-kernel.js'
 import { useAction } from '../action.js'
 
-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
+export interface CallOptions extends SessionRequestOptions {
+  readonly 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']> {
+export type CallResult = Value
+type CallAuthor<A extends unknown[]> = Call | ((...args: A) => Call)
+
+export function useCall(call: Call | null, options?: CallOptions): Action<[], CallResult>
+export function useCall<A extends unknown[]>(
+  author: ((...args: A) => Call) | null,
+  options?: CallOptions,
+): Action<A, CallResult>
+export function useCall<A extends unknown[]>(
+  author: CallAuthor<A> | null,
+  options?: CallOptions,
+): Action<A, CallResult> {
   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)')
+  return useAction(async (...args: A) => {
+    if (author === null) throw new Error('useCall: idle action invoked')
+    const call = typeof author === 'function' ? author(...args) : author
     try {
-      return await kernel.call(method, params, { timeout: opts?.timeout })
+      return await kernel.call(call, options)
     } catch (error) {
-      opts?.onError?.(error)
+      options?.onError?.(error)
       throw error
     }
   })

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

@@ -1,57 +1,44 @@
-import type { FnMap, StreamFns } from '@astrale-os/kernel-client'
+import type { Call } from '@astrale-os/kernel-client'
+import type { SessionRequestOptions } from '@astrale-os/kernel-client/session'
+import type { Value } from '@astrale-os/sdk/value'
+import type { KernelClient } from '@astrale-os/shell'
 
-/**
- * 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.js'
 
-export interface StreamOptions<T> {
-  /** Notified per chunk as it arrives (in addition to `chunks` accumulation). */
-  onChunk?(chunk: T): void
+export type KernelStream = Awaited<ReturnType<KernelClient['stream']>>
+export type StreamItem = Value
+export type CallAuthor<A extends unknown[]> = Call | ((...args: A) => Call)
+
+export interface StreamOptions<T = StreamItem> extends SessionRequestOptions {
+  readonly 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`. */
+export interface StreamHandle<A extends unknown[] = unknown[], T = StreamItem> {
+  start(...args: A): Promise<void>
   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> {
+interface Snapshot<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> =
+type Event<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> {
+function reducer<T>(state: Snapshot<T>, event: Event<T>): Snapshot<T> {
   switch (event.type) {
     case 'start':
       return { chunks: [], last: null, streaming: true, error: undefined }
@@ -63,138 +50,74 @@ function streamReducer<T>(state: StreamSnapshot<T>, event: StreamEvent<T>): Stre
         error: undefined,
       }
     case 'end':
+    case 'cancel':
       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']
+export function useStream<A extends unknown[] = []>(
+  author: CallAuthor<A> | null,
+  options?: StreamOptions,
+): StreamHandle<A, StreamItem> {
   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 authorRef = useRef(author)
+  authorRef.current = author
+  const optionsRef = useRef(options)
+  optionsRef.current = options
+  const [snapshot, dispatch] = useReducer(reducer<StreamItem>, {
+    chunks: [],
+    last: null,
+    streaming: false,
+    error: undefined,
+  })
+  const runId = useRef(0)
+  const controller = useRef<AbortController | null>(null)
 
-  const stop = useCallback(() => {
-    const run = currentRef.current
-    if (run !== null) {
-      run.controller.abort()
-      void run.iterator?.return?.(undefined)
-      currentRef.current = null
-    }
+  const cancel = useCallback(() => {
+    runId.current += 1
+    controller.current?.abort()
+    controller.current = null
+    dispatch({ type: 'cancel' })
   }, [])
 
-  useEffect(() => {
-    alive.current = true
-    return () => {
-      alive.current = false
-      stop()
-    }
-  }, [stop])
-
-  const cancel = useCallback(() => {
-    runIdRef.current += 1
-    stop()
-    if (alive.current) dispatch({ type: 'cancel' })
-  }, [stop])
+  useEffect(() => cancel, [cancel])
 
   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
+    async (...args: A): Promise<void> => {
+      const current = authorRef.current
+      if (current === null) throw new Error('useStream: idle handle started')
+      cancel()
+      const id = ++runId.current
+      const abort = new AbortController()
+      controller.current = abort
       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
+      const call = typeof current === 'function' ? current(...args) : current
+      try {
+        const { onChunk: _onChunk, ...requestOptions } = optionsRef.current ?? {}
+        const stream = await kernelRef.current.stream(call, {
+          ...requestOptions,
+          signal: abort.signal,
+        })
+        for await (const chunk of stream) {
+          if (id !== runId.current) return
+          dispatch({ type: 'chunk', value: chunk })
+          optionsRef.current?.onChunk?.(chunk)
         }
-      })()
+        if (id === runId.current) dispatch({ type: 'end' })
+      } catch (error) {
+        if (id !== runId.current) return
+        dispatch({ type: 'error', error })
+        throw error
+      } finally {
+        if (id === runId.current) controller.current = null
+      }
     },
-    [stop],
+    [cancel],
   )
 
-  // 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>
+  return { start, cancel, ...snapshot }
 }

package/src/graph/graph.context.ts

@@ -1,14 +1,9 @@
-import type { GraphMemory } from '@astrale-os/kernel-client/store'
+import type { GraphStore } 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'
+/** Optional exact Client GraphStore supplied by an injected Shell adapter. */
+export const GraphContext = createContext<GraphStore | null>(null)
+GraphContext.displayName = 'AstraleGraphStoreContext'
+
+export type { GraphStore }

package/src/graph/guards.error.ts

@@ -1,58 +1,20 @@
-/**
- * Error taxonomy (API §1.4) — re-exported from kernel-client so shell-react
- * consumers narrow dispatch failures through the single import surface. The
- * dispatched kernel call stays the source of truth; these guards drive UI
- * affordances (retry, request-access, toast). Names match kernel-client exactly.
- */
 export {
-  AuthBatchError,
-  AuthenticationError,
-  ClientSessionError,
-  ConnectionError,
-  DisconnectedError,
-  InvalidTransportError,
-  InvariantViolationError,
-  KernelError,
-  NodeUnavailableError,
-  NotFoundError,
-  PermissionDeniedError,
-  TimeoutError,
-  UnsupportedTransportError,
-  ValidationError,
-  WebOSError,
-  classifyKernelError,
-  isAuthBatchError,
-  isAuthenticationError,
-  isClientSessionError,
-  isDelegationMintError,
-  isDelegationPolicyError,
-  isDelegationRefusedError,
-  isHopLimitExceededError,
-  isIdentityError,
-  isInternalKernelError,
-  isInvalidRequestError,
-  isInvalidTransportError,
-  isInvariantViolationError,
-  isKernelError,
-  isNodeUnavailableError,
-  isNotFoundError,
-  isParseError,
-  isPermissionDeniedError,
-  isPersistenceLoadFailedError,
-  isPoolClosedError,
-  isRedirectPolicyError,
-  isRedirectRefusedError,
-  isRegistryWriteFailedError,
-  isSchemaOwnershipConflictError,
-  isTransportError,
-  isUnsupportedTransportError,
-  isValidationError,
-  isWebOSError,
-} from '@astrale-os/kernel-client'
-export type {
-  AuthReason,
-  ClientErrorDetails,
-  IdentityError,
-  KernelErrorKind,
+  ClientError,
+  ProtocolError,
+  ResponseError,
+  StaleRouteError,
   TransportError,
 } from '@astrale-os/kernel-client'
+export { NodeUnavailableError } from '@astrale-os/kernel-client/graph'
+export { UnsupportedFeatureError } from './memory/read/envelope.js'
+
+import { ClientError } from '@astrale-os/kernel-client'
+import { NodeUnavailableError } from '@astrale-os/kernel-client/graph'
+
+export function isClientError(error: unknown): error is ClientError {
+  return error instanceof ClientError
+}
+
+export function isNodeUnavailableError(error: unknown): error is NodeUnavailableError {
+  return error instanceof NodeUnavailableError
+}

package/src/graph/index.ts

@@ -1,20 +1,26 @@
-// graph — the graph plane (API §5 + §7). Merged read hooks, writes, dispatch.
-export { useNode } from './query/node.hook.js'
-export type { NodeResult } from './query/node.hook.js'
-export { useChildren } from './query/children.hook.js'
-export type { ChildrenOptions, ChildrenResult } from './query/children.hook.js'
-export { useQuery } from './query/query.hook.js'
-export type { QueryResult } from './query/query.hook.js'
-export { useGraph } from './query/graph.hook.js'
-export { useMutate } from './mutate/mutate.hook.js'
-export type { UseMutateOptions } from './mutate/mutate.hook.js'
-export { useMove } from './mutate/move.hook.js'
-export type { MoveAction } from './mutate/move.hook.js'
+export { useGraphStore } from './store.js'
+export { useQuery } from './query-definition.hook.js'
+export type { QueryResourceOptions } from './query-definition.hook.js'
+export type { GraphResource, GraphResourceState } from './resource.js'
 export { useCall } from './call/call.hook.js'
-export type { CallOptions } from './call/call.hook.js'
+export type { CallOptions, CallResult } from './call/call.hook.js'
 export { useStream } from './call/stream.hook.js'
-export type { StreamHandle, StreamOptions } from './call/stream.hook.js'
+export type {
+  CallAuthor,
+  KernelStream,
+  StreamHandle,
+  StreamItem,
+  StreamOptions,
+} from './call/stream.hook.js'
 export type { Action } from './action.js'
-export type { ReadState, ReadOptions, Windowed, Node } from './memory/read/envelope.js'
-export type { GraphMemory } from './graph.context.js'
-export type { ShapeInput } from '@astrale-os/kernel-client/store'
+export type { GraphStore } from './graph.context.js'
+export {
+  ClientError,
+  NodeUnavailableError,
+  ProtocolError,
+  ResponseError,
+  StaleRouteError,
+  TransportError,
+  isClientError,
+  isNodeUnavailableError,
+} from './guards.error.js'