helloloop 0.8.6 → 0.10.0

package/src/dashboard_web.mjs

@@ -0,0 +1,351 @@
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  ensureDir,
+  fileExists,
+  nowIso,
+  readJson,
+  sleep,
+  tailText,
+  writeJson,
+} from "./common.mjs";
+import { collectDashboardSnapshot, buildDashboardSnapshotSignature } from "./dashboard_command.mjs";
+import { renderDashboardWebHtml } from "./dashboard_web_page.mjs";
+import { resolveUserSettingsHome } from "./engine_selection_settings.mjs";
+import { spawnNodeProcess } from "./node_process_launch.mjs";
+
+const DEFAULT_BIND = "127.0.0.1";
+const DEFAULT_PORT = 3210;
+const WEB_SERVER_ENV = "HELLOLOOP_WEB_SERVER_ACTIVE";
+const BUNDLE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function dashboardRuntimeRoot() {
+  return path.join(resolveUserSettingsHome(), "runtime", "web-dashboard");
+}
+
+function dashboardRuntimeFiles() {
+  const root = dashboardRuntimeRoot();
+  ensureDir(root);
+  return {
+    root,
+    stateFile: path.join(root, "server.json"),
+    stdoutFile: path.join(root, "server-stdout.log"),
+    stderrFile: path.join(root, "server-stderr.log"),
+  };
+}
+
+function readJsonIfExists(filePath) {
+  try {
+    return filePath && fileExists(filePath) ? readJson(filePath) : null;
+  } catch {
+    return null;
+  }
+}
+
+function isPidAlive(pid) {
+  const value = Number(pid || 0);
+  if (!Number.isFinite(value) || value <= 0) {
+    return false;
+  }
+  try {
+    process.kill(value, 0);
+    return true;
+  } catch (error) {
+    return String(error?.code || "") === "EPERM";
+  }
+}
+
+function normalizeBind(value) {
+  const bind = String(value || "").trim();
+  return bind || DEFAULT_BIND;
+}
+
+function normalizePort(value) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 65535) {
+    return DEFAULT_PORT;
+  }
+  return parsed;
+}
+
+function writeWebServerState(patch) {
+  const files = dashboardRuntimeFiles();
+  const current = readJsonIfExists(files.stateFile) || {};
+  writeJson(files.stateFile, {
+    ...current,
+    ...patch,
+    updatedAt: nowIso(),
+  });
+}
+
+function readWebServerState() {
+  const files = dashboardRuntimeFiles();
+  const state = readJsonIfExists(files.stateFile);
+  if (!state) {
+    return null;
+  }
+  if (!isPidAlive(state.pid)) {
+    try {
+      fs.rmSync(files.stateFile, { force: true });
+    } catch {
+      // ignore stale state cleanup failure
+    }
+    return null;
+  }
+  return state;
+}
+
+function removeWebServerStateIfOwned(pid) {
+  const files = dashboardRuntimeFiles();
+  const state = readJsonIfExists(files.stateFile);
+  if (state?.pid === pid) {
+    try {
+      fs.rmSync(files.stateFile, { force: true });
+    } catch {
+      // ignore cleanup failure
+    }
+  }
+}
+
+function buildWebUrl(bind, port) {
+  return `http://${bind}:${port}`;
+}
+
+function renderStartSummary(state) {
+  return [
+    "HelloLoop Web Dashboard 已启动",
+    `- 地址：${state.url}`,
+    `- PID：${state.pid}`,
+    `- 监听：${state.bind}:${state.port}`,
+  ].join("\n");
+}
+
+function renderExistingSummary(state) {
+  return [
+    "HelloLoop Web Dashboard 已在运行",
+    `- 地址：${state.url}`,
+    `- PID：${state.pid}`,
+  ].join("\n");
+}
+
+async function waitForWebServerLaunch(launchId, timeoutMs = 8000) {
+  const files = dashboardRuntimeFiles();
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const state = readJsonIfExists(files.stateFile);
+    if (state?.launchId === launchId && isPidAlive(state.pid)) {
+      return state;
+    }
+    await sleep(150);
+  }
+  const stderr = fileExists(files.stderrFile) ? fs.readFileSync(files.stderrFile, "utf8") : "";
+  throw new Error(tailText(stderr, 40) || "HelloLoop Web Dashboard 启动超时。");
+}
+
+async function stopWebDashboardServer() {
+  const state = readWebServerState();
+  if (!state) {
+    console.log("HelloLoop Web Dashboard 当前未运行。");
+    return 0;
+  }
+
+  try {
+    process.kill(state.pid);
+  } catch {
+    // ignore if already down
+  }
+
+  const deadline = Date.now() + 5000;
+  while (Date.now() < deadline) {
+    if (!isPidAlive(state.pid)) {
+      removeWebServerStateIfOwned(state.pid);
+      console.log(`HelloLoop Web Dashboard 已停止：${state.url}`);
+      return 0;
+    }
+    await sleep(150);
+  }
+
+  throw new Error(`HelloLoop Web Dashboard 停止超时：pid=${state.pid}`);
+}
+
+function sendJson(response, statusCode, payload) {
+  response.writeHead(statusCode, {
+    "Content-Type": "application/json; charset=utf-8",
+    "Cache-Control": "no-store",
+  });
+  response.end(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+function createSseClient(response, snapshot) {
+  let previousSignature = "";
+  response.writeHead(200, {
+    "Content-Type": "text/event-stream; charset=utf-8",
+    "Cache-Control": "no-cache, no-transform",
+    Connection: "keep-alive",
+  });
+  response.write(`data: ${JSON.stringify(snapshot)}\n\n`);
+  previousSignature = buildDashboardSnapshotSignature(snapshot);
+  return {
+    push(nextSnapshot) {
+      const nextSignature = buildDashboardSnapshotSignature(nextSnapshot);
+      if (nextSignature === previousSignature) {
+        return;
+      }
+      previousSignature = nextSignature;
+      response.write(`data: ${JSON.stringify(nextSnapshot)}\n\n`);
+    },
+  };
+}
+
+async function startWebDashboardServer(options = {}) {
+  const files = dashboardRuntimeFiles();
+  const bind = normalizeBind(options.bind);
+  const preferredPort = normalizePort(options.port);
+  const pollMs = Math.max(500, Number(options.pollMs || options.watchPollMs || 1500));
+  const initialSnapshot = collectDashboardSnapshot();
+  const clients = new Set();
+  let lastSnapshot = initialSnapshot;
+
+  const server = http.createServer((request, response) => {
+    const url = new URL(request.url || "/", buildWebUrl(bind, preferredPort));
+    if (url.pathname === "/api/snapshot") {
+      sendJson(response, 200, collectDashboardSnapshot());
+      return;
+    }
+    if (url.pathname === "/events") {
+      const client = createSseClient(response, lastSnapshot);
+      clients.add(client);
+      request.on("close", () => clients.delete(client));
+      return;
+    }
+    if (url.pathname === "/healthz") {
+      sendJson(response, 200, { ok: true, generatedAt: nowIso() });
+      return;
+    }
+    response.writeHead(200, {
+      "Content-Type": "text/html; charset=utf-8",
+      "Cache-Control": "no-store",
+    });
+    response.end(renderDashboardWebHtml({
+      initialSnapshot: lastSnapshot,
+    }));
+  });
+
+  let settledPort = preferredPort;
+  await new Promise((resolve, reject) => {
+    const onError = (error) => {
+      if (String(error?.code || "") === "EADDRINUSE" && !options.port) {
+        server.off("error", onError);
+        server.listen(0, bind, resolve);
+        return;
+      }
+      reject(error);
+    };
+    server.once("error", onError);
+    server.listen(preferredPort, bind, resolve);
+  });
+  const address = server.address();
+  settledPort = Number(address?.port || preferredPort);
+  const state = {
+    pid: process.pid,
+    bind,
+    port: settledPort,
+    url: buildWebUrl(bind, settledPort),
+    startedAt: nowIso(),
+    launchId: String(options.launchId || "").trim(),
+    pollMs,
+  };
+  writeWebServerState(state);
+
+  const timer = setInterval(() => {
+    lastSnapshot = collectDashboardSnapshot();
+    writeWebServerState({
+      ...state,
+      generatedAt: lastSnapshot.generatedAt,
+    });
+    for (const client of clients) {
+      client.push(lastSnapshot);
+    }
+  }, pollMs);
+
+  const shutdown = () => {
+    clearInterval(timer);
+    server.close(() => {
+      removeWebServerStateIfOwned(process.pid);
+      process.exit(0);
+    });
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+
+  console.log(renderStartSummary({
+    ...state,
+    url: buildWebUrl(bind, settledPort),
+  }));
+}
+
+async function launchWebDashboardServer(options = {}) {
+  const existing = readWebServerState();
+  if (existing) {
+    console.log(renderExistingSummary(existing));
+    return 0;
+  }
+
+  const files = dashboardRuntimeFiles();
+  const launchId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const stdoutFd = fs.openSync(files.stdoutFile, "w");
+  const stderrFd = fs.openSync(files.stderrFile, "w");
+
+  try {
+    const args = [
+      path.join(BUNDLE_ROOT, "bin", "helloloop.js"),
+      "__web-server",
+      "--bind",
+      normalizeBind(options.bind),
+      "--launch-id",
+      launchId,
+      "--poll-ms",
+      String(Math.max(500, Number(options.pollMs || options.watchPollMs || 1500))),
+    ];
+    if (options.port !== undefined && options.port !== null && options.port !== "") {
+      args.push("--port", String(options.port));
+    }
+
+    const child = spawnNodeProcess({
+      args,
+      cwd: process.cwd(),
+      detached: true,
+      stdio: ["ignore", stdoutFd, stderrFd],
+      env: {
+        [WEB_SERVER_ENV]: "1",
+      },
+    });
+    child.unref();
+  } finally {
+    fs.closeSync(stdoutFd);
+    fs.closeSync(stderrFd);
+  }
+
+  const state = await waitForWebServerLaunch(launchId);
+  console.log(renderStartSummary(state));
+  return 0;
+}
+
+export async function runDashboardWebCommand(options = {}) {
+  if (options.stop === true) {
+    return stopWebDashboardServer();
+  }
+  const existing = readWebServerState();
+  if (existing) {
+    console.log(renderExistingSummary(existing));
+    return 0;
+  }
+  if (options.foreground === true || process.env[WEB_SERVER_ENV] === "1") {
+    await startWebDashboardServer(options);
+    return 0;
+  }
+  return launchWebDashboardServer(options);
+}

package/src/dashboard_web_client.mjs

@@ -0,0 +1,167 @@
+export const DASHBOARD_WEB_CSS = `
+  :root {
+    color-scheme: dark;
+    --bg: #081122;
+    --panel: #0f1a2f;
+    --panel-2: #13213c;
+    --border: rgba(148, 163, 184, 0.2);
+    --text: #e5eefc;
+    --muted: #9fb2d1;
+    --accent: #5eead4;
+    --warn: #fbbf24;
+    --danger: #f87171;
+    --ok: #34d399;
+    --shadow: 0 16px 40px rgba(0, 0, 0, 0.28);
+    font-family: Inter, "Segoe UI", system-ui, sans-serif;
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: radial-gradient(circle at top, #13284a 0%, var(--bg) 40%, #050b16 100%); color: var(--text); }
+  header { position: sticky; top: 0; z-index: 10; backdrop-filter: blur(14px); background: rgba(8, 17, 34, 0.86); border-bottom: 1px solid var(--border); padding: 20px 24px 16px; }
+  .title-row, .stats-row, .repo-header-top, .repo-meta { display: flex; gap: 12px; align-items: center; justify-content: space-between; flex-wrap: wrap; }
+  .title h1 { margin: 0; font-size: 24px; font-weight: 700; }
+  .title p { margin: 6px 0 0; color: var(--muted); font-size: 14px; }
+  .pill, .badge, .drawer-close { border-radius: 999px; border: 1px solid var(--border); background: rgba(19, 33, 60, 0.9); color: var(--text); }
+  .pill { display: inline-flex; align-items: center; gap: 8px; padding: 8px 14px; font-size: 13px; }
+  .stats-row { margin-top: 16px; }
+  .stats { display: grid; grid-template-columns: repeat(auto-fit, minmax(110px, 1fr)); gap: 12px; width: min(100%, 760px); }
+  .stat, .repo-board { background: rgba(15, 26, 47, 0.9); border: 1px solid var(--border); box-shadow: var(--shadow); }
+  .stat { border-radius: 16px; padding: 14px; }
+  .stat-label, .column-count, .repo-meta, .empty, .card-meta, .drawer-section h4 { color: var(--muted); font-size: 12px; }
+  .stat-value { margin-top: 6px; font-size: 22px; font-weight: 700; }
+  main { padding: 20px 24px 80px; display: grid; gap: 20px; }
+  .repo-board { border-radius: 22px; overflow: hidden; }
+  .repo-header { padding: 18px 20px 14px; border-bottom: 1px solid var(--border); background: linear-gradient(180deg, rgba(19, 33, 60, 0.96) 0%, rgba(15, 26, 47, 0.96) 100%); }
+  .repo-header h2 { margin: 0; font-size: 20px; }
+  .repo-meta { margin-top: 12px; font-size: 13px; }
+  .columns { display: grid; grid-template-columns: repeat(5, minmax(220px, 1fr)); gap: 16px; padding: 18px; overflow-x: auto; }
+  .column { min-height: 180px; background: rgba(9, 16, 29, 0.72); border: 1px solid rgba(148, 163, 184, 0.14); border-radius: 18px; padding: 14px; display: flex; flex-direction: column; gap: 12px; }
+  .column h3, .drawer h3 { margin: 0; font-size: 15px; }
+  .cards { display: grid; gap: 10px; align-content: start; }
+  .card { width: 100%; text-align: left; background: rgba(19, 33, 60, 0.96); border: 1px solid rgba(148, 163, 184, 0.16); border-radius: 14px; padding: 12px; cursor: pointer; color: inherit; }
+  .card:hover { border-color: rgba(94, 234, 212, 0.42); transform: translateY(-1px); }
+  .card-title { font-size: 14px; font-weight: 600; line-height: 1.45; }
+  .badges, .repo-badges { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 10px; }
+  .badge { padding: 4px 10px; font-size: 11px; border-color: transparent; background: rgba(148, 163, 184, 0.14); }
+  .badge.ok { background: rgba(52, 211, 153, 0.15); color: var(--ok); }
+  .badge.warn { background: rgba(251, 191, 36, 0.14); color: var(--warn); }
+  .badge.danger { background: rgba(248, 113, 113, 0.14); color: var(--danger); }
+  .badge.accent { background: rgba(94, 234, 212, 0.12); color: var(--accent); }
+  .card-meta { margin-top: 10px; line-height: 1.5; }
+  aside.drawer { position: fixed; top: 0; right: 0; width: min(480px, 100vw); height: 100vh; background: rgba(6, 13, 26, 0.98); border-left: 1px solid var(--border); box-shadow: var(--shadow); transform: translateX(100%); transition: transform 180ms ease; padding: 24px; overflow-y: auto; z-index: 20; }
+  aside.drawer.open { transform: translateX(0); }
+  .drawer h3 { font-size: 20px; }
+  .drawer-section { margin-top: 18px; }
+  .drawer-section h4 { margin: 0 0 8px; text-transform: uppercase; }
+  .drawer-list { margin: 0; padding-left: 18px; line-height: 1.6; }
+  .drawer-close { position: sticky; top: 0; float: right; padding: 6px 12px; cursor: pointer; }
+  @media (max-width: 1100px) { .columns { grid-template-columns: repeat(2, minmax(240px, 1fr)); } }
+  @media (max-width: 760px) { header, main { padding-left: 14px; padding-right: 14px; } .columns { grid-template-columns: 1fr; } }
+`;
+
+export const DASHBOARD_WEB_JS = `
+  const STATUS_COLUMNS = [
+    { key: "pending", label: "待处理" },
+    { key: "in_progress", label: "进行中" },
+    { key: "done", label: "已完成" },
+    { key: "blocked", label: "阻塞" },
+    { key: "failed", label: "失败" },
+  ];
+  const boardEl = document.getElementById("board");
+  const statsEl = document.getElementById("stats");
+  const sessionPillEl = document.getElementById("session-pill");
+  const updatePillEl = document.getElementById("update-pill");
+  const drawerEl = document.getElementById("drawer");
+  const drawerContentEl = document.getElementById("drawer-content");
+  const drawerCloseEl = document.getElementById("drawer-close");
+  let currentSnapshot = window.__HELLOLOOP_INITIAL_SNAPSHOT__;
+
+  function badgeClass(kind) {
+    if (kind === "done" || kind === "running" || kind === "ready") return "ok";
+    if (kind === "blocked" || kind === "failed") return "danger";
+    if (kind === "retry_waiting" || kind === "watchdog_waiting") return "warn";
+    return "accent";
+  }
+
+  function formatRuntime(session) {
+    const runtime = session.runtime || {};
+    const bits = [runtime.status || "idle"];
+    if (Number.isFinite(Number(runtime.recoveryCount)) && Number(runtime.recoveryCount) > 0) bits.push("recovery=" + runtime.recoveryCount);
+    if (Number.isFinite(Number(runtime?.heartbeat?.idleSeconds)) && Number(runtime.heartbeat.idleSeconds) > 0) bits.push("idle=" + runtime.heartbeat.idleSeconds + "s");
+    return bits.join(" | ");
+  }
+
+  function groupTasks(tasks) {
+    const grouped = Object.fromEntries(STATUS_COLUMNS.map((column) => [column.key, []]));
+    for (const task of Array.isArray(tasks) ? tasks : []) {
+      const key = task.status || "pending";
+      if (!grouped[key]) grouped[key] = [];
+      grouped[key].push(task);
+    }
+    return grouped;
+  }
+
+  function renderStats(snapshot) {
+    const totals = snapshot.taskTotals || {};
+    const items = [["仓库总数", snapshot.repoCount || 0], ["活跃会话", snapshot.activeCount || 0], ["任务总计", totals.total || 0], ["待处理", totals.pending || 0], ["进行中", totals.inProgress || 0], ["已完成", totals.done || 0], ["阻塞", totals.blocked || 0], ["失败", totals.failed || 0]];
+    statsEl.innerHTML = items.map(([label, value]) => '<div class="stat"><div class="stat-label">' + label + '</div><div class="stat-value">' + value + '</div></div>').join("");
+    sessionPillEl.textContent = "仓库 " + (snapshot.repoCount || 0) + " · 活跃会话 " + (snapshot.activeCount || 0);
+    updatePillEl.textContent = "最近刷新 " + (snapshot.generatedAt || "unknown");
+  }
+
+  function renderTaskCard(task, session) {
+    const isCurrent = task.id && task.id === session.latestStatus?.taskId;
+    const docsCount = Array.isArray(task.docs) ? task.docs.length : 0;
+    const pathsCount = Array.isArray(task.paths) ? task.paths.length : 0;
+    return '<button class="card" data-session="' + encodeURIComponent(session.sessionId || "") + '" data-task="' + encodeURIComponent(task.id || "") + '"><div class="card-title">' + (task.title || task.id || "未命名任务") + '</div><div class="badges"><span class="badge accent">' + (task.priority || "P2") + '</span><span class="badge ' + badgeClass(task.status || "pending") + '">' + (task.status || "pending") + '</span><span class="badge ' + badgeClass(task.risk || "low") + '">' + (task.risk || "low") + '</span>' + (isCurrent ? '<span class="badge warn">当前执行</span>' : "") + '</div><div class="card-meta">docs ' + docsCount + ' · paths ' + pathsCount + '</div></button>';
+  }
+
+  function renderSessionBoard(session) {
+    const grouped = groupTasks(session.tasks || []);
+    const repoBadges = ['<span class="badge ' + badgeClass(session.supervisor?.status || "running") + '">supervisor ' + (session.supervisor?.status || "unknown") + '</span>', '<span class="badge ' + badgeClass(session.runtime?.status || "idle") + '">runtime ' + formatRuntime(session) + '</span>', (session.latestStatus?.taskTitle ? '<span class="badge accent">当前任务 ' + session.latestStatus.taskTitle + '</span>' : "")].filter(Boolean).join("");
+    const columnsHtml = STATUS_COLUMNS.map((column) => {
+      const tasks = grouped[column.key] || [];
+      return '<section class="column"><div><h3>' + column.label + '</h3><div class="column-count">' + tasks.length + ' 个任务</div></div><div class="cards">' + (tasks.length ? tasks.map((task) => renderTaskCard(task, session)).join("") : '<div class="empty">当前列为空</div>') + '</div></section>';
+    }).join("");
+    return '<section class="repo-board"><div class="repo-header"><div class="repo-header-top"><div><h2>' + session.repoName + '</h2><div class="repo-meta"><span>仓库：' + session.repoRoot + '</span><span>会话：' + session.sessionId + '</span></div></div><div class="repo-badges">' + repoBadges + '</div></div><div class="repo-meta"><span>当前动作：' + (session.activity?.current?.label || session.latestStatus?.message || session.runtime?.failureReason || "等待新事件") + '</span><span>宿主续跑：' + (session.hostResume?.issue?.label || (session.hostResume?.supervisorActive ? "后台仍在运行，可直接接续观察" : "需要按续跑提示继续")) + '</span></div></div><div class="columns">' + columnsHtml + '</div></section>';
+  }
+
+  function renderSnapshot(snapshot) {
+    currentSnapshot = snapshot;
+    renderStats(snapshot);
+    if (!Array.isArray(snapshot.sessions) || !snapshot.sessions.length) {
+      boardEl.innerHTML = '<section class="repo-board"><div class="repo-header"><h2>当前没有已登记仓库或后台会话</h2></div></section>';
+      return;
+    }
+    boardEl.innerHTML = snapshot.sessions.map(renderSessionBoard).join("");
+  }
+
+  function openDrawer(task, session) {
+    const docs = Array.isArray(task.docs) ? task.docs : [];
+    const paths = Array.isArray(task.paths) ? task.paths : [];
+    const acceptance = Array.isArray(task.acceptance) ? task.acceptance : [];
+    drawerContentEl.innerHTML = '<h3>' + (task.title || task.id || "未命名任务") + '</h3><div class="badges"><span class="badge accent">仓库 ' + session.repoName + '</span><span class="badge accent">优先级 ' + (task.priority || "P2") + '</span><span class="badge ' + badgeClass(task.status || "pending") + '">状态 ' + (task.status || "pending") + '</span><span class="badge ' + badgeClass(task.risk || "low") + '">风险 ' + (task.risk || "low") + '</span></div><div class="drawer-section"><h4>目标</h4><div>' + (task.goal || "无") + '</div></div><div class="drawer-section"><h4>文档</h4><ul class="drawer-list">' + (docs.length ? docs.map((item) => '<li>' + item + '</li>').join("") : "<li>无</li>") + '</ul></div><div class="drawer-section"><h4>路径</h4><ul class="drawer-list">' + (paths.length ? paths.map((item) => '<li>' + item + '</li>').join("") : "<li>无</li>") + '</ul></div><div class="drawer-section"><h4>验收</h4><ul class="drawer-list">' + (acceptance.length ? acceptance.map((item) => '<li>' + item + '</li>').join("") : "<li>无</li>") + '</ul></div>';
+    drawerEl.classList.add("open");
+  }
+
+  boardEl.addEventListener("click", (event) => {
+    const button = event.target.closest(".card");
+    if (!button) return;
+    const sessionId = decodeURIComponent(button.dataset.session || "");
+    const taskId = decodeURIComponent(button.dataset.task || "");
+    const session = (currentSnapshot.sessions || []).find((item) => item.sessionId === sessionId);
+    const task = (session?.tasks || []).find((item) => item.id === taskId);
+    if (session && task) openDrawer(task, session);
+  });
+
+  drawerCloseEl.addEventListener("click", () => drawerEl.classList.remove("open"));
+  window.addEventListener("keydown", (event) => { if (event.key === "Escape") drawerEl.classList.remove("open"); });
+
+  function connectEvents() {
+    const source = new EventSource("/events");
+    source.onmessage = (event) => { try { renderSnapshot(JSON.parse(event.data)); } catch (error) { console.error("snapshot parse failed", error); } };
+    source.onerror = () => { source.close(); setTimeout(connectEvents, 1500); };
+  }
+
+  renderSnapshot(currentSnapshot);
+  connectEvents();
+`;

package/src/dashboard_web_page.mjs

@@ -0,0 +1,49 @@
+import { DASHBOARD_WEB_CSS, DASHBOARD_WEB_JS } from "./dashboard_web_client.mjs";
+
+function escapeInlineJson(value) {
+  return JSON.stringify(value)
+    .replace(/</gu, "\\u003c")
+    .replace(/>/gu, "\\u003e")
+    .replace(/&/gu, "\\u0026");
+}
+
+export function renderDashboardWebHtml(options = {}) {
+  const initialSnapshot = options.initialSnapshot || {
+    generatedAt: "",
+    activeCount: 0,
+    taskTotals: {},
+    sessions: [],
+  };
+
+  return `<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>HelloLoop Dashboard</title>
+  <style>${DASHBOARD_WEB_CSS}</style>
+</head>
+<body>
+  <header>
+    <div class="title-row">
+      <div class="title">
+        <h1>HelloLoop Dashboard</h1>
+        <p>本地实时多仓开发看板。页面会持续订阅后台会话状态，不依赖宿主聊天流刷新。</p>
+      </div>
+      <div class="pill" id="update-pill">等待首帧</div>
+    </div>
+    <div class="stats-row">
+      <div class="stats" id="stats"></div>
+      <div class="pill" id="session-pill">仓库 0 · 活跃会话 0</div>
+    </div>
+  </header>
+  <main id="board"></main>
+  <aside class="drawer" id="drawer">
+    <button class="drawer-close" id="drawer-close">关闭</button>
+    <div id="drawer-content"></div>
+  </aside>
+  <script>window.__HELLOLOOP_INITIAL_SNAPSHOT__ = ${escapeInlineJson(initialSnapshot)};</script>
+  <script>${DASHBOARD_WEB_JS}</script>
+</body>
+</html>`;
+}