@finesoft/front 0.5.1 → 0.5.3

package/docs/11-navigation.md

@@ -1,355 +1,210 @@
-# 11. Navigation
+# Structured navigation
 
-Chapters 2–4 cover the **flat single-page** lifecycle: one URL → one intent → one page. This chapter adds **structured navigation** — a recursive, UI-agnostic navigation tree analogous to SwiftUI's `NavigationStack`, `TabView`, and `NavigationSplitView`.
+Tabs, Stack and Split are immutable navigation declarations. Page references derive operation targets; branch and column names remain intentional layout identities.
 
-The framework owns navigation **state**, URL/history wiring, and per-destination intent dispatch. It ships **no UI**. Your `Page` models stay exactly as content-agnostic as before — you render tabs, stacks, and split views however you like with Svelte, React, or Vue.
+## Infer parameters from routes
 
-A single-leaf tree is **byte-for-byte** the flat single-page behavior, so this is fully opt-in: apps that never call `defineNavigation` are unaffected.
-
-## The mental model
-
-Navigation state is a tree of four node kinds:
-
-```
-NavigationNode = LeafNode | StackNode | TabsNode | SplitNode
-```
-
-| Node        | Holds                               | Meaning                                                                                                      | SwiftUI               |
-| ----------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------- |
-| `LeafNode`  | `intent` + `params`                 | One destination (one intent dispatch)                                                                        | a destination view    |
-| `StackNode` | ordered `entries[]`                 | A path: `entries[0]` is the root, the last is the visible top                                                | `NavigationStack`     |
-| `TabsNode`  | `active` key + `branches`           | Parallel branches; **only the active one is visible**                                                        | `TabView`             |
-| `SplitNode` | `columns[]` + optional `visibility` | Side-by-side columns; visible set is **all columns by default**, narrowable to `detailOnly` / `doubleColumn` | `NavigationSplitView` |
-
-A leaf carries `intent` + `params`, **not** a `Page`. The tree is pure, serializable data describing _where_ to go; the controller produces _what's there_ (the `Page`) during resolution and hands it back in a snapshot. This is what keeps the tree URL- and history-friendly.
-
-Interior nodes nest recursively — a `TabView` of `NavigationStack`s, a split whose detail column is a stack, and so on.
-
-## Declaring a tree
-
-Constructors live alongside everything else in `@finesoft/front`:
+Declare path and query types in the route and read them separately as `params.id` and `query.tab`. Existing handlers keep path parameters and context as the first two arguments; the third receives query:
 
 ```ts
-import { leaf, stack, tabs, split } from "@finesoft/front";
-
-// A single destination — equivalent to today's flat page
-leaf("home");
-leaf("product", { id: 42 });
-
-// A stack: root only, or root + already-pushed entries
-stack(leaf("feed"));
-stack([leaf("feed"), leaf("post", { id: 7 })]);
-
-// Tabs: each branch is its own stack
-tabs({
-    active: "home",
-    branches: {
-        home: stack(leaf("home")),
-        search: stack(leaf("search")),
-        me: stack(leaf("me")),
+import { definePage, defineWebApp, int, optional, oneOf } from "@finesoft/front";
+
+export const product = definePage({
+    id: "product",
+    routes: [
+        {
+            path: "/products/:id",
+            params: { id: int() },
+            query: { tab: optional(oneOf(["details", "reviews"])) },
+        },
+    ],
+    handler(params, context, query) {
+        context.signal.throwIfAborted();
+        // params.id: number; query.tab?: "details" | "reviews"
+        return { id: params.id.toFixed(), pageType: "product" as const, title: "Product" };
     },
 });
+export const definition = defineWebApp({
+    id: "shop",
+    pages: [product],
+    getErrorPage: (status, title) => ({ id: String(status), pageType: "error", title }),
+});
 
-// Split: sidebar + detail, where detail is a stack
-split([
-    { id: "sidebar", content: leaf("folders") },
-    { id: "detail", content: stack(leaf("folder", { id: "inbox" })) },
-]);
+product.leaf({ id: 42 });
+// product.leaf({ id: "42" }); // Type error
 ```
 
-`tabs()` derives a stable tab `order` from the `branches` insertion order unless you pass `order` explicitly. `stack()` accepts a single root node or an array of entries.
+Use an independent `BaseController` subclass for recovery. `execute` can return synchronously or asynchronously; `fallback` is optional and bypassed on cancellation. Existing `perform` factories remain supported. `create` does not accept objects with only `execute/fallback`.
 
