@finesoft/front 0.5.1 → 0.5.2

package/docs/zh/11-navigation.md

@@ -1,355 +1,195 @@
-# 11. 导航
+# 结构化导航
 
-第 2–4 章讲的是**扁平单页**生命周期：一个 URL → 一个 intent → 一个页面。本章补上**结构化导航** —— 一棵递归的、与 UI 无关的导航树，对标 SwiftUI 的 `NavigationStack`、`TabView`、`NavigationSplitView`。
+Tabs、Stack、Split 是不可变导航声明。页面引用生成操作目标；分支、列名称仍是明确的布局标识。
 
-框架持有导航的**状态**、URL/history 接线、以及对每个目标的 intent 派发。它**不含任何 UI**。你的 `Page` 模型与之前一样保持内容无关 —— tabs、stack、split 怎么画，由你用 Svelte / React / Vue 自行决定。
+## 路由定义驱动参数类型
 
-单个叶子树**逐位等价**于扁平单页，因此本特性完全可选：从不调用 `defineNavigation` 的应用行为不变。
-
-## 心智模型
-
-导航状态是一棵由四种节点构成的树：
-
-```
-NavigationNode = LeafNode | StackNode | TabsNode | SplitNode
-```
-
-| 节点        | 持有                            | 语义                                                                   | SwiftUI               |
-| ----------- | ------------------------------- | ---------------------------------------------------------------------- | --------------------- |
-| `LeafNode`  | `intent` + `params`             | 一个目标（一次 intent 派发）                                           | 一个 destination view |
-| `StackNode` | 有序 `entries[]`                | 一条路径：`entries[0]` 是根，末尾是可见的栈顶                          | `NavigationStack`     |
-| `TabsNode`  | `active` 键 + `branches`        | 并列分支；**仅激活分支可见**                                           | `TabView`             |
-| `SplitNode` | `columns[]` + 可选 `visibility` | 多列并存；可见集**默认全部列**，可收窄为 `detailOnly` / `doubleColumn` | `NavigationSplitView` |
-
-叶子持有 `intent` + `params`，**不是** `Page`。树是纯粹的、可序列化的数据，描述「要去哪」；「那里是什么」（`Page`）由 controller 在解析时产出，并随快照交回。这正是树能进 URL / history 的原因。
-
-内部节点递归嵌套 —— 一个由 `NavigationStack` 组成的 `TabView`、detail 列是 stack 的 split，等等。
-
-## 声明一棵树
-
-构造器与其它一切一样从 `@finesoft/front` 导入：
+路径参数和 query 都在路由中声明类型，并分别读取为 `params.id`、`query.tab`。既有 `handler` 仍接收路径参数和执行上下文，第三个参数接收 query：
 
 ```ts
-import { leaf, stack, tabs, split } from "@finesoft/front";
-
-// 一个目标 —— 等价于今天的扁平单页
-leaf("home");
-leaf("product", { id: 42 });
-
-// 栈：只有根，或根 + 已 push 的 entry
-stack(leaf("feed"));
-stack([leaf("feed"), leaf("post", { id: 7 })]);
-
-// Tabs：每个分支自成一个栈
-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，detail 是一个栈
-split([
-    { id: "sidebar", content: leaf("folders") },
-    { id: "detail", content: stack(leaf("folder", { id: "inbox" })) },
-]);
+product.leaf({ id: 42 });
+// product.leaf({ id: "42" }); // 编译错误
 ```
 
-`tabs()` 缺省 `order` 时按 `branches` 的插入顺序推导稳定 tab 顺序。`stack()` 接受单个根节点或一个 entries 数组。
+需要错误恢复时使用独立的 `BaseController` 子类；`execute` 可同步或异步返回，`fallback` 可省略，取消执行不会进入 `fallback`。已有 `perform` 工厂继续支持。`create` 不接受只有 `execute/fallback` 的对象。
 
-## 由 NavigationStack 组成的 TabView
+### 独立 Controller 类
 
