@route-forge/core 2.2.1 → 3.1.0

package/dist/index.d.ts

@@ -1,5 +1,497 @@
-import { a as RouteForgeOptions, b as RouteForge, I as InterceptorManager, c as InterceptorHandler, C as CacheStorage, R as RouteMeta, L as LevelRoutesResponse } from './types-CDKE8rw-.js';
-export { A as AdapterOption, d as ApiCallParams, B as BoundForge, F as Fetcher, e as ForgeApiParams, f as ForgeApiResponse, g as ForgeRequest, h as ForgeRouteMap, i as ForgeRouteName, j as LoadingChangeCallback, k as LoadingChangeEvent, l as LoadingTracker, m as RequestConfig, n as ResponseData, S as SummaryResponse, U as UseForgeApiBoundCall, o as UseForgeApiBoundReturn, p as UseForgeApiCall, q as UseForgeApiReturn } from './types-CDKE8rw-.js';
+import { R as RouteMeta, S as SummaryResponse, C as CacheStorage, L as LevelRoutesResponse } from './manifest-bjy4P_B4.js';
+
+/**
+ * 请求 / 响应 HTTP 层类型（拦截器、adapter、api 调用参数共用）
+ * @see .docs/SPEC.md §4.1.3a, §4.3
+ */
+
+/**
+ * 请求拦截器接收/返回的配置对象（可变，返回修改后的版本）
+ */
+interface RequestConfig {
+    route: string;
+    level: string;
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body?: unknown;
+    params: Record<string, unknown>;
+    meta: RouteMeta;
+    /** 请求超时毫秒数 */
+    timeout?: number;
+    /** 自定义 query 序列化函数 */
+    paramsSerializer?: (params: Record<string, unknown>) => string;
+    /** 请求取消信号（AbortSignal），用于取消已发出的请求 */
+    signal?: AbortSignal;
+}
+/**
+ * 响应拦截器首段接收的完整数据对象
+ */
+interface ResponseData {
+    route: string;
+    level: string;
+    method: string;
+    url: string;
+    status: number;
+    headers: Headers;
+    data: unknown;
+    config: RequestConfig;
+}
+/**
+ * forge.api() 返回的可取消请求对象。
+ * 继承 Promise，附加 abort() 方法用于取消请求。
+ * 内部自动创建 AbortController，用户无需手动管理。
+ */
+interface ForgeRequest<T = unknown> extends Promise<T> {
+    /** 取消请求。调用后请求将被中止，Promise reject 为 RequestAbortedError */
+    abort(): void;
+}
+/**
+ * forge.api(level, name, params) 调用参数
+ *
+ * 参数解析规则（智能消解）：
+ *   1. `params` — 显式指定路径参数，优先级最高
+ *   2. 平铺的 string | number 值 — 作为路径参数（含与 query/body/headers 同名的 key）
+ *   3. `query` (对象) — 查询参数，序列化到 URL query string
+ *   4. `body` (非 string/number) — 请求体
+ *   5. `headers` (对象) — 自定义请求头
+ *
+ * 当路径参数名与 query/body/headers 冲突时：
+ *   - 值为 string | number → 智能识别为路径参数
+ *   - 同时提供 params 显式指定 → params 优先，固定 key 按原定义处理
+ */
+interface ApiCallParams {
+    /** 路径参数：填充到 URI 模板的 {name} 占位符 */
+    [paramName: string]: unknown;
+    /** 显式指定路径参数（优先级最高，解决路径参数名与 query/body/headers 冲突的场景） */
+    params?: Record<string, unknown>;
+    /**
+     * 查询参数（对象 → query string）或路径参数（string | number → 填充 {query} 占位符）
+     * @see .docs/SPEC.md §4.1.3 参数智能解析
+     */
+    query?: Record<string, unknown> | string | number;
+    /**
+     * 请求体（非基元值 → body）或路径参数（string | number → 填充 {body} 占位符）
+     */
+    body?: unknown;
+    /**
+     * 自定义请求头（对象 → headers）或路径参数（string | number → 填充 {headers} 占位符）
+     */
+    headers?: Record<string, string> | string | number;
+    /**
+     * 单次请求超时覆盖（毫秒）；不传时使用 createRouteForge({ timeout }) 全局值
+     */
+    timeout?: number;
+    /**
+     * 外部取消信号（固定 key，恒不参与路径参数）。信号触发时请求被取消
+     * （reject 为 RequestAbortedError），与返回值自带的 `abort()` 联合生效——任一取消即中止。
+     * 若传入时 signal 已 abort，则直接短路、不发请求。适用于组件卸载 / React Query / AbortController 等外部生命周期。
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Adapter 选择值
+ */
+type AdapterOption = 'auto' | 'axios' | 'builtin' | Fetcher;
+/**
+ * Fetcher 接口（自定义 adapter）
+ * @see .docs/SPEC.md §4.3.3
+ */
+interface Fetcher {
+    request(config: RequestConfig): Promise<ResponseData>;
+    interceptors?: {
+        request?: InterceptorManager<RequestConfig, RequestConfig>;
+        response?: InterceptorManager<ResponseData, unknown>;
+    };
+}
+/**
+ * 拦截器管理器接口（与 axios use/eject/clear API 一致）
+ *
+ * 双类型参数说明（对应 SPEC §4.1.3a）：
+ *   - 请求拦截：TIn = TOut = RequestConfig（不可变换类型，仅修改字段）
+ *   - 响应拦截：TIn = ResponseData, TOut = unknown（首段接收 ResponseData，
+ *     后续段接收上一段返回值，返回类型由用户自行约束）
+ */
+interface InterceptorManager<TIn, TOut = TIn> {
+    use(onFulfilled?: (value: TIn) => TOut | Promise<TOut>, onRejected?: (error: unknown) => unknown | Promise<unknown>): number;
+    eject(id: number): void;
+    clear(): void;
+    /** 内部使用：当前已注册拦截器快照 */
+    forEach(fn: (handler: InterceptorHandler<TIn, TOut>) => void): void;
+}
+/**
+ * 单个拦截器内部结构
+ */
+interface InterceptorHandler<TIn, TOut = TIn> {
+    id: number;
+    onFulfilled?: (value: TIn) => TOut | Promise<TOut>;
+    onRejected?: (error: unknown) => unknown | Promise<unknown>;
+}
+
+/**
+ * 二级路由类型映射与推断条件类型
+ *
+ * 声明 `ForgeRouteMap`（codegen 生成或 module augmentation）后，
+ * api / route / hasRoute 的 name、params、响应类型按映射收敛；未声明时全部回退宽松类型。
+ */
+
+/**
+ * 二级路由类型映射（可由 codegen 生成或通过 module augmentation 增强）
+ *
+ * @example
+ * declare module '@route-forge/core' {
+ *   interface ForgeRouteMap {
+ *     admin: {
+ *       'users.show': { method: 'GET'; params: { user: string | number }; response: User };
+ *       'users.index': { method: 'GET'; params: {}; response: User[] };
+ *     };
+ *     public: {
+ *       'login.show': { method: 'GET'; params: {}; response: unknown };
+ *     };
+ *   }
+ * }
+ */
+interface ForgeRouteMap {
+}
+/** 从 ForgeRouteMap 推断指定层级下的路由名；未定义时回退 string */
+type ForgeRouteName<L extends string> = [
+    keyof ForgeRouteMap
+] extends [never] ? string : L extends keyof ForgeRouteMap ? keyof ForgeRouteMap[L] & string : string;
+/** 从 ForgeRouteMap 推断指定路由的 params 类型；未定义时回退 ApiCallParams */
+type ForgeApiParams<L extends string, N extends string> = [
+    keyof ForgeRouteMap
+] extends [never] ? ApiCallParams : L extends keyof ForgeRouteMap ? N extends keyof ForgeRouteMap[L] ? (ForgeRouteMap[L][N] extends {
+    params: infer P;
+} ? P & ApiCallParams : ApiCallParams) : ApiCallParams : ApiCallParams;
+/** 从 ForgeRouteMap 推断指定路由的响应类型；未定义时回退 unknown */
+type ForgeApiResponse<L extends string, N extends string> = [
+    keyof ForgeRouteMap
+] extends [never] ? unknown : L extends keyof ForgeRouteMap ? N extends keyof ForgeRouteMap[L] ? (ForgeRouteMap[L][N] extends {
+    response: infer R;
+} ? R : unknown) : unknown : unknown;
+
+/**
+ * LoadingTracker：加载中标识状态管理
+ *
+ * 通过引用计数器跟踪并发请求数。
+ * - start()：计数器 +1，进入加载状态
+ * - stop()：计数器 -1，归零时退出加载状态
+ * - isLoading()：查询当前是否处于加载中
+ * - subscribe(cb)：监听状态变化，返回取消订阅函数
+ *
+ * @see .docs/SPEC.md §4.1.8
+ */
+/** 状态变更回调签名 */
+type LoadingChangeCallback = (event: LoadingChangeEvent) => void;
+/** 状态变更事件 */
+interface LoadingChangeEvent {
+    /** 当前是否仍处于加载中 */
+    loading: boolean;
+    /** 当前并发请求数 */
+    count: number;
+}
+/**
+ * 加载状态跟踪器
+ *
+ * 单一计数器，跟踪所有 API 请求的并发数。
+ * 不绑定任何 UI 样式，仅提供状态供框架层或业务层消费。
+ */
+declare class LoadingTracker {
+    /** 当前并发请求计数 */
+    private count;
+    /** 订阅者集合 */
+    private subscribers;
+    /**
+     * 开始一次加载（计数器 +1）
+     */
+    start(): void;
+    /**
+     * 结束一次加载（计数器 -1）
+     */
+    stop(): void;
+    /**
+     * 查询当前是否处于加载中
+     */
+    isLoading(): boolean;
+    /**
+     * 获取当前并发计数
+     */
+    getCount(): number;
+    /**
+     * 订阅加载状态变更
+     * @returns 取消订阅函数
+     */
+    subscribe(cb: LoadingChangeCallback): () => void;
+    /** 通知所有订阅者 */
+    private notify;
+}
+
+/**
+ * RouteChangeTracker：路由表数据变更订阅（供框架层在缓存刷新后重算响应式 URL）
+ *
+ * 与 LoadingTracker（跟踪在途请求数）正交：本跟踪器表达的是「某层级的路由元信息内容已变化」
+ * ——发生在层级数据成功写入缓存（首次 load / revalidate）或失效（invalidate）之后。
+ *
+ * - notify(level)：广播某层级数据已变更（带 level，订阅者按自身绑定的 level 过滤，避免全量重渲染）
+ * - subscribe(cb)：订阅变更，返回取消订阅函数
+ *
+ * @see .docs/SPEC.md §4.1.8
+ */
+/** 路由表数据变更回调签名；level 为发生变化的层级 */
+type RouteChangeCallback = (level: string) => void;
+/**
+ * 路由数据变更广播器：微任务合批投递，避免同一 tick 内多次变更（invalidate-all、并发 load）
+ * 触发同步惊群，并把订阅者回调移出 cache.write 的关键路径。
+ */
+declare class RouteChangeTracker {
+    private readonly subscribers;
+    /** 本微任务周期内累积的变更层级（去重） */
+    private readonly pending;
+    /** 是否已排定一次微任务 flush */
+    private scheduled;
+    /** 订阅路由表数据变更；返回取消订阅函数 */
+    subscribe(cb: RouteChangeCallback): () => void;
+    /** 记录某层级数据已变更；同一 tick 多次调用合并为一次投递（每层级各投一次） */
+    notify(level: string): void;
+    /** 一次性投递本周期累积的所有变更层级；单订阅者抛错不影响其它 */
+    private flush;
+}
+
+/**
+ * forge 顶层 API 形状、配置项、BoundForge 与 useForgeApi 返回类型
+ * @see .docs/SPEC.md §4.1.6, §4.1.7, §5.2
+ */
+
+/**
+ * forge 顶层 API 形状
+ */
+interface RouteForge {
+    /**
+     * 通过层级 + 路由名调用 API；level 用于确定加载哪个层级的路由元信息。
+     * 声明 `ForgeRouteMap`（codegen 生成或 module augmentation）后，name / params / 响应类型
+     * 按映射收敛；未声明映射时完全等价于 `(level: string, name: string, params?: ApiCallParams) => ForgeRequest<unknown>`。
+     */
+    api<L extends string, N extends ForgeRouteName<L>>(level: L, name: N, params?: ForgeApiParams<L, N>): ForgeRequest<ForgeApiResponse<L, N>>;
+    /** 拉取一个或多个层级（自动并发去重） */
+    load(level: string | string[]): Promise<void>;
+    /**
+     * 强制刷新一个或多个层级：跳过缓存命中短路重新拉取，成功覆盖缓存、失败保留旧值。
+     * 与 `invalidate` + `load` 不同——全程不清空缓存，读取旧数据不受影响、无空窗。
+     * 刷新成功会经 `onRoutesChange` 广播该层级变更；失败时 Promise reject 携带拉取错误。
+     */
+    revalidate(level: string | string[]): Promise<void>;
+    /**
+     * 仅生成 URL，不发请求；level 用于定位路由所在的层级缓存。
+     * 声明 `ForgeRouteMap` 后 name 按映射收敛（params 保持宽松——路径参数与后端默认值均可）。
+     */
+    route<L extends string, N extends ForgeRouteName<L>>(level: L, name: N, params?: Record<string, unknown>): string;
+    /** route() 的语义别名，适用于链接生成等场景 */
+    url<L extends string, N extends ForgeRouteName<L>>(level: L, name: N, params?: Record<string, unknown>): string;
+    /**
+     * 失效缓存：
+     * - invalidate()：失效全部层级
+     * - invalidate('admin')：失效指定层级
+     * - invalidate(['admin', 'manage'])：批量失效指定层级
+     */
+    invalidate(level?: string | string[]): void;
+    /** 检查指定层级路由是否已加载并缓存；不传参检查全部 */
+    isLoaded(level?: string): boolean;
+    /** 检查指定层级下某路由是否存在（需该层级缓存已加载）；声明 `ForgeRouteMap` 后 name 按映射收敛 */
+    hasRoute<L extends string, N extends ForgeRouteName<L>>(level: L, name: N): boolean;
+    /** 查询加载中标识状态 */
+    isLoading(): boolean;
+    /**
+     * ready() 是否已成功 resolve（同步查询，不触发任何加载）。
+     * discovery + eager 完成为 true；reject 不算就绪（保持 false）。
+     * 供框架层 ready 门闩（react Provider `gate` / vue `ForgeReady`）避免多余的 fallback 首帧。
+     */
+    isReady(): boolean;
+    /** 非致命警告是否启用（来自 createRouteForge({ warnings })，默认 true）；vue/react 适配层共用此开关 */
+    readonly warnings: boolean;
+    /** 订阅加载状态变更，返回取消订阅函数 */
+    onLoadingChange(cb: LoadingChangeCallback): () => void;
+    /**
+     * 订阅路由表数据变更：层级数据成功写入（load / revalidate）或失效（invalidate）后，
+     * 回调携带发生变化的层级。框架层据此重算受影响的响应式 URL（后台刷新无需刷新页面即热更新）。
+     * @returns 取消订阅函数
+     */
+    onRoutesChange(cb: RouteChangeCallback): () => void;
+    /**
+     * 获取路由元信息快照（深拷贝，修改返回值不影响内部缓存）。
+     * - getRoutes(level)：返回指定层级下全部路由；层级未声明抛 `UnknownLevelError`，
+     *   已声明但未加载返回 `{}`
+     * - getRoutes()：返回全部层级的路由（按 level 分组）
+     */
+    getRoutes(level: string): Record<string, RouteMeta>;
+    getRoutes(): Record<string, Record<string, RouteMeta>>;
+    /**
+     * 当前已知的已声明层级列表（含后端恒注入的 `unassigned`）。
+     * 内嵌 / `summary` 引导：构造后即可用；网络引导：`ready()` 前可能为空数组、之后为全量。
+     * 只读发现 API，不触发加载、未就绪不抛错（返回 `[]`）。
+     */
+    getLevels(): string[];
+    /** 拦截器入口（请求 / 响应） */
+    interceptors: {
+        request: InterceptorManager<RequestConfig, RequestConfig>;
+        response: InterceptorManager<ResponseData, unknown>;
+    };
+    /**
+     * auto-discovery + eager load 完成后 resolve。
+     * 始终返回 Promise<this>，resolve 值为 forge 实例自身，支持链式调用。
+     *
+     * - 无参：返回 Promise，适合 async/await
+     * - 有参：回调内部走 then/catch，仍返回 Promise
+     */
+    ready(): Promise<RouteForge>;
+    ready(onFulfilled: (forge: RouteForge) => void, onRejected?: (error: unknown) => void): Promise<RouteForge>;
+    /**
+     * 绑定 level（+ 可选 prefix），返回 BoundForge。
+     * 唯一入口 — Vue/React/IIFE 共享同一套 API 表面。
+     *
+     * - use()：不绑定，返回 RouteForge 自身
+     * - use(level)：绑定 level
+     * - use(level, prefix)：绑定 level + prefix
+     */
+    use(): RouteForge;
+    use<L extends string>(level: L, prefix?: string): BoundForge;
+}
+/**
+ * createRouteForge 配置项
+ * @see .docs/SPEC.md §5.2
+ */
+interface RouteForgeOptions {
+    /**
+     * 摘要端点 URL（网络拉取来源）。
+     * 摘要数据源级联（SPEC §4.1.1）：Blade 注入的 `window.__ROUTE_FORGE__` > 本 `summary` 字段 > 网络拉取 `endpoint`。
+     * 命中前两者时可省略；层级明细端点取自摘要 `levels[].route.uri`，不依赖本字段。
+     * 三者皆无（既无注入/summary、又无 endpoint）时网络引导回退默认摘要端点 `/_forge/routes`（DEFAULT_ENDPOINT）。
+     */
+    endpoint?: string;
+    /**
+     * 直接提供摘要数据（SummaryResponse），跳过摘要 HTTP 往返——用于测试或非 Blade 的注入式引导。
+     * 优先级低于页面内嵌的 `window.__ROUTE_FORGE__`（存在时以后端真值为准）。
+     * @see .docs/SPEC.md §4.1.1 / §3.1.8
+     */
+    summary?: SummaryResponse;
+    /**
+     * 层级列表。未传时从摘要自动发现（SPEC §4.1.1）。
+     * 显式传入时取与摘要响应 levels 键的交集（前端不能声明后端不存在的层级，SPEC §5.3）。
+     */
+    levels?: string[];
+    eager?: string[];
+    adapter?: AdapterOption;
+    cache?: {
+        ttl?: number;
+        storage?: CacheStorage;
+    };
+    interceptors?: {
+        /**
+         * 声明式请求拦截器，只描述**一个**拦截器，支持三种写法（SPEC §4.1.1）：
+         * - 函数 `resolve` → 视为 onFulfilled
+         * - 元组 `[resolve?, reject?]` → 成功 / 失败（允许缺位，如 `[resolve]`、`[undefined, reject]`）
+         * - 对象 `{ resolve?, reject? }` → 具名成功 / 失败
+         * 需要注册多个拦截器请改用运行时 `forge.interceptors.request.use()`（可多次调用）。
+         */
+        request?: ((c: RequestConfig) => RequestConfig | Promise<RequestConfig>) | [
+            ((c: RequestConfig) => RequestConfig | Promise<RequestConfig>)?,
+            ((e: unknown) => unknown | Promise<unknown>)?
+        ] | {
+            resolve?: (c: RequestConfig) => RequestConfig | Promise<RequestConfig>;
+            reject?: (e: unknown) => unknown | Promise<unknown>;
+        };
+        /**
+         * 声明式响应拦截器，形状同 `request`（首段 onFulfilled 接收 ResponseData）。
+         * 同样只描述一个拦截器，多拦截器改用运行时 `forge.interceptors.response.use()`。
+         */
+        response?: ((r: ResponseData) => unknown | Promise<unknown>) | [((r: ResponseData) => unknown | Promise<unknown>)?, ((e: unknown) => unknown | Promise<unknown>)?] | {
+            resolve?: (r: ResponseData) => unknown | Promise<unknown>;
+            reject?: (e: unknown) => unknown | Promise<unknown>;
+        };
+    };
+    /**
+     * @deprecated 前端校验始终开启，此选项不再被消费。
+     * 前端在层级未声明时始终抛 `UnknownLevelError`、路由名不存在始终抛 `UnknownRouteError`、
+     * 必填路径参数缺失始终抛 `MissingRouteParamError` —— 校验行为与 strict 无关，静默忽略会掩盖拼写错误、难以排查。
+     * 后端 `strict_mode` 的宽松/严格语义（未命中层级路由是否归入 unassigned/fallback）由后端在生成 manifest 时决定。
+     * 字段保留仅为向后兼容，传入不会有任何效果。
+     */
+    strict?: boolean;
+    timeout?: number;
+    baseURL?: string;
+    /**
+     * 非致命警告开关（默认 true）：控制 core 内部的 `console.warn`（如显式 levels 降级、
+     * endpoint_prefix 覆盖、schemeVersion 兼容提示等）。`false` 时静音这些 warn——
+     * `console.error` 级输出（如 eager 层级加载失败）不受影响，错误永远响亮。
+     * 该值以只读字段 `RouteForge.warnings` 暴露，vue/react 适配层的渲染期降级警告同样遵循它。
+     */
+    warnings?: boolean;
+}
+/**
+ * 已绑定 level 的 forge 对象。
+ * 由 `forge.use(level, prefix?)` 返回，Vue/React/IIFE 共享同一 API 表面。
+ *
+ * @typeParam LL - levelLoaded 的类型：core 默认 Promise<void>，Vue 替换为 Ref<boolean>
+ */
+interface BoundForge<LL = Promise<void>> {
+    /** 直接调用 = api 快捷方式，自动带绑定的 level */
+    (name: string, params?: ApiCallParams): ForgeRequest;
+    /** 当前绑定的 level */
+    readonly level: string;
+    /** 绑定的路由名前缀（仅传入 prefix 时存在） */
+    readonly prefix?: string;
+    /** level 加载状态（core: Promise<void>，Vue: Ref<boolean>） */
+    levelLoaded: LL;
+    api(name: string, params?: ApiCallParams): ForgeRequest;
+    route(name: string, params?: Record<string, unknown>): string;
+    url(name: string, params?: Record<string, unknown>): string;
+    hasRoute(name: string): boolean;
+    getRoutes(): Record<string, RouteMeta>;
+    load(): Promise<void>;
+    invalidate(): void;
+    isLoaded(): boolean;
+    isLoading(): boolean;
+    onLoadingChange(cb: LoadingChangeCallback): () => void;
+    /** 等待绑定的 level 加载完成，resolve 值为自身（BoundForge），保证可安全调用 */
+    onLevelLoaded(): Promise<BoundForge<LL>>;
+    onLevelLoaded(onFulfilled: (bound: BoundForge<LL>) => void, onRejected?: (error: unknown) => void): Promise<BoundForge<LL>>;
+    /** 在已绑定 level 基础上追加/替换 prefix，返回新的 BoundForge */
+    useRoutePrefix(prefix: string): BoundForge<LL>;
+}
+/** call 函数签名 — 未绑定 level，需要显式传入 */
+interface UseForgeApiCall {
+    (level: string, name: string, params?: ApiCallParams): Promise<{
+        data: unknown;
+        error: unknown;
+    }>;
+}
+/** call 函数签名 — 已绑定 level，无需再传 */
+interface UseForgeApiBoundCall<L extends string> {
+    (name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): Promise<{
+        data: ForgeApiResponse<L, ForgeRouteName<L>>;
+        error: unknown;
+    }>;
+}
+/**
+ * useForgeApi 返回类型 — 未绑定 level
+ * @typeParam PendingType - 框架层 pending 状态类型（Vue: Ref<boolean>, React: boolean）
+ * @typeParam ErrorType - 框架层 error 状态类型（Vue: Ref<unknown>, React: unknown）
+ */
+interface UseForgeApiReturn<PendingType = unknown, ErrorType = unknown> {
+    pending: PendingType;
+    error: ErrorType;
+    call: UseForgeApiCall;
+}
+/**
+ * useForgeApi 返回类型 — 已绑定 level
+ * @typeParam L - 层级名
+ * @typeParam PendingType - 框架层 pending 状态类型
+ * @typeParam ErrorType - 框架层 error 状态类型
+ */
+interface UseForgeApiBoundReturn<L extends string, PendingType = unknown, ErrorType = unknown> {
+    pending: PendingType;
+    error: ErrorType;
+    call: UseForgeApiBoundCall<L>;
+}
 
 /**
  * Route Forge 主入口：createRouteForge
@@ -16,23 +508,10 @@ export { A as AdapterOption, d as ApiCallParams, B as BoundForge, F as Fetcher,
 declare function createRouteForge(options?: RouteForgeOptions): RouteForge;
 
 /**
- * 拦截器管理器实现
- * @see .docs/SPEC.md §4.1.3a, §4.1.1
- *
- * 执行顺序约定（对齐 axios）：
- *   - 请求拦截器：LIFO（后注册先执行），onRejected 与 onFulfilled 同序
- *   - 响应拦截器：FIFO（先注册先执行），onRejected 与 onFulfilled 同序
- *
- * 实现策略：
- *   - InterceptorManagerImpl.forEach 保持正序迭代（与 use/eject 语义一致）
- *   - runRequestInterceptors 收集 handlers 后 reverse() 再串联 Promise 链，实现 LIFO
- *   - runResponseInterceptors 直接正序串联，实现 FIFO
+ * 拦截器管理器实现：use/eject/clear/forEach 的注册与快照存储（不含执行编排）。
+ * @see .docs/SPEC.md §4.1.3a
  *
- * 串联实现：采用标准 Promise 链语义
- *   `Promise.resolve(initial).then(f0, r0).then(f1, r1).then(f2, r2)...`
- *   - onFulfilled 抛错 → 下一组 onRejected 接住
- *   - onRejected 返回值 → 后续 onFulfilled 继续执行（恢复为正常流程）
- *   - onRejected 抛错 → 下一组 onRejected 接住 / 进入调用方 catch
+ * 执行顺序编排见 interceptors/runner.ts；创建时声明式入参归一见 interceptors/normalize.ts。
  */
 
 declare class InterceptorManagerImpl<TIn, TOut = TIn> implements InterceptorManager<TIn, TOut> {
@@ -118,6 +597,8 @@ declare class RouteCache {
 interface RouteResolver {
     load(level: string | string[]): Promise<void>;
     hasRoute(level: string, name: string): boolean;
+    /** 可选：该层级当前已加载的路由名列表（UnknownRouteError 附候选值用） */
+    getRouteNames?(level: string): string[];
 }
 /**
  * 异步版本：先确保层级已加载，再做歧义消解。
@@ -134,6 +615,7 @@ declare function resolveRouteNameSync(forge: RouteResolver, level: string, prefi
  * Route Forge 错误基类与具体错误类
  * @see .docs/SPEC.md §6
  */
+
 interface ForgeErrorContext {
     [key: string]: unknown;
 }
@@ -158,15 +640,19 @@ declare class ForgeError extends Error {
 }
 /** RF_FE_001：路由名不存在于已加载层级中 */
 declare class UnknownRouteError extends ForgeError {
-    constructor(route: string, level?: string);
+    constructor(route: string, level?: string, candidates?: string[]);
 }
 /** RF_FE_002：路由所在层级未在 levels 声明 */
 declare class UnknownLevelError extends ForgeError {
-    constructor(level: string);
+    constructor(level: string, candidates?: string[]);
 }
-/** RF_FE_003：路径参数缺失（strict=true 时） */
+/** RF_FE_003：必填路径参数缺失（无后端 default 时，前端校验恒开） */
 declare class MissingRouteParamError extends ForgeError {
-    constructor(route: string, missingParams: string[]);
+    constructor(route: string, missingParams: string[], uri?: string);
+}
+/** RF_FE_003：路径参数收到非原始值（对象/数组等，无法安全插入 URI） */
+declare class InvalidPathParamError extends ForgeError {
+    constructor(route: string, param: string, value: unknown);
 }
 /** RF_FE_005：adapter: 'axios' 但未检测到 axios */
 declare class AdapterNotFoundError extends ForgeError {
@@ -180,8 +666,15 @@ declare class InvalidInterceptorReturnError extends ForgeError {
 declare class NetworkError extends ForgeError {
     constructor(message: string, route?: string, level?: string, cause?: unknown);
 }
-/** RF_FE_008：HTTP 非 2xx 且未被 onRejected 拦截器恢复 */
+/**
+ * RF_FE_008：HTTP 非 2xx 且未被 onRejected 拦截器恢复。
+ *
+ * `response` 携带完整的 ResponseData（status/headers/data/config），
+ * 供响应拦截器 onRejected 链与最终 catch 逐段检查响应体——典型场景：
+ * Laravel 422 校验错误回显（`err.response.data.errors`）。
+ */
 declare class HTTPError extends ForgeError {
+    readonly response?: ResponseData;
     constructor(message: string, opts: {
         route?: string;
         level?: string;
@@ -189,11 +682,16 @@ declare class HTTPError extends ForgeError {
         url?: string;
         method?: string;
         cause?: unknown;
+        response?: ResponseData;
     });
 }
 /** RF_FE_009：请求被 AbortSignal 取消 */
 declare class RequestAbortedError extends ForgeError {
     constructor(route?: string, level?: string, cause?: unknown);
 }
+/** RF_FE_010：auto-discovery 未完成时调用 route()/hasRoute() 的同步守卫（api() 内部 await discovery，不受此限） */
+declare class DiscoveryNotReadyError extends ForgeError {
+    constructor();
+}
 
-export { AdapterNotFoundError, CacheStorage, ForgeError, type ForgeErrorCode, HTTPError, InterceptorHandler, InterceptorManager, InterceptorManagerImpl, InvalidInterceptorReturnError, LevelRoutesResponse, MissingRouteParamError, NetworkError, RequestAbortedError, RouteCache, RouteForge, RouteForgeOptions, RouteMeta, type RouteResolver, UnknownLevelError, UnknownRouteError, createInterceptorManager, createRouteForge, resolveRouteName, resolveRouteNameSync };
+export { AdapterNotFoundError, type AdapterOption, type ApiCallParams, type BoundForge, CacheStorage, DiscoveryNotReadyError, type Fetcher, type ForgeApiParams, type ForgeApiResponse, ForgeError, type ForgeErrorCode, type ForgeRequest, type ForgeRouteMap, type ForgeRouteName, HTTPError, type InterceptorHandler, type InterceptorManager, InterceptorManagerImpl, InvalidInterceptorReturnError, InvalidPathParamError, LevelRoutesResponse, type LoadingChangeCallback, type LoadingChangeEvent, LoadingTracker, MissingRouteParamError, NetworkError, RequestAbortedError, type RequestConfig, type ResponseData, RouteCache, type RouteChangeCallback, RouteChangeTracker, type RouteForge, type RouteForgeOptions, RouteMeta, type RouteResolver, SummaryResponse, UnknownLevelError, UnknownRouteError, type UseForgeApiBoundCall, type UseForgeApiBoundReturn, type UseForgeApiCall, type UseForgeApiReturn, createInterceptorManager, createRouteForge, resolveRouteName, resolveRouteNameSync };