@finesoft/front 0.5.1 → 0.5.3

package/docs/zh/12-session-restoration.md

@@ -1,219 +1,11 @@
-# 12. 会话恢复
+# 会话恢复与多实例
 
-框架已经能恢复**首屏**：SSR 把 prefetch 出来的 intent 结果经 `PrefetchedIntents` 注入 HTML，浏览器在首次导航时复用它们；结构化导航的当前树也会随 `history.state` 走前进 / 后退。
+使用 `createBrowserApp({ definition, target, history: "memory", persistenceKey: "first", session: {}, domRestore: true })` 创建嵌入应用。每个实例需要独立的 target 和稳定 persistenceKey；同一窗口只允许一个浏览器地址栏所有者。
 
-但有一类状态以上手段**全都救不回**：用户**硬重载 / 标签崩溃 / 关掉再回来**时「当时在干什么」—— 他在哪一屏（或哪个栈深、哪个 tab、split 哪一列）、表单里打了一半的草稿、列表滚到哪里。内存里的 `history.state` map 整页重载即清空，`PrefetchedIntents` 只覆盖服务端渲染的那一屏。
+随后用原生 API 挂载 App，再等待 `app.ready`。会话读取及恢复在第一次原生提交确认之后开始，Outlet 的 commit 不等待恢复。React 的持久化 provider 在 layout effect 注册；Vue/Svelte 在原生挂载阶段注册。`app.session.register(provider)` 返回反注册函数。provider 的 capture/restore 直接读写原生业务状态，无需额外 NameStore。
 
-**会话恢复**填这个缺口：把一份带版本、JSON 安全的**会话快照**（导航位置 + 应用注册的状态切片 + 导航作用域的逐屏状态）序列化到可插拔 `Storage`，并在全新加载时重水化。框架**不含任何 UI** —— 它只恢复**状态**，应用据此自行重渲染。
+切换隐藏页面保留原生实例；pop 移除 entry 及其 scoped 草稿。`data-restore-root` 内明确标记的表单与滚动状态由 DOM 恢复层处理，范围限定在所属应用。多个实例不会读取彼此的输入。
 
-它完全可选：从不向 `startBrowserApp` 传 `session` 的应用**逐位等价**于原行为，毫无变化。
+`app.session.save()` / `clear()` 返回可检查的结果。相邻、尚未开始的隐式 save 合并；显式快照、load、restore、clear 构成顺序边界。最终 dispose 捕获当前状态并等待已登记存储操作；浏览器关闭仍不能保证异步存储完成。
 
