@route-forge/core 2.2.1 → 3.1.0

package/dist/route-forge.global.js

@@ -132,6 +132,36 @@ var RouteForge = (function (exports) {
     }
   };
 
+  // src/interceptors/manager.ts
+  var InterceptorManagerImpl = class {
+    constructor() {
+      this.handlers = [];
+      this.nextId = 0;
+    }
+    use(onFulfilled, onRejected) {
+      const id = this.nextId++;
+      this.handlers.push({ id, onFulfilled, onRejected });
+      return id;
+    }
+    eject(id) {
+      const idx = this.handlers.findIndex((h) => h.id === id);
+      if (idx >= 0) this.handlers.splice(idx, 1);
+    }
+    clear() {
+      this.handlers = [];
+    }
+    forEach(fn) {
+      for (const h of this.handlers) fn(h);
+    }
+    /** 测试用：当前注册数量 */
+    get size() {
+      return this.handlers.length;
+    }
+  };
+  function createInterceptorManager() {
+    return new InterceptorManagerImpl();
+  }
+
   // src/errors.ts
   var ForgeError = class extends Error {
     constructor(message, opts) {
@@ -144,30 +174,56 @@ var RouteForge = (function (exports) {
       if (opts.cause !== void 0) this.cause = opts.cause;
     }
   };
+  function formatCandidates(candidates) {
+    if (!candidates || candidates.length === 0) return "";
+    const MAX = 5;
+    const shown = candidates.slice(0, MAX).join(", ");
+    const more = candidates.length > MAX ? ` (+${candidates.length - MAX} more)` : "";
+    return ` Available: ${shown}${more}`;
+  }
   var UnknownRouteError = class extends ForgeError {
-    constructor(route, level) {
-      super(`Route "${route}" not found${level ? ` in level "${level}"` : ""}`, {
-        code: "RF_FE_001",
-        route,
-        level
-      });
+    constructor(route, level, candidates) {
+      super(
+        `Route "${route}" not found${level ? ` in level "${level}"` : ""}.${formatCandidates(candidates)}`,
+        {
+          code: "RF_FE_001",
+          route,
+          level,
+          context: candidates && candidates.length > 0 ? { candidates } : void 0
+        }
+      );
     }
   };
   var UnknownLevelError = class extends ForgeError {
-    constructor(level) {
-      super(`Level "${level}" not declared in options.levels`, {
-        code: "RF_FE_002",
-        level
-      });
+    constructor(level, candidates) {
+      super(
+        `Level "${level}" not declared in options.levels.${formatCandidates(candidates)}`,
+        {
+          code: "RF_FE_002",
+          level,
+          context: candidates && candidates.length > 0 ? { candidates } : void 0
+        }
+      );
     }
   };
   var MissingRouteParamError = class extends ForgeError {
-    constructor(route, missingParams) {
-      super(`Missing path parameter(s) ${missingParams.join(", ")} for route "${route}"`, {
-        code: "RF_FE_003",
-        route,
-        context: { missingParams }
-      });
+    constructor(route, missingParams, uri) {
+      super(
+        `Missing path parameter(s) ${missingParams.join(", ")} for route "${route}"${uri ? ` (${uri})` : ""}`,
+        {
+          code: "RF_FE_003",
+          route,
+          context: { missingParams, ...uri !== void 0 ? { uri } : {} }
+        }
+      );
+    }
+  };
+  var InvalidPathParamError = class extends ForgeError {
+    constructor(route, param, value) {
+      super(
+        `Path parameter "${param}" must be a primitive value (string, number, boolean), got ${typeof value}`,
+        { code: "RF_FE_003", route, context: { param, value } }
+      );
     }
   };
   var AdapterNotFoundError = class extends ForgeError {
@@ -200,6 +256,7 @@ var RouteForge = (function (exports) {
         context: { status: opts.status, url: opts.url, method: opts.method },
         cause: opts.cause
       });
+      if (opts.response !== void 0) this.response = opts.response;
     }
   };
   var RequestAbortedError = class extends ForgeError {
@@ -212,33 +269,16 @@ var RouteForge = (function (exports) {
       });
     }
   };
-
-  // src/interceptors.ts
-  var InterceptorManagerImpl = class {
+  var DiscoveryNotReadyError = class extends ForgeError {
     constructor() {
-      this.handlers = [];
-      this.nextId = 0;
-    }
-    use(onFulfilled, onRejected) {
-      const id = this.nextId++;
-      this.handlers.push({ id, onFulfilled, onRejected });
-      return id;
-    }
-    eject(id) {
-      const idx = this.handlers.findIndex((h) => h.id === id);
-      if (idx >= 0) this.handlers.splice(idx, 1);
-    }
-    clear() {
-      this.handlers = [];
-    }
-    forEach(fn) {
-      for (const h of this.handlers) fn(h);
-    }
-    /** 测试用：当前注册数量 */
-    get size() {
-      return this.handlers.length;
+      super(
+        "Route data not available. Auto-discovery has not completed. Use forge.ready() or forge.use(level) first, or await ready() before calling route()/hasRoute().",
+        { code: "RF_FE_010" }
+      );
     }
   };
+
+  // src/interceptors/runner.ts
   async function runRequestInterceptors(manager, initial) {
     const handlers = [];
     manager.forEach((h) => handlers.push(h));
@@ -275,8 +315,44 @@ var RouteForge = (function (exports) {
     }
     return p;
   }
-  function createInterceptorManager() {
-    return new InterceptorManagerImpl();
+
+  // src/interceptors/normalize.ts
+  function normalizeInterceptorDeclaration(value) {
+    if (value === null || value === void 0) return {};
+    let rawResolve;
+    let rawReject;
+    if (typeof value === "function") {
+      rawResolve = value;
+    } else if (Array.isArray(value)) {
+      rawResolve = value[0];
+      rawReject = value[1];
+    } else if (typeof value === "object") {
+      const obj = value;
+      rawResolve = obj.resolve;
+      rawReject = obj.reject;
+    } else {
+      throw new TypeError(
+        `Interceptor declaration must be a function, a [resolve, reject] tuple, or a { resolve, reject } object; received ${typeof value}.`
+      );
+    }
+    const handler = {};
+    if (rawResolve !== void 0 && rawResolve !== null) {
+      if (typeof rawResolve !== "function") {
+        throw new TypeError(
+          `Interceptor "resolve" (onFulfilled) must be a function; received ${typeof rawResolve}.`
+        );
+      }
+      handler.onFulfilled = rawResolve;
+    }
+    if (rawReject !== void 0 && rawReject !== null) {
+      if (typeof rawReject !== "function") {
+        throw new TypeError(
+          `Interceptor "reject" (onRejected) must be a function; received ${typeof rawReject}.`
+        );
+      }
+      handler.onRejected = rawReject;
+    }
+    return handler;
   }
 
   // src/adapters/fetch-core.ts
@@ -378,7 +454,10 @@ var RouteForge = (function (exports) {
         level: config.level,
         status: res.status,
         url,
-        method: config.method
+        method: config.method,
+        // 完整 ResponseData 随错误逐段传递（响应拦截器 onRejected 链 → 最终 catch），
+        // 供调用方检查响应体，如 Laravel 422 校验错误 err.response.data.errors
+        response: responseData
       }
     );
   }
@@ -507,6 +586,69 @@ var RouteForge = (function (exports) {
     return createBuiltinHttp(opts.forgeInterceptors);
   }
 
+  // src/adapter-bootstrap.ts
+  function createAdapterBootstrap(deps) {
+    const { adapter, requestInterceptors, responseInterceptors, warnings } = deps;
+    const adapterPromise = resolveAdapter({
+      adapter,
+      forgeInterceptors: { request: requestInterceptors, response: responseInterceptors }
+    });
+    let adapterResolved = false;
+    let adapterObj = null;
+    return async function ensureAdapter() {
+      if (!adapterResolved) {
+        adapterObj = await adapterPromise.catch((e) => {
+          if (e instanceof AdapterNotFoundError) throw e;
+          if (warnings) {
+            console.warn(
+              `[route-forge] adapter initialization failed (${e?.message ?? String(e)}); falling back to builtin`
+            );
+          }
+          return resolveAdapter({
+            adapter: "builtin",
+            forgeInterceptors: { request: requestInterceptors, response: responseInterceptors }
+          });
+        });
+        adapterResolved = true;
+      }
+      return adapterObj;
+    };
+  }
+
+  // src/ready-latch.ts
+  function createReadyLatch() {
+    let resolveReady;
+    let rejectReady;
+    const readyPromise = new Promise((resolve, reject) => {
+      resolveReady = resolve;
+      rejectReady = reject;
+    });
+    let settledValue;
+    readyPromise.catch(() => {
+    });
+    let readySettledOk = false;
+    readyPromise.then(
+      (value) => {
+        settledValue = value;
+        readySettledOk = true;
+      },
+      () => {
+      }
+    );
+    function ready(onFulfilled, onRejected) {
+      if (onFulfilled) {
+        return readyPromise.then(onFulfilled, onRejected).then(() => settledValue);
+      }
+      return readyPromise;
+    }
+    return {
+      resolve: (value) => resolveReady(value),
+      reject: (reason) => rejectReady(reason),
+      isReady: () => readySettledOk,
+      ready
+    };
+  }
+
   // src/loading.ts
   var LoadingTracker = class {
     constructor() {
@@ -566,12 +708,107 @@ var RouteForge = (function (exports) {
     }
   };
 
-  // src/url-builder.ts
+  // src/route-change.ts
+  var RouteChangeTracker = class {
+    constructor() {
+      this.subscribers = /* @__PURE__ */ new Set();
+      /** 本微任务周期内累积的变更层级（去重） */
+      this.pending = /* @__PURE__ */ new Set();
+      /** 是否已排定一次微任务 flush */
+      this.scheduled = false;
+    }
+    /** 订阅路由表数据变更；返回取消订阅函数 */
+    subscribe(cb) {
+      this.subscribers.add(cb);
+      return () => {
+        this.subscribers.delete(cb);
+      };
+    }
+    /** 记录某层级数据已变更；同一 tick 多次调用合并为一次投递（每层级各投一次） */
+    notify(level) {
+      if (this.subscribers.size === 0) return;
+      this.pending.add(level);
+      if (this.scheduled) return;
+      this.scheduled = true;
+      queueMicrotask(() => this.flush());
+    }
+    /** 一次性投递本周期累积的所有变更层级；单订阅者抛错不影响其它 */
+    flush() {
+      this.scheduled = false;
+      const levels = [...this.pending];
+      this.pending.clear();
+      for (const level of levels) {
+        for (const cb of this.subscribers) {
+          try {
+            cb(level);
+          } catch {
+          }
+        }
+      }
+    }
+  };
+
+  // src/url/utils.ts
+  function trimTrailingSlash(s) {
+    return s.endsWith("/") ? s.slice(0, -1) : s;
+  }
+  function withLeadingSlash(s) {
+    return s.startsWith("/") ? s : `/${s}`;
+  }
+  function joinBaseAndPath(base, path) {
+    return `${trimTrailingSlash(base)}${withLeadingSlash(path)}`;
+  }
+
+  // src/url/endpoint.ts
   function buildUrl(level, ctx) {
-    const base = ctx.baseURL.endsWith("/") ? ctx.baseURL.slice(0, -1) : ctx.baseURL;
-    const ep = ctx.endpoint.startsWith("/") ? ctx.endpoint : `/${ctx.endpoint}`;
-    return `${base}${ep}/${encodeURIComponent(level)}`;
+    return `${joinBaseAndPath(ctx.baseURL, withLeadingSlash(ctx.endpoint))}/${encodeURIComponent(level)}`;
   }
+
+  // src/url/params.ts
+  function resolveApiParams(input) {
+    const {
+      params: explicitParams,
+      query: rawQuery,
+      body: rawBody,
+      headers: rawHeaders,
+      timeout: perCallTimeout,
+      signal: rawSignal,
+      ...flatRest
+    } = input;
+    const pathParams = explicitParams ? { ...explicitParams } : {};
+    for (const [k, v] of Object.entries(flatRest)) {
+      if (!(k in pathParams)) {
+        pathParams[k] = v;
+      }
+    }
+    let query;
+    let body;
+    let headers;
+    if (rawQuery !== void 0) {
+      if (typeof rawQuery === "object" && rawQuery !== null) {
+        query = rawQuery;
+      } else if (!("query" in pathParams)) {
+        pathParams.query = rawQuery;
+      }
+    }
+    if (rawBody !== void 0) {
+      if (typeof rawBody !== "string" && typeof rawBody !== "number") {
+        body = rawBody;
+      } else if (!("body" in pathParams)) {
+        pathParams.body = rawBody;
+      }
+    }
+    if (rawHeaders !== void 0) {
+      if (typeof rawHeaders === "object" && rawHeaders !== null) {
+        headers = rawHeaders;
+      } else if (!("headers" in pathParams)) {
+        pathParams.headers = rawHeaders;
+      }
+    }
+    return { pathParams, query, body, headers, timeout: perCallTimeout, signal: rawSignal };
+  }
+
+  // src/url/request.ts
   function buildRequestUrl(meta, params, ctx) {
     const defaults = meta.parameter_defaults ?? {};
     const missingRequired = [];
@@ -590,7 +827,7 @@ var RouteForge = (function (exports) {
       }
     }
     if (missingRequired.length > 0) {
-      throw new MissingRouteParamError(meta.name, missingRequired);
+      throw new MissingRouteParamError(meta.name, missingRequired, meta.uri);
     }
     let uri = meta.uri.replace(/\{([^{}]+)\}/g, (match, raw) => {
       const optional = raw.endsWith("?");
@@ -598,10 +835,7 @@ var RouteForge = (function (exports) {
       if (values[name] !== void 0) {
         const val = values[name];
         if (typeof val === "object") {
-          throw new ForgeError(
-            `Path parameter "${name}" must be a primitive value (string, number, boolean), got ${typeof val}`,
-            { code: "RF_FE_003", route: meta.name, context: { param: name, value: val } }
-          );
+          throw new InvalidPathParamError(meta.name, name, val);
         }
         return encodeURIComponent(String(val));
       }
@@ -609,10 +843,10 @@ var RouteForge = (function (exports) {
     });
     uri = uri.replace(/\/+/g, "/").replace(/\/$/, "");
     if (/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(ctx.urlPrefix)) {
-      const prefix2 = ctx.urlPrefix.endsWith("/") ? ctx.urlPrefix.slice(0, -1) : ctx.urlPrefix;
+      const prefix2 = trimTrailingSlash(ctx.urlPrefix);
       return uri.startsWith("/") ? `${prefix2}${uri}` : `${prefix2}/${uri}`;
     }
-    const base = ctx.baseURL.endsWith("/") ? ctx.baseURL.slice(0, -1) : ctx.baseURL;
+    const base = trimTrailingSlash(ctx.baseURL);
     const prefix = ctx.urlPrefix;
     return uri.startsWith("/") ? `${base}${prefix}${uri}` : `${base}${prefix}/${uri}`;
   }
@@ -631,67 +865,44 @@ var RouteForge = (function (exports) {
     if (!qs) return url;
     return url.includes("?") ? `${url}&${qs}` : `${url}?${qs}`;
   }
-  function resolveApiParams(input) {
-    const {
-      params: explicitParams,
-      query: rawQuery,
-      body: rawBody,
-      headers: rawHeaders,
-      timeout: perCallTimeout,
-      ...flatRest
-    } = input;
-    const pathParams = explicitParams ? { ...explicitParams } : {};
-    for (const [k, v] of Object.entries(flatRest)) {
-      if (!(k in pathParams)) {
-        pathParams[k] = v;
-      }
-    }
-    let query;
-    let body;
-    let headers;
-    if (rawQuery !== void 0) {
-      if (typeof rawQuery === "object" && rawQuery !== null) {
-        query = rawQuery;
-      } else if (!("query" in pathParams)) {
-        pathParams.query = rawQuery;
-      }
-    }
-    if (rawBody !== void 0) {
-      if (typeof rawBody !== "string" && typeof rawBody !== "number") {
-        body = rawBody;
-      } else if (!("body" in pathParams)) {
-        pathParams.body = rawBody;
-      }
-    }
-    if (rawHeaders !== void 0) {
-      if (typeof rawHeaders === "object" && rawHeaders !== null) {
-        headers = rawHeaders;
-      } else if (!("headers" in pathParams)) {
-        pathParams.headers = rawHeaders;
+  var RESERVED_API_KEYS = ["params", "query", "body", "headers", "timeout", "signal"];
+  function buildRouteUrl(meta, params, ctx) {
+    if (params) {
+      const hasReservedKey = RESERVED_API_KEYS.some((k) => k in params);
+      if (!hasReservedKey) {
+        return buildRequestUrl(meta, params, ctx);
       }
+    } else {
+      return buildRequestUrl(meta, {}, ctx);
     }
-    return { pathParams, query, body, headers, timeout: perCallTimeout };
+    const { pathParams, query } = resolveApiParams(params);
+    return appendQuery(buildRequestUrl(meta, pathParams, ctx), query);
   }
 
   // src/auto-discovery.ts
+  var DEFAULT_ENDPOINT = "/_forge/routes";
   async function fetchSummary(inputs, baseURL, fetchMeta) {
-    const { explicitLevels, explicitEndpoint } = inputs;
-    if (!explicitEndpoint) {
-      throw new UnknownLevelError("(auto-discovery)");
-    }
+    const { explicitLevels, explicitEndpoint, warnings } = inputs;
+    const endpoint = explicitEndpoint ?? DEFAULT_ENDPOINT;
+    const url = joinBaseAndPath(baseURL, endpoint);
     try {
-      const base = baseURL.endsWith("/") ? baseURL.slice(0, -1) : baseURL;
-      const ep = explicitEndpoint.startsWith("/") ? explicitEndpoint : `/${explicitEndpoint}`;
-      const data = await fetchMeta("__forge__.summary", `${base}${ep}`);
+      const data = await fetchMeta("__forge__.summary", url);
       return data;
     } catch (e) {
       if (explicitLevels && explicitLevels.length > 0) {
-        console.warn(
-          `[route-forge] summary endpoint unreachable: ${e.message}; using explicit levels`
-        );
+        if (warnings) {
+          console.warn(
+            `[route-forge] summary endpoint unreachable: ${e.message}; using explicit levels`
+          );
+        }
         return null;
       }
-      throw new UnknownLevelError("(auto-discovery)");
+      throw new NetworkError(
+        `Failed to fetch route summary from "${url}": ${e?.message ?? String(e)}; check the backend manifest endpoint or options.endpoint`,
+        void 0,
+        void 0,
+        e
+      );
     }
   }
   function normalizeCacheTtl(raw) {
@@ -699,15 +910,15 @@ var RouteForge = (function (exports) {
     return raw;
   }
   function applySummaryToState(summary, state, inputs) {
-    const { explicitLevels, explicitEager, explicitEndpoint } = inputs;
+    const { explicitLevels, explicitEager, explicitEndpoint, warnings } = inputs;
     const schemeVersion = summary.schemeVersion ?? 1;
-    if (schemeVersion > 1) {
+    if (schemeVersion > 1 && warnings) {
       console.warn(
         `[route-forge] backend schemeVersion=${schemeVersion} > client supported 1; some features may be unavailable`
       );
     }
     if (summary.config.endpoint_prefix && summary.config.endpoint_prefix !== explicitEndpoint) {
-      if (explicitEndpoint) {
+      if (explicitEndpoint && warnings) {
         console.warn(
           `[route-forge] backend endpoint_prefix "${summary.config.endpoint_prefix}" overrides frontend endpoint "${explicitEndpoint}"`
         );
@@ -730,7 +941,7 @@ var RouteForge = (function (exports) {
     if (explicitLevels && explicitLevels.length > 0) {
       const intersection = explicitLevels.filter((l) => backendLevels.includes(l));
       const removed = explicitLevels.filter((l) => !backendLevels.includes(l));
-      if (removed.length > 0) {
+      if (removed.length > 0 && warnings) {
         console.warn(
           `[route-forge] levels not in backend summary and dropped: ${removed.join(", ")}`
         );
@@ -779,23 +990,18 @@ var RouteForge = (function (exports) {
       this.fetchMeta = deps.fetchMeta;
       this.autoDiscoveryPromise = deps.autoDiscoveryPromise;
       this.getAutoDiscoveryError = deps.getAutoDiscoveryError;
+      this.onChange = deps.onChange;
     }
     assertLevelDeclared(level) {
       if (!this.state.levels.includes(level)) {
-        throw new UnknownLevelError(level);
+        throw new UnknownLevelError(level, this.state.levels);
       }
     }
     async fetchLevel(level) {
       const uri = this.state.levelRoutes[level]?.uri;
-      const url = uri ? this.joinBaseAndPath(this.baseURL, uri) : buildUrl(level, { baseURL: this.baseURL, endpoint: this.state.endpoint });
+      const url = uri ? joinBaseAndPath(this.baseURL, uri) : buildUrl(level, { baseURL: this.baseURL, endpoint: this.state.endpoint });
       return await this.fetchMeta(`route-forge.${level}`, url, level);
     }
-    /** baseURL 与后端下发的绝对 path 拼接（规范化斜杠），与 buildUrl 的 base 处理一致 */
-    joinBaseAndPath(baseURL, path) {
-      const base = baseURL.endsWith("/") ? baseURL.slice(0, -1) : baseURL;
-      const p = path.startsWith("/") ? path : `/${path}`;
-      return `${base}${p}`;
-    }
     async loadOne(level) {
       const autoDiscoveryError = this.getAutoDiscoveryError();
       if (autoDiscoveryError) throw autoDiscoveryError;
@@ -810,6 +1016,7 @@ var RouteForge = (function (exports) {
           const resp = await this.fetchLevel(level);
           if ((this.invalidationGens.get(level) ?? 0) === gen) {
             this.cache.set(resp, this.state.cacheTtl);
+            this.onChange?.(level);
           }
         } finally {
           this.inflight.delete(level);
@@ -823,6 +1030,36 @@ var RouteForge = (function (exports) {
       const list = Array.isArray(level) ? level : [level];
       await Promise.all(list.map((l) => this.loadOne(l)));
     }
+    /**
+     * 强制刷新：跳过缓存命中短路重新拉取指定层级，成功后覆盖缓存、失败保留旧值。
+     * 与 invalidate→load 的区别——全程不清空缓存，故读取旧数据不受影响、无空窗。
+     */
+    async revalidate(level) {
+      await this.autoDiscoveryPromise;
+      const list = Array.isArray(level) ? level : [level];
+      await Promise.all(list.map((l) => this.revalidateOne(l)));
+    }
+    async revalidateOne(level) {
+      const autoDiscoveryError = this.getAutoDiscoveryError();
+      if (autoDiscoveryError) throw autoDiscoveryError;
+      this.assertLevelDeclared(level);
+      const existing = this.inflight.get(level);
+      if (existing) return existing;
+      const gen = this.invalidationGens.get(level) ?? 0;
+      const p = (async () => {
+        try {
+          const resp = await this.fetchLevel(level);
+          if ((this.invalidationGens.get(level) ?? 0) === gen) {
+            this.cache.set(resp, this.state.cacheTtl);
+            this.onChange?.(level);
+          }
+        } finally {
+          this.inflight.delete(level);
+        }
+      })();
+      this.inflight.set(level, p);
+      return p;
+    }
     invalidate(level) {
       if (level === void 0) {
         this.cache.clear();
@@ -830,16 +1067,19 @@ var RouteForge = (function (exports) {
         for (const lvl of this.state.levels) {
           this.invalidationGens.set(lvl, (this.invalidationGens.get(lvl) ?? 0) + 1);
         }
+        for (const lvl of this.state.levels) this.onChange?.(lvl);
       } else if (Array.isArray(level)) {
         for (const lvl of level) {
           this.cache.del(lvl);
           this.inflight.delete(lvl);
           this.invalidationGens.set(lvl, (this.invalidationGens.get(lvl) ?? 0) + 1);
         }
+        for (const lvl of level) this.onChange?.(lvl);
       } else {
         this.cache.del(level);
         this.inflight.delete(level);
         this.invalidationGens.set(level, (this.invalidationGens.get(level) ?? 0) + 1);
+        this.onChange?.(level);
       }
     }
     isLoaded(level) {
@@ -854,13 +1094,24 @@ var RouteForge = (function (exports) {
       }
       return void 0;
     }
+    /**
+     * 该层级当前已加载的路由名列表（不深拷贝，仅读键名）。
+     * 供错误候选与 prefix 解析使用——避免为取名字而 getRoutes 深拷贝整表。
+     * 层级未声明抛 UnknownLevelError（与 getRoutes/route 一致）。
+     */
+    routeNames(level) {
+      this.assertLevelDeclared(level);
+      const entry = this.cache.get(level);
+      return entry ? Object.keys(entry.routes) : [];
+    }
     getRoutes(level) {
       if (level !== void 0) {
+        this.assertLevelDeclared(level);
         const entry = this.cache.get(level);
         const routes = entry?.routes ?? {};
         const result2 = {};
         for (const [k, v] of Object.entries(routes)) {
-          result2[k] = JSON.parse(JSON.stringify(v));
+          result2[k] = structuredClone(v);
         }
         return result2;
       }
@@ -870,7 +1121,7 @@ var RouteForge = (function (exports) {
         if (entry) {
           const levelRoutes = {};
           for (const [k, v] of Object.entries(entry.routes)) {
-            levelRoutes[k] = JSON.parse(JSON.stringify(v));
+            levelRoutes[k] = structuredClone(v);
           }
           result[lvl] = levelRoutes;
         }
@@ -887,6 +1138,7 @@ var RouteForge = (function (exports) {
       responseInterceptors,
       load,
       findRouteMeta,
+      getRouteNames,
       baseURL,
       state,
       timeout,
@@ -938,7 +1190,10 @@ var RouteForge = (function (exports) {
                   level: resp.level,
                   status: resp.status,
                   url: resp.url,
-                  method: resp.method
+                  method: resp.method,
+                  // 完整 ResponseData 随错误逐段传递（响应拦截器 onRejected 链 → 最终 catch），
+                  // 供调用方检查响应体，如 Laravel 422 校验错误 err.response.data.errors
+                  response: resp
                 }
               );
             }
@@ -967,18 +1222,37 @@ var RouteForge = (function (exports) {
       let ctrl;
       let abortedBeforeInit = false;
       let abortReason;
-      const work = (async () => {
-        ctrl = new AbortController();
-        if (abortedBeforeInit) {
-          ctrl.abort(abortReason);
+      const externalSignal = params.signal;
+      const onExternalAbort = () => {
+        if (ctrl) {
+          ctrl.abort(externalSignal?.reason);
+        } else {
+          abortedBeforeInit = true;
+          abortReason = externalSignal?.reason;
         }
-        await autoDiscoveryPromise;
-        await load(level);
-        const meta = findRouteMeta(level, name);
-        if (!meta) {
-          throw new UnknownRouteError(name, level);
+      };
+      if (externalSignal?.aborted) {
+        abortedBeforeInit = true;
+        abortReason = externalSignal.reason;
+      } else {
+        externalSignal?.addEventListener("abort", onExternalAbort, { once: true });
+      }
+      const work = (async () => {
+        try {
+          ctrl = new AbortController();
+          if (abortedBeforeInit) {
+            ctrl.abort(abortReason);
+          }
+          await autoDiscoveryPromise;
+          await load(level);
+          const meta = findRouteMeta(level, name);
+          if (!meta) {
+            throw new UnknownRouteError(name, level, getRouteNames(level));
+          }
+          return await doApiCall(meta, params, ctrl.signal);
+        } finally {
+          externalSignal?.removeEventListener("abort", onExternalAbort);
         }
-        return doApiCall(meta, params, ctrl.signal);
       })();
       const request = work;
       request.abort = () => {
@@ -993,22 +1267,31 @@ var RouteForge = (function (exports) {
   }
 
   // src/resolveRouteName.ts
+  function stripTrailingSeparator(prefix, separator) {
+    let normalized = prefix;
+    while (normalized.endsWith(separator)) {
+      normalized = normalized.slice(0, -separator.length);
+    }
+    return normalized;
+  }
   async function resolveRouteName(forge, level, prefix, suffix, separator = ".") {
-    if (!suffix) return prefix;
-    const joined = `${prefix}${separator}${suffix}`;
-    if (!suffix.startsWith(`${prefix}${separator}`)) return joined;
+    const normalized = stripTrailingSeparator(prefix, separator);
+    if (!suffix) return normalized;
+    const joined = `${normalized}${separator}${suffix}`;
+    if (!suffix.startsWith(`${normalized}${separator}`)) return joined;
     await forge.load(level);
     if (forge.hasRoute(level, joined)) return joined;
     if (forge.hasRoute(level, suffix)) return suffix;
-    throw new UnknownRouteError(joined, level);
+    throw new UnknownRouteError(joined, level, forge.getRouteNames?.(level));
   }
   function resolveRouteNameSync(forge, level, prefix, suffix, separator = ".") {
-    if (!suffix) return prefix;
-    const joined = `${prefix}${separator}${suffix}`;
-    if (!suffix.startsWith(`${prefix}${separator}`)) return joined;
+    const normalized = stripTrailingSeparator(prefix, separator);
+    if (!suffix) return normalized;
+    const joined = `${normalized}${separator}${suffix}`;
+    if (!suffix.startsWith(`${normalized}${separator}`)) return joined;
     if (forge.hasRoute(level, joined)) return joined;
     if (forge.hasRoute(level, suffix)) return suffix;
-    throw new UnknownRouteError(joined, level);
+    throw new UnknownRouteError(joined, level, forge.getRouteNames?.(level));
   }
 
   // src/defineImmutableProps.ts
@@ -1027,8 +1310,8 @@ var RouteForge = (function (exports) {
 
   // src/bound-forge.ts
   function createBoundForgeFactory(deps) {
-    const { load, api, route, hasRoute, getRoutes, invalidate, isLoaded, loadingTracker } = deps;
-    const resolver = { load, hasRoute };
+    const { load, api, route, hasRoute, getRoutes, getRouteNames, invalidate, isLoaded, loadingTracker } = deps;
+    const resolver = { load, hasRoute, getRouteNames };
     function createBoundForge(level, prefix) {
       const levelLoadedPromise = load(level);
       levelLoadedPromise.catch(() => {
@@ -1094,11 +1377,6 @@ var RouteForge = (function (exports) {
   var DEFAULT_CACHE_TTL = 3600;
   function createRouteForge(options = {}) {
     const bootstrapSummary = readEmbeddedSummary() ?? options.summary ?? null;
-    if (!bootstrapSummary && !options.endpoint) {
-      throw new TypeError(
-        "createRouteForge: \u9700\u8981 options.endpoint\uFF0C\u6216 options.summary\uFF0C\u6216\u9875\u9762\u5185\u5D4C window.__ROUTE_FORGE__"
-      );
-    }
     const {
       adapter = "auto",
       timeout = DEFAULT_TIMEOUT,
@@ -1106,78 +1384,49 @@ var RouteForge = (function (exports) {
       interceptors: declarativeInterceptors,
       cache: cacheOpts = {}
     } = options;
+    const warnings = options.warnings ?? true;
     const loadingTracker = new LoadingTracker();
+    const routesTracker = new RouteChangeTracker();
     const explicitLevels = options.levels;
     const explicitEager = options.eager;
     const explicitEndpoint = options.endpoint;
     const discoveryState = {
       levels: explicitLevels ?? [],
       eager: explicitEager ?? [],
-      endpoint: explicitEndpoint ?? bootstrapSummary?.config?.endpoint_prefix ?? "",
+      endpoint: explicitEndpoint ?? bootstrapSummary?.config?.endpoint_prefix ?? DEFAULT_ENDPOINT,
       urlPrefix: "",
       cacheTtl: void 0,
       levelRoutes: {}
     };
-    const discoveryInputs = { explicitLevels, explicitEager, explicitEndpoint };
+    const discoveryInputs = { explicitLevels, explicitEager, explicitEndpoint, warnings };
     let autoDiscoveryCompleted = false;
-    let resolveReady;
-    let rejectReady;
-    const readyPromise = new Promise((resolve, reject) => {
-      resolveReady = resolve;
-      rejectReady = reject;
-    });
-    readyPromise.catch(() => {
-    });
+    const latch = createReadyLatch();
     const cacheTtl = cacheOpts.ttl ?? DEFAULT_CACHE_TTL;
     const cacheStorage = cacheOpts.storage ?? "memory";
     const cache = new RouteCache({ storage: cacheStorage, ttl: cacheTtl });
     const requestInterceptors = new InterceptorManagerImpl();
     const responseInterceptors = new InterceptorManagerImpl();
-    if (declarativeInterceptors?.request) {
-      for (const entry of declarativeInterceptors.request) {
-        if (typeof entry === "function") {
-          requestInterceptors.use(entry);
-        } else {
-          const [onFulfilled, onRejected] = entry;
-          requestInterceptors.use(onFulfilled, onRejected);
-        }
-      }
+    const reqDecl = normalizeInterceptorDeclaration(
+      declarativeInterceptors?.request
+    );
+    if (reqDecl.onFulfilled || reqDecl.onRejected) {
+      requestInterceptors.use(reqDecl.onFulfilled, reqDecl.onRejected);
     }
-    if (declarativeInterceptors?.response) {
-      for (const entry of declarativeInterceptors.response) {
-        if (typeof entry === "function") {
-          responseInterceptors.use(entry);
-        } else {
-          const [onFulfilled, onRejected] = entry;
-          responseInterceptors.use(onFulfilled, onRejected);
-        }
-      }
+    const resDecl = normalizeInterceptorDeclaration(
+      declarativeInterceptors?.response
+    );
+    if (resDecl.onFulfilled || resDecl.onRejected) {
+      responseInterceptors.use(resDecl.onFulfilled, resDecl.onRejected);
     }
-    const adapterPromise = resolveAdapter({
+    const ensureAdapter = createAdapterBootstrap({
       adapter,
-      forgeInterceptors: { request: requestInterceptors, response: responseInterceptors }
+      requestInterceptors,
+      responseInterceptors,
+      warnings
     });
-    let adapterResolved = false;
-    let adapterObj = null;
-    async function ensureAdapter() {
-      if (!adapterResolved) {
-        adapterObj = await adapterPromise.catch((e) => {
-          if (e instanceof AdapterNotFoundError) throw e;
-          return resolveAdapter({
-            adapter: "builtin",
-            forgeInterceptors: { request: requestInterceptors, response: responseInterceptors }
-          });
-        });
-        adapterResolved = true;
-      }
-      return adapterObj;
-    }
     function assertDiscoveryReady() {
       if (!autoDiscoveryCompleted && !explicitLevels?.length) {
-        throw new ForgeError(
-          "Route data not available. Auto-discovery has not completed. Use forge.ready() or forge.use(level) first.",
-          { code: "RF_FE_010" }
-        );
+        throw new DiscoveryNotReadyError();
       }
     }
     async function fetchMeta(routeTag, url, level = "") {
@@ -1202,8 +1451,8 @@ var RouteForge = (function (exports) {
       const resp = await doRawRequest(config);
       if (!resp || resp.status < 200 || resp.status >= 300) {
         throw new HTTPError(
-          `Failed to fetch "${routeTag}": HTTP ${resp?.status}`,
-          { level, status: resp?.status, url, method: "GET" }
+          `Failed to fetch "${routeTag}" (${url}): HTTP ${resp?.status}`,
+          { level, status: resp?.status, url, method: "GET", response: resp ?? void 0 }
         );
       }
       return resp.data;
@@ -1231,22 +1480,25 @@ var RouteForge = (function (exports) {
       baseURL,
       fetchMeta,
       autoDiscoveryPromise,
-      getAutoDiscoveryError: () => autoDiscoveryError
+      getAutoDiscoveryError: () => autoDiscoveryError,
+      onChange: (level) => routesTracker.notify(level)
     });
     const load = (level) => store.load(level);
+    const revalidate = (level) => store.revalidate(level);
     const findRouteMeta = (level, name) => store.findRouteMeta(level, name);
     const invalidate = (level) => store.invalidate(level);
     const isLoaded = (level) => store.isLoaded(level);
-    function getRoutes(level) {
-      return level === void 0 ? store.getRoutes() : store.getRoutes(level);
+    const getRoutes = store.getRoutes.bind(store);
+    function getLevels() {
+      return [...discoveryState.levels];
     }
     function route(level, name, params) {
       assertDiscoveryReady();
       const meta = findRouteMeta(level, name);
       if (!meta) {
-        throw new UnknownRouteError(name, level);
+        throw new UnknownRouteError(name, level, store.routeNames(level));
       }
-      return buildRequestUrl(meta, params ?? {}, { baseURL, urlPrefix: discoveryState.urlPrefix });
+      return buildRouteUrl(meta, params ?? {}, { baseURL, urlPrefix: discoveryState.urlPrefix });
     }
     const api = createHttpRunner({
       ensureAdapter,
@@ -1254,6 +1506,7 @@ var RouteForge = (function (exports) {
       responseInterceptors,
       load,
       findRouteMeta,
+      getRouteNames: (lvl) => store.routeNames(lvl),
       baseURL,
       state: discoveryState,
       timeout,
@@ -1279,23 +1532,17 @@ var RouteForge = (function (exports) {
         });
       }
     }).then(() => {
-      resolveReady(forgeInstance);
+      latch.resolve(forgeInstance);
     }).catch((e) => {
-      rejectReady(e);
+      latch.reject(e);
     });
-    function ready(onFulfilled, onRejected) {
-      if (onFulfilled) {
-        const p = readyPromise.then(onFulfilled, onRejected);
-        return p.then(() => forgeInstance);
-      }
-      return readyPromise;
-    }
     const createBoundForgeWithMethods = createBoundForgeFactory({
       load,
       api,
       route,
       hasRoute,
       getRoutes,
+      getRouteNames: (lvl) => store.routeNames(lvl),
       invalidate,
       isLoaded,
       loadingTracker
@@ -1303,19 +1550,24 @@ var RouteForge = (function (exports) {
     const forgeInstance = {
       api,
       load,
+      revalidate,
       route,
       url: route,
       invalidate,
       isLoaded,
       hasRoute,
       getRoutes,
+      getLevels,
+      warnings,
       isLoading: () => loadingTracker.isLoading(),
+      isReady: () => latch.isReady(),
       onLoadingChange: (cb) => loadingTracker.subscribe(cb),
+      onRoutesChange: (cb) => routesTracker.subscribe(cb),
       interceptors: {
         request: requestInterceptors,
         response: responseInterceptors
       },
-      ready,
+      ready: latch.ready,
       use(level, prefix) {
         if (level === void 0) return forgeInstance;
         return createBoundForgeWithMethods(level, prefix);
@@ -1325,15 +1577,18 @@ var RouteForge = (function (exports) {
   }
 
   exports.AdapterNotFoundError = AdapterNotFoundError;
+  exports.DiscoveryNotReadyError = DiscoveryNotReadyError;
   exports.ForgeError = ForgeError;
   exports.HTTPError = HTTPError;
   exports.InterceptorManagerImpl = InterceptorManagerImpl;
   exports.InvalidInterceptorReturnError = InvalidInterceptorReturnError;
+  exports.InvalidPathParamError = InvalidPathParamError;
   exports.LoadingTracker = LoadingTracker;
   exports.MissingRouteParamError = MissingRouteParamError;
   exports.NetworkError = NetworkError;
   exports.RequestAbortedError = RequestAbortedError;
   exports.RouteCache = RouteCache;
+  exports.RouteChangeTracker = RouteChangeTracker;
   exports.UnknownLevelError = UnknownLevelError;
   exports.UnknownRouteError = UnknownRouteError;
   exports.createInterceptorManager = createInterceptorManager;