@finesoft/front 0.5.1 → 0.5.2

package/dist/session-DnB4ZC3x.d.mts

@@ -0,0 +1,1279 @@
+import { E as ParamSchema, F as Token, S as EventRecorder, T as InferOutput, _ as OperationPolicy, c as ExecutionContext, d as ExecutionHandle, j as Container, k as StandardSchemaV1, n as PathDescriptor, p as Invocation, s as AppDefinition, y as RuntimeHandle } from "./path-CXT6xGPO.mjs";
+import { t as SecureFetchOptions } from "./secure-fetch-Xlht2jd7.mjs";
+//#region ../core/src/intents/types.d.ts
+/**
+ * A route/navigation target.  It remains a data transfer shape only: runtime
+ * operation execution never dispatches it or looks up a controller by id.
+ */
+interface Intent<T = unknown> {
+  readonly id: string;
+  readonly params?: Record<string, unknown>;
+  readonly _returnType?: T;
+}
+//#endregion
+//#region ../core/src/schema/multi.d.ts
+/** 多值（数组）query codec：输入为 string[]，并带 `multi` 运行时标记。 */
+interface MultiValueSchema<Output> extends StandardSchemaV1<string[], Output> {
+  readonly multi: true;
+}
+interface ListOptions {
+  /** 最少元素数 */
+  min?: number;
+  /** 最多元素数 */
+  max?: number;
+}
+/** 运行时判断一个 schema 是否为多值 codec（resolve 据此决定取全部值还是单值）。 */
+declare function isMultiValueSchema(schema: StandardSchemaV1): schema is MultiValueSchema<unknown>;
+/**
+ * 多值 query 原语：用内部单值 codec 逐项校验/转换，产出数组。
+ * 缺失（undefined）→ 空数组；任一项校验失败 → 整体失败（resolve 据此 fall-through）。
+ */
+declare function list<T>(item: ParamSchema<T>, opts?: ListOptions): MultiValueSchema<T[]>;
+//#endregion
+//#region ../core/src/schema/infer.d.ts
+/** 剥离可选参数尾随的 "?" */
+type StripOptional<S extends string> = S extends `${infer N}?` ? N : S;
+/** 从 path pattern 字面量提取参数名联合（处理 :param 与 :param?） */
+type ExtractParamNames<Path extends string> = Path extends `${infer _Head}:${infer Rest}` ? Rest extends `${infer Name}/${infer Tail}` ? StripOptional<Name> | ExtractParamNames<`/${Tail}`> : StripOptional<Rest> : never;
+/** path 参数 codec map 的形状：key 只能是 path 中出现的参数名（均可选声明） */
+type ParamsFor<Path extends string> = string extends Path ? Record<string, ParamSchema> : { [K in ExtractParamNames<Path>]?: ParamSchema; };
+/** query 参数 codec map：key 自由开放；值可为单值 codec 或多值（list）codec */
+type QuerySchemaMap = Record<string, StandardSchemaV1<string, unknown> | MultiValueSchema<unknown>>;
+/** 把对象类型「拍平」为单层，便于阅读与类型相等比较 */
+type Prettify<T> = { [K in keyof T]: T[K]; } & {};
+/** 输出类型含 undefined 的 key（由 optional() 产生）→ 渲染为可选属性 */
+type OptionalOutKeys<M extends Record<string, StandardSchemaV1>> = { [K in keyof M]: undefined extends InferOutput<M[K]> ? K : never; }[keyof M];
+type RequiredOutKeys<M extends Record<string, StandardSchemaV1>> = { [K in keyof M]: undefined extends InferOutput<M[K]> ? never : K; }[keyof M];
+/**
+ * 从 codec map 推导运行期参数类型。
+ * optional() 让输出含 undefined 的 key 渲染为可选属性（`tab?: T`，并剥掉冗余的 `| undefined`）；
+ * withDefault() 始终有值，key 保持必选。
+ */
+type InferSchemaMap<M extends Record<string, StandardSchemaV1>> = Prettify<{ [K in RequiredOutKeys<M>]: InferOutput<M[K]>; } & { [K in OptionalOutKeys<M>]?: Exclude<InferOutput<M[K]>, undefined>; }>;
+type InferParams<P extends Record<string, ParamSchema>> = InferSchemaMap<P>;
+type InferQuery<Q extends QuerySchemaMap> = InferSchemaMap<Q>;
+//#endregion
+//#region ../core/src/logger/types.d.ts
+/** 日志级别 */
+type Level = "debug" | "info" | "warn" | "error";
+/**
+ * Logger 接口
+ *
+ * Logging is observational and does not produce presentation output.
+ */
+interface Logger {
+  debug(...args: unknown[]): void;
+  info(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+}
+interface LoggerFactory {
+  loggerFor(category: string): Logger;
+}
+//#endregion
+//#region ../core/src/logger/console.d.ts
+type LogFilter = (category: string, level: "debug" | "info" | "warn" | "error") => boolean;
+declare class ConsoleLogger implements Logger {
+  private readonly category;
+  private readonly shouldLog;
+  constructor(category: string, shouldLog?: LogFilter);
+  debug(...args: unknown[]): void;
+  info(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+}
+declare class ConsoleLoggerFactory implements LoggerFactory {
+  private readonly shouldLog;
+  constructor(shouldLog?: LogFilter);
+  loggerFor(category: string): Logger;
+}
+//#endregion
+//#region ../core/src/logger/reporting.d.ts
+/** 日志上报回调 */
+interface ReportCallback {
+  (level: Level, category: string, args: unknown[]): void;
+}
+/** 配置 */
+interface ReportingLoggerOptions {
+  /** 最低上报级别（默认 "warn"） */
+  minLevel?: Level;
+  /** 上报回调 */
+  report: ReportCallback;
+}
+declare class ReportingLogger implements Logger {
+  private readonly category;
+  private readonly minPriority;
+  private readonly report;
+  constructor(category: string, options: ReportingLoggerOptions);
+  debug(...args: unknown[]): void;
+  info(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+  private maybeReport;
+}
+declare class ReportingLoggerFactory implements LoggerFactory {
+  private readonly options;
+  constructor(options: ReportingLoggerOptions);
+  loggerFor(category: string): Logger;
+}
+//#endregion
+//#region ../core/src/intents/base-controller.d.ts
+interface ControllerInput<TParams extends Record<string, unknown> = Record<string, unknown>, TQuery extends Record<string, unknown> = Record<string, unknown>, TContext extends ExecutionContext = ExecutionContext> {
+  readonly params: TParams;
+  readonly query: TQuery;
+  readonly context: TContext;
+}
+type InputFor<T extends ControllerInput> = T extends ControllerInput ? ControllerInput<T["params"], T["query"], T["context"]> extends T ? T : never : never;
+interface ControllerFailure<TParams extends Record<string, unknown> = Record<string, unknown>, TQuery extends Record<string, unknown> = Record<string, unknown>, TContext extends ExecutionContext = ExecutionContext> extends ControllerInput<TParams, TQuery, TContext> {
+  readonly error: Error;
+}
+/**
+ * 抽象 Controller 基类
+ *
+ * 统一处理:
+ * - 类型安全的输入 (ControllerInput)
+ * - 返回类型约束 (TResult)
+ * - try/catch 错误处理 + 可选 fallback
+ *
+ * 路由生成的输入可直接使用 BaseController<Input, Result>。
+ *
+ * @example
+ * ```ts
+ * const API = createToken<ApiClient>("api");
+ *
+ * type Input = ControllerInput<{ productId: string }>;
+ * class ProductController extends BaseController<Input, ProductPage> {
+ *   async execute({ params, context }: Input) {
+ *     const api = await context.get(API);
+ *     return api.getProduct(params.productId);
+ *   }
+ *
+ *   fallback({ params }: ControllerFailure<{ productId: string }>) {
+ *     return getMockProduct(params.productId);
+ *   }
+ * }
+ * ```
+ */
+declare abstract class BaseController<TInput extends ControllerInput = ControllerInput, TResult = unknown> {
+  protected prepareContext(context: ExecutionContext): TInput["context"];
+  /**
+   * 执行业务逻辑 — 子类必须实现
+   *
+   * @param input - 分离的 params、query 和执行 context
+   * @returns 页面数据
+   */
+  abstract execute(input: InputFor<TInput>): Promise<TResult> | TResult;
+  /**
+   * 错误回退 — 子类可选覆写
+   *
+   * 当 execute() 抛出异常时调用。
+   * 默认行为: 重新抛出原始错误。
+   *
+   * @param input - 操作输入与 execute() 抛出的 error
+   * @returns 回退数据
+   */
+  fallback({ error }: InputFor<TInput> & {
+    readonly error: Error;
+  }): Promise<TResult> | TResult;
+  /**
+   * 自动 try/catch → fallback 模式。
+   */
+  perform(params: InputFor<TInput>["params"], context: ExecutionContext, ...query: {} extends InputFor<TInput>["query"] ? [query?: InputFor<TInput>["query"]] : [query: InputFor<TInput>["query"]]): Promise<TResult>;
+}
+//#endregion
+//#region ../core/src/utils/platform.d.ts
+/**
+ * Platform — UA 解析与平台检测
+ *
+ * 提供统一的平台/浏览器/OS 检测，避免在各处手写 UA 判断。
+ */
+interface PlatformInfo {
+  /** 操作系统 */
+  os: "ios" | "android" | "macos" | "windows" | "linux" | "unknown";
+  /** 浏览器 */
+  browser: "safari" | "chrome" | "firefox" | "edge" | "opera" | "samsung" | "unknown";
+  /** 渲染引擎 */
+  engine: "webkit" | "blink" | "gecko" | "unknown";
+  /** 是否为移动设备 */
+  isMobile: boolean;
+  /** 是否为触摸设备 */
+  isTouch: boolean;
+}
+/**
+ * 从 User-Agent 字符串解析平台信息
+ *
+ * @param ua - 主机显式提供的 User-Agent 字符串，默认空字符串
+ * @param maxTouchPoints - 主机显式提供的触摸点数量，默认 0
+ */
+declare function detectPlatform(ua?: string, maxTouchPoints?: number): PlatformInfo;
+//#endregion
+//#region ../core/src/i18n/types.d.ts
+/**
+ * i18n — 类型定义
+ *
+ * 框架级国际化基础设施。
+ */
+/** 翻译函数 */
+interface Translator {
+  /**
+   * 翻译 key → 本地化字符串
+   * @param key - 翻译 key
+   * @param values - 插值参数
+   */
+  t(key: string, values?: Record<string, string | number>): string;
+  /**
+   * 复数形式翻译
+   * @param key - 翻译 key 前缀
+   * @param count - 数量
+   * @param values - 附加插值
+   */
+  plural(key: string, count: number, values?: Record<string, string | number>): string;
+  /** 当前 locale（如 "zh-Hans" / "en-US"） */
+  readonly locale: string;
+}
+/** 文本方向 */
+type TextDirection = "ltr" | "rtl";
+/** HTML 语言属性 */
+interface LocaleAttributes {
+  /** BCP 47 语言标签 */
+  lang: string;
+  /** 文本方向 */
+  dir: TextDirection;
+}
+/** Locale 信息 */
+interface LocaleInfo {
+  /** 语言代码（如 "zh-Hans", "en"） */
+  language: string;
+  /** 地区/Storefront 代码（如 "CN", "US"） */
+  region?: string;
+  /** BCP 47 完整标签 */
+  bcp47: string;
+  /** 文本方向 */
+  dir: TextDirection;
+}
+//#endregion
+//#region ../core/src/i18n/messages.d.ts
+/**
+ * i18n message helpers shared by SSR and browser startup.
+ */
+/** Flat translation table: key -> localized text */
+type FlatMessages = Record<string, string>;
+/** Nested translation value: plain text or pluralized text map */
+type NestedMessageValue = string | Record<string, string>;
+/** Locale-grouped translation table */
+type LocaleMessages = Record<string, Record<string, NestedMessageValue>>;
+/**
+ * Translation message formats supported by the framework:
+ * - flat messages for a single locale
+ * - locale-grouped messages with optional plural subkeys
+ */
+type TranslationMessages = FlatMessages | LocaleMessages;
+/**
+ * Resolve `TranslationMessages` into the flat map consumed by
+ * `SimpleTranslator`.
+ */
+declare function resolveMessages(messages: TranslationMessages, locale: string): Record<string, string> | undefined;
+//#endregion
+//#region ../core/src/dependencies/make-dependencies.d.ts
+/** 存储接口 */
+interface Storage {
+  get(key: string): string | undefined;
+  set(key: string, value: string): void;
+  delete(key: string): void;
+}
+/** Feature Flags */
+interface FeatureFlags {
+  isEnabled(key: string): boolean;
+  getString(key: string): string | undefined;
+  getNumber(key: string): number | undefined;
+}
+/** Feature Flags Provider — 用于从远程/外部源加载 flags */
+interface FeatureFlagsProvider {
+  isEnabled(key: string): boolean;
+  getString?(key: string): string | undefined;
+  getNumber?(key: string): number | undefined;
+}
+declare const DEP_KEYS: {
+  readonly LOGGER: Token<Logger>;
+  readonly LOGGER_FACTORY: Token<LoggerFactory>;
+  readonly STORAGE: Token<Storage>;
+  readonly FEATURE_FLAGS: Token<FeatureFlags>;
+  readonly FETCH: Token<typeof fetch>;
+  /**
+   * `fetch` 包了 SSRF 防护（拒绝 private / loopback / 保留 IP + DNS resolve 后逐 IP 校验）。
+   * 当 controller 用用户可控的 URL 发起请求（图片代理、链接预览、回调等），
+   * 优先 resolve 这个 key 而不是 `FETCH`。要 opt-out 可手动调 `secureFetch(baseFetch, { allowInternalHosts: true })`。
+   */
+  readonly SAFE_FETCH: Token<typeof fetch>;
+  readonly EVENT_RECORDER: Token<EventRecorder>;
+  readonly LOCALE: Token<LocaleAttributes>;
+  readonly PLATFORM: Token<PlatformInfo>;
+  readonly TRANSLATOR: Token<Translator>;
+};
+//#endregion
+//#region ../web/src/router/types.d.ts
+/** 路由参数：键为参数名，值为 codec 转换后的任意类型（string / number / boolean …）。 */
+type RouteParams = Record<string, unknown>;
+/** Path and query share codecs, but retain separate names and values. */
+interface RouteInput {
+  readonly params: RouteParams;
+  readonly query: RouteParams;
+}
+interface RouteIntent<T = unknown> extends Intent<T> {
+  readonly query?: RouteParams;
+}
+//#endregion
+//#region ../web/src/models/page.d.ts
+/**
+ * BasePage — 所有页面共享的基础属性
+ *
+ * 具体页面类型由应用层定义并扩展此接口。
+ *
+ * SSR prefetch 数据序列化时的可见性由 `FINESOFT_PUBLIC` symbol 控制 —— 见
+ * `markPublic` / `isPublicMarked`。没有 marker 时只序列化 BasePage 标准字段。
+ * 嵌套对象需独立 markPublic、递归 projection 或 codec；true 仅选择本层字段。
+ */
+interface BasePage {
+  id: string;
+  pageType: string;
+  title: string;
+  description?: string;
+  url?: string;
+}
+/**
+ * 显式声明 page 对象里哪些字段可以跨 SSR/CSR 边界进入 HTML。未列出的字段在
+ * `serializeServerData` 时会被剥除，杜绝整 page 对象（含 apiToken、内部备注等）
+ * 被无意中 hydrate 到客户端的失误。
+ *
+ * 用 symbol 而非普通字段名：避免和应用自己的字段冲突，且 `JSON.stringify` 自动
+ * 忽略 symbol key，所以 marker 永远不会出现在序列化输出里。
+ */
+declare const FINESOFT_PUBLIC: unique symbol;
+/** 标准 BasePage 字段 —— marker 缺失但显式标注时使用。 */
+declare const BASE_PAGE_FIELDS: readonly ["id", "pageType", "title", "description", "url"];
+/**
+ * 把 `publicFields` 列表写到 page 上，供 `serializeServerData` 读取。
+ * 推荐做法是不要直接渲染原始 page 对象，而是经过这个函数显式声明 contract：
+ *
+ * ```ts
+ * return markPublic(
+ *     {
+ *         id: "profile",
+ *         pageType: "profile",
+ *         title: user.name,
+ *         email: user.email,
+ *         apiToken: user.apiToken,        // 仍在对象上，给服务端别处用
+ *     },
+ *     ["id", "pageType", "title", "email"], // 但 prefetch 只 serialize 这些
+ * );
+ * ```
+ *
+ * `true` 选择本层字段；对象/数组仍需独立标记、递归 projection 或 codec。
+ */
+interface PublicValueCodec {
+  readonly kind: "codec";
+  encode(value: unknown): unknown;
+}
+interface PublicProjection {
+  readonly [field: string]: true | PublicProjection | PublicValueCodec;
+}
+declare function markPublic<P extends object>(page: P, publicFields: readonly (keyof P)[] | true | PublicProjection): P;
+/** True 如果 page 用 `markPublic` 显式标过。 */
+declare function isPublicMarked(page: unknown): boolean;
+/** 取出 `markPublic` 写入的字段白名单；`true` 表示本层字段，`null` 表示未标注。 */
+declare function getPublicFields(page: unknown): readonly string[] | true | PublicProjection | null;
+//#endregion
+//#region ../web/src/middleware/types.d.ts
+/** 导航上下文（beforeLoad 阶段可用） */
+interface NavigationContext {
+  readonly signal?: AbortSignal;
+  /** 完整 URL（path + query） */
+  readonly url: string;
+  /** 仅路径部分 */
+  readonly path: string;
+  /** 路径参数（codec 转换后可能是 number/boolean 等） */
+  readonly params: Record<string, unknown>;
+  readonly query: Record<string, unknown>;
+  /** 匹配的 Intent */
+  readonly intent: RouteIntent;
+  /** 是否在服务端运行 */
+  readonly isServer: boolean;
+  /** DI 容器（可获取自定义服务） */
+  readonly container: Container;
+  /** 获取 Cookie 值（两端均可用） */
+  getCookie(name: string): string | undefined;
+  /** 获取请求头值（仅服务端有值，客户端始终返回 undefined） */
+  getHeader(name: string): string | undefined;
+}
+/** 后置上下文（afterLoad 阶段，包含页面数据） */
+interface PostLoadContext extends NavigationContext {
+  /** 控制器返回的页面数据 */
+  readonly page: BasePage;
+}
+/** 继续执行下一个中间件 */
+interface NextResult {
+  readonly kind: "next";
+}
+/** 重定向（服务端: HTTP 301/302，客户端: 触发新导航） */
+interface RedirectResult {
+  readonly kind: "redirect";
+  readonly url: string;
+  readonly status: number;
+}
+/** URL 重写（服务端: HTTP 301，客户端: replaceState 仅更新地址栏） */
+interface RewriteResult {
+  readonly kind: "rewrite";
+  readonly url: string;
+}
+/** 拒绝访问 */
+interface DenyResult {
+  readonly kind: "deny";
+  readonly status: number;
+  readonly message: string;
+}
+type MiddlewareResult = NextResult | RedirectResult | RewriteResult | DenyResult;
+/** 继续执行 */
+declare function next(): NextResult;
+/** 重定向到新 URL */
+declare function redirect(url: string, status?: 301 | 302): RedirectResult;
+/** URL 重写（不重新加载数据） */
+declare function rewrite(url: string): RewriteResult;
+/** 拒绝访问 */
+declare function deny(status?: number, message?: string): DenyResult;
+/** beforeLoad 守卫：路由匹配后、数据加载前 */
+type BeforeLoadGuard = (ctx: NavigationContext) => MiddlewareResult | Promise<MiddlewareResult>;
+/** afterLoad 守卫：数据加载后、渲染前 */
+type AfterLoadGuard = (ctx: PostLoadContext) => MiddlewareResult | Promise<MiddlewareResult>;
+//#endregion
+//#region ../web/src/navigation/types.d.ts
+/** 导航节点 Kind 常量 */
+declare const NAVIGATION_NODE_KINDS: {
+  readonly LEAF: "leaf";
+  readonly STACK: "stack";
+  readonly TABS: "tabs";
+  readonly SPLIT: "split";
+};
+/** 所有导航节点 Kind 的联合类型 */
+type NavigationNodeKind = (typeof NAVIGATION_NODE_KINDS)[keyof typeof NAVIGATION_NODE_KINDS];
+type EntryId = string;
+type ResourceKey = string;
+/** 叶子：一个具体导航目标 */
+interface LeafNode {
+  readonly entryId: EntryId;
+  readonly url?: string;
+  readonly kind: typeof NAVIGATION_NODE_KINDS.LEAF;
+  readonly intent: string;
+  readonly params: RouteParams;
+  readonly query?: RouteParams;
+}
+/** 栈：有序路径，entries[0]=根，末尾=栈顶（可见） */
+interface StackNode {
+  readonly kind: typeof NAVIGATION_NODE_KINDS.STACK;
+  readonly entries: readonly NavigationNode[];
+}
+/** Tabs：并列分支 + 当前激活键 + 稳定顺序；仅激活分支可见 */
+interface TabsNode {
+  readonly kind: typeof NAVIGATION_NODE_KINDS.TABS;
+  readonly active: string;
+  readonly order: readonly string[];
+  readonly branches: Readonly<Record<string, NavigationNode>>;
+}
+/** Split 列：列 id + 该列内容（undefined = 尚未选择） */
+interface SplitColumn {
+  readonly id: string;
+  readonly content: NavigationNode | undefined;
+}
+/**
+ * Split 列可见性，对标 SwiftUI `NavigationSplitViewVisibility`。
+ *
+ * 这是**可绑定 / 可序列化 / 可恢复的导航状态**（不是渲染样式）：它决定哪些列算「可见」，
+ * 进而影响 `collectVisibleDestinations` 与 SSR 预取——例如深链到 `detailOnly` 时服务端只预取 detail 列。
+ *
+ * - `automatic`（缺省）：框架不裁剪，所有有内容的列都可见（SSR 端无视口信息时的安全默认；客户端再按视口自适应）。
+ * - `all`：显式所有列可见（语义同 automatic 的全列）。
+ * - `doubleColumn`：仅首列 + 末列可见（三列时隐藏中间 content 列）。
+ * - `detailOnly`：仅末列（detail）可见。
+ *
+ * 注意：compact 视口塌缩成单栈（SwiftUI 的 `preferredCompactColumn`）是视口反应式的纯渲染决策，
+ * 框架不建模，交给应用按 `getPlatform()` / 视口自行处理。
+ */
+declare const SPLIT_VISIBILITIES: {
+  readonly AUTOMATIC: "automatic";
+  readonly ALL: "all";
+  readonly DOUBLE_COLUMN: "doubleColumn";
+  readonly DETAIL_ONLY: "detailOnly";
+};
+/** Split 列可见性的联合类型 */
+type SplitVisibility = (typeof SPLIT_VISIBILITIES)[keyof typeof SPLIT_VISIBILITIES];
+/**
+ * Split：多列并存，列间通过 selectColumn 设置后续列内容。
+ * `visibility` 决定哪些列算可见（缺省 `automatic` = 全列），是可序列化的导航状态。
+ */
+interface SplitNode {
+  readonly kind: typeof NAVIGATION_NODE_KINDS.SPLIT;
+  readonly columns: readonly SplitColumn[];
+  readonly visibility?: SplitVisibility;
+}
+/** 所有导航节点的联合类型 */
+type NavigationNode = LeafNode | StackNode | TabsNode | SplitNode;
+/** 指向树中某节点的路径（从根到目标）的一步 */
+type NavigationPathStep = {
+  readonly kind: "stack-entry";
+  readonly index: number;
+} | {
+  readonly kind: "tab";
+  readonly key: string;
+} | {
+  readonly kind: "column";
+  readonly id: string;
+};
+/** 指向树中某节点的完整路径（从根到目标） */
+type NavigationPath = readonly NavigationPathStep[];
+/** 单个可见目标的解析结果 */
+interface ResolvedDestination {
+  readonly renderMode?: string;
+  readonly rewriteUrl?: string;
+  readonly cache?: "public";
+  readonly entryId: EntryId;
+  readonly resourceKey: ResourceKey;
+  readonly intent: string;
+  readonly params: RouteParams;
+  readonly query?: RouteParams;
+  readonly page: BasePage;
+  readonly status?: number;
+}
+/** 导航快照：当前树 + 所有可见目标解析结果（顺序与 collectVisibleDestinations 一致） */
+interface NavigationSnapshot {
+  /** Uncommitted redirect, including admission before any destination exists. */
+  readonly redirect?: {
+    readonly url: string;
+    readonly status: number;
+  };
+  /** Transaction denial is observable even for an empty tree; this snapshot is never committed. */
+  readonly rejection?: DenyResult;
+  readonly transitionId?: string;
+  readonly historyMode?: "push" | "replace";
+  readonly tree: NavigationNode;
+  readonly destinations: readonly ResolvedDestination[];
+}
+/** 错误类型：序列化 / 路径 / 操作非法时抛出 */
+declare class NavigationError extends Error {
+  constructor(message: string);
+}
+//#endregion
+//#region ../web/src/actions/types.d.ts
+/** Action Kind 常量 */
+declare const ACTION_KINDS: {
+  FLOW: "flow";
+  EXTERNAL_URL: "externalUrl";
+  COMPOUND: "compound";
+  PUSH: "push";
+  POP: "pop";
+  POP_TO_ROOT: "popToRoot";
+  POP_TO: "popTo";
+  REPLACE_TOP: "replaceTop";
+  SELECT_TAB: "selectTab";
+  SELECT_COLUMN: "selectColumn";
+  SET_VISIBILITY: "setVisibility";
+  HYDRATE: "hydrate";
+  REUSE_ENTRY: "reuseEntry";
+  REFRESH: "refresh";
+};
+/** FlowAction — SPA 导航 */
+interface FlowAction {
+  kind: typeof ACTION_KINDS.FLOW;
+  url: string;
+  /** 默认按应用的路由模型导航；modal 使用独立页面会话。 */
+  presentationContext?: "default" | "modal";
+}
+/** ExternalUrlAction — 外部链接 */
+interface ExternalUrlAction {
+  kind: typeof ACTION_KINDS.EXTERNAL_URL;
+  url: string;
+}
+/** CompoundAction — 组合 Action */
+interface CompoundAction<Params extends Record<string, RouteParams> = Record<string, RouteParams>, Queries extends Record<string, RouteParams> = Record<string, RouteParams>> {
+  kind: typeof ACTION_KINDS.COMPOUND;
+  actions: Action<Params, Queries>[];
+}
+type InputField<P extends RouteParams, Key extends string> = {} extends P ? { readonly [K in Key]?: P; } : { readonly [K in Key]: P; };
+type PageAction<Params extends Record<string, RouteParams>, Queries extends Record<string, RouteParams>> = { [Id in keyof Params & string]: InputField<Params[Id], "params"> & InputField<Queries[Id], "query"> & ({
+  readonly kind: "push" | "replaceTop";
+  readonly intent: Id;
+  readonly target?: NavigationPath;
+  readonly url?: string;
+} | {
+  readonly kind: "selectColumn";
+  readonly columnId: string;
+  readonly intent: Id;
+  readonly target?: NavigationPath;
+}); }[keyof Params & string];
+/** Structured actions share the same dispatcher and guarded commit as URL actions. */
+type TreeAction<Params extends Record<string, RouteParams> = Record<string, RouteParams>, Queries extends Record<string, RouteParams> = Record<string, RouteParams>> = PageAction<Params, Queries> | {
+  readonly kind: "pop";
+  readonly count?: number;
+  readonly target?: NavigationPath;
+} | {
+  readonly kind: "popToRoot";
+  readonly target?: NavigationPath;
+} | {
+  readonly kind: "popTo";
+  readonly index: number;
+  readonly target?: NavigationPath;
+} | {
+  readonly kind: "selectTab";
+  readonly key: string;
+  readonly target?: NavigationPath;
+} | {
+  readonly kind: "selectColumn";
+  readonly columnId: string;
+  readonly intent: undefined;
+  readonly params?: never;
+  readonly target?: NavigationPath;
+} | {
+  readonly kind: "setVisibility";
+  readonly visibility: SplitVisibility;
+  readonly target?: NavigationPath;
+} | {
+  readonly kind: "hydrate";
+  readonly tree: NavigationNode;
+} | {
+  readonly kind: "reuseEntry";
+  readonly entryId: string;
+} | {
+  readonly kind: "refresh";
+};
+type Action<Params extends Record<string, RouteParams> = Record<string, RouteParams>, Queries extends Record<string, RouteParams> = Record<string, RouteParams>> = FlowAction | TreeAction<Params, Queries> | ExternalUrlAction | CompoundAction<Params, Queries>;
+interface ActionInvocation {
+  readonly signal?: AbortSignal;
+}
+declare function isFlowAction(action: Action): action is FlowAction;
+declare function isExternalUrlAction(action: Action): action is ExternalUrlAction;
+declare function isCompoundAction(action: Action): action is CompoundAction;
+declare function makeFlowAction(url: string, presentationContext?: FlowAction["presentationContext"]): FlowAction;
+declare function makeExternalUrlAction(url: string): ExternalUrlAction;
+//#endregion
+//#region ../web/src/actions/dispatcher.d.ts
+/** Action 处理器函数类型 */
+type ActionHandler<A extends Action = Action, Result = void> = (action: A, invocation?: ActionInvocation) => Promise<Result | void> | Result | void;
+declare class ActionDispatcher<Result = void> {
+  private readonly currentResult?;
+  private handlers;
+  private closed;
+  private epoch;
+  private invocations;
+  private pendingFlow?;
+  constructor(currentResult?: (() => Result) | undefined);
+  get generation(): number;
+  /** Cancel pending groups; a handler may retain its own invocation during URL admission. */
+  cancel: (invocation?: ActionInvocation) => void;
+  /**
+   * 注册指定 kind 的 handler。
+   *
+   * 重复 kind 时保留第一个注册者并发出警告——这是有意设计：
+   * framework 内部 handler 先注册，应用层意外覆盖会被记录而非静默生效。
+   * 如需显式替换，先调用 removeAction(kind)。
+   */
+  onAction: <A extends Action>(kind: string, handler: ActionHandler<A, Result>) => void;
+  /** 移除指定 kind 的 handler（用于显式覆盖场景） */
+  removeAction: (kind: string) => boolean;
+  close(): void;
+  /** 执行一个 Action（CompoundAction 递归展开，有深度限制） */
+  perform: (action: Action, invocation?: ActionInvocation) => Promise<Result>;
+  private dispatch;
+}
+//#endregion
+//#region ../web/src/router/router.d.ts
+interface RouteMatch {
+  intent: RouteIntent;
+  action: FlowAction;
+  cache?: "public";
+  renderMode?: string;
+  beforeGuards?: BeforeLoadGuard[];
+  afterGuards?: AfterLoadGuard[];
+}
+interface RouteAddOptions {
+  cache?: "public";
+  renderMode?: string;
+  beforeGuards?: BeforeLoadGuard[];
+  afterGuards?: AfterLoadGuard[];
+  paramCodecs?: Record<string, ParamSchema>;
+  queryCodecs?: QuerySchemaMap;
+}
+/** The structured, portable part of a route declaration. */
+interface RouteDefinition$1 {
+  readonly pattern: string;
+  readonly intentId: string;
+  readonly path: PathDescriptor;
+}
+declare class Router {
+  private readonly debug?;
+  private routes;
+  private sealed;
+  constructor(debug?: ((message: string) => void) | undefined);
+  seal(): this;
+  add(pattern: string, intentId: string, options?: RouteAddOptions): this;
+  resolve(urlOrPath: string): Promise<RouteMatch | null>;
+  hasIntent(intentId: string): boolean;
+  getDefinitions(): readonly RouteDefinition$1[];
+  reverse(intentId: string, params: Readonly<RouteParams>, queryParams?: Readonly<RouteParams>): string | undefined;
+  private parseUrl;
+}
+//#endregion
+//#region ../web/src/prefetched-intents/prefetched-intents.d.ts
+/** 预获取的 Intent-Data 对 */
+interface PrefetchedIntent {
+  entryId?: string;
+  intent: RouteIntent;
+  data: unknown;
+}
+declare class PrefetchedIntents {
+  private readonly entryIds;
+  private intents;
+  private constructor();
+  /** 从 PrefetchedIntent 数组创建缓存实例 */
+  static fromArray(items: PrefetchedIntent[]): PrefetchedIntents;
+  /** 创建空缓存实例 */
+  static empty(): PrefetchedIntents;
+  /**
+   * 获取缓存的 Intent 结果（一次性使用）。
+   * 命中后从缓存中删除。
+   */
+  get<T>(intent: RouteIntent<T>, entryId?: string): T | undefined;
+  /** @internal Navigation-owned staged reads; direct get remains one-shot. */
+  stage(): {
+    cache: PrefetchedIntents;
+    commit(): void;
+  };
+  /** Read identity metadata without consuming data or bypassing operation policies. */
+  entryIdFor(intent: RouteIntent): string | undefined;
+  /** 检查缓存中是否有某个 Intent 的数据 */
+  has(intent: RouteIntent, entryId?: string): boolean;
+  /** 缓存中的条目数 */
+  get size(): number;
+}
+//#endregion
+//#region ../web/src/bootstrap/define-routes.d.ts
+/** 渲染模式 */
+type RenderMode = "ssr" | "csr" | "prerender";
+/** 单条路由定义 */
+interface PageRoute<Path extends string = string, P extends ParamsFor<Path> = ParamsFor<Path>, Q extends QuerySchemaMap = QuerySchemaMap> {
+  /** URL pattern (如 "/product/:id") */
+  path: Path;
+  /** path 参数 codec；key 必须是 path 中出现的 :param 名 */
+  params?: P;
+  /** query 参数 codec；key 自由 */
+  query?: Q;
+  /** 渲染模式（可选，默认 "ssr"） */
+  cache?: "public";
+  renderMode?: RenderMode;
+  /** 路由级 beforeLoad 守卫 */
+  beforeLoad?: BeforeLoadGuard[];
+  /** 路由级 afterLoad 守卫 */
+  afterLoad?: AfterLoadGuard[];
+}
+/** A normalized route associates a URL with its owning page. */
+interface RouteDefinition<Path extends string = string, P extends ParamsFor<Path> = ParamsFor<Path>, Q extends QuerySchemaMap = QuerySchemaMap> extends PageRoute<Path, P, Q> {
+  intentId: string;
+}
+/**
+ * 构造一条强类型路由定义。
+ * `params` 的 key 受 `path` 字面量约束——写入 path 中不存在的参数名会编译期报错。
+ *
+ * @example
+ * route("/product/:id", { intentId: "product", params: { id: int() } })
+ */
+declare function route<const Path extends string, const Definition extends Omit<RouteDefinition<Path>, "path">>(path: Path, def: Definition & NoInfer<Record<Exclude<keyof Definition, keyof Omit<RouteDefinition<Path>, "path">>, never>>): Readonly<{
+  path: Path;
+} & Definition>;
+//#endregion
+//#region ../web/src/navigation/serialization.d.ts
+/** 序列化叶子 */
+interface SerializedLeaf {
+  readonly entryId: string;
+  readonly url?: string;
+  readonly kind: typeof NAVIGATION_NODE_KINDS.LEAF;
+  readonly intent: string;
+  readonly params: RouteParams;
+  readonly query?: RouteParams;
+}
+/** 序列化栈 */
+interface SerializedStack {
+  readonly kind: typeof NAVIGATION_NODE_KINDS.STACK;
+  readonly entries: readonly SerializedNavigation[];
+}
+/** 序列化 Tabs */
+interface SerializedTabs {
+  readonly kind: typeof NAVIGATION_NODE_KINDS.TABS;
+  readonly active: string;
+  readonly order: readonly string[];
+  readonly branches: Readonly<Record<string, SerializedNavigation>>;
+}
+/** 序列化 Split 列（空内容用 null 表示，JSON 安全） */
+interface SerializedSplitColumn {
+  readonly id: string;
+  readonly content: SerializedNavigation | null;
+}
+/** 序列化 Split（visibility 缺省时不写该字段，保持紧凑） */
+interface SerializedSplit {
+  readonly kind: typeof NAVIGATION_NODE_KINDS.SPLIT;
+  readonly columns: readonly SerializedSplitColumn[];
+  readonly visibility?: SplitVisibility;
+}
+/** 序列化后的导航树（JSON 安全的可辨识联合） */
+type SerializedNavigation = SerializedLeaf | SerializedStack | SerializedTabs | SerializedSplit;
+/** 把导航树序列化为 JSON 安全的纯对象。 */
+declare function serializeNavigation(tree: NavigationNode): SerializedNavigation;
+/** 导航树的确定性字符串形式（keys 排序）；用于稳定缓存键 / 紧凑编码。 */
+declare function serializeNavigationStable(tree: NavigationNode): string;
+/** 从 JSON 安全数据还原导航树；结构畸形抛 NavigationError。 */
+declare function deserializeNavigation(data: unknown): NavigationNode;
+//#endregion
+//#region ../web/src/navigation/codec.d.ts
+interface NavigationRouterLike {
+  reverse(intentId: string, params: RouteParams, query?: RouteParams): string | undefined;
+}
+interface NavigationCodec {
+  encode(tree: NavigationNode, router: NavigationRouterLike): string;
+  decode(url: string, router: NavigationRouterLike): NavigationNode | undefined;
+}
+declare const DEFAULT_NAV_PARAM = "__nav";
+declare function encodeNavigationTreeParam(tree: NavigationNode): string;
+declare function decodeNavigationTreeParam(encoded: string): NavigationNode;
+declare function createActiveLeafCodec(): NavigationCodec;
+interface FullStateCodecOptions {
+  readonly param?: string;
+}
+declare function createFullStateCodec(options?: FullStateCodecOptions): NavigationCodec;
+//#endregion
+//#region ../web/src/i18n/messages.d.ts
+interface MessagesLoaderContext {
+  readonly runtime: "server" | "browser";
+  readonly fetch: typeof globalThis.fetch;
+  readonly url: string;
+  readonly request?: Request;
+}
+type MessagesLoader = (locale: string, context: MessagesLoaderContext) => TranslationMessages | Promise<TranslationMessages | undefined> | undefined;
+interface ResolveConfiguredMessagesOptions {
+  locale?: string;
+  loadMessages?: MessagesLoader;
+  context?: MessagesLoaderContext;
+}
+/**
+ * Resolve the effective translation source for a locale.
+ */
+declare function resolveConfiguredMessages(options: ResolveConfiguredMessagesOptions): Promise<TranslationMessages | undefined>;
+//#endregion
+//#region ../web/src/application/controller-context.d.ts
+/** Page metadata belongs to the current load, including when several pages share an execution. */
+interface ControllerContext extends ExecutionContext {
+  readonly url: string;
+  readonly path: string;
+  readonly intent: NavigationContext["intent"];
+  readonly isServer: boolean;
+  getCookie(name: string): string | undefined;
+  getHeader(name: string): string | undefined;
+}
+type PageControllerInput<P extends Record<string, unknown> = Record<string, unknown>, Q extends Record<string, unknown> = Record<string, unknown>> = ControllerInput<P, Q, ControllerContext>;
+declare const SERVER_CONTROLLER: unique symbol;
+declare const SERVER_REQUEST = "@finesoft/web/server-request";
+interface ServerRequestState {
+  readonly request: Request;
+  readonly responseHeaders: Headers;
+  readonly remote: boolean;
+  /** Incoming request cookies; outgoing response mutations do not change this view. */
+  readonly cookies: ReadonlyMap<string, string>;
+}
+declare function controllerContext(execution: ExecutionContext, navigation: Pick<NavigationContext, "url" | "path" | "intent" | "isServer" | "getCookie" | "getHeader">): ControllerContext;
+//#endregion
+//#region ../web/src/application/types.d.ts
+interface PageControllerDefinition {
+  readonly id: string;
+  readonly create?: () => {
+    perform(input: RouteParams, context: ExecutionContext, query: RouteParams): BasePage | Promise<BasePage>;
+  };
+  readonly handler?: (params: RouteParams, context: ControllerContext, query: RouteParams) => BasePage | Promise<BasePage>;
+  readonly policies?: readonly OperationPolicy<RouteParams>[];
+  readonly routes?: readonly (string | PageRoute)[];
+}
+interface NavigationTarget {
+  readonly url: string;
+  readonly match?: RouteMatch;
+  readonly target?: LeafNode;
+}
+interface WebAppDefinition<Pages extends readonly PageControllerDefinition[] = readonly PageControllerDefinition[]> {
+  readonly id: string;
+  readonly app?: AppDefinition;
+  readonly pages: Pages;
+  /** Opt into retained structured navigation. Without it or a codec, URL navigation replaces the page. */
+  readonly navigation?: NavigationNode | ((target: NavigationTarget) => NavigationNode | undefined);
+  readonly navigationCodec?: NavigationCodec;
+  readonly loadMessages?: MessagesLoader;
+  readonly getErrorPage: (status: number, message: string) => BasePage;
+  readonly configuration?: WebConfiguration;
+  readonly beforeNavigate?: readonly BeforeNavigatePolicy[];
+  readonly beforeCommit?: readonly BeforeCommitPolicy[];
+  readonly beforeLoad?: readonly BeforeLoadGuard[];
+  readonly afterLoad?: readonly AfterLoadGuard[];
+}
+type PageInput<P> = P extends {
+  leaf: (...args: infer A) => unknown;
+} ? NonNullable<A[0]> extends RouteParams ? NonNullable<A[0]> : RouteParams : P extends {
+  handler: (params: infer Input, ...rest: any[]) => unknown;
+} ? Input extends RouteParams ? Input : RouteParams : RouteParams;
+/** Structural metadata; no runtime registry or cross-package private brand. */
+type AppParams<Definition extends WebAppDefinition> = { [P in Definition["pages"][number] as P["id"]]: PageInput<P>; };
+type AppQueries<Definition extends WebAppDefinition> = { [P in Definition["pages"][number] as P["id"]]: P extends {
+  leaf: (...args: infer A) => unknown;
+} ? NonNullable<A[1]> extends {
+  query?: infer Q extends RouteParams;
+} ? Q : RouteParams : RouteParams; };
+//#endregion
+//#region ../web/src/application/runtime.d.ts
+interface WebConfiguration {
+  readonly fetch?: typeof globalThis.fetch;
+  readonly locale?: string;
+  readonly platform?: PlatformInfo;
+  readonly safeFetch?: SecureFetchOptions;
+  readonly logFilter?: LogFilter;
+  readonly reportCallback?: ReportCallback;
+  readonly eventRecorder?: EventRecorder;
+  readonly featureFlags?: Readonly<Record<string, boolean | string | number>>;
+  readonly featureFlagsProviders?: readonly FeatureFlagsProvider[];
+  /** Keep browser defaults shared; SSR supplies execution for request-local memory storage. */
+  readonly storageScope?: "runtime" | "execution";
+}
+interface WebRuntimeOptions<Definition extends WebAppDefinition = WebAppDefinition> extends WebConfiguration {
+  readonly definition: Definition;
+  readonly runtime?: RuntimeHandle;
+  readonly invocation?: Invocation;
+  readonly prefetchedIntents?: PrefetchedIntents;
+  readonly messages?: TranslationMessages;
+  /** Host-resolved attributes used by the default locale provider. */
+  readonly localeAttributes?: LocaleAttributes;
+}
+declare function createWebRuntime<Definition extends WebAppDefinition>(input: WebRuntimeOptions<Definition>): {
+  definition: Definition;
+  router: Router;
+  runtime: RuntimeHandle;
+  prefetchedIntents: PrefetchedIntents;
+  getLocale: (execution?: ExecutionHandle) => Promise<LocaleAttributes | undefined>;
+  getTranslator: (execution?: ExecutionHandle) => Promise<Translator | undefined>;
+  getLogger: (execution?: ExecutionHandle) => Promise<Logger>;
+  createExecution(invocation?: Invocation): ExecutionHandle;
+  dispose(): Promise<void>;
+};
+type WebRuntime<Definition extends WebAppDefinition = WebAppDefinition> = ReturnType<typeof createWebRuntime<Definition>>;
+//#endregion
+//#region ../web/src/session/types.d.ts
+/**
+ * Session — 会话恢复的核心类型
+ *
+ * 会话恢复把「用户当时在干什么」（导航位置 + 应用注册的状态切片 + 导航作用域状态）
+ * 序列化进一份可版本化、JSON 安全的快照，持久化到可插拔 `Storage`，并在全新加载时重水化。
+ * 框架只搬运状态、不解释内容，也不参与 UI —— 应用据恢复出的状态自行重渲染。
+ *
+ * 两层作用域共同序列化进快照：
+ * - **全局切片（`slices`）**：app-wide，键 = `provider.key`，生命周期 = 整个会话。
+ * - **导航作用域状态（`scoped`）**：绑定到某个导航条目（`entryKey`），对标 SwiftUI `@State`
+ *   的「位置作用域」语义 —— 条目离树即被 prune 丢弃（见 `scoped-state.ts`）。
+ */
+/** Asynchronous session persistence. A missing key resolves undefined; failures reject. */
+interface AsyncStorage {
+  get(key: string): Promise<string | undefined>;
+  set(key: string, value: string): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+declare class StorageUnavailableError extends Error {
+  constructor();
+}
+type SessionFailure = {
+  readonly status: "failed";
+  readonly cause: unknown;
+} | {
+  readonly status: "unavailable";
+} | {
+  readonly status: "closed";
+};
+type SessionWriteResult = {
+  readonly status: "saved" | "cleared";
+} | SessionFailure;
+type SessionLoadResult = {
+  readonly status: "loaded";
+  readonly snapshot: SessionSnapshot;
+} | {
+  readonly status: "missing" | "invalid" | "expired";
+} | SessionFailure;
+type SessionRestoreResult = {
+  readonly status: "restored";
+} | {
+  readonly status: "partial";
+  readonly discarded: readonly string[];
+} | {
+  readonly status: "skipped";
+} | Exclude<SessionLoadResult, {
+  status: "loaded";
+}>;
+interface SessionSlice {
+  readonly version: number;
+  readonly data: unknown;
+}
+/** 会话快照在 Storage 中的默认键。 */
+declare const SESSION_DEFAULT_KEY = "__finesoft_session__";
+/** 会话快照的默认版本号；解码时不匹配即整份丢弃。 */
+declare const SESSION_DEFAULT_VERSION = 2;
+/**
+ * 会话快照：用户「当时在干什么」的可序列化捕获。
+ *
+ * `navigation` 始终是结构化 `SerializedNavigation`；版本 2 不接受早期 URL-only 导航载荷。
+ */
+interface SessionSnapshot {
+  /** 快照版本；解码时与期望版本不符即丢弃。 */
+  readonly version: number;
+  /** 导航位置：统一为结构化导航树；缺省则不恢复导航。 */
+  readonly navigation?: SerializedNavigation;
+  /**
+   * 该快照导航位置的可比 URL（捕获时刻与 history 同步的浏览器 URL），供恢复门控做精确匹配。
+   *
+   * 适配器在 `capture` 时记录浏览器 URL。缺省时恢复门控只在根入口放行。
+   */
+  readonly url?: string;
+  /** 全局切片（app-wide）：`provider.key` → `{ version, data }`。 */
+  readonly slices: Readonly<Record<string, unknown>>;
+  /** 导航作用域状态：`entryKey` → 该导航条目的状态袋；条目离树即被 prune 丢弃。 */
+  readonly scoped: Readonly<Record<string, unknown>>;
+  /** 捕获时刻（epoch ms）；用于 `maxAgeMs` 过期判断。 */
+  readonly capturedAt: number;
+}
+/**
+ * 全局状态切片 Provider。
+ *
+ * capture 同步且 JSON 安全；decode 校验当前 schema，migration 按切片独立执行。应用控制捕获什么
+ * （敏感字段在 `capture()` 中自行排除）。
+ */
+interface SessionStateProvider<T = unknown> {
+  /** 切片唯一键（快照里 `slices` 的 key）。 */
+  readonly key: string;
+  readonly version: number;
+  /** Validate current-version data. Throw to discard this slice. */
+  decode(data: unknown): T;
+  /** Migrate old data; decoder always validates the result. */
+  migrate?(data: unknown, fromVersion: number): unknown;
+  /** 捕获当前切片状态，必须返回 JSON 安全的同步值。 */
+  capture(): T;
+  /** 用持久化的切片数据恢复（应用自行 setState / 填表单 / 滚动）。 */
+  restore(data: T): void | Promise<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[];
+}
+/**
+ * 持久化导航端口：WebSession 直接实现，SessionStore 只依赖捕获和恢复契约。
+ *
+ * 所有页面形态通过同一结构化树恢复。
+ */
+interface SessionNavigation {
+  /** 捕获当前导航位置。 */
+  captureNavigation(): SessionSnapshot["navigation"] | undefined;
+  /** 应用恢复的导航位置。 */
+  restoreNavigation(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" | "clear";
+  readonly code?: "slice-failed" | "slice-incompatible" | "navigation-invalid" | "storage-failed" | "storage-unavailable";
+  readonly key?: string;
+}
+/** `createSessionStore` 选项。 */
+interface SessionStoreOptions {
+  /** 异步持久化存储（独立于同步环境 Storage）。 */
+  readonly storage: AsyncStorage;
+  /** 快照键；默认 `SESSION_DEFAULT_KEY`。 */
+  readonly key?: string;
+  /** 快照版本；默认 `SESSION_DEFAULT_VERSION`，不符即丢弃。 */
+  readonly version?: number;
+  /** 快照最大存活时长（ms）；省略 = 不过期。 */
+  readonly maxAgeMs?: number;
+  /** 导航端口；省略 = 不恢复导航。 */
+  readonly navigation?: SessionNavigation;
+  /** 注入时钟（测试 / SSR 安全）；默认 `() => Date.now()`。 */
+  readonly now?: () => number;
+  /** 错误回调；默认 no-op，仅接收安全错误码与阶段/key，不接收私有异常。 */
+  readonly onError?: (error: unknown, ctx: SessionErrorContext) => void;
+}
+/** 会话编排器：组装 / 落盘 / 读取 / 恢复快照，并持有导航作用域状态。 */
+interface SessionStore {
+  /** 注册全局切片 provider；返回反注册函数。 */
+  register<T>(provider: SessionStateProvider<T>): () => void;
+  /** 导航作用域状态读写 + prune。 */
+  readonly scope: NavigationScopedState;
+  /** 同步复制 nav/slices/scoped 的 JSON 值，独立于可变来源；不冻结来源、不落盘。 */
+  capture(): SessionSnapshot;
+  /** 显式快照在调用时复制/编码；省略参数则在排队写入开始时捕获最新状态。 */
+  persist(snapshot?: SessionSnapshot): Promise<SessionWriteResult>;
+  /** 读取并校验，返回 loaded/missing/invalid/expired/failed/unavailable/closed。 */
+  load(): Promise<SessionLoadResult>;
+  /** 恢复：应用 nav + 回填 scoped + 派发各 slice 给对应 provider（省略则先 `load`）。 */
+  restore(snapshot?: SessionSnapshot): Promise<SessionRestoreResult>;
+  /** 清除持久化快照。 */
+  clear(): Promise<SessionWriteResult>;
+  /** 手动逃生口 = `capture` + `persist`。 */
+  save(): Promise<SessionWriteResult>;
+  /** Stop new work and await all registered operations. */
+  dispose(): Promise<void>;
+}
+/** 会话错误：序列化 / 编排过程中需要显式标识的错误类型。 */
+declare class SessionError extends Error {
+  constructor(message: string);
+}
+//#endregion
+//#region ../web/src/application/view.d.ts
+interface NavigationSummary {
+  readonly canGoBack: boolean;
+  readonly activeEntryId?: string;
+  readonly tabs?: {
+    readonly active: string;
+    readonly order: readonly string[];
+  };
+}
+interface ViewEntry extends ResolvedDestination {
+  readonly visible: boolean;
+}
+interface AppSnapshot extends NavigationSnapshot {
+  readonly revision: number;
+  readonly entries: readonly ViewEntry[];
+  readonly navigation: NavigationSummary;
+}
+/** Native roots consume the same view during SSR and in the browser. */
+interface WebAppView<Definition extends WebAppDefinition = WebAppDefinition> extends Pick<ActionDispatcher<NavigationSnapshot>, "onAction" | "removeAction"> {
+  perform(this: void, action: Action<AppParams<Definition>, AppQueries<Definition>>, invocation?: ActionInvocation): Promise<NavigationSnapshot>;
+  readonly runtime: RuntimeHandle;
+  readonly session?: SessionStore;
+  readonly locale?: LocaleAttributes;
+  readonly translator?: Translator;
+  getSnapshot(this: void): AppSnapshot;
+  subscribe(this: void, listener: () => void): () => void;
+  /** Called by a native post-commit hook; it never waits for session restore. */
+  commit(this: void, revision: number): void;
+}
+interface ViewProps<P extends BasePage = BasePage, Definition extends WebAppDefinition = WebAppDefinition> {
+  readonly page: P;
+  readonly app: WebAppView<Definition>;
+  readonly entry: ViewEntry;
+}
+//#endregion
+//#region ../web/src/application/session.d.ts
+/** Host metadata for a destination; execution owns dependency scope and cancellation. */
+interface NavigationContextInput {
+  readonly execution: ExecutionContext;
+  readonly intent: string;
+  readonly params: RouteParams;
+  readonly query?: RouteParams;
+  readonly signal?: AbortSignal;
+  readonly url?: string;
+}
+/** Admission runs once per transaction; page redirects do not repeat it. */
+type BeforeNavigateResult = NextResult | DenyResult | RedirectResult;
+/** The final candidate can only be accepted or denied, never redirected after inspection. */
+type BeforeCommitResult = Exclude<BeforeNavigateResult, {
+  kind: "redirect";
+}>;
+interface NavigationTransactionContext {
+  readonly from: NavigationSnapshot;
+  readonly tree: NavigationNode;
+  readonly transitionId: string;
+  readonly execution: ExecutionContext;
+  readonly signal: AbortSignal;
+  readonly isServer: boolean;
+}
+interface NavigationCommitContext extends NavigationTransactionContext {
+  readonly candidate: NavigationSnapshot;
+}
+type BeforeNavigatePolicy = (context: NavigationTransactionContext) => BeforeNavigateResult | Promise<BeforeNavigateResult>;
+type BeforeCommitPolicy = (context: NavigationCommitContext) => BeforeCommitResult | Promise<BeforeCommitResult>;
+interface WebSessionOptions<Definition extends WebAppDefinition = WebAppDefinition> {
+  readonly commit?: (revision: number) => void;
+  readonly session?: () => SessionStore | undefined;
+  readonly captureUrl?: () => string | undefined;
+  readonly beforeNavigate?: readonly BeforeNavigatePolicy[];
+  readonly beforeCommit?: readonly BeforeCommitPolicy[];
+  readonly web: WebRuntime<Definition>;
+  readonly execution?: ExecutionHandle;
+  readonly viewReady?: (snapshot: NavigationSnapshot, signal?: AbortSignal) => void | Promise<void>;
+  /** 初始导航树；单 LeafNode 表示扁平单页。 */
+  readonly initial: NavigationNode;
+  /** Host-specific guard context, including request cookies and headers. */
+  readonly createContext?: (input: NavigationContextInput) => NavigationContext;
+  /**
+   * 是否运行在服务端——仅用于未配置 `createContext` 时的最小上下文，
+   * 决定该上下文的 `isServer` 字段。缺省为 true；浏览器 host 显式传 false。
+   * 应用若已通过 `createContext` 提供完整上下文，此项不生效。
+   */
+  readonly isServer?: boolean;
+  /** 目标级 beforeLoad 守卫（在全局/路由守卫之外，由控制器对每个可见目标执行）。 */
+  readonly beforeLoad?: readonly BeforeLoadGuard[];
+  /** 目标级 afterLoad 守卫。 */
+  readonly afterLoad?: readonly AfterLoadGuard[];
+  /** Override the application's error page for this session. */
+  readonly getErrorPage?: (status: number, message: string) => BasePage;
+  /**
+   * Called after the redirecting execution finishes. Return a tree to follow within
+   * this same queued operation (at most five follows), preserving cancellation and
+   * history mode. Return void to report an HTTP redirect or finish an external handoff.
+   * Do not call queued controller operations from this callback.
+   */
+  readonly onRedirect?: (redirect: {
+    url: string;
+    status: number;
+  }, candidate: NavigationSnapshot) => void | NavigationNode | Promise<void | NavigationNode>;
+}
+/** Shared navigation, native view and persistence owner. */
+interface WebSession<Definition extends WebAppDefinition = WebAppDefinition> extends WebAppView<Definition>, SessionNavigation {
+  /** Initial host presentation; rejected candidates are sanitized without committing them. */
+  start(this: void, invocation?: ActionInvocation): Promise<AppSnapshot>;
+  /** 当前导航树。 */
+  getTree(this: void): NavigationNode;
+  onCommit(this: void, listener: (snapshot: AppSnapshot, previous: AppSnapshot) => void): () => void;
+  /** 当前快照（树 + 已解析的可见目标）。 */
+  getSnapshot(this: void): AppSnapshot;
+  cancel(this: void, invocation?: ActionInvocation): void;
+  dispose(this: void): Promise<void>;
+  /**
+   * 清除页面缓存：给 `entryId` 清单个，
+   * 不传清全部。仅清缓存、不触发重解析——该条目下次被解析时重新 dispatch。
+   */
+  invalidate(this: void, entryKey?: string): void;
+  /** 订阅快照变更；返回取消订阅函数。 */
+  subscribe(this: void, listener: (snapshot: AppSnapshot) => void): () => void;
+}
+declare function createWebSession<Definition extends WebAppDefinition>(options: WebSessionOptions<Definition>): WebSession<Definition>;
+/** State is already committed; observers and hosts must not report a pre-commit rejection. */
+declare class NavigationCommitError extends Error {
+  readonly snapshot: NavigationSnapshot;
+  readonly committed = true;
+  constructor(snapshot: NavigationSnapshot, causes: unknown[]);
+}
+//#endregion
+export { createActiveLeafCodec as $, list as $n, MiddlewareResult as $t, SessionStore as A, PlatformInfo as An, isCompoundAction as At, ControllerContext as B, ConsoleLoggerFactory as Bn, NavigationPath as Bt, SessionFailure as C, Storage as Cn, ACTION_KINDS as Ct, SessionSlice as D, LocaleInfo as Dn, ExternalUrlAction as Dt, SessionRestoreResult as E, LocaleAttributes as En, CompoundAction as Et, WebRuntime as F, ReportCallback as Fn, LeafNode as Ft, controllerContext as G, InferParams as Gn, SplitColumn as Gt, SERVER_CONTROLLER as H, Logger as Hn, NavigationSnapshot as Ht, WebRuntimeOptions as I, ReportingLogger as In, NAVIGATION_NODE_KINDS as It, resolveConfiguredMessages as J, QuerySchemaMap as Jn, StackNode as Jt, MessagesLoader as K, InferQuery as Kn, SplitNode as Kt, createWebRuntime as L, ReportingLoggerFactory as Ln, NavigationError as Lt, SessionWriteResult as M, BaseController as Mn, isFlowAction as Mt, StorageUnavailableError as N, ControllerFailure as Nn, makeExternalUrlAction as Nt, SessionSnapshot as O, TextDirection as On, FlowAction as Ot, WebConfiguration as P, ControllerInput as Pn, makeFlowAction as Pt, NavigationRouterLike as Q, isMultiValueSchema as Qn, DenyResult as Qt, PageControllerDefinition as R, ReportingLoggerOptions as Rn, NavigationNode as Rt, SessionErrorContext as S, FeatureFlagsProvider as Sn, ActionHandler as St, SessionNavigation as T, resolveMessages as Tn, ActionInvocation as Tt, SERVER_REQUEST as U, LoggerFactory as Un, ResolvedDestination as Ut, PageControllerInput as V, LogFilter as Vn, NavigationPathStep as Vt, ServerRequestState as W, ExtractParamNames as Wn, SPLIT_VISIBILITIES as Wt, FullStateCodecOptions as X, ListOptions as Xn, AfterLoadGuard as Xt, DEFAULT_NAV_PARAM as Y, StripOptional as Yn, TabsNode as Yt, NavigationCodec as Z, MultiValueSchema as Zn, BeforeLoadGuard as Zt, AsyncStorage as _, RouteInput as _n, PrefetchedIntents as _t, NavigationCommitContext as a, deny as an, SerializedSplit as at, SESSION_DEFAULT_VERSION as b, DEP_KEYS as bn, Router as bt, NavigationTransactionContext as c, rewrite as cn, SerializedTabs as ct, createWebSession as d, FINESOFT_PUBLIC as dn, serializeNavigationStable as dt, NavigationContext as en, Intent as er, createFullStateCodec as et, AppSnapshot as f, PublicProjection as fn, PageRoute as ft, WebAppView as g, markPublic as gn, PrefetchedIntent as gt, ViewProps as h, isPublicMarked as hn, route as ht, BeforeNavigateResult as i, RewriteResult as in, SerializedNavigation as it, SessionStoreOptions as j, detectPlatform as jn, isExternalUrlAction as jt, SessionStateProvider as k, Translator as kn, TreeAction as kt, WebSession as l, BASE_PAGE_FIELDS as ln, deserializeNavigation as lt, ViewEntry as m, getPublicFields as mn, RouteDefinition as mt, BeforeCommitResult as n, PostLoadContext as nn, encodeNavigationTreeParam as nt, NavigationCommitError as o, next as on, SerializedSplitColumn as ot, NavigationSummary as p, PublicValueCodec as pn, RenderMode as pt, MessagesLoaderContext as q, ParamsFor as qn, SplitVisibility as qt, BeforeNavigatePolicy as r, RedirectResult as rn, SerializedLeaf as rt, NavigationContextInput as s, redirect as sn, SerializedStack as st, BeforeCommitPolicy as t, NextResult as tn, decodeNavigationTreeParam as tt, WebSessionOptions as u, BasePage as un, serializeNavigation as ut, NavigationScopedState as v, RouteIntent as vn, RouteAddOptions as vt, SessionLoadResult as w, TranslationMessages as wn, Action as wt, SessionError as x, FeatureFlags as xn, ActionDispatcher as xt, SESSION_DEFAULT_KEY as y, RouteParams as yn, RouteMatch as yt, WebAppDefinition as z, ConsoleLogger as zn, NavigationNodeKind as zt };
+//# sourceMappingURL=session-DnB4ZC3x.d.mts.map