@omerdlw/base-framework 2.0.1 → 3.0.0

package/dist/modules/index.js

@@ -1,16 +1,18 @@
 "use client";
-export { defaultModules } from '../chunk-6ZJVLUBE.js';
+export { defaultModules } from '../chunk-M57SNWXK.js';
+export { navigationModule } from '../chunk-RIOKLMYM.js';
 export { modalModule } from '../chunk-FIMPHODX.js';
 import '../chunk-7HQMXTNP.js';
-export { ambientModule } from '../chunk-QXR55VVS.js';
+export { ambientModule } from '../chunk-TG6NMHXI.js';
 export { backgroundModule } from '../chunk-CGHZSSFR.js';
-export { contextMenuModule } from '../chunk-SKBITB5X.js';
-export { dockModule } from '../chunk-A5RE3F6O.js';
+export { contextMenuModule } from '../chunk-CYU6SGAL.js';
+export { dockModule } from '../chunk-JIXBFFRD.js';
+import '../chunk-HLL5EHXC.js';
 import '../chunk-QI3ALLIB.js';
 export { notificationModule } from '../chunk-SYAVGTOX.js';
 export { mediaModule } from '../chunk-R2YGFJDJ.js';
 export { controlsModule } from '../chunk-4GMQKD6F.js';
-export { loadingModule } from '../chunk-XASQT4CQ.js';
+export { loadingModule } from '../chunk-66EYJBIP.js';
 import '../chunk-7TAVYJ3A.js';
 import '../chunk-GF7TUX5I.js';
 import '../chunk-TV3WEF5G.js';

package/dist/modules/loading/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/modules/loading/context.tsx"],"names":[],"mappings":"AAyBA,OAAO,EAEL,KAAK,mBAAmB,EAExB,KAAK,oBAAoB,EAEzB,KAAK,oBAAoB,EAE1B,MAAM,SAAS,CAAC;AAEjB,eAAO,MAAM,cAAc,qDACmD,CAAC;AAE/E,eAAO,MAAM,kBAAkB,uDAE9B,CAAC;AAEF,wBAAgB,eAAe,CAAC,EAAE,QAAQ,EAAE,EAAE,oBAAoB,+BA8HjE"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/modules/loading/context.tsx"],"names":[],"mappings":"AAyBA,OAAO,EAEL,KAAK,mBAAmB,EAExB,KAAK,oBAAoB,EAEzB,KAAK,oBAAoB,EAE1B,MAAM,SAAS,CAAC;AAEjB,eAAO,MAAM,cAAc,qDACmD,CAAC;AAU/E,eAAO,MAAM,kBAAkB,uDAE9B,CAAC;AAEF,wBAAgB,eAAe,CAAC,EAAE,QAAQ,EAAE,EAAE,oBAAoB,+BAqJjE"}

package/dist/modules/loading/index.js

@@ -1,5 +1,5 @@
 "use client";
-export { DEFAULT_LOADING_STATE, DEFAULT_LOADING_STATE_WITH_PAGE, INERT_LOADING_ACTIONS, LOADING_REGISTRY_KEY, LoadingContext, LoadingOverlay, LoadingProvider, NOOP_LOADING_STORE, calculateRemainingMinDuration, defineLoading, loadingModule, loadingTheme, normalizeLoadingOptions, resolveLoadingState, selectPageLoading, useLoading, useLoadingActions, useLoadingOverlayModel, useLoadingRegistration, useLoadingState, useOptionalLoadingActions, useOptionalLoadingState } from '../../chunk-XASQT4CQ.js';
+export { DEFAULT_LOADING_STATE, DEFAULT_LOADING_STATE_WITH_PAGE, INERT_LOADING_ACTIONS, LOADING_REGISTRY_KEY, LoadingContext, LoadingOverlay, LoadingProvider, NOOP_LOADING_STORE, calculateRemainingMinDuration, defineLoading, loadingModule, loadingTheme, normalizeLoadingOptions, resolveLoadingState, selectPageLoading, useLoading, useLoadingActions, useLoadingOverlayModel, useLoadingRegistration, useLoadingState, useOptionalLoadingActions, useOptionalLoadingState } from '../../chunk-66EYJBIP.js';
 import '../../chunk-7TAVYJ3A.js';
 import '../../chunk-GF7TUX5I.js';
 import '../../chunk-TV3WEF5G.js';

package/dist/modules/navigation/constants.d.ts

