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

package/dist/navigation/adapters/url.adapter.js

@@ -1,34 +1,69 @@
-const VIEW_KEY = 'view';
+import { NodePath } from '@astrale-os/sdk/graph/path';
+import { Key } from '@astrale-os/sdk/schema';
+const VIEW_KEY = 'astrale.view';
+const PARAM_PREFIX = 'astrale.param.';
 /** History-API adapter — the location lives in the query string. */
 export function urlAdapter(opts) {
-    const param = opts?.param ?? 'node';
+    const param = opts?.param ?? 'astrale.node';
     const hasWindow = () => typeof window !== 'undefined';
     const build = (loc) => {
         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 = () => {
+        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)
+            const rawNode = sp.get(param);
+            if (rawNode === null)
                 return null;
-            const view = sp.get(VIEW_KEY) ?? undefined;
+            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;
+                }
+            }
+            catch {
+                return null;
+            }
             const params = {};
             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,
@@ -45,6 +80,15 @@ export function urlAdapter(opts) {
             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;
@@ -57,3 +101,6 @@ export function urlAdapter(opts) {
         },
     };
 }
+function isSensitive(key) {
+    return /token|credential|authorization|secret/i.test(key);
+}

package/dist/navigation/codec.d.ts

@@ -0,0 +1,60 @@
+import type { Key } from '@astrale-os/sdk/schema';
+import type { ReactElement, ReactNode } from 'react';
+import { Path } from '@astrale-os/sdk/graph/path';
+import type { NavAdapter } from './adapters/adapter.js';
+import type { NavSnapshot, SerializedLocation } from './history.js';
+export interface NavigationParam<Value> {
+    encode(value: Value): string;
+    decode(value: string | undefined): Value;
+}
+export declare function pathParam(_name: string): NavigationParam<Path>;
+export declare function enumParam<const Values extends readonly [string, ...string[]]>(values: Values, fallback: Values[number]): NavigationParam<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 declare 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>;
+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 declare function defineNavigation<const Routes extends NavigationRoutes>(routes: Routes): NavigationDefinition<Routes>;
+export declare function NavigationScope<Routes extends NavigationRoutes>(props: {
+    readonly navigation: NavigationDefinition<Routes>;
+    readonly adapter?: NavAdapter;
+    readonly restore?: NavSnapshot;
+    readonly initial?: RouteTarget<Routes>;
+    readonly children: ReactNode;
+}): ReactElement;
+export declare function useNavigation<Routes extends NavigationRoutes>(navigation: NavigationDefinition<Routes>): Readonly<{
+    location: RouteTarget<Routes> | null;
+    push: (target: RouteTarget<Routes>) => void;
+    replace: (target: RouteTarget<Routes>) => void;
+    back: () => void;
+    forward: () => void;
+    snapshot: () => NavSnapshot;
+}>;
+export type NavigationTarget<Definition> = Definition extends NavigationDefinition<infer Routes> ? RouteTarget<Routes> : never;
+export {};
+//# sourceMappingURL=codec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/navigation/codec.ts"],"names":[],"mappings":"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"}

package/dist/navigation/codec.js

