@astrale-os/shell-react 0.1.0

package/dist/navigation/adapters/memory.adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.adapter.d.ts","sourceRoot":"","sources":["../../../src/navigation/adapters/memory.adapter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAE3C,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,UAAU,CAatE"}

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

@@ -0,0 +1,15 @@
+/** In-memory adapter — the default scope backing (per-pane state, no URL). */
+export function memoryAdapter(initial) {
+    let current = initial ?? null;
+    const listeners = new Set();
+    return {
+        read: () => current,
+        write: (loc) => {
+            current = loc;
+        },
+        subscribe: (cb) => {
+            listeners.add(cb);
+            return () => listeners.delete(cb);
+        },
+    };
+}

package/dist/navigation/adapters/url.adapter.d.ts

@@ -0,0 +1,6 @@
+import type { NavAdapter } from './adapter';
+/** History-API adapter — the location lives in the query string. */
+export declare function urlAdapter(opts?: {
+    param?: string;
+}): NavAdapter;
+//# sourceMappingURL=url.adapter.d.ts.map

package/dist/navigation/adapters/url.adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.adapter.d.ts","sourceRoot":"","sources":["../../../src/navigation/adapters/url.adapter.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAI3C,oEAAoE;AACpE,wBAAgB,UAAU,CAAC,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,UAAU,CAiDhE"}

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

@@ -0,0 +1,59 @@
+const VIEW_KEY = 'view';
+/** History-API adapter — the location lives in the query string. */
+export function urlAdapter(opts) {
+    const param = opts?.param ?? 'node';
+    const hasWindow = () => typeof window !== 'undefined';
+    const build = (loc) => {
+        const url = new URL(window.location.href);
+        const sp = new URLSearchParams();
+        sp.set(param, loc.node);
+        if (loc.view !== undefined)
+            sp.set(VIEW_KEY, loc.view);
+        for (const [k, v] of Object.entries(loc.params ?? {})) {
+            if (k !== param && k !== VIEW_KEY)
+                sp.set(k, v);
+        }
+        url.search = sp.toString();
+        return `${url.pathname}${url.search}${url.hash}`;
+    };
+    return {
+        read() {
+            if (!hasWindow())
+                return null;
+            const sp = new URL(window.location.href).searchParams;
+            const node = sp.get(param);
+            if (node === null)
+                return null;
+            const view = sp.get(VIEW_KEY) ?? undefined;
+            const params = {};
+            for (const [k, v] of sp) {
+                if (k !== param && k !== VIEW_KEY)
+                    params[k] = v;
+            }
+            return {
+                node,
+                ...(view !== undefined ? { view } : {}),
+                ...(Object.keys(params).length > 0 ? { params } : {}),
+            };
+        },
+        write(loc, { replace }) {
+            if (!hasWindow())
+                return;
+            const href = build(loc);
+            if (replace)
+                window.history.replaceState(null, '', href);
+            else
+                window.history.pushState(null, '', href);
+        },
+        subscribe(cb) {
+            if (!hasWindow())
+                return () => undefined;
+            const handler = () => cb();
+            window.addEventListener('popstate', handler);
+            return () => window.removeEventListener('popstate', handler);
+        },
+        href(loc) {
+            return hasWindow() ? build(loc) : loc.node;
+        },
+    };
+}