@@ -0,0 +1,37 @@
+export declare const NAVIGATION_STATUS: Readonly<{
+    readonly PENDING: "pending";
+    readonly COMPLETED: "completed";
+    readonly CANCELLED: "cancelled";
+    readonly FAILED: "failed";
+    readonly TIMED_OUT: "timed-out";
+}>;
+export declare const NAVIGATION_PHASE: Readonly<{
+    readonly LEAVING: "leaving";
+    readonly ROUTING: "routing";
+}>;
+export declare const NAVIGATION_REASON: Readonly<{
+    readonly GUARD: "guard";
+    readonly RETURNED: "returned";
+    readonly SUPERSEDED: "superseded";
+    readonly TIME_OUT: "time-out";
+}>;
+export declare const NAVIGATION_SOURCE: Readonly<{
+    readonly HISTORY: "history";
+    readonly NAVIGATE: "navigate";
+}>;
+export declare const NAVIGATION_EVENTS: Readonly<{
+    /** A trip started (phase `leaving`). */
+    readonly START: "NAVIGATION_START";
+    /** The router was asked for the route (phase `routing`). */
+    readonly COMMIT: "NAVIGATION_COMMIT";
+    /** The trip settled, whatever its status. */
+    readonly END: "NAVIGATION_END";
+}>;
+export declare const NAVIGATION_INTENT_DELAY_MS = 180;
+export declare const NAVIGATION_PREFETCH_TTL_MS: number;
+export declare const NAVIGATION_ARRIVAL_TTL_MS = 20000;
+export declare const NAVIGATION_MAX_HOLD_MS = 5000;
+export declare const NAVIGATION_TIMEOUT_MS = 15000;
+/** Links with this attribute set to `"false"` are never warmed on intent. */
+export declare const NAVIGATION_PREFETCH_ATTRIBUTE = "data-prefetch";
+//# sourceMappingURL=constants.d.ts.map

package/dist/modules/navigation/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/modules/navigation/constants.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,iBAAiB;;;;;;EAMwB,CAAC;AAEvD,eAAO,MAAM,gBAAgB;;;EAGwB,CAAC;AAEtD,eAAO,MAAM,iBAAiB;;;;;EAKnB,CAAC;AAEZ,eAAO,MAAM,iBAAiB;;;EAGnB,CAAC;AAEZ,eAAO,MAAM,iBAAiB;IAC5B,wCAAwC;;IAExC,4DAA4D;;IAE5D,6CAA6C;;EAEpC,CAAC;AAEZ,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAC9C,eAAO,MAAM,0BAA0B,QAAa,CAAC;AACrD,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAChD,eAAO,MAAM,sBAAsB,OAAQ,CAAC;AAC5C,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAE5C,6EAA6E;AAC7E,eAAO,MAAM,6BAA6B,kBAAkB,CAAC"}

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

@@ -0,0 +1,10 @@
+import { type ReactNode } from "react";
+import type { NavigationActions, NavigationRuntime, NavigationState } from "./types";
+export declare const NavigationContext: import("react").Context<NavigationRuntime | null>;
+/** What readers get without the module: no trips, nothing held or warmed. */
+export declare const INERT_NAVIGATION_ACTIONS: NavigationActions;
+export declare const NOOP_NAVIGATION_STORE: import("../../utils").ExternalStore<NavigationState>;
+export declare function NavigationProvider({ children }: {
+    children?: ReactNode;
+}): import("react").JSX.Element;
+//# sourceMappingURL=context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/modules/navigation/context.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAgC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AASrE,OAAO,KAAK,EACV,iBAAiB,EAGjB,iBAAiB,EACjB,eAAe,EAChB,MAAM,SAAS,CAAC;AAGjB,eAAO,MAAM,iBAAiB,mDAI3B,CAAC;AAKJ,6EAA6E;AAC7E,eAAO,MAAM,wBAAwB,EAAE,iBAYrC,CAAC;AAEH,eAAO,MAAM,qBAAqB,kDAEjC,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAE,+BA0BxE"}

package/dist/modules/navigation/hooks.d.ts

@@ -0,0 +1,29 @@
+import type { NavigationActions, NavigationHold, NavigationHoldOptions, NavigationIntentListener, NavigationPayloadKey, NavigationPayloadValue, NavigationState, NavigationTrip } from "./types";
+/** The navigator's actions. Throws outside `NavigationProvider`. */
+export declare function useNavigation(): NavigationActions;
+/** The navigator's actions, or inert ones when the module is not installed. */
+export declare function useOptionalNavigation(): NavigationActions;
+export declare function useNavigationState(): NavigationState;
+export declare function useNavigationState<T>(selector: (state: NavigationState) => T, isEqual?: (a: T, b: T) => boolean): T;
+/**
+ * Holds every trip leaving while this component is mounted, until the
+ * returned promise settles (capped by `maxHoldMs`). Pass `false` or `null`
+ * to hold nothing. Watch `trip.signal` to undo an exit that never lands.
+ */
+export declare function useNavigationHold(hold: NavigationHold | false | null | undefined, { history }?: NavigationHoldOptions): void;
+/**
+ * Adds `key` to the payload of every trip leaving while this component is
+ * mounted. A function is called when the trip starts.
+ */
+export declare function useNavigationPayload<K extends NavigationPayloadKey>(key: K, value: NavigationPayloadValue<K>): void;
+/** Called with each path the navigator warms, from links, the dock or code. */
+export declare function useNavigationIntent(listener: NavigationIntentListener): void;
+/** The trip leaving the current page, while it is under way. */
+export declare function useDeparture(): NavigationTrip | null;
+/**
+ * The trip that brought the page to `pathname` (default: the current one),
+ * from the moment the router is asked for it until `arrivalTtlMs` later or
+ * until the page is left. A route's `loading.tsx` reads it too.
+ */
+export declare function useArrival(pathname?: string): NavigationTrip | null;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/modules/navigation/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../../src/modules/navigation/hooks.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EACd,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,EACf,cAAc,EACf,MAAM,SAAS,CAAC;AAGjB,oEAAoE;AACpE,wBAAgB,aAAa,IAAI,iBAAiB,CAMjD;AAED,+EAA+E;AAC/E,wBAAgB,qBAAqB,IAAI,iBAAiB,CAEzD;AAED,wBAAgB,kBAAkB,IAAI,eAAe,CAAC;AACtD,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,QAAQ,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,CAAC,EACvC,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,GAChC,CAAC,CAAC;AAsBL;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,cAAc,GAAG,KAAK,GAAG,IAAI,GAAG,SAAS,EAC/C,EAAE,OAAc,EAAE,GAAE,qBAA0B,GAC7C,IAAI,CAWN;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,oBAAoB,EACjE,GAAG,EAAE,CAAC,EACN,KAAK,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAC/B,IAAI,CAaN;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,wBAAwB,GAAG,IAAI,CAO5E;AAED,gEAAgE;AAChE,wBAAgB,YAAY,IAAI,cAAc,GAAG,IAAI,CAMpD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAKnE"}

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

