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

package/dist/navigation/location.d.ts

@@ -1,48 +1,21 @@
-import type { LiveResult } from '@astrale-os/kernel-client/store';
+import type { Node, NodeId } from '@astrale-os/sdk/graph/node';
+import type { NodePath } from '@astrale-os/sdk/graph/path';
+import type { Key } from '@astrale-os/sdk/schema';
+import type { ReadState } from '../graph/memory/read/envelope.js';
 import type { SerializedLocation } from './history.js';
-/**
- * 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 PointResult extends ReadState {
+    readonly node: Node | null;
+}
+/** One canonical location and its current caller-visible point projection. */
 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 target: NodePath | null;
+    readonly id: NodeId | null;
     readonly node: Node | null;
-    /** View function ref rendering it, when one is open. */
-    readonly view?: string;
+    readonly view?: Key.View;
     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[];
+export declare function buildLocation(entry: SerializedLocation | null, result: PointResult | null): NavLocation;
+export type { Node, NodeId };
 //# sourceMappingURL=location.d.ts.map

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

@@ -1 +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,cAAc,CAAA;AAEtD;;;;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"}
+{"version":3,"file":"location.d.ts","sourceRoot":"","sources":["../../src/navigation/location.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAA;AAC9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAA;AAC1D,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,wBAAwB,CAAA;AAIjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAA;AACjE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAEtD,MAAM,WAAW,WAAY,SAAQ,SAAS;IAC5C,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAA;CAC3B;AAED,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI,CAAA;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAA;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,IAAI,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACjD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AAID,eAAO,MAAM,aAAa,EAAE,WAM1B,CAAA;AAEF,wBAAgB,aAAa,CAC3B,KAAK,EAAE,kBAAkB,GAAG,IAAI,EAChC,MAAM,EAAE,WAAW,GAAG,IAAI,GACzB,WAAW,CAWb;AAOD,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,CAAA"}

package/dist/navigation/location.js

@@ -1,88 +1,26 @@
-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 { Path } from '@astrale-os/sdk/graph/path';
 const EMPTY_PARAMS = Object.freeze({});
-/** The idle location a scope with no current entry projects (inert / boot). */
-export const IDLE_LOCATION = {
-    id: '',
-    path: '',
+export const IDLE_LOCATION = Object.freeze({
+    target: null,
+    id: null,
     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) {
+});
+export function buildLocation(entry, result) {
     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),
+        target: entry.node,
+        id: node?.id ?? idAnchor(entry.node),
         node,
-        ...(entry.view !== undefined ? { view: entry.view } : {}),
-        params: entry.params ?? IDLE_LOCATION.params,
-        missing: settled && node === null,
+        ...(entry.view === undefined ? {} : { view: entry.view }),
+        params: entry.params ?? EMPTY_PARAMS,
+        missing: result !== null && !result.pending && 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;
+function idAnchor(target) {
+    const path = Path.from(target);
+    return path.ast.anchor.kind === 'id' && path.ast.steps.length === 0 ? path.ast.anchor.id : null;
 }

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

@@ -1,64 +1,55 @@
-import type { GraphMemory, LiveResult, ShapeInput } from '@astrale-os/kernel-client/store';
+import type { GraphStore } from '@astrale-os/kernel-client/store';
 import type { ReactElement, ReactNode } from 'react';
+import { NodePath } from '@astrale-os/sdk/graph/path';
 import type { NavAdapter } from './adapters/adapter.js';
-import type { NavSnapshot } from './history.js';
-import type { NavLocation } from './location.js';
+import type { NavSnapshot, SerializedLocation } from './history.js';
+import type { NavLocation, PointResult } from './location.js';
 import type { NavTarget } from './snapshot.js';
 import { NavHistory } from './history.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;
 }
 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);
+/** Caller-scoped canonical point read through the provider's one GraphStore. */
+export declare function useGraphPoint(target: NodePath | null): PointResult | 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 declare function NavScope(props: NavScopeProps): ReactElement;
+export {};
 //# sourceMappingURL=scope.context.d.ts.map

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

@@ -1 +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,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,WAAW,EAAsB,MAAM,cAAc,CAAA;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAI9C,OAAO,EAAE,UAAU,EAAe,MAAM,cAAc,CAAA;AAItD,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"}
+{"version":3,"file":"scope.context.d.ts","sourceRoot":"","sources":["../../src/navigation/scope.context.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAsB,MAAM,iCAAiC,CAAA;AACrF,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEpD,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAA;AAcrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAO9C,OAAO,EAAE,UAAU,EAAe,MAAM,cAAc,CAAA;AAItD,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,2EAA2E;IAC3E,EAAE,IAAI,KAAK,CAAA;IACX,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;CAC7B;AAED,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,KAAK,CAAA;IACX,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,EAAE,OAAO,CAAA;CACpB;AAED,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;IAC5B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;IAC5B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAA;CACnC;AAED,eAAO,MAAM,UAAU,wCAAqC,CAAA;AAG5D,wBAAgB,SAAS,IAAI,MAAM,CAIlC;AAED,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,IAAI,CAEjD;AAID,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,GAAG,MAAM,CAOpE;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI,GAAG,WAAW,GAAG,IAAI,CA6BzE;AAED,KAAK,eAAe,GAAG,CAAC,QAAQ,EAAE,WAAW,KAAK,SAAS,GAAG,IAAI,CAAA;AAClE,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,eAAe,CAAA;AAEpD,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,UAAU,CAAA;IACpB,OAAO,CAAC,EAAE,WAAW,CAAA;IACrB,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,KAAK,IAAI,CAAA;IACjE,gFAAgF;IAChF,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,kBAAkB,GAAG,IAAI,CAAA;IACnE,QAAQ,EAAE,SAAS,CAAA;CACpB;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,YAAY,CAsH3D"}

package/dist/navigation/scope.context.js

@@ -1,178 +1,210 @@
 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 { NodePath } from '@astrale-os/sdk/graph/path';
+import { Query } from '@astrale-os/sdk/query';
+import { Key } from '@astrale-os/sdk/schema';
 import { createContext, startTransition, useCallback, useContext, useEffect, useMemo, useRef, useSyncExternalStore, } from 'react';
-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';
 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]);
