@astrale-os/shell-react 0.1.0

package/src/application/roles.hook.ts

@@ -0,0 +1,41 @@
+import type { RoleNode } from '@astrale-os/shell'
+
+/**
+ * useRoles (API §12.2) — the roles self holds (`has_role` out-edges), over the
+ * async OS namespace (one-shot today, §12 flag).
+ */
+import { useMemo } from 'react'
+
+import type { ReadState } from '../graph/memory/read/envelope'
+
+import { useAsyncResource } from '../graph/async'
+import { useShell } from '../session/shell.hook'
+import { isOsPlaneAvailable } from './user/user.store'
+
+const NO_ROLES: readonly RoleNode[] = []
+
+export interface RolesResult extends ReadState {
+  readonly roles: readonly RoleNode[]
+}
+
+export function useRoles(): RolesResult {
+  const shell = useShell()
+  // OS plane unavailable (§12.2) → idle: no roles read.
+  const available = isOsPlaneAvailable(shell)
+  const res = useAsyncResource<readonly RoleNode[]>(
+    available ? () => shell.user.roles() : null,
+    NO_ROLES,
+    [shell, available],
+  )
+  return useMemo(
+    () => ({
+      roles: res.data,
+      pending: res.pending,
+      error: res.error,
+      live: false,
+      seq: 0,
+      refetch: res.refetch,
+    }),
+    [res],
+  )
+}

package/src/application/spaces/current-space.hook.ts

@@ -0,0 +1,43 @@
+import type { SpaceNode } from '@astrale-os/shell'
+
+/**
+ * useCurrentSpace (API §12.2) — the selected space, projected from the shared
+ * per-Shell current-space store (so a switch anywhere re-themes it). One-shot
+ * today (§12 flag); OS-plane-unavailable reads idle.
+ */
+import { useEffect, useMemo, useSyncExternalStore } from 'react'
+
+import type { ReadState } from '../../graph/memory/read/envelope'
+
+import { useShell } from '../../session/shell.hook'
+import { isOsPlaneAvailable } from '../user/user.store'
+import { currentSpaceStore, idleSnapshot, noopSubscribe } from './current-space.store'
+
+export interface CurrentSpaceResult extends ReadState {
+  readonly space: SpaceNode | null
+}
+
+export function useCurrentSpace(): CurrentSpaceResult {
+  const shell = useShell()
+  const available = isOsPlaneAvailable(shell)
+  const store = currentSpaceStore(shell)
+  useEffect(() => {
+    if (available) store.ensure()
+  }, [store, available])
+  const snap = useSyncExternalStore(
+    available ? store.subscribe : noopSubscribe,
+    available ? store.getSnapshot : idleSnapshot,
+    available ? store.getSnapshot : idleSnapshot,
+  )
+  return useMemo(
+    () => ({
+      space: snap.space,
+      pending: snap.pending,
+      error: snap.error,
+      live: false,
+      seq: 0,
+      refetch: store.refresh,
+    }),
+    [snap, store],
+  )
+}

package/src/application/spaces/current-space.store.ts

