synabun 2.0.9 → 2.0.10

package/neural-interface/public/shared/assistant/asst-run-stage.js

@@ -0,0 +1,231 @@
+// ═══════════════════════════════════════════
+// SynaBun Assistant — a worker's stage in its run card
+// ═══════════════════════════════════════════
+// While a dispatched run works (queued, starting, running a turn), its run
+// card in the transcript opens a stage: the mascot acting out the run's
+// scene (asst-scenes.js: its task class, or what its current tool call does),
+// the scene beside it and the worker's step. The run's elapsed time has one
+// place, the card's details line (asst-render.js ticks it with the stage's
+// beat), so the stage repeats no clock. The stage belongs to
+// the run, not to the Assistant's turn: it stays open and moving after the
+// turn that dispatched the run has ended, through new turns and messages,
+// card updates (it is built once and updated in place), a hidden panel (the
+// rig parks off screen and comes back by itself) and a reload (the renderer
+// restores the card). Waiting on you it holds a calm blocked frame; once the
+// run settles (its turn done, or the run ended) it shows the final frame,
+// holds it, and folds into the card's compact form; a new turn opens it
+// again.
+//
+// One rig per open stage on the shared ticker; the accessible name (whole
+// minutes) and the gaze or pop beats some scenes use run on the renderer's
+// 1 Hz beat (tick()), never a loop of their own. Styles:
+// asst-scene-styles.js.
+
+import * as mascotLib from '../synabun-mascot.js';
+import { isTerminalRunStatus } from './asst-state.js';
+import { SCENE_SPECS, compactActivity, finalFrame, isLivePhase, phaseLine, sceneFor, sceneSvg, stageLabel, stagePhase, stepLine } from './asst-scenes.js';
+
+export const STAGE_TIMING = Object.freeze({
+  settleHoldMs: 1400, // the final frame shows this long before the stage folds
+  foldMs: 260, // the fold, then the rig goes
+  sceneDwellMs: 2500, // a scene the activity picked stays at least this long
+});
+
+const GAZE = {
+  pointer: [[0.9, 0.25], [0.55, -0.35], [1, 0.45], [0.7, 0]],
+  canvas: [[0.8, -0.2], [0.95, 0.25], [0.7, 0.05]],
+  strip: [[0.35, 0], [0.75, 0.05], [1, 0], [0.75, -0.05]],
+};
+
+/**
+ * createWorkerStage(card, { t, calm, now, mascot })
+ * Builds the stage (closed) after the card's meta row. update(run) opens it
+ * for a live phase and settles it otherwise; tick(now) is the 1 Hz beat.
+ * Returns { el, update(run), setActivity(activity), tick(now), live(), state(), destroy() }.
+ */
+export function createWorkerStage(card, { t = (_key, fallback) => fallback, calm = () => false, now = () => Date.now(), mascot = mascotLib } = {}) {
+  const wrap = document.createElement('div');
+  wrap.className = 'asst-run-stage-wrap';
+  wrap.innerHTML = '<div class="asst-run-stage" role="img">'
+    + '<div class="asst-run-stage-face" aria-hidden="true"></div>'
+    + '<div class="asst-run-stage-scene" aria-hidden="true"></div>'
+    + '<div class="asst-run-stage-line" aria-hidden="true"><span class="asst-run-stage-step"></span></div>'
+    + '<div class="asst-run-stage-sweep" aria-hidden="true"></div>'
+    + '</div>';
+  const stage = wrap.firstElementChild;
+  const face = stage.querySelector('.asst-run-stage-face');
+  const sceneHost = stage.querySelector('.asst-run-stage-scene');
+  const stepEl = stage.querySelector('.asst-run-stage-step');
+  const meta = card.querySelector(':scope > .asst-run-meta');
+  if (meta) meta.after(wrap); else card.appendChild(wrap);
+
+  let run = null;
+  let phase = null;
+  let open = false;
+  let scene = '';
+  let sceneAt = -Infinity;
+  let activity = null;
+  let rig = null;
+  let pose = '';
+  let final = '';
+  let foldTimer = 0;
+  let clearTimer = 0;
+  let beat = 0;
+  let destroyed = false;
+
+  const safe = (fn) => { try { return fn(); } catch { return undefined; } };
+
+  function ensureRig() {
+    if (rig || destroyed) return;
+    rig = safe(() => mascot.createMascot(face, { width: 56, height: 28, rangeX: 10, rangeY: 7, pose: 'idle' })) || null;
+    pose = '';
+  }
+
+  function dropRig() {
+    if (rig) safe(() => rig.destroy());
+    rig = null;
+    pose = '';
+    face.textContent = '';
+  }
+
+  function setPose(name, opts) {
+    const key = `${name}|${opts?.then || ''}`;
+    if (!rig || key === pose) return;
+    pose = key;
+    safe(() => rig.setPose(name, opts));
+  }
+
+  /** The scene for now; a swap waits out the dwell of the one on screen (the beat tries again), except out of the generic one. */
+  function syncScene(at) {
+    const want = sceneFor(run, activity, at);
+    if (want === scene) return;
+    if (scene && scene !== 'generic' && at - sceneAt < STAGE_TIMING.sceneDwellMs) return;
+    scene = want;
+    sceneAt = at;
+    sceneHost.innerHTML = sceneSvg(scene);
+    stage.dataset.scene = scene;
+    pose = ''; // the new scene's pose
+  }
+
+  function moving() {
+    return open && !final && phase !== 'waiting' && isLivePhase(phase);
+  }
+
+  function paint() {
+    if (destroyed || !run) return;
+    const at = now();
+    syncScene(at);
+    const live = moving();
+    stage.dataset.phase = final ? phase || 'done' : phase || '';
+    stage.toggleAttribute('data-live', live);
+    if (final) stage.dataset.final = final; else delete stage.dataset.final;
+    sceneHost.firstElementChild?.toggleAttribute('data-live', live);
+    if (rig && !final) setPose(phase === 'waiting' ? 'blocked' : (SCENE_SPECS[scene] || SCENE_SPECS.generic).pose);
+    const text = final ? phaseLine(phase, run, scene, t)
+      : phase === 'working' ? (stepLine(activity, t, at) || phaseLine(phase, run, scene, t))
+        : phaseLine(phase, run, scene, t);
+    if (stepEl.textContent !== text) stepEl.textContent = text;
+    paintLabel(at);
+  }
+
+  function elapsedMs(at) {
+    const from = new Date(run?.startedAt || run?.createdAt || 0).getTime();
+    if (!from) return 0;
+    const end = isTerminalRunStatus(run?.status) ? new Date(run.completedAt || run.updatedAt || at).getTime() : at;
+    return Math.max(0, end - from);
+  }
+
+  /** The stage's accessible name; its minutes are the only time the stage says (the card's details line shows the clock). */
+  function paintLabel(at) {
+    const label = stageLabel({ scene, phase: final ? phase : phase || 'working', title: run?.title || run?.task || '', ms: elapsedMs(at), run }, t);
+    if (stage.getAttribute('aria-label') !== label) stage.setAttribute('aria-label', label);
+  }
+
+  function openStage() {
+    clearTimeout(foldTimer);
+    clearTimeout(clearTimer);
+    foldTimer = 0;
+    clearTimer = 0;
+    final = '';
+    if (!open) {
+      open = true;
+      card.classList.add('is-staged');
+    }
+    ensureRig();
+  }
+
+  /** The run settled: the final frame (a one-shot on the rig), held, then the fold. */
+  function settle() {
+    const next = finalFrame(phase, run);
+    if (final === next) return;
+    final = next;
+    if (rig) {
+      if (next === 'done') safe(() => rig.setPose('success', { then: 'idle' }));
+      else if (next === 'failed') safe(() => rig.setPose('error', { then: 'idle' }));
+      else safe(() => rig.setPose('idle'));
+      pose = `final|${next}`;
+    }
+    clearTimeout(foldTimer);
+    foldTimer = setTimeout(fold, calm() ? 0 : STAGE_TIMING.settleHoldMs);
+  }
+
+  function fold() {
+    foldTimer = 0;
+    if (destroyed || !open) return;
+    open = false;
+    card.classList.remove('is-staged');
+    clearTimeout(clearTimer);
+    clearTimer = setTimeout(() => { clearTimer = 0; if (!open) dropRig(); }, calm() ? 0 : STAGE_TIMING.foldMs);
+  }
+
+  function update(next) {
+    if (destroyed || !next) return;
+    run = next;
+    if (isTerminalRunStatus(run.status)) activity = null; // the run is over: so is what it was doing
+    phase = stagePhase(run);
+    if (isLivePhase(phase)) openStage();
+    else if (open) settle();
+    paint();
+  }
+
+  /** The 1 Hz beat: the minute in the name, a scene swap the dwell held back, and the gaze or pop some scenes use. */
+  function tick(at = now()) {
+    if (destroyed || !open || !run) return;
+    syncScene(at);
+    paint();
+    if (!moving() || !rig || calm()) return;
+    beat += 1;
+    const spec = SCENE_SPECS[scene] || SCENE_SPECS.generic;
+    const path = spec.gaze ? GAZE[spec.gaze] : null;
+    if (path) {
+      const [x, y] = path[beat % path.length];
+      safe(() => rig.look(x, y));
+      if (spec.gaze === 'pointer' && beat % 2 === 0) safe(() => rig.react('click'));
+    }
+    if (spec.pop && beat % 2 === 0) safe(() => rig.react('pop'));
+  }
+
+  return {
+    el: wrap,
+    update,
+    /** What the worker is doing now, from its provider events: kept compact ({ kind, name, step, at }), never its arguments. */
+    setActivity(next) {
+      activity = run && isTerminalRunStatus(run.status) ? null : compactActivity(next, t, now());
+      if (open) paint();
+    },
+    tick,
+    /** Open (live, or holding its final frame before the fold). */
+    live: () => open,
+    /** For tests and devtools. */
+    state: () => ({ open, phase, scene, final, pose: rig?.pose || null, step: stepEl.textContent, label: stage.getAttribute('aria-label') || '' }),
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      clearTimeout(foldTimer);
+      clearTimeout(clearTimer);
+      dropRig();
+      card.classList.remove('is-staged');
+      wrap.remove();
+    },
+  };
+}

