@route-forge/vue 2.2.1 → 3.1.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as vue from 'vue';
-import { InjectionKey, Ref, Plugin, ComputedRef, VNode, SlotsType } from 'vue';
+import { InjectionKey, Plugin, Ref, ComputedRef, VNode, SlotsType } from 'vue';
 import { RouteForge, RouteForgeOptions, BoundForge, UseForgeApiBoundReturn, UseForgeApiReturn } from '@route-forge/core';
 export { UseForgeApiBoundCall, UseForgeApiCall } from '@route-forge/core';
 
@@ -8,28 +8,29 @@ export { UseForgeApiBoundCall, UseForgeApiCall } from '@route-forge/core';
  * @see .docs/SPEC.md §4.1.7
  *
  * 提供：
- *   - 全局属性 $forge（route() 工具）
- *   - inject symbol 注入 RouteForge 实例供 composable 使用
- *   - useForge() / useForge(level) / useForge(level, prefix) 返回统一方法的 forge 实例
- *     • 不传 level：forge(level, name, params?) 直接调用
- *     • 传 level：forge(name, params?) 直接调用，自动绑定层级
- *     • 传 level + prefix：forge(suffix, params?) 自动拼接 prefix
+ *   - createRouteForgePlugin：装配插件，install 时经 inject symbol 注入 RouteForge 实例
+ *   - 返回对象上的 interceptors（转发实例拦截器）：创建后即可同步注册，无需等待 ready()
  *
- * 类型推断：
- *   当 ForgeRouteMap 通过 codegen 或 module augmentation 定义时，
- *   level / name / params 均自动推断，IDE 提供补全提示。
+ * useForge / useForgeApi / useForgeRoute 等消费 composable 见 composables/ 下各文件。
+ *
+ * 注：v3.0.0 起不再注入 `$forge` 全局属性（残缺 facade，仅 route() 且未 ready 时抛错断渲染）；
+ * 模板内生成链接用 useForgeRoute / ForgeLink / ForgeRoute，命令式场景用 useForge()。
  */
 
 declare const FORGE_INJECTION_KEY: InjectionKey<RouteForge>;
 interface RouteForgePluginOptions extends RouteForgeOptions {
 }
-/** Vue 特化类型：levelLoaded 为 Ref<boolean> */
-type VueBoundForge = BoundForge<Ref<boolean>>;
-declare function createRouteForgePlugin(options?: RouteForgePluginOptions): Plugin<[]> & {
+declare function createRouteForgePlugin(forgeOrOptions?: RouteForge | RouteForgePluginOptions): Plugin<[]> & {
     ready: RouteForge['ready'];
+    /** 转发实例上的拦截器管理器：创建后即可同步注册，无需等待 ready()（请求/响应拦截链仅影响后续 api() 调用，eager 元信息预加载走 requestRaw 不受影响） */
+    interceptors: RouteForge['interceptors'];
 };
+
 /**
- * 获取 forge 实例。内部委托 core 的 forge.use()，仅将 levelLoaded 替换为 Vue 响应式 Ref。
+ * useForge — 获取 forge 实例（Vue 特化：levelLoaded 为 Ref<boolean>）
+ * @see .docs/SPEC.md §4.1.7
+ *
+ * 内部委托 core 的 forge.use()，仅将 levelLoaded 从 Promise<void> 替换为 Vue 响应式 Ref。
  *
  * @example
  * // 不绑定层级
@@ -51,6 +52,9 @@ declare function createRouteForgePlugin(options?: RouteForgePluginOptions): Plug
  * forge('show', { user: 1 })           // → forge.api('admin', 'users.show', ...)
  * forge.route('show', { user: 1 })     // → forge.route('admin', 'users.show', ...)
  */
+
+/** Vue 特化类型：levelLoaded 为 Ref<boolean> */
+type VueBoundForge = BoundForge<Ref<boolean>>;
 declare function useForge<L extends string>(level: L, prefix: string): VueBoundForge;
 declare function useForge<L extends string>(level: L): VueBoundForge;
 declare function useForge(): RouteForge;
@@ -115,6 +119,11 @@ declare const ForgeRoute: vue.DefineComponent<vue.ExtractPropTypes<{
         readonly required: false;
         readonly default: undefined;
     };
+    readonly as: {
+        readonly type: vue.PropType<object>;
+        readonly required: false;
+        readonly default: undefined;
+    };
 }>, () => VNode<vue.RendererNode, vue.RendererElement, {
     [key: string]: any;
 }>[] | null, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
