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

package/dist/schema/write.js

@@ -1,56 +0,0 @@
-const writableCache = new WeakMap();
-export function writableFor(kernel, memory) {
-    let entry = writableCache.get(kernel);
-    if (entry === undefined) {
-        const nodeIndex = new Map();
-        entry = { writable: withMemoryWrites(kernel, memory, nodeIndex), nodeIndex };
-        writableCache.set(kernel, entry);
-    }
-    return entry;
-}
-/**
- * Wrap a session view so `updateNode`/`createNode` route through the memory's
- * optimistic write shorthands. `BoundNode.update` addresses a node by `@<id>`,
- * but the memory needs the node's class and tree path — so an `@<id>` ref is translated
- * through `nodeIndex` (populated at bind time). A ref that is NOT indexed (a node
- * that was never bound) falls back to the raw kernel-client floor:
- * it still dispatches, just without the overlay — matching the imperative floor.
- */
-function withMemoryWrites(kernel, memory, nodeIndex) {
-    const base = kernel;
-    const rawUpdate = base.updateNode.bind(base);
-    return extendCapabilities(kernel, {
-        updateNode: (cls, ref, props) => {
-            const node = indexedNode(nodeIndex, ref);
-            return node !== null ? memory.update(node, props) : rawUpdate(cls, ref, props);
-        },
-        createNode: (cls, at, props) => memory.create(cls, at, props),
-        // Credential rebind stays on the raw kernel-client floor (§6 note).
-        as: (cred) => base.as(cred),
-    });
-}
-/** Overlay memory writes without materializing a possibly virtual session surface. */
-function extendCapabilities(base, extension) {
-    return new Proxy(base, {
-        get(target, prop, receiver) {
-            return Object.prototype.hasOwnProperty.call(extension, prop)
-                ? Reflect.get(extension, prop, extension)
-                : Reflect.get(target, prop, receiver);
-        },
-    });
-}
-/** The tree path an `@<id>` write ref maps to, via the bind-time index; else null. */
-function indexedNode(nodeIndex, ref) {
-    if (typeof ref !== 'string' || !ref.startsWith('@'))
-        return null;
-    return nodeIndex.get(ref.slice(1)) ?? null;
-}
-/** Record a bound node's raw value so the write cap retains its class and tree path. */
-export function recordNode(nodeIndex, node) {
-    const wrapped = node;
-    const candidate = wrapped?.raw !== null && typeof wrapped?.raw === 'object' ? wrapped.raw : node;
-    const n = candidate;
-    if (n !== null && typeof n.id === 'string' && typeof n.path?.raw === 'string') {
-        nodeIndex.set(n.id, candidate);
-    }
-}

package/src/application/roles.hook.ts

@@ -1,41 +0,0 @@
-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.js'
-
-import { useAsyncResource } from '../graph/async.js'
-import { useShell } from '../session/shell.hook.js'
-import { isOsPlaneAvailable } from './user/user.store.js'
-
-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/graph/memory/base.ts

@@ -1,50 +0,0 @@
-import type { GraphApi } from '@astrale-os/kernel-client/graph'
-import type { GraphMemory, MemoryEvent } from '@astrale-os/kernel-client/store'
-/**
- * The base memory (API §5.4). One `GraphMemory` per live Shell — the partial
- * client copy of the graph every graph/schema/nav hook reads through, so they all
- * share one cache, one dedupe, one optimistic overlay. Derived from `shell.kernel`
- * and memoized on the Shell object. Its `onError` fans out through a per-Shell
- * sink the provider registers, so warm-refresh failures and rolled-back mutations
- * reach the provider's `onError` channel (§2).
- */
-import type { Shell } from '@astrale-os/shell'
-
-import { createMemory } from '@astrale-os/kernel-client/store'
-
-/** One memory per Shell reference — shared by every hook under that provider. */
-const memoryByShell = new WeakMap<Shell, GraphMemory>()
-
-/**
- * Per-Shell error sink (API §2/§8). The provider registers a bridge here; the
- * memory emits refresh/mutation/divergence events through it, read lazily at
- * emit time so registration order doesn't matter. Cleared on provider unmount.
- */
-const errorSinks = new WeakMap<Shell, (event: MemoryEvent) => void>()
-
-/** Register (or clear) the provider's memory-event bridge for a Shell. */
-export function setMemoryErrorSink(
-  shell: Shell,
-  sink: ((event: MemoryEvent) => void) | null,
-): void {
-  if (sink === null) errorSinks.delete(shell)
-  else errorSinks.set(shell, sink)
-}
-
-/**
- * The base (default-scope) memory for a Shell — the SAME instance every graph/
- * schema/nav hook reads through `useMemory`, so the provider can seat it in
- * `GraphContext` (selection's liveness source) without minting a rival copy.
- * Its `onError` fans out through the per-Shell sink so warm-refresh failures and
- * rolled-back mutations reach `ShellProvider`'s `onError` channel (§2).
- */
-export function baseMemoryFor(shell: Shell): GraphMemory {
-  let memory = memoryByShell.get(shell)
-  if (memory === undefined) {
-    memory = createMemory(shell.kernel as GraphApi, {
-      onError: (event) => errorSinks.get(shell)?.(event),
-    })
-    memoryByShell.set(shell, memory)
-  }
-  return memory
-}

