Add render-diff and render-fixture subpath exports + MDX↔MDXish regression suite

[jamestclark]

🎯 What does this PR do?

Adds two new subpath exports plus a 13-fixture regression suite that gates any future rendering change in the @readme/markdown engine.

New public surface

// Engine-free HTML diff — 152 KB
import { diff } from '@readme/markdown/render-diff';
import type { Change, DiffResult, Severity, Preset } from '@readme/markdown/render-diff';

// Fixture-based render helper — 4.04 MB (includes engines)
import { renderFixture, loadFixture } from '@readme/markdown/render-fixture';
import type { RenderContext, Engine, FixtureRenderResult } from '@readme/markdown/render-fixture';

The two subpaths intentionally split along the engine boundary so a consumer that only wants to diff two HTML strings (e.g. CI gating on rendering parity across @readme/markdown version bumps) doesn't have to pull in the full 4 MB engine bundle. Pairing them gives a complete render-and-compare loop in ~10 lines of consumer code:

import { renderFixture, loadFixture } from '@readme/markdown/render-fixture';
import { diff } from '@readme/markdown/render-diff';

const { body, ctx } = loadFixture('./docs/install/');
const { html: fresh } = renderFixture(body, ctx, 'mdxish');
const persisted = readFileSync('./snapshots/install.html', 'utf8');
const result = diff(persisted, fresh, { preset: 'minimal' });

if (result.status === 'differ' && result.severity !== 'cosmetic') {
  // regression — gate CI / surface diff
}

Why the diff tool is engine-agnostic

The public API uses neutral left/right naming (diff(leftHtml, rightHtml, opts), Change.left/Change.right), not mdx/mdxish. Suite B in this PR uses it for MDX↔MDXish comparison; other consumers use the same tool for before/after a version bump or any two-input HTML comparison. The 'minimal' preset is explicitly designed for same-engine before/after diffing (skips span-flatten + adjacent-text-merge that would mask real structural changes). 'cross-engine' (the default) does the fuller normalization needed for MDX↔MDXish.

Regression suite — 13 fixtures

Two suites share the fixture corpus:

• Suite A (__tests__/regression/snapshots.test.ts) renders each fixture through both engines separately and toMatchSnapshot()s the raw HTML. 26 entries total (13 fixtures × 2 engines). Byte-level changes in either engine surface as a failing snapshot on the PR that caused them.
• Suite B (__tests__/regression/equivalence.test.ts) renders each fixture through both engines, runs diff() on the two outputs, and toMatchSnapshot()s the structured diff. As MDX↔MDXish parity improves, snapshots shrink toward { status: 'match' }.

