@finesoft/front 0.1.78 → 0.3.0

package/dist/server-data-HVSgxEac.d.mts

@@ -0,0 +1,2272 @@
+//#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 的校验，吸收同步/异步差异 */
+declare function runStandard(schema: StandardSchemaV1, raw: string | undefined): Promise<{
+  ok: true;
+  value: unknown;
+} | {
+  ok: false;
+  issues: readonly StandardIssue[];
+}>;
+//#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?: Record<string, StandardSchemaV1<string, unknown>>;
+}
+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/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 自由开放 */
+type QuerySchemaMap = Record<string, StandardSchemaV1<string, unknown>>;
+/** 从 codec map 推导运行期参数类型 */
+type InferParams<P extends Record<string, ParamSchema>> = { [K in keyof P]: InferOutput<P[K]> };
+type InferQuery<Q extends QuerySchemaMap> = { [K in keyof Q]: InferOutput<Q[K]> };
+//#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/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[];
+/**
+ * 按 `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;
+//#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>;
+  /** 订阅快照变更；返回取消订阅函数。 */
+  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;
+/** 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[];
+}
+/**
+ * 声明式注册路由和 Controller
+ *
+ * - 自动去重: 同一 intentId 的 controller 只注册一次
+ * - 路由和 controller 在同一个配置数组中，方便检查一致性
+ *
+ * @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(framework: Framework, definitions: RouteDefinition[], options?: DefineRoutesOptions): void;
+//#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;
+}
+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;
+}
+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/start-app.d.ts
+/**
+ * 结构化导航定义 —— 由应用通过 `defineNavigation(...)` 或手写提供。
+ *
+ * 仅当该字段出现时 bridge 才激活；缺省时 `startBrowserApp` 走原有扁平单页路径，行为不变。
+ * 提供后：
+ * - 用 `initial` 树构建 `NavigationController`（守卫上下文走 `createBrowserContext`，
+ *   预取缓存复用 `framework.prefetchedIntents`）；
+ * - 装配 `NavigationBridge`（snapshot → history/URL，popstate → hydrate）；
+ * - 解析首屏树（一次 `resolve()`），通过 `onNavigationReady` 把 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;
+}
+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 实例 + 语言
+   * @returns 更新函数，用于后续页面切换
+   */
+  mount: (target: HTMLElement, context: {
+    framework: Framework;
+  }) => (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` 在挂载后构建 NavigationController + NavigationBridge，
+   * 解析首屏树，并通过 `onNavigationReady` 把导航 handle 交给应用。缺省时走原有
+   * 扁平单页路径（FlowAction handler），行为完全不变。
+   */
+  navigation?: BrowserNavigationConfig;
+  /**
+   * 导航就绪回调 —— bridge 装配并完成首屏 `resolve()` 后调用。
+   *
+   * 仅当提供了 `navigation` 时触发。应用拿到 handle 后用它驱动导航
+   * （push/pop/selectTab…）并订阅快照渲染 UI。
+   */
+  onNavigationReady?: (handle: NavigationHandle) => void | Promise<void>;
+}
+/**
+ * 启动客户端应用
+ *
+ * 自动执行 hydration 全流程。
+ */
+declare function startBrowserApp(config: BrowserAppConfig): Promise<void>;
+//#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 { isNone as $, Framework as $n, BASE_PAGE_FIELDS as $r, popToRoot as $t, resolvePluralKey as A, BaseLogger as Ai, SplitVisibility as An, RouteAddOptions as Ar, createNavigationController as At, ServerContextOptions as B, ActionHandler as Bi, classifyHost as Bn, AfterLoadGuard as Br, SerializedNavigation as Bt, makeLocaleInfo as C, ImpressionEntry as Ci, NavigationPathStep as Cn, bool as Cr, PopToRootOperation as Ct, PluralRuleProvider as D, ReportingLogger as Di, SPLIT_VISIBILITIES as Dn, str as Dr, SelectColumnOperation as Dt, PluralCategory as E, ReportCallback as Ei, ResolvedDestination as En, oneOf as Er, ReplaceTopOperation as Et, ConsoleEventRecorder as F, IntentDispatcher as Fi, mapEach as Fn, StandardIssue as Fr, createActiveLeafCodec as Ft, getBaseUrl as G, FlowAction as Gi, HttpError as Gn, NextResult as Gr, deserializeNavigation as Gt, createServerContext as H, Action as Hi, HostGuardError as Hn, DenyResult as Hr, SerializedSplitColumn as Ht, CompositeEventRecorder as I, Intent as Ii, pipe as In, StandardResult as Ir, createFullStateCodec as It, removeScheme as J, isFlowAction as Ji, stableStringify as Jn, RewriteResult as Jr, collectVisibleDestinations as Jt, removeHost as K, isCompoundAction as Ki, RequestInterceptor as Kn, PostLoadContext as Kr, serializeNavigation as Kt, runAfterLoadGuards as L, IntentController as Li, pipeAsync as Ln, StandardSchemaV1 as Lr, decodeNavigationTreeParam as Lt, VoidEventRecorder as M, LoggerFactory as Mi, TabsNode as Mn, Router as Mr, FullStateCodecOptions as Mt, ImpressionObserverOptions as N, SecureFetchOptions as Ni, AsyncMapper as Nn, InferOutput as Nr, NavigationCodec as Nt, englishPlural as O, ReportingLoggerFactory as Oi, SplitColumn as On, uuid as Or, SelectTabOperation as Ot, IntersectionImpressionObserver as P, secureFetch as Pi, Mapper as Pn, ParamSchema as Pr, NavigationRouterLike as Pt, Optional as Q, safeErrorPage as Qn, rewrite as Qr, popTo as Qt, runBeforeLoadGuards as R, Container as Ri, BaseController as Rn, makeSchema as Rr, encodeNavigationTreeParam as Rt, isRtl as S, EventRecorder as Si, NavigationPath as Sn, StrOptions as Sr, PopToOperation as St, setHtmlLocaleAttributes as T, MetricsFieldsProvider as Ti, Page as Tn, num as Tr, PushOptions as Tt, generateUuid as U, CompoundAction as Ui, HttpClient as Un, MiddlewareResult as Ur, SerializedStack as Ut, createBrowserContext as V, ACTION_KINDS as Vi, classifyUrl as Vn, BeforeLoadGuard as Vr, SerializedSplit as Vt, buildUrl as W, ExternalUrlAction as Wi, HttpClientConfig as Wn, NavigationContext as Wr, SerializedTabs as Wt, getPWADisplayMode as X, makeFlowAction as Xi, BaseShelf as Xn, next as Xr, findNode as Xt, PWADisplayMode as Y, makeExternalUrlAction as Yi, BaseItem as Yn, deny as Yr, findNearestStack as Yt, None as Z, SafeErrorPageOptions as Zn, redirect as Zr, pop as Zt, registerExternalUrlHandler as _, TranslationMessages as _i, LeafNode as _n, QuerySchemaMap as _r, NavigationControllerOptions as _t, BrowserAppConfig as a, RequestScopedKey as ai, setVisibility as an, TextDirection as ar, defineRoutes as at, getLocaleAttributes as b, PlatformInfo as bi, NavigationNode as bn, withDefault as br, NavigationOperation as bt, NavigationBridgeDependencies as c, FeatureFlags as ci, TabsInit as cn, shouldLog as cr, NavigationBrowserConfig as ct, ActionHandlerDependencies as d, MetricsRecorder as di, isStackNode as dn, CompositeLogger as dr, NavigationSSRDefinition as dt, BasePage as ei, push as en, FrameworkConfig as er, isSome as et, registerActionHandlers as f, Net as fi, isTabsNode as fn, CompositeLoggerFactory as fr, defineNavigation as ft, ExternalUrlDependencies as g, MessagesLoaderContext as gi, tabs as gn, ParamsFor as gr, NavigationController as gt, registerFlowActionHandler as h, MessagesLoader as hi, stack as hn, InferQuery as hr, NavigationContextInput as ht, History as i, markPublic as ii, selectTab as in, LocaleInfo as ir, RouteDefinition as it, WithFieldsRecorder as j, Logger as ji, StackNode as jn, RouteMatch as jr, DEFAULT_NAV_PARAM as jt, interpolate as k, ReportingLoggerOptions as ki, SplitNode as kn, RouteParams as kr, SetVisibilityOperation as kt, NavigationHandle as l, FeatureFlagsProvider as li, isLeafNode as ln, ConsoleLogger as lr, NavigationDefinition as lt, FlowActionDependencies as m, makeDependencies as mi, split as mn, InferParams as mr, NAVIGATION_OP_KINDS as mt, deserializeServerData as n, getPublicFields as ni, resolveActivePath as nn, PrefetchedIntents as nr, DefineRoutesOptions as nt, BrowserNavigationConfig as o, defineRequestScopedKey as oi, visibleSplitColumns as on, Translator as or, route as ot, FlowActionCallbacks as p, Storage as pi, leaf as pn, ExtractParamNames as pr, HydrateOperation as pt, removeQueryParams as q, isExternalUrlAction as qi, ResponseInterceptor as qn, RedirectResult as qr, serializeNavigationStable as qt, tryScroll as r, isPublicMarked as ri, selectColumn as rn, LocaleAttributes as rr, RenderMode as rt, startBrowserApp as s, DEP_KEYS as si, SplitColumnInit as sn, resetFilterCache as sr, DefineNavigationOptions as st, createPrefetchedIntentsFromDom as t, FINESOFT_PUBLIC as ti, replaceTop as tn, PrefetchedIntent as tr, LruMap as tt, createNavigationBridge as u, MakeDependenciesOptions as ui, isSplitNode as un, ConsoleLoggerFactory as ur, NavigationInitial as ut, SimpleTranslator as v, resolveConfiguredMessages as vi, NAVIGATION_NODE_KINDS as vn, StripOptional as vr, NavigationDispatchContext as vt, resolveLocaleFromUrl as w, ImpressionObserver as wi, NavigationSnapshot as wn, int as wr, PushOperation as wt, getTextDirection as x, detectPlatform as xi, NavigationNodeKind as xn, NumOptions as xr, PopOperation as xt, SimpleTranslatorOptions as y, resolveMessages as yi, NavigationError as yn, optional as yr, NavigationOpKind as yt, BrowserContextOptions as z, ActionDispatcher as zi, HostCheckResult as zn, runStandard as zr, SerializedLeaf as zt };
+//# sourceMappingURL=server-data-HVSgxEac.d.mts.map