preview-render-parity

# preview-render-parity Skill `q2 preview`'s React renderer (`ts-packages/preview-renderer/src/q2-preview/...`) is **supposed to produce the same DOM as `q2 render`'s native HTML writer** (`crates/pampa/src/writers/html.rs`) for the same input. Every divergence — wrong tag, classes on the wrong element, missing classes, attribute leakage, missing pipeline stage — costs the user visible style drift, because the Quarto theme CSS is the same in both places and assumes the native writer's DOM shape. This skill turns a "preview looks slightly wrong" report into a closed braid strand with a regression test, a verified-in-browser fix, and a `--no-ff` merge into the integration branch. ## When to use User says any of: - "preview shows X differently from render" - "spacing / margin / padding / indentation / etc. is different between preview and render" - "DOM doesn't match" - "this class is in render but missing in preview" (or vice versa) - "X is on `<pre>` in render but on `<code>` in preview" (or similar tag/element placement complaint) - describes a specific `getComputedStyle` mismatch ("17px vs 34px") - shows a screenshot comparison of the two pipelines - explicitly: `/preview-parity` or `/preview-render-parity` **Do not** use for: - Preview-server bugs that aren't about rendered output (file watcher misses, samod sync failures, capture pipeline failures, port conflicts). - Render-side bugs in `q2 render` (when the user wants the *render* output changed, not preview brought into line). - Quarto theme CSS changes (changing the rules themselves, not making preview match them). - Replay-engine / capture splice work (those have their own design space — see `claude-notes/plans/2026-05-18-q2-preview-project-replay-engine.md`). ## Preconditions - A running `q2 preview` URL (the user usually provides one, or you can start it: `cargo run --bin q2 -- preview <path> --no-browser --port <p>` after `cargo build --bin q2 --release` for the latest WASM). - A running comparison `q2 render` URL (typically `python -m http.server` over the fixture's `_site/` directory). - Chrome via the chrome-devtools MCP (`mcp__plugin_chrome-devtools-mcp_chrome-devtools__*`). **The native HTML writer is the canonical contract.** Whenever the spec is unclear, read `crates/pampa/src/writers/html.rs` for the `Block::*` or `Inline::*` arm in question — that's what `q2 render` actually does, and `q2 preview` must mirror it. Discrepancies between Pandoc's convention and pampa's are common; trust the pampa code, not your memory of Pandoc. ## The standing fixture `~/Desktop/daily-log/2026/05/15/q2-preview-test-website/` is a 2-page website with one R code cell that the user keeps using for these comparisons. Use it as the default fixture unless the user names another. Render it via `q2 render .`, serve `_site/` over `python -m http.server`, run `q2 preview .` against it, and compare in Chrome. ## Diagnosis workflow ### 0. Reproduce with the harness first Before opening Chrome, try to reproduce the divergence with the automated parity runner — it's faster to iterate on and gives you a normalised text diff instead of manual DOM inspection: 1. Write a minimal fixture under `crates/quarto/tests/smoke-all/q2-preview/` (or find an existing one that already shows the symptom). 2. Add `dom-parity: true` under its `_quarto.tests.html` block. 3. Run it in isolation: `cd hub-client && SMOKE_FILTER=<fixture-name> npm run test:wasm -- --reporter=verbose`. 4. Read the normalised output at `hub-client/test-results/parity/<fixture-path-with-__>/{render,preview}.norm.txt` — the diff between these two files usually points straight at the divergent tag/attribute/class. Reach for Chrome (steps 1-6 below) only when the symptom is a **computed-style** mismatch (margins, colors, layout) that the harness's DOM-only comparison can't see, or when the harness can't reproduce it at all. See `claude-notes/instructions/testing.md` § "4. Preview ↔ render DOM parity" for the runner's full contract (normalisation rules, opt-in policy, known open divergences). ### 1. Locate the element on both pages Open both URLs in Chrome via the MCP. Use `mcp__plugin_chrome-devtools-mcp_chrome-devtools__select_page` to switch between them. For `q2 render`, the target is in `document` directly. For `q2 preview`, the rendered document is **inside an iframe**: ```js const iframe = document.querySelector('iframe'); const doc = iframe.contentDocument; // ...querySelector on `doc` ``` When computing styles in preview, use `iframe.contentWindow.getComputedStyle(target)`, not the parent `window`'s. ### 2. Compare DOM shape For the same logical element on both sides, capture: `outerHTML.slice(0, 500)`, `tagName`, `className`, `id`, attribute list, and the parent chain (up to body). The parent chain often surfaces a structural difference one level up that explains the symptom. ### 3. Compare computed styles (when the symptom is visual) ```js const cs = getComputedStyle(target); // or iframe.contentWindow for preview return {marginTop: cs.marginTop, marginBottom: cs.marginBottom, /* ... */}; ``` A *value* difference (17px vs 34px) is usually a *selector* difference — one side matches a more specific rule. Enumerate the matching rules: ```js // Scan all stylesheets for rules that match the target and have margin/padding. const matches = []; for (const sheet of document.styleSheets) { try { for (const rule of sheet.cssRules || []) { if (!rule.selectorText) continue; try { if (target.matches(rule.selectorText) && /margin|padding/.test(rule.cssText)) { matches.push({selector: rule.selectorText, css: rule.cssText.slice(0, 200), href: sheet.href}); } } catch {} } } catch {} } ``` The render side will typically have a more-specific selector that doesn't match in preview because *some attribute or tag* differs (next-sibling tag, an absent class, etc.). ### 4. Classify the divergence The five categories observed so far: | Category | Symptom | Where the fix lives | |---|---|---| | **Wrong tag** | `<div>` vs `<section>`, `<pre>` vs `<code>`, etc. | React component in `q2-preview/blocks/` or `q2-preview/inlines/` | | **Wrong attribute placement** | classes on `<code>` instead of `<pre>` | Same — mirror `write_*_attr` in `crates/pampa/src/writers/html.rs` | | **Missing classes** | `sourceCode`, `cell-output`, etc. absent in preview | React component (often a conditional add — `if highlight present, prepend sourceCode`) | | **Stage exclusion** | Some pipeline-emitted attribute (`data-hl-spans`, `data-loc`) absent from the AST entirely | `Q2_PREVIEW_STAGE_EXCLUDED` in `crates/quarto-core/src/pipeline.rs` | | **Attribute leakage** | A `data-*` attr the writer *consumes* leaks to the DOM in preview | React component — filter the consumed key (e.g. `data-hl-spans`) | If the symptom looks like more than one category at once, file separate braid sub-strands and tackle them one at a time (the bd-y1fs3 work surfaced bd-coffj this way). ### 5. Find the canonical native behavior ```bash grep -n "Block::<NodeType>\|fn write_<thing>\|<tag\|class=\"<class>" crates/pampa/src/writers/html.rs ``` Read the matching arm. Pay attention to: - **Which element gets the `Attr`** (id + classes + kvs). Pampa's convention is: classes on the OUTER container (`<pre>`, `<section>`, `<figure>`), inner `<code>` / etc. bare. This is the opposite of vanilla Pandoc and a recurring gotcha. - **Helpers that prepend / mutate the attr** before emission (e.g. `write_code_container_attr` adds `sourceCode` when `data-hl-spans` is present). - **Tag elevation** based on classes (e.g. `Div` with `"section"` class → `<section>`). - **Attribute filtering** (consumed keys like `data-hl-spans`). ### 6. Find the React component handling the same AST node Block-level: ``` ts-packages/preview-renderer/src/q2-preview/blocks/<NodeType>.tsx ``` Inline: ``` ts-packages/preview-renderer/src/q2-preview/inlines/<NodeType>.tsx ``` Pipeline stages: `crates/quarto-core/src/stage/stages/<stage>.rs` + the q2-preview pipeline at `crates/quarto-core/src/pipeline.rs::build_q2_preview_pipeline_stages` (and the exclusion list `Q2_PREVIEW_STAGE_EXCLUDED`). ## TDD workflow ### File a braid strand + topic branch ```bash braid create "q2 preview: <one-line symptom>" \ -t bug -p 2 \ -l preview-parity \ -d "$(cat <<EOF <symptom — what the user sees> q2 render produces: <DOM/style> q2 preview produces: <DOM/style> Root cause: <where the divergence is>. Native writer: <file:line>. Fix: mirror the writer — <one-line plan>. EOF )" # braid prints the new strand id on stdout. Capture it as <id>. braid update <id> --status in_progress git switch -c braid/<id>-<short-slug> main ``` Parity strands branch off `main` directly and carry the `preview-parity` label (no parent-child epic dependency — the former parent epic, bd-kw93, is closed and its branch merged via PR #214). (The git branch prefix is `braid/` — a plain git namespace, renamed from the historical `beads/` in bd-yjh1y117.) ### Write the failing test FIRST **Prefer the parity harness's `dom-parity: true` opt-in as the regression test** whenever the fixture from step 0 can be made minimal — it exercises the real render and preview pipelines end-to-end (not a hand-mounted AST fragment) and stays green forever once the fix lands, with no separate assertion to keep in sync. Add/reuse the fixture under `crates/quarto/tests/smoke-all/q2-preview/`, confirm it fails RED before the fix (the parity diff should name the divergent tag/attribute/class), then implement. Fall back to one of the three surfaces below only when the symptom can't be captured as a minimal fixture (e.g. it needs SPA-level state, or a pipeline-stage inclusion check with no DOM to compare). Three test surfaces, pick the right one: | Test surface | Use when | |---|---| | `ts-packages/preview-renderer/src/q2-preview/q2-preview.integration.test.tsx` | DOM/component shape — most common. Mount a small AST fixture via `mount(blocks)`, assert on the rendered DOM. | | `crates/quarto-core/src/pipeline.rs` (tests module) | Pipeline stage inclusion / exclusion. Pattern: `q2_preview_pipeline_includes_<stage_name>` asserts the name appears in `build_q2_preview_pipeline_stages(None, None).iter().map(s => s.name())`. | | `q2-preview-spa/src/PreviewApp.integration.test.tsx` | SPA-app-level behavior (boot, document.title, capture wiring) — when the symptom is about the outer SPA, not a single AST node. | For the SPA-app integration tests, **the existing render-error tests at lines 415/460 of `PreviewApp.integration.test.tsx` override `renderPageForPreview` with `mockImplementation`**. `vi.clearAllMocks()` only clears call history, not implementations, so later tests inherit the stale stub. **Always restore the default closure-over-state mock at the top of your test** (see the bd-iuzmk pattern with `resetRenderPageForPreviewMockToDefault`). Run the failing test: ```bash # preview-renderer (component / DOM tests) (cd ts-packages/preview-renderer && npm run test:integration) # q2-preview-spa (SPA-app tests) (cd q2-preview-spa && npm run test:integration) # quarto-core (pipeline / Rust tests) cargo nextest run -p quarto-core --lib <test-name> ``` Confirm RED for the right reason — the assertion message should name the missing tag / class / attribute, not a generic JSON-shape error. ### Implement the fix Mirror the native writer's behavior in the React component (or update the exclusion list / add a stage). Keep the diff minimal and the comment dense — link bd-id and the native-writer file:line so future maintainers see the contract. ### Verify GREEN Same commands. Then full suite: ```bash cargo xtask verify ``` All 12 steps must pass. The verify rebuilds the WASM + the q2-preview SPA bundle, which is what `q2 preview` embeds in its binary. ### E2E browser verification Tests passing alone is NECESSARY BUT NOT SUFFICIENT — AGENTS.md mandates real-binary check for CLI / UI features. After verify: ```bash cargo build --bin q2 --release # picks up the freshly-built SPA pkill -f "q2 preview" 2>/dev/null; sleep 1 cd <fixture> && rm -rf .quarto /Users/cscheid/repos/github/quarto-dev/q2/target/release/q2 preview . --port <p> --no-browser & ``` Then load `http://127.0.0.1:<p>/?page=<file>` in Chrome via the MCP and run the SAME assertion against the live DOM (computed style, `querySelector` match, `outerHTML` substring). Record the snippet in the commit body. ## Ship ```bash # Close the strand (braid syncs the skein automatically — nothing to commit) braid close <id> --reason "Fixed: <one-line>" # Commit (component fix + test in one commit when they're tightly coupled) git add <component> <test> git commit -m "...(bd-<id>)" # Push (only after explicit user OK, per AGENTS.md GIT PUSH POLICY) and open a PR # against main — no integration branch to merge into (see worktrees.md § Pushing for PR) git push -u origin braid/<id>-<slug>:feature/<id>-<slug> ``` **Commit-message style** (per repo convention — read `git log -5 --pretty=format:"%h %s%n%b%n---"` on `main` if in doubt): - Title with bd-id: `<imperative one-line summary> (bd-<id>)`. - Body: user-visible symptom → root cause (cite native-writer file:line) → fix → verification recipe (include test counts + the `cargo xtask verify N/N green` line + a DOM-snippet from the live browser). - `Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>` footer. ## Landmines These caught me on previous fixes; check before assuming "it's broken": - **Pampa puts classes on the OUTER container.** For `CodeBlock`, classes go on `<pre>`, `<code>` is bare. This is the opposite of vanilla Pandoc. See `Block::CodeBlock` in `crates/pampa/src/writers/html.rs` and `write_code_container_attr`. bd-y1fs3. - **`sourceCode` class is conditional.** The native writer prepends it to a code container's class list **only when `data-hl-spans` is present** (i.e. the code-highlight stage actually annotated something). Idempotent: don't add if the author already has it. See `write_code_container_attr` lines 487-495. - **`data-hl-spans` is consumed, not forwarded.** The React `CodeBlock` reads it to emit `<span class="hl-...">` markup and must **not** leak the raw attr to the DOM. Other `data-*` keys (e.g. `data-loc`) still pass through. bd-nxslt.