@astrale-os/shell-react 0.1.0

package/src/navigation/location.ts

@@ -0,0 +1,122 @@
+import type { LiveResult } from '@astrale-os/kernel-client/store'
+
+import { rawOf } from '@astrale-os/kernel-client/graph'
+/**
+ * NavLocation projection (API §8.1) — the live, id-anchored location a scope
+ * points at (live path, missing flag), its `buildLocation` assembly, the
+ * `useSettled` guard against a one-render false-empty, and the framework-free
+ * path math (parent/chain) the scope and hooks share.
+ */
+import { useEffect, useRef } from 'react'
+
+import type { SerializedLocation } from './history'
+
+/**
+ * The rich graph `Node`, derived from the memory's read envelope — kernel-client
+ * does not re-export `Node` at its root yet (API §14 G8), so shell-react reads it
+ * off `LiveResult` rather than taking a direct kernel-core dependency.
+ */
+export type Node = NonNullable<LiveResult['node']>
+export type NodeId = Node['id']
+
+/** The live, id-anchored location a scope currently points at (API §8.1). */
+export interface NavLocation {
+  /** The anchor — survives rename/move. */
+  readonly id: NodeId
+  /** LIVE projection of the node's current path (empty until first resolve). */
+  readonly path: string
+  /** Live memory node — null while cold, or after the anchor stops resolving. */
+  readonly node: Node | null
+  /** View function ref rendering it, when one is open. */
+  readonly view?: string
+  readonly params: Readonly<Record<string, string>>
+  /** The anchor no longer resolves (deleted / masked). */
+  readonly missing: boolean
+}
+
+const EMPTY_PARAMS: Readonly<Record<string, string>> = Object.freeze({})
+
+/** The idle location a scope with no current entry projects (inert / boot). */
+export const IDLE_LOCATION: NavLocation = {
+  id: '' as NodeId,
+  path: '',
+  node: null,
+  params: EMPTY_PARAMS,
+  missing: false,
+}
+
+/** Project a serialized entry + its live read into the public {@link NavLocation}. */
+export function buildLocation(
+  entry: SerializedLocation | null,
+  result: LiveResult | null,
+  settled: boolean,
+): NavLocation {
+  if (entry === null) return IDLE_LOCATION
+  const node = result?.node ?? null
+  return {
+    id: (node?.id ?? idHint(entry.node)) as NodeId,
+    path: node ? pathOf(node) : pathHint(entry.node),
+    node,
+    ...(entry.view !== undefined ? { view: entry.view } : {}),
+    params: entry.params ?? IDLE_LOCATION.params,
+    missing: settled && node === null,
+  }
+}
+
+/**
+ * Whether a read has definitively settled — data present, a hard error, or a
+ * completed empty fetch. Guards `missing` (and the missing policy) against the
+ * one-render false-empty before a cold shape's first fetch is even in flight.
+ */
+export function useSettled(result: LiveResult | null, key: string | null): boolean {
+  const sawPending = useRef(new Map<string, boolean>())
+  useEffect(() => {
+    if (key !== null && result?.pending === true) sawPending.current.set(key, true)
+  }, [key, result?.pending])
+  if (key === null || result === null) return false
+  if (result.node !== null) return true
+  if (result.error !== undefined) return true
+  return !result.pending && sawPending.current.get(key) === true
+}
+
+// ── path math ──────────────────────────────────────────────────────────────
+
+/** The raw path of a live node (empty when cold). */
+export function pathOf(node: Node | null): string {
+  return node ? rawOf(node.path) : ''
+}
+
+/** Best-effort anchor id from a stored ref (`@<id>` → id, else the raw ref). */
+export function idHint(ref: string): string {
+  return ref.startsWith('@') ? ref.slice(1) : ref
+}
+
+/** Best-effort path from a stored ref (a `/…` ref is already a path). */
+export function pathHint(ref: string): string {
+  return ref.startsWith('/') ? ref : ''
+}
+
+/** The parent absolute path, or null at (or above) root. */
+export function parentPath(raw: string): string | null {
+  const norm = raw.replace(/\/+$/, '')
+  if (norm === '' || norm === '/') return null
+  const idx = norm.lastIndexOf('/')
+  return idx <= 0 ? '/' : norm.slice(0, idx)
+}
+
+/**
+ * The inclusive, root-first path chain for an absolute path — the ancestry the
+ * kernel tree encodes in the slug path (`/a/b/c` → `/`, `/a`, `/a/b`, `/a/b/c`).
+ * The node itself is the last element, so breadcrumbs map the chain directly.
+ */
+export function chainPaths(raw: string): string[] {
+  const norm = raw.replace(/\/+$/, '')
+  if (norm === '' || norm === '/') return ['/']
+  const out = ['/']
+  let acc = ''
+  for (const seg of norm.split('/').filter(Boolean)) {
+    acc += `/${seg}`
+    out.push(acc)
+  }
+  return out
+}