@@ -131,14 +140,24 @@ declare const ForgeRoute: vue.DefineComponent<vue.ExtractPropTypes<{
         readonly required: false;
         readonly default: undefined;
     };
+    readonly as: {
+        readonly type: vue.PropType<object>;
+        readonly required: false;
+        readonly default: undefined;
+    };
 }>> & Readonly<{}>, {
     readonly params: Record<string, unknown> | (() => Record<string, unknown>);
+    readonly as: object;
 }, SlotsType<{
     default?: (props: {
         href: string;
         loaded: boolean;
     }) => VNode[];
     loading?: () => VNode[];
+    /** 解析失败（路由名不存在等）：props 携带错误对象；未传回落 loading 插槽 */
+    error?: (props: {
+        error: unknown;
+    }) => VNode[];
 }>, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
 type ForgeRouteProps = InstanceType<typeof ForgeRoute>['$props'];
 
@@ -156,6 +175,11 @@ declare const ForgeLink: vue.DefineComponent<vue.ExtractPropTypes<{
         readonly required: false;
         readonly default: undefined;
     };
+    readonly as: {
+        readonly type: vue.PropType<object>;
+        readonly required: false;
+        readonly default: undefined;
+    };
 }>, () => VNode<vue.RendererNode, vue.RendererElement, {
     [key: string]: any;
 }> | VNode<vue.RendererNode, vue.RendererElement, {
@@ -174,14 +198,34 @@ declare const ForgeLink: vue.DefineComponent<vue.ExtractPropTypes<{
         readonly required: false;
         readonly default: undefined;
     };
+    readonly as: {
+        readonly type: vue.PropType<object>;
+        readonly required: false;
+        readonly default: undefined;
+    };
 }>> & Readonly<{}>, {
     readonly params: Record<string, unknown> | (() => Record<string, unknown>);
+    readonly as: object;
 }, SlotsType<{
     /** 链接文本/内容 */
     default?: () => VNode[];
     /** 未加载占位 */
     loading?: () => VNode[];
+    /** 解析失败（路由名不存在等）：props 携带错误对象；未传回落 loading 插槽 */
+    error?: (props: {
+        error: unknown;
+    }) => VNode[];
 }>, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
 type ForgeLinkProps = InstanceType<typeof ForgeLink>['$props'];
 
-export { FORGE_INJECTION_KEY, ForgeLink, type ForgeLinkProps, ForgeRoute, type ForgeRouteDegradeHooks, type ForgeRouteProps, type RouteForgePluginOptions, type UseForgeApiBoundReturnVue, type UseForgeApiReturnVue, type VueBoundForge, createRouteForgePlugin, useForge, useForgeApi, useForgeRoute };
+declare const ForgeReady: vue.DefineComponent<{}, () => VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}>[] | null | undefined, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<{}> & Readonly<{}>, {}, SlotsType<{
+    /** ready 后渲染的内容 */
+    default?: () => VNode[];
+    /** 门闩期间的占位 UI（缺省不渲染任何内容） */
+    fallback?: () => VNode[];
+}>, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+type ForgeReadyProps = InstanceType<typeof ForgeReady>['$props'];
+
+export { FORGE_INJECTION_KEY, ForgeLink, type ForgeLinkProps, ForgeReady, type ForgeReadyProps, ForgeRoute, type ForgeRouteDegradeHooks, type ForgeRouteProps, type RouteForgePluginOptions, type UseForgeApiBoundReturnVue, type UseForgeApiReturnVue, type VueBoundForge, createRouteForgePlugin, useForge, useForgeApi, useForgeRoute };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as vue from 'vue';
-import { InjectionKey, Ref, Plugin, ComputedRef, VNode, SlotsType } from 'vue';
+import { InjectionKey, Plugin, Ref, ComputedRef, VNode, SlotsType } from 'vue';
 import { RouteForge, RouteForgeOptions, BoundForge, UseForgeApiBoundReturn, UseForgeApiReturn } from '@route-forge/core';
 export { UseForgeApiBoundCall, UseForgeApiCall } from '@route-forge/core';
 