-## A TabView of NavigationStacks
+### Independent controller classes
 
-The most common shape: a bottom tab bar where each tab keeps its own navigation depth.
+Keep routes and classes in separate files. Declare input types only in the routes; use `execute({ params, query, context })` and optional `fallback({ params, query, context, error })` methods:
 
 ```ts
-// src/bootstrap.ts
-import { type Framework, defineRoutes, defineNavigation, leaf, stack, tabs } from "@finesoft/front";
-import { HomeController } from "./lib/controllers/home";
-import { SearchController } from "./lib/controllers/search";
-import { ProfileController } from "./lib/controllers/profile";
-import { PostController } from "./lib/controllers/post";
-
-export function bootstrap(framework: Framework): void {
-    defineRoutes(framework, [
-        { path: "/", intentId: "home", controller: new HomeController() },
-        { path: "/search", intentId: "search", controller: new SearchController() },
-        { path: "/me", intentId: "me", controller: new ProfileController() },
-        { path: "/posts/:id", intentId: "post", controller: new PostController() },
-    ]);
+// controllers/product.ts — no repeated input annotations when authoring
+import { BaseController } from "@finesoft/front";
+import type { ProductPage } from "../models/product";
+
+export class ProductController extends BaseController {
+    execute({ params, query, context }): ProductPage {
+        return { id: params.id.toFixed(), pageType: "product", title: "Product" };
+    }
 }
-
-// The navigation structure, declared once
-export const navigation = defineNavigation({
-    initial: tabs({
-        active: "home",
-        branches: {
-            home: stack(leaf("home")),
-            search: stack(leaf("search")),
-            me: stack(leaf("me")),
-        },
-    }),
-});
 ```
 
-`defineNavigation` returns a normalized definition with two adapters — `toBrowserConfig()` for CSR and `toSSRDefinition()` for SSR — so you declare the tree **once** and hand the right shape to each runner.
-
-### Wiring it into the browser
-
-`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 } from "@finesoft/front";
-import { bootstrap, navigation } from "./bootstrap";
-
-startBrowserApp({
-    bootstrap,
-    callbacks,
-    navigation: navigation.toBrowserConfig(),
-    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;
-    },
+// app-definition.ts
+import { definePage, int } from "@finesoft/front";
+import { ProductController } from "./controllers/product";
+
+export const product = definePage({
+    id: "product",
+    routes: [{ path: "/products/:id", params: { id: int() } }],
+    create: () => new ProductController(),
 });
 ```
 
-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
+The framework finds `BaseController` subclasses through the `create` return type. It maintains only type imports, parameter annotations and base-class generics. Declarations live in `.finesoft/controller-types.d.ts`; no declaration block is appended to controller files. These references appear in saved source, but application authors do not maintain them. Handwritten annotations are preserved; remove the input annotations and base input generic to let the generator manage a class. Keep explicit page return types on methods.
 