+    const subscribe = useCallback((listener) => (history === null ? NOOP_UNSUB : history.subscribe(listener)), [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, 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);
+/** Caller-scoped canonical point read through the provider's one GraphStore. */
+export function useGraphPoint(target) {
+    const query = useMemo(() => target === null
+        ? null
+        : Query.from({ kind: 'node', paths: [target], binding: 'navigation_target' }).select({
+            kind: 'graph',
+        }), [target]);
+    const project = useCallback((response) => {
+        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]);
+    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,
+    };
 }
 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 store = useGraphStore();
+    const shell = useShell();
     const adapterRef = useRef(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) => {
+        if (location === null)
+            return null;
+        const portable = admitLocation(location);
+        return admitRef.current?.(portable) ?? portable;
+    };
     const historyRef = useRef(null);
     if (historyRef.current === null) {
-        const seed = seedEntries(adapter.read(), props.restore, props.initial !== undefined ? serializeTarget(props.initial) : null);
+        const seed = seedEntries(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(() => {
-        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(() => {
         const commit = (changed, replace) => {
             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, opts) => {
-            const loc = serializeTarget(to);
-            const replace = opts?.replace ?? false;
-            startTransition(() => commit(history.push(loc, replace), replace));
+        const nav = ((to, options) => {
+            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));
         });
         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);
+            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);
-    // Mount: canonicalize a non-adapter seed into the adapter, then relay external
-    // (browser/URL) changes back into the history.
+    }, [history, adapter, fireOnChange, historyVersion]);
     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)
+            const location = admit(adapter.read());
+            if (location === null)
                 return;
             startTransition(() => {
-                if (history.syncExternal(loc))
+                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)
+        if (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]);
+        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]);
+    const current = history.current;
+    const result = useGraphPoint(current?.node ?? null);
+    const handled = useRef(null);
     useEffect(() => {
-        const entry = history.current;
-        if (entry === null)
+        if (current === null || result === null || result.pending)
             return;
-        if ((currentResult?.node ?? null) !== null) {
-            handledRef.current = null;
+        if (result.node !== null) {
+            handled.current = null;
             return;
         }
-        if (!settled || handledRef.current === entry.node)
+        if (handled.current === current.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]);
+        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(() => ({ history, store, adapter, navigate }), [history, store, 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;
+function admitLocation(location) {
+    if (location === null || typeof location !== 'object' || Array.isArray(location)) {
+        throw new TypeError('Navigation location is invalid.');
+    }
+    const node = NodePath(location.node);
+    let view;
+    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;
+    }
+    const params = {};
+    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/dist/navigation/snapshot.d.ts

@@ -1,22 +1,17 @@
-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.js';
-import type { SerializedLocation } from './history.js';
-import type { Node, NodeId } from './location.js';
-/** Everything `navigate()` / `Link` / `initial` accept (API §8.1). */
-export type NavTarget = NodeId | PathLike | Node | AnyBoundNode | {
-    node: NodeId | PathLike;
-    view?: NodeRefInput;
-    params?: Record<string, string>;
+import type { GraphStore } from '@astrale-os/kernel-client/store';
+import type { Node } from '@astrale-os/sdk/graph/node';
+import type { PathLike } from '@astrale-os/sdk/graph/path';
+import type { Key } from '@astrale-os/sdk/schema';
+import type { Shell } from '@astrale-os/shell';
+import type { NavHistory, SerializedLocation } from './history.js';
+/** Canonical navigation inputs; there is no implicit slash-tree or bare-id grammar. */
+export type NavTarget = PathLike | Node | {
+    readonly node: PathLike | Node;
+    readonly view?: Key.View;
+    readonly params?: Record<string, string>;
 };
-/** Normalize any {@link NavTarget} to its stored, id-anchored serialization. */
+/** Normalize every target to canonical astrale-node-path-v1 text. */
 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>;
+/** Drop restored entries that no longer resolve under the authenticated Graph capability. */
+export declare function revalidateAndPrune(history: NavHistory, store: GraphStore, shell: Shell): Promise<boolean>;
 //# sourceMappingURL=snapshot.d.ts.map