package/src/navigation/scope.context.tsx

@@ -0,0 +1,267 @@
+import type { GraphMemory, LiveResult, ShapeInput } from '@astrale-os/kernel-client/store'
+import type { ReactElement, ReactNode } from 'react'
+
+/**
+ * NavScope (API §8.2) — owns one history stack, wires it to an adapter, and seats
+ * the scope context. Seeds from restore/adapter/initial, revalidates a restored
+ * stack against the memory, mirrors navigations to/from the adapter, and runs the
+ * `missing` policy when the current anchor stops resolving. Also the scope's shared
+ * glue (`NavContext`, the `useSyncExternalStore` reads) and the imperative
+ * `Navigate` surface. Scopes nest.
+ */
+import {
+  createContext,
+  startTransition,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useSyncExternalStore,
+} from 'react'
+
+import type { NavAdapter } from './adapters/adapter'
+import type { NavSnapshot, SerializedLocation } from './history'
+import type { NavLocation } from './location'
+import type { NavTarget } from './snapshot'
+
+import { useMemory } from '../graph/memory/scope'
+import { memoryAdapter } from './adapters/memory.adapter'
+import { NavHistory, seedEntries } from './history'
+import { buildLocation, parentPath, pathHint, pathOf, useSettled } from './location'
+import { revalidateAndPrune, serializeTarget } from './snapshot'
+
+/** The imperative navigation surface (API §8.2). */
+export interface Navigate {
+  (to: NavTarget, opts?: { replace?: boolean }): void
+  back(): void
+  forward(): void
+  /** To the parent via `has_parent`; no-op at root or while the node is cold. */
+  up(): void
+  readonly canBack: boolean
+  readonly canForward: boolean
+}
+
+/** A mutable `Navigate` — the scope stamps `canBack`/`canForward` onto it live. */
+export interface MutableNavigate {
+  (to: Parameters<Navigate>[0], opts?: Parameters<Navigate>[1]): void
+  back(): void
+  forward(): void
+  up(): void
+  canBack: boolean
+  canForward: boolean
+}
+
+/** The nearest scope's shared handle (stable for the scope's lifetime). */
+export interface NavCtx {
+  readonly history: NavHistory
+  readonly memory: GraphMemory
+  readonly adapter: NavAdapter
+  readonly navigate: MutableNavigate
+}
+
+export const NavContext = createContext<NavCtx | null>(null)
+NavContext.displayName = 'AstraleNavContext'
+
+/** The nearest scope, or throw — the door every public nav hook goes through. */
+export function useNavCtx(): NavCtx {
+  const ctx = useContext(NavContext)
+  if (ctx === null) throw new Error('nav hooks must be used within a <NavScope>')
+  return ctx
+}
+
+/** The nearest scope or null (for `useAncestors`, usable outside a scope). */
+export function useOptionalNavCtx(): NavCtx | null {
+  return useContext(NavContext)
+}
+
+const NOOP_UNSUB = (): void => undefined
+
+/** Re-render on any history change (no-op subscription when there is no scope). */
+export function useHistoryVersion(history: NavHistory | null): number {
+  const subscribe = useCallback(
+    (cb: () => void) => (history !== null ? history.subscribe(cb) : NOOP_UNSUB),
+    [history],
+  )
+  const getSnapshot = useCallback(() => (history !== null ? history.getVersion() : 0), [history])
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+}
+
+/**
+ * Subscribe to one memory shape, tear-free. `shape` must be stable per read
+ * (a string ref, or a builder memoized upstream); a null shape is idle (no I/O).
+ */
+export function useMemoryShape(memory: GraphMemory, shape: ShapeInput | null): LiveResult | null {
+  const subscribe = useCallback(
+    (cb: () => void) => (shape !== null ? memory.subscribe(shape, cb) : NOOP_UNSUB),
+    [memory, shape],
+  )
+  const getSnapshot = useCallback(
+    () => (shape !== null ? memory.getSnapshot(shape) : null),
+    [memory, shape],
+  )
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+}
+
+/** The missing-anchor policy — a fallback strategy or a caller-supplied resolver. */
+export type MissingPolicy = 'ancestor' | 'hold' | ((loc: NavLocation) => NavTarget | null)
+
+export interface NavScopeProps {
+  /** Persistence seam. Default: a fresh {@link memoryAdapter} (captured once). */
+  adapter?: NavAdapter
+  /** A saved snapshot — revalidated against the memory; dead entries dropped. */
+  restore?: NavSnapshot
+  /** Seed target when neither `adapter.read()` nor `restore` yields one. */
+  initial?: NavTarget
+  /** Fires per navigation with the new location + snapshot — persist here. */
+  onChange?: (loc: NavLocation, snapshot: NavSnapshot) => void
+  /** What to do when the current anchor stops resolving. Default `'ancestor'`. */
+  missing?: MissingPolicy
+  children: ReactNode
+}
+
+export function NavScope(props: NavScopeProps): ReactElement {
+  const memory = useMemory()
+
+  // Adapter + history are captured ONCE — an inline `adapter={memoryAdapter()}`
+  // (or a re-passed `initial`) must never rebuild the scope's state.
+  const adapterRef = useRef<NavAdapter | null>(null)
+  if (adapterRef.current === null) adapterRef.current = props.adapter ?? memoryAdapter()
+  const adapter = adapterRef.current
+
+  const historyRef = useRef<NavHistory | null>(null)
+  if (historyRef.current === null) {
+    const seed = seedEntries(
+      adapter.read(),
+      props.restore,
+      props.initial !== undefined ? serializeTarget(props.initial) : null,
+    )
+    historyRef.current = new NavHistory(seed.entries, seed.cursor)
+  }
+  const history = historyRef.current
+
+  // Latest-value refs so the stable navigate + effects read current inputs.
+  const memoryRef = useRef(memory)
+  memoryRef.current = memory
+  const onChangeRef = useRef(props.onChange)
+  onChangeRef.current = props.onChange
+  const missingRef = useRef(props.missing)
+  missingRef.current = props.missing
+
+  const fireOnChange = useCallback((): void => {
+    const cb = onChangeRef.current
+    if (cb === undefined) return
+    const entry = history.current
+    const live = entry !== null ? memoryRef.current.peek(entry.node) : null
+    cb(buildLocation(entry, live, (live?.node ?? null) !== null), history.snapshot())
+  }, [history])
+
+  // The one stable navigate object; hooks re-stamp canBack/canForward onto it.
+  const navigate = useMemo<MutableNavigate>(() => {
+    const commit = (changed: boolean, replace: boolean): void => {
+      if (!changed) return
+      const loc = history.current
+      if (loc !== null) adapter.write(loc, { replace })
+      fireOnChange()
+    }
+    const nav = ((to: NavTarget, opts?: { replace?: boolean }) => {
+      const loc = serializeTarget(to)
+      const replace = opts?.replace ?? false
+      startTransition(() => commit(history.push(loc, replace), replace))
+    }) as MutableNavigate
+    nav.back = () => startTransition(() => commit(history.back(), false))
+    nav.forward = () => startTransition(() => commit(history.forward(), false))
+    nav.up = () => {
+      const entry = history.current
+      if (entry === null) return
+      const live = memoryRef.current.peek(entry.node)
+      const raw = live?.node ? pathOf(live.node) : pathHint(entry.node)
+      const parent = raw !== '' ? parentPath(raw) : null
+      if (parent !== null) nav(parent)
+    }
+    nav.canBack = history.canBack
+    nav.canForward = history.canForward
+    return nav
+  }, [history, adapter, fireOnChange])
+
+  // Re-render the scope on every navigation so the missing watcher tracks the
+  // current entry (consumers re-render through their own version subscription).
+  const historyVersion = useHistoryVersion(history)
+
+  // Mount: canonicalize a non-adapter seed into the adapter, then relay external
+  // (browser/URL) changes back into the history.
+  useEffect(() => {
+    const seedLoc = history.current
+    if (seedLoc !== null && adapter.read() === null) adapter.write(seedLoc, { replace: true })
+    return adapter.subscribe(() => {
+      const loc = adapter.read()
+      if (loc === null) return
+      startTransition(() => {
+        if (history.syncExternal(loc)) fireOnChange()
+      })
+    })
+  }, [history, adapter, fireOnChange])
+
+  // Restore revalidation — once, against the shared memory.
+  const revalidatedRef = useRef(false)
+  useEffect(() => {
+    if (revalidatedRef.current || props.restore === undefined) return
+    revalidatedRef.current = true
+    void revalidateAndPrune(history, memory)
+  }, [memory, props.restore, history])
+
+  // Missing-anchor watcher: the current entry's live read drives the policy.
+  const currentShape = history.current?.node ?? null
+  const currentResult = useMemoryShape(memory, currentShape)
+  const settled = useSettled(currentResult, currentShape)
+  const lastPathRef = useRef<string | null>(null)
+  const handledRef = useRef<string | null>(null)
+  useEffect(() => {
+    const resolved = currentResult?.node ?? null
+    if (resolved !== null) lastPathRef.current = pathOf(resolved)
+  }, [currentResult?.node])
+  useEffect(() => {
+    const entry = history.current
+    if (entry === null) return
+    if ((currentResult?.node ?? null) !== null) {
+      handledRef.current = null
+      return
+    }
+    if (!settled || handledRef.current === entry.node) return
+    handledRef.current = entry.node
+    applyMissingPolicy(entry, missingRef.current ?? 'ancestor', {
+      lastPath: lastPathRef.current,
+      result: currentResult,
+      navigate,
+    })
+    // historyVersion re-runs this when the current entry changes.
+  }, [settled, currentResult, history, navigate, historyVersion])
+
+  const ctx = useMemo<NavCtx>(
+    () => ({ history, memory, adapter, navigate }),
+    [history, memory, adapter, navigate],
+  )
+
+  return <NavContext.Provider value={ctx}>{props.children}</NavContext.Provider>
+}
+
+function applyMissingPolicy(
+  entry: SerializedLocation,
+  policy: MissingPolicy,
+  deps: {
+    lastPath: string | null
+    result: LiveResult | null
+    navigate: MutableNavigate
+  },
+): void {
+  if (policy === 'hold') return
+  if (typeof policy === 'function') {
+    const target = policy(buildLocation(entry, deps.result, true))
+    if (target !== null) deps.navigate(target, { replace: true })
+    return
+  }
+  // 'ancestor': climb one level toward a resolvable ancestor (repeats per settle).
+  const raw = deps.lastPath ?? pathHint(entry.node)
+  const parent = raw !== '' ? parentPath(raw) : null
+  if (parent !== null) deps.navigate(parent, { replace: true })
+}

