@mulmoclaude/markdown-utils 2.2.0 → 3.0.0

package/dist/index.d.ts

@@ -12,6 +12,9 @@ export * from "./image/resolve.js";
 export * from "./image/rewriteMarkdownImageRefs.js";
 export * from "./markdown/mermaidRender.js";
 export * from "./markdown/mermaidExtension.js";
+export * from "./markdown/codeCopyExtension.js";
+export * from "./markdown/codeCopyClipboard.js";
+export * from "./markdown/rawHtmlPolicy.js";
 export * from "./markdown/mathExtension.js";
 export * from "./markdown/mathRender.js";
 export * from "./dom/adoptSvg.js";

package/dist/index.js

@@ -12,6 +12,9 @@ export * from "./image/resolve.js";
 export * from "./image/rewriteMarkdownImageRefs.js";
 export * from "./markdown/mermaidRender.js";
 export * from "./markdown/mermaidExtension.js";
+export * from "./markdown/codeCopyExtension.js";
+export * from "./markdown/codeCopyClipboard.js";
+export * from "./markdown/rawHtmlPolicy.js";
 export * from "./markdown/mathExtension.js";
 export * from "./markdown/mathRender.js";
 export * from "./dom/adoptSvg.js";

package/dist/markdown/codeCopyClipboard.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Reads the raw source a block should copy: `textContent` of the
+ * `<code>`, so highlight.js's `<span>` markup never reaches the
+ * clipboard. Exported for the tests.
+ */
+export declare function codeTextOf(button: Element): string | null;
+/**
+ * Attach the delegated listener. Idempotent — a second call on the same
+ * document is a no-op, so the host and a plugin bundle can both ask.
+ */
+export declare function installCodeCopyHandler(doc: Document): void;
+/** Test seam — lets an isolated test install into a fresh document twice. */
+export declare function _resetCodeCopyHandlerForTests(doc: Document): void;

package/dist/markdown/codeCopyClipboard.js