-## 两种作用域
-
-一份快照捕获两层状态，一起序列化、跨重载一起恢复：
-
-| 作用域             | 存放于   | 键             | 生命周期                               | SwiftUI 对标    |
-| ------------------ | -------- | -------------- | -------------------------------------- | --------------- |
-| **全局切片**       | `slices` | `provider.key` | 整个会话（主题、跨屏向导草稿…）        | `@SceneStorage` |
-| **导航作用域状态** | `scoped` | `entryKey`     | 绑定到某个导航条目 —— 条目离树即被丢弃 | `@State`        |
-
-- **全局切片**是 app-wide 的。每个切片注册一个 `SessionStateProvider`；框架编排*何时*捕获与落盘，但从不解释内容 —— 它只搬运。
-- **导航作用域状态**绑定到某个*导航条目*，对标 SwiftUI 视图 `@State` 的位置作用域生命周期（见下）。
-
-## 全局切片：`SessionStateProvider`
-
-应用为每个切片注册一个 provider。`capture()` 返回 JSON 安全的同步值；`restore(data)` 把它放回（应用自行 `setState` / 回填表单 / 滚动）：
-
-```ts
-import type { SessionStateProvider } from "@finesoft/front";
-
-const themeSlice: SessionStateProvider<string> = {
-    key: "theme",
-    capture: () => getCurrentTheme(),
-    restore: (theme) => applyTheme(theme),
-};
-```
-
-框架原样搬运值、从不窥探 —— 所以捕获什么由**你**决定。敏感字段就在 `capture()` 里自行排除；不注册的切片永不被捕获。
-
-## 导航作用域状态：SwiftUI `@State` 生命周期
-
-导航作用域状态是更有意思的一半。它按**条目身份**而非可见性建键，遵循与 SwiftUI 视图 `@State` 相同的位置作用域生命周期：
-
-> `A` → push `B` → 返回（pop `B`）到 `A`：**`B` 的状态被丢弃，`A` 的状态仍在。**
-
-机制：每个条目的状态袋按 `entryKey = intent + " " + stableStringify(params)` 存放 —— 与导航 controller 给目标用的身份同源，故**跨重载稳定**。每次导航提交后，框架把 scoped map **prune** 到树中**实际存在**的条目 —— 注意是*存在*，不是*可见*。条目已不在树中的键即被丢弃。
-
-```ts
-import { sessionEntryKey } from "@finesoft/front";
-
-// 渲染某屏时，用该条目的键读写它的作用域袋：
-const key = sessionEntryKey("post", { id: 7 });
-store.scope.set(key, { scroll: 240, draft: "评论打了一半" });
-const bag = store.scope.get(key); // -> { scroll: 240, draft: "..." } | undefined
-```
-
-逐步走一遍生命周期：
-
-- **push `B`** → 树 `[A, B]`，present `{A, B}` → `A` 的状态**保留**（`A` 仍在栈中、只是不可见），`B` 拿到自己的作用域。
-- **pop `B`** → 树 `[A]`，present `{A}` → **`B` 的作用域被 prune 丢弃**，`A` 的原样保留；返回 `A` 按保留态渲染。
-- **切 TabView 的 tab** → 其它分支仍在树中 → 其状态保活（与 SwiftUI 让未激活 tab 保持挂载一致）。
-- **跨重载** → `scoped` 随快照序列化；重载后每个仍在树的条目恢复各自作用域，之后 pop 照常丢弃。
-
-`store.scope` 是 store 持有的 `NavigationScopedState` 实例 —— `get` / `set` / `delete` / `keys`，外加框架替你调用的 `prune(presentKeys)`。用高层 `startBrowserApp({ session })` 时无需直接持有 store：`mount` 回调（context）交给你的 `SessionHandle` 上的 `handle.scope` 就是同一个实例（restore 重建后仍指向最新），照样 `handle.scope.get(entryKey)` / `set(entryKey, data)`。
-
-### 扁平 vs 结构化：保留语义**本质就是栈**
-
-「把 `A` 留在 `B` 底下、pop 时丢 `B`、恢复 `A`」这套行为，按定义就是**栈语义** —— 所以它只在**结构化导航**里成立，那里栈 / 树能持有*存在但不可见*的条目。
-
-**扁平单页没有栈**：`A → B` 是整页替换，故 `presentKeys()` 恒为单条目（当前 URL）。一离开某屏，其作用域即被 prune，浏览器**返回**是 fresh 重渲染。
-
-两种模式都支持「当前屏作用域 + 跨重载恢复」。要「返回时保留上一屏」，就把它建成结构化栈 —— 用 push 而非 replace。这正是 `NavigationStack` 的*意义*，不是扁平模式的缺陷。
-
-## 快照
-
-`createSessionStore(options)` 返回 `SessionStore` 编排器。`capture()` 组装快照但不落盘；快照模型为：
-
-```ts
-interface SessionSnapshot {
-    readonly version: number;
-    readonly navigation?: SerializedNavigation | SessionUrlLocation; // 结构化树 | { url }
-    readonly slices: Readonly<Record<string, unknown>>; // provider.key -> capture()
-    readonly scoped: Readonly<Record<string, unknown>>; // entryKey -> 状态袋
-    readonly capturedAt: number; // epoch ms，用于 maxAgeMs 过期判断
-}
-```
-
-`navigation` 用一个轻判别区分：`SerializedNavigation` 始终带 `kind`（leaf/stack/tabs/split），扁平的 `SessionUrlLocation` 带 `url`。用 `isUrlLocation(nav)` 区分二者。
-
-store 暴露：
-
-```ts
-interface SessionStore {
-    register(provider: SessionStateProvider): () => void; // 返回反注册函数
-    readonly scope: NavigationScopedState;
-    capture(): SessionSnapshot; // 组装（nav + slices + scoped），无 I/O
-    persist(snapshot?: SessionSnapshot): void; // 省略则先 capture()，再落盘
-    load(): SessionSnapshot | undefined; // 读取 + 校验（version / maxAge / 结构）
-    restore(snapshot?: SessionSnapshot): void | Promise<void>; // 省略则先 load()，再应用
-    clear(): void; // 清除持久化快照
-    save(): void; // capture + persist —— 手动逃生口
-}
-```
-
-`load()` 会丢弃版本不符、`capturedAt` 超过 `maxAgeMs`、或结构畸形的快照 —— 返回 `undefined`，绝不向应用抛错。`capture()` / `restore()` 抛错的 provider 被隔离：跳过其切片、错误走 `onError`，快照其余部分照常存活。
-
-## 持久化：默认 `sessionStorage`，可替换
-
-快照经稳定 stringify 编码，作为一条 `storage.set(key, ...)` 写入。`Storage` 是 core 既有的依赖接口，所以 durability 由**你**决定：
-
-```ts
-import { createWebStorage } from "@finesoft/front";
-
-createWebStorage("session"); // sessionStorage —— 标签级，关闭即清（默认）
-createWebStorage("local"); // localStorage —— 跨标签、跨重启持久
-```
-
-`createWebStorage` 把 `get`/`set`/`delete` 映射到 `getItem`/`setItem`/`removeItem`，写入时吞掉配额错（会话恢复是尽力而为，绝不打断导航），选定的 Web Storage 不可用时（如隐私模式 `SecurityError`）降级为安全 no-op。
-
-因为它就是 `Storage` 接口，你可以塞**任意**实现 —— 测试用内存版，或服务端同步的 `Storage` 实现跨设备恢复。框架 v1 不内建服务端端点，但接缝是开放的。
-
-## 接入浏览器
-
-向 `startBrowserApp` 传可选的 `session`。存在时，框架构建 `SessionStore`、注册你的 providers、装配 `SessionBridge`（导航变更自动捕获 + `pagehide`/`visibilitychange`），在首次导航后跑 boot 恢复，并把 `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 缺省为 createWebStorage("session")
-        maxAgeMs: 1000 * 60 * 60 * 24, // 丢弃超过一天的快照（可选）
-    },
-    mount(target, { session, app }) {
-        // session: SessionHandle（save/clear/scope/…）；app：统一的 nav+session 句柄。
-        // 自动捕获/恢复已在跑；用 session.save() / session.clear() 作逃生口。
-        // ... 把 UI 挂载到 target，将 app（或 session）传给组件 ...
-        return () => undefined;
-    },
-});
-```
-
-`session` **缺省**时，以上整段不运行，原有 `startBrowserApp` 路径逐位不变。
-
-### 扁平 vs 结构化接线（自动）
-
-`startBrowserApp` 替你挑选导航适配器：
-
-- **有** `navigation` 配置 → 结构化 `createNavigationSessionAdapter(controller)`：序列化整棵树，恢复时 `hydrate` 回去。自动捕获由导航 handle 的 `subscribe` 驱动。
-- **无** `navigation`（扁平单页）→ 接 `framework.perform(makeFlowAction(url))` 的 `createUrlSessionAdapter`：捕获 `{ url }`，恢复时导航过去。
-
-只有自己装配 store 时（如在服务端、或测试里）才需要直接选适配器。
-
-## 句柄：手动 save / clear / dispose
-
-`SessionHandle`（通过 mount context 交付）给你逃生口 —— 自动捕获已在跑，但你可强制落盘、清快照、或整体拆除。统一的 `app` 句柄把导航命令与 session 的 `save`/`clear`/`scope` 合并，组件拿一个对象即可，免自己拼 controller：
-
-```ts
-interface SessionHandle {
-    restore(currentUrl: string): void | Promise<void>; // boot 恢复（已替你调过）
-    save(): void; // 立即强制落盘
-    clear(): void; // 丢弃持久化快照（如登出时）
-    dispose(): void; // 反订阅导航 + 解绑 pagehide/visibilitychange + 清定时器
-}
-```
-
-登出时调 `handle.clear()`，下个用户就不会继承陈旧会话；自己拆除应用实例时调 `handle.dispose()`。
-
-### 何时捕获？
-
-你很少需要调 `save()` —— 捕获是自动的：
-
-- **导航变更时**：bridge **先**把 scoped map prune 到 `adapter.presentKeys()`（这正是「pop `B` 丢掉 `B` 状态」的落点），再**防抖**落盘（默认 `SESSION_DEFAULT_DEBOUNCE_MS` = 500 ms，合并连续导航）。用 `session.debounceMs` 调。
-- **`pagehide` 与 `visibilitychange`（hidden）时**：**立即**落盘并取消挂起的防抖 —— 比 `beforeunload` 在移动端更可靠（标签切后台 / 被回收前能抓到末态）。
-
-## 深链策略：`shouldRestore`
-
-boot 时 bridge 读快照，**仅当** `shouldRestore(snapshot, currentUrl)` 通过才应用 —— 整份 `nav + slices` 恢复共用一个布尔门。默认的 `defaultShouldRestore` 遵循**显式深链优先于陈旧会话**：
-
-| 快照 `navigation`                    | 恢复当且仅当…                                                   |
-| ------------------------------------ | --------------------------------------------------------------- |
-| **扁平**（`SessionUrlLocation`）     | `currentUrl === snapshot.navigation.url` **或**当前路径为根 `/` |
-| **结构化**（`SerializedNavigation`） | 当前路径为根 `/`                                                |
-| **无**（仅切片）                     | 总恢复（与 URL 无关）                                           |
-
-于是重载同页（或全新进入 `/`）会恢复；打开不同深链 `/x` 则**不会**被旧会话覆盖。「根」判定为路径 `=== "/"`（剥离 query/hash）。带 base path 的应用应覆盖该门：
-
-```ts
-session: {
-    providers: [themeSlice],
-    shouldRestore: (snapshot, currentUrl) => currentUrl.startsWith("/app/"),
-}
-```
-
-恢复到与 SSR'd URL 不同的态会产生一次客户端跳变（SSR 渲染 URL 那屏，客户端再恢复）。该时机经 bridge 暴露给你掌控；纯 CSR 应用可在首次绘制前恢复、完全避免它。
-
-## 哪些**不**被捕获
-
-- **你没注册的 DOM。** 框架从不扫描 DOM。状态切片就是你的 provider `capture()` 出来的那些 —— 仅此而已。
-- **不注册任何 provider 时的一切。** 只注册导航（或什么都不注册）时，捕获实质为零 —— 隐私默认。
-- **你排除的敏感字段。** `capture()` 是你的过滤器；token、PII 之类在此剥掉。
-- **陈旧 / 过期 / 畸形的快照。** `load()` 返回 `undefined`，而非为恢复坏态崩掉应用。
-
-## 向后兼容
-
-- 不向 `startBrowserApp` 传 `session` 的应用走**原路径**、零行为变化 —— 整个特性被那一个字段门控。
-- 会话恢复对服务端无任何要求。提供自己的 `Storage` 即可实现服务端同步快照，但框架不内建任何东西。
-- 框架恢复**状态**、绝不恢复 UI。你的 `Page` 模型与渲染方式原封不动。
-
-## 下一步
-
-- [导航](./11-navigation.md) —— 其条目为逐屏状态划定作用域的结构化树
-- [渲染与 Hydration](./04-rendering-and-hydration.md) —— 首屏如何已经通过 prefetch 结果被恢复
-- [DI 容器](./07-di-container.md) —— 会话恢复落盘所经的 `Storage` 依赖
+清理顺序是 `try { await app.dispose(); } finally { nativeRoot.unmount(); }`，Svelte 使用其 `unmount` 函数。另一个实例仍可通过 `other.perform({ kind: "flow", url: "/" })` 工作。协议 v2 使用导航树，旧 URL-only 快照会被判为不兼容；业务切片有独立版本和迁移契约。

