@route-forge/core 2.1.0 → 2.2.0

package/README.md

@@ -1,335 +1,407 @@
 # @route-forge/core
 
-框架无关的命名路由客户端核心：分级懒加载、隔离缓存、并发去重、拦截器。
+**English** | [中文](./README_zh.md)
 
-## 安装
+The framework-agnostic client core for Laravel named routes: fetches route metadata from a backend manifest endpoint, lazy-loads and caches it per level, calls APIs **by route name**, and builds URLs — all with TypeScript type safety and axios-compatible interceptors.
+
+## What it does
+
+- **Call APIs by route name**: `forge.api('admin', 'users.show', { user: 123 })` — no hardcoded paths
+- **Tiered lazy loading**: route metadata is grouped into levels (e.g. `public` / `admin`) and fetched on demand
+- **Isolated cache + request deduplication**: per-level cache (memory / sessionStorage / localStorage with TTL); concurrent fetches of the same level are merged into one request
+- **Auto-discovery**: on startup it fetches the summary endpoint to discover levels, eager tiers, and the URL prefix
+- **Interceptors**: request / response chains with axios-compatible `use` / `eject` / `clear` (request LIFO, response FIFO)
+- **Request cancellation**: `forge.api()` returns a `ForgeRequest` with a built-in `abort()` that cooperates with timeouts
+- **Loading-state tracking**: in-flight request counter + subscriptions, ready to drive a global loading indicator
+- **Type safety**: `ForgeRouteMap` two-level mapping (codegen or module augmentation) gives compile-time checks for route names, params, and responses
+- **Pluggable transport**: zero-dependency built-in `fetch` implementation (default), host axios reuse, or a custom `Fetcher`
+- **Plain `<script>` usage**: an IIFE build is provided for direct browser inclusion, no bundler required
+
+## Installation
 
 ```bash
 pnpm add @route-forge/core
-# 可选：axios 适配器
+# Optional: if axios is installed in the host project and adapter is 'auto' (default),
+# it is detected and reused automatically; install it explicitly to force 'axios' mode
 pnpm add axios
 ```
 
-## 基本用法
+## Quick start
 
 ```ts
 import { createRouteForge } from '@route-forge/core'
 
 const forge = createRouteForge({
-  endpoint: '/_forge/routes',
+  endpoint: '/_forge/routes',   // backend manifest endpoint
 })
 
-// 调用 API（自动加载层级 + 填充参数 + 发送请求）
+// Call an API (auto-discovers → lazy-loads the level → fills path params → sends the request)
 const user = await forge.api('admin', 'users.show', { user: 123 })
 
-// 生成 URL（仅拼路径，不发请求）
-const url = forge.route('public', 'login.show')
-// → '/login'
+// Build URLs only (no request is sent)
+const url = forge.route('public', 'login.show')   // → '/login'
+const url2 = forge.url('public', 'login.show')    // url() is a semantic alias of route()
+
+// Route existence / metadata inspection
+forge.hasRoute('admin', 'users.show')             // true / false
+forge.getRoutes('admin')                          // snapshot of one level (deep copy)
+forge.getRoutes()                                 // all loaded levels, grouped by level
+
+// Level loading & cache management
+await forge.load('admin')                         // load a level (concurrent calls deduplicated)
+forge.isLoaded('admin')                           // is the level cached?
+forge.invalidate('admin')                         // invalidate one level
+forge.invalidate(['admin', 'manage'])             // invalidate several
+forge.invalidate()                                // invalidate all
+```
 
-// url() 是 route() 的语义别名
-const url2 = forge.url('public', 'login.show')
+## Initialization sequence & `ready()`
 
-// 检查路由是否存在
-forge.hasRoute('admin', 'users.show')  // true / false
+`createRouteForge()` immediately starts **auto-discovery** (summary endpoint) in the background, then preloads the **eager** levels. `ready()` resolves once both are done (it resolves with the forge instance itself, so chaining works):
 
