@icen.ai/ui 0.8.0 → 0.9.0

package/dist/behaviors/kb-passage.mjs

@@ -0,0 +1,529 @@
+// src/behaviors/ai-core.ts
+var svg = (body) => `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${body}</svg>`;
+var ICON_TERMINAL = svg('<path d="m4 17 6-6-6-6"/><path d="M12 19h8"/>');
+var ICON_FILE = svg(
+  '<path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7z"/><path d="M14 2v4a2 2 0 0 0 2 2h4"/>'
+);
+var ICON_FILE_PEN = svg(
+  '<path d="M12.5 22H6a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h8l5 5v3.5"/><path d="M14 2v4a2 2 0 0 0 2 2h4"/><path d="M19 6.5 16.5 4"/><path d="M21.378 16.626a1 1 0 0 0-3.004-3.004l-4.01 4.012a2 2 0 0 0-.506.854l-.837 2.87a.5.5 0 0 0 .62.62l2.87-.837a2 2 0 0 0 .854-.506z"/>'
+);
+var ICON_FILE_PLUS = svg(
+  '<path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7z"/><path d="M14 2v4a2 2 0 0 0 2 2h4"/><path d="M9 15h6"/><path d="M12 12v6"/>'
+);
+var ICON_TRASH = svg(
+  '<path d="M3 6h18"/><path d="M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6"/><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/><path d="M10 11v6"/><path d="M14 11v6"/>'
+);
+var ICON_SEARCH = svg('<circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/>');
+var ICON_FOLDER_SEARCH = svg(
+  '<path d="M11 20H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h3.9a2 2 0 0 1 1.69.9l.81 1.2a2 2 0 0 0 1.67.9H20a2 2 0 0 1 2 2v4"/><circle cx="17" cy="17" r="3"/><path d="m21 21-1.9-1.9"/>'
+);
+var ICON_SCAN_SEARCH = svg(
+  '<path d="M3 7V5a2 2 0 0 1 2-2h2"/><path d="M17 3h2a2 2 0 0 1 2 2v2"/><path d="M21 17v2a2 2 0 0 1-2 2h-2"/><path d="M7 21H5a2 2 0 0 1-2-2v-2"/><circle cx="12" cy="12" r="3"/><path d="m16 16-1.9-1.9"/>'
+);
+var ICON_GLOBE = svg(
+  '<circle cx="12" cy="12" r="10"/><path d="M12 2a14.5 14.5 0 0 0 0 20 14.5 14.5 0 0 0 0-20"/><path d="M2 12h20"/>'
+);
+var ICON_DOWNLOAD = svg(
+  '<path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><path d="m7 10 5 5 5-5"/><path d="M12 15V3"/>'
+);
+var ICON_BLOCKS = svg(
+  '<rect width="7" height="7" x="4" y="4" rx="1"/><rect width="7" height="7" x="13" y="4" rx="1"/><rect width="7" height="7" x="4" y="13" rx="1"/><rect width="7" height="7" x="13" y="13" rx="1"/>'
+);
+var ICON_ZAP = svg(
+  '<path d="M4 14a1 1 0 0 1-.78-1.63l9.9-10.2a.5.5 0 0 1 .86.46l-1.92 6.02A1 1 0 0 0 13 10h7a1 1 0 0 1 .78 1.63l-9.9 10.2a.5.5 0 0 1-.86-.46l1.92-6.02A1 1 0 0 0 11 14z"/>'
+);
+var ICON_LIST = svg(
+  '<path d="M3 12h.01"/><path d="M3 18h.01"/><path d="M3 6h.01"/><path d="M8 12h13"/><path d="M8 18h13"/><path d="M8 6h13"/>'
+);
+var ICON_LIST_CHECKS = svg(
+  '<path d="m3 17 2 2 4-4"/><path d="m3 7 2 2 4-4"/><path d="M13 6h8"/><path d="M13 12h8"/><path d="M13 18h8"/>'
+);
+var ICON_BOT = svg(
+  '<path d="M12 8V4H8"/><rect width="16" height="12" x="4" y="8" rx="2"/><path d="M2 14h2"/><path d="M20 14h2"/><path d="M15 13v2"/><path d="M9 13v2"/>'
+);
+var ICON_CHART = svg(
+  '<path d="M3 3v18h18"/><path d="M7 15l4-6 3 4 5-8"/>'
+);
+var ICON_FILE_TEXT = svg(
+  '<path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7z"/><path d="M14 2v4a2 2 0 0 0 2 2h4"/><path d="M10 9H8"/><path d="M16 13H8"/><path d="M16 17H8"/>'
+);
+function isObj(v) {
+  return typeof v === "object" && v !== null;
+}
+function pickStr(input, keys) {
+  if (!isObj(input)) return void 0;
+  for (const k of keys) {
+    const v = input[k];
+    if (typeof v === "string" && v) return v;
+  }
+  return void 0;
+}
+function pickNum(src, keys) {
+  if (!isObj(src)) return void 0;
+  for (const k of keys) {
+    const v = src[k];
+    if (typeof v === "number" && Number.isFinite(v)) return v;
+  }
+  return void 0;
+}
+function firstLine(s, max = 80) {
+  const line = s.split("\n", 1)[0]?.trim() ?? "";
+  return line.length > max ? `${line.slice(0, max)}\u2026` : line;
+}
+function filePathOf(input) {
+  return pickStr(input, ["file_path", "path", "file", "filename"]);
+}
+var summarizePath = (input) => filePathOf(input);
+function summarizeRead(input) {
+  const p = filePathOf(input);
+  if (!p) return void 0;
+  const offset = pickNum(input, ["offset", "start_line"]);
+  if (offset == null) return p;
+  const limit = pickNum(input, ["limit", "end_line"]);
+  return limit != null ? `${p}:${offset}-${offset + limit}` : `${p}:${offset}`;
+}
+function summarizeShell(input) {
+  const cmd = typeof input === "string" ? input : pickStr(input, ["command", "cmd", "script"]);
+  return cmd ? firstLine(cmd) : void 0;
+}
+function summarizeGrep(input) {
+  const pattern = pickStr(input, ["pattern", "regex", "query"]);
+  const p = filePathOf(input);
+  if (pattern) return p ? `${firstLine(pattern, 40)} \xB7 ${p}` : firstLine(pattern);
+  return p;
+}
+var sum = (fn) => {
+  return (input) => fn(input) ?? "";
+};
+var BUILTIN_KINDS = {
+  shell: { label: "\u547D\u4EE4", icon: ICON_TERMINAL, tint: "accent", summarize: sum(summarizeShell) },
+  read: { label: "\u8BFB\u53D6", icon: ICON_FILE, tint: "info", summarize: sum(summarizeRead) },
+  edit: { label: "\u7F16\u8F91", icon: ICON_FILE_PEN, tint: "warning", summarize: sum(summarizePath) },
+  write: { label: "\u5199\u5165", icon: ICON_FILE_PLUS, tint: "warning", summarize: sum(summarizePath) },
+  rm: { label: "\u5220\u9664", icon: ICON_TRASH, tint: "error", summarize: sum(summarizePath) },
+  grep: { label: "\u641C\u7D22", icon: ICON_SEARCH, tint: "info", summarize: sum(summarizeGrep) },
+  glob: { label: "\u5339\u914D", icon: ICON_FOLDER_SEARCH, tint: "info", summarize: sum((i) => pickStr(i, ["pattern", "glob", "path"])) },
+  browser: { label: "\u6D4F\u89C8", icon: ICON_GLOBE, tint: "accent", summarize: sum((i) => pickStr(i, ["url", "uri", "target"])) },
+  search: { label: "\u68C0\u7D22", icon: ICON_SCAN_SEARCH, tint: "accent", summarize: sum((i) => pickStr(i, ["query", "q", "pattern"])) },
+  fetch: { label: "\u8BF7\u6C42", icon: ICON_DOWNLOAD, tint: "info", summarize: sum((i) => pickStr(i, ["url", "uri", "endpoint"])) },
+  mcp: { label: "MCP", icon: ICON_BLOCKS, tint: "muted", summarize: sum((i) => pickStr(i, ["tool", "method", "name"])) },
+  skill: { label: "\u6280\u80FD", icon: ICON_ZAP, tint: "accent", summarize: sum((i) => pickStr(i, ["skill", "name", "command"])) },
+  todo: {
+    label: "\u5F85\u529E",
+    icon: ICON_LIST,
+    tint: "info",
+    summarize: sum((input) => {
+      const items = input && typeof input === "object" && Array.isArray(input.items) ? input.items : Array.isArray(input) ? input : [];
+      const done = items.filter((it) => it?.status === "done").length;
+      return items.length > 0 ? `${done}/${items.length} \u5B8C\u6210` : "";
+    })
+  },
+  plan: { label: "\u8BA1\u5212", icon: ICON_LIST_CHECKS, tint: "info" },
+  subagent: { label: "\u5B50\u4EE3\u7406", icon: ICON_BOT, tint: "accent", summarize: sum((i) => pickStr(i, ["task", "description", "prompt", "message", "subagent_type"])) },
+  note: { label: "\u7B14\u8BB0", icon: ICON_FILE_TEXT, tint: "muted" },
+  chart: { label: "\u56FE\u8868", icon: ICON_CHART, tint: "info", summarize: sum((i) => pickStr(i, ["title", "name"])) }
+};
+var kindRegistry = new Map(Object.entries(BUILTIN_KINDS));
+function h(tag, className, text) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text != null) node.textContent = text;
+  return node;
+}
+function svgIcon(svg2) {
+  if (typeof document === "undefined" || typeof DOMParser === "undefined") return null;
+  let parsed;
+  try {
+    parsed = new DOMParser().parseFromString(svg2, "image/svg+xml");
+  } catch {
+    return null;
+  }
+  const root = parsed.documentElement;
+  if (!root || root.tagName.toLowerCase() !== "svg" || parsed.querySelector("parsererror")) {
+    return null;
+  }
+  const sanitize = (el) => {
+    for (const attr of Array.from(el.attributes)) {
+      const name = attr.name.toLowerCase();
+      if (name.startsWith("on")) el.removeAttribute(attr.name);
+      if ((name === "href" || name === "xlink:href") && attr.value.trim().toLowerCase().startsWith("javascript:")) {
+        el.removeAttribute(attr.name);
+      }
+    }
+    for (const child of Array.from(el.children)) {
+      const tag = child.tagName.toLowerCase();
+      if (tag === "script" || tag === "foreignobject") {
+        child.remove();
+        continue;
+      }
+      sanitize(child);
+    }
+  };
+  sanitize(root);
+  return document.importNode(root, true);
+}
+
+// src/behaviors/kb-core.ts
+var ic = (label, d) => ({ label, icon: `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">${d}</svg>` });
+var BUILTIN_SOURCE_TYPES = {
+  doc: ic("\u6587\u6863", '<path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><path d="M14 2v6h6"/>'),
+  web: ic("\u7F51\u9875", '<circle cx="12" cy="12" r="10"/><path d="M2 12h20"/><path d="M12 2a15 15 0 0 1 0 20 15 15 0 0 1 0-20z"/>'),
+  wiki: ic("\u77E5\u8BC6\u5E93", '<path d="M4 19.5A2.5 2.5 0 0 1 6.5 17H20"/><path d="M6.5 2H20v20H6.5A2.5 2.5 0 0 1 4 19.5v-15A2.5 2.5 0 0 1 6.5 2z"/>'),
+  sheet: ic("\u8868\u683C", '<rect x="3" y="3" width="18" height="18" rx="2"/><path d="M3 9h18M3 15h18M9 3v18M15 3v18"/>'),
+  db: ic("\u6570\u636E\u5E93", '<ellipse cx="12" cy="5" rx="9" ry="3"/><path d="M3 5v14c0 1.7 4 3 9 3s9-1.3 9-3V5"/><path d="M3 12c0 1.7 4 3 9 3s9-1.3 9-3"/>'),
+  ticket: ic("\u5DE5\u5355", '<path d="M3 9V7a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2v2a2 2 0 0 0 0 6v2a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-2a2 2 0 0 0 0-6z"/><path d="M13 5v14"/>'),
+  code: ic("\u4EE3\u7801", '<path d="m16 18 6-6-6-6"/><path d="m8 6-6 6 6 6"/>'),
+  api: ic("\u63A5\u53E3", '<path d="M4 7a2 2 0 0 1 2-2h12a2 2 0 0 1 2 2v3a2 2 0 0 0 0 4v3a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2v-3a2 2 0 0 0 0-4z"/>'),
+  image: ic("\u56FE\u7247", '<rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="9" cy="9" r="2"/><path d="m21 15-4.6-4.6a2 2 0 0 0-2.8 0L3 21"/>'),
+  mail: ic("\u90AE\u4EF6", '<rect x="2" y="4" width="20" height="16" rx="2"/><path d="m22 7-10 7L2 7"/>')
+};
+var sourceTypeRegistry = new Map(Object.entries(BUILTIN_SOURCE_TYPES));
+function getKbSourceType(name) {
+  if (name) return sourceTypeRegistry.get(name) ?? BUILTIN_SOURCE_TYPES.doc;
+  return BUILTIN_SOURCE_TYPES.doc;
+}
+function normalizeCitation(raw) {
+  const r = raw;
+  const score = typeof r.score === "number" && Number.isFinite(r.score) ? r.score : r.score == null ? null : null;
+  return {
+    id: String(r.id ?? ""),
+    index: typeof r.index === "number" ? r.index : void 0,
+    title: String(r.title ?? "\u672A\u547D\u540D\u6765\u6E90"),
+    url: typeof r.url === "string" && r.url ? r.url : void 0,
+    kind: typeof r.kind === "string" ? r.kind : void 0,
+    citedText: typeof r.citedText === "string" ? r.citedText : void 0,
+    snippet: typeof r.snippet === "string" ? r.snippet : void 0,
+    date: typeof r.date === "string" ? r.date : void 0,
+    score: score === void 0 ? null : score,
+    scoreKind: r.scoreKind,
+    official: r.official === true,
+    permission: r.permission === "restricted" || r.permission === "requestable" ? r.permission : "readable",
+    owner: typeof r.owner === "string" ? r.owner : void 0,
+    loc: r.loc,
+    documentId: typeof r.documentId === "string" ? r.documentId : void 0,
+    useCount: typeof r.useCount === "number" ? r.useCount : void 0
+  };
+}
+
+// src/behaviors/events.ts
+function emitIcen(source, type, detail) {
+  return source.dispatchEvent(
+    new CustomEvent(type, { detail, bubbles: true, composed: true, cancelable: true })
+  );
+}
+
+// src/behaviors/kb-citation.ts
+var KB_ICON_LOCK = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><rect width="18" height="11" x="3" y="11" rx="2"/><path d="M7 11V7a5 5 0 0 1 10 0v4"/></svg>';
+
+// src/behaviors/kb-passage.ts
+var CLOSE_FALLBACK_MS = 240;
+function locLabel(loc) {
+  if (!loc) return "";
+  if (loc.kind === "page") {
+    return loc.start === loc.end ? `\u7B2C ${loc.start} \u9875` : `\u7B2C ${loc.start}\u2013${loc.end} \u9875`;
+  }
+  if (loc.kind === "block") return `\u5757 ${loc.start}\u2013${loc.end}`;
+  const unit = loc.unit === "byte" ? "\u5B57\u8282" : "\u5B57\u7B26";
+  return `${unit} ${loc.start}\u2013${loc.end}`;
+}
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function isPromiseLike(v) {
+  return !!v && typeof v.then === "function";
+}
+function createKbPassage(el, opts) {
+  if (typeof document === "undefined") {
+    const noop = () => void 0;
+    return { open: noop, close: noop, highlight: noop, expand: noop, destroy: noop };
+  }
+  const o = opts ?? {};
+  el.textContent = "";
+  const aside = h("aside", "kb-passage");
+  aside.hidden = true;
+  aside.setAttribute("role", "dialog");
+  aside.setAttribute("aria-modal", "false");
+  aside.setAttribute("aria-label", "\u539F\u6587\u5B9A\u4F4D");
+  const head = h("div", "kb-passage-head");
+  const headIcon = h("span", "kb-passage-icon");
+  const headSvg = svgIcon(getKbSourceType(void 0).icon);
+  if (headSvg) headIcon.appendChild(headSvg);
+  head.appendChild(headIcon);
+  const titleWrap = h("span", "kb-passage-titlewrap");
+  const titleEl = h("span", "kb-passage-title");
+  const locEl = h("span", "kb-passage-loc");
+  titleWrap.appendChild(titleEl);
+  titleWrap.appendChild(locEl);
+  head.appendChild(titleWrap);
+  const closeBtn = h("button", "kb-passage-close", "\xD7");
+  closeBtn.type = "button";
+  closeBtn.dataset.kbPassageClose = "";
+  closeBtn.setAttribute("aria-label", "\u5173\u95ED\u539F\u6587");
+  head.appendChild(closeBtn);
+  aside.appendChild(head);
+  const body = h("div", "kb-passage-body");
+  const ctxBefore = h("div", "kb-passage-context is-before");
+  ctxBefore.hidden = true;
+  const textEl = h("div", "kb-passage-text");
+  const ctxAfter = h("div", "kb-passage-context is-after");
+  ctxAfter.hidden = true;
+  const expandBtn = h("button", "kb-passage-expand", "\u5C55\u5F00\u4E0A\u4E0B\u6587");
+  expandBtn.type = "button";
+  expandBtn.dataset.kbPassageExpand = "";
+  expandBtn.hidden = true;
+  body.appendChild(ctxBefore);
+  body.appendChild(textEl);
+  body.appendChild(ctxAfter);
+  body.appendChild(expandBtn);
+  aside.appendChild(body);
+  el.appendChild(aside);
+  let destroyed = false;
+  let openToken = 0;
+  let current = null;
+  let plainText = "";
+  let pendingTerms = null;
+  let lastFocus = null;
+  let lastLocLabel = "";
+  function renderPlainText() {
+    textEl.textContent = plainText;
+    if (pendingTerms && pendingTerms.length) {
+      applyHighlight(pendingTerms);
+    }
+  }
+  function applyHighlight(terms) {
+    textEl.textContent = "";
+    if (!terms.length || !plainText) {
+      textEl.textContent = plainText;
+      return;
+    }
+    const sorted = terms.map((t, i) => ({ re: escapeRe(t), i })).sort((a, b) => b.re.length - a.re.length);
+    const re = new RegExp(`(${sorted.map((s) => s.re).join(")|(")})`, "gi");
+    let last = 0;
+    let m;
+    while ((m = re.exec(plainText)) !== null) {
+      if (m.index > last) textEl.appendChild(document.createTextNode(plainText.slice(last, m.index)));
+      let hit = 0;
+      for (let g = 1; g <= sorted.length; g++) {
+        if (m[g] !== void 0) {
+          hit = sorted[g - 1].i % 3;
+          break;
+        }
+      }
+      const mark = h("mark", "kb-passage-hit", m[0]);
+      mark.dataset.hit = String(hit);
+      textEl.appendChild(mark);
+      last = m.index + m[0].length;
+      if (m[0].length === 0) re.lastIndex++;
+    }
+    if (last < plainText.length) textEl.appendChild(document.createTextNode(plainText.slice(last)));
+  }
+  function fillBody(citation, resolved) {
+    const restricted = citation.permission !== "readable";
+    textEl.textContent = "";
+    ctxBefore.textContent = "";
+    ctxAfter.textContent = "";
+    ctxBefore.hidden = true;
+    ctxAfter.hidden = true;
+    expandBtn.hidden = true;
+    if (restricted) {
+      const masked = h("div", "kb-passage-masked", citation.citedText ?? citation.snippet ?? "\u5185\u5BB9\u53D7\u9650");
+      const request = h("button", "kb-passage-request", "\u7533\u8BF7\u8BBF\u95EE");
+      request.type = "button";
+      request.dataset.kbPassageRequest = "";
+      const lockSvg = svgIcon(KB_ICON_LOCK);
+      if (lockSvg) request.prepend(lockSvg);
+      request.addEventListener("click", () => {
+        emitIcen(aside, "icen:kb-source-open", { source: citation });
+      });
+      textEl.appendChild(masked);
+      textEl.appendChild(request);
+      plainText = "";
+      pendingTerms = null;
+      return;
+    }
+    plainText = resolved?.content ?? citation.citedText ?? citation.snippet ?? "\uFF08\u65E0\u539F\u6587\uFF09";
+    renderPlainText();
+    const locText = locLabel(citation.loc ?? resolved?.loc);
+    if (locText && locText !== lastLocLabel) {
+      lastLocLabel = locText;
+      locEl.textContent = locText;
+    }
+    const before = resolved?.contextBefore?.trim();
+    const after = resolved?.contextAfter?.trim();
+    const hasCtx = !!(before || after);
+    expandBtn.hidden = !hasCtx;
+    if (hasCtx) {
+      if (before) ctxBefore.textContent = before;
+      if (after) ctxAfter.textContent = after;
+    }
+  }
+  function anchorTo(citation) {
+    const anchorEl = typeof o.anchor === "function" ? o.anchor() : o.anchor;
+    if (!anchorEl || typeof anchorEl.querySelector !== "function") return;
+    const nodes = Array.from(anchorEl.querySelectorAll("[data-kb-loc]"));
+    if (nodes.length === 0) return;
+    const key = citation.documentId || citation.id;
+    let target = nodes.find((n) => n.dataset.kbLoc === key);
+    if (!target && citation.loc) {
+      let best = null;
+      let bestDist = Number.POSITIVE_INFINITY;
+      for (const n of nodes) {
+        const raw = n.dataset.kbLoc ?? "";
+        const start = Number(raw.split(":")[0]);
+        if (!Number.isFinite(start)) continue;
+        const dist = Math.abs(start - citation.loc.start);
+        if (dist < bestDist) {
+          bestDist = dist;
+          best = n;
+        }
+      }
+      target = best ?? void 0;
+    }
+    if (!target) return;
+    for (const n of nodes) n.classList.toggle("is-current", n === target);
+    target.scrollIntoView({ block: "center", behavior: "smooth" });
+  }
+  function isOpen() {
+    return !aside.hidden || aside.classList.contains("is-open");
+  }
+  function finishHide(restoreFocus) {
+    aside.hidden = true;
+    aside.classList.remove("is-open");
+    if (restoreFocus && lastFocus && document.contains(lastFocus)) lastFocus.focus();
+    lastFocus = null;
+  }
+  function trapFocus(ke) {
+    const focusables = Array.from(
+      aside.querySelectorAll('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])')
+    ).filter((n) => !n.hidden && n.getAttribute("aria-hidden") !== "true");
+    if (focusables.length === 0) {
+      ke.preventDefault();
+      aside.focus?.();
+      return;
+    }
+    const first = focusables[0];
+    const last = focusables[focusables.length - 1];
+    const active = document.activeElement;
+    if (ke.shiftKey) {
+      if (active === first || !aside.contains(active)) {
+        ke.preventDefault();
+        last.focus();
+      }
+    } else if (active === last || !aside.contains(active)) {
+      ke.preventDefault();
+      first.focus();
+    }
+  }
+  const onKeydown = (e) => {
+    if (destroyed || !isOpen()) return;
+    const ke = e;
+    if (ke.key === "Escape") {
+      ke.preventDefault();
+      handle.close();
+    } else if (ke.key === "Tab") {
+      trapFocus(ke);
+    }
+  };
+  document.addEventListener("keydown", onKeydown);
+  const onCloseClick = () => handle.close();
+  closeBtn.addEventListener("click", onCloseClick);
+  const onExpandClick = () => handle.expand();
+  expandBtn.addEventListener("click", onExpandClick);
+  const handle = {
+    open(citation) {
+      if (destroyed) return;
+      current = normalizeCitation(citation);
+      openToken++;
+      const token = openToken;
+      titleEl.textContent = current.title;
+      const iconSvg = svgIcon(getKbSourceType(current.kind).icon);
+      if (iconSvg) {
+        headIcon.textContent = "";
+        headIcon.appendChild(iconSvg);
+      }
+      lastLocLabel = locLabel(current.loc);
+      locEl.textContent = lastLocLabel;
+      textEl.textContent = "";
+      textEl.appendChild(h("span", "kb-meta", "\u52A0\u8F7D\u4E2D\u2026"));
+      let pending = false;
+      let syncDoc = null;
+      try {
+        const r = o.getDocument?.(current) ?? null;
+        if (isPromiseLike(r)) {
+          pending = true;
+          void r.then(
+            (doc_) => {
+              if (destroyed || token !== openToken) return;
+              fillBody(current, doc_ ?? null);
+            },
+            () => {
+              if (destroyed || token !== openToken) return;
+              fillBody(current, null);
+            }
+          );
+        } else {
+          syncDoc = r;
+        }
+      } catch {
+        syncDoc = null;
+      }
+      if (!pending) fillBody(current, syncDoc);
+      if (!isOpen()) {
+        lastFocus = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+        aside.hidden = false;
+        void aside.offsetWidth;
+        aside.classList.add("is-open");
+      }
+      closeBtn.focus();
+      anchorTo(current);
+      emitIcen(aside, "icen:kb-passage-jump", { citation: current });
+      o.onJump?.(current);
+    },
+    close() {
+      if (destroyed || !aside.classList.contains("is-open") && aside.hidden) return;
+      aside.classList.remove("is-open");
+      emitIcen(aside, "icen:kb-passage-close", {});
+      o.onClose?.();
+      current = null;
+      pendingTerms = null;
+      let done = false;
+      const onEnd = () => {
+        if (done) return;
+        done = true;
+        aside.removeEventListener("transitionend", onEnd);
+        finishHide(true);
+      };
+      aside.addEventListener("transitionend", onEnd);
+      setTimeout(onEnd, CLOSE_FALLBACK_MS);
+    },
+    highlight(terms) {
+      if (destroyed) return;
+      const list = (Array.isArray(terms) ? terms : [terms]).map((t) => t.trim()).filter(Boolean);
+      pendingTerms = list.length ? list : null;
+      if (current && current.permission === "readable" && plainText) applyHighlight(list);
+    },
+    expand(_delta) {
+      if (destroyed || !current) return;
+      ctxBefore.hidden = false;
+      ctxAfter.hidden = false;
+      expandBtn.hidden = true;
+      aside.classList.add("is-expanded");
+    },
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      document.removeEventListener("keydown", onKeydown);
+      closeBtn.removeEventListener("click", onCloseClick);
+      expandBtn.removeEventListener("click", onExpandClick);
+      finishHide(false);
+      current = null;
+      plainText = "";
+      pendingTerms = null;
+      el.textContent = "";
+    }
+  };
+  return handle;
+}
+export {
+  createKbPassage
+};

package/dist/behaviors/kb-pipeline.d.mts

@@ -0,0 +1,18 @@
+import { KbPipelineRun } from './kb-core.js';
+import './ai-core.js';
+
+/**
+ * 渲染解析管线时间线（快照：整树重建后返回挂载容器 el）。
+ * 单 run 渲染单卡；runs 数组渲染纵向列表（外层 .kb-pipeline-list）；空数组给空态。
+ * 重渲染会保留用户已展开/收起过的卡片折叠态（按 data-document-id 匹配）。
+ * SSR（无 document）下原样返回 el。
+ */
+declare function renderKbPipeline(el: HTMLElement, run: KbPipelineRun | KbPipelineRun[]): HTMLElement;
+/**
+ * 接线管线折叠与单文档重跑（scope 级事件委托，重复调用幂等）。
+ * root 缺省 document：页面一次 init 即接管后续插入的管线卡。
+ * 返回销毁函数：摘除委托并复位幂等标记，销毁后可重新 initKbPipeline。SSR 下 no-op。
+ */
+declare function initKbPipeline(root?: ParentNode): () => void;
+
+export { initKbPipeline, renderKbPipeline };