package/dist/navigation/history.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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.
+ */
+/** The serializable projection persisted in history / URLs / snapshots. */
+export interface SerializedLocation {
+    node: string;
+    view?: string;
+    params?: Record<string, string>;
+}
+/** A versioned history snapshot — round-trips through `NavScope.restore`. */
+export interface NavSnapshot {
+    v: 1;
+    entries: SerializedLocation[];
+    cursor: number;
+}
+/** Structural equality of two serialized locations (node + view + params). */
+export declare function sameLocation(a: SerializedLocation, b: SerializedLocation): boolean;
+/** A deep-enough clone for a serialized entry (params copied). */
+export declare function cloneLocation(loc: SerializedLocation): SerializedLocation;
+export declare class NavHistory {
+    private entries;
+    private cursor;
+    private version;
+    private readonly listeners;
+    constructor(entries: SerializedLocation[], cursor: number);
+    subscribe(listener: () => void): () => void;
+    getVersion(): number;
+    get current(): SerializedLocation | null;
+    get canBack(): boolean;
+    get canForward(): boolean;
+    snapshot(): NavSnapshot;
+    /** Push (or replace the current entry with) a location. No-op on same location. */
+    push(loc: SerializedLocation, replace: boolean): boolean;
+    back(): boolean;
+    forward(): boolean;
+    /**
+     * Reconcile an externally-observed location (browser back/forward, URL edit):
+     * step the cursor when it matches an adjacent entry, else push it fresh.
+     */
+    syncExternal(loc: SerializedLocation): boolean;
+    /** Replace the whole stack (restore revalidation prune). */
+    reset(entries: SerializedLocation[], cursor: number): void;
+    private emit;
+}
+/**
+ * Seed the initial entries+cursor from the three sources, in precedence order:
+ * a `restore` snapshot (revalidated later against the memory), then the
+ * adapter's current read, then `initial`; empty (idle) when none yields one.
+ * A live adapter read that disagrees with a restored cursor is appended as the
+ * current entry (a deep link overrides the saved position but keeps its back
+ * history).
+ */
+export declare function seedEntries(fromAdapter: SerializedLocation | null, restore: {
+    entries: SerializedLocation[];
+    cursor: number;
+} | undefined, initialSerialized: SerializedLocation | null): {
+    entries: SerializedLocation[];
+    cursor: number;
+};
+//# sourceMappingURL=history.d.ts.map

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

@@ -0,0 +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"}

package/dist/navigation/history.js

