@ai-slot/runtime 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iannil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# @ai-slot/runtime
+
+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
+
+```bash
+npm install @ai-slot/runtime
+```
+
+## Usage
+
+```html
+<ai-slot name="hero" src="/ai-render/hero" editable stream live>
+  <h1>Original content — stays in the page as the fallback</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 });
+</script>
+```
+
+Element attributes: `src`, `name`, `renderer` (default `dom`), `editable`, `stream` (SSE skeleton → tree), `live` + `live-src` (invalidation push), `refresh-interval`.
+
+> Registration must happen synchronously in the same module graph that imports the runtime — custom element upgrade is synchronous.
+
+## Docs
+
+- [Root README](https://github.com/iannil/ai-slot-component#readme) — full attribute table and framework examples
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,78 @@
+import { Registry, ComponentNode } from '@ai-slot/registry';
+
+/** 全局配置：提供 registry 时，客户端在渲染前对 AI 输出再做一次校验（双保险）。 */
+declare function configureAiSlot(opts: {
+    registry?: Registry;
+}): void;
+/**
+ * <ai-slot> 自定义元素。渐进增强：内部永远先保留原始兜底内容，
+ * AI 结果就绪且校验通过后才替换；任何失败静默回退，不白屏、不报错给用户。
+ */
+declare class AiSlotElement extends HTMLElement {
+    protected fallbackHTML: string;
+    protected editor: HTMLElement | null;
+    private fallbackCaptured;
+    private timer;
+    private liveSub;
+    private loadSeq;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /** 拉取并渲染组件树；userPrompt 存在时走 POST 用户路径。失败时静默保留当前内容。 */
+    load(userPrompt?: string): Promise<void>;
+    /** live 属性：订阅失效推送，收到本槽位信号后静默重新加载。 */
+    protected mountLive(): void;
+    /** 恢复为挂载时的原始兜底内容。 */
+    restore(): void;
+    protected setContent(el: HTMLElement): void;
+    /** editable 的默认编辑条；样式通过 .ai-slot-editor 完全开放给用户自定义。 */
+    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;
+    /** 测试注入用 */
+    fetchImpl?: typeof fetch;
+}
+interface InvalidationSubscription {
+    close: () => void;
+}
+/**
+ * 订阅失效推送（fetch 流式读取 SSE）。任何失败静默——订阅是渐进增强，
+ * 断开即停止（v1.1 不做自动重连）。
+ */
+declare function subscribeInvalidation(opts: SubscribeInvalidationOptions): InvalidationSubscription;
+
+interface RenderContext {
+    /** 已渲染完成的默认槽位子元素 */
+    children: HTMLElement[];
+    /** 已渲染完成的命名槽位子元素，按槽位名分组 */
+    slots: Record<string, HTMLElement[]>;
+}
+/** 把单个组件树节点映射为真实元素；返回 null 表示跳过该节点。 */
+type Renderer = (node: ComponentNode, ctx: RenderContext) => HTMLElement | null | Promise<HTMLElement | null>;
+/** 注册渲染适配器，如 registerRenderer("dom", createDomRenderer(...))。渲染器必须与导入 runtime 的代码在同一 module graph 中同步注册（custom elements upgrade 是同步的，首个 load 只推迟到一个 microtask）。 */
+declare function registerRenderer(name: string, renderer: Renderer): void;
+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 };

package/dist/index.js

