@excom/spa-route 0.1.0

package/support/dist-docs/spa-a.md

@@ -0,0 +1,40 @@
+# `<spa-a>`
+
+> Declarative SPA link with active-state styling.
+
+**Tag:** `<spa-a>`
+
+## API
+
+### Attributes
+
+| Name | Surface | Type | Default | Values | Description | Inherited from |
+| --- | --- | --- | --- | --- | --- | --- |
+| `route-action` | option | `string` | `"push"` | `"push"` \| `"replace"` \| `"back"` \| `"forward"` | Navigation mode when activated (default click). |  |
+| `document-title` | option | `string` |  |  | Sets `document.title` after navigation. |  |
+| `transition-types` | option | `tokenlist` |  | `<token>…` | Space-separated View Transition types for this navigation (CSS View Transitions API). Useful for shared-element morphs like card expansion. |  |
+| `match-hash` | option | `boolean` |  |  | Require the URL hash to match when setting `is-active`. |  |
+| `is-active` | state | `boolean` |  |  | Current URL matches `route-href`. Style with `spa-a[is-active]`. |  |
+| `was-active` | state | `boolean` |  |  | Previous URL matched `route-href`. Style outgoing links / card-expansion exits with `spa-a[was-active]`. |  |
+| `host-ref` | option | `string` |  | `<CSS Selector>` \| `"window"` \| `"document"` \| `"html"` \| `"body"` \| `"head"` | Listen on another element / `window` / `document` — e.g. Escape to dismiss a dialog from a global `keydown`. Defaults to `:scope`. Used with `listen-for`. Not compatible with `listen-for-lifecycle`. The selector MUST resolve when `host-ref` is set — it will not wait for a match to appear. | `@excom/listenable-element` |
+| `listen-for` | option | `tokenlist` |  | `<EventName>…` | Space-separated event names to listen for. Defaults to `click` when unset (and no lifecycle list is set). | `@excom/listenable-element` |
+| `listen-for-lifecycle` | option | `tokenlist` |  | `"connected"` \| `"disconnected"` \| `"adopted"` | Space-separated element lifecycles to handle. | `@excom/listenable-element` |
+| `listen-once` | option | `boolean` |  |  | Handle each distinct event name / lifecycle at most once. | `@excom/listenable-element` |
+| `selector-filter` | option | `string` |  | `<CSS Selector>` | Only handle events whose `event.target` matches this CSS selector. Does not support `:scope` in the selector. | `@excom/listenable-element` |
+| `keycode-filter` | option | `tokenlist` |  | `<key` \| `mod+key>…` | Space-separated key filters (OR). Join modifiers with `+` (AND, any order): `shift+k tab` → Shift+K or Tab. Modifiers: `shift`, `alt`, `ctrl`/`control`, `meta`. Case-insensitive. | `@excom/listenable-element` |
+| `pathname-filter` | option | `tokenlist` |  | `<pathname>…` | Only handle when `location.pathname` is one of these values — route-aware behaviors without a separate router element. | `@excom/listenable-element` |
+| `prevent-default` | option | `boolean` |  |  | Call `preventDefault()` on matched events (ignored for lifecycles). | `@excom/listenable-element` |
+| `stop-propagation` | option | `boolean` |  |  | Call `stopPropagation()` on matched events (ignored for lifecycles). | `@excom/listenable-element` |
+| `stop-immediate-propagation` | option | `boolean` |  |  | Call `stopImmediatePropagation()` on matched events (ignored for lifecycles). | `@excom/listenable-element` |
+| `vibrate-ms` | option | `number` | `"20 (when attribute is present with no value)"` |  | Vibrate on handle (`navigator.vibrate`). Empty / `0` uses a 20ms pulse. | `@excom/listenable-element` |
+| `delay-ms` | option | `number` |  |  | Delay handling by this many milliseconds. | `@excom/listenable-element` |
+| `is-debounced` | option | `boolean` |  |  | With `delay-ms`, coalesce bursts into one trailing call (debounce). | `@excom/listenable-element` |
+| `route-href` | option | `string` |  | `<path pattern>` | URL pattern to match. Supports named placeholders (`/users/:id`) and wildcards. Set this or `route-regex`. | `@excom/routable-element` |
+| `route-regex` | option | `string` |  | `<RegExp source>` | RegExp source string matched against the current URL — alternative to `route-href` for catch-alls / advanced patterns. | `@excom/routable-element` |
+| `match-nested` | option | `boolean` |  |  | Also match nested paths of `route-href` (e.g. `/users` stays active on `/users/42`). Essential for layout routes and nested SPAs. | `@excom/routable-element` |
+
+### CSS Aliases
+
+| Alias | Kind | Matches | Description |
+| --- | --- | --- | --- |
+| `:--spa-a` | element | `spa-a`, `.tag-spa-a` |  |