@@ -0,0 +1,144 @@
+/**
+ * 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);
+}
+function sameParams(a, b) {
+    if (a === b)
+        return true;
+    const ak = a ? Object.keys(a) : [];
+    const bk = b ? Object.keys(b) : [];
+    if (ak.length !== bk.length)
+        return false;
+    return ak.every((k) => a?.[k] === b?.[k]);
+}
+/** A deep-enough clone for a serialized entry (params copied). */
+export function cloneLocation(loc) {
+    return {
+        node: loc.node,
+        ...(loc.view !== undefined ? { view: loc.view } : {}),
+        ...(loc.params !== undefined ? { params: { ...loc.params } } : {}),
+    };
+}
+export class NavHistory {
+    entries;
+    cursor;
+    version = 0;
+    listeners = new Set();
+    constructor(entries, cursor) {
+        this.entries = entries;
+        this.cursor = cursor;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    getVersion() {
+        return this.version;
+    }
+    get current() {
+        return this.entries[this.cursor] ?? null;
+    }
+    get canBack() {
+        return this.cursor > 0;
+    }
+    get canForward() {
+        return this.cursor >= 0 && this.cursor < this.entries.length - 1;
+    }
+    snapshot() {
+        return { v: 1, entries: this.entries.map(cloneLocation), cursor: this.cursor };
+    }
+    /** Push (or replace the current entry with) a location. No-op on same location. */
+    push(loc, replace) {
+        const cur = this.current;
+        if (cur !== null && sameLocation(cur, loc))
+            return false;
+        if (replace && cur !== null) {
+            this.entries = [...this.entries];
+            this.entries[this.cursor] = loc;
+        }
+        else {
+            this.entries = [...this.entries.slice(0, this.cursor + 1), loc];
+            this.cursor = this.entries.length - 1;
+        }
+        this.emit();
+        return true;
+    }
+    back() {
+        if (!this.canBack)
+            return false;
+        this.cursor--;
+        this.emit();
+        return true;
+    }
+    forward() {
+        if (!this.canForward)
+            return false;
+        this.cursor++;
+        this.emit();
+        return true;
+    }
+    /**
+     * Reconcile an externally-observed location (browser back/forward, URL edit):
+     * step the cursor when it matches an adjacent entry, else push it fresh.
+     */
+    syncExternal(loc) {
+        const cur = this.current;
+        if (cur !== null && sameLocation(cur, loc))
+            return false;
+        const back = this.entries[this.cursor - 1];
+        if (back !== undefined && sameLocation(back, loc)) {
+            this.cursor--;
+            this.emit();
+            return true;
+        }
+        const fwd = this.entries[this.cursor + 1];
+        if (fwd !== undefined && sameLocation(fwd, loc)) {
+            this.cursor++;
+            this.emit();
+            return true;
+        }
+        return this.push(loc, false);
+    }
+    /** Replace the whole stack (restore revalidation prune). */
+    reset(entries, cursor) {
+        this.entries = entries;
+        this.cursor = cursor;
+        this.emit();
+    }
+    emit() {
+        this.version++;
+        for (const listener of this.listeners)
+            listener();
+    }
+}
+/**
+ * Seed the initial entries+cursor from the three sources, in precedence order:
+ * a `restore` snapshot (revalidated later against the memory), then the
+ * adapter's current read, then `initial`; empty (idle) when none yields one.
+ * A live adapter read that disagrees with a restored cursor is appended as the
+ * current entry (a deep link overrides the saved position but keeps its back
+ * history).
+ */
+export function seedEntries(fromAdapter, restore, initialSerialized) {
+    if (restore !== undefined && restore.entries.length > 0) {
+        const entries = restore.entries.map(cloneLocation);
+        let cursor = Math.min(Math.max(restore.cursor, 0), entries.length - 1);
+        if (fromAdapter !== null && !sameLocation(fromAdapter, entries[cursor])) {
+            entries.splice(cursor + 1);
+            entries.push(cloneLocation(fromAdapter));
+            cursor = entries.length - 1;
+        }
+        return { entries, cursor };
+    }
+    if (fromAdapter !== null)
+        return { entries: [cloneLocation(fromAdapter)], cursor: 0 };
+    if (initialSerialized !== null)
+        return { entries: [initialSerialized], cursor: 0 };
+    return { entries: [], cursor: -1 };
+}

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

@@ -0,0 +1,13 @@
+import type { PathLike } from '@astrale-os/kernel-client/graph';
+import type { ReadState } from '../../graph/memory/read/envelope';
+import type { Node } from '../location';
+/**
+ * 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.
+ */
+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

@@ -0,0 +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,kCAAkC,CAAA;AACjE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAQvC;;;;;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"}

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

@@ -0,0 +1,56 @@
+/**
+ * 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';
+import { useMemory } from '../../graph/memory/scope';
+import { chainPaths, pathHint, pathOf } from '../location';
+import { useHistoryVersion, useOptionalNavCtx, useMemoryShape } from '../scope.context';
+import { serializeTarget } from '../snapshot';
+/**
+ * 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.
+ */
+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();
+    return {
+        pending: result.pending,
+        error: result.error,
+        live: result.live,
+        seq: result.seq,
+        refetch: result.refetch,
+    };
+}

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

@@ -0,0 +1,4 @@
+import type { NavLocation } from '../location';
+/** The nearest scope's live location. Throws outside any {@link NavScope}. */
+export declare function useLocation(): NavLocation;
+//# sourceMappingURL=location.hook.d.ts.map

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

@@ -0,0 +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,aAAa,CAAA;AAK9C,8EAA8E;AAC9E,wBAAgB,WAAW,IAAI,WAAW,CAQzC"}

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