-The `NavigationHandle` exposes the operations. Each returns a `Promise<NavigationSnapshot>` (the committed tree plus every visible destination's resolved `Page`) and, in the browser, writes the new state to history/URL.
+Generated source uses short type names and passes the complete input contract to the base class:
 
 ```ts
-// Push a destination onto the active stack
-await handle.push("post", { id: 7 });
-
-// Pop back
-await handle.pop(); // one level
-await handle.pop(2); // two levels — never past the stack root
-await handle.popToRoot();
-
-// Replace the current top (e.g. login → dashboard without a back step)
-await handle.replaceTop("dashboard");
-
-// Switch the active tab — the other tabs keep their stack depth
-await handle.selectTab("search");
+import type {
+    ProductControllerInput as Input,
+    ProductControllerFailure as Failure,
+} from "../../../.finesoft/controller-types";
+
+export class ProductController extends BaseController<Input, ProductPage> {
+    async execute({ params, query, context }: Input): Promise<ProductPage> {
+        /* application logic */
+    }
+    fallback({ params, error }: Failure): ProductPage {
+        /* recovery logic */
+    }
+}
 ```
 
-`pop` never pops below a stack's root entry. With no explicit target, stack operations act on the **deepest active stack** (the one currently visible), and `selectTab` acts on the **outermost** tabs node — exactly what you want for a tab bar driving the focused stack.
+`Input` includes `params`, `query` and `context`; `Failure` adds `error`. The generator uses class-qualified aliases when multiple controllers share a file or names are occupied. `BaseController<Input, Result>` is the only generic form; handwritten inputs can use `ControllerInput<Params, Query>`. Direct `perform` calls retain parameter and result checks.
 
-### Reading the result
+Migrate existing positional `execute` / `fallback` methods to the object argument first. The generator updates type references; it does not rewrite method bodies and reports a migration error for the old multi-argument signature.
 
-A `NavigationSnapshot` is what you render:
+Standard TypeScript declarations provide editor completion and command-line checking. Generation never executes application modules or instantiates controllers, and adds no runtime code. A class registered against several routes receives their input union, with normal narrowing required.
 
-```ts
-const snapshot = handle.getSnapshot();
-snapshot.tree; // the current NavigationNode tree
-snapshot.destinations; // ResolvedDestination[]: { intent, params, page, status? }
-```
-
-`destinations` is ordered to match `collectVisibleDestinations(tree)`: a tabs node contributes **only** its active branch, a split contributes **every** non-empty column. That ordering is also exactly what gets prefetched on the server.
-
-Your view layer walks `snapshot.tree` to lay out the chrome (which tabs exist, how deep each stack is) and reads `snapshot.destinations` for the page content. The framework never tells you _how_ to draw any of it.
+When a route registration is removed but its class remains, generation retains that class's last input contract for independent use. Registering it again updates the contract from the new routes. Solution-style `tsconfig.json` files automatically select the referenced application project containing `src`; use `controllerTypes.tsconfig` when several projects qualify.
 
-## A NavigationSplitView
-
-A split view shows multiple columns at once — the classic sidebar + detail (+ sub-detail) layout. Selecting in one column drives the next.
+Templates already enable generation. For existing apps, install `typescript` as a development dependency and create the framework plugin outside `lazyPlugins` so `vp check` generates types when reading the config:
 
 ```ts
-export const navigation = defineNavigation({
-    initial: split([
-        { id: "sidebar", content: leaf("mailboxes") },
-        { id: "list", content: undefined }, // chosen later
-        { id: "detail", content: undefined },
-    ]),
+const front = finesoftFrontViteConfig({
+    controllerTypes: { root: import.meta.dirname },
+});
+export default defineConfig({
+    lint: { options: { typeAware: true, typeCheck: true } },
+    plugins: lazyPlugins(() => [front, react()]),
 });
 ```
 
-Use `selectColumn(columnId, intent, params?)` to set a column's content:
-
-```ts
-// Pick a mailbox → fills the "list" column
-await handle.selectColumn("list", "messages", { mailbox: "inbox" });
-
-// Pick a message → fills the "detail" column
-await handle.selectColumn("detail", "message", { id: 1024 });
-
-// Re-pick a mailbox → clears "list" AND "detail" (everything after it)
-await handle.selectColumn("list", "messages", { mailbox: "archive" });
-
-// Clear a column explicitly by passing undefined for the intent
-await handle.selectColumn("detail", undefined);
-```
-
-Setting a column **clears every column after it**. Re-choosing the sidebar correctly invalidates the open detail, so you never render a stale "old detail with a new sidebar" combination.
-
-By default every column is visible, so the snapshot's `destinations` contains one entry **per non-empty column** — the framework dispatches (and on the server, prefetches) each of them.
-
-### Column visibility
+`vp dev` watches source changes; `vp check` and builds also generate declarations. Run one of these commands when first opening a project. Ignore `.finesoft/` in Git and commit the managed source references. With standalone `tsc` or a custom toolchain, first call `generateControllerTypes({ root })` from `@finesoft/front`. Set `controllerTypes: false` to disable maintenance.
 
-Mirroring SwiftUI's `NavigationSplitViewVisibility`, a split carries an optional **visibility** — bindable, serializable navigation state (not styling) that decides which columns count as visible, and therefore what gets prefetched on the server:
-
-| `visibility`                  | Visible columns                 |
-| ----------------------------- | ------------------------------- |
-| `automatic` (default) / `all` | every column                    |
-| `doubleColumn`                | first + last (hides the middle) |
-| `detailOnly`                  | last (detail) only              |
+The app returned by `createBrowserApp({ definition, target })`, `createWebSession`, and the SSR `render(app)` callback retain the definition's parameter map:
 
 ```ts
-import { SPLIT_VISIBILITIES, visibleSplitColumns } from "@finesoft/front";
-
-// Declare it up front (e.g. deep-link straight to the detail)
-split(
-    [
-        { id: "sidebar", content: leaf("mailboxes") },
-        { id: "detail", content: leaf("message", { id: 7 }) },
-    ],
-    SPLIT_VISIBILITIES.DETAIL_ONLY,
-);
-
-// Or change it at runtime — newly-visible columns are dispatched, hidden ones are dropped from the snapshot
-await handle.setVisibility(SPLIT_VISIBILITIES.DETAIL_ONLY); // only the detail destination remains
-await handle.setVisibility(SPLIT_VISIBILITIES.ALL); // re-prefetches sidebar + list
-
-// Render only the visible columns without re-implementing the mapping
-for (const col of visibleSplitColumns(splitNode)) renderColumn(col);
+await app.perform({ kind: "push", intent: "product", params: { id: 42 } });
+// A string id, missing id, or unknown intent produces a type error.
 ```
 
-`detailOnly` deep-links resolve and prefetch **only** the detail column on the server — the hidden columns cost nothing until shown. Compact-width collapse (SwiftUI's `preferredCompactColumn`) is viewport-reactive rendering, so it stays entirely in your hands; read `getPlatform()` / the viewport and collapse the split into a stack view however you like.
+`route()` and page reference `.route()` results retain their declared codec types. Keep the inferred factory return types instead of annotating `definition` with the broad `WebAppDefinition`. An explicit `PageRoute` annotation permits absent codecs, so inferred inputs must also account for that possibility; use `satisfies PageRoute` to check the declaration without erasing its concrete type. Components needing an explicit app type can use `WebAppView<typeof definition>` or `ViewProps<ProductPage, typeof definition>` without repeating parameter interfaces. The default `WebAppView` remains suitable for generic layouts and Outlets.
 
-## Targeting a nested container
+String arrays such as `routes: ["/items/:id", "/products/:id"]` still declare aliases. Unspecified path codecs produce strings; `:tab?` is optional. Different alias parameter shapes produce a union that the controller must narrow. When several aliases match the same parameters, provide `url` on the structured destination to select a path, for example `product.leaf({ id: 42 }, { url: "/products/42" })`.
 
-When a tree has more than one stack/tabs/split, pass an explicit `target` path to operate on a deeper one. A path is a list of steps from the root:
+`optional`, `withDefault`, `list`, and third-party Standard Schema outputs determine receiver types. References and structured actions use this same output shape, so defaulted fields remain required there; URL navigation can omit them and let the Router apply defaults. The existing Router still validates and converts parameters, without a second schema pass.
 
-```ts
-import type { NavigationPath } from "@finesoft/front";
-
-// The stack inside the detail column of a split
-const detailStack: NavigationPath = [
-    { kind: "column", id: "detail" },
-    { kind: "stack-entry", index: 0 },
-];
-
-await handle.push("attachment", { id: 3 }, { target: detailStack });
-await handle.selectTab("photos", someTabsPath);
-```
+### Query and path parameters
 
-Without a `target`, operations default to the active path, which is the right choice the vast majority of the time.
-
-## Pure operations (no controller needed)
-
-Everything above is backed by pure, immutable tree functions you can use directly — for tests, optimistic computation, or building your own controller:
+Both use the same codecs and inference, supplied as separate properties of the controller argument. No manual URL parsing is required:
 
 ```ts
-import {
-    push,
-    pop,
-    selectTab,
-    collectVisibleDestinations,
-    resolveActivePath,
-} from "@finesoft/front";
-
-const next = push(tree, leaf("post", { id: 7 })); // returns a new tree
-const visible = collectVisibleDestinations(next); // readonly LeafNode[]
-const activePath = resolveActivePath(next);
+routes: [
+    {
+        path: "/products/:id",
+        params: { id: int() },
+        query: {
+            q: withDefault(str(), ""),
+            tags: optional(list(str())),
+        },
+    },
+];
+// execute({ params, query, context }):
+// params.id: number; query.q: string; query.tags: string[] | undefined.
+await app.perform({
+    kind: "push",
+    intent: "product",
+    params: { id: 42 },
+    query: { q: "a & b", tags: ["new", "sale"] },
+});
 ```
 
-These never mutate their input — only the nodes on the changed path are rebuilt; the rest of the tree is shared by reference. Invalid targets (e.g. `selectTab` on a non-tabs node, popping an empty stack target) throw a `NavigationError`.
-
-## Server-side rendering
+The router encodes params in the path and query in the query string. Arrays preserve their order as repeated keys. URL navigation also accepts `/products/42?q=a%20%26%20b&tags=new&tags=sale` directly.
 
-SSR prefetches **all** visible destinations and serializes them — plus the tree itself — into the HTML, so the browser's first render reuses the server result without refetching. Multi-column split views naturally prefetch multiple intents.
+Query names are not restricted to path placeholders. `optional` permits missing values; `withDefault` supplies missing values while explicit empty strings still undergo validation. `list` collects repeated keys and yields `[]` when absent. `optional(list(...))` yields `undefined` when absent; `withDefault(list(...), [...])` uses the default array. Single-value schemas keep the last repeated value. Undeclared query fields retain string compatibility without declared-field type guarantees; same-named path and query fields retain their independent values.
 
-Use `createSSRNavigationRender` with the SSR adapter:
+## Tree / 导航树
 
 ```ts
-// src/ssr.ts
-import { createSSRNavigationRender } from "@finesoft/front";
-import { bootstrap, navigation } from "./bootstrap";
-import { renderApp } from "./lib/render";
-
-export const render = createSSRNavigationRender({
-    bootstrap,
-    getErrorPage: (status, message) => ({
-        id: `error-${status}`,
-        pageType: "error",
-        title: message,
-    }),
-    renderApp, // (page, framework, snapshot) => { html, head, css }
-    navigation: navigation.toSSRDefinition(),
+import { stack, tabs, split } from "@finesoft/front";
+import { home, product } from "./pages";
+export const navigation = tabs({
+    active: "catalog",
+    branches: {
+        catalog: stack([home.leaf(), product.leaf({ id: 42 })]),
+        compare: split([{ id: "left", content: product.leaf({ id: 42 }) }, { id: "right" }]),
+    },
 });
+// defineWebApp({ ..., navigation })
 ```
 
-`renderApp` receives three arguments: the **primary** page (the active leaf's result — compatible with the flat SSR `renderApp` signature), the framework, and the full multi-region `snapshot` so you can render tabs/split layouts:
-
-```ts
-function renderApp(page, framework, snapshot) {
-    // page         → the focused destination (e.g. for <title>, status)
-    // snapshot.tree         → which tabs/columns to draw
-    // snapshot.destinations → the Page for each visible region
-    return renderYourFramework(snapshot);
-}
-```
+Each equal target still receives its own EntryId and draft. ResourceKey may share explicitly cached query data without sharing view state. Standard browser start owns URL actions, redirects and popstate; obsolete URL results cannot commit over later work. Explicit tree operations use one serialized controller queue. Tabs retain branches, Stack retains present entries, Split guards each destination. Choose renderer mode `entries` when native entry lifetimes should follow the tree.
 
-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).
+## Navigation actions
 
-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.
+All navigation uses `app.perform(action)`. URLs use `{ kind: "flow", url }`; structured navigation uses these actions:
 
-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.
+| kind              | Fields                                                        |
+| ----------------- | ------------------------------------------------------------- |
+| push / replaceTop | intent, params?, query?, target?, url?                        |
+| pop               | count?, target?                                               |
+| popToRoot         | target?                                                       |
+| popTo             | index, target?                                                |
+| selectTab         | key, target?                                                  |
+| selectColumn      | columnId, intent (undefined clears), params?, query?, target? |
+| setVisibility     | visibility, target?                                           |
+| reuseEntry        | entryId                                                       |
+| refresh           | —                                                             |
+| hydrate           | tree                                                          |
 
-## Deep-linking with `createFullStateCodec`
+## Transaction policies
 
-By default, the **active leaf** drives the URL (`/posts/7`) and the full tree travels via history state — clean, shareable URLs for the focused destination. To encode the **entire** tree into the URL for full deep-linking (sharing a link that restores tabs, stack depth, and split selections), opt into `createFullStateCodec`:
+`defineWebApp({ beforeNavigate, beforeCommit })` adds optional whole-tree policies. Each policy in its array runs once per transaction, even when the target tree is empty. Definition policies run before controller-local policies. `beforeLoad` / `afterLoad` still run for each visible page.
 
 ```ts
-import { createFullStateCodec } from "@finesoft/front";
-
-export const navigation = defineNavigation({
-    initial: tabs({
-        active: "home",
-        branches: { home: stack(leaf("home")), me: stack(leaf("me")) },
-    }),
-    codec: createFullStateCodec(), // whole tree → "?__nav=..." query param
-});
+import { next, deny, type BeforeCommitPolicy } from "@finesoft/front";
+import { hasUnsavedDraft } from "./editor-state";
+export const preserveDraft: BeforeCommitPolicy = ({ from, candidate }) => {
+    // Inspect application-owned draft state and both trees here.
+    const leavingEditor =
+        from.destinations.some((page) => page.intent === "editor") &&
+        !candidate.destinations.some((page) => page.intent === "editor");
+    return leavingEditor && hasUnsavedDraft()
+        ? deny(409, "Save your draft before leaving")
+        : next();
+};
+// defineWebApp({ ..., beforeCommit: [preserveDraft] })
 ```
 
-Now URLs look like `/me?__nav=<encoded-tree>`, and pasting one restores the complete navigation state on both SSR and the browser. The encoding is compact (base64url), stable (sorted keys, so the same tree always yields the same string), and lossless. Pass `createFullStateCodec({ param: "nav" })` to rename the reserved query parameter.
-
-You can also implement a custom `NavigationCodec` if you need a bespoke URL scheme — both built-ins only depend on the router's `getRoutes()` (and optional `reverse()`), nothing more.
-
-## Guards still work
-
-Navigation-level `beforeLoad` / `afterLoad` guards run for the **primary** destination (the active leaf) on every navigation, with the same `redirect` / `rewrite` / `deny` semantics as [chapter 3](./03-middleware.md):
-
-```ts
-export const navigation = defineNavigation({
-    initial: tabs({
-        active: "home",
-        branches: { home: stack(leaf("home")), me: stack(leaf("me")) },
-    }),
-    beforeLoad: [authGuard],
-});
-```
-
-- `redirect` → handled as an in-app navigation (the browser reuses the FlowAction pipeline); the target isn't dispatched.
-- `rewrite` → the new URL is re-resolved into the destination's intent/params.
-- `deny` → the destination is marked with the deny status and its intent is not dispatched.
-
-A single destination's dispatch failure never throws out of an operation — it records a `status` and a fallback page on that destination (the same `fallback` safety net as controllers), so one failing split column can't blank the whole screen.
-
-## Backward compatibility
+Admission receives `from`, candidate `tree`, stable `transitionId`, active `execution`, its `signal`, and `isServer`. It returns `next`, `deny`, or `redirect`. Page redirects keep the same transaction identity and do not repeat admission. Commit policies also receive the loaded `candidate`; they return only `next` or `deny`, before cache consumption, committed state, history, events or views change. Each redirect hop retains its existing execution cleanup; the final commit policy sees the final hop's execution. Async policies must honor cancellation for their own I/O; stale results cannot commit.
 
-- Apps that don't pass `navigation` to `startBrowserApp` / `createSSRRender` run the **original flat path** with zero behavior change.
-- A single-leaf tree is equivalent to the flat single page: one visible destination, one resolve/dispatch, one before/after pass. SSR only adds the tree sentinel to `serverData` (stripped before it reaches `PrefetchedIntents`).
-- `Page` stays content-agnostic. Navigation adds structure _around_ your pages; it never dictates their shape or how you render them.
+A denial returns an uncommitted snapshot with `rejection`, including for empty trees. Session restore rejects it before replacing scopes or slices. Initial browser denial renders the error without committing navigation or recording a page visit; later denial preserves the displayed draft. Both flat and navigation SSR honor these policies and emit no rejected page data or public-cache permission. CSR shells still defer navigation to the browser.
 
-## Next
+Owned back/forward rejection compensates to the committed history entry and restores its scroll identity. Additive history metadata preserves ownership and position across reloads. Entries without compatible ownership metadata are diagnosed; the framework cannot infer a safe traversal distance for external entries.
 
-- [Middleware](./03-middleware.md) — the guard semantics navigation reuses
-- [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
+Low-level hosts configuring `createWebSession({ createContext })` return a `NavigationContext` directly. The execution supplies its DI container and cancellation signal; request cookies and headers stay in the host context. The session uses the application's `getErrorPage` unless explicitly overridden.