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

package/src/navigation/scope.context.tsx

@@ -1,14 +1,9 @@
-import type { GraphMemory, LiveResult, ShapeInput } from '@astrale-os/kernel-client/store'
+import type { GraphStore, StoreQueryResponse } 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 { NodePath } from '@astrale-os/sdk/graph/path'
+import { Query } from '@astrale-os/sdk/query'
+import { Key } from '@astrale-os/sdk/schema'
 import {
   createContext,
   startTransition,
@@ -22,40 +17,40 @@ import {
 
 import type { NavAdapter } from './adapters/adapter.js'
 import type { NavSnapshot, SerializedLocation } from './history.js'
-import type { NavLocation } from './location.js'
+import type { NavLocation, PointResult } from './location.js'
 import type { NavTarget } from './snapshot.js'
 
-import { useMemory } from '../graph/memory/scope.js'
+import { UnsupportedFeatureError } from '../graph/memory/read/envelope.js'
+import { useStoreResource } from '../graph/resource.js'
+import { useGraphStore } from '../graph/store.js'
+import { useShell } from '../session/shell.hook.js'
 import { memoryAdapter } from './adapters/memory.adapter.js'
 import { NavHistory, seedEntries } from './history.js'
-import { buildLocation, parentPath, pathHint, pathOf, useSettled } from './location.js'
+import { buildLocation } from './location.js'
 import { revalidateAndPrune, serializeTarget } from './snapshot.js'
 
-/** 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
+  /** Unsupported until the caller supplies an explicit parent Edge Class. */
+  up(): never
   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
+  up(): never
   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 store: GraphStore
   readonly adapter: NavAdapter
   readonly navigate: MutableNavigate
 }
@@ -63,205 +58,225 @@ export interface NavCtx {
 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),
+    (listener: () => void) => (history === null ? NOOP_UNSUB : history.subscribe(listener)),
     [history],
   )
