@finesoft/front 0.1.3 → 0.1.12

package/dist/index.d.cts

@@ -1,754 +1,8 @@
+import { FrameworkConfig, Framework, BasePage, PrefetchedIntent } from './browser.cjs';
+export { ACTION_KINDS, Action, ActionDispatcher, ActionHandler, ActionHandlerDependencies, AsyncMapper, BaseController, BaseItem, BaseLogger, BaseShelf, BrowserAppConfig, CompositeLogger, CompositeLoggerFactory, CompoundAction, ConsoleLogger, ConsoleLoggerFactory, Container, DEP_KEYS, ExternalUrlAction, ExternalUrlDependencies, FeatureFlags, FlowAction, FlowActionCallbacks, FlowActionDependencies, History, HttpClient, HttpClientConfig, HttpError, Intent, IntentController, IntentDispatcher, Locale, Logger, LoggerFactory, Logger as LoggerInterface, LruMap, Mapper, MetricsRecorder, Net, None, Optional, PrefetchedIntents, RouteDefinition, RouteMatch, Router, Storage, buildUrl, createPrefetchedIntentsFromDom, defineRoutes, deserializeServerData, generateUuid, getBaseUrl, isCompoundAction, isExternalUrlAction, isFlowAction, isNone, isSome, makeDependencies, makeExternalUrlAction, makeFlowAction, mapEach, pipe, pipeAsync, registerActionHandlers, registerExternalUrlHandler, registerFlowActionHandler, removeHost, removeQueryParams, removeScheme, resetFilterCache, shouldLog, stableStringify, startBrowserApp, tryScroll } from './browser.cjs';
 import { Hono } from 'hono';
 import { ViteDevServer } from 'vite';
 
