mulmoclaude 0.5.2 → 0.6.0

package/src/utils/chat/exportMarkdown.ts

@@ -0,0 +1,243 @@
+// Convert an in-memory chat session (a sequence of ToolResultComplete
+// items + per-uuid timestamps) into a self-contained Markdown document
+// suitable for pasting into a doc, an issue, or another chat.
+//
+// Each turn is rendered as a `## ⬜︎ Speaker · HH:MM` heading followed
+// by the message body, with `---` horizontal rules between turns.
+// Headings inside message bodies are demoted by 2 levels (e.g. an
+// assistant `# Heading` becomes `### Heading`) so the speaker headings
+// always sit above message-internal structure in the document outline.
+//
+// Tool calls (anything other than `text-response`) render as a `## ⬛︎
+// toolName HH:MM` heading — a compact marker showing which tools the
+// assistant invoked. Tool payloads are intentionally omitted to keep
+// the export readable; users wanting fidelity can view the raw JSONL.
+// The one exception is `presentDocument`: its `data.markdown` is
+// itself a piece of prose worth reading out of context, so we inline
+// the document body (demoted by 2 levels) under the marker. In real
+// sessions `data.markdown` is usually a workspace path
+// (`artifacts/documents/*.md`) rather than inline text, so the export
+// is async — callers pass a `readFile` resolver that reads the file
+// off the workspace, mirroring the in-app Markdown View's loader.
+
+import type { ToolResultComplete } from "gui-chat-protocol/vue";
+import { isRecord } from "../types";
+
+const TEXT_RESPONSE_TOOL = "text-response";
+const PRESENT_DOCUMENT_TOOL = "presentDocument";
+
+/** Heuristic for the file-path mode of presentDocument's `markdown` field
+ *  (server-side documents stored under `artifacts/documents/*.md`). When
+ *  matched, the value is a path — not inline content — and the export
+ *  has to read the file off the workspace via the caller-supplied
+ *  resolver to inline the body. */
+function looksLikeDocumentPath(value: string): boolean {
+  return value.endsWith(".md") && value.startsWith("artifacts/documents/");
+}
+
+const ROLE_LABELS = {
+  user: "⬜︎ You",
+  assistant: "⬛︎ Assistant",
+  system: "◇ System",
+} as const;
+
+type Role = keyof typeof ROLE_LABELS;
+
+export interface ExportChatOptions {
+  /** Friendly role / persona name shown in the document title (e.g. "General"). */
+  sessionRoleName?: string;
+  /** ISO string for the document's "Exported …" line. Defaults to `new Date()`. */
+  exportedAt?: string;
+  /** Per-uuid epoch-ms map matching `ActiveSession.resultTimestamps`. */
+  resultTimestamps?: Map<string, number>;
+  /** Resolver for workspace-relative file paths (currently the
+   *  `artifacts/documents/*.md` form used by presentDocument). Returns
+   *  the file's text content, or null if the read fails. Omit it to
+   *  skip file-mode resolution and emit only the marker line. */
+  readFile?: (path: string) => Promise<string | null>;
+}
+
+/** Format `epochMs` as `HH:MM` in 24h, locale-independent. */
+function formatHHMM(epochMs: number): string {
+  const date = new Date(epochMs);
+  const hours = String(date.getHours()).padStart(2, "0");
+  const minutes = String(date.getMinutes()).padStart(2, "0");
+  return `${hours}:${minutes}`;
+}
+
+/** Narrow `data?.role` to a known speaker label. Defaults to "assistant". */
+function roleOf(result: ToolResultComplete): Role {
+  const { data } = result;
+  // Own-property check via Object.prototype.hasOwnProperty so an
+  // inherited key on the runtime ROLE_LABELS object (e.g. `toString`,
+  // or anything that crawled in via Object.prototype pollution)
+  // can't satisfy the gate and produce a `## undefined` speaker line
+  // (#1065 review).
+  if (isRecord(data) && typeof data.role === "string" && Object.prototype.hasOwnProperty.call(ROLE_LABELS, data.role)) {
+    return data.role as Role;
+  }
+  return "assistant";
+}
+
+/** Pull the displayable text from a text-response result. Falls back to
+ *  `message` for older/saved sessions where `data.text` may be missing. */
+function textOf(result: ToolResultComplete): string {
+  const { data } = result;
+  if (isRecord(data) && typeof data.text === "string") return data.text;
+  return result.message ?? "";
+}
+
+function isTextResponse(result: ToolResultComplete): boolean {
+  return result.toolName === TEXT_RESPONSE_TOOL;
+}
+
+// Allow up to 3 leading spaces before the fence run, per GFM. A
+// 4-space indent is a regular indented code block and isn't a fence
+// in the first place; the heading-demotion path doesn't need to skip
+// inside those because they preserve the literal characters anyway,
+// but a real fence indented by 1-3 spaces (legal GFM) would
+// previously slip past `matchFenceRun` and any `# heading` line
+// inside got mistakenly demoted (#1065 review).
+const FENCE_RUN_RE = /^ {0,3}(`{3,}|~{3,})/;
+const ATX_HEADING_RE = /^(#{1,6})([ \t].*)$/;
+
+interface OpenFence {
+  char: "`" | "~";
+  len: number;
+}
+
+/** Match the leading run of fence characters on `line` (allowing up
+ *  to 3 leading spaces, per GFM), if any. Captures the fence char +
+ *  length so the closing logic can apply GFM's rules (close fence
+ *  must be the same char and at least as long as the open). */
+function matchFenceRun(line: string): OpenFence | null {
+  const match = FENCE_RUN_RE.exec(line);
+  if (!match) return null;
+  const [, run] = match;
+  return { char: run[0] as "`" | "~", len: run.length };
+}
+
+/** A line closes `open` only when it uses the same fence char, has at
+ *  least as many of them, and carries no info-string after the run.
+ *  Anything else inside the fence is content (including a different
+ *  fence type or a shorter run). The fence run can sit after up to
+ *  3 leading spaces; the closing check looks at content after the
+ *  fence run wherever it lands on the line. */
+function isClosingFence(line: string, fence: OpenFence, open: OpenFence): boolean {
+  if (fence.char !== open.char) return false;
+  if (fence.len < open.len) return false;
+  const runStart = line.search(/[`~]/);
+  return runStart >= 0 ? line.slice(runStart + fence.len).trim() === "" : false;
+}
+
+/** Demote every ATX heading inside `markdown` by `levels` (`#` → `#`+levels),
+ *  capping at h6. Skips lines inside fenced code blocks so `# comment`
+ *  lines in code samples are left alone. Honours GFM fence rules: a
+ *  block opened with N backticks (or N tildes) only closes on a line of
+ *  the same character with ≥N of them and nothing else, so nested
+ *  shorter fences and the opposite fence char both count as content. */
+function demoteHeadings(markdown: string, levels: number): string {
+  if (levels <= 0 || markdown.length === 0) return markdown;
+  const out: string[] = [];
+  let openFence: OpenFence | null = null;
+  for (const line of markdown.split(/\r\n|\r|\n/)) {
+    const fence = matchFenceRun(line);
+    if (openFence !== null) {
+      if (fence !== null && isClosingFence(line, fence, openFence)) {
+        openFence = null;
+      }
+      out.push(line);
+      continue;
+    }
+    if (fence !== null) {
+      openFence = fence;
+      out.push(line);
+      continue;
+    }
+    const match = ATX_HEADING_RE.exec(line);
+    if (!match) {
+      out.push(line);
+      continue;
+    }
+    const [, hashes, rest] = match;
+    const newDepth = Math.min(6, hashes.length + levels);
+    out.push(`${"#".repeat(newDepth)}${rest}`);
+  }
+  return out.join("\n");
+}
+
+function renderTextTurn(result: ToolResultComplete, timestamps: Map<string, number>): string {
+  const role = roleOf(result);
+  const epochMs = timestamps.get(result.uuid);
+  // Use `!== undefined` rather than truthiness so a 0 (Unix epoch)
+  // timestamp still renders. Practically irrelevant for live chat, but
+  // it removes a foot-gun for any synthetic / migrated session that
+  // ends up with that boundary value.
+  const time = epochMs !== undefined ? ` · ${formatHHMM(epochMs)}` : "";
+  // Speaker is `##`; demote any in-body heading by 2 so it always sits
+  // strictly below the speaker (`#` → `###`, `##` → `####`, …).
+  const body = demoteHeadings(textOf(result).trim(), 2);
+  return body.length > 0 ? `## ${ROLE_LABELS[role]}${time}\n\n${body}` : `## ${ROLE_LABELS[role]}${time}`;
+}
+
+/** Resolve presentDocument's `data.markdown` to inline content. If the
+ *  value is a workspace path, defer to `readFile`; otherwise treat it
+ *  as inline markdown. Returns null when the data is missing/empty or
+ *  the file read fails. */
+async function presentDocumentBody(result: ToolResultComplete, readFile: ExportChatOptions["readFile"]): Promise<string | null> {
+  const { data } = result;
+  if (!isRecord(data)) return null;
+  const { markdown } = data;
+  if (typeof markdown !== "string" || markdown.length === 0) return null;
+  if (!looksLikeDocumentPath(markdown)) return markdown;
+  if (!readFile) return null;
+  // Honour the documented "returns null on failure" contract — a
+  // single rejected resolver shouldn't blow up the whole export.
+  try {
+    return await readFile(markdown);
+  } catch {
+    return null;
+  }
+}
+
+async function renderToolTurn(result: ToolResultComplete, timestamps: Map<string, number>, readFile: ExportChatOptions["readFile"]): Promise<string> {
+  const epochMs = timestamps.get(result.uuid);
+  const time = epochMs !== undefined ? ` ${formatHHMM(epochMs)}` : "";
+  const marker = `## ⬛︎ ${result.toolName}${time}`;
+
+  if (result.toolName === PRESENT_DOCUMENT_TOOL) {
+    const documentBody = await presentDocumentBody(result, readFile);
+    if (documentBody !== null) {
+      return `${marker}\n\n${demoteHeadings(documentBody.trim(), 2)}`;
+    }
+  }
+
+  return marker;
+}
+
+/** Build the document header. Title and the "Exported" subtitle are
+ *  intentionally plain — the conversation body is what the reader cares
+ *  about. The horizontal rule separates header from first turn. */
+function renderHeader(opts: ExportChatOptions): string {
+  const role = opts.sessionRoleName?.trim();
+  const exportedAt = new Date(opts.exportedAt ?? new Date().toISOString());
+  const dateStamp = exportedAt.toISOString().slice(0, 16).replace("T", " ");
+  const title = role ? `# Conversation · ${role}` : "# Conversation";
+  return `${title}\n\n*Exported ${dateStamp} UTC*\n\n---`;
+}
+
+/** Convert a chat session to a Markdown string. Async because
+ *  presentDocument's body may live on disk and need a `readFile` round
+ *  trip. Returns at minimum a non-empty header so callers never have
+ *  to special-case empty sessions. */
+export async function exportChatToMarkdown(results: readonly ToolResultComplete[], options: ExportChatOptions = {}): Promise<string> {
+  const timestamps = options.resultTimestamps ?? new Map<string, number>();
+  const turns = await Promise.all(
+    results.map((result) =>
+      isTextResponse(result) ? Promise.resolve(renderTextTurn(result, timestamps)) : renderToolTurn(result, timestamps, options.readFile),
+    ),
+  );
+  const body = turns.join("\n\n---\n\n");
+  const header = renderHeader(options);
+  return body.length > 0 ? `${header}\n\n${body}\n` : `${header}\n`;
+}

package/src/utils/errors.ts

@@ -6,13 +6,21 @@
 // `err instanceof Error ? err.message : String(err)` — searching for
 // one canonical helper is easier than grepping for the inline form.
 //
+// Non-Error objects with a `details` (gRPC convention) or `message`
+// string field have that field surfaced — without this, gRPC errors
+// like `{ code, details, metadata }` show up as `[object Object]`.
+//
 // The optional `fallback` covers the common idiom of surfacing a
 // descriptive message ("Invalid JSON", "Connection error.") when a
-// throw turns out to be a non-Error value — otherwise `String(err)`
-// yields noise like `[object Object]`.
+// throw turns out to be a non-Error value.
 
 export function errorMessage(err: unknown, fallback?: string): string {
   if (err instanceof Error) return err.message;
+  if (err !== null && typeof err === "object") {
+    const obj = err as { details?: unknown; message?: unknown };
+    if (typeof obj.details === "string" && obj.details) return obj.details;
+    if (typeof obj.message === "string" && obj.message) return obj.message;
+  }
   if (fallback !== undefined) return fallback;
   return String(err);
 }

package/src/utils/files/expandedDirs.ts

@@ -6,7 +6,7 @@ export const EXPANDED_DIRS_STORAGE_KEY = "files_expanded_dirs";
 // Default: only the workspace root ("") is expanded — matches the
 // pre-persistence behavior of FileTree.vue, where nested dirs start
 // collapsed so opening Files mode doesn't render the whole tree.
-const DEFAULT_EXPANDED: ReadonlyArray<string> = [""];
+const DEFAULT_EXPANDED: readonly string[] = [""];
 
 export function parseStoredExpandedDirs(raw: string | null): Set<string> {
   if (raw === null) return new Set(DEFAULT_EXPANDED);

package/src/utils/filesPreview/todoPreview.ts

@@ -3,10 +3,21 @@
 // Extracted from FilesView.vue (#507 step 8).
 
 import type { ToolResultComplete } from "gui-chat-protocol/vue";
-import type { StatusColumn, TodoData, TodoItem } from "../../plugins/todo/index";
+import type { StatusColumn, TodoData, TodoItem } from "@mulmoclaude/todo-plugin/shared";
 import { WORKSPACE_FILES } from "../../config/workspacePaths";
 import { isRecord } from "../types";
 
+// `WORKSPACE_FILES.todosItems` lives under
+// `data/plugins/%40mulmoclaude%2Ftodo-plugin/todos.json` — the
+// directory name is the URL-encoded npm package (#1145). When the
+// path round-trips through Vue Router (deep-link via the URL bar),
+// the encoded segment gets decoded once to `@mulmoclaude/todo-plugin`,
+// so a strict equality check against the literal constant misses
+// that case. Compare against both encoded and decoded forms so the
+// comparison works for both router-decoded deep links and
+// tree-click flows that preserve the encoded literal.
+const TODOS_ITEMS_PATHS: ReadonlySet<string> = new Set([WORKSPACE_FILES.todosItems, decodeURIComponent(WORKSPACE_FILES.todosItems)]);
+
 function isTodoItem(value: unknown): value is TodoItem {
   if (!isRecord(value)) return false;
   if (typeof value["id"] !== "string" || typeof value["text"] !== "string") return false;
@@ -20,7 +31,7 @@ function isTodoItemArray(value: unknown): value is TodoItem[] {
 }
 
 export function toTodoExplorerResult(selectedPath: string | null, rawText: string | null): ToolResultComplete<TodoData> | null {
-  if (selectedPath !== WORKSPACE_FILES.todosItems) return null;
+  if (selectedPath === null || !TODOS_ITEMS_PATHS.has(selectedPath)) return null;
   if (rawText === null) return null;
   let parsed: unknown;
   try {

package/src/utils/format/date.ts

@@ -5,9 +5,7 @@
 /** "Apr 11 06:32" — short month + day + 24h time. */
 export function formatDate(iso: string): string {
   const date = new Date(iso);
-  return (
-    date.toLocaleDateString(undefined, { month: "short", day: "numeric" }) + " " + date.toLocaleTimeString(undefined, { hour: "2-digit", minute: "2-digit" })
-  );
+  return `${date.toLocaleDateString(undefined, { month: "short", day: "numeric" })} ${date.toLocaleTimeString(undefined, { hour: "2-digit", minute: "2-digit" })}`;
 }
 
 /** "Apr 11 06:32" — same format as formatDate but from epoch ms. */

package/src/utils/format/jsonSyntax.ts

@@ -25,6 +25,11 @@ export const JSON_TOKEN_CLASS: Record<JsonTokenType, string> = {
 // sonarjs/regex-complexity and is easier to reason about.
 const STRING_RE = /^"(?:[^"\\]|\\.)*"/;
 const KEYWORD_RE = /^(?:true|false|null)\b/;
+// Bounded JSON number parser — each `\d+` runs over a digits-only
+// class with hard delimiters (`.`, `e`, `E`, `+`, `-`) between
+// segments. Linear in input length; safe-regex flags the optional
+// groups generically.
+// eslint-disable-next-line security/detect-unsafe-regex -- bounded JSON number parser, no nested-quantifier overlap
 const NUMBER_RE = /^-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/;
 const WS_RE = /^\s+/;
 const PUNCT_RE = /^[{}[\]:,]/;

package/src/utils/html/iframeHeightReporterScript.ts

@@ -0,0 +1,62 @@
+// Tiny inline script injected into every `/artifacts/html/...` document
+// so the parent (StackView in chat) can size each iframe to its
+// rendered content height — despite the sandbox treating the iframe as
+// cross-origin (#1219 follow-up).
+//
+// Why this matters: presentHtml's iframe runs with
+// `sandbox="allow-scripts"` (deliberate — `allow-same-origin` would let
+// LLM-generated HTML read the parent's cookies / localStorage / bearer
+// token). Without `allow-same-origin`, the parent's
+// `iframe.contentDocument.documentElement.scrollHeight` access throws
+// cross-origin, leaving the iframe at the browser-default 150px and
+// clipping the actual chart / Sankey / report inside.
+//
+// The reporter runs INSIDE the iframe (under its null origin), reads
+// only its own document height, and posts a message to its parent. The
+// parent then sets `iframe.style.height` from the reported value. No
+// parent state is exposed to the iframe.
+//
+// Posts on initial `load`, on every subsequent body resize (charts that
+// populate after DOMContentLoaded, web-font settling, etc.), and once
+// more on `DOMContentLoaded` so the first paint is also sized.
+//
+// On iframe WIDTH changes:
+//
+// 1. Fires a synthetic `window.resize` event so libraries hooked into
+//    that signal (Chart.js, ECharts, custom code) get the nudge.
+// 2. Calls `Plotly.Plots.resize` on every `.js-plotly-plot` /
+//    `.plotly-graph-div` element if Plotly is loaded. Plotly v2's
+//    `responsive: true` is supposed to catch this via its own
+//    ResizeObserver, but in the sandboxed iframe context the observer
+//    sometimes misses the change. Calling resize directly is the
+//    documented escape hatch and a no-op when the chart was already
+//    correctly sized. Gated on `window.Plotly` so HTML pages without
+//    Plotly are unaffected.
+//
+// Pairs with the listener in `src/components/StackView.vue`. Message
+// shape: `{ type: "mc-iframe-height", height: <pixels> }`. The listener
+// matches the iframe via `event.source === iframe.contentWindow`, then
+// `iframe.style.setProperty("height", "<n>px", "important")` (the
+// `!important` defeats the stack-natural `:deep(.h-full)` override).
+
+const REPORTER_SCRIPT = `(()=>{const p=()=>{try{parent.postMessage({type:"mc-iframe-height",height:document.documentElement.scrollHeight},"*")}catch(e){}};const r=()=>{try{window.dispatchEvent(new Event("resize"))}catch(e){}try{const P=window.Plotly;if(P&&P.Plots&&P.Plots.resize){document.querySelectorAll(".js-plotly-plot,.plotly-graph-div").forEach(el=>{try{P.Plots.resize(el)}catch(e){}})}}catch(e){}};addEventListener("DOMContentLoaded",p);addEventListener("load",p);if(window.ResizeObserver&&document.documentElement){let w=0;new ResizeObserver((es)=>{p();const nw=es[0]&&es[0].contentRect?es[0].contentRect.width:0;if(nw&&nw!==w){w=nw;r()}}).observe(document.documentElement)}})();`;
+
+export const HEIGHT_REPORTER_SCRIPT_TAG = `<script>${REPORTER_SCRIPT}</script>`;
+
+const BODY_CLOSE_RE = /<\/body\s*>/gi;
+
+/** Splice the height-reporter `<script>` tag immediately before the
+ *  document's last `</body>`. Pure string operation — no DOM parsing,
+ *  linear time in input length, idempotent in effect (the script is
+ *  one-shot; duplicates produce duplicate postMessages, the parent
+ *  listener handles them identically). When `</body>` is missing
+ *  (server-streamed HTML, partial output, hand-written fragment), the
+ *  tag is appended at the end so the script still loads. */
+export function injectHeightReporterScript(html: string): string {
+  if (!html) return html;
+  const matches = [...html.matchAll(BODY_CLOSE_RE)];
+  if (matches.length === 0) return html + HEIGHT_REPORTER_SCRIPT_TAG;
+  const idx = matches[matches.length - 1].index;
+  if (idx === undefined) return html + HEIGHT_REPORTER_SCRIPT_TAG;
+  return `${html.slice(0, idx)}${HEIGHT_REPORTER_SCRIPT_TAG}${html.slice(idx)}`;
+}

package/src/utils/html/previewCsp.ts

@@ -14,14 +14,31 @@ export const HTML_PREVIEW_CSP_ALLOWED_CDNS: readonly string[] = [
   "https://cdnjs.cloudflare.com",
   "https://fonts.googleapis.com",
   "https://fonts.gstatic.com",
+  // Plotly's official CDN. The LLM defaults to this URL when it
+  // includes a Sankey or other Plotly chart in presentHtml output —
+  // Plotly's docs recommend it, so unconditioned LLM output ends up
+  // pointing here. Also reachable through jsdelivr, but adding the
+  // first-party CDN keeps historical artifacts (where the URL is
+  // already baked into the file on disk) rendering correctly.
+  "https://cdn.plot.ly",
 ];
 
 /**
  * Build the CSP string. Split from the wrapper so tests can exercise
  * the policy without HTML-template noise.
+ *
+ * `origin`, when provided, replaces `'self'` in `img-src`. The preview
+ * iframe is `sandbox="allow-scripts"` only, so its document has an
+ * opaque origin: Safari/WebKit matches `'self'` against the (opaque)
+ * origin tuple and rejects every same-origin image request. Chrome
+ * matches `'self'` against the document URL and works either way. Pass
+ * the explicit server origin from HTTP-header callers; leave it
+ * undefined for the `srcdoc` fallback (where `'self'` is meaningless
+ * either way and there are no same-origin refs to resolve).
  */
-export function buildHtmlPreviewCsp(cdns: readonly string[] = HTML_PREVIEW_CSP_ALLOWED_CDNS): string {
+export function buildHtmlPreviewCsp(origin?: string, cdns: readonly string[] = HTML_PREVIEW_CSP_ALLOWED_CDNS): string {
   const cdnList = cdns.join(" ");
+  const imgSelf = origin ?? "'self'";
   return [
     "default-src 'none'",
     // LLM-authored HTML almost always uses inline <script> blocks
@@ -37,13 +54,23 @@ export function buildHtmlPreviewCsp(cdns: readonly string[] = HTML_PREVIEW_CSP_A
     // could exfiltrate data via image requests even with connect-src
     // blocked. Widen via HTML_PREVIEW_CSP_ALLOWED_CDNS if LLM output
     // legitimately needs more hosts.
-    `img-src 'self' ${cdnList} data: blob:`,
+    `img-src ${imgSelf} ${cdnList} data: blob:`,
     // Block XHR / fetch / WebSocket so previews can't phone home or
     // exfiltrate anything the inline scripts happen to compute.
     "connect-src 'none'",
   ].join("; ");
 }
 
+/**
+ * Build the CSP string for the print-mode hidden iframe (presentHtml's
+ * printToPdf). Same policy as the preview header with the explicit
+ * server origin substituted for `'self'` — see `buildHtmlPreviewCsp`
+ * for why the substitution is required.
+ */
+export function buildPrintCspContent(origin: string, cdns: readonly string[] = HTML_PREVIEW_CSP_ALLOWED_CDNS): string {
+  return buildHtmlPreviewCsp(origin, cdns);
+}
+
 const CSP_META_NONCE = ""; // reserved for future use (per-render nonce)
 
 /**

package/src/utils/image/htmlSrcAttrs.ts

@@ -0,0 +1,122 @@
+// Shared HTML-tag URL rewriter — used by:
+//   - browser markdown surface (`rewriteImgSrcAttrsInHtml` in
+//     `rewriteMarkdownImageRefs.ts`) → rewrites to
+//     `/api/files/raw?path=...`
+//   - server PDF surface (`inlineImages` in
+//     `server/api/routes/pdf.ts`) → rewrites to `data:` URIs
+//
+// Both used to keep their own copy of the same regex shape with a
+// `// Mirrors the shape used by …` comment. That mirroring drifts the
+// moment one side adds a tag (`<source>`, `<video poster>`) and the
+// other doesn't. Single helper here, two callers, one tag list — the
+// drift becomes structurally impossible (#1011 Stage B).
+//
+// `srcset` (comma-separated descriptor list) and SVG `<image href>` /
+// CSS `url()` are deliberately out of scope — see the deferred-list
+// comment on `RESOLVABLE_TAG_ATTRS` below.
+
+// Tag (lowercased) → URL-bearing attribute(s). Adding a row here
+// extends both Markdown and PDF surfaces simultaneously.
+//
+// Deferred (NOT here):
+//   - `srcset` on `<img>` / `<source>` — comma-separated list with
+//     descriptors (`url 1x, url2 2x`), needs a separate split/rewrite
+//     pass. Tracked under #1011 Stage B follow-up.
+//   - SVG `<image href>` — gap table item #9, low priority per plan
+//     §修正提案 P3-A.
+//   - CSS `url()` in `style=` attributes — gap table item #8, same
+//     priority.
+export const RESOLVABLE_TAG_ATTRS: Readonly<Record<string, readonly string[]>> = {
+  img: ["src"],
+  source: ["src"],
+  video: ["poster", "src"],
+  audio: ["src"],
+};
+
+// Outer regex: scan any tag whose name appears in `RESOLVABLE_TAG_ATTRS`,
+// respecting quoted attribute values so `>` inside e.g. `alt="x>y"`
+// doesn't terminate the tag early. The body is one of:
+//   - any non-`>` non-quote char     `[^>"']`
+//   - a complete double-quoted span  `"[^"]*"`
+//   - a complete single-quoted span  `'[^']*'`
+// All branches bounded — no nested quantifiers, no overlap.
+//
+// The tag-name alternation is hand-listed rather than computed from
+// `Object.keys(RESOLVABLE_TAG_ATTRS)` so the regex is a const string
+// (lint-friendly) and the alternation order matches the readable
+// declaration order. Adding a tag means: update the map AND the
+// alternation here. The unit test in test_htmlSrcAttrs.ts pins this
+// in lockstep so the two never disagree silently.
+//
+// eslint-disable-next-line security/detect-unsafe-regex -- bounded alternatives, ReDoS-safe (test in test_htmlSrcAttrs.ts)
+const RESOLVABLE_TAG_OUTER_RE = /<(?:img|source|video|audio)\b(?:[^>"']|"[^"]*"|'[^']*')*\/?>/gi;
+// Tag-name extractor for the matched outer tag. Anchored so we only
+// read the leading `<name`, never an attribute value that happens to
+// look like a tag.
+const TAG_NAME_RE = /^<([a-z]+)/i;
+
+// Attribute iterator: walks each `name=value` pair inside a tag. The
+// leading `\s+` ensures we only match real attribute boundaries, not
+// `src=` text embedded inside another attribute's quoted value.
+// Capture groups:
+//   1: leading whitespace
+//   2: attribute name
+//   3: `=` with surrounding spaces (only when value present)
+//   4: full quoted/unquoted value (unused but captured for clarity)
+//   5: double-quoted value (without quotes)
+//   6: single-quoted value (without quotes)
+//   7: unquoted value — refuses leading `"` / `'` so a malformed
+//      `<img src="aaaa` (no closing quote) doesn't capture the stray
+//      quote as the value
+//
+// All quantifiers bounded — verified ReDoS-safe in test_htmlSrcAttrs.ts.
+// eslint-disable-next-line sonarjs/slow-regex, sonarjs/regex-complexity, security/detect-unsafe-regex -- bounded quantifiers, ReDoS-safe (test in test_htmlSrcAttrs.ts)
+const ATTR_ITER_RE = /(\s+)([A-Za-z][\w:-]*)(?:(\s*=\s*)("([^"]*)"|'([^']*)'|([^\s>"'][^\s>]*)))?/g;
+
+/** Transform every URL-bearing attribute on a recognised tag.
+ *
+ *  `transform` is invoked once per matching attribute value. Return:
+ *    - `string` to substitute the value (callee is responsible for
+ *      not breaking out of the surrounding quotes — most callers
+ *      route through `encodeURIComponent` or a fixed-prefix path)
+ *    - `null` to leave the attribute untouched (e.g. external URL,
+ *      `data:` URI, escape-the-workspace path)
+ *
+ *  Other attributes (alt, class, style, …) and `src=`-shaped text
+ *  inside their quoted values are preserved verbatim because we
+ *  parse attribute-by-attribute, not by free-form regex.
+ *
+ *  Recognised tags + attributes live in `RESOLVABLE_TAG_ATTRS`. Any
+ *  tag whose name isn't in the map is returned untouched. Any
+ *  attribute on a recognised tag whose name isn't in the map's entry
+ *  is also untouched. */
+export function transformResolvableUrlsInHtml(html: string, transform: (url: string) => string | null): string {
+  if (!html) return html;
+  return html.replace(RESOLVABLE_TAG_OUTER_RE, (tag) => {
+    const tagNameMatch = TAG_NAME_RE.exec(tag);
+    if (!tagNameMatch) return tag;
+    const resolvableAttrs = RESOLVABLE_TAG_ATTRS[tagNameMatch[1].toLowerCase()];
+    if (!resolvableAttrs) return tag;
+    return tag.replace(ATTR_ITER_RE, (...captures: unknown[]) => replaceAttrIfResolvable(captures, resolvableAttrs, transform));
+  });
+}
+
+function replaceAttrIfResolvable(captures: unknown[], resolvableAttrs: readonly string[], transform: (url: string) => string | null): string {
+  const [full, leading, name, eqWithSpaces, , doubleQuoted, singleQuoted, bare] = captures as [
+    string,
+    string,
+    string,
+    string | undefined,
+    string | undefined,
+    string | undefined,
+    string | undefined,
+    string | undefined,
+  ];
+  if (!eqWithSpaces || !resolvableAttrs.includes(name.toLowerCase())) return full;
+  const value = (doubleQuoted ?? singleQuoted ?? bare ?? "").trim();
+  if (!value) return full;
+  const replacement = transform(value);
+  if (replacement === null) return full;
+  const quote = doubleQuoted !== undefined ? '"' : singleQuoted !== undefined ? "'" : '"';
+  return `${leading}${name}${eqWithSpaces}${quote}${replacement}${quote}`;
+}