package/docs/zh/README.md

@@ -20,14 +20,14 @@
 6. [HTTP 客户端](./06-http-client.md) —— `HttpClient` 子类化、拦截器、`HttpError`
 7. [DI 容器](./07-di-container.md) —— 注册、scope、`DEP_KEYS`、dispose
 8. [可观测性](./08-observability.md) —— `Logger`、`EventRecorder`、Impression 追踪、`ReportCallback`
-9. [服务器与部署](./09-server-and-deployment.md) —— `createServer`、proxy、adapter、Vite 插件
+9. [服务器与部署](./09-server-and-deployment.md) —— HTTP / Node / Worker、proxy、adapter、Vite 插件
 10. [Feature flags、平台、PWA](./10-features-platform-pwa.md) —— 特性开关、平台检测、PWA 模式
 
 ### 已经在维护项目的工程师 —— 直接看实践
 
 横切关注点和约定。先理解基础后再读。
 
-- [项目结构](./engineering/project-structure.md) —— 推荐布局、`bootstrap.ts` 拆分、单一来源
+- [项目结构](./engineering/project-structure.md) —— 推荐布局、`app-definition.ts` 拆分、单一来源
 - [测试](./engineering/testing.md) —— Controller、中间件、scoped DI、mock 框架
 - [CI 与发布流程](./engineering/ci-release-flow.md) —— changesets、内联发布 workflow、版本对账
 
