@finesoft/front 0.3.0 → 0.4.1

package/dist/{server-data-HVSgxEac.d.mts → browser-DMw76sEo.d.mts}

@@ -1274,6 +1274,25 @@ declare function isStackNode(node: NavigationNode): node is StackNode;
 declare function isTabsNode(node: NavigationNode): node is TabsNode;
 declare function isSplitNode(node: NavigationNode): node is SplitNode;
 //#endregion
+//#region ../core/src/navigation/islands.d.ts
+/** 交给挂载/渲染原语的单条目解析结果。 */
+interface ResolvedEntry {
+  readonly intent: string;
+  readonly params: RouteParams;
+  readonly entryKey: string;
+  readonly page: BasePage;
+  /**
+   * SSR 水合提示：true = 该条目的容器已含服务端渲染标记，挂载原语应**水合**（如 Vue
+   * `createSSRApp().mount()`）而非新建（`createApp().mount()`）。缺省 false（新建）。
+   */
+  readonly hydrate?: boolean;
+}
+/**
+ * island 容器的标记属性 —— 客户端 orchestrator 与服务端 helper 的单一来源。
+ * `data-fs-entry`（标识容器）、`data-fs-intent`、`data-fs-key`（水合按它匹配）。
+ */
+declare function islandContainerAttributes(intent: string, entryKey: string): Record<string, string>;
+//#endregion
 //#region ../core/src/navigation/operations.d.ts
 /**
  * 解析「激活路径」：从根沿可见分支一路向下，直到叶子或无法继续。
@@ -1301,6 +1320,12 @@ declare function findNearestStack(tree: NavigationNode, path: NavigationPath): N
  * - split → 每个有内容的列的可见目标，按列序拼接
  */
 declare function collectVisibleDestinations(tree: NavigationNode): readonly LeafNode[];
+/**
+ * 收集树中**全部存在**的叶子（含不可见：栈非顶 entry、未激活 tab 分支、所有非空 split 列）。
+ * 区别于 `collectVisibleDestinations`（只沿可见分支）—— 保活 / 缓存 prune / 作用域保留需要
+ * 全部 present 条目。顺序：栈按序、tabs 按 `Object.values(branches)` 序、split 按列序。
+ */
+declare function collectAllLeaves(tree: NavigationNode): readonly LeafNode[];
 /**
  * 按 `visibility` 求出一个 split 节点当前**可见**的列（不裁剪空内容列——空 content 由调用方处理）。
  *
@@ -1427,6 +1452,17 @@ interface FullStateCodecOptions {
  * - `decode`：读取保留参数无损还原整棵树；缺失该参数时返回 `undefined`（交由调用方走默认路径）。
  */
 declare function createFullStateCodec(options?: FullStateCodecOptions): NavigationCodec;
+/**
+ * 扁平栈 codec —— flat-islands 用：URL ↔ 单叶栈。
+ *
+ * - `decode(url, router)`：同步把 URL 匹配成单叶意图，返回 `stack([leaf(intent, params)])`；
+ *   不可路由时返回 `undefined`（调用方保留当前树，与 createActiveLeafCodec 约定一致）。
+ * - `encode(tree, router)`：取激活叶子（activeLeaf）的 intent + params 反查 URL；
+ *   无对应路由时回退 `"/"`。
+ *
+ * 全部复用本模块已有 helper：`parseRouteSummaries`、`parseUrlParts`、`reverseUrl`、`activeLeaf`。
+ */
+declare function createFlatStackCodec(): NavigationCodec;
 //#endregion
 //#region ../core/src/navigation/controller.d.ts
 /** 导航操作 Kind 常量 */