@@ -0,0 +1,265 @@
+// src/fetch-tree.ts
+import { validateComponentTree } from "@ai-slot/registry";
+async function fetchComponentTree(opts) {
+  const doFetch = opts.fetchImpl ?? fetch;
+  try {
+    const headers = {};
+    if (opts.stream) headers.accept = "text/event-stream";
+    const init = opts.userPrompt === void 0 ? opts.stream ? { headers } : void 0 : {
+      method: "POST",
+      headers: { "content-type": "application/json", ...opts.stream ? { accept: headers.accept } : {} },
+      body: JSON.stringify({ prompt: opts.userPrompt })
+    };
+    const res = await doFetch(opts.src, init);
+    if (!res.ok) 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 {
+    return null;
+  }
+}
+async function readSSE(res, opts) {
+  const text = (await readBody(res)).replace(/\r\n/g, "\n");
+  let finalTree = null;
+  for (const chunk of text.split("\n\n")) {
+    const event = chunk.match(/^event: (.+)$/m)?.[1];
+    const raw = chunk.match(/^data: (.+)$/m)?.[1];
+    if (!event || !raw) continue;
+    let data;
+    try {
+      data = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    if (event === "skeleton") {
+      if (data?.tree && !(opts.registry && !validateComponentTree(opts.registry, data.tree).ok)) {
+        try {
+          opts.onSkeleton?.(data.tree);
+        } catch {
+        }
+      }
+    } else if (event === "tree") {
+      finalTree = data?.tree ?? null;
+    }
+  }
+  if (finalTree === null) return null;
+  if (opts.registry && !validateComponentTree(opts.registry, finalTree).ok) return null;
+  return finalTree;
+}
+async function readBody(res) {
+  if (typeof res.text === "function") return res.text();
+  const reader = res.body?.getReader();
+  if (!reader) return "";
+  const decoder = new TextDecoder();
+  let text = "";
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    text += decoder.decode(value, { stream: true });
+  }
+  text += decoder.decode();
+  return text;
+}
+
+// src/live.ts
+function subscribeInvalidation(opts) {
+  const doFetch = opts.fetchImpl ?? fetch;
+  const controller = new AbortController();
+  let closed = false;
+  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 {
+          }
+        }
+      }
+    } catch {
+    }
+  })();
+  return {
+    close() {
+      closed = true;
+      controller.abort();
+    }
+  };
+}
+
+// src/renderer.ts
+var renderers = /* @__PURE__ */ new Map();
+function registerRenderer(name, renderer) {
+  renderers.set(name, renderer);
+}
+function getRenderer(name) {
+  return renderers.get(name);
+}
+async function renderTree(renderer, node) {
+  const children = [];
+  for (const child of node.children ?? []) {
+    const el = await renderTree(renderer, child);
+    if (el) children.push(el);
+  }
+  const slots = {};
+  for (const [name, nodes] of Object.entries(node.slots ?? {})) {
+    slots[name] = [];
+    for (const child of nodes) {
+      const el = await renderTree(renderer, child);
+      if (el) slots[name].push(el);
+    }
+  }
+  return renderer(node, { children, slots });
+}
+
+// src/ai-slot.ts
+var globalRegistry;
+function configureAiSlot(opts) {
+  globalRegistry = opts.registry;
+}
+var AiSlotElement = class extends HTMLElement {
+  fallbackHTML = "";
+  editor = null;
+  fallbackCaptured = false;
+  timer;
+  liveSub = null;
+  loadSeq = 0;
+  connectedCallback() {
+    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();
+    });
+  }
+  disconnectedCallback() {
+    clearInterval(this.timer);
+    this.liveSub?.close();
+    this.liveSub = null;
+  }
+  /** 拉取并渲染组件树；userPrompt 存在时走 POST 用户路径。失败时静默保留当前内容。 */
+  async load(userPrompt) {
+    const seq = ++this.loadSeq;
+    let finalApplied = false;
+    let skeletonApplied = false;
+    const src = this.getAttribute("src");
+    const renderer = getRenderer(this.getAttribute("renderer") ?? "dom");
+    if (!src || !renderer) return;
+    const tree = await fetchComponentTree({
+      src,
+      userPrompt,
+      registry: globalRegistry,
+      stream: this.hasAttribute("stream"),
+      onSkeleton: (skeleton) => {
+        if (seq !== this.loadSeq || finalApplied) return;
+        skeletonApplied = true;
+        void renderTree(renderer, skeleton).then((el) => {
+          if (el && !finalApplied && seq === this.loadSeq) this.setContent(el);
+        }).catch(() => {
+        });
+      }
+    });
+    if (!tree) {
+      if (skeletonApplied && seq === this.loadSeq) this.restore();
+      return;
+    }
+    try {
+      const el = await renderTree(renderer, tree);
+      if (!el) return;
+      if (seq !== this.loadSeq) return;
+      finalApplied = true;
+      this.setContent(el);
+    } catch {
+    }
+  }
+  /** live 属性：订阅失效推送，收到本槽位信号后静默重新加载。 */
+  mountLive() {
+    const src = this.getAttribute("live-src") ?? this.getAttribute("src")?.replace(/\/ai-render\/.*$/, "/ai-invalidate");
+    const slot = this.getAttribute("name");
+    if (!src || !slot || this.liveSub) return;
+    this.liveSub = subscribeInvalidation({
+      src,
+      slot,
+      onInvalidate: () => void this.load()
+    });
+  }
+  /** 恢复为挂载时的原始兜底内容。 */
+  restore() {
+    this.loadSeq += 1;
+    this.innerHTML = this.fallbackHTML;
+    if (this.editor) this.appendChild(this.editor);
+  }
+  setContent(el) {
+    this.replaceChildren(el);
+    if (this.editor) this.appendChild(this.editor);
+  }
+  /** editable 的默认编辑条；样式通过 .ai-slot-editor 完全开放给用户自定义。 */
+  mountEditor() {
+    if (this.editor) {
+      if (this.editor.parentNode !== this) this.appendChild(this.editor);
+      return;
+    }
+    const form = document.createElement("form");
+    form.className = "ai-slot-editor";
+    const input = document.createElement("input");
+    input.name = "prompt";
+    input.maxLength = 500;
+    input.placeholder = "\u7528\u4E00\u53E5\u8BDD\u8C03\u6574\u8FD9\u4E2A\u533A\u57DF\u2026";
+    const submit = document.createElement("button");
+    submit.type = "submit";
+    submit.textContent = "\u5E94\u7528";
+    const reset = document.createElement("button");
+    reset.type = "button";
+    reset.textContent = "\u6062\u590D\u9ED8\u8BA4";
+    form.append(input, submit, reset);
+    form.addEventListener("submit", (event) => {
+      event.preventDefault();
+      const value = input.value.trim();
+      if (value) void this.load(value);
+    });
+    reset.addEventListener("click", () => this.restore());
+    this.editor = form;
+    this.appendChild(form);
+  }
+};
+if (typeof customElements !== "undefined" && !customElements.get("ai-slot")) {
+  customElements.define("ai-slot", AiSlotElement);
+}
+export {
+  AiSlotElement,
+  configureAiSlot,
+  fetchComponentTree,
+  getRenderer,
+  registerRenderer,
+  renderTree,
+  subscribeInvalidation
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@ai-slot/runtime",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "Zero-dependency <ai-slot> Web Component runtime for AI-enhanced pages with guaranteed fallback.",
+  "keywords": [
+    "web-components",
+    "custom-elements",
+    "ai",
+    "llm",
+    "progressive-enhancement"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iannil/ai-slot-component.git",
+    "directory": "packages/runtime"
+  },
+  "bugs": "https://github.com/iannil/ai-slot-component/issues",
+  "homepage": "https://github.com/iannil/ai-slot-component/tree/master/packages/runtime#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@ai-slot/registry": "0.1.0"
+  },
+  "devDependencies": {
+    "jsdom": "^25.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}