@@ -0,0 +1,17 @@
+/**
+ * useLocation (API §8.2) — the nearest scope's live, id-anchored location (live
+ * path/node, missing flag). Throws outside any {@link NavScope}.
+ */
+import { useMemo } from 'react';
+import { buildLocation, useSettled } from '../location';
+import { useHistoryVersion, useNavCtx, useMemoryShape } from '../scope.context';
+/** 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]);
+}

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

@@ -0,0 +1,12 @@
+import type { NavCtx, Navigate } from '../scope.context';
+/** The nearest scope's imperative navigation surface. Throws outside a scope. */
+export declare function useNavigate(): Navigate;
+/**
+ * A per-consumer navigate handle with fresh `canBack`/`canForward`, delegating to
+ * the scope's ONE stable callable. Render-pure: it never mutates the shared
+ * callable during render (a concurrent render could otherwise read flags from a
+ * newer history version than its own snapshot). The wrapper's identity changes
+ * only when navigation availability changes.
+ */
+export declare function useNavigateHandle(ctx: NavCtx): Navigate;
+//# sourceMappingURL=navigate.hook.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"navigate.hook.d.ts","sourceRoot":"","sources":["../../../src/navigation/hooks/navigate.hook.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAmB,MAAM,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAIzE,iFAAiF;AACjF,wBAAgB,WAAW,IAAI,QAAQ,CAEtC;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAQvD"}

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

@@ -0,0 +1,33 @@
+/**
+ * useNavigate (API §8.2) — the nearest scope's imperative navigation surface
+ * (back/forward/up + live canBack/canForward, wrapped in transitions). A
+ * per-consumer handle that delegates to the scope's ONE stable callable.
+ */
+import { useMemo } from 'react';
+import { useHistoryVersion, useNavCtx } from '../scope.context';
+/** The nearest scope's imperative navigation surface. Throws outside a scope. */
+export function useNavigate() {
+    return useNavigateHandle(useNavCtx());
+}
+/**
+ * A per-consumer navigate handle with fresh `canBack`/`canForward`, delegating to
+ * the scope's ONE stable callable. Render-pure: it never mutates the shared
+ * callable during render (a concurrent render could otherwise read flags from a
+ * newer history version than its own snapshot). The wrapper's identity changes
+ * only when navigation availability changes.
+ */
+export function useNavigateHandle(ctx) {
+    useHistoryVersion(ctx.history);
+    const canBack = ctx.history.canBack;
+    const canForward = ctx.history.canForward;
+    return useMemo(() => wrapNavigate(ctx.navigate, canBack, canForward), [ctx.navigate, canBack, canForward]);
+}
+function wrapNavigate(base, canBack, canForward) {
+    const fn = ((to, opts) => base(to, opts));
+    fn.back = base.back;
+    fn.forward = base.forward;
+    fn.up = base.up;
+    fn.canBack = canBack;
+    fn.canForward = canForward;
+    return fn;
+}

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

@@ -0,0 +1,12 @@
+import type { NavSnapshot } from '../history';
+import type { NavLocation } from '../location';
+import type { Navigate } from '../scope.context';
+/** The nearest scope, for chrome/persistence (API §8.2). */
+export interface NavScopeHandle {
+    readonly location: NavLocation;
+    snapshot(): NavSnapshot;
+    navigate: Navigate;
+}
+/** The nearest scope, for chrome/persistence (API §8.2). Throws outside a scope. */
+export declare function useNavScope(): NavScopeHandle;
+//# sourceMappingURL=scope.hook.d.ts.map

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

@@ -0,0 +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,YAAY,CAAA;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAMhD,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"}

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