@@ -0,0 +1,172 @@
+// Click behaviour for the copy buttons `codeCopyExtension` emits.
+//
+// ONE delegated listener for the whole document, not a listener per
+// viewer: the buttons live inside `v-html`, so Vue cannot bind `@click`
+// to them, and they are destroyed and recreated on every streamed chunk.
+// Delegation is indifferent to both — the listener is attached to a node
+// that outlives every re-render, and a button that appears mid-stream
+// works without anyone re-running an attach pass.
+//
+// It takes no labels. Only the FIRST install on a document keeps its
+// listener (host and plugin bundles both call this), so any provider
+// captured here would caption the other bundle's buttons too. The
+// renderer writes both label states into each button instead, which also
+// keeps them following the locale for free: a language switch re-renders
+// the markdown, and the new markup carries the new strings.
+import { CODE_COPY_ATTR, CODE_COPY_BLOCK_ATTR, CODE_COPY_ICON, CODE_COPIED_ICON, CODE_COPY_IDLE_LABEL_ATTR, CODE_COPY_COPIED_LABEL_ATTR, CODE_BLOCK_STYLE_INDENTED, CODE_COPY_NONCE_UNAVAILABLE, codeCopyNonce, setCodeCopyNonce, } from "./codeCopyExtension.js";
+/** How long the button stays in its "copied" state before reverting. */
+const FEEDBACK_DURATION_MS = 2000;
+/** Applied on success and removed on revert — the whole visual delta. */
+const COPIED_TINT_CLASS = "text-green-600";
+/** Pairs a document with the renderer, and returns the nonce they agree on.
+ *
+ *  The value lives on the DOCUMENT for the same reason the install flag
+ *  does: host and plugin each have their own module instance, and the
+ *  document is the only thing they share.
+ *
+ *  A document that has none adopts the RENDERER's current value rather
+ *  than minting its own, and that direction is the whole point. The
+ *  renderer's nonce is module state with no idea which document it is
+ *  rendering for, so minting per document lets the two drift: pair A,
+ *  pair B, then re-render A, and A's buttons carry B's nonce while A's
+ *  listener still demands A's. Adopting makes every document in a realm
+ *  converge on one value, which costs nothing — the nonce defends against
+ *  markup that cannot read ANY of them (codex round 2, P3). */
+function ensureNonce(doc) {
+    const target = doc;
+    const existing = target.__mulmoclaudeCodeCopyNonce;
+    if (existing !== undefined)
+        return existing;
+    const adopted = codeCopyNonce();
+    target.__mulmoclaudeCodeCopyNonce = adopted;
+    return adopted;
+}
+// `nodeType`, not `instanceof Element`: this package is browser-SAFE, not
+// browser-ONLY, and the Node + jsdom harness installs `window`/`document`
+// as globals without the DOM constructors — where a bare `Element` is a
+// ReferenceError. Same reason `sanitizeMarkdownHtml` in core discriminates
+// this way. nodeType 1 is the DOM standard's own element discriminant.
+const ELEMENT_NODE = 1;
+const isElement = (value) => typeof value === "object" && value !== null && "nodeType" in value && value.nodeType === ELEMENT_NODE;
+// An element that can carry `classList` / `innerHTML` — everything the
+// feedback swap touches. `Element` alone lacks them.
+const isHtmlElement = (value) => isElement(value) && "classList" in value && "innerHTML" in value;
+/**
+ * Reads the raw source a block should copy: `textContent` of the
+ * `<code>`, so highlight.js's `<span>` markup never reaches the
+ * clipboard. Exported for the tests.
+ */
+export function codeTextOf(button) {
+    const block = button.closest(`[${CODE_COPY_BLOCK_ATTR}]`);
+    const code = block?.querySelector("pre > code");
+    const text = code?.textContent;
+    if (text === undefined || text === null)
+        return null;
+    // ONLY for an indented block. Marked leaves a trailing newline there
+    // that the author did not write, and strips it from a fenced block —
+    // so on a fence the very same `\n` IS content, the blank line before
+    // the closing ```. The two are identical once rendered, which is why
+    // the style has to travel in the markup rather than be guessed here.
+    const indented = block?.getAttribute(CODE_COPY_BLOCK_ATTR) === CODE_BLOCK_STYLE_INDENTED;
+    return indented ? stripTrailingNewline(text) : text;
+}
+function stripTrailingNewline(text) {
+    if (text.endsWith("\r\n"))
+        return text.slice(0, -2);
+    return text.endsWith("\n") ? text.slice(0, -1) : text;
+}
+/** The accessible name and the tooltip are the same string; setting them
+ *  in one place is what stops the two drifting apart. */
+function setLabel(button, label) {
+    if (label === null)
+        return;
+    button.setAttribute("aria-label", label);
+    button.setAttribute("title", label);
+}
+// One pending revert per button. Without this, clicking again while the
+// confirmation is up leaves the FIRST timer running: it fires on the old
+// schedule and clears the second click's feedback early. Keyed weakly so
+// a button removed by the next streamed re-render is collectable.
+const pendingReverts = new WeakMap();
+function showCopied(button) {
+    const view = button.ownerDocument.defaultView;
+    // No window means a detached document nobody is looking at. Bail
+    // before mutating, rather than leaving a confirmation that can never
+    // revert because there is no timer to schedule.
+    if (view === null || view === undefined)
+        return;
+    setLabel(button, button.getAttribute(CODE_COPY_COPIED_LABEL_ATTR));
+    button.innerHTML = CODE_COPIED_ICON;
+    button.classList.add(COPIED_TINT_CLASS);
+    const pending = pendingReverts.get(button);
+    if (pending !== undefined)
+        view.clearTimeout(pending);
+    const handle = view.setTimeout(() => {
+        // Identity check, not just `clearTimeout`: a stale callback that
+        // still runs — a timer already dispatched when the second click
+        // cancelled it — must not clear the live confirmation.
+        if (pendingReverts.get(button) !== handle)
+            return;
+        pendingReverts.delete(button);
+        button.innerHTML = CODE_COPY_ICON;
+        button.classList.remove(COPIED_TINT_CLASS);
+        setLabel(button, button.getAttribute(CODE_COPY_IDLE_LABEL_ATTR));
+    }, FEEDBACK_DURATION_MS);
+    pendingReverts.set(button, handle);
+}
+async function handleClick(event) {
+    const { target } = event;
+    if (!isElement(target))
+        return;
+    const button = target.closest(`[${CODE_COPY_ATTR}]`);
+    if (!isHtmlElement(button))
+        return;
+    // The marker's VALUE is the check, not its presence. Author markup can
+    // carry the attribute — marked passes raw HTML through and DOMPurify
+    // keeps `data-*` — so a bare marker would let a rendered README drive
+    // the clipboard. An empty nonce never matches, which is what makes the
+    // no-CSPRNG case inert instead of guessable.
+    const expected = ensureNonce(button.ownerDocument);
+    if (expected === CODE_COPY_NONCE_UNAVAILABLE)
+        return;
+    if (button.getAttribute(CODE_COPY_ATTR) !== expected)
+        return;
+    const text = codeTextOf(button);
+    if (text === null)
+        return;
+    const clipboard = button.ownerDocument.defaultView?.navigator?.clipboard;
+    if (clipboard === undefined)
+        return;
+    try {
+        await clipboard.writeText(text);
+    }
+    catch {
+        // A denied clipboard permission is the user's answer, not an app
+        // error: leave the button in its idle state so the icon never claims
+        // a copy that did not happen. Nothing to log — the page is not the
+        // place to report a permission the user controls.
+        return;
+    }
+    showCopied(button);
+}
+/**
+ * Attach the delegated listener. Idempotent — a second call on the same
+ * document is a no-op, so the host and a plugin bundle can both ask.
+ */
+export function installCodeCopyHandler(doc) {
+    const target = doc;
+    // Before the install guard, and on EVERY call: the second bundle's
+    // listener install is a no-op, but its renderer still has to learn the
+    // nonce the first bundle's listener will demand.
+    setCodeCopyNonce(ensureNonce(doc));
+    if (target.__mulmoclaudeCodeCopyInstalled === true)
+        return;
+    target.__mulmoclaudeCodeCopyInstalled = true;
+    doc.addEventListener("click", (event) => void handleClick(event));
+}
+/** Test seam — lets an isolated test install into a fresh document twice. */
+export function _resetCodeCopyHandlerForTests(doc) {
+    const target = doc;
+    target.__mulmoclaudeCodeCopyInstalled = false;
+    delete target.__mulmoclaudeCodeCopyNonce;
+}

package/dist/markdown/codeCopyExtension.d.ts