@@ -1590,6 +1626,13 @@ interface NavigationController {
   setVisibility(visibility: SplitVisibility, target?: NavigationPath): Promise<NavigationSnapshot>;
   /** 用外部树替换当前树并重解析（history/URL 还原）。 */
   hydrate(tree: NavigationNode): Promise<NavigationSnapshot>;
+  /**
+   * 清除页面缓存：给 `entryKey`（= `sessionEntryKey(intent, params)`）清单个，
+   * 不传清全部。仅清缓存、不触发重解析——该条目下次被解析时重新 dispatch。
+   */
+  invalidate(entryKey?: string): void;
+  /** 清当前激活叶子的缓存并重解析当前树（「下拉刷新」式：守卫跑、数据重 fetch）。 */
+  refresh(): Promise<NavigationSnapshot>;
   /** 订阅快照变更；返回取消订阅函数。 */
   subscribe(listener: (snapshot: NavigationSnapshot) => void): () => void;
   /** 解析当前树（首屏 SSR/CSR），提交并返回快照。 */
@@ -1779,6 +1822,218 @@ interface DefineRoutesOptions {
  */
 declare function defineRoutes(framework: Framework, definitions: RouteDefinition[], options?: DefineRoutesOptions): void;
 //#endregion
+//#region ../core/src/session/types.d.ts
+/** 会话快照在 Storage 中的默认键。 */
+declare const SESSION_DEFAULT_KEY = "__finesoft_session__";
+/** 会话快照的默认版本号；解码时不匹配即整份丢弃。 */
+declare const SESSION_DEFAULT_VERSION = 1;
+/** 扁平单页的导航位置：一个 URL（区别于结构化树的 `SerializedNavigation`）。 */
+interface SessionUrlLocation {
+  readonly url: string;
+}
+/**
+ * 会话快照：用户「当时在干什么」的可序列化捕获。
+ *
+ * `navigation` 用一个轻判别区分两种导航形态：`SerializedNavigation` 自带 `kind`
+ * （leaf/stack/tabs/split），`SessionUrlLocation` 用独有的 `url` 字段（见 `isUrlLocation`）。
+ */
+interface SessionSnapshot {
+  /** 快照版本；解码时与期望版本不符即丢弃。 */
+  readonly version: number;
+  /** 导航位置：结构化 → `SerializedNavigation`；扁平 → `SessionUrlLocation`；缺省 → 不恢复导航。 */
+  readonly navigation?: SerializedNavigation | SessionUrlLocation;
+  /**
+   * 该快照导航位置的可比 URL（捕获时刻与 history 同步的浏览器 URL），供恢复门控做精确匹配。
+   *
+   * 扁平与结构化适配器均可在 `capture` 时记录（见 `SessionNavigationAdapter.captureUrl`）。
+   * 缺省时（旧快照 / 适配器不提供）门控回退到旧策略：扁平比 `nav.url`、结构化只在根放行。
+   * 它让结构化导航也能像扁平一样「重载同深链即恢复、改去别的深链则跳过」（对称）。
+   */
+  readonly url?: string;
+  /** 全局切片（app-wide）：`provider.key` → 该 provider `capture()` 的 JSON 值。 */
+  readonly slices: Readonly<Record<string, unknown>>;
+  /** 导航作用域状态：`entryKey` → 该导航条目的状态袋；条目离树即被 prune 丢弃。 */
+  readonly scoped: Readonly<Record<string, unknown>>;
+  /** 捕获时刻（epoch ms）；用于 `maxAgeMs` 过期判断。 */
+  readonly capturedAt: number;
+}
+/**
+ * 判别 `navigation` 是否为扁平 URL 位置。
+ *
+ * `SerializedNavigation` 始终带 `kind`、从不带 `url` 字段，故 `url` 是无歧义判别位。
+ */
+declare function isUrlLocation(nav: SessionSnapshot["navigation"]): nav is SessionUrlLocation;
+/**
+ * 全局状态切片 Provider。
+ *
+ * 同步、JSON 安全。框架不解释切片内容 —— 它只搬运。应用控制捕获什么
+ * （敏感字段在 `capture()` 中自行排除）。
+ */
+interface SessionStateProvider<T = unknown> {
+  /** 切片唯一键（快照里 `slices` 的 key）。 */
+  readonly key: string;
+  /** 捕获当前切片状态，必须返回 JSON 安全的同步值。 */
+  capture(): T;
+  /** 用持久化的切片数据恢复（应用自行 setState / 填表单 / 滚动）。 */
+  restore(data: T): void;
+}
+/**
+ * 导航作用域状态：`entryKey` → 状态袋；条目离树由框架 prune 丢弃（见 `scoped-state.ts`）。
+ */
+interface NavigationScopedState {
+  /** 读取某条目的状态袋（不存在返回 `undefined`，`unknown` 已含此情形）。 */
+  get(entryKey: string): unknown;
+  /** 写入某条目的状态袋。 */
+  set(entryKey: string, data: unknown): void;
+  /** 删除某条目的状态袋。 */
+  delete(entryKey: string): void;
+  /** 仅保留 `presentKeys` 中的键，丢弃其余（导航提交后由 bridge 调用）。 */
+  prune(presentKeys: Iterable<string>): void;
+  /** 当前持有状态的全部条目键。 */
+  keys(): readonly string[];
+}
+/**
+ * 导航适配器：SessionStore 与具体导航机制（结构化 controller / 扁平 URL）解耦的接缝。
+ *
+ * SessionStore 不直接依赖 `NavigationController`，core 不产生 nav → session 的反向耦合；
+ * 扁平与结构化导航经此同一套机制覆盖（见 `navigation-adapter.ts`）。
+ */
+interface SessionNavigationAdapter {
+  /** 捕获当前导航位置。 */
+  capture(): SessionSnapshot["navigation"] | undefined;
+  /** 应用恢复的导航位置。 */
+  apply(navigation: SessionSnapshot["navigation"]): void | Promise<void>;
+  /**
+   * 可选：计算当前导航位置的可比 URL，写入 `SessionSnapshot.url` 供恢复门控精确匹配。
+   *
+   * 浏览器侧适配器返回当时的 `location`（pushState 后与导航树同步）；返回 `undefined`
+   * 或不实现 = 快照不带 `url`，门控回退旧策略（见 `defaultShouldRestore`）。
+   */
+  captureUrl?(): string | undefined;
+  /** 树中**存在**的全部条目身份键（用于 scoped prune；「存在」非「可见」）。 */
+  presentKeys(): Iterable<string>;
+}
+/** 会话错误上下文：标记出错所处阶段，供 `onError` 上报。 */
+interface SessionErrorContext {
+  readonly phase: "capture" | "restore" | "persist" | "load";
+  readonly key?: string;
+}
+/** `createSessionStore` 选项。 */
+interface SessionStoreOptions {
+  /** 持久化存储（`DEP_KEYS.STORAGE`）。 */
+  readonly storage: Storage;
+  /** 快照键；默认 `SESSION_DEFAULT_KEY`。 */
+  readonly key?: string;
+  /** 快照版本；默认 `SESSION_DEFAULT_VERSION`，不符即丢弃。 */
+  readonly version?: number;
+  /** 快照最大存活时长（ms）；省略 = 不过期。 */
+  readonly maxAgeMs?: number;
+  /** 导航适配器；省略 = 不恢复导航。 */
+  readonly navigation?: SessionNavigationAdapter;
+  /** 注入时钟（测试 / SSR 安全）；默认 `() => Date.now()`。 */
+  readonly now?: () => number;
+  /** 错误回调；默认 no-op，应用可接 EventRecorder。 */
+  readonly onError?: (error: unknown, ctx: SessionErrorContext) => void;
+}
+/** 会话编排器：组装 / 落盘 / 读取 / 恢复快照，并持有导航作用域状态。 */
+interface SessionStore {
+  /** 注册全局切片 provider；返回反注册函数。 */
+  register(provider: SessionStateProvider): () => void;
+  /** 导航作用域状态读写 + prune。 */
+  readonly scope: NavigationScopedState;
+  /** 组装当前快照（nav + slices + scoped），不落盘。 */
+  capture(): SessionSnapshot;
+  /** 落盘（省略参数则先 `capture`）。 */
+  persist(snapshot?: SessionSnapshot): void;
+  /** 从 Storage 读取并校验（version / maxAge / 畸形 → `undefined`）。 */
+  load(): SessionSnapshot | undefined;
+  /** 恢复：应用 nav + 回填 scoped + 派发各 slice 给对应 provider（省略则先 `load`）。 */
+  restore(snapshot?: SessionSnapshot): void | Promise<void>;
+  /** 清除持久化快照。 */
+  clear(): void;
+  /** 手动逃生口 = `capture` + `persist`。 */
+  save(): void;
+}
+/** 会话错误：序列化 / 编排过程中需要显式标识的错误类型。 */
+declare class SessionError extends Error {
+  constructor(message: string);
+}
+//#endregion
+//#region ../core/src/session/snapshot.d.ts
+/** 把快照编码为确定性字符串（keys 排序），用作 `storage.set` 的值。 */
+declare function encodeSnapshot(snapshot: SessionSnapshot): string;
+/**
+ * 解码并校验快照。
+ *
+ * 校验：`version === expectedVersion`、`slices`/`scoped` 为对象、`capturedAt` 为数值；
+ * `navigation` 可缺省。任一不符或解析失败 → `undefined`（永不抛）。
+ */
+declare function decodeSnapshot(raw: string | undefined, expectedVersion: number): SessionSnapshot | undefined;
+//#endregion
+//#region ../core/src/session/scoped-state.d.ts
+/**
+ * 导航条目身份键：`intent + " " + stableStringify(params)`。
+ *
+ * 与 controller 的目标键同源、跨重载稳定（`stableStringify` 对 params 键排序，
+ * 故 `{a,b}` 与 `{b,a}` 产出同一键）。
+ */
+declare function sessionEntryKey(intent: string, params: RouteParams): string;
+/**
+ * 收集导航树中**全部 leaf** 的身份键（含不可见 / 未激活分支 / 各 split 列）。
+ * 委派给 `collectAllLeaves`（同一「全部存在」遍历），映射成 entryKey。
+ * 「全部存在」而非「可见」，用于 scoped 状态保留。
+ */
+declare function collectLeafKeys(tree: NavigationNode): string[];
+/**
+ * 创建导航作用域状态容器。
+ *
+ * 内部持一个 `Map`；`prune` 由 `presentKeys` 构造 `Set`，删除不在其中的全部键。
+ * `initial` 在构造时浅拷贝进 `Map`，构造后改动源对象不会泄漏进容器。
+ */
+declare function createNavigationScopedState(initial?: Record<string, unknown>): NavigationScopedState;
+//#endregion
+//#region ../core/src/session/session-store.d.ts
+/**
+ * 创建会话编排器。
+ *
+ * `scope` 是一个 `createNavigationScopedState()` 实例，由 store 持有；`restore` 用快照
+ * 的 `scoped` 重建其内容。时钟 `now` 注入（默认 `() => Date.now()`），`capturedAt` 由它产出。
+ */
+declare function createSessionStore(options: SessionStoreOptions): SessionStore;
+//#endregion
+//#region ../core/src/session/navigation-adapter.d.ts
+/**
+ * 结构化导航适配器：把 `NavigationController` 接到会话编排器。
+ *
+ * `apply` 仅处理 `SerializedNavigation`；`SessionUrlLocation` 与 `undefined` 一律 no-op
+ * （结构化应用始终捕获一棵树，不会落到 URL 形态）。
+ *
+ * `currentUrl`（可选）：捕获时刻读取的浏览器 URL（pushState 后与导航树同步），写入快照
+ * `url` 字段供恢复门控精确匹配 —— 让结构化导航也能像扁平一样「重载同深链即恢复、改去别的
+ * 深链则跳过」。省略时快照不带 `url`，门控回退到「只在根放行」的旧策略。
+ */
+declare function createNavigationSessionAdapter(controller: NavigationController, currentUrl?: () => string): SessionNavigationAdapter;
+/** `createUrlSessionAdapter` 选项（扁平单页）。 */
+interface UrlAdapterOptions {
+  /** 读取当前 URL（如 `() => location.pathname + location.search`）。 */
+  readonly currentUrl: () => string;
+  /** 应用恢复的 URL（应用提供，如 `framework.perform(makeFlowAction(url))`）。 */
+  readonly navigate: (url: string) => void | Promise<void>;
+  /** 可选：当前屏的 intent + params，用于 `presentKeys` 产出稳定身份键。 */
+  readonly currentIntent?: () => {
+    intent: string;
+    params: RouteParams;
+  };
+}
+/**
+ * 扁平 URL 适配器：把单页 URL 接到会话编排器。
+ *
+ * `apply` 仅处理 `SessionUrlLocation`；`SerializedNavigation` 与 `undefined` 一律 no-op
+ * （扁平只认 URL 形态）。`presentKeys` 恒为单条目：有 `currentIntent` 时用
+ * `sessionEntryKey(intent, params)`，否则退化为当前 URL 字符串。
+ */
+declare function createUrlSessionAdapter(opts: UrlAdapterOptions): SessionNavigationAdapter;
+//#endregion
 //#region ../core/src/utils/lru-map.d.ts
 /**
  * LruMap — 固定容量的 LRU 缓存
@@ -2053,6 +2308,12 @@ interface FlowActionDependencies {
    * 仍负责 dispatch + updateApp（初始渲染 / redirect / modal），只是不碰 history。
    */
   manageHistory?: boolean;
+  /**
+   * flat-islands 正向导航钩子（可选）。提供后，正向 FlowAction（非 modal）会调用此函数
+   * 并 return，**绕过** navigateTo / updateApp。由 activateFlatIslands 注入，把 URL
+   * 路由到隐式单栈 `NavigationController.push`。未提供时行为与今天扁平路径字节级相同。
+   */
+  onForward?: (url: string) => void | Promise<void>;
 }
 declare function registerFlowActionHandler(deps: FlowActionDependencies): void;
 //#endregion
@@ -2069,6 +2330,8 @@ interface ActionHandlerDependencies {
   getScrollablePageElement?: () => HTMLElement | null;
   /** 是否由 FlowAction handler 管理 history；结构化导航下传 `false`（见 registerFlowActionHandler）。 */
   manageHistory?: boolean;
+  /** flat-islands 正向导航钩子（透传给 registerFlowActionHandler）。 */
+  onForward?: (url: string) => void | Promise<void>;
 }
 declare function registerActionHandlers(deps: ActionHandlerDependencies): void;
 //#endregion
@@ -2123,6 +2386,108 @@ interface NavigationHandle {
  */
 declare function createNavigationBridge(deps: NavigationBridgeDependencies): NavigationHandle;
 //#endregion
+//#region ../browser/src/session-bridge.d.ts
+/** 导航变更后自动落盘的默认防抖窗口（ms）：合并连续导航，避免每跳一屏写一次。 */
+declare const SESSION_DEFAULT_DEBOUNCE_MS = 500;
+/** `createSessionBridge` 选项。 */
+interface SessionBridgeOptions {
+  /** 会话编排器（core）。 */
+  readonly store: SessionStore;
+  /** 导航适配器；导航变更时用其 `presentKeys()` 驱动 scoped prune。 */
+  readonly adapter: SessionNavigationAdapter;
+  /** 订阅导航变更；返回反订阅函数。省略 = 不自动捕获（仅靠生命周期事件 + 手动 `save`）。 */
+  readonly subscribeNavigation?: (onChange: () => void) => () => void;
+  /** 自动落盘防抖窗口（ms）；默认 `SESSION_DEFAULT_DEBOUNCE_MS`。 */
+  readonly debounceMs?: number;
+  /** 恢复门控；默认 `defaultShouldRestore`（显式深链优先，见其文档）。 */
+  readonly shouldRestore?: (snapshot: SessionSnapshot, currentUrl: string) => boolean;
+}
+/** SessionBridge 对外句柄：导航作用域读写 + boot 恢复 + 手动逃生口 + 解绑。 */
+interface SessionHandle {
+  /**
+   * 导航作用域状态（每屏 per-entry）。应用渲染某屏时用 `scope.get(entryKey)` /
+   * `set(entryKey, data)` 读写（`entryKey = sessionEntryKey(intent, params)`）。
+   * 始终委托当前 store 的 scope —— restore 会重建 scope map，经此 getter 取到的恒是最新实例。
+   */
+  readonly scope: NavigationScopedState;
+  /** boot 时调用：读快照，通过门控则整体恢复（nav + slices + scoped）。 */
+  restore(currentUrl: string): void | Promise<void>;
+  /** 手动落盘（= `store.save()`）。 */
+  save(): void;
+  /** 清除持久化快照（= `store.clear()`）。 */
+  clear(): void;
+  /** 反订阅导航 + 解绑全部监听 + 清挂起定时器（幂等）。 */
+  dispose(): void;
+}
+/**
+ * 默认恢复门控策略（精确、无歧义，遵循「显式深链优先」）。
+ *
+ * - **带可比 URL**（快照含 `url` —— 扁平天然有，结构化由适配器在 capture 时记录浏览器
+ *   `location`）：当且仅当 `currentUrl` 全等 `snapshot.url`，**或** `currentUrl` 路径为根 `/`
+ *   （重载同深链 / 全新进入 → 恢复；改去别的深链 → 跳过，显式深链不被旧会话覆盖）。
+ *   这让结构化导航与扁平**对称**：重载 `/item/1` 即恢复其作用域状态。
+ * - **回退（无 `url`）**：旧快照 / 适配器不提供 URL 时 —— 扁平比 `nav.url`，结构化只在根 `/`
+ *   放行（树无单一可比 URL，门设在「入口」；要更细由应用覆盖 predicate）。
+ * - **无 `navigation`**（仅切片）：总恢复（与 URL 无关）。
+ *
+ * 「根」判定为路径 `=== "/"`（剥离 query/hash）；带 base path 的应用应覆盖 `shouldRestore`。
+ */
+declare function defaultShouldRestore(snapshot: SessionSnapshot, currentUrl: string): boolean;
+/**
+ * 创建 SessionBridge：订阅导航、装配生命周期监听、返回会话句柄。
+ *
+ * 调用后 bridge 已激活（已订阅导航 + 已注册 `pagehide` / `visibilitychange`）。应用应在
+ * 首次导航完成后调一次 `restore(initialUrl)` 完成 boot 恢复。
+ */
+declare function createSessionBridge(options: SessionBridgeOptions): SessionHandle;
+//#endregion
+//#region ../browser/src/app-handle.d.ts
+/** 统一 app 句柄。两个子系统都配齐时成员完整;只配其一则仅含该子系统成员(另一组运行期缺席)。 */
+interface AppHandle {
+  getSnapshot: NavigationHandle["getSnapshot"];
+  subscribe: NavigationHandle["subscribe"];
+  push: NavigationHandle["push"];
+  pop: NavigationHandle["pop"];
+  popToRoot: NavigationHandle["popToRoot"];
+  replaceTop: NavigationHandle["replaceTop"];
+  selectTab: NavigationHandle["selectTab"];
+  selectColumn: NavigationHandle["selectColumn"];
+  save: SessionHandle["save"];
+  clear: SessionHandle["clear"];
+  readonly scope: SessionHandle["scope"];
+}
+/**
+ * 构建统一 app 句柄。`navigation`/`session` 任一缺省则其成员不并入。
+ * 至少应有一个非空(调用方在配了 navigation 和/或 session 时才构建)。
+ */
+declare function createAppHandle(navigation: NavigationHandle | undefined, session: SessionHandle | undefined): AppHandle;
+//#endregion
+//#region ../browser/src/navigation-islands.d.ts
+/** `mountEntry` 返回的 island 句柄。 */
+interface IslandHandle {
+  /** 销毁该 island 实例（应用用 app.unmount() / root.unmount() / comp.$destroy() 实现）。 */
+  unmount(): void;
+}
+/** 通用挂载原语：把一个条目的视图挂进 container，返回卸载句柄。 */
+type MountEntry = (entry: ResolvedEntry, container: HTMLElement) => IslandHandle;
+/** `createIslandOrchestrator` 选项。 */
+interface IslandOrchestratorOptions {
+  /** 框架在其内构建/挂载 island 容器的 outlet 元素（应用渲染、稳定、空）。 */
+  readonly outlet: HTMLElement;
+  /** 应用提供的挂载原语。 */
+  readonly mountEntry: MountEntry;
+  /** 重放调度（默认 requestAnimationFrame；测试可注入同步执行）。 */
+  readonly schedule?: (cb: () => void) => void;
+}
+/** 编排器对外接口。 */
+interface IslandOrchestrator {
+  /** 把 DOM 同步到一个导航快照（挂新/卸离树/detach 隐藏/attach 可见）。 */
+  sync(snapshot: NavigationSnapshot): void;
+  /** 卸载全部 island、清空 outlet。 */
+  dispose(): void;
+}
+declare function createIslandOrchestrator(options: IslandOrchestratorOptions): IslandOrchestrator;
+//#endregion
 //#region ../browser/src/start-app.d.ts
 /**
  * 结构化导航定义 —— 由应用通过 `defineNavigation(...)` 或手写提供。
@@ -2132,7 +2497,7 @@ declare function createNavigationBridge(deps: NavigationBridgeDependencies): Nav
  * - 用 `initial` 树构建 `NavigationController`（守卫上下文走 `createBrowserContext`，
  *   预取缓存复用 `framework.prefetchedIntents`）；
  * - 装配 `NavigationBridge`（snapshot → history/URL，popstate → hydrate）；
- * - 解析首屏树（一次 `resolve()`），通过 `onNavigationReady` 把 handle 交给应用。
+ * - 解析首屏树（一次 `resolve()`），通过 mount context 把 handle 交给应用。
  */
 interface BrowserNavigationConfig {
   /** 初始导航树（单 LeafNode = 今天的扁平单页）。 */
@@ -2145,6 +2510,36 @@ interface BrowserNavigationConfig {
   readonly afterLoad?: readonly AfterLoadGuard[];
   /** dispatch 失败 / deny 时的兜底错误页工厂。 */
   readonly getErrorPage?: (status: number, message: string) => BasePage;
+  /**
+   * opt-in islands 挂载原语：提供后框架按 per-entry 把视图挂为独立 root 并保活（见 Phase 2）。
+   * 缺省时走原有「单 mount + 应用订阅 snapshot 重渲」路径，不变。
+   */
+  readonly mountEntry?: MountEntry;
+}
+/**
+ * 会话恢复定义（可选）。
+ *
+ * 仅当该字段出现时会话能力才激活；缺省时 `startBrowserApp` 启动路径字节级不变。提供后：
+ * - 构建 `SessionStore`（导航适配器：有 `navigation` 配置 → 结构化
+ *   `createNavigationSessionAdapter(controller)`；否则 → 扁平 `createUrlSessionAdapter`
+ *   接 `framework.perform(makeFlowAction(url))`）；
+ * - 注册 `providers` 为全局切片来源；
+ * - 装配 `SessionBridge`（导航变更防抖落盘 + `pagehide` / `visibilitychange` 即时落盘 + scoped prune）；
+ * - mount 后 `restore(initialUrl)` 完成 boot 恢复，handle 经 mount context 交付。
+ */
+interface BrowserSessionConfig {
+  /** 全局状态切片 provider；启动时全部注册。 */
+  readonly providers?: readonly SessionStateProvider[];
+  /** 快照存储；缺省 `createWebStorage("session")`（标签级，关闭即清）。 */
+  readonly storage?: Storage;
+  /** 快照版本；缺省 `SESSION_DEFAULT_VERSION`，不符即整份丢弃。 */
+  readonly version?: number;
+  /** 快照最大存活时长（ms）；省略 = 不过期。 */
+  readonly maxAgeMs?: number;
+  /** 导航变更自动落盘防抖窗口（ms）；缺省 `SESSION_DEFAULT_DEBOUNCE_MS`。 */
+  readonly debounceMs?: number;
+  /** 恢复门控；缺省 `defaultShouldRestore`（显式深链优先）。 */
+  readonly shouldRestore?: (snapshot: SessionSnapshot, currentUrl: string) => boolean;
 }
 interface BrowserAppConfig {
   /** 注册 controllers 和路由的引导函数 */
@@ -2171,11 +2566,14 @@ interface BrowserAppConfig {
    * 框架无关 — Svelte / React / Vue 均可通过此回调实现。
    *
    * @param target - DOM 挂载点
-   * @param context - Framework 实例 + 语言
+   * @param context - Framework 实例 + 语言 + handle（配了 navigation/session 时）
    * @returns 更新函数，用于后续页面切换
    */
   mount: (target: HTMLElement, context: {
     framework: Framework;
+    navigation?: NavigationHandle;
+    session?: SessionHandle;
+    app?: AppHandle;
   }) => (props: {
     page: Promise<BasePage> | BasePage;
     isFirstPage?: boolean;
@@ -2198,18 +2596,34 @@ interface BrowserAppConfig {
   /**
    * 结构化导航定义（可选）。
    *
-   * 提供后，`startBrowserApp` 在挂载后构建 NavigationController + NavigationBridge，
-   * 解析首屏树，并通过 `onNavigationReady` 把导航 handle 交给应用。缺省时走原有
-   * 扁平单页路径（FlowAction handler），行为完全不变。
+   * 提供后，`startBrowserApp` 在 mount 前构建 NavigationController + NavigationBridge，
+   * 并通过 mount context 把导航 handle 交给应用。缺省时走原有扁平单页路径，行为完全不变。
    */
   navigation?: BrowserNavigationConfig;
   /**
-   * 导航就绪回调 —— bridge 装配并完成首屏 `resolve()` 后调用。
+   * 会话恢复定义（可选）。
+   *
+   * 提供后，`startBrowserApp` 在 mount 前装配 `SessionStore` + `SessionBridge`，
+   * 并通过 mount context 把会话 handle 交给应用；boot 恢复（restore）在 mount 后执行。
+   * 缺省时整段不生效，启动路径字节级不变。
+   */
+  session?: BrowserSessionConfig;
+  /**
+   * opt-in 重载 DOM 自动恢复（spec §4.5）。仅当同时提供 `navigation.mountEntry`（islands）+
+   * `session` 时生效：标 `data-restore-root` 的容器内表单/滚动/<details> 自动捕获进会话作用域、
+   * 重载后回填。缺省关闭。
+   */
+  domRestore?: boolean;
+  /**
+   * 顶层 islands 挂载原语（flat-islands opt-in，Phase 4）。
+   *
+   * 提供此字段且**未提供** `navigation` 时，框架合成一个隐式单栈 `NavigationController`，
+   * 把 `FlowAction` 正向导航路由为 `controller.push`，`popstate` 路由为 `hydrate`，
+   * island 实例在 back/forward 时保活不重挂。
    *
-   * 仅当提供了 `navigation` 时触发。应用拿到 handle 后用它驱动导航
-   * （push/pop/selectTab…）并订阅快照渲染 UI。
+   * 提供了 `navigation` 时请使用 `navigation.mountEntry`，顶层该字段被忽略。
    */
-  onNavigationReady?: (handle: NavigationHandle) => void | Promise<void>;
+  mountEntry?: MountEntry;
 }
 /**
  * 启动客户端应用
@@ -2218,6 +2632,51 @@ interface BrowserAppConfig {
  */
 declare function startBrowserApp(config: BrowserAppConfig): Promise<void>;
 //#endregion
+//#region ../browser/src/islands-shell.d.ts
+/**
+ * islands 应用 shell（方案 C）：chrome-root 与 outlet 为兄弟。
+ *
+ * SSR 已渲 → target 内已有 `[data-fs-chrome]` + `[data-fs-outlet]`，复用之，`hydrate` 取决于
+ * chrome-root 是否有内容（SSR 渲过 → true）。纯 CSR（无 SSR shell）→ 建出二者兄弟，`hydrate=false`。
+ * 编排器经 `[data-fs-outlet]` 找 outlet（与此约定同源）。
+ */
+interface IslandsShell {
+  readonly chromeRoot: HTMLElement;
+  readonly outlet: HTMLElement;
+  /** chrome-root 是否含 SSR 内容（true → 应水合 chrome，false → 客户端新建）。 */
+  readonly hydrate: boolean;
+}
+declare function resolveIslandsShell(target: HTMLElement): IslandsShell;
+//#endregion
+//#region ../browser/src/web-storage.d.ts
+/** Web Storage 类型：会话级（标签关闭即清）或本地级（跨会话持久）。 */
+type WebStorageKind = "session" | "local";
+/**
+ * 创建一个由浏览器 Web Storage 支撑的 core `Storage`。
+ *
+ * @param kind `"session"` → `sessionStorage`；`"local"` → `localStorage`。
+ */
+declare function createWebStorage(kind: WebStorageKind): Storage;
+//#endregion
+//#region ../browser/src/dom-restore.d.ts
+interface DomRestoreOptions {
+  /** 会话作用域（来自 SessionHandle.scope）；DOM 状态写进 `scope[key].__dom`。 */
+  readonly scope: NavigationScopedState;
+  /** 回填调度（默认 requestAnimationFrame；测试可注入同步执行）。 */
+  readonly schedule?: (cb: () => void) => void;
+}
+interface DomRestore {
+  /** 捕获一个 island container 的 DOM 状态进 scope（供测试 + 内部接线复用）。 */
+  captureEntry(container: HTMLElement): void;
+  /** 回填一个 island container（从 scope 读，scheduled）。 */
+  restoreEntry(container: HTMLElement): void;
+  /** 接线进 outlet（fs:* / input / pagehide + boot catch-up）。 */
+  attach(outlet: HTMLElement): void;
+  /** 解绑全部监听（幂等）。 */
+  dispose(): void;
+}
+declare function createDomRestore(options: DomRestoreOptions): DomRestore;
+//#endregion
 //#region ../browser/src/utils/history.d.ts
 interface HistoryOptions {
   getScrollablePageElement: () => HTMLElement | null;
@@ -2268,5 +2727,5 @@ declare function deserializeServerData(): PrefetchedIntent[] | undefined;
  */
 declare function createPrefetchedIntentsFromDom(): PrefetchedIntents;
 //#endregion
-export { isNone as $, Framework as $n, BASE_PAGE_FIELDS as $r, popToRoot as $t, resolvePluralKey as A, BaseLogger as Ai, SplitVisibility as An, RouteAddOptions as Ar, createNavigationController as At, ServerContextOptions as B, ActionHandler as Bi, classifyHost as Bn, AfterLoadGuard as Br, SerializedNavigation as Bt, makeLocaleInfo as C, ImpressionEntry as Ci, NavigationPathStep as Cn, bool as Cr, PopToRootOperation as Ct, PluralRuleProvider as D, ReportingLogger as Di, SPLIT_VISIBILITIES as Dn, str as Dr, SelectColumnOperation as Dt, PluralCategory as E, ReportCallback as Ei, ResolvedDestination as En, oneOf as Er, ReplaceTopOperation as Et, ConsoleEventRecorder as F, IntentDispatcher as Fi, mapEach as Fn, StandardIssue as Fr, createActiveLeafCodec as Ft, getBaseUrl as G, FlowAction as Gi, HttpError as Gn, NextResult as Gr, deserializeNavigation as Gt, createServerContext as H, Action as Hi, HostGuardError as Hn, DenyResult as Hr, SerializedSplitColumn as Ht, CompositeEventRecorder as I, Intent as Ii, pipe as In, StandardResult as Ir, createFullStateCodec as It, removeScheme as J, isFlowAction as Ji, stableStringify as Jn, RewriteResult as Jr, collectVisibleDestinations as Jt, removeHost as K, isCompoundAction as Ki, RequestInterceptor as Kn, PostLoadContext as Kr, serializeNavigation as Kt, runAfterLoadGuards as L, IntentController as Li, pipeAsync as Ln, StandardSchemaV1 as Lr, decodeNavigationTreeParam as Lt, VoidEventRecorder as M, LoggerFactory as Mi, TabsNode as Mn, Router as Mr, FullStateCodecOptions as Mt, ImpressionObserverOptions as N, SecureFetchOptions as Ni, AsyncMapper as Nn, InferOutput as Nr, NavigationCodec as Nt, englishPlural as O, ReportingLoggerFactory as Oi, SplitColumn as On, uuid as Or, SelectTabOperation as Ot, IntersectionImpressionObserver as P, secureFetch as Pi, Mapper as Pn, ParamSchema as Pr, NavigationRouterLike as Pt, Optional as Q, safeErrorPage as Qn, rewrite as Qr, popTo as Qt, runBeforeLoadGuards as R, Container as Ri, BaseController as Rn, makeSchema as Rr, encodeNavigationTreeParam as Rt, isRtl as S, EventRecorder as Si, NavigationPath as Sn, StrOptions as Sr, PopToOperation as St, setHtmlLocaleAttributes as T, MetricsFieldsProvider as Ti, Page as Tn, num as Tr, PushOptions as Tt, generateUuid as U, CompoundAction as Ui, HttpClient as Un, MiddlewareResult as Ur, SerializedStack as Ut, createBrowserContext as V, ACTION_KINDS as Vi, classifyUrl as Vn, BeforeLoadGuard as Vr, SerializedSplit as Vt, buildUrl as W, ExternalUrlAction as Wi, HttpClientConfig as Wn, NavigationContext as Wr, SerializedTabs as Wt, getPWADisplayMode as X, makeFlowAction as Xi, BaseShelf as Xn, next as Xr, findNode as Xt, PWADisplayMode as Y, makeExternalUrlAction as Yi, BaseItem as Yn, deny as Yr, findNearestStack as Yt, None as Z, SafeErrorPageOptions as Zn, redirect as Zr, pop as Zt, registerExternalUrlHandler as _, TranslationMessages as _i, LeafNode as _n, QuerySchemaMap as _r, NavigationControllerOptions as _t, BrowserAppConfig as a, RequestScopedKey as ai, setVisibility as an, TextDirection as ar, defineRoutes as at, getLocaleAttributes as b, PlatformInfo as bi, NavigationNode as bn, withDefault as br, NavigationOperation as bt, NavigationBridgeDependencies as c, FeatureFlags as ci, TabsInit as cn, shouldLog as cr, NavigationBrowserConfig as ct, ActionHandlerDependencies as d, MetricsRecorder as di, isStackNode as dn, CompositeLogger as dr, NavigationSSRDefinition as dt, BasePage as ei, push as en, FrameworkConfig as er, isSome as et, registerActionHandlers as f, Net as fi, isTabsNode as fn, CompositeLoggerFactory as fr, defineNavigation as ft, ExternalUrlDependencies as g, MessagesLoaderContext as gi, tabs as gn, ParamsFor as gr, NavigationController as gt, registerFlowActionHandler as h, MessagesLoader as hi, stack as hn, InferQuery as hr, NavigationContextInput as ht, History as i, markPublic as ii, selectTab as in, LocaleInfo as ir, RouteDefinition as it, WithFieldsRecorder as j, Logger as ji, StackNode as jn, RouteMatch as jr, DEFAULT_NAV_PARAM as jt, interpolate as k, ReportingLoggerOptions as ki, SplitNode as kn, RouteParams as kr, SetVisibilityOperation as kt, NavigationHandle as l, FeatureFlagsProvider as li, isLeafNode as ln, ConsoleLogger as lr, NavigationDefinition as lt, FlowActionDependencies as m, makeDependencies as mi, split as mn, InferParams as mr, NAVIGATION_OP_KINDS as mt, deserializeServerData as n, getPublicFields as ni, resolveActivePath as nn, PrefetchedIntents as nr, DefineRoutesOptions as nt, BrowserNavigationConfig as o, defineRequestScopedKey as oi, visibleSplitColumns as on, Translator as or, route as ot, FlowActionCallbacks as p, Storage as pi, leaf as pn, ExtractParamNames as pr, HydrateOperation as pt, removeQueryParams as q, isExternalUrlAction as qi, ResponseInterceptor as qn, RedirectResult as qr, serializeNavigationStable as qt, tryScroll as r, isPublicMarked as ri, selectColumn as rn, LocaleAttributes as rr, RenderMode as rt, startBrowserApp as s, DEP_KEYS as si, SplitColumnInit as sn, resetFilterCache as sr, DefineNavigationOptions as st, createPrefetchedIntentsFromDom as t, FINESOFT_PUBLIC as ti, replaceTop as tn, PrefetchedIntent as tr, LruMap as tt, createNavigationBridge as u, MakeDependenciesOptions as ui, isSplitNode as un, ConsoleLoggerFactory as ur, NavigationInitial as ut, SimpleTranslator as v, resolveConfiguredMessages as vi, NAVIGATION_NODE_KINDS as vn, StripOptional as vr, NavigationDispatchContext as vt, resolveLocaleFromUrl as w, ImpressionObserver as wi, NavigationSnapshot as wn, int as wr, PushOperation as wt, getTextDirection as x, detectPlatform as xi, NavigationNodeKind as xn, NumOptions as xr, PopOperation as xt, SimpleTranslatorOptions as y, resolveMessages as yi, NavigationError as yn, optional as yr, NavigationOpKind as yt, BrowserContextOptions as z, ActionDispatcher as zi, HostCheckResult as zn, runStandard as zr, SerializedLeaf as zt };
-//# sourceMappingURL=server-data-HVSgxEac.d.mts.map
+export { IntersectionImpressionObserver as $, FeatureFlagsProvider as $i, isLeafNode as $n, ConsoleLogger as $r, HydrateOperation as $t, ActionHandlerDependencies as A, ActionHandler as Aa, AfterLoadGuard as Ai, SerializedStack as An, classifyHost as Ar, NavigationScopedState as At, getTextDirection as B, makeFlowAction as Ba, next as Bi, popTo as Bn, BaseShelf as Br, SessionUrlLocation as Bt, SessionBridgeOptions as C, SecureFetchOptions as Ca, InferOutput as Ci, createFullStateCodec as Cn, AsyncMapper as Cr, createUrlSessionAdapter as Ct, NavigationBridgeDependencies as D, IntentController as Da, StandardSchemaV1 as Di, SerializedNavigation as Dn, pipeAsync as Dr, sessionEntryKey as Dt, defaultShouldRestore as E, Intent as Ea, StandardResult as Ei, SerializedLeaf as En, pipe as Er, createNavigationScopedState as Et, ExternalUrlDependencies as F, FlowAction as Fa, NextResult as Fi, collectAllLeaves as Fn, HttpError as Fr, SessionNavigationAdapter as Ft, PluralCategory as G, FINESOFT_PUBLIC as Gi, selectColumn as Gn, PrefetchedIntent as Gr, defineRoutes as Gt, makeLocaleInfo as H, rewrite as Hi, push as Hn, safeErrorPage as Hr, DefineRoutesOptions as Ht, registerExternalUrlHandler as I, isCompoundAction as Ia, PostLoadContext as Ii, collectVisibleDestinations as In, RequestInterceptor as Ir, SessionSnapshot as It, interpolate as J, markPublic as Ji, visibleSplitColumns as Jn, LocaleInfo as Jr, NavigationBrowserConfig as Jt, PluralRuleProvider as K, getPublicFields as Ki, selectTab as Kn, PrefetchedIntents as Kr, route as Kt, SimpleTranslator as L, isExternalUrlAction as La, RedirectResult as Li, findNearestStack as Ln, ResponseInterceptor as Lr, SessionStateProvider as Lt, FlowActionCallbacks as M, Action as Ma, DenyResult as Mi, deserializeNavigation as Mn, HostGuardError as Mr, SESSION_DEFAULT_VERSION as Mt, FlowActionDependencies as N, CompoundAction as Na, MiddlewareResult as Ni, serializeNavigation as Nn, HttpClient as Nr, SessionError as Nt, NavigationHandle as O, Container as Oa, makeSchema as Oi, SerializedSplit as On, BaseController as Or, decodeSnapshot as Ot, registerFlowActionHandler as P, ExternalUrlAction as Pa, NavigationContext as Pi, serializeNavigationStable as Pn, HttpClientConfig as Pr, SessionErrorContext as Pt, ImpressionObserverOptions as Q, FeatureFlags as Qi, TabsInit as Qn, shouldLog as Qr, defineNavigation as Qt, SimpleTranslatorOptions as R, isFlowAction as Ra, RewriteResult as Ri, findNode as Rn, stableStringify as Rr, SessionStore as Rt, SESSION_DEFAULT_DEBOUNCE_MS as S, LoggerFactory as Sa, Router as Si, createFlatStackCodec as Sn, TabsNode as Sr, createNavigationSessionAdapter as St, createSessionBridge as T, IntentDispatcher as Ta, StandardIssue as Ti, encodeNavigationTreeParam as Tn, mapEach as Tr, collectLeafKeys as Tt, resolveLocaleFromUrl as U, BASE_PAGE_FIELDS as Ui, replaceTop as Un, Framework as Ur, RenderMode as Ut, isRtl as V, redirect as Vi, popToRoot as Vn, SafeErrorPageOptions as Vr, isUrlLocation as Vt, setHtmlLocaleAttributes as W, BasePage as Wi, resolveActivePath as Wn, FrameworkConfig as Wr, RouteDefinition as Wt, WithFieldsRecorder as X, defineRequestScopedKey as Xi, islandContainerAttributes as Xn, Translator as Xr, NavigationInitial as Xt, resolvePluralKey as Y, RequestScopedKey as Yi, ResolvedEntry as Yn, TextDirection as Yr, NavigationDefinition as Yt, VoidEventRecorder as Z, DEP_KEYS as Zi, SplitColumnInit as Zn, resetFilterCache as Zr, NavigationSSRDefinition as Zt, IslandOrchestratorOptions as _, ReportingLogger as _a, str as _i, DEFAULT_NAV_PARAM as _n, SPLIT_VISIBILITIES as _r, Optional as _t, DomRestore as a, MessagesLoader as aa, InferQuery as ai, NavigationOpKind as an, stack as ar, ServerContextOptions as at, AppHandle as b, BaseLogger as ba, RouteAddOptions as bi, NavigationRouterLike as bn, SplitVisibility as br, LruMap as bt, createWebStorage as c, resolveConfiguredMessages as ca, StripOptional as ci, PopToOperation as cn, NAVIGATION_NODE_KINDS as cr, generateUuid as ct, BrowserAppConfig as d, detectPlatform as da, NumOptions as di, PushOptions as dn, NavigationNodeKind as dr, removeHost as dt, MakeDependenciesOptions as ea, ConsoleLoggerFactory as ei, NAVIGATION_OP_KINDS as en, isSplitNode as er, ConsoleEventRecorder as et, BrowserNavigationConfig as f, EventRecorder as fa, StrOptions as fi, ReplaceTopOperation as fn, NavigationPath as fr, removeQueryParams as ft, IslandOrchestrator as g, ReportCallback as ga, oneOf as gi, createNavigationController as gn, ResolvedDestination as gr, None as gt, IslandHandle as h, MetricsFieldsProvider as ha, num as hi, SetVisibilityOperation as hn, Page as hr, getPWADisplayMode as ht, History as i, makeDependencies as ia, InferParams as ii, NavigationDispatchContext as in, split as ir, BrowserContextOptions as it, registerActionHandlers as j, ACTION_KINDS as ja, BeforeLoadGuard as ji, SerializedTabs as jn, classifyUrl as jr, SESSION_DEFAULT_KEY as jt, createNavigationBridge as k, ActionDispatcher as ka, runStandard as ki, SerializedSplitColumn as kn, HostCheckResult as kr, encodeSnapshot as kt, IslandsShell as l, resolveMessages as la, optional as li, PopToRootOperation as ln, NavigationError as lr, buildUrl as lt, startBrowserApp as m, ImpressionObserver as ma, int as mi, SelectTabOperation as mn, NavigationSnapshot as mr, PWADisplayMode as mt, deserializeServerData as n, Net as na, CompositeLoggerFactory as ni, NavigationController as nn, isTabsNode as nr, runAfterLoadGuards as nt, DomRestoreOptions as o, MessagesLoaderContext as oa, ParamsFor as oi, NavigationOperation as on, tabs as or, createBrowserContext as ot, BrowserSessionConfig as p, ImpressionEntry as pa, bool as pi, SelectColumnOperation as pn, NavigationPathStep as pr, removeScheme as pt, englishPlural as q, isPublicMarked as qi, setVisibility as qn, LocaleAttributes as qr, DefineNavigationOptions as qt, tryScroll as r, Storage as ra, ExtractParamNames as ri, NavigationControllerOptions as rn, leaf as rr, runBeforeLoadGuards as rt, createDomRestore as s, TranslationMessages as sa, QuerySchemaMap as si, PopOperation as sn, LeafNode as sr, createServerContext as st, createPrefetchedIntentsFromDom as t, MetricsRecorder as ta, CompositeLogger as ti, NavigationContextInput as tn, isStackNode as tr, CompositeEventRecorder as tt, resolveIslandsShell as u, PlatformInfo as ua, withDefault as ui, PushOperation as un, NavigationNode as ur, getBaseUrl as ut, MountEntry as v, ReportingLoggerFactory as va, uuid as vi, FullStateCodecOptions as vn, SplitColumn as vr, isNone as vt, SessionHandle as w, secureFetch as wa, ParamSchema as wi, decodeNavigationTreeParam as wn, Mapper as wr, createSessionStore as wt, createAppHandle as x, Logger as xa, RouteMatch as xi, createActiveLeafCodec as xn, StackNode as xr, UrlAdapterOptions as xt, createIslandOrchestrator as y, ReportingLoggerOptions as ya, RouteParams as yi, NavigationCodec as yn, SplitNode as yr, isSome as yt, getLocaleAttributes as z, makeExternalUrlAction as za, deny as zi, pop as zn, BaseItem as zr, SessionStoreOptions as zt };
+//# sourceMappingURL=browser-DMw76sEo.d.mts.map