-// 获取路由元信息
-const routes = forge.getRoutes('admin')          // 指定层级
-const allRoutes = forge.getRoutes()              // 全部层级
+```ts
+const forge = createRouteForge({ endpoint: '/_forge/routes' })
 
-// 检查层级是否已加载
-if (!forge.isLoaded('admin')) {
-  await forge.load('admin')
-}
+// Recommended: mount the app after ready() — sync methods like route()/hasRoute() are then safe
+forge.ready()
+  .then(() => app.mount('#app'))
+  .catch((err) => {
+    // Always handle this: ready() rejects when the summary endpoint is unreachable
+    // and no explicit levels were given — otherwise users face a silent blank page
+    console.error('[route-forge] init failed', err)
+  })
+
+// Callback style: onFulfilled / onRejected (still returns a Promise)
+forge.ready(
+  (f) => console.log('ready!', f),
+  (err) => console.error(err),
+)
 
-// 失效缓存
-forge.invalidate('admin')                     // 失效指定层级
-forge.invalidate(['admin', 'manage'])         // 批量失效多个层级
-forge.invalidate()                            // 失效全部
+// async/await style
+await forge.ready()
 ```
 
-## URL 前缀（`url_prefix`）
+The three loading phases and how to track them:
 
-后端可在摘要端点 `config.url_prefix` 中下发 URL 前缀，前端生成路由 URL 时自动拼接，无需手动配置。
+| Phase | Description | Tracking |
+|-------|-------------|----------|
+| Auto-discovery | fetch the summary endpoint, discover levels/config | `forge.ready()` |
+| Level load | fetch one level's route metadata | `forge.isLoaded(level)` / `bound.onLevelLoaded()` |
+| API request | business API calls | `forge.isLoading()` / `forge.onLoadingChange()` |
 
-支持两种形式：
+**Degradation rule**: if explicit `levels` were provided, an unreachable summary endpoint logs a `console.warn` and falls back to the explicit configuration; without explicit `levels` there is no fallback and `ready()` rejects (with `HTTPError` / `NetworkError` / `UnknownLevelError`).
 
-```ts
-// 1. 路径前缀 — 拼接在 baseURL 之后、路由 URI 之前
-// 后端返回 { "config": { "url_prefix": "/api/v1" } }
-forge.route('public', 'users.show', { user: 1 })
-// → '/api/v1/users/1'
-
-// 2. 完整 URL（含协议+域名）— 直接作为基础 URL，忽略客户端 baseURL
-//    适用于前后端不同域名的场景
-// 后端返回 { "config": { "url_prefix": "https://api.example.com" } }
-forge.route('public', 'users.show', { user: 1 })
-// → 'https://api.example.com/users/1'
-```
+**Guard**: while auto-discovery has not completed and no explicit `levels` exist, `route()` / `hasRoute()` throw `ForgeError (RF_FE_010)` to prevent wrong results from unready data; `api()` is unaffected (it awaits discovery internally).
+
+## Options (`createRouteForge(options)`)
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `endpoint` | `string` | — | summary/manifest endpoint path (network source). Optional: at least one of `endpoint`, `summary`, or an embedded `window.__ROUTE_FORGE__` must exist, otherwise `createRouteForge` throws `TypeError` |
+| `summary` | `SummaryResponse` | — | Provide the summary directly (tests / non-global bootstrap), skipping the summary HTTP request. Takes lower priority than an embedded `window.__ROUTE_FORGE__` |
+| `levels` | `string[]` | auto-discovered | discovered from the summary when omitted; when given, intersected with the backend summary (the frontend cannot declare levels the backend doesn't know) |
+| `eager` | `string[]` | backend `load:'eager'` levels | levels preloaded after discovery; union with the backend marks when given |
+| `adapter` | `'auto' \| 'axios' \| 'builtin' \| Fetcher` | `'auto'` | see "Adapters" below |
+| `cache.ttl` | `number` (seconds) | `3600` | frontend fallback TTL; the backend's global `config.cache_ttl` is the ceiling — the effective TTL is `min(backend, frontend)` (frontend may shorten but never extend; `0` = forever; `config.cache_ttl: null` = don't cache) |
+| `cache.storage` | `'memory' \| 'sessionStorage' \| 'localStorage'` | `'memory'` | cache backend; storage modes keep an in-memory mirror and invalidate cross-tab writes via `storage` events |
+| `interceptors.request` | array | none | declarative request interceptors: plain function (treated as `onFulfilled`) or `[onFulfilled?, onRejected?]` tuple |
+| `interceptors.response` | array | none | declarative response interceptors, same shapes |
+| `timeout` | `number` (ms) | `30000` | global timeout; a single call can override it via `params.timeout` |
+| `baseURL` | `string` | `''` | base prepended to every generated URL |
+| `strict` | `boolean` | — | **Deprecated, ignored.** Frontend validation is always on (unknown level → `UnknownLevelError`, unknown route → `UnknownRouteError`, missing required param → `MissingRouteParamError`); silently ignoring typos hides bugs. The backend's `strict_mode` is a manifest-generation concern and unrelated to the frontend |
+
+## Embedded bootstrap (optional hydration)
+
+Summary discovery reads from one source in this cascade: **embedded `window.__ROUTE_FORGE__` → `createRouteForge({ summary })` → network `GET {endpoint}`**. All three deliver the same `SummaryResponse`.
 