@@ -0,0 +1,77 @@
+import type { MarkedExtension } from "marked";
+/** Accessible names for the copy control. Resolved at render time through
+ *  the provider below, never captured at module load. */
+export interface CodeCopyLabels {
+    /** Idle state, e.g. "Copy code". */
+    copy: string;
+    /** Post-click confirmation, e.g. "Copied". */
+    copied: string;
+}
+/**
+ * Point the renderer at the app's i18n. The provider is called on every
+ * render rather than once, so a host whose provider reads a REACTIVE
+ * locale gets live translations for free: the read lands inside the
+ * `renderedHtml` computed's evaluation and Vue re-runs it on locale
+ * change. Mirrors `setEmbedLocaleProvider`.
+ */
+export declare function setCodeCopyLabelProvider(provider: () => CodeCopyLabels): void;
+/** Test seam — restores the built-in English labels. */
+export declare function _resetCodeCopyLabelsForTests(): void;
+/** Marks the button for the delegated click listener. Its VALUE is a
+ *  per-document nonce, and the listener copies nothing without a match.
+ *
+ *  The attribute cannot be a bare marker: `marked` passes an author's raw
+ *  HTML straight through, DOMPurify's defaults keep `<button>` and every
+ *  `data-*`, and the listener is document-wide. A bare marker therefore
+ *  lets any rendered markdown — a cloned repository's README, which is
+ *  exactly what `sanitizeMarkdownHtml` exists for — mint a working copy
+ *  control and put text of its choosing on the clipboard. Verified: the
+ *  spoof reached `clipboard.writeText`, and with a `display:none` decoy
+ *  block the user saw `npm install` while the clipboard took
+ *  `curl … | bash`. Structure cannot be the check, because an author can
+ *  reproduce any structure; only a secret they cannot read works, and
+ *  they cannot read this one because the sanitizer strips scripts. */
+export declare const CODE_COPY_ATTR = "data-code-copy";
+/** Returned when no CSPRNG is reachable. The listener refuses it, so the
+ *  copy button goes inert rather than becoming guessable — a feature that
+ *  quietly stops working is recoverable, a clipboard anyone can drive is
+ *  not. Every environment this ships to has one (browsers, Node >= 19,
+ *  jsdom), so this is the unreachable branch, not a supported mode. */
+export declare const CODE_COPY_NONCE_UNAVAILABLE = "";
+/** A value author-supplied markup cannot guess. Static text is the whole
+ *  threat: it never executes, so it can neither read nor predict this.
+ *  CSPRNG only — `Math.random` is not a fallback here, it is a weaker
+ *  version of the thing being defended. */
+export declare function createCodeCopyNonce(): string;
+/** Point the renderer at the document's nonce. `installCodeCopyHandler`
+ *  calls this on EVERY invocation, including the ones whose listener
+ *  install is a no-op, so a second bundle's renderer agrees with the one
+ *  listener that is actually running. */
+export declare function setCodeCopyNonce(value: string): void;
+/** The value the renderer is currently stamping. */
+export declare function codeCopyNonce(): string;
+/** Marks the wrapper the listener searches for the block's `<code>`. Its
+ *  VALUE is the block style, because the two are indistinguishable once
+ *  rendered and they must be copied differently: marked leaves a
+ *  trailing newline on an indented block, while the same newline on a
+ *  FENCED block is a blank line the author actually wrote. */
+export declare const CODE_COPY_BLOCK_ATTR = "data-code-copy-block";
+/** Value of the above for a 4-space block — the only style that carries
+ *  a renderer-added trailing newline. */
+export declare const CODE_BLOCK_STYLE_INDENTED = "indented";
+/** Value for every fenced block. */
+export declare const CODE_BLOCK_STYLE_FENCED = "fenced";
+/** The button carries BOTH label states, so the delegated listener needs
+ *  no label provider of its own. It cannot have a correct one: only the
+ *  first install on a document keeps its listener, so a plugin's buttons
+ *  would otherwise be captioned by whichever provider registered first. */
+export declare const CODE_COPY_IDLE_LABEL_ATTR = "data-code-copy-idle";
+export declare const CODE_COPY_COPIED_LABEL_ATTR = "data-code-copy-copied";
+/** The idle glyph. Exported so the click handler can swap it back. */
+export declare const CODE_COPY_ICON: string;
+/** The confirmation glyph shown for a moment after a successful copy. */
+export declare const CODE_COPIED_ICON: string;
+/** Idle button classes. The handler tints the button on success rather
+ *  than rewriting this list, so both states stay greppable. */
+export declare const CODE_COPY_BUTTON_CLASS: string;
+export declare const codeCopyExtension: MarkedExtension;

package/dist/markdown/codeCopyExtension.js

