@finesoft/front 0.3.0 → 0.4.1

package/docs/04-rendering-and-hydration.md

@@ -1,6 +1,6 @@
 # 4. Rendering & hydration
 
-How a page travels from controller output to bytes on the wire, then back into a live browser app. This chapter covers SSR, CSR, prerender, and the `PrefetchedIntents` machinery that ties them together.
+How a page travels from controller output to bytes on the wire, then back into a live browser app. This chapter covers SSR, CSR, prerender, the second axis they compose with — **app architecture** (flat single page vs structured navigation + islands) — and the `PrefetchedIntents` machinery that ties them together.
 
 ## The three modes side by side
 
@@ -15,6 +15,25 @@ How a page travels from controller output to bytes on the wire, then back into a
 
 Mode is **per-route**. Mix freely.
 
+## Two axes: render mode × app architecture
+
+Render mode is one axis. The **app architecture** is a second, orthogonal axis:
+
+- **Flat single page** — `createSSRRender` on the server, a single client mount that re-renders on each navigation. One root, one visible page. (See [SSR pipeline](#ssr-pipeline) below.)
+- **Structured navigation + islands** — `createSSRNavigationRender` on the server, per-destination _islands_ on the client: independent roots that stay alive across tab/stack switches. (See [Navigation](./11-navigation.md) and [Islands SSR](#islands-ssr-structured-architecture-approach-c) below.)
+
+The two axes compose into a matrix — render mode decides _when/where_ HTML is produced; architecture decides _how_ the app is structured:
+
+|               | Flat single page          | Structured nav + islands (approach C) |
+| ------------- | ------------------------- | ------------------------------------- |
+| **ssr**       | ✅ `svelte-minimal`       | ✅ `vue-minimal`, `react-minimal`     |
+| **csr**       | ◐ shell → one client root | ◐ shell → islands mount client-side   |
+| **prerender** | ◐ cached flat SSR         | ◐ cached approach-C SSR               |
+
+✅ demonstrated by a starter template · ◐ composes by design, no starter template yet.
+
+**Islands are SSR'd or CSR'd as a consequence of the mode, not as a separate choice:** under `ssr`/`prerender` the framework server-renders each visible island and the client _adopts and hydrates_ it; under `csr` there is no server HTML, so every island mounts fresh on the client. The per-mode sub-dimensions still apply on top — CSR has two triggers ([below](#csr-client-side-render)), prerender has build-time-static and runtime-ISR forms ([below](#prerender-static--isr)). Session restoration + DOM restore are a further orthogonal layer (client-side, post-hydration) that stacks onto any cell — see [Session restoration](./12-session-restoration.md).
+
 ## SSR pipeline
 
 ```
@@ -83,6 +102,57 @@ The Vite plugin and adapters call `render(url, options)` for you. You return `{
 - Sets HTTP status from `deny()` / `redirect()` / `rewrite()` results
 - Adds `Content-Location` header when `afterLoad` signaled a rewrite
 
+## Islands SSR (structured architecture, "approach C")
+
+The structured architecture renders the **chrome** (tab bar, headers — the persistent frame) and the **island content** (the active page) as **independent hydration roots**, placed as siblings under the mount node:
+
+```html
+<div id="app">
+    <div data-fs-chrome><!-- chrome SSR'd here --></div>
+    <main data-fs-outlet><!-- each visible island SSR'd here --></main>
+</div>
+```
+
+**Server** — `renderApp` renders the chrome; `renderIslandsHtml(snapshot, renderEntry)` renders each visible destination into the outlet with shared markers (`data-fs-entry` / `data-fs-intent` / `data-fs-key`) so the client can match them:
+
+```ts
+// src/ssr.ts — structured entry (createSSRNavigationRender)
+async renderApp(page, _framework, snapshot) {
+    const chromeHtml = await renderToString(createSSRApp(App, { snapshot }));
+    const islandsHtml = await renderIslandsHtml(snapshot, (entry) =>
+        renderToString(createSSRApp(VIEWS[entry.intent], { page: entry.page })),
+    );
+    return {
+        html: `<div data-fs-chrome>${chromeHtml}</div><main data-fs-outlet>${islandsHtml}</main>`,
+        head: `<title>${page.title}</title>`,
+        css: "",
+    };
+}
+```
+
+**Client** — `resolveIslandsShell(target)` locates (or creates) the chrome/outlet siblings and reports whether the chrome was server-rendered (`hydrate`). The island orchestrator adopts each SSR'd container by `data-fs-key` and calls your `mountEntry(entry, container)` with `entry.hydrate = true`, so you hydrate the existing DOM rather than create new:
+
+```ts
+// src/main.ts
+const mountEntry = (entry, container) => {
+    const factory = entry.hydrate ? createSSRApp : createApp; // hydrate SSR'd vs mount fresh (client nav)
+    const app = factory(VIEWS[entry.intent], { page: entry.page, controller: ctx.app });
+    app.mount(container);
+    return { unmount: () => app.unmount() };
+};
+
+startBrowserApp({
+    bootstrap,
+    mount,
+    callbacks,
+    navigation: { ...navigation.toBrowserConfig(), mountEntry },
+});
+```
+
+> **Synchronous-mount contract.** After `mountEntry` returns, the island's DOM must already exist: the framework restores `data-restore-root` fields on the next animation frame (see [Session restoration](./12-session-restoration.md)). Vue/Svelte `.mount()` satisfies this synchronously. **React** commits asynchronously, so wrap the **client-mount** path in `flushSync(() => root.render(view))` — only client-mounted islands need it (SSR'd islands already have their DOM from the server). See `templates/react-minimal/src/main.tsx`.
+
+Complete examples: `templates/vue-minimal` and `templates/react-minimal` (both `ssr` + structured navigation + islands + session restoration).
+
 ## CSR (client-side render)
 
 For routes marked `renderMode: "csr"`, the server returns a minimal shell:
@@ -123,21 +193,18 @@ The adapter serves these static files directly. No controller runs at request ti
 
 ### Incremental Static Regeneration (ISR)
 
-The bundled server (`createServer`) and the preview server (`vp preview`) support cached on-demand regeneration. Configure via `finesoftFrontViteConfig`:
+The bundled server (`createServer`) and the preview server (`vp preview`) also cache `prerender` routes at runtime: a route is rendered on its **first** request and the HTML kept in an in-memory LRU (`ISR_CACHE_MAX = 1000` entries, evicted least-recently-used). Subsequent requests serve the cached HTML without re-running the controller.
+
+Mark routes `prerender` per route (`renderMode: "prerender"`) or per glob via the Vite plugin (config-level wins over route-level):
 
 ```ts
 finesoftFrontViteConfig({
     ssr: { entry: "src/ssr.ts" },
-    isr: {
-        // routes that should regenerate on demand
-        routes: ["/blog/*"],
-        // cache TTL in seconds
-        ttl: 300,
-    },
+    renderModes: { "/blog/*": "prerender" },
 });
 ```
 
-The first request after expiry triggers a fresh render; concurrent requests get the stale version until the regeneration completes. See [server & deployment](./09-server-and-deployment.md#isr) for details.
+The runtime cache has **no TTL and no background regeneration** — entries live until LRU-evicted or the process restarts. Time-based stale-while-revalidate is delegated to the CDN by the platform adapters (Netlify emits a real `stale-while-revalidate` header; Cloudflare a plain `max-age`; node/Vercel none). See [server & deployment](./09-server-and-deployment.md#isr-incremental-static-regeneration) for the full picture.
 
 ## `PrefetchedIntents` — the SSR → CSR bridge
 

package/docs/09-server-and-deployment.md

@@ -22,7 +22,7 @@ export default defineConfig({
             i18n: { messagesDir: "src/locales" },
             proxies: [{ prefix: "/api", target: "https://upstream.example" }],
             adapter: "auto",
-            isr: { routes: ["/blog/*"], ttl: 300 },
+            renderModes: { "/blog/*": "prerender" },
         }),
     ],
 });
@@ -30,13 +30,13 @@ export default defineConfig({
 
 ### Options
 
-| Option             | Type                      | Notes                                                   |
-| ------------------ | ------------------------- | ------------------------------------------------------- |
-| `ssr.entry`        | `string`                  | Path to your SSR entry (default `src/ssr.ts`).          |
-| `i18n.messagesDir` | `string`                  | Folder with `{locale}.json` files (default off).        |
-| `proxies`          | `ProxyRouteConfig[]`      | Declarative API forwarding. See below.                  |
-| `adapter`          | `"auto" \| "node" \| ...` | Target platform. `"auto"` detects from env vars.        |
-| `isr`              | `{ routes, ttl }`         | Incremental Static Regeneration for prerendered routes. |
+| Option             | Type                         | Notes                                                                          |
+| ------------------ | ---------------------------- | ------------------------------------------------------------------------------ |
+| `ssr.entry`        | `string`                     | Path to your SSR entry (default `src/ssr.ts`).                                 |
+| `i18n.messagesDir` | `string`                     | Folder with `{locale}.json` files (default off).                               |
+| `proxies`          | `ProxyRouteConfig[]`         | Declarative API forwarding. See below.                                         |
+| `adapter`          | `"auto" \| "node" \| ...`    | Target platform. `"auto"` detects from env vars.                               |
+| `renderModes`      | `Record<string, RenderMode>` | Per-route render-mode override (glob keys); `"prerender"` enables ISR caching. |
 
 ### What it does
 
@@ -55,21 +55,20 @@ In build:
 
 ## `createServer` — the standalone Hono server
 
-For Node deployments and tests, the framework exports a function that gives you a ready-to-run Hono app:
+For Node deployments and tests, the framework exports an async factory. It loads `.env`, detects the runtime, builds the Hono app, registers proxies + your `setup` routes, mounts the SSR catch-all, and **starts listening** (port from config or `PORT`, default `3000`) — then returns `{ app, vite, runtime }`:
 
 ```ts
 import { createServer } from "@finesoft/front";
 
-const app = createServer({
-    ssrEntry: "./dist/server/ssr.js",
+const { app } = await createServer({
+    ssr: { ssrProductionModule: "./dist/server/ssr.js" }, // or ssrEntryPath in dev
     proxies: [{ prefix: "/api", target: "https://upstream.example" }],
-    staticDir: "./dist/client",
-    isr: { routes: ["/blog/*"], ttl: 300 },
+    port: 3000,
 });
 
-// app is a Hono instance — mount it however your runtime expects
-import { serve } from "@hono/node-server";
-serve({ fetch: app.fetch, port: 3000 });
+// `app` is the started Hono instance — export it for serverless runtimes whose
+// adapter imports the fetch handler (Vercel / Cloudflare / Netlify).
+export { app };
 ```
 
 ### What it includes
@@ -149,48 +148,58 @@ This works for most CI environments — Vercel / Cloudflare / Netlify all set th
 
 ## ISR (Incremental Static Regeneration)
 
+Mark routes `prerender` — per route (`renderMode: "prerender"`) or per glob via the Vite plugin's `renderModes` (config-level wins over route-level):
+
 ```ts
-isr: {
-    routes: ["/blog/*", "/products/*"],
-    ttl: 300,  // seconds
-}
+finesoftFrontViteConfig({
+    ssr: { entry: "src/ssr.ts" },
+    renderModes: { "/blog/*": "prerender", "/products/*": "prerender" },
+});
 ```
 
-How it works:
+A `prerender` route is served two ways:
 
-1. First request to `/blog/hello-world`: render fully, cache the HTML, set expiry to now + 300s
-2. Subsequent requests within TTL: serve cached HTML directly
-3. After expiry: next request triggers re-render; concurrent requests get stale HTML until re-render finishes
+1. **Build-time static** — the static adapter renders each prerender route at build and writes `dist/<route>.html` (one per locale when i18n is on). Served as plain static files; no controller runs at request time.
+2. **Runtime cache** — the bundled server (`createServer`) and `vp preview` render a prerender route on its **first** request and store the HTML in an in-memory LRU (`ISR_CACHE_MAX = 1000` entries, evicted least-recently-used). Subsequent requests serve the cached HTML without re-running the controller.
 
-The cache is in-memory per server instance. For multi-instance deployments where consistency matters, put a CDN in front and use HTTP `Cache-Control` headers instead.
+> **No TTL, no background regeneration.** The runtime cache has no time-based expiry and no stale-while-revalidate — an entry lives until it is LRU-evicted or the process restarts. The "regenerate after N seconds" semantics live at the **CDN**, not in the framework (below). There is no `isr` config option and no programmatic invalidation API.
 
-Routes not matched by `isr.routes` always render fresh.
+### Stale-while-revalidate is delegated to the CDN
 
-### Cache invalidation
+Platform adapters set cache headers on prerender responses so the edge does the real ISR:
 
-Programmatic invalidation is not exposed in the public API. To force a refresh:
+| Adapter                   | Header on prerender responses                                                              |
+| ------------------------- | ------------------------------------------------------------------------------------------ |
+| Netlify                   | `Netlify-CDN-Cache-Control: max-age=3600, stale-while-revalidate=3600, durable` (true SWR) |
+| Cloudflare                | `Cache-Control: public, max-age=3600`                                                      |
+| Node (self-host) / Vercel | none — relies on the in-memory LRU                                                         |
+
+The `3600`s window is a hard-coded per-adapter constant, not user-configurable. For multi-instance / multi-region deployments the CDN headers are what give you consistent caching; the in-memory LRU is per-instance single-server serving.
+
+### Cache invalidation
 
-- Restart the server (loses entire cache)
-- Wait for TTL
-- Add a cache-busting query param the controller can ignore but that bypasses the cache key
+There is no programmatic invalidation API. To force a refresh:
 
-For production, push invalidation up to CDN level — the framework's in-memory cache is for single-instance serving.
+- Restart the server (clears the entire in-memory LRU)
+- Redeploy (rebuilds build-time static and resets caches)
+- On Netlify / Cloudflare, purge the CDN cache for the path
 
 ## Custom Hono middleware
 
-If you need server logic outside the proxy and SSR (e.g., a webhook endpoint, a health check), mount it on the same Hono app:
+If you need server logic outside the proxy and SSR (e.g., a webhook endpoint, a health check), register it via the `setup` hook — it runs after proxies but **before** the SSR catch-all, so your routes win:
 
 ```ts
-const app = createServer({ ssrEntry: "./dist/server/ssr.js" });
-
-app.get("/health", (c) => c.json({ status: "ok" }));
-app.post("/webhook", async (c) => {
-    const body = await c.req.json();
-    await handleWebhook(body);
-    return c.json({ ok: true });
+await createServer({
+    ssr: { ssrProductionModule: "./dist/server/ssr.js" },
+    setup: (app) => {
+        app.get("/health", (c) => c.json({ status: "ok" }));
+        app.post("/webhook", async (c) => {
+            const body = await c.req.json();
+            await handleWebhook(body);
+            return c.json({ ok: true });
+        });
+    },
 });
-
-// SSR catch-all is registered last by createServer — your routes win.
 ```
 
 ## Environment variables
@@ -215,25 +224,16 @@ framework.container.register("config", () => ({
 For Node deployments behind a load balancer:
 
 ```ts
-import { serve } from "@hono/node-server";
-
-const app = createServer({
-    /* ... */
+await createServer({
+    ssr: { ssrProductionModule: "./dist/server/ssr.js" },
+    setup: (app) => app.get("/health", (c) => c.json({ ok: true })),
 });
-app.get("/health", (c) => c.json({ ok: true }));
-
-const server = serve({ fetch: app.fetch, port: 3000 });
 
-process.on("SIGTERM", () => {
-    server.close(() => {
-        // dispose Framework if you held a reference
-        framework.dispose();
-        process.exit(0);
-    });
-});
+// createServer starts the listener itself — no manual serve() needed.
+process.on("SIGTERM", () => process.exit(0));
 ```
 
-`framework.dispose()` recursively disposes the container, calls `destroy()` on registered recorders/loggers, and unregisters all routes.
+`createServer` does not return the underlying `http.Server`, so there's no built-in `server.close()` connection-drain. If you need graceful draining — or a handle to call `framework.dispose()` (recursively disposes the container, calls `destroy()` on recorders/loggers, unregisters routes) on shutdown — compose the lower level instead: build the Hono app and own framework yourself and `serve()` it so you keep both handles.
 
 ## Next
 

package/docs/11-navigation.md

@@ -97,31 +97,29 @@ export const navigation = defineNavigation({
 
 ### Wiring it into the browser
 
-`startBrowserApp` gains an optional `navigation` field and an `onNavigationReady` callback that hands you a `NavigationHandle`:
+`startBrowserApp` gains an optional `navigation` field; when present, the `NavigationHandle` (and a unified `app` handle) is handed to your `mount` callback in its context, ready to use:
 
 ```ts
 // src/main.ts
-import { startBrowserApp, type NavigationHandle } from "@finesoft/front";
+import { startBrowserApp } from "@finesoft/front";
 import { bootstrap, navigation } from "./bootstrap";
-import { mount } from "./lib/mount";
-
-let handle: NavigationHandle;
 
 startBrowserApp({
     bootstrap,
-    mount,
     callbacks,
     navigation: navigation.toBrowserConfig(),
-    onNavigationReady(h) {
-        handle = h;
-        // Re-render whenever the snapshot changes
-        h.subscribe((snapshot) => mountNavigation(snapshot));
-        mountNavigation(h.getSnapshot());
+    mount(target, { navigation: nav, app }) {
+        // nav/app are ready at mount time (no callback needed).
+        // Re-render whenever the snapshot changes:
+        nav?.subscribe((snapshot) => mountNavigation(snapshot));
+        if (nav) mountNavigation(nav.getSnapshot());
+        // ... mount your UI into `target`, pass `app` to components ...
+        return () => undefined;
     },
 });
 ```
 
-When `navigation` is present, the framework builds a `NavigationController` and a history bridge, resolves the first screen, and gives you the handle. When it's absent, `startBrowserApp` runs the original flat single-page path unchanged.
+When `navigation` is present, the framework builds a `NavigationController` and a history bridge, resolves the first screen, and gives you the handle in the mount context. When it's absent, `startBrowserApp` runs the original flat single-page path unchanged.
 
 ## Driving navigation
 
@@ -299,6 +297,8 @@ function renderApp(page, framework, snapshot) {
 }
 ```
 
+For the concrete islands shell that `renderApp` builds — chrome + per-destination islands as independent hydration roots, plus the client-side `mountEntry` / `resolveIslandsShell` that adopt and hydrate them — see [Islands SSR](./04-rendering-and-hydration.md#islands-ssr-structured-architecture-approach-c).
+
 How it works under the hood: each visible destination is serialized through the **existing** `PrefetchedIntents` channel as a normal `{ intent, data: page }` entry, plus one sentinel entry carrying the serialized tree. `@finesoft/server` needs **zero changes** — it transports the sentinel through the same `#serialized-server-data` script. On hydration the browser bridge reads the tree back from history state (or the sentinel) and reuses the prefetched pages.
 
 If a request has no structural deep-link and your app provides no skeleton, SSR falls back to `Router.resolve(url)` → a single leaf — i.e. today's flat single page, including its `renderMode`. The 404 path is unchanged.
@@ -352,4 +352,4 @@ A single destination's dispatch failure never throws out of an operation — it
 ## Next
 
 - [Middleware](./03-middleware.md) — the guard semantics navigation reuses
-- [Rendering & hydration](./04-rendering-and-hydration.md) — how prefetched results cross the SSR → CSR boundary
+- [Rendering & hydration](./04-rendering-and-hydration.md) — the render-mode × architecture matrix, the islands SSR shell, and how prefetched results cross the SSR → CSR boundary

package/docs/12-session-restoration.md

@@ -0,0 +1,219 @@
+# 12. Session restoration
+
+The framework already restores the **first screen**: SSR injects the prefetched intent results through `PrefetchedIntents`, and the browser reuses them on the first navigation. Structured navigation also carries the current tree across back/forward via `history.state`.
+
+But one class of state survives **none** of that: what the user was actually _doing_ when they **hard-reloaded, crashed the tab, or closed and came back** — which screen (or stack depth, or tab, or split column) they were on, the half-typed draft in a form, how far a list was scrolled. The in-memory `history.state` map is wiped by a full reload; `PrefetchedIntents` only covers the one server-rendered screen.
+
+**Session restoration** fills that gap: it serializes a versioned, JSON-safe **session snapshot** (navigation position + app-registered state slices + navigation-scoped per-screen state) to a pluggable `Storage`, and rehydrates it on a fresh load. The framework ships **no UI** — it restores **state**, and your app re-renders from it however you like.
+
+It is entirely opt-in: an app that never passes `session` to `startBrowserApp` is **byte-for-byte unchanged**.
+
+## The two scopes
+
+A snapshot captures two layers of state, serialized together and restored together across a reload:
+
+| Scope                       | Lives in | Keyed by       | Lifetime                                                                | SwiftUI analogue |
+| --------------------------- | -------- | -------------- | ----------------------------------------------------------------------- | ---------------- |
+| **Global slices**           | `slices` | `provider.key` | The whole session (theme, a cross-screen wizard draft…)                 | `@SceneStorage`  |
+| **Navigation-scoped state** | `scoped` | `entryKey`     | Bound to one navigation entry — dropped when that entry leaves the tree | `@State`         |
+
+- **Global slices** are app-wide. You register a `SessionStateProvider` per slice; the framework orchestrates _when_ it is captured and persisted. It never interprets the contents — it only moves them.
+- **Navigation-scoped state** is bound to a _navigation entry_, mirroring the position-scoped lifecycle of a SwiftUI view's `@State` (covered below).
+
+## Global slices: `SessionStateProvider`
+
+An app registers one provider per slice. `capture()` returns a JSON-safe synchronous value; `restore(data)` puts it back (your app calls `setState` / refills the form / scrolls):
+
+```ts
+import type { SessionStateProvider } from "@finesoft/front";
+
+const themeSlice: SessionStateProvider<string> = {
+    key: "theme",
+    capture: () => getCurrentTheme(),
+    restore: (theme) => applyTheme(theme),
+};
+```
+
+The framework moves the value verbatim and never inspects it — so **you** decide what to capture. Exclude sensitive fields right here in `capture()`; a slice you never register is never captured.
+
+## Navigation-scoped state: the SwiftUI `@State` lifecycle
+
+Navigation-scoped state is the interesting half. It is keyed by **entry identity**, not by visibility, and it follows the same position-scoped lifecycle as a SwiftUI view's `@State`:
+
+> `A` → push `B` → go back (pop `B`) to `A`: **`B`'s state is discarded, `A`'s state is still there.**
+
+The mechanism: each entry's state bag is stored under `entryKey = intent + " " + stableStringify(params)` — the same identity the navigation controller uses for a destination, so it is **stable across a reload**. After every committed navigation, the framework **prunes** the scoped map down to the entries **actually present in the tree** — note _present_, not _visible_. Any key whose entry is no longer in the tree is dropped.
+
+```ts
+import { sessionEntryKey } from "@finesoft/front";
+
+// When you render a screen, read/write its scoped bag with the entry's key:
+const key = sessionEntryKey("post", { id: 7 });
+store.scope.set(key, { scroll: 240, draft: "half a comment" });
+const bag = store.scope.get(key); // -> { scroll: 240, draft: "..." } | undefined
+```
+
+Walking through the lifecycle:
+
+- **push `B`** → tree `[A, B]`, present `{A, B}` → `A`'s state is **kept** (`A` is still on the stack, just not visible) and `B` gets its own scope.
+- **pop `B`** → tree `[A]`, present `{A}` → **`B`'s scope is pruned away**, `A`'s is kept intact; going back to `A` renders with its retained state.
+- **switch a TabView tab** → the other branches are still in the tree → their state is kept alive (exactly like SwiftUI keeping inactive tabs mounted).
+- **across a reload** → `scoped` is serialized into the snapshot; after reload, every entry still in the tree gets its scope back, and a later pop discards it as usual.
+
+`store.scope` is the `NavigationScopedState` instance held by the store — `get` / `set` / `delete` / `keys`, plus the `prune(presentKeys)` the framework calls for you. With the high-level `startBrowserApp({ session })` path you don't hold the store directly: the `SessionHandle` handed to your `mount` callback (context) exposes the same instance as `handle.scope` (still live after a restore rebuilds it), so you `handle.scope.get(entryKey)` / `set(entryKey, data)` the same way.
+
+### Flat vs structured: retention _is_ a stack
+
+That "keep `A` under `B`, drop `B` on pop, restore `A`" behavior is, by definition, **stack semantics** — so it only exists in **structured navigation**, where a stack/tree can hold entries that are _present but not visible_.
+
+A **flat single page has no stack**: `A → B` is a full-page replacement, so `presentKeys()` is always a single entry (the current URL). The moment you leave a screen its scope is pruned, and a browser **Back** re-renders it fresh.
+
+Both modes support "current-screen scope + restore-across-reload". If you want "go Back and keep the previous screen", build it as a structured stack — push instead of replace. That is precisely what `NavigationStack` is _for_; it is not a shortcoming of flat mode.
+
+## The snapshot
+
+`createSessionStore(options)` returns the `SessionStore` orchestrator. `capture()` assembles a snapshot without persisting; the snapshot model is:
+
+```ts
+interface SessionSnapshot {
+    readonly version: number;
+    readonly navigation?: SerializedNavigation | SessionUrlLocation; // structured tree | { url }
+    readonly slices: Readonly<Record<string, unknown>>; // provider.key -> capture()
+    readonly scoped: Readonly<Record<string, unknown>>; // entryKey -> state bag
+    readonly capturedAt: number; // epoch ms, for maxAgeMs expiry
+}
+```
+
+`navigation` is discriminated with a light guard: a `SerializedNavigation` always carries a `kind` (leaf/stack/tabs/split); a flat `SessionUrlLocation` carries a `url`. `isUrlLocation(nav)` tells them apart.
+
+The store exposes:
+
+```ts
+interface SessionStore {
+    register(provider: SessionStateProvider): () => void; // returns a disposer
+    readonly scope: NavigationScopedState;
+    capture(): SessionSnapshot; // assemble (nav + slices + scoped), no I/O
+    persist(snapshot?: SessionSnapshot): void; // capture() if omitted, then write
+    load(): SessionSnapshot | undefined; // read + validate (version / maxAge / shape)
+    restore(snapshot?: SessionSnapshot): void | Promise<void>; // load() if omitted, then apply
+    clear(): void; // remove the persisted snapshot
+    save(): void; // capture + persist — the manual escape hatch
+}
+```
+
+`load()` discards a snapshot whose version mismatches, whose `capturedAt` is older than `maxAgeMs`, or whose shape is malformed — it returns `undefined` rather than ever throwing into your app. A provider that throws in `capture()` / `restore()` is isolated: its slice is skipped, the error goes to `onError`, and the rest of the snapshot survives.
+
+## Persistence: `sessionStorage` by default, swappable
+
+The snapshot is encoded with a stable stringify and written as a single `storage.set(key, ...)`. `Storage` is the existing core dependency interface, so durability is **your** choice:
+
+```ts
+import { createWebStorage } from "@finesoft/front";
+
+createWebStorage("session"); // sessionStorage — tab-scoped, cleared when the tab closes (default)
+createWebStorage("local"); // localStorage — survives across tabs and restarts
+```
+
+`createWebStorage` maps `get`/`set`/`delete` onto `getItem`/`setItem`/`removeItem`, swallows quota errors on write (session restoration is best-effort — it never interrupts navigation), and degrades to a safe no-op when the chosen Web Storage is unavailable (e.g. private mode `SecurityError`).
+
+Because it is just the `Storage` interface, you can supply **any** implementation — an in-memory store for tests, or a server-synced `Storage` for cross-device restoration. The framework v1 ships no built-in server endpoint, but the seam is open.
+
+## Wiring it into the browser
+
+Pass an optional `session` to `startBrowserApp`. When present, the framework builds a `SessionStore`, registers your providers, wires a `SessionBridge` (auto-capture on navigation + `pagehide`/`visibilitychange`), runs the boot restore after the first navigation, and hands you a `SessionHandle`:
+
+```ts
+// src/main.ts
+import { startBrowserApp } from "@finesoft/front";
+import { bootstrap } from "./bootstrap";
+import { themeSlice, draftSlice } from "./lib/session";
+
+startBrowserApp({
+    bootstrap,
+    callbacks,
+    session: {
+        providers: [themeSlice, draftSlice],
+        // storage defaults to createWebStorage("session")
+        maxAgeMs: 1000 * 60 * 60 * 24, // discard snapshots older than a day (optional)
+    },
+    mount(target, { session, app }) {
+        // session: SessionHandle (save/clear/scope/...); app: unified nav+session handle.
+        // Auto-capture/restore already run; use session.save() / session.clear() as escape hatches.
+        // ... mount your UI; pass `app` (or `session`) to components ...
+        return () => undefined;
+    },
+});
+```
+
+When `session` is **absent**, none of this runs and the original `startBrowserApp` path is byte-for-byte unchanged.
+
+### Flat vs structured wiring (automatic)
+
+`startBrowserApp` picks the navigation adapter for you:
+
+- **With** a `navigation` config → the structured `createNavigationSessionAdapter(controller)`: it serializes the whole tree, and on restore `hydrate`s it back. Auto-capture is driven by the navigation handle's `subscribe`.
+- **Without** `navigation` (flat single page) → the `createUrlSessionAdapter` bound to `framework.perform(makeFlowAction(url))`: it captures `{ url }` and navigates on restore.
+
+You only choose the adapter directly if you are assembling the store yourself (e.g. on the server, or in tests).
+
+## The handle: manual save / clear / dispose
+
+The `SessionHandle` (delivered in the mount context) gives you the escape hatches — auto-capture already runs, but you can force a write, clear the snapshot, or tear everything down. The unified `app` handle merges navigation commands with session `save`/`clear`/`scope`, so components can hold a single object instead of assembling their own controller:
+
+```ts
+interface SessionHandle {
+    restore(currentUrl: string): void | Promise<void>; // boot restore (already called for you)
+    save(): void; // force an immediate persist
+    clear(): void; // drop the persisted snapshot (e.g. on logout)
+    dispose(): void; // unsubscribe navigation + remove pagehide/visibilitychange + clear timers
+}
+```
+
+Call `handle.clear()` on logout so the next user doesn't inherit a stale session; call `handle.dispose()` if you tear down the app instance yourself.
+
+### When does it capture?
+
+You rarely call `save()` — capture is automatic:
+
+- **On navigation change**: the bridge first prunes the scoped map to `adapter.presentKeys()` (this is where "pop `B` drops `B`'s state" actually lands), then **debounces** a write (default `SESSION_DEFAULT_DEBOUNCE_MS` = 500 ms, coalescing rapid navigations). Tune with `session.debounceMs`.
+- **On `pagehide` and `visibilitychange` (hidden)**: it persists **immediately** and cancels any pending debounce — more reliable than `beforeunload` on mobile (the last state is captured before the tab is backgrounded or reclaimed).
+
+## Deep-link policy: `shouldRestore`
+
+On boot the bridge reads the snapshot and applies it **only if** `shouldRestore(snapshot, currentUrl)` passes — a single boolean gate for the whole `nav + slices` restore. The default, `defaultShouldRestore`, honors **explicit deep links over a stale session**:
+
+| Snapshot `navigation`                   | Restores when…                                                               |
+| --------------------------------------- | ---------------------------------------------------------------------------- |
+| **Flat** (`SessionUrlLocation`)         | `currentUrl === snapshot.navigation.url` **or** the current path is root `/` |
+| **Structured** (`SerializedNavigation`) | the current path is root `/`                                                 |
+| **None** (slices only)                  | always (URL-independent)                                                     |
+
+So reloading the same page (or entering fresh at `/`) restores; opening a different deep link `/x` does **not** get overwritten by an old session. "Root" is the path `=== "/"` (query/hash stripped). Apps served under a base path should override the gate:
+
+```ts
+session: {
+    providers: [themeSlice],
+    shouldRestore: (snapshot, currentUrl) => currentUrl.startsWith("/app/"),
+}
+```
+
+Restoring to a different state than the SSR'd URL produces one client-side jump (SSR renders the URL's screen, then the client restores). That timing is exposed through the bridge so you can control it; a pure-CSR app can restore before first paint and avoid it entirely.
+
+## What is _not_ captured
+
+- **DOM you didn't register.** The framework never scans the DOM. State slices are whatever your providers `capture()` — nothing more.
+- **Anything when you register no providers.** With only navigation (or nothing) registered, capture is effectively zero — the privacy default.
+- **Sensitive fields you exclude.** `capture()` is your filter; strip tokens, PII, and the like there.
+- **A stale, expired, or malformed snapshot.** `load()` returns `undefined` instead of crashing the app to restore a bad state.
+
+## Backward compatibility
+
+- An app that doesn't pass `session` to `startBrowserApp` runs the **original path** with zero behavior change — the entire feature is gated behind that one field.
+- Session restoration adds no requirement on the server. A server-synced snapshot is possible by supplying your own `Storage`, but nothing is built in.
+- The framework restores **state**, never UI. Your `Page` models and how you render them are untouched.
+
+## Next
+
+- [Navigation](./11-navigation.md) — the structured tree whose entries scope per-screen state
+- [Rendering & hydration](./04-rendering-and-hydration.md) — how the first screen is already restored via prefetched results
+- [DI container](./07-di-container.md) — the `Storage` dependency that session restoration persists through