package/src/graph/memory/read/read.ts

@@ -1,103 +0,0 @@
-import type {
-  LiveResult,
-  ReadOptions as StoreReadOptions,
-  ShapeInput,
-} from '@astrale-os/kernel-client/store'
-
-import { canonicalizeAST, shapeInputToAST, stableStringify } from '@astrale-os/kernel-client/store'
-/**
- * The shared read substrate (API §1, §5). One `useSyncExternalStore` binding over
- * a memory shape — the substrate every graph read hook narrows. Handles the four
- * cross-cutting concerns once: idle inputs (§1.3), suspense-first on a cold shape
- * (§1.4), stale-while-revalidate + `keepPrevious` (§1.5), and referential
- * stability (§1.7 — an unchanged shape returns the store's own stable snapshot).
- */
-import { useCallback, useRef, useSyncExternalStore } from 'react'
-
-import type { CoreReadOptions, RawRead } from './envelope.js'
-
-import { useMemory } from '../scope.js'
-import { EMPTY_PENDING, IDLE_READ, withPending } from './envelope.js'
-import { isIdleInput } from './idle.js'
-
-const NOOP_UNSUB = (): void => {}
-const IDLE_TOKEN = ' idle'
-
-/** Project shell-react read options onto the store's — `with`/`window`/`live` key the shape. */
-function storeReadOptions(opts?: CoreReadOptions): StoreReadOptions | undefined {
-  if (opts === undefined) return undefined
-  const out: StoreReadOptions = {}
-  if (opts.live !== undefined) out.live = opts.live
-  if (opts.window !== undefined) out.window = opts.window
-  // `with` is a PermName at the store/kernel (READ lit-up today); the public
-  // `PermMask` typing reconciles with the grant epoch (API §14 G7).
-  if (opts.with !== undefined) out.with = opts.with as unknown as StoreReadOptions['with']
-  return out
-}
-
-/**
- * A stable per-render key for a shape input + its keying options, so the
- * subscription/snapshot closures only re-bind when the LOGICAL read changes
- * (not when an inline builder closure is re-created each render).
- */
-function shapeToken(shape: ShapeInput, opts?: CoreReadOptions): string {
-  const canon = stableStringify(canonicalizeAST(shapeInputToAST(shape)))
-  return `${canon}#w=${String(opts?.with ?? '')}#win=${opts?.window ?? ''}#live=${
-    opts?.live === false ? '0' : '1'
-  }`
-}
-
-/**
- * Subscribe to a memory shape and project it. `null`/`undefined` shape → idle.
- * Cold + `suspend` (default) throws the cold-shape promise; `suspend:false`
- * returns empty-pending; `keepPrevious` returns the last data while confirming.
- */
-export function useRead(shape: ShapeInput | null | undefined, opts?: CoreReadOptions): RawRead {
-  const memory = useMemory()
-  const idle = isIdleInput(shape)
-
-  const shapeRef = useRef<ShapeInput | null | undefined>(shape)
-  shapeRef.current = shape
-  const optsRef = useRef<CoreReadOptions | undefined>(opts)
-  optsRef.current = opts
-
-  const token = idle ? IDLE_TOKEN : shapeToken(shape as ShapeInput, opts)
-
-  const subscribe = useCallback(
-    (onStoreChange: () => void) => {
-      const s = shapeRef.current
-      if (token === IDLE_TOKEN || s === null || s === undefined) return NOOP_UNSUB
-      return memory.subscribe(s, onStoreChange, storeReadOptions(optsRef.current))
-    },
-    [memory, token],
-  )
-  const getSnapshot = useCallback((): LiveResult | null => {
-    const s = shapeRef.current
-    if (token === IDLE_TOKEN || s === null || s === undefined) return null
-    return memory.getSnapshot(s, storeReadOptions(optsRef.current))
-  }, [memory, token])
-
-  const snap = useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
-  const prevRef = useRef<LiveResult | null>(null)
-
-  if (idle) return IDLE_READ
-
-  const warm = memory.peek(shape as ShapeInput, storeReadOptions(opts)) !== null
-  if (warm && snap !== null) {
-    prevRef.current = snap
-    return snap
-  }
-  if (opts?.keepPrevious === true && prevRef.current !== null) {
-    return withPending(prevRef.current)
-  }
-  if (opts?.suspend !== false) {
-    // Cold FAILURE (§1.4): the shape fetched and rejected with no data to show —
-    // throw the error to the nearest boundary. Re-throwing the promise here would
-    // re-arm a fresh fetch every retry (the entry's inflight was cleared on
-    // failure), looping render→fetch→reject forever. This breaks that loop.
-    if (snap !== null && snap.error !== undefined) throw snap.error
-    // Cold shape: suspend on the first-confirmed-data promise (§1.4).
-    throw memory.promise(shape as ShapeInput, storeReadOptions(opts))
-  }
-  return EMPTY_PENDING
-}