@@ -0,0 +1,110 @@
+/**
+ * The shared current-space store (API §12.2). ONE reactive resolver per Shell, so
+ * useCurrentSpace / useApps / useSpaces.selected all observe the SAME selected
+ * space: a `switch` in any window re-themes every consumer in this window at once,
+ * with a manual optimistic override applied ahead of the round-trip (§1.6). This
+ * closes the same-window cross-hook divergence; cross-WINDOW liveness still waits
+ * on the memory-shape move (§12 flag).
+ */
+import type { Shell, SpaceNode } from '@astrale-os/shell'
+
+export interface CurrentSpaceSnapshot {
+  readonly space: SpaceNode | null
+  readonly pending: boolean
+  readonly error: unknown
+}
+
+// Stable idles for when the OS plane is unavailable (§12.2) — a fixed snapshot
+// and a no-op subscription keep `useSyncExternalStore` tear-free without touching
+// (and re-triggering a fetch on) the real current-space store.
+export const IDLE_SNAPSHOT: CurrentSpaceSnapshot = { space: null, pending: false, error: undefined }
+export const idleSnapshot = (): CurrentSpaceSnapshot => IDLE_SNAPSHOT
+export const noopSubscribe = (): (() => void) => () => {}
+
+export interface CurrentSpaceStore {
+  subscribe(cb: () => void): () => void
+  getSnapshot(): CurrentSpaceSnapshot
+  /** Kick a first load if the confirmed value was never fetched. */
+  ensure(): void
+  /** Refetch the confirmed selected space; resolves when it lands. */
+  refresh(): Promise<void>
+  /** Apply an optimistic override (a switch in flight) — every consumer re-renders. */
+  setOptimistic(space: SpaceNode | null): void
+  /** Drop the optimistic override, revealing confirmed truth again. */
+  clearOptimistic(): void
+}
+
+function createStore(load: () => Promise<SpaceNode | null>): CurrentSpaceStore {
+  let confirmed: SpaceNode | null = null
+  let loaded = false
+  let pending = false
+  let error: unknown = undefined
+  let override: { space: SpaceNode | null } | null = null
+  let seq = 0
+  let snap: CurrentSpaceSnapshot = { space: null, pending: false, error: undefined }
+  const listeners = new Set<() => void>()
+
+  /** Recompute the projection (override wins) and notify only on a real change. */
+  function rebuild(): void {
+    const space = override !== null ? override.space : confirmed
+    if (space === snap.space && pending === snap.pending && error === snap.error) return
+    snap = { space, pending, error }
+    for (const l of listeners) l()
+  }
+
+  function fetch(): Promise<void> {
+    const my = ++seq
+    pending = true
+    rebuild()
+    return load().then(
+      (space) => {
+        if (my !== seq) return
+        confirmed = space
+        loaded = true
+        pending = false
+        error = undefined
+        rebuild()
+      },
+      (e: unknown) => {
+        if (my !== seq) return
+        pending = false
+        error = e
+        rebuild()
+      },
+    )
+  }
+
+  return {
+    subscribe(cb) {
+      listeners.add(cb)
+      if (!loaded && !pending) void fetch()
+      return () => listeners.delete(cb)
+    },
+    getSnapshot: () => snap,
+    ensure() {
+      if (!loaded && !pending) void fetch()
+    },
+    refresh: () => fetch(),
+    setOptimistic(space) {
+      override = { space }
+      rebuild()
+    },
+    clearOptimistic() {
+      if (override === null) return
+      override = null
+      rebuild()
+    },
+  }
+}
+
+const stores = new WeakMap<Shell, CurrentSpaceStore>()
+
+/** The one current-space store for a Shell (created on first touch). */
+export function currentSpaceStore(shell: Shell): CurrentSpaceStore {
+  let s = stores.get(shell)
+  if (s === undefined) {
+    s = createStore(() => shell.user.currentSpace())
+    stores.set(shell, s)
+  }
+  return s
+}

package/src/application/spaces/space.hook.ts

@@ -0,0 +1,41 @@
+import type { NodeRefInput } from '@astrale-os/kernel-client'
+import type { SpaceNode } from '@astrale-os/shell'
+
+import { normalizeRef } from '@astrale-os/kernel-client'
+/**
+ * useSpace(ref) (API §12.2) — a single space by ref; `null`/`undefined` (or an
+ * unavailable OS plane) is idle (§1.3). One-shot today (§12 flag).
+ */
+import { useMemo } from 'react'
+
+import type { CurrentSpaceResult } from './current-space.hook'
+
+import { useAsyncResource } from '../../graph/async'
+import { isIdleInput } from '../../graph/memory/read/idle'
+import { useShell } from '../../session/shell.hook'
+import { isOsPlaneAvailable } from '../user/user.store'
+
+export type SpaceResult = CurrentSpaceResult
+
+export function useSpace(ref: NodeRefInput | null | undefined): SpaceResult {
+  const shell = useShell()
+  const idle = isIdleInput(ref) || !isOsPlaneAvailable(shell)
+  // The inline guard (not the stored `idle`) narrows `ref` to non-null below.
+  const key = idle ? null : normalizeRef(ref as NodeRefInput)
+  const res = useAsyncResource<SpaceNode | null>(
+    idle ? null : () => shell.spaces.get(ref as NodeRefInput),
+    null,
+    [shell, key],
+  )
+  return useMemo(
+    () => ({
+      space: idle ? null : res.data,
+      pending: idle ? false : res.pending,
+      error: idle ? undefined : res.error,
+      live: false,
+      seq: 0,
+      refetch: res.refetch,
+    }),
+    [idle, res],
+  )
+}