@@ -57,12 +57,12 @@
 ```
 URL/Action → Router.resolve()
           → beforeLoad chain   (NavigationContext: redirect/rewrite/deny/next)
-          → IntentDispatcher   (controller.execute() → Page；出错走 fallback())
+          → RuntimeHandle   (controller.execute() → Page；出错走 fallback())
           → afterLoad chain    (PostLoadContext)
           → render             (SSR: HTML + 序列化的 PrefetchedIntents；CSR: 空壳)
 ```
 
-同一个 `bootstrap()` 同时在服务器和浏览器执行。SSR 把 prefetch 后的 intent 结果序列化进 HTML，浏览器再反序列化为 `PrefetchedIntents`，让首次客户端导航复用服务端结果而不重新发请求。
+服务器和浏览器使用同一应用声明。SSR 把 prefetch 后的 intent 结果序列化进 HTML，浏览器再反序列化为 `PrefetchedIntents`，让首次客户端导航复用服务端结果而不重新发请求。
 
 ## 约定
 

package/docs/zh/advanced/custom-action-handler.md

@@ -1,248 +1,48 @@
-# 高阶：自定义 Action handler
+# 应用 Action
 
-框架内置三种 action：`flow`（应用内导航）、`external-url`（整页浏览器跳转）、`compound`（按顺序执行的 action 元组）。对大多数应用够用。
+WebSession 本身就是 ActionDispatcher 和导航状态所有者。原生页面、链接拦截、自定义处理器共用 `app.perform(action)`。Action 同时表达 URL 路由和 Stack、Tab、Split 结构化导航，不再有另一套导航命令对象。
 