@@ -0,0 +1,10 @@
+export type * from "./types";
+export { navigationModule } from "./module";
+export { INERT_NAVIGATION_ACTIONS, NavigationContext, NavigationProvider, } from "./context";
+export { useArrival, useDeparture, useNavigation, useNavigationHold, useNavigationIntent, useNavigationPayload, useNavigationState, useOptionalNavigation, } from "./hooks";
+export { createNavigator } from "./navigator";
+export { watchHistory, watchIntent } from "./listeners";
+export { configureNavigation, getNavigationSettings, } from "./settings";
+export { NAVIGATION_EVENTS, NAVIGATION_PHASE, NAVIGATION_REASON, NAVIGATION_SOURCE, NAVIGATION_STATUS, } from "./constants";
+export { isSafeInternalHref, locationKeyOf, pathOf } from "./utils";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/navigation/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,SAAS,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,UAAU,EACV,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EACL,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC"}

package/dist/modules/navigation/index.js

@@ -0,0 +1,81 @@
+"use client";
+import { NavigationContext, INERT_NAVIGATION_ACTIONS, NOOP_NAVIGATION_STORE } from '../../chunk-RIOKLMYM.js';
+export { INERT_NAVIGATION_ACTIONS, NavigationContext, NavigationProvider, navigationModule, watchHistory, watchIntent } from '../../chunk-RIOKLMYM.js';
+import { isSamePathname, tripDestination } from '../../chunk-HLL5EHXC.js';
+export { NAVIGATION_EVENTS, NAVIGATION_PHASE, NAVIGATION_REASON, NAVIGATION_SOURCE, NAVIGATION_STATUS, configureNavigation, createNavigator, getNavigationSettings, isSafeInternalHref, locationKeyOf, pathOf } from '../../chunk-HLL5EHXC.js';
+import '../../chunk-GF7TUX5I.js';
+import { useRequiredContext, useStore, useIsomorphicLayoutEffect } from '../../chunk-TV3WEF5G.js';
+import { useContext, useEffect, useRef } from 'react';
+import { usePathname } from 'next/navigation';
+
+function useNavigation() {
+  return useRequiredContext(
+    NavigationContext,
+    "useNavigation",
+    "NavigationProvider"
+  ).actions;
+}
+function useOptionalNavigation() {
+  return useContext(NavigationContext)?.actions ?? INERT_NAVIGATION_ACTIONS;
+}
+function useNavigationState(selector, isEqual) {
+  const store = useContext(NavigationContext)?.store ?? NOOP_NAVIGATION_STORE;
+  return useStore(
+    store,
+    selector,
+    isEqual
+  );
+}
+function useLatest(value) {
+  const ref = useRef(value);
+  useIsomorphicLayoutEffect(() => {
+    ref.current = value;
+  }, [value]);
+  return ref;
+}
+function useNavigationHold(hold, { history = true } = {}) {
+  const { hold: register } = useOptionalNavigation();
+  const latest = useLatest(hold);
+  const enabled = Boolean(hold);
+  useEffect(() => {
+    if (!enabled) return;
+    return register((trip) => {
+      const run = latest.current;
+      return run ? run(trip) : void 0;
+    }, { history });
+  }, [enabled, history, latest, register]);
+}
+function useNavigationPayload(key, value) {
+  const { provide } = useOptionalNavigation();
+  const latest = useLatest(value);
+  useEffect(
+    () => provide(key, (() => {
+      const current = latest.current;
+      return typeof current === "function" ? current() : current;
+    })),
+    [key, latest, provide]
+  );
+}
+function useNavigationIntent(listener) {
+  const { onIntent } = useOptionalNavigation();
+  const latest = useLatest(listener);
+  useEffect(
+    () => onIntent((path, href) => latest.current(path, href)),
+    [latest, onIntent]
+  );
+}
+function useDeparture() {
+  const pathname = usePathname();
+  const active = useNavigationState((state) => state.active);
+  return active && !isSamePathname(tripDestination(active), pathname) ? active : null;
+}
+function useArrival(pathname) {
+  const routePathname = usePathname();
+  const target = pathname ?? routePathname;
+  const { arrival } = useOptionalNavigation();
+  return useNavigationState(() => arrival(target));
+}
+
+export { useArrival, useDeparture, useNavigation, useNavigationHold, useNavigationIntent, useNavigationPayload, useNavigationState, useOptionalNavigation };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/modules/navigation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/modules/navigation/hooks.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["\"use client\";\n\nimport { useContext, useEffect, useRef } from \"react\";\nimport { usePathname } from \"next/navigation\";\nimport { useIsomorphicLayoutEffect, useRequiredContext, useStore } from \"@/hooks\";\nimport {\n  INERT_NAVIGATION_ACTIONS,\n  NOOP_NAVIGATION_STORE,\n  NavigationContext,\n} from \"./context\";\nimport { tripDestination } from \"./state\";\nimport type {\n  NavigationActions,\n  NavigationHold,\n  NavigationHoldOptions,\n  NavigationIntentListener,\n  NavigationPayloadKey,\n  NavigationPayloadValue,\n  NavigationState,\n  NavigationTrip,\n} from \"./types\";\nimport { isSamePathname } from \"./utils\";\n\n/** The navigator's actions. Throws outside `NavigationProvider`. */\nexport function useNavigation(): NavigationActions {\n  return useRequiredContext(\n    NavigationContext,\n    \"useNavigation\",\n    \"NavigationProvider\",\n  ).actions;\n}\n\n/** The navigator's actions, or inert ones when the module is not installed. */\nexport function useOptionalNavigation(): NavigationActions {\n  return useContext(NavigationContext)?.actions ?? INERT_NAVIGATION_ACTIONS;\n}\n\nexport function useNavigationState(): NavigationState;\nexport function useNavigationState<T>(\n  selector: (state: NavigationState) => T,\n  isEqual?: (a: T, b: T) => boolean,\n): T;\nexport function useNavigationState<T = NavigationState>(\n  selector?: (state: NavigationState) => T,\n  isEqual?: (a: T, b: T) => boolean,\n): T {\n  const store = useContext(NavigationContext)?.store ?? NOOP_NAVIGATION_STORE;\n  return useStore(\n    store,\n    selector as (state: NavigationState) => T,\n    isEqual,\n  );\n}\n\n/** The latest value of `value`, readable from callbacks registered once. */\nfunction useLatest<T>(value: T) {\n  const ref = useRef(value);\n  useIsomorphicLayoutEffect(() => {\n    ref.current = value;\n  }, [value]);\n  return ref;\n}\n\n/**\n * Holds every trip leaving while this component is mounted, until the\n * returned promise settles (capped by `maxHoldMs`). Pass `false` or `null`\n * to hold nothing. Watch `trip.signal` to undo an exit that never lands.\n */\nexport function useNavigationHold(\n  hold: NavigationHold | false | null | undefined,\n  { history = true }: NavigationHoldOptions = {},\n): void {\n  const { hold: register } = useOptionalNavigation();\n  const latest = useLatest(hold);\n  const enabled = Boolean(hold);\n  useEffect(() => {\n    if (!enabled) return;\n    return register((trip) => {\n      const run = latest.current;\n      return run ? run(trip) : undefined;\n    }, { history });\n  }, [enabled, history, latest, register]);\n}\n\n/**\n * Adds `key` to the payload of every trip leaving while this component is\n * mounted. A function is called when the trip starts.\n */\nexport function useNavigationPayload<K extends NavigationPayloadKey>(\n  key: K,\n  value: NavigationPayloadValue<K>,\n): void {\n  const { provide } = useOptionalNavigation();\n  const latest = useLatest(value);\n  useEffect(\n    () =>\n      provide(key, (() => {\n        const current = latest.current;\n        return typeof current === \"function\"\n          ? (current as () => unknown)()\n          : current;\n      }) as NavigationPayloadValue<K>),\n    [key, latest, provide],\n  );\n}\n\n/** Called with each path the navigator warms, from links, the dock or code. */\nexport function useNavigationIntent(listener: NavigationIntentListener): void {\n  const { onIntent } = useOptionalNavigation();\n  const latest = useLatest(listener);\n  useEffect(\n    () => onIntent((path, href) => latest.current(path, href)),\n    [latest, onIntent],\n  );\n}\n\n/** The trip leaving the current page, while it is under way. */\nexport function useDeparture(): NavigationTrip | null {\n  const pathname = usePathname();\n  const active = useNavigationState((state) => state.active);\n  return active && !isSamePathname(tripDestination(active), pathname)\n    ? active\n    : null;\n}\n\n/**\n * The trip that brought the page to `pathname` (default: the current one),\n * from the moment the router is asked for it until `arrivalTtlMs` later or\n * until the page is left. A route's `loading.tsx` reads it too.\n */\nexport function useArrival(pathname?: string): NavigationTrip | null {\n  const routePathname = usePathname();\n  const target = pathname ?? routePathname;\n  const { arrival } = useOptionalNavigation();\n  return useNavigationState(() => arrival(target));\n}\n"]}