Both suites auto-discover fixture directories via readdirSync — adding a new fixture takes zero code change. The fixture format (body.md + context.json + optional components/*.mdx) is documented in __tests__/regression/fixtures/README.md.

The 13 fixtures break into baselines and regression coverage:

Baselines (the two arms of DiffResult + the data-plumbing surface):

• convergent — match branch (plain markdown)
• divergent — differ branch (HTMLBlock safeMode)
• rich — variables + glossary + custom component

Regression fixtures (each grounded in a real merged bug fix from the past few months):

• tables-with-html (PR fix: code elements stripped from td elements #1466, fix: don't parse content of <code> elements in table cells #1467, fix(mdxish): preserve attributes on raw <table> rows/cells #1463, fix(mdxish): keep md images inline when in tableCells #1469, fix: dont normalize emphasis syntax within html code elements #1471)
• magic-blocks-table (PR fix(mdxish): multiple consecutive magic blocks under a list item not rendering & out of order #1451, fix(mdxish): consecutive magic blocks not rendering if they have html tags in their content #1452)
• unclosed-tags (PR fix(mdxish): bail orphaned <Tag> openers before they eat sibling blocks #1474, fix(mdxish): preserve raw-content HTML tags when unclosed on a line #1477, fix(mdxish): stop orphan closer tags from breaking table parsing #1480, fix(mdxish): handle orphan void closers in JSX table cells #1482)
• callouts-and-glossary (PR fix: guard against empty Glossary tag causing crash #1408, fix(mdxish): fix FA Emojis in Callouts #1421, fix(mdxish): legacy glossary syntax in callout title crashing #1441, fix(Callout): only apply callout title style to headings #1454)
• jsx-attribute-entities (PR fix(mdxish): render Image captions containing entity-encoded JSX #1461, fix(mdxish): decode html entities in jsx attribute values #1462)
• variables-everywhere (PR fix(mdxish): handle user vars on standalone lines in tables #1423, fix(mdxish): skip variable resolution in Mermaid code blocks #1459, fix: dont normalize emphasis syntax within html code elements #1471)
• embeds (PR fix: render iframe/youtube/pdf/jsfiddle embeds without embedly html #1476)
• consecutive-emojis-fa (PR fix(mdxish): allow rendering consecutive emojis #1390, fix(mdxish): add gemoji support to api-header title parser #1416, fix(mdxish): fix FA Emojis in Callouts #1421, fix(mdxish): gemoji & expressions not rendering in components #1449)
• compact-headings (PR fix(mdxish): Add compact heading preprocessor #1428)
• htmlblock-with-script (PR fix(mdxish): scope \n unescaping in HTMLBlock content #1457 — scoped to non-runScripts path)

Each fixture has its own README documenting what it covers and what regressing it would mean.

Build verification

• npm run build:verify runs both subpath check scripts in CI:
  • scripts/verify-render-diff.cjs — dist-grep ensures dist/render-diff.node.js contains none of 5 engine identifiers (bundle isolation); self-ref probe confirms the subpath resolves and diff() works
  • scripts/verify-render-fixture.cjs — positive control ensures dist/render-fixture.node.js contains all 5 engine identifiers (would-be-broken if missing); self-ref probe confirms both engines render via the subpath
• Source-level guard __tests__/lib/render-diff/no-engine-imports.test.ts prevents any file under lib/render-diff/ from importing engine modules directly (defense-in-depth for the dist-grep)
• Bundlewatch budgets: render-diff 185 KB (actual 152 KB), render-fixture 4.5 MB (actual 4.04 MB)

Commit-by-commit

Commit	What	LOC
feat(render-diff)	render-diff subpath + tests + verify script + CI step	+993
feat(render-fixture)	render-fixture subpath + tests + verify script	+456
test(regression)	13 fixtures + Suite A + Suite B + 39 snapshots	+1487

Each commit builds and verifies in isolation (bisectable).

🧪 QA tips

npm install
npm run build:verify    # builds dist/, runs both subpath verify scripts
npm test                # full vitest suite; new tests under __tests__/regression and __tests__/lib/render-{diff,fixture}

Specifically:

• dist/render-diff.node.js is ~152 KB and contains no engine identifiers (grep mdxishAstProcessor dist/render-diff.node.js should be empty)
• dist/render-fixture.node.js is ~4.04 MB and contains all engine identifiers (grep -c mdxishAstProcessor dist/render-fixture.node.js should be > 0)
• node -e "console.log(require('@readme/markdown/render-diff').diff('<p>x</p>', '<p>x</p>'))" prints { status: 'match' }
• node -e "const {renderFixture} = require('@readme/markdown/render-fixture'); console.log(renderFixture('# hi', { variables: { defaults: [], user: {} }, glossary: [], components: [] }, 'mdxish').html.includes('hi'))" prints true
• Adding a new directory under __tests__/regression/fixtures/ is auto-discovered by both suites on the next npm test run
• No regressions in existing npm test suite (full run: 1059 pass on this branch)

📸 Screenshot or Loom

N/A — no user-visible UI change. The new surface is a pair of programmatic subpath exports and a CI test suite.