feat: add mermaid diagram rendering support

[marcoscaceres]

• Adds mermaid diagram rendering for <pre class="mermaid"> blocks inside <figure> elements
• Lazy-loads mermaid from a separate build chunk (zero cost if unused)
• Flip-card UI: hover reveals toolbar with "Mermaid" label, source toggle (</>), and clipboard copy
• Error display: red-themed card with line-numbered source, inline error pointer, and ReSpec pill reporting
• Supports i18n (6 languages), dark mode, prefers-reduced-motion, touch/mobile, and print

Details

• Theme configurable via respecConfig.mermaid.theme (default: neutral)
• Warns if diagram is not wrapped in a <figure> with <figcaption>
• Shares clipboard infrastructure with WebIDL/CDDL copy buttons
• Uses hyperHTML tagged templates for DOM construction (consistent with codebase)
• CSS uses show/hide for prefers-reduced-motion instead of instant 3D flip
• Print: hides toolbar and back face, neutralizes 3D transforms

Written with AI: this change was generated by Claude. Per AI_POLICY.md.

[Copilot]

Pull request overview

This PR introduces first-class Mermaid diagram support to ReSpec by adding a new core/diagrams coordinator that detects pre.mermaid blocks, lazy-loads a Mermaid runtime bundle, renders diagrams to SVG, and provides a flip-card UI to view/copy the underlying source, plus linting/styling/test coverage updates.

Changes:

• Added Mermaid rendering pipeline (runtime bundle + coordinator + renderer + runtime flip handler) and associated CSS for interactive diagrams.
• Updated highlighting to exclude Mermaid source blocks and added a new linter rule for diagram placement.
• Added integration tests and wired the new modules into the W3C profile + build/dependency graph.

Reviewed changes

Copilot reviewed 11 out of 15 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
worker/rollup.config.js	Adds a separate Rollup output to build a dedicated Mermaid runtime bundle.
worker/respec-mermaid.js	Implements the Mermaid runtime wrapper (initialize, render) and exposes it on self.
src/core/diagrams.js	New coordinator that loads Mermaid, renders SVG, builds UI/error views, injects runtime, and emits warnings/errors.
src/core/diagrams/mermaid.js	New “pure renderer” that delegates rendering to the injected runtime.
src/core/diagrams-runtime.js	New exported runtime script that wires up flip-button behavior in exported documents.
src/styles/diagrams.css.js	New styles for diagram flip-card UI, error presentation, reduced-motion, dark mode, and print.
src/core/highlight.js	Excludes .mermaid blocks from syntax highlighting selection.
src/core/linter-rules/no-uncaptioned-diagram.js	New linter rule to warn about Mermaid/Jake diagrams outside figures.
profiles/w3c.js	Ensures core/diagrams and the new linter rule run in the W3C profile.
tests/spec/core/diagrams-spec.js	Adds integration tests for Mermaid rendering, toolbar presence, errors, config, and highlighting behavior.
package.json	Adds mermaid dependency.
pnpm-lock.yaml	Locks Mermaid and transitive dependencies.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

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

[Copilot]

Pull request overview

Copilot reviewed 14 out of 18 changed files in this pull request and generated 3 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

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

[Copilot]

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated 1 comment.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

Suppressed comments (4)

src/styles/diagrams.css.js:104

• visibility: hidden makes the toolbar buttons unfocusable, so keyboard users cannot focus a button to trigger the :focus-within rule that reveals the toolbar. Keep the toolbar visible to the accessibility/focus model (opacity can still hide it visually); then tabbing to a button will reveal it.

  visibility: hidden;

src/core/diagrams.js:302

• The new public respecConfig.mermaid.theme option is deliberately omitted from Conf and hidden with a type suppression. This leaves the supported option undiscoverable to typed consumers and lets invalid config shapes bypass checking. Add a mermaid configuration type (including Mermaid's supported theme values) to src/type-helper.d.ts and remove this suppression.

  // @ts-expect-error -- mermaid config not in Conf type yet
  const theme = conf.mermaid?.theme || "neutral";

profiles/w3c.js:30

• The feature is registered only in the W3C profile, although the PR exposes it as general Mermaid support and the generic core/diagrams module has no W3C-specific dependency. The AOM, DINI, and Geonovum profiles also include core/figures but will leave identical <pre class="mermaid"> blocks untouched. Register the module in the other profiles as well, or explicitly scope the feature to W3C.

  import("../src/core/diagrams.js"),

src/styles/diagrams.css.js:322

• Printing a currently flipped card still applies rotateY(180deg) from .diagram-container--flipped .diagram-flip, while the back face is hidden below. Error cards start flipped, so they print with no visible face; user-flipped valid diagrams do as well. Override the transform in print mode, not just transform-style.

  .diagram-flip {
    transform-style: flat;
  }