package/dist/modules/navigation/listeners.d.ts

@@ -0,0 +1,15 @@
+import type { NavigationSettings, Navigator } from "./types";
+/**
+ * Prefetches internal links on intent: after `intent.delayMs` of mouse hover,
+ * and at once on pointerdown or focus. Returns the cleanup.
+ */
+export declare function watchIntent(navigator: Pick<Navigator, "prefetch">, settings: () => NavigationSettings, doc?: Document): () => void;
+/**
+ * Turns back/forward steps into trips. While a hold wants history steps, the
+ * step is swallowed before the router sees it (a capture listener on
+ * `window` runs first), the holds run, and the same `popstate` is replayed
+ * for the router. Stepping back to the origin during the hold cancels the
+ * trip. Returns the cleanup.
+ */
+export declare function watchHistory(navigator: Pick<Navigator, "cancel" | "depart" | "holdsHistory" | "store">, win?: Window): () => void;
+//# sourceMappingURL=listeners.d.ts.map

package/dist/modules/navigation/listeners.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listeners.d.ts","sourceRoot":"","sources":["../../../src/modules/navigation/listeners.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAQ7D;;;GAGG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,EACtC,QAAQ,EAAE,MAAM,kBAAkB,EAClC,GAAG,GAAE,QAAmB,GACvB,MAAM,IAAI,CAmDZ;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,GAAG,QAAQ,GAAG,cAAc,GAAG,OAAO,CAAC,EAC1E,GAAG,GAAE,MAAe,GACnB,MAAM,IAAI,CA2CZ"}