@@ -0,0 +1,21 @@
+/**
+ * useNavScope (API §8.2) — the nearest scope, for chrome/persistence: the live
+ * location, a `snapshot()` handle, and the imperative navigate. Throws outside a
+ * scope.
+ */
+import { useCallback, useMemo } from 'react';
+import { buildLocation, useSettled } from '../location';
+import { useNavCtx, useMemoryShape } from '../scope.context';
+import { useNavigateHandle } from './navigate.hook';
+/** 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 snapshot = useCallback(() => ctx.history.snapshot(), [ctx.history]);
+    return { location, snapshot, navigate };
+}

package/dist/navigation/index.d.ts

@@ -0,0 +1,16 @@
+export { NavScope } from './scope.context';
+export type { MissingPolicy, NavScopeProps, Navigate } from './scope.context';
+export { useLocation } from './hooks/location.hook';
+export { useNavigate } from './hooks/navigate.hook';
+export { useAncestors } from './hooks/ancestors.hook';
+export { useNavScope } from './hooks/scope.hook';
+export type { NavScopeHandle } from './hooks/scope.hook';
+export { Link } from './link';
+export type { LinkProps } from './link';
+export { memoryAdapter } from './adapters/memory.adapter';
+export { urlAdapter } from './adapters/url.adapter';
+export type { NavAdapter } from './adapters/adapter';
+export type { NavLocation } from './location';
+export type { NavSnapshot, SerializedLocation } from './history';
+export type { NavTarget } from './snapshot';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/navigation/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC1C,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC7E,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAChD,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAC7B,YAAY,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACnD,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACpD,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC7C,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAChE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA"}

package/dist/navigation/index.js

@@ -0,0 +1,10 @@
+// navigation — API §8 (NavScope, useLocation, useNavigate, Link, useAncestors,
+// useNavScope, adapters). See SHELL_REACT_API.md.
+export { NavScope } from './scope.context';
+export { useLocation } from './hooks/location.hook';
+export { useNavigate } from './hooks/navigate.hook';
+export { useAncestors } from './hooks/ancestors.hook';
+export { useNavScope } from './hooks/scope.hook';
+export { Link } from './link';
+export { memoryAdapter } from './adapters/memory.adapter';
+export { urlAdapter } from './adapters/url.adapter';

package/dist/navigation/link.d.ts

@@ -0,0 +1,11 @@
+import type { AnchorHTMLAttributes, ReactElement, ReactNode } from 'react';
+import type { NavTarget } from './snapshot';
+export interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
+    to: NavTarget;
+    replace?: boolean;
+    /** Warm the target shape ahead of navigation. Default `'intent'`. */
+    prefetch?: 'intent' | 'render' | false;
+    children: ReactNode;
+}
+export declare function Link(props: LinkProps): ReactElement;
+//# sourceMappingURL=link.d.ts.map

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

@@ -0,0 +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,YAAY,CAAA;AAK3C,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"}

package/dist/navigation/link.js

@@ -0,0 +1,62 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * 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
+ * to the browser), else an href-less `<a role="link">` with identical behavior.
+ * Default prefetch `'intent'` warms the target shape on hover/pointer-down/focus.
+ */
+import { useCallback, useEffect } from 'react';
+import { useNavCtx } from './scope.context';
+import { serializeTarget } from './snapshot';
+export function Link(props) {
+    const { to, replace, prefetch = 'intent', children, onClick, onPointerEnter, onPointerDown, onFocus, onKeyDown, ...rest } = props;
+    const ctx = useNavCtx();
+    const target = serializeTarget(to);
+    const href = ctx.adapter.href?.(target);
+    const nodeRef = target.node;
+    const preload = useCallback(() => {
+        void ctx.memory?.preload(nodeRef);
+    }, [ctx.memory, nodeRef]);
+    useEffect(() => {
+        if (prefetch === 'render')
+            preload();
+    }, [prefetch, preload]);
+    const intent = useCallback(() => {
+        if (prefetch === 'intent')
+            preload();
+    }, [prefetch, preload]);
+    const go = useCallback(() => ctx.navigate(to, { replace }), [ctx, to, replace]);
+    const handleClick = (e) => {
+        onClick?.(e);
+        if (e.defaultPrevented)
+            return;
+        const modified = e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0;
+        if (href !== undefined && modified)
+            return; // let the browser open it (new tab / window)
+        e.preventDefault();
+        go();
+    };
+    const handleKeyDown = (e) => {
+        onKeyDown?.(e);
+        if (e.defaultPrevented || href !== undefined)
+            return; // a real anchor handles Enter itself
+        if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            go();
+        }
+    };
+    const handlePointerEnter = (e) => {
+        onPointerEnter?.(e);
+        intent();
+    };
+    const handlePointerDown = (e) => {
+        onPointerDown?.(e);
+        intent();
+    };
+    const handleFocus = (e) => {
+        onFocus?.(e);
+        intent();
+    };
+    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 }));
+}