-> `url_prefix` 为后端权威，前端不能覆盖。不下发或为空字符串时不影响 URL 生成。
+For Laravel/Blade server-rendered first pages, the backend `@forgeSummary` directive inlines the summary as a one-shot, non-enumerable `window.__ROUTE_FORGE__` accessor that self-deletes on first read. When core finds it, it **skips the summary HTTP round-trip and completes discovery synchronously** — `route()` / `ready()` work immediately after `createRouteForge()` returns, eliminating the "routes not ready" first-paint flash. Level route tables are still lazy-loaded per level over HTTP (protected routes never enter the public HTML). A module-level memo lets a second instance (React StrictMode / a second provider) reuse the summary after the global is gone.
 
-## 参数智能解析
+If no embed exists (standalone SPA, Vite dev), core falls back to the network summary automatically. `createRouteForge({ summary })` is the explicit, test/SSR-friendly entry.
 
-`forge.api()` 的第二参数支持四种数据类型：路径参数（平铺）、`query`（查询参数）、`body`（请求体）、`headers`
-（请求头）。同时提供 `params` 固定 key 用于显式指定路径参数。
+> Honest scope: the one-shot self-delete only shrinks the summary's runtime footprint on `window`; the data is still present in the HTML source. This is a latency/flash optimization, **not** an XSS- or network-egavesdropping-proof boundary.
 
-当路径参数名与 `query`/`body`/`headers` 冲突时，按类型智能消解：
+## Smart parameter resolution
+
+The third argument `params` of `forge.api(level, name, params)` carries four kinds of data — path parameters (flattened), `query`, `body`, `headers` — plus `timeout` (per-call override) and the explicit `params` key:
 
 ```ts
-// 向后兼容：原有写法不变
+// Flattened path params + query string
 forge.api('admin', 'users.show', { user: 1, query: { include: 'posts' } })
 
-// 冲突消解：query 为 string → 自动识别为路径参数
-// 路由: /search/{query}
+// Conflict resolution: route /search/{query} — a string `query` is detected as a path param
 forge.api('admin', 'search.show', { query: 'keyword' })
 // → URL: /search/keyword
 
-// 显式 params：同时需要路径参数和 query string
+// Explicit params: need BOTH a path param and a query string (`params` wins)
 forge.api('admin', 'search.show', {
-  params: { query: 'keyword' },   // → 替换 {query}
+  params: { query: 'keyword' },   // → fills the {query} placeholder
   query: { page: 1 },             // → query string
-  body: { detailed: true },       // → 请求体
+  body: { detailed: true },       // → request body
+  headers: { 'X-Trace': 'a1' },   // → request headers
+  timeout: 120_000,               // → per-call timeout override (default 30s)
 })
 ```
 
