negotium 0.1.7 → 0.1.9

package/dist/runtime/src/runtime/usage-alert.ts

@@ -0,0 +1,84 @@
+/**
+ * Session-bloat alert.
+ *
+ * Adapted from the Telegram build's `telegram/topic/alert.ts`. After each AI turn
+ * we inspect the provider's latest-request context occupancy. Aggregate turn
+ * input is deliberately not used: a tool-heavy turn can make many cached model
+ * calls and report millions of billable input tokens while the actual context
+ * window remains mostly empty.
+ *
+ * Deliberately quiet: at most ONE alert per session lifetime (until the next
+ * `/new` clears it), so a long-running topic is never nagged turn after turn.
+ *
+ * The heavy lifting here (threshold, per-topic dedup, message text) is kept free
+ * of I/O so it unit-tests cleanly; the caller in `runtime/turn-runner.ts` handles
+ * the General/subagent guards and the actual posting.
+ */
+import type { TokenUsage } from "#types";
+
+const CONTEXT_ALERT_RATIO = 0.8;
+
+// Topics already warned this session, keyed by (user, topic) so the same topic
+// under different users tracks independently. Cleared on session reset (`/new`).
+const alerted = new Set<string>();
+
+const alertKey = (userId: string, topicId: string) => `${userId}:${topicId}`;
+
+/** Latest-request context occupancy, or null when the provider did not report it. */
+export function contextUsageRatio(usage: TokenUsage): number | null {
+  if (
+    usage.contextTokens === undefined ||
+    usage.contextWindow === undefined ||
+    !Number.isFinite(usage.contextTokens) ||
+    !Number.isFinite(usage.contextWindow) ||
+    usage.contextTokens < 0 ||
+    usage.contextWindow <= 0
+  ) {
+    return null;
+  }
+  return usage.contextTokens / usage.contextWindow;
+}
+
+function fmt(n: number): string {
+  return n >= 1_000_000 ? `${(n / 1_000_000).toFixed(1)}M` : `${Math.round(n / 1000)}K`;
+}
+
+function buildUsageAlertText(topicTitle: string, usage: TokenUsage): string {
+  const ratio = contextUsageRatio(usage) ?? 0;
+  const used = usage.contextTokens ?? 0;
+  const window = usage.contextWindow ?? 0;
+  return (
+    `⚠️ "${topicTitle}" context가 ${Math.round(ratio * 100)}% 찼어요 ` +
+    `(${fmt(used)} / ${fmt(window)} 토큰)\n\n` +
+    `이 토픽에서 /compact 를 입력하면 핵심 맥락을 요약해 이어가면서 context를 줄입니다. ` +
+    `완전히 새로 시작하려면 /new 를 사용하세요.\n\n` +
+    `두 명령 모두 지금까지 주고받은 보이는 대화 내역은 그대로 유지합니다.`
+  );
+}
+
+/**
+ * If the latest request filled at least 80% of the provider context window and
+ * the topic hasn't been warned yet this session, return the alert text and mark
+ * it warned; otherwise null. Fires at most once per session lifetime — the
+ * notice won't repeat turn after turn — and re-arms only after `/new` clears it.
+ */
+export function nextUsageAlert(
+  userId: string,
+  topicId: string,
+  topicTitle: string,
+  usage: TokenUsage,
+): string | null {
+  const ratio = contextUsageRatio(usage);
+  if (ratio === null || ratio < CONTEXT_ALERT_RATIO) return null;
+
+  const key = alertKey(userId, topicId);
+  if (alerted.has(key)) return null;
+  alerted.add(key);
+
+  return buildUsageAlertText(topicTitle, usage);
+}
+
+/** Re-arm the alert for a topic so a fresh session can warn again (called on `/new`). */
+export function clearQueryUsageAlert(userId: string, topicId: string): void {
+  alerted.delete(alertKey(userId, topicId));
+}

package/dist/runtime/src/runtime/visual-html.ts

