@astrale-os/shell-react 0.1.0

package/dist/navigation/location.d.ts

@@ -0,0 +1,48 @@
+import type { LiveResult } from '@astrale-os/kernel-client/store';
+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;
+}
+/** The idle location a scope with no current entry projects (inert / boot). */
+export declare const IDLE_LOCATION: NavLocation;
+/** Project a serialized entry + its live read into the public {@link NavLocation}. */
+export declare function buildLocation(entry: SerializedLocation | null, result: LiveResult | null, settled: boolean): NavLocation;
+/**
+ * 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 declare function useSettled(result: LiveResult | null, key: string | null): boolean;
+/** The raw path of a live node (empty when cold). */
+export declare function pathOf(node: Node | null): string;
+/** Best-effort anchor id from a stored ref (`@<id>` → id, else the raw ref). */
+export declare function idHint(ref: string): string;
+/** Best-effort path from a stored ref (a `/…` ref is already a path). */
+export declare function pathHint(ref: string): string;
+/** The parent absolute path, or null at (or above) root. */
+export declare function parentPath(raw: string): string | null;
+/**
+ * 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 declare function chainPaths(raw: string): string[];
+//# sourceMappingURL=location.d.ts.map

package/dist/navigation/location.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"location.d.ts","sourceRoot":"","sources":["../../src/navigation/location.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AAWjE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAEnD;;;;GAIG;AACH,MAAM,MAAM,IAAI,GAAG,WAAW,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAA;AAClD,MAAM,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAA;AAE/B,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,yCAAyC;IACzC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAA;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACjD,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AAID,+EAA+E;AAC/E,eAAO,MAAM,aAAa,EAAE,WAM3B,CAAA;AAED,sFAAsF;AACtF,wBAAgB,aAAa,CAC3B,KAAK,EAAE,kBAAkB,GAAG,IAAI,EAChC,MAAM,EAAE,UAAU,GAAG,IAAI,EACzB,OAAO,EAAE,OAAO,GACf,WAAW,CAWb;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CASjF;AAID,qDAAqD;AACrD,wBAAgB,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,CAEhD;AAED,gFAAgF;AAChF,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE1C;AAED,yEAAyE;AACzE,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,4DAA4D;AAC5D,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKrD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAUhD"}

package/dist/navigation/location.js

@@ -0,0 +1,88 @@
+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';
+const EMPTY_PARAMS = Object.freeze({});
+/** The idle location a scope with no current entry projects (inert / boot). */
+export const IDLE_LOCATION = {
+    id: '',
+    path: '',
+    node: null,
+    params: EMPTY_PARAMS,
+    missing: false,
+};
+/** Project a serialized entry + its live read into the public {@link NavLocation}. */
+export function buildLocation(entry, result, settled) {
+    if (entry === null)
+        return IDLE_LOCATION;
+    const node = result?.node ?? null;
+    return {
+        id: (node?.id ?? idHint(entry.node)),
+        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, key) {
+    const sawPending = useRef(new Map());
+    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) {
+    return node ? rawOf(node.path) : '';
+}
+/** Best-effort anchor id from a stored ref (`@<id>` → id, else the raw ref). */
+export function idHint(ref) {
+    return ref.startsWith('@') ? ref.slice(1) : ref;
+}
+/** Best-effort path from a stored ref (a `/…` ref is already a path). */
+export function pathHint(ref) {
+    return ref.startsWith('/') ? ref : '';
+}
+/** The parent absolute path, or null at (or above) root. */
+export function parentPath(raw) {
+    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) {
+    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/dist/navigation/scope.context.d.ts

@@ -0,0 +1,64 @@
+import type { GraphMemory, LiveResult, ShapeInput } from '@astrale-os/kernel-client/store';
+import type { ReactElement, ReactNode } from 'react';
+import type { NavAdapter } from './adapters/adapter';
+import type { NavSnapshot } from './history';
+import type { NavLocation } from './location';
+import type { NavTarget } from './snapshot';
+import { NavHistory } from './history';
+/** 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 declare const NavContext: import("react").Context<NavCtx | null>;
+/** The nearest scope, or throw — the door every public nav hook goes through. */
+export declare function useNavCtx(): NavCtx;
+/** The nearest scope or null (for `useAncestors`, usable outside a scope). */
+export declare function useOptionalNavCtx(): NavCtx | null;
+/** Re-render on any history change (no-op subscription when there is no scope). */
+export declare function useHistoryVersion(history: NavHistory | null): number;
+/**
+ * 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 declare function useMemoryShape(memory: GraphMemory, shape: ShapeInput | null): LiveResult | null;
+/** 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 declare function NavScope(props: NavScopeProps): ReactElement;
+//# sourceMappingURL=scope.context.d.ts.map

package/dist/navigation/scope.context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.context.d.ts","sourceRoot":"","sources":["../../src/navigation/scope.context.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AAC1F,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAqBpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACpD,OAAO,KAAK,EAAE,WAAW,EAAsB,MAAM,WAAW,CAAA;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAI3C,OAAO,EAAE,UAAU,EAAe,MAAM,WAAW,CAAA;AAInD,oDAAoD;AACpD,MAAM,WAAW,QAAQ;IACvB,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAA;IACnD,IAAI,IAAI,IAAI,CAAA;IACZ,OAAO,IAAI,IAAI,CAAA;IACf,+EAA+E;IAC/E,EAAE,IAAI,IAAI,CAAA;IACV,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;CAC7B;AAED,mFAAmF;AACnF,MAAM,WAAW,eAAe;IAC9B,CAAC,EAAE,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;IACnE,IAAI,IAAI,IAAI,CAAA;IACZ,OAAO,IAAI,IAAI,CAAA;IACf,EAAE,IAAI,IAAI,CAAA;IACV,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,EAAE,OAAO,CAAA;CACpB;AAED,2EAA2E;AAC3E,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;IAC5B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;IAC5B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAA;CACnC;AAED,eAAO,MAAM,UAAU,wCAAqC,CAAA;AAG5D,iFAAiF;AACjF,wBAAgB,SAAS,IAAI,MAAM,CAIlC;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,IAAI,CAEjD;AAID,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,GAAG,MAAM,CAOpE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI,GAAG,UAAU,GAAG,IAAI,CAU/F;AAED,qFAAqF;AACrF,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,MAAM,GAAG,CAAC,CAAC,GAAG,EAAE,WAAW,KAAK,SAAS,GAAG,IAAI,CAAC,CAAA;AAE1F,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,OAAO,CAAC,EAAE,UAAU,CAAA;IACpB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,WAAW,CAAA;IACrB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,KAAK,IAAI,CAAA;IAC5D,gFAAgF;IAChF,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,QAAQ,EAAE,SAAS,CAAA;CACpB;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,YAAY,CA2H3D"}

package/dist/navigation/scope.context.js

@@ -0,0 +1,178 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * 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 { 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';
+export const NavContext = createContext(null);
+NavContext.displayName = 'AstraleNavContext';
+/** The nearest scope, or throw — the door every public nav hook goes through. */
+export function useNavCtx() {
+    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() {
+    return useContext(NavContext);
+}
+const NOOP_UNSUB = () => undefined;
+/** Re-render on any history change (no-op subscription when there is no scope). */
+export function useHistoryVersion(history) {
+    const subscribe = useCallback((cb) => (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, shape) {
+    const subscribe = useCallback((cb) => (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);
+}
+export function NavScope(props) {
+    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(null);
+    if (adapterRef.current === null)
+        adapterRef.current = props.adapter ?? memoryAdapter();
+    const adapter = adapterRef.current;
+    const historyRef = useRef(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(() => {
+        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(() => {
+        const commit = (changed, replace) => {
+            if (!changed)
+                return;
+            const loc = history.current;
+            if (loc !== null)
+                adapter.write(loc, { replace });
+            fireOnChange();
+        };
+        const nav = ((to, opts) => {
+            const loc = serializeTarget(to);
+            const replace = opts?.replace ?? false;
+            startTransition(() => commit(history.push(loc, replace), replace));
+        });
+        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(null);
+    const handledRef = useRef(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(() => ({ history, memory, adapter, navigate }), [history, memory, adapter, navigate]);
+    return _jsx(NavContext.Provider, { value: ctx, children: props.children });
+}
+function applyMissingPolicy(entry, policy, deps) {
+    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/dist/navigation/snapshot.d.ts

@@ -0,0 +1,22 @@
+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 { 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>;
+};
+/** Normalize any {@link NavTarget} to its stored, id-anchored serialization. */
+export declare function serializeTarget(target: NavTarget): SerializedLocation;
+/**
+ * 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 declare function revalidateAndPrune(history: NavHistory, memory: GraphMemory): Promise<void>;
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/navigation/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../src/navigation/snapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAC3E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAA;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAA;AASlE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAC3C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAE9C,sEAAsE;AACtE,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,QAAQ,GACR,IAAI,GACJ,YAAY,GACZ;IAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;IAAC,IAAI,CAAC,EAAE,YAAY,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAA;AAMrF,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,kBAAkB,CAgBrE;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBhG"}

package/dist/navigation/snapshot.js

@@ -0,0 +1,65 @@
+/**
+ * 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';
+function isRecord(x) {
+    return typeof x === 'object' && x !== null;
+}
+/** Normalize any {@link NavTarget} to its stored, id-anchored serialization. */
+export function serializeTarget(target) {
+    if (typeof target === 'string')
+        return { node: normalizeRef(target) };
+    if (isRecord(target) && 'node' in target) {
+        const t = target;
+        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.id) };
+    }
+    return { node: normalizeRef(target) };
+}
+/**
+ * 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, memory) {
+    const { entries, cursor } = history.snapshot();
+    const alive = await Promise.all(entries.map((e) => resolves(memory, e.node)));
+    if (alive.every(Boolean))
+        return;
+    const survivors = [];
+    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, ref) {
+    try {
+        const result = await memory.query(ref, { live: false });
+        return result.node !== null;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/schema/bind-read.d.ts

@@ -0,0 +1,37 @@
+import type { OrderInput } from '@astrale-os/kernel-client/graph';
+import type { LiveResult, ShapeInput } from '@astrale-os/kernel-client/store';
+import type { Node } from '@astrale-os/kernel-core';
+import type { Schema } from '@astrale-os/kernel-dsl';
+import { type AnyBoundNode, type BoundNode, type DefOf, type NodeRefInput, type SchemaBoundView, type TypeNames } from '@astrale-os/kernel-client';
+import type { ReadOptions } from '../graph/memory/read/envelope';
+import type { TypedChildrenResult, TypedNodeResult } from './types';
+/** Bind one wire node as `type`; stable while the wire node, binding, and type hold. */
+export declare function useBoundNode<S extends Schema, T extends TypeNames<S>>(binding: SchemaBoundView<S>, type: T, wire: Node | null | undefined): BoundNode<DefOf<S, T>, S> | null;
+/**
+ * Bind many wire nodes as `type`; per-node identity + a stable array on no
+ * change. `skipMismatch` drops nodes whose class is not `type` (a mixed-class
+ * child set) instead of throwing.
+ */
+export declare function useBoundNodes<S extends Schema, T extends TypeNames<S>>(binding: SchemaBoundView<S>, type: T, wires: readonly Node[], skipMismatch?: boolean): readonly BoundNode<DefOf<S, T>, S>[];
+/** Bind many wire nodes classlessly (traversal endpoints); per-node + stable array. */
+export declare function useBoundEndpoints<S extends Schema>(binding: SchemaBoundView<S>, wires: readonly Node[]): readonly AnyBoundNode<S>[];
+/** Base read options plus the window growth mode (a `useChildren`-specific extra). */
+export type ShapeOptions = ReadOptions & {
+    window?: 'append' | 'paged';
+};
+/**
+ * Subscribe to a memory shape. `null` shape → idle (`null`, no I/O). A cold
+ * shape suspends unless `suspend: false`. The returned `LiveResult` is the
+ * unified read envelope — callers project `node`/`children`/`nodes`.
+ */
+export declare function useShape(shape: ShapeInput | null | undefined, opts?: ShapeOptions): LiveResult | null;
+export declare function useNode<S extends Schema, T extends TypeNames<S>>(schema: S, type: T, ref: NodeRefInput | null | undefined, opts?: ReadOptions): TypedNodeResult<S, T>;
+export declare 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>;
+/** Recover the schema a BoundNode was bound under; a clear error if it is untagged. */
+export declare function requireSchema(node: object): Schema;
+//# sourceMappingURL=bind-read.d.ts.map

package/dist/schema/bind-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bind-read.d.ts","sourceRoot":"","sources":["../../src/schema/bind-read.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,UAAU,EAAe,MAAM,iCAAiC,CAAA;AAC7F,OAAO,KAAK,EACV,UAAU,EAEV,UAAU,EACX,MAAM,iCAAiC,CAAA;AACxC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAA;AACnD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AAEpD,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,KAAK,EACV,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,SAAS,EACf,MAAM,2BAA2B,CAAA;AAalC,OAAO,KAAK,EAAa,WAAW,EAAE,MAAM,+BAA+B,CAAA;AAC3E,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAiBnE,wFAAwF;AACxF,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,SAAS,CAAC,CAAC,CAAC,EACnE,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,EAC3B,IAAI,EAAE,CAAC,EACP,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,SAAS,GAC5B,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAclC;AASD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,SAAS,CAAC,CAAC,CAAC,EACpE,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,EAC3B,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,YAAY,UAAQ,GACnB,SAAS,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAuBtC;AAQD,uFAAuF;AACvF,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,EAChD,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,EAC3B,KAAK,EAAE,SAAS,IAAI,EAAE,GACrB,SAAS,YAAY,CAAC,CAAC,CAAC,EAAE,CAiB5B;AAQD,sFAAsF;AACtF,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG;IAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAA;CAAE,CAAA;AAkBxE;;;;GAIG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,EACpC,IAAI,CAAC,EAAE,YAAY,GAClB,UAAU,GAAG,IAAI,CA6BnB;AAID,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,SAAS,CAAC,CAAC,CAAC,EAC9D,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,CAAC,EACP,GAAG,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,EACpC,IAAI,CAAC,EAAE,WAAW,GACjB,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAYvB;AAED,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,SAAS,CAAC,CAAC,CAAC,EAClE,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,EAC1C,IAAI,EAAE,WAAW,GAAG;IAClB,IAAI,EAAE,CAAC,CAAA;IACP,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAA;CAC5B,GACA,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAkC3B;AAwBD,uFAAuF;AACvF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASlD"}