-规则：`params` 优先 > 平铺 `string|number` → 路径参数 > 对象类型按原定义（`query`/`body`/`headers`）。
+Resolution rules (by priority):
+
+1. Explicit `params` → path parameters, highest priority
+2. Remaining flattened keys → path parameters (they never overwrite keys already present in `params`)
+3. Fixed keys resolved by value type: object `query` / `headers` → their fixed purpose; `string|number` → path parameter; `body` non-`string|number` → request body, `string|number` → path parameter
+4. Optional URI params (`{param?}`) become empty segments when missing (extra `/` cleaned up); backend-provided `parameter_defaults` fill in for missing params
+
+## URL prefix (`url_prefix`)
+
+The backend may deliver a URL prefix via `config.url_prefix` in the summary endpoint; generated URLs automatically include it:
+
+```ts
+// 1. Path prefix — inserted after baseURL, before the route URI
+// backend returns { "config": { "url_prefix": "/api/v1" } }
+forge.route('public', 'users.show', { user: 1 })   // → '/api/v1/users/1'
+
+// 2. Full URL (protocol + host) — used as the base URL, the client's baseURL is ignored;
+//    ideal when frontend and backend live on different origins
+// backend returns { "config": { "url_prefix": "https://api.example.com" } }
+forge.route('public', 'users.show', { user: 1 })   // → 'https://api.example.com/users/1'
+```
+
+> `url_prefix` is backend-authoritative; the frontend cannot override it. An absent or empty prefix leaves URLs unchanged.
 
-## 单次超时覆盖
+## Level binding: `forge.use(level, prefix?)`
 
-`forge.api()` 支持通过 `timeout` 参数覆盖单次请求的超时时间（毫秒），不传时使用
-`createRouteForge({ timeout })` 的全局值（默认 30s）：
+`use()` is the single level-binding entry point and returns a `BoundForge` — Vue / React / IIFE share the exact same API surface:
 
 ```ts
-// 全局超时 30s，单次导出请求覆盖为 120s
-forge.api('admin', 'reports.export', { timeout: 120_000 })
+// Bind a level — triggers load automatically, exposes shortcuts
+const bound = forge.use('admin')
+bound('users.show', { user: 1 })      // callable directly (= bound.api())
+bound.route('users.show')             // URL generation
+bound.level                           // → 'admin'
+bound.levelLoaded                     // Promise<void> in core (Vue/React specialize this)
+
+// Bind level + prefix — route names are joined automatically
+// (ambiguity is resolved smartly: prefer prefix.suffix, fall back to suffix itself)
+const users = forge.use('admin', 'users')
+users('show', { user: 1 })            // → forge.api('admin', 'users.show', ...)
+
+// Other BoundForge methods
+await bound.onLevelLoaded()           // wait until the level is loaded (callback form supported)
+bound.hasRoute('users.show')          // existence check within the bound level
+bound.useRoutePrefix('posts')         // returns a NEW BoundForge with the new prefix (original unchanged)
+// Generic methods act on the bound level: bound.load() / bound.invalidate() / bound.isLoaded()
+// Global methods still work: bound.isLoading() / bound.onLoadingChange()
 ```
 
-## 认证（Authentication）
+> Every `use()` call returns a fresh `BoundForge` (not cached); `forge.use()` without arguments returns the forge itself.
 
-Route Forge 不内置登录态管理，认证逻辑通过拦截器实现，灵活且完全可控。
+## Request cancellation
 
-### Token 注入
+`forge.api()` returns a `ForgeRequest` — a `Promise` with an extra `abort()` method; the internal `AbortController` is managed for you:
 
 ```ts
-// 声明式（初始化时配置）
+const req = forge.api('admin', 'reports.export', { timeout: 120_000 })
+req.abort()   // the request is aborted; the Promise rejects with RequestAbortedError (RF_FE_009)
+```
+
+`abort()` and the timeout (`AbortSignal.timeout`) cooperate — whichever fires first cancels the request. Interceptors can read the AbortSignal via `config.signal`.
+
+## Interceptors & authentication
+
+The interceptor API matches axios (`use` / `eject` / `clear`); request interceptors run **LIFO** (last registered, first executed), response interceptors **FIFO**. Route Forge ships no built-in session management — auth is done via interceptors:
+
+```ts
+// Declarative (at initialization)
 const forge = createRouteForge({
   endpoint: '/_forge/routes',
   interceptors: {
     request: [
       (config) => {
         const token = authStore.getToken()
-        if (token) {
-          config.headers.Authorization = `Bearer ${token}`
-        }
-        return config
+        if (token) config.headers.Authorization = `Bearer ${token}`
+        return config   // must return a RequestConfig object, otherwise RF_FE_006 is thrown
       },
     ],
+    response: [
+      (resp) => resp.data,                    // unwrap: api() resolves with business data directly
+      [undefined, (err) => {                  // tuple form: [onFulfilled?, onRejected?]
+        if (err instanceof HTTPError && err.context?.status === 401) {
+          authStore.logout()
+          window.location.href = '/login'
+        }
+        return Promise.reject(err)
+      }],
+    ],
   },
 })
 
-// 或运行时动态注册
-forge.interceptors.request.use((config) => {
-  const token = authStore.getToken()
-  if (token) {
-    config.headers.Authorization = `Bearer ${token}`
-  }
-  return config
-})
+// Runtime registration / removal / clearing
+const id = forge.interceptors.request.use((config) => { /* ... */ return config })
+forge.interceptors.request.eject(id)
+forge.interceptors.request.clear()
+forge.interceptors.response.clear()
 ```
 