@@ -8,28 +8,29 @@ export { UseForgeApiBoundCall, UseForgeApiCall } from '@route-forge/core';
  * @see .docs/SPEC.md §4.1.7
  *
  * 提供：
- *   - 全局属性 $forge（route() 工具）
- *   - inject symbol 注入 RouteForge 实例供 composable 使用
- *   - useForge() / useForge(level) / useForge(level, prefix) 返回统一方法的 forge 实例
- *     • 不传 level：forge(level, name, params?) 直接调用
- *     • 传 level：forge(name, params?) 直接调用，自动绑定层级
- *     • 传 level + prefix：forge(suffix, params?) 自动拼接 prefix
+ *   - createRouteForgePlugin：装配插件，install 时经 inject symbol 注入 RouteForge 实例
+ *   - 返回对象上的 interceptors（转发实例拦截器）：创建后即可同步注册，无需等待 ready()
  *
- * 类型推断：
- *   当 ForgeRouteMap 通过 codegen 或 module augmentation 定义时，
- *   level / name / params 均自动推断，IDE 提供补全提示。
+ * useForge / useForgeApi / useForgeRoute 等消费 composable 见 composables/ 下各文件。
+ *
+ * 注：v3.0.0 起不再注入 `$forge` 全局属性（残缺 facade，仅 route() 且未 ready 时抛错断渲染）；
+ * 模板内生成链接用 useForgeRoute / ForgeLink / ForgeRoute，命令式场景用 useForge()。
  */
 
 declare const FORGE_INJECTION_KEY: InjectionKey<RouteForge>;
 interface RouteForgePluginOptions extends RouteForgeOptions {
 }
-/** Vue 特化类型：levelLoaded 为 Ref<boolean> */
-type VueBoundForge = BoundForge<Ref<boolean>>;
-declare function createRouteForgePlugin(options?: RouteForgePluginOptions): Plugin<[]> & {
+declare function createRouteForgePlugin(forgeOrOptions?: RouteForge | RouteForgePluginOptions): Plugin<[]> & {
     ready: RouteForge['ready'];
+    /** 转发实例上的拦截器管理器：创建后即可同步注册，无需等待 ready()（请求/响应拦截链仅影响后续 api() 调用，eager 元信息预加载走 requestRaw 不受影响） */
+    interceptors: RouteForge['interceptors'];
 };
+
 /**
- * 获取 forge 实例。内部委托 core 的 forge.use()，仅将 levelLoaded 替换为 Vue 响应式 Ref。
+ * useForge — 获取 forge 实例（Vue 特化：levelLoaded 为 Ref<boolean>）
+ * @see .docs/SPEC.md §4.1.7
+ *
+ * 内部委托 core 的 forge.use()，仅将 levelLoaded 从 Promise<void> 替换为 Vue 响应式 Ref。
  *
  * @example
  * // 不绑定层级
@@ -51,6 +52,9 @@ declare function createRouteForgePlugin(options?: RouteForgePluginOptions): Plug
  * forge('show', { user: 1 })           // → forge.api('admin', 'users.show', ...)
  * forge.route('show', { user: 1 })     // → forge.route('admin', 'users.show', ...)
  */
+
+/** Vue 特化类型：levelLoaded 为 Ref<boolean> */
+type VueBoundForge = BoundForge<Ref<boolean>>;
 declare function useForge<L extends string>(level: L, prefix: string): VueBoundForge;
 declare function useForge<L extends string>(level: L): VueBoundForge;
 declare function useForge(): RouteForge;
@@ -115,6 +119,11 @@ declare const ForgeRoute: vue.DefineComponent<vue.ExtractPropTypes<{
         readonly required: false;
         readonly default: undefined;
     };
+    readonly as: {
+        readonly type: vue.PropType<object>;
+        readonly required: false;
+        readonly default: undefined;
+    };
 }>, () => VNode<vue.RendererNode, vue.RendererElement, {
     [key: string]: any;
 }>[] | null, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