-最常见的形态：底部标签栏，每个 tab 保留自己的导航深度。
+路由与类可以分文件。只在路由中维护输入类型，类统一使用 `execute({ params, query, context })` / `fallback({ params, query, context, error })`：
 
 ```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 — 编写时不用重复参数类型
+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" };
+    }
 }
-
-// 导航结构，只声明一次
-export const navigation = defineNavigation({
-    initial: tabs({
-        active: "home",
-        branches: {
-            home: stack(leaf("home")),
-            search: stack(leaf("search")),
-            me: stack(leaf("me")),
-        },
-    }),
-});
 ```
 
-`defineNavigation` 返回一个规范化的定义，附带两个适配器 —— `toBrowserConfig()` 给 CSR、`toSSRDefinition()` 给 SSR —— 因此你只声明**一次**树，就能把各自需要的形态交给对应 runner。
-
-### 接入浏览器
-
-`startBrowserApp` 新增一个可选 `navigation` 字段；存在时，`NavigationHandle`（以及统一的 `app` 句柄）会在 `mount` 回调的 context 里交给你，挂载时即可直接使用：
-
 ```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 在 mount 时已就绪，无需等待回调。
-        // 快照变更时重渲染：
-        nav?.subscribe((snapshot) => mountNavigation(snapshot));
-        if (nav) mountNavigation(nav.getSnapshot());
-        // ... 把 UI 挂载到 target，将 app 传给组件 ...
-        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(),
 });
 ```
 
-提供 `navigation` 时，框架会构建 `NavigationController` 和 history 桥、解析首屏，并在 mount context 中把 handle 交给你。缺省时 `startBrowserApp` 走原有扁平单页路径，行为不变。
-
-## 驱动导航
+框架根据 `create` 返回的类定位 `BaseController` 子类，只维护 `import type`、参数注解与基类泛型。`context` 保留 DI、取消信号等执行服务；query 不混入 params。类型声明集中在 `.finesoft/controller-types.d.ts`，不会在 Controller 文件末尾追加声明区块。保存的类源码会出现这些引用，业务无需手写或同步。手写参数类型保留；移除参数注解与基类输入泛型即可交给生成器管理。建议保留方法的返回页面类型。
 
-`NavigationHandle` 暴露各操作。每个都返回 `Promise<NavigationSnapshot>`（提交后的树 + 每个可见目标解析出的 `Page`），并在浏览器侧把新状态写入 history/URL。
+生成后使用短类型名，基类直接接收完整输入类型：
 
 ```ts
-// 在激活栈压入一个目标
-await handle.push("post", { id: 7 });
-
-// 弹回
-await handle.pop(); // 一层
-await handle.pop(2); // 两层 —— 绝不越过栈根
-await handle.popToRoot();
-
-// 替换当前栈顶（如 登录 → dashboard 且不留返回步）
-await handle.replaceTop("dashboard");
-
-// 切换激活 tab —— 其它 tab 保留各自栈深
-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> {
+        /* 业务逻辑 */
+    }
+    fallback({ params, error }: Failure): ProductPage {
+        /* 回退逻辑 */
+    }
+}
 ```
 
-`pop` 绝不弹到栈根之下。不显式给 target 时，栈操作作用于**最深的激活栈**（当前可见的那个），`selectTab` 作用于**最外层**的 tabs 节点 —— 这正是「标签栏驱动聚焦栈」想要的。
-
-### 读取结果
+`Input` 已包含 `params`、`query` 和 `context`，无需在基类中再次拆开；`Failure` 额外包含 `error`。同文件有多个控制器或名称冲突时使用带类名的别名。基类统一使用 `BaseController<Input, Result>`，手写输入可使用 `ControllerInput<Params, Query>`。直接调用 `perform` 的参数与结果保持类型检查。
 
-`NavigationSnapshot` 就是你拿来渲染的东西：
+旧的多个位置参数写法需要先迁移为单对象参数。生成器只更新类型引用，不改写方法业务逻辑；遇到旧的多参数 `execute` / `fallback` 签名时会报告迁移提示。
 