package/support/dist-docs/spa-manager.md

@@ -0,0 +1,66 @@
+# `<spa-manager>`
+
+> SPA shell — view transitions, swipe nav, route orchestration.
+
+**Tag:** `<spa-manager>`
+
+## API
+
+### Attributes
+
+| Name | Surface | Type | Default | Values | Description | Inherited from |
+| --- | --- | --- | --- | --- | --- | --- |
+| `transition-first-render` | option | `boolean` |  |  | Animate the very first activation (cold load) with a View Transition. Off by default so the initial paint is instant. |  |
+| `transition-delay` | option | `number` |  |  | Delay (ms) before starting the batched View Transition. Gives late sibling render/unrender events time to queue, or room for last-second DOM work. Unset / `null` starts synchronously. |  |
+| `no-transition` | option | `boolean` |  |  | Disable View Transitions for every child route. |  |
+| `render-timeout` | option | `number` | `2000` |  | Max wait (ms) for child render promises before forcing the transition to resolve. Raise for slow remote templates. |  |
+| `overscroll-behavior-x` | option | `string` |  | `"none"` \| `"navigate"` | Touch edge-swipe on touch devices. `none` blocks horizontal overscroll; `navigate` also calls back / forward past the threshold. |  |
+| `overscroll-x-threshold` | option | `number` | `40` |  | Edge inset (px) where a touch start counts as an edge swipe. |  |
+| `max-states` | option | `number` |  |  | Cap retained router history states (scroll positions, transition types, etc.). |  |
+| `last-move` | state | `string` |  | `"push"` \| `"replace"` \| `"back"` \| `"forward"` | Last navigation direction (`push` / `replace` / `back` / `forward`). Pick CSS transition styles from this. |  |
+| `active-url` | state | `string` |  |  | URL of the currently active route. |  |
+| `is-transitioning` | state | `boolean` |  |  | A View Transition is in flight. |  |
+| `has-rendered` | state | `boolean` |  |  | At least one render has committed. Gates `transition-first-render`; useful for hiding loading shells. |  |
+| `route-href` | option | `string` |  | `<path pattern>` | URL pattern to match. Supports named placeholders (`/users/:id`) and wildcards. Set this or `route-regex`. | `@excom/routable-element` |
+| `route-regex` | option | `string` |  | `<RegExp source>` | RegExp source string matched against the current URL — alternative to `route-href` for catch-alls / advanced patterns. | `@excom/routable-element` |
+| `match-nested` | option | `boolean` |  |  | Also match nested paths of `route-href` (e.g. `/users` stays active on `/users/42`). Essential for layout routes and nested SPAs. | `@excom/routable-element` |
+
+### Provision
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `provision` | `KitRouteData` (`{ previous: { id: string; url: string; title?: string; isInit?: boolean; scrollX?: number; scrollY?: number; ttypes?: string[]; } \| null; active: { id: string; url: string; title?: string; isInit?: boolean; scrollX?: number; scrollY?: number; ttypes?: string[]; }; next: { id: string; url: string; title?: string; isInit?: boolean; scrollX?: number; scrollY?: number; ttypes?: string[]; } \| null; all: { id: string; url: string; title?: string; isInit?: boolean; scrollX?: number; scrollY?: number; ttypes?: string[]; }[]; params: Record<string, string> \| null; match: Array<any> \| null; move: null \| "push" \| "replace" \| "back" \| "forward"; event?: { hasUAVisualTransition: boolean; }; route: KitRoute; }`) | Current route payload. Not reflected as an attribute. |
+
+### Recognized Elements
+
+| Relationship | Selector | Required | Description |
+| --- | --- | --- | --- |
+| `spa-route` | descendant | yes | Routes this manager coordinates. Their render lifecycle is intercepted and batched into one view transition per navigation. |
+
+### Fires
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `spa-manager-will-transition` | `SpaManagerWillTransitionEvent` (`CustomEvent & { type: "spa-manager-will-transition"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Cancelable. Once per navigation, just before the View Transition starts. `preventDefault()` skips the transition for this navigation. |
+| `spa-manager-transition` | `SpaManagerTransitionEvent` (`CustomEvent & { type: "spa-manager-transition"; detail: { transition: ViewTransition; }; bubbles: true; cancelable: true; composed: true }`) | After `document.startViewTransition()` is called. |
+| `spa-manager-rendered` | `SpaManagerRenderedEvent` (`CustomEvent & { type: "spa-manager-rendered"; detail: void; bubbles: true; cancelable: true; composed: true }`) | After the transition (or synchronous fallback) finishes and routes are settled. |
+| `spa-manager-error` | `SpaManagerErrorEvent` (`CustomEvent & { type: "spa-manager-error"; detail: unknown; bubbles: true; cancelable: true; composed: true }`) | Re-emitted when a child fires `spa-route-error`. `event.detail` mirrors the source error. |
+| `spa-manager-push` | `SpaManagerPushEvent` (`CustomEvent & { type: "spa-manager-push"; detail: void; bubbles: true; cancelable: true; composed: true }`) | On `pushState` navigations. |
+| `spa-manager-replace` | `SpaManagerReplaceEvent` (`CustomEvent & { type: "spa-manager-replace"; detail: void; bubbles: true; cancelable: true; composed: true }`) | On `replaceState` navigations. |
+| `spa-manager-back` | `SpaManagerBackEvent` (`CustomEvent & { type: "spa-manager-back"; detail: void; bubbles: true; cancelable: true; composed: true }`) | On `back` navigations. |
+| `spa-manager-forward` | `SpaManagerForwardEvent` (`CustomEvent & { type: "spa-manager-forward"; detail: void; bubbles: true; cancelable: true; composed: true }`) | On `forward` navigations. |
+
+### Listens for
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `spa-route-render` | `RenderableRenderEvent` (`CustomEvent & { type: "{tag}-render"; detail: () => Promise<void>; bubbles: true; cancelable: true; composed: true }`) | Queues the child's render callback for the next batched transition. |
+| `spa-route-unrender` | `RenderableUnrenderEvent` (`CustomEvent & { type: "{tag}-unrender"; detail: () => void; bubbles: true; cancelable: true; composed: true }`) | Queues the child's unrender callback (runs before renders so the outgoing route leaves first). |
+| `spa-route-provision` | `SpaRouteProvisionEvent` (`CustomEvent & { type: "spa-route-provision"; detail: () => void; bubbles: true; cancelable: true; composed: true }`) | Queues a same-route param update (reuse) into the next batched transition. |
+| `spa-route-error` | `RenderableErrorEvent` (`CustomEvent & { type: "{tag}-error"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Falls back to a non-transitioned update and re-emits as `spa-manager-error`. |
+
+### Default actions
+
+| Event | Default behavior (unless preventDefault() is called) |
+| --- | --- |
+| `spa-manager-will-transition` | Starts the batched View Transition (or synchronous update when transitions are unavailable / opted out). |

package/support/dist-docs/spa-route.md

@@ -0,0 +1,408 @@
+# spa-route
+
+Build a full SPA from HTML alone — screens, links, and view transitions.
+
+> This site is a live demo... inspect its HTML! Other live demos of spa-route coming soon.
+
+```html
+<spa-manager>
+  <spa-route route-href="/" template-ref="/views/home.html"></spa-route>
+  <spa-route route-href="/about" template-ref="/views/about.html"></spa-route>
+</spa-manager>
+
+<nav>
+  <spa-a route-href="/">Home</spa-a>
+  <spa-a route-href="/about">About</spa-a>
+</nav>
+```
+
+## Features
+
+- **Pure CSS View Transitions** Write CSS, get beautiful animations between routes
+- **Active / was-active** Style current and outgoing links & screens (nav chrome, card expansion)
+- **Same-route reuse / refresh** Keep or rebuild the view when only params change
+- **Scroll reset / restore** Per-axis control for push, replace, back, forward
+- **Nested layouts** Keep a parent route mounted under child paths
+- **404 fallbacks** Catch-alls that only fire when nothing else matched
+- **Per-route document title** `document.title` follows the active route
+- **History actions** Push, replace, back, forward from a link
+
+## Installation
+
+
+`@excom/spa-route` v0.1.0
+
+```bash
+pnpm add @excom/spa-route
+```
+
+```bash
+npm install @excom/spa-route
+```
+
+```bash
+yarn add @excom/spa-route
+```
+
+### Import
+
+```ts
+import "@excom/spa-route";
+```
+
+
+
+## Usage
+
+Wrap screens in `<spa-manager>`, give each `<spa-route>` a `route-href`, and link with `<spa-a>`.
+
+```html
+<!-- Optional SPA manager for View Transitions and batched router config -->
+<spa-manager>
+  <!-- SPA routing -->
+  <spa-route route-href="/" template-ref="/views/home.html"></spa-route>
+  <spa-route route-href="/about" template-ref="/views/about.html"></spa-route>
+</spa-manager>
+<nav>
+  <!-- SPA links -->
+  <spa-a route-href="/">Home</spa-a>
+  <spa-a route-href="/about">About</spa-a>
+</nav>
+```
+
+### API Reference
+
+
+#### Attributes
+
+| Name | Surface | Type | Default | Values | Description | Inherited from |
+| --- | --- | --- | --- | --- | --- | --- |
+| `same-route` | option | `string` | `"reuse"` | `"reuse"` \| `"refresh"` | When this route matches while already active, `reuse` keeps the rendered tree and updates route data; `refresh` tears down and re-renders. Use `refresh` for param-driven screens (e.g. `/users/:id` → `/users/2`); `reuse` when only route data should change (e.g. `/logs/:view`). Pair with `scroll-set-disabled` to leave the viewport untouched. |  |
+| `no-transition` | option | `boolean` |  |  | Opt this route out of the parent `<spa-manager>` View Transition. Still renders/unrenders — just without the cross-fade. |  |
+| `scroll-reset-behavior` | option | `string` | `"instant"` | `"auto"` \| `"instant"` \| `"smooth"` | `window.scrollTo` behavior when this route applies a scroll reset / restore. |  |
+| `scroll-reset-x` | option | `tokenlist` | `"push replace"` | `"push"` \| `"replace"` \| `"back"` \| `"forward"` | Navigation moves that reset scroll X to `0`. Moves omitted here restore the saved X for that history entry instead. |  |
+| `scroll-reset-y` | option | `tokenlist` | `"push replace"` | `"push"` \| `"replace"` \| `"back"` \| `"forward"` | Navigation moves that reset scroll Y to `0`. Moves omitted here restore the saved Y for that history entry instead. |  |
+| `scroll-set-disabled` | option | `boolean` |  |  | Disable all scroll reset / restore for this route. |  |
+| `is-fallback` | option | `boolean` |  |  | Only activate when this route matches *and* no earlier sibling `<spa-route>` is already active. Pair with a permissive `route-regex` (e.g. `.*`) for 404 catch-alls. |  |
+| `document-title` | option | `string` |  |  | `document.title` while this route is active. The outermost `<spa-manager>` applies the last active route carrying one — so a nested route beats its ancestor — and restores the page's own `<title>` once no active route has one. Cold loads and back / forward retitle too: it keys off activation, not clicks. |  |
+| `was-active` | state | `boolean` |  |  | Set briefly while navigating away. Style outgoing screens / card-expansion exits with `spa-route[was-active]`. |  |
+| `template-ref` | option | `string` | `":scope > template"` | `<CSS Selector>` \| `<URL>` | Source `<template>` — in-document selector or remote URL. Changing mid-flight aborts and reloads. Can use `:scope` to relatively select elements: e.g. `main:has(:scope) > template` | `@excom/renderable-element` |
+| `bypass-cache` | option | `boolean` |  |  | Skip the in-memory response cache (URL `template-ref` only). | `@excom/renderable-element` |
+| `pre-fetch` | option | `string` | `"lazy"` | `""` \| `"eager"` \| `"idle"` \| `"lazy"` | When to fetch the template, independent of when it renders. `""` aliases `eager`. | `@excom/renderable-element` |
+| `persist-content` | option | `boolean` |  |  | Reuse the same live nodes across unrender / render (held on `_persistedTree`) so form values, scroll position, and subtree state survive toggles. | `@excom/renderable-element` |
+| `host-ref` | option | `string` |  | `"shadow"` \| `"iframe"` \| `<CSS Selector>` | Where rendered children land. Unset = this element's light DOM. `shadow` attaches an open shadow root. `iframe` paints into a child `<iframe data-render-host>` body (you supply the iframe — useful for sandboxed / third-party document isolation). Any other value is a portal selector. | `@excom/renderable-element` |
+| `ready-on` | option | `string` |  | `<Event Name>` | Event name that marks rendered children "ready". Until it fires, `delaying-ready` is set so CSS can hide the host for a coordinated paint / view transition. | `@excom/renderable-element` |
+| `is-active` | hybrid | `boolean` |  |  | Master switch. Set to load (if needed) and render; unset to unrender. Drive from visibility, route match, hover, etc. | `@excom/renderable-element` |
+| `is-loading` | state | `boolean` |  |  | Template fetch in flight. | `@excom/renderable-element` |
+| `did-load` | state | `boolean` |  |  | Template resolved at least once. Stays set across `is-active` toggles so consumers know later paints are warm (URL refs reuse the shared fetch cache in kit-utils). Cleared when `template-ref` changes or `--reload` forces a fresh resolve. | `@excom/renderable-element` |
+| `is-error` | state | `boolean` |  |  | Latest template fetch rejected (excluding abort). Fires with the `error` event. | `@excom/renderable-element` |
+| `delaying-ready` | state | `boolean` |  |  | Between `render` and the matching `ready-on` event. Hook with CSS for coordinated paints / view transitions. | `@excom/renderable-element` |
+| `route-href` | option | `string` |  | `<path pattern>` | URL pattern to match. Supports named placeholders (`/users/:id`) and wildcards. Set this or `route-regex`. | `@excom/routable-element` |
+| `route-regex` | option | `string` |  | `<RegExp source>` | RegExp source string matched against the current URL — alternative to `route-href` for catch-alls / advanced patterns. | `@excom/routable-element` |
+| `match-nested` | option | `boolean` |  |  | Also match nested paths of `route-href` (e.g. `/users` stays active on `/users/42`). Essential for layout routes and nested SPAs. | `@excom/routable-element` |
+
+#### Provision
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `provision` | `SpaRouteProvision` (`{ routeHref: string; matchNested: boolean; scrollResetY: string[]; scrollResetX: string[]; scrollResetBehavior: ScrollBehavior; noTransition: boolean; active: { id: string; url: string; title?: string; isInit?: boolean; scrollX?: number; scrollY?: number; ttypes?: string[]; }; event: { hasUAVisualTransition: boolean; }; match: Array<any> \| null; move: null \| "push" \| "replace" \| "back" \| "forward"; next: { id: string; url: string; title?: string; isInit?: boolean; scrollX?: number; scrollY?: number; ttypes?: string[]; } \| null; previous: { id: string; url: string; title?: string; isInit?: boolean; scrollX?: number; scrollY?: number; ttypes?: string[]; } \| null; params: Record<string, string> \| null; }`) | Active route payload for this activation (`null` when inactive). Not reflected as an attribute. |
+
+#### Recognized Elements
+
+| Relationship | Selector | Required | Description | Inherited from |
+| --- | --- | --- | --- | --- |
+| `template` | child | yes | Screen content. Cloned (or reused with `persist-content`) on activation. |  |
+| `iframe[data-render-host]` | child | no | Required when `host-ref="iframe"`. Content paints into `iframe.contentDocument.body`. Provide your own iframe (e.g. with `srcdoc`); the element will not create one. | `@excom/renderable-element` |
+
+#### Fires
+
+| Name | Type | Description | Inherited from |
+| --- | --- | --- | --- |
+| `spa-route-provision` | `SpaRouteProvisionEvent` (`CustomEvent & { type: "spa-route-provision"; detail: () => void; bubbles: true; cancelable: true; composed: true }`) | Cancelable. Same route stayed active but params changed (`same-route="reuse"`). `event.detail` is a thunk that updates route data and resolves the ready promise. `<spa-manager>` batches this into the View Transition like render/unrender. |  |
+| `spa-route-render` | `RenderableRenderEvent` (`CustomEvent & { type: "{tag}-render"; detail: () => Promise<void>; bubbles: true; cancelable: true; composed: true }`) | Cancelable. Dispatched when the element becomes active and is about to place template content into the host. `event.detail` is a thunk that performs the load (if not already loaded) and renders the children, returning a Promise that resolves once the corresponding `ready-on` event fires (or immediately if `ready-on` is unset). The promise rejects if the element is torn down mid-flight (`startTeardown` while loading / `delaying-ready`). Call `preventDefault()` to defer rendering and invoke `event.detail()` later. | `@excom/renderable-element` |
+| `spa-route-unrender` | `RenderableUnrenderEvent` (`CustomEvent & { type: "{tag}-unrender"; detail: () => void; bubbles: true; cancelable: true; composed: true }`) | Cancelable. Dispatched when the element becomes inactive and content is already painted. `event.detail` is a thunk that removes the rendered children. Call `preventDefault()` to defer the removal. Not fired when teardown cancels an in-flight load — that path emits `aborted` instead. | `@excom/renderable-element` |
+| `spa-route-did-render` | `RenderableDidRenderEvent` (`CustomEvent & { type: "{tag}-did-render"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Dispatched after the template content has actually been placed into the host. | `@excom/renderable-element` |
+| `spa-route-did-unrender` | `RenderableDidUnrenderEvent` (`CustomEvent & { type: "{tag}-did-unrender"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Dispatched after rendered children have been removed from the host. | `@excom/renderable-element` |
+| `spa-route-error` | `RenderableErrorEvent` (`CustomEvent & { type: "{tag}-error"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Dispatched when the template promise rejects with anything other than an `AbortError`. | `@excom/renderable-element` |
+| `spa-route-aborted` | `RenderableAbortedEvent` (`CustomEvent & { type: "{tag}-aborted"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Dispatched when an in-flight load / ready wait is canceled because `is-active` was unset (via `startTeardown`). | `@excom/renderable-element` |
+
+#### Commands
+
+| Command | Action | Inherited from |
+| --- | --- | --- |
+| `--reload` | Aborts any in-flight fetch and re-resolves the template, bypassing the cache for URL refs (useful after remote content changes). | `@excom/renderable-element` |
+
+#### Default actions
+
+| Event | Default behavior (unless preventDefault() is called) | Inherited from |
+| --- | --- | --- |
+| `spa-route-provision` | Invokes `event.detail()` to apply the new provision. |  |
+| `spa-route-render` | Invokes `event.detail()` to load (if needed) and render the template into the host. | `@excom/renderable-element` |
+| `spa-route-unrender` | Invokes `event.detail()` to remove rendered children from the host. | `@excom/renderable-element` |
+
+#### CSS Aliases
+
+| Alias | Kind | Matches | Description |
+| --- | --- | --- | --- |
+| `:--spa-route` | element | `spa-route`, `.tag-spa-route` |  |
+
+
+
+### Examples
+
+#### Minimal SPA
+
+Three routes, three links. Active links style via `spa-a[is-active]`.
+
+```html
+<spa-manager>
+  <nav>
+    <spa-a route-href="/home">Home</spa-a>
+    <spa-a route-href="/users">Users</spa-a>
+    <spa-a route-href="/about">About</spa-a>
+    <spa-a route-href="/contact">Contact</spa-a>
+  </nav>
+  <spa-route route-href="/home">
+    <template>
+      <h3>Welcome</h3>
+      <p>Mounted because the URL matched <code>/home</code>.</p>
+    </template>
+  </spa-route>
+  <spa-route route-href="/users">
+    <template>
+      <h3>Users</h3>
+      <ul>
+        <li>Adam</li>
+        <li>Linus</li>
+        <li>Grace</li>
+      </ul>
+    </template>
+  </spa-route>
+  <spa-route route-href="/about" template-ref="/this/view/is/remote.html"></spa-route>
+  <spa-route route-href="/contact" template-ref="#this-view-is-dom-selected"></spa-route>
+</spa-manager>
+
+<template id="this-view-is-dom-selected">foo@bar.com</template>
+```
+
+```css
+spa-a[is-active] {
+  font-weight: bold;
+  pointer-events: none;
+  text-decoration: none;
+}
+```
+
+#### Nested layout & 404
+
+`match-nested` keeps a layout mounted under child paths. `is-fallback` with `route-regex=".*"` is a 404 that only activates when no preceding sibling matched.
+
+```html
+<spa-manager>
+  <nav>
+    <spa-a route-href="/users">Users list</spa-a>
+    <spa-a route-href="/users/42">User 42</spa-a>
+    <spa-a route-href="/missing">Missing page</spa-a>
+  </nav>
+  <spa-route route-href="/users" match-nested>
+    <template>
+      <section>
+        <h3>Users layout</h3>
+        <spa-manager>
+          <spa-route route-href="/users">
+            <template><p>List of users.</p></template>
+          </spa-route>
+          <spa-route route-href="/users/:id">
+            <template><p>Detail for a single user.</p></template>
+          </spa-route>
+        </spa-manager>
+      </section>
+    </template>
+  </spa-route>
+  <spa-route route-regex=".*?view=admin.*" template-ref="/views/admin-sidebar.html"></spa-route>
+  <spa-route route-regex=".*" is-fallback>
+    <template>
+      <section>
+        <h3>404</h3>
+        <p>Catch-all — only when no preceding sibling matched.</p>
+      </section>
+    </template>
+  </spa-route>
+</spa-manager>
+```
+
+#### Document title
+
+`document-title` sets `document.title` while its route is active. It keys off
+activation, not clicks, so cold loads and back / forward retitle too. The
+outermost `<spa-manager>` applies the last active route carrying one — a
+nested route beats its ancestor — and restores the page's own `<title>` once
+no active route has a title.
+
+```html
+<title>Nucleus · docs</title>
+
+<spa-manager>
+  <spa-route route-href="/" document-title="My company">
+    <template><p>The company page.</p></template>
+  </spa-route>
+  <!-- untitled: the page's own <title> comes back -->
+  <spa-route route-href="/docs">
+    <template><p>The docs.</p></template>
+  </spa-route>
+</spa-manager>
+```
+
+#### History actions
+
+`route-action="back"` / `"forward"` walk history; `"replace"` swaps the current entry instead of pushing.
+
+```html
+<spa-manager>
+  <nav>
+    <spa-a route-action="back">‹ Back</spa-a>
+    <spa-a route-action="forward">Forward ›</spa-a>
+    <spa-a route-href="/one">Push /one</spa-a>
+    <spa-a route-href="/two">Push /two</spa-a>
+    <spa-a route-href="/login" route-action="replace">
+      Replace with /login
+    </spa-a>
+  </nav>
+  <spa-route route-href="/one">
+    <template><p>You're on <code>/one</code>.</p></template>
+  </spa-route>
+  <spa-route route-href="/two">
+    <template><p>You're on <code>/two</code>.</p></template>
+  </spa-route>
+  <spa-route route-href="/login">
+    <template>
+      <p>You're on <code>/login</code> — this entry replaced the
+        previous one in history.</p>
+    </template>
+  </spa-route>
+</spa-manager>
+```
+
+#### View Transitions
+
+`<spa-manager>` wraps each navigation in `document.startViewTransition()` (when supported). Style with `::view-transition-*`; set per-link types via `transition-types` (e.g. card expansion); opt a route out with `no-transition`.
+
+```css
+::view-transition-old(root),
+::view-transition-new(root) {
+  animation-duration: 0.25s;
+}
+```
+
+#### View Transitions - Localized
+If you had a list of cards, and clicking on one expanded it to the detail view (and vice versa, contracting), you would achieve it similarly to the code example below. This technique relies on styling the `<spa-a>` with its `[is-active]` (incoming view) and `[was-active]` (outgoing view).
+
+```html
+<spa-manager>
+  <spa-route id="route-list" route-href="/list">
+    <template>
+      <spa-a route-href="/detail/123" transition-types="card-morph" class="mini-card">
+        Go to detail
+      </spa-a>
+    </template>
+  </spa-route>
+  <spa-route id="route-detail" route-href="/detail/:id">
+    <template>
+      <article id="detail-card" class="card">
+        <!-- other content here -->
+      </article>
+    </template>
+  </spa-route>
+</spa-manager>
+```
+
+```css
+html:active-view-transition-type(card-morph) {
+  #route-list spa-a[transition-types="card-morph"][was-active], /* outgoing list card (forward) */
+  #route-list spa-a[transition-types="card-morph"][is-active], /* incoming list card (back) */
+  #detail-card /* detail card (forward & back) */ {
+    contain: layout;
+    height: fit-content;
+    view-transition-name: card-morph;
+  }
+}
+::view-transition-old(card-morph),
+::view-transition-new(card-morph) {
+  mix-blend-mode: normal;
+  height: 100%;
+  width: 100%;
+  will-change: opacity;
+  animation-fill-mode: both;
+}
+::view-transition-old(card-morph) {
+  animation-name: fade-out 1s ease;
+}
+::view-transition-new(card-morph) {
+  animation-name: fade-in 1s ease;
+}
+@keyframes fade-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+@keyframes fade-out {
+  from { opacity: 1; }
+  to { opacity: 0; }
+}
+```
+
+#### Touch edge-swipe
+On touch devices, horizontal drags from within `overscroll-x-threshold` of an edge trigger back / forward. Use `"none"` to block overscroll without navigating. Useful for preventing native swipes in Safari, which visually break SPAs.
+
+```html
+<spa-manager overscroll-behavior-x="navigate"></spa-manager>
+```
+
+
+#### Scroll reset / restore
+
+By default, `<spa-route>`:
+- resets scroll to top-left on `push` / `replace`
+- restores the saved scroll position on `back` / `forward`
+
+Override per axis with `scroll-reset-y` / `scroll-reset-x` — space-separated moves that should reset to `0` (omitted moves restore instead):
+
+```html
+<!-- also reset Y when the user hits back -->
+<spa-route
+  route-href="/article/:id"
+  scroll-reset-y="push replace back"
+></spa-route>
+```
+
+Animate with `scroll-reset-behavior="smooth"`. Disable all scroll handling with `scroll-set-disabled`.
+
+#### Same-route params
+
+When the matched route stays the same but params change (e.g. `/users/1` → `/users/2`):
+
+- `same-route="reuse"` (default) — keep the rendered tree, update route data, and let `<spa-manager>` run a View Transition
+- `same-route="refresh"` — tear down and re-render the view
+
+```html
+<spa-route route-href="/users/:id" same-route="refresh">
+  <template><!-- fresh tree per user id --></template>
+</spa-route>
+
+<spa-route
+  route-href="/logs/:view"
+  same-route="reuse"
+  scroll-set-disabled
+>
+  <template><!-- preserve content + scroll across view tabs --></template>
+</spa-route>
+```
+
+#### Transition delay
+
+`transition-delay` on `<spa-manager>` waits N ms before starting the batched View Transition — useful when sibling routes need a beat to queue their render/unrender callbacks, or for last-second DOM work.
+
+```html
+<spa-manager transition-delay="50">
+  <!-- routes -->
+</spa-manager>
+```