@@ -131,14 +140,24 @@ declare const ForgeRoute: vue.DefineComponent<vue.ExtractPropTypes<{
         readonly required: false;
         readonly default: undefined;
     };
+    readonly as: {
+        readonly type: vue.PropType<object>;
+        readonly required: false;
+        readonly default: undefined;
+    };
 }>> & Readonly<{}>, {
     readonly params: Record<string, unknown> | (() => Record<string, unknown>);
+    readonly as: object;
 }, SlotsType<{
     default?: (props: {
         href: string;
         loaded: boolean;
     }) => VNode[];
     loading?: () => VNode[];
+    /** 解析失败（路由名不存在等）：props 携带错误对象；未传回落 loading 插槽 */
+    error?: (props: {
+        error: unknown;
+    }) => VNode[];
 }>, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
 type ForgeRouteProps = InstanceType<typeof ForgeRoute>['$props'];
 
@@ -156,6 +175,11 @@ declare const ForgeLink: vue.DefineComponent<vue.ExtractPropTypes<{
         readonly required: false;
         readonly default: undefined;
     };
+    readonly as: {
+        readonly type: vue.PropType<object>;
+        readonly required: false;
+        readonly default: undefined;
+    };
 }>, () => VNode<vue.RendererNode, vue.RendererElement, {
     [key: string]: any;
 }> | VNode<vue.RendererNode, vue.RendererElement, {
@@ -174,14 +198,34 @@ declare const ForgeLink: vue.DefineComponent<vue.ExtractPropTypes<{
         readonly required: false;
         readonly default: undefined;
     };
+    readonly as: {
+        readonly type: vue.PropType<object>;
+        readonly required: false;
+        readonly default: undefined;
+    };
 }>> & Readonly<{}>, {
     readonly params: Record<string, unknown> | (() => Record<string, unknown>);
+    readonly as: object;
 }, SlotsType<{
     /** 链接文本/内容 */
     default?: () => VNode[];
     /** 未加载占位 */
     loading?: () => VNode[];
+    /** 解析失败（路由名不存在等）：props 携带错误对象；未传回落 loading 插槽 */
+    error?: (props: {
+        error: unknown;
+    }) => VNode[];
 }>, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
 type ForgeLinkProps = InstanceType<typeof ForgeLink>['$props'];
 
-export { FORGE_INJECTION_KEY, ForgeLink, type ForgeLinkProps, ForgeRoute, type ForgeRouteDegradeHooks, type ForgeRouteProps, type RouteForgePluginOptions, type UseForgeApiBoundReturnVue, type UseForgeApiReturnVue, type VueBoundForge, createRouteForgePlugin, useForge, useForgeApi, useForgeRoute };
+declare const ForgeReady: vue.DefineComponent<{}, () => VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}>[] | null | undefined, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<{}> & Readonly<{}>, {}, SlotsType<{
+    /** ready 后渲染的内容 */
+    default?: () => VNode[];
+    /** 门闩期间的占位 UI（缺省不渲染任何内容） */
+    fallback?: () => VNode[];
+}>, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+type ForgeReadyProps = InstanceType<typeof ForgeReady>['$props'];
+
+export { FORGE_INJECTION_KEY, ForgeLink, type ForgeLinkProps, ForgeReady, type ForgeReadyProps, ForgeRoute, type ForgeRouteDegradeHooks, type ForgeRouteProps, type RouteForgePluginOptions, type UseForgeApiBoundReturnVue, type UseForgeApiReturnVue, type VueBoundForge, createRouteForgePlugin, useForge, useForgeApi, useForgeRoute };