package/src/navigation/snapshot.ts

@@ -0,0 +1,79 @@
+import type { AnyBoundNode, NodeRefInput } from '@astrale-os/kernel-client'
+import type { PathLike } from '@astrale-os/kernel-client/graph'
+import type { GraphMemory } from '@astrale-os/kernel-client/store'
+
+/**
+ * NavSnapshot serialize/restore (API §8.1/§8.2) — the `NavTarget` input space, the
+ * `serializeTarget` normalization into the id-anchored stored form, and the
+ * restore-time `revalidateAndPrune` that drops dead entries against the memory.
+ */
+import { normalizeRef } from '@astrale-os/kernel-client'
+
+import type { NavHistory } from './history'
+import type { SerializedLocation } from './history'
+import type { Node, NodeId } from './location'
+
+/** Everything `navigate()` / `Link` / `initial` accept (API §8.1). */
+export type NavTarget =
+  | NodeId
+  | PathLike
+  | Node
+  | AnyBoundNode
+  | { node: NodeId | PathLike; view?: NodeRefInput; params?: Record<string, string> }
+
+function isRecord(x: unknown): x is Record<string, unknown> {
+  return typeof x === 'object' && x !== null
+}
+
+/** Normalize any {@link NavTarget} to its stored, id-anchored serialization. */
+export function serializeTarget(target: NavTarget): SerializedLocation {
+  if (typeof target === 'string') return { node: normalizeRef(target) }
+  if (isRecord(target) && 'node' in target) {
+    const t = target as { node: NodeRefInput; view?: NodeRefInput; params?: Record<string, string> }
+    return {
+      node: normalizeRef(t.node),
+      ...(t.view !== undefined ? { view: normalizeRef(t.view) } : {}),
+      ...(t.params !== undefined ? { params: { ...t.params } } : {}),
+    }
+  }
+  // A Node / BoundNode carries `id` (id-anchored, so rename/move survive) and `path`;
+  // anything else is a typed `Path` value → its raw address.
+  if (isRecord(target) && 'id' in target && 'path' in target) {
+    return { node: normalizeRef((target as { id: NodeRefInput }).id) }
+  }
+  return { node: normalizeRef(target as NodeRefInput) }
+}
+
+/**
+ * Revalidate a restored stack against the memory and drop dead entries (API §8.2).
+ * Each entry is point-read one-shot; a null/failed read is a dead anchor. The
+ * cursor re-lands on the surviving current entry, else the nearest survivor
+ * before it.
+ */
+export async function revalidateAndPrune(history: NavHistory, memory: GraphMemory): Promise<void> {
+  const { entries, cursor } = history.snapshot()
+  const alive = await Promise.all(entries.map((e) => resolves(memory, e.node)))
+  if (alive.every(Boolean)) return
+
+  const survivors: SerializedLocation[] = []
+  let newCursor = -1
+  let fallback = -1
+  entries.forEach((entry, i) => {
+    if (!alive[i]) return
+    survivors.push(entry)
+    const idx = survivors.length - 1
+    if (i === cursor) newCursor = idx
+    else if (i < cursor) fallback = idx
+  })
+  if (newCursor === -1) newCursor = fallback !== -1 ? fallback : survivors.length > 0 ? 0 : -1
+  history.reset(survivors, newCursor)
+}
+
+async function resolves(memory: GraphMemory, ref: string): Promise<boolean> {
+  try {
+    const result = await memory.query(ref, { live: false })
+    return result.node !== null
+  } catch {
+    return false
+  }
+}