-/**
- * 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;
-
-/**
- * ActionDispatcher — Action 分发器
- *
- * 注册不同 kind 的 handler，按类型分发。
- * CompoundAction 自动展开递归执行。
- */
-
-/** Action 处理器函数类型 */
-type ActionHandler<A extends Action = Action> = (action: A) => Promise<void> | void;
-declare class ActionDispatcher {
-    private handlers;
-    private wiredActions;
-    /** 注册指定 kind 的 handler（防止重复注册） */
-    onAction<A extends Action>(kind: string, handler: ActionHandler<A>): void;
-    /** 执行一个 Action（CompoundAction 递归展开） */
-    perform(action: Action): Promise<void>;
-}
-
-/**
- * Container — 通用的依赖注入容器
- */
-type Factory<T> = () => T;
-declare class Container {
-    private registrations;
-    /** 注册依赖（默认单例） */
-    register<T>(key: string, factory: Factory<T>, singleton?: boolean): this;
-    /** 解析依赖 */
-    resolve<T>(key: string): T;
-    /** 检查是否已注册 */
-    has(key: string): boolean;
-    /** 销毁容器，清除所有缓存 */
-    dispose(): void;
-}
-
-/**
- * Intent 类型定义
- */
-
-/** Intent — 描述一个用户意图 */
-interface Intent<T = unknown> {
-    /** Intent 标识符（用于匹配 Controller） */
-    id: string;
-    /** 意图参数 */
-    params?: Record<string, string>;
-    /** 预期返回的数据（仅用于类型推断） */
-    _returnType?: T;
-}
-/** Intent Controller — 处理特定 intentId 的业务逻辑 */
-interface IntentController<T = unknown> {
-    /** Controller 对应的 Intent ID */
-    intentId: string;
-    /** 执行意图，返回页面数据 */
-    perform(intent: Intent<T>, container: Container): Promise<T> | T;
-}
-
-/**
- * IntentDispatcher — Intent 分发器
- *
- * 注册 IntentController，按 intentId 分发。
- */
-
-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;
-}
-
-/** 日志级别 */
-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;
-}
-
-/**
- * 依赖工厂 — 创建所有基础依赖
- */
-
-/** 网络请求层 */
-interface Net {
-    fetch(url: string, options?: RequestInit): Promise<Response>;
-}
-/** 多语言状态 */
-interface Locale {
-    language: string;
-    storefront: string;
-    setActiveLocale(language: string, storefront: string): void;
-}
-/** 存储接口 */
-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;
-}
-/** Metrics 记录器 */
-interface MetricsRecorder {
-    recordPageView(page: string, fields?: Record<string, unknown>): void;
-    recordEvent(name: string, fields?: Record<string, unknown>): void;
-}
-declare const DEP_KEYS: {
-    readonly LOGGER: "logger";
-    readonly LOGGER_FACTORY: "loggerFactory";
-    readonly NET: "net";
-    readonly LOCALE: "locale";
-    readonly STORAGE: "storage";
-    readonly FEATURE_FLAGS: "featureFlags";
-    readonly METRICS: "metrics";
-    readonly FETCH: "fetch";
-};
-interface MakeDependenciesOptions {
-    fetch?: typeof globalThis.fetch;
-    language?: string;
-    storefront?: string;
-    featureFlags?: Record<string, boolean | string | number>;
-}
-declare function makeDependencies(container: Container, options?: MakeDependenciesOptions): void;
-
-/**
- * URL 路由器 — URL pattern → Intent + FlowAction
- */
-
-/** 路由匹配结果 */
-interface RouteMatch {
-    intent: Intent;
-    action: FlowAction;
-}
-declare class Router {
-    private routes;
-    /** 添加路由规则 */
-    add(pattern: string, intentId: string): this;
-    /** 解析 URL → RouteMatch */
-    resolve(urlOrPath: string): RouteMatch | null;
-    /** 获取所有已注册的路由 */
-    getRoutes(): string[];
-    private extractPath;
-    private extractQueryParams;
-}
-
-/**
- * BaseLogger — 抽象日志基类
- */
-
-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;
-}
-
-/**
- * Composite Logger — 组合日志，广播到多个后端
- */
-
-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;
-}
-
-/**
- * ConsoleLogger — 基于 console 的日志实现
- */
-
-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;
-}
-
-/**
- * localStorage 日志级别过滤
- *
- * 通过 localStorage.onyxLog 控制日志级别:
- *   '*=info'              — 全局 info 及以上
- *   '*=info,Foo=off'      — 全局 info，Foo 静默
- *   'Bar=error,Baz=warn'  — Bar 只输出 error，Baz 输出 warn+
- */
-
-declare function shouldLog(name: string, level: Level): boolean;
-declare function resetFilterCache(): void;
-
-/**
- * BasePage — 所有页面共享的基础属性
- *
- * 具体页面类型由应用层定义并扩展此接口。
- */
-interface BasePage {
-    id: string;
-    pageType: string;
-    title: string;
-    description?: string;
-    url?: string;
-}
-
-/**
- * PrefetchedIntents — SSR 数据缓存
- *
- * 服务端渲染时将 Intent→Data 映射序列化嵌入 HTML，
- * 客户端 hydrate 时提取缓存。Framework.dispatch() 优先查缓存，
- * 命中则直接返回，未命中则走 Controller 调度。
- */
-
-/** 预获取的 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;
-}
-
-/**
- * Framework — 框架核心类
- *
- * 对应原版 Jet 类，统一管理: DI 容器、Intent 分发、Action 分发、路由、Metrics。
- * 纯 TypeScript，不依赖任何 UI 框架。
- */
-
-/** 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 constructor();
-    /** 创建并初始化 Framework 实例 */
-    static create(config?: FrameworkConfig): Framework;
-    /** 分发 Intent — 获取页面数据 */
-    dispatch<T>(intent: Intent<T>): Promise<T>;
-    /** 执行 Action — 处理用户交互 */
-    perform(action: Action): Promise<void>;
-    /** 路由 URL — 将 URL 解析为 Intent + Action */
-    routeUrl(url: string): RouteMatch | null;
-    /** 记录页面访问事件 */
-    didEnterPage(page: BasePage): void;
-    /** 注册 Action 处理器 */
-    onAction<A extends Action>(kind: string, handler: ActionHandler<A>): void;
-    /** 注册 Intent Controller */
-    registerIntent(controller: IntentController): void;
-    /** 销毁 Framework 实例 */
-    dispose(): void;
-}
-
-/**
- * BaseShelf / BaseItem — 所有 Shelf 和 Item 共享的基础属性
- *
- * 具体 Shelf/Item 类型由应用层定义并扩展此接口。
- */
-
-interface BaseShelf {
-    id: string;
-    shelfType: string;
-    title?: string;
-    subtitle?: string;
-    seeAllAction?: Action;
-    isHorizontal?: boolean;
-}
-interface BaseItem {
-    id: string;
-    itemType: string;
-    clickAction?: Action;
-}
-
-/**
- * stableStringify — 确定性 JSON 序列化（keys 按字母排序）
- *
- * 用作缓存 key：相同内容的对象始终产生相同字符串。
- */
-declare function stableStringify(obj: unknown): string;
-
-/**
- * HttpClient — 通用 HTTP 客户端基类
- *
- * 为 API Client 提供标准化的 HTTP 请求能力。
- * 子类继承后只需关注业务端点定义，不需要重复实现 fetch / JSON 解析 / 错误处理。
- */
-/** HTTP 请求错误 */
-declare class HttpError extends Error {
-    readonly status: number;
-    readonly statusText: string;
-    readonly body?: string | undefined;
-    constructor(status: number, statusText: string, body?: string | undefined);
-}
-/** HttpClient 构造配置 */
-interface HttpClientConfig {
-    /** API base URL（如 "/api" 或 "https://example.com/api"） */
-    baseUrl: string;
-    /** 默认请求头 */
-    defaultHeaders?: Record<string, string>;
-    /** 自定义 fetch 实现（便于测试或 SSR） */
-    fetch?: typeof globalThis.fetch;
-}
-/**
- * 通用 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;
-    constructor(config: HttpClientConfig);
-    /** 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)
-     * - 默认 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;
-}
-
-/**
- * BaseController — 抽象 Intent Controller 基类
- *
- * 提供标准化的 try/catch → fallback 模式。
- * 子类只需实现 execute() 和可选的 fallback()。
- */
-
-/**
- * 抽象 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, string | undefined> = Record<string, string>, 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>;
-}
-
-/**
- * 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[]>;
-
-/**
- * defineRoutes — 声明式路由 + Controller 注册
- *
- * 将命令式的路由注册 (20+ 行 framework.router.add / framework.registerIntent)
- * 简化为声明式配置数组。
- */
-
-/** 单条路由定义 */
-interface RouteDefinition {
-    /** URL pattern (如 "/product/:productId") */
-    path: string;
-    /** Intent ID (如 "product-page") */
-    intentId: string;
-    /**
-     * Controller 实例（可选）。
-     * 同一个 intentId 的多条路由只需在第一条提供 controller。
-     */
-    controller?: IntentController;
-}
-/**
- * 声明式注册路由和 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[]): void;
-
-/**
- * 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;
-}
-
-/**
- * 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;
-
-/**
- * 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;
-
-/**
- * UUID v4 生成器
- */
-declare function generateUuid(): string;
-
-/**
- * ExternalUrl Action Handler — 外部链接处理器
- */
-
-interface ExternalUrlDependencies {
-    framework: Framework;
-    log: Logger;
-}
-declare function registerExternalUrlHandler(deps: ExternalUrlDependencies): void;
-
-/**
- * FlowAction Handler — 核心 SPA 导航处理器
- *
- * 通过 FlowActionCallbacks 注入 UI 更新回调，
- * 不直接依赖任何 UI 框架的 store。
- */
-
-/** 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;
-}
-declare function registerFlowActionHandler(deps: FlowActionDependencies): void;
-
-/**
- * Action Handler 统一注册入口
- */
-
-interface ActionHandlerDependencies {
-    framework: Framework;
-    log: Logger;
-    callbacks: FlowActionCallbacks;
-    updateApp: (props: {
-        page: Promise<BasePage> | BasePage;
-        isFirstPage?: boolean;
-    }) => void;
-}
-declare function registerActionHandlers(deps: ActionHandlerDependencies): void;
-
-/**
- * startBrowserApp — 客户端 hydration 一站式启动
- *
- * 封装:
- * 1. PrefetchedIntents 从 DOM 提取
- * 2. Framework 创建 + 引导
- * 3. 应用层挂载（通过 mount 回调，框架无关）
- * 4. Action handlers 注册
- * 5. 初始页面触发
- */
-
-interface BrowserAppConfig {
-    /** 注册 controllers 和路由的引导函数 */
-    bootstrap: (framework: Framework) => void;
-    /** 默认语言（回退值） */
-    defaultLocale?: string;
-    /**
-     * 挂载应用到 DOM
-     *
-     * 框架无关 — Svelte / React / Vue 均可通过此回调实现。
-     *
-     * @param target - DOM 挂载点
-     * @param context - Framework 实例 + 语言
-     * @returns 更新函数，用于后续页面切换
-     */
-    mount: (target: HTMLElement, context: {
-        framework: Framework;
-        locale: string;
-    }) => (props: {
-        page: Promise<BasePage> | BasePage;
-        isFirstPage?: boolean;
-    }) => void;
-    /** FlowAction / ExternalUrl 回调 */
-    callbacks: FlowActionCallbacks;
-}
-/**
- * 启动客户端应用
- *
- * 自动执行 hydration 全流程。
- */
-declare function startBrowserApp(config: BrowserAppConfig): Promise<void>;
-
-/**
- * History 管理器 — 浏览器历史状态 + 滚动位置
- */
-
-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): void;
-    updateState(update: (current?: State) => State): void;
-    private get scrollTop();
-    private set scrollTop(value);
-}
-
-/**
- * tryScroll — 渐进式滚动位置恢复
- *
- * 使用 rAF 循环等待页面高度足够后恢复滚动位置。
- */
-
-declare function tryScroll(log: Logger, getScrollableElement: () => HTMLElement | null, scrollY: number): void;
-
-/**
- * Server Data (browser side) — 从 DOM 反序列化服务端嵌入数据
- */
-
-/**
- * 从 DOM 反序列化服务端嵌入的数据。
- * 读取 `<script id="serialized-server-data">` 的内容并移除标签。
- */
-declare function deserializeServerData(): PrefetchedIntent[] | undefined;
-/**
- * 从 DOM 提取 SSR 数据并构建 PrefetchedIntents 实例。
- * 替代原来的 PrefetchedIntents.fromDom()。
- */
-declare function createPrefetchedIntentsFromDom(): PrefetchedIntents;
-
 /**
  * ssrRender — 通用 SSR 渲染管线
  *
@@ -817,6 +71,13 @@ declare function createSSRRender(config: SSRRenderConfig): (url: string, locale:
 /**
  * injectSSRContent — 将 SSR 渲染结果注入 HTML 模板
  */
