@finesoft/front 0.5.0 → 0.5.2

package/dist/browser-JTs2jqVY.d.mts

@@ -1,2811 +0,0 @@
-//#region ../core/src/actions/types.d.ts
-/**
- * Action 类型定义
- *
- * FlowAction — SPA 内部导航
- * ExternalUrlAction — 打开外部链接
- * CompoundAction — 组合多个 Action
- */
-/** Action Kind 常量 */
-declare const ACTION_KINDS: {
-  FLOW: "flow";
-  EXTERNAL_URL: "externalUrl";
-  COMPOUND: "compound";
-};
-/** FlowAction — SPA 导航 */
-interface FlowAction {
-  kind: typeof ACTION_KINDS.FLOW;
-  url: string;
-  /** 展示方式: 默认 push，modal 弹窗 */
-  presentationContext?: "default" | "modal";
-}
-/** ExternalUrlAction — 外部链接 */
-interface ExternalUrlAction {
-  kind: typeof ACTION_KINDS.EXTERNAL_URL;
-  url: string;
-}
-/** CompoundAction — 组合 Action */
-interface CompoundAction {
-  kind: typeof ACTION_KINDS.COMPOUND;
-  actions: Action[];
-}
-/** 所有 Action 的联合类型 */
-type Action = FlowAction | ExternalUrlAction | CompoundAction;
-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 ../core/src/actions/dispatcher.d.ts
-/** Action 处理器函数类型 */
-type ActionHandler<A extends Action = Action> = (action: A) => Promise<void> | void;
-declare class ActionDispatcher {
-  private handlers;
-  /**
-   * 注册指定 kind 的 handler。
-   *
-   * 重复 kind 时保留第一个注册者并发出警告——这是有意设计：
-   * framework 内部 handler 先注册，应用层意外覆盖会被记录而非静默生效。
-   * 如需显式替换，先调用 removeAction(kind)。
-   */
-  onAction<A extends Action>(kind: string, handler: ActionHandler<A>): void;
-  /** 移除指定 kind 的 handler（用于显式覆盖场景） */
-  removeAction(kind: string): boolean;
-  /** 执行一个 Action（CompoundAction 递归展开，有深度限制） */
-  perform(action: Action, _depth?: number): Promise<void>;
-}
-//#endregion
-//#region ../core/src/dependencies/container.d.ts
-/**
- * Container — 通用的依赖注入容器
- */
-type Factory<T> = () => T;
-declare class Container {
-  private registrations;
-  private resolutionStack;
-  private parent?;
-  private children;
-  /** 注册依赖（默认单例） */
-  register<T>(key: string, factory: Factory<T>, singleton?: boolean): this;
-  /** 解析依赖 — 当前容器未注册时回退到 parent */
-  resolve<T>(key: string): T;
-  /** 检查是否已注册（含 parent） */
-  has(key: string): boolean;
-  /**
-   * 移除当前容器的注册（不影响 parent）。
-   *
-   * 用途：在 scope 内显式撤销之前覆写的依赖，避免用 `register(() => null)` 这种
-   * 反语义的写法。被移除的 key 之后再 resolve 会回退到 parent 容器。
-   *
-   * 返回 true 表示当前层确实存在过这个注册并被移除，false 表示未注册（含「只在
-   * parent 注册」的情况，本方法不向上递归删除 —— scope 不应能影响 parent 状态）。
-   */
-  unregister(key: string): boolean;
-  /**
-   * 创建子容器（请求级 scope）
-   *
-   * 子容器可覆写父容器的依赖（如每请求的 locale、user），
-   * 未覆写的 key 自动回退到父容器解析。子容器会被父容器跟踪，
-   * 父容器 dispose 时一并销毁所有未独立 dispose 的子容器。
-   */
-  createScope(): Container;
-  /**
-   * 销毁容器，清除所有缓存。
-   *
-   * - 递归 dispose 所有 createScope() 创建的未 dispose 子容器
-   * - 自身被 dispose 后从父容器移除引用，允许 GC
-   * - 重复 dispose 安全（幂等）
-   */
-  dispose(): void;
-}
-//#endregion
-//#region ../core/src/intents/types.d.ts
-/** Intent — 描述一个用户意图 */
-interface Intent<T = unknown> {
-  /** Intent 标识符（用于匹配 Controller） */
-  id: string;
-  /** 意图参数（path/query 经 codec 转换后可能是 number/boolean 等） */
-  params?: Record<string, unknown>;
-  /** 预期返回的数据（仅用于类型推断） */
-  _returnType?: T;
-}
-/** Intent Controller — 处理特定 intentId 的业务逻辑 */
-interface IntentController<T = unknown> {
-  /** Controller 对应的 Intent ID */
-  intentId: string;
-  /** 执行意图，返回页面数据 */
-  perform(intent: Intent<T>, container: Container): Promise<T> | T;
-}
-//#endregion
-//#region ../core/src/intents/dispatcher.d.ts
-declare class IntentDispatcher {
-  private controllers;
-  /** 注册一个 IntentController */
-  register(controller: IntentController): void;
-  /** 分发 Intent 到对应 Controller */
-  dispatch<T>(intent: Intent<T>, container: Container): Promise<T>;
-  /** 检查是否已注册某个 Intent */
-  has(intentId: string): boolean;
-}
-//#endregion
-//#region ../core/src/http/secure-fetch.d.ts
-/**
- * secureFetch — `fetch` with SSRF defense baked in.
- *
- * Wraps an existing fetch implementation and refuses targets that resolve to
- * private / loopback / reserved ranges. Use when your controller fetches a
- * URL that the user can influence (image proxies, link previews, callbacks).
- *
- * Defaults to checking IP literals (sync) AND resolving hostnames via DNS
- * (Node only; silently skipped in browsers). Pass `allowInternalHosts: true`
- * to opt out — for example, when you have a legitimate server-to-server call
- * to 10.x or 127.0.0.1 and you trust the URL source.
- *
- * @example
- * ```ts
- * import { secureFetch, DEP_KEYS } from "@finesoft/front";
- *
- * class ShareController extends BaseController<{ next?: string }, Page> {
- *     async execute(params, container) {
- *         const baseFetch = container.resolve<typeof globalThis.fetch>(DEP_KEYS.FETCH);
- *         const fetch = secureFetch(baseFetch);
- *         const response = await fetch(params.next ?? "https://example.com");
- *         ...
- *     }
- * }
- * ```
- */
-interface SecureFetchOptions {
-  /** Opt out of SSRF defense entirely (default false). */
-  allowInternalHosts?: boolean;
-  /** DNS-resolve hostnames and check each resolved IP (default true, Node only). */
-  validateDns?: boolean;
-}
-/**
- * Return a `fetch`-shaped function that refuses requests to private hosts
- * before calling through to `baseFetch`.
- */
-declare function secureFetch(baseFetch: typeof globalThis.fetch, options?: SecureFetchOptions): typeof globalThis.fetch;
-//#endregion
-//#region ../core/src/logger/types.d.ts
-/** 日志级别 */
-type Level = "debug" | "info" | "warn" | "error";
-/**
- * Logger 接口
- *
- * 所有方法返回空字符串，允许在模板中内联使用而不渲染文本。
- */
-interface Logger {
-  debug(...args: unknown[]): string;
-  info(...args: unknown[]): string;
-  warn(...args: unknown[]): string;
-  error(...args: unknown[]): string;
-}
-interface LoggerFactory {
-  loggerFor(category: string): Logger;
-}
-//#endregion
-//#region ../core/src/logger/base.d.ts
-declare abstract class BaseLogger implements Logger {
-  protected category: string;
-  constructor(category: string);
-  abstract debug(...args: unknown[]): string;
-  abstract info(...args: unknown[]): string;
-  abstract warn(...args: unknown[]): string;
-  abstract error(...args: unknown[]): string;
-}
-//#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 extends BaseLogger {
-  private readonly minPriority;
-  private readonly report;
-  constructor(category: string, options: ReportingLoggerOptions);
-  debug(...args: unknown[]): string;
-  info(...args: unknown[]): string;
-  warn(...args: unknown[]): string;
-  error(...args: unknown[]): string;
-  private maybeReport;
-}
-declare class ReportingLoggerFactory implements LoggerFactory {
-  private readonly options;
-  constructor(options: ReportingLoggerOptions);
-  loggerFor(category: string): Logger;
-}
-//#endregion
-//#region ../core/src/metrics/types.d.ts
-/**
- * Metrics — 类型定义
- *
- * 框架级埋点基础设施的核心接口。
- */
-/** 事件记录器 — 所有 metrics 后端实现此接口 */
-interface EventRecorder {
-  /** 记录一条事件 */
-  record(type: string, fields?: Record<string, unknown>): void;
-  /** 刷新待发送的事件队列 */
-  flush?(): Promise<void>;
-  /** 销毁记录器，释放资源 */
-  destroy?(): void;
-}
-/** 字段提供者 — 每次记录前自动注入公共字段 */
-interface MetricsFieldsProvider {
-  /** 返回需要附加到每条事件的字段 */
-  getFields(): Record<string, unknown>;
-}
-/** Impression 条目 */
-interface ImpressionEntry {
-  /** 被追踪元素的唯一标识 */
-  id: string;
-  /** 元素进入视口的时间戳 */
-  timestamp: number;
-  /** 附加数据 */
-  metadata?: Record<string, unknown>;
-}
-/** Impression 观察器 — 追踪元素可见性 */
-interface ImpressionObserver {
-  /** 开始追踪一个元素 */
-  observe(element: Element, id: string, metadata?: Record<string, unknown>): void;
-  /** 停止追踪一个元素 */
-  unobserve(element: Element): void;
-  /** 获取已捕获的曝光并清空 */
-  consume(): ImpressionEntry[];
-  /** 销毁观察器 */
-  destroy(): void;
-}
-//#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 字符串（默认取 navigator.userAgent）
- */
-declare function detectPlatform(ua?: string): PlatformInfo;
-//#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;
-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>;
-/**
- * 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 Net {
-  fetch(url: string, options?: RequestInit): Promise<Response>;
-}
-/** 存储接口 */
-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;
-}
-/** Metrics 记录器 */
-interface MetricsRecorder {
-  /** 记录一条事件（通用方法） */
-  record(type: string, fields?: Record<string, unknown>): void;
-  /** 记录页面访问（便捷方法） */
-  recordPageView(page: string, fields?: Record<string, unknown>): void;
-  /** 记录自定义事件（便捷方法） */
-  recordEvent(name: string, fields?: Record<string, unknown>): void;
-  /** 刷新待发送队列 */
-  flush?(): Promise<void>;
-  /** 销毁记录器 */
-  destroy?(): void;
-}
-declare const DEP_KEYS: {
-  readonly LOGGER: "logger";
-  readonly LOGGER_FACTORY: "loggerFactory";
-  readonly NET: "net";
-  readonly STORAGE: "storage";
-  readonly FEATURE_FLAGS: "featureFlags";
-  readonly METRICS: "metrics";
-  readonly FETCH: "fetch";
-  /**
-   * `fetch` 包了 SSRF 防护（拒绝 private / loopback / 保留 IP + DNS resolve 后逐 IP 校验）。
-   * 当 controller 用用户可控的 URL 发起请求（图片代理、链接预览、回调等），
-   * 优先 resolve 这个 key 而不是 `FETCH`。要 opt-out 可手动调 `secureFetch(baseFetch, { allowInternalHosts: true })`。
-   */
-  readonly SAFE_FETCH: "safeFetch";
-  readonly EVENT_RECORDER: "eventRecorder";
-  readonly LOCALE: "locale";
-  readonly PLATFORM: "platform";
-  readonly TRANSLATOR: "translator";
-};
-interface MakeDependenciesOptions {
-  fetch?: typeof globalThis.fetch;
-  featureFlags?: Record<string, boolean | string | number>;
-  /** 外部 feature flags providers（远程配置、A/B 测试等） */
-  featureFlagsProviders?: FeatureFlagsProvider[];
-  /** 日志上报回调 — 提供后自动组合 ReportingLoggerFactory */
-  reportCallback?: ReportCallback;
-  /** 自定义 EventRecorder（默认 ConsoleEventRecorder） */
-  eventRecorder?: EventRecorder;
-  /** 语言代码（如 "zh-Hans"、"en-US"），用于注入 locale 信息 */
-  locale?: string;
-  /** 自定义 PlatformInfo（默认通过 UA 自动检测） */
-  platform?: PlatformInfo;
-  /**
-   * 覆盖 `DEP_KEYS.SAFE_FETCH` 默认行为。比如服务正常需要打内网，可以传
-   * `{ allowInternalHosts: true }` 整体放行；或自定义 DNS 校验策略。
-   */
-  safeFetch?: SecureFetchOptions;
-}
-declare function makeDependencies(container: Container, options?: MakeDependenciesOptions): void;
-//#endregion
-//#region ../core/src/dependencies/request-scoped-key.d.ts
-/** Anything that exposes the per-request DI container — covers NavigationContext, PostLoadContext, and raw Container. */
-type ContainerHolder = Container | {
-  container: Container;
-};
-interface RequestScopedKey<T> {
-  /** The underlying string key registered with the Container. */
-  readonly key: string;
-  /** Write the current request's value. Overwrites any prior registration. */
-  set(target: ContainerHolder, value: T): void;
-  /** Read the current request's value, or `undefined` if not set. */
-  get(target: ContainerHolder): T | undefined;
-  /**
-   * Remove the registration from this request's container. Subsequent `get`
-   * calls return `undefined`. Returns true if the key existed.
-   */
-  clear(target: ContainerHolder): boolean;
-}
-/**
- * Define a typed, request-scoped DI key.
- *
- * The returned object's `set`/`get`/`clear` work against the container belonging
- * to the request you hand in — typically `ctx.container` from a middleware or
- * the `container` argument inside `BaseController.execute`.
- */
-declare function defineRequestScopedKey<T>(key: string): RequestScopedKey<T>;
-//#endregion
-//#region ../core/src/models/page.d.ts
-/**
- * BasePage — 所有页面共享的基础属性
- *
- * 具体页面类型由应用层定义并扩展此接口。
- *
- * SSR prefetch 数据序列化时的可见性由 `FINESOFT_PUBLIC` symbol 控制 —— 见
- * `markPublic` / `isPublicMarked`。没有 marker 时 `serializeServerData` 仍按全字段
- * 序列化（向后兼容），但会在 dev 启动后打印一次告警，下一个 major 会改为只序列化
- * `BasePage` 的标准字段（id/pageType/title/description/url）。
- */
-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` 表示「所有字段都安全」—— 当作 opt-out，等价于不调用本函数。
- */
-declare function markPublic<P extends BasePage>(page: P, publicFields: readonly (keyof P)[] | true): P;
-/** True 如果 page 用 `markPublic` 显式标过。 */
-declare function isPublicMarked(page: unknown): boolean;
-/** 取出 `markPublic` 写入的字段白名单；`true` 表示全开放，`null` 表示未标注。 */
-declare function getPublicFields(page: unknown): readonly string[] | true | null;
-//#endregion
-//#region ../core/src/middleware/types.d.ts
-/** 导航上下文（beforeLoad 阶段可用） */
-interface NavigationContext {
-  /** 完整 URL（path + query） */
-  readonly url: string;
-  /** 仅路径部分 */
-  readonly path: string;
-  /** 路由参数 + 查询参数（codec 转换后可能是 number/boolean 等） */
-  readonly params: Record<string, unknown>;
-  /** 匹配的 Intent */
-  readonly intent: Intent;
-  /** 是否在服务端运行 */
-  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 ../core/src/router/params/standard.d.ts
-/**
- * Standard Schema v1 接口的最小本地声明 + 运行助手。
- * 纯 type-level 规范 + 运行时鸭子类型，不依赖 @standard-schema/spec 运行时包。
- * https://standardschema.dev
- */
-interface StandardSchemaV1<Input = unknown, Output = Input> {
-  readonly "~standard": {
-    readonly version: 1;
-    readonly vendor: string;
-    readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>;
-    readonly types?: {
-      readonly input: Input;
-      readonly output: Output;
-    };
-  };
-}
-type StandardResult<Output> = {
-  readonly value: Output;
-  readonly issues?: undefined;
-} | {
-  readonly issues: ReadonlyArray<StandardIssue>;
-};
-interface StandardIssue {
-  readonly message: string;
-  readonly path?: ReadonlyArray<PropertyKey | {
-    readonly key: PropertyKey;
-  }>;
-}
-/** 提取 Standard Schema 的输出类型 */
-type InferOutput<S extends StandardSchemaV1> = NonNullable<S["~standard"]["types"]>["output"];
-/** 路由参数 codec：输入恒为 string（缺失时 undefined），输出为目标类型 T */
-type ParamSchema<T = unknown> = StandardSchemaV1<string, T>;
-/** 工厂：从一个 validate 函数构造实现了 ~standard 的 codec */
-declare function makeSchema<T>(validate: (value: unknown) => StandardResult<T> | Promise<StandardResult<T>>): ParamSchema<T>;
-/** 统一执行任意 Standard Schema 的校验，吸收同步/异步差异（raw 可为单值或多值 query） */
-declare function runStandard(schema: StandardSchemaV1, raw: string | string[] | undefined): Promise<{
-  ok: true;
-  value: unknown;
-} | {
-  ok: false;
-  issues: readonly StandardIssue[];
-}>;
-//#endregion
-//#region ../core/src/router/params/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/router/params/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> = { [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 InferParams<P extends Record<string, ParamSchema>> = Prettify<{ [K in RequiredOutKeys<P>]: InferOutput<P[K]> } & { [K in OptionalOutKeys<P>]?: Exclude<InferOutput<P[K]>, undefined> }>;
-type InferQuery<Q extends QuerySchemaMap> = Prettify<{ [K in RequiredOutKeys<Q>]: InferOutput<Q[K]> } & { [K in OptionalOutKeys<Q>]?: Exclude<InferOutput<Q[K]>, undefined> }>;
-//#endregion
-//#region ../core/src/router/router.d.ts
-/** 路由匹配结果 */
-interface RouteMatch {
-  intent: Intent;
-  action: FlowAction;
-  renderMode?: string;
-  /** 该路由绑定的 beforeLoad 守卫 */
-  beforeGuards?: BeforeLoadGuard[];
-  /** 该路由绑定的 afterLoad 守卫 */
-  afterGuards?: AfterLoadGuard[];
-}
-/** 路由添加选项 */
-interface RouteAddOptions {
-  renderMode?: string;
-  beforeGuards?: BeforeLoadGuard[];
-  afterGuards?: AfterLoadGuard[];
-  paramCodecs?: Record<string, ParamSchema>;
-  queryCodecs?: QuerySchemaMap;
-}
-declare class Router {
-  private readonly debug?;
-  private routes;
-  constructor(debug?: ((message: string) => void) | undefined);
-  /** 添加路由规则 */
-  add(pattern: string, intentId: string, renderModeOrOptions?: string | RouteAddOptions): this;
-  /** 解析 URL → RouteMatch（含参数校验；校验失败则 fall-through 到下一条路由） */
-  resolve(urlOrPath: string): Promise<RouteMatch | null>;
-  /** 获取所有已注册的路由 */
-  getRoutes(): string[];
-  private parseUrl;
-}
-//#endregion
-//#region ../core/src/router/types.d.ts
-/**
- * Router 共享类型
- *
- * `RouteParams` 是路由参数（path + query 经 codec 转换后）的统一形状，
- * 同时也是 Intent.params、NavigationContext.params 与 LeafNode.params 的共同类型。
- */
-/** 路由参数：键为参数名，值为 codec 转换后的任意类型（string / number / boolean …）。 */
-type RouteParams = Record<string, unknown>;
-//#endregion
-//#region ../core/src/router/params/primitives.d.ts
-interface StrOptions {
-  minLength?: number;
-  maxLength?: number;
-  pattern?: RegExp;
-}
-declare function str(opts?: StrOptions): ParamSchema<string>;
-interface NumOptions {
-  min?: number;
-  max?: number;
-}
-declare function int(opts?: NumOptions): ParamSchema<number>;
-declare function num(opts?: NumOptions): ParamSchema<number>;
-declare function bool(): ParamSchema<boolean>;
-declare function oneOf<const T extends readonly string[]>(values: T): ParamSchema<T[number]>;
-declare function uuid(): ParamSchema<string>;
-//#endregion
-//#region ../core/src/router/params/modifiers.d.ts
-/** 输入缺失（undefined）时跳过校验、产出 undefined；否则委托内部 codec（同步或异步均可）。 */
-declare function optional<T>(codec: ParamSchema<T>): ParamSchema<T | undefined>;
-/** 输入缺失时用 fallback；否则委托内部 codec。 */
-declare function withDefault<T>(codec: ParamSchema<T>, fallback: T): ParamSchema<T>;
-//#endregion
-//#region ../core/src/logger/composite.d.ts
-declare class CompositeLoggerFactory implements LoggerFactory {
-  private readonly factories;
-  constructor(factories: LoggerFactory[]);
-  loggerFor(name: string): Logger;
-}
-declare class CompositeLogger implements Logger {
-  private readonly loggers;
-  constructor(loggers: Logger[]);
-  debug(...args: unknown[]): string;
-  info(...args: unknown[]): string;
-  warn(...args: unknown[]): string;
-  error(...args: unknown[]): string;
-  private callAll;
-}
-//#endregion
-//#region ../core/src/logger/console.d.ts
-declare class ConsoleLogger extends BaseLogger {
-  debug(...args: unknown[]): string;
-  info(...args: unknown[]): string;
-  warn(...args: unknown[]): string;
-  error(...args: unknown[]): string;
-}
-declare class ConsoleLoggerFactory implements LoggerFactory {
-  loggerFor(category: string): Logger;
-}
-//#endregion
-//#region ../core/src/logger/local-storage-filter.d.ts
-declare function shouldLog(name: string, level: Level): boolean;
-declare function resetFilterCache(): void;
-//#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/prefetched-intents/prefetched-intents.d.ts
-/** 预获取的 Intent-Data 对 */
-interface PrefetchedIntent {
-  intent: Intent;
-  data: unknown;
-}
-declare class PrefetchedIntents {
-  private intents;
-  private constructor();
-  /** 从 PrefetchedIntent 数组创建缓存实例 */
-  static fromArray(items: PrefetchedIntent[]): PrefetchedIntents;
-  /** 创建空缓存实例 */
-  static empty(): PrefetchedIntents;
-  /**
-   * 获取缓存的 Intent 结果（一次性使用）。
-   * 命中后从缓存中删除。
-   */
-  get<T>(intent: Intent<T>): T | undefined;
-  /** 检查缓存中是否有某个 Intent 的数据 */
-  has(intent: Intent): boolean;
-  /** 缓存中的条目数 */
-  get size(): number;
-}
-//#endregion
-//#region ../core/src/framework.d.ts
-/** Framework 初始化配置 */
-interface FrameworkConfig extends MakeDependenciesOptions {
-  setupRoutes?: (router: Router) => void;
-  prefetchedIntents?: PrefetchedIntents;
-}
-declare class Framework {
-  readonly container: Container;
-  readonly intentDispatcher: IntentDispatcher;
-  readonly actionDispatcher: ActionDispatcher;
-  readonly router: Router;
-  readonly prefetchedIntents: PrefetchedIntents;
-  private readonly beforeGuards;
-  private readonly afterGuards;
-  private _logger?;
-  private constructor();
-  /** 创建并初始化 Framework 实例 */
-  static create(config?: FrameworkConfig): Framework;
-  private getLogger;
-  /** 分发 Intent — 获取页面数据 */
-  dispatch<T>(intent: Intent<T>): Promise<T>;
-  /** 执行 Action — 处理用户交互 */
-  perform(action: Action): Promise<void>;
-  /** 路由 URL — 将 URL 解析为 Intent + Action */
-  routeUrl(url: string): Promise<RouteMatch | null>;
-  /** 记录页面访问事件 */
-  didEnterPage(page: BasePage): void;
-  /** 获取 locale 信息（如果已配置） */
-  getLocale(): LocaleAttributes | undefined;
-  /** 获取翻译器（如果当前 locale 已经初始化了翻译字典） */
-  getTranslator(): Translator | undefined;
-  /** 获取平台信息 */
-  getPlatform(): PlatformInfo;
-  /** 注册 Action 处理器 */
-  onAction<A extends Action>(kind: string, handler: ActionHandler<A>): void;
-  /** 注册 Intent Controller */
-  registerIntent(controller: IntentController): void;
-  /** 注册 beforeLoad 守卫（路由匹配后、数据加载前） */
-  beforeLoad(guard: BeforeLoadGuard): void;
-  /** 注册 afterLoad 守卫（数据加载后、渲染前） */
-  afterLoad(guard: AfterLoadGuard): void;
-  /** 执行所有 beforeLoad 守卫（全局 → 路由级） */
-  runBeforeLoad(ctx: NavigationContext, routeGuards?: BeforeLoadGuard[]): Promise<MiddlewareResult>;
-  /** 执行所有 afterLoad 守卫（全局 → 路由级） */
-  runAfterLoad(ctx: PostLoadContext, routeGuards?: AfterLoadGuard[]): Promise<MiddlewareResult>;
-  /** 销毁 Framework 实例 */
-  dispose(): void;
-}
-//#endregion
-//#region ../core/src/models/safe-error-page.d.ts
-interface SafeErrorPageOptions {
-  /** HTTP-style status code used in the page title (e.g. 404, 500). */
-  status: number;
-  /**
-   * The message users / client code may safely see in production. Should
-   * contain no stack, file paths, hostnames, or secrets.
-   */
-  publicMessage: string;
-  /**
-   * Optional error / debug payload to surface only in non-production. In
-   * production this is dropped entirely; only `publicMessage` is exposed.
-   */
-  devError?: unknown;
-  /**
-   * Override the production detection. Pass `true` to force the prod-safe
-   * variant (drops devError). Defaults to detecting `process.env.NODE_ENV`.
-   */
-  isProduction?: boolean;
-}
-/**
- * Build a BasePage for an error condition. In production, only `publicMessage`
- * makes it into the page. In dev, `devError` (if provided) is appended.
- */
-declare function safeErrorPage(options: SafeErrorPageOptions): BasePage;
-//#endregion
-//#region ../core/src/models/shelf.d.ts
-interface BaseShelf {
-  id: string;
-  shelfType: string;
-  title?: string;
-  subtitle?: string;
-  seeAllAction?: Action;
-  isHorizontal?: boolean;
-}
-interface BaseItem {
-  id: string;
-  itemType: string;
-  clickAction?: Action;
-}
-//#endregion
-//#region ../core/src/prefetched-intents/stable-stringify.d.ts
-/**
- * stableStringify — 确定性 JSON 序列化（keys 按字母排序）
- *
- * 用作缓存 key：相同内容的对象始终产生相同字符串。
- */
-declare function stableStringify(obj: unknown): string;
-//#endregion
-//#region ../core/src/http/client.d.ts
-/**
- * HttpClient — 通用 HTTP 客户端基类
- *
- * 为 API Client 提供标准化的 HTTP 请求能力。
- * 子类继承后只需关注业务端点定义，不需要重复实现 fetch / JSON 解析 / 错误处理。
- *
- * 默认安全：拒绝向内网 / loopback / 保留地址发请求（SSRF 防御）。应用层
- * 显式 opt-out 用 `allowInternalHosts: true`。详见 host-guard.ts。
- */
-/** HTTP 请求错误 */
-declare class HttpError extends Error {
-  readonly status: number;
-  readonly statusText: string;
-  readonly body?: string | undefined;
-  constructor(status: number, statusText: string, body?: string | undefined);
-}
-/**
- * SSRF 防护拦截到不安全的目标地址时抛出。应用层可以 catch 它来给出业务友好的错误，
- * 不需要靠 message 字符串匹配。
- */
-declare class HostGuardError extends Error {
-  readonly url: string;
-  readonly reason: string;
-  constructor(url: string, reason: string);
-}
-/** 请求拦截器 — 在发送前修改请求 */
-interface RequestInterceptor {
-  (url: string, init: RequestInit): RequestInit | Promise<RequestInit>;
-}
-/** 响应拦截器 — 在解析前修改响应 */
-interface ResponseInterceptor {
-  (response: Response, url: string): Response | Promise<Response>;
-}
-/** HttpClient 构造配置 */
-interface HttpClientConfig {
-  /** API base URL（如 "/api" 或 "https://example.com/api"） */
-  baseUrl: string;
-  /** 默认请求头 */
-  defaultHeaders?: Record<string, string>;
-  /** 自定义 fetch 实现（便于测试或 SSR） */
-  fetch?: typeof globalThis.fetch;
-  /** 请求拦截器（按注册顺序执行） */
-  requestInterceptors?: RequestInterceptor[];
-  /** 响应拦截器（按注册顺序执行） */
-  responseInterceptors?: ResponseInterceptor[];
-  /**
-   * 是否允许向私有 / loopback / 保留 IP 段发请求。
-   *
-   * **默认 false** —— 阻止内网穿透（SSRF）。如果你的服务正常需要打内网（如
-   * 微服务对内 API、127.0.0.1 上的开发依赖），把它设为 true 显式 opt-out，并
-   * 自己做来源校验。
-   */
-  allowInternalHosts?: boolean;
-  /**
-   * 是否在请求前 DNS 解析 hostname 并对解析结果做 IP 段校验。
-   *
-   * **默认 true**（仅 Node 环境有效；浏览器静默跳过）。配合 `allowInternalHosts`
-   * 防御 DNS rebinding：如果 hostname 不是 IP 字面量，框架会 resolve 它的 A/AAAA
-   * 记录并按 IP 段校验。`false` 关闭只剩 IP 字面量同步校验。
-   */
-  validateDns?: boolean;
-}
-/**
- * 通用 HTTP 客户端基类
- *
- * 使用方式: 创建子类继承 HttpClient，定义业务方法调用 this.get() / this.post() 等。
- *
- * @example
- * ```ts
- * class MyApiClient extends HttpClient {
- *   async getUser(id: string) {
- *     return this.get<User>(`/users/${id}`);
- *   }
- * }
- * ```
- */
-declare abstract class HttpClient {
-  protected readonly baseUrl: string;
-  protected readonly defaultHeaders: Record<string, string>;
-  protected readonly fetchFn: typeof globalThis.fetch;
-  private readonly requestInterceptors;
-  private readonly responseInterceptors;
-  private readonly allowInternalHosts;
-  private readonly validateDns;
-  constructor(config: HttpClientConfig);
-  /** 动态添加请求拦截器 */
-  useRequestInterceptor(interceptor: RequestInterceptor): this;
-  /** 动态添加响应拦截器 */
-  useResponseInterceptor(interceptor: ResponseInterceptor): this;
-  /** GET 请求，返回解析后的 JSON */
-  protected get<T>(path: string, params?: Record<string, string>): Promise<T>;
-  /** POST 请求，自动序列化 body 为 JSON */
-  protected post<T>(path: string, body?: unknown, params?: Record<string, string>): Promise<T>;
-  /** PUT 请求 */
-  protected put<T>(path: string, body?: unknown, params?: Record<string, string>): Promise<T>;
-  /** DELETE 请求 */
-  protected del<T>(path: string, params?: Record<string, string>): Promise<T>;
-  /**
-   * 底层请求方法 — 子类可覆写以自定义行为
-   *
-   * 自动处理:
-   * - URL 拼接 (baseUrl + path + params)
-   * - SSRF 防护（IP 字面量同步校验 + 可选 DNS 解析校验）
-   * - 默认 headers 合并
-   * - JSON body 序列化
-   * - 响应 JSON 解析
-   * - 非 2xx 状态码抛出 HttpError
-   */
-  protected request<T>(method: string, path: string, options?: {
-    params?: Record<string, string>;
-    body?: unknown;
-    headers?: Record<string, string>;
-  }): Promise<T>;
-  /** 构建完整 URL — 子类可覆写以自定义 URL 拼接逻辑 */
-  protected buildUrl(path: string, params?: Record<string, string>): string;
-  private enforceHostGuard;
-}
-//#endregion
-//#region ../core/src/http/host-guard.d.ts
-/**
- * host-guard — refuse outbound requests to private / loopback / reserved hosts.
- *
- * Why this exists: `HttpClient` and the raw `fetch` injected via DI both used
- * to accept any URL the application built. SSR controllers that take a
- * user-controlled URL (image proxy, link preview, OAuth callback) could be
- * tricked into fetching `http://127.0.0.1/admin` and embedding the response in
- * the SSR HTML. Round 1 of the adversarial drill walked straight through this;
- * round 2's hand-rolled IPv4 regex was bypassed in five minutes with
- * `[::ffff:7f00:1]`. This module centralises the check so applications can stop
- * re-implementing it (badly).
- *
- * Coverage (synchronous, IP-literal forms):
- * - IPv4 dotted-decimal: `127.0.0.1`, `10.0.0.5`, `192.168.1.1`, `172.16.0.1`
- * - IPv4 zero / link-local / multicast / reserved: `0.0.0.0`, `169.254.0.1`,
- *   `224.0.0.1`, `240.0.0.0/4`
- * - IPv4 non-dotted forms accepted by some parsers: decimal `2130706433`,
- *   hex `0x7f000001`, octal `0177.0.0.1`
- * - IPv6 loopback `::1`, link-local `fe80::/10`, ULA `fc00::/7`, unspecified `::`
- * - IPv4-mapped IPv6: `::ffff:7f00:1`, `::ffff:127.0.0.1`
- * - Names: `localhost`, `*.localhost`
- *
- * NOT covered here (callers can layer on top):
- * - DNS resolution of arbitrary hostnames — see `validateUrlWithDns` in
- *   server-only callers. DNS rebinding is impossible to fix at this layer
- *   alone; the right pattern is "resolve once, then fetch by IP".
- * - IDN / homograph attacks — Node's URL parser punycode-encodes hostnames
- *   already, so the hostname this code sees is the ASCII form.
- */
-type HostCheckResult = {
-  ok: true;
-} | {
-  ok: false;
-  reason: string;
-};
-/**
- * Inspect a hostname string (the `URL.hostname` value, without brackets, port,
- * or userinfo). Returns `{ok: false}` for anything in a private/loopback/
- * reserved range; `{ok: true}` if the literal looks like a public address or a
- * non-IP name (the caller may then DNS-resolve and re-check).
- */
-declare function classifyHost(rawHost: string): HostCheckResult;
-/**
- * Convenience wrapper for callers holding a full URL string. Also rejects
- * non-http(s) schemes (gopher, file, data, …).
- */
-declare function classifyUrl(rawUrl: string): HostCheckResult;
-//#endregion
-//#region ../core/src/intents/base-controller.d.ts
-/**
- * 抽象 Controller 基类
- *
- * 统一处理:
- * - 类型安全的参数提取 (TParams)
- * - 返回类型约束 (TResult)
- * - try/catch 错误处理 + 可选 fallback
- *
- * @example
- * ```ts
- * class ProductController extends BaseController<{ productId: string }, ProductPage> {
- *   readonly intentId = "product-page";
- *
- *   async execute(params: { productId: string }, container: Container) {
- *     const api = container.resolve<ApiClient>("api");
- *     return api.getProduct(params.productId);
- *   }
- *
- *   fallback(params: { productId: string }, error: Error) {
- *     return getMockProduct(params.productId);
- *   }
- * }
- * ```
- */
-declare abstract class BaseController<TParams extends Record<string, unknown> = Record<string, unknown>, TResult = unknown> implements IntentController<TResult> {
-  /** Controller 对应的 Intent ID */
-  abstract readonly intentId: string;
-  /**
-   * 执行业务逻辑 — 子类必须实现
-   *
-   * @param params - Intent 参数（已类型化）
-   * @param container - DI 容器
-   * @returns 页面数据
-   */
-  abstract execute(params: TParams, container: Container): Promise<TResult> | TResult;
-  /**
-   * 错误回退 — 子类可选覆写
-   *
-   * 当 execute() 抛出异常时调用。
-   * 默认行为: 重新抛出原始错误。
-   *
-   * @param params - Intent 参数
-   * @param error - execute() 抛出的错误
-   * @returns 回退数据
-   */
-  fallback(params: TParams, error: Error): Promise<TResult> | TResult;
-  /**
-   * IntentController.perform() 实现
-   *
-   * 自动 try/catch → fallback 模式。
-   */
-  perform(intent: Intent<TResult>, container: Container): Promise<TResult>;
-}
-//#endregion
-//#region ../core/src/data/mapper.d.ts
-/**
- * Mapper 类型工具 — 标准化数据转换管线
- *
- * 提供类型约定和组合函数，让 API 响应 → 页面模型 的转换有统一的签名模式。
- */
-/** 同步映射函数 */
-type Mapper<TInput, TOutput> = (input: TInput) => TOutput;
-/** 异步映射函数 */
-type AsyncMapper<TInput, TOutput> = (input: TInput) => TOutput | Promise<TOutput>;
-/**
- * 组合两个同步 Mapper: A → B → C
- */
-declare function pipe<A, B, C>(m1: Mapper<A, B>, m2: Mapper<B, C>): Mapper<A, C>;
-/**
- * 组合三个同步 Mapper: A → B → C → D
- */
-declare function pipe<A, B, C, D>(m1: Mapper<A, B>, m2: Mapper<B, C>, m3: Mapper<C, D>): Mapper<A, D>;
-/**
- * 组合四个同步 Mapper: A → B → C → D → E
- */
-declare function pipe<A, B, C, D, E>(m1: Mapper<A, B>, m2: Mapper<B, C>, m3: Mapper<C, D>, m4: Mapper<D, E>): Mapper<A, E>;
-/**
- * 组合任意数量的同步 Mapper
- */
-declare function pipe(...mappers: Mapper<unknown, unknown>[]): Mapper<unknown, unknown>;
-/**
- * 组合两个可能异步的 Mapper: A → B → C
- */
-declare function pipeAsync<A, B, C>(m1: AsyncMapper<A, B>, m2: AsyncMapper<B, C>): AsyncMapper<A, C>;
-/**
- * 组合三个可能异步的 Mapper
- */
-declare function pipeAsync<A, B, C, D>(m1: AsyncMapper<A, B>, m2: AsyncMapper<B, C>, m3: AsyncMapper<C, D>): AsyncMapper<A, D>;
-/**
- * 将一个 Mapper 应用到数组的每个元素
- */
-declare function mapEach<TInput, TOutput>(mapper: Mapper<TInput, TOutput>): Mapper<TInput[], TOutput[]>;
-//#endregion
-//#region ../core/src/navigation/types.d.ts
-/**
- * 导航树里 `Page` 的别名 —— 运行期 dispatch 始终产出 `BasePage`，
- * 但导航层对内容无关，字段语义由应用决定。
- */
-type Page = BasePage;
-/** 导航节点 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];
-/** 叶子：一个具体导航目标 */
-interface LeafNode {
-  readonly kind: typeof NAVIGATION_NODE_KINDS.LEAF;
-  readonly intent: string;
-  readonly params: 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 intent: string;
-  readonly params: RouteParams;
-  readonly page: Page;
-  readonly status?: number;
-}
-/** 导航快照：当前树 + 所有可见目标解析结果（顺序与 collectVisibleDestinations 一致） */
-interface NavigationSnapshot {
-  readonly tree: NavigationNode;
-  readonly destinations: readonly ResolvedDestination[];
-}
-/** 错误类型：序列化 / 路径 / 操作非法时抛出 */
-declare class NavigationError extends Error {
-  constructor(message: string);
-}
-//#endregion
-//#region ../core/src/navigation/nodes.d.ts
-/** 构造叶子节点（一个具体导航目标）。 */
-declare function leaf(intent: string, params?: RouteParams): LeafNode;
-/**
- * 构造栈节点。
- * 接受单个根节点（栈仅含根）或一个 entries 数组（entries[0]=根，末尾=栈顶）。
- *
- * @example
- * stack(leaf("home"))                       // 单根栈
- * stack([leaf("home"), leaf("detail")])     // 根 + 栈顶
- */
-declare function stack(rootOrEntries: NavigationNode | readonly NavigationNode[]): StackNode;
-/** tabs 构造选项 */
-interface TabsInit {
-  /** 当前激活分支键 */
-  readonly active: string;
-  /** 分支映射（键 → 子节点） */
-  readonly branches: Readonly<Record<string, NavigationNode>>;
-  /** 稳定顺序；缺省时按 branches 的插入顺序推导 */
-  readonly order?: readonly string[];
-}
-/**
- * 构造 Tabs 节点。
- * 缺省 `order` 时按 `branches` 的插入顺序（`Object.keys`）推导稳定顺序。
- */
-declare function tabs(init: TabsInit): TabsNode;
-/** split 列初始化（content 可缺省 = 尚未选择） */
-interface SplitColumnInit {
-  readonly id: string;
-  readonly content?: NavigationNode;
-}
-/**
- * 构造 Split 节点（多列并存）。
- * `visibility` 缺省（不写字段）等价 `automatic` = 全列可见；
- * 显式传入时纳入节点状态，影响 `collectVisibleDestinations` 与 SSR 预取。
- *
- * @example
- * split([{ id: "sidebar", content: leaf("folders") }, { id: "detail" }])
- * split([...], "detailOnly")   // 深链：仅 detail 列可见
- */
-declare function split(columns: readonly SplitColumnInit[], visibility?: SplitVisibility): SplitNode;
-declare function isLeafNode(node: NavigationNode): node is LeafNode;
-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
-/**
- * 解析「激活路径」：从根沿可见分支一路向下，直到叶子或无法继续。
- * - leaf：路径在此结束
- * - stack：进入栈顶 entry
- * - tabs：进入 active 分支
- * - split：进入最后一个有内容的列（无任何内容则结束）
- */
-declare function resolveActivePath(tree: NavigationNode): NavigationPath;
-/**
- * 按路径定位节点；任一步无效（索引越界 / 键不存在 / 列为空 / kind 不匹配）返回 undefined。
- */
-declare function findNode(tree: NavigationNode, path: NavigationPath): NavigationNode | undefined;
-/**
- * 找到 target 处（默认激活路径）「at/under」最近的 StackNode 路径。
- * 从 target 节点沿激活分支向下，返回第一个遇到的 StackNode 的完整路径；
- * 找不到则返回 undefined。
- */
-declare function findNearestStack(tree: NavigationNode, path: NavigationPath): NavigationPath | undefined;
-/**
- * 收集所有可见的叶子目标（顺序即渲染/解析顺序）。
- * - leaf → [leaf]
- * - stack → 栈顶 entry 的可见目标
- * - tabs → active 分支的可见目标
- * - 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 由调用方处理）。
- *
- * - `automatic`（缺省）/ `all`：全部列。
- * - `doubleColumn`：首列 + 末列（三列时隐藏中间 content 列；列数 ≤ 2 时等价全部）。
- * - `detailOnly`：仅末列（detail）。
- *
- * 应用渲染时也可用它决定该画哪几列，无需自行重实现可见性映射。
- */
-declare function visibleSplitColumns(node: SplitNode): readonly SplitColumn[];
-/** 在目标栈（默认激活栈，或 target「at/under」最近的 stack）顶部 push 一个节点。 */
-declare function push(tree: NavigationNode, node: NavigationNode, target?: NavigationPath): NavigationNode;
-/** 从 target 处最近的 stack 弹出 count 个 entry（默认 1）；绝不弹到根 entry 之下。 */
-declare function pop(tree: NavigationNode, count?: number, target?: NavigationPath): NavigationNode;
-/** 把 target 处最近的 stack 弹回到根 entry。 */
-declare function popToRoot(tree: NavigationNode, target?: NavigationPath): NavigationNode;
-/** 把 target 处最近的 stack 弹回到指定 index（保留 [0..index]）。 */
-declare function popTo(tree: NavigationNode, index: number, target?: NavigationPath): NavigationNode;
-/** 替换 target 处最近 stack 的栈顶 entry（栈为空时抛错）。 */
-declare function replaceTop(tree: NavigationNode, node: NavigationNode, target?: NavigationPath): NavigationNode;
-/**
- * 切换 tabs 节点的激活分支。
- * target 默认为「最近的激活 tabs 节点」；target 必须指向 TabsNode，且 key 必须是已知分支。
- */
-declare function selectTab(tree: NavigationNode, key: string, target?: NavigationPath): NavigationNode;
-/**
- * 设置 split 某列内容，并清空它之后的所有列（content 置 undefined）。
- * target 默认为「最近的激活 split 节点」；columnId 必须是已知列。
- */
-declare function selectColumn(tree: NavigationNode, columnId: string, content: NavigationNode | undefined, target?: NavigationPath): NavigationNode;
-/**
- * 设置 split 节点的列可见性（对标 SwiftUI `NavigationSplitViewVisibility`）。
- * target 默认为「最近的激活 split 节点」。改变 visibility 会影响 `collectVisibleDestinations`，
- * 进而触发 controller 对「新变可见」的列做 dispatch / SSR 预取（如 detailOnly → all 时补预取 sidebar/content）。
- */
-declare function setVisibility(tree: NavigationNode, visibility: SplitVisibility, target?: NavigationPath): NavigationNode;
-//#endregion
-//#region ../core/src/navigation/serialization.d.ts
-/** 序列化叶子 */
-interface SerializedLeaf {
-  readonly kind: typeof NAVIGATION_NODE_KINDS.LEAF;
-  readonly intent: string;
-  readonly params: 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 ../core/src/navigation/codec.d.ts
-/**
- * Router 的最小读取面 —— codec 只依赖这两个公共方法，避免与 Router 实现耦合。
- * （`reverse` 为可选：若 Router 将来提供则优先使用。）
- */
-interface NavigationRouterLike {
-  /** 所有已注册路由的 `"pattern → intentId"` 摘要 */
-  getRoutes(): string[];
-  /** 可选：把 intentId + 参数反查为 URL（若实现则 encode 优先使用） */
-  reverse?(intentId: string, params: RouteParams): string | undefined;
-}
-/**
- * 导航 URL 编解码器。
- * - `encode`：把导航树映射为 URL。
- * - `decode`：把 URL 还原为导航树；无法（或无需）从 URL 同步还原时返回 `undefined`。
- */
-interface NavigationCodec {
-  encode(tree: NavigationNode, router: NavigationRouterLike): string;
-  decode(url: string, router: NavigationRouterLike): NavigationNode | undefined;
-}
-/** 默认结构化覆盖参数名（full-state 编码所用的保留 query key）。 */
-declare const DEFAULT_NAV_PARAM = "__nav";
-/**
- * 把整棵树编码为紧凑、URL 安全、确定性的字符串。
- * 用 `serializeNavigationStable`（keys 排序）保证相同树产出相同串，再做 base64url。
- */
-declare function encodeNavigationTreeParam(tree: NavigationNode): string;
-/**
- * 还原 `encodeNavigationTreeParam` 的输出为导航树；畸形输入抛 NavigationError。
- */
-declare function decodeNavigationTreeParam(encoded: string): NavigationNode;
-/**
- * 默认 codec：
- * - `encode`：把激活叶子反查为 URL（`Router.reverse` 或路由摘要反查）；激活叶子无对应路由时回退 `"/"`。
- * - `decode`：仅在 URL 带 `__nav` 结构化覆盖时同步还原整棵树；否则返回 `undefined`，
- *   交由调用方走 `await router.resolve(url)` 异步重建单个 LeafNode（今天的行为）。
- */
-declare function createActiveLeafCodec(): NavigationCodec;
-/** full-state codec 选项 */
-interface FullStateCodecOptions {
-  /** 保留 query 参数名（整树编码所用）；默认 `__nav`。 */
-  readonly param?: string;
-}
-/**
- * 整树 codec：把整棵树编码进保留 query 参数（默认 `__nav`），支持完整深链。
- * - `encode`：以激活叶子的 URL 作为基底路径（保留 app 可能依赖的 path/query），
- *   再写入保留参数承载整棵树。激活叶子无对应路由时基底退化为 `"/"`。
- * - `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 常量 */
-declare const NAVIGATION_OP_KINDS: {
-  readonly PUSH: "push";
-  readonly POP: "pop";
-  readonly POP_TO_ROOT: "popToRoot";
-  readonly POP_TO: "popTo";
-  readonly REPLACE_TOP: "replaceTop";
-  readonly SELECT_TAB: "selectTab";
-  readonly SELECT_COLUMN: "selectColumn";
-  readonly SET_VISIBILITY: "setVisibility";
-  readonly HYDRATE: "hydrate";
-};
-/** 所有导航操作 Kind 的联合类型 */
-type NavigationOpKind = (typeof NAVIGATION_OP_KINDS)[keyof typeof NAVIGATION_OP_KINDS];
-/** push：在目标栈顶压入一个新 leaf（intent + params）。 */
-interface PushOperation {
-  readonly kind: typeof NAVIGATION_OP_KINDS.PUSH;
-  readonly intent: string;
-  readonly params?: RouteParams;
-  readonly target?: NavigationPath;
-}
-/** pop：从目标栈弹出 count 个 entry（默认 1）。 */
-interface PopOperation {
-  readonly kind: typeof NAVIGATION_OP_KINDS.POP;
-  readonly count?: number;
-  readonly target?: NavigationPath;
-}
-/** popToRoot：把目标栈弹回根 entry。 */
-interface PopToRootOperation {
-  readonly kind: typeof NAVIGATION_OP_KINDS.POP_TO_ROOT;
-  readonly target?: NavigationPath;
-}
-/** popTo：把目标栈弹回指定 index。 */
-interface PopToOperation {
-  readonly kind: typeof NAVIGATION_OP_KINDS.POP_TO;
-  readonly index: number;
-  readonly target?: NavigationPath;
-}
-/** replaceTop：替换目标栈的栈顶为新 leaf。 */
-interface ReplaceTopOperation {
-  readonly kind: typeof NAVIGATION_OP_KINDS.REPLACE_TOP;
-  readonly intent: string;
-  readonly params?: RouteParams;
-  readonly target?: NavigationPath;
-}
-/** selectTab：切换 tabs 节点的激活分支。 */
-interface SelectTabOperation {
-  readonly kind: typeof NAVIGATION_OP_KINDS.SELECT_TAB;
-  readonly key: string;
-  readonly target?: NavigationPath;
-}
-/** selectColumn：设置 split 某列内容（intent 为 undefined 表示清空该列）。 */
-interface SelectColumnOperation {
-  readonly kind: typeof NAVIGATION_OP_KINDS.SELECT_COLUMN;
-  readonly columnId: string;
-  readonly intent: string | undefined;
-  readonly params?: RouteParams;
-  readonly target?: NavigationPath;
-}
-/** setVisibility：设置 split 节点的列可见性（对标 NavigationSplitViewVisibility）。 */
-interface SetVisibilityOperation {
-  readonly kind: typeof NAVIGATION_OP_KINDS.SET_VISIBILITY;
-  readonly visibility: SplitVisibility;
-  readonly target?: NavigationPath;
-}
-/** hydrate：用外部给定的整棵树替换当前树（来自 history/URL 还原）。 */
-interface HydrateOperation {
-  readonly kind: typeof NAVIGATION_OP_KINDS.HYDRATE;
-  readonly tree: NavigationNode;
-}
-/** 所有导航操作的可辨识联合。 */
-type NavigationOperation = PushOperation | PopOperation | PopToRootOperation | PopToOperation | ReplaceTopOperation | SelectTabOperation | SelectColumnOperation | SetVisibilityOperation | HydrateOperation;
-/**
- * 控制器解析单个目标时需要的「环境」——由应用提供。
- *
- * 仓库里没有契约所说的 `IntentContext`：dispatch 需要 `Container`，守卫需要
- * `NavigationContext`（含 url/cookie/header）。所以 `createContext` 在此被建模为
- * 「给定目标 intent/params，返回构建守卫上下文 + 派发所需的零件」：
- * - `container`：派发 intent 用（`intentDispatcher.dispatch(intent, container)`）。
- * - `navigation`：完整的 `NavigationContext`（应用按 SSR/CSR 用
- *   `createServerContext`/`createBrowserContext` 造好传入）；缺省时控制器用一个不含
- *   cookie/header 的最小上下文兜底（含 url/path/params/intent/container/isServer，
- *   其中 isServer 取 `NavigationControllerOptions.isServer`，缺省按运行环境推断）。
- *
- * `signal` 暂无消费方（现有 runner 也没有 AbortSignal 管线），仅透传保留。
- */
-interface NavigationContextInput {
-  readonly intent: string;
-  readonly params: RouteParams;
-  readonly signal?: AbortSignal;
-}
-/** `createContext` 的返回：派发用的 Container + 守卫用的 NavigationContext（可选）。 */
-interface NavigationDispatchContext {
-  /** DI 容器 —— intent 派发的必备参数。 */
-  readonly container: Container;
-  /** 守卫上下文；缺省时控制器用最小上下文兜底。 */
-  readonly navigation?: NavigationContext;
-  /** 该目标对应的完整 URL（用于最小兜底上下文的 url/path）。 */
-  readonly url?: string;
-}
-/** NavigationController 构造选项。 */
-interface NavigationControllerOptions {
-  /** Intent 派发器（派发可见目标的 intent → page）。 */
-  readonly intentDispatcher: IntentDispatcher;
-  /** 路由器（beforeLoad rewrite/redirect 时把 URL 重解析为 leaf）。 */
-  readonly router: Router;
-  /** 初始导航树（单 LeafNode = 今天的扁平单页）。 */
-  readonly initial: NavigationNode;
-  /** 应用提供的「目标 → 派发上下文」构建回调。 */
-  readonly createContext: (input: NavigationContextInput) => NavigationDispatchContext;
-  /**
-   * 是否运行在服务端——仅用于 `createContext` 未返回 `navigation` 时的最小兜底上下文，
-   * 决定该上下文的 `isServer` 字段。缺省时按运行环境推断（`typeof window === "undefined"`）。
-   * 应用若已通过 `createContext` 提供完整 `navigation`，此项不生效。
-   */
-  readonly isServer?: boolean;
-  /** 目标级 beforeLoad 守卫（在全局/路由守卫之外，由控制器对主目标执行）。 */
-  readonly beforeLoad?: readonly BeforeLoadGuard[];
-  /** 目标级 afterLoad 守卫。 */
-  readonly afterLoad?: readonly AfterLoadGuard[];
-  /** SSR 预取缓存（浏览器 hydration 时复用服务端解析结果）。 */
-  readonly prefetched?: PrefetchedIntents;
-  /**
-   * 兜底错误页工厂——dispatch 失败 / deny 时，用它产出该目标的 page。
-   * 缺省用一个最小的 BasePage（pageType="error"）。复刻 runner 的 fallback 语义。
-   */
-  readonly getErrorPage?: (status: number, message: string) => Page;
-  /**
-   * redirect 处理器——beforeLoad/afterLoad 返回 redirect 时调用（SPA 内跳 / 外链）。
-   * 控制器不持有 history，把「怎么跳」交给应用（浏览器侧 → `framework.perform`）。
-   * 缺省为 no-op（该目标不 dispatch、不再跳，仅保留当前页/兜底页）。
-   */
-  readonly onRedirect?: (redirect: {
-    url: string;
-    status: number;
-  }) => void;
-}
-/** 导航控制器对外接口。 */
-interface NavigationController {
-  /** 当前导航树。 */
-  getTree(): NavigationNode;
-  /** 当前快照（树 + 已解析的可见目标）。 */
-  getSnapshot(): NavigationSnapshot;
-  /** 应用一个声明式操作，重解析并提交，返回新快照。 */
-  apply(op: NavigationOperation): Promise<NavigationSnapshot>;
-  /** 便捷：在激活栈压入新目标。 */
-  push(intent: string, params?: RouteParams, options?: PushOptions): Promise<NavigationSnapshot>;
-  /** 便捷：从激活栈弹出。 */
-  pop(count?: number): Promise<NavigationSnapshot>;
-  /** 便捷：激活栈弹回根。 */
-  popToRoot(): Promise<NavigationSnapshot>;
-  /** 便捷：替换激活栈栈顶。 */
-  replaceTop(intent: string, params?: RouteParams): Promise<NavigationSnapshot>;
-  /** 便捷：切换 tabs 激活分支。 */
-  selectTab(key: string, target?: NavigationPath): Promise<NavigationSnapshot>;
-  /** 便捷：设置 split 列内容（intent=undefined 清空）。 */
-  selectColumn(columnId: string, intent: string | undefined, params?: RouteParams, target?: NavigationPath): Promise<NavigationSnapshot>;
-  /** 便捷：设置 split 列可见性（对标 NavigationSplitViewVisibility）；改变可见集会触发新可见列的派发。 */
-  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），提交并返回快照。 */
-  resolve(): Promise<NavigationSnapshot>;
-}
-/** `push` 便捷方法的可选项。 */
-interface PushOptions {
-  readonly target?: NavigationPath;
-}
-declare function createNavigationController(options: NavigationControllerOptions): NavigationController;
-//#endregion
-//#region ../core/src/bootstrap/define-navigation.d.ts
-/**
- * `initial` 既可是一棵静态初始树，也可是按 URL 产出树骨架的工厂。
- *
- * - 静态树：所有请求（CSR 首屏 / SSR 无深链回退）都以这棵树为初始结构。
- * - 工厂 `(url) => NavigationNode | undefined`：按请求 URL 动态决定骨架；返回 `undefined`
- *   表示「此 URL 无结构化骨架」，SSR 侧据此回退到「`Router.resolve` → 单 LeafNode」
- *   （今天的单页行为）。CSR 侧首屏对工厂传入当前 `window.location` 的 path+query。
- */
-type NavigationInitial = NavigationNode | ((url: string) => NavigationNode | undefined);
-/**
- * 浏览器 runner（`startBrowserApp`）期望的导航配置形态。
- *
- * 与 `@finesoft/browser` 的 `BrowserNavigationConfig` 结构等价（`initial` 为具体树）；
- * 在 core 中以结构化形状声明，避免 core → browser 的反向依赖。
- */
-interface NavigationBrowserConfig {
-  readonly initial: NavigationNode;
-  readonly codec?: NavigationCodec;
-  readonly beforeLoad?: readonly BeforeLoadGuard[];
-  readonly afterLoad?: readonly AfterLoadGuard[];
-  readonly getErrorPage?: (status: number, message: string) => BasePage;
-}
-/**
- * SSR runner（`createSSRNavigationRender` / `ssrRenderNavigation`）期望的导航定义形态。
- *
- * 与 `@finesoft/ssr` 的 `SSRNavigationDefinition` 结构等价（`codec` 必填、`initial`
- * 为骨架工厂）；在 core 中以结构化形状声明，避免 core → ssr 的反向依赖。
- */
-interface NavigationSSRDefinition {
-  readonly codec: NavigationCodec;
-  readonly initial?: (url: string) => NavigationNode | undefined;
-  readonly beforeLoad?: readonly BeforeLoadGuard[];
-  readonly afterLoad?: readonly AfterLoadGuard[];
-}
-/** `defineNavigation` 的输入声明。 */
-interface DefineNavigationOptions {
-  /**
-   * 初始导航结构：静态树或按 URL 产出树骨架的工厂。
-   * 单个 `leaf(...)` 树即为今天的扁平单页（向后兼容）。
-   */
-  readonly initial: NavigationInitial;
-  /**
-   * URL ⇄ 树 编解码器；缺省 `createActiveLeafCodec()`
-   * （URL 只反映激活叶子，整树通过 history/hydration 旁路）。
-   */
-  readonly codec?: NavigationCodec;
-  /** 导航级 beforeLoad 守卫（控制器对主目标执行，叠加在全局/路由守卫之外）。 */
-  readonly beforeLoad?: readonly BeforeLoadGuard[];
-  /** 导航级 afterLoad 守卫。 */
-  readonly afterLoad?: readonly AfterLoadGuard[];
-  /** dispatch 失败 / deny 时的兜底错误页工厂（仅 CSR runner 直接消费；SSR runner 用其自带的 getErrorPage）。 */
-  readonly getErrorPage?: (status: number, message: string) => BasePage;
-}
-/**
- * `defineNavigation` 的产物：规范化后的导航定义。
- *
- * 既暴露规范化字段（应用可自取），也提供两个适配器把定义转成各 runner 需要的精确形态。
- * 字段全部 `readonly`、不可变。
- */
-interface NavigationDefinition {
-  /** 规范化的初始结构（静态树或工厂）。 */
-  readonly initial: NavigationInitial;
-  /** 最终生效的 codec（已套用默认值）。 */
-  readonly codec: NavigationCodec;
-  /** 导航级 beforeLoad 守卫。 */
-  readonly beforeLoad?: readonly BeforeLoadGuard[];
-  /** 导航级 afterLoad 守卫。 */
-  readonly afterLoad?: readonly AfterLoadGuard[];
-  /** 兜底错误页工厂。 */
-  readonly getErrorPage?: (status: number, message: string) => BasePage;
-  /**
-   * 适配为浏览器 runner 配置（`initial` 收敛为具体树）。
-   * `initial` 是工厂时，对 `url`（缺省当前 `window.location`）求值；返回 `undefined`
-   * 时回退到一个最小的占位 leaf（`@finesoft/navigation-root`），保证 bridge 能挂载——
-   * 浏览器首屏随后会用 SSR 注入的真实树 hydrate（见 navigation-bridge）。
-   */
-  toBrowserConfig(url?: string): NavigationBrowserConfig;
-  /** 适配为 SSR runner 定义（`initial` 收敛为骨架工厂、`codec` 必填）。 */
-  toSSRDefinition(): NavigationSSRDefinition;
-}
-/**
- * 声明结构化导航。
- *
- * 在 `bootstrap(framework)` 里与 `defineRoutes` 并列调用，返回一个 `NavigationDefinition`，
- * 由应用分别交给 CSR / SSR runner：
- *
- * @example
- * ```ts
- * const nav = defineNavigation({
- *   initial: tabs({
- *     active: "home",
- *     branches: { home: stack(leaf("home")), me: stack(leaf("me")) },
- *   }),
- *   beforeLoad: [authGuard],
- * });
- *
- * // CSR
- * startBrowserApp({ bootstrap, mount, callbacks, navigation: nav.toBrowserConfig() });
- * // SSR
- * createSSRNavigationRender({ bootstrap, getErrorPage, renderApp, navigation: nav.toSSRDefinition() });
- * ```
- */
-declare function defineNavigation(options: DefineNavigationOptions): NavigationDefinition;
-//#endregion
-//#region ../core/src/bootstrap/define-routes.d.ts
-/** 渲染模式 */
-type RenderMode = "ssr" | "csr" | "prerender";
-/** 单条路由定义 */
-interface RouteDefinition<Path extends string = string, P extends ParamsFor<Path> = ParamsFor<Path>, Q extends QuerySchemaMap = QuerySchemaMap> {
-  /** URL pattern (如 "/product/:id") */
-  path: Path;
-  /** Intent ID */
-  intentId: string;
-  /** Controller 实例（可选）。同一 intentId 的多条路由只需在第一条提供。 */
-  controller?: IntentController;
-  /** path 参数 codec；key 必须是 path 中出现的 :param 名 */
-  params?: P;
-  /** query 参数 codec；key 自由 */
-  query?: Q;
-  /** 渲染模式（可选，默认 "ssr"） */
-  renderMode?: RenderMode;
-  /** 路由级 beforeLoad 守卫 */
-  beforeLoad?: BeforeLoadGuard[];
-  /** 路由级 afterLoad 守卫 */
-  afterLoad?: AfterLoadGuard[];
-}
-/**
- * 构造一条强类型路由定义。
- * `params` 的 key 受 `path` 字面量约束——写入 path 中不存在的参数名会编译期报错。
- *
- * @example
- * route("/product/:id", { intentId: "product", controller, params: { id: int() } })
- */
-declare function route<const Path extends string, P extends ParamsFor<Path> = ParamsFor<Path>, Q extends QuerySchemaMap = QuerySchemaMap>(path: Path, def: {
-  intentId: string;
-  controller?: IntentController;
-  params?: P;
-  query?: Q;
-  renderMode?: RenderMode;
-  beforeLoad?: BeforeLoadGuard[];
-  afterLoad?: AfterLoadGuard[];
-}): RouteDefinition;
-/** defineRoute 的 handler 入参类型：path 参数 + query 经 codec 推导后合并（免手写）。 */
-type HandlerParams<P, Q> = InferParams<{ [K in keyof P]: P[K] extends ParamSchema ? P[K] : never }> & InferQuery<{ [K in keyof Q]: Q[K] extends QuerySchemaMap[string] ? Q[K] : never }>;
-/**
- * 构造一条强类型路由定义，**handler 的入参类型从 `path` + codec 自动推导**——免手写
- * `BaseController<InferParams<typeof ...> & InferQuery<typeof ...>>`。
- *
- * 与 `route()`（类 controller）互补：用 handler 函数代替 `BaseController` 子类，框架据
- * `params`/`query` codec 自动算出 handler 入参类型；内部把 handler 合成为 `IntentController`，
- * 复刻 `BaseController` 的 try/catch → fallback 行为。`params` 的 key 同样受 `path` 字面量约束。
- *
- * @example
- * route 同款的强类型，但无需声明 controller 类：
- * ```ts
- * defineRoute("/product/:id", {
- *   intentId: "product",
- *   params: { id: int() },
- *   query: { page: withDefault(int(), 1) },
- *   handler: (params) => ({ ... }),   // params: { id: number; page: number }，自动推导
- * })
- * ```
- */
-declare function defineRoute<const Path extends string, P extends ParamsFor<Path> = ParamsFor<Path>, Q extends QuerySchemaMap = QuerySchemaMap, TResult = unknown>(path: Path, def: {
-  intentId: string;
-  params?: P;
-  query?: Q;
-  handler: (params: HandlerParams<P, Q>, container: Container) => TResult | Promise<TResult>;
-  fallback?: (params: HandlerParams<P, Q>, error: Error) => TResult | Promise<TResult>;
-  renderMode?: RenderMode;
-  beforeLoad?: BeforeLoadGuard[];
-  afterLoad?: AfterLoadGuard[];
-}): RouteDefinition;
-/** defineRoutes 选项 */
-interface DefineRoutesOptions {
-  /**
-   * 支持的 locale 列表。
-   * 提供后，每条路由会额外注册 `/:locale/path` 版本，
-   * `:locale` 参数自动出现在 `intent.params.locale` 中。
-   * 原始无前缀路径保留作为备选路由。
-   *
-   * @example
-   * ```ts
-   * defineRoutes(framework, routes, { locales: ["zh", "en", "ja"] });
-   * // "/about" → 注册 /about + /zh/about + /en/about + /ja/about
-   * ```
-   */
-  locales?: string[];
-}
-/**
- * 数组形态 6c 一致性的载体：把一条路由的 `params` 按其自身 `path` 字面量重新约束 key。
- *
- * 不在 path 参数名集合内的 key 显式映射为 `never`——结构化赋值不会对非 fresh 对象做
- * excess-property 检查（`route()` 单数 helper 靠 fresh 字面量 + `ParamsFor` 拿到 excess
- * 检查，但数组元素流经泛型推断后不再是 fresh，故改用 never 映射），使其值（`ParamSchema`）
- * 不可赋给 `never` 而编译期报错。
- */
-type ValidateRouteParams<Path extends string, Params> = { [K in keyof Params]: K extends ExtractParamNames<Path> ? Params[K] : never };
-/**
- * 仅当元素是「带 params 的对象字面量」时重写其 params 约束；无 params 的路由与 `route()`
- * 输出（`params` 可选、Path 已擦除为 string）走 false 分支，原样透传、不被过度约束。
- */
-type ValidateRouteDef<R> = R extends {
-  path: infer P extends string;
-  params: infer Params;
-} ? Omit<R, "params"> & {
-  params: ValidateRouteParams<P, Params>;
-} : R;
-/**
- * 声明式注册路由和 Controller
- *
- * - 自动去重: 同一 intentId 的 controller 只注册一次
- * - 路由和 controller 在同一个配置数组中，方便检查一致性
- * - **数组形态 6c**: 每条对象字面量路由的 `params` key 受其自身 `path` 字面量约束，
- *   写入 path 中不存在的参数名会编译期报错（与 `route()` 单数 helper 同等保证）。
- *
- * @example
- * ```ts
- * defineRoutes(framework, [
- *   { path: "/",                intentId: "home",     controller: new HomeController() },
- *   { path: "/product/:id",    intentId: "product",  controller: new ProductController() },
- *   { path: "/search",         intentId: "search",   controller: new SearchController() },
- *   { path: "/charts/:type",   intentId: "charts",   controller: new ChartsController() },
- *   { path: "/charts",         intentId: "charts" },  // 同 intentId，不需要重复 controller
- * ]);
- * ```
- */
-declare function defineRoutes<const T extends readonly RouteDefinition[]>(framework: Framework, definitions: { [I in keyof T]: ValidateRouteDef<T[I]> }, 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 缓存
- */
-declare class LruMap<K, V> {
-  private map;
-  private readonly capacity;
-  constructor(capacity: number);
-  get(key: K): V | undefined;
-  set(key: K, value: V): void;
-  has(key: K): boolean;
-  delete(key: K): boolean;
-  get size(): number;
-  clear(): void;
-}
-//#endregion
-//#region ../core/src/utils/optional.d.ts
-/**
- * Optional 类型工具
- */
-type None = null | undefined;
-type Optional<T> = T | None;
-declare function isSome<T>(value: Optional<T>): value is T;
-declare function isNone<T>(value: Optional<T>): value is None;
-//#endregion
-//#region ../core/src/utils/pwa.d.ts
-/**
- * PWA Display Mode 检测
- *
- * 检测当前应用是否以 PWA 模式运行。
- */
-type PWADisplayMode = "standalone" | "twa" | "browser";
-/**
- * 检测 PWA display mode
- *
- * - `standalone`: 已安装的 PWA（通过 Add to Home Screen）
- * - `twa`: Trusted Web Activity（Android 原生壳）
- * - `browser`: 普通浏览器标签页
- */
-declare function getPWADisplayMode(): PWADisplayMode;
-//#endregion
-//#region ../core/src/utils/url.d.ts
-/**
- * URL 工具函数
- */
-/** 移除 URL scheme (https://, http://) */
-declare function removeScheme(url: string): string;
-/** 移除 URL host 部分，保留路径 */
-declare function removeHost(url: string): string;
-/** 移除 query 参数 */
-declare function removeQueryParams(url: string): string;
-/** 获取 URL 的基础路径（无 query、hash） */
-declare function getBaseUrl(url: string): string;
-/** 构建 URL（路径 + query 参数） */
-declare function buildUrl(path: string, params?: Record<string, string | undefined>): string;
-//#endregion
-//#region ../core/src/utils/uuid.d.ts
-/**
- * UUID v4 生成器
- */
-declare function generateUuid(): string;
-//#endregion
-//#region ../core/src/middleware/context.d.ts
-interface ServerContextOptions {
-  url: string;
-  intent: Intent;
-  container: Container;
-  /** 原始 Request 对象（提取 cookie 和 header） */
-  request?: Request;
-}
-/** 从 Request 对象构建服务端上下文 */
-declare function createServerContext(options: ServerContextOptions): NavigationContext;
-interface BrowserContextOptions {
-  url: string;
-  intent: Intent;
-  container: Container;
-}
-/** 从 document.cookie 构建浏览器端上下文 */
-declare function createBrowserContext(options: BrowserContextOptions): NavigationContext;
-//#endregion
-//#region ../core/src/middleware/pipeline.d.ts
-/** 执行 beforeLoad 守卫链 */
-declare function runBeforeLoadGuards(guards: BeforeLoadGuard[], ctx: NavigationContext): Promise<MiddlewareResult>;
-/** 执行 afterLoad 守卫链 */
-declare function runAfterLoadGuards(guards: AfterLoadGuard[], ctx: PostLoadContext): Promise<MiddlewareResult>;
-//#endregion
-//#region ../core/src/metrics/composite-recorder.d.ts
-declare class CompositeEventRecorder implements EventRecorder {
-  private readonly recorders;
-  constructor(recorders: EventRecorder[]);
-  record(type: string, fields?: Record<string, unknown>): void;
-  flush(): Promise<void>;
-  destroy(): void;
-}
-//#endregion
-//#region ../core/src/metrics/console-recorder.d.ts
-declare class ConsoleEventRecorder implements EventRecorder {
-  private readonly prefix;
-  constructor(prefix?: string);
-  record(type: string, fields?: Record<string, unknown>): void;
-  flush(): Promise<void>;
-  destroy(): void;
-}
-//#endregion
-//#region ../core/src/metrics/impression-observer.d.ts
-interface ImpressionObserverOptions {
-  /** 可见比例阈值（0~1），默认 0.5 */
-  threshold?: number;
-  /** 最小可见时长（毫秒），默认 1000 */
-  minVisibleDuration?: number;
-}
-declare class IntersectionImpressionObserver implements ImpressionObserver {
-  private readonly observer;
-  private readonly tracked;
-  private readonly captured;
-  private readonly minDuration;
-  constructor(options?: ImpressionObserverOptions);
-  observe(element: Element, id: string, metadata?: Record<string, unknown>): void;
-  unobserve(element: Element): void;
-  consume(): ImpressionEntry[];
-  destroy(): void;
-}
-//#endregion
-//#region ../core/src/metrics/void-recorder.d.ts
-declare class VoidEventRecorder implements EventRecorder {
-  record(): void;
-  flush(): Promise<void>;
-  destroy(): void;
-}
-//#endregion
-//#region ../core/src/metrics/with-fields-recorder.d.ts
-declare class WithFieldsRecorder implements EventRecorder {
-  private readonly inner;
-  private readonly providers;
-  constructor(inner: EventRecorder, providers: MetricsFieldsProvider[]);
-  record(type: string, fields?: Record<string, unknown>): void;
-  flush(): Promise<void>;
-  destroy(): void;
-}
-//#endregion
-//#region ../core/src/i18n/interpolate.d.ts
-/**
- * ICU 消息格式插值
- *
- * 支持 `{name}` 占位符替换和基础复数规则。
- */
-/** 将 `{key}` 占位符替换为 values 中的对应值 */
-declare function interpolate(template: string, values?: Record<string, string | number>): string;
-/**
- * CLDR 复数类别
- *
- * 简化版：覆盖 zero / one / two / few / many / other。
- * 完整 CLDR 规则可通过 PluralRuleProvider 注入。
- */
-type PluralCategory = "zero" | "one" | "two" | "few" | "many" | "other";
-/** 复数规则函数 — 给定数量返回复数类别 */
-type PluralRuleProvider = (count: number) => PluralCategory;
-/**
- * 英语复数规则（默认）
- * 0 → other, 1 → one, 2+ → other
- */
-declare function englishPlural(count: number): PluralCategory;
-/**
- * 解析带复数后缀的翻译 key
- *
- * 约定: `key.one`, `key.other`, `key.zero`, etc.
- */
-declare function resolvePluralKey(key: string, category: PluralCategory): string;
-//#endregion
-//#region ../core/src/i18n/locale.d.ts
-/** 检测语言是否为 RTL */
-declare function isRtl(language: string): boolean;
-/** 获取文本方向 */
-declare function getTextDirection(language: string): TextDirection;
-/**
- * 从语言代码生成 HTML lang/dir 属性
- *
- * @example
- * ```ts
- * getLocaleAttributes("ar-SA") // { lang: "ar-SA", dir: "rtl" }
- * getLocaleAttributes("en-US") // { lang: "en-US", dir: "ltr" }
- * ```
- */
-declare function getLocaleAttributes(language: string): LocaleAttributes;
-/**
- * 构建 LocaleInfo
- *
- * @param language - 语言代码（如 "zh-Hans"）
- * @param region - 地区代码（如 "CN"），可选
- */
-declare function makeLocaleInfo(language: string, region?: string): LocaleInfo;
-/**
- * 将 locale 属性应用到 `<html>` 元素
- *
- * 服务端渲染时可用于字符串拼接，浏览器端直接操作 DOM。
- */
-declare function setHtmlLocaleAttributes(attrs: LocaleAttributes): void;
-/**
- * 从 URL 前缀中提取 locale
- *
- * @param url - 请求 URL（如 "/zh/about"）
- * @param supportedLocales - 支持的 locale 列表（如 ["zh", "en", "ja"]）
- * @returns 匹配时返回 `{ locale, strippedUrl }`，不匹配返回 null
- *
- * @example
- * ```ts
- * resolveLocaleFromUrl("/zh/about", ["zh", "en"])
- * // → { locale: "zh", strippedUrl: "/about" }
- *
- * resolveLocaleFromUrl("/about", ["zh", "en"])
- * // → null
- * ```
- */
-declare function resolveLocaleFromUrl(url: string, supportedLocales: string[]): {
-  locale: string;
-  strippedUrl: string;
-} | null;
-//#endregion
-//#region ../core/src/i18n/translator.d.ts
-interface SimpleTranslatorOptions {
-  /** 翻译映射 */
-  messages: Record<string, string>;
-  /** 当前 locale */
-  locale: string;
-  /** 复数规则函数（默认英语规则） */
-  pluralRule?: PluralRuleProvider;
-  /** 找不到翻译时的回退行为（默认返回 key） */
-  fallback?: (key: string) => string;
-}
-declare class SimpleTranslator implements Translator {
-  readonly locale: string;
-  private readonly messages;
-  private readonly pluralRule;
-  private readonly fallback;
-  constructor(options: SimpleTranslatorOptions);
-  t(key: string, values?: Record<string, string | number>): string;
-  plural(key: string, count: number, values?: Record<string, string | number>): string;
-}
-//#endregion
-//#region ../browser/src/action-handlers/external-url-action.d.ts
-interface ExternalUrlDependencies {
-  framework: Framework;
-  log: Logger;
-}
-declare function registerExternalUrlHandler(deps: ExternalUrlDependencies): void;
-//#endregion
-//#region ../browser/src/action-handlers/flow-action.d.ts
-/** UI 框架回调 — 解耦 Svelte store 等依赖 */
-interface FlowActionCallbacks {
-  /** 导航后更新当前路径（替代 currentPath.set()） */
-  onNavigate(pathname: string): void;
-  /** 模态页面展示（替代 openModal()） */
-  onModal(page: BasePage): void;
-}
-/** 注册 FlowAction handler 所需的依赖 */
-interface FlowActionDependencies {
-  framework: Framework;
-  log: Logger;
-  callbacks: FlowActionCallbacks;
-  /** 更新应用 UI 的回调，page 可以是 Promise */
-  updateApp: (props: {
-    page: Promise<BasePage> | BasePage;
-    isFirstPage?: boolean;
-  }) => void;
-  /** 获取可滚动页面元素，用于滚动位置保存/恢复 */
-  getScrollablePageElement?: () => HTMLElement | null;
-  /**
-   * 是否由本 handler 管理浏览器 history（pushState / popstate）。缺省 `true`。
-   * 结构化导航（`startBrowserApp({ navigation })`）下应传 `false`：history 由
-   * NavigationBridge 独占，否则两套 `History` 实例会争抢同一个 `window.history.state`、
-   * 各自注册 popstate 互相 clobber，导致 back/forward 行为错乱。传 `false` 时本 handler
-   * 仍负责 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
-//#region ../browser/src/action-handlers/register.d.ts
-interface ActionHandlerDependencies {
-  framework: Framework;
-  log: Logger;
-  callbacks: FlowActionCallbacks;
-  updateApp: (props: {
-    page: Promise<BasePage> | BasePage;
-    isFirstPage?: boolean;
-  }) => void;
-  /** 获取可滚动页面元素，用于滚动位置保存/恢复 */
-  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
-//#region ../browser/src/navigation-bridge.d.ts
-/** NavigationBridge 构造依赖。 */
-interface NavigationBridgeDependencies {
-  /** 已构建好的导航控制器（持有 initial 树、intentDispatcher、router 等）。 */
-  readonly controller: NavigationController;
-  /** URL 编解码器（默认 `createActiveLeafCodec`）。 */
-  readonly codec: NavigationCodec;
-  /** Router 的最小读取面（encode 反查 / decode 用）。 */
-  readonly router: NavigationRouterLike;
-  /** 日志器。 */
-  readonly log: Logger;
-  /** 获取可滚动页面元素，用于滚动位置保存/恢复（透传给 History）。 */
-  readonly getScrollablePageElement?: () => HTMLElement | null;
-}
-/**
- * 导航操作句柄 —— 向应用暴露的对外面。
- *
- * 所有写操作返回提交后的 `NavigationSnapshot`；写操作会同步把新树落到 history/URL。
- * `subscribe` 与 controller 的订阅一致（每次提交都回调，含来自 popstate 的 hydrate）。
- */
-interface NavigationHandle {
-  /** 当前快照（树 + 已解析的可见目标）。 */
-  getSnapshot(): NavigationSnapshot;
-  /** 在激活栈压入新目标。 */
-  push(intent: string, params?: RouteParams, options?: {
-    target?: NavigationPath;
-  }): Promise<NavigationSnapshot>;
-  /** 从激活栈弹出 count 个（默认 1）。 */
-  pop(count?: number): Promise<NavigationSnapshot>;
-  /** 激活栈弹回根。 */
-  popToRoot(): Promise<NavigationSnapshot>;
-  /** 替换激活栈栈顶。 */
-  replaceTop(intent: string, params?: RouteParams): Promise<NavigationSnapshot>;
-  /** 切换 tabs 激活分支。 */
-  selectTab(key: string, target?: NavigationPath): Promise<NavigationSnapshot>;
-  /** 设置 split 列内容（intent=undefined 清空该列）。 */
-  selectColumn(columnId: string, intent: string | undefined, params?: RouteParams, target?: NavigationPath): Promise<NavigationSnapshot>;
-  /** 用外部树替换当前树并重解析（一般由桥内部 popstate 调用，亦对外暴露）。 */
-  hydrate(tree: NavigationNode): Promise<NavigationSnapshot>;
-  /** 订阅快照变更；返回取消订阅函数。 */
-  subscribe(listener: (snapshot: NavigationSnapshot) => void): () => void;
-}
-/**
- * 创建 NavigationBridge：订阅 controller、装配 popstate、返回 navigation handle。
- *
- * 调用后 bridge 已激活（已订阅 controller + 已注册 popstate listener）。应用应在调用前/后
- * 调一次 `controller.resolve()` 完成首屏解析；首屏的快照提交会被 bridge 用 `replaceState`
- * 写入 history（first-page 语义），不会污染历史栈。
- */
-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(...)` 或手写提供。
- *
- * 仅当该字段出现时 bridge 才激活；缺省时 `startBrowserApp` 走原有扁平单页路径，行为不变。
- * 提供后：
- * - 用 `initial` 树构建 `NavigationController`（守卫上下文走 `createBrowserContext`，
- *   预取缓存复用 `framework.prefetchedIntents`）；
- * - 装配 `NavigationBridge`（snapshot → history/URL，popstate → hydrate）；
- * - 解析首屏树（一次 `resolve()`），通过 mount context 把 handle 交给应用。
- */
-interface BrowserNavigationConfig {
-  /** 初始导航树（单 LeafNode = 今天的扁平单页）。 */
-  readonly initial: NavigationNode;
-  /** URL 编解码器；缺省 `createActiveLeafCodec()`。 */
-  readonly codec?: NavigationCodec;
-  /** 导航级 beforeLoad 守卫（对主目标执行）。 */
-  readonly beforeLoad?: readonly BeforeLoadGuard[];
-  /** 导航级 afterLoad 守卫。 */
-  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 和路由的引导函数 */
-  bootstrap: (framework: Framework) => void;
-  /** DOM 挂载点 ID（默认 "app"） */
-  mountId?: string;
-  /** 获取可滚动页面元素，用于滚动位置保存/恢复 */
-  getScrollablePageElement?: () => HTMLElement | null;
-  /**
-   * 启动前钩子 — 在 Framework 创建后、挂载前执行
-   *
-   * 用于初始化错误监控、埋点 SDK、i18n 等。
-   */
-  onBeforeStart?: (framework: Framework) => void | Promise<void>;
-  /**
-   * 启动后钩子 — 在初始页面触发后执行
-   *
-   * 用于启动后操作（如 service worker 注册、性能打点）。
-   */
-  onAfterStart?: (framework: Framework) => void | Promise<void>;
-  /**
-   * 挂载应用到 DOM
-   *
-   * 框架无关 — Svelte / React / Vue 均可通过此回调实现。
-   *
-   * @param target - DOM 挂载点
-   * @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;
-  }) => void;
-  /** FlowAction / ExternalUrl 回调 */
-  callbacks: FlowActionCallbacks;
-  /**
-   * Framework 配置 — locale、reportCallback、eventRecorder 等
-   *
-   * 传入后会在 Framework.create() 时合并。
-   * prefetchedIntents 由框架自动从 DOM 提取，无需传入。
-   */
-  frameworkConfig?: Omit<FrameworkConfig, "prefetchedIntents">;
-  /**
-   * 异步加载当前 locale 的翻译字典。
-   *
-   * 显式传入时会覆盖 bootstrap / Vite 自动生成的 loader。
-   */
-  loadMessages?: MessagesLoader;
-  /**
-   * 结构化导航定义（可选）。
-   *
-   * 提供后，`startBrowserApp` 在 mount 前构建 NavigationController + NavigationBridge，
-   * 并通过 mount context 把导航 handle 交给应用。缺省时走原有扁平单页路径，行为完全不变。
-   */
-  navigation?: BrowserNavigationConfig;
-  /**
-   * 会话恢复定义（可选）。
-   *
-   * 提供后，`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` 时请使用 `navigation.mountEntry`，顶层该字段被忽略。
-   */
-  mountEntry?: MountEntry;
-}
-/**
- * 启动客户端应用
- *
- * 自动执行 hydration 全流程。
- */
-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;
-  /**
-   * 是否把 `state` 一并写入 `window.history.state`（而非仅 `{ id }` + 内存 LruMap）。缺省 `false`。
-   *
-   * 内存 LruMap 在整页刷新后丢失；若 state 小且可结构化克隆（如导航树 `{ tree }`），开启此项
-   * 可让 state 随 `window.history.state` **跨刷新按 entry 保留**，刷新后 back/forward 仍能从
-   * history.state 还原（onPopState 在 LruMap 未命中时回退到 `event.state.state`）。
-   * 大状态（如整页 `{ page }`）不应开启，避免撑爆 history.state。
-   */
-  persistInHistoryState?: boolean;
-}
-declare class History<State> {
-  private readonly entries;
-  private readonly log;
-  private readonly getScrollablePageElement;
-  private readonly persistInHistoryState;
-  private currentStateId;
-  constructor(log: Logger, options: HistoryOptions, sizeLimit?: number);
-  /** 写入 window.history.state 的载荷：persist 时连 state 一起带（跨刷新保留）。 */
-  private historyState;
-  replaceState(state: State, url: string): void;
-  pushState(state: State, url: string): void;
-  beforeTransition(): void;
-  onPopState(listener: (url: string, state?: State) => void | Promise<void>): void;
-  /** 仅推入 URL，不缓存页面状态（用于页面加载失败场景） */
-  pushUrl(url: string): void;
-  /** 仅替换 URL，不缓存页面状态（用于页面加载失败场景） */
-  replaceUrl(url: string): void;
-  updateState(update: (current?: State) => State): void;
-  private get scrollTop();
-  private set scrollTop(value);
-}
-//#endregion
-//#region ../browser/src/utils/try-scroll.d.ts
-declare function tryScroll(log: Logger, getScrollableElement: () => HTMLElement | null, scrollY: number): void;
-//#endregion
-//#region ../browser/src/server-data.d.ts
-/**
- * 从 DOM 反序列化服务端嵌入的数据。
- * 读取 `<script id="serialized-server-data">` 的内容并移除标签。
- */
-declare function deserializeServerData(): PrefetchedIntent[] | undefined;
-/**
- * 从 DOM 提取 SSR 数据并构建 PrefetchedIntents 实例。
- * 替代原来的 PrefetchedIntents.fromDom()。
- */
-declare function createPrefetchedIntentsFromDom(): PrefetchedIntents;
-//#endregion
-export { IntersectionImpressionObserver as $, markPublic as $i, TabsInit as $n, shouldLog as $r, defineNavigation as $t, ActionHandlerDependencies as A, IntentDispatcher as Aa, StandardIssue as Ai, SerializedSplitColumn as An, HostCheckResult as Ar, NavigationScopedState as At, getTextDirection as B, FlowAction as Ba, NextResult as Bi, pop as Bn, BaseItem as Br, SessionUrlLocation as Bt, SessionBridgeOptions as C, ReportingLoggerFactory as Ca, StripOptional as Ci, createFlatStackCodec as Cn, TabsNode as Cr, createUrlSessionAdapter as Ct, NavigationBridgeDependencies as D, LoggerFactory as Da, list as Di, SerializedLeaf as Dn, pipe as Dr, sessionEntryKey as Dt, defaultShouldRestore as E, Logger as Ea, isMultiValueSchema as Ei, encodeNavigationTreeParam as En, mapEach as Er, createNavigationScopedState as Et, ExternalUrlDependencies as F, ActionHandler as Fa, AfterLoadGuard as Fi, serializeNavigationStable as Fn, HttpClientConfig as Fr, SessionNavigationAdapter as Ft, PluralCategory as G, makeFlowAction as Ga, next as Gi, resolveActivePath as Gn, FrameworkConfig as Gr, defineRoute as Gt, makeLocaleInfo as H, isExternalUrlAction as Ha, RedirectResult as Hi, popToRoot as Hn, SafeErrorPageOptions as Hr, DefineRoutesOptions as Ht, registerExternalUrlHandler as I, ACTION_KINDS as Ia, BeforeLoadGuard as Ii, collectAllLeaves as In, HttpError as Ir, SessionSnapshot as It, interpolate as J, BASE_PAGE_FIELDS as Ji, setVisibility as Jn, LocaleAttributes as Jr, DefineNavigationOptions as Jt, PluralRuleProvider as K, redirect as Ki, selectColumn as Kn, PrefetchedIntent as Kr, defineRoutes as Kt, SimpleTranslator as L, Action as La, DenyResult as Li, collectVisibleDestinations as Ln, RequestInterceptor as Lr, SessionStateProvider as Lt, FlowActionCallbacks as M, IntentController as Ma, StandardSchemaV1 as Mi, SerializedTabs as Mn, classifyUrl as Mr, SESSION_DEFAULT_VERSION as Mt, FlowActionDependencies as N, Container as Na, makeSchema as Ni, deserializeNavigation as Nn, HostGuardError as Nr, SessionError as Nt, NavigationHandle as O, SecureFetchOptions as Oa, InferOutput as Oi, SerializedNavigation as On, pipeAsync as Or, decodeSnapshot as Ot, registerFlowActionHandler as P, ActionDispatcher as Pa, runStandard as Pi, serializeNavigation as Pn, HttpClient as Pr, SessionErrorContext as Pt, ImpressionObserverOptions as Q, isPublicMarked as Qi, SplitColumnInit as Qn, resetFilterCache as Qr, NavigationSSRDefinition as Qt, SimpleTranslatorOptions as R, CompoundAction as Ra, MiddlewareResult as Ri, findNearestStack as Rn, ResponseInterceptor as Rr, SessionStore as Rt, SESSION_DEFAULT_DEBOUNCE_MS as S, ReportingLogger as Sa, QuerySchemaMap as Si, createActiveLeafCodec as Sn, StackNode as Sr, createNavigationSessionAdapter as St, createSessionBridge as T, BaseLogger as Ta, MultiValueSchema as Ti, decodeNavigationTreeParam as Tn, Mapper as Tr, collectLeafKeys as Tt, resolveLocaleFromUrl as U, isFlowAction as Ua, RewriteResult as Ui, push as Un, safeErrorPage as Ur, RenderMode as Ut, isRtl as V, isCompoundAction as Va, PostLoadContext as Vi, popTo as Vn, BaseShelf as Vr, isUrlLocation as Vt, setHtmlLocaleAttributes as W, makeExternalUrlAction as Wa, deny as Wi, replaceTop as Wn, Framework as Wr, RouteDefinition as Wt, WithFieldsRecorder as X, FINESOFT_PUBLIC as Xi, ResolvedEntry as Xn, TextDirection as Xr, NavigationDefinition as Xt, resolvePluralKey as Y, BasePage as Yi, visibleSplitColumns as Yn, LocaleInfo as Yr, NavigationBrowserConfig as Yt, VoidEventRecorder as Z, getPublicFields as Zi, islandContainerAttributes as Zn, Translator as Zr, NavigationInitial as Zt, IslandOrchestratorOptions as _, EventRecorder as _a, Router as _i, createNavigationController as _n, ResolvedDestination as _r, Optional as _t, DomRestore as a, MakeDependenciesOptions as aa, withDefault as ai, NavigationDispatchContext as an, split as ar, ServerContextOptions as at, AppHandle as b, MetricsFieldsProvider as ba, InferQuery as bi, NavigationCodec as bn, SplitNode as br, LruMap as bt, createWebStorage as c, Storage as ca, bool as ci, PopOperation as cn, LeafNode as cr, generateUuid as ct, BrowserAppConfig as d, MessagesLoaderContext as da, oneOf as di, PushOperation as dn, NavigationNode as dr, removeHost as dt, RequestScopedKey as ea, ConsoleLogger as ei, HydrateOperation as en, isLeafNode as er, ConsoleEventRecorder as et, BrowserNavigationConfig as f, TranslationMessages as fa, str as fi, PushOptions as fn, NavigationNodeKind as fr, removeQueryParams as ft, IslandOrchestrator as g, detectPlatform as ga, RouteMatch as gi, SetVisibilityOperation as gn, Page as gr, None as gt, IslandHandle as h, PlatformInfo as ha, RouteAddOptions as hi, SelectTabOperation as hn, NavigationSnapshot as hr, getPWADisplayMode as ht, History as i, FeatureFlagsProvider as ia, optional as ii, NavigationControllerOptions as in, leaf as ir, BrowserContextOptions as it, registerActionHandlers as j, Intent as ja, StandardResult as ji, SerializedStack as jn, classifyHost as jr, SESSION_DEFAULT_KEY as jt, createNavigationBridge as k, secureFetch as ka, ParamSchema as ki, SerializedSplit as kn, BaseController as kr, encodeSnapshot as kt, IslandsShell as l, makeDependencies as la, int as li, PopToOperation as ln, NAVIGATION_NODE_KINDS as lr, buildUrl as lt, startBrowserApp as m, resolveMessages as ma, RouteParams as mi, SelectColumnOperation as mn, NavigationPathStep as mr, PWADisplayMode as mt, deserializeServerData as n, DEP_KEYS as na, CompositeLogger as ni, NavigationContextInput as nn, isStackNode as nr, runAfterLoadGuards as nt, DomRestoreOptions as o, MetricsRecorder as oa, NumOptions as oi, NavigationOpKind as on, stack as or, createBrowserContext as ot, BrowserSessionConfig as p, resolveConfiguredMessages as pa, uuid as pi, ReplaceTopOperation as pn, NavigationPath as pr, removeScheme as pt, englishPlural as q, rewrite as qi, selectTab as qn, PrefetchedIntents as qr, route as qt, tryScroll as r, FeatureFlags as ra, CompositeLoggerFactory as ri, NavigationController as rn, isTabsNode as rr, runBeforeLoadGuards as rt, createDomRestore as s, Net as sa, StrOptions as si, NavigationOperation as sn, tabs as sr, createServerContext as st, createPrefetchedIntentsFromDom as t, defineRequestScopedKey as ta, ConsoleLoggerFactory as ti, NAVIGATION_OP_KINDS as tn, isSplitNode as tr, CompositeEventRecorder as tt, resolveIslandsShell as u, MessagesLoader as ua, num as ui, PopToRootOperation as un, NavigationError as ur, getBaseUrl as ut, MountEntry as v, ImpressionEntry as va, ExtractParamNames as vi, DEFAULT_NAV_PARAM as vn, SPLIT_VISIBILITIES as vr, isNone as vt, SessionHandle as w, ReportingLoggerOptions as wa, ListOptions as wi, createFullStateCodec as wn, AsyncMapper as wr, createSessionStore as wt, createAppHandle as x, ReportCallback as xa, ParamsFor as xi, NavigationRouterLike as xn, SplitVisibility as xr, UrlAdapterOptions as xt, createIslandOrchestrator as y, ImpressionObserver as ya, InferParams as yi, FullStateCodecOptions as yn, SplitColumn as yr, isSome as yt, getLocaleAttributes as z, ExternalUrlAction as za, NavigationContext as zi, findNode as zn, stableStringify as zr, SessionStoreOptions as zt };
-//# sourceMappingURL=browser-JTs2jqVY.d.mts.map