@astrale-os/shell-react 0.2.8 → 0.2.10-beta.2

package/src/intents/envelope.ts

@@ -3,28 +3,13 @@
  * a registry entry, the wire constants, and `intentMessage` — the single builder
  * both directions (send + reply) share.
  */
-import type { IntentMessage, IntentRegistry } from '@astrale-os/shell'
+import type { IntentMessage, IntentRegistry, PayloadOf, ReplyOf } from '@astrale-os/shell'
 
-/**
- * Payload of a registry entry: the `{ payload }` field for the wrapped shape,
- * else the whole entry (a legacy bare-payload augmentation). Robust to both, so
- * bare augmentations keep compiling unchanged.
- */
-export type IntentPayload<K extends keyof IntentRegistry> = IntentRegistry[K] extends {
-  payload: infer P
-}
-  ? P
-  : IntentRegistry[K]
+/** Payload declared by the canonical Shell intent registry entry. */
+export type IntentPayload<K extends keyof IntentRegistry> = PayloadOf<K>
 
-/**
- * Reply of a registry entry: the `{ reply }` field when declared, else `void`
- * (bare-payload and today's reply-less entries — forward-compatible with G4).
- */
-export type IntentReply<K extends keyof IntentRegistry> = IntentRegistry[K] extends {
-  reply: infer R
-}
-  ? R
-  : void
+/** Reply declared by the canonical Shell intent registry entry. */
+export type IntentReply<K extends keyof IntentRegistry> = ReplyOf<K>
 
 /** Sentinel `ctx.sender` carries for a parent-delivered intent (the shell stamps it). */
 export const PARENT_SENDER = '<parent>'