+/** SSR HTML 模板占位符常量 */
+declare const SSR_PLACEHOLDERS: {
+    readonly LANG: "<!--ssr-lang-->";
+    readonly HEAD: "<!--ssr-head-->";
+    readonly BODY: "<!--ssr-body-->";
+    readonly DATA: "<!--ssr-data-->";
+};
 interface InjectSSROptions {
     template: string;
     locale: string;
@@ -952,9 +213,15 @@ interface StartServerOptions {
     vite?: ViteDevServer;
     /** 运行时信息（可选，不传时自动检测） */
     runtime?: RuntimeInfo;
+    /** 已注册的路由列表（用于启动日志） */
+    routes?: string[];
+    /** 支持的语言列表（用于启动日志） */
+    locales?: string[];
+    /** SSR 入口路径（用于启动日志） */
+    ssrEntryPath?: string;
 }
 declare function startServer(options: StartServerOptions): Promise<{
     vite?: ViteDevServer;
 }>;
 
-export { ACTION_KINDS, type Action, ActionDispatcher, type ActionHandler, type ActionHandlerDependencies, type AsyncMapper, BaseController, type BaseItem, BaseLogger, type BasePage, type BaseShelf, type BrowserAppConfig, CompositeLogger, CompositeLoggerFactory, type CompoundAction, ConsoleLogger, ConsoleLoggerFactory, Container, DEP_KEYS, type ExternalUrlAction, type ExternalUrlDependencies, type FeatureFlags, type FlowAction, type FlowActionCallbacks, type FlowActionDependencies, Framework, type FrameworkConfig, History, HttpClient, type HttpClientConfig, HttpError, type InjectSSROptions, type Intent, type IntentController, IntentDispatcher, type Locale, type Logger, type LoggerFactory, type Logger as LoggerInterface, LruMap, type Mapper, type MetricsRecorder, type Net, type None, type Optional, type PrefetchedIntent, PrefetchedIntents, type RouteDefinition, type RouteMatch, Router, type RuntimeInfo, type SSRAppOptions, type SSRModule, type SSRRenderConfig, type SSRRenderOptions, type SSRRenderResult, type ServerConfig, type ServerInstance, type StartServerOptions, type Storage, buildUrl, createPrefetchedIntentsFromDom, createSSRApp, createSSRRender, createServer, defineRoutes, deserializeServerData, detectRuntime, generateUuid, getBaseUrl, injectSSRContent, isCompoundAction, isExternalUrlAction, isFlowAction, isNone, isSome, makeDependencies, makeExternalUrlAction, makeFlowAction, mapEach, parseAcceptLanguage, pipe, pipeAsync, registerActionHandlers, registerExternalUrlHandler, registerFlowActionHandler, removeHost, removeQueryParams, removeScheme, resetFilterCache, resolveRoot, serializeServerData, shouldLog, ssrRender, stableStringify, startBrowserApp, startServer, tryScroll };
+export { BasePage, Framework, FrameworkConfig, type InjectSSROptions, PrefetchedIntent, type RuntimeInfo, type SSRAppOptions, type SSRModule, type SSRRenderConfig, type SSRRenderOptions, type SSRRenderResult, SSR_PLACEHOLDERS, type ServerConfig, type ServerInstance, type StartServerOptions, createSSRApp, createSSRRender, createServer, detectRuntime, injectSSRContent, parseAcceptLanguage, resolveRoot, serializeServerData, ssrRender, startServer };