portal-mojo 0.1.0

package/src/client/markdown-parse.ts

@@ -0,0 +1,386 @@
+// Markdown → block AST. ONE parser, two emitters:
+//
+//   · `markdownToNodes` (markdown-fallback.tsx) → React elements. The client
+//     fallback path — it never touches innerHTML, so nothing on it can be
+//     markup at all.
+//   · `markdownToHtml` (here) → an HTML STRING. Used ONLY by the mock's
+//     /api/docit/render route, which stands in for django-mojo's renderer so
+//     mock and live behave alike. Its output re-enters through the sanitizer
+//     exactly like real server HTML — the mock does not get a trusted lane.
+//
+// Parity with the backend renderer (mojo/apps/docit/services/markdown.py —
+// mistune, `render_safe`), which is what /api/docit/render actually runs:
+//   · hard_wrap=True → a single newline inside a paragraph is a <br>.
+//   · escape=True    → raw HTML in the SOURCE is escaped to text, never
+//     re-emitted as markup. Both emitters here do the same by construction
+//     (React escapes; markdownToHtml runs every text node through esc()).
+//
+// Deliberately a SUBSET of mistune: headings, paragraphs, hr, fenced code,
+// blockquotes, nested/task lists, GFM tables, and inline emphasis / code /
+// links / images / autolinks. Footnotes, math, abbr, spoiler and syntax
+// highlighting are server-only — when the server answers you get them; on the
+// fallback path they degrade to their literal text.
+
+export type MdInline =
+    | { t: 'text'; v: string }
+    | { t: 'br' }
+    | { t: 'code'; v: string }
+    | { t: 'strong'; c: MdInline[] }
+    | { t: 'em'; c: MdInline[] }
+    | { t: 'del'; c: MdInline[] }
+    | { t: 'link'; href: string; c: MdInline[] }
+    | { t: 'img'; src: string; alt: string };
+
+export interface MdListItem {
+    /** null = a plain bullet; true/false = a `- [x]` / `- [ ]` task item. */
+    task: boolean | null;
+    /**
+     * No blank line inside the item — its paragraphs render WITHOUT a <p>
+     * wrapper, which is what keeps `- a` + a nested list on one line instead of
+     * growing a paragraph's margins mid-bullet.
+     */
+    tight: boolean;
+    blocks: MdBlock[];
+}
+
+export type MdBlock =
+    | { t: 'heading'; level: number; c: MdInline[] }
+    | { t: 'para'; c: MdInline[] }
+    | { t: 'hr' }
+    | { t: 'code'; lang: string | null; v: string }
+    | { t: 'quote'; blocks: MdBlock[] }
+    | { t: 'list'; ordered: boolean; start: number; items: MdListItem[] }
+    | { t: 'table'; head: MdInline[][]; rows: MdInline[][][] };
+
+// ── Block grammar ────────────────────────────────────────────────────────
+const FENCE_RE = /^\s{0,3}(`{3,}|~{3,})\s*([^\s`]*)\s*$/;
+const HEADING_RE = /^ {0,3}(#{1,6})\s+(.*?)\s*#*\s*$/;
+const HR_RE = /^ {0,3}([-*_])[ \t]*(?:\1[ \t]*){2,}$/;
+const QUOTE_RE = /^ {0,3}>[ \t]?(.*)$/;
+const LIST_RE = /^([ \t]*)(?:([-*+])|(\d{1,9})[.)])[ \t]+(.*)$/;
+const TABLE_DIV_RE = /^[ \t]*\|?[ \t]*:?-+:?[ \t]*(?:\|[ \t]*:?-+:?[ \t]*)*\|?[ \t]*$/;
+/** Guards pathological nesting (a fallback must never hang the tab). */
+const MAX_DEPTH = 6;
+
+function indentOf(line: string): number {
+    return line.length - line.trimStart().length;
+}
+
+/** Drop up to `n` leading spaces — list-item continuation lines. */
+function dedent(line: string, n: number): string {
+    let k = 0;
+    while (k < n && (line[k] === ' ' || line[k] === '\t')) k++;
+    return line.slice(k);
+}
+
+/**
+ * What a container renders as once MAX_DEPTH is hit: its text as one
+ * paragraph. Never "render nothing" — the depth guard is a performance
+ * ceiling, not a reason to lose the reader's content.
+ */
+function depthLimitBlocks(lines: string[]): MdBlock[] {
+    const text = lines.join('\n').trim();
+    return text ? [{ t: 'para', c: parseInline(text) }] : [];
+}
+
+function startsBlock(line: string): boolean {
+    return (
+        FENCE_RE.test(line) ||
+        HEADING_RE.test(line) ||
+        HR_RE.test(line) ||
+        QUOTE_RE.test(line) ||
+        LIST_RE.test(line)
+    );
+}
+
+function isTableStart(lines: string[], i: number): boolean {
+    const head = lines[i]!;
+    const div = lines[i + 1];
+    return !!div && head.includes('|') && div.includes('-') && TABLE_DIV_RE.test(div);
+}
+
+/** Split a table row on unescaped pipes, dropping the optional outer ones. */
+function splitRow(line: string): string[] {
+    let s = line.trim();
+    if (s.startsWith('|')) s = s.slice(1);
+    if (s.endsWith('|') && !s.endsWith('\\|')) s = s.slice(0, -1);
+    return s.split(/(?<!\\)\|/).map((c) => c.trim().replace(/\\\|/g, '|'));
+}
+
+export function parseMarkdown(source: string, depth = 0): MdBlock[] {
+    return parseBlocks(source.replace(/\r\n?/g, '\n').split('\n'), depth);
+}
+
+function parseBlocks(lines: string[], depth: number): MdBlock[] {
+    const out: MdBlock[] = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i]!;
+        if (!line.trim()) { i++; continue; }
+
+        const fence = FENCE_RE.exec(line);
+        if (fence) {
+            const closer = fence[1]![0] === '`' ? /^\s{0,3}`{3,}\s*$/ : /^\s{0,3}~{3,}\s*$/;
+            const body: string[] = [];
+            i++;
+            while (i < lines.length && !closer.test(lines[i]!)) { body.push(lines[i]!); i++; }
+            if (i < lines.length) i++; // consume the closing fence
+            out.push({ t: 'code', lang: fence[2] || null, v: body.join('\n') });
+            continue;
+        }
+
+        const heading = HEADING_RE.exec(line);
+        if (heading) {
+            out.push({ t: 'heading', level: heading[1]!.length, c: parseInline(heading[2]!) });
+            i++;
+            continue;
+        }
+
+        // Before the list rule: `---` is a rule, `- x` is a bullet.
+        if (HR_RE.test(line)) { out.push({ t: 'hr' }); i++; continue; }
+
+        if (QUOTE_RE.test(line)) {
+            const inner: string[] = [];
+            while (i < lines.length) {
+                const q = QUOTE_RE.exec(lines[i]!);
+                if (!q) break;
+                inner.push(q[1]!);
+                i++;
+            }
+            out.push({ t: 'quote', blocks: depth < MAX_DEPTH ? parseBlocks(inner, depth + 1) : depthLimitBlocks(inner) });
+            continue;
+        }
+
+        if (isTableStart(lines, i)) {
+            const head = splitRow(line).map((c) => parseInline(c));
+            i += 2; // header + divider
+            const rows: MdInline[][][] = [];
+            while (i < lines.length && lines[i]!.includes('|') && lines[i]!.trim()) {
+                rows.push(splitRow(lines[i]!).map((c) => parseInline(c)));
+                i++;
+            }
+            out.push({ t: 'table', head, rows });
+            continue;
+        }
+
+        const listStart = LIST_RE.exec(line);
+        if (listStart) {
+            const baseIndent = listStart[1]!.length;
+            const ordered = !!listStart[3];
+            const listLines: string[] = [];
+            while (i < lines.length) {
+                const cur = lines[i]!;
+                if (!cur.trim()) {
+                    // A blank line only ends the list when what follows it is
+                    // neither a sibling marker nor indented item content.
+                    let j = i + 1;
+                    while (j < lines.length && !lines[j]!.trim()) j++;
+                    if (j >= lines.length) break;
+                    const nextMarker = LIST_RE.exec(lines[j]!);
+                    const continues =
+                        indentOf(lines[j]!) > baseIndent ||
+                        (!!nextMarker && nextMarker[1]!.length === baseIndent);
+                    if (!continues) break;
+                    listLines.push('');
+                    i++;
+                    continue;
+                }
+                const marker = LIST_RE.exec(cur);
+                const isSibling = !!marker && marker[1]!.length === baseIndent;
+                if (!isSibling && indentOf(cur) <= baseIndent) break;
+                listLines.push(cur);
+                i++;
+            }
+            out.push({ t: 'list', ordered, start: ordered ? Number(listStart[3]) : 1, items: parseItems(listLines, baseIndent, depth) });
+            continue;
+        }
+
+        // Paragraph: run to the next blank line or block start (hard_wrap
+        // parity — the interior newlines become <br>, see parseInline).
+        const buf: string[] = [line.trim()];
+        i++;
+        while (i < lines.length && lines[i]!.trim() && !startsBlock(lines[i]!) && !isTableStart(lines, i)) {
+            buf.push(lines[i]!.trim());
+            i++;
+        }
+        out.push({ t: 'para', c: parseInline(buf.join('\n')) });
+    }
+    return out;
+}
+
+const TASK_RE = /^\[([ xX])\]\s+(.*)$/;
+
+function parseItems(lines: string[], baseIndent: number, depth: number): MdListItem[] {
+    const items: MdListItem[] = [];
+    let cur: { body: string[]; strip: number } | null = null;
+    const flush = () => {
+        if (!cur) return;
+        const first = cur.body[0] ?? '';
+        const task = TASK_RE.exec(first);
+        if (task) cur.body[0] = task[2]!;
+        items.push({
+            task: task ? task[1]!.toLowerCase() === 'x' : null,
+            tight: !cur.body.some((l) => !l.trim()),
+            blocks: depth < MAX_DEPTH ? parseBlocks(cur.body, depth + 1) : depthLimitBlocks(cur.body),
+        });
+        cur = null;
+    };
+    for (const line of lines) {
+        const marker = LIST_RE.exec(line);
+        if (marker && marker[1]!.length === baseIndent) {
+            flush();
+            cur = { body: [marker[4]!], strip: marker[0]!.length - marker[4]!.length };
+            continue;
+        }
+        if (cur) cur.body.push(dedent(line, cur.strip));
+    }
+    flush();
+    return items;
+}
+
+// ── Inline grammar ───────────────────────────────────────────────────────
+//
+// Every rule is scanned over the WHOLE string (global regexes + lastIndex)
+// rather than over a shrinking slice: it keeps the scan near-linear, and it
+// keeps lookbehind context intact at token boundaries (`snake_case_word` must
+// not become emphasis).
+interface InlineRule {
+    re: RegExp;
+    make(m: RegExpExecArray, depth: number): MdInline;
+}
+
+const INLINE_RULES: InlineRule[] = [
+    // Code first: its contents are literal, so nothing inside it is markup.
+    { re: /`([^`\n]+)`/g, make: (m) => ({ t: 'code', v: m[1]! }) },
+    // The URL part allows ONE level of balanced parens, so wiki-style links
+    // (`.../X_(disambiguation)`) survive.
+    { re: /!\[([^\]]*)\]\(\s*((?:[^()\s]|\([^()\s]*\))+)(?:\s+"[^"]*")?\s*\)/g, make: (m) => ({ t: 'img', src: m[2]!, alt: m[1] ?? '' }) },
+    { re: /\[([^\]]*)\]\(\s*((?:[^()\s]|\([^()\s]*\))+)(?:\s+"[^"]*")?\s*\)/g, make: (m, d) => ({ t: 'link', href: m[2]!, c: parseInline(m[1]!, d + 1) }) },
+    { re: /\*\*\*(?=\S)([\s\S]*?\S)\*\*\*/g, make: (m, d) => ({ t: 'strong', c: [{ t: 'em', c: parseInline(m[1]!, d + 1) }] }) },
+    { re: /\*\*(?=\S)([\s\S]*?\S)\*\*/g, make: (m, d) => ({ t: 'strong', c: parseInline(m[1]!, d + 1) }) },
+    { re: /(?<![\w\\])__(?=\S)([\s\S]*?\S)__(?!\w)/g, make: (m, d) => ({ t: 'strong', c: parseInline(m[1]!, d + 1) }) },
+    { re: /\*(?=\S)([^*\n]*\S|\S)\*/g, make: (m, d) => ({ t: 'em', c: parseInline(m[1]!, d + 1) }) },
+    { re: /(?<![\w\\])_(?=\S)([^_\n]*\S|\S)_(?!\w)/g, make: (m, d) => ({ t: 'em', c: parseInline(m[1]!, d + 1) }) },
+    { re: /~~(?=\S)([\s\S]*?\S)~~/g, make: (m, d) => ({ t: 'del', c: parseInline(m[1]!, d + 1) }) },
+    { re: /<((?:https?:\/\/|mailto:)[^>\s]+)>/g, make: (m) => ({ t: 'link', href: m[1]!, c: [{ t: 'text', v: m[1]! }] }) },
+    // Bare autolink (mistune's `url` plugin). The final character class keeps
+    // sentence punctuation OUT of the match, so "see https://x/a." links `a`
+    // and leaves the period as text.
+    {
+        re: /(?<![\w/@.:-])https?:\/\/[^\s<>()"']*[^\s<>()"'.,;:!?]/g,
+        make: (m) => ({ t: 'link', href: m[0]!, c: [{ t: 'text', v: m[0]! }] }),
+    },
+];
+
+/** Split on newlines so hard_wrap's <br> is part of the AST, not the emitter. */
+function pushText(out: MdInline[], text: string): void {
+    const parts = text.split('\n');
+    parts.forEach((part, idx) => {
+        if (idx > 0) out.push({ t: 'br' });
+        if (part) out.push({ t: 'text', v: part });
+    });
+}
+
+export function parseInline(text: string, depth = 0): MdInline[] {
+    const out: MdInline[] = [];
+    if (!text) return out;
+    if (depth >= MAX_DEPTH) { pushText(out, text); return out; }
+
+    // One live match per rule, refreshed only once the cursor passes it.
+    const found: (RegExpExecArray | null)[] = INLINE_RULES.map(() => null);
+    const exhausted: boolean[] = INLINE_RULES.map(() => false);
+    let pos = 0;
+    while (pos < text.length) {
+        let bestIdx = -1;
+        let best = -1;
+        for (let k = 0; k < INLINE_RULES.length; k++) {
+            if (exhausted[k]) continue;
+            let m = found[k];
+            if (!m || m.index < pos) {
+                const re = INLINE_RULES[k]!.re;
+                re.lastIndex = pos;
+                m = re.exec(text);
+                found[k] = m;
+                if (!m) { exhausted[k] = true; continue; }
+            }
+            if (best === -1 || m.index < best) { best = m.index; bestIdx = k; }
+        }
+        if (bestIdx === -1) { pushText(out, text.slice(pos)); return out; }
+        const m = found[bestIdx]!;
+        if (m.index > pos) pushText(out, text.slice(pos, m.index));
+        out.push(INLINE_RULES[bestIdx]!.make(m, depth));
+        pos = m.index + m[0]!.length;
+    }
+    return out;
+}
+
+// ── HTML emitter (mock transport only) ───────────────────────────────────
+const ESCAPES: Record<string, string> = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+
+function esc(s: string): string {
+    return s.replace(/[&<>"']/g, (ch) => ESCAPES[ch]!);
+}
+
+function inlineHtml(nodes: MdInline[]): string {
+    return nodes
+        .map((n) => {
+            switch (n.t) {
+                case 'text': return esc(n.v);
+                case 'br': return '<br>';
+                case 'code': return `<code>${esc(n.v)}</code>`;
+                case 'strong': return `<strong>${inlineHtml(n.c)}</strong>`;
+                case 'em': return `<em>${inlineHtml(n.c)}</em>`;
+                case 'del': return `<del>${inlineHtml(n.c)}</del>`;
+                case 'img': return `<img src="${esc(n.src)}" alt="${esc(n.alt)}">`;
+                // href is emitted verbatim (escaped) — vetting it is the
+                // SANITIZER's job on the way in, same as for real server HTML.
+                case 'link': return `<a href="${esc(n.href)}">${inlineHtml(n.c)}</a>`;
+            }
+        })
+        .join('');
+}
+
+function itemHtml(item: MdListItem): string {
+    const body = item.tight
+        ? item.blocks.map((b) => (b.t === 'para' ? inlineHtml(b.c) : blocksHtml([b]))).join('')
+        : blocksHtml(item.blocks);
+    const box = item.task === null ? '' : `<input type="checkbox" disabled${item.task ? ' checked' : ''}> `;
+    return `<li>${box}${body}</li>`;
+}
+
+function blocksHtml(blocks: MdBlock[]): string {
+    return blocks
+        .map((b) => {
+            switch (b.t) {
+                case 'heading': return `<h${b.level}>${inlineHtml(b.c)}</h${b.level}>`;
+                case 'para': return `<p>${inlineHtml(b.c)}</p>`;
+                case 'hr': return '<hr>';
+                // `language-x` mirrors what a server renderer emits; the
+                // sanitizer strips it (only `md-` classes survive) — see
+                // markdown-sanitize.ts.
+                case 'code': return `<pre><code${b.lang ? ` class="language-${esc(b.lang)}"` : ''}>${esc(b.v)}</code></pre>`;
+                case 'quote': return `<blockquote>${blocksHtml(b.blocks)}</blockquote>`;
+                case 'list': {
+                    const tag = b.ordered ? 'ol' : 'ul';
+                    const startAttr = b.ordered && b.start !== 1 ? ` start="${b.start}"` : '';
+                    return `<${tag}${startAttr}>${b.items.map(itemHtml).join('')}</${tag}>`;
+                }
+                case 'table': {
+                    const head = `<thead><tr>${b.head.map((c) => `<th>${inlineHtml(c)}</th>`).join('')}</tr></thead>`;
+                    const body = b.rows.map((r) => `<tr>${r.map((c) => `<td>${inlineHtml(c)}</td>`).join('')}</tr>`).join('');
+                    return `<table>${head}<tbody>${body}</tbody></table>`;
+                }
+            }
+        })
+        .join('\n');
+}
+
+/**
+ * Markdown → HTML string. The MOCK's stand-in for django-mojo's renderer —
+ * production code never calls this: it calls `renderMarkdown` (server) or
+ * renders `<MarkdownFallback>` (React elements). Raw HTML in the source is
+ * escaped, matching mistune's `render_safe`.
+ */
+export function markdownToHtml(source: string): string {
+    return blocksHtml(parseMarkdown(source));
+}

package/src/client/markdown-sanitize.ts

@@ -0,0 +1,217 @@
+// The allowlist sanitizer — the ONE place in portal-mojo that produces a
+// string destined for `dangerouslySetInnerHTML` (ui/MarkdownView.tsx).
+//
+// THE TRUST MODEL, in one line: server-rendered HTML is UNTRUSTED. django-mojo
+// escapes raw HTML in the markdown source (mistune `render_safe`), but a
+// portal must not be one backend regression away from stored XSS — so every
+// byte of server HTML is re-derived here from an allowlist before it reaches
+// the DOM. Nothing is trusted because of where it came from.
+//
+// How it works:
+//   1. Parse with DOMParser('text/html') — an INERT document: no script runs,
+//      no image loads, no `onerror` fires. (Assigning to a live element's
+//      innerHTML would already have fetched `<img src=x onerror=...>`.)
+//   2. Walk the tree. Every element is one of three things:
+//        · allowlisted   → keep it, then scrub its attributes to an allowlist
+//        · dangerous     → REMOVE it and its whole subtree (script/style/...)
+//        · anything else → UNWRAP it: the element goes, its (already
+//          sanitized) children stay. Text is never lost — which is what keeps
+//          a server syntax-highlighted `<div class=highlight><span class=k>`
+//          block readable after its markup is stripped.
+//   3. Serialize with the browser's own serializer (`body.innerHTML`).
+//
+// Fail-closed everywhere: unknown attribute → dropped; unparseable URL →
+// dropped; no DOM available → throws, and MarkdownView falls back to the
+// React-element renderer, which cannot emit markup at all.
+
+/** Elements that survive. Everything else is unwrapped or removed. */
+const ALLOWED_TAGS = new Set([
+    'p', 'br', 'hr',
+    'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+    'ul', 'ol', 'li',
+    'strong', 'em', 'del', 'code', 'pre', 'blockquote',
+    'a', 'img',
+    'table', 'thead', 'tbody', 'tr', 'th', 'td',
+    // Task lists (`- [x] ...`); constrained hard below to disabled checkboxes.
+    'input',
+    // Beyond the base set, because the backend's mistune plugin list emits
+    // them (mark, footnote refs) and all three are inert — no URL-bearing
+    // attribute, no scripting surface.
+    'mark', 'sup', 'sub',
+]);
+
+/**
+ * Removed WITH their subtree — for these, the text content is itself a payload
+ * (CSS, script source) or the element is a script/navigation host.
+ */
+const DROP_SUBTREE = new Set([
+    'script', 'style', 'iframe', 'object', 'embed', 'applet',
+    'noscript', 'template', 'link', 'meta', 'base', 'title',
+    'frame', 'frameset', 'form', 'button', 'select', 'textarea',
+    // Namespaced content the HTML allowlist above cannot reason about.
+    'svg', 'math',
+]);
+
+/** Per-tag attribute allowlist. `class` is handled separately (md- prefix). */
+const ALLOWED_ATTRS: Record<string, Set<string>> = {
+    a: new Set(['href']),
+    img: new Set(['src', 'alt']),
+    input: new Set(['type', 'checked', 'disabled']),
+};
+
+const XHTML_NS = 'http://www.w3.org/1999/xhtml';
+const SCHEME_RE = /^([a-z][a-z0-9+.-]*):/i;
+const LINK_SCHEMES = new Set(['http:', 'https:', 'mailto:']);
+const IMG_SCHEMES = new Set(['http:', 'https:']);
+/** Control + zero-width chars: `java&#9;script:` must not sneak past. */
+const URL_NOISE_RE = /[\u0000-\u0020\u007F-\u009F\u200B-\u200D\u2060\uFEFF]/g;
+
+export interface SanitizeDrop {
+    /** What the sanitizer did: removed, unwrapped, or stripped a value. */
+    kind: 'element' | 'unwrapped' | 'attribute' | 'url';
+    detail: string;
+}
+
+/**
+ * Vet a URL. Returns the cleaned value, or null to drop it.
+ *
+ * Order matters: NORMALIZE first (strip control/zero-width chars — that is how
+ * `java&#9;script:` is smuggled), THEN allowlist the scheme. Anything without a
+ * recognized scheme is dropped too: a relative link inside rendered markdown
+ * would resolve against the hash router, which is never what the author meant.
+ */
+function vetUrl(raw: string | null | undefined, schemes: Set<string>, allowFragment: boolean): string | null {
+    if (!raw) return null;
+    const value = raw.replace(URL_NOISE_RE, '');
+    if (!value) return null;
+    // Same-document fragments cannot navigate off the page, and the server
+    // renderer's footnote/TOC links are made of them.
+    if (value.startsWith('#')) return allowFragment ? value : null;
+    const scheme = SCHEME_RE.exec(value);
+    if (!scheme) return null;
+    return schemes.has(`${scheme[1]!.toLowerCase()}:`) ? value : null;
+}
+
+/** http / https / mailto / #fragment — anything else is dropped. */
+export function safeLinkUrl(raw: string | null | undefined): string | null {
+    return vetUrl(raw, LINK_SCHEMES, true);
+}
+
+/** http / https only — `data:image/svg+xml` is a script vector, not an image. */
+export function safeImgUrl(raw: string | null | undefined): string | null {
+    return vetUrl(raw, IMG_SCHEMES, false);
+}
+
+/** http/https links leave the portal — they get the noopener treatment. */
+function isExternal(url: string): boolean {
+    return /^https?:/i.test(url);
+}
+
+function scrubAttributes(el: Element, tag: string, onDrop?: (d: SanitizeDrop) => void): void {
+    const allowed = ALLOWED_ATTRS[tag];
+    for (const attr of Array.from(el.attributes)) {
+        const name = attr.name.toLowerCase();
+        if (name === 'class') {
+            // Only `md-` classes survive, so a document can never reach for an
+            // app class (`sidebar`, `panel`) and repaint the portal around it.
+            const kept = attr.value.split(/\s+/).filter((c) => c.startsWith('md-'));
+            if (kept.length) {
+                el.setAttribute('class', kept.join(' '));
+            } else {
+                el.removeAttribute(attr.name);
+                onDrop?.({ kind: 'attribute', detail: `${tag}[class="${attr.value}"]` });
+            }
+            continue;
+        }
+        // Everything not explicitly allowed: on* handlers, style, srcset,
+        // formaction, xlink:href, data-*, id, ...
+        if (!allowed?.has(name)) {
+            el.removeAttribute(attr.name);
+            onDrop?.({ kind: 'attribute', detail: `${tag}[${name}]` });
+        }
+    }
+}
+
+/** Per-tag value rules. @returns false when the element itself must go. */
+function applyElementRules(el: Element, tag: string, onDrop?: (d: SanitizeDrop) => void): boolean {
+    if (tag === 'a') {
+        const raw = el.getAttribute('href');
+        const href = safeLinkUrl(raw);
+        if (!href) {
+            if (raw !== null) onDrop?.({ kind: 'url', detail: `a[href="${raw}"]` });
+            // The link TEXT stays — only the navigation goes.
+            el.removeAttribute('href');
+            return true;
+        }
+        el.setAttribute('href', href);
+        if (isExternal(href)) {
+            el.setAttribute('target', '_blank');
+            el.setAttribute('rel', 'noopener noreferrer');
+        }
+        return true;
+    }
+    if (tag === 'img') {
+        const raw = el.getAttribute('src');
+        const src = safeImgUrl(raw);
+        if (!src) {
+            onDrop?.({ kind: 'url', detail: `img[src="${raw}"]` });
+            return false; // no usable src → nothing to show
+        }
+        el.setAttribute('src', src);
+        return true;
+    }
+    if (tag === 'input') {
+        // Task-list checkboxes only, and never interactive: any other input in
+        // rendered markdown is a phishing surface.
+        if (el.getAttribute('type')?.toLowerCase() !== 'checkbox') {
+            onDrop?.({ kind: 'element', detail: `input[type=${el.getAttribute('type') ?? 'text'}]` });
+            return false;
+        }
+        el.setAttribute('disabled', '');
+        return true;
+    }
+    return true;
+}
+
+function sanitizeChildren(parent: Element, onDrop?: (d: SanitizeDrop) => void): void {
+    // Snapshot: the live child list mutates as elements are unwrapped/removed.
+    for (const node of Array.from(parent.childNodes)) {
+        if (node.nodeType === Node.TEXT_NODE) continue;
+        if (node.nodeType !== Node.ELEMENT_NODE) {
+            node.parentNode?.removeChild(node); // comments, processing instructions
+            continue;
+        }
+        const el = node as Element;
+        const tag = el.tagName.toLowerCase();
+
+        // Non-HTML namespaces (SVG/MathML) go whole: their attribute and
+        // element semantics are not what the allowlist above describes.
+        if (DROP_SUBTREE.has(tag) || el.namespaceURI !== XHTML_NS) {
+            el.remove();
+            onDrop?.({ kind: 'element', detail: `<${tag}>` });
+            continue;
+        }
+        if (!ALLOWED_TAGS.has(tag)) {
+            sanitizeChildren(el, onDrop);                 // clean the subtree...
+            el.replaceWith(...Array.from(el.childNodes)); // ...then unwrap it
+            onDrop?.({ kind: 'unwrapped', detail: `<${tag}>` });
+            continue;
+        }
+        scrubAttributes(el, tag, onDrop);
+        if (!applyElementRules(el, tag, onDrop)) { el.remove(); continue; }
+        sanitizeChildren(el, onDrop);
+    }
+}
+
+/**
+ * Reduce untrusted HTML to the markdown allowlist. Throws when there is no DOM
+ * to parse with — callers must fall back to the React-element renderer rather
+ * than ship unsanitized markup.
+ */
+export function sanitizeMarkdownHtml(html: string, onDrop?: (d: SanitizeDrop) => void): string {
+    if (!html) return '';
+    if (typeof DOMParser === 'undefined') throw new Error('sanitizeMarkdownHtml requires a DOM (DOMParser)');
+    const doc = new DOMParser().parseFromString(html, 'text/html');
+    sanitizeChildren(doc.body, onDrop);
+    return doc.body.innerHTML;
+}