@@ -35,9 +20,8 @@ export const INTENT_REPLY = 'intentReply'
 export const NOOP = (): void => {}
 
 /**
- * Build an intent wire message. Bare-vs-wrapped payload variance (§11 pin) is
- * erased on the wire — the receiver reads `envelope.payload` verbatim; the cast
- * bridges the correlated name↔payload the union type cannot express.
+ * Build an intent wire message. The cast bridges the correlated name↔payload
+ * relation that the generic union type cannot express.
  */
 export function intentMessage(
   name: string,

package/src/intents/send-intent.hook.ts

@@ -1,108 +1,53 @@
-import type { IntentMessage, IntentRegistry } from '@astrale-os/shell'
+import type { IntentRegistry, RequestIntentOptions } from '@astrale-os/shell'
 
-/**
- * useSendIntent (API §11) — a stable typed sender. Each call attaches a
- * `correlationId`, subscribes for the matching `intentReply` on the origin channel
- * BEFORE sending, then resolves with the reply's result. The promise also resolves
- * (`void`) if the target window closes or this hook unmounts — a pending reply
- * never strands.
- */
+import { requestChildIntent, requestIntent } from '@astrale-os/shell'
 import { useCallback, useEffect, useRef } from 'react'
 
 import type { IntentPayload, IntentReply } from './envelope.js'
 
 import { useShell } from '../session/shell.hook.js'
-import { INTENT_REPLY, NOOP, intentMessage } from './envelope.js'
 import { resolveIntentTarget } from './resolve-intent-target.js'
 
-/** The typed sender returned by {@link useSendIntent}. */
+/** Typed request sender backed exclusively by Shell's core correlation implementation. */
 export interface SendIntent {
   <K extends keyof IntentRegistry>(
     name: K,
     payload: IntentPayload<K>,
-    /** `to`: `'parent'` (reserved) or a child windowId. Default: the parent, if any. */
-    opts?: { to?: 'parent' | string },
-  ): Promise<IntentReply<K> | void>
+    options?: RequestIntentOptions & { readonly to?: 'parent' | string },
+  ): Promise<IntentReply<K>>
 }
 
 export function useSendIntent(): SendIntent {
   const shell = useShell()
-  // Unmount settlers for in-flight sends, so a pending reply resolves on teardown.
-  const pendingRef = useRef<Set<() => void>>(new Set())
+  const lifetime = useRef(new AbortController())
+
   useEffect(() => {
-    const pending = pendingRef.current
-    return () => {
-      for (const settle of pending) settle()
-      pending.clear()
-    }
+    const controller = lifetime.current.signal.aborted ? new AbortController() : lifetime.current
+    lifetime.current = controller
+    return () => controller.abort(new Error('Intent requester unmounted'))
   }, [])
 
   return useCallback(
     <K extends keyof IntentRegistry>(
       name: K,
       payload: IntentPayload<K>,
-      opts?: { to?: 'parent' | string },
-    ): Promise<IntentReply<K> | void> => {
-      const target = resolveIntentTarget(shell, opts?.to)
+      options?: RequestIntentOptions & { readonly to?: 'parent' | string },
+    ): Promise<IntentReply<K>> => {
+      const target = resolveIntentTarget(shell, options?.to)
       if (target.kind === 'invalid') {
         return Promise.reject(new Error(`useSendIntent: ${target.reason}`))
       }
-      const correlationId = crypto.randomUUID()
-      const message = intentMessage(name, payload, correlationId)
-      const pending = pendingRef.current
-
-      return new Promise<IntentReply<K> | void>((resolve, reject) => {
-        let done = false
-        let offReply = NOOP
-        let offClose = NOOP
-        const onUnmount = (): void => settle(undefined)
-        function settle(value: IntentReply<K> | void): void {
-          if (done) return
-          done = true
-          offReply()
-          offClose()
-          pending.delete(onUnmount)
-          resolve(value)
-        }
-        function fail(error: Error): void {
-          if (done) return
-          done = true
-          offReply()
-          offClose()
-          pending.delete(onUnmount)
-          reject(error)
-        }
-        const onReply = (m: IntentMessage): void => {
-          if (m.envelope.name !== INTENT_REPLY) return
-          const reply = m.envelope.payload as {
-            correlationId: string
-            result?: unknown
-            error?: { message: string }
-          }
-          if (reply.correlationId !== correlationId) return
-          if (reply.error) {
-            fail(new Error(reply.error.message))
-            return
-          }
-          settle(reply.result as IntentReply<K>)
-        }
-
-        pending.add(onUnmount)
-        if (target.kind === 'parent') {
-          const parent = shell.parent!
-          offReply = parent.on('intent', onReply)
-          parent.send(message)
-        } else {
-          const { windowId } = target
-          offReply = shell.children.on('intent', (wid, m) => {
-            if (wid === windowId) onReply(m)
-          })
-          offClose = shell.children.onClose((wid) => {
-            if (wid === windowId) settle(undefined)
-          })
-          shell.children.send(windowId, message)
-        }
-      })
+      const signal =
+        options?.signal === undefined
+          ? lifetime.current.signal
+          : AbortSignal.any([lifetime.current.signal, options.signal])
+      const requestOptions: RequestIntentOptions = {
+        signal,
+        ...(options?.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+      }
+      return target.kind === 'parent'
+        ? requestIntent(shell.parent!, name, payload, requestOptions)
+        : requestChildIntent(shell.children, target.windowId, name, payload, requestOptions)
     },
     [shell],
   )

package/src/navigation/adapters/adapter.ts

@@ -6,8 +6,11 @@
 import type { SerializedLocation } from '../history.js'
 
 export interface NavAdapter {
+  readonly kind: 'memory' | 'browser'
   read(): SerializedLocation | null
   write(loc: SerializedLocation, opts: { replace: boolean }): void
+  /** Remove only this adapter's owned projection when no history entry survives. */
+  clear(opts: { replace: boolean }): void
   subscribe(onExternalChange: () => void): () => void
   href?(loc: SerializedLocation): string
 }

package/src/navigation/adapters/memory.adapter.ts

@@ -10,10 +10,14 @@ export function memoryAdapter(initial?: SerializedLocation): NavAdapter {
   let current: SerializedLocation | null = initial ?? null
   const listeners = new Set<() => void>()
   return {
+    kind: 'memory',
     read: () => current,
     write: (loc) => {
       current = loc
     },
+    clear: () => {
+      current = null
+    },
     subscribe: (cb) => {
       listeners.add(cb)
       return () => listeners.delete(cb)

package/src/navigation/adapters/url.adapter.ts

@@ -1,3 +1,6 @@
+import { NodePath } from '@astrale-os/sdk/graph/path'
+import { Key } from '@astrale-os/sdk/schema'
+
 /**
  * urlAdapter (API §8.1) — the History-API adapter: mirrors the location into the
  * query string (URL form → `<a href>`), owning the nav query keys (`param`,
@@ -6,35 +9,62 @@
 import type { SerializedLocation } from '../history.js'
 import type { NavAdapter } from './adapter.js'
 
-const VIEW_KEY = 'view'
+const VIEW_KEY = 'astrale.view'
+const PARAM_PREFIX = 'astrale.param.'
 
 /** History-API adapter — the location lives in the query string. */
 export function urlAdapter(opts?: { param?: string }): NavAdapter {
-  const param = opts?.param ?? 'node'
+  const param = opts?.param ?? 'astrale.node'
   const hasWindow = (): boolean => typeof window !== 'undefined'
 
   const build = (loc: SerializedLocation): string => {
     const url = new URL(window.location.href)
-    const sp = new URLSearchParams()
+    const sp = url.searchParams
     sp.set(param, loc.node)
     if (loc.view !== undefined) sp.set(VIEW_KEY, loc.view)
+    else sp.delete(VIEW_KEY)
+    for (const key of sp.keys()) if (key.startsWith(PARAM_PREFIX)) sp.delete(key)
     for (const [k, v] of Object.entries(loc.params ?? {})) {
-      if (k !== param && k !== VIEW_KEY) sp.set(k, v)
+      if (isSensitive(k)) throw new TypeError(`Navigation param '${k}' is sensitive.`)
+      sp.set(`${PARAM_PREFIX}${k}`, v)
     }
     url.search = sp.toString()
     return `${url.pathname}${url.search}${url.hash}`
   }
 
+  const clear = (): string => {
+    const url = new URL(window.location.href)
+    const sp = url.searchParams
+    sp.delete(param)
+    sp.delete(VIEW_KEY)
+    for (const key of sp.keys()) if (key.startsWith(PARAM_PREFIX)) sp.delete(key)
+    url.search = sp.toString()
+    return `${url.pathname}${url.search}${url.hash}`
+  }
+
   return {
+    kind: 'browser',
     read() {
       if (!hasWindow()) return null
       const sp = new URL(window.location.href).searchParams
-      const node = sp.get(param)
-      if (node === null) return null
-      const view = sp.get(VIEW_KEY) ?? undefined
+      const rawNode = sp.get(param)
+      if (rawNode === null) return null
+      let node
+      let view
+      try {
+        node = NodePath(rawNode)
+        const rawView = sp.get(VIEW_KEY)
+        if (rawView !== null) {
+          const admitted = Key(rawView)
+          if (!Key.ref(admitted).startsWith('view.')) throw new TypeError('Invalid View key.')
+          view = admitted as Key.View
+        }
+      } catch {
+        return null
+      }
       const params: Record<string, string> = {}
       for (const [k, v] of sp) {
-        if (k !== param && k !== VIEW_KEY) params[k] = v
+        if (k.startsWith(PARAM_PREFIX)) params[k.slice(PARAM_PREFIX.length)] = v
       }
       return {
         node,
@@ -48,6 +78,12 @@ export function urlAdapter(opts?: { param?: string }): NavAdapter {
       if (replace) window.history.replaceState(null, '', href)
       else window.history.pushState(null, '', href)
     },
+    clear({ replace }) {
+      if (!hasWindow()) return
+      const href = clear()
+      if (replace) window.history.replaceState(null, '', href)
+      else window.history.pushState(null, '', href)
+    },
     subscribe(cb) {
       if (!hasWindow()) return () => undefined
       const handler = (): void => cb()
@@ -59,3 +95,7 @@ export function urlAdapter(opts?: { param?: string }): NavAdapter {
     },
   }
 }
+
+function isSensitive(key: string): boolean {
+  return /token|credential|authorization|secret/i.test(key)
+}

package/src/navigation/codec.ts

@@ -0,0 +1,190 @@
+import type { Key } from '@astrale-os/sdk/schema'
+import type { ReactElement, ReactNode } from 'react'
+
+import { Path } from '@astrale-os/sdk/graph/path'
+import { Key as admitKey } from '@astrale-os/sdk/schema'
+import { createElement } from 'react'
+
+import type { NavAdapter } from './adapters/adapter.js'
+import type { NavSnapshot, SerializedLocation } from './history.js'
+
+import { NavScope } from './scope.context.js'
+import { useNavCtx } from './scope.context.js'
+import { useHistoryVersion } from './scope.context.js'
+
+export interface NavigationParam<Value> {
+  encode(value: Value): string
+  decode(value: string | undefined): Value
+}
+
+export function pathParam(_name: string): NavigationParam<Path> {
+  return Object.freeze({
+    encode: (value: Path) => Path.from(value).raw,
+    decode(value: string | undefined) {
+      if (value === undefined) throw new TypeError('Navigation target is missing.')
+      return Path.parse(value)
+    },
+  })
+}
+
+export function enumParam<const Values extends readonly [string, ...string[]]>(
+  values: Values,
+  fallback: Values[number],
+): NavigationParam<Values[number]> {
+  if (!values.includes(fallback)) throw new TypeError('Navigation enum fallback is not admitted.')
+  return Object.freeze({
+    encode(value: Values[number]) {
+      if (!values.includes(value)) throw new TypeError(`Invalid navigation enum value '${value}'.`)
+      return value
+    },
+    decode(value: string | undefined) {
+      if (value === undefined) return fallback
+      if (!values.includes(value)) throw new TypeError(`Invalid navigation enum value '${value}'.`)
+      return value as Values[number]
+    },
+  })
+}
+
+export type NavigationParams = Readonly<Record<string, NavigationParam<unknown>>>
+
+export interface LocationDefinition<Target, Params extends NavigationParams> {
+  readonly view: Key.View
+  readonly target: NavigationParam<Target>
+  readonly params: Params
+}
+
+export function location<
+  Target,
+  const Params extends NavigationParams = Readonly<Record<never, never>>,
+>(input: {
+  readonly view: Key.View | { readonly key: Key.View }
+  readonly target: NavigationParam<Target>
+  readonly params?: Params
+}): LocationDefinition<Target, Params> {
+  return Object.freeze({
+    view: viewKey(typeof input.view === 'string' ? input.view : input.view.key),
+    target: input.target,
+    params: Object.freeze({ ...input.params }) as Params,
+  })
+}
+
+type ValueOf<Codec> = Codec extends NavigationParam<infer Value> ? Value : never
+type RouteTarget<
+  Routes extends Readonly<Record<string, LocationDefinition<unknown, NavigationParams>>>,
+> = {
+  [Name in keyof Routes]: Readonly<{
+    name: Name
+    target: ValueOf<Routes[Name]['target']>
+    params: Readonly<{
+      [Param in keyof Routes[Name]['params']]: ValueOf<Routes[Name]['params'][Param]>
+    }>
+  }>
+}[keyof Routes]
+
+export type NavigationRoutes = Readonly<
+  Record<string, LocationDefinition<unknown, NavigationParams>>
+>
+
+export interface NavigationDefinition<Routes extends NavigationRoutes = NavigationRoutes> {
+  readonly routes: Routes
+  encode(target: RouteTarget<Routes>): SerializedLocation
+  decode(location: SerializedLocation): RouteTarget<Routes> | null
+  admit(location: SerializedLocation): SerializedLocation | null
+}
+
+export function defineNavigation<const Routes extends NavigationRoutes>(
+  routes: Routes,
+): NavigationDefinition<Routes> {
+  const names = Object.keys(routes).sort() as (keyof Routes)[]
+  const byView = new Map(names.map((name) => [routes[name]!.view, name] as const))
+  if (byView.size !== names.length) throw new TypeError('Navigation Views must be unique.')
+  const definition: NavigationDefinition<Routes> = {
+    routes: Object.freeze({ ...routes }),
+    encode(target) {
+      const route = routes[target.name]
+      if (route === undefined)
+        throw new TypeError(`Unknown navigation location '${String(target.name)}'.`)
+      const params = Object.fromEntries(
+        Object.entries(route.params).map(([name, codec]) => [
+          name,
+          codec.encode((target.params as Record<string, unknown>)[name]),
+        ]),
+      )
+      return Object.freeze({
+        node: Path.parse(route.target.encode(target.target)).raw,
+        view: route.view,
+        ...(Object.keys(params).length === 0 ? {} : { params: Object.freeze(params) }),
+      })
+    },
+    decode(serialized) {
+      if (serialized.view === undefined) return null
+      const name = byView.get(serialized.view)
+      if (name === undefined) return null
+      const route = routes[name]!
+      try {
+        const params = Object.fromEntries(
+          Object.entries(route.params).map(([param, codec]) => [
+            param,
+            codec.decode(serialized.params?.[param]),
+          ]),
+        )
+        if (Object.keys(serialized.params ?? {}).some((param) => !(param in route.params)))
+          return null
+        return Object.freeze({
+          name,
+          target: route.target.decode(serialized.node),
+          params: Object.freeze(params),
+        }) as RouteTarget<Routes>
+      } catch {
+        return null
+      }
+    },
+    admit(serialized) {
+      const decoded = definition.decode(serialized)
+      return decoded === null ? null : definition.encode(decoded)
+    },
+  }
+  return Object.freeze(definition)
+}
+
+export function NavigationScope<Routes extends NavigationRoutes>(props: {
+  readonly navigation: NavigationDefinition<Routes>
+  readonly adapter?: NavAdapter
+  readonly restore?: NavSnapshot
+  readonly initial?: RouteTarget<Routes>
+  readonly children: ReactNode
+}): ReactElement {
+  return createElement(NavScope, {
+    ...(props.adapter === undefined ? {} : { adapter: props.adapter }),
+    ...(props.restore === undefined ? {} : { restore: props.restore }),
+    ...(props.initial === undefined ? {} : { initial: props.navigation.encode(props.initial) }),
+    admit: props.navigation.admit,
+    children: props.children,
+  })
+}
+
+export function useNavigation<Routes extends NavigationRoutes>(
+  navigation: NavigationDefinition<Routes>,
+) {
+  const context = useNavCtx()
+  useHistoryVersion(context.history)
+  const current = context.history.current
+  return Object.freeze({
+    location: current === null ? null : navigation.decode(current),
+    push: (target: RouteTarget<Routes>) => context.navigate(navigation.encode(target)),
+    replace: (target: RouteTarget<Routes>) =>
+      context.navigate(navigation.encode(target), { replace: true }),
+    back: context.navigate.back,
+    forward: context.navigate.forward,
+    snapshot: () => context.history.snapshot(),
+  })
+}
+
+export type NavigationTarget<Definition> =
+  Definition extends NavigationDefinition<infer Routes> ? RouteTarget<Routes> : never
+
+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
+}

package/src/navigation/history.ts

@@ -4,19 +4,21 @@
  * (`SerializedLocation`/`NavSnapshot` + equality/clone), and the seed precedence.
  * Source of truth for back/forward; the adapter is a projection sink around it.
  */
+import type { NodePath } from '@astrale-os/sdk/graph/path'
+import type { Key } from '@astrale-os/sdk/schema'
 
 /** The serializable projection persisted in history / URLs / snapshots. */
 export interface SerializedLocation {
-  node: string
-  view?: string
-  params?: Record<string, string>
+  readonly node: NodePath
+  readonly view?: Key.View
+  readonly params?: Readonly<Record<string, string>>
 }
 
 /** A versioned history snapshot — round-trips through `NavScope.restore`. */
 export interface NavSnapshot {
-  v: 1
-  entries: SerializedLocation[]
-  cursor: number
+  readonly v: 1
+  readonly entries: readonly SerializedLocation[]
+  readonly cursor: number
 }
 
 /** Structural equality of two serialized locations (node + view + params). */
@@ -24,7 +26,10 @@ export function sameLocation(a: SerializedLocation, b: SerializedLocation): bool
   return a.node === b.node && a.view === b.view && sameParams(a.params, b.params)
 }
 
-function sameParams(a?: Record<string, string>, b?: Record<string, string>): boolean {
+function sameParams(
+  a?: Readonly<Record<string, string>>,
+  b?: Readonly<Record<string, string>>,
+): boolean {
   if (a === b) return true
   const ak = a ? Object.keys(a) : []
   const bk = b ? Object.keys(b) : []
@@ -74,7 +79,11 @@ export class NavHistory {
   }
 
   snapshot(): NavSnapshot {
-    return { v: 1, entries: this.entries.map(cloneLocation), cursor: this.cursor }
+    return Object.freeze({
+      v: 1 as const,
+      entries: Object.freeze(this.entries.map(cloneLocation)),
+      cursor: this.cursor,
+    })
   }
 
   /** Push (or replace the current entry with) a location. No-op on same location. */
@@ -129,8 +138,8 @@ export class NavHistory {
   }
 
   /** Replace the whole stack (restore revalidation prune). */
-  reset(entries: SerializedLocation[], cursor: number): void {
-    this.entries = entries
+  reset(entries: readonly SerializedLocation[], cursor: number): void {
+    this.entries = [...entries]
     this.cursor = cursor
     this.emit()
   }
@@ -151,7 +160,7 @@ export class NavHistory {
  */
 export function seedEntries(
   fromAdapter: SerializedLocation | null,
-  restore: { entries: SerializedLocation[]; cursor: number } | undefined,
+  restore: { readonly entries: readonly SerializedLocation[]; readonly cursor: number } | undefined,
   initialSerialized: SerializedLocation | null,
 ): { entries: SerializedLocation[]; cursor: number } {
   if (restore !== undefined && restore.entries.length > 0) {

package/src/navigation/hooks/ancestors.hook.ts

@@ -1,71 +1,21 @@
-import type { PathLike } from '@astrale-os/kernel-client/graph'
-import type { LiveResult, ShapeInput } from '@astrale-os/kernel-client/store'
-
-/**
- * useAncestors (API §8.2) — the live, inclusive root-first ancestor chain of a
- * node (a move re-renders it). Defaults to the nearest scope's location node;
- * passing a node/path makes it usable outside a scope. Drops any masked ancestor.
- */
-import { useMemo } from 'react'
+import type { Node } from '@astrale-os/sdk/graph/node'
+import type { PathLike } from '@astrale-os/sdk/graph/path'
 
 import type { ReadState } from '../../graph/memory/read/envelope.js'
-import type { Node } from '../location.js'
 
-import { idleReadState } from '../../graph/memory/read/idle.js'
-import { useMemory } from '../../graph/memory/scope.js'
-import { chainPaths, pathHint, pathOf } from '../location.js'
-import { useHistoryVersion, useOptionalNavCtx, useMemoryShape } from '../scope.context.js'
-import { serializeTarget } from '../snapshot.js'
+import { unsupportedReadState } from '../../graph/memory/read/envelope.js'
+
+const EMPTY_CHAIN: readonly Node[] = Object.freeze([])
 
 /**
- * The root-first ancestor chain (inclusive of the node itself), live: a move
- * re-renders it. `node` defaults to the nearest scope's location node; passing a
- * node/path makes it usable outside a scope. The chain drops any ancestor whose
- * record is masked/absent.
+ * Retained public concern with an explicit failed state: V2 has no implicit
+ * slash-tree ancestry. Callers must query a declared Edge Class instead.
  */
 export function useAncestors(
-  node?: Node | PathLike,
+  _node?: Node | PathLike,
 ): ReadState & { readonly chain: readonly Node[] } {
-  const memory = useMemory()
-  const ctx = useOptionalNavCtx()
-  useHistoryVersion(ctx?.history ?? null)
-
-  const baseRef =
-    node !== undefined ? serializeTarget(node).node : (ctx?.history.current?.node ?? null)
-  const baseResult = useMemoryShape(memory, baseRef)
-  const basePath = baseResult?.node ? pathOf(baseResult.node) : pathHint(baseRef ?? '')
-
-  const paths = useMemo(() => (basePath !== '' ? chainPaths(basePath) : EMPTY_PATHS), [basePath])
-  const shape = useMemo<ShapeInput | null>(
-    () => (basePath !== '' ? (q) => q.from(...chainPaths(basePath)) : null),
-    [basePath],
-  )
-  const chainResult = useMemoryShape(memory, shape)
-  const chain = useMemo<readonly Node[]>(() => {
-    if (chainResult === null) return EMPTY_CHAIN
-    const byPath = new Map<string, Node>()
-    for (const n of chainResult.roots) byPath.set(pathOf(n), n)
-    const out: Node[] = []
-    for (const p of paths) {
-      const hit = byPath.get(p)
-      if (hit !== undefined) out.push(hit)
-    }
-    return out
-  }, [paths, chainResult])
-
-  return { ...readStateOf(chainResult), chain }
-}
-
-const EMPTY_PATHS: readonly string[] = Object.freeze([])
-const EMPTY_CHAIN: readonly Node[] = Object.freeze([])
-
-function readStateOf(result: LiveResult | null): ReadState {
-  if (result === null) return idleReadState()
   return {
-    pending: result.pending,
-    error: result.error,
-    live: result.live,
-    seq: result.seq,
-    refetch: result.refetch,
+    ...unsupportedReadState('navigation.ancestors requires an explicit parent Edge Class'),
+    chain: EMPTY_CHAIN,
   }
 }

package/src/navigation/hooks/location.hook.ts

@@ -6,16 +6,14 @@ import { useMemo } from 'react'
 
 import type { NavLocation } from '../location.js'
 
-import { buildLocation, useSettled } from '../location.js'
-import { useHistoryVersion, useNavCtx, useMemoryShape } from '../scope.context.js'
+import { buildLocation } from '../location.js'
+import { useGraphPoint, useHistoryVersion, useNavCtx } from '../scope.context.js'
 
 /** The nearest scope's live location. Throws outside any {@link NavScope}. */
 export function useLocation(): NavLocation {
   const ctx = useNavCtx()
   useHistoryVersion(ctx.history)
   const entry = ctx.history.current
-  const shape = entry?.node ?? null
-  const result = useMemoryShape(ctx.memory, shape)
-  const settled = useSettled(result, shape)
-  return useMemo(() => buildLocation(entry, result, settled), [entry, result, settled])
+  const result = useGraphPoint(entry?.node ?? null)
+  return useMemo(() => buildLocation(entry, result), [entry, result])
 }