package/dist/modules/navigation/module.d.ts

@@ -0,0 +1,25 @@
+import type { NavigationTrip } from "./types";
+export declare const navigationModule: import("@omerdlw/base-framework/kernel").CoreModule<"navigation", import("./types").NavigationRuntime, never, never>;
+interface NavigationEventPayload {
+    from: string;
+    source: string;
+    timestamp: number;
+    to: string;
+    trip: NavigationTrip;
+    type: string;
+    [key: string]: unknown;
+}
+declare module "@omerdlw/base-framework/events" {
+    interface FrameworkEventMap {
+        NAVIGATION_START: NavigationEventPayload;
+        NAVIGATION_COMMIT: NavigationEventPayload;
+        NAVIGATION_END: NavigationEventPayload;
+    }
+}
+declare module "@omerdlw/base-framework/kernel" {
+    interface CoreModules {
+        navigation: typeof navigationModule;
+    }
+}
+export {};
+//# sourceMappingURL=module.d.ts.map

package/dist/modules/navigation/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../../../src/modules/navigation/module.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,eAAO,MAAM,gBAAgB,sHAI3B,CAAC;AAEH,UAAU,sBAAsB;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,OAAO,QAAQ,gCAAgC,CAAC;IAC9C,UAAU,iBAAiB;QACzB,gBAAgB,EAAE,sBAAsB,CAAC;QACzC,iBAAiB,EAAE,sBAAsB,CAAC;QAC1C,cAAc,EAAE,sBAAsB,CAAC;KACxC;CACF;AAED,OAAO,QAAQ,gCAAgC,CAAC;IAC9C,UAAU,WAAW;QACnB,UAAU,EAAE,OAAO,gBAAgB,CAAC;KACrC;CACF"}

package/dist/modules/navigation/navigator.d.ts

@@ -0,0 +1,8 @@
+import type { Navigator, NavigatorOptions } from "./types";
+/**
+ * The navigation state machine: one active trip at a time, from the first
+ * intent through holds and the router call to arrival. Pure: no React, no
+ * Next; the provider binds a router and reports arrivals.
+ */
+export declare function createNavigator(options?: NavigatorOptions): Navigator;
+//# sourceMappingURL=navigator.d.ts.map

package/dist/modules/navigation/navigator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigator.d.ts","sourceRoot":"","sources":["../../../src/modules/navigation/navigator.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAcV,SAAS,EACT,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAqBjB;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,gBAAqB,GAAG,SAAS,CA2YzE"}

package/dist/modules/navigation/settings.d.ts

@@ -0,0 +1,10 @@
+import type { NavigationSettings, NavigationSettingsInput } from "./types";
+export declare function getNavigationSettings(): NavigationSettings;
+export declare function mergeNavigationSettings(base: NavigationSettings, input: NavigationSettingsInput): NavigationSettings;
+/**
+ * Sets intent prefetch, the warm cache, hold and arrival windows and the
+ * route timeout for every navigator. Returns a function that restores the
+ * previous settings.
+ */
+export declare function configureNavigation(input: NavigationSettingsInput): () => void;
+//# sourceMappingURL=settings.d.ts.map

package/dist/modules/navigation/settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../../src/modules/navigation/settings.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAEV,kBAAkB,EAClB,uBAAuB,EACxB,MAAM,SAAS,CAAC;AA0BjB,wBAAgB,qBAAqB,IAAI,kBAAkB,CAE1D;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,kBAAkB,EACxB,KAAK,EAAE,uBAAuB,GAC7B,kBAAkB,CAWpB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,uBAAuB,GAAG,MAAM,IAAI,CAO9E"}

package/dist/modules/navigation/state.d.ts