@@ -0,0 +1,187 @@
+// Marked `code` renderer override that gives every non-mermaid fenced
+// block a copy control in its top-right corner. The click behaviour is
+// NOT here — `codeCopyClipboard.ts` installs one delegated listener for
+// the whole document. This file stays pure (marked + the zero-dep
+// `@mulmoclaude/common` leaf) so tests can assert the html shape without
+// a browser.
+//
+// Why the renderer and not a post-render DOM scan (the shape
+// `useMermaidRenderer` uses): a viewer's `renderedHtml` is a computed
+// over streaming text, so `v-html` replaces the container's innerHTML on
+// every chunk. A scan-and-attach pass would re-insert a button into every
+// block on every chunk, and an "already attached" marker cannot prevent
+// it because the nodes it marked are gone after the next patch. Markup
+// emitted here rides along in the string Vue already writes.
+//
+// Why the button floats over a wrapper instead of sitting in a header
+// strip above the block: `pre` is styled by UNLAYERED css in at least
+// three places (`.markdown-content pre` in `src/index.css`, plus scoped
+// `:deep(pre)` in textResponse's and skill's Views). Unlayered rules beat
+// Tailwind's `@layer utilities` outright, so a utility on the `pre` could
+// not flatten its bottom corners — a header strip would mean editing the
+// global stylesheet in two packages. A wrapper the existing selectors do
+// not name collides with none of it. The button lives on the WRAPPER, not
+// inside the `pre`, so it stays put when a wide block scrolls sideways.
+//
+// Registration order (see setup.ts): AFTER `markedHighlightExtension`,
+// BEFORE `mermaidExtension`. Later `.use()` calls wrap earlier ones, so
+// mermaid ends up outermost and a `mermaid` fence short-circuits into its
+// placeholder without reaching this wrapper; every other fence falls
+// through to here. Registering after highlight is what lets us emit the
+// finished block: highlight's `walkTokens` has already rewritten
+// `token.text` to highlighted html and stamped `token.escaped`.
+import { escapeHtml } from "@mulmoclaude/common";
+const DEFAULT_LABELS = { copy: "Copy code", copied: "Copied" };
+let labelProvider = () => DEFAULT_LABELS;
+/**
+ * Point the renderer at the app's i18n. The provider is called on every
+ * render rather than once, so a host whose provider reads a REACTIVE
+ * locale gets live translations for free: the read lands inside the
+ * `renderedHtml` computed's evaluation and Vue re-runs it on locale
+ * change. Mirrors `setEmbedLocaleProvider`.
+ */
+export function setCodeCopyLabelProvider(provider) {
+    labelProvider = provider;
+}
+/** Test seam — restores the built-in English labels. */
+export function _resetCodeCopyLabelsForTests() {
+    labelProvider = () => DEFAULT_LABELS;
+}
+/** Marks the button for the delegated click listener. Its VALUE is a
+ *  per-document nonce, and the listener copies nothing without a match.
+ *
+ *  The attribute cannot be a bare marker: `marked` passes an author's raw
+ *  HTML straight through, DOMPurify's defaults keep `<button>` and every
+ *  `data-*`, and the listener is document-wide. A bare marker therefore
+ *  lets any rendered markdown — a cloned repository's README, which is
+ *  exactly what `sanitizeMarkdownHtml` exists for — mint a working copy
+ *  control and put text of its choosing on the clipboard. Verified: the
+ *  spoof reached `clipboard.writeText`, and with a `display:none` decoy
+ *  block the user saw `npm install` while the clipboard took
+ *  `curl … | bash`. Structure cannot be the check, because an author can
+ *  reproduce any structure; only a secret they cannot read works, and
+ *  they cannot read this one because the sanitizer strips scripts. */
+export const CODE_COPY_ATTR = "data-code-copy";
+const isRandomSource = (value) => typeof value === "object" && value !== null;
+const NONCE_BYTES = 16;
+const HEX_RADIX = 16;
+const HEX_PAIR = 2;
+/** Returned when no CSPRNG is reachable. The listener refuses it, so the
+ *  copy button goes inert rather than becoming guessable — a feature that
+ *  quietly stops working is recoverable, a clipboard anyone can drive is
+ *  not. Every environment this ships to has one (browsers, Node >= 19,
+ *  jsdom), so this is the unreachable branch, not a supported mode. */
+export const CODE_COPY_NONCE_UNAVAILABLE = "";
+/** A value author-supplied markup cannot guess. Static text is the whole
+ *  threat: it never executes, so it can neither read nor predict this.
+ *  CSPRNG only — `Math.random` is not a fallback here, it is a weaker
+ *  version of the thing being defended. */
+export function createCodeCopyNonce() {
+    const source = globalThis.crypto;
+    if (!isRandomSource(source))
+        return CODE_COPY_NONCE_UNAVAILABLE;
+    if (typeof source.randomUUID === "function")
+        return source.randomUUID();
+    if (typeof source.getRandomValues !== "function")
+        return CODE_COPY_NONCE_UNAVAILABLE;
+    const bytes = source.getRandomValues(new Uint8Array(NONCE_BYTES));
+    return Array.from(bytes, (byte) => byte.toString(HEX_RADIX).padStart(HEX_PAIR, "0")).join("");
+}
+// Seeded so a renderer used without the click handler still emits a value
+// no author can guess: the pairing then simply fails closed.
+let nonce = createCodeCopyNonce();
+/** Point the renderer at the document's nonce. `installCodeCopyHandler`
+ *  calls this on EVERY invocation, including the ones whose listener
+ *  install is a no-op, so a second bundle's renderer agrees with the one
+ *  listener that is actually running. */
+export function setCodeCopyNonce(value) {
+    nonce = value;
+}
+/** The value the renderer is currently stamping. */
+export function codeCopyNonce() {
+    return nonce;
+}
+/** Marks the wrapper the listener searches for the block's `<code>`. Its
+ *  VALUE is the block style, because the two are indistinguishable once
+ *  rendered and they must be copied differently: marked leaves a
+ *  trailing newline on an indented block, while the same newline on a
+ *  FENCED block is a blank line the author actually wrote. */
+export const CODE_COPY_BLOCK_ATTR = "data-code-copy-block";
+/** Value of the above for a 4-space block — the only style that carries
+ *  a renderer-added trailing newline. */
+export const CODE_BLOCK_STYLE_INDENTED = "indented";
+/** Value for every fenced block. */
+export const CODE_BLOCK_STYLE_FENCED = "fenced";
+/** The button carries BOTH label states, so the delegated listener needs
+ *  no label provider of its own. It cannot have a correct one: only the
+ *  first install on a document keeps its listener, so a plugin's buttons
+ *  would otherwise be captioned by whichever provider registered first. */
+export const CODE_COPY_IDLE_LABEL_ATTR = "data-code-copy-idle";
+export const CODE_COPY_COPIED_LABEL_ATTR = "data-code-copy-copied";
+// A fence tag is author-controlled text that lands in a class attribute,
+// so anything outside the shape marked already treats as a language name
+// is dropped rather than escaped — a tag is a word, and a "language"
+// holding markup is a typo at best.
+const SAFE_LANGUAGE = /^[A-Za-z0-9][A-Za-z0-9+#._-]{0,31}$/;
+const languageOf = (token) => {
+    const lang = (token.lang ?? "").trim().split(/\s+/)[0] ?? "";
+    return SAFE_LANGUAGE.test(lang) ? lang : "";
+};
+// Two overlapping rounded rectangles — the copy glyph every editor and
+// chat app uses. Inline rather than a `material-icons` class because the
+// icon font is imported by the HOST (`src/main.ts`), while this markup
+// also ships inside a plugin package a different host may load.
+const ICON_ATTRS = 'viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"';
+/** The idle glyph. Exported so the click handler can swap it back. */
+export const CODE_COPY_ICON = [
+    `<svg class="h-4 w-4" ${ICON_ATTRS}>`,
+    '<rect x="9" y="9" width="13" height="13" rx="2"></rect>',
+    '<path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path>',
+    "</svg>",
+].join("");
+/** The confirmation glyph shown for a moment after a successful copy. */
+export const CODE_COPIED_ICON = [`<svg class="h-4 w-4" ${ICON_ATTRS}>`, '<path d="M20 6 9 17l-5-5"></path>', "</svg>"].join("");
+/** Idle button classes. The handler tints the button on success rather
+ *  than rewriting this list, so both states stay greppable. */
+export const CODE_COPY_BUTTON_CLASS = [
+    "absolute top-2 right-2 z-10 inline-flex items-center justify-center",
+    "rounded-md border border-gray-300 bg-white/90 p-1.5 text-gray-600 shadow-sm",
+    "transition-colors hover:bg-gray-100 hover:text-gray-900",
+    "focus-visible:outline-2 focus-visible:outline-offset-2",
+].join(" ");
+export const codeCopyExtension = {
+    renderer: {
+        code(token) {
+            const language = languageOf(token);
+            // `escaped` is markedHighlight's flag that `text` is already html.
+            // Re-escaping it would turn `&quot;` into `&amp;quot;` and print the
+            // entity to the reader — the same trap documented in
+            // `mermaidExtension.ts`. Escape only when nobody has.
+            const body = token.escaped === true ? token.text : escapeHtml(token.text);
+            // Reproduces marked-highlight's own class shape (`langPrefix:
+            // "hljs language-"`, `emptyLangClass: "hljs"`) because this renderer
+            // replaces it rather than wrapping it — nothing calls through to
+            // highlight's renderer once we return a string.
+            const codeClass = language === "" ? "hljs" : `hljs language-${language}`;
+            const labels = labelProvider();
+            const idle = escapeHtml(labels.copy);
+            const copied = escapeHtml(labels.copied);
+            const style = token.codeBlockStyle === "indented" ? CODE_BLOCK_STYLE_INDENTED : CODE_BLOCK_STYLE_FENCED;
+            return [
+                `<div class="relative" ${CODE_COPY_BLOCK_ATTR}="${style}">`,
+                `<button type="button" ${CODE_COPY_ATTR}="${escapeHtml(nonce)}" ${CODE_COPY_IDLE_LABEL_ATTR}="${idle}" ${CODE_COPY_COPIED_LABEL_ATTR}="${copied}" class="${CODE_COPY_BUTTON_CLASS}" aria-label="${idle}" title="${idle}">`,
+                CODE_COPY_ICON,
+                "</button>",
+                // `dir="ltr"` isolates the block from an author's `dir="rtl"`
+                // wrapper. Without it the code renders right-aligned and a long
+                // line's LEFT end — where a payload would sit — scrolls out of
+                // view while the clipboard still takes the whole logical string.
+                // Measured: the rendered pixels change, the clipboard does not
+                // (codex round 2). Isolating the block rather than stripping the
+                // author's `dir` keeps legitimate right-to-left prose working.
+                `<pre dir="ltr"><code class="${codeClass}">${body}</code></pre>`,
+                "</div>\n",
+            ].join("");
+        },
+    },
+};

package/dist/markdown/mermaidRender.js

@@ -23,7 +23,11 @@ async function loadMermaid() {
         // instead of letting mermaid walk the document on DOMContentLoaded.
         // `securityLevel: "strict"` — mermaid sanitises its own labels and
         // will not execute user-authored HTML/JS in diagram text.
-        mermaid.initialize({ startOnLoad: false, securityLevel: "strict", theme: "default" });
+        // `layout` / `look` / `theme` — mermaid 12 moved its defaults to ELK +
+        // redux-color + neo, which re-lays out and recolours every diagram that
+        // already exists. These three pin the pre-12 appearance; changing the
+        // look is a deliberate design decision, not a side effect of an upgrade.
+        mermaid.initialize({ startOnLoad: false, securityLevel: "strict", theme: "default", layout: "dagre", look: "classic" });
         return mermaid;
     });
     // Share the in-flight promise with parallel callers, but drop the

