feat: domain-node Mermaid flowchart popup

[lxb12123]

Summary

• Click a domain node on the Domain graph → 480×260 slide-up popup with a Mermaid flowchart of the node's internal business logic (nodes = logical steps, arrows labeled with API calls where applicable)
• Fullscreen modal with Copy source and Open in Mermaid Live (pako-encoded URL); popup + modal close via ✕ / Esc (modal only)
• Source is generated offline by domain-analyzer and persisted to domainMeta.mermaid; assemble-reviewer dry-run-validates via new scripts/validate-mermaid.mjs; dashboard lazy-imports mermaid so the main bundle is unaffected
• Small-window scroll area supports drag-to-pan for oversized diagrams
• Theme-reactive: onThemeChange subscription re-renders the SVG when the user switches themes

Design docs

• Spec: docs/superpowers/specs/2026-04-20-mermaid-service-flowchart-design.md
• Plan: docs/superpowers/plans/2026-04-20-mermaid-service-flowchart.md

What's new

• Schema (packages/core): optional DomainMeta.mermaid: string field (z.string().min(1).optional(), .passthrough() preserves it through sanitization)
• Plugin (understand-anything-plugin/): scripts/validate-mermaid.mjs JSONL-in/out dry-run parser
• Agents: domain-analyzer.md emits Mermaid flowcharts with API labels on edges (5–15 nodes per domain); assemble-reviewer.md strips invalid entries with [mermaid-invalid] log
• Dashboard (packages/dashboard):
  • New components: MermaidRenderer, MermaidFlowchartPopup, MermaidFlowchartModal
  • New hook: useMermaidPopupPosition (5-candidate collision avoidance; reactive to ReactFlow viewport)
  • New theme helper: themes/mermaid-theme.ts (CSS vars → Mermaid themeVariables)
  • Store slice: mermaidPopupNodeId, mermaidModalOpen + 4 actions
  • Integration: DomainClusterNode triggers popup; DomainGraphView mounts popup/modal; setViewMode auto-closes on non-domain view
  • Theme engine now emits onThemeChange notifications
  • New test infrastructure (Vitest + JSDOM + @testing-library) — dashboard had no tests before this PR
  • aria-modal=\"true\" on both dialogs; modal focuses close button on open and restores focus on close

Test plan

• Core tests: 659 pass (+5 new)
• Dashboard tests: 28 pass (new infrastructure)
• pnpm --filter @understand-anything/core build — success
• pnpm --filter @understand-anything/dashboard build — success; `mermaid` is in a separate lazy chunk (verified by inspecting dist/assets/)
• Manual: Mermaid popup renders on domain click; fullscreen modal copy + Live link work; Esc closes modal; ✕ closes popup; empty-state when mermaid field missing; <pre> fallback on parse error
• Drag-to-pan inside scroll container (both horizontal and vertical)
• (Reviewer to verify) Re-run /understand --full on a real project and confirm agent emits domainMeta.mermaid

Non-goals / known limitations

• Only domain node type in v1 (not flow/step)
• Only flowchart TD diagram type; sequenceDiagram/classDiagram/stateDiagram deferred
• No pinch/zoom inside the modal (relies on browser scroll + drag-to-pan)
• mermaid is a production dep of dashboard — acceptable while dashboard is \"private\": true

Version

Bumped 2.3.1 → 2.4.0 across all four version files per CLAUDE.md §Versioning.

result

🤖 Generated with Claude Code

[Lum1104]

@codex review this

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4c48501726

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Normalize node coords to popup container before intersecting

This collision check mixes coordinate spaces: flowToScreenPosition returns screen/viewport pixels, while popupRect is computed in popup-container local coordinates (0..container.width/height). When the ReactFlow canvas is offset from the page origin, intersections are miscomputed, so the hook can pick a “free” candidate that still overlaps nodes (or reject valid positions). Convert node bounds into the same container-local space (for example by subtracting the container's bounding rect) before calling aabbIntersect.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Promote mermaid to runtime dependency for validator script

The new scripts/validate-mermaid.mjs imports mermaid at runtime, and assemble-reviewer now invokes that script during graph assembly, but mermaid is declared only in devDependencies. In installs that omit dev deps (common for packaged/production usage), the validator fails with ERR_MODULE_NOT_FOUND, which breaks Mermaid dry-run validation in this feature path. mermaid should be listed under dependencies for this package.

Useful? React with 👍 / 👎.

[Lum1104]

Awesome, it would be nice if you can have the pop out frame larger. Like half 3/5 of the full screen? Then the expand version bigger.

[Lum1104]

Hi, seems that you miss understand the /understand command, I think you should add the workflow to /understand-domain or add a new command like /understand-{xxx}. Feel free to open a new pr, I'll close this for the commit history cleanning.