-```ts
-const snapshot = handle.getSnapshot();
-snapshot.tree; // 当前 NavigationNode 树
-snapshot.destinations; // ResolvedDestination[]：{ intent, params, page, status? }
-```
-
-`destinations` 的顺序与 `collectVisibleDestinations(tree)` 一致：tabs 节点**只**贡献激活分支，split **每个**非空列都贡献。这个顺序也正是服务端预取的内容。
+这使用标准 TypeScript 声明，因此编辑器补全与命令行检查一致。它不会执行路由模块、实例化 Controller，也不会增加运行时代码。同一类用于多个路由时，params/query 分别保留对应路由的输入类型，需要正常收窄。
 
-你的视图层遍历 `snapshot.tree` 排布外壳（有哪些 tab、每个栈多深），从 `snapshot.destinations` 读页面内容。框架从不告诉你**怎么**画。
+取消路由注册但保留类时，框架保留该类最后一次生成的输入契约，避免破坏它的独立使用；重新注册后按新路由更新。引用式 `tsconfig.json` 会自动选择包含 `src` 的应用项目；有多个候选项目时，通过 `controllerTypes.tsconfig` 指定应用配置。
 
-## NavigationSplitView
-
-split 视图同时展示多列 —— 经典的 sidebar + detail（+ sub-detail）布局。一列的选择驱动下一列。
+模板已配置自动生成。现有项目安装开发依赖 `typescript`，并把框架插件的创建放在 `lazyPlugins` 外，确保 `vp check` 读取配置时也会生成类型：
 
 ```ts
-export const navigation = defineNavigation({
-    initial: split([
-        { id: "sidebar", content: leaf("mailboxes") },
-        { id: "list", content: undefined }, // 稍后选择
-        { 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()]),
 });
 ```
 
-用 `selectColumn(columnId, intent, params?)` 设置某列内容：
-
-```ts
-// 选一个邮箱 → 填充 "list" 列
-await handle.selectColumn("list", "messages", { mailbox: "inbox" });
-
-// 选一封邮件 → 填充 "detail" 列
-await handle.selectColumn("detail", "message", { id: 1024 });
-
-// 重选邮箱 → 清空 "list" 与 "detail"（它之后的所有列）
-await handle.selectColumn("list", "messages", { mailbox: "archive" });
-
-// 给 intent 传 undefined 显式清空某列
-await handle.selectColumn("detail", undefined);
-```
-
-设置某列会**清空它之后的所有列**。重选 sidebar 会正确作废已打开的 detail，于是你绝不会渲染出「旧 detail 配新 sidebar」的错配。
-
-默认所有列都可见，快照的 `destinations` 里**每个非空列**各一条 —— 框架会派发（服务端则预取）它们每一个。
-
-### 列可见性
-
-对标 SwiftUI 的 `NavigationSplitViewVisibility`，split 带一个可选的 **visibility** —— 这是**可绑定、可序列化的导航状态**（不是样式），它决定哪些列算可见，进而决定服务端预取什么：
+`vp dev` 启动后监听源码变更；`vp check` 与构建也会生成。初次打开项目先运行其中一个命令。将 `.finesoft/` 加入 `.gitignore`，提交类中的框架管理引用。直接使用 `tsc` 或自定义工具链时，先调用 `@finesoft/front` 导出的 `generateControllerTypes({ root })`。`controllerTypes: false` 关闭自动维护。
 