-本配方展示怎么加自己的 —— 适用于有一类操作需要横切处理（分析、确认、遥测）又不想污染每个调用点。
+`FlowAction` 加载 URL。普通应用未显式声明导航树或 codec 时，离开的页面会卸载；结构化应用保留树中分支。同址 URL 刷新原条目，显式 `push` 则创建新条目，相同目标也有独立草稿。
 
-## 用例：带确认的 action
+`perform` 等待守卫、数据加载、提交及原生视图确认完成，返回导航快照。结构化动作被拒绝时返回带 `rejection` 的未提交快照。Compound 按顺序执行，遇到拒绝或失败即停止后续动作。第二个参数 `{ signal }` 可将取消传入页面加载。
 
-加 `"confirm"` action kind：dispatch `{ kind: "confirm", message, then }`，框架在 dispatch `then` 之前（`then` 本身也是个 action）显示确认对话框。
+`app.onAction(kind, handler)` 与 `app.removeAction(kind)` 在同一执行器上注册或显式替换处理器。业务数据操作继续调用 `app.runtime.execute`。ExternalUrlAction 使用 `noopener,noreferrer` 打开新窗口；`{ kind: "reuseEntry", entryId }` 恢复保留实例，无须额外携带 URL。
 
-```ts
-dispatch({
-    kind: "confirm",
-    message: "Delete this item permanently?",
-    then: { kind: "flow", url: "/items/42/deleted" },
-});
-```
-
-用户点 Cancel → 不导航。点 OK → 内层 flow action 触发。
-
-## 步骤 1：定义 action 类型
-
-```ts
-// src/lib/actions/confirm.ts
-import { type Action } from "@finesoft/front";
-
-export interface ConfirmAction {
-    kind: "confirm";
-    message: string;
-    then: Action;
-}
-
-export function makeConfirmAction(message: string, then: Action): ConfirmAction {
-    return { kind: "confirm", message, then };
-}
-
-export function isConfirmAction(action: Action): action is ConfirmAction {
-    return (action as any).kind === "confirm";
-}
-```
-
-形状你定 —— `kind` 只要在已注册 handler 中唯一即可。
-
-## 步骤 2：扩展 `Action` 类型 union
-
-TypeScript 不会自动扩展框架的 `Action` 类型。声明模块增强：
-
-```ts
-// src/lib/actions/confirm.ts
-declare module "@finesoft/front" {
-    interface ActionRegistry {
-        confirm: ConfirmAction;
-    }
-}
-```
-
-框架暴露 `ActionRegistry` 的话（大多数可插拔框架会），TypeScript 就知道你的新 kind。没暴露的话，注册时 cast：
-
-```ts
-framework.actionDispatcher.register("confirm" as any, handleConfirm as any);
-```
-
-运行时不在乎 —— `kind` dispatch 时就是普通字符串。
-
-## 步骤 3：写 handler
-
-```ts
-// src/lib/actions/confirm.ts
-import type { Framework } from "@finesoft/front";
-
-export function registerConfirmHandler(framework: Framework): void {
-    framework.actionDispatcher.register("confirm", async (action: ConfirmAction) => {
-        if (typeof window === "undefined") {
-            // SSR：没法弹确认 —— 直接 dispatch 内层 action
-            await framework.actionDispatcher.dispatch(action.then);
-            return;
-        }
-
-        const confirmed = window.confirm(action.message);
-        if (!confirmed) return;
-
-        await framework.actionDispatcher.dispatch(action.then);
-    });
-}
-```
-
-要点：
-
-- handler 服务端和客户端都跑。服务端没有 `window` —— 决定「没 UI」对你的 action 意味着什么。
-- 递归 dispatch（`actionDispatcher.dispatch(action.then)`）走普通管线，包含任何其他自定义 handler。
-- 框架已经用递归深度限制（默认 4）保护 compound action。你的 handler 通过 dispatch 到达，继承了这个限制。
-
-## 步骤 4：应用启动时注册
-
-```ts
-// src/main.ts
-import { startBrowserApp } from "@finesoft/front/browser";
-import { bootstrap } from "./bootstrap";
-import { registerConfirmHandler } from "./lib/actions/confirm";
-
-startBrowserApp({
-    bootstrap,
-    onBeforeStart(framework) {
-        registerConfirmHandler(framework);
-    },
-    mount: /* ... */,
-});
-```
-
-SSR 端镜像一份：
+处理器接收 `(action, invocation)`。委托其他动作时，将同一个 invocation 传给 `app.perform(nextAction, invocation)`，使整个执行序列共用取消边界。新的 URL 导航取消旧动作组；结构化动作仍顺序执行，并阻止尚未完成解析的旧 URL 覆盖它。模态和外链动作不替换背景导航。
 