package/src/application/spaces/spaces.hook.ts

@@ -0,0 +1,113 @@
+import type { NodeRefInput } from '@astrale-os/kernel-client'
+import type { SpaceNode } from '@astrale-os/shell'
+
+import { normalizeRef } from '@astrale-os/kernel-client'
+/**
+ * useSpaces (API §12.2) — the spaces list, the selected space, and a `switch`
+ * Action that repoints the `selected_space` edge. Reads the SAME per-Shell
+ * current-space store as useCurrentSpace/useApps, so a switch re-themes every
+ * consumer in the window at once — optimistically ahead of the round-trip (§1.6),
+ * commit reconciles, failure rolls back. Reads are one-shot today (§12 flag).
+ */
+import { useEffect, useMemo, useSyncExternalStore } from 'react'
+
+import type { Action } from '../../graph/action'
+import type { ReadState } from '../../graph/memory/read/envelope'
+
+import { useAction } from '../../graph/action'
+import { useAsyncResource } from '../../graph/async'
+import { useShell } from '../../session/shell.hook'
+import { isOsPlaneAvailable } from '../user/user.store'
+import { currentSpaceStore, idleSnapshot, noopSubscribe } from './current-space.store'
+
+const NO_SPACES: readonly SpaceNode[] = []
+
+export interface SpacesResult extends ReadState {
+  /** Spaces-dir children, live (one-shot today), the caller's readable set. */
+  readonly spaces: readonly SpaceNode[]
+  /** The `selected_space` target — optimistically ahead during a `switch`. */
+  readonly selected: SpaceNode | null
+  /** `user::switchSpace` with a manual optimistic overlay (§1.6). */
+  readonly switch: Action<[NodeRefInput], void>
+}
+
+export function useSpaces(): SpacesResult {
+  const shell = useShell()
+  const available = isOsPlaneAvailable(shell)
+  const store = currentSpaceStore(shell)
+
+  const spacesRes = useAsyncResource<readonly SpaceNode[]>(
+    available ? () => shell.spaces.list() : null,
+    NO_SPACES,
+    [shell, available],
+  )
+  useEffect(() => {
+    if (available) store.ensure()
+  }, [store, available])
+  const selectedSnap = useSyncExternalStore(
+    available ? store.subscribe : noopSubscribe,
+    available ? store.getSnapshot : idleSnapshot,
+    available ? store.getSnapshot : idleSnapshot,
+  )
+
+  const spaces = spacesRes.data
+
+  const switchAction = useAction(async (ref: NodeRefInput): Promise<void> => {
+    // Optimistic override on the SHARED store, so useCurrentSpace / useApps ahead
+    // of the round-trip too (§12.2). Only overlay a known target (a path ref that
+    // matches nothing in the list simply skips the preview).
+    const target = findSpace(spaces, ref)
+    if (target !== null) store.setOptimistic(target)
+    try {
+      await shell.user.switchSpace(ref)
+      await store.refresh() // reconcile confirmed truth BEFORE dropping the preview
+      store.clearOptimistic()
+    } catch (error) {
+      store.clearOptimistic() // rollback: reveal the confirmed (previous) space
+      throw error
+    }
+  })
+
+  return useMemo<SpacesResult>(
+    () => ({
+      spaces,
+      selected: selectedSnap.space,
+      switch: switchAction,
+      pending: spacesRes.pending || selectedSnap.pending,
+      error: spacesRes.error ?? selectedSnap.error,
+      live: false,
+      seq: 0,
+      refetch: async () => {
+        await Promise.all([spacesRes.refetch(), store.refresh()])
+      },
+    }),
+    [
+      spaces,
+      selectedSnap,
+      switchAction,
+      spacesRes.pending,
+      spacesRes.error,
+      spacesRes.refetch,
+      store,
+    ],
+  )
+}
+
+/** The space in `spaces` denoted by `ref`, or `null` (path refs don't match by id). */
+function findSpace(spaces: readonly SpaceNode[], ref: NodeRefInput): SpaceNode | null {
+  const id = refIdOf(ref)
+  if (id === null) return null
+  return spaces.find((s) => s.id === id) ?? null
+}
+
+/** A bound-node-ish subject carries a graph id. */
+function hasId(x: unknown): x is { readonly id: string } {
+  return typeof x === 'object' && x !== null && 'id' in x
+}
+
+/** The graph id a subject denotes, or `null` when it is a path (no id to match). */
+function refIdOf(x: NodeRefInput | { readonly id: string }): string | null {
+  if (hasId(x)) return x.id
+  const raw = normalizeRef(x)
+  return raw.startsWith('@') ? raw.slice(1) : null
+}