-| `visibility`               | 可见列                    |
-| -------------------------- | ------------------------- |
-| `automatic`（缺省）/ `all` | 全部列                    |
-| `doubleColumn`             | 首列 + 末列（隐藏中间列） |
-| `detailOnly`               | 仅末列（detail）          |
+`createBrowserApp({ definition, target })` 返回的 `app`、`createWebSession` 和 SSR 的 `render(app)` 都保留该定义的参数关联：
 
 ```ts
-import { SPLIT_VISIBILITIES, visibleSplitColumns } from "@finesoft/front";
-
-// 声明时即指定（例如深链直达 detail）
-split(
-    [
-        { id: "sidebar", content: leaf("mailboxes") },
-        { id: "detail", content: leaf("message", { id: 7 }) },
-    ],
-    SPLIT_VISIBILITIES.DETAIL_ONLY,
-);
-
-// 或运行时切换 —— 新变可见的列会被派发，隐藏的列从快照中移除
-await handle.setVisibility(SPLIT_VISIBILITIES.DETAIL_ONLY); // 只剩 detail 目标
-await handle.setVisibility(SPLIT_VISIBILITIES.ALL); // 重新预取 sidebar + list
-
-// 无需自己重实现映射，直接拿可见列渲染
-for (const col of visibleSplitColumns(splitNode)) renderColumn(col);
+await app.perform({ kind: "push", intent: "product", params: { id: 42 } });
+// id: "42"、缺少 id 或未知 intent 都会产生编译错误。
 ```
 
-`detailOnly` 深链在服务端**只**解析并预取 detail 列 —— 隐藏列在显示前不耗成本。compact 窗口塌缩成单栈（SwiftUI 的 `preferredCompactColumn`）是视口反应式的纯渲染，框架不碰，完全交给你：读 `getPlatform()` / 视口，自行把 split 塌成栈视图。
-
-## 定位嵌套容器
+`route()` 和页面引用的 `.route()` 返回值也保留已声明的 codec 类型。保留工厂返回值的推导；不要用宽类型 `WebAppDefinition` 注解覆盖 `definition`。显式标为 `PageRoute` 的变量允许省略 codec，接收方类型也必须考虑未配置 codec 的情况；需要校验声明形状时可用 `satisfies PageRoute` 保留具体类型。组件需要显式声明应用类型时使用 `WebAppView<typeof definition>`（或 `ViewProps<ProductPage, typeof definition>`），无需再写参数接口。通用 `WebAppView` 仍用于与任意应用兼容的布局和 Outlet。
 
-当一棵树里有不止一个 stack/tabs/split 时，传一个显式的 `target` 路径来操作更深的那个。路径是从根出发的步骤序列：
+字符串数组如 `routes: ["/items/:id", "/products/:id"]` 继续支持多个别名，未声明 codec 的路径参数为 `string`，`:tab?` 为可选字符串。不同别名的参数结构不同时，控制器接收联合类型，需要先判断对应属性。相同参数匹配多个别名时，结构化目标需提供 `url` 指明路径，例如 `product.leaf({ id: 42 }, { url: "/products/42" })`。
 
-```ts
-import type { NavigationPath } from "@finesoft/front";
-
-// split 的 detail 列里那个栈
-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);
-```
+`optional`、`withDefault`、`list` 与第三方 Standard Schema 的输出决定接收方类型。`leaf` 和结构化 Action 使用同一输出形状；默认值字段在该形状中为必填，URL 导航省略它时仍由 Router 填入默认值。运行时仍由原有 Router 校验和转换参数，不增加第二次 Schema 校验。
 
-不给 `target` 时，操作默认作用于激活路径 —— 绝大多数情况下这都是对的。
+### Query 与路径参数
 
-## 纯操作（不需要 controller）
-
-上面这一切都由纯粹、不可变的树函数支撑，你可以直接用 —— 写测试、做乐观计算、或自建 controller：
+两者共用 codec 与推导规则，在 Controller 的对象入参中分别提供，不需要手动解析 URL：
 
 ```ts
-import {
-    push,
-    pop,
-    selectTab,
-    collectVisibleDestinations,
-    resolveActivePath,
-} from "@finesoft/front";
-
-const next = push(tree, leaf("post", { id: 7 })); // 返回一棵新树
-const visible = collectVisibleDestinations(next); // readonly LeafNode[]
-const activePath = resolveActivePath(next);
-```
-
-它们绝不修改输入 —— 只有被改动路径上的节点会重建，树的其余部分按引用复用。非法 target（如对非 tabs 节点 `selectTab`、对空栈 target 执行 pop）会抛 `NavigationError`。
-
-## 服务端渲染
-
-SSR 预取**所有**可见目标并把它们 —— 连同树本身 —— 序列化进 HTML，于是浏览器首屏直接复用服务端结果、不再取数。多列 split 视图天然预取多个 intent。
-
-用 `createSSRNavigationRender` 配合 SSR 适配器：
-
-```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(),
+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"] },
 });
 ```
 