-```ts
-// src/ssr.ts
-export const render = createSSRRender({
-    bootstrap,
-    onBeforeStart(framework) {
-        registerConfirmHandler(framework);
-    },
-    async renderApp(page) {
-        /* ... */
-    },
-});
-```
-
-或者更简单：在 `bootstrap()` 内注册，两端都自动拿到。
-
-## 步骤 5：使用
-
-```ts
-// 在 view 组件里
-import { makeConfirmAction, makeFlowAction } from "@finesoft/front";
-
-function onDelete(id: string) {
-    framework.actionDispatcher.dispatch(
-        makeConfirmAction(`Delete item ${id}?`, makeFlowAction(`/items/${id}/deleted`)),
-    );
-}
-```
-
-## 替换已有 handler
-
-每个 `kind` 只能注册一次。dispatcher 对重复注册打 warning 并跳过：
-
-```ts
-framework.actionDispatcher.register("flow", myFlowHandler);
-// [ActionDispatcher] kind="flow" already registered, skipping
-```
-
-要替换先 unregister：
-
-```ts
-framework.actionDispatcher.removeAction("flow");
-framework.actionDispatcher.register("flow", myFlowHandler);
-```
-
-适用于想用日志或分析包默认 flow handler：
+浏览器导航与守卫重定向接受 HTTP(S)，ExternalUrlAction 还接受 `mailto:`、`tel:`。无效 URL 和可执行或不支持的协议在浏览器跳转前拒绝；需要自定义协议时可以显式替换处理器。
 