package/src/application/user/user.hook.ts

@@ -0,0 +1,27 @@
+/**
+ * useUser (API §12.2) — self as the shell-domain `User` (typed
+ * firstName/lastName/email). The provider PRE-RESOLVES it at boot (`primeUser`),
+ * so `useUser` is synchronous below the provider (API §2). OS-plane absent → throws
+ * descriptively to the nearest boundary; a never-primed shell suspends on first use
+ * (§1.4). FLAG: not yet re-rendered on rename — becomes live via a memory shape.
+ */
+import type { UserNode } from '@astrale-os/shell'
+
+import { useShell } from '../../session/shell.hook'
+import { loadUser, userCache } from './user.store'
+
+export function useUser(): UserNode {
+  const shell = useShell()
+  const entry = userCache.get(shell) ?? loadUser(shell)
+  if (entry.status === 'pending') throw entry.promise
+  // OS plane resolved absent at boot — throw to the nearest boundary; do NOT
+  // re-load (the plane is not coming back this session).
+  if (entry.status === 'unavailable') throw entry.error
+  if (entry.status === 'rejected') {
+    // Retryable transient: drop the poisoned cell so an error-boundary retry
+    // re-loads `me()` instead of re-throwing the same failure forever.
+    userCache.delete(shell)
+    throw entry.error
+  }
+  return entry.value
+}

package/src/application/user/user.store.ts

@@ -0,0 +1,85 @@
+/**
+ * The OS-plane user store (API §2/§12.2). Provider-boot priming (`primeUser`) seeds
+ * the per-Shell user cache so `useUser` is synchronous, and tracks OS-plane
+ * availability: a missing/rejecting `shell.user.me` marks the plane down (the other
+ * OS hooks then read idle) without failing boot. A never-primed shell falls back to
+ * a lazy cold read that SUSPENDS on first use (§1.4).
+ */
+import type { Shell, UserNode } from '@astrale-os/shell'
+
+export type UserEntry =
+  | { status: 'pending'; promise: Promise<void> }
+  | { status: 'resolved'; value: UserNode }
+  | { status: 'rejected'; error: unknown }
+  /** OS plane absent — throw descriptively, do NOT re-load (a reload just refails). */
+  | { status: 'unavailable'; error: unknown }
+
+export const userCache = new WeakMap<Shell, UserEntry>()
+
+/** Shells whose OS plane could not be resolved at boot — OS hooks read idle. */
+const osPlaneDown = new WeakSet<Shell>()
+
+/** Is the OS plane (shell.user/spaces/apps) usable for this shell? */
+export function isOsPlaneAvailable(shell: Shell): boolean {
+  return !osPlaneDown.has(shell)
+}
+
+interface UserSurface {
+  user?: { me?: () => Promise<UserNode> }
+}
+
+function osPlaneError(cause: unknown): Error {
+  const detail = cause instanceof Error ? cause.message : String(cause)
+  return new Error(
+    `The OS plane is unavailable (useUser/useSpaces/useApps): shell.user.me() could not resolve ` +
+      `— the workspace/shell domain may not be installed for this identity. (${detail})`,
+  )
+}
+
+/**
+ * Provider-boot priming (API §2). Best-effort: seed the user cache so `useUser`
+ * is synchronous, or mark the OS plane down. NEVER throws — boot must not fail on
+ * a missing OS plane.
+ */
+export async function primeUser(shell: Shell): Promise<void> {
+  const me = (shell as unknown as UserSurface).user?.me
+  if (typeof me !== 'function') {
+    osPlaneDown.add(shell)
+    userCache.set(shell, {
+      status: 'unavailable',
+      error: osPlaneError('shell.user.me is not a function'),
+    })
+    return
+  }
+  try {
+    const value = await me.call((shell as unknown as UserSurface).user)
+    osPlaneDown.delete(shell)
+    userCache.set(shell, { status: 'resolved', value })
+  } catch (error) {
+    osPlaneDown.add(shell)
+    userCache.set(shell, { status: 'unavailable', error: osPlaneError(error) })
+  }
+}
+
+/** Kick off `me()` lazily (a shell that was never primed) and cache a suspense cell. */
+export function loadUser(shell: Shell): UserEntry {
+  const cell: {
+    status: 'pending' | 'resolved' | 'rejected'
+    promise?: Promise<void>
+    value?: UserNode
+    error?: unknown
+  } = { status: 'pending' }
+  cell.promise = shell.user.me().then(
+    (value) => {
+      cell.status = 'resolved'
+      cell.value = value
+    },
+    (error: unknown) => {
+      cell.status = 'rejected'
+      cell.error = error
+    },
+  )
+  const entry = cell as unknown as UserEntry
+  userCache.set(shell, entry)
+  return entry
+}