package/dist/markdown/rawHtmlPolicy.d.ts

@@ -0,0 +1,14 @@
+import type { MarkedExtension } from "marked";
+/**
+ * Removes `class` and `style` from every tag in an HTML fragment, leaving
+ * text, comments and every other attribute byte-identical.
+ *
+ * Lexical on purpose: `marked` chunks raw HTML into pieces that are not
+ * well-formed — an opening `<div …>` and its `</div>` arrive as separate
+ * tokens — so parsing a chunk as a document and re-serialising it would
+ * close the first and delete the second.
+ */
+export declare function stripPresentationAttributes(fragment: string): string;
+/** Marked extension applying the rule. Register in every marked setup that
+ *  renders markdown the app did not write. */
+export declare const rawHtmlPolicyExtension: MarkedExtension;

package/dist/markdown/rawHtmlPolicy.js

@@ -0,0 +1,385 @@
+// Author-supplied raw HTML in markdown may carry neither `class` nor
+// `style`.
+//
+// WHY, and why the narrower rules do not work. Markdown passes raw HTML
+// straight through, and DOMPurify's defaults keep both attributes. That
+// lets a rendered file position content of its own over the app's output:
+// a `<pre>` absolutely positioned across a fenced code block, with an
+// opaque background, makes the reader see one command while the block
+// underneath holds another — and both the copy button and a plain text
+// selection then take the hidden one. Measured in a real browser
+// (receptron/mulmoclaude#3151).
+//
+// Banning `style` alone does NOT close it. This app ships a utility-CSS
+// framework, so the same overlay is available as `class="absolute inset-0
+// bg-white pointer-events-none"` with no `style` anywhere — every one of
+// those utilities is in the shipped stylesheet because the app's own UI
+// uses them. `mathRender.ts` warned about exactly this: a utility-CSS
+// framework turns a class name into positioning. A denylist of CSS
+// properties or class names is the shape that comes back every time
+// someone finds one more spelling, so the rule states what is PERMITTED:
+// neither attribute, on author HTML only.
+//
+// It applies to author HTML ONLY, which is possible because `marked`
+// routes raw HTML — and nothing else — through `renderer.html`. Highlight
+// spans, the copy button, mermaid placeholders and wiki EMBEDS come from
+// other renderers and keep their classes. The markdown-level sanitiser
+// cannot make that distinction: by the time it runs, the two are one
+// document.
+//
+// It once had to make an exception. `[[wiki-link]]` used to be a rewrite of the
+// markdown SOURCE, so its span arrived here indistinguishable from author HTML
+// and needed an unforgeable per-render nonce to keep its class. Wiki links are
+// a marked extension now (#3164), so nothing app-generated reaches this
+// renderer and the whole mechanism is gone — which is the point: a security
+// control with one fewer moving part, rather than one more.
+/** Attributes an author may not set. Presentation only — this is not the
+ *  XSS boundary, which stays with DOMPurify. */
+const FORBIDDEN = ["class", "style"];
+const isAsciiLetter = (char) => (char >= "a" && char <= "z") || (char >= "A" && char <= "Z");
+// HTML's whitespace is EXACTLY tab, LF, FF, CR and space. JavaScript's `\s`
+// is wider — NBSP, vertical tab, U+2028 and more — and using it here made
+// the scanner treat characters the tokenizer does not as attribute
+// separators: `<div\u00a0class=x>` has no `class` attribute to a parser, yet
+// it was being rewritten to `<div>` (codex round 6). Anywhere whitespace is
+// HTML SYNTAX, it has to be this set and not `\s`.
+const HTML_WHITESPACE = [" ", "\t", "\n", "\f", "\r"];
+const isHtmlWhitespace = (char) => HTML_WHITESPACE.includes(char);
+// Elements whose content the HTML parser reads as TEXT, not markup. Inside
+// them a `<div class=x>` is characters a reader is meant to see, so
+// rewriting it corrupts the document rather than protecting anyone —
+// `<textarea><div class=foo></textarea>` was coming out as
+// `<textarea><div></textarea>` (codex round 2). Only `textarea` currently
+// survives the sanitiser; the rest are here because this helper is exported
+// and must not depend on that staying true.
+const RAW_TEXT_ELEMENTS = ["textarea", "title", "script", "style", "xmp", "iframe", "noembed", "noframes", "plaintext"];
+/** `<plaintext>` has no end tag at all — it consumes the rest of the
+ *  document, `</plaintext>` included. Treating it like the others resumed
+ *  markup after a close tag no parser honours (codex round 3). */
+const UNCLOSEABLE_RAW_TEXT = "plaintext";
+/** True when `char` ends a TAG name. Deliberately NOT `endsAttributeName`:
+ *  that also stops at `=`, which the tokenizer's tag-name state keeps as part
+ *  of the name, so reusing it would leave `<style=foo>` reading as `style`. */
+function endsTagName(char) {
+    if (char === undefined)
+        return true;
+    return isHtmlWhitespace(char) || char === "/" || char === ">";
+}
+/** Name of the tag starting at `start`, lower-cased; "" for a closing tag
+ *  or anything that is not a plain element name.
+ *
+ *  The name runs to whitespace, `/` or `>` — HTML's own boundary — and not to
+ *  the end of a `[A-Za-z0-9-]` run. Stopping early made a name that merely
+ *  BEGINS with a raw-text one read as that element: `<style:foo>` came back as
+ *  `style`, so its contents were copied verbatim and a nested
+ *  `<pre class="absolute" style="position:absolute">` survived (codex round 17).
+ *  The attribute-name boundary had the identical bug in round 8 (`classé`); this
+ *  is the same rule one level up. */
+function openingTagName(fragment, start) {
+    if (fragment[start] !== "<" || !isAsciiLetter(fragment[start + 1] ?? ""))
+        return "";
+    let index = start + 1;
+    while (index < fragment.length && !endsTagName(fragment[index]))
+        index += 1;
+    return fragment.slice(start + 1, index).toLowerCase();
+}
+/** Index just past a `<!…>` run: `-->` for a real comment, the first `>`
+ *  for a doctype or bogus comment.
+ *
+ *  `<!-->` and `<!--->` are COMPLETE empty comments — the spec's
+ *  abrupt-closing-of-empty-comment, reached from comment-start and
+ *  comment-start-dash — so the markup after them is LIVE. Searching only for
+ *  `-->` from `start + 4` misses both, and the scanner then copied the rest of
+ *  the fragment verbatim: `<!---><pre class="absolute inset-0 bg-white">` kept
+ *  its class all the way through marked and the sanitiser, which is the overlay
+ *  this file exists to stop (codex round 21, P1). */
+function commentEnd(fragment, start) {
+    if (fragment.startsWith("<!--", start)) {
+        if (fragment[start + 4] === ">")
+            return start + 5;
+        if (fragment[start + 4] === "-" && fragment[start + 5] === ">")
+            return start + 6;
+        return commentBodyEnd(fragment, start + 4);
+    }
+    const close = fragment.indexOf(">", start);
+    return close === -1 ? fragment.length : close + 1;
+}
+/** Index just past whichever closes the comment first: `-->`, or `--!>` — the
+ *  spec's incorrectly-closed-comment, reached from comment-end-bang. Knowing
+ *  only `-->` made `<!--a--!>` read as unterminated, so the live markup after it
+ *  was swallowed and `<div class="absolute inset-0" style="position:absolute">`
+ *  kept both attributes. Same shape as the `<!--->` bypass, one variant along. */
+function commentBodyEnd(fragment, from) {
+    const plain = fragment.indexOf("-->", from);
+    const bang = fragment.indexOf("--!>", from);
+    if (plain === -1 && bang === -1)
+        return fragment.length;
+    if (bang === -1 || (plain !== -1 && plain <= bang))
+        return plain + 3;
+    return bang + 4;
+}
+/** Index just past the element's APPROPRIATE END TAG, searched from `from`.
+ *
+ *  "Appropriate" is HTML's own definition, not a rule of mine: the name has
+ *  to be followed by whitespace, `/` or `>`. A prefix match ends raw text at
+ *  `</textareax>`, which no parser does — verified against jsdom, where
+ *  `<textarea>keep </textareax><div class=foo></textarea>` has the VALUE
+ *  `keep </textareax><div class=foo>` (codex round 3).
+ *
+ *  The END of the fragment when there is no such tag, which is again what the
+ *  parser does, and the right answer when `marked` has split the element
+ *  across chunks. */
+function rawTextEnd(fragment, from, name) {
+    if (name === UNCLOSEABLE_RAW_TEXT)
+        return fragment.length;
+    const lowered = fragment.toLowerCase();
+    const needle = `</${name}`;
+    let search = from;
+    for (;;) {
+        const close = lowered.indexOf(needle, search);
+        if (close === -1)
+            return fragment.length;
+        const after = fragment[close + needle.length] ?? ">";
+        if (after === ">" || after === "/" || isHtmlWhitespace(after)) {
+            const closeEnd = fragment.indexOf(">", close);
+            return closeEnd === -1 ? fragment.length : closeEnd + 1;
+        }
+        search = close + 1;
+    }
+}
+/** True when `</` at `index` is NOT an end tag. HTML's end-tag-open state takes
+ *  an ASCII letter and nothing else: `>` drops the token, EOF emits the two
+ *  characters, and anything else opens a BOGUS COMMENT that runs to the next
+ *  `>`. All three want the bytes copied through untouched — and the last one
+ *  matters, because the text inside is comment content a parser never treats as
+ *  markup: `</é <span class=x>>` was having its inner span rewritten
+ *  (codex rounds 19-20). */
+function isBogusEndTag(fragment, index) {
+    return fragment[index + 1] === "/" && !isAsciiLetter(fragment[index + 2] ?? "");
+}
+/** True when `<?` opens a bogus comment. Tag-open takes `?` as an
+ *  unexpected-question-mark-instead-of-tag-name parse error and reconsumes in
+ *  bogus comment state, so everything to the next `>` is comment TEXT. Copying
+ *  only the `<` and scanning on rewrote that text: `<?x <span class=y>>` lost
+ *  the class a parser keeps (codex round 23). Every other non-letter after `<`
+ *  is literal text and needs no special case — the bytes are copied either way. */
+function isProcessingInstruction(fragment, index) {
+    return fragment[index + 1] === "?";
+}
+/** True when `<` at `index` opens a tag rather than being literal text.
+ *  `a < b` in prose must survive untouched.
+ *
+ *  A closing tag needs an ASCII LETTER after the `/`, which is HTML's own rule:
+ *  end-tag-open only enters end-tag-name for a letter, and treats anything else
+ *  as a bogus comment. Accepting any `</` rewrote parser COMMENT text as if it
+ *  were a tag — `</ class=x>` came back as `</>`, while a parser reads the
+ *  original as `<!-- class=x-->` (codex round 19). Left alone the bytes are
+ *  copied through and the parser still sees its comment. */
+function opensTag(fragment, index) {
+    const next = fragment[index + 1];
+    if (next === undefined)
+        return false;
+    if (next === "/")
+        return isAsciiLetter(fragment[index + 2] ?? "");
+    return isAsciiLetter(next);
+}
+/** Index just past the `>` that closes the tag starting at `start`, with
+ *  quoted attribute values skipped so a `>` inside one does not end it.
+ *  Returns the string length for an unterminated tag. */
+function tagEnd(fragment, start) {
+    let quote = "";
+    // A quote opens a VALUE only after `=`. In attribute-name position a
+    // quote is a parse error that the tokenizer keeps as part of the name,
+    // so treating every quote as a value delimiter swallowed the rest of
+    // the tag: `<div ">text class=x</div>` lost its literal text, because
+    // the `"` was read as opening a value that ran past the `>`
+    // (codex round 5).
+    let afterEquals = false;
+    for (let index = start; index < fragment.length; index += 1) {
+        const char = fragment[index] ?? "";
+        if (quote !== "") {
+            if (char === quote)
+                quote = "";
+            continue;
+        }
+        if (char === ">")
+            return index + 1;
+        if (char === "=") {
+            afterEquals = true;
+            continue;
+        }
+        // Whitespace between `=` and the value does not end the wait for one.
+        if (isHtmlWhitespace(char))
+            continue;
+        if (afterEquals && (char === '"' || char === "'")) {
+            quote = char;
+        }
+        afterEquals = false;
+    }
+    return fragment.length;
+}
+/** Index just past an attribute value beginning at `start` (which may be
+ *  quoted or bare). */
+function valueEnd(tag, start) {
+    const first = tag[start];
+    if (first === '"' || first === "'") {
+        const close = tag.indexOf(first, start + 1);
+        return close === -1 ? tag.length : close + 1;
+    }
+    let index = start;
+    while (index < tag.length && !isHtmlWhitespace(tag[index] ?? ">") && tag[index] !== ">")
+        index += 1;
+    return index;
+}
+/** Length of the `=value` that may follow an attribute name at `from`,
+ *  including surrounding whitespace. Zero when the attribute is bare. */
+function assignmentLength(tag, from) {
+    let index = from;
+    while (index < tag.length && isHtmlWhitespace(tag[index] ?? ""))
+        index += 1;
+    if (tag[index] !== "=")
+        return { length: 0, quoted: false };
+    index += 1;
+    while (index < tag.length && isHtmlWhitespace(tag[index] ?? ""))
+        index += 1;
+    const first = tag[index];
+    return { length: valueEnd(tag, index) - from, quoted: first === '"' || first === "'" };
+}
+/** True when `char` ends an attribute name rather than continuing it. */
+function endsAttributeName(char) {
+    if (char === undefined)
+        return true;
+    return isHtmlWhitespace(char) || char === "=" || char === "/" || char === ">";
+}
+/** Index just past `<`, an optional `/`, and the tag name.
+ *
+ *  The attribute walk has to START here. Beginning at the `<` instead made the
+ *  NAME of a closing tag read as an attribute, because `/` is an attribute
+ *  separator: `</style=foo>` matched separator `/` + name `style`, which is
+ *  FORBIDDEN, and the tag was eaten down to `<>`. It stayed invisible only
+ *  because a real `</style>` is reached through `rawTextEnd` and never comes
+ *  here — a name that merely begins with a raw-text one does. */
+function tagNameEnd(tag) {
+    let index = tag[1] === "/" ? 2 : 1;
+    while (index < tag.length && !endsTagName(tag[index]))
+        index += 1;
+    return index;
+}
+/** Index just past a run of separators — whitespace, or a `/` that is not
+ *  closing the tag. HTML's before-attribute-name state treats such a `/` as a
+ *  parse error and then reads an attribute name anyway, so
+ *  `<div /class="absolute">` really does set a class (codex round 4, P1). */
+function separatorEnd(tag, from) {
+    let index = from;
+    while (index < tag.length && (isHtmlWhitespace(tag[index] ?? "") || tag[index] === "/"))
+        index += 1;
+    return index;
+}
+function readAttribute(tag, nameStart) {
+    // An `=` in before-attribute-name is a parse error that becomes the name's
+    // FIRST character, not a value separator — `<div ="x" class="y">` really has
+    // an attribute called `="x"` and then a separate `class`. Treating it as a
+    // boundary made the walk abandon the rest of the tag, so that `class`
+    // survived (found re-auditing the rewrite against the tokenizer, round 19).
+    let index = nameStart + (tag[nameStart] === "=" ? 1 : 0);
+    while (index < tag.length && !endsAttributeName(tag[index]))
+        index += 1;
+    return { end: index + assignmentLength(tag, index).length, name: tag.slice(nameStart, index) };
+}
+/** Whether the separators before a dropped attribute may go with it. They may,
+ *  unless the next attribute has none of its own — which HTML allows directly
+ *  after a quoted value, and where dropping them fuses `<div class="x"id="a">`
+ *  into `<divid="a">`. */
+function separatorsAreSpare(tag, after) {
+    const next = tag[after];
+    return next === undefined || next === ">" || next === "/" || isHtmlWhitespace(next);
+}
+/** Removes the forbidden attributes from ONE tag's source text. */
+function stripFromTag(tag) {
+    let index = tagNameEnd(tag);
+    const out = [tag.slice(0, index)];
+    while (index < tag.length) {
+        const nameStart = separatorEnd(tag, index);
+        if (nameStart >= tag.length || tag[nameStart] === ">") {
+            out.push(tag.slice(index));
+            break;
+        }
+        const attribute = readAttribute(tag, nameStart);
+        if (FORBIDDEN.includes(attribute.name.toLowerCase()))
+            out.push(separatorsAreSpare(tag, attribute.end) ? "" : " ");
+        else
+            out.push(tag.slice(index, attribute.end));
+        index = attribute.end;
+    }
+    return out.join("");
+}
+/**
+ * Removes `class` and `style` from every tag in an HTML fragment, leaving
+ * text, comments and every other attribute byte-identical.
+ *
+ * Lexical on purpose: `marked` chunks raw HTML into pieces that are not
+ * well-formed — an opening `<div …>` and its `</div>` arrive as separate
+ * tokens — so parsing a chunk as a document and re-serialising it would
+ * close the first and delete the second.
+ */
+export function stripPresentationAttributes(fragment) {
+    const out = [];
+    let index = 0;
+    while (index < fragment.length) {
+        const char = fragment[index] ?? "";
+        if (char !== "<") {
+            out.push(char);
+            index += 1;
+            continue;
+        }
+        // Comments, doctype, CDATA, bogus end tags and `<?…>` processing
+        // instructions are copied verbatim; they carry no attributes and their
+        // contents must not be treated as tags.
+        //
+        // `<![CDATA[` is read as HTML's bogus comment — ending at the first `>` —
+        // which is right everywhere markdown raw HTML actually lands. Inside
+        // FOREIGN content (`<svg>`, `<math>`) a parser would instead run it to
+        // `]]>`, so a `>` in the body diverges. Not fixed on purpose: knowing
+        // whether we are in foreign content needs element state that cannot survive
+        // marked handing raw HTML over in chunks, and the divergence only ever
+        // rewrites text a parser keeps — it cannot let an attribute through.
+        // Where each one ENDS is the whole question, and both directions have been
+        // wrong. Too early: a comment runs to `-->`, not to the first `>`, or its
+        // later text gets rewritten (round 3). Too late: `<!-->`, `<!--->` and
+        // `--!>` all end a comment where a `-->` search does not find one, and the
+        // live markup after them was swallowed and kept its class (rounds 21-22).
+        // `commentEnd` owns every one of those rules.
+        if (fragment.startsWith("<!", index) || isBogusEndTag(fragment, index) || isProcessingInstruction(fragment, index)) {
+            const end = commentEnd(fragment, index);
+            out.push(fragment.slice(index, end));
+            index = end;
+            continue;
+        }
+        if (!opensTag(fragment, index)) {
+            out.push(char);
+            index += 1;
+            continue;
+        }
+        const end = tagEnd(fragment, index);
+        out.push(stripFromTag(fragment.slice(index, end)));
+        const name = openingTagName(fragment, index);
+        if (RAW_TEXT_ELEMENTS.includes(name)) {
+            // Copy the element's text content — and its close tag — verbatim.
+            const rawEnd = rawTextEnd(fragment, end, name);
+            out.push(fragment.slice(end, rawEnd));
+            index = rawEnd;
+            continue;
+        }
+        index = end;
+    }
+    return out.join("");
+}
+/** Marked extension applying the rule. Register in every marked setup that
+ *  renders markdown the app did not write. */
+export const rawHtmlPolicyExtension = {
+    renderer: {
+        html(token) {
+            return stripPresentationAttributes(token.text);
+        },
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmoclaude/markdown-utils",
-  "version": "2.2.0",
+  "version": "3.0.0",
   "description": "Browser-safe markdown / image rendering utilities shared by the MulmoClaude host and the markdown plugin",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,19 +33,19 @@
   "license": "MIT",
   "author": "Receptron Team",
   "dependencies": {
-    "@mulmoclaude/common": "^1.2.0",
-    "dompurify": "^3.4.13",
-    "js-yaml": "^5.4.1",
-    "marked": "^18.0.11"
+    "@mulmoclaude/common": "^1.3.0",
+    "dompurify": "^3.4.15",
+    "js-yaml": "^5.4.2",
+    "marked": "^18.0.13"
   },
   "peerDependencies": {
     "mathjax-full": "^3.2.2",
-    "mermaid": "^11.16.1",
+    "mermaid": "^12.0.0",
     "vue": "^3.5.0"
   },
   "devDependencies": {
     "mathjax-full": "^3.2.2",
-    "mermaid": "^11.17.2",
+    "mermaid": "^12.0.0",
     "typescript": "^6.0.3",
     "vue": "^3.5.42"
   },