AB#131731 chat-components: DOM compatibility regression check

[kwinto]

Summary

Extracts the DOM-compatibility regression test from PR #242 (closed) into its own PR so the safety net can land independently of the layout-variant work.

The check renders every supported <Message> variant on this branch and asserts the normalized DOM matches the same fixture rendered by the latest published @cognigy/chat-components release. A failure means the branch would silently break consumers of the existing DOM contract.

What's in the box

• test/dom-compat.spec.tsx — 40 cases covering every MessageSender variant, both plugin payload shapes (generic gallery, quick replies), every demo-page tab that renders via <Message>, plus the gated branches (Default Preview, HTML Sanitization custom-tags / disabled, xApp buttons, markdown / borderless text variants, message collation).
• test/fixtures/messages.ts — fixture helpers consumed by the spec: per-source bot/user/agent/engagement, gallery + quick-replies plugin payloads, Default Preview / xApp / sanitization / markdown / collation contrast fixtures.
• scripts/install-dom-compat-baseline.mjs — resolves the latest published version at CI time (npm view) and installs it as the chat-components-baseline alias with --no-save --no-package-lock so it never dirties the lockfile.
• vitest.dom-compat.config.ts — narrows include to just this spec; the main vite.config.ts excludes it from npm test because it has preconditions (dist/ build + the dynamic alias).
• tsconfig.json — excludes the spec from tsc for the same preconditions.
• .github/workflows/dom-compat.yml — dedicated GitHub Action so a DOM-compat break shows as its own PR check, separate from the unit-test workflow.
• eslint.config.js — adds a **/*.mjs block with globals.node so the install script doesn't trip no-undef under CodeQL's ESLint pass (local npm run lint only scans .ts/.tsx).

How the comparison stays honest

• Built artifact vs built artifact: importing from dist/ on both sides goes through the same Vite production CSS-module pipeline. Avoids false positives from Vitest's classNameStrategy: "non-scoped" (phantom classes from missing keys, collapsed scopes from key collisions).
• DOM normalization: strips indentation between tags (only whitespace runs containing a newline — single intentional spaces between inline elements are preserved), masks React useId tokens (both :r0: and «r0» shapes), react-tooltip ids, UUIDs, swiper wrapper hashes; canonicalizes hashed CSS-module class names (_header_21mid_1 → header); and collapses double spaces that arise inside attribute values from that canonicalization (scoped to ="..." so meaningful spaces in text content are preserved).
• Non-empty render guard: every assertion verifies the rendered HTML is non-empty before comparing. Without this, a fixture that silently fails to match a plugin would render null on both sides and trivially pass — that exact gap was caught and fixed for engagement messages in 0f2fed4.

Test plan

• npx tsc --noEmit — clean
• npm run lint — clean
• npm run test — 121/121
• npm run test:dom-compat:install-baseline — installs current latest (0.70.0) as the alias
• npm run build — produces dist/chat-components.js
• npm run test:dom-compat — 40/40
• Negative-test (perturb DOM, run again) — 40/40 fail, confirming every case exercises real DOM
• CI: dedicated DOM compatibility workflow runs green on this PR

Notes for reviewers

• Sourced from three commits on the now-closed PR AB#131731 chat-components: layout variant mechanism (webchat + c26) #242 branch (b901373, 99df823, fb2183f) plus follow-up commits that decouple them from the layout-variant work, plug coverage gaps, and address review feedback.
• When the working tree's own version equals the latest published version (as today: 0.70.0 == 0.70.0), the install script logs a notice — the comparison is rebuild-vs-itself and won't catch much. The check becomes meaningful as soon as work starts toward 0.71.x.
• Excluded from coverage: "UI Components" tab (renders ActionButtons / Typography / ChatEvent directly, not via <Message>) and "Streaming messages with markdown" (animationState transitions change the DOM over time, so a static comparison would be flaky).

🤖 Generated with Claude Code

[graymalkin77]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[Copilot]

Pull request overview

Adds a dedicated DOM-compatibility regression check that renders <Message> variants from this branch and compares normalized DOM output against the latest published @cognigy/chat-components, with a standalone CI workflow to surface DOM contract breaks independently of unit tests.

Changes:

• Introduces test/dom-compat.spec.tsx plus a dedicated Vitest config to run it separately from npm test.
• Adds a script to install the latest published package at CI/runtime as chat-components-baseline.
• Updates repo config (Vite/Vitest, TS, ESLint) and adds a GitHub Actions workflow to run the check.

Reviewed changes

Copilot reviewed 8 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
vitest.dom-compat.config.ts	New Vitest config that runs only the DOM-compat spec.
vite.config.ts	Excludes the DOM-compat spec from the default npm test run.
tsconfig.json	Excludes the DOM-compat spec from tsc typechecking.
test/fixtures/layout-messages.ts	Adds fixture messages used by the DOM-compat spec.
test/dom-compat.spec.tsx	New DOM-compat regression suite comparing branch vs latest published baseline.
scripts/install-dom-compat-baseline.mjs	Installs latest published package as an alias for baseline comparison.
package.json	Adds npm scripts for baseline install and dom-compat test run.
eslint.config.js	Declares Node globals for .mjs scripts under flat ESLint config.
.github/workflows/dom-compat.yml	New workflow to run the DOM-compat check as its own PR status check.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

normalize() removes all whitespace between tags via />\s+</, which also strips intentional single-space text nodes (e.g. </strong> <em>). That can hide real DOM/text regressions; consider only stripping indentation/newline whitespace or otherwise preserving meaningful spaces while still normalizing formatting.

[Copilot]

The final .replace(/ +/g, " ") runs on the entire HTML string, not just inside attributes, so it can collapse meaningful multiple spaces in rendered text content (e.g. inside <pre> or intentionally spaced strings). If the goal is to de-dupe class/attr spacing after canonicalization, constrain this normalization to attribute values (or at least to class="...").

Suggested change

	// collapse any resulting double spaces inside attribute values
	.replace(/ +/g, " ")
	// collapse any resulting double spaces only inside class attribute values
	.replace(/\bclass=(["'])([^"']*)\1/g, (_match, quote: string, classValue: string) => {
	const normalizedClassValue = classValue.replace(/ +/g, " ").trim();
	return `class=${quote}${normalizedClassValue}${quote}`;
	})

[Copilot]

npm install --no-save typically still updates package-lock.json; so running this script locally can dirty the lockfile even though the header comment says it won't. If you want to avoid modifying the lockfile, add the appropriate npm flag (and/or adjust the comment to reflect actual behavior).

[Copilot]

PR description mentions test/fixtures/layout-messages.ts, but this PR adds test/fixtures/messages.ts (and there is no layout-messages.ts under test/fixtures). Update the PR description to match the actual file(s) introduced so reviewers know what moved/was added.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The comment explaining CSS-module class normalization is inconsistent with how this spec actually runs: both CurrentMessage and BaselineMessage are imported from built dist bundles, so neither side is using Vitest's classNameStrategy: "non-scoped" output. Consider updating this comment to explain that normalization is needed because CSS-module hash suffixes can differ between builds/releases even when the DOM structure is identical, not because one side is un-hashed.

Suggested change

	// 3. CSS-module hashed class names. The published baseline build emits
	// classes in the default hashed form (`_header_21mid_1`, `_incoming_21mid_8`,
	// `_title2-regular_1ltiv_41`), while the branch-under-test source is
	// loaded by Vitest with `classNameStrategy: "non-scoped"` (see
	// vite.config.ts test.css.modules), which yields plain class names
	// (`header`, `incoming`, `title2-regular`). This is a build-time
	// packaging difference, not a DOM-structural one, so we canonicalize
	// both shapes to the plain name before comparing.
	// 3. CSS-module hashed class names. Both CurrentMessage and
	// BaselineMessage are imported from built dist bundles, so both sides
	// use hashed CSS-module output. Those hash suffixes can still differ
	// between builds/releases (`_header_21mid_1`, `_incoming_21mid_8`,
	// `_title2-regular_1ltiv_41`) even when the underlying DOM structure
	// and logical class identity are unchanged. That is a build-artifact
	// difference, not a DOM-structural one, so we canonicalize hashed
	// class tokens to their plain local names before comparing.