package/dist/index.js

@@ -1,20 +1,21 @@
-import { defineComponent, inject, h, ref, onMounted, computed, getCurrentInstance } from 'vue';
 import { createRouteForge } from '@route-forge/core';
+import { defineComponent, h, ref, inject, onMounted, getCurrentScope, onScopeDispose, computed, watch, getCurrentInstance } from 'vue';
 
 // src/plugin.ts
 var FORGE_INJECTION_KEY = /* @__PURE__ */ Symbol("route-forge");
-function createRouteForgePlugin(options = {}) {
-  const forge = createRouteForge(options);
+function createRouteForgePlugin(forgeOrOptions = {}) {
+  const forge = isRouteForge(forgeOrOptions) ? forgeOrOptions : createRouteForge(forgeOrOptions);
   return {
     ready: forge.ready.bind(forge),
+    interceptors: forge.interceptors,
     install(app) {
       app.provide(FORGE_INJECTION_KEY, forge);
-      app.config.globalProperties.$forge = {
-        route: (level, name, params) => forge.route(level, name, params)
-      };
     }
   };
 }
+function isRouteForge(x) {
+  return typeof x === "object" && x !== null && typeof x.api === "function" && typeof x.ready === "function";
+}
 function useForge(level, prefix) {
   const forge = inject(FORGE_INJECTION_KEY);
   if (!forge) {
@@ -62,7 +63,40 @@ function useForgeApi(level, prefix) {
   }
   return { pending, error, call };
 }
-function warnRenderError(error) {
+function useInjectedForge(apiName) {
+  const forge = inject(FORGE_INJECTION_KEY);
+  if (!forge) {
+    throw new Error(
+      `[route-forge/vue] ${apiName} must be used inside an app with createRouteForgePlugin() installed`
+    );
+  }
+  return forge;
+}
+
+// src/degrade.ts
+var reportedKeys = /* @__PURE__ */ new Set();
+var renderWarnKeys = /* @__PURE__ */ new Set();
+function dedupeKey(component, error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return `${component}:${message}`;
+}
+function reportDegrade(component, error, enabled = true) {
+  if (!enabled) return;
+  const key = dedupeKey(component, error);
+  if (reportedKeys.has(key)) return;
+  reportedKeys.add(key);
+  console.error(
+    `%c[route-forge]%c ${component} \u8DEF\u7531\u89E3\u6790\u5931\u8D25\uFF08\u5DF2\u964D\u7EA7\u4E3A\u7A7A\u5B57\u7B26\u4E32\uFF0C\u6E32\u67D3\u672A\u4E2D\u65AD\uFF09`,
+    "color:#c0392b;font-weight:bold",
+    "color:inherit",
+    error
+  );
+}
+function reportRenderWarn(error, enabled) {
+  if (!enabled) return;
+  const key = `useForgeRoute:${error instanceof Error ? error.message : String(error)}`;
+  if (renderWarnKeys.has(key)) return;
+  renderWarnKeys.add(key);
   console.warn(
     "%c[route-forge]%c useForgeRoute \u6E32\u67D3\u671F\u9519\u8BEF\uFF08\u5DF2\u964D\u7EA7\u4E3A\u7A7A\u5B57\u7B26\u4E32\uFF0C\u6E32\u67D3\u672A\u4E2D\u65AD\uFF09",
     "color:#e67e22;font-weight:bold",
@@ -70,13 +104,18 @@ function warnRenderError(error) {
     error
   );
 }
+
+// src/composables/useForgeRoute.ts
 function useForgeRoute(level, name, params, hooks) {
+  return useForgeRouteState(level, name, params, hooks).href;
+}
+function useForgeRouteState(level, name, params, hooks) {
   if (typeof level !== "string") {
     throw new TypeError(
       "[route-forge/vue] useForgeRoute(): level must be a static string \u2014 getter form is not supported (levels are deterministic declarations; create another useForgeRoute call for another level)"
     );
   }
-  const forge = inject(FORGE_INJECTION_KEY);
+  const forge = useInjectedForge("useForgeRoute()");
   const lvl = level;
   const levelLoaded = ref(forge.isLoaded(lvl));
   if (!levelLoaded.value) {
@@ -87,17 +126,36 @@ function useForgeRoute(level, name, params, hooks) {
       });
     });
   }
-  return computed(() => {
-    if (!levelLoaded.value) return "";
+  const dataVersion = ref(0);
+  const unsubscribe = forge.onRoutesChange((changed) => {
+    if (changed === lvl) dataVersion.value++;
+  });
+  if (getCurrentScope()) onScopeDispose(unsubscribe);
+  const state = computed(() => {
+    if (!levelLoaded.value) return { href: "", error: null };
+    void dataVersion.value;
     const n = typeof name === "function" ? name() : name;
     const p = params ? params() : void 0;
     try {
-      return forge.route(lvl, n, p);
+      return { href: forge.route(lvl, n, p), error: null };
     } catch (e) {
-      (hooks?.onDegrade ?? warnRenderError)(e);
-      return "";
+      return { href: "", error: e };
     }
   });
+  watch(
+    () => state.value.error,
+    (err) => {
+      if (err == null) return;
+      if (hooks?.onDegrade) hooks.onDegrade(err);
+      else reportRenderWarn(err, forge.warnings);
+    },
+    { immediate: true }
+  );
+  return {
+    href: computed(() => state.value.href),
+    error: computed(() => state.value.error),
+    isLevelLoaded: computed(() => levelLoaded.value)
+  };
 }
 var forgeLinkProps = {
   /** 层级名：静态快照，setup 求值一次后固定，不支持中途切换 */
@@ -112,16 +170,18 @@ var forgeLinkProps = {
     type: [Object, Function],
     required: false,
     default: void 0
+  },
+  /**
+   * 手动注入链接组件（组件对象或标签名字符串），注入后同时收到 `href` 与 `to` 两个 prop
+   * （对齐 @route-forge/react 的 ForgeLink `as` 契约）。不传时按默认链路：
+   * 探测全局 RouterLink → 原生 `<a>`。用于 RouterLink 局部注册 / 非 vue-router 链接组件场景。
+   */
+  as: {
+    type: [Object, String, Function],
+    required: false,
+    default: void 0
   }
 };
-function reportDegrade(component, error) {
-  console.error(
-    `%c[route-forge]%c ${component} \u8DEF\u7531\u89E3\u6790\u5931\u8D25\uFF08\u5DF2\u964D\u7EA7\u4E3A\u7A7A\u5B57\u7B26\u4E32\uFF0C\u6E32\u67D3\u672A\u4E2D\u65AD\uFF09`,
-    "color:#c0392b;font-weight:bold",
-    "color:inherit",
-    error
-  );
-}
 function warnUnloadedOnce(component, level, warned) {
   if (warned.value) return;
   warned.value = true;
@@ -143,20 +203,23 @@ var ForgeRoute = defineComponent({
   props: forgeLinkProps,
   slots: Object,
   setup(props, { slots }) {
-    const forge = inject(FORGE_INJECTION_KEY);
+    const forge = useInjectedForge("ForgeRoute");
     const nameGetter = () => typeof props.name === "function" ? props.name() : props.name;
     const paramsGetter = () => typeof props.params === "function" ? props.params() : props.params;
-    const href = useForgeRoute(props.level, nameGetter, paramsGetter, {
-      onDegrade: (e) => reportDegrade("ForgeRoute", e)
+    const state = useForgeRouteState(props.level, nameGetter, paramsGetter, {
+      onDegrade: (e) => reportDegrade("ForgeRoute", e, forge.warnings)
     });
     const unloadWarned = { value: false };
     return () => {
-      const url = href.value;
+      const url = state.href.value;
       const loaded = url !== "";
       if (!loaded && !forge.isLoaded(props.level)) {
         warnUnloadedOnce("ForgeRoute", props.level, unloadWarned);
       }
-      if (!loaded) return slots.loading ? slots.loading() : null;
+      if (!state.isLevelLoaded.value) return slots.loading ? slots.loading() : null;
+      if (state.error.value != null) {
+        return slots.error ? slots.error({ error: state.error.value }) : slots.loading ? slots.loading() : null;
+      }
       return slots.default ? slots.default({ href: url, loaded }) : null;
     };
   }
@@ -168,22 +231,32 @@ var ForgeLink = defineComponent({
   props: forgeLinkProps,
   slots: Object,
   setup(props, { slots, attrs }) {
-    const forge = inject(FORGE_INJECTION_KEY);
+    const forge = useInjectedForge("ForgeLink");
     const nameGetter = () => typeof props.name === "function" ? props.name() : props.name;
     const paramsGetter = () => typeof props.params === "function" ? props.params() : props.params;
-    const href = useForgeRoute(props.level, nameGetter, paramsGetter, {
-      onDegrade: (e) => reportDegrade("ForgeLink", e)
+    const state = useForgeRouteState(props.level, nameGetter, paramsGetter, {
+      onDegrade: (e) => reportDegrade("ForgeLink", e, forge.warnings)
     });
     const unloadWarned = { value: false };
     const routerLink = resolveRouterLink();
     return () => {
-      const url = href.value;
+      const url = state.href.value;
       const loaded = url !== "";
       if (!loaded && !forge.isLoaded(props.level)) {
         warnUnloadedOnce("ForgeLink", props.level, unloadWarned);
       }
-      if (!loaded) return slots.loading ? slots.loading() : null;
+      if (!state.isLevelLoaded.value) return slots.loading ? slots.loading() : null;
+      if (state.error.value != null) {
+        return slots.error ? slots.error({ error: state.error.value }) : slots.loading ? slots.loading() : null;
+      }
       const children = slots.default ? slots.default() : void 0;
+      if (props.as) {
+        return h(
+          props.as,
+          { ...attrs, to: url, href: url },
+          { default: () => children }
+        );
+      }
       if (routerLink) {
         return h(
           routerLink,
@@ -195,7 +268,29 @@ var ForgeLink = defineComponent({
     };
   }
 });
+var ForgeReady = defineComponent({
+  name: "ForgeReady",
+  slots: Object,
+  setup(_, { slots }) {
+    const forge = useInjectedForge("ForgeReady");
+    const open = ref(forge.isReady());
+    if (!open.value) {
+      forge.ready().then(
+        () => {
+          open.value = true;
+        },
+        (err) => {
+          console.error(
+            "[route-forge] ForgeReady: ready() rejected \u2014 content stays gated (same as an unhandled ready().catch)",
+            err
+          );
+        }
+      );
+    }
+    return () => open.value ? slots.default?.() : slots.fallback ? slots.fallback() : null;
+  }
+});
 
-export { FORGE_INJECTION_KEY, ForgeLink, ForgeRoute, createRouteForgePlugin, useForge, useForgeApi, useForgeRoute };
+export { FORGE_INJECTION_KEY, ForgeLink, ForgeReady, ForgeRoute, createRouteForgePlugin, useForge, useForgeApi, useForgeRoute };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map