package/src/auth/act-as.context.tsx

@@ -0,0 +1,124 @@
+import type { CredentialInput, FnMap } from '@astrale-os/kernel-client'
+import type { BoundClientSessionView } from '@astrale-os/kernel-client/session'
+import type { ReactElement, ReactNode } from 'react'
+
+/**
+ * The acting-principal binding (API §4). `IdentityContext` seats the effective
+ * principal a subtree dispatches as — its bound kernel view + whoami + memory
+ * scope; `useIdentityBinding` resolves it (an `<ActAs>` override, else the root
+ * off ShellContext). `<ActAs>` rebinds a subtree to another principal with a
+ * DISTINCT memory scope so results never leak across principals (§5.4).
+ */
+import { createContext, useContext, useEffect, useMemo, useState } from 'react'
+
+import type { SelfNode } from '../session/session.context'
+
+import { ShellContext } from '../session/session.context'
+
+/** A bound session view — the kernel surface `session.as(cred)` yields. */
+export type SessionView = BoundClientSessionView<FnMap>
+
+/** A whoami-shaped identity/graph node (kernel-client does not yet re-export `Node` — G8). */
+export type NodeValue = SelfNode
+
+/** The root scope key — the memory's own default scope (`createMemory` default). */
+export const ROOT_SCOPE = 'default'
+
+/**
+ * The principal a subtree acts as (API §4). `scope` is the memory isolation key
+ * (§5.4): the graph plane scopes its memory by `memory.forScope(scope)` so an
+ * <ActAs> subtree never shares cached results with another principal.
+ */
+export interface IdentityBinding {
+  readonly kernel: SessionView
+  readonly self: SelfNode
+  readonly scope: string
+}
+export const IdentityContext = createContext<IdentityBinding | null>(null)
+IdentityContext.displayName = 'AstraleIdentityContext'
+
+/**
+ * The principal this subtree dispatches as. An <ActAs> value wins; otherwise the
+ * root binding off ShellContext. Throws outside a provider, or when the bound
+ * kernel resolved no identity (a bare prebuilt Shell with no auth surface).
+ */
+export function useIdentityBinding(): IdentityBinding {
+  const override = useContext(IdentityContext)
+  if (override !== null) return override
+
+  const runtime = useContext(ShellContext)
+  if (runtime === null) {
+    throw new Error('identity hooks must be used within a <ShellProvider>')
+  }
+  if (runtime.self === null) {
+    throw new Error(
+      'identity hooks require an identity: this shell exposed no auth surface, so whoami ' +
+        'resolved nothing at boot',
+    )
+  }
+  // The root binding reads stable fields (self, shell.kernel), so a fresh object
+  // per render is inert — consumers key off `kernel`/`self`, both stable.
+  return { kernel: runtime.shell.kernel, self: runtime.self, scope: ROOT_SCOPE }
+}
+
+export interface ActAsProps {
+  /** The principal to act as. A thunk is resolved by the kernel per dispatch. */
+  credential: CredentialInput | (() => CredentialInput)
+  children: ReactNode
+}
+
+/**
+ * A subtree that dispatches as another principal: rebinds the kernel (session.as),
+ * resolves whoami, and provides a fresh identity binding with a DISTINCT memory
+ * scope (`as:<id>`). Nestable — it rebinds from the current effective principal. A
+ * brief nested boot holds the subtree (renders null) until whoami resolves.
+ */
+export function ActAs({ credential, children }: ActAsProps): ReactElement | null {
+  const parent = useIdentityBinding()
+  // Key the rebind on a STABLE credential identity (like `configIdentity` does),
+  // so an inline object credential (`credential={{ … }}`) does not re-mint the
+  // session view — and re-run whoami, unmounting the subtree — every parent
+  // render. A thunk still keys by reference: pass a stable thunk to avoid churn.
+  const credKey = credentialIdentity(credential)
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const kernel = useMemo(() => parent.kernel.as(credential), [parent.kernel, credKey])
+
+  const [self, setSelf] = useState<SelfNode | null>(null)
+  useEffect(() => {
+    let alive = true
+    setSelf(null)
+    void kernel.auth.whoami().then(
+      (node) => {
+        if (alive) setSelf(node)
+      },
+      () => {
+        /* held (null) subtree on resolve failure — transport errors surface via the provider */
+      },
+    )
+    return () => {
+      alive = false
+    }
+  }, [kernel])
+
+  const value = useMemo<IdentityBinding | null>(
+    () => (self === null ? null : { kernel, self, scope: `as:${self.id}` }),
+    [kernel, self],
+  )
+
+  if (value === null) return null
+  return <IdentityContext.Provider value={value}>{children}</IdentityContext.Provider>
+}
+
+/**
+ * A stable identity for a credential: the thunk by reference, a string as itself,
+ * and an object by a serialized form — so an equal inline object does not churn
+ * the memo (worst case a serialize failure falls back to reference identity).
+ */
+function credentialIdentity(credential: CredentialInput | (() => CredentialInput)): unknown {
+  if (typeof credential === 'function' || typeof credential === 'string') return credential
+  try {
+    return `cred:${JSON.stringify(credential)}`
+  } catch {
+    return credential
+  }
+}

