@finesoft/front 0.1.53 → 0.1.55

package/dist/index.d.mts

@@ -60,12 +60,20 @@ type Factory<T> = () => T;
 declare class Container {
   private registrations;
   private resolutionStack;
+  private parent?;
   /** 注册依赖（默认单例） */
   register<T>(key: string, factory: Factory<T>, singleton?: boolean): this;
-  /** 解析依赖 */
+  /** 解析依赖 — 当前容器未注册时回退到 parent */
   resolve<T>(key: string): T;
-  /** 检查是否已注册 */
+  /** 检查是否已注册（含 parent） */
   has(key: string): boolean;
+  /**
+   * 创建子容器（请求级 scope）
+   *
+   * 子容器可覆写父容器的依赖（如每请求的 locale、user），
+   * 未覆写的 key 自动回退到父容器解析。
+   */
+  createScope(): Container;
   /** 销毁容器，清除所有缓存 */
   dispose(): void;
 }
@@ -117,6 +125,110 @@ 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/dependencies/make-dependencies.d.ts
 /** 网络请求层 */
 interface Net {
@@ -134,10 +246,24 @@ interface FeatureFlags {
   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";
@@ -147,10 +273,47 @@ declare const DEP_KEYS: {
   readonly FEATURE_FLAGS: "featureFlags";
   readonly METRICS: "metrics";
   readonly FETCH: "fetch";
+  readonly EVENT_RECORDER: "eventRecorder";
+  readonly LOCALE: "locale";
+  readonly PLATFORM: "platform";
+  readonly TRANSLATOR: "translator";
 };
+/** 扁平格式消息：key → 翻译字符串 */
+type FlatMessages = Record<string, string>;
+/** 嵌套格式消息值：字符串 或 复数表 */
+type NestedMessageValue = string | Record<string, string>;
+/** 按 locale 分组的嵌套消息 */
+type LocaleMessages = Record<string, Record<string, NestedMessageValue>>;
+/**
+ * 翻译消息映射
+ *
+ * - 扁平格式: `{ "greeting": "Hello", "itemCount.one": "1 item" }`
+ * - 按 locale 分组: `{ "en": { "greeting": "Hello", "itemCount": { "one": "1 item" } } }`
+ */
+type TranslationMessages = FlatMessages | LocaleMessages;
 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;
+  /**
+   * 翻译消息映射 — 与 locale 同时提供时自动创建 SimpleTranslator 注册到容器。
+   *
+   * 支持两种格式：
+   * 1. 扁平格式（直接用于当前 locale）：
+   *    `{ "greeting": "Hello", "itemCount.one": "1 item" }`
+   * 2. 按 locale 分组 + 复数嵌套（自动提取当前 locale 并展平）：
+   *    `{ "en": { "greeting": "Hello", "itemCount": { "one": "1 item", "other": "{count} items" } } }`
+   */
+  messages?: TranslationMessages;
 }
 declare function makeDependencies(container: Container, options?: MakeDependenciesOptions): void;
 //#endregion
@@ -256,16 +419,6 @@ declare class Router {
   private parseUrl;
 }
 //#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/composite.d.ts
 declare class CompositeLoggerFactory implements LoggerFactory {
   private readonly factories;
@@ -297,6 +450,51 @@ declare class ConsoleLoggerFactory implements LoggerFactory {
 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 {
@@ -348,6 +546,12 @@ declare class Framework {
   routeUrl(url: string): RouteMatch | null;
   /** 记录页面访问事件 */
   didEnterPage(page: BasePage): void;
+  /** 获取 locale 信息（如果已配置） */
+  getLocale(): LocaleAttributes | undefined;
+  /** 获取翻译器（如果已通过 messages + locale 配置） */
+  getTranslator(): Translator | undefined;
+  /** 获取平台信息 */
+  getPlatform(): PlatformInfo;
   /** 注册 Action 处理器 */
   onAction<A extends Action>(kind: string, handler: ActionHandler<A>): void;
   /** 注册 Intent Controller */
@@ -401,6 +605,14 @@ declare class HttpError extends Error {
   readonly body?: string | undefined;
   constructor(status: number, statusText: string, body?: string | undefined);
 }
+/** 请求拦截器 — 在发送前修改请求 */
+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"） */
@@ -409,6 +621,10 @@ interface HttpClientConfig {
   defaultHeaders?: Record<string, string>;
   /** 自定义 fetch 实现（便于测试或 SSR） */
   fetch?: typeof globalThis.fetch;
+  /** 请求拦截器（按注册顺序执行） */
+  requestInterceptors?: RequestInterceptor[];
+  /** 响应拦截器（按注册顺序执行） */
+  responseInterceptors?: ResponseInterceptor[];
 }
 /**
  * 通用 HTTP 客户端基类
@@ -428,7 +644,13 @@ 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;
   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 */
@@ -582,6 +804,22 @@ interface RouteDefinition {
    */
   afterLoad?: AfterLoadGuard[];
 }
+/** 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
  *
@@ -599,7 +837,7 @@ interface RouteDefinition {
  * ]);
  * ```
  */
-declare function defineRoutes(framework: Framework, definitions: RouteDefinition[]): void;
+declare function defineRoutes(framework: Framework, definitions: RouteDefinition[], options?: DefineRoutesOptions): void;
 //#endregion
 //#region ../core/src/utils/lru-map.d.ts
 /**
@@ -626,6 +864,22 @@ 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 工具函数
@@ -671,6 +925,159 @@ declare function runBeforeLoadGuards(guards: BeforeLoadGuard[], ctx: NavigationC
 /** 执行 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;
@@ -723,6 +1130,18 @@ interface BrowserAppConfig {
   mountId?: string;
   /** 获取可滚动页面元素，用于滚动位置保存/恢复 */
   getScrollablePageElement?: () => HTMLElement | null;
+  /**
+   * 启动前钩子 — 在 Framework 创建后、挂载前执行
+   *
+   * 用于初始化错误监控、埋点 SDK、i18n 等。
+   */
+  onBeforeStart?: (framework: Framework) => void | Promise<void>;
+  /**
+   * 启动后钩子 — 在初始页面触发后执行
+   *
+   * 用于启动后操作（如 service worker 注册、性能打点）。
+   */
+  onAfterStart?: (framework: Framework) => void | Promise<void>;
   /**
    * 挂载应用到 DOM
    *
@@ -740,6 +1159,13 @@ interface BrowserAppConfig {
   }) => void;
   /** FlowAction / ExternalUrl 回调 */
   callbacks: FlowActionCallbacks;
+  /**
+   * Framework 配置 — locale、reportCallback、eventRecorder 等
+   *
+   * 传入后会在 Framework.create() 时合并。
+   * prefetchedIntents 由框架自动从 DOM 提取，无需传入。
+   */
+  frameworkConfig?: Omit<FrameworkConfig, "prefetchedIntents">;
 }
 /**
  * 启动客户端应用
@@ -800,6 +1226,11 @@ interface SSRRenderOptions {
   renderApp: (page: BasePage, framework: Framework) => SSRAppResult | Promise<SSRAppResult>;
   /** 可选的 SSR 请求上下文（如自定义 fetch） */
   ssrContext?: SSRContext;
+  /** 解析请求 locale 的回调（返回 lang + dir 用于 <html> 属性） */
+  resolveLocale?: (url: string, request?: Request) => {
+    lang: string;
+    dir: string;
+  } | undefined;
 }
 /** SSR 请求级上下文 */
 interface SSRContext {
@@ -829,6 +1260,11 @@ interface SSRRenderResult {
   };
   /** 自定义 slot 替换 */
   slots?: Record<string, string>;
+  /** 解析出的 locale 属性（用于 <html lang="" dir="">） */
+  locale?: {
+    lang: string;
+    dir: string;
+  };
 }
 declare function ssrRender(options: SSRRenderOptions): Promise<SSRRenderResult>;
 //#endregion
@@ -842,11 +1278,17 @@ interface SSRRenderConfig {
    * 应用层渲染函数
    *
    * @param page - 当前页面数据
+   * @param framework - Framework 实例（可用于获取 translator、locale 等）
    * @returns SSR 渲染结果 { html, head, css, slots? }
    */
-  renderApp: (page: BasePage) => SSRAppResult | Promise<SSRAppResult>;
+  renderApp: (page: BasePage, framework: Framework) => SSRAppResult | Promise<SSRAppResult>;
   /** Framework 构造配置（可选） */
   frameworkConfig?: FrameworkConfig;
+  /** 解析请求 locale 的回调（返回 lang + dir 用于 <html> 属性） */
+  resolveLocale?: (url: string, request?: Request) => {
+    lang: string;
+    dir: string;
+  } | undefined;
 }
 /**
  * 创建 render 函数
@@ -873,13 +1315,23 @@ interface InjectSSROptions {
   serializedData: string;
   /** 自定义 slot 替换：`{ "my-slot": "<div>content</div>" }` 会替换 `<!--ssr-my-slot-->`（含 `<!--ssr-lang-->`） */
   slots?: Record<string, string>;
+  /** Locale 属性，自动注入到 <html> 标签 */
+  locale?: {
+    lang: string;
+    dir: string;
+  };
 }
 declare function injectSSRContent(options: InjectSSROptions): string;
 /**
  * CSR 空壳注入 — 清空所有占位符
  * 用于 renderMode === "csr" 的路由
+ *
+ * @param locale - 可选的 locale 属性，注入到 `<html lang="" dir="">`
  */
-declare function injectCSRShell(template: string): string;
+declare function injectCSRShell(template: string, locale?: {
+  lang: string;
+  dir: string;
+}): string;
 //#endregion
 //#region ../ssr/src/server-data.d.ts
 declare function serializeServerData(data: PrefetchedIntent[]): string;
@@ -942,6 +1394,10 @@ interface AdapterContext {
   renderModes?: Record<string, string>;
   /** 声明式代理路由配置 */
   proxies?: ProxyRouteConfig[];
+  /** 支持的 locale 列表（用于预渲染 locale 矩阵） */
+  locales?: string[];
+  /** 默认 locale（CSR shell 使用） */
+  defaultLocale?: string;
   vite: any;
   fs: typeof node_fs0;
   path: {
@@ -1058,6 +1514,10 @@ interface SSRModule {
       status: number;
     };
     slots?: Record<string, string>;
+    locale?: {
+      lang: string;
+      dir: string;
+    };
   }>;
   serializeServerData: (data: unknown) => string;
 }
@@ -1083,6 +1543,11 @@ interface SSRAppOptions {
    * 优先级高于路由级 renderMode。
    */
   renderModes?: Record<string, string>;
+  /**
+   * 默认 locale（如 "zh-Hans"、"en-US"）。
+   * 用于 CSR 早退场景（配置级 renderMode=csr，未调用 render）将 lang/dir 注入 `<html>` 属性。
+   */
+  defaultLocale?: string;
 }
 declare function createSSRApp(options: SSRAppOptions): Hono;
 //#endregion
@@ -1212,6 +1677,17 @@ interface FinesoftFrontViteOptions {
    * 如果项目不使用声明式路由定义，可以不设置。
    */
   bootstrapEntry?: string;
+  /**
+   * 默认 locale（如 "zh-Hans"、"en-US"）。
+   * 用于 CSR 壳注入 `<html lang="" dir="">`，以及预渲染时的默认语言。
+   */
+  defaultLocale?: string;
+  /**
+   * 预渲染支持的语言列表。
+   * 提供后，每个 prerender 路由会与每个 locale 组合生成 `/:locale/path` 版本。
+   * `defaultLocale` 的路由同时输出无前缀版本。
+   */
+  locales?: string[];
 }
 declare function finesoftFrontViteConfig(options?: FinesoftFrontViteOptions): {
   name: string;
@@ -1246,5 +1722,5 @@ declare function finesoftFrontViteConfig(options?: FinesoftFrontViteOptions): {
   closeBundle(): Promise<void>;
 };
 //#endregion
-export { ACTION_KINDS, Action, ActionDispatcher, ActionHandler, type ActionHandlerDependencies, type Adapter, type AdapterContext, AfterLoadGuard, AsyncMapper, BaseController, BaseItem, BaseLogger, BasePage, BaseShelf, BeforeLoadGuard, type BrowserAppConfig, BrowserContextOptions, CompositeLogger, CompositeLoggerFactory, CompoundAction, ConsoleLogger, ConsoleLoggerFactory, Container, DEP_KEYS, DenyResult, ExternalUrlAction, type ExternalUrlDependencies, FeatureFlags, type FinesoftFrontViteOptions, FlowAction, type FlowActionCallbacks, type FlowActionDependencies, Framework, FrameworkConfig, History, HttpClient, HttpClientConfig, HttpError, type InjectSSROptions, Intent, IntentController, IntentDispatcher, type Logger, Logger as LoggerInterface, type LoggerFactory, LruMap, Mapper, MetricsRecorder, MiddlewareResult, NavigationContext, Net, NextResult, None, Optional, PostLoadContext, PrefetchedIntent, PrefetchedIntents, type ProxyAuthConfig, type ProxyRouteConfig, RedirectResult, RenderMode, RewriteResult, RouteAddOptions, RouteDefinition, RouteMatch, Router, type RuntimeInfo, type SSRAppOptions, type SSRContext, type SSRModule, type SSRRenderConfig, type SSRRenderOptions, type SSRRenderResult, SSR_PLACEHOLDERS, type ServerConfig, ServerContextOptions, type ServerInstance, type StartServerOptions, Storage, autoAdapter, buildUrl, cloudflareAdapter, createBrowserContext, createPrefetchedIntentsFromDom, createSSRApp, createSSRRender, createServer, createServerContext, defineRoutes, deny, deserializeServerData, detectRuntime, finesoftFrontViteConfig, generateProxyCode, generateUuid, getBaseUrl, injectCSRShell, injectSSRContent, isCompoundAction, isExternalUrlAction, isFlowAction, isNone, isSome, makeDependencies, makeExternalUrlAction, makeFlowAction, mapEach, netlifyAdapter, next, nodeAdapter, parseAcceptLanguage, pipe, pipeAsync, redirect, registerActionHandlers, registerExternalUrlHandler, registerFlowActionHandler, registerProxyRoutes, removeHost, removeQueryParams, removeScheme, resetFilterCache, resolveAdapter, resolveRoot, rewrite, runAfterLoadGuards, runBeforeLoadGuards, serializeServerData, shouldLog, ssrRender, stableStringify, startBrowserApp, startServer, staticAdapter, tryScroll, vercelAdapter };
+export { ACTION_KINDS, Action, ActionDispatcher, ActionHandler, type ActionHandlerDependencies, type Adapter, type AdapterContext, AfterLoadGuard, AsyncMapper, BaseController, BaseItem, BaseLogger, BasePage, BaseShelf, BeforeLoadGuard, type BrowserAppConfig, BrowserContextOptions, CompositeEventRecorder, CompositeLogger, CompositeLoggerFactory, CompoundAction, ConsoleEventRecorder, ConsoleLogger, ConsoleLoggerFactory, Container, DEP_KEYS, DefineRoutesOptions, DenyResult, EventRecorder, ExternalUrlAction, type ExternalUrlDependencies, FeatureFlags, FeatureFlagsProvider, type FinesoftFrontViteOptions, FlowAction, type FlowActionCallbacks, type FlowActionDependencies, Framework, FrameworkConfig, History, HttpClient, HttpClientConfig, HttpError, ImpressionEntry, ImpressionObserver, ImpressionObserverOptions, type InjectSSROptions, Intent, IntentController, IntentDispatcher, IntersectionImpressionObserver, LocaleAttributes, LocaleInfo, type Logger, Logger as LoggerInterface, type LoggerFactory, LruMap, MakeDependenciesOptions, Mapper, MetricsFieldsProvider, MetricsRecorder, MiddlewareResult, NavigationContext, Net, NextResult, None, Optional, PWADisplayMode, PlatformInfo, PluralCategory, PluralRuleProvider, PostLoadContext, PrefetchedIntent, PrefetchedIntents, type ProxyAuthConfig, type ProxyRouteConfig, RedirectResult, RenderMode, ReportCallback, ReportingLogger, ReportingLoggerFactory, ReportingLoggerOptions, RequestInterceptor, ResponseInterceptor, RewriteResult, RouteAddOptions, RouteDefinition, RouteMatch, Router, type RuntimeInfo, type SSRAppOptions, type SSRContext, type SSRModule, type SSRRenderConfig, type SSRRenderOptions, type SSRRenderResult, SSR_PLACEHOLDERS, type ServerConfig, ServerContextOptions, type ServerInstance, SimpleTranslator, SimpleTranslatorOptions, type StartServerOptions, Storage, TextDirection, TranslationMessages, Translator, VoidEventRecorder, WithFieldsRecorder, autoAdapter, buildUrl, cloudflareAdapter, createBrowserContext, createPrefetchedIntentsFromDom, createSSRApp, createSSRRender, createServer, createServerContext, defineRoutes, deny, deserializeServerData, detectPlatform, detectRuntime, englishPlural, finesoftFrontViteConfig, generateProxyCode, generateUuid, getBaseUrl, getLocaleAttributes, getPWADisplayMode, getTextDirection, injectCSRShell, injectSSRContent, interpolate, isCompoundAction, isExternalUrlAction, isFlowAction, isNone, isRtl, isSome, makeDependencies, makeExternalUrlAction, makeFlowAction, makeLocaleInfo, mapEach, netlifyAdapter, next, nodeAdapter, parseAcceptLanguage, pipe, pipeAsync, redirect, registerActionHandlers, registerExternalUrlHandler, registerFlowActionHandler, registerProxyRoutes, removeHost, removeQueryParams, removeScheme, resetFilterCache, resolveAdapter, resolveLocaleFromUrl, resolvePluralKey, resolveRoot, rewrite, runAfterLoadGuards, runBeforeLoadGuards, serializeServerData, setHtmlLocaleAttributes, shouldLog, ssrRender, stableStringify, startBrowserApp, startServer, staticAdapter, tryScroll, vercelAdapter };
 //# sourceMappingURL=index.d.mts.map