-  const getSnapshot = useCallback(() => (history !== null ? history.getVersion() : 0), [history])
+  const getSnapshot = useCallback(() => (history === null ? 0 : history.getVersion()), [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],
+/** Caller-scoped canonical point read through the provider's one GraphStore. */
+export function useGraphPoint(target: NodePath | null): PointResult | null {
+  const query = useMemo(
+    () =>
+      target === null
+        ? null
+        : Query.from({ kind: 'node', paths: [target], binding: 'navigation_target' }).select({
+            kind: 'graph',
+          }),
+    [target],
   )
-  const getSnapshot = useCallback(
-    () => (shape !== null ? memory.getSnapshot(shape) : null),
-    [memory, shape],
+  const project = useCallback(
+    (response: StoreQueryResponse<NonNullable<typeof query>>) => {
+      const result = response.result
+      if (result.kind !== 'graph' || result.selection.kind !== 'node') return null
+      const id = result.selection.ids[0]
+      return id === undefined ? null : (result.graph.nodes.find((node) => node.id === id) ?? null)
+    },
+    [query],
   )
-  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+  const resource = useStoreResource(query, 1, project)
+  if (target === null) return null
+  return {
+    node: resource.data ?? null,
+    pending: resource.state === 'loading' || resource.state === 'refreshing',
+    error: resource.error,
+    live: false,
+    seq: 0,
+    refetch: resource.refresh,
+  }
 }
 
-/** The missing-anchor policy — a fallback strategy or a caller-supplied resolver. */
-export type MissingPolicy = 'ancestor' | 'hold' | ((loc: NavLocation) => NavTarget | null)
+type MissingResolver = (location: NavLocation) => NavTarget | null
+export type MissingPolicy = 'hold' | MissingResolver
 
 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'`. */
+  onChange?: (location: NavLocation, snapshot: NavSnapshot) => void
+  /** Default `hold`; parent fallback requires an explicit caller relationship. */
   missing?: MissingPolicy
+  /** Closed codec admission applied before any history or adapter mutation. */
+  admit?: (location: SerializedLocation) => SerializedLocation | null
   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 store = useGraphStore()
+  const shell = useShell()
   const adapterRef = useRef<NavAdapter | null>(null)
   if (adapterRef.current === null) adapterRef.current = props.adapter ?? memoryAdapter()
   const adapter = adapterRef.current
+  if (adapter.kind === 'browser' && shell.hostCapabilities.navigation.history !== 'browser') {
+    throw new Error('Browser navigation is not granted to this Shell.')
+  }
+  const admitRef = useRef(props.admit)
+  admitRef.current = props.admit
+  const admit = (location: SerializedLocation | null): SerializedLocation | null => {
+    if (location === null) return null
+    const portable = admitLocation(location)
+    return admitRef.current?.(portable) ?? portable
+  }
 
   const historyRef = useRef<NavHistory | null>(null)
   if (historyRef.current === null) {
     const seed = seedEntries(
-      adapter.read(),
-      props.restore,
-      props.initial !== undefined ? serializeTarget(props.initial) : null,
+      admit(adapter.read()),
+      props.restore === undefined || props.restore.v !== 1
+        ? undefined
+        : {
+            entries: props.restore.entries.flatMap((entry) => {
+              const accepted = admit(entry)
+              return accepted === null ? [] : [accepted]
+            }),
+            cursor: props.restore.cursor,
+          },
+      props.initial === undefined ? null : admit(serializeTarget(props.initial)),
     )
     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 historyVersion = useHistoryVersion(history)
 
   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())
+    onChangeRef.current?.(buildLocation(history.current, 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 })
+      const location = history.current
+      if (location !== null) adapter.write(location, { 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))
+    const nav = ((to: NavTarget, options?: { replace?: boolean }) => {
+      const replace = options?.replace ?? false
+      const location = admit(serializeTarget(to))
+      if (location === null) throw new TypeError('Navigation target was rejected by its codec.')
+      startTransition(() => commit(history.push(location, 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.up = (): never => {
+      throw new UnsupportedFeatureError('navigation.up requires an explicit parent Edge Class')
     }
     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)
+  }, [history, adapter, fireOnChange, historyVersion])
 
-  // 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 })
+    const seed = history.current
+    if (seed !== null && adapter.read() === null) adapter.write(seed, { replace: true })
     return adapter.subscribe(() => {
-      const loc = adapter.read()
-      if (loc === null) return
+      const location = admit(adapter.read())
+      if (location === null) return
       startTransition(() => {
-        if (history.syncExternal(loc)) fireOnChange()
+        if (history.syncExternal(location)) 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])
+    if (props.restore === undefined) return
+    let current = true
+    void revalidateAndPrune(history, store, shell).then((changed) => {
+      if (!current || !changed) return
+      const accepted = history.current
+      if (accepted === null) adapter.clear({ replace: true })
+      else adapter.write(accepted, { replace: true })
+      fireOnChange()
+    })
+    return () => {
+      current = false
+    }
+  }, [store, shell, history, adapter, props.restore, fireOnChange])
 
-  // 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)
+  const current = history.current
+  const result = useGraphPoint(current?.node ?? null)
+  const handled = useRef<NodePath | 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
+    if (current === null || result === null || result.pending) return
+    if (result.node !== null) {
+      handled.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])
+    if (handled.current === current.node) return
+    handled.current = current.node
+    const policy = missingRef.current ?? 'hold'
+    if (typeof policy === 'function') {
+      const target = policy(buildLocation(current, result))
+      if (target !== null) navigate(target, { replace: true })
+    }
+  }, [current, result, navigate, historyVersion])
 
   const ctx = useMemo<NavCtx>(
-    () => ({ history, memory, adapter, navigate }),
-    [history, memory, adapter, navigate],
+    () => ({ history, store, adapter, navigate }),
+    [history, store, 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
+function admitLocation(location: SerializedLocation): SerializedLocation {
+  if (location === null || typeof location !== 'object' || Array.isArray(location)) {
+    throw new TypeError('Navigation location is invalid.')
+  }
+  const node = NodePath(location.node)
+  let view: Key.View | undefined
+  if (location.view !== undefined) {
+    const key = Key(location.view)
+    if (!Key.ref(key).startsWith('view.')) throw new TypeError('Navigation View key is invalid.')
+    view = key as Key.View
+  }
+  const params: Record<string, string> = {}
+  if (location.params !== undefined) {
+    if (
+      location.params === null ||
+      typeof location.params !== 'object' ||
+      Array.isArray(location.params)
+    ) {
+      throw new TypeError('Navigation params are invalid.')
+    }
+    for (const [key, value] of Object.entries(location.params)) {
+      if (/token|credential|authorization|secret/i.test(key)) {
+        throw new TypeError(`Navigation param '${key}' is sensitive.`)
+      }
+      if (typeof value !== 'string') throw new TypeError(`Navigation param '${key}' is invalid.`)
+      params[key] = value
+    }
   }
-  // '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 })
+  return Object.freeze({
+    node,
+    ...(view === undefined ? {} : { view }),
+    ...(Object.keys(params).length === 0 ? {} : { params: Object.freeze(params) }),
+  })
 }

package/src/navigation/snapshot.ts

@@ -1,78 +1,97 @@
-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'
+import type { GraphStore } from '@astrale-os/kernel-client/store'
+import type { Node } from '@astrale-os/sdk/graph/node'
+import type { NodePath, PathLike } from '@astrale-os/sdk/graph/path'
+import type { Key } from '@astrale-os/sdk/schema'
+import type { Shell } from '@astrale-os/shell'
 
-/**
- * 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 { Path } from '@astrale-os/sdk/graph/path'
+import { Query } from '@astrale-os/sdk/query'
+import { Key as admitKey } from '@astrale-os/sdk/schema'
 
-import type { NavHistory } from './history.js'
-import type { SerializedLocation } from './history.js'
-import type { Node, NodeId } from './location.js'
+import type { NavHistory, SerializedLocation } from './history.js'
 
-/** Everything `navigate()` / `Link` / `initial` accept (API §8.1). */
+/** Canonical navigation inputs; there is no implicit slash-tree or bare-id grammar. */
 export type NavTarget =
-  | NodeId
   | PathLike
   | Node
-  | AnyBoundNode
-  | { node: NodeId | PathLike; view?: NodeRefInput; params?: Record<string, string> }
+  | {
+      readonly node: PathLike | Node
+      readonly view?: Key.View
+      readonly params?: Record<string, string>
+    }
+
+function isNode(value: PathLike | Node): value is Node {
+  return typeof value === 'object' && value !== null && 'id' in value && 'class' in value
+}
+
+function nodePath(value: PathLike | Node): NodePath {
+  return isNode(value) ? Path.id(value.id).raw : Path.from(value).raw
+}
 
-function isRecord(x: unknown): x is Record<string, unknown> {
-  return typeof x === 'object' && x !== null
+function isComposite(
+  value: NavTarget,
+): value is Extract<NavTarget, { readonly node: PathLike | Node }> {
+  return typeof value === 'object' && value !== null && 'node' in value
 }
 
-/** Normalize any {@link NavTarget} to its stored, id-anchored serialization. */
+/** Normalize every target to canonical astrale-node-path-v1 text. */
 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) }
+  if (!isComposite(target)) return { node: nodePath(target) }
+  return {
+    node: nodePath(target.node),
+    ...(target.view === undefined ? {} : { view: viewKey(target.view) }),
+    ...(target.params === undefined ? {} : { params: { ...target.params } }),
   }
-  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> {
+function viewKey(input: string): Key.View {
+  const key = admitKey(input)
+  if (!admitKey.ref(key).startsWith('view.')) throw new TypeError(`Invalid View key '${input}'.`)
+  return key as Key.View
+}
+
+/** Drop restored entries that no longer resolve under the authenticated Graph capability. */
+export async function revalidateAndPrune(
+  history: NavHistory,
+  store: GraphStore,
+  shell: Shell,
+): Promise<boolean> {
   const { entries, cursor } = history.snapshot()
-  const alive = await Promise.all(entries.map((e) => resolves(memory, e.node)))
-  if (alive.every(Boolean)) return
+  const alive = await Promise.all(entries.map((entry) => resolves(store, shell, entry)))
+  if (alive.every(Boolean)) return false
 
   const survivors: SerializedLocation[] = []
   let newCursor = -1
   let fallback = -1
-  entries.forEach((entry, i) => {
-    if (!alive[i]) return
+  entries.forEach((entry, index) => {
+    if (!alive[index]) return
     survivors.push(entry)
-    const idx = survivors.length - 1
-    if (i === cursor) newCursor = idx
-    else if (i < cursor) fallback = idx
+    const next = survivors.length - 1
+    if (index === cursor) newCursor = next
+    else if (index < cursor) fallback = next
   })
   if (newCursor === -1) newCursor = fallback !== -1 ? fallback : survivors.length > 0 ? 0 : -1
   history.reset(survivors, newCursor)
+  return true
 }
 
-async function resolves(memory: GraphMemory, ref: string): Promise<boolean> {
+async function resolves(
+  store: GraphStore,
+  shell: Shell,
+  entry: SerializedLocation,
+): Promise<boolean> {
   try {
-    const result = await memory.query(ref, { live: false })
-    return result.node !== null
+    const query = Query.from({ kind: 'node', paths: [entry.node] }).select({ kind: 'graph' })
+    const response = await store.read(query, { page: { size: 1 } })
+    if (
+      response.result.kind !== 'graph' ||
+      response.result.selection.kind !== 'node' ||
+      response.result.selection.ids.length === 0
+    )
+      return false
+    if (entry.view === undefined) return true
+    const routes = await shell.views.resolve(entry.node)
+    return routes.some((candidate) => candidate.route.key === entry.view)
   } catch {
     return false
   }