@@ -0,0 +1,109 @@
+export const MERMAID_BROWSER_VERSION = "11.4.1";
+export const MERMAID_BROWSER_ASSET_PATH = `/api/v1/assets/mermaid-${MERMAID_BROWSER_VERSION}.min.js`;
+export const MERMAID_BROWSER_ASSET_RELATIVE_URL = `../../../../assets/mermaid-${MERMAID_BROWSER_VERSION}.min.js`;
+
+export type MermaidTheme = "default" | "neutral" | "dark" | "forest";
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+export function normalizeMermaidTheme(value: unknown): MermaidTheme {
+  return value === "default" || value === "dark" || value === "forest" ? value : "neutral";
+}
+
+/** Preserve the selected theme when a stored Mermaid document is rebuilt. */
+export function mermaidThemeFromHtml(html: string): MermaidTheme {
+  const match = html.match(/\btheme\s*:\s*["'](default|neutral|dark|forest)["']/i);
+  return normalizeMermaidTheme(match?.[1]?.toLowerCase());
+}
+
+/**
+ * Build a self-contained Mermaid viewer. Diagrams retain a readable minimum
+ * scale and scroll instead of being squeezed into a narrow side panel; quiet
+ * zoom controls remain available for large graphs.
+ */
+export function buildMermaidHtml(
+  code: string,
+  theme: MermaidTheme,
+  scriptUrl = MERMAID_BROWSER_ASSET_RELATIVE_URL,
+): string {
+  const safeCode = escapeHtml(code);
+  const safeTheme = JSON.stringify(theme);
+  const safeScriptUrl = escapeHtml(scriptUrl);
+  return `<!doctype html>
+<html data-otium-mermaid-version="3">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <style>
+    :root{color-scheme:light;--ink:#161614;--ivory:#F6F2EA;--surface:#FFFCF6;--graphite:#2C2D2A;--celadon:#A8BDB2;--border:#DDD7CD}
+    *{box-sizing:border-box}
+    html,body{margin:0;width:100%;min-height:100%;background:var(--ivory);color:var(--ink);font-family:Geist,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif}
+    body{overflow:hidden}
+    .viewport{width:100vw;height:100vh;min-height:260px;overflow:auto;padding:58px 24px 24px;scrollbar-gutter:stable}
+    .mermaid{display:flex;width:max-content;min-width:100%;justify-content:center;align-items:flex-start}
+    .mermaid svg{display:block;max-width:none!important;height:auto!important;flex:none}
+    .controls{position:fixed;z-index:2;top:12px;right:12px;display:flex;align-items:center;gap:2px;padding:3px;background:color-mix(in srgb,var(--surface) 94%,transparent);border:1px solid var(--border);border-radius:6px}
+    .controls button{height:28px;min-width:30px;padding:0 8px;border:0;border-radius:4px;background:transparent;color:var(--graphite);font:600 12px/1 Geist,system-ui,sans-serif;cursor:pointer}
+    .controls button:hover{background:color-mix(in srgb,var(--celadon) 24%,transparent)}
+    .controls button:focus-visible{outline:2px solid var(--celadon);outline-offset:1px}
+    .zoom-value{min-width:46px;color:var(--graphite);font:500 11px/1 Geist,system-ui,sans-serif;text-align:center;font-variant-numeric:tabular-nums}
+    .error{margin:0;white-space:pre-wrap;color:#7D2E2E;background:#FFF5F2;border:1px solid #E4B9B1;border-radius:6px;padding:14px;font:13px ui-monospace,SFMono-Regular,Menlo,monospace}
+    @media(max-width:600px){.viewport{padding:54px 14px 18px}.controls{top:10px;right:10px}}
+  </style>
+</head>
+<body>
+  <div class="controls" role="group" aria-label="Diagram zoom">
+    <button type="button" data-zoom-out aria-label="Zoom out">−</button>
+    <span class="zoom-value" aria-live="polite">100%</span>
+    <button type="button" data-zoom-in aria-label="Zoom in">+</button>
+    <button type="button" data-zoom-fit aria-label="Fit diagram">Fit</button>
+  </div>
+  <main class="viewport"><pre class="mermaid">${safeCode}</pre></main>
+  <script data-otium-mermaid-runtime src="${safeScriptUrl}"></script>
+  <script>
+    (async () => {
+      try {
+      const runtime = globalThis.mermaid;
+      if (!runtime) throw new Error("Mermaid renderer failed to load.");
+      runtime.initialize({ startOnLoad: false, securityLevel: "strict", theme: ${safeTheme} });
+      await runtime.run({ querySelector: ".mermaid" });
+      const viewport = document.querySelector(".viewport");
+      const svg = document.querySelector(".mermaid svg");
+      const value = document.querySelector(".zoom-value");
+      const bounds = svg && svg.viewBox && svg.viewBox.baseVal;
+      const naturalWidth = Math.max(1, Math.ceil((bounds && bounds.width) || (svg && svg.getBoundingClientRect().width) || 1));
+      let scale = Math.max(0.72, Math.min(1, (viewport.clientWidth - 48) / naturalWidth));
+      const applyScale = (next, center = true) => {
+        const previousWidth = naturalWidth * scale;
+        const centerRatio = previousWidth > viewport.clientWidth
+          ? (viewport.scrollLeft + viewport.clientWidth / 2) / previousWidth
+          : 0.5;
+        scale = Math.max(0.5, Math.min(2, next));
+        svg.style.width = Math.round(naturalWidth * scale) + "px";
+        svg.style.maxWidth = "none";
+        svg.style.height = "auto";
+        value.textContent = Math.round(scale * 100) + "%";
+        if (center) requestAnimationFrame(() => {
+          viewport.scrollLeft = Math.max(0, centerRatio * viewport.scrollWidth - viewport.clientWidth / 2);
+        });
+      };
+      document.querySelector("[data-zoom-out]").addEventListener("click", () => applyScale(scale - 0.1));
+      document.querySelector("[data-zoom-in]").addEventListener("click", () => applyScale(scale + 0.1));
+      document.querySelector("[data-zoom-fit]").addEventListener("click", () => applyScale(Math.min(1, (viewport.clientWidth - 48) / naturalWidth)));
+      applyScale(scale, false);
+      } catch (error) {
+        document.querySelector(".controls")?.remove();
+        document.querySelector(".viewport").innerHTML = '<pre class="error">' + String(error && error.message ? error.message : error).replace(/[&<>]/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;'}[c])) + '</pre>';
+      }
+    })();
+  </script>
+</body>
+</html>`;
+}

package/dist/runtime/src/runtime/visual-store.ts

@@ -0,0 +1,430 @@
+/** Visual (HTML snippet) storage for the Otium WebView renderer.
+ *
+ *  Each topic stores up to 10 visuals (newest-first); older ones are pruned.
+ *  Each user's active selection is tracked separately so multiple people in
+ *  the same topic can be on different visuals independently.
+ *
+ *  Port of the storage/prompt-context half of otium's `api/routes/visual.ts`;
+ *  the REST routes (serve HTML/media, CSP headers, list/select endpoints)
+ *  stayed in the host.
+ */
+import { randomUUID } from "node:crypto";
+import { db } from "#storage/forum-db";
+
+const MAX_HISTORY = 10;
+const MAX_VISUAL_TITLE_CHARS = 180;
+export const VISUAL_MEDIA_URL_PLACEHOLDER = "__NEGOTIUM_VISUAL_MEDIA_URL__";
+
+db.exec(`
+  CREATE TABLE IF NOT EXISTS api_topic_visuals (
+    id         INTEGER PRIMARY KEY AUTOINCREMENT,
+    topic_id   TEXT    NOT NULL,
+    html       TEXT    NOT NULL,
+    title      TEXT,
+    created_at INTEGER NOT NULL,
+    kind       TEXT    NOT NULL DEFAULT 'html',
+    source     TEXT,
+    file_id    TEXT,
+    mime_type  TEXT,
+    media_token TEXT
+  );
+  CREATE INDEX IF NOT EXISTS idx_api_topic_visuals_topic
+    ON api_topic_visuals(topic_id, created_at DESC);
+
+  CREATE TABLE IF NOT EXISTS api_topic_visual_views (
+    topic_id  TEXT NOT NULL,
+    user_id   TEXT NOT NULL,
+    visual_id INTEGER NOT NULL,
+    PRIMARY KEY (topic_id, user_id)
+  );
+`);
+
+for (const statement of [
+  "ALTER TABLE api_topic_visuals ADD COLUMN kind TEXT NOT NULL DEFAULT 'html'",
+  "ALTER TABLE api_topic_visuals ADD COLUMN source TEXT",
+  "ALTER TABLE api_topic_visuals ADD COLUMN file_id TEXT",
+  "ALTER TABLE api_topic_visuals ADD COLUMN mime_type TEXT",
+  "ALTER TABLE api_topic_visuals ADD COLUMN media_token TEXT",
+]) {
+  try {
+    db.exec(statement);
+  } catch {
+    // Column already exists.
+  }
+}
+
+// ── DB helpers ──────────────────────────────────────────────────────────────
+
+export const VISUAL_KINDS = ["html", "mermaid", "image", "video"] as const;
+export type VisualKind = (typeof VISUAL_KINDS)[number];
+
+type VisualRow = {
+  id: number;
+  topic_id: string;
+  html: string;
+  title: string | null;
+  created_at: number;
+  kind: VisualKind;
+  source: string | null;
+  file_id: string | null;
+  mime_type: string | null;
+  media_token: string | null;
+};
+type VisualListRow = {
+  id: number;
+  title: string | null;
+  created_at: number;
+  kind: VisualKind;
+  mime_type: string | null;
+};
+
+export function normalizeVisualTitle(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const normalized = value.replace(/\s+/g, " ").trim();
+  if (!normalized) return undefined;
+  return normalized.length > MAX_VISUAL_TITLE_CHARS
+    ? `${normalized.slice(0, MAX_VISUAL_TITLE_CHARS).trimEnd()}...`
+    : normalized;
+}
+
+function normalizeVisualKind(value: unknown): VisualKind {
+  return VISUAL_KINDS.includes(value as VisualKind) ? (value as VisualKind) : "html";
+}
+
+function insertVisual(input: {
+  topicId: string;
+  html: string;
+  title: string | null;
+  kind?: VisualKind;
+  source?: string | null;
+  fileId?: string | null;
+  mimeType?: string | null;
+  mediaToken?: string | null;
+}): number {
+  const result = db
+    .query<
+      { id: number },
+      [
+        string,
+        string,
+        string | null,
+        number,
+        string,
+        string | null,
+        string | null,
+        string | null,
+        string | null,
+      ]
+    >(
+      `INSERT INTO api_topic_visuals
+         (topic_id, html, title, created_at, kind, source, file_id, mime_type, media_token)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+       RETURNING id`,
+    )
+    .get(
+      input.topicId,
+      input.html,
+      input.title,
+      Date.now(),
+      input.kind ?? "html",
+      input.source ?? null,
+      input.fileId ?? null,
+      input.mimeType ?? null,
+      input.mediaToken ?? null,
+    );
+  if (!result) throw new Error("Failed to insert visual");
+  // Prune: keep only the newest MAX_HISTORY rows per topic.
+  db.query(
+    `DELETE FROM api_topic_visual_views
+     WHERE visual_id IN (
+       SELECT id FROM api_topic_visuals
+       WHERE topic_id = ? AND id NOT IN (
+         SELECT id FROM api_topic_visuals WHERE topic_id = ?
+         ORDER BY created_at DESC LIMIT ?
+       )
+     )`,
+  ).run(input.topicId, input.topicId, MAX_HISTORY);
+  db.query(
+    `DELETE FROM api_topic_visuals
+     WHERE topic_id = ? AND id NOT IN (
+       SELECT id FROM api_topic_visuals WHERE topic_id = ?
+       ORDER BY created_at DESC LIMIT ?
+     )`,
+  ).run(input.topicId, input.topicId, MAX_HISTORY);
+  return result.id;
+}
+
+function listVisuals(topicId: string): VisualListRow[] {
+  return db
+    .query<Omit<VisualListRow, "kind"> & { kind: string | null }, [string]>(
+      "SELECT id, title, created_at, kind, mime_type FROM api_topic_visuals WHERE topic_id = ? ORDER BY created_at DESC",
+    )
+    .all(topicId)
+    .map((row) => ({ ...row, kind: normalizeVisualKind(row.kind) }));
+}
+
+function getVisualById(id: number): VisualRow | null {
+  const row = db
+    .query<Omit<VisualRow, "kind"> & { kind: string | null }, [number]>(
+      "SELECT * FROM api_topic_visuals WHERE id = ?",
+    )
+    .get(id);
+  return row ? { ...row, kind: normalizeVisualKind(row.kind) } : null;
+}
+
+export function topicHasVisualFileId(topicId: string, fileId: string): boolean {
+  const row = db
+    .query<{ id: number }, [string, string]>(
+      "SELECT id FROM api_topic_visuals WHERE topic_id = ? AND file_id = ? LIMIT 1",
+    )
+    .get(topicId, fileId);
+  return Boolean(row);
+}
+
+function getUserActiveVisualId(topicId: string, userId: string): number | null {
+  const row = db
+    .query<{ visual_id: number }, [string, string]>(
+      "SELECT visual_id FROM api_topic_visual_views WHERE topic_id = ? AND user_id = ?",
+    )
+    .get(topicId, userId);
+  return row?.visual_id ?? null;
+}
+
+function setUserActiveVisualId(topicId: string, userId: string, visualId: number): void {
+  db.query(
+    `INSERT INTO api_topic_visual_views (topic_id, user_id, visual_id) VALUES (?, ?, ?)
+     ON CONFLICT(topic_id, user_id) DO UPDATE SET visual_id = excluded.visual_id`,
+  ).run(topicId, userId, visualId);
+}
+
+// ── Public helpers ──────────────────────────────────────────────────────────
+
+// Dark-step token values shared by the two dark selectors below (OS-auto via
+// media query, and the explicit data-viz-theme="dark" override). Single source
+// so the manual switch can never drift from the auto dark palette.
+const VIZ_DARK_TOKENS =
+  "--viz-surface:#1a1a1a;--viz-plane:#111111;--viz-text:#f2f2f0;--viz-text-secondary:#b6b8ae;--viz-muted:#8f938a;--viz-grid:#2a2a2a;--viz-axis:#3a3a38;--viz-border:rgba(255,255,255,.12);" +
+  "--viz-accent:#98ac83;--viz-accent-strong:#b3c49f;--viz-accent-soft:#2a3320;" +
+  "--viz-series-1:#98ac83;--viz-series-2:#9aa08f;--viz-series-3:#b0b4a8;--viz-series-4:#7f8f70;--viz-series-5:#d9dbcf;--viz-series-6:#c9d1bf;" +
+  "--viz-seq-100:#2f3a26;--viz-seq-200:#40513b;--viz-seq-300:#556845;--viz-seq-400:#6c7d57;--viz-seq-500:#8a9a74;--viz-seq-600:#a7b499;--viz-seq-700:#c9d1bf;" +
+  "--viz-good:#4caf50;--viz-warning:#d9a520;--viz-serious:#d98a5a;--viz-critical:#e06666;";
+
+// Base design tokens injected into every stored HTML visual so charts share one
+// clean, near-white look built around the olive accent #40513B, with a selected
+// dark-mode step (values chosen for the dark surface, validated for contrast and
+// CVD, not an automatic flip). Placed first in <head> so an agent's own styles
+// override the reset, while the --viz-* custom properties stay available to
+// reference. Values mirror prompts/sessions/visual-design.md; keep them in sync.
+//
+// Theme resolution: no data-viz-theme attribute → follow the OS
+// (prefers-color-scheme); data-viz-theme="light"/"dark" → forced by the in-viz
+// switch (see VISUAL_THEME_TOGGLE below).
+const VISUAL_BASE_STYLE = `<style id="viz-base">
+:root{color-scheme:light dark;
+--viz-surface:#ffffff;--viz-plane:#f6f6f4;--viz-text:#141414;--viz-text-secondary:#565b50;--viz-muted:#8a8f84;--viz-grid:#ececea;--viz-axis:#d7d7d2;--viz-border:rgba(20,20,20,.10);
+--viz-accent:#40513b;--viz-accent-strong:#2c3826;--viz-accent-soft:#eef1ea;
+--viz-series-1:#40513b;--viz-series-2:#8c9187;--viz-series-3:#6b7a5f;--viz-series-4:#b9bcb4;--viz-series-5:#2c3826;--viz-series-6:#a0a89a;
+--viz-seq-100:#eef1ea;--viz-seq-200:#d4dcca;--viz-seq-300:#9aab8c;--viz-seq-400:#77896a;--viz-seq-500:#566848;--viz-seq-600:#40513b;--viz-seq-700:#2c3826;
+--viz-good:#2e7d32;--viz-warning:#b8860b;--viz-serious:#bf6a3a;--viz-critical:#b23b3b;}
+@media (prefers-color-scheme:dark){:root:not([data-viz-theme=light]){${VIZ_DARK_TOKENS}}}
+:root[data-viz-theme=dark]{${VIZ_DARK_TOKENS}}
+:root[data-viz-theme=light]{color-scheme:light}
+:root[data-viz-theme=dark]{color-scheme:dark}
+*{box-sizing:border-box}
+html{background:var(--viz-surface)}
+html,body{margin:0;min-height:100%}
+body{font-family:system-ui,-apple-system,"Segoe UI",sans-serif;background:var(--viz-surface);color:var(--viz-text);-webkit-text-size-adjust:100%}
+</style>`;
+
+// Floating light/dark switch rendered inside every HTML visual. One inline
+// <script> (CSP already allows 'unsafe-inline' for html visuals) that injects
+// its own style, so upgrades and idempotency hinge on a single id. The button
+// shows the mode a click switches TO (moon while light, sun while dark) and
+// flips the data-viz-theme override consumed by VISUAL_BASE_STYLE above.
+// No persistence: sandboxed srcDoc iframes have no reliable localStorage, and
+// per-document lifetime matches how visuals are reopened from the store.
+const VISUAL_THEME_TOGGLE = `<script id="viz-theme-toggle">
+(function(){function init(){if(document.getElementById("viz-theme-toggle-btn"))return;
+var s=document.createElement("style");
+s.textContent="#viz-theme-toggle-btn{position:fixed;top:10px;right:10px;z-index:2147483647;width:30px;height:30px;border-radius:50%;border:1px solid var(--viz-border);background:var(--viz-plane);font:15px/1 system-ui;display:grid;place-items:center;cursor:pointer;opacity:.5;transition:opacity .15s;padding:0}#viz-theme-toggle-btn:hover{opacity:1}";
+document.head.appendChild(s);
+var b=document.createElement("button");b.id="viz-theme-toggle-btn";b.type="button";b.setAttribute("aria-label","Toggle color theme");
+var mq=window.matchMedia?window.matchMedia("(prefers-color-scheme: dark)"):null;
+function effective(){var f=document.documentElement.getAttribute("data-viz-theme");return f==="dark"||f==="light"?f:(mq&&mq.matches?"dark":"light")}
+function paint(){var dark=effective()==="dark";b.textContent=dark?"\\u2600\\uFE0F":"\\uD83C\\uDF19";b.title=dark?"Light mode":"Dark mode"}
+b.addEventListener("click",function(){document.documentElement.setAttribute("data-viz-theme",effective()==="dark"?"light":"dark");paint()});
+if(mq&&mq.addEventListener)mq.addEventListener("change",paint);
+paint();document.body.appendChild(b)}
+if(document.readyState==="loading")document.addEventListener("DOMContentLoaded",init);else init()})();
+</script>`;
+
+/**
+ * Bake the base design tokens + theme switch into an agent-provided HTML
+ * document so every visual shares one palette/reset regardless of render path
+ * (web srcDoc, desktop iframe, and native WebView all serve this stored HTML
+ * directly). Inserted at the top of <head> so agent styles win the cascade;
+ * the --viz-* variables are only added, never overriding what the agent set.
+ * Idempotent AND upgrading: a doc that already carries a baked block gets it
+ * swapped for the current version (so legacy stored visuals pick up the theme
+ * switch at serve time) instead of stacking a second copy.
+ */
+export function withVisualBaseStyle(html: string): string {
+  const inject = `${VISUAL_BASE_STYLE}${VISUAL_THEME_TOGGLE}`;
+  if (html.includes('id="viz-base"')) {
+    let out = html.replace(/<style id="viz-base">[\s\S]*?<\/style>/, VISUAL_BASE_STYLE);
+    out = out.includes('id="viz-theme-toggle"')
+      ? out.replace(/<script id="viz-theme-toggle">[\s\S]*?<\/script>/, VISUAL_THEME_TOGGLE)
+      : out.replace(VISUAL_BASE_STYLE, inject);
+    return out;
+  }
+  if (/<head(?:\s[^>]*)?>/i.test(html)) {
+    return html.replace(/<head(?:\s[^>]*)?>/i, (match) => `${match}${inject}`);
+  }
+  if (/<html(?:\s[^>]*)?>/i.test(html)) {
+    return html.replace(/<html(?:\s[^>]*)?>/i, (match) => `${match}<head>${inject}</head>`);
+  }
+  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">${inject}</head><body>${html}</body></html>`;
+}
+
+/** Persist a new visual and return its id. Called by the show_html tool path. */
+export function storeTopicVisual(
+  topicId: string,
+  html: string,
+  title?: string,
+  activeUserId?: string,
+): number {
+  const visualId = insertVisual({
+    topicId,
+    // Rendered document carries the house style; source stays the agent's own
+    // HTML so edit-context feedback isn't padded with our boilerplate.
+    html: withVisualBaseStyle(html),
+    title: normalizeVisualTitle(title) ?? null,
+    kind: "html",
+    source: html,
+  });
+  if (activeUserId) setUserActiveVisualId(topicId, activeUserId, visualId);
+  return visualId;
+}
+
+export function storeTopicMermaidVisual(
+  topicId: string,
+  code: string,
+  html: string,
+  title?: string,
+  activeUserId?: string,
+): number {
+  const visualId = insertVisual({
+    topicId,
+    html,
+    title: normalizeVisualTitle(title) ?? null,
+    kind: "mermaid",
+    source: code,
+  });
+  if (activeUserId) setUserActiveVisualId(topicId, activeUserId, visualId);
+  return visualId;
+}
+
+export function storeTopicMediaVisual(input: {
+  topicId: string;
+  kind: "image" | "video";
+  html: string;
+  title?: string;
+  fileId: string;
+  mimeType: string;
+  source?: string;
+  activeUserId?: string;
+}): number {
+  const visualId = insertVisual({
+    topicId: input.topicId,
+    html: input.html,
+    title: normalizeVisualTitle(input.title) ?? null,
+    kind: input.kind,
+    source: input.source ?? null,
+    fileId: input.fileId,
+    mimeType: input.mimeType,
+    mediaToken: randomUUID(),
+  });
+  if (input.activeUserId) setUserActiveVisualId(input.topicId, input.activeUserId, visualId);
+  return visualId;
+}
+
+/** Returns info for the system-prompt visual context section, or null if none. */
+export function getActiveVisualForPrompt(
+  topicId: string,
+  userId: string,
+): {
+  kind: VisualKind;
+  content: string;
+  fence: "html" | "mermaid" | "text";
+  title: string | null;
+  index: number;
+  total: number;
+} | null {
+  const rows = listVisuals(topicId);
+  if (rows.length === 0) return null;
+  const activeId = getUserActiveVisualId(topicId, userId) ?? rows[0]!.id;
+  const idx = rows.findIndex((r) => r.id === activeId);
+  const targetId = idx >= 0 ? activeId : rows[0]!.id;
+  const row = getVisualById(targetId);
+  if (!row) return null;
+  const total = rows.length;
+  const position = idx >= 0 ? idx + 1 : 1;
+  if (row.kind === "mermaid") {
+    return {
+      kind: row.kind,
+      content: row.source ?? row.html,
+      fence: "mermaid",
+      title: row.title,
+      index: position,
+      total,
+    };
+  }
+  if (row.kind === "image" || row.kind === "video") {
+    return {
+      kind: row.kind,
+      content: [
+        `${row.kind === "image" ? "Image" : "Video"} visual`,
+        row.title ? `title: ${row.title}` : null,
+        row.file_id ? `file_id: ${row.file_id}` : null,
+        row.mime_type ? `mime_type: ${row.mime_type}` : null,
+        "Binary media data is omitted from the prompt.",
+      ]
+        .filter(Boolean)
+        .join("\n"),
+      fence: "text",
+      title: row.title,
+      index: position,
+      total,
+    };
+  }
+  return {
+    kind: row.kind,
+    content: row.html,
+    fence: "html",
+    title: row.title,
+    index: position,
+    total,
+  };
+}
+
+/** Delete visual history and per-user selections for a hard-deleted topic. */
+export function deleteTopicVisuals(topicId: string): { visuals: number; views: number } {
+  return db.transaction(() => {
+    const views = db
+      .query("DELETE FROM api_topic_visual_views WHERE topic_id = ?")
+      .run(topicId).changes;
+    const visuals = db
+      .query("DELETE FROM api_topic_visuals WHERE topic_id = ?")
+      .run(topicId).changes;
+    return { visuals, views };
+  })();
+}
+
+/** URL that serves the HTML content for a specific visual id (used by iframe). */
+export function topicVisualUrl(topicId: string, vizId: number): string {
+  return `/api/v1/topics/${encodeURIComponent(topicId)}/visual/${vizId}/html`;
+}
+
+export function topicVisualMediaUrl(topicId: string, vizId: number, token: string): string {
+  return `/api/v1/topics/${encodeURIComponent(topicId)}/visual/${vizId}/media?token=${encodeURIComponent(token)}`;
+}