package/src/auth/auth.hook.ts

@@ -0,0 +1,36 @@
+import type { AuthApi } from '@astrale-os/kernel-client/auth'
+
+/**
+ * useAuth (API §4) — the imperative AuthApi of the effective principal
+ * (whoami/credential/mint/delegate/check/grant/revoke/bind/unbind). Grant and
+ * revoke additionally nudge the principal's useCan ledger on success, delivering
+ * the Tier-0 local re-check (SPEC §11.3). DEVIATION: API §4 describes a pure
+ * passthrough; the wrap is the only way to surface a local grant/revoke today,
+ * since permissions dispatch as identity methods rather than graph patches.
+ * Cross-client liveness still awaits the watch tiers (G7).
+ */
+import { useMemo } from 'react'
+
+import type { SessionView } from './act-as.context'
+
+import { useIdentityBinding } from './act-as.context'
+import { ledgerFor } from './can.hook'
+
+export function useAuth(): AuthApi {
+  const { kernel } = useIdentityBinding()
+  return useMemo(() => withLedgerNudge(kernel), [kernel])
+}
+
+/** Wrap grant/revoke so a successful local change re-checks the principal's cells. */
+function withLedgerNudge(kernel: SessionView): AuthApi {
+  const auth = kernel.auth
+  const ledger = ledgerFor(kernel)
+  const invalidate = (): void => ledger.invalidateAll()
+
+  const grant = ((arg: never) =>
+    Promise.resolve(auth.grant(arg)).then(invalidate)) as AuthApi['grant']
+  const revoke = ((arg: never) =>
+    Promise.resolve(auth.revoke(arg)).then(invalidate)) as AuthApi['revoke']
+
+  return { ...auth, grant, revoke }
+}