@ai-slot/runtime 0.1.2 → 0.2.1

package/README.md

@@ -1,5 +1,7 @@
 # @ai-slot/runtime
 
+**English** | [简体中文](https://github.com/iannil/ai-slot-component/blob/master/packages/runtime/README.zh-CN.md)
+
 Zero-dependency `<ai-slot>` Web Component runtime for [ai-slot-component](https://github.com/iannil/ai-slot-component#readme): wrap existing markup, fetch a validated component tree from the proxy, and render it through a registered adapter — with a guaranteed fallback to your original content.
 
 ## Install
@@ -24,7 +26,11 @@ npm install @ai-slot/runtime
 </script>
 ```
 
-Element attributes: `src`, `name`, `renderer` (default `dom`), `editable`, `stream` (SSE skeleton → tree), `live` + `live-src` (invalidation push), `refresh-interval`.
+Element attributes: `src`, `name`, `renderer` (default `dom`), `editable`, `stream` (SSE skeleton → tree), `live` + `live-src` (invalidation push), `refresh-interval`, `fresh-only`.
+
+When the element is disconnected, in-flight load results are ignored. Reconnecting the same instance triggers a content check. Every successful `live` connection also triggers a check, so the initial load and the connection check may read concurrently; the latest load determines what is displayed.
+
+`fresh-only` is an optional boundary for managed content, configured before mounting. First configure the registry with `configureAiSlot({ registry })`; the server must provide a trusted Unix millisecond deadline in `meta.expiresAt` of the validated final-tree response. Missing, invalid, or expired deadlines, and failed subsequent updates, restore the original fallback. The currently displayed tree also falls back when it expires. The runtime uses the visitor’s local clock and rechecks when the page becomes visible again. Background-tab timer throttling or an incorrect system clock may delay removal; immediate removal at the deadline millisecond cannot be guaranteed for every visitor. Ordinary slots retain their existing behavior and do not require expiry metadata. Like `live`, configure this attribute before mounting.
 
 Wire format APIs: `registerWireFormat(id, format)` / `unregisterWireFormat(id)` plug alternative wire formats into the fetch pipeline. Failures are observed via `onFailure` as `FetchFailure { stage: "http-non-ok" | "parse" | "validate" | "fetch-error", message }` — set it globally in `configureAiSlot` or per call on `fetchComponentTree`. The silent-fallback behavior never changes; the hook is observation only.
 

package/README.zh-CN.md

@@ -0,0 +1,45 @@
+# @ai-slot/runtime
+
+[English](https://github.com/iannil/ai-slot-component/blob/master/packages/runtime/README.md) | **简体中文**
+
+[ai-slot-component](https://github.com/iannil/ai-slot-component#readme) 的 `<ai-slot>` Web Component 运行时：包裹原有标记，从代理获取经过校验的组件树，再由已注册的适配器渲染；失败时回退到原始内容。
+
+## 安装
+
+```bash
+npm install @ai-slot/runtime
+```
+
+## 用法
+
+```html
+<ai-slot name="hero" src="/ai-render/hero" editable stream live>
+  <h1>原始内容，保留在页面中作为兜底</h1>
+</ai-slot>
+
+<script type="module">
+  import { configureAiSlot, registerRenderer } from "@ai-slot/runtime";
+  import { createDomRenderer } from "@ai-slot/adapter-dom";
+
+  registerRenderer("dom", createDomRenderer(components));
+  configureAiSlot({ registry, onFailure: (f) => console.debug(f) });
+</script>
+```
+
+元素属性：`src`、`name`、`renderer`（默认 `dom`）、`editable`、`stream`（SSE 骨架 → 终树）、`live` + `live-src`（失效推送）、`refresh-interval`、`fresh-only`。
+
+卸载元素时，在途的加载结果会被忽略；同一实例重新挂载后会重新核对内容。`live` 通道每次成功连接也会核对一次，因此初次挂载的加载与连接后的核对可能并发读取，由最新一次加载结果决定显示内容。
+
+`fresh-only` 是挂载前配置的可选管理内容边界：需先通过 `configureAiSlot({ registry })` 配置注册表，且服务端必须在通过校验的最终树响应 `meta.expiresAt` 中提供可信的 Unix 毫秒截止时间。缺失、非法、已过期或后续更新失败时，槽位恢复原始兜底；当前显示的树到期也会恢复。运行时使用访客本机时钟，并在页面重新可见时复核。后台标签页的定时器节流或错误的系统时钟可能延迟撤回，不能保证所有访客在截止毫秒立即消失。普通槽位保持原有行为，不要求期限元数据。属性和 `live` 一样应在挂载前配置。
+
+传输格式 API：`registerWireFormat(id, format)` / `unregisterWireFormat(id)` 可将其他传输格式接入请求流水线。通过 `onFailure` 观测失败，类型为 `FetchFailure { stage: "http-non-ok" | "parse" | "validate" | "fetch-error", message }`；可在 `configureAiSlot` 中全局配置，也可在每次 `fetchComponentTree` 调用中配置。该钩子仅用于观测，不改变静默回退行为。
+
+> 注册必须在导入 runtime 的同一个模块图中同步完成，因为自定义元素升级是同步的。
+
+## 文档
+
+- [项目介绍](https://github.com/iannil/ai-slot-component#readme) — 完整属性表和框架示例
+
+## 许可证
+
+MIT

package/dist/index.d.ts

@@ -1,8 +1,41 @@
 import { Registry, ComponentNode } from '@ai-slot/registry';
 
-/** 全局配置：提供 registry 时，客户端在渲染前对 AI 输出再做一次校验（双保险）。 */
+interface FetchTreeOptions {
+    src: string;
+    /** 存在时走 POST 用户路径 */
+    userPrompt?: string;
+    /** 提供时渲染前对 AI 输出再校验一次（双保险） */
+    registry?: Registry;
+    /** true 时请求 SSE 流式（Accept: text/event-stream） */
+    stream?: boolean;
+    /** SSE skeleton 帧回调（先于终树到达） */
+    onSkeleton?: (tree: ComponentNode) => void;
+    /** 可选失败观测：每个失败路径触发一次。回调异常被吞掉，绝不影响兜底。 */
+    onFailure?: (failure: FetchFailure) => void;
+    /** 最终树校验通过后报告服务端截止时间（Unix 毫秒）；缺失或非法时传 undefined。 */
+    onExpiration?: (expiresAt: number | undefined) => void;
+    /** 测试注入用 */
+    fetchImpl?: typeof fetch;
+}
+/** 失败观测事件：stage 标识失败阶段，message 为人读原因（英文短语，API 面向国际用户）。 */
+interface FetchFailure {
+    stage: "http-non-ok" | "parse" | "validate" | "fetch-error";
+    message: string;
+}
+/** 拉取并（可选）校验组件树。任何失败返回 null——调用方据此静默保留兜底内容。 */
+declare function fetchComponentTree(opts: FetchTreeOptions): Promise<ComponentNode | null>;
+
+/** editable 编辑条文案，可被 configureAiSlot 的 editorLabels 覆盖（默认中文）。 */
+interface EditorLabels {
+    placeholder: string;
+    submit: string;
+    reset: string;
+}
+/** 全局配置：registry 供渲染前二次校验；onFailure 为可选失败观测（load 时透传给 fetchComponentTree）；editorLabels 覆盖编辑条文案。 */
 declare function configureAiSlot(opts: {
     registry?: Registry;
+    onFailure?: (failure: FetchFailure) => void;
+    editorLabels?: Partial<EditorLabels>;
 }): void;
 /**
  * <ai-slot> 自定义元素。渐进增强：内部永远先保留原始兜底内容，
@@ -15,12 +48,20 @@ declare class AiSlotElement extends HTMLElement {
     private timer;
     private liveSub;
     private loadSeq;
+    private mountSeq;
+    private displayedExpiresAt;
+    private expirationTimer;
+    private readonly checkVisibleExpiration;
     connectedCallback(): void;
     disconnectedCallback(): void;
-    /** 拉取并渲染组件树；userPrompt 存在时走 POST 用户路径。失败时静默保留当前内容。 */
+    /** 拉取并渲染组件树；普通槽位失败时保留当前内容，fresh-only 失败时恢复兜底。 */
     load(userPrompt?: string): Promise<void>;
     /** live 属性：订阅失效推送，收到本槽位信号后静默重新加载。 */
     protected mountLive(): void;
+    /** 计时器绑定当前显示产物；长于浏览器上限的间隔分段复核。 */
+    private checkExpiration;
+    private clearExpirationTimer;
+    private clearExpiration;
     /** 恢复为挂载时的原始兜底内容。 */
     restore(): void;
     protected setContent(el: HTMLElement): void;
@@ -28,37 +69,21 @@ declare class AiSlotElement extends HTMLElement {
     protected mountEditor(): void;
 }
 
-interface FetchTreeOptions {
-    src: string;
-    /** 存在时走 POST 用户路径 */
-    userPrompt?: string;
-    /** 提供时渲染前对 AI 输出再校验一次（双保险） */
-    registry?: Registry;
-    /** true 时请求 SSE 流式（Accept: text/event-stream） */
-    stream?: boolean;
-    /** SSE skeleton 帧回调（先于终树到达） */
-    onSkeleton?: (tree: ComponentNode) => void;
-    /** 测试注入用 */
-    fetchImpl?: typeof fetch;
-}
-/** 拉取并（可选）校验组件树。任何失败返回 null——调用方据此静默保留兜底内容。 */
-declare function fetchComponentTree(opts: FetchTreeOptions): Promise<ComponentNode | null>;
-
 interface SubscribeInvalidationOptions {
     /** 通道地址，如 /ai-invalidate（slot 以查询参数附加） */
     src: string;
     slot: string;
     onInvalidate: () => void;
+    /** 每次成功建立连接时调用，供上层主动核对内容。 */
+    onConnect?: () => void;
     /** 测试注入用 */
     fetchImpl?: typeof fetch;
+    random?: () => number;
 }
 interface InvalidationSubscription {
     close: () => void;
 }
-/**
- * 订阅失效推送（fetch 流式读取 SSE）。任何失败静默——订阅是渐进增强，
- * 断开即停止（v1.1 不做自动重连）。
- */
+/** 订阅失效推送；断线、超时和异常均静默重连。 */
 declare function subscribeInvalidation(opts: SubscribeInvalidationOptions): InvalidationSubscription;
 
 interface RenderContext {
@@ -75,4 +100,24 @@ declare function getRenderer(name: string): Renderer | undefined;
 /** 递归渲染组件树：先渲染子节点与命名槽位，再交给 Renderer 组装当前节点。 */
 declare function renderTree(renderer: Renderer, node: ComponentNode): Promise<HTMLElement | null>;
 
-export { AiSlotElement, type FetchTreeOptions, type InvalidationSubscription, type RenderContext, type Renderer, type SubscribeInvalidationOptions, configureAiSlot, fetchComponentTree, getRenderer, registerRenderer, renderTree, subscribeInvalidation };
+/**
+ * 可插拔线格式：把非原生响应（如 A2UI messages）解析为内部组件树。
+ * detect 必须是纯函数且不得抛异常；parse 任何失败返回 null，调用方据此静默兜底。
+ */
+interface WireFormat {
+    detect(data: unknown): boolean;
+    parse(data: unknown): ComponentNode | null;
+}
+/** 注册线格式解析器（与 registerRenderer 对称）。同 id 后注册覆盖先注册；检测按注册顺序。 */
+declare function registerWireFormat(id: string, format: WireFormat): void;
+/** 注销线格式解析器。返回是否确实删除了条目（Map.delete 语义）。用于测试隔离与动态换装。 */
+declare function unregisterWireFormat(id: string): boolean;
+interface WireParseResult {
+    /** 有 wire format 的 detect 命中（命中后无论 parse 成败都不再走原生路径） */
+    matched: boolean;
+    tree: ComponentNode | null;
+}
+/** 供 fetch-tree 调用：按注册顺序探测。防御性容错——detect/parse 抛异常按「未命中/失败」处理。 */
+declare function parseWithWireFormats(data: unknown): WireParseResult;
+
+export { AiSlotElement, type EditorLabels, type FetchFailure, type FetchTreeOptions, type InvalidationSubscription, type RenderContext, type Renderer, type SubscribeInvalidationOptions, type WireFormat, type WireParseResult, configureAiSlot, fetchComponentTree, getRenderer, parseWithWireFormats, registerRenderer, registerWireFormat, renderTree, subscribeInvalidation, unregisterWireFormat };

package/dist/index.js

@@ -1,5 +1,47 @@
 // src/fetch-tree.ts
 import { validateComponentTree } from "@ai-slot/registry";
+
+// src/wire.ts
+var wireFormats = /* @__PURE__ */ new Map();
+function registerWireFormat(id, format) {
+  wireFormats.set(id, format);
+}
+function unregisterWireFormat(id) {
+  return wireFormats.delete(id);
+}
+function parseWithWireFormats(data) {
+  for (const format of wireFormats.values()) {
+    try {
+      if (!format.detect(data)) continue;
+    } catch {
+      continue;
+    }
+    try {
+      return { matched: true, tree: format.parse(data) };
+    } catch {
+      return { matched: true, tree: null };
+    }
+  }
+  return { matched: false, tree: null };
+}
+
+// src/fetch-tree.ts
+function safeReport(onFailure, failure) {
+  if (!onFailure) return;
+  try {
+    onFailure(failure);
+  } catch {
+  }
+}
+function reportExpiration(value, callback) {
+  try {
+    callback?.(typeof value === "number" && Number.isFinite(value) ? value : void 0);
+  } catch {
+  }
+}
+function validationFailure(result) {
+  return { stage: "validate", message: result.errors[0]?.message ?? "validation failed" };
+}
 async function fetchComponentTree(opts) {
   const doFetch = opts.fetchImpl ?? fetch;
   try {
@@ -11,20 +53,48 @@ async function fetchComponentTree(opts) {
       body: JSON.stringify({ prompt: opts.userPrompt })
     };
     const res = await doFetch(opts.src, init);
-    if (!res.ok) return null;
+    if (!res.ok) {
+      safeReport(opts.onFailure, { stage: "http-non-ok", message: `HTTP ${res.status}` });
+      return null;
+    }
     if (opts.stream && res.headers?.get("content-type")?.includes("text/event-stream")) {
       return await readSSE(res, opts);
     }
-    const data = await res.json();
-    if (opts.registry && !validateComponentTree(opts.registry, data?.tree).ok) return null;
-    return data?.tree ?? null;
-  } catch {
+    const { tree, failure, expiresAt } = extractTree(await res.json());
+    if (!tree) {
+      safeReport(opts.onFailure, failure ?? { stage: "parse", message: "empty response" });
+      return null;
+    }
+    if (opts.registry) {
+      const result = validateComponentTree(opts.registry, tree);
+      if (!result.ok) {
+        safeReport(opts.onFailure, validationFailure(result));
+        return null;
+      }
+    }
+    reportExpiration(opts.registry ? expiresAt : void 0, opts.onExpiration);
+    return tree;
+  } catch (error) {
+    safeReport(opts.onFailure, {
+      stage: "fetch-error",
+      message: error instanceof Error ? error.message : "unknown error"
+    });
     return null;
   }
 }
+function extractTree(data) {
+  const wire = parseWithWireFormats(data);
+  if (wire.matched) {
+    return wire.tree ? { tree: wire.tree } : { tree: null, failure: { stage: "parse", message: "wire format parse returned null" } };
+  }
+  const body = data;
+  return body?.tree ? { tree: body.tree, expiresAt: body.meta?.expiresAt } : { tree: null, failure: { stage: "parse", message: "response carried no component tree" } };
+}
 async function readSSE(res, opts) {
   const text = (await readBody(res)).replace(/\r\n/g, "\n");
   let finalTree = null;
+  let finalFailure;
+  let finalExpiresAt;
   for (const chunk of text.split("\n\n")) {
     const event = chunk.match(/^event: (.+)$/m)?.[1];
     const raw = chunk.match(/^data: (.+)$/m)?.[1];
@@ -36,18 +106,32 @@ async function readSSE(res, opts) {
       continue;
     }
     if (event === "skeleton") {
-      if (data?.tree && !(opts.registry && !validateComponentTree(opts.registry, data.tree).ok)) {
+      const skeleton = extractTree(data).tree;
+      if (skeleton && !(opts.registry && !validateComponentTree(opts.registry, skeleton).ok)) {
         try {
-          opts.onSkeleton?.(data.tree);
+          opts.onSkeleton?.(skeleton);
         } catch {
         }
       }
     } else if (event === "tree") {
-      finalTree = data?.tree ?? null;
+      const extracted = extractTree(data);
+      finalTree = extracted.tree;
+      finalFailure = extracted.failure;
+      finalExpiresAt = extracted.expiresAt;
+    }
+  }
+  if (finalTree === null) {
+    if (finalFailure) safeReport(opts.onFailure, finalFailure);
+    return null;
+  }
+  if (opts.registry) {
+    const result = validateComponentTree(opts.registry, finalTree);
+    if (!result.ok) {
+      safeReport(opts.onFailure, validationFailure(result));
+      return null;
     }
   }
-  if (finalTree === null) return null;
-  if (opts.registry && !validateComponentTree(opts.registry, finalTree).ok) return null;
+  reportExpiration(opts.registry ? finalExpiresAt : void 0, opts.onExpiration);
   return finalTree;
 }
 async function readBody(res) {
@@ -66,45 +150,120 @@ async function readBody(res) {
 }
 
 // src/live.ts
+function abortable(work, signal) {
+  return new Promise((resolve, reject) => {
+    const stop = () => reject(new Error("aborted"));
+    if (signal.aborted) {
+      stop();
+      return;
+    }
+    signal.addEventListener("abort", stop, { once: true });
+    work.then(
+      (value) => {
+        signal.removeEventListener("abort", stop);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener("abort", stop);
+        reject(error);
+      }
+    );
+  });
+}
+function retryDelay(failures, random) {
+  return Math.floor(Math.min(3e4, 1e3 * 2 ** Math.min(failures, 5)) * (0.5 + 0.5 * random()));
+}
+function consumeFrames(buffer, slot, notify) {
+  const frames = buffer.replace(/\r\n/g, "\n").split("\n\n");
+  const rest = frames.pop() ?? "";
+  for (const frame of frames) {
+    const event = frame.match(/^event: ?(.+)$/m)?.[1];
+    const raw = frame.split("\n").filter((line) => line.startsWith("data:")).map((line) => line.slice(5).replace(/^ /, "")).join("\n");
+    if (event !== "invalidate" || !raw) continue;
+    try {
+      if (JSON.parse(raw).slot === slot) notify();
+    } catch {
+    }
+  }
+  return rest;
+}
 function subscribeInvalidation(opts) {
   const doFetch = opts.fetchImpl ?? fetch;
-  const controller = new AbortController();
+  const random = opts.random ?? Math.random;
+  const url = `${opts.src}${opts.src.includes("?") ? "&" : "?"}slot=${encodeURIComponent(opts.slot)}`;
   let closed = false;
+  let failures = 0;
+  let currentController;
+  let currentReader;
+  let timer;
+  let wake;
+  const clearTimer = () => {
+    if (timer !== void 0) clearTimeout(timer);
+    timer = void 0;
+  };
   void (async () => {
-    try {
-      const res = await doFetch(`${opts.src}${opts.src.includes("?") ? "&" : "?"}slot=${encodeURIComponent(opts.slot)}`, {
-        headers: { accept: "text/event-stream" },
-        signal: controller.signal
-      });
-      if (!res.ok || !res.body) return;
-      const reader = res.body.getReader();
-      const decoder = new TextDecoder();
-      let buffer = "";
-      for (; ; ) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        buffer += decoder.decode(value, { stream: true });
-        buffer = buffer.replace(/\r\n/g, "\n");
-        const frames = buffer.split("\n\n");
-        buffer = frames.pop() ?? "";
-        for (const frame of frames) {
-          const event = frame.match(/^event: (.+)$/m)?.[1];
-          const raw = frame.match(/^data: (.+)$/m)?.[1];
-          if (event !== "invalidate" || !raw) continue;
-          try {
-            const data = JSON.parse(raw);
-            if (data.slot === opts.slot && !closed) opts.onInvalidate();
-          } catch {
-          }
+    while (!closed) {
+      const controller = new AbortController();
+      currentController = controller;
+      let connectedAt;
+      try {
+        timer = setTimeout(() => controller.abort(), 8e3);
+        const res = await abortable(doFetch(url, {
+          headers: { accept: "text/event-stream" },
+          signal: controller.signal
+        }), controller.signal);
+        clearTimer();
+        if (!res.ok || !res.body) throw new Error("invalid SSE response");
+        if (closed) break;
+        connectedAt = Date.now();
+        try {
+          opts.onConnect?.();
+        } catch {
+        }
+        const reader = res.body.getReader();
+        currentReader = reader;
+        const decoder = new TextDecoder();
+        let buffer = "";
+        for (; ; ) {
+          timer = setTimeout(() => controller.abort(), 6e4);
+          const { done, value } = await abortable(reader.read(), controller.signal);
+          clearTimer();
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+          if (buffer.length > 65536) throw new Error("SSE buffer exceeded");
+          buffer = consumeFrames(buffer, opts.slot, () => {
+            failures = 0;
+            if (!closed) opts.onInvalidate();
+          });
         }
+      } catch {
+      } finally {
+        clearTimer();
+        controller.abort();
+        if (currentReader) void currentReader.cancel().catch(() => {
+        });
+        currentReader = void 0;
+        currentController = void 0;
       }
-    } catch {
+      if (closed) break;
+      if (connectedAt !== void 0 && Date.now() - connectedAt >= 3e4) failures = 0;
+      await new Promise((resolve) => {
+        wake = resolve;
+        timer = setTimeout(resolve, retryDelay(failures++, random));
+      });
+      wake = void 0;
+      clearTimer();
     }
   })();
   return {
     close() {
+      if (closed) return;
       closed = true;
-      controller.abort();
+      clearTimer();
+      currentController?.abort();
+      if (currentReader) void currentReader.cancel().catch(() => {
+      });
+      wake?.();
     }
   };
 }
@@ -136,8 +295,17 @@ async function renderTree(renderer, node) {
 
 // src/ai-slot.ts
 var globalRegistry;
+var globalOnFailure;
+var defaultEditorLabels = {
+  placeholder: "\u7528\u4E00\u53E5\u8BDD\u8C03\u6574\u8FD9\u4E2A\u533A\u57DF\u2026",
+  submit: "\u5E94\u7528",
+  reset: "\u6062\u590D\u9ED8\u8BA4"
+};
+var globalEditorLabels = { ...defaultEditorLabels };
 function configureAiSlot(opts) {
   globalRegistry = opts.registry;
+  globalOnFailure = opts.onFailure;
+  globalEditorLabels = { ...defaultEditorLabels, ...opts.editorLabels };
 }
 var AiSlotElement = class extends HTMLElement {
   fallbackHTML = "";
@@ -146,59 +314,101 @@ var AiSlotElement = class extends HTMLElement {
   timer;
   liveSub = null;
   loadSeq = 0;
+  mountSeq = 0;
+  displayedExpiresAt;
+  expirationTimer;
+  checkVisibleExpiration = () => {
+    if (document.visibilityState === "visible") this.checkExpiration();
+  };
   connectedCallback() {
+    const mount = ++this.mountSeq;
+    if (this.hasAttribute("fresh-only")) {
+      document.addEventListener("visibilitychange", this.checkVisibleExpiration);
+      this.checkExpiration();
+    }
     if (!this.fallbackCaptured) {
       this.fallbackHTML = this.innerHTML;
       this.fallbackCaptured = true;
     }
-    if (this.hasAttribute("editable")) this.mountEditor();
     const intervalSec = Number(this.getAttribute("refresh-interval") ?? 0);
     if (intervalSec > 0) {
       this.timer = setInterval(() => void this.load(), intervalSec * 1e3);
     }
     queueMicrotask(() => {
-      if (this.isConnected) void this.load();
-      if (this.isConnected && this.hasAttribute("live")) this.mountLive();
+      if (!this.isConnected || mount !== this.mountSeq) return;
+      if (this.hasAttribute("editable")) this.mountEditor();
+      void this.load();
+      if (this.hasAttribute("live")) this.mountLive();
     });
   }
   disconnectedCallback() {
+    this.mountSeq++;
+    this.loadSeq++;
     clearInterval(this.timer);
     this.liveSub?.close();
     this.liveSub = null;
+    document.removeEventListener("visibilitychange", this.checkVisibleExpiration);
+    if (this.hasAttribute("fresh-only")) this.restore();
   }
-  /** 拉取并渲染组件树；userPrompt 存在时走 POST 用户路径。失败时静默保留当前内容。 */
+  /** 拉取并渲染组件树；普通槽位失败时保留当前内容，fresh-only 失败时恢复兜底。 */
   async load(userPrompt) {
     const seq = ++this.loadSeq;
+    const freshOnly = this.hasAttribute("fresh-only");
+    let expiresAt;
     let finalApplied = false;
     let skeletonApplied = false;
     const src = this.getAttribute("src");
     const renderer = getRenderer(this.getAttribute("renderer") ?? "dom");
-    if (!src || !renderer) return;
+    if (!src || !renderer) {
+      if (freshOnly && this.isConnected && seq === this.loadSeq) this.restore();
+      return;
+    }
     const tree = await fetchComponentTree({
       src,
       userPrompt,
       registry: globalRegistry,
+      onFailure: globalOnFailure,
       stream: this.hasAttribute("stream"),
+      onExpiration: (value) => {
+        expiresAt = value;
+      },
       onSkeleton: (skeleton) => {
-        if (seq !== this.loadSeq || finalApplied) return;
+        if (freshOnly || !this.isConnected || seq !== this.loadSeq || finalApplied) return;
         skeletonApplied = true;
         void renderTree(renderer, skeleton).then((el) => {
-          if (el && !finalApplied && seq === this.loadSeq) this.setContent(el);
+          if (el && this.isConnected && !finalApplied && seq === this.loadSeq) this.setContent(el);
         }).catch(() => {
         });
       }
     });
     if (!tree) {
-      if (skeletonApplied && seq === this.loadSeq) this.restore();
+      if ((freshOnly || skeletonApplied) && this.isConnected && seq === this.loadSeq) this.restore();
+      return;
+    }
+    if (freshOnly && (expiresAt === void 0 || expiresAt <= Date.now())) {
+      if (this.isConnected && seq === this.loadSeq) this.restore();
       return;
     }
     try {
       const el = await renderTree(renderer, tree);
-      if (!el) return;
-      if (seq !== this.loadSeq) return;
+      if (!this.isConnected || seq !== this.loadSeq) return;
+      if (freshOnly && (expiresAt === void 0 || expiresAt <= Date.now())) {
+        this.restore();
+        return;
+      }
+      if (!el) {
+        if (freshOnly) this.restore();
+        return;
+      }
       finalApplied = true;
       this.setContent(el);
+      if (freshOnly) {
+        this.clearExpiration();
+        this.displayedExpiresAt = expiresAt;
+        this.checkExpiration();
+      }
     } catch {
+      if (freshOnly && this.isConnected && seq === this.loadSeq) this.restore();
     }
   }
   /** live 属性：订阅失效推送，收到本槽位信号后静默重新加载。 */
@@ -209,11 +419,33 @@ var AiSlotElement = class extends HTMLElement {
     this.liveSub = subscribeInvalidation({
       src,
       slot,
-      onInvalidate: () => void this.load()
+      onInvalidate: () => void this.load(),
+      onConnect: () => void this.load()
     });
   }
+  /** 计时器绑定当前显示产物；长于浏览器上限的间隔分段复核。 */
+  checkExpiration() {
+    const deadline = this.displayedExpiresAt;
+    if (deadline === void 0 || !this.isConnected) return;
+    this.clearExpirationTimer();
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) {
+      this.restore();
+      return;
+    }
+    this.expirationTimer = setTimeout(() => this.checkExpiration(), Math.min(remaining, 2147483647));
+  }
+  clearExpirationTimer() {
+    if (this.expirationTimer !== void 0) clearTimeout(this.expirationTimer);
+    this.expirationTimer = void 0;
+  }
+  clearExpiration() {
+    this.clearExpirationTimer();
+    this.displayedExpiresAt = void 0;
+  }
   /** 恢复为挂载时的原始兜底内容。 */
   restore() {
+    this.clearExpiration();
     this.loadSeq += 1;
     this.innerHTML = this.fallbackHTML;
     if (this.editor) this.appendChild(this.editor);
@@ -233,13 +465,13 @@ var AiSlotElement = class extends HTMLElement {
     const input = document.createElement("input");
     input.name = "prompt";
     input.maxLength = 500;
-    input.placeholder = "\u7528\u4E00\u53E5\u8BDD\u8C03\u6574\u8FD9\u4E2A\u533A\u57DF\u2026";
+    input.placeholder = globalEditorLabels.placeholder;
     const submit = document.createElement("button");
     submit.type = "submit";
-    submit.textContent = "\u5E94\u7528";
+    submit.textContent = globalEditorLabels.submit;
     const reset = document.createElement("button");
     reset.type = "button";
-    reset.textContent = "\u6062\u590D\u9ED8\u8BA4";
+    reset.textContent = globalEditorLabels.reset;
     form.append(input, submit, reset);
     form.addEventListener("submit", (event) => {
       event.preventDefault();
@@ -259,7 +491,10 @@ export {
   configureAiSlot,
   fetchComponentTree,
   getRenderer,
+  parseWithWireFormats,
   registerRenderer,
+  registerWireFormat,
   renderTree,
-  subscribeInvalidation
+  subscribeInvalidation,
+  unregisterWireFormat
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-slot/runtime",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "license": "MIT",
   "description": "Zero-dependency <ai-slot> Web Component runtime for AI-enhanced pages with guaranteed fallback.",
   "keywords": [
@@ -32,7 +32,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@ai-slot/registry": "0.1.0"
+    "@ai-slot/registry": "0.1.2"
   },
   "devDependencies": {
     "jsdom": "^25.0.0",
@@ -40,6 +40,9 @@
     "typescript": "^5.6.0",
     "vitest": "^2.1.0"
   },
+  "engines": {
+    "node": ">=18"
+  },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --clean",
     "test": "vitest run",