package/src/graph/memory/scope.ts

@@ -1,29 +0,0 @@
-import type { GraphApi } from '@astrale-os/kernel-client/graph'
-import type { GraphMemory } from '@astrale-os/kernel-client/store'
-
-/**
- * Memory scope resolution (API §5.4). `useMemory` returns the memory for this
- * subtree: the base memory derived from the provider's Shell, re-scoped (and
- * re-api'd) to the `<ActAs>` principal via `forScope` when an identity binding is
- * present — so a principal never shares cached results with another.
- */
-import { useContext, useMemo } from 'react'
-
-import { IdentityContext } from '../../auth/act-as.context.js'
-import { ShellContext } from '../../session/session.context.js'
-import { baseMemoryFor } from './base.js'
-
-/**
- * The memory for this subtree. Throws outside a `<ShellProvider>`. Above any
- * `<ActAs>` it is the base memory; inside one it is scoped by the binding.
- */
-export function useMemory(): GraphMemory {
-  const runtime = useContext(ShellContext)
-  const binding = useContext(IdentityContext)
-  const shell = runtime?.shell ?? null
-  return useMemo(() => {
-    if (shell === null) throw new Error('graph hooks must be used within a <ShellProvider>')
-    const base = baseMemoryFor(shell)
-    return binding === null ? base : base.forScope(binding.scope, binding.kernel as GraphApi)
-  }, [shell, binding])
-}

package/src/graph/mutate/move.hook.ts

@@ -1,70 +0,0 @@
-import type { NodeRefInput } from '@astrale-os/kernel-client'
-import type { PathLike } from '@astrale-os/kernel-client/graph'
-import type { GraphMemory } from '@astrale-os/kernel-client/store'
-
-import { rawOf } from '@astrale-os/kernel-client/graph'
-/**
- * useMove (API §5, the G1 seam) — dispatch the sealed `node::move` method (the one
- * tree op no patch arm can express). PESSIMISTIC today (honest `pending`); affected
- * container shapes revalidate on settlement. Turns optimistic when the `nodes.move`
- * patch arm lands, with zero consumer change.
- */
-import { useCallback } from 'react'
-
-import type { Action } from '../action.js'
-import type { Node } from '../memory/read/envelope.js'
-
-import { useSessionKernel } from '../../auth/session-kernel.js'
-import { useAction } from '../action.js'
-import { useMemory } from '../memory/scope.js'
-
-export type MoveAction = Action<[node: Node | NodeRefInput, to: PathLike], void>
-
-export function useMove(): MoveAction {
-  const kernel = useSessionKernel()
-  const memory = useMemory()
-  const run = useCallback(
-    async (node: Node | NodeRefInput, to: PathLike): Promise<void> => {
-      const method = isNode(node) ? `@${node.id}::move` : `${rawOf(node)}::move`
-      await kernel.call(method, { to: rawOf(to) })
-      await reconcileMove(memory, node, to)
-    },
-    [kernel, memory],
-  )
-  return useAction(run)
-}
-
-function isNode(x: Node | NodeRefInput): x is Node {
-  return typeof x === 'object' && x !== null && 'id' in x && 'class' in x && 'path' in x
-}
-
-/** Root-first parent of a raw absolute path, or `null` at the root. */
-function parentPathOf(raw: string): string | null {
-  const trimmed = raw.replace(/\/+$/, '')
-  const i = trimmed.lastIndexOf('/')
-  if (i < 0) return null
-  return i === 0 ? '/' : trimmed.slice(0, i)
-}
-
-/**
- * Best-effort settlement reconciliation (Tier 0): refetch the source and
- * destination container's default `children` shapes when they are observed. A
- * custom-ordered/filtered children shape is keyed distinctly and is not reached
- * here — consumers get honest `pending` and reconcile on G1.
- */
-async function reconcileMove(
-  memory: GraphMemory,
-  node: Node | NodeRefInput,
-  to: PathLike,
-): Promise<void> {
-  const path = isNode(node) ? rawOf(node.path) : rawOf(node)
-  const containers = new Set<string>([rawOf(to)])
-  const old = parentPathOf(path)
-  if (old !== null) containers.add(old)
-  await Promise.allSettled(
-    [...containers].map((c) => {
-      const snap = memory.peek((q) => q.from(c).children())
-      return snap !== null ? snap.refetch() : Promise.resolve()
-    }),
-  )
-}

