@ai-setting/roy-plugin-task-show 2.5.0 → 2.5.1

package/public/chat-panel.js

@@ -1,18 +1,30 @@
 /**
- * @fileoverview Home chat panel — client controller.
+ * @fileoverview Chat panel — client controller.
  *
- * v2.5.0+ REQ-2: lives on the index page (top of body). Hooks the
- * following DOM contract (pinned by `test/home-chat-v25.test.ts`):
+ * v2.5.0+ REQ-2 (home) + REQ-3 (task-aware) + REQ-4 (markdown).
+ *
+ * The module exposes a single `attachChatPanel(root, opts)` factory so
+ * the same JS file can drive both the home chat panel and the
+ * task-detail chat panel. The legacy `init()` entry-point is preserved
+ * for backward compat with any page that wires the home chat via
+ * `<script src="chat-panel.js">` alone (no opts needed).
+ *
+ * DOM contract (pinned by `test/home-chat-v25.test.ts` and
+ * `test/task-chat-v25.test.ts`):
  *
  *   [data-chat-shell]      <section> wrapper
+ *   [data-chat-scope]      "home" | "task"           (read by factory)
+ *   [data-task-id]         task id (when scope=task) (read by factory)
  *   [data-chat-messages]   <div>    message log (role="log")
  *   [data-chat-form]       <form>   submit handler
  *   [data-chat-input]      <input>  text input
  *   [data-chat-send]       <button> send button (type="submit")
  *
- * sessionId is persisted in `localStorage["taskShow.chat.sessionId"]`
- * across page loads so the conversation survives reloads. The first
- * run (no stored id) POSTs `/api/chat/start` to allocate one.
+ * sessionId is persisted in localStorage under a scope-aware key:
+ *   - scope=home: `taskShow.chat.sessionId`             (one-off uuid)
+ *   - scope=task: `taskShow.chat.task.${taskId}.sid`    (long-lived, per task)
+ * The task-detail key intentionally differs from the home key so the
+ * two scopes don't clobber each other.
  *
  * The server speaks SSE for streaming chunks. We use `fetch` + an
  * `ReadableStream` reader instead of `EventSource` because the chat
@@ -21,240 +33,533 @@
  *
  * If the chat feature is disabled server-side (503), the panel hides
  * itself with a banner instead of throwing.
+ *
+ * v2.5.x REQ-4: assistant messages are rendered through
+ * `markdownRenderer.renderMarkdown()` (vendored `marked` +
+ * `DOMPurify`). User messages deliberately stay `textContent` —
+ * users must not be able to inject markdown / HTML into their own
+ * bubbles.
  */
 