@@ -0,0 +1,121 @@
+import { Path } from '@astrale-os/sdk/graph/path';
+import { Key as admitKey } from '@astrale-os/sdk/schema';
+import { createElement } from 'react';
+import { NavScope } from './scope.context.js';
+import { useNavCtx } from './scope.context.js';
+import { useHistoryVersion } from './scope.context.js';
+export function pathParam(_name) {
+    return Object.freeze({
+        encode: (value) => Path.from(value).raw,
+        decode(value) {
+            if (value === undefined)
+                throw new TypeError('Navigation target is missing.');
+            return Path.parse(value);
+        },
+    });
+}
+export function enumParam(values, fallback) {
+    if (!values.includes(fallback))
+        throw new TypeError('Navigation enum fallback is not admitted.');
+    return Object.freeze({
+        encode(value) {
+            if (!values.includes(value))
+                throw new TypeError(`Invalid navigation enum value '${value}'.`);
+            return value;
+        },
+        decode(value) {
+            if (value === undefined)
+                return fallback;
+            if (!values.includes(value))
+                throw new TypeError(`Invalid navigation enum value '${value}'.`);
+            return value;
+        },
+    });
+}
+export function location(input) {
+    return Object.freeze({
+        view: viewKey(typeof input.view === 'string' ? input.view : input.view.key),
+        target: input.target,
+        params: Object.freeze({ ...input.params }),
+    });
+}
+export function defineNavigation(routes) {
+    const names = Object.keys(routes).sort();
+    const byView = new Map(names.map((name) => [routes[name].view, name]));
+    if (byView.size !== names.length)
+        throw new TypeError('Navigation Views must be unique.');
+    const definition = {
+        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[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),
+                });
+            }
+            catch {
+                return null;
+            }
+        },
+        admit(serialized) {
+            const decoded = definition.decode(serialized);
+            return decoded === null ? null : definition.encode(decoded);
+        },
+    };
+    return Object.freeze(definition);
+}
+export function NavigationScope(props) {
+    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(navigation) {
+    const context = useNavCtx();
+    useHistoryVersion(context.history);
+    const current = context.history.current;
+    return Object.freeze({
+        location: current === null ? null : navigation.decode(current),
+        push: (target) => context.navigate(navigation.encode(target)),
+        replace: (target) => context.navigate(navigation.encode(target), { replace: true }),
+        back: context.navigate.back,
+        forward: context.navigate.forward,
+        snapshot: () => context.history.snapshot(),
+    });
+}
+function viewKey(input) {
+    const key = admitKey(input);
+    if (!admitKey.ref(key).startsWith('view.'))
+        throw new TypeError(`Invalid View key '${input}'.`);
+    return key;
+}

package/dist/navigation/history.d.ts

@@ -4,17 +4,19 @@
  * (`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). */
 export declare function sameLocation(a: SerializedLocation, b: SerializedLocation): boolean;
@@ -42,7 +44,7 @@ export declare class NavHistory {
      */
     syncExternal(loc: SerializedLocation): boolean;
     /** Replace the whole stack (restore revalidation prune). */
-    reset(entries: SerializedLocation[], cursor: number): void;
+    reset(entries: readonly SerializedLocation[], cursor: number): void;
     private emit;
 }
 /**
@@ -54,8 +56,8 @@ export declare class NavHistory {
  * history).
  */
 export declare function seedEntries(fromAdapter: SerializedLocation | null, restore: {
-    entries: SerializedLocation[];
-    cursor: number;
+    readonly entries: readonly SerializedLocation[];
+    readonly cursor: number;
 } | undefined, initialSerialized: SerializedLocation | null): {
     entries: SerializedLocation[];
     cursor: number;

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

@@ -1 +1 @@
-{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/navigation/history.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAChC;AAED,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,CAAC,EAAE,CAAC,CAAA;IACJ,OAAO,EAAE,kBAAkB,EAAE,CAAA;IAC7B,MAAM,EAAE,MAAM,CAAA;CACf;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,CAAC,EAAE,kBAAkB,EAAE,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAElF;AAUD,kEAAkE;AAClE,wBAAgB,aAAa,CAAC,GAAG,EAAE,kBAAkB,GAAG,kBAAkB,CAMzE;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,OAAO,CAAI;IACnB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwB;IAElD,YAAY,OAAO,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,MAAM,EAGxD;IAED,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAG1C;IAED,UAAU,IAAI,MAAM,CAEnB;IAED,IAAI,OAAO,IAAI,kBAAkB,GAAG,IAAI,CAEvC;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,QAAQ,IAAI,WAAW,CAEtB;IAED,mFAAmF;IACnF,IAAI,CAAC,GAAG,EAAE,kBAAkB,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAYvD;IAED,IAAI,IAAI,OAAO,CAKd;IAED,OAAO,IAAI,OAAO,CAKjB;IAED;;;OAGG;IACH,YAAY,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAgB7C;IAED,4DAA4D;IAC5D,KAAK,CAAC,OAAO,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAIzD;IAED,OAAO,CAAC,IAAI;CAIb;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,WAAW,EAAE,kBAAkB,GAAG,IAAI,EACtC,OAAO,EAAE;IAAE,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,EACtE,iBAAiB,EAAE,kBAAkB,GAAG,IAAI,GAC3C;IAAE,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAcnD"}
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/navigation/history.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAA;AAC1D,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,wBAAwB,CAAA;AAEjD,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,IAAI,CAAA;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CACnD;AAED,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAA;IACb,QAAQ,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,CAAC,EAAE,kBAAkB,EAAE,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAElF;AAaD,kEAAkE;AAClE,wBAAgB,aAAa,CAAC,GAAG,EAAE,kBAAkB,GAAG,kBAAkB,CAMzE;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,OAAO,CAAI;IACnB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwB;IAElD,YAAY,OAAO,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,MAAM,EAGxD;IAED,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAG1C;IAED,UAAU,IAAI,MAAM,CAEnB;IAED,IAAI,OAAO,IAAI,kBAAkB,GAAG,IAAI,CAEvC;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,QAAQ,IAAI,WAAW,CAMtB;IAED,mFAAmF;IACnF,IAAI,CAAC,GAAG,EAAE,kBAAkB,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAYvD;IAED,IAAI,IAAI,OAAO,CAKd;IAED,OAAO,IAAI,OAAO,CAKjB;IAED;;;OAGG;IACH,YAAY,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAgB7C;IAED,4DAA4D;IAC5D,KAAK,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAIlE;IAED,OAAO,CAAC,IAAI;CAIb;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,WAAW,EAAE,kBAAkB,GAAG,IAAI,EACtC,OAAO,EAAE;IAAE,QAAQ,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,EACjG,iBAAiB,EAAE,kBAAkB,GAAG,IAAI,GAC3C;IAAE,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAcnD"}

package/dist/navigation/history.js

@@ -1,9 +1,3 @@
-/**
- * The per-scope history model (API §8.2) — a framework-free entries+cursor stack
- * with a version counter for `useSyncExternalStore`, its serialized entry shape
- * (`SerializedLocation`/`NavSnapshot` + equality/clone), and the seed precedence.
- * Source of truth for back/forward; the adapter is a projection sink around it.
- */
 /** Structural equality of two serialized locations (node + view + params). */
 export function sameLocation(a, b) {
     return a.node === b.node && a.view === b.view && sameParams(a.params, b.params);
@@ -51,7 +45,11 @@ export class NavHistory {
         return this.cursor >= 0 && this.cursor < this.entries.length - 1;
     }
     snapshot() {
-        return { v: 1, entries: this.entries.map(cloneLocation), cursor: this.cursor };
+        return Object.freeze({
+            v: 1,
+            entries: Object.freeze(this.entries.map(cloneLocation)),
+            cursor: this.cursor,
+        });
     }
     /** Push (or replace the current entry with) a location. No-op on same location. */
     push(loc, replace) {
@@ -107,7 +105,7 @@ export class NavHistory {
     }
     /** Replace the whole stack (restore revalidation prune). */
     reset(entries, cursor) {
-        this.entries = entries;
+        this.entries = [...entries];
         this.cursor = cursor;
         this.emit();
     }

package/dist/navigation/hooks/ancestors.hook.d.ts

@@ -1,13 +1,11 @@
-import type { PathLike } from '@astrale-os/kernel-client/graph';
+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';
 /**
- * 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 declare function useAncestors(node?: Node | PathLike): ReadState & {
+export declare function useAncestors(_node?: Node | PathLike): ReadState & {
     readonly chain: readonly Node[];
 };
 //# sourceMappingURL=ancestors.hook.d.ts.map

package/dist/navigation/hooks/ancestors.hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ancestors.hook.d.ts","sourceRoot":"","sources":["../../../src/navigation/hooks/ancestors.hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAA;AAU/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAA;AACpE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAA;AAQ1C;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,IAAI,CAAC,EAAE,IAAI,GAAG,QAAQ,GACrB,SAAS,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAA;CAAE,CA6BjD"}
+{"version":3,"file":"ancestors.hook.d.ts","sourceRoot":"","sources":["../../../src/navigation/hooks/ancestors.hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,4BAA4B,CAAA;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAA;AAE1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAA;AAMpE;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,KAAK,CAAC,EAAE,IAAI,GAAG,QAAQ,GACtB,SAAS,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAA;CAAE,CAKjD"}

package/dist/navigation/hooks/ancestors.hook.js

@@ -1,56 +1,12 @@
+import { unsupportedReadState } from '../../graph/memory/read/envelope.js';
+const EMPTY_CHAIN = Object.freeze([]);
 /**
- * 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 { 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';
-/**
- * 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) {
-    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(() => (basePath !== '' ? (q) => q.from(...chainPaths(basePath)) : null), [basePath]);
-    const chainResult = useMemoryShape(memory, shape);
-    const chain = useMemo(() => {
-        if (chainResult === null)
-            return EMPTY_CHAIN;
-        const byPath = new Map();
-        for (const n of chainResult.roots)
-            byPath.set(pathOf(n), n);
-        const out = [];
-        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 = Object.freeze([]);
-const EMPTY_CHAIN = Object.freeze([]);
-function readStateOf(result) {
-    if (result === null)
-        return idleReadState();
+export function useAncestors(_node) {
     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/dist/navigation/hooks/location.hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"location.hook.d.ts","sourceRoot":"","sources":["../../../src/navigation/hooks/location.hook.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAKjD,8EAA8E;AAC9E,wBAAgB,WAAW,IAAI,WAAW,CAQzC"}
+{"version":3,"file":"location.hook.d.ts","sourceRoot":"","sources":["../../../src/navigation/hooks/location.hook.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAKjD,8EAA8E;AAC9E,wBAAgB,WAAW,IAAI,WAAW,CAMzC"}

package/dist/navigation/hooks/location.hook.js

@@ -3,15 +3,13 @@
  * path/node, missing flag). Throws outside any {@link NavScope}.
  */
 import { useMemo } from 'react';
-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() {
     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]);
 }

package/dist/navigation/hooks/scope.hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scope.hook.d.ts","sourceRoot":"","sources":["../../../src/navigation/hooks/scope.hook.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AACjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAMnD,4DAA4D;AAC5D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAA;IAC9B,QAAQ,IAAI,WAAW,CAAA;IACvB,QAAQ,EAAE,QAAQ,CAAA;CACnB;AAED,oFAAoF;AACpF,wBAAgB,WAAW,IAAI,cAAc,CAU5C"}
+{"version":3,"file":"scope.hook.d.ts","sourceRoot":"","sources":["../../../src/navigation/hooks/scope.hook.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AACjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAMnD,4DAA4D;AAC5D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAA;IAC9B,QAAQ,IAAI,WAAW,CAAA;IACvB,QAAQ,EAAE,QAAQ,CAAA;CACnB;AAED,oFAAoF;AACpF,wBAAgB,WAAW,IAAI,cAAc,CAQ5C"}

package/dist/navigation/hooks/scope.hook.js

@@ -4,18 +4,16 @@
  * scope.
  */
 import { useCallback, useMemo } from 'react';
-import { buildLocation, useSettled } from '../location.js';
-import { useNavCtx, useMemoryShape } from '../scope.context.js';
+import { buildLocation } from '../location.js';
+import { useGraphPoint, useNavCtx } from '../scope.context.js';
 import { useNavigateHandle } from './navigate.hook.js';
 /** The nearest scope, for chrome/persistence (API §8.2). Throws outside a scope. */
 export function useNavScope() {
     const ctx = useNavCtx();
     const navigate = useNavigateHandle(ctx);
     const entry = ctx.history.current;
-    const shape = entry?.node ?? null;
-    const result = useMemoryShape(ctx.memory, shape);
-    const settled = useSettled(result, shape);
-    const location = useMemo(() => buildLocation(entry, result, settled), [entry, result, settled]);
+    const result = useGraphPoint(entry?.node ?? null);
+    const location = useMemo(() => buildLocation(entry, result), [entry, result]);
     const snapshot = useCallback(() => ctx.history.snapshot(), [ctx.history]);
     return { location, snapshot, navigate };
 }

package/dist/navigation/index.d.ts

@@ -5,8 +5,10 @@ export { useNavigate } from './hooks/navigate.hook.js';
 export { useAncestors } from './hooks/ancestors.hook.js';
 export { useNavScope } from './hooks/scope.hook.js';
 export type { NavScopeHandle } from './hooks/scope.hook.js';
-export { Link } from './link.js';
-export type { LinkProps } from './link.js';
+export { Link, NodeLink, ViewLink } from './link.js';
+export type { LinkProps, NodeLinkProps, ViewLinkProps } from './link.js';
+export { NavigationScope, defineNavigation, enumParam, location, pathParam, useNavigation, } from './codec.js';
+export type { LocationDefinition, NavigationDefinition, NavigationParam, NavigationParams, NavigationRoutes, NavigationTarget, } from './codec.js';
 export { memoryAdapter } from './adapters/memory.adapter.js';
 export { urlAdapter } from './adapters/url.adapter.js';
 export type { NavAdapter } from './adapters/adapter.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/navigation/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAC7C,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAChF,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACnD,YAAY,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAC3D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,YAAY,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAA;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAA;AACtD,YAAY,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACvD,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAChD,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AACnE,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/navigation/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAC7C,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAChF,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACnD,YAAY,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAC3D,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpD,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AACxE,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,SAAS,EACT,QAAQ,EACR,SAAS,EACT,aAAa,GACd,MAAM,YAAY,CAAA;AACnB,YAAY,EACV,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAA;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAA;AACtD,YAAY,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACvD,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAChD,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AACnE,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA"}

package/dist/navigation/index.js

@@ -5,6 +5,7 @@ export { useLocation } from './hooks/location.hook.js';
 export { useNavigate } from './hooks/navigate.hook.js';
 export { useAncestors } from './hooks/ancestors.hook.js';
 export { useNavScope } from './hooks/scope.hook.js';
-export { Link } from './link.js';
+export { Link, NodeLink, ViewLink } from './link.js';
+export { NavigationScope, defineNavigation, enumParam, location, pathParam, useNavigation, } from './codec.js';
 export { memoryAdapter } from './adapters/memory.adapter.js';
 export { urlAdapter } from './adapters/url.adapter.js';

package/dist/navigation/link.d.ts

@@ -1,4 +1,5 @@
 import type { AnchorHTMLAttributes, ReactElement, ReactNode } from 'react';
+import type { NavigationDefinition, NavigationTarget } from './codec.js';
 import type { NavTarget } from './snapshot.js';
 export interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
     to: NavTarget;
@@ -8,4 +9,15 @@ export interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
     children: ReactNode;
 }
 export declare function Link(props: LinkProps): ReactElement;
+export type ViewLinkProps<Definition extends NavigationDefinition> = Omit<LinkProps, 'to'> & {
+    readonly navigation: Definition;
+    readonly to: NavigationTarget<Definition>;
+};
+/** Codec-admitted link for one declared View location. */
+export declare function ViewLink<Definition extends NavigationDefinition>(props: ViewLinkProps<Definition>): ReactElement;
+export type NodeLinkProps = Omit<LinkProps, 'to'> & {
+    readonly to: Extract<NavTarget, string | object>;
+};
+/** Canonical node-only link; use ViewLink when a View/params contract exists. */
+export declare function NodeLink(props: NodeLinkProps): ReactElement;
 //# sourceMappingURL=link.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["../../src/navigation/link.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EAKpB,YAAY,EACZ,SAAS,EACV,MAAM,OAAO,CAAA;AAUd,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAK9C,MAAM,WAAW,SAAU,SAAQ,oBAAoB,CAAC,iBAAiB,CAAC;IACxE,EAAE,EAAE,SAAS,CAAA;IACb,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,KAAK,CAAA;IACtC,QAAQ,EAAE,SAAS,CAAA;CACpB;AAED,wBAAgB,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,YAAY,CA8EnD"}
+{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["../../src/navigation/link.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EAKpB,YAAY,EACZ,SAAS,EACV,MAAM,OAAO,CAAA;AAWd,OAAO,KAAK,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AACxE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAK9C,MAAM,WAAW,SAAU,SAAQ,oBAAoB,CAAC,iBAAiB,CAAC;IACxE,EAAE,EAAE,SAAS,CAAA;IACb,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,KAAK,CAAA;IACtC,QAAQ,EAAE,SAAS,CAAA;CACpB;AAED,wBAAgB,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,YAAY,CA+EnD;AAED,MAAM,MAAM,aAAa,CAAC,UAAU,SAAS,oBAAoB,IAAI,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG;IAC3F,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;IAC/B,QAAQ,CAAC,EAAE,EAAE,gBAAgB,CAAC,UAAU,CAAC,CAAA;CAC1C,CAAA;AAED,0DAA0D;AAC1D,wBAAgB,QAAQ,CAAC,UAAU,SAAS,oBAAoB,EAC9D,KAAK,EAAE,aAAa,CAAC,UAAU,CAAC,GAC/B,YAAY,CAGd;AAED,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG;IAClD,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,CAAA;CACjD,CAAA;AAED,iFAAiF;AACjF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,YAAY,CAE3D"}

package/dist/navigation/link.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { Query } from '@astrale-os/sdk/query';
 /**
  * Link (API §8.2) — navigates the nearest scope. Renders `<a href>` when the
  * scope's adapter exposes a URL form (cmd/ctrl/middle-click then falls through
@@ -15,8 +16,9 @@ export function Link(props) {
     const href = ctx.adapter.href?.(target);
     const nodeRef = target.node;
     const preload = useCallback(() => {
-        void ctx.memory?.preload(nodeRef);
-    }, [ctx.memory, nodeRef]);
+        const query = Query.from({ kind: 'node', paths: [nodeRef] }).select({ kind: 'graph' });
+        void ctx.store.preload(query, { page: { size: 1 } }).catch(() => { });
+    }, [ctx.store, nodeRef]);
     useEffect(() => {
         if (prefetch === 'render')
             preload();
@@ -60,3 +62,12 @@ export function Link(props) {
     const linkRole = href !== undefined ? { href } : { role: 'link', tabIndex: rest.tabIndex ?? 0 };
     return (_jsx("a", { ...rest, ...linkRole, onClick: handleClick, onKeyDown: handleKeyDown, onPointerEnter: handlePointerEnter, onPointerDown: handlePointerDown, onFocus: handleFocus, children: children }));
 }
+/** Codec-admitted link for one declared View location. */
+export function ViewLink(props) {
+    const { navigation, to, ...link } = props;
+    return _jsx(Link, { ...link, to: navigation.encode(to) });
+}
+/** Canonical node-only link; use ViewLink when a View/params contract exists. */
+export function NodeLink(props) {
+    return _jsx(Link, { ...props });
+}