package/src/graph/mutate/mutate.hook.ts

@@ -1,69 +0,0 @@
-import type { PatchBuilder } from '@astrale-os/kernel-client/graph'
-import type { GraphMemory } from '@astrale-os/kernel-client/store'
-
-/**
- * useMutate (API 5/1.6) - build a graph-scoped Action. The callback receives
- * this subtree's GraphMemory, so callers do not need a separate useGraph() just
- * to author the mutation. Patch-shaped writes are optimistic via their own
- * overlay; pass a function `optimistic` to preview an opaque dispatch effect.
- */
-import { useCallback, useRef } from 'react'
-
-import type { Action } from '../action.js'
-
-import { useAction } from '../action.js'
-import { useMemory } from '../memory/scope.js'
-
-export interface UseMutateOptions<A extends unknown[], R> {
-  /**
-   * `'auto'` (default) / `false`: the write's own overlay governs optimism - the
-   * callback's graph writes apply the authored patch. A function opens a
-   * MANUAL overlay decoupled from what the callback dispatches.
-   */
-  optimistic?: 'auto' | false | ((overlay: PatchBuilder, ...args: A) => void)
-  /** default 'auto'. false = keep the manual overlay on failure (caller reconciles). */
-  rollback?: 'auto' | false
-  onCommit?: (result: R) => void
-  onError?: (error: unknown) => void
-}
-
-export function useMutate<A extends unknown[], R>(
-  fn: (graph: GraphMemory, ...args: A) => Promise<R>,
-  opts?: UseMutateOptions<A, R>,
-): Action<A, R> {
-  const memory = useMemory()
-  const fnRef = useRef(fn)
-  fnRef.current = fn
-  const optsRef = useRef(opts)
-  optsRef.current = opts
-
-  const run = useCallback(
-    async (...args: A): Promise<R> => {
-      const o = optsRef.current
-      const optimistic = o?.optimistic
-      if (typeof optimistic === 'function') {
-        const overlay = memory.overlay((m) => optimistic(m, ...args))
-        try {
-          const result = await fnRef.current(memory, ...args)
-          overlay.commit()
-          o?.onCommit?.(result)
-          return result
-        } catch (error) {
-          if (o?.rollback !== false) overlay.rollback()
-          o?.onError?.(error)
-          throw error
-        }
-      }
-      try {
-        const result = await fnRef.current(memory, ...args)
-        o?.onCommit?.(result)
-        return result
-      } catch (error) {
-        o?.onError?.(error)
-        throw error
-      }
-    },
-    [memory],
-  )
-  return useAction(run)
-}

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