-```ts
-import { registerFlowActionHandler, type FlowActionDependencies } from "@finesoft/front";
-
-const baseHandler = framework.actionDispatcher.getHandler("flow"); // 假设暴露
-framework.actionDispatcher.removeAction("flow");
-framework.actionDispatcher.register("flow", async (action) => {
-    console.log("[nav]", action.url);
-    await baseHandler(action);
-});
-```
-
-实践中，导航的横切关注点优先用中间件（`beforeLoad`）—— 替换 flow handler 太侵入。
-
-## 自定义 kind 的 compound action
-
-`CompoundAction` 配任何已注册 kind 都行：
+## 两种导航
 
 ```ts
-framework.actionDispatcher.dispatch({
-    kind: "compound",
-    actions: [
-        makeFlowAction("/checkout/complete"),
-        makeConfirmAction("Add to email list?", { kind: "subscribe", email: user.email }),
-    ],
-});
+await app.perform({ kind: "flow", url: "/items/42" });
+await app.perform({ kind: "push", intent: "item", params: { id: 42 } });
+await app.perform({ kind: "selectTab", key: "favorites" });
+await app.perform({ kind: "pop" });
+await app.perform({ kind: "refresh" });
 ```
 
-每个内层 action 顺序跑。一个 handler 抛错短路 compound 剩余 action —— 想要 best-effort 语义就 `try/catch` 包起来。
-
-## 服务端考虑
+## 现有代码迁移
 
