@omerdlw/base-framework 2.0.1 → 3.0.0

package/docs/modules/ambient.md

@@ -119,7 +119,7 @@ Default names; see §5.2 to rename them or turn groups off. Nothing is written u
 
 `colors` keys are custom property names: a key starting with `--` is used verbatim; anything else becomes `--color-<key>`. `colors` always wins over extracted values.
 
-On cleanup the previous inline values (and priorities) are restored exactly. If `transition` is true (default) the theme's `transition` classes are added to the target while the theme is active (and removed again only for scoped targets, so the global tint keeps animating between pages).
+Themes on the same element stack: the latest wins each variable, and when one goes the one beneath shows again; when the last goes, the inline values (and priorities) from before are restored exactly. A page-wide theme **lingers** `linger` ms (3 s) after it goes, and the next theme to arrive takes over from it at once: so a page that leaves through a `loading.tsx` hands its colours to the next page instead of dropping to the CSS fallbacks for the length of the loading screen. With no next theme, the variables are removed when the time runs out. If `transition` is true (default) the theme's `transition` classes are added to the target while the theme is active (and removed again only for scoped targets, so the global tint keeps animating between pages).
 
 ## 5. Public API
 
@@ -135,6 +135,7 @@ On cleanup the previous inline values (and priorities) are restored exactly. If
 | `extractPaletteFromImage(src, options?)`                                                         | util      | Async client extraction with cache and in-flight de-duplication; resolves `null` on any failure.                                                                                 |
 | `primeAmbientPalette(src, palette)`, `getCachedAmbientPalette(src)`                              | utils     | Seed / read the client cache (e.g. with server palettes).                                                                                                                         |
 | `analyzeAmbientPixels(pixels, options?)`                                                         | util      | The pure analysis on RGBA pixels (`{ data, width, height }`). Same function on server, worker and client.                                                                     |
+| `AMBIENT_ANALYSIS_VERSION`, `skinLikeness(color)`                                                 | const / util | The analysis version (put it in long-lived palette cache keys); how skin-like an OKLCH colour is (0–1).                                                                  |
 | `findContentBounds(pixels)`                                                                      | util      | The letterbox / pillarbox cut used by the analysis.                                                                                                                               |
 | `maxChroma(l, h)`, `toneOf(h, l, rel, cap?)`, `onColorFor(bg, min?)`, `contrastRatio(a, b)`, `formatOklch(lch)`, `srgbToOklab(r, g, b)` | utils | Gamut-aware OKLCH helpers. |
 | `paletteVarMap(palette, names?)`, `resolveAmbientVarMap(…)`, `resolveCssVarNames(overrides?)`    | utils     | The variable maps the hooks write.                                                                                                                                                |
@@ -151,6 +152,7 @@ On cleanup the previous inline values (and priorities) are restored exactly. If
 | `cssVars`        | `null`                              | Per-theme override of the variable names (same shape as `configureAmbient({ cssVars })`).       |
 | `scope`          | `null` → `document.documentElement` | CSS selector string, element, or `ref`. A selector that matches nothing applies nothing.        |
 | `transition`     | `true`                              | Add the theme's transition classes to the target.                                               |
+| `linger`         | `configureAmbient` `linger` (3000) on the page root, `0` on a scoped target | How long (ms) the variables stay after the theme goes, unless another theme takes over first. |
 | `initialPalette` | `null`                              | Palette shown before extraction finishes (and if it fails); used as is (no extraction) when `source` equals `image`. |
 | `options`        | `null`                              | `{ initialPalette, strategy, proxy, analysis }` for this theme.                                 |
 