-(function () {
-  const STORAGE_KEY = "taskShow.chat.sessionId";
-  const SHELL_SEL = "[data-chat-shell]";
-  const MESSAGES_SEL = "[data-chat-messages]";
-  const FORM_SEL = "[data-chat-form]";
-  const INPUT_SEL = "[data-chat-input]";
-  const SEND_SEL = "[data-chat-send]";
+// ---------------------------------------------------------------------------
+// Module dual-mode
+//
+//   - In the browser this file is loaded as a classic <script>. The
+//     trailing bootstrap calls `init()` and the panel becomes live.
+//   - In tests (bun:test) it is imported as an ES module; the bootstrap
+//     branch is skipped (no `document`/`window` globals), and the named
+//     exports below are what the harness drives.
+// ---------------------------------------------------------------------------
+
+const HOME_STORAGE_KEY = "taskShow.chat.sessionId";
+const SHELL_SEL = "[data-chat-shell]";
+const MESSAGES_SEL = "[data-chat-messages]";
+const FORM_SEL = "[data-chat-form]";
+const INPUT_SEL = "[data-chat-input]";
+const SEND_SEL = "[data-chat-send]";
+
+// ---------------------------------------------------------------------------
+// Portable DOM access. happy-dom tests give us a Window via
+// `container.ownerDocument`; the browser gives us a global `document`.
+// ---------------------------------------------------------------------------
+
+function getDoc(container) {
+  if (container && container.ownerDocument) return container.ownerDocument;
+  if (typeof document !== "undefined") return document;
+  return null;
+}
+
+function getWindow(doc) {
+  if (doc && doc.defaultView) return doc.defaultView;
+  if (typeof window !== "undefined") return window;
+  return null;
+}
+
+function $(container, sel) {
+  const doc = getDoc(container);
+  if (doc) return doc.querySelector(sel);
+  // Fallback — should never happen for the production code path.
+  return typeof document !== "undefined" ? document.querySelector(sel) : null;
+}
+
+// ---------------------------------------------------------------------------
+// Markdown renderer resolution. In production the browser script tag
+// order is:
+//   marked.min.js → dompurify.min.js → markdown-renderer.js → chat-panel.js
+// so by the time chat-panel.js runs, `window.markdownRenderer` is set.
+//
+// If a test harness imported chat-panel.js without loading
+// markdown-renderer.js first, we lazily require it (Node-only path).
+// ---------------------------------------------------------------------------
+
+function resolveRenderer() {
+  if (typeof window !== "undefined" && window.markdownRenderer) {
+    return window.markdownRenderer;
+  }
+  if (typeof globalThis !== "undefined" && globalThis.markdownRenderer) {
+    return globalThis.markdownRenderer;
+  }
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const mod = require("./markdown-renderer.js");
+    return { renderMarkdown: mod.renderMarkdown, attachStreamingRenderer: mod.attachStreamingRenderer };
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Scope-aware storage key helpers (REQ-3). The home key is the legacy
+// single global; the task key is per-task-id so different tasks don't
+// clobber each other across reloads.
+// ---------------------------------------------------------------------------
+
+function storageKey(scope, taskId) {
+  if (scope === "task" && Number.isInteger(taskId)) {
+    return `taskShow.chat.task.${taskId}.sid`;
+  }
+  return HOME_STORAGE_KEY;
+}
 
-  function $(sel) { return document.querySelector(sel); }
+function readScopedSessionId(scope, taskId) {
+  try {
+    const w = typeof window !== "undefined" ? window : null;
+    if (!w || !w.localStorage) return "";
+    return w.localStorage.getItem(storageKey(scope, taskId)) || "";
+  } catch {
+    return "";
+  }
+}
 
-  function readSessionId() {
-    try { return window.localStorage.getItem(STORAGE_KEY) || ""; }
-    catch { return ""; }
+function writeScopedSessionId(scope, taskId, id) {
+  try {
+    const w = typeof window !== "undefined" ? window : null;
+    if (!w || !w.localStorage) return;
+    w.localStorage.setItem(storageKey(scope, taskId), id);
+  } catch {
+    /* ignore */
   }
+}
+
+// ---------------------------------------------------------------------------
+// Persistence helpers (legacy single-key API; REQ-2 home path uses
+// these directly). REQ-3 task scope goes through readScopedSessionId /
+// writeScopedSessionId above. Guarded try/catch so headless test envs
+// without localStorage don't blow up.
+// ---------------------------------------------------------------------------
 
-  function writeSessionId(id) {
-    try { window.localStorage.setItem(STORAGE_KEY, id); } catch { /* ignore */ }
+export function readSessionId(win) {
+  try {
+    const w = win || (typeof window !== "undefined" ? window : null);
+    if (!w || !w.localStorage) return "";
+    return w.localStorage.getItem(HOME_STORAGE_KEY) || "";
+  } catch {
+    return "";
   }
+}
 
-  function clearMessages(container) {
-    while (container.firstChild) container.removeChild(container.firstChild);
+export function writeSessionId(id, win) {
+  try {
+    const w = win || (typeof window !== "undefined" ? window : null);
+    if (!w || !w.localStorage) return;
+    w.localStorage.setItem(HOME_STORAGE_KEY, id);
+  } catch {
+    /* ignore */
   }
+}
+
+// ---------------------------------------------------------------------------
+// DOM mutation helpers
+// ---------------------------------------------------------------------------
+
+export function clearMessages(container) {
+  while (container.firstChild) container.removeChild(container.firstChild);
+}
 
-  function appendMessage(container, role, text) {
-    const empty = container.querySelector(".chat-empty");
-    if (empty) empty.remove();
-    const el = document.createElement("div");
-    el.className = "chat-message chat-message--" + role;
-    el.dataset.role = role;
-    const label = role === "user" ? "You" : role === "assistant" ? "Assistant" : "Error";
-    el.innerHTML =
-      `<div class="chat-message-meta">${label}</div>` +
-      `<div class="chat-message-text"></div>`;
-    el.querySelector(".chat-message-text").textContent = text;
-    container.appendChild(el);
+/**
+ * Append a message bubble to the chat log.
+ *
+ *  - `role === "assistant"` → text is rendered via
+ *    `markdownRenderer.renderMarkdown()` (marked + DOMPurify).
+ *  - `role === "user"`      → text stays `textContent`. Users must not
+ *    be able to inject HTML / markdown into their own bubble.
+ *  - `role === "error"`     → also `textContent` — error text should
+ *    be readable as-is, no formatting.
+ *
+ * Returns the created element so the test harness can inspect it.
+ */
+export function appendMessage(container, role, text) {
+  const doc = getDoc(container);
+  if (!doc) throw new Error("chat-panel.appendMessage: no document available");
+  const empty = container.querySelector(".chat-empty");
+  if (empty) empty.remove();
+  const el = doc.createElement("div");
+  el.className = "chat-message chat-message--" + role;
+  el.dataset.role = role;
+  const label = role === "user" ? "You" : role === "assistant" ? "Assistant" : "Error";
+  el.innerHTML =
+    `<div class="chat-message-meta">${label}</div>` +
+    `<div class="chat-message-text"></div>`;
+  const textEl = el.querySelector(".chat-message-text");
+  if (role === "assistant") {
+    const renderer = resolveRenderer();
+    if (renderer) {
+      textEl.innerHTML = renderer.renderMarkdown(text);
+    } else {
+      // Defensive fallback — should never hit in production.
+      textEl.textContent = text;
+    }
+  } else {
+    // user / error — textContent literal.
+    textEl.textContent = text;
+  }
+  container.appendChild(el);
+  if (container.scrollHeight != null) {
     container.scrollTop = container.scrollHeight;
-    return el;
+  }
+  return el;
+}
+
+/**
+ * Streaming chunk → debounced markdown render. The first chunk of a
+ * turn creates the assistant bubble lazily; subsequent chunks feed
+ * the bubble's streaming renderer.
+ *
+ * Returns the controller (with `flush` / `dispose`) so the caller
+ * can force a final render on `event: done`.
+ */
+export function appendChunk(container, text) {
+  const win = getWindow(getDoc(container));
+  let last = container.querySelector(".chat-message--assistant:last-of-type");
+  if (!last) last = appendMessage(container, "assistant", "");
+  const textEl = last.querySelector(".chat-message-text");
+
+  // Cache the streaming controller on the element so successive
+  // chunks reuse the same buffer + timer.
+  let ctrl = last.__markdownStreamCtrl;
+  const renderer = resolveRenderer();
+  if (!ctrl && renderer) {
+    ctrl = renderer.attachStreamingRenderer(textEl, { debounceMs: 50 });
+    last.__markdownStreamCtrl = ctrl;
   }
 
-  /**
-   * Append a streaming chunk to the last assistant message. If no
-   * assistant message exists yet (first chunk of a turn), create one.
-   */
-  function appendChunk(container, text) {
-    let last = container.querySelector(".chat-message--assistant:last-of-type");
-    if (!last) last = appendMessage(container, "assistant", "");
-    const textEl = last.querySelector(".chat-message-text");
+  if (ctrl) {
+    ctrl.append(text);
+  } else {
+    // No renderer available — fall back to textContent (textContent
+    // of a chunk is the safest path when DOMPurify isn't loaded).
     textEl.textContent += text;
+  }
+  if (win && container.scrollHeight != null) {
     container.scrollTop = container.scrollHeight;
   }
+}
 
-  function setBusy(form, busy) {
-    const input = form.querySelector(INPUT_SEL);
-    const send = form.querySelector(SEND_SEL);
-    if (input) input.disabled = busy;
-    if (send) {
-      send.disabled = busy;
-      send.textContent = busy ? "Sending…" : "Send";
-    }
+// ---------------------------------------------------------------------------
+// Form / network helpers (kept outside any IIFE so they can be reached
+// in the browser; tests don't exercise these).
+// ---------------------------------------------------------------------------
+
+function setBusy(form, busy) {
+  const input = form.querySelector(INPUT_SEL);
+  const send = form.querySelector(SEND_SEL);
+  if (input) input.disabled = busy;
+  if (send) {
+    send.disabled = busy;
+    send.textContent = busy ? "Sending…" : "Send";
   }
+}
+
+function showDisabledBanner(shell, msg) {
+  const doc = getDoc(shell);
+  if (!doc) return;
+  const banner = doc.createElement("p");
+  banner.className = "chat-banner";
+  banner.dataset.role = "banner";
+  banner.textContent = msg;
+  shell.appendChild(banner);
+  const form = shell.querySelector(FORM_SEL);
+  if (form) form.remove();
+}
 
-  function showDisabledBanner(shell, msg) {
-    const banner = document.createElement("p");
-    banner.className = "chat-banner";
-    banner.dataset.role = "banner";
-    banner.textContent = msg;
-    shell.appendChild(banner);
-    const form = shell.querySelector(FORM_SEL);
-    if (form) form.remove();
+/**
+ * Resolve a fresh session id for the current scope.
+ *   - scope=home: POST /api/chat/start → { sessionId }
+ *   - scope=task: deterministic `task-${taskId}`; we don't need to
+ *     round-trip the server because the task-detail endpoint keys
+ *     off the taskId directly. This guarantees multi-turn
+ *     conversations survive reloads even when the CLI never saw a
+ *     /start call.
+ */
+async function ensureSessionId(scope, taskId) {
+  if (scope === "task" && Number.isInteger(taskId)) {
+    return `task-${taskId}`;
   }
+  const cached = readScopedSessionId(scope, taskId);
+  if (cached) return cached;
+  const res = await fetch("/api/chat/start", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: "{}",
+  });
+  if (!res.ok) throw new Error("chat_start_failed: " + res.status);
+  const j = await res.json();
+  writeScopedSessionId(scope, taskId, j.sessionId);
+  return j.sessionId;
+}
 
-  async function ensureSessionId() {
-    let id = readSessionId();
-    if (id) return id;
-    const res = await fetch("/api/chat/start", {
+/**
+ * Compute the message-endpoint URL for the current scope.
+ *   - scope=home: /api/chat/<sessionId>/message
+ *   - scope=task: /api/task-chat/<taskId>/message  (server derives
+ *     sessionId from taskId, so we never need it on the client side)
+ *
+ * If `opts.endpoint` is supplied, it's used as the base prefix
+ * (mostly for tests / proxies); the resource sub-path is still
+ * computed from scope + (taskId|sessionId).
+ */
+function endpointFor(opts, sessionId) {
+  const base = (opts && opts.endpoint) || "";
+  const trimBase = base.replace(/\/+$/, "");
+  if (opts.scope === "task" && Number.isInteger(opts.taskId)) {
+    const url = `/api/task-chat/${opts.taskId}/message`;
+    return trimBase ? `${trimBase}${url}` : url;
+  }
+  const url = `/api/chat/${encodeURIComponent(sessionId)}/message`;
+  return trimBase ? `${trimBase}${url}` : url;
+}
+
+/**
+ * Public hook for the test harness — only used by the browser init
+ * flow in tests that simulate a full submit. Kept as a named export
+ * so home-chat-v25's fake ACT test can call into the same code path.
+ *
+ * Legacy signature: sendMessage(form, container, message) — used by
+ * `init()` for the home scope. REQ-3 goes through attachChatPanel()
+ * instead, which calls into streamSession() below.
+ */
+export async function sendMessage(form, container, message) {
+  return streamSession({ scope: "home", endpoint: "" }, form, container, message);
+}
+
+/**
+ * Stream one user message to the server, render chunks back into the
+ * container. Shared by both legacy `sendMessage` (home) and the
+ * REQ-3 `attachChatPanel` (home + task).
+ */
+async function streamSession(opts, form, container, message) {
+  let sessionId;
+  try {
+    sessionId = await ensureSessionId(opts.scope, opts.taskId);
+  } catch (e) {
+    appendMessage(container, "error", String(e && e.message || e));
+    return;
+  }
+  appendMessage(container, "user", message);
+  setBusy(form, true);
+
+  const url = endpointFor(opts, sessionId);
+  let res;
+  try {
+    res = await fetch(url, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: "{}",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "text/event-stream",
+      },
+      body: JSON.stringify({ message }),
     });
-    if (!res.ok) throw new Error("chat_start_failed: " + res.status);
-    const j = await res.json();
-    id = j.sessionId;
-    writeSessionId(id);
-    return id;
+  } catch (e) {
+    appendMessage(container, "error", "network_error: " + (e && e.message || e));
+    setBusy(form, false);
+    return;
   }
 
-  async function sendMessage(form, container, message) {
-    let sessionId;
-    try {
-      sessionId = await ensureSessionId();
-    } catch (e) {
-      appendMessage(container, "error", String(e && e.message || e));
-      return;
-    }
-    appendMessage(container, "user", message);
-    setBusy(form, true);
-
-    let res;
-    try {
-      res = await fetch(`/api/chat/${encodeURIComponent(sessionId)}/message`, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Accept: "text/event-stream",
-        },
-        body: JSON.stringify({ message }),
-      });
-    } catch (e) {
-      appendMessage(container, "error", "network_error: " + (e && e.message || e));
-      setBusy(form, false);
-      return;
-    }
+  if (!res.ok || !res.body) {
+    let detail = "";
+    try { detail = await res.text(); } catch { /* ignore */ }
+    appendMessage(container, "error", `server_error: ${res.status} ${detail.slice(0, 200)}`);
+    setBusy(form, false);
+    return;
+  }
 
-    if (!res.ok || !res.body) {
-      let detail = "";
-      try { detail = await res.text(); } catch { /* ignore */ }
-      appendMessage(container, "error", `server_error: ${res.status} ${detail.slice(0, 200)}`);
-      setBusy(form, false);
-      return;
-    }
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder("utf-8");
+  let buf = "";
+  let sawError = false;
 
-    const reader = res.body.getReader();
-    const decoder = new TextDecoder("utf-8");
-    let buf = "";
-    let sawError = false;
-
-    try {
-      while (true) {
-        const { value, done } = await reader.read();
-        if (done) break;
-        buf += decoder.decode(value, { stream: true });
-        let nl;
-        while ((nl = buf.indexOf("\n\n")) >= 0) {
-          const frame = buf.slice(0, nl);
-          buf = buf.slice(nl + 2);
-          handleFrame(frame, container, (err) => { sawError = sawError || !!err; });
-        }
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      let nl;
+      while ((nl = buf.indexOf("\n\n")) >= 0) {
+        const frame = buf.slice(0, nl);
+        buf = buf.slice(nl + 2);
+        handleFrame(frame, container, (err) => { sawError = sawError || !!err; });
       }
-      // Flush trailing frame if any.
-      if (buf.trim().length > 0) handleFrame(buf, container, () => {});
-    } catch (e) {
-      appendMessage(container, "error", "stream_error: " + (e && e.message || e));
-    } finally {
-      setBusy(form, false);
-      // Suppress the final empty-message that may have been left if the
-      // assistant produced no text. We intentionally leave error messages
-      // alone so the user can see what went wrong.
-      if (!sawError) {
-        const last = container.querySelector(".chat-message--assistant:last-of-type");
-        if (last && !last.querySelector(".chat-message-text").textContent.trim()) {
-          last.remove();
-        }
+    }
+    // Flush trailing frame if any.
+    if (buf.trim().length > 0) handleFrame(buf, container, () => {});
+  } catch (e) {
+    appendMessage(container, "error", "stream_error: " + (e && e.message || e));
+  } finally {
+    setBusy(form, false);
+    // Final markdown flush so the last debounced chunk renders before
+    // the busy spinner goes away.
+    const last = container.querySelector(".chat-message--assistant:last-of-type");
+    if (last && last.__markdownStreamCtrl && last.__markdownStreamCtrl.flush) {
+      last.__markdownStreamCtrl.flush();
+    }
+    // Suppress the final empty-message that may have been left if the
+    // assistant produced no text. We intentionally leave error messages
+    // alone so the user can see what went wrong.
+    if (!sawError) {
+      const last2 = container.querySelector(".chat-message--assistant:last-of-type");
+      if (last2 && !last2.querySelector(".chat-message-text").textContent.trim()) {
+        last2.remove();
       }
     }
   }
+}
 
-  /** Parse one SSE frame (event:/data:/id: lines). Returns the parsed frame or null. */
-  function handleFrame(raw, container, onError) {
-    let event = "";
-    let data = "";
-    let id = "";
-    for (const line of raw.split(/\r?\n/)) {
-      if (line.startsWith(":")) continue;
-      if (line.startsWith("event:")) event = line.slice(6).trim();
-      else if (line.startsWith("data:")) data += (data ? "\n" : "") + line.slice(5).trim();
-      else if (line.startsWith("id:")) id = line.slice(3).trim();
-    }
-    if (!event && !data) return null;
-    let parsed = null;
-    if (data) {
-      try { parsed = JSON.parse(data); } catch { parsed = data; }
-    }
-    if (event === "chunk" && parsed && typeof parsed === "object") {
-      if (parsed.type === "text" && typeof parsed.text === "string") {
-        appendChunk(container, parsed.text);
-      } else if (parsed.type === "reasoning" && typeof parsed.text === "string") {
-        // Reasoning is hidden in the chat UI by design; we still log it
-        // so a developer can inspect via DevTools.
-        if (window.console && window.console.debug) {
-          window.console.debug("[chat] reasoning:", parsed.text);
-        }
-      } else if (parsed.type === "start") {
-        // No-op: the assistant bubble is created lazily on first text chunk.
-      } else if (parsed.type === "error" && parsed.error) {
-        onError(parsed);
-        appendMessage(container, "error", parsed.error.message || "unknown error");
+/** Parse one SSE frame (event:/data:/id: lines). Returns the parsed frame or null. */
+function handleFrame(raw, container, onError) {
+  let event = "";
+  let data = "";
+  let id = "";
+  for (const line of raw.split(/\r?\n/)) {
+    if (line.startsWith(":")) continue;
+    if (line.startsWith("event:")) event = line.slice(6).trim();
+    else if (line.startsWith("data:")) data += (data ? "\n" : "") + line.slice(5).trim();
+    else if (line.startsWith("id:")) id = line.slice(3).trim();
+  }
+  if (!event && !data) return null;
+  let parsed = null;
+  if (data) {
+    try { parsed = JSON.parse(data); } catch { parsed = data; }
+  }
+  if (event === "chunk" && parsed && typeof parsed === "object") {
+    if (parsed.type === "text" && typeof parsed.text === "string") {
+      appendChunk(container, parsed.text);
+    } else if (parsed.type === "reasoning" && typeof parsed.text === "string") {
+      // Reasoning is hidden in the chat UI by design; we still log it
+      // so a developer can inspect via DevTools.
+      if (typeof console !== "undefined" && console.debug) {
+        console.debug("[chat] reasoning:", parsed.text);
       }
-    } else if (event === "done") {
-      // Terminal marker — nothing to render.
-    } else if (event === "error") {
+    } else if (parsed.type === "start") {
+      // No-op: the assistant bubble is created lazily on first text chunk.
+    } else if (parsed.type === "error" && parsed.error) {
       onError(parsed);
-      const msg = parsed && parsed.error && parsed.error.message
-        ? parsed.error.message
-        : "stream error";
-      appendMessage(container, "error", msg);
-    } else if (event === "ready") {
-      // SSE handshake — nothing to render.
+      appendMessage(container, "error", parsed.error.message || "unknown error");
     }
-    return { event, data, id, parsed };
+  } else if (event === "done") {
+    // Terminal marker — final flush is handled by the caller's finally.
+  } else if (event === "error") {
+    onError(parsed);
+    const msg = parsed && parsed.error && parsed.error.message
+      ? parsed.error.message
+      : "stream error";
+    appendMessage(container, "error", msg);
+  } else if (event === "ready") {
+    // SSE handshake — nothing to render.
   }
+  return { event, data, id, parsed };
+}
 
-  function init() {
-    const shell = document.querySelector(SHELL_SEL);
-    if (!shell) return;
-    const form = shell.querySelector(FORM_SEL);
-    const container = shell.querySelector(MESSAGES_SEL);
-    const input = shell.querySelector(INPUT_SEL);
-    if (!form || !container || !input) return;
-
-    // Probe feature availability with a HEAD request. If 503, hide UI.
-    fetch("/api/chat/start", { method: "HEAD" }).then((res) => {
-      if (res.status === 503) {
-        showDisabledBanner(shell, "Chat disabled (server returned 503 — chatOptions not configured).");
-      }
-    }).catch(() => { /* offline — leave UI alone */ });
-
-    form.addEventListener("submit", (e) => {
-      e.preventDefault();
-      const message = (input.value || "").trim();
-      if (!message) return;
-      input.value = "";
-      sendMessage(form, container, message);
-    });
+/**
+ * Resolve the chat options from DOM data-attrs when the caller
+ * didn't pass them explicitly. Lets the server emit a single
+ * `<section data-chat-scope="task" data-task-id="4242">` and have
+ * the JS pick up the right endpoint / storage key automatically.
+ */
+function readOptsFromRoot(root, opts) {
+  const merged = Object.assign({}, opts || {});
+  if (!merged.scope) {
+    const scopeAttr = root.getAttribute && root.getAttribute("data-chat-scope");
+    merged.scope = scopeAttr === "task" ? "task" : "home";
+  }
+  if (merged.scope === "task" && !Number.isInteger(merged.taskId)) {
+    const idAttr = root.getAttribute && root.getAttribute("data-task-id");
+    const n = Number(idAttr);
+    if (Number.isInteger(n)) merged.taskId = n;
   }
+  return merged;
+}
 
+/**
+ * Factory — wire a chat panel inside `root` using the supplied
+ * options. Returns the controller handle (for tests / programmatic
+ * sends). Backward-compatible with the legacy `init()` entry point
+ * which auto-discovers the home shell.
+ *
+ * @param {HTMLElement} root  the [data-chat-shell] element
+ * @param {{
+ *   endpoint?: string;     // optional base prefix (e.g. "" or "https://proxy")
+ *   scope?: "home"|"task"; // which API endpoint to use (default: from DOM data-chat-scope)
+ *   taskId?: number;       // required when scope === "task"
+ * }} [opts]
+ */
+export function attachChatPanel(root, opts) {
+  if (!root) return null;
+  const finalOpts = readOptsFromRoot(root, opts);
+  const form = root.querySelector(FORM_SEL);
+  const container = root.querySelector(MESSAGES_SEL);
+  const input = root.querySelector(INPUT_SEL);
+  if (!form || !container || !input) return null;
+
+  // Probe feature availability with a HEAD request. If 503, hide UI.
+  // For task scope we don't have a generic /api/chat/start — but
+  // the same server returns 503 on /api/task-chat/0/message when
+  // the chat is disabled (any numeric id triggers the chatManager
+  // check), so we use that as a feature probe.
+  const probeUrl = finalOpts.scope === "task"
+    ? `/api/task-chat/0/message`
+    : "/api/chat/start";
+  fetch(probeUrl, { method: "HEAD" }).then((res) => {
+    if (res.status === 503) {
+      showDisabledBanner(root, "Chat disabled (server returned 503 — chatOptions not configured).");
+    }
+  }).catch(() => { /* offline — leave UI alone */ });
+
+  form.addEventListener("submit", (e) => {
+    e.preventDefault();
+    const message = (input.value || "").trim();
+    if (!message) return;
+    input.value = "";
+    streamSession(finalOpts, form, container, message);
+  });
+
+  return { root, opts: finalOpts, send: (msg) => streamSession(finalOpts, form, container, msg) };
+}
+
+export function init() {
+  const shell = $(null, SHELL_SEL);
+  if (!shell) return null;
+  return attachChatPanel(shell, {});
+}
+
+// ---------------------------------------------------------------------------
+// Browser-only bootstrap. Tests run this file under bun:test where
+// `document`/`window` are not globals, so the if-branch is skipped and
+// only the named exports are available.
+// ---------------------------------------------------------------------------
+
+if (typeof document !== "undefined" && typeof window !== "undefined") {
   if (document.readyState === "loading") {
     document.addEventListener("DOMContentLoaded", init);
   } else {
     init();
   }
-
   // Expose a tiny test hook so headless harness can drive the panel
   // without firing real events.
-  window.taskShowChatPanel = { init, sendMessage, STORAGE_KEY };
-})();
+  window.taskShowChatPanel = {
+    init,
+    attachChatPanel,
+    sendMessage,
+    storageKey,
+    HOME_STORAGE_KEY,
+  };
+}