@finesoft/front 0.2.0 → 0.4.0

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

@@ -1,1573 +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 的校验，吸收同步/异步差异 */
-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/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/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;
-}
-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;
-}
-declare function registerActionHandlers(deps: ActionHandlerDependencies): void;
-//#endregion
-//#region ../browser/src/start-app.d.ts
-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;
-}
-/**
- * 启动客户端应用
- *
- * 自动执行 hydration 全流程。
- */
-declare function startBrowserApp(config: BrowserAppConfig): Promise<void>;
-//#endregion
-//#region ../browser/src/utils/history.d.ts
-interface HistoryOptions {
-  getScrollablePageElement: () => HTMLElement | null;
-}
-declare class History<State> {
-  private readonly entries;
-  private readonly log;
-  private readonly getScrollablePageElement;
-  private currentStateId;
-  constructor(log: Logger, options: HistoryOptions, sizeLimit?: number);
-  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 { RenderMode as $, BaseLogger as $n, RouteAddOptions as $t, IntersectionImpressionObserver as A, DEP_KEYS as An, Translator as At, buildUrl as B, TranslationMessages as Bn, ParamsFor as Bt, PluralRuleProvider as C, BasePage as Cn, Framework as Ct, WithFieldsRecorder as D, markPublic as Dn, LocaleAttributes as Dt, resolvePluralKey as E, isPublicMarked as En, PrefetchedIntents as Et, BrowserContextOptions as F, Net as Fn, CompositeLogger as Ft, PWADisplayMode as G, EventRecorder as Gn, NumOptions as Gt, removeHost as H, resolveMessages as Hn, StripOptional as Ht, ServerContextOptions as I, Storage as In, CompositeLoggerFactory as It, Optional as J, MetricsFieldsProvider as Jn, int as Jt, getPWADisplayMode as K, ImpressionEntry as Kn, StrOptions as Kt, createBrowserContext as L, makeDependencies as Ln, ExtractParamNames as Lt, CompositeEventRecorder as M, FeatureFlagsProvider as Mn, shouldLog as Mt, runAfterLoadGuards as N, MakeDependenciesOptions as Nn, ConsoleLogger as Nt, VoidEventRecorder as O, RequestScopedKey as On, LocaleInfo as Ot, runBeforeLoadGuards as P, MetricsRecorder as Pn, ConsoleLoggerFactory as Pt, DefineRoutesOptions as Q, ReportingLoggerOptions as Qn, uuid as Qt, createServerContext as R, MessagesLoader as Rn, InferParams as Rt, PluralCategory as S, BASE_PAGE_FIELDS as Sn, safeErrorPage as St, interpolate as T, getPublicFields as Tn, PrefetchedIntent as Tt, removeQueryParams as U, PlatformInfo as Un, optional as Ut, getBaseUrl as V, resolveConfiguredMessages as Vn, QuerySchemaMap as Vt, removeScheme as W, detectPlatform as Wn, withDefault as Wt, isSome as X, ReportingLogger as Xn, oneOf as Xt, isNone as Y, ReportCallback as Yn, num as Yt, LruMap as Z, ReportingLoggerFactory as Zn, str as Zt, getTextDirection as _, RewriteResult as _n, isFlowAction as _r, ResponseInterceptor as _t, BrowserAppConfig as a, StandardResult as an, Intent as ar, mapEach as at, resolveLocaleFromUrl as b, redirect as bn, BaseShelf as bt, registerActionHandlers as c, runStandard as cn, ActionDispatcher as cr, BaseController as ct, registerFlowActionHandler as d, DenyResult as dn, Action as dr, classifyUrl as dt, RouteMatch as en, Logger as er, RouteDefinition as et, ExternalUrlDependencies as f, MiddlewareResult as fn, CompoundAction as fr, HostGuardError as ft, getLocaleAttributes as g, RedirectResult as gn, isExternalUrlAction as gr, RequestInterceptor as gt, SimpleTranslatorOptions as h, PostLoadContext as hn, isCompoundAction as hr, HttpError as ht, History as i, StandardIssue as in, IntentDispatcher as ir, Mapper as it, ConsoleEventRecorder as j, FeatureFlags as jn, resetFilterCache as jt, ImpressionObserverOptions as k, defineRequestScopedKey as kn, TextDirection as kt, FlowActionCallbacks as l, AfterLoadGuard as ln, ActionHandler as lr, HostCheckResult as lt, SimpleTranslator as m, NextResult as mn, FlowAction as mr, HttpClientConfig as mt, deserializeServerData as n, InferOutput as nn, SecureFetchOptions as nr, route as nt, startBrowserApp as o, StandardSchemaV1 as on, IntentController as or, pipe as ot, registerExternalUrlHandler as p, NavigationContext as pn, ExternalUrlAction as pr, HttpClient as pt, None as q, ImpressionObserver as qn, bool as qt, tryScroll as r, ParamSchema as rn, secureFetch as rr, AsyncMapper as rt, ActionHandlerDependencies as s, makeSchema as sn, Container as sr, pipeAsync as st, createPrefetchedIntentsFromDom as t, Router as tn, LoggerFactory as tr, defineRoutes as tt, FlowActionDependencies as u, BeforeLoadGuard as un, ACTION_KINDS as ur, classifyHost as ut, isRtl as v, deny as vn, makeExternalUrlAction as vr, stableStringify as vt, englishPlural as w, FINESOFT_PUBLIC as wn, FrameworkConfig as wt, setHtmlLocaleAttributes as x, rewrite as xn, SafeErrorPageOptions as xt, makeLocaleInfo as y, next as yn, makeFlowAction as yr, BaseItem as yt, generateUuid as z, MessagesLoaderContext as zn, InferQuery as zt };
-//# sourceMappingURL=server-data-DQzknR97.d.mts.map