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:

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)

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:

// 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:

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

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

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:

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:

# 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:

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:

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

# 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>
# Later pushes need the same refspec: local and remote names differ, so a
# bare `git push` fails. Confirm with `git ls-remote origin 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.
• Tag elevation for Divs. Div.attr.classes.contains("section") → emit <section>, not <div> (sectionize transform output). Quarto theme CSS keys off <section>. The constant SECTION = 'section' lives in ts-packages/preview-renderer/src/q2-preview/quartoClasses.ts. bd-coffj.
• Q2_PREVIEW_STAGE_EXCLUDED only drops HTML-emission stages. AST-level stages (they write annotations onto existing nodes, not raw HTML) belong in q2-preview. CodeHighlightStage was wrongly excluded for the same wrong reason. Before adding to the exclusion list, confirm the stage actually produces an HTML string. bd-nxslt.
• iframe getComputedStyle. Always iframe.contentWindow.getComputedStyle(target) — never the parent window's. Wrong window returns the parent's <body> styles applied to whatever target happens to inherit.

• Vitest clearAllMocks does NOT clear mockImplementation. It clears call history only. Earlier tests in PreviewApp.integration.test.tsx override renderPageForPreview; your new tests inherit the stale impl. Top-of-test reset:

  async function resetRenderPageForPreviewMockToDefault() {
    const runtime = await import('@quarto/preview-runtime');
    (runtime.renderPageForPreview as ReturnType<typeof vi.fn>).mockImplementation(
      async () => runtimeMockState.renderResult,
    );
  }

  bd-iuzmk.

• Pampa MetaValue shape: {t: 'MetaString' | 'MetaInlines' | 'MetaBlocks' | 'MetaMap' | 'MetaList' | 'MetaBool', c: ...}. Use @quarto/preview-renderer/framework's extractMetaString / extractMetaStringList rather than reading raw c.
• WASM safety. Stages live in quarto-core and run on both native and wasm32-unknown-unknown. Anything WASM-incompatible must be cfg(not(target_arch = "wasm32"))-gated. quarto-highlight's user-grammar machinery is native-only; built-in grammars are WASM-safe.

Sub-strands to file when discovered

If diagnosis surfaces a second divergence in the same area, file a sibling braid strand rather than expanding the current fix's scope. The repo's convention is one small focused PR per parity fix. bd-y1fs3 surfaced bd-coffj this way; both shipped as separate --no-ff merges. The skill optimizes for cycle time per fix, not for batched mega-PRs.

Cross-references

• Former parent epic (closed, merged via PR #214): bd-kw93 — q2 preview. Parity strands no longer depend on it; they branch off main and carry the preview-parity label.
• Capture-splice design (separate scope): claude-notes/plans/2026-05-18-q2-preview-project-replay-engine.md.
• Phase F (chrome-rendering parity): claude-notes/plans/2026-05-14-q2-preview-phase-f.md.
• Native HTML writer: crates/pampa/src/writers/html.rs. Read this. Often.
• Q2-preview pipeline build: crates/quarto-core/src/pipeline.rs::build_q2_preview_pipeline_stages.
• Q2-preview React block components: ts-packages/preview-renderer/src/q2-preview/blocks/.
• Q2-preview React inline components: ts-packages/preview-renderer/src/q2-preview/inlines/.
• Class-name constants shared between Rust + React: ts-packages/preview-renderer/src/q2-preview/quartoClasses.ts.