-### 401 响应处理
-
-```ts
-forge.interceptors.response.use(
-  (res) => res,  // 2xx 正常通过
-  (err) => {
-    if (err instanceof HTTPError && err.context?.status === 401) {
-      authStore.logout()
-      window.location.href = '/login'
-    }
-    return Promise.reject(err)
-  },
-)
-```
-
-### 登出清理
+**Logout cleanup** example:
 
 ```ts
 function logout() {
   authStore.clearToken()
-  forge.invalidate()                        // 清空路由缓存
-  forge.interceptors.request.clear()        // 清空拦截器
+  forge.invalidate()                     // clear the route cache
+  forge.interceptors.request.clear()     // clear interceptors
   forge.interceptors.response.clear()
 }
 ```
 
-> 拦截器 API 与 axios 完全一致（`use` / `eject` / `clear`），如果项目已使用 axios 拦截器，可跳过此节——
-> `adapter: 'auto'` 模式下宿主 axios 的拦截器会自动生效。
+> With `adapter: 'auto'` reusing host axios, interceptors already registered on the host axios instance run first; Route Forge interceptors run after them.
+> Metadata fetching (summary / level tables) goes through the adapter's raw channel and never passes the business interceptor chains, so unwrapping interceptors can't corrupt it.
 
-## 加载状态跟踪
+## Loading-state tracking
 
-核心始终跟踪并发 API 请求的加载状态，无需配置。不需要使用时，不调用相关 API 即可。
+The core always tracks concurrent API requests; there is nothing to configure — just don't subscribe if you don't need it:
 
 ```ts
-// 查询当前是否处于加载中
-forge.isLoading()  // boolean
+forge.isLoading()   // boolean: any request in flight?
 
-// 订阅状态变更
 const unsub = forge.onLoadingChange((event) => {
   console.log(event.loading)  // true / false
-  console.log(event.count)    // 当前并发请求数
+  console.log(event.count)    // current number of concurrent requests
 })
-
-// 取消订阅
-unsub()
+unsub()   // unsubscribe
 ```
 
-> 加载状态始终跟踪，用户不使用则不订阅即可。Vue/React 包可通过 `onLoadingChange` 订阅状态变更驱动组件显隐。
-
-## 初始化合时序与推荐模式
+The Vue / React packages can drive component-level loading indicators from `onLoadingChange`.
 
-### 三种加载状态
+## Type safety (optional but recommended)
 
-| 类型           | 说明                           | 跟踪方式                    |
-|----------------|--------------------------------|-----------------------------|
-| Auto-discovery | 拉取摘要端点发现 levels/config | 内部 `autoDiscoveryPromise` |
-| Level load     | 拉取某层级路由元数据           | `forge.isLoaded(level)`     |
-| API request    | 业务接口请求                   | `forge.isLoading()`         |
+`ForgeRouteMap` is a two-level mapping interface: level → route name → metadata. Once defined, **level / route name / params are inferred automatically** in `useForge` / `useForgeApi` / `bound()` calls — a typo'd route name becomes a compile error.
 
-### `ready()` 后挂载应用
+Two ways to define it:
 