-Controller dispatch action 时 action handler 在 SSR 期间在服务端跑。常见模式：
+| 旧 API                                               | 替换方式                                                                                                           |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `app.navigation.navigate(url)`                       | `app.perform({ kind: "flow", url })`                                                                               |
+| `app.navigation.push(intent, params)`                | `app.perform({ kind: "push", intent, params })`                                                                    |
+| `controller.apply(operation)`                        | `controller.perform(action)`，保留原有结构化字段                                                                   |
+| 首次 `controller.resolve()`                          | `controller.start()`                                                                                               |
+| `app.actionDispatcher.onAction/removeAction`         | `app.onAction/removeAction`                                                                                        |
+| `FlowAction.entryId`                                 | `{ kind: "reuseEntry", entryId }`                                                                                  |
+| `NavigationHandle`、`SessionHandle`、`SessionAccess` | History 清理使用 `NavigationBridge`；持久化使用 `SessionStore`；浏览器启动恢复使用 `BrowserSession.restoreFromUrl` |
 
-- **外部 URL**：服务端没法让用户导航 —— 大多数应用提前返回。框架内置 `external-url` handler 在 SSR 上正是这样做的。
-- **Confirm 类**：没用户能问。要么自动接受（用内层 action）要么自动拒绝（丢弃）。
-- **仅遥测**：两端工作一样。记录就行。
+旧导航命令与转发方法已删除，其余树操作使用同名 Action kind。不可变树构建纯函数继续保留。
 
-handler 依赖服务端没有的浏览器 API，用 `typeof window === "undefined"` 守卫。
+## 模态展示
 
-## 测试
+创建浏览器应用时提供 `onModal(page, { app, snapshot })`，然后调用：
 
 ```ts
-import { afterEach, describe, expect, test, vi } from "vite-plus/test";
-import { Framework } from "@finesoft/front";
-import { registerConfirmHandler, makeConfirmAction } from "./confirm";
-
-describe("confirm action", () => {
-    afterEach(() => vi.restoreAllMocks());
-
-    test("dispatches inner action when confirmed", async () => {
-        const framework = Framework.create({});
-        registerConfirmHandler(framework);
-        vi.stubGlobal("window", { confirm: () => true });
-
-        const innerHandler = vi.fn();
-        framework.actionDispatcher.register("test", innerHandler);
-
-        await framework.actionDispatcher.dispatch(
-            makeConfirmAction("ok?", { kind: "test" } as any),
-        );
-
-        expect(innerHandler).toHaveBeenCalled();
-    });
-
-    test("skips inner action when cancelled", async () => {
-        const framework = Framework.create({});
-        registerConfirmHandler(framework);
-        vi.stubGlobal("window", { confirm: () => false });
-
-        const innerHandler = vi.fn();
-        framework.actionDispatcher.register("test", innerHandler);
-
-        await framework.actionDispatcher.dispatch(
-            makeConfirmAction("ok?", { kind: "test" } as any),
-        );
-
-        expect(innerHandler).not.toHaveBeenCalled();
-    });
-});
+import { makeFlowAction } from "@finesoft/front";
+await app.perform(makeFlowAction("/items/42", "modal"));
 ```
 
-## 自定义 action vs 中间件 怎么选
-
-| 关注点                          | 自定义 action | 中间件（`beforeLoad`） |
-| ------------------------------- | ------------- | ---------------------- |
-| 导航到特定 URL 前确认           | ✅            | ❌（每个导航都跑）     |
-| 每次导航的审计日志              | ❌            | ✅                     |
-| 引入新的操作机制                | ✅            | ❌                     |
-| 把守所有导航到 admin 路由的访问 | ❌            | ✅                     |
-
-自定义 action 是**新种类的操作**。中间件是**已有操作的横切关注点**。
+宿主先运行导航策略和页面守卫，再调用一次 `onModal`，由业务原生 UI 呈现；背景导航与历史不变。拒绝只交付错误页和已清理快照，不交付被拒绝数据。内部重定向仍处于模态会话，外部重定向直接跳转且不交付模态。使用前须配置 `onModal`；SSR 视图不能执行浏览器动作。