@omerdlw/base-framework 2.0.1 → 3.0.1

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/docs/theming.md

@@ -221,7 +221,7 @@ Each animating module exports its contract type. Give it a full value, the same
 
 | Module | Spec | Contract type | What it holds |
 | :--- | :--- | :--- | :--- |
-| Dock | `dockTheme` | `DockMotion` | `transitions` (stack, expand, surface enter/step/exit/resize, cards, text, header swap, press, …), `variants` (fade, text crossfade, header swap/restore, controls, command bar, badge, hud, …), `deck` (elevation, compress, `peek(position)`, `exit(card)`, `tapScale`), `drag`, `skeleton`, `timings` (surface phase lengths and card staggers, in seconds) |
+| Dock | `dockTheme` | `DockMotion` | `transitions` (stack, expand, surface exit, layout, cards, text, header swap, press, …), `variants` (fade, text crossfade, header swap/restore, controls, command bar, badge, hud, …), `phases` (what the deck, header and body play in each surface phase, and the deck's compression), `deck` (elevation, `peek(position)`, `exit(card)`, `tapScale`, `stacking`, breadcrumb offset, fullscreen opacity, origin, resize fallback), `opacity` (banner and description rest), `drag` (swipe feel and the dismiss distance and speed), `skeleton`, `timings` (surface phase lengths and card staggers, in seconds) |
 | Modal | `modalTheme` | `ModalMotion` | `backdrop`, `content`, `header`, `footer` variants, and `positions` (`center`, `top`, `right`, `bottom`, `left`: variants plus an optional own `transition`) |
 | Notification | `notificationTheme` | `NotificationMotion` | `toast` variants and the toast's `transition` |
 | Context menu | `contextMenuTheme` | `ContextMenuMotion` | `pop`, `content`, `item` variants (`item.visible` may take the row index), `itemTap`, `itemTransition` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omerdlw/base-framework",
-  "version": "2.0.1",
+  "version": "3.0.1",
   "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",

package/templates/AGENTS.md

@@ -141,6 +141,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";
 
 const modules = [
   dockModule,
@@ -150,6 +151,7 @@ const modules = [
   backgroundModule,
   controlsModule,
   loadingModule,
+  navigationModule,
 ];
 
 export function Providers({ children }: { children: React.ReactNode }) {

package/templates/motion/dock.ts

@@ -1,4 +1,7 @@
-import type { DockMotion } from "@omerdlw/base-framework/modules/dock";
+import type {
+  DockMotion,
+  DockSurfacePhaseMotion,
+} from "@omerdlw/base-framework/modules/dock";
 import {
   chip,
   contentSwap,
@@ -70,31 +73,51 @@ const crossfade = {
   scale: 1 - 0.018,
 };
 
+// The deck's size while an open surface changes height: a longer move takes a
+// little longer.
+const surfaceResize = (distancePx: number) => {
+  const resize = surfaceResizeTransition(distancePx, {
+    base: 0.5,
+    min: 0.4,
+    max: durations.cinematic,
+    ease: easings.weighted,
+  });
+  return { ...resize, height: resize, width: resize };
+};
+
+// The deck's lift and scale while the body grows in, and just before a surface
+// opens or closes.
+const surfaceArrival = tween(durations.cinematic, easings.overshoot);
+const anticipation = tween(SURFACE.anticipation, easings.weighted);
+
+// The body growing in, and the body changing between steps.
+const surfaceEnter = { ...surfaceBody.visible.transition, delay: SURFACE.bodyEnterDelay };
+const surfaceStep = swap(durations.base, easings.enter).enter;
+
 const controlsSlot = (enter: object, exit: object) => ({
   hidden: { opacity: 0, scale: 0.96, width: 0, marginRight: -2 },
   visible: { opacity: 1, scale: 1, width: "auto", marginRight: 0, transition: enter },
   exit: { opacity: 0, scale: 0.96, width: 0, marginRight: -2, transition: exit },
 });
 
+// A phase that plays nothing of its own: the deck rests, the header swaps and
+// the body steps. Each phase below changes only what it plays differently.
+const REST_PHASE: DockSurfacePhaseMotion = {
+  deck: null,
+  transform: null,
+  scale: 1,
+  body: surfaceStep,
+  header: headerSwap.enter,
+  headerReturn: null,
+};
+
 // defineTheme(dockTheme, { slots, motion: dockMotion })
 export const dockMotion: DockMotion = {
   transitions: {
     stack: tween(COLLAPSE, easings.enter),
     expand,
-    surfaceResize: (distancePx) => {
-      const resize = surfaceResizeTransition(distancePx, {
-        base: 0.5,
-        min: 0.4,
-        max: durations.cinematic,
-        ease: easings.weighted,
-      });
-      return { ...resize, height: resize, width: resize };
-    },
-    surfaceArrival: tween(durations.cinematic, easings.overshoot),
-    anticipation: tween(SURFACE.anticipation, easings.weighted),
-    surfaceEnter: { ...surfaceBody.visible.transition, delay: SURFACE.bodyEnterDelay },
-    surfaceStep: swap(durations.base, easings.enter).enter,
     surfaceExit: surfaceBody.exit.transition,
+    layout: { type: "tween", duration: 0.45, ease: [0.4, 0, 0.1, 1] },
     card,
     cardExpanded: springs.deck,
     cardPeek: tween(durations.fast, easings.enter),
@@ -279,13 +302,44 @@ export const dockMotion: DockMotion = {
       visible: { opacity: 1, transform: gpuTransform(0, 1) },
     },
   },
+  phases: {
+    idle: REST_PHASE,
+    // The inline action leaves and the deck compresses for a beat.
+    dismissAction: {
+      ...REST_PHASE,
+      transform: anticipation,
+      scale: 0.94,
+      header: anticipation,
+    },
+    // The body grows in; the deck arrives with a little overshoot.
+    expandBody: {
+      ...REST_PHASE,
+      deck: expand,
+      transform: surfaceArrival,
+      body: surfaceEnter,
+    },
+    open: { ...REST_PHASE, deck: surfaceResize },
+    // The deck compresses again before the body leaves.
+    anticipation: {
+      ...REST_PHASE,
+      deck: surfaceResize,
+      transform: anticipation,
+      scale: 0.96,
+    },
+    // The body leaves and the card header comes back.
+    collapseBody: {
+      ...REST_PHASE,
+      deck: expand,
+      headerReturn: surfaceEnter,
+    },
+    restoreHeader: { ...REST_PHASE, deck: expand },
+  },
   deck: {
     elevation: {
       rest: "0px 12px 32px 0px rgba(0,0,0,0.35), 0px 2px 8px 0px rgba(0,0,0,0.25)",
       elevated:
         "0px 32px 80px 0px rgba(0,0,0,0.55), 0px 8px 24px 0px rgba(0,0,0,0.35)",
     },
-    compress: { open: 0.94, close: 0.96 },
     // Cards further back lift a little further and grow a little less.
     peek: (position) => {
       const progress = Math.min(position / 3, 1);
@@ -303,12 +357,26 @@ export const dockMotion: DockMotion = {
       transition: { ...cardCollapse },
     }),
     tapScale: 0.97,
+    // Cards stack 10px apart and shrink to 0.88 per level, fading by 0.2. The
+    // expanded deck spaces them by a card's height (68px) and a 4px gap.
+    stacking: {
+      collapsed: { offsetY: -10, scale: 0.88, opacityStep: 0.2, opacityMin: 0.1 },
+      expanded: { offsetY: -72 },
+      shelf: { offsetY: -42, scale: 0.94 },
+      visible: { stack: 3, extensions: 2, status: 1 },
+    },
+    breadcrumbOffset: -44,
+    fullscreenOpacity: 0,
+    origin: "50% 100%",
+    resizeFallback: 260,
   },
+  opacity: { banner: 0.95, description: 0.7 },
   drag: {
     elastic: { top: 0.05, bottom: 0.5 },
     range: [0, 180],
     opacity: [1, 0.75],
     scale: [1, 0.96],
+    dismiss: { offset: 65, velocity: 400 },
   },
   skeleton: "animate-pulse motion-reduce:animate-none",
   timings: {