@@ -0,0 +1,20 @@
+import type { NavigationPayload, NavigationState, NavigationStatus, NavigationTrip } from "./types";
+export declare function createNavigationState(location?: string): NavigationState;
+export declare function createTrip({ from, href, id, payload, signal, source, startedAt, }: {
+    from: string;
+    href: string;
+    id: number;
+    payload?: NavigationPayload;
+    signal: AbortSignal;
+    source: string;
+    startedAt: number;
+}): NavigationTrip;
+export declare function settleTrip(trip: NavigationTrip, status: NavigationStatus, { arrivedAt, endedAt, error, reason, }: {
+    arrivedAt?: string;
+    endedAt: number;
+    error?: unknown;
+    reason?: string | null;
+}): NavigationTrip;
+/** Where a trip ends up: where it landed, else where it was headed. */
+export declare const tripDestination: (trip: NavigationTrip) => string;
+//# sourceMappingURL=state.d.ts.map

package/dist/modules/navigation/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/modules/navigation/state.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,cAAc,EACf,MAAM,SAAS,CAAC;AAGjB,wBAAgB,qBAAqB,CAAC,QAAQ,SAAK,GAAG,eAAe,CAEpE;AAED,wBAAgB,UAAU,CAAC,EACzB,IAAI,EACJ,IAAI,EACJ,EAAE,EACF,OAAY,EACZ,MAAM,EACN,MAAM,EACN,SAAS,GACV,EAAE;IACD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,cAAc,CAajB;AAED,wBAAgB,UAAU,CACxB,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,gBAAgB,EACxB,EACE,SAAS,EACT,OAAO,EACP,KAAY,EACZ,MAAa,GACd,EAAE;IACD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB,GACA,cAAc,CAIhB;AAED,uEAAuE;AACvE,eAAO,MAAM,eAAe,GAAI,MAAM,cAAc,KAAG,MAC5B,CAAC"}

package/dist/modules/navigation/types.d.ts