@@ -1,136 +0,0 @@
-import type { AnyBoundNode, TypeNames } from '@astrale-os/kernel-client'
-import type {
-  GatherBuilder,
-  OrderInput,
-  PathLike,
-  QuerySource,
-  WalkOpts,
-} from '@astrale-os/kernel-client/graph'
-import type { Schema } from '@astrale-os/kernel-dsl'
-
-import { rawOf } from '@astrale-os/kernel-client/graph'
-/**
- * useChildren (API §5 + §6) — ONE public symbol, overloaded: pass `opts.type`
- * (over a `BoundNode` parent) for the typed children, or a bare parent for the
- * untyped children. Both ride the SAME windowed memory shape. The untyped floor
- * is a windowed, live read of a node's direct children; the typed twin binds them.
- */
-import { useMemo } from 'react'
-
-import type { TypedChildrenResult } from '../../schema/types.js'
-import type { ReadState, Node, ReadOptions, Windowed } from '../memory/read/envelope.js'
-
-import { useChildren as useChildrenTyped } from '../../schema/bind-read.js'
-import { useRead } from '../memory/read/read.js'
-
-export interface ChildrenOptions extends ReadOptions {
-  /** Restrict to these classes (dual-path descent filter). */
-  classes?: PathLike[]
-  /** Server-ordered by a node prop / `id`. */
-  order?: OrderInput
-  /** Page size; `more.load()` extends. */
-  limit?: number
-  /** `append` (default, infinite) vs `paged` (replace). */
-  window?: 'append' | 'paged'
-}
-
-export interface ChildrenResult extends ReadState, Windowed {
-  /** Ordered, all loaded pages, parent excluded. */
-  readonly children: readonly Node[]
-}
-
-/** A node's direct children — windowed, live; `null` parent is idle (§1.3). */
-function useChildrenUntyped(
-  parent: Node | PathLike | null | undefined,
-  opts?: ChildrenOptions,
-): ChildrenResult {
-  const shape = isIdle(parent) ? null : childrenShape(parent, opts)
-  const r = useRead(shape, opts)
-  return useMemo(
-    () => ({
-      pending: r.pending,
-      error: r.error,
-      live: r.live,
-      seq: r.seq,
-      refetch: r.refetch,
-      children: r.children,
-      more: r.more,
-    }),
-    [r],
-  )
-}
-
-/** Typed: a bound node's children of `opts.type`. */
-export function useChildren<S extends Schema, T extends TypeNames<S>>(
-  parent: AnyBoundNode<S> | null | undefined,
-  opts: ReadOptions & {
-    type: T
-    order?: OrderInput
-    limit?: number
-    window?: 'append' | 'paged'
-  },
-): TypedChildrenResult<S, T>
-/** Untyped: a node's direct children — windowed, live; `null` parent is idle (§1.3). */
-export function useChildren(
-  parent: Node | PathLike | null | undefined,
-  opts?: ChildrenOptions,
-): ChildrenResult
-export function useChildren(
-  parent: unknown,
-  opts?: unknown,
-): ReadState & Windowed & { readonly children: readonly unknown[] } {
-  if (hasType(opts)) {
-    return useChildrenTyped(
-      parent as AnyBoundNode<Schema> | null | undefined,
-      opts as ReadOptions & { type: string },
-    )
-  }
-  return useChildrenUntyped(
-    parent as Node | PathLike | null | undefined,
-    opts as ChildrenOptions | undefined,
-  )
-}
-
-function hasType(opts: unknown): opts is { type: string } {
-  return (
-    typeof opts === 'object' &&
-    opts !== null &&
-    'type' in opts &&
-    (opts as { type?: unknown }).type !== undefined
-  )
-}
-
-// ── internals ────────────────────────────────────────────────────────────────
-
-function isIdle(x: unknown): x is null | undefined {
-  return x === null || x === undefined
-}
-
-function isNode(x: Node | PathLike): x is Node {
-  return typeof x === 'object' && x !== null && 'id' in x && 'class' in x && 'path' in x
-}
-
-/** A parent ref anchored on the node id (stable across rename) or the raw path. */
-function refOf(parent: Node | PathLike): PathLike {
-  return isNode(parent) ? `@${parent.id}` : parent
-}
-
-function walkOptsOf(opts?: ChildrenOptions): WalkOpts | undefined {
-  if (opts === undefined) return undefined
-  const { classes, order, limit } = opts
-  if (classes === undefined && order === undefined && limit === undefined) return undefined
-  return {
-    ...(classes !== undefined ? { classes: classes.map((c) => rawOf(c)) } : {}),
-    ...(order !== undefined ? { order } : {}),
-    ...(limit !== undefined ? { limit } : {}),
-  }
-}
-
-function childrenShape(
-  parent: Node | PathLike,
-  opts?: ChildrenOptions,
-): (q: QuerySource) => GatherBuilder {
-  const ref = refOf(parent)
-  const walk = walkOptsOf(opts)
-  return (q) => q.from(ref).children(walk)
-}

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

@@ -1,13 +0,0 @@
-/**
- * useGraph (API §5) — the memory handle for this subtree (the raw floor plus the
- * memory's optimistic-auto write shorthands). The same scoped memory every
- * graph/schema/nav hook reads.
- */
-import type { GraphMemory } from '@astrale-os/kernel-client/store'
-
-import { useMemory } from '../memory/scope.js'
-
-/** The memory for this subtree — the raw floor plus optimistic-auto shorthands (§5). */
-export function useGraph(): GraphMemory {
-  return useMemory()
-}