@@ -168,6 +170,7 @@ Settings live on `globalThis`, so every bundled copy of the module (one per pack
 | `cssVars`    | `--ambient-shadow`, `--ambient-{role}`, `--ambient-on-{role}`, `--ambient-{role}-{tone}`, `--ambient-{region}`, all 11 tones | Rename any variable; `null` turns that variable or group off; `tones: [10, 20, 90]` or `false` limits the ramp variables. |
 | `analysis`   | `DEFAULT_ANALYSIS`                        | `sampleSize` 128, `clusters` 7, `centerWeight` 0.5, `letterbox` true, `minHueDistance` 40, `minContrast` 4.5, `shadowLightness` 0.16. |
 | `cacheLimit` | `100`                                     | Client palettes kept (oldest evicted). |
+| `linger`     | `3000` (`DEFAULT_LINGER_MS`)              | How long (ms) a page-wide theme's variables stay after it goes, so the next page takes over from them. `0` removes them at once. |
 
 ### 5.3 `AmbientPalette`
 
@@ -209,15 +212,15 @@ Before every request, redirects included, the host is resolved (`resolve`, defau
 
 - **Loading (client).** The image URL is fetched as is with `mode: "cors"`: no `?cors=1`, so the request the page already made is answered from the HTTP cache. If that is blocked and the image is cross-origin, it is fetched once more with `cache: "reload"`: some CDNs (TMDB's among them) send CORS headers only to requests that carry an `Origin` and do not `Vary: Origin`, so the copy a plain `<img>` cached has none. Only then is the proxy tried. Give such images `crossOrigin="anonymous"` (`next/image` takes it too) and the one download serves both the `<img>` and the palette, with no blocked request in the console. Decoding uses `createImageBitmap` (asking for a 128 px wide bitmap where supported) and an `OffscreenCanvas` (or a `<canvas>`), so a full-size image is never drawn on the main thread; browsers without `createImageBitmap` fall back to an `<img>`.
 - **Sampling.** The image is scaled to 128 px on its long side, keeping its aspect ratio. Pixels with alpha < 128 are skipped. Uniformly near-black rows/columns at the edges (letterbox / pillarbox; mean L < 0.12, max L < 0.2, at most 22% per side) are cut. Each pixel's weight falls from 1.5 at the centre to 0.5 at the corners (`centerWeight` 0.5).
-- **Clustering.** Pixels are binned by 15-bit RGB (OKLab averaged per bin). Coloured bins (chroma ≥ 0.022) and grey bins are clustered **apart** with weighted, deterministically seeded k-means in OKLab (ΔL counts 0.45×, so hue beats lightness; vivid bins pull up to ~2.5× harder), 5 + 2 clusters by default. Splitting them keeps the greys of a dark poster from using up every cluster and swallowing its one coloured detail.
-- **Roles.** A hue's share is that of its family (clusters within 20°). `dominant` = max share × chroma; `vibrant` = max chroma² × share^0.3; `accent` = the best hue at least `minHueDistance` (40°) from `dominant`, or `vibrant` marked `fromImage: false` when the image has one hue; `muted` = the largest low-chroma (≤ 0.09) colour, or a quiet tone of the dominant hue. Hue trust fades below L 0.28 and above L 0.9.
-- **Tones.** Every role colour and ramp tone is `toneOf(h, L, rel)`: `rel` (the source colour's share of the available chroma, lifted per role) × the most chroma sRGB allows at that L and hue (`maxChroma`, a binary search on the gamut edge, × 0.96). So a dark tone of blue stays blue, and nothing is ever out of gamut.
+- **Clustering.** Pixels are binned by 15-bit RGB (OKLab averaged per bin). Coloured bins (chroma ≥ 0.022) and grey bins are clustered **apart** with weighted, deterministically seeded k-means in OKLab (ΔL counts 0.45×, so hue beats lightness; vivid bins pull up to ~2.5× harder), 5 + 2 clusters by default. Splitting them keeps the greys of a dark poster from using up every cluster and swallowing its one coloured detail. The vivid pull only shapes the clusters: a cluster's colour is the plain mean of its pixels, so a face is not tinted toward the red title it shares a cluster with.
+- **Roles.** A hue's share is that of its family (clusters within 20°). `dominant` = max share × chroma; `vibrant` = max chroma² × share^0.3; `accent` = the best hue at least `minHueDistance` (40°) from `dominant`, or `vibrant` marked `fromImage: false` when the image has one hue; `muted` = the largest low-chroma (≤ 0.09) colour, or a quiet tone of the dominant hue. Skin, hair, wood and tungsten-lit walls (hues near 54°, chroma 0.03–0.12, see `skinLikeness`) count up to 65% less in every pick, roles and regions alike: film frames are full of them, and they are what a frame shows, rarely its mood. Hue trust fades below L 0.28 and above L 0.9.
+- **Tones.** A role keeps about its source's **chroma**, not its share of the gamut: × 1.15 (`dominant`, regions), × 1.3 (`accent`), × 1.35 (`vibrant`), × 1 (`muted`); a faint tint is raised to at most 0.05 so it still reads as a colour; skin is held back up to 30%; and reds and oranges get a 30% lower ceiling, since they read louder than blues at the same chroma. Carrying the gamut share instead (as before `AMBIENT_ANALYSIS_VERSION` 2) turned pale faces and beige rooms into loud orange: at mid lightness orange has twice the room teal has. The ramp keeps the role's share of the gamut at each L (`toneOf`, × 0.96 of `maxChroma`), so a dark tone of blue stays blue; nothing is ever out of gamut.
 - **`shadow`.** The hue of the shadows (clusters at L ≤ 0.5, scored by share × relative chroma) or, without coloured shadows, of `dominant`; at L `shadowLightness` ± 0.02 and up to 0.1 chroma.
 - **`on`.** A near-white or near-black carrying a hint of the role's hue, pushed toward pure white / black until it reaches `minContrast`.
-- **Regions.** Each region (thirds of the content box; `center` is the middle half) takes its most chromatic-and-present cluster at L 0.42–0.72; `strength` is how coloured the region is.
+- **Regions.** Each region (thirds of the content box; `center` is the middle half) takes its most chromatic-and-present cluster, coloured by that cluster's own pixels **in the region** (not its frame-wide mean), at L 0.42–0.72 and × 1.15 its chroma; `strength` is how coloured the region is.
 - **Neutral images.** If coloured pixels make up under 3% (weighted), the palette is grey: `neutral: true`, `dominant`, `vibrant`, `muted`, `shadow` and regions have chroma 0. A vivid detail (≥ 0.6% of the image, chroma ≥ 0.06) still becomes `accent`, e.g. the red coat in *Schindler's List*.
 - **Cost.** About 3–8 ms per image for the analysis (Node, warm); in Chromium, ~13 ms for a cached image end to end on the main thread, ~20 ms through the worker (off the main thread). ~2.7 KB of JSON per palette.
-- **Cache.** Client: `cacheLimit` palettes (oldest evicted), keyed by URL (+ analysis overrides); concurrent requests share one promise. Server: 500 per process.
+- **Cache.** Client: `cacheLimit` palettes (oldest evicted), keyed by URL (+ analysis overrides); concurrent requests share one promise. Server: 500 per process. A cache that outlives a deploy (`unstable_cache`, a database) should carry `AMBIENT_ANALYSIS_VERSION` in its key, so palettes are computed again when the analysis changes.
 - **Stability.** `colors`, `cssVars`, `options` and `initialPalette` are stabilized with `shallowEqual`, so fresh object literals each render do **not** re-apply the theme (keep `cssVars.tones` a constant array). The same pixels always give the same palette.
 - **Failure.** Client: `extractPaletteFromImage` resolves `null` and the hooks keep `initialPalette` (or nothing); it never throws. Server: `null`, except a missing decoder.
 

package/docs/modules/dock.md

@@ -11,7 +11,7 @@
 | **Renders**        | `Dock` overlay, portalled to `document.body`, DOM id `dock-card-stack`                                                                                     |
 | **Registry type**  | `dock` (key policy `path`, lifecycle `route`, cleanup delay 600 ms, entries merged by priority)                                                            |
 | **Page slice**     | `usePage({ dock: {…} })` → controller `page.modules.dock`                                                                                                  |
-| **Peers (`uses`)** | `loading`, `media`, `notification` (optional; inert stand-ins when absent)                                                                                 |
+| **Peers (`uses`)** | `loading`, `media`, `navigation`, `notification` (optional; inert stand-ins when absent, a private navigator for `navigation`)                            |
 | **Theme**          | `dockTheme` slots in `src/config/dock.module.theme.ts`                                                                                                     |
 | **Events it owns** | `DOCK_STATUS_SET`, `DOCK_STATUS_CLEAR`, `DOCK_GUARD`, `DOCK_NOT_FOUND`, `DOCK_NAVIGATE_START` / `DOCK_NAVIGATE` / `DOCK_NAVIGATE_END`, `DOCK_UPDATE_BADGE` |
 | **CSS output**     | `--dock-h` on `<html>` (dock height + 16 px buffer)                                                                                                        |
@@ -35,7 +35,7 @@ Three ideas explain everything else:
 
 1. **Cards come from the registry.** A page registers a card (`usePage({ dock })`, `useDockRegistration`, or static entries in `src/app/registry.tsx`). The card whose `path` matches the URL is the active item. Expanding the stack lists all registered cards and turns it into a navigator.
 2. **One thing owns the top card at a time ("attention").** Surface, status, HUD, operation, loading and the plain route all compete; the highest priority wins (see [§7](#7-attention-who-owns-the-top-card)).
-3. **Navigation goes through the dock.** `navigate()` runs guards, records scroll/focus so "back" restores position, tracks a transaction (timeout, supersession), and prefetches on hover intent.
+3. **Navigation goes through the dock.** `navigate()` runs guards, records scroll/focus so "back" restores position, tracks a transaction (timeout, supersession), and prefetches on hover intent. The transaction is a trip of the [navigation module](./navigation.md) when it is installed.
 
 ## 3. Quick start
 
@@ -270,6 +270,8 @@ How `usePage` turns the slice into registry entries (`dockModule.page`):
 
 The active card is chosen from registered items in this order: a selected data-source item → exact `path` / `targetPath` match → longest path-prefix match → first item. On a 404 page only `/` and the not-found card are listed. While a navigation transaction is pending, the card for the **destination** is used so the dock changes before the route does.
 
+When the path changes and no card claims it yet (only `/` as a prefix, or the first item), the dock **holds the previous card** on top instead of falling back to Home. This covers a `loading.tsx` boundary or a slow fetch before the new page's `usePage` registers. The held card carries `isRoutePending: true` and stays even if its own registration is gone. The hold lasts while the navigation is in flight plus `DOCK_PENDING_ROUTE_HOLD_MS` (2.5 s) after it commits. If no card arrives by then, the usual fallback applies. The first page load has nothing to hold.
+
 ## 7. Attention: who owns the top card?
 
 `resolveDockAttention` scores each candidate and the highest wins. A new candidate with a higher score takes over immediately; when it goes away the next one returns.
@@ -552,12 +554,13 @@ The starter `src/app/error.tsx` (Next.js's segment boundary, which catches page
 Returns `Promise<boolean>` — `true` only when the route change was committed.
 
 1. Rejects unsafe or non-internal hrefs and the current location (`false`).
-2. Starts a **transaction** `{ id, from, to, source, status }` (superseding any pending one).
-3. Unless `force`, awaits every registered guard. If one blocks → the transaction is cancelled with reason `guard`, a `GUARD` status is shown, and the promise resolves `false`. "Leave" later re-commits through the same path (source `guard-confirmation`).
-4. Commit: remember scroll/focus of the old path, blur the active element, prepare the route reset policy, emit `DOCK_NAVIGATE_START`, `router.push`, emit `DOCK_NAVIGATE`.
-5. `DOCK_NAVIGATE_END` is emitted when the location key changes (or in the next frame for same-path hash/query changes); the `loading` module is told to stop.
+2. Starts a **transaction** `{ id, from, to, source, status }` (superseding any pending one). The transaction is a navigation trip ([navigation.md](./navigation.md)): of the shared navigator when the `navigation` module is installed, otherwise of a navigator the dock creates for itself.
+3. Unless `force`, awaits every registered guard (as the trip's `guard`). If one blocks → the transaction is cancelled with reason `guard`, a `GUARD` status is shown, and the promise resolves `false`. "Leave" later re-commits through the same path (source `guard-confirmation`, `force`).
+4. Navigation holds run (exit animations, `useNavigationHold`).
+5. Commit: remember scroll/focus of the old path, blur the active element, prepare the route reset policy, emit `DOCK_NAVIGATE_START`, `router.push`, emit `DOCK_NAVIGATE`.
+6. `DOCK_NAVIGATE_END` is emitted when the location key changes (or in the next frame for same-path hash/query changes); the `loading` module is told to stop.
 
-A transaction times out after 15 s (`stopLoading` is called). Statuses: `pending → completed | cancelled | failed | timed-out`. Expanding or navigating collapses the stack and clears hover/search.
+A transaction times out after 15 s from its start and again from its commit (`navigation` `timeoutMs`; `stopLoading` is called). With the module installed, `dockTransaction` is also set for trips the dock did not start (back/forward, `useNavigation().navigate`), so the dock shows the destination card for them too. Statuses: `pending → completed | cancelled | failed | timed-out`. Expanding or navigating collapses the stack and clears hover/search.
 
 ### 12.2 Guards
 
@@ -577,7 +580,7 @@ const { isActive, setGuard, clearGuard } = useDockGuard({
 
 ### 12.3 Prefetch
 
-Hovering a card for 90 ms prefetches its `path` with `router.prefetch` (leaving the card cancels a pending prefetch); focusing a card with the keyboard prefetches its `targetPath ?? path` **immediately**. Not prefetched: loading, overlay and surface cards, cards with `prefetchDisabled` or `dockPolicy.prefetch: false`. A route is prefetched once; if Next.js invalidates it, it can be prefetched again.
+Hovering a card for 90 ms prefetches its `path` with `router.prefetch` (leaving the card cancels a pending prefetch); focusing a card with the keyboard prefetches its `targetPath ?? path` **immediately**. Not prefetched: loading, overlay and surface cards, cards with `prefetchDisabled` or `dockPolicy.prefetch: false`. A route is prefetched once; if Next.js invalidates it, it can be prefetched again. With the `navigation` module installed the prefetch goes through its shared warm cache (`prefetchKind`, `prefetchTtlMs`, intent listeners), the same one plain links use.
 
 ### 12.4 Route policy
 
@@ -719,8 +722,7 @@ Gotchas:
 | `runtime/display.ts`      | Item pipeline: registry entries → filtered items → active item (applies surface / status / media).                                                                                                                        |
 | `runtime/pipeline.ts`     | Item identity, active item detection, ancestor deduplication, loading item cleanup, and stacking reorder.                                                                                                                |
 | `runtime/commands.ts`     | Context-action registry, `useDockContextActions`, `defineDockAction`.                                                                                                                                                     |
-| `routing/navigation.ts`   | `useDockNavigation`, route policy, topology, prefetch, location key, view connection.                                                                                                                                     |
-| `routing/transactions.ts` | Navigation transaction reducer and timeout.                                                                                                                                                                               |
+| `routing/navigation.ts`   | `useDockNavigation` (on a navigation trip), route policy, topology, prefetch, location key, view connection.                                                                                                                                     |
 | `routing/guards.ts`       | Guard registry, `useDockGuard`, guard confirmation.                                                                                                                                                                       |
 | `routing/continuity.ts`   | Scroll/focus snapshots and return handoffs.                                                                                                                                                                               |
 | `routing/breadcrumbs.tsx` | Breadcrumb resolution, provider, overrides, `defineBreadcrumb`.                                                                                                                                                           |

package/docs/modules/loading.md

@@ -95,7 +95,7 @@ CheckoutLoading.use(isSubmitting); // boolean | message string | LoadingOptions
 | `stopLoading()`                         | Turn it off. If `minDuration` has not elapsed yet, the stop is **delayed** by the remaining time. With no `minDuration` it is immediate. |
 | `setLoading(boolean)`                   | Shorthand for the two above (no options).                                                                                                |
 | `setSkeleton(nodeOrUpdater)`            | Replace the manual skeleton; accepts `(current) => next`. No re-render when unchanged.                                                   |
-| `withLoading(task, options \| message)` | `startLoading`, await the promise (or call the function and await its result), `stopLoading` in `finally`. Rejections propagate.         |
+| `withLoading(task, options \| message)` | Starts its own task, awaits the promise (or calls the function and awaits its result), ends the task in `finally`. Rejections propagate. |
 
 `page.modules.loading` = these actions plus `set(loading)` (`page.set({ loading })`).
 
@@ -115,7 +115,7 @@ The same value also feeds the dock's `isLoading` card flag (`usePage({ dock })`
 - **Graceful cleanup.** The registry entry survives 600 ms after the page unmounts, so a route change does not flash the overlay off and on between pages.
 - **`minDuration` is manual-only.** Page-registered loading ends as soon as the page stops declaring it.
 - **Navigation.** The dock calls `stopLoading()` after a navigation completes or times out (15 s), so a `startLoading()` made before navigating does not stick.
-- **No counter.** Manual loading is a single flag. Two overlapping `withLoading` calls share it: the **first** to finish stops it. Use a page-level `loading` flag derived from your own pending count if you need reference counting.
+- **Overlapping tasks.** Each `withLoading` call is its own task: loading stays on until the **last** one ends, and the overlay shows the latest task's message and skeleton (the one beneath shows again when it ends). `startLoading` / `stopLoading` / `setLoading` are one more task, a single switch: calling `startLoading` twice and `stopLoading` once turns it off. `minDuration` counts from the first task to the last.
 - **Fullscreen suppression.** While `useIsFullscreenStateActive()` is true (a full-screen view is active) the overlay is hidden.
 - **Accessibility.** The overlay has `role="status"`, `aria-busy="true"` and `aria-label="Loading"`.
 - **Next.js `loading.tsx`.** `src/app/loading.tsx` (a bare `Spinner`) is the route-segment fallback and is independent of this module.

package/docs/modules/navigation.md

@@ -0,0 +1,216 @@
+# Navigation — `@omerdlw/base-framework/modules/navigation`
+
+> **Read this first if you need to:** play an exit animation before the route changes (on a click, the dock or the back button), hand data from the page being left to the page being opened (a palette, a scroll position, a grade), prefetch links on hover intent, or know whether a navigation is under way.
+
+## 1. At a glance
+
+|                    |                                                                                                                         |
+| :----------------- | :---------------------------------------------------------------------------------------------------------------------- |
+| **Import**         | `import { useNavigation, useNavigationHold, useArrival, … } from "@omerdlw/base-framework/modules/navigation"` (also `/navigation`) |
+| **Module id**      | `navigation` (`navigationModule`, in `defaultModules`)                                                                  |
+| **Renders**        | nothing; `NavigationProvider` binds the Next router and installs the `popstate` and intent listeners                    |
+| **Registry type**  | none                                                                                                                    |
+| **Page slice**     | none                                                                                                                    |
+| **Peers (`uses`)** | none (the **dock** reads _this_ module through `useModule("navigation")`)                                               |
+| **Events**         | `NAVIGATION_START`, `NAVIGATION_COMMIT`, `NAVIGATION_END` on `globalEvents`                                             |
+| **DOM contracts**  | `a[href]` for intent prefetch; `data-prefetch="false"` opts a link out                                                  |
+| **Tests**          | `tests/modules/navigation.test.ts`                                                                                      |
+
+## 2. Mental model
+
+Every navigation is a **trip**. There is one active trip at a time; a new one supersedes it.
+
+```
+navigate(href) / dock click          back / forward (popstate)
+            │                                  │
+            ▼                                  ▼
+ ┌─────────────────────────── trip ───────────────────────────┐
+ │ phase "leaving"  guard (dock) → holds run, capped           │
+ │                  payload collected from providers           │
+ │ phase "routing"  router.push / replayed popstate            │
+ │                  timeoutMs of patience                      │
+ │ settled          completed | cancelled | failed | timed-out │
+ └─────────────────────────────────────────────────────────────┘
+        trip.signal aborts on anything but "completed"
+        the destination reads the trip with useArrival()
+```
+
+- A **hold** is a function that runs when a trip leaves and returns a promise; the router is asked for the route once every hold settles (or after `maxHoldMs`). This is where exit animations go.
+- The **payload** is what the page being left hands the next one. Components contribute keys while they are mounted (`useNavigationPayload`); getters are read when the trip starts.
+- A trip **arrives** when the location changes while it is `routing` (a different location than the one asked for counts too: a redirect, recorded as `arrivedAt`). A location change while it is still `leaving` cancels it.
+- `useArrival()` returns the trip from the moment the route is asked for (so a route's `loading.tsx` can read it) until the page it landed on is left, or `arrivalTtlMs` after it started.
+
+## 3. Quick start
+
+```tsx
+// An exit animation for links, the dock and the back button alike
+const [leaving, setLeaving] = useState(false);
+useNavigationHold(
+  reduced
+    ? null
+    : (trip) => {
+        setLeaving(true);
+        trip.signal.addEventListener("abort", () => setLeaving(false)); // never landed
+        return delay(600);
+      },
+);
+
+// Hand the destination this page's palette
+useNavigationPayload("palette", palette);
+useNavigationPayload("grade", () => readGrade()); // a getter, read at departure
+
+// The destination (its loading.tsx too)
+const arrival = useArrival();
+const [inherited] = useState(() => arrival?.payload.palette ?? null);
+
+// Navigate from code
+const { navigate } = useNavigation();
+await navigate("/movie/42", { payload: { palette } });
+```
+
+Type the payload once, in the app:
+
+```ts
+declare module "@omerdlw/base-framework/modules/navigation" {
+  interface NavigationPayload {
+    palette?: AmbientPalette | null;
+    grade?: string | null;
+  }
+}
+```
+
+Tune it once, at start-up:
+
+```ts
+configureNavigation({
+  intent: { match: (href) => /^\/(movie|person)\//.test(href) },
+  maxHoldMs: 3000,
+});
+```
+
+## 4. Capabilities
+
+| Capability                           | API                                              | Notes                                                    |
+| :----------------------------------- | :----------------------------------------------- | :------------------------------------------------------- |
+| Navigate with holds and a payload    | `useNavigation().navigate`                       | [§5.2](#52-navigatehref-options)                          |
+| Exit animation before the route      | `useNavigationHold`                              | Also for back/forward unless `{ history: false }`.        |
+| Data for the next page               | `useNavigationPayload`, `useArrival`             | Typed by augmenting `NavigationPayload`.                  |
+| "We are leaving" UI                  | `useDeparture`, `useNavigationState`             |                                                          |
+| Intent prefetch for every link       | built in, `configureNavigation({ intent })`      | 180 ms mouse dwell; pointerdown and focus at once.        |
+| Shared warm cache                    | `prefetch`, `useNavigationIntent`                | The dock's card prefetch goes through it too.             |
+| Hold the back button                 | built in                                         | Only while a hold with `history` is mounted.              |
+| React to trips anywhere              | `NAVIGATION_EVENTS` on `globalEvents`            |                                                          |
+| Use the machine outside React        | `createNavigator`, `watchHistory`, `watchIntent` | What the provider and the dock use.                      |
+
+## 5. API reference
+
+### 5.1 Exports
+
+| Export                                         | Kind      | Description                                                                                                                                  |
+| :--------------------------------------------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------- |
+| `navigationModule`                             | module    | `defineModule` definition.                                                                                                                   |
+| `NavigationProvider`                           | component | Creates the navigator, binds `useRouter()`, reports `usePathname()` arrivals, installs the listeners. Mounted by the host.                  |
+| `NavigationContext`                            | context   | `{ actions, store }`.                                                                                                                        |
+| `useNavigation()`                              | hook      | `NavigationActions`. Throws outside the provider.                                                                                            |
+| `useOptionalNavigation()`                      | hook      | `NavigationActions`, or `INERT_NAVIGATION_ACTIONS` (no trips, nothing held, `navigate` resolves `{ ok: false }`) when the module is absent. |
+| `useNavigationState(selector?, isEqual?)`      | hook      | `{ active, last, location }`. Idle state without the module.                                                                                 |
+| `useNavigationHold(hold, { history? })`        | hook      | Registers `hold` while mounted. `false`/`null` holds nothing. The latest `hold` is called; no deps needed.                                  |
+| `useNavigationPayload(key, value)`             | hook      | Contributes `key` while mounted. A function is a getter called when a trip starts. The latest registration of a key wins.                   |
+| `useNavigationIntent((path, href) => void)`    | hook      | Called with every path the navigator warms (links, dock, code). Use it to preload images for the page.                                       |
+| `useDeparture()`                               | hook      | The active trip when it leads away from the current pathname, else `null`.                                                                   |
+| `useArrival(pathname?)`                        | hook      | The trip that brought the page to `pathname` (default: current), see §2.                                                                     |
+| `createNavigator(options?)`                    | factory   | The pure machine (§5.4).                                                                                                                     |
+| `watchHistory(navigator, window?)`             | function  | The `popstate` capture listener. Returns the cleanup.                                                                                        |
+| `watchIntent(navigator, settings, document?)`  | function  | The intent listeners. Returns the cleanup.                                                                                                   |
+| `configureNavigation(input)`                   | function  | Global settings (§5.3). Returns a restore function.                                                                                          |
+| `getNavigationSettings()`                      | function  | Current settings.                                                                                                                            |
+| `NAVIGATION_EVENTS`, `NAVIGATION_STATUS`, `NAVIGATION_PHASE`, `NAVIGATION_REASON`, `NAVIGATION_SOURCE` | constants |                                                                     |
+| `isSafeInternalHref`, `locationKeyOf`, `pathOf` | utils    | `locationKeyOf("/a/?q=1")` → `"/a?q=1"`.                                                                                                     |
+| Types                                          |           | `NavigationTrip`, `NavigationState`, `NavigationPayload`, `NavigateOptions`, `NavigationResult`, `NavigationActions`, `Navigator`, …        |
+
+### 5.2 `navigate(href, options?)`
+
+Resolves `{ ok, trip, blocked? }`; `ok` is `true` when the router was asked for the route.
+
+| Option     | Default      | Meaning                                                                                                  |
+| :--------- | :----------- | :------------------------------------------------------------------------------------------------------- |
+| `payload`  | —            | Merged over what `useNavigationPayload` contributes.                                                     |
+| `replace`  | `false`      | `router.replace` instead of `router.push`.                                                               |
+| `scroll`   | —            | Passed to the router when set.                                                                           |
+| `source`   | `"navigate"` | Recorded on the trip (`"dock"`, `"history"`, `"guard-confirmation"` are used by the framework).         |
+| `guard`    | —            | `(trip) => boolean \| { blocked, message? }` (sync or async), before holds. Blocking cancels with reason `guard`. |
+| `force`    | `false`      | Skip `guard`. Holds still run.                                                                           |
+| `onCommit` | —            | `(trip) => void` right before the router call.                                                           |
+
+Unsafe hrefs (not starting with a single `/`) and the current location start nothing (`{ ok: false, trip: null }`).
+
+### 5.3 Settings
+
+| Setting          | Default            | Meaning                                                                       |
+| :--------------- | :----------------- | :---------------------------------------------------------------------------- |
+| `intent`         | on                 | `false` turns intent prefetch off; an object merges into the current one.     |
+| `intent.delayMs` | `180`              | Mouse dwell before a hovered link is warmed. Touch hover is ignored.          |
+| `intent.match`   | every internal link | `(href) => boolean`.                                                         |
+| `prefetchKind`   | `"full"`           | Passed to `router.prefetch` as `kind`.                                        |
+| `prefetchTtlMs`  | `240000`           | A warmed href (without hash) is not prefetched again for this long, unless Next invalidates it. |
+| `arrivalTtlMs`   | `20000`            | How long `useArrival` returns a trip after it started.                        |
+| `maxHoldMs`      | `5000`             | Cap on holds.                                                                 |
+| `timeoutMs`      | `15000`            | Patience from the start, and again from the commit; then `timed-out`.         |
+
+Settings live on `globalThis`, so every bundled entry shares them.
+
+### 5.4 `createNavigator(options?)`
+
+`{ router?, settings?, now?, readLocation?, nextFrame?, emit? }` → `Navigator`: every action in `NavigationActions` plus `store` and `dispose()`. The provider and the dock create one each way; tests inject a fake router, clock and location. `arrive(location)` reports location changes, `depart(to, { replay? })` starts a history trip (with `replay`, holds with `history` run before it is called), `setRouter` rebinds.
+
+### 5.5 `NavigationTrip`
+
+`{ id, from, to, href, source, phase, status, startedAt, endedAt?, reason?, error?, arrivedAt?, payload, signal }`. `from`/`to` are location keys (pathname, search, hash). Reasons: `superseded`, `guard`, `returned` (stepped back to the origin during a held back step), `time-out`, or what `cancel(reason)` was given.
+
+## 6. Behaviour details
+
+- **Back/forward.** A capture listener on `window` runs before Next's own `popstate` listener. With no hold that wants history steps the event is left alone and recorded as a trip that is already `routing`. Otherwise it is stopped (`stopImmediatePropagation`), its `state` kept, the holds run, and `new PopStateEvent("popstate", { state })` is dispatched for Next. During the hold the URL already shows the destination while the old page stays rendered. Stepping back to the origin cancels the trip and lets the event through. A step that keeps the pathname (hash, query) is ignored. Unmounting the provider replays a held step so the page never stays behind the URL.
+- **Same-pathname pushes.** No pathname changes, so the navigator reads `window.location` on the next frame and arrives if it matches.
+- **No `useSearchParams`.** The provider watches `usePathname()` only (`useSearchParams` would force a client-side bailout on static routes).
+- **Side effects at import:** none (the package is `sideEffects: false`); listeners are installed in effects.
+- **Plain `next/link` clicks** are warmed on intent and recorded on arrival, but they do not go through `navigate()`, so they get no hold. Route them through `navigate` (or the dock) when the exit matters.
+
+## 7. With the dock
+
+The dock lists `navigation` in `uses`. When the module is installed, dock navigation **is** a trip of the shared navigator (`source: "dock"`): holds and payloads apply to dock clicks, `useDock().dockTransaction` is the active trip, and card prefetch uses the shared warm cache. Dock guards run as the trip's `guard`. Without the module the dock creates a navigator of its own from the same factory (no listeners, no shared cache), so its pending state and timeouts behave the same. See [dock.md §12](./dock.md#12-navigation-guards-and-transactions).
+
+## 8. Recipes and gotchas
+
+| I want to…                                  | Do this                                                                                     |
+| :------------------------------------------ | :------------------------------------------------------------------------------------------ |
+| Skip the exit for reduced motion            | `useNavigationHold(reduced ? null : hold)`.                                                 |
+| Exit on links but not on back               | `useNavigationHold(hold, { history: false })`.                                              |
+| Show the destination's tint in `loading.tsx` | Make it a client component and read `useArrival()?.payload`.                               |
+| Preload a page's hero image on hover        | `useNavigationIntent((path) => preloadHero(path))`.                                         |
+| Never warm a link                           | `data-prefetch="false"` on the `<a>`.                                                       |
+| Undo the exit when the route never comes    | `trip.signal.addEventListener("abort", undo)` inside the hold.                              |
+
+- A hold's promise is awaited only up to `maxHoldMs`; an animation longer than that is cut.
+- `useNavigationPayload` with the same key in two mounted components: the one registered last wins.
+- Trips record `from` as the navigator last saw it; without the provider (`createNavigator` alone) call `arrive` yourself.
+
+## 9. File map
+
+| File            | Responsibility                                                                      |
+| :-------------- | :---------------------------------------------------------------------------------- |
+| `index.ts`      | Public barrel.                                                                      |
+| `types.ts`      | Trip, state, options, actions, settings contracts; the `NavigationPayload` to augment. |
+| `constants.ts`  | Statuses, phases, reasons, sources, event names, default timings.                   |
+| `utils.ts`      | Href and location-key helpers, the link lookup for intent.                          |
+| `state.ts`      | Pure trip factory and settling.                                                     |
+| `settings.ts`   | `configureNavigation`, `getNavigationSettings` (on `globalThis`).                   |
+| `navigator.ts`  | `createNavigator`: the state machine, holds, payload, warm cache, arrivals.         |
+| `listeners.ts`  | `watchHistory` (popstate hold and replay), `watchIntent` (hover/press/focus).       |
+| `context.tsx`   | `NavigationContext`, `NavigationProvider`, inert actions and store.                 |
+| `hooks.ts`      | Public hooks.                                                                       |
+| `module.tsx`    | `navigationModule`, event and kernel type augmentation.                             |
+
+## 10. Dependencies
+
+- **Uses:** `next/navigation` (`useRouter`, `usePathname`), `@omerdlw/base-framework/kernel` (`defineModule`, `getOrCreateGlobalContext`), `@omerdlw/base-framework/events`, `@omerdlw/base-framework/hooks`, `@omerdlw/base-framework/utils`.
+- **Used by:** the **dock** (`useModule("navigation")`, falling back to its own navigator); pages and features through the hooks.

package/docs/proposals/navigation.md

@@ -0,0 +1,209 @@
+# Proposal: a navigation layer (`modules/navigation`)
+
+> Status: **approved and implemented** (see [modules/navigation.md](../modules/navigation.md)).
+> Changes from the draft: there is no `getArrival(pathname)`; read `useArrival()` and keep what you need in `useState(() => …)`. A module-level getter would need a global navigator, which the module avoids. `useNavigationHold` takes no deps array (it always calls the latest hold). `navigate` also takes `onCommit`, which the dock uses for its own commit-time work.
+
+## 1. Why
+
+Guffin, the first app on the framework, wrote its own navigation layer
+(`src/motion/handoff.tsx`, ~250 lines) because the framework has the pieces
+only inside the dock:
+
+| Guffin needed                                                             | What it wrote                                                                     | What the framework has                                                        |
+| :------------------------------------------------------------------------ | :-------------------------------------------------------------------------------- | :---------------------------------------------------------------------------- |
+| Prefetch any link on intent (180 ms hover, pointerdown, focus), warm 4 min | `watchIntent`, `warm`, a `Map` of warmed paths, `foresee` listeners               | `useRoutePrefetch`, dock cards only, 90 ms, no shared cache                   |
+| A "trip": what the departing page hands the destination (palette, grade)  | a module-level `trip`, `beginHandoff`, `handoffTo(pathname)`, `useDeparture`      | nothing                                                                       |
+| An exit animation before the route changes                                | a dock **guard** whose `when` resolves `false` after `wait` (a guard used as a delay) | guards can only block                                                         |
+| Give up when the route never commits, and undo the exit                   | `depart()` with two patience timers keyed off `DOCK_EVENTS.NAVIGATE_START`        | the dock's transaction times out, but nobody outside the dock can react to it |
+| The same exit on the browser back button                                  | a capture-phase `popstate` holder (`holdSteps`) that swallows and replays the event | nothing                                                                       |
+
+Every app with page transitions will need the same five things. They belong in
+the framework, behind one state machine that the dock also uses.
+
+## 2. Decision: a new module, read by the dock as a peer
+
+Two options were on the table:
+
+- **A. Lift the transaction machine into the kernel.** The kernel would own a
+  router binding, DOM listeners (`popstate`, `pointerover`) and timers. That
+  grows the microkernel with app-runtime concerns it has avoided so far, and
+  every app would pay for it.
+- **B. A new `modules/navigation`.** ✅ Recommended.
+
+Why B:
+
+1. It is installable and removable like every other module; `defaultModules`
+   gets it, a subset install can leave it out.
+2. The machine itself is a **pure factory** (`createNavigator`, no React, no
+   Next imports), so it is unit-testable with a fake router and fake timers.
+3. The dock lists `navigation` in `uses` and reads it with
+   `useModule("navigation")`. **When the module is missing, the dock creates a
+   private navigator from the same factory**, bound to its own router and
+   without global listeners. So the dock keeps its pending state and timeouts
+   in a subset install, and there is still only one implementation of the
+   machine. This is the `definePeer` contract (the peer may be absent, the
+   reader still works), with a working stand-in instead of an inert one.
+4. Features that only want to read trips use `useOptionalNavigation()`, a
+   `definePeer("navigation", inert)` whose inert runtime never has a trip.
+
+The dock's `routing/transactions.ts` reducer moves into
+`modules/navigation/state.ts`. `useDockNavigation()` keeps its return shape
+(`activeTransaction`, `lastTransaction`, `cancelDock`, `navigate`, …), so
+`runtime/dock.tsx` does not change. `DOCK_TRANSACTION_*` and the transaction
+reducer types are removed (`DockTransaction` is now `NavigationTrip`);
+`DOCK_EVENTS.NAVIGATE_*` keep firing.
+
+## 3. The model
+
+```
+navigate(href, { payload })      popstate (back/forward)
+            │                              │
+            ▼                              ▼
+      ┌──────────────── trip (one active at a time) ────────────────┐
+      │ phase "leaving" ─ holds run (exit animations), capped        │
+      │        │            payload collected from providers        │
+      │        ▼                                                     │
+      │ phase "routing" ─ router.push / replayed popstate            │
+      │        │            patience timer (timeoutMs)               │
+      │        ▼                                                     │
+      │ settled: completed | cancelled | failed | timed-out          │
+      └──────────────────────────────────────────────────────────────┘
+                     │ trip.signal aborts on cancel / time-out
+                     ▼
+          destination reads it: useArrival() within arrivalTtlMs
+```
+
+- **Trip** = today's `DockTransaction` plus `href`, `phase`, `payload` and an
+  `AbortSignal`. Same ids, same status strings, so the dock maps it 1:1.
+- A new trip **supersedes** the active one (cancelled, reason `superseded`), as
+  today.
+- **Arrival**: the provider watches `usePathname()` (and, after a same-path
+  push, `window.location` on the next frame, as the dock does now). A
+  location change while the trip is `routing` completes it; while it is
+  `leaving` it cancels it.
+
+## 4. API sketch
+
+### Engine (pure, `createNavigator(options)`)
+
+```ts
+const navigator = createNavigator({ router, timeoutMs, maxHoldMs, now });
+
+navigator.navigate(href, { source?, replace?, scroll?, payload?, force?, guard? })
+  // → Promise<{ ok: boolean; trip: NavigationTrip; blocked?: { message?: string } }>
+navigator.hold((trip) => Promise<void> | void, { history?: true })  // → unregister
+navigator.provide(key, valueOrGetter)                              // → unregister
+navigator.prefetch(href, { immediate?, kind? })                    // shared warm cache
+navigator.onIntent((path, href) => void)                           // → unsubscribe
+navigator.arrive(locationKey)        // called by the provider
+navigator.cancel(reason?)
+navigator.arrival(pathname)          // the fresh trip that ended here, or null
+navigator.store                      // ExternalStore<{ active, last }>
+```
+
+`guard` is the dock's hook to run its existing guard registry and
+confirmation surface inside the trip; app-wide blockers are out of scope (§7).
+
+### React (`@omerdlw/base-framework/modules/navigation`)
+
+| Export                                  | Replaces in Guffin                                  |
+| :-------------------------------------- | :-------------------------------------------------- |
+| `navigationModule`                      | —                                                   |
+| `useNavigation()` / `useOptionalNavigation()` | `useRouter` + `depart`                        |
+| `useNavigationHold(fn, deps, options?)` | the guard-as-delay + `depart` + `onReturn` + `holdSteps` |
+| `useNavigationPayload(key, value)`      | `useHeldPalette`, the `--grade` read in `beginHandoff` |
+| `useDeparture()`                        | `useDeparture(pathname)`                            |
+| `useArrival()` / `getArrival(pathname)` | `handoffTo(pathname)` (`getArrival` for `useState` initialisers) |
+| `useNavigationIntent(fn)`               | `foresee`                                           |
+| `configureNavigation(settings)`         | the constants `DWELL`, `WARM_FOR`, `FRESH`, `isFilmPage` |
+| `NAVIGATION_EVENTS`                     | listening to `DOCK_EVENTS.NAVIGATE_START`           |
+
+The payload is typed by augmentation, so the framework does not depend on
+ambient:
+
+```ts
+declare module "@omerdlw/base-framework/modules/navigation" {
+  interface NavigationPayload {
+    palette?: AmbientPalette | null;
+    grade?: string | null;
+  }
+}
+```
+
+### Settings (`configureNavigation`, same pattern as `configureAmbient`)
+
+| Setting          | Default  | Meaning                                                                  |
+| :--------------- | :------- | :----------------------------------------------------------------------- |
+| `intent`         | `true`   | Document-level intent prefetch for `a[href]`; `false` turns it off.       |
+| `intent.delayMs` | `180`    | Mouse dwell before prefetching. `pointerdown` and `focusin` are immediate. |
+| `intent.match`   | internal | `(href) => boolean`, which links to warm (Guffin: film pages).           |
+| `prefetchKind`   | `"full"` | Passed to `router.prefetch`.                                             |
+| `prefetchTtlMs`  | `240000` | How long a warmed path is not prefetched again.                          |
+| `arrivalTtlMs`   | `20000`  | How long a trip stays readable by `useArrival`.                          |
+| `maxHoldMs`      | `5000`   | Cap on holds; past it the trip commits anyway.                           |
+| `timeoutMs`      | `15000`  | Patience after commit (today's `DOCK_TRANSACTION_TIMEOUT_MS`).           |
+
+Links opt out with `data-prefetch="false"`.
+
+## 5. Guffin after the move (illustrative, Guffin is not edited here)
+
+```tsx
+// stage.tsx: the exit, for dock clicks and the back button alike
+useNavigationHold(
+  (trip) => {
+    setLeaving(true);
+    trip.signal.addEventListener("abort", () => setLeaving(false));
+    return delay(wait * 1000);
+  },
+  [wait],
+  { enabled: !reduced },
+);
+useNavigationPayload("grade", () => readGrade());   // getter, read at departure
+
+// movie-page-chrome.tsx
+useNavigationPayload("palette", lit);
+const [inherited] = useState(() => getArrival(pathname)?.payload.palette);
+
+// loading.tsx
+const arrival = useArrival();
+return arrival ? <Dark palette={arrival.payload.palette ?? null} /> : children;
+```
+
+## 6. Next.js App Router notes
+
+- Everything is a client module (`"use client"` entry, like the other
+  modules). The package is `sideEffects: false`, so listeners are installed in
+  the provider's effects, never at import.
+- Back/forward: a capture-phase `popstate` listener on `window` runs before
+  Next's own listener. With holds registered it swallows the event
+  (`stopImmediatePropagation`), keeps `event.state`, and after the holds
+  replays `new PopStateEvent("popstate", { state })` so Next restores the
+  route itself. A second step back to the origin during the hold cancels the
+  trip. Without holds the event is left alone and only recorded as a trip.
+- No `useSearchParams` in the provider (it would force a client-side bailout
+  on static routes); search/hash arrivals use the location check the dock
+  already does.
+- `router.prefetch(href, { kind })` is called defensively; a throw drops the
+  path from the warm cache.
+
+## 7. Out of scope for this change
+
+- App-wide blockers (`navigation.block`): the dock's guards stay where they
+  are and run through the `guard` option.
+- A `<NavigationLink>` that routes plain link clicks through `navigate()`.
+  `next/link` clicks still prefetch on intent and are recorded on arrival, but
+  get no exit hold. Follow-up if wanted.
+- Scroll restoration and the dock's continuity store.
+
+## 8. Plan
+
+1. `src/modules/navigation/` with the canonical files (`index`, `types`,
+   `constants`, `utils`, `state`, `context.tsx`, `hooks.ts`, `module.tsx`), a
+   `tsup` entry and a `package.json` export.
+2. Dock: `routing/navigation.ts` and `routing/transactions.ts` move onto the
+   navigator; `cards.tsx` prefetch goes through it; `uses` gains
+   `navigation`. `runtime/dock.tsx`, `display.ts` untouched.
+3. Tests: `tests/modules/navigation.test.ts` (engine with fake timers,
+   provider + popstate with happy-dom), existing dock tests unchanged, a dist
+   smoke check that the module and its context are one object.
+4. Docs: `docs/modules/navigation.md`, index row, dock page cross-links.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omerdlw/base-framework",
-  "version": "2.0.1",
+  "version": "3.0.0",
   "description": "Microkernel engine and first-party declarative UI modules for app-like Next.js products.",
   "type": "module",
   "sideEffects": false,
@@ -117,6 +117,11 @@
       "import": "./dist/modules/media/index.js",
       "default": "./dist/modules/media/index.js"
     },
+    "./navigation": {
+      "types": "./dist/modules/navigation/index.d.ts",
+      "import": "./dist/modules/navigation/index.js",
+      "default": "./dist/modules/navigation/index.js"
+    },
     "./modules": {
       "types": "./dist/modules/index.d.ts",
       "import": "./dist/modules/index.js",