@@ -0,0 +1,168 @@
+import type { ExternalStore } from "../../utils";
+/**
+ * What a departing page hands the destination. Empty by default: apps add
+ * their own keys by augmentation, so the framework depends on none of them.
+ *
+ * ```ts
+ * declare module "@omerdlw/base-framework/modules/navigation" {
+ *   interface NavigationPayload {
+ *     palette?: AmbientPalette | null;
+ *   }
+ * }
+ * ```
+ */
+export interface NavigationPayload {
+}
+export type NavigationPayloadKey = keyof NavigationPayload & string;
+export type NavigationStatus = "pending" | "completed" | "cancelled" | "failed" | "timed-out";
+/** `leaving`: holds run, the route has not been asked for yet. `routing`: it has. */
+export type NavigationPhase = "leaving" | "routing";
+export interface NavigationTrip {
+    /** Where the trip actually landed, when it differs from `to` (a redirect). */
+    arrivedAt?: string;
+    endedAt?: number;
+    error?: unknown;
+    /** The location key the trip left from. */
+    from: string;
+    /** The href as given, passed to the router unchanged. */
+    href: string;
+    id: number;
+    payload: Readonly<NavigationPayload>;
+    phase: NavigationPhase;
+    reason?: string | null;
+    /** Aborts when the trip is cancelled, fails or times out. */
+    signal: AbortSignal;
+    /** `dock`, `history`, `navigate`, or whatever the caller passed. */
+    source: string;
+    startedAt: number;
+    status: NavigationStatus;
+    /** The destination's location key (pathname, search and hash). */
+    to: string;
+}
+export interface NavigationState {
+    active: NavigationTrip | null;
+    last: NavigationTrip | null;
+    /** The location key the navigator last saw arrive. */
+    location: string;
+}
+export type NavigationPrefetchKind = "auto" | "full" | "temporary";
+export interface NavigationRouter {
+    back?(): void;
+    prefetch(href: string, options?: {
+        kind?: NavigationPrefetchKind;
+        onInvalidate?: () => void;
+    }): void;
+    push(href: string, options?: {
+        scroll?: boolean;
+    }): void;
+    replace(href: string, options?: {
+        scroll?: boolean;
+    }): void;
+}
+export interface NavigationBlock {
+    blocked: boolean;
+    message?: string;
+    [key: string]: unknown;
+}
+export interface NavigateOptions {
+    /** Skip `guard`. Holds still run. */
+    force?: boolean;
+    /**
+     * Runs once the trip has started and before holds. A `blocked` result
+     * cancels the trip with reason `blocked`. The dock runs its guards here.
+     */
+    guard?: (trip: NavigationTrip) => NavigationBlock | boolean | Promise<NavigationBlock | boolean>;
+    /** Runs right before the router is called, once guard and holds passed. */
+    onCommit?: (trip: NavigationTrip) => void;
+    /** Merged over what `provide` contributes. */
+    payload?: Partial<NavigationPayload>;
+    replace?: boolean;
+    scroll?: boolean;
+    source?: string;
+}
+export interface NavigationResult {
+    blocked?: NavigationBlock;
+    /** `true` when the router was asked for the route. */
+    ok: boolean;
+    trip: NavigationTrip | null;
+}
+/**
+ * Runs when a trip leaves. The trip commits once every returned promise
+ * settles, or after `maxHoldMs`. Watch `trip.signal` to undo an exit that
+ * never lands.
+ */
+export type NavigationHold = (trip: NavigationTrip) => void | Promise<unknown>;
+export interface NavigationHoldOptions {
+    /** Also hold back/forward steps. Default `true`. */
+    history?: boolean;
+}
+export type NavigationPayloadValue<K extends NavigationPayloadKey> = NavigationPayload[K] | (() => NavigationPayload[K]);
+export type NavigationIntentListener = (path: string, href: string) => void;
+export interface NavigationPrefetchOptions {
+    /** Skip the warm cache and prefetch again. */
+    force?: boolean;
+    kind?: NavigationPrefetchKind;
+}
+export interface NavigationIntentSettings {
+    /** Mouse dwell before a hovered link is prefetched. */
+    delayMs: number;
+    /** Which links to warm. Internal hrefs only, whatever this returns. */
+    match: (href: string) => boolean;
+}
+export interface NavigationSettings {
+    /** How long a settled trip stays readable by `useArrival`. */
+    arrivalTtlMs: number;
+    /** Document-level intent prefetch for `a[href]`; `false` turns it off. */
+    intent: NavigationIntentSettings | false;
+    /** Cap on holds; past it the trip commits anyway. */
+    maxHoldMs: number;
+    prefetchKind: NavigationPrefetchKind;
+    /** How long a warmed path is not prefetched again. */
+    prefetchTtlMs: number;
+    /** Patience once the route was asked for; then the trip times out. */
+    timeoutMs: number;
+}
+export interface NavigationSettingsInput extends Partial<Omit<NavigationSettings, "intent">> {
+    intent?: Partial<NavigationIntentSettings> | boolean;
+}
+export interface NavigatorOptions {
+    emit?: (event: string, payload: Record<string, unknown>) => void;
+    /** Runs `callback` after the next paint. */
+    nextFrame?: (callback: () => void) => void;
+    now?: () => number;
+    /** The browser's current location key, or `null` off the browser. */
+    readLocation?: () => string | null;
+    router?: NavigationRouter | null;
+    settings?: () => NavigationSettings;
+}
+export interface NavigationActions {
+    /** The fresh trip that ended at `pathname`, or `null`. */
+    arrival(pathname: string): NavigationTrip | null;
+    /** Tells the navigator the location changed. The provider calls it. */
+    arrive(location: string): void;
+    /** Cancels the active trip. */
+    cancel(reason?: string | null): boolean;
+    /** Starts a trip from the browser's own back/forward step. */
+    depart(to: string, options?: {
+        replay?: () => void;
+        source?: string;
+    }): NavigationTrip | null;
+    hold(hold: NavigationHold, options?: NavigationHoldOptions): () => void;
+    /** Whether a hold wants back/forward steps. */
+    holdsHistory(): boolean;
+    navigate(href: string, options?: NavigateOptions): Promise<NavigationResult>;
+    onIntent(listener: NavigationIntentListener): () => void;
+    prefetch(href: string, options?: NavigationPrefetchOptions): boolean;
+    provide<K extends NavigationPayloadKey>(key: K, value: NavigationPayloadValue<K>): () => void;
+    /** Points the navigator at another router (the provider's). */
+    setRouter(router: NavigationRouter | null): void;
+}
+export interface Navigator extends NavigationActions {
+    dispose(): void;
+    store: ExternalStore<NavigationState>;
+}
+export interface NavigationRuntime {
+    actions: NavigationActions;
+    store: ExternalStore<NavigationState>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/modules/navigation/types.d.ts.map

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

package/dist/modules/navigation/utils.d.ts

@@ -0,0 +1,11 @@
+export declare function isSafeInternalHref(value: unknown): boolean;
+/** The pathname of an href, without search, hash or trailing slash. */
+export declare function pathOf(href: string): string;
+/** An href's location key: normalized pathname plus its search and hash. */
+export declare function locationKeyOf(href: string): string;
+export declare function isSameLocation(left: string, right: string): boolean;
+export declare function isSamePathname(left: string, right: string): boolean;
+export declare function readWindowLocation(): string | null;
+/** The link with an internal href around `target`, or `null`. */
+export declare function internalLinkOf(target: EventTarget | null): Element | null;
+//# sourceMappingURL=utils.d.ts.map

package/dist/modules/navigation/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/modules/navigation/utils.ts"],"names":[],"mappings":"AAEA,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAG1D;AAED,uEAAuE;AACvE,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKlD;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnE;AAED,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,IAAI,CAIlD;AAED,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,GAAG,OAAO,GAAG,IAAI,CAKzE"}

package/docs/getting-started.md

@@ -77,6 +77,7 @@ import { ambientModule } from "@omerdlw/base-framework/modules/ambient";
 import { backgroundModule } from "@omerdlw/base-framework/modules/background";
 import { controlsModule } from "@omerdlw/base-framework/modules/controls";
 import { loadingModule } from "@omerdlw/base-framework/modules/loading";
+import { navigationModule } from "@omerdlw/base-framework/modules/navigation";
 import { contextMenuModule } from "@omerdlw/base-framework/modules/context-menu";
 
 // Define the modules your application uses
@@ -88,6 +89,7 @@ const modules = [
   backgroundModule,
   controlsModule,
   loadingModule,
+  navigationModule,
   contextMenuModule,
 ];
 

package/docs/modules/README.md

@@ -12,6 +12,7 @@ One page per module/core entry. Each page answers, from the big picture down to
 | Dock           | `@omerdlw/base-framework/modules/dock`                            | [dock.md](./dock.md)                     | The only chrome: card stack, surfaces/flows, HUD, operations, status overlays, guards, breadcrumbs | `dock`               | `dock`        |
 | Modal          | `@omerdlw/base-framework/modules/modal`                           | [modal.md](./modal.md)                   | Promise-based stacked dialogs                                                                      | `modal`              | `modal`       |
 | Notification   | `@omerdlw/base-framework/modules/notification`                    | [notification.md](./notification.md)     | Single-slot toasts docked to the dock; event-driven feedback                                       | `notification`       | —             |
+| Navigation     | `@omerdlw/base-framework/modules/navigation`                      | [navigation.md](./navigation.md)         | Trips: exit holds, payload to the next page, back-button hold, intent prefetch                     | —                    | —             |
 | Loading        | `@omerdlw/base-framework/modules/loading`                         | [loading.md](./loading.md)               | Loading overlay + busy flag                                                                        | `loading`            | `loading`     |
 | Background     | `@omerdlw/base-framework/modules/background`                      | [background.md](./background.md)         | Image / video / YouTube layer behind the page                                                      | `background`         | `background`  |
 | Media          | `@omerdlw/base-framework/modules/media`                           | [media.md](./media.md)                   | The active media session the dock controls operate on                                              | `media`              | `media`       |
@@ -44,6 +45,7 @@ Modules never import each other. They connect through three channels only:
 | dock → `loading`              | `definePeer`             | Page-loading flag; `stopLoading()` after navigation.                         |
 | dock → `media`                | `definePeer`             | Play/pause icon, media controls.                                             |
 | dock → `notification`         | `definePeer`             | Is a toast visible (breadcrumbs yield).                                      |
+| dock → `navigation`           | `useModule`              | Transactions are its trips; card prefetch uses its warm cache. Without it the dock runs its own navigator. |
 | background → `media`          | `definePeer`             | Registers the background video as source `background`.                       |
 | ambient → `background`        | `useModuleState`         | Poster URL as the default tint image.                                        |
 | context-menu → `dock`         | `useModuleState`         | Active card as the default menu header.                                      |
@@ -55,7 +57,7 @@ Every `definePeer`/`useModuleState`/`useModule` call needs the **peer id as a st
 
 ## 3. Install-time facts
 
-- `src/modules/index.ts` exports every module and `defaultModules` (`background, ambient, dock, controls, contextMenu, loading, media, modal, notification`); it is the only place that lists them all. `src/app/providers.tsx` passes the list to `CoreProvider`.
+- `src/modules/index.ts` exports every module and `defaultModules` (`background, ambient, navigation, dock, controls, contextMenu, loading, media, modal, notification`); it is the only place that lists them all. `src/app/providers.tsx` passes the list to `CoreProvider`.
 - Install a subset to ship less: `modules={[dockModule, notificationModule, loadingModule]}`.
 - Module ids are **camelCase** (`contextMenu`); the folder and theme id may be kebab-case (`context-menu`).
 - A module is installable when it has a `module.tsx` (or `module.ts`) with `defineModule`; the order of the list does not matter (`uses` sorts it).
@@ -97,6 +99,7 @@ Rules of thumb:
 | loading      |              ✅               |     ✅      |      ✅      |   ✅    |    —    |    ✅     |    —     |                                                                                      |
 | media        |              ✅               |     ✅      |      ✅      |   ✅    |    —    |    ✅     |    —     |                                                                                      |
 | modal        |              ✅               |     ✅      |      ✅      |   ✅    |   ✅    |    ✅     |    ✅    |                                                                                      |
+| navigation   |              ✅               |     ✅      |      ✅      |   ✅    |   ✅    |     —     |    —     | `navigator.ts`, `listeners.ts`, `settings.ts`                                        |
 | notification |              ✅               | `module.ts` |      ✅      |   ✅    |    —    |    ✅     |    ✅    |                                                                                      |
 
 ### 4.2 Why some optional slots are absent
@@ -106,6 +109,7 @@ Rules of thumb:
 | `ambient`      | `overlay`, `motion`     | Renders nothing: it writes CSS custom properties; transitions are CSS classes from the theme.                                          |
 | `controls`     | `context`, `motion`     | Stateless: entries live in the registry and layout is measured from the DOM. No animation.                                             |
 | `loading`      | `motion`, `state`       | The overlay renders `Spinner` (or a skeleton) and mounts/unmounts instantly; state is a small `useState` in the provider.              |
+| `navigation`   | `overlay`, `motion`     | Renders nothing: it binds the router and listens to the document; animation is the app's, in its holds. |
 | `media`        | `motion`                | Renders nothing; `overlay.tsx` holds only the components that return `null` (`MediaSource`, `MediaOverlay`).                           |
 | `notification` | builder                 | Toasts are imperative: `useToast` (in `hooks.ts`) plays the builder role.                                                              |
 | core `error`   | provider, builder, view | Boundaries are class components configured through props; `boundary.tsx` is the view, `listener.ts` and `reporter.ts` are topic files. |