-推荐在 `ready()` resolve 后挂载应用（auto-discovery + eager 层级全部完成），
-失败走 `catch`（onSummaryReady 回调已移除，统一走 ready——完整成功/失败语义链）：
+```bash
+# Option 1: codegen CLI (fetches the backend manifest, emits a .d.ts)
+npx route-forge-codegen \
+  --endpoint http://localhost/_forge/routes \
+  --out src/types/forge-routes.d.ts \
+  [--levels public,admin] [--responseTypes path/to/map.json]
+```
 
 ```ts
-const forge = createRouteForge({
-  endpoint: '/_forge/routes',
-})
-// 成功：摘要 + eager 完成后挂载；失败：接住 reject，避免静默白屏
-forge.ready()
-  .then(() => app.mount('#app'))
-  .catch((err) => {
-    console.error('[route-forge] init failed', err)
-    // 按业务需要降级：渲染错误页 / 重试 / 上报
-  })
+// Option 2: TypeScript module augmentation
+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[] }
+    }
+  }
+}
 ```
 
-### `forge.ready()` 方法
+The backend Laravel package ([route-forge/route-forge-laravel](https://github.com/route-forge/route-forge-laravel)) also ships `php artisan route:forge:types`, which generates the same structure.
 
-auto-discovery + eager load 完成后 resolve，返回 `Promise<RouteForge>`（resolve 值为 forge 自身），适合 async/await 风格：
+## The `unassigned` level
 
-```ts
-const forge = createRouteForge({ endpoint: '/_forge/routes' })
-
-// 无参模式：直接 await
-await forge.ready()
-// 路由数据已就绪，可安全调用 route() / hasRoute()
+Routes the backend did not assign to any level live under a special `unassigned` level that the backend always injects into the summary's `levels`. The frontend treats it exactly like any other level — it lazy-loads `levels.unassigned.route.uri` over HTTP:
 
-// 回调模式：onFulfilled / onRejected
-forge.ready(
-  (f) => { console.log('ready!', f) },
-  (err) => { console.error(err) }
-)
-
-// 链式调用：ready 返回 forge 自身
-const bound = await forge.ready().then(f => f.use('admin'))
+```ts
+await forge.load('unassigned')
+const data = await forge.api('unassigned', 'some.route')
 ```
 
-### `forge.use(level?, prefix?)` 层级绑定
+## Adapters
 
-`forge.use()` 是 core 层唯一的 level 绑定入口，返回 `BoundForge` 对象：
+| `adapter` value | Behavior |
+|-----------------|----------|
+| `'auto'` (default) | probes the host via dynamic `import('axios')`: reuses it when found (inheriting its interceptors / defaults), otherwise falls back to the built-in `builtin` implementation |
+| `'axios'` | forces host axios; throws `AdapterNotFoundError` (RF_FE_005) when not installed |
+| `'builtin'` | forces the built-in fetch implementation (zero dependencies, min+gzip < 3KB, axios-compatible interceptor behavior) |
+| custom `Fetcher` | pass any object implementing `request(config): Promise<ResponseData>` for full control |
 
-```ts
-// 绑定层级 — 自动触发 load，提供快捷方法
-const bound = forge.use('admin')
-bound('users.show', { user: 1 })   // 可直接调用（= bound.api()）
-bound.route('users.show')           // URL 生成
-bound.level                         // → 'admin'
-bound.levelLoaded                   // Promise<void>
-
-// 绑定层级 + 前缀 — 路由名自动拼接
-const bound = forge.use('admin', 'users')
-bound('show', { user: 1 })           // → forge.api('admin', 'users.show', ...)
-
-// BoundForge 独有方法
-await bound.onLevelLoaded()          // 等待 level 加载完成
-const prefixed = bound.useRoutePrefix('posts')  // 追加前缀
-```
+Bodies of type `FormData` / `Blob` / `ArrayBuffer` / `URLSearchParams` / `ReadableStream` skip JSON serialization automatically (plain `string` bodies pass through as well).
 
-### IIFE 浏览器用法
+## IIFE browser usage
 
-通过 `<script>` 标签引入后，`RouteForge` 全局可用：
+With a `<script>` tag, the `RouteForge` global becomes available:
 
 ```html
-<script src="https://unpkg.com/@route-forge/core"></script>
+<!-- production build (minified, ~19 KB / ~7 KB gzip) -->
+<script src="https://unpkg.com/@route-forge/core/dist/route-forge.global.min.js"></script>
 <script>
-  const forge = RouteForge.createRouteForge({
-    endpoint: '/_forge/routes',
-  })
-
-  // 等待就绪后绑定层级
-  forge.ready().then(function(f) {
+  const forge = RouteForge.createRouteForge({ endpoint: '/_forge/routes' })
+  forge.ready().then(function (f) {
     const admin = f.use('admin')
-    return admin.onLevelLoaded()
-  }).then(function(bound) {
-    return bound('users.show', { user: 1 })
-  }).then(function(data) {
+    return admin.onLevelLoaded().then(function () {
+      return admin('users.show', { user: 1 })
+    })
+  }).then(function (data) {
     console.log(data)
   })
 </script>
 ```
 
-### Auto-discovery 守卫
-
-`route()` / `hasRoute()` 在 auto-discovery 未完成且无 explicit levels 时抛出
-`ForgeError (RF_FE_010)`， 防止在路由数据未就绪时返回错误结果。`api()` 不受影响（内部自动 await
-discovery）。
-
-## 工具导出
+> Always reference the IIFE artifact under `dist/`; the bare unpkg package name resolves to the CJS entry, which browsers cannot execute directly.
 
-除 `createRouteForge` 外，core 包还导出以下工具件，供高级场景按需使用：
+## Error reference
 
-| 导出                        | 说明                                                                                   |
-|-----------------------------|----------------------------------------------------------------------------------------|
-| `createInterceptorManager`  | 创建拦截器管理器（`use`/`eject`/`clear`），供自定义 Fetcher 复用统一拦截器实现   |
-| `RouteCache`                | 按层级隔离的路由缓存类（memory / sessionStorage / localStorage，TTL 过期），可独立使用 |
-| `LoadingTracker`            | 加载状态跟踪器（引用计数 + 订阅），框架适配层可基于它实现全局加载指示                |
-| `resolveRouteName`          | 前缀歧义异步消解（`prefix.suffix` 优先，回退后缀本身），`api()` 调用路径使用      |
-| `resolveRouteNameSync`      | 前缀歧义同步消解（基于已加载缓存），`route()` / `url()` 调用路径使用              |
+All errors extend `ForgeError` and carry a stable `code` field (the `ForgeErrorCode` literal union), so you can branch on `code` (with exhaustive `switch` checking):
 
-## 错误参考
+| Error class | code | Trigger |
+|-------------|------|---------|
+| `UnknownRouteError` | `RF_FE_001` | route name not found in the loaded level |
+| `UnknownLevelError` | `RF_FE_002` | level not declared (frontend validation is always on) |
+| `MissingRouteParamError` | `RF_FE_003` | required path parameter missing (no backend default); also thrown when a path parameter receives an object |
+| `AdapterNotFoundError` | `RF_FE_005` | `adapter: 'axios'` but no usable host axios |
+| `InvalidInterceptorReturnError` | `RF_FE_006` | a request interceptor did not return a RequestConfig object |
+| `NetworkError` | `RF_FE_007` | network-layer failure (DNS, refused connection…); `cause` keeps the original error |
+| `HTTPError` | `RF_FE_008` | non-2xx HTTP response; `context.status` holds the status code |
+| `RequestAbortedError` | `RF_FE_009` | request cancelled via `abort()` / AbortSignal |
+| `ForgeError` (guard) | `RF_FE_010` | `route()` / `hasRoute()` called before auto-discovery completed |
 
-所有错误均为 `ForgeError` 子类，携带稳定的 `code` 字段，可按 `code` 分支处理：
-
-| 错误类                        | code        | 触发场景                                             |
-|-------------------------------|-------------|------------------------------------------------------|
-| `UnknownRouteError`         | `RF_FE_001` | 路由名不存在于已加载层级中                           |
-| `UnknownLevelError`         | `RF_FE_002` | 层级未在 levels 声明（前端校验始终开启）             |
-| `MissingRouteParamError`    | `RF_FE_003` | 必填路径参数缺失（无后端默认值）                     |
-| `AdapterNotFoundError`      | `RF_FE_005` | `adapter: 'axios'` 但宿主未安装/无有效 axios       |
-| `InvalidInterceptorReturnError` | `RF_FE_006` | 请求拦截器未返回 RequestConfig 对象               |
-| `NetworkError`              | `RF_FE_007` | 网络层失败（DNS、连接被拒等），`cause` 保留原始错误 |
-| `HTTPError`                 | `RF_FE_008` | HTTP 非 2xx，`context.status` 为状态码             |
-| `RequestAbortedError`       | `RF_FE_009` | 请求被 `abort()` / AbortSignal 取消               |
-| `ForgeError`（守卫）        | `RF_FE_010` | auto-discovery 未完成时调用 `route()`/`hasRoute()` |
-
-错误对象结构：
+Error object shape:
 
 ```ts
 {
-  code: 'RF_FE_008',          // 稳定错误码
-  route?: string,             // 关联路由名
-  level?: string,             // 关联层级
-  context?: Record<string, unknown>,  // 附加上下文（如 HTTP 状态码）
-  cause?: unknown,            // 原始底层错误
+  code: 'RF_FE_008',                     // stable error code
+  route?: string,                        // related route name
+  level?: string,                        // related level
+  context?: Record<string, unknown>,     // extra context (HTTP status, url, method…)
+  cause?: unknown,                       // original underlying error
 }
 ```
 
-## 文档
+## Utility exports
+
+Besides `createRouteForge`, the core package exports these building blocks for advanced scenarios:
+
+| Export | Description |
+|--------|-------------|
+| `createInterceptorManager` | creates an interceptor manager (`use`/`eject`/`clear`) so custom Fetchers can reuse the same interceptor implementation |
+| `RouteCache` | per-level isolated route cache (memory / sessionStorage / localStorage, TTL expiry); usable standalone |
+| `LoadingTracker` | loading-state tracker (reference counting + subscriptions) for building global loading indicators |
+| `resolveRouteName` | async prefix-ambiguity resolution (prefer `prefix.suffix`, fall back to suffix); used by the `api()` path |
+| `resolveRouteNameSync` | sync variant based on the loaded cache; used by the `route()` / `url()` path |
+
+Type exports: `RouteForge` / `RouteForgeOptions` / `BoundForge` / `ApiCallParams` / `RequestConfig` / `ResponseData` / `ForgeRequest` / `Fetcher` / `RouteMeta` / `SummaryResponse` / `ForgeRouteMap` / `ForgeErrorCode` and more (full list in `dist/index.d.ts`).
+
+## FAQ
+
+**`route()` / `hasRoute()` throw `RF_FE_010`?**
+Auto-discovery hasn't completed. `await forge.ready()` first, or use the framework packages' `useForgeRoute`, which handles the loading state internally (returns `''` until ready).
+
+**`ready()` rejected — what now?**
+The summary endpoint is unreachable and no explicit `levels` were provided. Either fix endpoint connectivity, or pass explicit `levels` to gain the degradation path (falls back to the explicit configuration when the summary fails).
+
+**Responses aren't unwrapped with `resp.data`?**
+Unwrapping is response-interceptor behavior — register `(resp) => resp.data` yourself; by default `api()` resolves with the final value of the interceptor chain over the full `ResponseData`.
+
+**Cache out of sync across browser tabs?**
+Storage modes (sessionStorage / localStorage) automatically invalidate the in-memory mirror when another tab writes, via `storage` events; `memory` mode is per-tab by design.
+
+## Documentation
 
-- 仓库主页: https://github.com/route-forge/route-forge
-- 设计文档: https://github.com/route-forge/route-forge/blob/main/.docs/DESIGN.md
-- 规范: https://github.com/route-forge/route-forge/blob/main/.docs/SPEC.md
+- Repository: <https://github.com/route-forge/route-forge>
+- Design notes: <https://github.com/route-forge/route-forge/blob/main/.docs/DESIGN.md>
+- Specification: <https://github.com/route-forge/route-forge/blob/main/.docs/SPEC.md>
+- Backend package (Laravel): <https://github.com/route-forge/route-forge-laravel>
 
 ## License