From dfc086b3abd9c616a5008fee2cfc078239c926c1 Mon Sep 17 00:00:00 2001
From: Jason Grey <jason@jason-grey.com>
Date: Wed, 13 May 2026 20:00:53 -0500
Subject: [PATCH] docs(faq): explain the runtime-DOM-mutation false-invalid
 case

Adds an FAQ entry for the failure mode we hit on this site: the
Hugo Blox theme injects copy buttons into <pre> blocks at runtime,
which makes the live-DOM innerHTML disagree with the static HTML
the signer hashed. The signature is mathematically correct, but
the verifier reads a different canonical text and reports invalid.

Documents the three practical workarounds (configure/patch the
theme, pre-render decoration server-side, move decoration outside
the signed region) and links to the matching Known Issue section
in the spec README.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 content/faq/_index.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/content/faq/_index.md b/content/faq/_index.md
index d520499..5ec42cb 100644
--- a/content/faq/_index.md
+++ b/content/faq/_index.md
@@ -58,6 +58,26 @@ Yes — that is a core feature. Each `<signed-section>` is independent, so a sin
 
 HTMLTrust degrades gracefully. Unsigned or unrecognized `<signed-section>` elements render as normal content. Only the verification features are unavailable. The page remains fully readable and functional.
 
+## Why does a signed page show as *invalid* in the browser even when the signature is mathematically correct?
+
+This is a real, observed issue: HTMLTrust signs the **static HTML** that leaves the publishing pipeline, but the browser extension verifies against the **live DOM** — the state of the page after every script on the page has finished running. If anything inside a `<signed-section>` is mutated between page load and verification, the recomputed `content-hash` won't match the signed one, and the extension reports an invalid signature.
+
+We hit this on our own site initially: the Hugo Blox docs theme injects a `<button class="copy-button">Copy</button>` into every `<pre>` code block at runtime. The signer never saw the button, so the canonical text the verifier reads includes extra "Copy" tokens that aren't in the hash.
+
+Other common culprits:
+
+- Client-side syntax highlighters (Prism, highlight.js) that rewrite code blocks
+- Lazy-loading or share-button widgets that add nodes inside article content
+- Theme JS that decorates headings, callouts, or admonitions at runtime
+
+**What to do about it** — until the spec defines a mutation-skip marker, the practical workarounds are:
+
+1. Configure or patch the theme so it does **not** inject nodes inside `<signed-section>` descendants
+2. Pre-render any decoration server-side, so the signer hashes it
+3. Move runtime-injected decoration **outside** the signed region (as a sibling, not a child)
+
+This is being tracked as a spec open design question — see [Known Issue: Runtime DOM Mutation](https://github.com/HTMLTrust/htmltrust-spec#known-issue-runtime-dom-mutation-breaks-verification) in the spec README.
+
 ## What browsers are supported?
 
 A reference browser extension is available for **Chrome** (and Chromium-based browsers like Edge). Firefox and Safari support is planned. Eventually, the goal is native browser support via a W3C standard.