package/neural-interface/public/shared/assistant/asst-sanitize.js

@@ -4,12 +4,14 @@
 // marked turns what a brain said into HTML, and that text is not ours: a
 // quoted web page, a plan, a tool's output can carry <img onerror>, a
 // javascript: link or an <svg onload>. Every Markdown sink in the Assistant
-// goes through this allowlist first. The markup is parsed into an inert
+// and in the Claude, Codex and OpenCode panels goes through this allowlist
+// first: it is the one sanitiser, never write a second. The markup is parsed into an inert
 // <template> (nothing runs, nothing loads) and rebuilt node by node into
 // fresh elements, so nothing the parser saw survives unless it is listed
 // here: no on* or style attributes, no ids, no namespaced markup. No
 // dependency beyond file-links.js (pure), nothing touches `document` at
-// import time.
+// import time. A transcript a panel saved and shows again goes through the
+// second list at the end of this file (sanitizeStoredHtml).
 
 import { localFileHref } from '../file-links.js';
 
@@ -27,7 +29,21 @@ const SAFE_SCHEMES = new Set(['http:', 'https:', 'mailto:']);
 const CLASS_RE = /^language-[\w+#.-]{1,40}$/;
 // The panel's own generated media (readRun shows a run's images inline).
 const MEDIA_SRC_RE = /^\/api\/assistant\/runs\/[\w.-]+\/media\/\d+$/;
+// An image of SynaBun's own gallery (GET /api/images/file/<name>: a screenshot, a paste, an image a CLI saved), as
+// written by the model: a path of this server only (no host, scheme, query or fragment), one file name (no folder,
+// no escaped slash, backslash or dot) with an image extension.
+const GALLERY_SRC_RE = /^\/api\/images\/file\/((?!\.)(?:[\w.-]|%(?!2[eEfF]|5[cC])[0-9A-Fa-f]{2})+)$/;
+const GALLERY_EXT_RE = /\.(?:png|jpe?g|gif|webp|bmp|svg)$/i;
+
+/** An <img> src the Markdown list keeps: a run's own media, or an image of SynaBun's gallery. */
+export function isOwnImageSrc(src) {
+  const value = String(src ?? '');
+  if (MEDIA_SRC_RE.test(value)) return true;
+  const gallery = GALLERY_SRC_RE.exec(value);
+  return !!gallery && GALLERY_EXT_RE.test(gallery[1]);
+}
 const MAX_DEPTH = 64;
+const ALIGNS = new Set(['left', 'center', 'right']);
 
 /** An href the Assistant may render: http(s) or mailto after resolving it, else null. */
 export function safeHref(raw, base = globalThis.document?.baseURI || 'http://localhost/') {
@@ -54,6 +70,8 @@ function copyAttributes(from, to, tag) {
     if (href) to.setAttribute('href', href);
     // A path or a file: URL does not survive as an href (it is resolved against the page, or dropped).
     // Kept as written, as data: ui-file-links.js reads it on a click and opens the file in the editor.
+    // A target whose scheme hides behind spaces, controls or entities (`JaVa\tScript:`), or is one a browser
+    // runs (javascript, vbscript, data…), is no file: that link keeps neither an href nor a target.
     const file = localFileHref(from.getAttribute('href'));
     if (file) to.setAttribute('data-file-target', file);
     const title = from.getAttribute('title');
@@ -65,6 +83,15 @@ function copyAttributes(from, to, tag) {
     const classes = String(from.getAttribute('class') || '').split(/\s+/).filter(c => CLASS_RE.test(c));
     if (classes.length) to.setAttribute('class', classes.join(' '));
   }
+  // A table column's alignment and a list's first number: marked writes both, and they are words and digits only.
+  if (tag === 'th' || tag === 'td') {
+    const align = String(from.getAttribute('align') || '').toLowerCase();
+    if (ALIGNS.has(align)) to.setAttribute('align', align);
+  }
+  if (tag === 'ol') {
+    const start = String(from.getAttribute('start') || '');
+    if (/^\d{1,9}$/.test(start)) to.setAttribute('start', start);
+  }
 }
 
 function clean(source, target, doc, depth) {
@@ -84,7 +111,7 @@ function clean(source, target, doc, depth) {
     }
     if (tag === 'img') {
       const src = String(node.getAttribute('src') || '');
-      if (MEDIA_SRC_RE.test(src)) {
+      if (isOwnImageSrc(src)) {
         const img = doc.createElement('img');
         img.setAttribute('src', src);
         img.setAttribute('alt', node.getAttribute('alt') || '');
@@ -122,3 +149,166 @@ export function sanitizeHtmlString(html, doc = globalThis.document) {
   holder.appendChild(sanitizeHtml(html, doc));
   return holder.innerHTML;
 }
+
+// ── Stored transcripts ──
+// A side panel saves its transcript's own markup (messages, cards, buttons, data attributes, the inline SVG of
+// its icons) and puts it back when the session is opened again. That markup is the panel's, so the Markdown list
+// above would take it apart; but it comes back from storage, and a build from before the panels sanitised their
+// Markdown saved model HTML into it as it was. So it is rebuilt here the same way, node by node into fresh
+// elements, from a second list: what a panel writes is kept exactly as it was written (a normal transcript looks
+// as it did), and nothing else is. No script, handler, frame or form, no id or name, no image from another site
+// (a remote image is not loaded again from storage), no style that loads something or leaves the transcript.
+
+const SVG_NS = 'http://www.w3.org/2000/svg';
+const STORED_MAX_DEPTH = 128;
+/** The panel's own elements, besides the Markdown ones; an element not listed is unwrapped (a <form> too). */
+const STORED_TAGS = new Set([...ALLOWED_TAGS, 'div', 'section', 'header', 'footer', 'article', 'aside', 'figure', 'figcaption',
+  'small', 'b', 'i', 'u', 's', 'sub', 'sup', 'mark', 'kbd', 'samp', 'var', 'abbr', 'cite', 'q', 'dfn', 'ins', 'time', 'wbr',
+  'caption', 'colgroup', 'col', 'tfoot', 'dl', 'dt', 'dd', 'details', 'summary', 'label', 'button', 'input', 'textarea',
+  'select', 'option', 'optgroup', 'progress', 'meter', 'img']);
+const STORED_DROPPED = new Set([...DROPPED].filter(tag => tag !== 'input'));
+/** The shapes of the panels' icons; any other SVG element (script, a, use, image, foreignObject, animate…) goes with what is in it. */
+const STORED_SVG_TAGS = new Set(['svg', 'g', 'path', 'circle', 'ellipse', 'line', 'polyline', 'polygon', 'rect', 'title', 'desc']);
+const STORED_SVG_ATTRS = new Set(['viewBox', 'width', 'height', 'fill', 'stroke', 'stroke-width', 'stroke-linecap', 'stroke-linejoin',
+  'stroke-dasharray', 'stroke-dashoffset', 'stroke-miterlimit', 'stroke-opacity', 'fill-opacity', 'fill-rule', 'clip-rule', 'opacity',
+  'd', 'cx', 'cy', 'r', 'rx', 'ry', 'x', 'y', 'x1', 'y1', 'x2', 'y2', 'points', 'transform', 'preserveAspectRatio', 'vector-effect',
+  'shape-rendering', 'focusable']);
+const SVG_PAINT_ATTRS = new Set(['fill', 'stroke']);
+const SVG_PAINT_RE = /^(?:none|currentColor|transparent|context-fill|context-stroke|inherit|#[0-9a-f]{3,8}|[a-z]{3,24}|(?:rgb|rgba|hsl|hsla)\(\s*[0-9.,%\s/+-]*\))$/i;
+const STORED_GLOBAL_ATTRS = new Set(['class', 'title', 'role', 'hidden', 'lang', 'dir', 'tabindex', 'draggable', 'spellcheck', 'translate']);
+// ARIA that names an element by id: the ids are gone, so these would point at nothing (or at the panel's own chrome).
+const ARIA_ID_REFS = new Set(['aria-controls', 'aria-describedby', 'aria-labelledby', 'aria-owns', 'aria-activedescendant', 'aria-details', 'aria-errormessage', 'aria-flowto']);
+const STORED_TAG_ATTRS = {
+  a: ['target', 'rel'],
+  img: ['alt', 'width', 'height', 'loading', 'decoding'],
+  button: ['type', 'disabled', 'value'],
+  input: ['type', 'value', 'checked', 'disabled', 'readonly', 'placeholder', 'min', 'max', 'step', 'maxlength', 'size', 'autocomplete'],
+  textarea: ['rows', 'cols', 'placeholder', 'disabled', 'readonly', 'maxlength', 'wrap', 'autocomplete'],
+  select: ['disabled', 'multiple', 'size'],
+  option: ['value', 'selected', 'disabled', 'label'],
+  optgroup: ['label', 'disabled'],
+  details: ['open'],
+  th: ['align', 'colspan', 'rowspan', 'scope'],
+  td: ['align', 'colspan', 'rowspan'],
+  col: ['span'],
+  colgroup: ['span'],
+  ol: ['start', 'reversed', 'type'],
+  li: ['value'],
+  time: ['datetime'],
+  progress: ['value', 'max'],
+  meter: ['value', 'min', 'max', 'low', 'high', 'optimum'],
+};
+const STORED_VALUES = {
+  target: /^_blank$/,
+  type: /^(?:button|submit|reset|text|search|number|checkbox|radio|range|email|url|tel|hidden|1|a|A|i|I)$/,
+  tabindex: /^-?\d{1,3}$/,
+};
+const REL_TOKENS = new Set(['noopener', 'noreferrer', 'nofollow', 'ugc', 'external']);
+// Inline styles: the layout properties the panels set (a code block's position, an image preview's size, a card
+// hidden or dimmed while busy, a chip's colour) and nothing that loads, positions over the page or hides behind an
+// escape: a value names no function but the colour and arithmetic ones, so `background` is a colour, never an image.
+const STYLE_PROPS = new Set(['display', 'position', 'width', 'height', 'min-width', 'min-height', 'max-width', 'max-height',
+  'margin', 'margin-top', 'margin-right', 'margin-bottom', 'margin-left', 'padding', 'padding-top', 'padding-right', 'padding-bottom',
+  'padding-left', 'border', 'border-top', 'border-right', 'border-bottom', 'border-left', 'border-color', 'border-width', 'border-style',
+  'border-radius', 'box-sizing', 'opacity', 'visibility', 'pointer-events', 'cursor', 'overflow', 'overflow-x', 'overflow-y',
+  'overflow-wrap', 'word-break', 'white-space', 'text-overflow', 'text-align', 'vertical-align', 'line-height', 'font-size',
+  'font-weight', 'font-style', 'letter-spacing', 'text-decoration', 'color', 'background', 'background-color', 'gap', 'row-gap', 'column-gap',
+  'flex', 'flex-direction', 'flex-wrap', 'flex-grow', 'flex-shrink', 'flex-basis', 'align-items', 'align-self', 'justify-content',
+  'object-fit', 'tab-size']);
+const STYLE_FUNCTIONS = new Set(['var', 'calc', 'rgb', 'rgba', 'hsl', 'hsla', 'min', 'max', 'clamp']);
+
+/** A style attribute as written when every declaration is a layout one; else only those; '' when none is left. */
+export function storedStyle(text) {
+  const kept = [];
+  let dropped = false;
+  for (const part of String(text ?? '').split(';')) {
+    const decl = part.trim();
+    if (!decl) continue;
+    const colon = decl.indexOf(':');
+    const prop = colon > 0 ? decl.slice(0, colon).trim().toLowerCase() : '';
+    const value = colon > 0 ? decl.slice(colon + 1).trim() : '';
+    const functions = [...value.matchAll(/([a-z-]*)\s*\(/gi)].map(m => m[1].toLowerCase());
+    const ok = (STYLE_PROPS.has(prop) || /^--[a-z0-9-]{1,64}$/.test(prop)) && value !== ''
+      && functions.every(fn => STYLE_FUNCTIONS.has(fn))
+      && !/[\\<>{}@"']|\/\*|url|expression|javascript|image|attr/i.test(value)
+      && (prop !== 'position' || /^(?:static|relative)$/i.test(value));
+    if (ok) kept.push(decl); else dropped = true;
+  }
+  if (!dropped) return String(text ?? '');
+  return kept.length ? `${kept.join('; ')};` : '';
+}
+
+/** An image a stored transcript may show again: a data: image, or a file of this page's own origin (a blob: of it). */
+export function storedImageSrc(raw, base = globalThis.document?.baseURI || 'http://localhost/') {
+  const value = String(raw ?? '');
+  if (/^data:image\//i.test(value.replace(/[\u0000- ]/g, ''))) return value;
+  let url;
+  let page;
+  try { url = new URL(value, base); page = new URL(base); } catch { return null; }
+  if (!value.trim() || !['http:', 'https:', 'blob:'].includes(url.protocol)) return null;
+  return url.origin === page.origin ? value : null;
+}
+
+function storedAttribute(tag, svg, name, value, base) {
+  const lower = name.toLowerCase();
+  if (lower === 'style') {
+    const style = storedStyle(value);
+    return style || null;
+  }
+  if (/^data-[\w.-]+$/i.test(name)) return value;
+  if (/^aria-[a-z]+$/.test(lower)) return ARIA_ID_REFS.has(lower) ? null : value;
+  if (STORED_GLOBAL_ATTRS.has(lower)) return !STORED_VALUES[lower] || STORED_VALUES[lower].test(value) ? value : null;
+  if (svg) {
+    if (name === 'xmlns') return value === SVG_NS ? value : null;
+    // A presentation attribute is read as CSS, where an escape spells anything (u\72 l( is url(): a value with an
+    // escape, a comment or the word url is not kept, and a paint is a colour or a keyword, never a paint server.
+    if (!STORED_SVG_ATTRS.has(name) || /\\|\/\*|url/i.test(value)) return null;
+    return !SVG_PAINT_ATTRS.has(name) || SVG_PAINT_RE.test(value.trim()) ? value : null;
+  }
+  if (tag === 'a' && lower === 'href') return safeHref(value, base) ? value : null;
+  if (tag === 'img' && lower === 'src') return storedImageSrc(value, base);
+  if (!(STORED_TAG_ATTRS[tag] || []).includes(lower)) return null;
+  if (lower === 'rel') {
+    const tokens = value.split(/\s+/).filter(token => REL_TOKENS.has(token.toLowerCase()));
+    return tokens.length ? tokens.join(' ') : null;
+  }
+  return !STORED_VALUES[lower] || STORED_VALUES[lower].test(value) ? value : null;
+}
+
+function cleanStored(source, target, doc, depth, base) {
+  for (const node of source.childNodes) {
+    if (node.nodeType === 3) { target.appendChild(doc.createTextNode(node.data)); continue; }
+    if (node.nodeType !== 1) continue;
+    const tag = node.localName;
+    const svg = node.namespaceURI === SVG_NS;
+    if (depth >= STORED_MAX_DEPTH || (!svg && (node.namespaceURI !== HTML_NS || tag === 'math'))) {
+      const text = textOf(node);
+      if (text) target.appendChild(doc.createTextNode(text));
+      continue;
+    }
+    if (svg ? !STORED_SVG_TAGS.has(tag) : STORED_DROPPED.has(tag)) continue;
+    if (!svg && !STORED_TAGS.has(tag)) { cleanStored(node, target, doc, depth + 1, base); continue; } // unwrap
+    if (tag === 'img' && !storedImageSrc(node.getAttribute('src'), base)) continue;
+    const el = svg ? doc.createElementNS(SVG_NS, tag) : doc.createElement(tag);
+    for (const name of node.getAttributeNames()) {
+      const value = storedAttribute(tag, svg, name, node.getAttribute(name), base);
+      if (value !== null) el.setAttribute(name, value);
+    }
+    // A link that opens a tab never hands that tab this page.
+    if (tag === 'a' && el.getAttribute('target') === '_blank') {
+      const rel = new Set(String(el.getAttribute('rel') || '').split(/\s+/).filter(Boolean));
+      if (!rel.has('noopener') || !rel.has('noreferrer')) el.setAttribute('rel', [...rel, 'noopener', 'noreferrer'].filter((t, i, all) => all.indexOf(t) === i).join(' '));
+    }
+    cleanStored(node, el, doc, depth + 1, base);
+    target.appendChild(el);
+  }
+}
+
+/** A stored transcript's markup → a DocumentFragment of fresh nodes from the stored-transcript list. */
+export function sanitizeStoredHtml(html, doc = globalThis.document) {
+  const tpl = doc.createElement('template');
+  tpl.innerHTML = String(html ?? '');
+  const out = doc.createDocumentFragment();
+  cleanStored(tpl.content, out, doc, 0, doc.baseURI || globalThis.document?.baseURI || 'http://localhost/');
+  return out;
+}