-`renderApp` 收三个参数：**主目标**页面（激活叶子的结果 —— 与扁平 SSR 的 `renderApp` 签名兼容）、framework、以及完整的多区域 `snapshot`，让你渲染 tabs/split 布局：
-
-```ts
-function renderApp(page, framework, snapshot) {
-    // page                  → 聚焦目标（如用于 <title>、status）
-    // snapshot.tree         → 要画哪些 tab / 列
-    // snapshot.destinations → 每个可见区域的 Page
-    return renderYourFramework(snapshot);
-}
-```
+框架把 params 编入路径、query 编入查询串；数组保留顺序并编码成重复键。普通 URL 导航仍可直接使用 `/products/42?q=a%20%26%20b&tags=new&tags=sale`。
 
-`renderApp` 具体要搭的 islands 外壳 —— chrome + 按目标的 islands 作为独立水合 root，以及客户端 `mountEntry` / `resolveIslandsShell` 如何收养并水合它们 —— 见 [Islands SSR](./04-rendering-and-hydration.md#islands-ssr结构化架构方案-c)。
+Query 的字段名不限于路径占位符；`optional` 允许缺失，`withDefault` 仅在缺失时补值，显式空字符串仍参与校验。`list` 收集同名键，缺失时为 `[]`；`optional(list(...))` 缺失时为 `undefined`，`withDefault(list(...), [...])` 使用默认数组。普通单值字段遇到重复键仍取最后一个值。未声明的 query 保持字符串兼容行为，不会获得声明字段的类型保证；同名字段各自保留，例如 `/products/42?id=other` 的 params.id 为 42，query.id 为 "other"（声明为 str 时）。
 
-底层原理：每个可见目标经**既有的** `PrefetchedIntents` 通道序列化为一条普通的 `{ intent, data: page }`，再额外挂一条承载序列化树的哨兵条目。`@finesoft/server` **零改动** —— 它经同一个 `#serialized-server-data` 脚本透传哨兵。hydration 时浏览器桥从 history state（或哨兵）读回树，并复用预取的页面。
-
-若某请求没有结构化深链、应用也没提供骨架，SSR 回退到 `Router.resolve(url)` → 单个叶子 —— 即今天的扁平单页（含其 `renderMode`）。404 路径不变。
-
-## 用 `createFullStateCodec` 做深链
-
-默认情况下，**激活叶子**驱动 URL（`/posts/7`），完整的树通过 history state 旁路传输 —— 聚焦目标拥有干净、可分享的 URL。若要把**整棵**树编码进 URL 以支持完整深链（分享一个能还原 tab、栈深、split 选择的链接），改用 `createFullStateCodec`：
+## Tree / 导航树
 
 ```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(), // 整树 → "?__nav=..." query 参数
+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 })
 ```
 
-此时 URL 形如 `/me?__nav=<编码后的树>`，粘贴它即可在 SSR 与浏览器两侧还原完整导航状态。编码紧凑（base64url）、稳定（key 排序，相同树永远产出相同串）、无损。传 `createFullStateCodec({ param: "nav" })` 可重命名保留 query 参数。
+相同目标仍有独立 EntryId 与草稿；ResourceKey 可共享显式缓存的查询数据，但不会共享视图状态。标准浏览器启动器拥有 URL 动作、重定向、popstate，过期 URL 结果不能覆盖后来的操作。显式树操作通过单个串行队列执行。Tabs 保留分支，Stack 保留在树条目，Split 检查各个目标。原生视图生命周期需跟随树时选择 `entries`。
 
-如需自定义 URL 方案，你也可以实现自己的 `NavigationCodec` —— 两个内置实现仅依赖 router 的 `getRoutes()`（和可选的 `reverse()`），别无其它。
+## Action 导航
 
-## 守卫照常生效
+所有导航通过 `app.perform(action)` 执行。URL 使用 `{ kind: "flow", url }`；结构化导航使用下列 Action：
 
-导航级 `beforeLoad` / `afterLoad` 守卫在每次导航时对**主目标**（激活叶子）执行，`redirect` / `rewrite` / `deny` 语义与[第 3 章](./03-middleware.md)一致：
-
-```ts
-export const navigation = defineNavigation({
-    initial: tabs({
-        active: "home",
-        branches: { home: stack(leaf("home")), me: stack(leaf("me")) },
-    }),
-    beforeLoad: [authGuard],
-});
-```
+| 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                                                          |
 
-- `redirect` → 当作 SPA 内跳处理（浏览器复用 FlowAction 管线）；该目标不派发。
-- `rewrite` → 用新 URL 重新解析出该目标的 intent/params。
-- `deny` → 给目标打上 deny status，不派发其 intent。
+## 导航事务策略
 
-单个目标的 dispatch 失败绝不会从操作里抛出 —— 它在该目标上记一个 `status` 和一张兜底页（与 controller 一样的 `fallback` 安全网），于是某一列失败不会让整屏空白。
+`defineWebApp({ beforeNavigate, beforeCommit })` 可选地声明整棵树的策略。数组中的每个策略每次事务只运行一次，空树退出也会执行；先执行应用定义的策略，再执行控制器附加策略。`beforeLoad` / `afterLoad` 仍按每个可见页面运行。
 
-## 向后兼容
+`beforeNavigate` 接收原快照 `from`、候选树 `tree`、稳定的 `transitionId`、当前 `execution` 及其 `signal`、`isServer`，返回 `next`、`deny` 或 `redirect`。页面重定向沿用同一事务标识，不重复运行准入策略；各跳转仍由原所有者释放执行资源。`beforeCommit` 另接收加载完成的 `candidate`，仅允许 `next` 或 `deny`，在消费预取缓存、写入快照、历史、事件和视图之前执行。普通应用无需配置策略或手动管理作用域。
 
-- 不向 `startBrowserApp` / `createSSRRender` 传 `navigation` 的应用走**原有扁平路径**，行为零变化。
-- 单叶子树等价于扁平单页：一个可见目标、一次 resolve/dispatch、一对 before/after。SSR 仅在 `serverData` 多挂一条树哨兵（在抵达 `PrefetchedIntents` 前被剔除）。
-- `Page` 保持内容无关。导航在你的页面**周围**加结构，从不规定页面形状或你怎么渲染它。
+拒绝返回带 `rejection` 的未提交快照，空树也能表达拒绝。会话恢复会在替换 scope 和业务 slice 前检查是否提交。浏览器首屏拒绝显示错误页，不提交导航或记录页面访问；后续拒绝保留当前草稿。扁平和导航 SSR 都执行相同策略，不输出被拒绝页面的数据或公开缓存许可。CSR 空壳继续由浏览器执行导航。
 
-## 下一步
+自有历史条目的后退或前进被拒绝时，History 补偿回已提交条目并保持滚动身份；附加元数据让刷新后仍可识别所有权与位置。缺少兼容元数据的外部条目会给出诊断，不猜测应跨越几个历史位置。异步策略应把 `signal` 传给自身 I/O；取消不会回滚已经完成的业务写入。
 
-- [中间件](./03-middleware.md) —— 导航复用的守卫语义
-- [渲染与 Hydration](./04-rendering-and-hydration.md) —— 渲染模式 × 架构矩阵、islands SSR 外壳，以及预取结果如何跨越 SSR → CSR 边界
+底层宿主配置 `createWebSession({ createContext })` 时，回调直接返回 `NavigationContext`。执行作用域提供 DI 容器和取消信号，请求 cookie 与 header 由宿主上下文提供。会话默认使用应用的 `getErrorPage`，也可显式覆盖。