@route-forge/core 2.2.1 → 3.1.0

package/dist/index.cjs

@@ -131,6 +131,36 @@ var RouteCache = class {
   }
 };
 
+// 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) {
@@ -143,30 +173,56 @@ var ForgeError = class extends Error {
     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 {
@@ -199,6 +255,7 @@ var HTTPError = class extends ForgeError {
       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 {
@@ -211,33 +268,16 @@ var RequestAbortedError = class extends ForgeError {
     });
   }
 };
-
-// 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));
@@ -274,8 +314,44 @@ async function runResponseInterceptors(manager, source) {
   }
   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
@@ -377,7 +453,10 @@ async function rawFetch(config) {
       level: config.level,
       status: res.status,
       url,
-      method: config.method
+      method: config.method,
+      // 完整 ResponseData 随错误逐段传递（响应拦截器 onRejected 链 → 最终 catch），
+      // 供调用方检查响应体，如 Laravel 422 校验错误 err.response.data.errors
+      response: responseData
     }
   );
 }
@@ -506,6 +585,69 @@ async function resolveAdapter(opts) {
   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() {
@@ -565,12 +707,107 @@ var LoadingTracker = class {
   }
 };
 
-// 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 = [];
@@ -589,7 +826,7 @@ function buildRequestUrl(meta, params, ctx) {
     }
   }
   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("?");
@@ -597,10 +834,7 @@ function buildRequestUrl(meta, params, ctx) {
     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));
     }
@@ -608,10 +842,10 @@ function buildRequestUrl(meta, params, ctx) {
   });
   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}`;
 }
@@ -630,67 +864,44 @@ function appendQuery(url, query) {
   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) {
@@ -698,15 +909,15 @@ function normalizeCacheTtl(raw) {
   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}"`
       );
@@ -729,7 +940,7 @@ function applySummaryToState(summary, state, inputs) {
   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(", ")}`
       );
@@ -778,23 +989,18 @@ var RouteStore = class {
     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;
@@ -809,6 +1015,7 @@ var RouteStore = class {
         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);
@@ -822,6 +1029,36 @@ var RouteStore = class {
     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();
@@ -829,16 +1066,19 @@ var RouteStore = class {
       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) {
@@ -853,13 +1093,24 @@ var RouteStore = class {
     }
     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;
     }
@@ -869,7 +1120,7 @@ var RouteStore = class {
       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;
       }
@@ -886,6 +1137,7 @@ function createHttpRunner(deps) {
     responseInterceptors,
     load,
     findRouteMeta,
+    getRouteNames,
     baseURL,
     state,
     timeout,
@@ -937,7 +1189,10 @@ function createHttpRunner(deps) {
                 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
               }
             );
           }
@@ -966,18 +1221,37 @@ function createHttpRunner(deps) {
     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 = () => {
@@ -992,22 +1266,31 @@ function createHttpRunner(deps) {
 }
 
 // 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
@@ -1026,8 +1309,8 @@ function defineImmutableProps(target, props) {
 
 // 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(() => {
@@ -1093,11 +1376,6 @@ var DEFAULT_TIMEOUT = 3e4;
 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,
@@ -1105,78 +1383,49 @@ function createRouteForge(options = {}) {
     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 = "") {
@@ -1201,8 +1450,8 @@ function createRouteForge(options = {}) {
     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;
@@ -1230,22 +1479,25 @@ function createRouteForge(options = {}) {
     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,
@@ -1253,6 +1505,7 @@ function createRouteForge(options = {}) {
     responseInterceptors,
     load,
     findRouteMeta,
+    getRouteNames: (lvl) => store.routeNames(lvl),
     baseURL,
     state: discoveryState,
     timeout,
@@ -1278,23 +1531,17 @@ function createRouteForge(options = {}) {
       });
     }
   }).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
@@ -1302,19 +1549,24 @@ function createRouteForge(options = {}) {
   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);
@@ -1324,15 +1576,18 @@ function createRouteForge(options = {}) {
 }
 
 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;