styleproof 1.9.3 → 1.10.0

package/CHANGELOG.md

@@ -7,14 +7,67 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [1.10.0] - 2026-06-22
+
+### Added
+
+- **`approve-all` input.** In review-gate mode, render a single **Approve all
+  changes** checkbox at the top of the report instead of one box per change, so a
+  reviewer signs off every change with one tick. Off by default (per-change boxes
+  are unchanged); the `styleproof-approve` workflow accepts either shape.
+- **Fork and Dependabot support.** The Action now resolves the PR number and head
+  SHA in an event-aware way, so it can be driven from a `workflow_run` as well as
+  from `pull_request`. New example workflows `example/styleproof-capture.yml`
+  (read-only `pull_request` capture + artifact upload) and
+  `example/styleproof-report.yml` (`workflow_run` report under a write token, never
+  running the PR's code) let fork and Dependabot PRs gate without handing a write
+  token to untrusted code — the secure alternative to `pull_request_target`. PR
+  identity is taken only from the trusted `workflow_run` event (`head_sha`, the
+  event's `pull_requests`, and a commit→PR lookup against that same head SHA for
+  forks) — never from the capture artifact — so an untrusted PR cannot redirect the
+  privileged comment or status at a victim PR or commit.
+
+### Fixed
+
+- **Real focus no longer makes `:focus` capture nondeterministic.** Capture froze
+  motion (`FREEZE_CSS`) and the clock but never neutralised real DOM focus, so
+  whatever element happened to hold focus at capture time (autofocus, late
+  hydration, a stray prior action) contaminated the capture across runs: it baked
+  a focus ring into the resting `elements` map, and it cancelled the forced-state
+  `:focus` delta — forcing `:focus` on an already-focused element changes nothing,
+  so the ring showed up as a delta on some runs but not others, surfacing as a
+  self-check `outline-color: … → (state does not change it)` failure on a no-op
+  PR. `captureStyleMap` now blurs the active element before any read, mirroring
+  the motion freeze; `:hover`/`:focus`/`:active` are still certified
+  deterministically via CDP `forcePseudoState`.
+- **SSE streams no longer read as phantom diffs under replay.** A long-lived
+  stream can't round-trip through a HAR, so `routeFromHAR`'s url glob (default
+  `**/api/**`) would intercept an app's `EventSource` endpoint and, on the replay
+  run, abort it — dropping the app to its no-stream fallback (a different but
+  _stable_ render that settle/volatile can't catch). That surfaced as a
+  computed-style change on every diff even when no CSS changed. Capture now lets
+  `Accept: text/event-stream` requests bypass record/replay and reach the live
+  server on both runs, so both sides see the same streamed state. Stream-pushed
+  data must be deterministic at capture time (fixtures/frozen clock), as the
+  README already requires of live regions.
+- The README CI recipe pointed `baseline-dir` / `fresh-dir` at the bare `base` /
+  `head` labels, but captures land under `baseDir` (`__stylemaps__/base`,
+  `__stylemaps__/head`), so `styleproof-diff` failed with `no capture at base`.
+  The recipe now uses the full `__stylemaps__/<label>` paths.
+
+## [1.9.4]
+
+### Changed
+
+- Repository URLs now use the canonical `BenSheridanEdwards/StyleProof` casing
+  everywhere — README badges, Action references, and doc links, plus the CHANGELOG
+  compare links, CONTRIBUTING, SECURITY, `action.yml`, and the release workflow.
+  (npm package-name URLs stay lowercase, as npm requires.)
+
 ## [1.9.3]
 
 ### Changed
 
-- Maintainer contact moved off a personal email address: security issues now go
-  through GitHub's private vulnerability reporting and conduct reports through the
-  maintainer's GitHub profile, and the `package.json` `author` no longer carries an
-  email. The published package and its metadata are now contact-clean.
 - Canonical `StyleProof`-cased GitHub URLs in `package.json` (`homepage`,
   `repository`, `bugs`).
 
@@ -503,15 +556,15 @@ number)`), so each viewport band can capture at its own height. Default remains
 - `styleproof-diff` CLI: certifies a refactor (exit 0) or names the exact element,
   property, and state that drifted (exit 1).
 
-[Unreleased]: https://github.com/BenSheridanEdwards/styleproof/compare/v1.2.0...HEAD
-[1.2.0]: https://github.com/BenSheridanEdwards/styleproof/compare/v1.1.0...v1.2.0
-[1.1.0]: https://github.com/BenSheridanEdwards/styleproof/compare/v1.0.0...v1.1.0
-[1.0.0]: https://github.com/BenSheridanEdwards/styleproof/compare/v0.7.0...v1.0.0
-[0.7.0]: https://github.com/BenSheridanEdwards/styleproof/compare/v0.6.0...v0.7.0
-[0.6.0]: https://github.com/BenSheridanEdwards/styleproof/compare/v0.5.0...v0.6.0
-[0.5.0]: https://github.com/BenSheridanEdwards/styleproof/compare/v0.4.0...v0.5.0
-[0.4.0]: https://github.com/BenSheridanEdwards/styleproof/compare/v0.3.0...v0.4.0
-[0.3.0]: https://github.com/BenSheridanEdwards/styleproof/compare/v0.2.1...v0.3.0
-[0.2.1]: https://github.com/BenSheridanEdwards/styleproof/compare/v0.2.0...v0.2.1
-[0.2.0]: https://github.com/BenSheridanEdwards/styleproof/compare/v0.1.0...v0.2.0
-[0.1.0]: https://github.com/BenSheridanEdwards/styleproof/releases/tag/v0.1.0
+[Unreleased]: https://github.com/BenSheridanEdwards/StyleProof/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v0.7.0...v1.0.0
+[0.7.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v0.2.1...v0.3.0
+[0.2.1]: https://github.com/BenSheridanEdwards/StyleProof/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/BenSheridanEdwards/StyleProof/releases/tag/v0.1.0

package/README.md

@@ -3,8 +3,8 @@
 **Know exactly what every PR changes visually, and sign it off.** StyleProof captures the browser's _computed_ styles (not pixels), diffs your PR's HEAD against its base branch, and posts a per-change report on the PR, so a styling change never ships without someone confirming it was intended.
 
 [![npm version](https://img.shields.io/npm/v/styleproof.svg)](https://www.npmjs.com/package/styleproof)
-[![CI](https://github.com/BenSheridanEdwards/styleproof/actions/workflows/ci.yml/badge.svg)](https://github.com/BenSheridanEdwards/styleproof/actions)
-[![license](https://img.shields.io/npm/l/styleproof.svg)](https://github.com/BenSheridanEdwards/styleproof/blob/main/LICENSE)
+[![CI](https://github.com/BenSheridanEdwards/StyleProof/actions/workflows/ci.yml/badge.svg)](https://github.com/BenSheridanEdwards/StyleProof/actions)
+[![license](https://img.shields.io/npm/l/styleproof.svg)](https://github.com/BenSheridanEdwards/StyleProof/blob/main/LICENSE)
 
 ## Why
 
@@ -15,7 +15,7 @@ Pixel-snapshot tools miss most CSS regressions: they can't force `:hover` / `:fo
 On every PR, StyleProof captures a `StyleMap` from the HEAD and from the base branch, diffs them, and posts a Markdown comment:
 
 - A summary line, then **one section per distinct change**, with a side-by-side before/after cropped screenshot (both sides cropped from the same rectangle, so they line up exactly) and **plain-English bullets that tell you what to look for** (`columns: 2 → 3`, `recoloured cyan → amber`) above the exact property changes, folded under a toggle.
-- An **approval checkbox per change**, driving a `StyleProof` commit status: red until every change is signed off, green when there are none.
+- An **approval checkbox per change** — or, with `approve-all: true`, a single **Approve all changes** box at the top that signs off everything in one tick — driving a `StyleProof` commit status: red until signed off, green when there are none.
 - **New surfaces don't block.** A surface that exists only on the PR head (no baseline to diff — e.g. the bootstrap PR that first adds the capture spec, or a brand-new page) is shown with its screenshot under a `🆕 new surface` heading and an _optional_ approval box, but it never holds the status red. It becomes part of the baseline once merged.
 - No committed baseline to maintain — the diff is HEAD-vs-base, so the report is _exactly what this PR changes_.
 
@@ -111,17 +111,32 @@ jobs:
       - run: STYLEMAP_DIR=head STYLEPROOF_REPLAY_FROM=__stylemaps__/base npx playwright test e2e/styleproof.spec.ts
 
       # report + gate
-      - uses: BenSheridanEdwards/styleproof@v1
+      - uses: BenSheridanEdwards/StyleProof@v1
         with:
-          baseline-dir: base
-          fresh-dir: head
+          baseline-dir: __stylemaps__/base # captures land under baseDir (default __stylemaps__)
+          fresh-dir: __stylemaps__/head
           require-approval: true # review-gate mode (omit / use fail-on-diff: true to certify)
 ```
 
-**3. Copy [`example/styleproof-approve.yml`](https://github.com/BenSheridanEdwards/styleproof/blob/main/example/styleproof-approve.yml) to `.github/workflows/` on your default branch** — GitHub only runs `issue_comment` workflows from there, so the checkboxes do nothing until it's merged.
+**3. Copy [`example/styleproof-approve.yml`](https://github.com/BenSheridanEdwards/StyleProof/blob/main/example/styleproof-approve.yml) to `.github/workflows/` on your default branch** — GitHub only runs `issue_comment` workflows from there, so the checkboxes do nothing until it's merged.
 
 **4. Require the `StyleProof` status** in branch protection. Now an unsigned visual change can't merge.
 
+## Forks and Dependabot
+
+The single-workflow setup above runs the whole gate in one `pull_request` job — which needs a **write** token to push the report branch, post the comment, and set the `StyleProof` status. That's fine for same-repo PRs, but **fork and Dependabot PRs run with a read-only `GITHUB_TOKEN`** (GitHub's security default for untrusted PRs). So the job can't post the status — and a required `StyleProof` check then sits `pending` forever, blocking the PR even though a dependency or fork change usually touches no UI at all.
+
+Fix it by splitting capture from reporting, the way the approve workflow is already split out:
+
+- **[`example/styleproof-capture.yml`](example/styleproof-capture.yml)** runs `on: pull_request` with a **read-only** token and no secrets — safe to run untrusted PR code. It only builds, captures the style maps, and uploads them as an artifact.
+- **[`example/styleproof-report.yml`](example/styleproof-report.yml)** runs `on: workflow_run` (after capture finishes) from your **default branch** with a write token. It downloads the artifact and does the diff, comment, and status — but **never checks out or runs the PR's code**, only the trusted style-map data.
+
+That last point is why this works where `pull_request_target` does not: StyleProof builds and serves the PR's head, so running it under `pull_request_target` would hand a write token (and your secrets) to untrusted code — the exact supply-chain risk StyleProof exists to help you catch. The `workflow_run` split keeps the privileged half away from PR code entirely.
+
+**Where the PR identity comes from.** The report stage comments on the PR and sets the `StyleProof` status against a specific PR number and head commit, so those values have to be trustworthy. It takes them from the trusted `workflow_run` event — `head_sha`, then the event's `pull_requests`, with a commit→PR lookup against that **same trusted head SHA** for fork PRs (whose association the event doesn't carry directly) — and **never** from the downloaded artifact. The artifact is produced by the untrusted capture job, so treating anything in it as identity would let a malicious PR point the privileged comment and status at a victim PR or an arbitrary commit (a confused-deputy attack). The artifact therefore carries only the style-map captures, consumed purely as diff input.
+
+Copy both `capture` and `report` files to `.github/workflows/` (the `report` one must be on your default branch, like `styleproof-approve.yml`), then require the `StyleProof` status as in step 4. The single-job `styleproof.yml` above remains fine for repos that never see fork or bot PRs.
+
 **Deterministic by default — no fixtures required.** A style diff only means something if both sides saw the same inputs; otherwise live-data drift (a backend blip, a `5m ago` timestamp, a status chip that flips) reads as a style change on a PR that touched no CSS. StyleProof handles this for you:
 
 - **Record / replay.** The base capture records each surface's data responses (anything matching `**/api/**`) to a HAR; the head capture replays them, so the head renders _its_ code against the _base's_ data — the app's own JS/CSS still load live. Backend down during a run? Both sides replay the same recording, so there's no phantom diff. Point the head capture at the base's recording with `STYLEPROOF_REPLAY_FROM=<base dir>` (see the CI step above); tune the data boundary with `STYLEPROOF_REPLAY_URL` / `replayUrl` if your API isn't under `/api`.
@@ -133,19 +148,40 @@ jobs:
 
 **Live pages just work.** Before each capture, StyleProof settles the page — it waits until the computed-style map stops changing, so async content (a fetch, an SSE/WebSocket stream backfilling a grid) is captured loaded, not mid-load. Anything still moving on its own after that is detected as a live region and excluded from the diff, so a stream or ticker never reads as a change — no manual `ignore` needed. Disable or tune with `captureStyleMap(page, { stabilize: false })` / `{ stabilize: { quietFor, timeout } }`.
 
+## Optional: content layer (advisory)
+
+StyleProof is **computed-styles first**, and stays that way: a CSS-only refactor that also rewrites text is still certified identical, and live text (a clock, "2m ago") never reads as a change. But a pure-style diff is blind to copy, and copy isn't always cosmetic: **new or longer text can overflow or clip its box, silently breaking the layout.** A visual-confidence tool that can't see that isn't quite complete. So the content layer exists as an explicit **opt-in**, off by default, and **advisory** — it never feeds the certification or the gate.
+
+Turn it on in two places:
+
+```ts
+// styleproof.spec.ts — record each element's own text alongside its computed style
+defineStyleMapCapture({ surfaces: SURFACES, dir: process.env.STYLEMAP_DIR, captureText: true });
+```
+
+```bash
+# render the advisory content section (each change with a before/after crop)
+styleproof-report before after --out report --include-content
+```
+
+The report then carries a separate **📝 Content changes (advisory)** section: every element whose own text changed, with the before/after strings and a side-by-side crop, so a silent copy edit (and any overflow it causes) is visible in review. It does **not** affect `changed`, the `StyleProof` status, or the diff exit code, by design. With capture left at its default (`captureText` off), there's no text in the maps and the section is always empty, so existing setups are completely unaffected.
+
+Notes: only an element's _own_ text is recorded (so a parent and child never double-report the same string); text churn in a live region is auto-excluded by the same settle pass that guards styles; and the certification CLI (`styleproof-diff`) is deliberately left content-blind.
+
 ## Reference
 
-**Action `BenSheridanEdwards/styleproof@v1`** — key inputs:
+**Action `BenSheridanEdwards/StyleProof@v1`** — key inputs:
 
-| Input              | Default      | Purpose                                                                    |
-| ------------------ | ------------ | -------------------------------------------------------------------------- |
-| `baseline-dir`     | _required_   | Base-branch captures.                                                      |
-| `fresh-dir`        | _required_   | PR-head captures to compare.                                               |
-| `require-approval` | `false`      | Review-gate mode: set the `StyleProof` status instead of failing.          |
-| `fail-on-diff`     | `true`       | Certify mode: fail on any diff. Ignored when `require-approval` is true.   |
-| `status-context`   | `StyleProof` | Commit-status name. Must match the approve workflow and branch protection. |
+| Input              | Default      | Purpose                                                                                 |
+| ------------------ | ------------ | --------------------------------------------------------------------------------------- |
+| `baseline-dir`     | _required_   | Base-branch captures.                                                                   |
+| `fresh-dir`        | _required_   | PR-head captures to compare.                                                            |
+| `require-approval` | `false`      | Review-gate mode: set the `StyleProof` status instead of failing.                       |
+| `fail-on-diff`     | `true`       | Certify mode: fail on any diff. Ignored when `require-approval` is true.                |
+| `status-context`   | `StyleProof` | Commit-status name. Must match the approve workflow and branch protection.              |
+| `approve-all`      | `false`      | Review-gate UI: one **Approve all changes** box at the top instead of per-change boxes. |
 
-Outputs: `changed` (`"true"` when anything changed), `report-url`. Other inputs (`report-branch`, `inline-images`, `github-token`) have sensible defaults — see [`action.yml`](https://github.com/BenSheridanEdwards/styleproof/blob/main/action.yml).
+Outputs: `changed` (`"true"` when anything changed), `report-url`. Other inputs (`report-branch`, `inline-images`, `github-token`) have sensible defaults — see [`action.yml`](https://github.com/BenSheridanEdwards/StyleProof/blob/main/action.yml).
 
 **Capture spec `defineStyleMapCapture({ surfaces, … })`** — determinism is on by default; you rarely set more than `surfaces` and `dir`:
 
@@ -176,9 +212,9 @@ Non-visual and framework-injected elements (`<meta>`/`<title>`/`<script>`/`<styl
 
 - `styleproof-init` — scaffold the capture spec (and a starter `playwright.config.ts` if none exists).
 - `styleproof-diff <beforeDir> <afterDir>` — the certify gate; exits `1` on any difference.
-- `styleproof-report <beforeDir> <afterDir> --out <dir>` — render the diff to a Markdown report with before/after crops.
+- `styleproof-report <beforeDir> <afterDir> --out <dir>` — render the diff to a Markdown report with before/after crops. Add `--include-content` for the opt-in, advisory content section (see above).
 
-A programmatic API (`captureStyleMap`, `diffStyleMaps`, `generateStyleMapReport`, …) is also exported. For the capture internals, the approve-workflow trust model, and how to contribute, see [CONTRIBUTING](https://github.com/BenSheridanEdwards/styleproof/blob/main/CONTRIBUTING.md) and the [`example/`](https://github.com/BenSheridanEdwards/styleproof/tree/main/example) workflows.
+A programmatic API (`captureStyleMap`, `diffStyleMaps`, `generateStyleMapReport`, …) is also exported. For the capture internals, the approve-workflow trust model, and how to contribute, see [CONTRIBUTING](https://github.com/BenSheridanEdwards/StyleProof/blob/main/CONTRIBUTING.md) and the [`example/`](https://github.com/BenSheridanEdwards/StyleProof/tree/main/example) workflows.
 
 ## License
 

package/bin/styleproof-report.mjs

@@ -28,6 +28,10 @@ options:
   --include-layout-noise    keep size/position-derived longhands (height, width,
                             transform-origin, top…) that a reflow changes up the
                             whole ancestor chain (off by default)
+  --include-content         render the opt-in content layer: an advisory section
+                            of elements whose text changed, each with a
+                            before/after crop. Needs captures taken with
+                            captureText:true; never affects the check (off by default)
   -h, --help                show this help
 
 exit: 0 no changes, 1 report generated, 2 usage error.
@@ -42,6 +46,7 @@ let foldDetailsAt;
 let minWidth;
 let minHeight;
 let includeLayoutNoise = false;
+let includeContent = false;
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
   if (a === '-h' || a === '--help') {
@@ -63,6 +68,8 @@ for (let i = 0; i < argv.length; i++) {
   else if (a.startsWith('--min-height=')) minHeight = Number(a.slice(13));
   else if (a === '--include-layout-noise') includeLayoutNoise = true;
   else if (a.startsWith('--include-layout-noise=')) includeLayoutNoise = a.slice(23) !== 'false';
+  else if (a === '--include-content') includeContent = true;
+  else if (a.startsWith('--include-content=')) includeContent = a.slice(18) !== 'false';
   else if (a.startsWith('--')) {
     console.error(`unknown flag: ${a}`);
     process.exit(2);
@@ -102,6 +109,7 @@ try {
     minWidth,
     minHeight,
     includeLayoutNoise,
+    includeContent,
   });
 } catch (e) {
   console.error(e.message);
@@ -117,4 +125,7 @@ console.log(
     : `✗ ${result.changedSurfaces} changed surface(s), ${result.totalFindings} finding(s)${newNote}`,
 );
 console.log(`report: ${result.reportMdPath}`);
+if (includeContent && result.contentChanges > 0) {
+  console.log(`📝 ${result.contentChanges} advisory content change(s) — does not affect the exit code`);
+}
 process.exit(result.changedSurfaces === 0 && result.newSurfaces === 0 ? 0 : 1);

package/dist/capture.d.ts

@@ -33,6 +33,15 @@ export type ElementEntry = {
     rect?: Rect;
     style: Props;
     pseudo?: Record<string, Props>;
+    /**
+     * The element's OWN rendered text (direct text-node children only, whitespace
+     * collapsed) — present only when capture ran with `captureText: true` (the
+     * opt-in content layer, off by default). Own-text, not subtree text, so each
+     * change is attributed to the single element that owns it. Diffed by
+     * {@link diffContentMaps}, never by the certification diff — content is
+     * advisory, not a computed-style outcome. See README "Optional: content layer".
+     */
+    text?: string;
 };
 export type StyleMap = {
     defaults: Record<string, Props>;
@@ -107,6 +116,19 @@ export type CaptureOptions = {
      * minutes; raise it deliberately if you need full coverage of a huge page.
      */
     maxInteractive?: number;
+    /**
+     * Opt-in content layer (default OFF). When true, each element's own rendered
+     * text is recorded on `ElementEntry.text` so {@link diffContentMaps} can
+     * surface copy changes a pure-style diff is blind to — most importantly the
+     * silent ones where new or longer text overflows or clips its box. This is
+     * ADVISORY: it never feeds the certification diff or its blocking counts, and
+     * StyleProof stays computed-styles-first. Off by default keeps the core
+     * promise (a CSS-only refactor that rewrites text is still certified
+     * identical) intact for anyone who doesn't opt in. Text churn (clocks,
+     * "2m ago") is auto-excluded by the same live-region settle pass that already
+     * guards styles, since text now participates in change detection.
+     */
+    captureText?: boolean;
 };
 /** True if `path` is one of `roots` or a structural descendant of one. Shared by
  *  the capture (excluding live regions) and the diff (skipping them). */

package/dist/capture.js

@@ -31,7 +31,10 @@ export function isUnder(path, roots) {
     return roots.some((r) => path === r || path.startsWith(r + ' > '));
 }
 // Serialized into the browser by page.evaluate; cannot call module helpers.
-function capturePage({ ignore, motionOnly }) {
+// Pre-existing, grandfathered in the health baseline; the content layer adds
+// one small captureText block, not new structure.
+// fallow-ignore-next-line complexity
+function capturePage({ ignore, motionOnly, captureText }) {
     const MOTION = /^(transition|animation)/;
     const PSEUDOS = ['::before', '::after', '::marker', '::placeholder'];
     const skipSel = ignore.length ? ignore.map((s) => `${s}, ${s} *`).join(', ') : '';
@@ -131,6 +134,19 @@ function capturePage({ ignore, motionOnly }) {
                 Math.round(r.width),
                 Math.round(r.height),
             ];
+            if (captureText) {
+                // Own text only (direct text-node children, whitespace collapsed), so a
+                // parent and child never both report the same string — each change is
+                // attributed to the element that actually owns the text.
+                let t = '';
+                for (const node of Array.prototype.slice.call(el.childNodes)) {
+                    if (node.nodeType === 3 /* TEXT_NODE */)
+                        t += node.textContent ?? '';
+                }
+                t = t.replace(/\s+/g, ' ').trim();
+                if (t)
+                    entry.text = t;
+            }
         }
         for (const ps of PSEUDOS) {
             if (ps === '::marker' && getComputedStyle(el).display !== 'list-item')
@@ -209,8 +225,14 @@ const STATE_SETS = {
     focus: ['focus', 'focus-visible'],
     active: ['active'],
 };
-/** Structural paths for every selector match, index-aligned with CDP's DOM.querySelectorAll. */
-function pathsForSelector({ selector, skipSel }) {
+const STATE_ID_ATTR = 'data-styleproof-state-id';
+/**
+ * Mark interactive elements once, then address that same element from both CDP
+ * and page.evaluate. Positional CDP nodeId ↔ querySelectorAll index alignment is
+ * flaky on hydrated apps: two non-atomic DOM snapshots can have the same count
+ * but different ordering, which produces phantom forced-state diffs.
+ */
+function markInteractiveElements({ selector, skipSel, attr }) {
     const pathOf = (el) => {
         if (el === document.documentElement)
             return 'html';
@@ -227,7 +249,18 @@ function pathsForSelector({ selector, skipSel }) {
         }
         return 'body > ' + parts.join(' > ');
     };
-    return [...document.querySelectorAll(selector)].map((el) => (skipSel && el.matches(skipSel) ? null : pathOf(el)));
+    let i = 0;
+    return [...document.querySelectorAll(selector)].flatMap((el) => {
+        if (skipSel && el.matches(skipSel))
+            return [];
+        const id = `sp-${i++}`;
+        el.setAttribute(attr, id);
+        return [{ id, path: pathOf(el) }];
+    });
+}
+function clearInteractiveMarks(attr) {
+    for (const el of document.querySelectorAll(`[${attr}]`))
+        el.removeAttribute(attr);
 }
 // Forced pseudo-class states on interactive elements, via CDP so no real
 // mouse or focus is involved and parent-state descendant rules still apply.
@@ -236,49 +269,39 @@ async function captureForcedStates(page, ignore, maxInteractive, skipPaths = [])
     await client.send('DOM.enable');
     await client.send('CSS.enable');
     const { root } = await client.send('DOM.getDocument');
-    const { nodeIds } = await client.send('DOM.querySelectorAll', { nodeId: root.nodeId, selector: INTERACTIVE });
     const skipSel = ignore.length ? ignore.map((s) => `${s}, ${s} *`).join(', ') : '';
-    // Null out forced-state work for live (volatile) paths too, so they're not
-    // probed and can't reintroduce the churn the settle pass just excluded.
-    const paths = (await page.evaluate(pathsForSelector, { selector: INTERACTIVE, skipSel })).map((p) => p && skipPaths.length && isUnder(p, skipPaths) ? null : p);
-    // The CDP DOM snapshot and the live querySelectorAll are two separate,
-    // non-atomic reads. They can legitimately disagree — display:contents,
-    // nodes detached or injected between the two calls (next-route-announcer,
-    // Playwright internals, late hydration adding [tabindex]). A mismatch is NOT
-    // a fatal error: positional nodeId↔path alignment is only valid when the
-    // counts agree, so on skew we warn and skip the forced-state layer for this
-    // surface rather than aborting the whole capture (base + pseudo layers,
-    // the load-bearing certification, still succeed).
-    if (paths.length !== nodeIds.length) {
-        // eslint-disable-next-line no-console
-        console.warn(`styleproof: interactive-element count skew (CDP saw ${nodeIds.length}, page saw ${paths.length}); ` +
-            'skipping forced :hover/:focus/:active capture for this surface. This is usually a benign, ' +
-            'transient DOM difference (display:contents, injected/detached nodes). Re-run if it persists.');
-        await client.detach();
-        return { states: {}, skipped: true };
-    }
-    const limit = Math.min(nodeIds.length, maxInteractive);
-    if (nodeIds.length > maxInteractive) {
+    const marked = (await page.evaluate(markInteractiveElements, { selector: INTERACTIVE, skipSel, attr: STATE_ID_ATTR })).filter((m) => !(skipPaths.length && isUnder(m.path, skipPaths)));
+    const limit = Math.min(marked.length, maxInteractive);
+    if (marked.length > maxInteractive) {
         // eslint-disable-next-line no-console
-        console.warn(`styleproof: ${nodeIds.length} interactive elements exceeds maxInteractive=${maxInteractive}; ` +
+        console.warn(`styleproof: ${marked.length} interactive elements exceeds maxInteractive=${maxInteractive}; ` +
             `forced-state capture truncated to the first ${maxInteractive}. Raise maxInteractive to cover them all.`);
     }
     const states = {};
-    for (let i = 0; i < limit; i++) {
-        const p = paths[i];
-        if (!p)
-            continue;
-        const baseSnap = await page.evaluate(snapSubtree, { selector: INTERACTIVE, index: i });
-        for (const [stateName, forcedPseudoClasses] of Object.entries(STATE_SETS)) {
-            await client.send('CSS.forcePseudoState', { nodeId: nodeIds[i], forcedPseudoClasses });
-            const forcedSnap = await page.evaluate(snapSubtree, { selector: INTERACTIVE, index: i });
-            await client.send('CSS.forcePseudoState', { nodeId: nodeIds[i], forcedPseudoClasses: [] });
-            const delta = deltaBetween(baseSnap, forcedSnap);
-            if (Object.keys(delta).length)
-                (states[p] ??= {})[stateName] = delta;
+    try {
+        for (const { id, path: p } of marked.slice(0, limit)) {
+            const selector = `[${STATE_ID_ATTR}="${id}"]`;
+            const { nodeId } = await client.send('DOM.querySelector', { nodeId: root.nodeId, selector });
+            if (!nodeId) {
+                // eslint-disable-next-line no-console
+                console.warn(`styleproof: interactive element ${id} detached before forced-state capture; skipping it.`);
+                continue;
+            }
+            const baseSnap = await page.evaluate(snapSubtree, { selector, index: 0 });
+            for (const [stateName, forcedPseudoClasses] of Object.entries(STATE_SETS)) {
+                await client.send('CSS.forcePseudoState', { nodeId, forcedPseudoClasses });
+                const forcedSnap = await page.evaluate(snapSubtree, { selector, index: 0 });
+                await client.send('CSS.forcePseudoState', { nodeId, forcedPseudoClasses: [] });
+                const delta = deltaBetween(baseSnap, forcedSnap);
+                if (Object.keys(delta).length)
+                    (states[p] ??= {})[stateName] = delta;
+            }
         }
     }
-    await client.detach();
+    finally {
+        await page.evaluate(clearInteractiveMarks, STATE_ID_ATTR).catch(() => undefined);
+        await client.detach();
+    }
     return { states, skipped: false };
 }
 /** Element paths that differ between two captures (added, removed, or restyled). */
@@ -299,8 +322,11 @@ function changedElementPaths(a, b) {
  * Reuses `capturePage` (motion already frozen by the caller), so only
  * content/layout churn — not an animation frame — keeps it from settling.
  */
-async function stabilizePage(page, ignore, interval, quietFor, timeout) {
-    const snap = async () => (await page.evaluate(capturePage, { ignore, motionOnly: false })).elements;
+async function stabilizePage(page, ignore, interval, quietFor, timeout, captureText) {
+    // captureText is threaded in so text churn participates in settle detection:
+    // a clock/ticker whose text changes (with no style change) keeps the map from
+    // settling and is excluded as a live region, exactly as style churn already is.
+    const snap = async () => (await page.evaluate(capturePage, { ignore, motionOnly: false, captureText })).elements;
     const start = Date.now();
     let prev = await snap();
     let lastChangeAt = start;
@@ -349,11 +375,11 @@ function capturePageTokens() {
     return tokens;
 }
 /** Settle the page and return the paths of live regions to exclude. */
-async function detectVolatile(page, ignore, stabilize) {
+async function detectVolatile(page, ignore, stabilize, captureText) {
     if (stabilize === false)
         return [];
     const opt = typeof stabilize === 'object' ? stabilize : {};
-    const volatile = await stabilizePage(page, ignore, opt.interval || 150, opt.quietFor || 600, opt.timeout || 5000);
+    const volatile = await stabilizePage(page, ignore, opt.interval || 150, opt.quietFor || 600, opt.timeout || 5000, captureText);
     if (volatile.length) {
         // eslint-disable-next-line no-console
         console.warn(`styleproof: ${volatile.length} live region(s) kept changing on their own and were excluded from ` +
@@ -406,15 +432,27 @@ export async function captureStyleMap(page, options = {}) {
     const captureStates = options.captureStates ?? true;
     const maxInteractive = options.maxInteractive ?? 800;
     const stabilize = options.stabilize ?? true;
+    const captureText = options.captureText ?? false;
+    // Neutralise real focus the same way FREEZE_CSS neutralises motion: blur
+    // whatever element holds focus so every read below is the no-interaction
+    // resting state. Real :focus is nondeterministic across runs (autofocus, late
+    // hydration, a stray prior action) and contaminates BOTH layers — it bakes a
+    // focus ring into the resting map, AND it cancels the forced-state :focus delta
+    // (forcing :focus on an already-focused element changes nothing, so the ring
+    // shows up as a delta on some runs but not others — a self-check "non-
+    // deterministic" failure). Interaction states are certified deterministically
+    // via CDP forcePseudoState below, never via whatever happened to be focused.
+    await page.evaluate(() => document.activeElement?.blur?.());
     // Motion longhands first (FREEZE_CSS would null them), then everything else.
-    const motion = await page.evaluate(capturePage, { ignore, motionOnly: true });
+    // Motion never carries text — it's a settled end state of declared motion.
+    const motion = await page.evaluate(capturePage, { ignore, motionOnly: true, captureText: false });
     await page.addStyleTag({ content: FREEZE_CSS });
     // Settle: wait for async content to finish painting so base and head capture
     // the same loaded state, and collect any region still changing on its own
     // (a live stream/ticker) to exclude — animations are frozen above, so only
     // real content/layout churn lands here.
-    const volatile = await detectVolatile(page, ignore, stabilize);
-    const base = await page.evaluate(capturePage, { ignore, motionOnly: false });
+    const volatile = await detectVolatile(page, ignore, stabilize, captureText);
+    const base = await page.evaluate(capturePage, { ignore, motionOnly: false, captureText });
     dropVolatile(base.elements, volatile);
     warnUntraversed(base.shadowHosts, base.sameOriginFrames);
     mergeMotion(base.elements, motion.elements);

package/dist/diff.d.ts

@@ -40,6 +40,15 @@ export type DiffCounts = {
     style: number;
     state: number;
 };
+/** A change to an element's own rendered text (opt-in content layer). Kept out
+ *  of `Finding`/`DiffCounts` on purpose: content is advisory, never part of the
+ *  computed-style certification or its blocking counts. */
+export type ContentChange = {
+    path: string;
+    cls: string;
+    before: string;
+    after: string;
+};
 /** Diff two style maps of the same surface. */
 export declare function diffStyleMaps(a: StyleMap, b: StyleMap): Finding[];
 /** Diff every same-named capture between two directories. `volatile` is the
@@ -49,5 +58,17 @@ export declare function diffStyleMapDirs(dirA: string, dirB: string): {
     counts: DiffCounts;
     volatile: number;
 };
+export declare function diffContentMaps(a: StyleMap, b: StyleMap): ContentChange[];
+/** Per-surface content diff across two capture dirs (opt-in layer). Mirrors
+ *  {@link diffStyleMapDirs} but content-only and non-gating; surfaces present on
+ *  just one side have no baseline and are skipped (the style diff reports those
+ *  as new surfaces). */
+export declare function diffContentDirs(dirA: string, dirB: string): {
+    surfaces: {
+        surface: string;
+        changes: ContentChange[];
+    }[];
+    count: number;
+};
 /** Human label: structural path plus a truncated class hint. */
 export declare function findingLabel(path: string, cls: string): string;

package/dist/diff.js

@@ -13,14 +13,22 @@ function diffProps(propsA, propsB, fallbackA, fallbackB, unsetA, unsetB) {
     }
     return changed;
 }
+/** Union of both captures' live-region paths — skipped by every diff layer so a
+ *  region volatile on either side never reads as a change. */
+function volatilePaths(a, b) {
+    return [...new Set([...(a.volatile ?? []), ...(b.volatile ?? [])])];
+}
 /** Diff two style maps of the same surface. */
+// Pre-existing, grandfathered in the health baseline; the content layer only
+// extracted volatilePaths out of this, it is not newly complex.
+// fallow-ignore-next-line complexity
 export function diffStyleMaps(a, b) {
     const findings = [];
     // Live regions either capture flagged as nondeterministic (a stream, ticker,
     // late-loading content): never diff them — their values move with no code
     // change. Union both sides so a region volatile on only one capture is still
     // skipped, in every layer (element, pseudo, forced-state).
-    const volatile = [...new Set([...(a.volatile ?? []), ...(b.volatile ?? [])])];
+    const volatile = volatilePaths(a, b);
     for (const p of [...new Set([...Object.keys(a.elements), ...Object.keys(b.elements)])].sort()) {
         if (volatile.length && isUnder(p, volatile))
             continue;
@@ -133,6 +141,58 @@ export function diffStyleMapDirs(dirA, dirB) {
     }
     return { surfaces, counts, volatile };
 }
+/**
+ * Diff the OPT-IN content layer: elements whose own rendered text changed.
+ * Separate from {@link diffStyleMaps} by design — content never enters the
+ * certification or its counts. Yields nothing unless capture ran with
+ * `captureText: true` (no `text` on either side → nothing to compare), so it's a
+ * no-op for anyone who hasn't opted in. Add/remove of an element is left to the
+ * style diff (it surfaces there as a DOM change); this reports text that changed
+ * on an element present in BOTH captures. Volatile (live) regions are skipped,
+ * same as the style diff.
+ */
+/** Normalise captured text (absent → empty) so undefined and '' compare equal. */
+const ownText = (t) => t ?? '';
+export function diffContentMaps(a, b) {
+    const volatile = volatilePaths(a, b);
+    // Only paths present in BOTH captures: an add/remove is a DOM change the style
+    // diff already owns, so iterating the intersection both skips them and keeps
+    // this loop branch-light. Equal text (incl. both absent → '' === '') drops out.
+    const common = Object.keys(a.elements)
+        .filter((p) => p in b.elements)
+        .sort();
+    const out = [];
+    for (const p of common) {
+        if (isUnder(p, volatile))
+            continue;
+        const before = ownText(a.elements[p].text);
+        const after = ownText(b.elements[p].text);
+        if (before !== after)
+            out.push({ path: p, cls: a.elements[p].cls, before, after });
+    }
+    return out;
+}
+/** Per-surface content diff across two capture dirs (opt-in layer). Mirrors
+ *  {@link diffStyleMapDirs} but content-only and non-gating; surfaces present on
+ *  just one side have no baseline and are skipped (the style diff reports those
+ *  as new surfaces). */
+export function diffContentDirs(dirA, dirB) {
+    const indexA = indexDir(dirA);
+    const indexB = indexDir(dirB);
+    const both = Object.keys(indexA)
+        .filter((s) => s in indexB)
+        .sort();
+    const surfaces = [];
+    let count = 0;
+    for (const surface of both) {
+        const changes = diffContentMaps(loadStyleMap(indexA[surface]), loadStyleMap(indexB[surface]));
+        if (changes.length) {
+            surfaces.push({ surface, changes });
+            count += changes.length;
+        }
+    }
+    return { surfaces, count };
+}
 /** Human label: structural path plus a truncated class hint. */
 export function findingLabel(path, cls) {
     if (!cls)

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { captureStyleMap, saveStyleMap, loadStyleMap } from './capture.js';
 export type { StyleMap, CaptureOptions, ElementEntry, Rect } from './capture.js';
 export { defineStyleMapCapture } from './runner.js';
 export type { Surface, DefineOptions } from './runner.js';
-export { diffStyleMaps, diffStyleMapDirs, findingLabel } from './diff.js';
-export type { Finding, PropChange, SurfaceDiff, DiffCounts } from './diff.js';
+export { diffStyleMaps, diffStyleMapDirs, diffContentMaps, diffContentDirs, findingLabel } from './diff.js';
+export type { Finding, PropChange, SurfaceDiff, DiffCounts, ContentChange } from './diff.js';
 export { generateStyleMapReport, summarizeProps, prettyLabel } from './report.js';
 export type { ReportOptions, ReportResult } from './report.js';

package/dist/index.js

@@ -1,4 +1,4 @@
 export { captureStyleMap, saveStyleMap, loadStyleMap } from './capture.js';
 export { defineStyleMapCapture } from './runner.js';
-export { diffStyleMaps, diffStyleMapDirs, findingLabel } from './diff.js';
+export { diffStyleMaps, diffStyleMapDirs, diffContentMaps, diffContentDirs, findingLabel } from './diff.js';
 export { generateStyleMapReport, summarizeProps, prettyLabel } from './report.js';

package/dist/report.d.ts

@@ -40,6 +40,16 @@ export type ReportOptions = {
      * (`styleproof-diff`) always keeps them.
      */
     includeLayoutNoise?: boolean;
+    /**
+     * Render the opt-in content layer (default OFF): a separate, ADVISORY section
+     * listing elements whose own text changed, each with a before/after crop.
+     * Requires captures taken with `captureText: true`; otherwise there's no text
+     * to diff and the section is empty. Never affects `changedSurfaces`,
+     * `totalFindings`, or the exit code — StyleProof stays computed-styles-first;
+     * this only surfaces copy changes (and any silent overflow/clipping they
+     * cause) for the reviewer's eye.
+     */
+    includeContent?: boolean;
 };
 export type ReportResult = {
     /** Surfaces carrying a reviewable change (excludes new, one-sided surfaces). */
@@ -47,6 +57,8 @@ export type ReportResult = {
     /** New surfaces present on only one side, with no baseline to compare. */
     newSurfaces: number;
     totalFindings: number;
+    /** Advisory content-layer changes rendered (0 unless includeContent + captured text). Never gates. */
+    contentChanges: number;
     reportMdPath: string;
     reportJsonPath: string;
 };

package/dist/report.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { PNG } from 'pngjs';
 import { loadStyleMap } from './capture.js';
-import { diffStyleMapDirs } from './diff.js';
+import { diffStyleMapDirs, diffContentDirs, } from './diff.js';
 import { describeChange, tokenIndex, toHex, trackCount } from './describe.js';
 // Re-export the plain-English summariser so consumers (and tests) reach it
 // through the package's report module rather than a deep path.
@@ -620,6 +620,92 @@ function buildElementChanges(findings) {
     }
     return els;
 }
+/** One-line, backtick-safe display text, clipped so the report stays scannable. */
+function clipText(s, max = 200) {
+    const t = s.replace(/\s+/g, ' ').replace(/`/g, "'").trim();
+    return t.length > max ? t.slice(0, max - 1) + '…' : t;
+}
+/** An element's padded box on one side, or null when it has no visible rect. */
+function paddedRect(entry, padBy) {
+    if (!entry?.rect)
+        return null;
+    const b = pad(rectToBox(entry.rect), padBy);
+    return visible(b) ? b : null;
+}
+/** Crop box for a content change: the union of where the element sits on each
+ *  side (so the pair lines up), or null if it's not visible anywhere. */
+function contentBox(mapA, mapB, p, padBy) {
+    const ba = paddedRect(mapA.elements[p], padBy);
+    const bb = paddedRect(mapB.elements[p], padBy);
+    if (ba && bb)
+        return union(ba, bb);
+    return bb ?? ba;
+}
+/** before|after crop lines for one content change, or [] when there's no box or
+ *  no screenshots. Writes the composite PNG as a side effect. */
+function contentCropLines(ctx, surface, c, mapA, mapB, pngA, pngB, seq) {
+    const box = contentBox(mapA, mapB, c.path, ctx.padBy);
+    if (!box || !pngA || !pngB)
+        return [];
+    const w = Math.max(ctx.minWidth, box.w);
+    const h = Math.min(ctx.maxHeight, Math.max(ctx.minHeight, box.h));
+    const composite = compositePair(cropPng(pngA, box, w, h).png, cropPng(pngB, box, w, h).png);
+    const stem = `crops/${surface.replace(/[^a-z0-9-]/gi, '-')}-content-${seq}`;
+    writePng(path.join(ctx.outDir, `${stem}-composite.png`), composite);
+    return [
+        '',
+        `![before ◀ │ ▶ after](${ctx.img(`${stem}-composite.png`)})`,
+        '',
+        `<sub>◀ before  ·  after ▶ — ${surface}</sub>`,
+    ];
+}
+/** One surface's content block: heading, then per change the before/after text
+ *  and its crop. Returns the markdown plus the advanced crop counter. */
+function renderContentSurface(ctx, surface, changes, seq) {
+    const mapA = loadStyleMap(findCapture(ctx.beforeDir, surface));
+    const mapB = loadStyleMap(findCapture(ctx.afterDir, surface));
+    const pngA = readPng(path.join(ctx.beforeDir, `${surface}.png`));
+    const pngB = readPng(path.join(ctx.afterDir, `${surface}.png`));
+    const md = ['', `### \`${surface}\` · ${changes.length} content change(s)`];
+    for (const c of changes) {
+        seq++;
+        md.push('', `**\`${prettyLabel(c.path, c.cls)}\`**`, '', `- before: \`${clipText(c.before) || '(empty)'}\``, `- after: \`${clipText(c.after) || '(empty)'}\``, ...contentCropLines(ctx, surface, c, mapA, mapB, pngA, pngB, seq));
+    }
+    return { md, seq };
+}
+/**
+ * The opt-in content layer, rendered as its own ADVISORY section. Reuses the
+ * style report's crop/composite machinery so every copy change gets a
+ * before/after screenshot — the whole point being to make a silent text change,
+ * and any overflow or clipping it triggers, visible in review. Returns the
+ * markdown plus a count; the caller keeps both out of the gate (counts/exit live
+ * on the computed-style path).
+ */
+function renderContentSection(ctx) {
+    const { surfaces, count } = diffContentDirs(ctx.beforeDir, ctx.afterDir);
+    if (!count)
+        return { md: [], count: 0 };
+    const md = [
+        '',
+        '---',
+        '',
+        '## 📝 Content changes (advisory)',
+        '',
+        `_${count} element(s) changed their own text. **Advisory only** — content is not part of the computed-style ` +
+            `certification and does not affect the check. Surfaced so a copy change the style diff can't see (and any ` +
+            `overflow or clipping it causes) is visible in review._`,
+    ];
+    let seq = 0;
+    for (const { surface, changes } of surfaces) {
+        const out = renderContentSurface(ctx, surface, changes, seq);
+        md.push(...out.md);
+        seq = out.seq;
+    }
+    return { md, count };
+}
+// Pre-existing, grandfathered in the health baseline; the content layer is
+// rendered by extracted helpers, this only gained a call + headline branch.
+// fallow-ignore-next-line complexity
 export function generateStyleMapReport(opts) {
     const { beforeDir, afterDir, outDir, imageBaseUrl = '', 
     // Tighter than before (was 24) so the change fills the frame — the annotation
@@ -629,6 +715,7 @@ export function generateStyleMapReport(opts) {
     // own focused frame rather than one wide merged one.
     maxCrops = 8, foldDetailsAt = 0, } = opts;
     const includeNoise = opts.includeLayoutNoise ?? false;
+    const includeContent = opts.includeContent ?? false;
     const { surfaces, volatile: volatileCount } = diffStyleMapDirs(beforeDir, afterDir);
     fs.mkdirSync(path.join(outDir, 'crops'), { recursive: true });
     // Focus each surface on styling intent: drop reflow-casualty props, suppress
@@ -680,9 +767,16 @@ export function generateStyleMapReport(opts) {
     const md = [];
     const json = [];
     const img = (rel) => (imageBaseUrl ? `${imageBaseUrl.replace(/\/$/, '')}/${rel}` : rel);
+    // Opt-in, advisory: computed here so its count can colour the headline, but its
+    // markdown is appended at the very end and it NEVER feeds the gate below.
+    const contentSection = includeContent
+        ? renderContentSection({ beforeDir, afterDir, outDir, img, padBy, minWidth, minHeight, maxHeight })
+        : { md: [], count: 0 };
     md.push('## 🗺️ StyleProof report', '');
     if (changeGroups.length === 0 && missing.length === 0) {
-        md.push('✓ All surfaces identical: every computed style, pseudo-element, and hover/focus/active state matches.');
+        md.push(contentSection.count > 0
+            ? '✓ Computed styles identical: every longhand, pseudo-element, and hover/focus/active state matches. See the advisory content changes below.'
+            : '✓ All surfaces identical: every computed style, pseudo-element, and hover/focus/active state matches.');
     }
     else {
         if (changeGroups.length > 0) {
@@ -698,6 +792,9 @@ export function generateStyleMapReport(opts) {
     if (volatileCount > 0) {
         md.push('', `_${volatileCount} live region(s) auto-excluded as nondeterministic (a stream, ticker, or late-loading content) — they don't affect the check._`);
     }
+    if (contentSection.count > 0 && (changeGroups.length > 0 || missing.length > 0)) {
+        md.push('', `📝 _${contentSection.count} advisory content change(s) below — they don't affect the check._`);
+    }
     let totalFindings = 0;
     let cropSeq = 0;
     for (const cg of changeGroups) {
@@ -808,6 +905,7 @@ export function generateStyleMapReport(opts) {
         md.push('', `_No baseline to compare against — this surface is new, so it doesn't block the check. It becomes part of the baseline once this merges._`);
         json.push(surfaceJson);
     }
+    md.push(...contentSection.md);
     const reportMdPath = path.join(outDir, 'report.md');
     const reportJsonPath = path.join(outDir, 'report.json');
     fs.writeFileSync(reportMdPath, md.join('\n') + '\n');
@@ -816,6 +914,7 @@ export function generateStyleMapReport(opts) {
         changedSurfaces: prepared.length - missing.length,
         newSurfaces: missing.length,
         totalFindings,
+        contentChanges: contentSection.count,
         reportMdPath,
         reportJsonPath,
     };

package/dist/runner.d.ts

@@ -64,7 +64,29 @@ export type DefineOptions = {
      * as a phantom change on an unrelated diff. Default from STYLEPROOF_SELFCHECK=1.
      */
     selfCheck?: boolean;
+    /**
+     * Opt-in content layer (default OFF). Record each element's own rendered text
+     * so the report's optional content section can surface copy changes (run
+     * `styleproof-report --include-content`). Advisory only — never gates. See
+     * `CaptureOptions.captureText` and the README's "Optional: content layer".
+     */
+    captureText?: boolean;
 };
+/**
+ * Let SSE (EventSource) requests bypass HAR record/replay and reach the live
+ * server. A long-lived stream can't round-trip through a HAR entry: recording
+ * captures at most a truncated body, and on replay the connection aborts, so the
+ * app drops to its no-stream fallback — a DIFFERENT but STABLE state that
+ * settle/volatile can't catch (it isn't moving, so it reads as a real change).
+ * Passing the stream through on BOTH record and replay keeps both sides in the
+ * same streamed state; the data it pushes must be deterministic at capture time
+ * (fixtures/frozen clock), same as any live region. Detected by the
+ * `Accept: text/event-stream` header EventSource always sends.
+ *
+ * Registered AFTER routeFromHAR so it matches first (Playwright runs the most
+ * recently added route first); non-stream requests `fallback()` to the HAR.
+ */
+export declare function passLiveStreams(page: Page, url: string): Promise<void>;
 /**
  * Generate one Playwright test per surface × width that captures the style
  * map to `<baseDir>/<dir>/<key>@<width>.json.gz`. Captures are made
@@ -78,4 +100,4 @@ export type DefineOptions = {
  * defineStyleMapCapture({ surfaces: SURFACES, dir: process.env.STYLEMAP_DIR });
  * ```
  */
-export declare function defineStyleMapCapture({ surfaces, dir, baseDir, screenshots, replayFrom, replayUrl, freezeClock, clockTime, selfCheck, }: DefineOptions): void;
+export declare function defineStyleMapCapture({ surfaces, dir, baseDir, screenshots, replayFrom, replayUrl, freezeClock, clockTime, selfCheck, captureText, }: DefineOptions): void;

package/dist/runner.js

@@ -10,18 +10,42 @@ function driftDesc(f) {
     const p = f.props[0];
     return p ? `${f.path} ${p.prop}: ${p.before} → ${p.after}` : f.path;
 }
+/**
+ * Let SSE (EventSource) requests bypass HAR record/replay and reach the live
+ * server. A long-lived stream can't round-trip through a HAR entry: recording
+ * captures at most a truncated body, and on replay the connection aborts, so the
+ * app drops to its no-stream fallback — a DIFFERENT but STABLE state that
+ * settle/volatile can't catch (it isn't moving, so it reads as a real change).
+ * Passing the stream through on BOTH record and replay keeps both sides in the
+ * same streamed state; the data it pushes must be deterministic at capture time
+ * (fixtures/frozen clock), same as any live region. Detected by the
+ * `Accept: text/event-stream` header EventSource always sends.
+ *
+ * Registered AFTER routeFromHAR so it matches first (Playwright runs the most
+ * recently added route first); non-stream requests `fallback()` to the HAR.
+ */
+export async function passLiveStreams(page, url) {
+    await page.route(url, async (route) => {
+        if ((route.request().headers()['accept'] ?? '').includes('text/event-stream'))
+            await route.continue();
+        else
+            await route.fallback();
+    });
+}
 /**
  * Pin the surface's inputs: replay the baseline's recorded data (or record ours),
  * scoped to the data URLs so the app's own JS/CSS still load live, then freeze the
  * clock so time-derived styling is stable.
  */
 async function pinInputs(page, harName, s) {
+    let intercepting = false;
     if (s.replayFrom) {
         const har = path.join(s.replayFrom, harName);
         if (fs.existsSync(har)) {
             // notFound:'abort' — a request the baseline never recorded fails
             // deterministically rather than silently hitting the live backend.
             await page.routeFromHAR(har, { url: s.replayUrl, update: false, notFound: 'abort' });
+            intercepting = true;
         }
         else {
             // eslint-disable-next-line no-console
@@ -34,14 +58,20 @@ async function pinInputs(page, harName, s) {
             update: true,
             updateContent: 'embed', // single portable file, no sidecar resources
         });
+        intercepting = true;
     }
+    // Streams can't be HAR'd; let them reach the live server so replay doesn't
+    // abort them into the app's no-stream fallback (a phantom diff). Only when a
+    // HAR route is active — otherwise everything is already live.
+    if (intercepting)
+        await passLiveStreams(page, s.replayUrl);
     if (s.freezeClock)
         await page.clock.setFixedTime(new Date(s.clockTime));
 }
 /** Capture the surface again and throw if the computed styles drifted from `first`. */
-async function assertDeterministic(page, surface, first) {
+async function assertDeterministic(page, surface, first, captureText) {
     await surface.go(page);
-    const again = await captureStyleMap(page, { ignore: surface.ignore ?? [] });
+    const again = await captureStyleMap(page, { ignore: surface.ignore ?? [], captureText });
     const drift = diffStyleMaps(first, again);
     if (drift.length) {
         throw new Error(`styleproof self-check failed: ${surface.key} is non-deterministic — ` +
@@ -57,9 +87,9 @@ async function captureSurface(page, surface, width, s) {
     const height = typeof surface.height === 'function' ? surface.height(width) : (surface.height ?? 800);
     await page.setViewportSize({ width, height });
     await surface.go(page);
-    const map = await captureStyleMap(page, { ignore: surface.ignore ?? [] });
+    const map = await captureStyleMap(page, { ignore: surface.ignore ?? [], captureText: s.captureText });
     if (s.selfCheck)
-        await assertDeterministic(page, surface, map);
+        await assertDeterministic(page, surface, map, s.captureText);
     const stem = path.join(s.baseDir, s.dir, `${surface.key}@${width}`);
     saveStyleMap(`${stem}.json.gz`, map);
     if (s.screenshots) {
@@ -81,7 +111,7 @@ async function captureSurface(page, surface, width, s) {
  * defineStyleMapCapture({ surfaces: SURFACES, dir: process.env.STYLEMAP_DIR });
  * ```
  */
-export function defineStyleMapCapture({ surfaces, dir, baseDir = '__stylemaps__', screenshots = true, replayFrom = process.env.STYLEPROOF_REPLAY_FROM, replayUrl = process.env.STYLEPROOF_REPLAY_URL ?? '**/api/**', freezeClock = true, clockTime = '2025-01-01T00:00:00Z', selfCheck = process.env.STYLEPROOF_SELFCHECK === '1', }) {
+export function defineStyleMapCapture({ surfaces, dir, baseDir = '__stylemaps__', screenshots = true, replayFrom = process.env.STYLEPROOF_REPLAY_FROM, replayUrl = process.env.STYLEPROOF_REPLAY_URL ?? '**/api/**', freezeClock = true, clockTime = '2025-01-01T00:00:00Z', selfCheck = process.env.STYLEPROOF_SELFCHECK === '1', captureText = false, }) {
     test.skip(!dir, 'set STYLEMAP_DIR=<label> to capture computed-style maps');
     const settings = {
         dir: dir,
@@ -92,6 +122,7 @@ export function defineStyleMapCapture({ surfaces, dir, baseDir = '__stylemaps__'
         freezeClock,
         clockTime,
         selfCheck,
+        captureText,
     };
     test.describe('styleproof capture', () => {
         for (const surface of surfaces) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "1.9.3",
+  "version": "1.10.0",
   "description": "Catch every CSS change before it ships — review PRs and certify refactors by the browser's computed styles, not pixels. Works with any styling system.",
   "keywords": [
     "playwright",