From 48b8d3ed4c6a8426a80fc05b5979ea2a9a023e8b Mon Sep 17 00:00:00 2001
From: Casey Gollan <hello@caseyagollan.com>
Date: Sun, 1 Nov 2026 11:25:29 -0500
Subject: [PATCH 01/21] docs: design for pele renderer PoC

---
 .../2026-11-01-pele-renderer-poc-design.md    | 273 ++++++++++++++++++
 1 file changed, 273 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-11-01-pele-renderer-poc-design.md

diff --git a/docs/superpowers/specs/2026-11-01-pele-renderer-poc-design.md b/docs/superpowers/specs/2026-11-01-pele-renderer-poc-design.md
new file mode 100644
index 0000000..9c962a2
--- /dev/null
+++ b/docs/superpowers/specs/2026-11-01-pele-renderer-poc-design.md
@@ -0,0 +1,273 @@
+# Pele renderer PoC — design
+
+Date: 2026-11-01
+Status: awaiting approval
+
+## Intent
+
+Visimer's canvas renders through a user-supplied `mermaid` instance and
+correlates the rendered SVG back to core's lossless CST to provide WYSIWYG
+point editing. **Pele** (github.com/obsidianmd/pele, v1.x) is Obsidian's
+from-scratch Mermaid renderer: it consumes the same Mermaid source syntax,
+has zero runtime dependencies, is ~230 kB gzipped vs Mermaid's 1.6 MB,
+renders synchronously in well under a millisecond, themes via CSS variables
+instead of initialize-config, and was recently integrated into Obsidian.
+
+End goal (not this PoC): Visimer editing on top of Pele charts inside
+Obsidian. This PoC proves the foundation standalone inside Visimer: that
+the renderer is genuinely swappable behind one seam, with the full editing
+loop working over a Pele-rendered flowchart, demonstrated side-by-side with
+Mermaid in the playground.
+
+## Why it's plausible
+
+An audit of both codebases shows the Mermaid-specific surface of
+`@visimer/dom` is small and well-fenced:
+
+- `MermaidLike` (packages/dom/src/view.ts:141) — 3 methods, the only
+  mermaid API the view consumes
+- The 8 correlator bodies in packages/dom/src/correlate.ts — the only
+  mermaid-DOM conventions
+- Scattered conventions: per-render re-initialize (mermaid's config is
+  module-global), `d${id}` error-element cleanup, font-settle re-render,
+  HTML-label in-place editing
+
+Everything downstream — gestures, popovers, selection, hit-testing — keys
+off Visimer's own `data-mw-entity` tagging and core's entity-id scheme,
+never mermaid's DOM. And Pele's SVG is friendlier to correlate than
+Mermaid's: every entity carries a documented `data-id`.
+
+## Goals
+
+1. `@visimer/dom` renders and edits over a user-supplied Pele instance:
+   `ViewOptions` gains an optional `renderer` (additive; the `mermaid` path
+   is unchanged)
+2. Full editing loop over a Pele-rendered flowchart: select, double-click
+   rename (overlay editor), drag-to-connect, add/delete nodes and edges,
+   popovers, one undo stack shared with the CodeMirror pane
+3. Playground shows a Mermaid ⇄ Pele renderer toggle over the same source
+   and code pane
+4. Correlator tests run against real Pele render output in jsdom (Pele's
+   text measurement has a no-DOM fallback) — closing, for the pele family,
+   the correlator-seam coverage gap TESTING.md documents
+5. Existing mermaid behavior byte-identical: all current suites green
+   without modification
+
+## Non-goals
+
+- Obsidian integration (separate design after the PoC)
+- Pele correlators beyond flowchart (state/class/ER/sequence are the next
+  wave)
+- In-place contenteditable editing over SVG text (PoC uses the overlay
+  editor; SVG-text in-place is a later UX upgrade)
+- Pele hard dependency in any Visimer package (apps add it; packages treat
+  it as an optional peer, mirroring mermaid)
+- Any change to core's parsing/ops behavior — one exception, below:
+  widening `Diagnostic.source`
+
+## Anti-goals
+
+- Duplicating `MermaidCanvasView` or any of the gesture/popover layer for
+  Pele — failure even if the demo works
+- Correlating against undocumented Pele internals — `data-id` and the
+  `pele-*` classes are the documented contract (pele.run/theming);
+  scraping undocumented structure would recreate the "highest-risk seam"
+  the mermaid correlators already suffer from (TESTING.md:17)
+- Breaking or reordering the mermaid path's behavior (its render/config/
+  error conventions are load-bearing for existing consumers)
+
+## Constraints
+
+Facts from the Pele v1.13.0 source audit that shape the design:
+
+- `render(source, options?) → { svg, width, height, links }` is
+  **synchronous** and **throws** `PeleError { code, type, line, column,
+  snippet }` on any syntax/semantic error — there is no partial render.
+  Keep-last-good (already the view's behavior: error badge + diagnostics +
+  prior SVG stays) covers mid-keystroke typing.
+- Flowchart SVG structure (src/diagrams/flowchart/render.ts): role groups
+  `g.pele-clusters`, `g.pele-edges`, `g.pele-cluster-titles`,
+  `g.pele-edge-labels`, `g.pele-nodes`. Nodes: `g.pele-node
+  pele-shape-<shape>` with `data-id="<source id>"` (escaped) and
+  `transform="translate(x,y)"`, shapes centered on the group origin.
+  Clusters: `g.pele-cluster[data-id="<id>"]`. Edges: `g.pele-edge[data-id]`
+  where data-id is the user's `@id` when given, else generated
+  `L_<src>_<tgt>_<count>`. Edge labels: `g.pele-edge-label[data-id]` with
+  the same id scheme.
+- Node/cluster data-ids are source ids (stable); edge data-ids are
+  count-based (unstable when a duplicate edge is inserted).
+- Labels are plain SVG `<text class="pele-label">` — no foreignObject
+  HTML. The view's `editInPlace` already returns false when no HTMLElement
+  label is found and falls back to the overlay editor (view.ts:1403) — no
+  code change needed for the PoC editing UX.
+- Pele's text measurement falls back to a baked-in metrics table when no
+  canvas exists, so `render()` works under jsdom — correlator tests get
+  real output.
+- Pele targets Mermaid 12.1.0 syntax; Visimer apps pin mermaid ^11.16.1
+  and core tracks v11 grammar. The flowchart grammar subset in scope is
+  stable across both (core already preserves `@{ shape: ... }` attrs raw,
+  flowchart/parse.ts:222). If a source uses syntax core can't project, it
+  degrades to view-only exactly as today (editor.ts:69-71).
+- `Diagnostic.source` in core is `'core' | 'mermaid'`
+  (core/src/types.ts:55); a pele render error needs an honest source.
+  **Widen the union to `'core' | 'mermaid' | 'pele'`** — the single core
+  change, type-only, additive.
+
+## Approaches
+
+Three were considered (agreed in conversation):
+
+1. **Renderer adapter inside `@visimer/dom`** ✅ picked — generalize the
+   seam, add a Pele correlator set next to the existing eight, selected by
+   adapter id. Proves the exact swappable-seam property the Obsidian goal
+   needs, least scaffolding, no new packages. Cost: dom carries a second
+   correlator family.
+2. **Separate `@visimer/pele` package** — extraction + injection hooks
+   before anything renders; premature packaging before the adapter shape is
+   proven; revisit for the next wave (sequence/state/class/ER correlators)
+   once the seam settles.
+3. **Playground-only hack** — proves nothing that carries toward Obsidian;
+   dropped.
+
+## The design
+
+### 1. Renderer seam (packages/dom/src/renderer.ts, new file)
+
+`MermaidLike` stays exported for compatibility. New, minimal,
+renderer-agnostic adapter:
+
+```ts
+export interface RendererAdapter {
+  /** correlator family + capability selector */
+  readonly id: 'mermaid' | 'pele'
+  /** render source to a full SVG document string */
+  render(code: string): Promise<{ svg: string }>
+  /** validate source; null when no diagnostic */
+  validate?(code: string): Promise<{ message: string } | null>
+}
+```
+
+- `mermaidAdapter(mermaid: MermaidLike, config?): RendererAdapter` —
+  wraps today's exact behavior: initialize-per-render (module-global config
+  compensation, comment preserved), id generation `mw-render-N`,
+  `parse` → `validate`.
+- `peleAdapter(pele: PeleLike, options?): RendererAdapter` — wraps
+  `pele.render(code, options)` (sync → resolved promise), `PeleError` →
+  `{ message }` including line/column. `PeleLike` is a one-method interface
+  (`render(source, options?)`), so dom never imports pele.
+
+View integration (packages/dom/src/view.ts):
+
+- `ViewOptions`: `mermaid` becomes optional; new `renderer?:
+  RendererAdapter`. Exactly one must be provided (constructor throws a
+  clear error otherwise). When `mermaid` is given, the view wraps it in
+  `mermaidAdapter` internally — every existing consumer keeps working
+  unchanged, and the internal call sequence for mermaid is byte-identical.
+- `render()`: calls `this.renderer.render(code)` instead of
+  `this.mermaid.render(id, code)`. The `d${id}`/`${id}` error-element
+  cleanup (view.ts:848-850) is mermaid-specific → it moves behind adapter
+  identity (`if (this.renderer.id === 'mermaid')`) and must not run for
+  pele. Implementer's choice: adapter-identity check in the view or a
+  `cleanupErrorDom?(id)` hook on the adapter.
+- `bindSvg()`: under `renderer.id === 'pele'`, only the flowchart slot
+  correlates (`correlatePeleFlowchart`); every other slot → `null`
+  correlation (view-only) until the next wave. The mermaid chain is
+  untouched.
+- `validate()`: delegates to `this.renderer.validate?.(code)`.
+- Diagnostic source: `'mermaid'` when `renderer.id === 'mermaid'` else
+  `'pele'`.
+- `setMermaidConfig`: under pele it no-ops with a console warning (pele
+  theming is CSS variables).
+- Font-settle re-render stays unconditional: Pele is also text-measured,
+  so re-render-on-fonts-settle is equally desirable.
+
+### 2. Pele flowchart correlator (packages/dom/src/correlate.pele.ts, new file)
+
+Same return shape as the mermaid family — the existing `Correlation`
+(correlate.ts:12-18) — so `data-mw-entity` tagging, hit overlays, popovers,
+and gestures work untouched. Strategy: **data-id first, degrade on miss**
+(the inverse of mermaid's convention-scraping):
+
+- Nodes: `g.pele-node[data-id="<id>"]` per core node (`node:A` → `A`).
+  Pele escapes ids when writing data-id (`escText`); normalize core's id
+  with the same rules before matching (port them into the correlator;
+  verify against src/diagrams/flowchart/render.ts:220).
+- Clusters/subgraphs: `g.pele-cluster[data-id="<id>"]`, with
+  `.pele-cluster-label` for the label.
+- Edges: core knows (source, target) and declaration order per pair.
+  Match by user `@id` (`data-id` exact) when present; else group
+  `g.pele-edge[data-id^="L_<src>_<tgt>"]` in DOM order against core's
+  per-pair declaration order. Never trust count-based ids globally.
+- Edge labels: `g.pele-edge-label[data-id="<same edge id>"]`.
+- Everything unmatched lands in `failed` → view-only, same philosophy as
+  today.
+
+### 3. Editing UX over pele (mostly free)
+
+- Double-click rename: `editInPlace` finds no HTMLElement label in a pele
+  node → falls back to `openOverlayEditor` (already renderer-agnostic,
+  positioned off the entity bbox). Zero changes; the PoC accepts
+  overlay-editor UX.
+- Drag-to-connect ghost, add-node, delete, popovers, selection styles,
+  hit-walking (`data-mw-entity`) — renderer-agnostic already.
+- `addEdgeHitOverlay` clones visible `<path>` elements; pele edges are
+  `<path>` children of `g.pele-edge` (stroke set on the group). Verify
+  stroke inheritance produces a sane 14px hit overlay; if not, have the
+  clone read effective stroke.
+
+### 4. React plumbing (packages/react/src/index.tsx)
+
+- `MermaidWysiwyg` and `MermaidCanvas`: `mermaid` becomes optional, new
+  optional `renderer` prop; exactly one required at runtime. Making
+  `mermaid` optional is safe for existing callers (they still pass it) —
+  the constructor throws a clear error if neither is given.
+- View-recreation effect deps gain `renderer` next to `mermaid`.
+
+### 5. Playground demo (apps/playground)
+
+- Toolbar: renderer toggle `Mermaid | Pele` (default Mermaid, persisted in
+  localStorage).
+- Pele path: `renderer={peleAdapter(pele, { fontFamily: <INK stack> })}`;
+  theme via a `--pele-*` CSS-variable block eyeball-matched to INK_THEME
+  (pele's theming docs list the variables).
+- Same editor, source, CodeMirror pane, and undo stack across the toggle
+  (the editor is renderer-independent — core only).
+- Under Pele: non-flowchart types render but are view-only (correlator
+  returns null); zenuml samples show a "not supported by pele" notice (pele
+  supports no external diagrams).
+
+### 6. Tests
+
+- `packages/dom/test/correlate-pele.test.ts` — the big win: jsdom + real
+  `pele.render()` output (metrics fallback makes it deterministic in
+  Node). Fixtures: standard flowchart, subgraphs, `@id` edges, duplicate
+  A→B edges, special-char ids, multi-line labels. Assert every entity
+  correlates to the right element; assert `failed` on a synthetic id
+  mismatch.
+- `packages/dom/test/renderer.test.ts` — adapter contracts:
+  `mermaidAdapter` preserves the call sequence (initialize before every
+  render); `peleAdapter` maps `PeleError` → diagnostic; view over a fake
+  pele renderer: keep-last-good on throw, overlay fallback, toggle
+  re-render.
+- Existing suites green unmodified.
+
+### 7. Sequencing (implementation order, one commit each)
+
+1. Renderer seam + `mermaidAdapter` (no behavior change; existing tests
+   prove it)
+2. `correlate.pele.ts` + correlator tests
+3. View wiring: bindSvg dispatch, validate, diagnostic source, error-DOM
+   gating (+ core `Diagnostic.source` widening)
+4. React optional `renderer` prop
+5. Playground toggle + theme
+
+## What's left to the builder
+
+- Exact pele id-escape normalization (port `escText` rules; verify
+  special-char ids)
+- Edge per-pair DOM-order matching details (document order of
+  `L_src_tgt_*` groups vs core declaration order)
+- Whether `addEdgeHitOverlay` needs an effective-stroke fix for pele's
+  group-level stroke
+- Pele CSS-variable theme values for the playground (eyeball-match INK)
+- zenuml/non-flowchart picker behavior details under pele

From 47ce87adb5aa23c5e79282ac9141fcf4e4d3ef88 Mon Sep 17 00:00:00 2001
From: Casey Gollan <hello@caseyagollan.com>
Date: Sun, 1 Nov 2026 11:35:26 -0500
Subject: [PATCH 02/21] docs: fold builder-check findings into pele PoC design

---
 .../2026-11-01-pele-renderer-poc-design.md    | 69 +++++++++++++++----
 1 file changed, 55 insertions(+), 14 deletions(-)

diff --git a/docs/superpowers/specs/2026-11-01-pele-renderer-poc-design.md b/docs/superpowers/specs/2026-11-01-pele-renderer-poc-design.md
index 9c962a2..d85be48 100644
--- a/docs/superpowers/specs/2026-11-01-pele-renderer-poc-design.md
+++ b/docs/superpowers/specs/2026-11-01-pele-renderer-poc-design.md
@@ -96,6 +96,23 @@ Facts from the Pele v1.13.0 source audit that shape the design:
   the same id scheme.
 - Node/cluster data-ids are source ids (stable); edge data-ids are
   count-based (unstable when a duplicate edge is inserted).
+- **Pele does not render invisible (`~~~`) edges at all** (the
+  `g.pele-edge` group is gated on `thickness !== 'invisible'`; a labeled
+  invisible edge still gets its `g.pele-edge-label`). Mermaid renders
+  invisible edges as real clickable paths, so under pele they are
+  genuinely view-only — and a naive order-match would pair the wrong core
+  edge with a rendered path (mis-correlation that edits the wrong line).
+- **Pele filters style declarations through a fixed allowlist**
+  (`SHAPE_PROPS`/`TEXT_PROPS`, src/svg/theme.ts): `animation-*`
+  declarations are silently dropped, so the edge-animation popover action
+  is a silent no-op under pele.
+- **Subgraph titles crossed by edges are drawn outside their cluster**,
+  in a top-level `g.pele-cluster-titles` as
+  `g.pele-cluster-title[data-id="<id>"]`.
+- **Core cannot parse edge-id syntax today** (`A e1@--> B` fails at `e1@`
+  and the line degrades to unknown, for both renderers equally) — so edge
+  `@id` matching is not implementable without a core parse change, which
+  the non-goals exclude. Pre-existing limitation, out of PoC scope.
 - Labels are plain SVG `<text class="pele-label">` — no foreignObject
   HTML. The view's `editInPlace` already returns false when no HTMLElement
   label is found and falls back to the overlay editor (view.ts:1403) — no
@@ -193,14 +210,25 @@ and gestures work untouched. Strategy: **data-id first, degrade on miss**
   with the same rules before matching (port them into the correlator;
   verify against src/diagrams/flowchart/render.ts:220).
 - Clusters/subgraphs: `g.pele-cluster[data-id="<id>"]`, with
-  `.pele-cluster-label` for the label.
-- Edges: core knows (source, target) and declaration order per pair.
-  Match by user `@id` (`data-id` exact) when present; else group
-  `g.pele-edge[data-id^="L_<src>_<tgt>"]` in DOM order against core's
-  per-pair declaration order. Never trust count-based ids globally.
-- Edge labels: `g.pele-edge-label[data-id="<same edge id>"]`.
+  `.pele-cluster-label` for the label. Struck titles in
+  `g.pele-cluster-titles` (`g.pele-cluster-title[data-id="<id>"]`) also
+  correlate to the subgraph entity, so crossed titles stay clickable and
+  renamable.
+- Edges: core knows (source, target) and declaration order per pair;
+  pele never exposes user edge-ids core could use (core can't parse
+  `@id` syntax — see constraints). Match **per (source, target) pair,
+  count-checked**: group `g.pele-edge[data-id^="L_<src>_<tgt>"]` in DOM
+  order against core's per-pair declaration order — but only when the
+  pair's rendered count equals the core count. If pele rendered fewer
+  elements than core has edges for a pair (e.g. invisible `~~~` edges,
+  which pele does not render), degrade that pair to `failed` rather than
+  blind-order-match: a mis-paired edge would edit or delete the wrong
+  source line, the worst failure mode for an editor. Invisible edges are
+  accepted as view-only under pele.
+- Edge labels: `g.pele-edge-label[data-id="<same edge id>"]`, with the
+  same per-pair count check.
 - Everything unmatched lands in `failed` → view-only, same philosophy as
-  today.
+  today. Degrade, never mis-correlate.
 
 ### 3. Editing UX over pele (mostly free)
 
@@ -210,6 +238,13 @@ and gestures work untouched. Strategy: **data-id first, degrade on miss**
   overlay-editor UX.
 - Drag-to-connect ghost, add-node, delete, popovers, selection styles,
   hit-walking (`data-mw-entity`) — renderer-agnostic already.
+- **One popover action is gated under pele**: the edge-animation picker
+  emits `linkStyle N animation-*`, which pele's style allowlist silently
+  drops — so under `renderer.id === 'pele'` the animation action is
+  hidden and `injectAnimationKeyframes` is skipped. Silent feature loss
+  is this codebase's documented highest-risk failure mode
+  (TESTING.md:17); gate it instead. Node colors, shapes, arrows,
+  thickness, and curve all round-trip under pele and stay enabled.
 - `addEdgeHitOverlay` clones visible `<path>` elements; pele edges are
   `<path>` children of `g.pele-edge` (stroke set on the group). Verify
   stroke inheritance produces a sane 14px hit overlay; if not, have the
@@ -240,10 +275,12 @@ and gestures work untouched. Strategy: **data-id first, degrade on miss**
 
 - `packages/dom/test/correlate-pele.test.ts` — the big win: jsdom + real
   `pele.render()` output (metrics fallback makes it deterministic in
-  Node). Fixtures: standard flowchart, subgraphs, `@id` edges, duplicate
-  A→B edges, special-char ids, multi-line labels. Assert every entity
-  correlates to the right element; assert `failed` on a synthetic id
-  mismatch.
+  Node). Fixtures: standard flowchart, subgraphs (including a title
+  struck by an edge), duplicate A→B edges, invisible `~~~` edges
+  (asserting degradation, not mis-pairing), special-char ids, and
+  multi-line labels. Assert every entity correlates to the right
+  element; assert `failed` on a synthetic id mismatch and on
+  count-mismatched pairs.
 - `packages/dom/test/renderer.test.ts` — adapter contracts:
   `mermaidAdapter` preserves the call sequence (initialize before every
   render); `peleAdapter` maps `PeleError` → diagnostic; view over a fake
@@ -265,9 +302,13 @@ and gestures work untouched. Strategy: **data-id first, degrade on miss**
 
 - Exact pele id-escape normalization (port `escText` rules; verify
   special-char ids)
-- Edge per-pair DOM-order matching details (document order of
-  `L_src_tgt_*` groups vs core declaration order)
+- Verify pele emits a pair's `L_src_tgt_*` groups in declaration order
+  (the count-checked order-match assumes it)
+- Store the inner `<path>`, not the `g.pele-edge` group, in
+  `Correlation.edges` — the overlay editor's `SVGPathElement` midpoint
+  branch and the hover-CSS sibling rule depend on it
 - Whether `addEdgeHitOverlay` needs an effective-stroke fix for pele's
   group-level stroke
 - Pele CSS-variable theme values for the playground (eyeball-match INK)
-- zenuml/non-flowchart picker behavior details under pele
+- Memoize the adapter in the playground so the view isn't recreated per
+  React render; zenuml/non-flowchart picker behavior details under pele

From 82f86694f701286e2404445843b0c30646472e32 Mon Sep 17 00:00:00 2001
From: Casey Gollan <hello@caseyagollan.com>
Date: Sun, 1 Nov 2026 11:45:13 -0500
Subject: [PATCH 03/21] docs: implementation plan for pele renderer PoC

---
 .../plans/2026-11-01-pele-renderer-poc.md     | 297 ++++++++++++++++++
 1 file changed, 297 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-11-01-pele-renderer-poc.md

diff --git a/docs/superpowers/plans/2026-11-01-pele-renderer-poc.md b/docs/superpowers/plans/2026-11-01-pele-renderer-poc.md
new file mode 100644
index 0000000..45cf1b2
--- /dev/null
+++ b/docs/superpowers/plans/2026-11-01-pele-renderer-poc.md
@@ -0,0 +1,297 @@
+# Pele Renderer PoC Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Let `@visimer/dom` render and fully WYSIWYG-edit flowcharts through Obsidian's Pele renderer (user-supplied instance), behind a generalized renderer seam, demoed by a playground toggle.
+
+**Architecture:** Generalize dom's private `MermaidLike` usage into a `RendererAdapter` (new `renderer.ts`); the view routes render/validate through it and picks correlators by `adapter.id`. A new `correlate.pele.ts` maps Pele's documented `data-id`/`pele-*` SVG contract onto the existing `Correlation` shape, so gestures/popovers/undo work untouched. Core, CodeMirror, and Monaco are untouched except one type-union widening.
+
+**Tech Stack:** TypeScript (strict, ESM), vitest + jsdom, pnpm workspace, pele v1.13.0 (devDep of `@visimer/dom`, dep of playground only).
+
+**Spec:** `docs/superpowers/specs/2026-11-01-pele-renderer-poc-design.md` — the plan argues from the spec; read both.
+
+## Global Constraints
+
+- Packages never depend on pele: `PeleLike` is a hand-written structural interface in dom; `pele` appears only as a devDependency of `@visimer/dom` (tests) and a dependency of `apps/playground` (demo). Spec anti-goal.
+- The mermaid path keeps byte-identical behavior (initialize-at-creation and per-render, temp-element cleanup, validate, config re-init). Existing suites stay green, unmodified. Spec goal 5.
+- Never mis-correlate: when a match is ambiguous, the entity degrades to view-only (`failed`) instead of pairing a wrong element. Spec anti-goal.
+- Core's only change: `Diagnostic.source` widens to `'core' | 'mermaid' | 'pele'` (packages/core/src/types.ts:55). Spec constraint.
+- Entity-id formats from core (flowchart/graph.ts): nodes `node:<id>`, edges `edge:<src>-><tgt>#<occ>`, subgraphs `subgraph:<id>`.
+- Test files start with `// @vitest-environment jsdom` and polyfill `CSS.escape` exactly like packages/dom/test/fonts.test.ts:1-10.
+- Commands: single file `pnpm --filter @visimer/dom exec vitest run test/<file>`; package suite `pnpm --filter @visimer/dom test` / `--filter @visimer/core test`; everything `pnpm test` / `pnpm typecheck`.
+- Commits: one per task, repo style (`feat(dom): …`), on branch `pele-renderer-poc`.
+
+## Review Focus
+
+1. **A pair mixing visible and invisible edges** (pele omits `g.pele-edge` for `~~~`): blind order-matching would pair the wrong core edge with the rendered path and edit/delete the wrong source line. → Task 3, Fixture 4 asserts both edges degrade and the rendered path carries no `data-mw-entity`.
+2. **Ids containing underscores** corrupt `L_<src>_<tgt>_<n>` parsing (`L_a_b_c_0` is pair `a→b_c` or `a_b→c`). → Task 3, Fixture 5 asserts correct correlation via the leftover rule.
+3. **Entity-coded ids** (`A&quot;q`): pele writes `data-id` entity-decoded, so raw comparison silently degrades nodes to view-only. → Task 3, Fixture 6 + `decodeEntities` helper tests.
+4. **Silent no-op of the animation picker under pele** (pele's style allowlist drops `animation-*`). → Task 4 asserts the animation section is absent from edge popover actions and keyframes are not injected.
+5. **Pele throws on any mid-keystroke syntax error** (no partial render) — a blank canvas would break the error-tolerance promise. → Task 4 asserts keep-last-good: prior SVG stays, badge shows, diagnostics carry `source: 'pele'`.
+
+---
+
+### Task 1: Renderer adapter module (`renderer.ts`)
+
+**Files:**
+- Create: `packages/dom/src/renderer.ts`
+- Modify: `packages/dom/src/index.ts` (add exports)
+- Modify: `packages/dom/package.json` (devDependency `pele`)
+- Test: `packages/dom/test/renderer.test.ts`
+
+**Interfaces:**
+- Produces (later tasks rely on exactly these):
+  - `interface RendererAdapter { readonly id: 'mermaid' | 'pele'; render(code: string): Promise<{ svg: string }>; validate?(code: string): Promise<{ message: string } | null> }`
+  - `interface PeleLike { render(source: string, options?: Record<string, unknown>): { svg: string; [key: string]: unknown }; parse?(text: string): unknown }` (method syntax — bivariance makes the real `pele` module structurally assignable)
+  - `mermaidAdapter(mermaid: MermaidLike, config?: Record<string, unknown>): RendererAdapter`
+  - `peleAdapter(pele: PeleLike, options?: Record<string, unknown>): RendererAdapter`
+
+- [ ] **Step 1: Write failing tests in `packages/dom/test/renderer.test.ts`**
+
+  jsdom pragma + `CSS.escape` polyfill per Global Constraints. Cases:
+
+  1. `mermaidAdapter` initializes at creation and before every render — fake mermaid records `'initialize'` / `'render:<id>'` into a `calls` array; render twice; assert `calls.filter(c => c.startsWith('render')).length === 2` and every `render` entry is immediately preceded by an `initialize`.
+  2. `mermaidAdapter` cleans mermaid's temp error elements — fake `render(id)` appends `<div id="d${id}"></div><div id="${id}"></div>` to `document.body` then throws; `await expect(adapter.render('bad')).rejects.toThrow()`; assert `document.querySelectorAll('[id^="mw-render"], [id^="dmw-render"]').length === 0`.
+  3. `mermaidAdapter.validate` resolves `null` on parse success, `{ message }` (first line of the error) on parse throw.
+  4. `peleAdapter` wraps synchronous render: fake pele `{ render: (src) => ({ svg: `<svg class="pele">${src}</svg>` }) }` → `await adapter.render('x')` resolves `{ svg }` containing `pele`.
+  5. `peleAdapter.validate` maps a pele error to a diagnostic message. Fake `parse` throws `Object.assign(new Error('Parse error on line 2:\n…'), { type: 'flowchart', line: 2, column: 13 })`. Pinned message format: `` `${type} error: ${firstLine}` + (line ? ` (line ${line}, column ${column})` : '') `` → assert `expect.stringContaining('flowchart error: Parse error on line 2:')` and `expect.stringContaining('(line 2, column 13)')`. When the fake pele has no `parse`, `adapter.validate` is `undefined`.
+  6. Real-pele smoke: `import { render as peleRender } from 'pele'`; build the `PeleLike` as `{ render: (src, o) => peleRender(src, o) }`; `const adapter = peleAdapter(peleLike)`; `const { svg } = await adapter.render('flowchart LR\n  A --> B')`; assert `svg` contains `class="pele-node` and `data-id="A"`.
+
+- [ ] **Step 2: Run to verify failure**
+
+  Run: `pnpm --filter @visimer/dom exec vitest run test/renderer.test.ts`
+  Expected: FAIL — cannot resolve `../src/renderer`.
+
+- [ ] **Step 3: Implement `packages/dom/src/renderer.ts`**
+
+  Module-global render-id counter moved from view.ts (`mw-render-${++n}`, keep the "concurrent views never collide" comment). `mermaidAdapter`: call `initialize(config ?? {})` once at creation and before each `render(id, code)`; on throw, remove `d${id}` and `${id}` elements then rethrow; `validate` wraps `parse` (null on success, `{ message: firstLine }` on throw). `peleAdapter`: `render` returns `{ svg: pele.render(code, options).svg }` (sync → promise); `validate` present iff `pele.parse` exists, message format pinned in Step 1.5. No pele import.
+
+- [ ] **Step 4: Run tests to verify pass**
+
+  Run: `pnpm --filter @visimer/dom exec vitest run test/renderer.test.ts`
+  Expected: PASS (all 6 cases)
+
+- [ ] **Step 5: Wire exports + devDep, run full gates**
+
+  `packages/dom/src/index.ts`: export `RendererAdapter`, `PeleLike`, `mermaidAdapter`, `peleAdapter` alongside the existing view exports. Add devDep: `pnpm --filter @visimer/dom add -D pele` (resolves ^1.13.0). Run `pnpm --filter @visimer/dom test` and `pnpm typecheck`.
+  Expected: all pass.
+
+- [ ] **Step 6: Commit**
+
+  ```bash
+  git add packages/dom/src/renderer.ts packages/dom/src/index.ts packages/dom/package.json packages/dom/test/renderer.test.ts pnpm-lock.yaml
+  git commit -m "feat(dom): renderer adapter seam with mermaid and pele adapters"
+  ```
+
+### Task 2: View routes through `RendererAdapter`
+
+**Files:**
+- Modify: `packages/dom/src/view.ts` (ViewOptions:155-173, constructor, render():793-858, validate():2713-2722, setMermaidConfig():529-534; delete `MermaidLike` usage in those paths — keep the type export)
+- Modify: `packages/core/src/types.ts:55` (`Diagnostic.source` widening)
+- Test: `packages/dom/test/renderer.test.ts` (extend)
+
+**Interfaces:**
+- Consumes: `RendererAdapter`, `mermaidAdapter` (Task 1), `MermaidLike` (existing export, unchanged).
+- Produces: `ViewOptions { editor; container; mermaid?: MermaidLike; renderer?: RendererAdapter; mermaidConfig?; … }` — exactly one of `mermaid`/`renderer` required (constructor throws `Error('MermaidCanvasView: pass exactly one of `mermaid` or `renderer`')`); view keeps `private renderer: RendererAdapter` and `private mermaidInstance: MermaidLike | null`; render-error and validate diagnostics carry `source: this.renderer.id`.
+
+- [ ] **Step 1: Write failing tests (extend `renderer.test.ts`)**
+
+  1. View renders through a custom adapter: fake `RendererAdapter` (`id: 'pele'`, render returns `<svg>…</svg>`); construct `MermaidCanvasView` with `renderer` and no `mermaid`; assert container's `svgHost` contains the fake svg after the initial render (await the view's `'render'` event).
+  2. Exactly-one enforcement: constructor without either option throws; with both throws.
+  3. Mermaid call-order preserved: fake mermaid (fonts.test.ts pattern) records calls; construct view (initialize #1 at construction), then `editor.setCode('flowchart LR\n  A --> B\n  A --> C\n', 'external')` and await render → initialize #2 precedes render.
+  4. Diagnostics source follows the adapter: fake adapter with `id: 'pele'` whose `render` rejects → after render settles, `view.renderError` truthy and `editor` diagnostics contain `{ source: 'pele' }` (read via the view's render error path; assert through `editor`'s diagnostics getter or the `'render'` event payload `{ ok: false }`).
+  5. `setMermaidConfig` no-ops under a non-mermaid adapter: fake `id: 'pele'` adapter records render calls; `view.setMermaidConfig({ theme: 'dark' })` → `console.warn` spy called once, no additional render, `view.renderError` unchanged.
+
+- [ ] **Step 2: Run to verify failure**
+
+  Run: `pnpm --filter @visimer/dom exec vitest run test/renderer.test.ts`
+  Expected: FAIL — `renderer` not a known `ViewOptions` key / type errors.
+
+- [ ] **Step 3: Widen core's `Diagnostic.source`**
+
+  `packages/core/src/types.ts:55`: `'core' | 'mermaid'` → `'core' | 'mermaid' | 'pele'`. Run `pnpm --filter @visimer/core test`.
+  Expected: PASS (widening is additive).
+
+- [ ] **Step 4: Implement the view seam**
+
+  Constructor: exactly-one check; `this.mermaidInstance = options.mermaid ?? null`; `this.renderer = options.renderer ?? mermaidAdapter(options.mermaid!, this.mermaidConfig)` (config defaults at view.ts:428 unchanged); drop the constructor's direct `mermaid.initialize` (the adapter initializes at creation). `render()`: delete the id-generation and `this.mermaid.initialize` lines; `const { svg } = await this.renderer.render(code)`; in the catch, delete the `d${id}`/`${id}` cleanup (Task 1 moved it into `mermaidAdapter`) and set `source: this.renderer.id`. `validate()`: `const d = await this.renderer.validate?.(this.editor.code); if (!d) return true; setDiagnostics([{ message: d.message, span: null, severity: 'error', source: this.renderer.id }]); return false`. `setMermaidConfig`: keep today's mermaid behavior exactly (rebuild `this.renderer = mermaidAdapter(this.mermaidInstance, this.mermaidConfig)`, clear `lastRenderedCode`, re-render); under `renderer.id !== 'mermaid'` warn once and return. Update `ViewOptions` JSDoc: `mermaid` optional when `renderer` is provided.
+
+- [ ] **Step 5: Run all gates**
+
+  Run: `pnpm --filter @visimer/dom test && pnpm --filter @visimer/core test && pnpm typecheck`
+  Expected: PASS — including the pre-existing suites (fonts, inplace, visibility-retry, correlate-hidden-mount) unmodified.
+
+- [ ] **Step 6: Commit**
+
+  ```bash
+  git add packages/dom/src/view.ts packages/core/src/types.ts packages/dom/test/renderer.test.ts
+  git commit -m "refactor(dom): route the canvas view through RendererAdapter"
+  ```
+
+### Task 3: Pele flowchart correlator + dispatch
+
+**Files:**
+- Create: `packages/dom/src/correlate.pele.ts`
+- Modify: `packages/dom/src/correlate.ts:32` (`addEdgeHitOverlay` becomes `export function`)
+- Modify: `packages/dom/src/view.ts` (`bindSvg()`:898-917 dispatch)
+- Modify: `packages/dom/src/index.ts` (export `correlatePeleFlowchart`)
+- Test: `packages/dom/test/correlate-pele.test.ts`
+
+**Interfaces:**
+- Consumes: `Correlation` (correlate.ts:12-18), `FlowGraph`/`FlowNode`/`FlowEdge`/`FlowSubgraph` from `@visimer/core`, `addEdgeHitOverlay(path, entityId)`.
+- Produces: `correlatePeleFlowchart(svg: SVGSVGElement, graph: FlowGraph): Correlation`, selected in `bindSvg` when `this.renderer.id === 'pele'` (flowchart slot only; all other slots → `null` correlation, `seqCorrelation` `null`, `armVisibilityRetry` passed `null`).
+
+- [ ] **Step 1: Write failing tests in `packages/dom/test/correlate-pele.test.ts`**
+
+  Harness: pragma + polyfill; `import { render as peleRender } from 'pele'`; helper `correlate(code)` → `new MermaidWysiwygEditor({ code })`, `graph = editor.result.flowchart`, `host.innerHTML = peleRender(code).svg`, `correlatePeleFlowchart(host.querySelector('svg')!, graph)`. Real pele works under jsdom (no canvas → its `metricsMeasurer` fallback).
+
+  Fixtures (exact code strings):
+  1. Standard — `'flowchart TD\n  A[Start] --> B{OK?}\n  B -->|yes| C[Ship]\n'`: `nodes` has `node:A`/`node:B`/`node:C` mapped to `g.pele-node` elements (each tagged `data-mw-entity`), `edges` has `edge:A->B#0`/`edge:B->C#0` mapped to the **inner `<path>`** of the right `g.pele-edge` (assert path is inside the group whose `data-id` starts `L_A_B_` / `L_B_C_`, and that the path's `data-mw-hit-overlay` sibling clone exists), `edgeLabels` has `edge:B->C#0` mapped to `g.pele-edge-label[data-id="L_B_C_0"]`, `failed` empty.
+  2. Subgraph — `'flowchart TD\n  subgraph SG [Group]\n    A[Start] --> B\n  end\n  B --> C\n'`: `nodes` includes `subgraph:SG` → `g.pele-cluster[data-id="SG"]`. Then inject synthetically `<g class="pele-cluster-titles"><g class="pele-cluster-title" data-id="SG">Group</g></g>` into the svg and re-correlate: the `g.pele-cluster-title` element is tagged `data-mw-entity="subgraph:SG"` (struck titles live outside their cluster; pele src/svg/cluster.ts:67).
+  3. Duplicate pair — `'flowchart TD\n  A -->|one| B\n  A -->|two| B\n'`: `edge:A->B#0` and `edge:A->B#1` both correlate, each to a distinct path, first-declared → first-in-DOM for the pair; `edgeLabels` maps both.
+  4. Invisible member — `'flowchart TD\n  A --> B\n  A ~~~ B\n'`: pele renders one `g.pele-edge`; assert `edges` is empty, `failed` contains `edge:A->B#0` **and** `edge:A->B#1`, and the rendered path carries no `data-mw-entity` (degrade, never mis-pair).
+  5. Special ids — `'flowchart TD\n  a-b --> c\n  a --> b_c\n'`: `node:a-b`, `node:b_c`, `edge:a-b->c#0` all correlate (underscore target `b_c` makes pele's `data-id` `L_a_b_c_0`; the leftover rule must pair it correctly).
+  6. Entity-coded id — synthetic: `svg.insertAdjacentHTML` a `<g class="pele-node" data-id="A&quot;x">…` (DOM attribute value `A"x`) and a hand-built minimal graph node `{ entityId: 'node:x', id: 'A&quot;x', … }` as `FlowNode`; assert it correlates. Plus unit tests for the helper: `decodeEntities('A&quot;x') === 'A"x'`, `decodeEntities('a&amp;b') === 'a&b'`, `decodeEntities('&#65;') === 'A'`, unknown entity passes through.
+  7. Multi-line label — `'flowchart TD\n  A -->|"line1<br/>line2"| B\n'`: `edgeLabels` has `edge:A->B#0`.
+  8. View dispatch — `MermaidCanvasView` + `peleAdapter({ render: (src) => peleRender(src) })` on fixture 1: after `'render'`, container svg contains `[data-mw-entity="node:A"]`. Same view on a pie (`'pie title Pets\n  "cat": 40\n  "dog": 60\n'`): renders (svg exists) but contains zero `data-mw-entity` attributes.
+
+- [ ] **Step 2: Run to verify failure**
+
+  Run: `pnpm --filter @visimer/dom exec vitest run test/correlate-pele.test.ts`
+  Expected: FAIL — cannot resolve `../src/correlate.pele`.
+
+- [ ] **Step 3: Implement `correlate.pele.ts` + dispatch**
+
+  Algorithm (data-id first, degrade on miss):
+  - `decodeEntities(s)`: decode `&amp; &lt; &gt; &quot; &apos;` and `&#NN;`/`&#xHH;`; leave unknown codes as-is.
+  - Nodes: iterate all `g.pele-node`; match when `el.getAttribute('data-id') === node.id || === decodeEntities(node.id)`; tag + claim. Leftovers on both sides: if counts equal, zip in DOM order; else all unmatched → `failed`.
+  - Clusters: for each subgraph, `g.pele-cluster` by the same data-id rule → tag + `nodes.set`; additionally tag any `g.pele-cluster-title` with matching data-id (don't store in the map — selection styling queries the live DOM).
+  - Edge groups: for every `g.pele-edge`, require `data-id` starting `L_`; parse from the right: last `_`-segment must be numeric (count), second-last is target, remainder is source; bucket DOM elements by `source->target`. Core edges bucketed by `${source}->${target}` in `edges`-array order (declaration order). Per pair: equal counts → zip DOM order to declaration order, storing the group's inner `<path>` with `data-mw-entity` + `addEdgeHitOverlay(path, entityId)`; unequal counts → the whole pair's core edges go to `failed` and its DOM elements stay unclaimed.
+  - Leftover reconciliation (handles underscore ids): unclaimed DOM edge elements vs still-unmatched core edges — equal counts → zip in document order; else all degrade.
+  - Edge labels: same parse over `g.pele-edge-label`; per pair, zip against that pair's **labeled** core edges when counts are equal; leftovers reconciled the same way; store the `g` element tagged.
+  - `bindSvg` (view.ts:898-917): `const isPele = this.renderer.id === 'pele'`; under pele `this.correlation = flowchart ? correlatePeleFlowchart(svg, flowchart) : null`; `this.seqCorrelation = !isPele && sequence ? correlateSequence(svg, sequence) : null`; pass `null` (not `sequence`) to `armVisibilityRetry` under pele. The mermaid chain stays byte-identical.
+  - `correlate.ts:32`: `function addEdgeHitOverlay` → `export function` (comment moves with it).
+
+- [ ] **Step 4: Run tests to verify pass**
+
+  Run: `pnpm --filter @visimer/dom exec vitest run test/correlate-pele.test.ts`
+  Expected: PASS (all fixtures)
+
+- [ ] **Step 5: Full gates + export**
+
+  `packages/dom/src/index.ts`: export `correlatePeleFlowchart` next to `correlateFlowchart`. Run `pnpm --filter @visimer/dom test && pnpm typecheck`.
+  Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+  ```bash
+  git add packages/dom/src/correlate.pele.ts packages/dom/src/correlate.ts packages/dom/src/view.ts packages/dom/src/index.ts packages/dom/test/correlate-pele.test.ts
+  git commit -m "feat(dom): pele flowchart correlator"
+  ```
+
+### Task 4: Pele view behaviors (gating + integration)
+
+**Files:**
+- Modify: `packages/dom/src/view.ts` (edge-popover animation section gated; `injectAnimationKeyframes` call skipped)
+- Test: `packages/dom/test/pele-view.test.ts`
+
+**Interfaces:**
+- Consumes: `RendererAdapter` (Task 1), view seam (Task 2), `peleAdapter` over real pele.
+- Produces: no new exports — behavior gates only.
+
+- [ ] **Step 1: Write failing tests in `packages/dom/test/pele-view.test.ts`**
+
+  Harness: real pele through `peleAdapter`; `MermaidCanvasView` in a jsdom container; await the view's `'render'` event.
+
+  1. Keep-last-good: render `'flowchart TD\n  A[Start] --> B\n'`; then `editor.setCode('flowchart TD\n  A[unclosed', 'external')` and await the next `'render'` event → `{ ok: false }`; assert container still shows an svg containing `data-mw-entity="node:A"` (the previous render), `view.renderError` is truthy, and editor diagnostics contain `source: 'pele'`. Then `editor.setCode` back to the valid source → next render `{ ok: true }`, `renderError` null.
+  2. Overlay-editor fallback: render the standard fixture; call `view.editEntityLabel('node:A')`; assert no element inside the svg has `contenteditable` (pele labels are SVG `<text>`), and an overlay editor element (input/textarea, per `openOverlayEditor`'s implementation) appears in the container showing `Start`. Commit a new value following the commit path used by packages/dom/test/inplace.test.ts (Enter/blur per the overlay editor's own contract); assert `editor.code` contains the new label. Read `openOverlayEditor` (view.ts:1597+) first and follow its actual commit event.
+  3. Animation gating: with `'flowchart TD\n  A --> B\n'` rendered under pele, call `actionsFor` via bracket access (`(view as unknown as { actionsFor(id: string): PopoverAction[] }).actionsFor('edge:A->B#0')`); assert no item title contains `'Slow flow'` (the `anims` section, view.ts:1959-1963). Then repeat with a fake mermaid view on the same code: the animation items ARE present.
+  4. Keyframes skipped: after rendering under pele, the svg contains no `<style>` mentioning `vsmr-flow`; under the fake mermaid view it does (current unconditional behavior).
+
+- [ ] **Step 2: Run to verify failure**
+
+  Run: `pnpm --filter @visimer/dom exec vitest run test/pele-view.test.ts`
+  Expected: FAIL — cases 3 and 4 (animation items present / style injected under pele).
+
+- [ ] **Step 3: Implement the gates**
+
+  In the edge popover panel construction (the section built from the `anims` array, view.ts:1959-1963 and its panel use): omit the animation section entirely when `this.renderer.id === 'pele'`. In `render()`, wrap the `injectAnimationKeyframes(this.svg)` call (view.ts:833) in `if (this.renderer.id !== 'pele')`.
+
+- [ ] **Step 4: Run tests to verify pass**
+
+  Run: `pnpm --filter @visimer/dom exec vitest run test/pele-view.test.ts`
+  Expected: PASS.
+
+- [ ] **Step 5: Full gates**
+
+  Run: `pnpm --filter @visimer/dom test && pnpm typecheck`
+  Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+  ```bash
+  git add packages/dom/src/view.ts packages/dom/test/pele-view.test.ts
+  git commit -m "feat(dom): gate mermaid-only affordances under the pele renderer"
+  ```
+
+### Task 5: React `renderer` prop
+
+**Files:**
+- Modify: `packages/react/src/index.tsx` (`MermaidWysiwygProps`, `MermaidCanvasProps`, view-creation effects)
+
+**Interfaces:**
+- Consumes: `RendererAdapter` from `@visimer/dom` (Task 1), view seam (Task 2).
+- Produces: `renderer?: RendererAdapter` on both components; `mermaid` becomes optional (`mermaid?: MermaidLike`) — exactly one required at runtime (the view's constructor enforces it).
+
+- [ ] **Step 1: Update the two prop interfaces and components**
+
+  `MermaidWysiwygProps` / `MermaidCanvasProps`: `mermaid?: MermaidLike`, add `renderer?: RendererAdapter` with JSDoc "alternate renderer (e.g. `peleAdapter(pele)`); pass exactly one of `mermaid`/`renderer`". Pass both through to `new MermaidCanvasView({ …, mermaid, renderer })`. View-recreation effect deps: `[mermaid]` → `[mermaid, renderer]`; `[editor, mermaid]` → `[editor, mermaid, renderer]`. Skip the `setMermaidConfig` effect when `renderer` is provided (pass `mermaidConfig` only on the mermaid path).
+
+- [ ] **Step 2: Typecheck (react has no test suite — the playground in Task 6 exercises it)**
+
+  Run: `pnpm typecheck`
+  Expected: PASS with no edits to any existing consumer (all still pass `mermaid`).
+
+- [ ] **Step 3: Commit**
+
+  ```bash
+  git add packages/react/src/index.tsx
+  git commit -m "feat(react): optional renderer prop"
+  ```
+
+### Task 6: Playground renderer toggle
+
+**Files:**
+- Modify: `apps/playground/package.json` (dependency `pele`)
+- Modify: `apps/playground/src/App.tsx` (toggle state, `Workspace` plumbing, pele notice)
+- Modify: `apps/playground/src/app.css` (`--pele-*` theme block)
+- Test: no automated playground tests (repo convention: playground is the manual harness, TESTING.md:41-42)
+
+**Interfaces:**
+- Consumes: `peleAdapter` from `@visimer/dom`, `renderer` prop from Task 5, pele package.
+- Produces: user-facing toggle; nothing for later tasks.
+
+- [ ] **Step 1: Add the dependency**
+
+  `pnpm --filter playground add pele` (use the actual package name from apps/playground/package.json if different).
+
+- [ ] **Step 2: Implement the toggle**
+
+  `App`: `const [renderer, setRenderer] = useState<'mermaid' | 'pele'>(() => localStorage.getItem('visimer.renderer') === 'pele' ? 'pele' : 'mermaid')`, persist on change; segmented control in the topbar `.controls` (Mermaid | Pele). Pass `renderer` down to `Workspace`. `Workspace`: `import * as pele from 'pele'` + `import { peleAdapter } from '@visimer/dom'`; memoize once (`useRef`/`useMemo`, module scope preferred) `peleAdapter(pele, { fontFamily: '"Inter Variable", "Inter", ui-sans-serif, system-ui, sans-serif' })`; `<MermaidCanvas … mermaid={renderer === 'mermaid' ? mermaid : undefined} renderer={renderer === 'pele' ? peleRendererAdapter : undefined} mermaidConfig={renderer === 'mermaid' ? { securityLevel: 'loose', ...themeConfig(theme) } : undefined} />`. Under pele add one notice element under the toolbar: flowcharts editable; other types render view-only; zenuml unsupported.
+
+- [ ] **Step 3: Theme pele to match INK**
+
+  `app.css`: on the canvas container (`.canvas`):
+  `--pele-bg: #000000; --pele-fg: #ededed; --pele-muted: #a1a1a1; --pele-line: #8f8f8f; --pele-surface: #111111; --pele-surface-alt: #1a1a1a; --pele-border: #3f3f3f; --pele-accent: #3784ff; --pele-font: "Inter Variable", "Inter", ui-sans-serif, system-ui, sans-serif;` — eyeball-match only; adjust while looking at it.
+
+- [ ] **Step 4: Gates + manual smoke**
+
+  Run: `pnpm typecheck && pnpm test`
+  Expected: PASS. Then `pnpm dev` → playground: toggle to Pele on the flowchart sample → double-click rename (overlay editor), drag-to-connect, delete, undo all work; switch to a non-flowchart sample → renders view-only with the notice; toggle back to Mermaid → everything as before.
+
+- [ ] **Step 5: Commit**
+
+  ```bash
+  git add apps/playground/package.json apps/playground/src/App.tsx apps/playground/src/app.css pnpm-lock.yaml
+  git commit -m "feat(playground): mermaid/pele renderer toggle"
+  ```

From b72b9615b87f721d933140d1cf4659b99e387a4f Mon Sep 17 00:00:00 2001
From: Casey Gollan <hello@caseyagollan.com>
Date: Sun, 1 Nov 2026 11:51:58 -0500
Subject: [PATCH 04/21] feat(dom): renderer adapter seam with mermaid and pele
 adapters

---
 packages/dom/package.json          |   5 +-
 packages/dom/src/index.ts          |   1 +
 packages/dom/src/renderer.ts       |  90 ++++++++++++++++++++
 packages/dom/test/renderer.test.ts | 131 +++++++++++++++++++++++++++++
 pnpm-lock.yaml                     |   9 ++
 5 files changed, 234 insertions(+), 2 deletions(-)
 create mode 100644 packages/dom/src/renderer.ts
 create mode 100644 packages/dom/test/renderer.test.ts

diff --git a/packages/dom/package.json b/packages/dom/package.json
index 5bde617..0ba9b52 100644
--- a/packages/dom/package.json
+++ b/packages/dom/package.json
@@ -17,9 +17,10 @@
     "@visimer/core": "workspace:*"
   },
   "devDependencies": {
+    "jsdom": "^25.0.1",
+    "pele": "^1.13.0",
     "typescript": "^5.6.3",
-    "vitest": "^2.1.9",
-    "jsdom": "^25.0.1"
+    "vitest": "^2.1.9"
   },
   "license": "MIT",
   "files": [
diff --git a/packages/dom/src/index.ts b/packages/dom/src/index.ts
index 1276ba7..859ed6c 100644
--- a/packages/dom/src/index.ts
+++ b/packages/dom/src/index.ts
@@ -1,3 +1,4 @@
 export { MermaidCanvasView, type ViewOptions, type ViewHooks, type Tool, type MermaidLike } from './view'
+export { mermaidAdapter, peleAdapter, type RendererAdapter, type PeleLike } from './renderer'
 export { correlateFlowchart, correlateSequence, type Correlation, type SequenceCorrelation } from './correlate'
 export { Popover, type PopoverAction, type PopoverPanelItem } from './popover'
diff --git a/packages/dom/src/renderer.ts b/packages/dom/src/renderer.ts
new file mode 100644
index 0000000..5bfd7c5
--- /dev/null
+++ b/packages/dom/src/renderer.ts
@@ -0,0 +1,90 @@
+import type { MermaidLike } from './view'
+
+/**
+ * A renderer behind a uniform seam, so the canvas can drive Mermaid or Pele
+ * without knowing which one is mounted.
+ */
+export interface RendererAdapter {
+  readonly id: 'mermaid' | 'pele'
+  render(code: string): Promise<{ svg: string }>
+  validate?(code: string): Promise<{ message: string } | null>
+}
+
+/**
+ * Structural view of Pele's `render`/`parse`, declared with method syntax so
+ * an implementation's narrower parameters stay assignable. This package never
+ * imports pele; the tests wrap the real module.
+ */
+export interface PeleLike {
+  render(source: string, options?: Record<string, unknown>): { svg: string; [key: string]: unknown }
+  parse?(text: string): unknown
+}
+
+/** global counter so concurrent adapters never collide on mermaid's DOM ids */
+let renderIdCounter = 0
+
+function firstLine(err: unknown): string {
+  return err instanceof Error ? err.message.split('\n')[0] : String(err)
+}
+
+/**
+ * Drive Mermaid through the adapter seam. Mermaid keeps a module-global
+ * config, so `initialize` is re-asserted before every render rather than
+ * trusted from creation time (a second adapter on the page overwrites it).
+ */
+export function mermaidAdapter(mermaid: MermaidLike, config?: Record<string, unknown>): RendererAdapter {
+  const initConfig = config ?? {}
+  mermaid.initialize(initConfig)
+  return {
+    id: 'mermaid',
+    async render(code) {
+      const id = `mw-render-${++renderIdCounter}`
+      mermaid.initialize(initConfig)
+      try {
+        const { svg } = await mermaid.render(id, code)
+        return { svg }
+      } catch (err) {
+        // mermaid can leave a temp error element behind
+        document.getElementById(`d${id}`)?.remove()
+        document.getElementById(id)?.remove()
+        throw err
+      }
+    },
+    async validate(code) {
+      try {
+        await mermaid.parse(code)
+        return null
+      } catch (err) {
+        return { message: firstLine(err) }
+      }
+    },
+  }
+}
+
+/**
+ * Drive Pele through the same seam. Pele renders synchronously; the adapter
+ * lifts the result into a promise. `validate` is only offered when the
+ * underlying module exposes `parse`.
+ */
+export function peleAdapter(pele: PeleLike, options?: Record<string, unknown>): RendererAdapter {
+  const { parse } = pele
+  const validate = parse
+    ? async (code: string): Promise<{ message: string } | null> => {
+        try {
+          parse(code)
+          return null
+        } catch (err) {
+          const info = err as { message?: string; type?: string; line?: number; column?: number }
+          const location = info.line ? ` (line ${info.line}, column ${info.column})` : ''
+          return { message: `${info.type ?? 'pele'} error: ${firstLine(err)}${location}` }
+        }
+      }
+    : undefined
+  return {
+    id: 'pele',
+    async render(code) {
+      return { svg: pele.render(code, options).svg }
+    },
+    ...(validate ? { validate } : {}),
+  }
+}
diff --git a/packages/dom/test/renderer.test.ts b/packages/dom/test/renderer.test.ts
new file mode 100644
index 0000000..c5018ef
--- /dev/null
+++ b/packages/dom/test/renderer.test.ts
@@ -0,0 +1,131 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest'
+import { render as peleRender } from 'pele'
+import { mermaidAdapter, peleAdapter, type PeleLike } from '../src/renderer'
+import type { MermaidLike } from '../src'
+
+// jsdom has no CSS.escape (browsers do)
+if (typeof (globalThis as { CSS?: unknown }).CSS === 'undefined') {
+  ;(globalThis as { CSS?: { escape(s: string): string } }).CSS = {
+    escape: (s: string) => s.replace(/[^a-zA-Z0-9_-]/g, (c) => `\\${c}`),
+  }
+}
+
+// jsdom has no canvas: pele probes for one to measure text, and jsdom's
+// getContext raises a noisy "not implemented" error. Return null so pele falls
+// back to its built-in metrics table (the assertions here are structural, not
+// pixel-precise).
+HTMLCanvasElement.prototype.getContext = (() => null) as typeof HTMLCanvasElement.prototype.getContext
+
+describe('mermaidAdapter', () => {
+  it('initializes at creation and before every render', async () => {
+    const calls: string[] = []
+    const mermaid: MermaidLike = {
+      initialize() {
+        calls.push('initialize')
+      },
+      async render(id) {
+        calls.push(`render:${id}`)
+        return { svg: '<svg></svg>' }
+      },
+      async parse() {
+        return null
+      },
+    }
+
+    const adapter = mermaidAdapter(mermaid, { theme: 'dark' })
+    expect(calls).toEqual(['initialize'])
+
+    await adapter.render('flowchart TD\n  A --> B')
+    await adapter.render('flowchart TD\n  A --> B')
+
+    expect(calls.filter((c) => c.startsWith('render'))).toHaveLength(2)
+    calls.forEach((call, i) => {
+      if (call.startsWith('render')) expect(calls[i - 1]).toBe('initialize')
+    })
+  })
+
+  it('removes the temp error elements mermaid leaves behind when render throws', async () => {
+    const mermaid: MermaidLike = {
+      initialize() {},
+      async render(id) {
+        const doomed = document.createElement('div')
+        doomed.id = `d${id}`
+        document.body.appendChild(doomed)
+        const named = document.createElement('div')
+        named.id = id
+        document.body.appendChild(named)
+        throw new Error('boom')
+      },
+      async parse() {
+        return null
+      },
+    }
+
+    const adapter = mermaidAdapter(mermaid)
+    await expect(adapter.render('bad')).rejects.toThrow('boom')
+    expect(document.querySelectorAll('[id^="mw-render"], [id^="dmw-render"]')).toHaveLength(0)
+  })
+
+  it('validate resolves null on parse success and the first error line on throw', async () => {
+    const ok: MermaidLike = {
+      initialize() {},
+      async render() {
+        return { svg: '' }
+      },
+      async parse() {
+        return true
+      },
+    }
+    expect(await mermaidAdapter(ok).validate?.('flowchart TD')).toBeNull()
+
+    const bad: MermaidLike = {
+      initialize() {},
+      async render() {
+        return { svg: '' }
+      },
+      async parse() {
+        throw new Error('Parse error on line 3:\nexpecting FOO')
+      },
+    }
+    expect(await mermaidAdapter(bad).validate?.('nope')).toEqual({ message: 'Parse error on line 3:' })
+  })
+})
+
+describe('peleAdapter', () => {
+  it('wraps pele synchronous render in a promise', async () => {
+    const pele: PeleLike = { render: (src) => ({ svg: `<svg class="pele">${src}</svg>` }) }
+    const { svg } = await peleAdapter(pele).render('x')
+    expect(svg).toContain('pele')
+    expect(svg).toContain('x')
+  })
+
+  it('validate maps a pele error and is absent without parse', async () => {
+    const error = Object.assign(new Error('Parse error on line 2:\nunexpected token'), {
+      type: 'flowchart',
+      line: 2,
+      column: 13,
+    })
+    const pele: PeleLike = {
+      render: () => ({ svg: '' }),
+      parse: () => {
+        throw error
+      },
+    }
+    const { message } = (await peleAdapter(pele).validate?.('flowchart LR\n  A --')) ?? {}
+    expect(message).toEqual(expect.stringContaining('flowchart error: Parse error on line 2:'))
+    expect(message).toEqual(expect.stringContaining('(line 2, column 13)'))
+
+    const noParse: PeleLike = { render: () => ({ svg: '' }) }
+    expect(peleAdapter(noParse).validate).toBeUndefined()
+  })
+
+  it('renders a real flowchart through pele', async () => {
+    // pele's RenderResult is an interface, so it has no implicit index
+    // signature; spread it to satisfy PeleLike's `[key: string]: unknown`.
+    const peleLike: PeleLike = { render: (src, options) => ({ ...peleRender(src, options) }) }
+    const { svg } = await peleAdapter(peleLike).render('flowchart LR\n  A --> B')
+    expect(svg).toContain('class="pele-node')
+    expect(svg).toContain('data-id="A"')
+  })
+})
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index dfa64ca..fababb4 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -229,6 +229,9 @@ importers:
       jsdom:
         specifier: ^25.0.1
         version: 25.0.1
+      pele:
+        specifier: ^1.13.0
+        version: 1.13.0
       typescript:
         specifier: ^5.6.3
         version: 5.9.3
@@ -2290,6 +2293,10 @@ packages:
     resolution: {integrity: sha512-//nshmD55c46FuFw26xV/xFAaB5HF9Xdap7HJBBnrKdAd6/GxDBaNA1870O79+9ueg61cZLSVc+OaFlfmObYVQ==}
     engines: {node: '>= 14.16'}
 
+  pele@1.13.0:
+    resolution: {integrity: sha512-Ie8UKY9x00MsuR3jO6AzUwzK2Z6MIV3Tf4EDdITiuk8Uaz8K7g0R082WqsqNaSU8DdgkrRvZThzhit83mi/uiw==}
+    engines: {node: '>=20'}
+
   picocolors@1.1.1:
     resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==}
 
@@ -4766,6 +4773,8 @@ snapshots:
 
   pathval@2.0.1: {}
 
+  pele@1.13.0: {}
+
   picocolors@1.1.1: {}
 
   picomatch@2.3.2: {}

From 7d5ad748622c9b66cdb0c32660d663442981ceef Mon Sep 17 00:00:00 2001
From: Casey Gollan <hello@caseyagollan.com>
Date: Sun, 1 Nov 2026 11:53:54 -0500
Subject: [PATCH 05/21] fix(dom): pele adapter interface matches the real pele
 module

---
 packages/dom/src/renderer.ts       | 9 +++++----
 packages/dom/test/renderer.test.ts | 4 +---
 2 files changed, 6 insertions(+), 7 deletions(-)

diff --git a/packages/dom/src/renderer.ts b/packages/dom/src/renderer.ts
index 5bfd7c5..8d355c7 100644
--- a/packages/dom/src/renderer.ts
+++ b/packages/dom/src/renderer.ts
@@ -11,12 +11,13 @@ export interface RendererAdapter {
 }
 
 /**
- * Structural view of Pele's `render`/`parse`, declared with method syntax so
- * an implementation's narrower parameters stay assignable. This package never
- * imports pele; the tests wrap the real module.
+ * Structural view of Pele's `render`/`parse`. Method syntax keeps parameter
+ * checking bivariant, so the real `pele` module — whose `render` accepts a
+ * wider source union and its own options type — is assignable without this
+ * package importing pele.
  */
 export interface PeleLike {
-  render(source: string, options?: Record<string, unknown>): { svg: string; [key: string]: unknown }
+  render(source: string, options?: Record<string, unknown>): { svg: string }
   parse?(text: string): unknown
 }
 
diff --git a/packages/dom/test/renderer.test.ts b/packages/dom/test/renderer.test.ts
index c5018ef..fa5a3c7 100644
--- a/packages/dom/test/renderer.test.ts
+++ b/packages/dom/test/renderer.test.ts
@@ -121,9 +121,7 @@ describe('peleAdapter', () => {
   })
 
   it('renders a real flowchart through pele', async () => {
-    // pele's RenderResult is an interface, so it has no implicit index
-    // signature; spread it to satisfy PeleLike's `[key: string]: unknown`.
-    const peleLike: PeleLike = { render: (src, options) => ({ ...peleRender(src, options) }) }
+    const peleLike: PeleLike = { render: (src, options) => peleRender(src, options) }
     const { svg } = await peleAdapter(peleLike).render('flowchart LR\n  A --> B')
     expect(svg).toContain('class="pele-node')
     expect(svg).toContain('data-id="A"')

From 605601019907927b8d46f5d86141686163514e4d Mon Sep 17 00:00:00 2001
From: Casey Gollan <hello@caseyagollan.com>
Date: Sun, 1 Nov 2026 11:53:54 -0500
Subject: [PATCH 06/21] chore: package-local vitest configs

---
 packages/codemirror/vitest.config.ts | 3 +++
 packages/core/vitest.config.ts       | 3 +++
 packages/dom/vitest.config.ts        | 3 +++
 packages/monaco/vitest.config.ts     | 3 +++
 4 files changed, 12 insertions(+)
 create mode 100644 packages/codemirror/vitest.config.ts
 create mode 100644 packages/core/vitest.config.ts
 create mode 100644 packages/dom/vitest.config.ts
 create mode 100644 packages/monaco/vitest.config.ts

diff --git a/packages/codemirror/vitest.config.ts b/packages/codemirror/vitest.config.ts
new file mode 100644
index 0000000..abed6b2
--- /dev/null
+++ b/packages/codemirror/vitest.config.ts
@@ -0,0 +1,3 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({})
diff --git a/packages/core/vitest.config.ts b/packages/core/vitest.config.ts
new file mode 100644
index 0000000..abed6b2
--- /dev/null
+++ b/packages/core/vitest.config.ts
@@ -0,0 +1,3 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({})
diff --git a/packages/dom/vitest.config.ts b/packages/dom/vitest.config.ts
new file mode 100644
index 0000000..abed6b2
--- /dev/null
+++ b/packages/dom/vitest.config.ts
@@ -0,0 +1,3 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({})
diff --git a/packages/monaco/vitest.config.ts b/packages/monaco/vitest.config.ts
new file mode 100644
index 0000000..abed6b2
--- /dev/null
+++ b/packages/monaco/vitest.config.ts
@@ -0,0 +1,3 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({})

From 16edd8fa95953194639c21943d5e38deff86efea Mon Sep 17 00:00:00 2001
From: Casey Gollan <hello@caseyagollan.com>
Date: Sun, 1 Nov 2026 12:03:29 -0500
Subject: [PATCH 07/21] refactor(dom): route the canvas view through
 RendererAdapter

---
 packages/core/src/types.ts         |   2 +-
 packages/dom/src/view.ts           |  67 ++++++-----
 packages/dom/test/renderer.test.ts | 187 ++++++++++++++++++++++++++++-
 3 files changed, 224 insertions(+), 32 deletions(-)

diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts
index 1a5372b..e680765 100644
--- a/packages/core/src/types.ts
+++ b/packages/core/src/types.ts
@@ -52,5 +52,5 @@ export interface Diagnostic {
   message: string
   span: Span | null
   severity: 'error' | 'warning'
-  source: 'core' | 'mermaid'
+  source: 'core' | 'mermaid' | 'pele'
 }
diff --git a/packages/dom/src/view.ts b/packages/dom/src/view.ts
index 1738f32..76ff2ab 100644
--- a/packages/dom/src/view.ts
+++ b/packages/dom/src/view.ts
@@ -32,6 +32,7 @@ import {
   type PopoverPanelSection,
 } from './popover'
 import { ICONS } from './icons'
+import { mermaidAdapter, type RendererAdapter } from './renderer'
 
 /** default swatches offered in the color panels (works on light and dark themes) */
 export const COLOR_PALETTE = ['#ef4444', '#f97316', '#eab308', '#22c55e', '#06b6d4', '#6366f1', '#d946ef', '#64748b']
@@ -155,8 +156,11 @@ export interface ViewHooks {
 export interface ViewOptions {
   editor: MermaidWysiwygEditor
   container: HTMLElement
-  mermaid: MermaidLike
-  /** merged into mermaid.initialize; e.g. { theme: 'dark' } */
+  /** mermaid instance to drive when no `renderer` is given (either one, exactly, is required) */
+  mermaid?: MermaidLike
+  /** renderer driving the canvas (e.g. `mermaidAdapter(...)` or `peleAdapter(...)`); exactly one of `mermaid`/`renderer` is required */
+  renderer?: RendererAdapter
+  /** merged into mermaid.initialize; e.g. { theme: 'dark' } (only used under the mermaid path) */
   mermaidConfig?: Record<string, unknown>
   debounceMs?: number
   readOnly?: boolean
@@ -237,8 +241,6 @@ const BASE_CSS = `
 `
 
 let styleInjected = false
-/** global counter so concurrent views never collide on mermaid's DOM ids */
-let renderIdCounter = 0
 
 /**
  * Read the in-place editor's label back to the string form the mermaid source
@@ -329,8 +331,12 @@ function placeCaretAt(root: HTMLElement, offset: number) {
 export class MermaidCanvasView {
   readonly editor: MermaidWysiwygEditor
   readonly container: HTMLElement
-  private mermaid: MermaidLike
+  private renderer: RendererAdapter
+  /** kept so setMermaidConfig can rebuild the mermaid adapter under new config */
+  private mermaidInstance: MermaidLike | null
   private mermaidConfig: Record<string, unknown>
+  /** setMermaidConfig warned under a custom renderer already; one notice is enough */
+  private setConfigWarned = false
   private svgHost: HTMLElement
   private overlayHost: HTMLElement
   private errorBadge: HTMLElement
@@ -417,15 +423,23 @@ export class MermaidCanvasView {
   private destroyed = false
 
   constructor(options: ViewOptions) {
+    if ((options.mermaid ? 1 : 0) + (options.renderer ? 1 : 0) !== 1) {
+      throw new Error('MermaidCanvasView: pass exactly one of `mermaid` or `renderer`')
+    }
     this.editor = options.editor
     this.container = options.container
-    this.mermaid = options.mermaid
+    this.mermaidInstance = options.mermaid ?? null
     this.readOnly = options.readOnly ?? false
     this.panZoomEnabled = options.panZoom ?? false
     this.debounceMs = options.debounceMs ?? 200
     this.defaultEdge = options.defaultEdge ?? {}
     this.hooks = options.hooks ?? {}
     this.mermaidConfig = { startOnLoad: false, ...options.mermaidConfig }
+    // mermaid.initialize writes a module-global config, so with more than one
+    // canvas on a page the last one to mount owns it and every other canvas
+    // renders with the wrong theme and layout — the adapter re-asserts ours
+    // before every render rather than trusting creation time
+    this.renderer = options.renderer ?? mermaidAdapter(options.mermaid!, this.mermaidConfig)
 
     if (!styleInjected) {
       const style = document.createElement('style')
@@ -449,8 +463,6 @@ export class MermaidCanvasView {
     this.container.append(this.svgHost, this.overlayHost, this.errorBadge)
     this.popover = new Popover(this.overlayHost)
 
-    this.mermaid.initialize(this.mermaidConfig)
-
     this.disposers.push(
       this.editor.on('change', () => this.scheduleRender()),
       this.editor.on('selectionChange', () => this.applySelectionStyles()),
@@ -527,8 +539,18 @@ export class MermaidCanvasView {
 
   /** Re-initialize mermaid with new config (e.g. theme) and re-render. */
   setMermaidConfig(config: Record<string, unknown>) {
+    // a custom renderer owns its own config — including a caller-built
+    // `mermaidAdapter(...)`, which has no instance here to rebuild under new
+    // config; warn once and leave the render as is
+    if (this.renderer.id !== 'mermaid' || this.mermaidInstance === null) {
+      if (!this.setConfigWarned) {
+        this.setConfigWarned = true
+        console.warn('MermaidCanvasView: setMermaidConfig has no effect under a custom renderer')
+      }
+      return
+    }
     this.mermaidConfig = { ...this.mermaidConfig, ...config }
-    this.mermaid.initialize(this.mermaidConfig)
+    this.renderer = mermaidAdapter(this.mermaidInstance!, this.mermaidConfig)
     this.lastRenderedCode = ''
     void this.render()
   }
@@ -792,14 +814,8 @@ export class MermaidCanvasView {
       return
     }
     const seq = ++this.renderSeq
-    const id = `mw-render-${++renderIdCounter}`
     try {
-      // mermaid.initialize writes a module-global config, so with more than one
-      // canvas on a page the last one to mount owns it and every other canvas
-      // renders with the wrong theme and layout. Re-assert ours here rather than
-      // trusting whatever was initialized in the constructor.
-      this.mermaid.initialize(this.mermaidConfig)
-      const { svg } = await this.mermaid.render(id, code)
+      const { svg } = await this.renderer.render(code)
       if (seq !== this.renderSeq) return // stale
       // an in-place edit may have kept typing since the live commit this render
       // came from — snapshot the label's real text and caret before the swap
@@ -845,14 +861,11 @@ export class MermaidCanvasView {
       }
     } catch (err) {
       if (seq !== this.renderSeq) return
-      // mermaid can leave a temp error element behind
-      document.getElementById(`d${id}`)?.remove()
-      document.getElementById(id)?.remove()
       const message = err instanceof Error ? err.message.split('\n')[0] : String(err)
       this.lastError = message
       this.errorBadge.textContent = `render error: ${message}`
       this.errorBadge.style.display = 'block'
-      const diag: Diagnostic = { message, span: null, severity: 'error', source: 'mermaid' }
+      const diag: Diagnostic = { message, span: null, severity: 'error', source: this.renderer.id }
       this.editor.setDiagnostics([diag])
       this.emit('render', { ok: false, error: message })
     }
@@ -2710,16 +2723,12 @@ export class MermaidCanvasView {
     return this.clientToSvg(rect.left + rect.width / 2, rect.top + rect.height / 2)
   }
 
-  /** Validate code through mermaid.parse and publish diagnostics (does not render). */
+  /** Validate code through the renderer's parse and publish diagnostics (does not render). */
   async validate(): Promise<boolean> {
-    try {
-      await this.mermaid.parse(this.editor.code)
-      return true
-    } catch (err) {
-      const message = err instanceof Error ? err.message.split('\n')[0] : String(err)
-      this.editor.setDiagnostics([{ message, span: null, severity: 'error', source: 'mermaid' }])
-      return false
-    }
+    const d = await this.renderer.validate?.(this.editor.code)
+    if (!d) return true
+    this.editor.setDiagnostics([{ message: d.message, span: null, severity: 'error', source: this.renderer.id }])
+    return false
   }
 
   destroy() {
diff --git a/packages/dom/test/renderer.test.ts b/packages/dom/test/renderer.test.ts
index fa5a3c7..272a16b 100644
--- a/packages/dom/test/renderer.test.ts
+++ b/packages/dom/test/renderer.test.ts
@@ -1,8 +1,9 @@
 // @vitest-environment jsdom
-import { describe, expect, it } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi, type MockInstance } from 'vitest'
 import { render as peleRender } from 'pele'
+import { MermaidWysiwygEditor } from '@visimer/core'
 import { mermaidAdapter, peleAdapter, type PeleLike } from '../src/renderer'
-import type { MermaidLike } from '../src'
+import { MermaidCanvasView, type MermaidLike, type RendererAdapter } from '../src'
 
 // jsdom has no CSS.escape (browsers do)
 if (typeof (globalThis as { CSS?: unknown }).CSS === 'undefined') {
@@ -127,3 +128,185 @@ describe('peleAdapter', () => {
     expect(svg).toContain('data-id="A"')
   })
 })
+
+/** drain microtasks and the macrotask queue so renders in flight land */
+async function flush() {
+  for (let i = 0; i < 5; i++) await new Promise((r) => setTimeout(r, 0))
+}
+
+describe('MermaidCanvasView renderer seam', () => {
+  const CODE = 'flowchart LR\n  A --> B\n'
+
+  let container: HTMLElement
+  let views: MermaidCanvasView[]
+  let warnSpy: MockInstance
+
+  beforeEach(() => {
+    container = document.createElement('div')
+    document.body.appendChild(container)
+    views = []
+    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    for (const view of views) view.destroy()
+    container.remove()
+    warnSpy.mockRestore()
+  })
+
+  it('renders through a custom renderer adapter', async () => {
+    const renderer: RendererAdapter = {
+      id: 'pele',
+      async render(code) {
+        return { svg: `<svg class="pele">${code}</svg>` }
+      },
+    }
+    const editor = new MermaidWysiwygEditor({ code: CODE })
+    let resolveRender!: () => void
+    const rendered = new Promise<void>((r) => (resolveRender = r))
+    const view = new MermaidCanvasView({ editor, container, renderer, debounceMs: 0 })
+    views.push(view)
+    view.on('render', () => resolveRender())
+    await rendered
+
+    const host = container.querySelector('.mw-svg-host')!
+    const svg = host.querySelector('svg.pele')
+    expect(svg).toBeTruthy()
+    expect(svg?.textContent).toContain('flowchart LR')
+  })
+
+  it('requires exactly one of mermaid or renderer', () => {
+    const editor = new MermaidWysiwygEditor({ code: CODE })
+    const mermaid: MermaidLike = {
+      initialize() {},
+      async render() {
+        return { svg: '<svg></svg>' }
+      },
+      async parse() {
+        return true
+      },
+    }
+    const renderer: RendererAdapter = {
+      id: 'pele',
+      async render() {
+        return { svg: '<svg></svg>' }
+      },
+    }
+    expect(() => new MermaidCanvasView({ editor, container })).toThrow(
+      'MermaidCanvasView: pass exactly one of `mermaid` or `renderer`',
+    )
+    expect(() => new MermaidCanvasView({ editor, container, mermaid, renderer })).toThrow(
+      'MermaidCanvasView: pass exactly one of `mermaid` or `renderer`',
+    )
+  })
+
+  it('keeps the mermaid initialize-then-render call order', async () => {
+    const calls: string[] = []
+    const mermaid: MermaidLike = {
+      initialize() {
+        calls.push('initialize')
+      },
+      async render(id) {
+        calls.push(`render:${id}`)
+        return { svg: '<svg></svg>' }
+      },
+      async parse() {
+        return true
+      },
+    }
+    const editor = new MermaidWysiwygEditor({ code: '' })
+    const view = new MermaidCanvasView({ editor, container, mermaid, debounceMs: 0 })
+    views.push(view)
+    await flush()
+    // the adapter initializes once at creation; the empty document renders nothing
+    expect(calls).toEqual(['initialize'])
+
+    editor.setCode('flowchart LR\n  A --> B\n  A --> C\n', 'external')
+    await flush()
+
+    const renderIdx = calls.findIndex((c) => c.startsWith('render:'))
+    expect(renderIdx).toBeGreaterThan(-1)
+    expect(calls[renderIdx - 1]).toBe('initialize')
+    expect(calls.filter((c) => c === 'initialize')).toHaveLength(2)
+  })
+
+  it('labels render-error diagnostics with the adapter id', async () => {
+    const renderer: RendererAdapter = {
+      id: 'pele',
+      async render() {
+        throw new Error('pele exploded')
+      },
+    }
+    const editor = new MermaidWysiwygEditor({ code: CODE })
+    let settle!: (p: { ok: boolean; error?: string }) => void
+    const outcome = new Promise<{ ok: boolean; error?: string }>((r) => (settle = r))
+    const view = new MermaidCanvasView({ editor, container, renderer, debounceMs: 0 })
+    views.push(view)
+    view.on('render', (p) => settle(p))
+    const payload = await outcome
+
+    expect(payload.ok).toBe(false)
+    expect(view.renderError).toBe('pele exploded')
+    const diag = editor.diagnostics.find((d) => d.source === 'pele')
+    expect(diag?.message).toBe('pele exploded')
+  })
+
+  it('setMermaidConfig warns once and does not re-render under a custom renderer', async () => {
+    let renders = 0
+    const renderer: RendererAdapter = {
+      id: 'pele',
+      async render() {
+        renders++
+        return { svg: '<svg></svg>' }
+      },
+    }
+    const editor = new MermaidWysiwygEditor({ code: CODE })
+    const view = new MermaidCanvasView({ editor, container, renderer, debounceMs: 0 })
+    views.push(view)
+    await flush()
+    const rendersBefore = renders
+    const errorBefore = view.renderError
+
+    view.setMermaidConfig({ theme: 'dark' })
+    await flush()
+
+    expect(warnSpy).toHaveBeenCalledTimes(1)
+    expect(renders).toBe(rendersBefore)
+    expect(view.renderError).toBe(errorBefore)
+
+    view.setMermaidConfig({ theme: 'forest' })
+    await flush()
+    expect(warnSpy).toHaveBeenCalledTimes(1)
+  })
+
+  it('setMermaidConfig warns instead of crashing when the mermaid adapter was built by the caller', async () => {
+    let renders = 0
+    const mermaid: MermaidLike = {
+      initialize() {},
+      async render() {
+        renders++
+        return { svg: '<svg></svg>' }
+      },
+      async parse() {
+        return true
+      },
+    }
+    const editor = new MermaidWysiwygEditor({ code: CODE })
+    // the JSDoc's own first example: caller-built mermaidAdapter, no `mermaid`
+    const view = new MermaidCanvasView({
+      editor,
+      container,
+      renderer: mermaidAdapter(mermaid),
+      debounceMs: 0,
+    })
+    views.push(view)
+    await flush()
+    const rendersBefore = renders
+
+    expect(() => view.setMermaidConfig({ theme: 'dark' })).not.toThrow()
+    await flush()
+
+    expect(warnSpy).toHaveBeenCalledTimes(1)
+    expect(renders).toBe(rendersBefore)
+  })
+})

From 6dd601e0b3ca6fc5f5f2c482971271b6b76384c3 Mon Sep 17 00:00:00 2001
From: Casey Gollan <hello@caseyagollan.com>
Date: Sun, 1 Nov 2026 12:26:28 -0500
Subject: [PATCH 08/21] feat(dom): pele flowchart correlator

---
 packages/dom/src/correlate.pele.ts       | 239 ++++++++++++++++
 packages/dom/src/correlate.ts            |   2 +-
 packages/dom/src/index.ts                |   1 +
 packages/dom/src/view.ts                 |  43 +--
 packages/dom/test/correlate-pele.test.ts | 340 +++++++++++++++++++++++
 5 files changed, 607 insertions(+), 18 deletions(-)
 create mode 100644 packages/dom/src/correlate.pele.ts
 create mode 100644 packages/dom/test/correlate-pele.test.ts

diff --git a/packages/dom/src/correlate.pele.ts b/packages/dom/src/correlate.pele.ts
new file mode 100644
index 0000000..643deb0
--- /dev/null
+++ b/packages/dom/src/correlate.pele.ts
@@ -0,0 +1,239 @@
+import type { FlowEdge, FlowGraph } from '@visimer/core'
+import { addEdgeHitOverlay, type Correlation } from './correlate'
+
+/**
+ * Decode the entity encodings pele bakes into `data-id` values (`&quot;`,
+ * `&#65;`, ...). The DOM has already decoded the attribute by the time we read
+ * it, so the graph id may still be encoded while the attribute is not — decode
+ * the graph side for comparison. Unknown entities pass through untouched.
+ */
+export function decodeEntities(s: string): string {
+  return s.replace(/&(amp|lt|gt|quot|apos|#\d+|#x[0-9a-fA-F]+);/g, (raw) => {
+    switch (raw) {
+      case '&amp;':
+        return '&'
+      case '&lt;':
+        return '<'
+      case '&gt;':
+        return '>'
+      case '&quot;':
+        return '"'
+      case '&apos;':
+        return "'"
+    }
+    const body = raw.slice(2, -1)
+    const code = body[0] === 'x' || body[0] === 'X' ? parseInt(body.slice(1), 16) : parseInt(body, 10)
+    // String.fromCodePoint throws above 0x10FFFF — leave invalid codes as-is
+    return code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : raw
+  })
+}
+
+/**
+ * Pele edge ids are `L_<src>_<tgt>_<count>` where count is per-pair and
+ * non-contiguous (first 0, then count+1: 2, 3, ...) — NOT an occurrence index.
+ * Parse from the right so underscore-bearing ids split at the right segments:
+ * `L_a_b_c_0` yields source `a_b`, target `c`. That can be a PHANTOM pair —
+ * the document's real edge may be `a -> b_c`, which pele encodes with the
+ * identical string — so callers must treat the parse as a hint, never proof.
+ * Ids not following the scheme (user-defined edge ids) return null and stay
+ * unclaimed.
+ */
+function parseEdgeId(dataId: string | null): { source: string; target: string } | null {
+  if (!dataId?.startsWith('L_')) return null
+  const body = dataId.slice(2)
+  const last = body.lastIndexOf('_')
+  if (last === -1 || !/^\d+$/.test(body.slice(last + 1))) return null
+  const rest = body.slice(0, last)
+  const second = rest.lastIndexOf('_')
+  if (second <= 0) return null
+  return { source: rest.slice(0, second), target: rest.slice(second + 1) }
+}
+
+/**
+ * Correlate pele's rendered flowchart SVG with the semantic graph.
+ * Strategy: pele's `data-id` attributes first, then count-checked per-pair
+ * zips, then an ambiguity-guarded leftover pass (underscore ids parse to
+ * phantom pairs). Invisible edges never claim a group, and any ambiguous
+ * match degrades BOTH sides — never mis-pairs.
+ */
+export function correlatePeleFlowchart(svg: SVGSVGElement, graph: FlowGraph): Correlation {
+  const nodes = new Map<string, SVGGElement>()
+  const edges = new Map<string, SVGElement>()
+  const edgeLabels = new Map<string, SVGGElement>()
+  const failed: string[] = []
+
+  const dataId = (el: Element) => el.getAttribute('data-id')
+
+  // --- nodes: pele stamps the node's entity-decoded id in data-id
+  const nodeEls = [...svg.querySelectorAll<SVGGElement>('g.pele-node')]
+  const claimed = new Set<Element>()
+  for (const node of graph.nodes) {
+    const el = nodeEls.find(
+      (e) => !claimed.has(e) && (dataId(e) === node.id || dataId(e) === decodeEntities(node.id)),
+    )
+    if (el) {
+      claimed.add(el)
+      nodes.set(node.entityId, el)
+      el.setAttribute('data-mw-entity', node.entityId)
+    }
+  }
+  // leftovers on both sides: equal counts → zip in DOM order, else degrade
+  const unmatchedNodes = graph.nodes.filter((n) => !nodes.has(n.entityId))
+  const unclaimedNodeEls = nodeEls.filter((e) => !claimed.has(e))
+  if (unmatchedNodes.length === unclaimedNodeEls.length) {
+    unmatchedNodes.forEach((n, i) => {
+      nodes.set(n.entityId, unclaimedNodeEls[i])
+      unclaimedNodeEls[i].setAttribute('data-mw-entity', n.entityId)
+    })
+  } else {
+    for (const n of unmatchedNodes) failed.push(n.entityId)
+  }
+
+  // --- clusters: subgraphs render as g.pele-cluster. Struck titles render in
+  // a top-level g.pele-cluster-titles OUTSIDE their cluster — tag them too,
+  // but don't store them: selection styling queries the live DOM.
+  for (const sg of graph.subgraphs) {
+    const cluster = [...svg.querySelectorAll<SVGGElement>('g.pele-cluster')].find(
+      (el) => dataId(el) === sg.id || dataId(el) === decodeEntities(sg.id),
+    )
+    if (cluster) {
+      cluster.setAttribute('data-mw-entity', sg.entityId)
+      nodes.set(sg.entityId, cluster)
+    }
+    for (const title of svg.querySelectorAll<SVGGElement>('g.pele-cluster-title')) {
+      const id = dataId(title)
+      if (id === sg.id || id === decodeEntities(sg.id)) {
+        title.setAttribute('data-mw-entity', sg.entityId)
+      }
+    }
+  }
+
+  // --- edges: bucket both sides by `source->target`, zip per pair only when
+  // the pair's counts agree, store the group's inner <path>. Invisible (`~~~`)
+  // core edges are excluded up front: pele never renders them, so they can
+  // never claim a group — and counted in, one once let its phantom bucket
+  // (L_a_b_c_0 parses as a_b->c) swallow the group rendered for a visible
+  // `a --> b_c` and mis-tag that path with the invisible edge.
+  const domEdges = [...svg.querySelectorAll<SVGGElement>('g.pele-edge')]
+  const claimedEdges = new Set<Element>()
+  const domEdgeBuckets = new Map<string, Element[]>()
+  for (const el of domEdges) {
+    const parsed = parseEdgeId(dataId(el))
+    if (!parsed) continue
+    const key = `${parsed.source}->${parsed.target}`
+    const list = domEdgeBuckets.get(key) ?? []
+    list.push(el)
+    domEdgeBuckets.set(key, list)
+  }
+  // core edges bucketed in declaration order (== edges-array order)
+  const coreEdgeBuckets = new Map<string, FlowEdge[]>()
+  for (const edge of graph.edges) {
+    if (edge.seg.line === 'invisible') {
+      failed.push(edge.entityId)
+      continue
+    }
+    const key = `${edge.source}->${edge.target}`
+    const list = coreEdgeBuckets.get(key) ?? []
+    list.push(edge)
+    coreEdgeBuckets.set(key, list)
+  }
+  const unmatchedEdges: FlowEdge[] = []
+  const claimEdge = (el: Element, edge: FlowEdge): boolean => {
+    const path = el.querySelector('path')
+    if (!path) return false
+    claimedEdges.add(el)
+    edges.set(edge.entityId, path)
+    path.setAttribute('data-mw-entity', edge.entityId)
+    addEdgeHitOverlay(path, edge.entityId)
+    return true
+  }
+  for (const [key, coreList] of coreEdgeBuckets) {
+    const domList = domEdgeBuckets.get(key) ?? []
+    if (coreList.length === domList.length) {
+      coreList.forEach((edge, i) => {
+        if (!claimEdge(domList[i], edge)) unmatchedEdges.push(edge)
+      })
+    } else {
+      // a pair whose counts disagree can't be zipped — degrade the pair
+      unmatchedEdges.push(...coreList)
+    }
+  }
+  // leftover reconciliation: an underscore id like L_a_b_c_0 right-parses to
+  // `a_b -> c`, a phantom bucket, so its group can leave the pair pass
+  // unclaimed while its real edge (`a -> b_c`) sits unmatched. Pair the two
+  // only when the assignment is unambiguous — the group's data-id starts
+  // with `L_<src>_<tgt>_` for that edge, it is the ONLY unclaimed group that
+  // fits, and it fits no other unmatched edge. Otherwise degrade both sides:
+  // an ambiguous match must never become a wrong pairing.
+  const unclaimedEdgeEls = domEdges.filter((e) => !claimedEdges.has(e))
+  for (const edge of unmatchedEdges) {
+    const fits = unclaimedEdgeEls.filter((el) =>
+      (dataId(el) ?? '').startsWith(`L_${edge.source}_${edge.target}_`),
+    )
+    const unambiguous =
+      fits.length === 1 &&
+      unmatchedEdges.every(
+        (other) => other === edge || !(dataId(fits[0]) ?? '').startsWith(`L_${other.source}_${other.target}_`),
+      )
+    // a claimed-but-pathless group degrades the edge instead of dropping it
+    if (!(unambiguous && claimEdge(fits[0], edge))) failed.push(edge.entityId)
+  }
+
+  // --- edge labels: same pairing over g.pele-edge-label, against the pair's
+  // labeled core edges. Label misses degrade silently (unmapped) — the edge
+  // entity itself may still correlate; mermaid's correlator treats labels the
+  // same way.
+  const labelEls = [...svg.querySelectorAll<SVGGElement>('g.pele-edge-label')]
+  const claimedLabels = new Set<Element>()
+  const domLabelBuckets = new Map<string, Element[]>()
+  for (const el of labelEls) {
+    const parsed = parseEdgeId(dataId(el))
+    if (!parsed) continue
+    const key = `${parsed.source}->${parsed.target}`
+    const list = domLabelBuckets.get(key) ?? []
+    list.push(el)
+    domLabelBuckets.set(key, list)
+  }
+  const coreLabelBuckets = new Map<string, FlowEdge[]>()
+  for (const edge of graph.edges) {
+    if (edge.label === null || edge.label === '') continue
+    // invisible edges are view-only under pele — their labels never claim a
+    // group, even though pele still renders them (label misses degrade
+    // silently, like every other label miss)
+    if (edge.seg.line === 'invisible') continue
+    const key = `${edge.source}->${edge.target}`
+    const list = coreLabelBuckets.get(key) ?? []
+    list.push(edge)
+    coreLabelBuckets.set(key, list)
+  }
+  const unmatchedLabelEdges: FlowEdge[] = []
+  const claimLabel = (el: Element, edge: FlowEdge): void => {
+    if (!el) return
+    claimedLabels.add(el)
+    edgeLabels.set(edge.entityId, el as SVGGElement)
+    el.setAttribute('data-mw-entity', edge.entityId)
+  }
+  for (const [key, coreList] of coreLabelBuckets) {
+    const domList = domLabelBuckets.get(key) ?? []
+    if (coreList.length === domList.length) {
+      coreList.forEach((edge, i) => claimLabel(domList[i], edge))
+    } else {
+      unmatchedLabelEdges.push(...coreList)
+    }
+  }
+  // same ambiguity guard as the edge leftovers above, applied to labels
+  const unclaimedLabelEls = labelEls.filter((e) => !claimedLabels.has(e))
+  for (const edge of unmatchedLabelEdges) {
+    const fits = unclaimedLabelEls.filter((el) =>
+      (dataId(el) ?? '').startsWith(`L_${edge.source}_${edge.target}_`),
+    )
+    const unambiguous =
+      fits.length === 1 &&
+      unmatchedLabelEdges.every(
+        (other) => other === edge || !(dataId(fits[0]) ?? '').startsWith(`L_${other.source}_${other.target}_`),
+      )
+    if (unambiguous) claimLabel(fits[0], edge)
+  }
+
+  return { nodes, edges, edgeLabels, failed }
+}
diff --git a/packages/dom/src/correlate.ts b/packages/dom/src/correlate.ts
index caa8157..983dd3b 100644
--- a/packages/dom/src/correlate.ts
+++ b/packages/dom/src/correlate.ts
@@ -29,7 +29,7 @@ function esc(s: string): string {
  * overlay is painted BEFORE the visible path so the arrow head, cross, or
  * dot still visually wins overlap, and it inherits the same paint transform.
  */
-function addEdgeHitOverlay(path: SVGElement, entityId: string): void {
+export function addEdgeHitOverlay(path: SVGElement, entityId: string): void {
   const doc = path.ownerDocument
   if (!doc || path.hasAttribute('data-mw-hit-overlay')) return
   const parent = path.parentNode
diff --git a/packages/dom/src/index.ts b/packages/dom/src/index.ts
index 859ed6c..f46befb 100644
--- a/packages/dom/src/index.ts
+++ b/packages/dom/src/index.ts
@@ -1,4 +1,5 @@
 export { MermaidCanvasView, type ViewOptions, type ViewHooks, type Tool, type MermaidLike } from './view'
 export { mermaidAdapter, peleAdapter, type RendererAdapter, type PeleLike } from './renderer'
 export { correlateFlowchart, correlateSequence, type Correlation, type SequenceCorrelation } from './correlate'
+export { correlatePeleFlowchart } from './correlate.pele'
 export { Popover, type PopoverAction, type PopoverPanelItem } from './popover'
diff --git a/packages/dom/src/view.ts b/packages/dom/src/view.ts
index 76ff2ab..13f30da 100644
--- a/packages/dom/src/view.ts
+++ b/packages/dom/src/view.ts
@@ -33,6 +33,7 @@ import {
 } from './popover'
 import { ICONS } from './icons'
 import { mermaidAdapter, type RendererAdapter } from './renderer'
+import { correlatePeleFlowchart } from './correlate.pele'
 
 /** default swatches offered in the color panels (works on light and dark themes) */
 export const COLOR_PALETTE = ['#ef4444', '#f97316', '#eab308', '#22c55e', '#06b6d4', '#6366f1', '#d946ef', '#64748b']
@@ -912,24 +913,32 @@ export class MermaidCanvasView {
     const svg = this.svg
     if (!svg) return
     const { flowchart, sequence, state, classGraph, er } = this.editor.result
-    this.correlation = flowchart
-      ? correlateFlowchart(svg, flowchart)
-      : state
-        ? correlateState(svg, state)
-        : classGraph
-          ? correlateClass(svg, classGraph)
-          : er
-            ? correlateEr(svg, er)
-            : this.editor.result.pie
-              ? correlatePie(svg, this.editor.result.pie)
-              : this.editor.result.gantt
-                ? correlateGantt(svg, this.editor.result.gantt)
-                : this.editor.result.lineItems
-                  ? correlateLineItems(svg, this.editor.result.lineItems)
-                  : null
-    this.seqCorrelation = sequence ? correlateSequence(svg, sequence) : null
+    const isPele = this.renderer.id === 'pele'
+    // Under pele, flowcharts correlate through their own module; every other
+    // diagram slot stays view-only, and sequence correlation plus the
+    // visibility retry are mermaid-only.
+    if (isPele) {
+      this.correlation = flowchart ? correlatePeleFlowchart(svg, flowchart) : null
+    } else {
+      this.correlation = flowchart
+        ? correlateFlowchart(svg, flowchart)
+        : state
+          ? correlateState(svg, state)
+          : classGraph
+            ? correlateClass(svg, classGraph)
+            : er
+              ? correlateEr(svg, er)
+              : this.editor.result.pie
+                ? correlatePie(svg, this.editor.result.pie)
+                : this.editor.result.gantt
+                  ? correlateGantt(svg, this.editor.result.gantt)
+                  : this.editor.result.lineItems
+                    ? correlateLineItems(svg, this.editor.result.lineItems)
+                    : null
+    }
+    this.seqCorrelation = !isPele && sequence ? correlateSequence(svg, sequence) : null
     this.clearLifelineUi()
-    this.armVisibilityRetry(svg, sequence)
+    this.armVisibilityRetry(svg, isPele ? null : sequence)
 
     svg.addEventListener('click', (e) => this.onSvgClick(e))
     svg.addEventListener('dblclick', (e) => this.onSvgDblClick(e))
diff --git a/packages/dom/test/correlate-pele.test.ts b/packages/dom/test/correlate-pele.test.ts
new file mode 100644
index 0000000..c158604
--- /dev/null
+++ b/packages/dom/test/correlate-pele.test.ts
@@ -0,0 +1,340 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { render as peleRender } from 'pele'
+import { MermaidWysiwygEditor, type FlowGraph, type FlowNode } from '@visimer/core'
+import { correlatePeleFlowchart, decodeEntities } from '../src/correlate.pele'
+import { MermaidCanvasView, peleAdapter } from '../src'
+
+// jsdom has no CSS.escape (browsers do)
+if (typeof (globalThis as { CSS?: unknown }).CSS === 'undefined') {
+  ;(globalThis as { CSS?: { escape(s: string): string } }).CSS = {
+    escape: (s: string) => s.replace(/[^a-zA-Z0-9_-]/g, (c) => `\\${c}`),
+  }
+}
+
+// jsdom has no canvas: pele probes for one to measure text, and jsdom's
+// getContext raises a noisy "not implemented" error. Return null so pele falls
+// back to its built-in metrics table (the assertions here are structural, not
+// pixel-precise).
+HTMLCanvasElement.prototype.getContext = (() => null) as typeof HTMLCanvasElement.prototype.getContext
+
+const hosts: HTMLElement[] = []
+
+/** render a code string with real pele, correlate it against core's graph */
+function correlate(code: string) {
+  const editor = new MermaidWysiwygEditor({ code })
+  const graph = editor.result.flowchart!
+  const host = document.createElement('div')
+  document.body.appendChild(host)
+  hosts.push(host)
+  host.innerHTML = peleRender(code).svg
+  const svg = host.querySelector('svg')!
+  return { svg, graph, result: correlatePeleFlowchart(svg, graph) }
+}
+afterEach(() => {
+  for (const host of hosts.splice(0)) host.remove()
+})
+
+describe('correlatePeleFlowchart', () => {
+  it('correlates nodes, edge paths and edge labels of a standard flowchart', () => {
+    const { result, svg } = correlate(
+      'flowchart TD\n  A[Start] --> B{OK?}\n  B -->|yes| C[Ship]\n',
+    )
+    // nodes land on the pele node groups, tagged
+    for (const [entityId, id] of [
+      ['node:A', 'A'],
+      ['node:B', 'B'],
+      ['node:C', 'C'],
+    ] as const) {
+      const el = result.nodes.get(entityId)!
+      expect(el).toBeTruthy()
+      expect(el).toBe(svg.querySelector(`g.pele-node[data-id="${id}"]`))
+      expect(el.getAttribute('data-mw-entity')).toBe(entityId)
+    }
+    // edges land on the inner <path> of the right pele-edge group
+    const ab = result.edges.get('edge:A->B#0')!
+    const bc = result.edges.get('edge:B->C#0')!
+    expect(ab).toBeTruthy()
+    expect(bc).toBeTruthy()
+    expect(ab).not.toBe(bc)
+    expect(ab.closest('g.pele-edge')?.getAttribute('data-id')).toMatch(/^L_A_B_/)
+    expect(bc.closest('g.pele-edge')?.getAttribute('data-id')).toMatch(/^L_B_C_/)
+    expect(ab.getAttribute('data-mw-entity')).toBe('edge:A->B#0')
+    // the transparent hit-overlay sibling clone exists for the visible path
+    const overlay = ab.parentElement!.querySelector('[data-mw-hit-overlay="edge:A->B#0"]')
+    expect(overlay).toBeTruthy()
+    expect(overlay!.getAttribute('d')).toBe(ab.getAttribute('d'))
+    // the labeled edge's label correlates to its pele-edge-label group
+    const label = result.edgeLabels.get('edge:B->C#0')!
+    expect(label).toBe(svg.querySelector('g.pele-edge-label[data-id="L_B_C_0"]'))
+    expect(label.getAttribute('data-mw-entity')).toBe('edge:B->C#0')
+    expect(result.failed).toEqual([])
+  })
+
+  it('correlates clusters, and struck cluster titles outside their cluster', () => {
+    const { result, svg, graph } = correlate(
+      'flowchart TD\n  subgraph SG [Group]\n    A[Start] --> B\n  end\n  B --> C\n',
+    )
+    const cluster = result.nodes.get('subgraph:SG')!
+    expect(cluster).toBe(svg.querySelector('g.pele-cluster[data-id="SG"]'))
+    expect(cluster.getAttribute('data-mw-entity')).toBe('subgraph:SG')
+
+    // pele draws struck cluster titles in a top-level group OUTSIDE their
+    // cluster (pele src/svg/cluster.ts:67) — inject that shape and re-correlate
+    svg.insertAdjacentHTML(
+      'beforeend',
+      '<g class="pele-cluster-titles"><g class="pele-cluster-title" data-id="SG">Group</g></g>',
+    )
+    const again = correlatePeleFlowchart(svg, graph)
+    const title = svg.querySelector('g.pele-cluster-title[data-id="SG"]')!
+    expect(title.getAttribute('data-mw-entity')).toBe('subgraph:SG')
+    // the title is tagged but not stored — selection styling queries the DOM
+    expect(again.nodes.get('subgraph:SG')).toBe(cluster)
+  })
+
+  it('zips duplicate pair edges first-declared to first-in-DOM', () => {
+    const { result } = correlate('flowchart TD\n  A -->|one| B\n  A -->|two| B\n')
+    const first = result.edges.get('edge:A->B#0')!
+    const second = result.edges.get('edge:A->B#1')!
+    expect(first).toBeTruthy()
+    expect(second).toBeTruthy()
+    expect(first).not.toBe(second)
+    // pele numbers a pair's edges 0, 2, ... (count is per-pair and skips 1) —
+    // the zip must follow DOM order, never pele's count
+    expect(first.closest('g.pele-edge')?.getAttribute('data-id')).toBe('L_A_B_0')
+    expect(second.closest('g.pele-edge')?.getAttribute('data-id')).toBe('L_A_B_2')
+    expect(result.edgeLabels.get('edge:A->B#0')?.textContent).toContain('one')
+    expect(result.edgeLabels.get('edge:A->B#1')?.textContent).toContain('two')
+    expect(result.failed).toEqual([])
+  })
+
+  // amended per review ruling: with invisible edges never claimable, the
+  // visible member pairs correctly (per-pair: 1 visible vs 1 DOM) and only
+  // the invisible edge lands in failed
+  it('pairs the visible member and degrades only the invisible one', () => {
+    const { result, svg } = correlate('flowchart TD\n  A --> B\n  A ~~~ B\n')
+    // pele does not render the invisible edge: one DOM group, one visible edge
+    expect(svg.querySelectorAll('g.pele-edge')).toHaveLength(1)
+    const path = result.edges.get('edge:A->B#0')!
+    expect(path).toBeTruthy()
+    expect(path.closest('g.pele-edge')).toBe(svg.querySelector('g.pele-edge'))
+    expect(path.getAttribute('data-mw-entity')).toBe('edge:A->B#0')
+    // the hit overlay clone sits immediately before the visible path
+    expect(path.previousElementSibling?.getAttribute('data-mw-hit-overlay')).toBe('edge:A->B#0')
+    expect(result.failed).toEqual(['edge:A->B#1'])
+  })
+
+  // review finding 1 (critical): pele omits the invisible `a_b ~~~ c`, but
+  // its phantom bucket — L_a_b_c_0 right-parses as a_b->c — used to swallow
+  // the group rendered for the visible `a --> b_c` and tag that path with the
+  // INVISIBLE edge's entity. Invisible edges are never claimable now; the
+  // group survives to the leftover pass, which pairs it with the visible
+  // edge unambiguously.
+  it('never pairs a rendered path with an invisible edge (phantom bucket)', () => {
+    const { result, svg } = correlate('flowchart TD\n  a --> b_c\n  a_b ~~~ c\n')
+    expect(svg.querySelectorAll('g.pele-edge')).toHaveLength(1)
+    const path = result.edges.get('edge:a->b_c#0')!
+    expect(path).toBeTruthy()
+    expect(path.getAttribute('data-mw-entity')).toBe('edge:a->b_c#0')
+    expect(path.closest('g.pele-edge')?.getAttribute('data-id')).toBe('L_a_b_c_0')
+    expect(result.failed).toEqual(['edge:a_b->c#0'])
+  })
+
+  // review finding 2 (important): pele renders BOTH edges with the identical
+  // data-id L_a_b_c_0 (the subgraph-crossing edge hoists after the regular
+  // one, so DOM order is reversed too). Identical ids are indistinguishable —
+  // the guarded leftover degrades both rather than cross-pairing them.
+  // (node:a_b also degrades: core creates it from the edge ref, but pele
+  // renders a_b only as the cluster.)
+  it('degrades both edges when leftover candidates are ambiguous (identical data-ids)', () => {
+    const { result, svg } = correlate(
+      'flowchart TD\n  subgraph a_b [T]\n    c\n  end\n  a_b --> c\n  a --> b_c\n',
+    )
+    expect(result.edges.size).toBe(0)
+    expect(result.failed).toEqual(
+      expect.arrayContaining(['edge:a_b->c#0', 'edge:a->b_c#0', 'node:a_b']),
+    )
+    expect(result.failed).toHaveLength(3)
+    for (const path of svg.querySelectorAll('g.pele-edge path')) {
+      expect(path.hasAttribute('data-mw-entity')).toBe(false)
+    }
+  })
+
+  // review fix-round-2: pele RENDERS the invisible edge's label (design-doc
+  // constraint; verified by probe — the re-review assumed otherwise), as a
+  // second g.pele-edge-label with the IDENTICAL data-id L_a_b_c_0. Two
+  // prefix-compatible unclaimed candidates for the visible edge's label →
+  // ambiguous → the label degrades and is never bound to the invisible
+  // edge's entity.
+  it('degrades the visible edge label when the invisible twin renders an identical label id', () => {
+    const { result, svg } = correlate('flowchart TD\n  a -->|x| b_c\n  a_b ~~~|y| c\n')
+    // the visible edge's path pairs via the guarded leftover; the invisible
+    // edge itself degrades
+    const path = result.edges.get('edge:a->b_c#0')!
+    expect(path.closest('g.pele-edge')?.getAttribute('data-id')).toBe('L_a_b_c_0')
+    expect(path.getAttribute('data-mw-entity')).toBe('edge:a->b_c#0')
+    expect(result.failed).toEqual(['edge:a_b->c#0'])
+    // pele renders both label groups (x and y) — none of them is claimable
+    expect(svg.querySelectorAll('g.pele-edge-label')).toHaveLength(2)
+    expect(result.edgeLabels.size).toBe(0)
+    for (const label of svg.querySelectorAll('g.pele-edge-label')) {
+      expect(label.hasAttribute('data-mw-entity')).toBe(false)
+    }
+  })
+
+  // same class, the one-label shape: only the invisible edge is labeled, so
+  // pele renders exactly one label group — FOR the invisible edge. Invisible
+  // edges are view-only, so that label must stay untagged; before the
+  // label-pass skip it was zipped 1-vs-1 with the invisible edge's entity.
+  it('never lets an invisible edge claim its rendered label group', () => {
+    const { result, svg } = correlate('flowchart TD\n  a --> b_c\n  a_b ~~~|y| c\n')
+    expect(svg.querySelectorAll('g.pele-edge-label')).toHaveLength(1)
+    expect(result.edgeLabels.size).toBe(0)
+    expect(svg.querySelector('g.pele-edge-label')!.hasAttribute('data-mw-entity')).toBe(false)
+    // the visible edge's path still correlates
+    expect(result.edges.get('edge:a->b_c#0')!.getAttribute('data-mw-entity')).toBe('edge:a->b_c#0')
+    expect(result.failed).toEqual(['edge:a_b->c#0'])
+  })
+
+  // kept per controller ruling: the brief pinned node:a-b / edge:a-b->c#0
+  // correlating here, but core's node-id grammar excludes '-' — `a-b --> c`
+  // parses as an `unknown` statement, so the graph only ever holds a, b_c and
+  // edge:a->b_c#0, while pele renders DOM for the dropped line too. The
+  // fixture's point: that foreign DOM is never mis-paired AND never blocks a
+  // correct pairing — the visible edge claims its L_a_b_c_0 group through the
+  // guarded leftover (its unique prefix-compatible unclaimed candidate), and
+  // the foreign L_a-b_c_0 group just stays untagged.
+  it('leaves foreign DOM untagged when a source line core cannot parse', () => {
+    const { result, svg } = correlate('flowchart TD\n  a-b --> c\n  a --> b_c\n')
+    expect(result.nodes.get('node:a')).toBe(svg.querySelector('g.pele-node[data-id="a"]'))
+    expect(result.nodes.get('node:b_c')).toBe(svg.querySelector('g.pele-node[data-id="b_c"]'))
+    // nodes pele rendered that core dropped stay untagged (view-only)
+    expect(svg.querySelector('g.pele-node[data-id="a-b"]')!.hasAttribute('data-mw-entity')).toBe(false)
+    expect(svg.querySelector('g.pele-node[data-id="c"]')!.hasAttribute('data-mw-entity')).toBe(false)
+    // the visible edge pairs with its own group despite the foreign DOM
+    const path = result.edges.get('edge:a->b_c#0')!
+    expect(path).toBeTruthy()
+    expect(path.closest('g.pele-edge')?.getAttribute('data-id')).toBe('L_a_b_c_0')
+    expect(path.getAttribute('data-mw-entity')).toBe('edge:a->b_c#0')
+    // the foreign group (rendered for the core-unparseable line) stays untagged
+    expect(
+      svg.querySelector('g.pele-edge[data-id="L_a-b_c_0"] path')!.hasAttribute('data-mw-entity'),
+    ).toBe(false)
+    expect(result.failed).toEqual([])
+  })
+
+  // leftover-rule success: dots are in core's id grammar, so both lines parse.
+  // Pele's data-id for a --> b_c is L_a_b_c_0, which right-parses into the
+  // WRONG bucket (a_b -> c) in the pair pass — the leftover rule must
+  // reconcile it against exactly that DOM element.
+  it('pairs an edge via the leftover rule when its data-id parses into the wrong bucket', () => {
+    const { result, svg } = correlate('flowchart TD\n  a.b --> c\n  a --> b_c\n')
+    for (const [entityId, id] of [
+      ['node:a.b', 'a.b'],
+      ['node:c', 'c'],
+      ['node:a', 'a'],
+      ['node:b_c', 'b_c'],
+    ] as const) {
+      expect(result.nodes.get(entityId)).toBe(svg.querySelector(`g.pele-node[data-id="${id}"]`))
+    }
+    const dotEdge = result.edges.get('edge:a.b->c#0')!
+    expect(dotEdge).toBeTruthy()
+    expect(dotEdge.closest('g.pele-edge')?.getAttribute('data-id')).toMatch(/^L_a\.b_c_/)
+    const underscoreEdge = result.edges.get('edge:a->b_c#0')!
+    expect(underscoreEdge).toBeTruthy()
+    expect(underscoreEdge).not.toBe(dotEdge)
+    expect(underscoreEdge.closest('g.pele-edge')?.getAttribute('data-id')).toBe('L_a_b_c_0')
+    expect(underscoreEdge.getAttribute('data-mw-entity')).toBe('edge:a->b_c#0')
+    expect(result.failed).toEqual([])
+  })
+
+  it('correlates entity-coded graph ids against DOM-decoded data-ids', () => {
+    const host = document.createElement('div')
+    hosts.push(host)
+    // the attribute value is A"x after HTML parsing; the graph id arrives encoded
+    host.innerHTML = '<svg><g class="pele-node" data-id="A&quot;x"><rect/></g></svg>'
+    const svg = host.querySelector('svg')!
+    const node: FlowNode = {
+      entityId: 'node:x',
+      id: 'A&quot;x',
+      label: 'A"x',
+      shape: 'rect',
+      refs: [],
+      primary: null,
+      classes: [],
+      subgraph: null,
+    }
+    const graph = { nodes: [node], edges: [], subgraphs: [] } as unknown as FlowGraph
+    const result = correlatePeleFlowchart(svg, graph)
+    const el = result.nodes.get('node:x')!
+    expect(el).toBe(svg.querySelector('g.pele-node'))
+    expect(el.getAttribute('data-mw-entity')).toBe('node:x')
+    expect(result.failed).toEqual([])
+  })
+
+  it('decodeEntities decodes the named set and numeric codes, passing unknown through', () => {
+    expect(decodeEntities('A&quot;x')).toBe('A"x')
+    expect(decodeEntities('a&amp;b')).toBe('a&b')
+    expect(decodeEntities('&#65;')).toBe('A')
+    expect(decodeEntities('&#x41;')).toBe('A')
+    expect(decodeEntities('&nbsp;')).toBe('&nbsp;')
+  })
+
+  it('correlates multi-line edge labels', () => {
+    const { result, svg } = correlate('flowchart TD\n  A -->|"line1<br/>line2"| B\n')
+    const label = result.edgeLabels.get('edge:A->B#0')!
+    expect(label).toBe(svg.querySelector('g.pele-edge-label[data-id="L_A_B_0"]'))
+    expect(label.getAttribute('data-mw-entity')).toBe('edge:A->B#0')
+  })
+})
+
+/** drain microtasks and the macrotask queue so renders in flight land */
+async function flush() {
+  for (let i = 0; i < 5; i++) await new Promise((r) => setTimeout(r, 0))
+}
+
+describe('view dispatch', () => {
+  let container: HTMLElement
+  let views: MermaidCanvasView[]
+
+  beforeEach(() => {
+    container = document.createElement('div')
+    document.body.appendChild(container)
+    views = []
+  })
+
+  afterEach(() => {
+    for (const view of views) view.destroy()
+    container.remove()
+  })
+
+  it('dispatches flowcharts through the pele correlator', async () => {
+    const editor = new MermaidWysiwygEditor({
+      code: 'flowchart TD\n  A[Start] --> B{OK?}\n  B -->|yes| C[Ship]\n',
+    })
+    const view = new MermaidCanvasView({
+      editor,
+      container,
+      renderer: peleAdapter({ render: (src) => peleRender(src) }),
+      debounceMs: 0,
+    })
+    views.push(view)
+    await flush()
+    expect(container.querySelector('svg')).toBeTruthy()
+    expect(container.querySelector('[data-mw-entity="node:A"]')).toBeTruthy()
+  })
+
+  it('renders non-flowchart slots view-only under pele', async () => {
+    const editor = new MermaidWysiwygEditor({ code: 'pie title Pets\n  "cat": 40\n  "dog": 60\n' })
+    const view = new MermaidCanvasView({
+      editor,
+      container,
+      renderer: peleAdapter({ render: (src) => peleRender(src) }),
+      debounceMs: 0,
+    })
+    views.push(view)
+    await flush()
+    expect(container.querySelector('svg')).toBeTruthy()
+    expect(container.querySelectorAll('[data-mw-entity]')).toHaveLength(0)
+  })
+})

From f3a3c9f2285f8f033d7c56e277eb6e45c442bdee Mon Sep 17 00:00:00 2001
From: Casey Gollan <hello@caseyagollan.com>
Date: Sun, 1 Nov 2026 15:12:29 -0500
Subject: [PATCH 09/21] feat(dom): gate mermaid-only affordances under the pele
 renderer

---
 packages/dom/src/view.ts            |  48 +++---
 packages/dom/test/pele-view.test.ts | 218 ++++++++++++++++++++++++++++
 2 files changed, 246 insertions(+), 20 deletions(-)
 create mode 100644 packages/dom/test/pele-view.test.ts

diff --git a/packages/dom/src/view.ts b/packages/dom/src/view.ts
index 13f30da..0289354 100644
--- a/packages/dom/src/view.ts
+++ b/packages/dom/src/view.ts
@@ -847,7 +847,10 @@ export class MermaidCanvasView {
       if (this.svg) {
         if (this.panZoomEnabled) this.prepareSvgForPanZoom()
         else this.svg.style.maxWidth = '100%'
-        injectAnimationKeyframes(this.svg)
+        // pele's style allowlist silently drops `animation-*` declarations, so
+        // its edges can never run the vsmr-flow dash animation — injecting the
+        // keyframes would pretend otherwise. Mermaid honors them.
+        if (this.renderer.id !== 'pele') injectAnimationKeyframes(this.svg)
         this.bindSvg()
       }
       this.editor.setDiagnostics([])
@@ -1985,6 +1988,29 @@ export class MermaidCanvasView {
       ]
       const currentCurve = readFlowCurve(this.editor.code)
       const currentAnim = readEdgeAnimation(this.editor.code, edge.order)
+      // pele's style allowlist silently drops `animation-*` declarations, so
+      // an animated edge would render as a plain solid line while the source
+      // claims animation — a silent no-op the spec forbids. The picker is
+      // offered only where the renderer can honor it.
+      const animate: PopoverAction = {
+        icon: ICONS.circlePlay,
+        title: 'Animate edge',
+        panel: {
+          title: 'Animate edge',
+          sections: [
+            {
+              columns: 3,
+              items: anims.map((a) => ({
+                svg: a.svg,
+                title: a.t,
+                label: a.label,
+                selected: currentAnim === a.v,
+                onClick: () => this.editor.dispatch({ type: 'setEdgeAnimation', edgeId: id, value: a.v }),
+              })),
+            },
+          ],
+        },
+      }
       return [
         {
           icon: ICONS.arrowRight,
@@ -2037,25 +2063,7 @@ export class MermaidCanvasView {
             sections: [this.colorSection('Stroke', (value) => this.editor.dispatch({ type: 'setEdgeColor', edgeId: id, value }))],
           },
         },
-        {
-          icon: ICONS.circlePlay,
-          title: 'Animate edge',
-          panel: {
-            title: 'Animate edge',
-            sections: [
-              {
-                columns: 3,
-                items: anims.map((a) => ({
-                  svg: a.svg,
-                  title: a.t,
-                  label: a.label,
-                  selected: currentAnim === a.v,
-                  onClick: () => this.editor.dispatch({ type: 'setEdgeAnimation', edgeId: id, value: a.v }),
-                })),
-              },
-            ],
-          },
-        },
+        ...(this.renderer.id === 'pele' ? [] : [animate]),
         {
           icon: ICONS.spline,
           title: 'Edge curve (diagram-wide)',
diff --git a/packages/dom/test/pele-view.test.ts b/packages/dom/test/pele-view.test.ts
new file mode 100644
index 0000000..c7c0a4e
--- /dev/null
+++ b/packages/dom/test/pele-view.test.ts
@@ -0,0 +1,218 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { render as peleRender } from 'pele'
+import { MermaidWysiwygEditor } from '@visimer/core'
+import { peleAdapter } from '../src/renderer'
+import { MermaidCanvasView, type MermaidLike, type PopoverAction } from '../src'
+
+// jsdom has no CSS.escape (browsers do)
+if (typeof (globalThis as { CSS?: unknown }).CSS === 'undefined') {
+  ;(globalThis as { CSS?: { escape(s: string): string } }).CSS = {
+    escape: (s: string) => s.replace(/[^a-zA-Z0-9_-]/g, (c) => `\\${c}`),
+  }
+}
+
+// jsdom has no canvas: pele probes for one to measure text, and jsdom's
+// getContext raises a noisy "not implemented" error. Return null so pele falls
+// back to its built-in metrics table (the assertions here are structural, not
+// pixel-precise).
+HTMLCanvasElement.prototype.getContext = (() => null) as typeof HTMLCanvasElement.prototype.getContext
+
+const CODE = 'flowchart TD\n  A[Start] --> B\n'
+const UNLABELED = 'flowchart TD\n  A --> B\n'
+
+/**
+ * Fake mermaid for the mermaid side of the renderer comparisons: emits a
+ * minimal svg skeleton (the shape correlateFlowchart matches) so the view
+ * runs its real mermaid code path under jsdom.
+ */
+function makeFakeMermaid(): MermaidLike {
+  return {
+    initialize() {},
+    async render(_id: string, code: string) {
+      const nodes = [...code.matchAll(/(\w+)\[([^\]]*)\]/g)]
+      const svg = [
+        '<svg xmlns="http://www.w3.org/2000/svg">',
+        '<g class="nodes">',
+        ...nodes.map(
+          ([, id, label], i) =>
+            `<g class="node" id="flowchart-${id}-${i}"><g class="label"><foreignObject width="80" height="24">` +
+            `<div xmlns="http://www.w3.org/1999/xhtml"><span class="nodeLabel"><p>${label}</p></span></div>` +
+            `</foreignObject></g></g>`,
+        ),
+        '</g>',
+        '<g class="edgePaths"></g>',
+        '<g class="edgeLabels"></g>',
+        '</svg>',
+      ].join('')
+      return { svg }
+    },
+    async parse() {
+      return {}
+    },
+  }
+}
+
+/** drain microtasks and the macrotask queue so renders in flight land */
+async function flush() {
+  for (let i = 0; i < 5; i++) await new Promise((r) => setTimeout(r, 0))
+}
+
+/** the payload shape the view emits on its 'render' event */
+type RenderOutcome = { ok: boolean; error?: string }
+
+/** arm a listener for the view's next 'render' event, then trigger it */
+async function renderAfter(view: MermaidCanvasView, act: () => void): Promise<RenderOutcome> {
+  let settle!: (p: RenderOutcome) => void
+  const outcome = new Promise<RenderOutcome>((r) => (settle = r))
+  view.on('render', (p) => settle(p))
+  act()
+  return outcome
+}
+
+/** every title an edge popover can surface: action titles plus panel cell titles */
+function popoverTitles(actions: PopoverAction[]): string[] {
+  const titles = actions.map((a) => a.title)
+  for (const a of actions) {
+    if (a.panel?.items) titles.push(...a.panel.items.map((i) => i.title))
+    for (const s of a.panel?.sections ?? []) titles.push(...s.items.map((i) => i.title))
+  }
+  return titles
+}
+
+describe('pele view behaviors', () => {
+  let container: HTMLElement
+  let views: MermaidCanvasView[]
+
+  beforeEach(() => {
+    container = document.createElement('div')
+    document.body.appendChild(container)
+    views = []
+  })
+
+  afterEach(() => {
+    for (const view of views) view.destroy()
+    container.remove()
+  })
+
+  describe('keep-last-good on mid-keystroke syntax errors', () => {
+    it('keeps the previous svg and reports a pele diagnostic until the code recovers', async () => {
+      const editor = new MermaidWysiwygEditor({ code: CODE })
+      const view = new MermaidCanvasView({
+        editor,
+        container,
+        renderer: peleAdapter({ render: (src) => peleRender(src) }),
+        debounceMs: 0,
+      })
+      views.push(view)
+      await flush()
+      expect(container.querySelector('.mw-svg-host svg [data-mw-entity="node:A"]')).toBeTruthy()
+
+      // a half-typed label breaks the parse mid-keystroke
+      const broken = await renderAfter(view, () => editor.setCode('flowchart TD\n  A[unclosed', 'external'))
+      expect(broken.ok).toBe(false)
+      // the canvas still shows the last good render — nothing was swapped out
+      expect(container.querySelector('.mw-svg-host svg [data-mw-entity="node:A"]')).toBeTruthy()
+      expect(view.renderError).toBeTruthy()
+      expect(editor.diagnostics.some((d) => d.source === 'pele')).toBe(true)
+
+      // typing the label closed again restores a clean canvas
+      const good = await renderAfter(view, () => editor.setCode(CODE, 'external'))
+      expect(good.ok).toBe(true)
+      expect(view.renderError).toBeNull()
+      expect(editor.diagnostics).toHaveLength(0)
+    })
+  })
+
+  describe('overlay-editor fallback for label editing', () => {
+    it('edits pele labels through the overlay editor, not contenteditable SVG', async () => {
+      const editor = new MermaidWysiwygEditor({ code: CODE })
+      const view = new MermaidCanvasView({
+        editor,
+        container,
+        renderer: peleAdapter({ render: (src) => peleRender(src) }),
+        debounceMs: 0,
+      })
+      views.push(view)
+      await flush()
+
+      view.editEntityLabel('node:A')
+
+      // pele labels are SVG <text> — no HTML label inside the svg ever turns
+      // contenteditable (in-node editing is mermaid's foreignObject shape)
+      const svg = container.querySelector('svg')!
+      expect(svg.querySelector('[contenteditable]')).toBeNull()
+      // the overlay editor takes over instead, seeded with the current label
+      const overlay = container.querySelector<HTMLElement>('.mw-inplace-editor')
+      expect(overlay).not.toBeNull()
+      expect(overlay?.textContent).toBe('Start')
+
+      // commit follows the overlay's own contract: Enter
+      overlay!.textContent = 'Done'
+      overlay!.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }))
+      expect(editor.code).toContain('A[Done]')
+      await flush()
+      expect(container.querySelector('.mw-inplace-editor')).toBeNull()
+    })
+  })
+
+  describe('edge animation picker', () => {
+    it('is omitted under pele (pele silently drops animation-* styles)', async () => {
+      const editor = new MermaidWysiwygEditor({ code: UNLABELED })
+      const view = new MermaidCanvasView({
+        editor,
+        container,
+        renderer: peleAdapter({ render: (src) => peleRender(src) }),
+        debounceMs: 0,
+      })
+      views.push(view)
+      await flush()
+
+      const actions = (view as unknown as { actionsFor(id: string): PopoverAction[] }).actionsFor('edge:A->B#0')
+      const titles = popoverTitles(actions)
+      expect(titles).not.toContain('Animate edge')
+      expect(titles.some((t) => t.includes('Slow flow'))).toBe(false)
+    })
+
+    it('stays available under mermaid on the same code', async () => {
+      const editor = new MermaidWysiwygEditor({ code: UNLABELED })
+      const view = new MermaidCanvasView({ editor, container, mermaid: makeFakeMermaid(), debounceMs: 0 })
+      views.push(view)
+      await flush()
+
+      const actions = (view as unknown as { actionsFor(id: string): PopoverAction[] }).actionsFor('edge:A->B#0')
+      const titles = popoverTitles(actions)
+      expect(titles).toContain('Animate edge')
+      expect(titles).toContain('Slow flow')
+    })
+  })
+
+  describe('animation keyframes', () => {
+    it('are not injected under pele', async () => {
+      const editor = new MermaidWysiwygEditor({ code: CODE })
+      const view = new MermaidCanvasView({
+        editor,
+        container,
+        renderer: peleAdapter({ render: (src) => peleRender(src) }),
+        debounceMs: 0,
+      })
+      views.push(view)
+      await flush()
+
+      const styles = [...container.querySelector('svg')!.querySelectorAll('style')]
+      expect(styles.some((s) => s.hasAttribute('data-vsmr-flow'))).toBe(false)
+      expect(styles.some((s) => (s.textContent ?? '').includes('vsmr-flow'))).toBe(false)
+    })
+
+    it('are injected under mermaid on the same code', async () => {
+      const editor = new MermaidWysiwygEditor({ code: CODE })
+      const view = new MermaidCanvasView({ editor, container, mermaid: makeFakeMermaid(), debounceMs: 0 })
+      views.push(view)
+      await flush()
+
+      const styles = [...container.querySelector('svg')!.querySelectorAll('style')]
+      expect(styles.some((s) => s.hasAttribute('data-vsmr-flow'))).toBe(true)
+      expect(styles.some((s) => (s.textContent ?? '').includes('vsmr-flow'))).toBe(true)
+    })
+  })
+})

From ddb132c1260e32a8be59424886855240f3d167b7 Mon Sep 17 00:00:00 2001
From: Casey Gollan <hello@caseyagollan.com>
Date: Sun, 1 Nov 2026 15:34:26 -0500
Subject: [PATCH 10/21] feat(react): optional renderer prop

---
 packages/react/src/index.tsx | 28 +++++++++++++++++-----------
 1 file changed, 17 insertions(+), 11 deletions(-)

diff --git a/packages/react/src/index.tsx b/packages/react/src/index.tsx
index a375e0d..08e4ded 100644
--- a/packages/react/src/index.tsx
+++ b/packages/react/src/index.tsx
@@ -1,6 +1,6 @@
 import { useEffect, useRef, useState, useSyncExternalStore, type CSSProperties } from 'react'
 import { MermaidWysiwygEditor } from '@visimer/core'
-import { MermaidCanvasView, type MermaidLike, type Tool, type ViewHooks } from '@visimer/dom'
+import { MermaidCanvasView, type MermaidLike, type RendererAdapter, type Tool, type ViewHooks } from '@visimer/dom'
 
 export { MermaidWysiwygEditor } from '@visimer/core'
 export { MermaidCanvasView } from '@visimer/dom'
@@ -27,7 +27,9 @@ export interface MermaidWysiwygProps {
   code: string
   onCodeChange?: (code: string) => void
   /** your mermaid instance (`import mermaid from 'mermaid'`) */
-  mermaid: MermaidLike
+  mermaid?: MermaidLike
+  /** alternate renderer (e.g. `peleAdapter(pele)`); pass exactly one of `mermaid`/`renderer` */
+  renderer?: RendererAdapter
   /** passed to `mermaid.initialize` (theme, curves, securityLevel, …) */
   mermaidConfig?: Record<string, unknown>
   accentColor?: string
@@ -52,7 +54,7 @@ export interface MermaidWysiwygProps {
  * ```
  */
 export function MermaidWysiwyg(props: MermaidWysiwygProps) {
-  const { code, onCodeChange, mermaid, mermaidConfig, accentColor, readOnly, panZoom, tool, hooks, onSelectionChange, onReady, className, style } = props
+  const { code, onCodeChange, mermaid, renderer, mermaidConfig, accentColor, readOnly, panZoom, tool, hooks, onSelectionChange, onReady, className, style } = props
   const hostRef = useRef<HTMLDivElement>(null)
   const editorRef = useRef<MermaidWysiwygEditor | null>(null)
   const viewRef = useRef<MermaidCanvasView | null>(null)
@@ -68,6 +70,7 @@ export function MermaidWysiwyg(props: MermaidWysiwygProps) {
       editor,
       container: hostRef.current,
       mermaid,
+      renderer,
       mermaidConfig,
       accentColor,
       readOnly,
@@ -92,7 +95,7 @@ export function MermaidWysiwyg(props: MermaidWysiwygProps) {
     }
     // the view is created once; prop updates are applied by the effects below
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [mermaid])
+  }, [mermaid, renderer])
 
   useEffect(() => {
     const editor = editorRef.current
@@ -112,9 +115,9 @@ export function MermaidWysiwyg(props: MermaidWysiwygProps) {
   }, [accentColor])
 
   useEffect(() => {
-    if (mermaidConfig) viewRef.current?.setMermaidConfig(mermaidConfig)
+    if (!renderer && mermaidConfig) viewRef.current?.setMermaidConfig(mermaidConfig)
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [JSON.stringify(mermaidConfig)])
+  }, [JSON.stringify(mermaidConfig), renderer])
 
   useEffect(() => {
     viewRef.current?.setHooks(hooks ?? {})
@@ -126,7 +129,9 @@ export function MermaidWysiwyg(props: MermaidWysiwygProps) {
 export interface MermaidCanvasProps {
   /** an editor you own (e.g. from `useMermaidEditor`) */
   editor: MermaidWysiwygEditor
-  mermaid: MermaidLike
+  mermaid?: MermaidLike
+  /** alternate renderer (e.g. `peleAdapter(pele)`); pass exactly one of `mermaid`/`renderer` */
+  renderer?: RendererAdapter
   mermaidConfig?: Record<string, unknown>
   accentColor?: string
   readOnly?: boolean
@@ -140,7 +145,7 @@ export interface MermaidCanvasProps {
 
 /** Canvas-only binding for an editor instance you manage yourself. */
 export function MermaidCanvas(props: MermaidCanvasProps) {
-  const { editor, mermaid, mermaidConfig, accentColor, readOnly, panZoom, hooks, onReady, className, style } = props
+  const { editor, mermaid, renderer, mermaidConfig, accentColor, readOnly, panZoom, hooks, onReady, className, style } = props
   const hostRef = useRef<HTMLDivElement>(null)
   const viewRef = useRef<MermaidCanvasView | null>(null)
 
@@ -150,6 +155,7 @@ export function MermaidCanvas(props: MermaidCanvasProps) {
       editor,
       container: hostRef.current,
       mermaid,
+      renderer,
       mermaidConfig,
       accentColor,
       readOnly,
@@ -163,7 +169,7 @@ export function MermaidCanvas(props: MermaidCanvasProps) {
       viewRef.current = null
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [editor, mermaid])
+  }, [editor, mermaid, renderer])
 
   useEffect(() => {
     viewRef.current?.setHooks(hooks ?? {})
@@ -178,9 +184,9 @@ export function MermaidCanvas(props: MermaidCanvasProps) {
   }, [accentColor])
 
   useEffect(() => {
-    if (mermaidConfig) viewRef.current?.setMermaidConfig(mermaidConfig)
+    if (!renderer && mermaidConfig) viewRef.current?.setMermaidConfig(mermaidConfig)
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [JSON.stringify(mermaidConfig)])
+  }, [JSON.stringify(mermaidConfig), renderer])
 
   return <div ref={hostRef} className={className} style={{ minHeight: 240, ...style }} />
 }

From 8315985302c214a3e8fbf6e23a4a57582d0ab033 Mon Sep 17 00:00:00 2001
From: Casey Gollan <hello@caseyagollan.com>
Date: Sun, 1 Nov 2026 15:44:23 -0500
Subject: [PATCH 11/21] feat(playground): mermaid/pele renderer toggle

---
 apps/playground/package.json |  1 +
 apps/playground/src/App.tsx  | 38 +++++++++++++++++++++++++++++++-----
 apps/playground/src/app.css  | 18 +++++++++++++++++
 pnpm-lock.yaml               |  3 +++
 4 files changed, 55 insertions(+), 5 deletions(-)

diff --git a/apps/playground/package.json b/apps/playground/package.json
index 9f0304b..839f831 100644
--- a/apps/playground/package.json
+++ b/apps/playground/package.json
@@ -22,6 +22,7 @@
     "@visimer/react": "workspace:*",
     "mermaid": "^11.16.1",
     "monaco-editor": "^0.55.1",
+    "pele": "^1.13.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1"
   },
diff --git a/apps/playground/src/App.tsx b/apps/playground/src/App.tsx
index bb63f8b..f6fcda3 100644
--- a/apps/playground/src/App.tsx
+++ b/apps/playground/src/App.tsx
@@ -7,12 +7,22 @@ import {
   type ParticipantType,
   type ShapeId,
 } from '@visimer/core'
-import type { MermaidCanvasView, Tool } from '@visimer/dom'
+import * as pele from 'pele'
+import { peleAdapter, type MermaidCanvasView, type Tool } from '@visimer/dom'
 import { MermaidCanvas, useMermaidEditor } from '@visimer/react'
 import { MermaidCodeMirror } from '@visimer/codemirror'
 import { MonacoPane } from './MonacoPane'
 import { SAMPLES } from '../../js-playground/src/samples'
 
+/**
+ * Pele is stateless, so one adapter serves every canvas — built once at module
+ * scope instead of per-render, keeping the `renderer` prop identity stable (the
+ * canvas re-creates its view when props it was constructed with change).
+ */
+const peleRenderer = peleAdapter(pele, {
+  fontFamily: '"Inter Variable", "Inter", ui-sans-serif, system-ui, sans-serif',
+})
+
 let zenumlReady: Promise<boolean> | null = null
 function ensureZenuml(): Promise<boolean> {
   zenumlReady ??= import('@mermaid-js/mermaid-zenuml')
@@ -142,6 +152,13 @@ export default function App() {
   const [theme, setTheme] = useState('ink')
   const [readOnly, setReadOnly] = useState(false)
   const [zenumlOk, setZenumlOk] = useState(false)
+  const [renderer, setRenderer] = useState<'mermaid' | 'pele'>(() =>
+    localStorage.getItem('visimer.renderer') === 'pele' ? 'pele' : 'mermaid',
+  )
+
+  useEffect(() => {
+    localStorage.setItem('visimer.renderer', renderer)
+  }, [renderer])
 
   const sample = SAMPLES[sampleIndex]
   useEffect(() => {
@@ -160,6 +177,10 @@ export default function App() {
           <span className="sub">playground</span>
         </div>
         <div className="controls">
+          <div className="seg" role="group" aria-label="Renderer">
+            <button className={renderer === 'mermaid' ? 'on' : ''} onClick={() => setRenderer('mermaid')}>Mermaid</button>
+            <button className={renderer === 'pele' ? 'on' : ''} onClick={() => setRenderer('pele')}>Pele</button>
+          </div>
           <select value={theme} onChange={(e) => setTheme(e.target.value)} title="Mermaid theme">
             {['ink', 'dark', 'default', 'forest', 'neutral'].map((t) => (
               <option key={t} value={t}>{t}</option>
@@ -189,13 +210,13 @@ export default function App() {
             <span><i className="dot render" /> render</span>
           </div>
         </aside>
-        {!waitForZenuml && <Workspace key={sampleIndex} code={sample.code} theme={theme} readOnly={readOnly} />}
+        {!waitForZenuml && <Workspace key={sampleIndex} code={sample.code} theme={theme} readOnly={readOnly} renderer={renderer} />}
       </div>
     </div>
   )
 }
 
-function Workspace({ code, theme, readOnly }: { code: string; theme: string; readOnly: boolean }) {
+function Workspace({ code, theme, readOnly, renderer }: { code: string; theme: string; readOnly: boolean; renderer: 'mermaid' | 'pele' }) {
   const { editor } = useMermaidEditor(code)
   const [view, setView] = useState<MermaidCanvasView | null>(null)
   const [tool, setToolState] = useState<Tool>('select')
@@ -234,10 +255,17 @@ function Workspace({ code, theme, readOnly }: { code: string; theme: string; rea
           <button disabled={!editor.canUndo} onClick={() => editor.undo()}>Undo</button>
           <button disabled={!editor.canRedo} onClick={() => editor.redo()}>Redo</button>
         </div>
+        {renderer === 'pele' && (
+          <div className="notice" role="note">
+            <strong>Pele</strong> renders flowcharts only as far as editing goes: flowcharts are
+            editable, every other diagram type renders view-only, and zenuml is unsupported.
+          </div>
+        )}
         <MermaidCanvas
           editor={editor}
-          mermaid={mermaid}
-          mermaidConfig={{ securityLevel: 'loose', ...themeConfig(theme) }}
+          mermaid={renderer === 'mermaid' ? mermaid : undefined}
+          renderer={renderer === 'pele' ? peleRenderer : undefined}
+          mermaidConfig={renderer === 'mermaid' ? { securityLevel: 'loose', ...themeConfig(theme) } : undefined}
           accentColor="#69a3ff"
           readOnly={readOnly}
           onReady={setView}
diff --git a/apps/playground/src/app.css b/apps/playground/src/app.css
index a3d0007..56e6e62 100644
--- a/apps/playground/src/app.css
+++ b/apps/playground/src/app.css
@@ -83,6 +83,14 @@ body {
 .toolbar.disabled { opacity: 0.4; pointer-events: none; }
 .spacer { flex: 1; }
 
+/* renderer notice (shown under the toolbar when the pele renderer is active) */
+.notice {
+  flex: 0 0 auto; padding: 6px 12px; font-size: 12px; line-height: 1.45;
+  color: var(--dim); background: var(--panel);
+  border-bottom: 1px solid var(--border);
+}
+.notice strong { color: var(--fg); font-weight: 600; }
+
 button, select {
   height: 30px; padding: 0 12px; border-radius: 6px; font-size: 13px; font-family: var(--sans);
   background: var(--bg); color: var(--fg); border: 1px solid var(--border-strong);
@@ -110,6 +118,16 @@ select { appearance: none; padding-right: 26px; background-image: url("data:imag
   --mw-chrome-fg: var(--fg);
   --mw-chrome-hover: oklch(0.269 0 0);
   --mw-chrome-dim: var(--dim);
+  /* pele theme (INK-matched; read by pele's SVG stylesheet) */
+  --pele-bg: #000000;
+  --pele-fg: #ededed;
+  --pele-muted: #a1a1a1;
+  --pele-line: #8f8f8f;
+  --pele-surface: #111111;
+  --pele-surface-alt: #1a1a1a;
+  --pele-border: #3f3f3f;
+  --pele-accent: #3784ff;
+  --pele-font: "Inter Variable", "Inter", ui-sans-serif, system-ui, sans-serif;
 }
 .canvas:focus { outline: none; }
 
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index fababb4..20cf1f7 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -99,6 +99,9 @@ importers:
       monaco-editor:
         specifier: ^0.55.1
         version: 0.55.1
+      pele:
+        specifier: ^1.13.0
+        version: 1.13.0
       react:
         specifier: ^18.3.1
         version: 18.3.1

From e2f39dab239c8f60e1a8c609895a64397cece8a3 Mon Sep 17 00:00:00 2001
From: Casey Gollan <hello@caseyagollan.com>
Date: Sun, 1 Nov 2026 17:11:56 -0500
Subject: [PATCH 12/21] docs: design for pele full-coverage wave

---
 .../2026-11-01-pele-full-coverage-design.md   | 242 ++++++++++++++++++
 1 file changed, 242 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-11-01-pele-full-coverage-design.md

diff --git a/docs/superpowers/specs/2026-11-01-pele-full-coverage-design.md b/docs/superpowers/specs/2026-11-01-pele-full-coverage-design.md
new file mode 100644
index 0000000..71158f1
--- /dev/null
+++ b/docs/superpowers/specs/2026-11-01-pele-full-coverage-design.md
@@ -0,0 +1,242 @@
+# Pele full-coverage wave — design
+
+Date: 2026-11-01
+Status: awaiting approval
+Builds on: `docs/superpowers/specs/2026-11-01-pele-renderer-poc-design.md` (approved, implemented on branch `pele-renderer-poc`)
+
+## Intent
+
+The PoC proved the renderer seam and the correlator pattern on flowchart. This
+wave makes **every diagram type that is editable under Mermaid editable under
+Pele**: sequence, state, class, ER, pie, gantt, and the 15 line-item types.
+zenuml stays impossible (external Mermaid plugin; Pele supports no external
+diagram types — upstream limitation).
+
+## Why
+
+The user's goal is Obsidian Pele charts being WYSIWYG-editable with Visimer.
+The PoC's flowchart-only coverage was scope, not architecture — correlators
+are per-diagram-family work, and Mermaid's 22-type coverage represents the
+correlator work Visimer already paid against Mermaid's DOM. Pele's documented
+`data-id`/`pele-*` contract makes the remaining families tractable, and the
+flowchart correlator (`packages/dom/src/correlate.pele.ts`) established the
+pattern this wave applies: data-id first, count-checked zips,
+ambiguity-guarded leftovers, invisible/unrendered entities never claimable,
+degrade-never-mis-pair.
+
+## Goals
+
+1. Under `renderer.id === 'pele'`, all 22 editable types correlate and
+   support the full editing loop (select, rename where the type supports it,
+   popovers, delete, shared undo) — parity with the mermaid column of the
+   README's support table
+2. Each family's correlator ships with real-pele-render fixtures including
+   at least one adversarial case that would mis-pair under naive matching
+3. Existing suites stay green; the mermaid path stays untouched
+4. Playground notice updated: all types editable under Pele except zenuml
+5. TESTING.md updated: the pele correlator tests cover, per family, the seam
+   its map lists as uncovered
+
+## Non-goals
+
+- zenuml (impossible upstream)
+- Changes to core (entity ids, graphs, ops are the anchor — if a family's
+  core graph proves insufficient mid-wave, stop and rule; a core change is a
+  new decision, not an implementation detail)
+- New renderer adapters or API changes (the seam from the PoC is final)
+- Obsidian integration (separate future project)
+
+## Anti-goals
+
+- Mis-pairing: any ambiguous match degrades BOTH sides to view-only. The
+  flowchart Critical (invisible edge + phantom bucket) and the label-pass
+  sibling must not get new relatives.
+- Scraping pele internals beyond the documented CSS-targeting surface
+  (`pele-*` classes, `data-id`) — with one honest caveat below (sequence
+  index ids) and its mitigation.
+- Duplicating the gesture/popover/ops layers — they key off `data-mw-entity`
+  and entity-id prefixes and stay untouched.
+
+## Constraints (from the pele@1.13.0 audit; verify at implementation time)
+
+- **Sequence**: actors carry `data-id` = source participant id (stable);
+  lifelines also carry the participant's `data-id` (builder-verified);
+  messages/notes/activations are index-based (`i0, i1…` — an internal
+  convention, NOT in pele's CSS docs). **Activation rects and destroy
+  marks also carry the participant's `data-id`** — they are message-scoped
+  scenery core has no entity for, so the correlator must NOT sweep them
+  into the participant maps (see §2). Pele draws actor boxes top AND bottom
+  (twins), lifelines, activation bars, message arrows, notes, fragment
+  bands (fragments ARE parsed by pele). Core's `SequenceGraph`
+  (participants + events in declaration order) is the anchor: index zips
+  against declaration order are exact WHEN counts match.
+- **State**: `pele-state` groups with `data-id` (plus semantic variants
+  start/end/choice/fork/join); transitions rendered through the same layered
+  engine as flowchart edges (probe their id scheme — likely `L_`-family or
+  per-state; count-checked zips either way).
+- **Class**: `pele-class[data-id]` groups; relations also carry `data-id`
+  (builder-verified); members render as label rows inside the class box —
+  pele groups attributes first, then methods, with `pele-attribute`/
+  `pele-method` kind classes (builder-verified) — so the correlator mirrors
+  mermaid's attribute/method reorder, not raw declaration order.
+- **ER**: entities carry `data-id` **keyed by display label** (not source
+  id; core's alias syntax makes duplicate labels genuinely producible —
+  builder-verified — so the adversarial fixture is buildable); relationship
+  lines positional.
+- **Pie**: slices `data-id` keyed by label; legend rows text-keyed; core's
+  pie graph has slices with label/value. (Builder-verified.)
+- **Gantt**: tasks `pele-task[data-id]` (builder-verified present; probe
+  whether the id is task name or index), plus `pele-<done|active|crit|
+  milestone>` classes; sections positional. **Gridlines can share task
+  `data-id`s — the task sweep must class-filter to `pele-task`.**
+- **Line-item types** (journey, timeline, quadrant, kanban, mindmap,
+  treemap, packet, sankey, radar, gitgraph, xychart, architecture,
+  requirement, c4, block): mixed. First-class `data-id` where pele stamps it
+  (kanban cards/columns, git commits, sankey nodes/links, mindmap nodes,
+  treemap blocks); label/text-keyed elsewhere (journey tasks, timeline
+  periods, quadrant points). The mermaid generic correlator
+  (`correlateLineItems`) matches core's `item.matchText` against leaf text
+  elements — the pele port keeps that approach with pele's class names as
+  the leaf filter.
+- All families: `decodeEntities` comparison where data-ids may be
+  entity-encoded (helper exists in correlate.pele.ts); per-pair/per-group
+  count checks before any order zip; leftover passes guarded by
+  prefix/text-compatibility + unambiguity, exactly as the flowchart
+  correlator does.
+
+## Approaches
+
+One sensible way (the PoC settled it): per-family correlators in dom on the
+established pattern, selected by a pele mirror of `bindSvg`'s existing
+chain. Considered and rejected: a single generic text-only correlator for
+all types (loses edges/structure — most types need node+edge pairing, not
+just item text; would recreate mis-pairing risk). A separate
+`@visimer/pele` package (parked in the PoC's approaches section for exactly
+this moment): still premature — the correlator set belongs beside the
+mermaid ones until a third renderer exists.
+
+## The design
+
+### 1. Module layout
+
+- `packages/dom/src/correlate.pele.ts` — keep flowchart (exists); the wave
+  adds the other families either in the same module or sibling files
+  (`correlate.pele.sequence.ts`, etc.) — implementer's call by size, but
+  the `Correlation`/`SequenceCorrelation` contracts are fixed.
+- Sequence must return the existing `SequenceCorrelation` shape
+  (correlate.ts:464-474: `participants: Map<string, Element[]>` with
+  top+bottom twins, `lifelines`, `events`, `eventTexts`) so the view's
+  sequence machinery (lifeline UI, visibility retry, message drag) works
+  unchanged.
+
+### 2. Per-family correlators
+
+Each follows: probe pele's real output first (the flowchart wave's
+probes beat its docs twice); then data-id-first matching with
+`decodeEntities`; count-checked zips; guarded leftovers; degrade both
+sides on ambiguity. Per family:
+
+- **sequence**: participants = the actor box groups only (`g.pele-actor
+  [data-id]`, top+bottom twins both stored, as mermaid does) — activation
+  rects, destroy marks, and lifelines are **excluded from the participant
+  sweep by class filter** (they carry the same `data-id` but are
+  message-scoped scenery core has no entity for; sweeping them would make
+  clicking an activation bar select the participant and mis-anchor
+  popovers — they stay view-only); lifelines go in the `lifelines` slot
+  matched by their own `data-id` (fall back to x-geometry if the probe
+  shows gaps); events: zip core's declaration order against
+  `pele-message` document order, count-checked — never trust `i0/i1` ids
+  beyond using them as a consistency hint; notes positional/data-id per
+  the probe. No core change.
+- **state**: states by data-id (decode-entities); transitions by the
+  probed id scheme with per-pair count checks; choice/fork/join shapes
+  are plain states to core.
+- **class**: classes by data-id; member rows tagged positionally per class
+  (attribute/method order is core's declaration order), count-checked
+  against core's member list; member misses degrade the member, not the
+  class.
+- **ER**: entities by data-id == `decodeEntities(label)`; on duplicate
+  labels, count-check the label group and degrade the ambiguity;
+  attributes positional per entity (count-checked); relationship lines
+  order-zipped against core's erel list.
+- **pie**: slices by label-keyed data-id (decode-entities), count-checked
+  against core's slice list; legend rows text-matched to the same
+  entities.
+- **gantt**: tasks by probed id scheme + order zip with count-check;
+  sections/milestones follow core's task list.
+- **lineItems (15 types)**: port `correlateLineItems` — match
+  `item.matchText` against pele's leaf text elements (`.pele-label` and
+  per-type text classes), re-enable pointer-events on hit elements as the
+  mermaid version does; where a type stamps first-class `data-id`
+  (kanban cards, git commits, sankey nodes), prefer it with text as
+  fallback; ambiguous text matches (duplicate labels within a type)
+  count-check and degrade. Class-filter every data-id sweep (the gantt
+  gridline lesson generalizes: pele reuses ids across semantic layers).
+
+### 3. View wiring
+
+`bindSvg`'s pele branch becomes a full mirror of the mermaid chain: for
+each slot (sequence/state/classGraph/er/pie/gantt/lineItems) call the
+pele correlator for that slot; `null` only for types pele genuinely cannot
+render (zenuml — renders nothing; error badge already covers it). The
+sequence path reuses `seqCorrelation` + `armVisibilityRetry` (geometry
+retry applies to pele lifelines as well — keep it enabled under pele once
+sequence correlates).
+
+### 4. Tests
+
+Per family: `packages/dom/test/correlate-pele-<family>.test.ts` with the
+established harness (real pele render via the metrics fallback, real core
+parse, `correlate()` helper). Each family pins:
+
+1. **Render smoke**: the family's representative sample renders under pele
+   without `PeleError` — this is what makes the "all types editable"
+   notice honest, and catches any type pele genuinely cannot render
+   (beyond zenuml) as a loud stop-and-rule instead of an overclaim.
+2. Full correlation on a representative sample.
+3. At least one adversarial case that would mis-pair under naive matching
+   (sequence: message insertion shifts index ids — assert order zip, not
+   id trust; ER: duplicate entity labels via alias syntax; class:
+   member-count mismatch; gantt: gridline/task data-id sharing; lineItems:
+   duplicate item text within one type) and degrade-not-mis-pair outcomes.
+4. **Style-op spot-check where the family has a style-picking action**: emit
+   one representative style op, re-render, assert the change is visible in
+   the SVG (the flowchart wave proved colors/shapes/arrows/thickness
+   round-trip; anything that does NOT round-trip is a stop-and-rule — gate
+   it like the animation picker, never ship a silent no-op).
+
+Sequence also pins the twins + lifeline matching and that activation bars
+stay untagged (clicking them selects nothing). The acceptance bar per
+family is correlation parity + the render smoke + the style spot-check —
+NOT a per-action audit of all 22 types; surprises become stop-and-rule
+moments, exactly as the flowchart wave handled the animation picker.
+
+### 5. Playground + docs
+
+- Notice copy: "All diagram types are editable under Pele; zenuml is not
+  supported."
+- TESTING.md: add the pele correlator rung to the seam map.
+- README: one line under Architecture that the canvas is
+  renderer-swappable (Mermaid or Pele).
+
+### 6. Sequencing for the plan (order is risk-then-volume)
+
+1. state → class → ER (compound-layout families closest to the flowchart
+   pattern; probes first)
+2. pie + gantt (simple, high fixture value)
+3. lineItems (15 types, repetitive; one correlator + per-type fixtures)
+4. sequence (most machinery: twins, lifelines, fragments; last, with all
+   lessons applied)
+5. view dispatch completion + playground notice + TESTING.md/README
+
+Each family = one implementer + one reviewer seat; one commit per family
+plus a final wiring/docs commit.
+
+## What's left to the builder
+
+- Per-family probe results (id schemes for state transitions, gantt tasks,
+  sequence notes/activations) — probes before code, fixtures pin what the
+  probe shows
+- Sibling-file vs single-module layout for the new correlators
+- Lifeline matching (geometry vs data-id) per the probe
+- Per-type lineItem selector lists

From b2fad4c52f9aeda38c0d4b5d17da75344169e627 Mon Sep 17 00:00:00 2001
From: Casey Gollan <hello@caseyagollan.com>
Date: Sun, 1 Nov 2026 17:15:50 -0500
Subject: [PATCH 13/21] docs: implementation plan for pele full-coverage wave

---
 .../plans/2026-11-01-pele-full-coverage.md    | 164 ++++++++++++++++++
 1 file changed, 164 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-11-01-pele-full-coverage.md

diff --git a/docs/superpowers/plans/2026-11-01-pele-full-coverage.md b/docs/superpowers/plans/2026-11-01-pele-full-coverage.md
new file mode 100644
index 0000000..4d8ada3
--- /dev/null
+++ b/docs/superpowers/plans/2026-11-01-pele-full-coverage.md
@@ -0,0 +1,164 @@
+# Pele Full-Coverage Wave Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Every diagram type editable under Mermaid is editable under Pele — per-family correlators on the established pattern, wired into the view, with per-family fixtures.
+
+**Architecture:** Seven correlator additions to `@visimer/dom` keyed off Pele's `data-id`/`pele-*` contract, each returning the existing `Correlation`/`SequenceCorrelation` shapes so gestures/popovers/ops work untouched. Core anchors every zip; ids are hints, order+count is truth, ambiguity degrades both sides. Spec: `docs/superpowers/specs/2026-11-01-pele-full-coverage-design.md`.
+
+**Tech Stack:** TypeScript (strict, ESM), vitest + jsdom, real pele renders via metrics fallback, pnpm workspace.
+
+**Model plan (user-directed cost optimization):** probing was done at plan time (facts pinned below), so Tasks 1–6 and 8 are transcription+testing → **implementers on `inference-coop/greenpt/glm-5.3-flash`** (cheap tier), reviewed by `inference-coop/greenpt/deepseek-v4.1-flash` (mid). Task 7 (sequence) carries real judgment → implementer AND reviewer on `inference-coop/greenpt/glm-5.3` (capable). Scoped re-reviews of small fix diffs: flash allowed; escalation on BLOCKED or two rounds of Important findings: one tier up. Final whole-branch review: glm-5.3.
+
+## Global Constraints
+
+- "Never mis-correlate: when a match is ambiguous, the entity degrades to view-only (`failed`) instead of pairing a wrong element."
+- The mermaid path stays untouched; existing suites stay green, unmodified.
+- Core changes are forbidden; a family whose core graph proves insufficient is a stop-and-rule, not an implementation detail.
+- Scenery exclusions (spec rulings): `pele-state-start/-end` elements, sequence activation rects / destroy marks / fragment frames, and gantt gridlines are NEVER tagged — filter by class, never sweep by `data-id` alone.
+- Index-style ids (`i0`, `edge0`, `task1`, `id_…_1`) are hints only — never trust them beyond consistency checks; order zips require equal counts on both sides.
+- Entity-id formats from core: `state:`/`trans:`, `class:`/`rel:`, `entity:`/`erel:`, `slice:`, `task:<lineIndex>`, `item:`, `participant:`/`event:<lineIndex>`.
+- Tests: `// @vitest-environment jsdom` pragma + `CSS.escape` polyfill + `HTMLCanvasElement.prototype.getContext = () => null` stub (pattern: packages/dom/test/renderer.test.ts). Harness helper: the `correlate(code)` pattern from packages/dom/test/correlate-pele.test.ts.
+- Commands: `pnpm --filter @visimer/dom exec vitest run test/<file>`; gates `pnpm --filter @visimer/dom test`, per-package `typecheck`; pnpm workaround when `pnpm` fails with ENOEXEC: `node /Users/cag/Library/pnpm/.tools/pnpm/12.8.1/node_modules/pnpm/bin/pnpm.mjs <args>`.
+- Commits: one per task, `feat(dom): pele <family> correlator`, on branch `pele-renderer-poc`.
+
+## Probe facts (verified 2026-11-01 against pele@1.13.0 by rendering real samples; every task cites its section)
+
+- **state**: states `g.pele-node.pele-state[data-id=<id>]`; pseudo-states render as `pele-state-start[data-id=root_start|<comp>_start]` / `pele-state-end[data-id=root_end|<comp>_end]`; transitions `g.pele-edge.pele-transition[data-id=edge<N>]` (+ `g.pele-edge-label` same id); composites `g.pele-cluster.pele-state-composite[data-id=<id>]` with `.pele-cluster-label`.
+- **class**: classes `g.pele-node.pele-class[data-id=<id>]`; members `text.pele-member.pele-attribute` / `.pele-method` (no data-id; attributes grouped before methods); relations `g.pele-edge.pele-relation[data-id=id_<Src>_<Tgt>_<N>]` (+ labels same id); cardinalities `text.pele-cardinality` (positional).
+- **ER**: entities `g.pele-node.pele-entity[data-id=<label>]` (label-keyed!); relationships `g.pele-edge.pele-er-identifying[data-id=id_entity-<label>-<idx>_entity-<label>-<idx>_<n>]`; attributes `text.pele-er-name` / `.pele-er-type` rows (no data-id; positional per entity) inside `g.pele-er-attributes`.
+- **pie**: slices `path.pele-slice[data-id=<label>]`; legend `g.pele-legend-item[data-id=<label>]` — both label-keyed, no order dependence.
+- **gantt**: tasks `g.pele-task[data-id=<sourceId|taskN>]` (core has no ids → order-zip); milestone variant class `pele-milestone`; sections `rect.pele-section.pele-section-<N>` + `text.pele-section-label[data-id=<name>]`; grid is `g.pele-grid` (separate group, still class-filter to `g.pele-task`).
+- **line-items**: kanban columns `g.pele-cluster.pele-column[data-id]` / cards `g.pele-node.pele-card[data-id]`; git commits `g.pele-commit.pele-commit-<kind>[data-id=<commitId|generated>]`, branches `g.pele-branch[data-id]`; timeline periods `g.pele-node.pele-period[data-id=<text>]` (events have NO data-id → text fallback); journey tasks `g.pele-node.pele-task[data-id=<taskText>]`, sections `g.pele-cluster.pele-section[data-id]`; sankey nodes `rect.pele-sankey-node[data-id]` / links `path.pele-sankey-link[data-id=<A>-><B>]` / labels `g.pele-label[data-id]`.
+- **sequence**: actors `g.pele-node.pele-actor.pele-actor-<kind>[data-id=<participantId>]` (bottom twins carry `pele-actor-footer`); lifelines `path.pele-lifeline[data-id=<participantId>]`; messages `g.pele-edge.pele-message[data-id=i<N>]` + `g.pele-edge-label[data-id=i<N>]`; notes `g.pele-note[data-id=i<N>]`; activations `rect.pele-activation[data-id=<participantId>]` (scenery); fragments `g.pele-frame.pele-frame-<kind>` (no data-id; scenery). **The `i<N>` counter is global across messages AND notes and non-contiguous per kind** (probe: messages i0, i2, i6 with note i4 between).
+
+## Review Focus
+
+1. **Index-id trust** — sequence/state/class/gantt index-style ids shift under insertion (sequence probe: i0,i2,i6). Every order zip is count-checked and ids are hints only. → Tasks 1, 2, 3, 5, 7 fixtures each pin a shifted-index or insertion case.
+2. **Scenery mis-tagging** — start/end states, activations, destroys, frames, gridlines carry ids of real entities; a bare `[data-id]` sweep tags them. → Tasks 1, 5, 7 fixtures assert scenery stays untagged.
+3. **Label-keyed ambiguity** — duplicate labels (ER entities via alias syntax, pie slices, kanban cards, timeline periods) collide on data-id. → Tasks 3, 4, 6 adversarial fixtures: duplicates degrade both sides, never mis-pair.
+4. **Positional member/attribute mismatch** — class members and ER attributes have no ids; a count mismatch must degrade the rows, not zip partials. → Tasks 2, 3 count-mismatch fixtures.
+5. **Silent style no-op** — pele's style allowlist can drop a family's style op. → Each family's spot-check step emits one style op and asserts visible change or escalates as stop-and-rule.
+
+---
+
+### Task 1: State correlator
+
+**Model tier:** implementer flash, reviewer mid. **Files:** Create `packages/dom/src/correlate.pele.state.ts`; Modify `packages/dom/src/view.ts` (bindSvg pele branch: state slot), `packages/dom/src/index.ts` (export); Test `packages/dom/test/correlate-pele-state.test.ts`.
+
+**Interfaces:**
+- Consumes: `Correlation` (correlate.ts:12-18), `addEdgeHitOverlay`, `decodeEntities` (export from correlate.pele.ts if not already exported), `StateGraph` (`@visimer/core`: `states: {entityId 'state:<id>', id, isComposite}[]`, `transitions` in document order).
+- Produces: `correlatePeleState(svg: SVGSVGElement, graph: StateGraph): Correlation`, wired under pele for the state slot.
+
+- [ ] **Step 1: Failing tests** — harness per Global Constraints; sample: the probe's state sample (composite + labeled transitions). Assert: every `state:` entity correlates to `g.pele-state[data-id]` (decode-entities compare); composite state ALSO tags `g.pele-cluster.pele-state-composite[data-id=Processing]`; transitions zip document-order count-checked (`trans:` ids, hit overlays added, inner `<path>` stored); transition labels correlate; `[*]`-rendered elements (`pele-state-start/-end`) carry NO `data-mw-entity`; adversarial: a transition whose source sample makes counts mismatch degrades that transition (never mis-zips).
+- [ ] **Step 2: Run to verify failure** — `pnpm --filter @visimer/dom exec vitest run test/correlate-pele-state.test.ts` → FAIL (module missing).
+- [ ] **Step 3: Implement** — states: data-id match (decodeEntities), excluding elements with class `pele-state-start`/`pele-state-end`; leftover equal-count zip else degrade. Composites: cluster data-id match, tag + `nodes.set`, cluster-label tagged too. Transitions: `g.pele-edge.pele-transition` document order vs core transitions, count-check, store inner `<path>` + `addEdgeHitOverlay`; labels via `g.pele-edge-label[data-id]` matched to the transition's edge element (same data-id), count-checked. Wire bindSvg: under pele, state slot → `correlatePeleState`.
+- [ ] **Step 4: Verify pass** — focused file, then `pnpm --filter @visimer/dom test` + dom typecheck.
+- [ ] **Step 5: Style spot-check** — emit one state style op through a view-level render (e.g. a `classDef`/`style` on a state) and assert the re-rendered SVG changes visibly; if dropped by pele's allowlist → STOP and report (gate it, don't ship silent no-op).
+- [ ] **Step 6: Commit** — `git commit -m "feat(dom): pele state correlator"` (files: new module, view.ts, index.ts, test).
+
+### Task 2: Class correlator
+
+**Model tier:** implementer flash, reviewer mid. **Files:** Create `packages/dom/src/correlate.pele.class.ts`; Modify view.ts (classGraph slot), index.ts; Test `packages/dom/test/correlate-pele-class.test.ts`.
+
+**Interfaces:**
+- Consumes: `Correlation`, `addEdgeHitOverlay`, `decodeEntities`, `ClassGraph` (`classes: {entityId 'class:<id>'}[]`, members, `relations: {entityId 'rel:…'}[]` — read core/src/class/graph.ts for member/relations shape and mirror what mermaid's correlateClass tags).
+- Produces: `correlatePeleClass(svg, graph): Correlation` wired for the classGraph slot.
+
+- [ ] **Step 1: Failing tests** — probe's class sample. Assert: classes correlate to `g.pele-class[data-id]`; member rows tagged mirroring mermaid's supplementary tags (`data-mw-member-class` on the row, `data-mw-member-line` on the divider — read correlate.ts:252-268 for the exact mermaid contract and mirror it, mapping attributes to `text.pele-member.pele-attribute` then methods to `.pele-method`, count-checked per class); relations correlate to `g.pele-edge.pele-relation` inner path + hit overlay, matched by `id_<Src>_<Tgt>_` prefix + ambiguity guard (same guard as flowchart leftovers); adversarial: member-count mismatch degrades the class's member rows, not the class; duplicate `L_`-style relation prefix collisions degrade.
+- [ ] **Step 2: Run to verify failure** → FAIL.
+- [ ] **Step 3: Implement** — per Step 1's contract; wire bindSvg classGraph slot under pele.
+- [ ] **Step 4: Verify pass** — focused + full dom suite + typecheck.
+- [ ] **Step 5: Style spot-check** — one class member style op round-trips visibly (or stop-and-rule).
+- [ ] **Step 6: Commit** — `feat(dom): pele class correlator`.
+
+### Task 3: ER correlator
+
+**Model tier:** implementer flash, reviewer mid. **Files:** Create `packages/dom/src/correlate.pele.er.ts`; Modify view.ts (er slot), index.ts; Test `packages/dom/test/correlate-pele-er.test.ts`.
+
+**Interfaces:**
+- Consumes: `Correlation`, guards as above, `ErGraph` (`entity:` entities keyed by name; `erel:` relationships; attributes — mirror mermaid's correlateEr contract incl. `data-mw-attr-entity`/`data-mw-attr-line` tags, correlate.ts:293-367).
+- Produces: `correlatePeleEr(svg, graph): Correlation` wired for the er slot.
+
+- [ ] **Step 1: Failing tests** — probe's ER sample. Assert: entities correlate to `g.pele-entity[data-id=decodeEntities(name)]`; label-KEYED (not id) — adversarial: duplicate entity names via alias syntax degrade the colliding entities, never mis-pair; attributes positional per entity count-checked, tagged with mermaid's attr tags; relationships match `g.pele-edge.pele-er-identifying` by document-order count-check against core's `erel` list (the `id_entity-…` scheme is a hint only) + labels same; stripes/dividers excluded.
+- [ ] **Step 2: Run to verify failure** → FAIL.
+- [ ] **Step 3: Implement** — per Step 1; wire the er slot.
+- [ ] **Step 4: Verify pass** — focused + gates.
+- [ ] **Step 5: Style spot-check** — one entity/attribute style op round-trips visibly (or stop-and-rule).
+- [ ] **Step 6: Commit** — `feat(dom): pele er correlator`.
+
+### Task 4: Pie correlator
+
+**Model tier:** implementer flash, reviewer mid. **Files:** Create `packages/dom/src/correlate.pele.pie.ts`; Modify view.ts (pie slot), index.ts; Test `packages/dom/test/correlate-pele-pie.test.ts`.
+
+**Interfaces:**
+- Consumes: `Correlation`, `decodeEntities`, `PieGraph` (`slice:` entities with label/value).
+- Produces: `correlatePelePie(svg, graph): Correlation` wired for the pie slot.
+
+- [ ] **Step 1: Failing tests** — probe's pie sample. Assert: every `slice:` correlates to `path.pele-slice[data-id=decodeEntities(label)]`; legend `g.pele-legend-item[data-id]` tagged with the same entity id; adversarial: duplicate slice labels degrade both colliding slices + legend items; all-correlated leaves `failed` empty.
+- [ ] **Step 2: Run to verify failure** → FAIL.
+- [ ] **Step 3: Implement** — data-id matching only (no order dependence); wire the pie slot.
+- [ ] **Step 4: Verify pass** — focused + gates.
+- [ ] **Step 5: Style spot-check** — one slice color op round-trips visibly (pele colors via `--pele-series-N` CSS vars — assert the series class/index changes or the op's source diff lands; if pele ignores per-slice styling → stop-and-rule before gating).
+- [ ] **Step 6: Commit** — `feat(dom): pele pie correlator`.
+
+### Task 5: Gantt correlator
+
+**Model tier:** implementer flash, reviewer mid. **Files:** Create `packages/dom/src/correlate.pele.gantt.ts`; Modify view.ts (gantt slot), index.ts; Test `packages/dom/test/correlate-pele-gantt.test.ts`.
+
+**Interfaces:**
+- Consumes: `Correlation`, `GanttGraph` (`task:<lineIndex>` entities in document order).
+- Produces: `correlatePeleGantt(svg, graph): Correlation` wired for the gantt slot.
+
+- [ ] **Step 1: Failing tests** — probe's gantt sample (sections + milestone). Assert: tasks order-zip `g.pele-task` (document order vs core tasks, count-checked — core has no source ids; `data-id` values are NOT match keys); milestone variant correlated same as any task; gridlines (`g.pele-grid` children) and section rects carry NO `data-mw-entity`; adversarial: task-count mismatch degrades (e.g. a task pele drops) rather than zips.
+- [ ] **Step 2: Run to verify failure** → FAIL.
+- [ ] **Step 3: Implement** — order zip only; class-filter the sweep to `g.pele-task`; wire the slot.
+- [ ] **Step 4: Verify pass** — focused + gates.
+- [ ] **Step 5: Style spot-check** — one task status op (`done`/`active`/`crit`) round-trips visibly (class change on `pele-task`).
+- [ ] **Step 6: Commit** — `feat(dom): pele gantt correlator`.
+
+### Task 6: Line-items correlator (15 types)
+
+**Model tier:** implementer flash, reviewer mid. **Files:** Create `packages/dom/src/correlate.pele.lineitems.ts`; Modify view.ts (lineItems slot), index.ts; Test `packages/dom/test/correlate-pele-lineitems.test.ts`.
+
+**Interfaces:**
+- Consumes: `Correlation`, `decodeEntities`, `LineItemsGraph` (`item:` entities with `matchText`), the probe facts above.
+- Produces: `correlatePeleLineItems(svg, graph): Correlation` wired for the lineItems slot.
+
+- [ ] **Step 1: Failing tests** — one fixture per type (15), using the playground sample strings from `apps/js-playground/src/samples` as sources. Match strategy per the probe: prefer first-class `data-id` (kanban cards/columns, git commits, sankey nodes/links, journey tasks, timeline periods) with `decodeEntities` compare; text fallback (`item.matchText` vs leaf `text/tspan` content, `.pele-label` and per-type text classes) for data-id-less elements (timeline events); re-enable `pointer-events: auto` on hit elements exactly as mermaid's correlateLineItems does (correlate.ts:452-457). Adversarial per the Review Focus: duplicate item text within one type (e.g. two kanban cards named the same) degrades both, never mis-pairs.
+- [ ] **Step 2: Run to verify failure** → FAIL.
+- [ ] **Step 3: Implement** — for types not probed at plan time (mindmap, treemap, packet, radar, xychart, architecture, requirement, c4, block, quadrant), run the probe first: the probe script is preserved at `/private/var/folders/b2/t9b43n89205878w6fwy1qhx40000gn/T/opencode/pele-probe/probe.mjs` (copy it into the workspace; render each sample, read its class/data-id surface) and pin what it shows in the fixtures. No guessing selectors.
+- [ ] **Step 4: Verify pass** — focused (15+ fixtures) + gates.
+- [ ] **Step 5: Style spot-check** — one kanban-card style op round-trips visibly (or stop-and-rule).
+- [ ] **Step 6: Commit** — `feat(dom): pele line-items correlator`.
+
+### Task 7: Sequence correlator
+
+**Model tier:** implementer AND reviewer on the capable model. **Files:** Create `packages/dom/src/correlate.pele.sequence.ts`; Modify `packages/dom/src/view.ts` (seqCorrelation under pele + `armVisibilityRetry` re-enabled), index.ts; Test `packages/dom/test/correlate-pele-sequence.test.ts`.
+
+**Interfaces:**
+- Consumes: `SequenceCorrelation` (correlate.ts:464-474 — read it first: `participants: Map<string, Element[]>`, lifelines, events, eventTexts), `SequenceGraph` (`participant:` + `event:<lineIndex>` message/note events in document order), `addEdgeHitOverlay`, `decodeEntities`.
+- Produces: `correlatePeleSequence(svg, graph): SequenceCorrelation` wired so the view's sequence machinery (lifeline UI, message drag, visibility retry) works under pele.
+
+- [ ] **Step 1: Failing tests** — probe's sequence sample (participants incl. `actor` kind, messages, activation, note, loop frame). Assert:
+  - participants: BOTH actor twins (`pele-actor` with and without `pele-actor-footer`) stored in `participants` per `data-id`; `participant:` ids tagged on both.
+  - lifelines: `path.pele-lifeline[data-id]` fills the lifelines slot per participant.
+  - events: `g.pele-edge.pele-message` and `g.pele-note` merged in DOCUMENT ORDER, zipped count-checked against core's events array (`event:` ids); the `i<N>` ids are NOT match keys (probe: i0, i2, i6 non-contiguous); message labels via `g.pele-edge-label` matched to their message group's data-id when equal-counted, else document-order zip.
+  - scenery: `rect.pele-activation`, destroy marks, `g.pele-frame` carry NO `data-mw-entity` (clicking them selects nothing).
+  - adversarial: inserting a note mid-sequence shifts message `i<N>` ids — assert the zip still pairs by order (the fixture pins exactly this).
+  - view-level: a `MermaidCanvasView` over `peleAdapter` renders the sample, entities tagged, and `armVisibilityRetry` is armed for sequence under pele (hidden-mount case).
+- [ ] **Step 2: Run to verify failure** → FAIL.
+- [ ] **Step 3: Implement** — per Step 1; wire `seqCorrelation` under pele and pass the sequence graph to `armVisibilityRetry` (replacing the current `null`).
+- [ ] **Step 4: Verify pass** — focused + full gates.
+- [ ] **Step 5: Style spot-check** — one note/message style op round-trips visibly (or stop-and-rule).
+- [ ] **Step 6: Commit** — `feat(dom): pele sequence correlator`.
+
+### Task 8: Notice, TESTING.md, README
+
+**Model tier:** implementer flash, reviewer mid. **Files:** Modify `apps/playground/src/App.tsx` (notice copy), `TESTING.md`, `README.md`.
+
+- [ ] **Step 1: Update notice copy** — under pele: "All diagram types are editable under Pele; zenuml is not supported." (replaces the flowchart-only notice).
+- [ ] **Step 2: TESTING.md** — add the pele correlator rung to the SVG-correlation seam row (per-family real-render fixture suites; still uncovered: mermaid-side correlation).
+- [ ] **Step 3: README** — one line under Architecture: the canvas is renderer-swappable (Mermaid or Pele); badge note optional.
+- [ ] **Step 4: Gates** — `pnpm test`, per-package typecheck, playground build.
+- [ ] **Step 5: Commit** — `docs+feat(playground): pele full-coverage notice and docs` (or split if cleaner).

From 1718da12b6813178e9a7117eec739cdbe0ed1470 Mon Sep 17 00:00:00 2001
From: Casey Gollan <hello@caseyagollan.com>
Date: Sun, 1 Nov 2026 17:21:00 -0500
Subject: [PATCH 14/21] feat(dom): pele state correlator

---
 packages/dom/src/correlate.pele.state.ts      | 149 +++++++++
 packages/dom/src/index.ts                     |   1 +
 packages/dom/src/view.ts                      |  13 +-
 .../dom/test/correlate-pele-state.test.ts     | 306 ++++++++++++++++++
 4 files changed, 465 insertions(+), 4 deletions(-)
 create mode 100644 packages/dom/src/correlate.pele.state.ts
 create mode 100644 packages/dom/test/correlate-pele-state.test.ts

diff --git a/packages/dom/src/correlate.pele.state.ts b/packages/dom/src/correlate.pele.state.ts
new file mode 100644
index 0000000..2a1ff89
--- /dev/null
+++ b/packages/dom/src/correlate.pele.state.ts
@@ -0,0 +1,149 @@
+import type { StateGraph } from '@visimer/core'
+import { addEdgeHitOverlay, type Correlation } from './correlate'
+import { decodeEntities } from './correlate.pele'
+
+/**
+ * Correlate pele's rendered state-diagram SVG with the semantic graph.
+ * Strategy: pele's `data-id` attributes first (states, the composite cluster,
+ * and transition labels via their edge group's data-id), then count-checked
+ * zips in document order for transitions. `[*]` pseudo-states render as
+ * `pele-state-start`/`pele-state-end` scenery that core excludes from its
+ * graph — those elements are never tagged. Any ambiguous or count-mismatched
+ * match degrades to view-only instead of pairing a wrong element.
+ */
+export function correlatePeleState(svg: SVGSVGElement, graph: StateGraph): Correlation {
+  const nodes = new Map<string, SVGGElement>()
+  const edges = new Map<string, SVGElement>()
+  const edgeLabels = new Map<string, SVGGElement>()
+  const failed: string[] = []
+
+  const dataId = (el: Element) => el.getAttribute('data-id')
+  // pele entity-encodes data-id values (`&quot;`, `&#65;`, ...) — compare the
+  // decoded graph id against the DOM-decoded attribute (and the raw one)
+  const matchesId = (el: Element, id: string) => {
+    const dom = dataId(el)
+    return dom === id || dom === decodeEntities(id)
+  }
+
+  // --- states: pele stamps the state's id in data-id on g.pele-node.pele-state.
+  // The `[*]` pseudo-states render with the pele-state-start/-end classes (no
+  // plain `pele-state` class) — filtered out here so scenery can never be
+  // claimed, not even by the leftover zip.
+  const stateEls = [...svg.querySelectorAll<SVGGElement>('g.pele-node.pele-state')].filter(
+    (el) => !el.classList.contains('pele-state-start') && !el.classList.contains('pele-state-end'),
+  )
+  const claimed = new Set<Element>()
+  /** state entityId → the pele-state group pele rendered for it, if any */
+  const stateElByEntity = new Map<string, SVGGElement>()
+  for (const state of graph.states) {
+    const el = stateEls.find((e) => !claimed.has(e) && matchesId(e, state.id))
+    if (el) {
+      claimed.add(el)
+      stateElByEntity.set(state.entityId, el)
+      el.setAttribute('data-mw-entity', state.entityId)
+    }
+  }
+
+  // simple states store their pele-state group directly
+  for (const state of graph.states) {
+    if (!state.isComposite) {
+      const el = stateElByEntity.get(state.entityId)
+      if (el) nodes.set(state.entityId, el)
+    }
+  }
+
+  // --- composites: pele draws the composite as a g.pele-cluster with a
+  // .pele-cluster-label inside. The cluster is the composite state's primary
+  // element (selection styling paints the whole box); a pele-state group pele
+  // may also render stays tagged from the pass above as a click target.
+  for (const state of graph.states) {
+    if (!state.isComposite) continue
+    const cluster = [...svg.querySelectorAll<SVGGElement>('g.pele-cluster.pele-state-composite')].find(
+      (el) => !claimed.has(el) && matchesId(el, state.id),
+    )
+    if (cluster) {
+      claimed.add(cluster)
+      nodes.set(state.entityId, cluster)
+      cluster.setAttribute('data-mw-entity', state.entityId)
+      const label = cluster.querySelector('.pele-cluster-label')
+      if (label) label.setAttribute('data-mw-entity', state.entityId)
+    } else {
+      // no cluster: fall back to the pele-state group, if pele rendered one
+      const el = stateElByEntity.get(state.entityId)
+      if (el) nodes.set(state.entityId, el)
+      // neither rendered: unresolved — handled by the degrade pass below
+    }
+  }
+
+  // leftovers on both sides: equal counts → zip in DOM order, else degrade
+  const unmatchedStates = graph.states.filter((s) => !nodes.has(s.entityId))
+  const unclaimedStateEls = stateEls.filter((e) => !claimed.has(e))
+  if (unmatchedStates.length === unclaimedStateEls.length) {
+    unmatchedStates.forEach((s, i) => {
+      nodes.set(s.entityId, unclaimedStateEls[i])
+      unclaimedStateEls[i].setAttribute('data-mw-entity', s.entityId)
+    })
+  } else {
+    for (const s of unmatchedStates) failed.push(s.entityId)
+  }
+
+  // --- transitions: pele renders one g.pele-edge.pele-transition per
+  // transition, in document order (core's transitions array order). Note
+  // edges (pele-note-edge) and the `[*]` scenery sit outside this set. A
+  // count disagreement means the zip could shift pairings — degrade every
+  // transition rather than risk mis-zipping.
+  const domEdges = [...svg.querySelectorAll<SVGGElement>('g.pele-edge.pele-transition')]
+  if (domEdges.length === graph.transitions.length) {
+    graph.transitions.forEach((t, i) => {
+      const path = visiblePath(domEdges[i])
+      if (!path) {
+        failed.push(t.entityId)
+        return
+      }
+      edges.set(t.entityId, path)
+      path.setAttribute('data-mw-entity', t.entityId)
+      addEdgeHitOverlay(path, t.entityId)
+    })
+  } else {
+    for (const t of graph.transitions) failed.push(t.entityId)
+  }
+
+  // --- edge labels: pele only renders label groups for labeled transitions,
+  // with the same data-id as their edge group. Match through the transition's
+  // claimed edge group; a count disagreement degrades every label (unmapped)
+  // instead of shifting them onto the wrong transition — the edge entity
+  // itself may still correlate.
+  const labelEls = [...svg.querySelectorAll<SVGGElement>('g.pele-edge-label')]
+  const labeledTransitions = graph.transitions.filter(
+    (t) => t.label !== null && t.label !== '' && edges.has(t.entityId),
+  )
+  if (labelEls.length === labeledTransitions.length && labelEls.length > 0) {
+    const byEdgeDataId = new Map<string, SVGGElement>()
+    let unique = true
+    for (const el of labelEls) {
+      const id = dataId(el)
+      if (!id || byEdgeDataId.has(id)) {
+        unique = false
+        break
+      }
+      byEdgeDataId.set(id, el)
+    }
+    if (unique) {
+      for (const t of labeledTransitions) {
+        const edgeId = edges.get(t.entityId)!.closest('g.pele-edge')?.getAttribute('data-id') ?? null
+        const label = edgeId ? byEdgeDataId.get(edgeId) : undefined
+        if (label) {
+          edgeLabels.set(t.entityId, label)
+          label.setAttribute('data-mw-entity', t.entityId)
+        }
+      }
+    }
+  }
+
+  return { nodes, edges, edgeLabels, failed }
+}
+
+/** a pele-transition group's visible line path (never the pele-marker arrowhead) */
+function visiblePath(group: SVGGElement): SVGPathElement | null {
+  return group.querySelector('path:not(.pele-marker)')
+}
diff --git a/packages/dom/src/index.ts b/packages/dom/src/index.ts
index f46befb..c7c7d7c 100644
--- a/packages/dom/src/index.ts
+++ b/packages/dom/src/index.ts
@@ -2,4 +2,5 @@ export { MermaidCanvasView, type ViewOptions, type ViewHooks, type Tool, type Me
 export { mermaidAdapter, peleAdapter, type RendererAdapter, type PeleLike } from './renderer'
 export { correlateFlowchart, correlateSequence, type Correlation, type SequenceCorrelation } from './correlate'
 export { correlatePeleFlowchart } from './correlate.pele'
+export { correlatePeleState } from './correlate.pele.state'
 export { Popover, type PopoverAction, type PopoverPanelItem } from './popover'
diff --git a/packages/dom/src/view.ts b/packages/dom/src/view.ts
index 0289354..77d0f9e 100644
--- a/packages/dom/src/view.ts
+++ b/packages/dom/src/view.ts
@@ -34,6 +34,7 @@ import {
 import { ICONS } from './icons'
 import { mermaidAdapter, type RendererAdapter } from './renderer'
 import { correlatePeleFlowchart } from './correlate.pele'
+import { correlatePeleState } from './correlate.pele.state'
 
 /** default swatches offered in the color panels (works on light and dark themes) */
 export const COLOR_PALETTE = ['#ef4444', '#f97316', '#eab308', '#22c55e', '#06b6d4', '#6366f1', '#d946ef', '#64748b']
@@ -917,11 +918,15 @@ export class MermaidCanvasView {
     if (!svg) return
     const { flowchart, sequence, state, classGraph, er } = this.editor.result
     const isPele = this.renderer.id === 'pele'
-    // Under pele, flowcharts correlate through their own module; every other
-    // diagram slot stays view-only, and sequence correlation plus the
-    // visibility retry are mermaid-only.
+    // Under pele, flowcharts and state diagrams correlate through their own
+    // modules; every other diagram slot stays view-only, and sequence
+    // correlation plus the visibility retry are mermaid-only.
     if (isPele) {
-      this.correlation = flowchart ? correlatePeleFlowchart(svg, flowchart) : null
+      this.correlation = flowchart
+        ? correlatePeleFlowchart(svg, flowchart)
+        : state
+          ? correlatePeleState(svg, state)
+          : null
     } else {
       this.correlation = flowchart
         ? correlateFlowchart(svg, flowchart)
diff --git a/packages/dom/test/correlate-pele-state.test.ts b/packages/dom/test/correlate-pele-state.test.ts
new file mode 100644
index 0000000..c61c0e1
--- /dev/null
+++ b/packages/dom/test/correlate-pele-state.test.ts
@@ -0,0 +1,306 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { render as peleRender } from 'pele'
+import { MermaidWysiwygEditor, type StateGraph } from '@visimer/core'
+import { correlatePeleState } from '../src/correlate.pele.state'
+import { MermaidCanvasView, peleAdapter } from '../src'
+
+// jsdom has no CSS.escape (browsers do)
+if (typeof (globalThis as { CSS?: unknown }).CSS === 'undefined') {
+  ;(globalThis as { CSS?: { escape(s: string): string } }).CSS = {
+    escape: (s: string) => s.replace(/[^a-zA-Z0-9_-]/g, (c) => `\\${c}`),
+  }
+}
+
+// jsdom has no canvas: pele probes for one to measure text, and jsdom's
+// getContext raises a noisy "not implemented" error. Return null so pele falls
+// back to its built-in metrics table (the assertions here are structural, not
+// pixel-precise).
+HTMLCanvasElement.prototype.getContext = (() => null) as typeof HTMLCanvasElement.prototype.getContext
+
+const hosts: HTMLElement[] = []
+
+const SAMPLE = `stateDiagram-v2
+  [*] --> Idle
+  Idle --> Processing: start
+  state Processing {
+    [*] --> Run
+    Run --> Done
+  }
+  Processing --> Idle: retry
+  Done --> [*]
+`
+
+/** render a code string with real pele, correlate it against core's state graph */
+function correlate(code: string) {
+  const editor = new MermaidWysiwygEditor({ code })
+  const graph = editor.result.state
+  if (!graph) throw new Error('code did not parse as a state diagram')
+  const host = document.createElement('div')
+  document.body.appendChild(host)
+  hosts.push(host)
+  host.innerHTML = peleRender(code).svg
+  const svg = host.querySelector('svg')!
+  return { svg, graph, result: correlatePeleState(svg, graph) }
+}
+
+/** minimal StateGraph for synthetic-DOM tests (decode entities, leftover zip) */
+function fakeGraph(states: Array<{ id: string; composite?: boolean }>): StateGraph {
+  return {
+    states: states.map((s) => ({
+      entityId: `state:${s.id}`,
+      id: s.id,
+      label: s.id,
+      decl: null,
+      declLines: [],
+      refLines: [],
+      firstRefLine: 0,
+      parent: null,
+      isComposite: s.composite ?? false,
+      stereotype: null,
+      typeDeclLine: null,
+    })),
+    transitions: [],
+  } as unknown as StateGraph
+}
+
+afterEach(() => {
+  for (const host of hosts.splice(0)) host.remove()
+})
+
+describe('correlatePeleState', () => {
+  it('correlates states, the composite cluster, transitions and labels', () => {
+    const { result, svg, graph } = correlate(SAMPLE)
+
+    // every simple state lands on its pele-state group (data-id compare goes
+    // through decodeEntities), tagged with its entity id
+    for (const id of ['Idle', 'Run', 'Done'] as const) {
+      const el = result.nodes.get(`state:${id}`)!
+      expect(el).toBeTruthy()
+      expect(el).toBe(svg.querySelector(`g.pele-state[data-id="${id}"]`))
+      expect(el.getAttribute('data-mw-entity')).toBe(`state:${id}`)
+    }
+
+    // the composite state correlates to its pele-cluster (pele renders
+    // composites as clusters, not pele-state boxes), and the cluster-label
+    // inside is tagged too
+    const cluster = result.nodes.get('state:Processing')!
+    expect(cluster).toBe(svg.querySelector('g.pele-cluster.pele-state-composite[data-id="Processing"]'))
+    expect(cluster.getAttribute('data-mw-entity')).toBe('state:Processing')
+    const label = cluster.querySelector('.pele-cluster-label')!
+    expect(label).toBeTruthy()
+    expect(label.getAttribute('data-mw-entity')).toBe('state:Processing')
+
+    // transitions zip in document order, count-checked: 6 core transitions
+    // (including the two `[*]` ones) against 6 pele-transition groups
+    expect(svg.querySelectorAll('g.pele-edge.pele-transition')).toHaveLength(6)
+    expect(result.edges.size).toBe(6)
+    for (const t of graph.transitions) {
+      const path = result.edges.get(t.entityId)!
+      expect(path).toBeTruthy()
+      expect(path.tagName.toLowerCase()).toBe('path')
+      // the inner <path> is the visible line, never the pele-marker arrowhead
+      expect(path.classList.contains('pele-marker')).toBe(false)
+      expect(path.getAttribute('data-mw-entity')).toBe(t.entityId)
+      expect(path.closest('g.pele-edge')?.getAttribute('data-id')).toBe(`edge${t.order}`)
+      // the transparent hit-overlay sibling clone exists for the visible path
+      const overlay = path.parentElement!.querySelector(`[data-mw-hit-overlay="${t.entityId}"]`)
+      expect(overlay).toBeTruthy()
+      expect(overlay!.getAttribute('d')).toBe(path.getAttribute('d'))
+    }
+    expect(result.failed).toEqual([])
+  })
+
+  it('correlates labeled transition labels to their edge groups', () => {
+    const { result, svg } = correlate(SAMPLE)
+    // pele only renders label groups for labeled transitions; the label's
+    // data-id equals its edge group's data-id
+    const start = result.edgeLabels.get('trans:Idle->Processing#0')!
+    expect(start).toBe(svg.querySelector('g.pele-edge-label[data-id="edge1"]'))
+    expect(start.getAttribute('data-mw-entity')).toBe('trans:Idle->Processing#0')
+    expect(start.textContent).toContain('start')
+    const retry = result.edgeLabels.get('trans:Processing->Idle#0')!
+    expect(retry).toBe(svg.querySelector('g.pele-edge-label[data-id="edge4"]'))
+    expect(retry.getAttribute('data-mw-entity')).toBe('trans:Processing->Idle#0')
+    expect(retry.textContent).toContain('retry')
+    // unlabeled transitions claim no label group
+    expect(result.edgeLabels.size).toBe(2)
+    expect(result.failed).toEqual([])
+  })
+
+  it('never tags [*] scenery (pele-state-start / pele-state-end)', () => {
+    const { result, svg } = correlate(SAMPLE)
+    for (const id of ['root_start', 'root_end', 'Processing_start'] as const) {
+      const el = svg.querySelector(`g.pele-state-${id.endsWith('start') ? 'start' : 'end'}[data-id="${id}"]`)
+      expect(el).toBeTruthy()
+      expect(el!.hasAttribute('data-mw-entity')).toBe(false)
+      // no descendant scenery picked up an entity tag either
+      for (const child of el!.querySelectorAll('[data-mw-entity]')) {
+        expect(child).toBeNull()
+      }
+    }
+    // and no state entity ever points at a pseudo-state element
+    for (const el of result.nodes.values()) {
+      expect(el.classList.contains('pele-state-start')).toBe(false)
+      expect(el.classList.contains('pele-state-end')).toBe(false)
+    }
+  })
+
+  // adversarial: with counts mismatched (an extra pele renders a group core
+  // has no transition for) the zip must degrade EVERY transition rather than
+  // shift pairings. pele's edge list mirrors core's transitions 1:1 for every
+  // source we probed, so the mismatch is injected the same way the flowchart
+  // suite injects foreign pele-cluster-titles DOM.
+  it('degrades every transition when counts mismatch (never mis-zips)', () => {
+    const editor = new MermaidWysiwygEditor({ code: SAMPLE })
+    const graph = editor.result.state!
+    const host = document.createElement('div')
+    document.body.appendChild(host)
+    hosts.push(host)
+    host.innerHTML = peleRender(SAMPLE).svg
+    const svg = host.querySelector('svg')!
+    // one foreign group: 7 DOM groups vs 6 core transitions
+    svg.querySelector('g.pele-edges')!.insertAdjacentHTML(
+      'beforeend',
+      '<g class="pele-edge pele-transition" data-id="edge6"><path d="M0,0L10,10"/><path class="pele-marker" d="M10,10"/></g>',
+    )
+    const result = correlatePeleState(svg, graph)
+    expect(result.edges.size).toBe(0)
+    expect(result.failed).toEqual(graph.transitions.map((t) => t.entityId))
+    // no rendered path was tagged with anyone's entity
+    for (const path of svg.querySelectorAll('g.pele-edge.pele-transition path')) {
+      expect(path.hasAttribute('data-mw-entity')).toBe(false)
+    }
+    // states are unaffected by the transition degradation
+    expect(result.nodes.get('state:Idle')).toBe(svg.querySelector('g.pele-state[data-id="Idle"]'))
+    // and labels degrade with their edges (no claimed edge to match against)
+    expect(result.edgeLabels.size).toBe(0)
+    for (const label of svg.querySelectorAll('g.pele-edge-label')) {
+      expect(label.hasAttribute('data-mw-entity')).toBe(false)
+    }
+  })
+
+  // label-side count check: an extra label group makes the counts disagree,
+  // so every label degrades instead of shifting onto the wrong transition
+  it('degrades labels when label-group counts mismatch', () => {
+    const editor = new MermaidWysiwygEditor({ code: SAMPLE })
+    const graph = editor.result.state!
+    const host = document.createElement('div')
+    document.body.appendChild(host)
+    hosts.push(host)
+    host.innerHTML = peleRender(SAMPLE).svg
+    const svg = host.querySelector('svg')!
+    svg.querySelector('g.pele-edge-labels')!.insertAdjacentHTML(
+      'beforeend',
+      '<g class="pele-edge-label" data-id="edge9"><text>stray</text></g>',
+    )
+    const result = correlatePeleState(svg, graph)
+    expect(result.edgeLabels.size).toBe(0)
+    for (const label of svg.querySelectorAll('g.pele-edge-label')) {
+      expect(label.hasAttribute('data-mw-entity')).toBe(false)
+    }
+    // transitions themselves still correlate
+    expect(result.edges.size).toBe(graph.transitions.length)
+  })
+
+  it('correlates entity-coded graph ids against DOM-decoded data-ids', () => {
+    const host = document.createElement('div')
+    hosts.push(host)
+    // the attribute value is S"x after HTML parsing; the graph id arrives encoded
+    host.innerHTML = '<svg><g class="pele-node pele-state" data-id="S&quot;x"><rect/></g></svg>'
+    const svg = host.querySelector('svg')!
+    const result = correlatePeleState(svg, fakeGraph([{ id: 'S&quot;x' }]))
+    const el = result.nodes.get('state:S&quot;x')!
+    expect(el).toBe(svg.querySelector('g.pele-state'))
+    expect(el.getAttribute('data-mw-entity')).toBe('state:S&quot;x')
+    expect(result.failed).toEqual([])
+  })
+
+  it('zips leftover states in DOM order when data-id matching misses', () => {
+    const host = document.createElement('div')
+    hosts.push(host)
+    host.innerHTML =
+      '<svg><g class="pele-nodes">' +
+      '<g class="pele-node pele-state" data-id="Unknown1"><rect/></g>' +
+      '<g class="pele-node pele-state" data-id="Unknown2"><rect/></g>' +
+      '</g></svg>'
+    const svg = host.querySelector('svg')!
+    const result = correlatePeleState(svg, fakeGraph([{ id: 'P' }, { id: 'Q' }]))
+    expect(result.nodes.get('state:P')).toBe(svg.querySelector('[data-id="Unknown1"]'))
+    expect(result.nodes.get('state:Q')).toBe(svg.querySelector('[data-id="Unknown2"]'))
+    expect(result.failed).toEqual([])
+  })
+
+  it('degrades leftover states when counts disagree', () => {
+    const host = document.createElement('div')
+    hosts.push(host)
+    // core has two states, pele rendered only one — the zip must not fire
+    host.innerHTML = '<svg><g class="pele-nodes"><g class="pele-node pele-state" data-id="X"><rect/></g></g></svg>'
+    const svg = host.querySelector('svg')!
+    const result = correlatePeleState(svg, fakeGraph([{ id: 'P' }, { id: 'Q' }]))
+    expect(result.nodes.size).toBe(0)
+    expect(result.failed).toEqual(['state:P', 'state:Q'])
+    expect(svg.querySelector('[data-id="X"]')!.hasAttribute('data-mw-entity')).toBe(false)
+  })
+})
+
+/** drain microtasks and the macrotask queue so renders in flight land */
+async function flush() {
+  for (let i = 0; i < 5; i++) await new Promise((r) => setTimeout(r, 0))
+}
+
+describe('view dispatch', () => {
+  let container: HTMLElement
+  let views: MermaidCanvasView[]
+
+  beforeEach(() => {
+    container = document.createElement('div')
+    document.body.appendChild(container)
+    views = []
+  })
+
+  afterEach(() => {
+    for (const view of views) view.destroy()
+    container.remove()
+  })
+
+  it('dispatches state diagrams through the pele correlator', async () => {
+    const editor = new MermaidWysiwygEditor({ code: SAMPLE })
+    const view = new MermaidCanvasView({
+      editor,
+      container,
+      renderer: peleAdapter({ render: (src) => peleRender(src) }),
+      debounceMs: 0,
+    })
+    views.push(view)
+    await flush()
+    expect(container.querySelector('svg')).toBeTruthy()
+    expect(container.querySelector('[data-mw-entity="state:Idle"]')).toBeTruthy()
+    expect(container.querySelector('[data-mw-entity="state:Processing"]')).toBeTruthy()
+    expect(container.querySelector('[data-mw-entity="trans:Idle->Processing#0"]')).toBeTruthy()
+    // scenery stays untagged through the view path too
+    expect(container.querySelector('.pele-state-start[data-mw-entity]')).toBeNull()
+    expect(container.querySelector('.pele-state-end[data-mw-entity]')).toBeNull()
+  })
+
+  // Step 5 style spot-check: pele's allowlist keeps state classDef styling —
+  // the re-rendered SVG must visibly change (fill on the state's rect), and
+  // the styled state must still correlate
+  it('keeps classDef state styling visible under pele', async () => {
+    const editor = new MermaidWysiwygEditor({
+      code: 'stateDiagram-v2\n  classDef bad fill:#f00,stroke:#900\n  A: my state\n  A --> B\n  class A bad\n',
+    })
+    const view = new MermaidCanvasView({
+      editor,
+      container,
+      renderer: peleAdapter({ render: (src) => peleRender(src) }),
+      debounceMs: 0,
+    })
+    views.push(view)
+    await flush()
+    expect(container.querySelector('svg')).toBeTruthy()
+    const rect = container.querySelector('[data-mw-entity="state:A"] rect')
+    expect(rect).toBeTruthy()
+    expect(rect!.getAttribute('style')).toContain('fill:#f00')
+  })
+})

From 7fecae0bddbbeefa0ed3a724e282704269deda39 Mon Sep 17 00:00:00 2001
From: Casey Gollan <hello@caseyagollan.com>
Date: Sun, 1 Nov 2026 17:28:28 -0500
Subject: [PATCH 15/21] feat(dom): pele class correlator

---
 packages/dom/src/correlate.pele.class.ts      | 161 +++++++
 packages/dom/src/index.ts                     |   1 +
 packages/dom/src/view.ts                      |  23 +-
 .../dom/test/correlate-pele-class.test.ts     | 432 ++++++++++++++++++
 4 files changed, 612 insertions(+), 5 deletions(-)
 create mode 100644 packages/dom/src/correlate.pele.class.ts
 create mode 100644 packages/dom/test/correlate-pele-class.test.ts

diff --git a/packages/dom/src/correlate.pele.class.ts b/packages/dom/src/correlate.pele.class.ts
new file mode 100644
index 0000000..aeeefe0
--- /dev/null
+++ b/packages/dom/src/correlate.pele.class.ts
@@ -0,0 +1,161 @@
+import type { ClassGraph } from '@visimer/core'
+import { addEdgeHitOverlay, type Correlation } from './correlate'
+import { decodeEntities } from './correlate.pele'
+
+/**
+ * Correlate pele's rendered class-diagram SVG with the semantic graph.
+ * Strategy: pele's `data-id` attributes first (class boxes and relation labels
+ * via their edge group's data-id), then count-checked zips in document order
+ * for leftover classes. Member rows carry no data-id — pele groups ALL
+ * attributes before ALL methods (mirroring mermaid's display order), so rows
+ * are zipped count-checked per class under mermaid's supplementary tag
+ * contract. Relations render as `id_<Src>_<Tgt>_<N>` where N is pele's
+ * document-wide counter — the same underscore ambiguity as flowchart's `L_`
+ * scheme, so they match by prefix with an unambiguity guard and degrade when
+ * the prefix fits more than one relation. Anything ambiguous or
+ * count-mismatched degrades to view-only instead of pairing a wrong element.
+ */
+export function correlatePeleClass(svg: SVGSVGElement, graph: ClassGraph): Correlation {
+  const nodes = new Map<string, SVGGElement>()
+  const edges = new Map<string, SVGElement>()
+  const edgeLabels = new Map<string, SVGGElement>()
+  const failed: string[] = []
+
+  const dataId = (el: Element) => el.getAttribute('data-id')
+  // pele entity-encodes data-id values (`&quot;`, `&#65;`, ...) — compare the
+  // decoded graph id against the DOM-decoded attribute (and the raw one)
+  const matchesId = (el: Element, id: string) => {
+    const dom = dataId(el)
+    return dom === id || dom === decodeEntities(id)
+  }
+
+  // --- classes: pele stamps the class's id in data-id on g.pele-node.pele-class.
+  // Lollipop interface endpoints render as `pele-interface` scenery core has no
+  // entity for — outside this selector, so they can never be claimed, not even
+  // by the leftover zip.
+  const classEls = [...svg.querySelectorAll<SVGGElement>('g.pele-node.pele-class')]
+  const claimed = new Set<Element>()
+  for (const cls of graph.classes) {
+    const el = classEls.find((e) => !claimed.has(e) && matchesId(e, cls.id))
+    if (el) {
+      claimed.add(el)
+      nodes.set(cls.entityId, el)
+      el.setAttribute('data-mw-entity', cls.entityId)
+    }
+  }
+
+  // leftovers on both sides: equal counts → zip in DOM order, else degrade
+  const unmatchedClasses = graph.classes.filter((c) => !nodes.has(c.entityId))
+  const unclaimedClassEls = classEls.filter((e) => !claimed.has(e))
+  if (unmatchedClasses.length === unclaimedClassEls.length) {
+    unmatchedClasses.forEach((c, i) => {
+      nodes.set(c.entityId, unclaimedClassEls[i])
+      unclaimedClassEls[i].setAttribute('data-mw-entity', c.entityId)
+    })
+  } else {
+    for (const c of unmatchedClasses) failed.push(c.entityId)
+  }
+
+  // --- member rows: pele renders member texts without data-id, ALL attributes
+  // first then ALL methods — mermaid's display order (correlate.ts tags
+  // `.nodeLabel`s in the same attribute-then-method arrangement). Zip
+  // count-checked per class against the same split mermaid's correlator uses
+  // (`(` marks a method): any disagreement means the row→member mapping could
+  // shift onto the wrong line, so the rows degrade — untagged, view-only —
+  // while the class box itself stays correlated and selectable.
+  //
+  // The invariant relied on: pele@1.13.0 classifies a member as method only
+  // for balanced parens, so pele-method ⊆ our-method; positional pairing
+  // within kind is safe under that invariant — if a pele release changes
+  // member classification, the count check degrades here rather than
+  // mis-pairs.
+  for (const cls of graph.classes) {
+    const el = nodes.get(cls.entityId)
+    if (!el) continue
+    const attrs = cls.members.filter((m) => !m.text.includes('('))
+    const methods = cls.members.filter((m) => m.text.includes('('))
+    const attrEls = [...el.querySelectorAll('text.pele-member.pele-attribute')]
+    const methodEls = [...el.querySelectorAll('text.pele-member.pele-method')]
+    if (attrEls.length !== attrs.length || methodEls.length !== methods.length) continue
+    attrs.forEach((m, i) => {
+      attrEls[i].setAttribute('data-mw-member-class', cls.id)
+      attrEls[i].setAttribute('data-mw-member-line', String(m.lineIndex))
+    })
+    methods.forEach((m, i) => {
+      methodEls[i].setAttribute('data-mw-member-class', cls.id)
+      methodEls[i].setAttribute('data-mw-member-line', String(m.lineIndex))
+    })
+  }
+
+  // --- relations: pele renders one g.pele-edge.pele-relation per relation,
+  // with data-id `id_<Src>_<Tgt>_<N>` (N is pele's document-wide relation
+  // counter, not an occurrence index, and underscore-bearing ids right-parse
+  // to phantom pairs — `id_A_B_C_1` may be `A -> B_C` or `A_B -> C`). Match by
+  // `id_<src>_<tgt>_` prefix with the flowchart leftover guard: claim a group
+  // only when it is the ONLY unclaimed group fitting that relation and it
+  // fits no other relation. An ambiguous prefix (duplicate pairs, phantom
+  // splits) degrades BOTH sides — never mis-pairs. pele's note edges render
+  // as pele-note-edge (outside this selector) and cardinality texts live in a
+  // separate positional g.pele-cardinalities group that is never tagged.
+  const domEdges = [...svg.querySelectorAll<SVGGElement>('g.pele-edge.pele-relation')]
+  const claimedEdges = new Set<Element>()
+  const claimEdge = (el: SVGGElement, rel: { entityId: string }): boolean => {
+    // the first <path> is the visible line; the pele-marker paths are the
+    // arrowhead/diamond/lollipop ornaments
+    const path = el.querySelector<SVGPathElement>('path:not(.pele-marker)')
+    if (!path) return false
+    claimedEdges.add(el)
+    edges.set(rel.entityId, path)
+    path.setAttribute('data-mw-entity', rel.entityId)
+    addEdgeHitOverlay(path, rel.entityId)
+    return true
+  }
+  const fitsRelation = (el: Element, source: string, target: string) =>
+    (dataId(el) ?? '').startsWith(`id_${source}_${target}_`)
+  for (const rel of graph.relations) {
+    const fits = domEdges.filter(
+      (e) => !claimedEdges.has(e) && fitsRelation(e, rel.source, rel.target),
+    )
+    const unambiguous =
+      fits.length === 1 &&
+      graph.relations.every(
+        (other) => other === rel || !fitsRelation(fits[0], other.source, other.target),
+      )
+    // a claimed-but-pathless group degrades the relation instead of dropping it
+    if (!(unambiguous && claimEdge(fits[0], rel))) failed.push(rel.entityId)
+  }
+
+  // --- edge labels: pele only renders label groups for labeled relations,
+  // with the same data-id as their edge group. Match through the relation's
+  // claimed edge group; a count disagreement degrades every label (unmapped)
+  // instead of shifting them onto the wrong relation — the relation entity
+  // itself may still correlate.
+  const labelEls = [...svg.querySelectorAll<SVGGElement>('g.pele-edge-label')]
+  const labeledRelations = graph.relations.filter(
+    (r) => r.label !== null && r.label !== '' && edges.has(r.entityId),
+  )
+  if (labelEls.length === labeledRelations.length && labelEls.length > 0) {
+    const byEdgeDataId = new Map<string, SVGGElement>()
+    let unique = true
+    for (const el of labelEls) {
+      const id = dataId(el)
+      if (!id || byEdgeDataId.has(id)) {
+        unique = false
+        break
+      }
+      byEdgeDataId.set(id, el)
+    }
+    if (unique) {
+      for (const rel of labeledRelations) {
+        const edgeId = edges.get(rel.entityId)!.closest('g.pele-edge')?.getAttribute('data-id') ?? null
+        const label = edgeId ? byEdgeDataId.get(edgeId) : undefined
+        if (label) {
+          edgeLabels.set(rel.entityId, label)
+          label.setAttribute('data-mw-entity', rel.entityId)
+        }
+      }
+    }
+  }
+
+  return { nodes, edges, edgeLabels, failed }
+}
diff --git a/packages/dom/src/index.ts b/packages/dom/src/index.ts
index c7c7d7c..6f6bc92 100644
--- a/packages/dom/src/index.ts
+++ b/packages/dom/src/index.ts
@@ -2,5 +2,6 @@ export { MermaidCanvasView, type ViewOptions, type ViewHooks, type Tool, type Me
 export { mermaidAdapter, peleAdapter, type RendererAdapter, type PeleLike } from './renderer'
 export { correlateFlowchart, correlateSequence, type Correlation, type SequenceCorrelation } from './correlate'
 export { correlatePeleFlowchart } from './correlate.pele'
+export { correlatePeleClass } from './correlate.pele.class'
 export { correlatePeleState } from './correlate.pele.state'
 export { Popover, type PopoverAction, type PopoverPanelItem } from './popover'
diff --git a/packages/dom/src/view.ts b/packages/dom/src/view.ts
index 77d0f9e..dc50aa1 100644
--- a/packages/dom/src/view.ts
+++ b/packages/dom/src/view.ts
@@ -34,6 +34,7 @@ import {
 import { ICONS } from './icons'
 import { mermaidAdapter, type RendererAdapter } from './renderer'
 import { correlatePeleFlowchart } from './correlate.pele'
+import { correlatePeleClass } from './correlate.pele.class'
 import { correlatePeleState } from './correlate.pele.state'
 
 /** default swatches offered in the color panels (works on light and dark themes) */
@@ -918,15 +919,17 @@ export class MermaidCanvasView {
     if (!svg) return
     const { flowchart, sequence, state, classGraph, er } = this.editor.result
     const isPele = this.renderer.id === 'pele'
-    // Under pele, flowcharts and state diagrams correlate through their own
-    // modules; every other diagram slot stays view-only, and sequence
-    // correlation plus the visibility retry are mermaid-only.
+    // Under pele, flowcharts, state and class diagrams correlate through
+    // their own modules; every other diagram slot stays view-only, and
+    // sequence correlation plus the visibility retry are mermaid-only.
     if (isPele) {
       this.correlation = flowchart
         ? correlatePeleFlowchart(svg, flowchart)
         : state
           ? correlatePeleState(svg, state)
-          : null
+          : classGraph
+            ? correlatePeleClass(svg, classGraph)
+            : null
     } else {
       this.correlation = flowchart
         ? correlateFlowchart(svg, flowchart)
@@ -1111,7 +1114,7 @@ export class MermaidCanvasView {
       if (member) {
         e.preventDefault()
         this.popover.hide()
-        this.editInPlace(
+        const committed = this.editInPlace(
           `member:${clsId}:${lineIndex}`,
           memberEl,
           '.nodeLabel',
@@ -1119,6 +1122,16 @@ export class MermaidCanvasView {
           (v) => this.editor.dispatch({ type: 'cl.setMemberText', id: clsId, memberLine: lineIndex, text: v }, 'canvas'),
           { live: false },
         )
+        // pele renders member rows as SVG <text> — no HTML `.nodeLabel` for
+        // the in-place session to attach to, so editInPlace returns false and
+        // the edit must not silently no-op. Route to the overlay editor with
+        // the same commit op. Fires only where editInPlace already returned
+        // false; mermaid's HTML-label path is untouched.
+        if (!committed) {
+          this.openOverlayEditor(memberEl, member.text, (v) =>
+            this.editor.dispatch({ type: 'cl.setMemberText', id: clsId, memberLine: lineIndex, text: v }, 'canvas'),
+          )
+        }
         return
       }
     }
diff --git a/packages/dom/test/correlate-pele-class.test.ts b/packages/dom/test/correlate-pele-class.test.ts
new file mode 100644
index 0000000..9636e45
--- /dev/null
+++ b/packages/dom/test/correlate-pele-class.test.ts
@@ -0,0 +1,432 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { render as peleRender } from 'pele'
+import { MermaidWysiwygEditor, type ClassGraph } from '@visimer/core'
+import { correlatePeleClass } from '../src/correlate.pele.class'
+import { MermaidCanvasView, peleAdapter } from '../src'
+
+// jsdom has no CSS.escape (browsers do)
+if (typeof (globalThis as { CSS?: unknown }).CSS === 'undefined') {
+  ;(globalThis as { CSS?: { escape(s: string): string } }).CSS = {
+    escape: (s: string) => s.replace(/[^a-zA-Z0-9_-]/g, (c) => `\\${c}`),
+  }
+}
+
+// jsdom has no canvas: pele probes for one to measure text, and jsdom's
+// getContext raises a noisy "not implemented" error. Return null so pele falls
+// back to its built-in metrics table (the assertions here are structural, not
+// pixel-precise).
+HTMLCanvasElement.prototype.getContext = (() => null) as typeof HTMLCanvasElement.prototype.getContext
+
+const hosts: HTMLElement[] = []
+
+const SAMPLE = `classDiagram
+  class BankAccount {
+    +String owner
+    +int balance
+    +deposit() bool
+    -withdraw(int amount)
+  }
+  BankAccount "1" *-- "many" Transaction : holds
+`
+
+/** render a code string with real pele, correlate it against core's class graph */
+function correlate(code: string) {
+  const editor = new MermaidWysiwygEditor({ code })
+  const graph = editor.result.classGraph
+  if (!graph) throw new Error('code did not parse as a class diagram')
+  const host = document.createElement('div')
+  document.body.appendChild(host)
+  hosts.push(host)
+  host.innerHTML = peleRender(code).svg
+  const svg = host.querySelector('svg')!
+  return { svg, graph, result: correlatePeleClass(svg, graph) }
+}
+
+/** minimal ClassGraph for synthetic-DOM tests (decode entities, leftover zip) */
+function fakeGraph(classes: Array<{ id: string; members?: string[] }>): ClassGraph {
+  return {
+    headerLine: 0,
+    classes: classes.map((c, i) => ({
+      entityId: `class:${c.id}`,
+      id: c.id,
+      label: c.id,
+      decl: null,
+      block: null,
+      members: (c.members ?? []).map((text, j) => ({
+        lineIndex: i * 10 + j + 1,
+        text,
+        textSpan: { start: 0, end: text.length },
+      })),
+      extraLines: [],
+      refLines: [],
+      firstRefLine: 0,
+    })),
+    classById: new Map(),
+    relations: [],
+    statements: new Map(),
+    direction: null,
+    lastContentLine: 0,
+  } as unknown as ClassGraph
+}
+
+afterEach(() => {
+  for (const host of hosts.splice(0)) host.remove()
+})
+
+describe('correlatePeleClass', () => {
+  it('correlates classes, member rows, the relation and its label', () => {
+    const { result, svg, graph } = correlate(SAMPLE)
+
+    // every class lands on its pele-class group (data-id compare goes through
+    // decodeEntities), tagged with its entity id
+    for (const id of ['BankAccount', 'Transaction'] as const) {
+      const el = result.nodes.get(`class:${id}`)!
+      expect(el).toBeTruthy()
+      expect(el).toBe(svg.querySelector(`g.pele-class[data-id="${id}"]`))
+      expect(el.getAttribute('data-mw-entity')).toBe(`class:${id}`)
+    }
+    expect(result.failed).toEqual([])
+
+    // member rows are tagged mirroring mermaid's supplementary contract:
+    // attributes first, then methods, count-checked per class
+    const box = svg.querySelector('g.pele-class[data-id="BankAccount"]')!
+    const attrEls = [...box.querySelectorAll('text.pele-member.pele-attribute')]
+    const methodEls = [...box.querySelectorAll('text.pele-member.pele-method')]
+    expect(attrEls).toHaveLength(2)
+    expect(methodEls).toHaveLength(2)
+    const cls = graph.classes.find((c) => c.id === 'BankAccount')!
+    const attrs = cls.members.filter((m) => !m.text.includes('('))
+    const methods = cls.members.filter((m) => m.text.includes('('))
+    expect(attrs).toHaveLength(2)
+    expect(methods).toHaveLength(2)
+    attrs.forEach((m, i) => {
+      expect(attrEls[i].getAttribute('data-mw-member-class')).toBe('BankAccount')
+      expect(attrEls[i].getAttribute('data-mw-member-line')).toBe(String(m.lineIndex))
+    })
+    methods.forEach((m, i) => {
+      expect(methodEls[i].getAttribute('data-mw-member-class')).toBe('BankAccount')
+      expect(methodEls[i].getAttribute('data-mw-member-line')).toBe(String(m.lineIndex))
+    })
+
+    // the class-name label is never tagged as a member row
+    expect(box.querySelector('text.pele-label')!.hasAttribute('data-mw-member-line')).toBe(false)
+    // classes without members tag nothing
+    expect(svg.querySelectorAll('[data-mw-member-line]')).toHaveLength(4)
+
+    // the relation correlates to its pele-relation group's inner path — the
+    // data-id is pele's `id_<Src>_<Tgt>_<N>` scheme
+    const relId = 'rel:BankAccount->Transaction#0'
+    const path = result.edges.get(relId)!
+    expect(path).toBeTruthy()
+    expect(path.tagName.toLowerCase()).toBe('path')
+    expect(path.classList.contains('pele-marker')).toBe(false)
+    expect(path.getAttribute('data-mw-entity')).toBe(relId)
+    expect(path.closest('g.pele-edge')?.getAttribute('data-id')).toBe('id_BankAccount_Transaction_1')
+    // the transparent hit-overlay sibling clone exists for the visible path
+    const overlay = path.parentElement!.querySelector(`[data-mw-hit-overlay="${relId}"]`)
+    expect(overlay).toBeTruthy()
+    expect(overlay!.getAttribute('d')).toBe(path.getAttribute('d'))
+
+    // the relation label group carries the same data-id as its edge group
+    const label = result.edgeLabels.get(relId)!
+    expect(label).toBe(svg.querySelector('g.pele-edge-label[data-id="id_BankAccount_Transaction_1"]'))
+    expect(label.getAttribute('data-mw-entity')).toBe(relId)
+    expect(label.textContent).toContain('holds')
+
+    // cardinality texts are positional scenery — they never claim a tag
+    const cards = svg.querySelectorAll('text.pele-cardinality')
+    expect(cards).toHaveLength(2)
+    for (const card of cards) expect(card.hasAttribute('data-mw-entity')).toBe(false)
+  })
+
+  it('degrades member rows (not the class) when pele split them differently', () => {
+    const editor = new MermaidWysiwygEditor({ code: SAMPLE })
+    const graph = editor.result.classGraph!
+    const host = document.createElement('div')
+    document.body.appendChild(host)
+    hosts.push(host)
+    host.innerHTML = peleRender(SAMPLE).svg
+    const svg = host.querySelector('svg')!
+    // pele rendered one more attribute than core has — inject a foreign row
+    // the same way the state suite injects foreign pele DOM
+    svg
+      .querySelector('g.pele-class[data-id="BankAccount"] g.pele-members')!
+      .insertAdjacentHTML('beforeend', '<text class="pele-member pele-attribute" x="0" y="0">+stray int</text>')
+    const result = correlatePeleClass(svg, graph)
+    // the class itself still correlates
+    expect(result.nodes.get('class:BankAccount')).toBe(svg.querySelector('g.pele-class[data-id="BankAccount"]'))
+    expect(result.nodes.get('class:BankAccount')!.getAttribute('data-mw-entity')).toBe('class:BankAccount')
+    // but not one member row on it is tagged — a shifted zip would edit the
+    // wrong member line
+    for (const row of svg.querySelectorAll('text.pele-member')) {
+      expect(row.hasAttribute('data-mw-member-class')).toBe(false)
+      expect(row.hasAttribute('data-mw-member-line')).toBe(false)
+    }
+    // the other class (no members) and the relation are unaffected
+    expect(result.nodes.get('class:Transaction')).toBeTruthy()
+    expect(result.edges.size).toBe(1)
+    expect(result.failed).toEqual([])
+  })
+
+  it('degrades relations when the id_<Src>_<Tgt>_ prefix collides (duplicate pair)', () => {
+    const { result, svg } = correlate(
+      'classDiagram\n  A --> B : first\n  A --> B : second\n',
+    )
+    // both pele groups share the `id_A_B_` prefix — the guard degrades BOTH
+    // relations instead of pairing either, however plausibly
+    expect(svg.querySelectorAll('g.pele-edge.pele-relation')).toHaveLength(2)
+    expect(result.edges.size).toBe(0)
+    expect(result.failed).toEqual(['rel:A->B#0', 'rel:A->B#1'])
+    for (const path of svg.querySelectorAll('g.pele-edge.pele-relation path')) {
+      expect(path.hasAttribute('data-mw-entity')).toBe(false)
+    }
+    // labels degrade with their edges (no claimed edge to match against)
+    expect(result.edgeLabels.size).toBe(0)
+    for (const label of svg.querySelectorAll('g.pele-edge-label')) {
+      expect(label.hasAttribute('data-mw-entity')).toBe(false)
+    }
+    // classes are unaffected by the relation degradation
+    expect(result.nodes.size).toBe(2)
+    expect(result.failed.filter((f) => f.startsWith('class:'))).toEqual([])
+  })
+
+  it('degrades an underscore id whose prefix fits two relations', () => {
+    // `A-->B` and `A_B-->C`: pele's ids are id_A_B_1 and id_A_B_C_2. The
+    // first relation's prefix fits BOTH groups (ambiguous), and the second's
+    // group fits the first relation's prefix too — both degrade, nothing is
+    // mis-paired across the phantom split.
+    const { result, svg } = correlate('classDiagram\n  A --> B\n  A_B --> C\n')
+    expect(result.edges.size).toBe(0)
+    expect(result.failed).toEqual(['rel:A->B#0', 'rel:A_B->C#0'])
+    for (const path of svg.querySelectorAll('g.pele-edge.pele-relation path')) {
+      expect(path.hasAttribute('data-mw-entity')).toBe(false)
+    }
+    // all four classes still correlate through their data-ids
+    expect(result.nodes.size).toBe(4)
+  })
+
+  it('matches relation prefixes through pele entity encoding', () => {
+    // pele entity-encodes data-id values; the graph id arrives encoded, the
+    // DOM attribute decodes it. Core class ids are [\\w.~]+, so this is a
+    // no-op in practice — pinned so it stays that way.
+    const host = document.createElement('div')
+    hosts.push(host)
+    host.innerHTML =
+      '<svg><g class="pele-edges">' +
+      '<g class="pele-edge pele-relation" data-id="id_A_B_1"><path d="M0,0L10,10"/><path class="pele-marker" d="M1,1"/></g>' +
+      '</g></svg>'
+    const svg = host.querySelector('svg')!
+    const graph = {
+      classes: [],
+      relations: [
+        {
+          entityId: 'rel:A->B#0',
+          source: 'A',
+          target: 'B',
+          lineIndex: 1,
+          label: null,
+          order: 0,
+          stmt: {},
+        },
+      ],
+    } as unknown as ClassGraph
+    const result = correlatePeleClass(svg, graph)
+    const path = result.edges.get('rel:A->B#0')!
+    expect(path.getAttribute('d')).toBe('M0,0L10,10')
+    expect(path.classList.contains('pele-marker')).toBe(false)
+    expect(path.getAttribute('data-mw-entity')).toBe('rel:A->B#0')
+    expect(result.failed).toEqual([])
+  })
+
+  it('zips leftover classes in DOM order when data-id matching misses', () => {
+    const host = document.createElement('div')
+    hosts.push(host)
+    host.innerHTML =
+      '<svg><g class="pele-nodes">' +
+      '<g class="pele-node pele-class" data-id="Unknown1"><rect/></g>' +
+      '<g class="pele-node pele-class" data-id="Unknown2"><rect/></g>' +
+      '</g></svg>'
+    const svg = host.querySelector('svg')!
+    const result = correlatePeleClass(svg, fakeGraph([{ id: 'P' }, { id: 'Q' }]))
+    expect(result.nodes.get('class:P')).toBe(svg.querySelector('[data-id="Unknown1"]'))
+    expect(result.nodes.get('class:Q')).toBe(svg.querySelector('[data-id="Unknown2"]'))
+    expect(result.failed).toEqual([])
+  })
+
+  it('degrades leftover classes when counts disagree', () => {
+    const host = document.createElement('div')
+    hosts.push(host)
+    // core has two classes, pele rendered only one — the zip must not fire
+    host.innerHTML = '<svg><g class="pele-nodes"><g class="pele-node pele-class" data-id="X"><rect/></g></g></svg>'
+    const svg = host.querySelector('svg')!
+    const result = correlatePeleClass(svg, fakeGraph([{ id: 'P' }, { id: 'Q' }]))
+    expect(result.nodes.size).toBe(0)
+    expect(result.failed).toEqual(['class:P', 'class:Q'])
+    expect(svg.querySelector('[data-id="X"]')!.hasAttribute('data-mw-entity')).toBe(false)
+  })
+
+  it('degrades member rows when pele and core split the same members differently', () => {
+    // probe (pele@1.13.0): pele renders BOTH `+foo(` and `+bar)` as
+    // pele-attribute — its classifier only makes a balanced `()` pair a
+    // method, so unbalanced parens stay attributes — while our
+    // `includes('(')` verdict splits the same members 1 attribute + 1 method.
+    // The per-kind counts disagree (2 attribute rows vs 1 + 1): BOTH rows
+    // degrade, never swap.
+    const { result, svg } = correlate('classDiagram\n  class A {\n    +foo(\n    +bar)\n  }\n')
+    const rows = [...svg.querySelectorAll('text.pele-member')]
+    expect(rows).toHaveLength(2)
+    // pele's own kind classes, pinned from the probe: both attributes
+    for (const row of rows) expect(row.classList.contains('pele-attribute')).toBe(true)
+    // both rows degraded — no member tags, so no member edit can route
+    for (const row of rows) {
+      expect(row.hasAttribute('data-mw-member-class')).toBe(false)
+      expect(row.hasAttribute('data-mw-member-line')).toBe(false)
+    }
+    // the class itself stays correlated and selectable
+    expect(result.nodes.get('class:A')!.getAttribute('data-mw-entity')).toBe('class:A')
+    expect(result.failed).toEqual([])
+  })
+
+  it('degrades member rows when pele split a member into the other group', () => {
+    // pele@1.13.0 makes a member a method only for a balanced `()` pair —
+    // unbalanced parens fall back to attribute — so pele-method ⊆ our
+    // `includes('(')` method set. A member like `+foo(` (has `(`, no `()`)
+    // splits differently: pele renders it an attribute, we split it as a
+    // method, and the per-kind counts disagree: the rows degrade rather than
+    // shift.
+    const host = document.createElement('div')
+    hosts.push(host)
+    host.innerHTML =
+      '<svg><g class="pele-nodes">' +
+      '<g class="pele-node pele-class" data-id="A"><rect/>' +
+      '<g class="pele-members">' +
+      '<text class="pele-member pele-attribute" x="0" y="0">+foo(</text>' +
+      '<text class="pele-member pele-attribute" x="0" y="0">+int x</text>' +
+      '</g></g></g></svg>'
+    const svg = host.querySelector('svg')!
+    const result = correlatePeleClass(svg, fakeGraph([{ id: 'A', members: ['+foo(', '+int x'] }]))
+    expect(result.nodes.get('class:A')).toBeTruthy()
+    for (const row of svg.querySelectorAll('text.pele-member')) {
+      expect(row.hasAttribute('data-mw-member-line')).toBe(false)
+    }
+  })
+})
+
+describe('view dispatch', () => {
+  let container: HTMLElement
+  let views: MermaidCanvasView[]
+
+  beforeEach(() => {
+    container = document.createElement('div')
+    document.body.appendChild(container)
+    views = []
+  })
+
+  afterEach(() => {
+    for (const view of views) view.destroy()
+    container.remove()
+  })
+
+  it('dispatches class diagrams through the pele correlator', async () => {
+    const editor = new MermaidWysiwygEditor({ code: SAMPLE })
+    const view = new MermaidCanvasView({
+      editor,
+      container,
+      renderer: peleAdapter({ render: (src) => peleRender(src) }),
+      debounceMs: 0,
+    })
+    views.push(view)
+    // drain microtasks and the macrotask queue so the render lands
+    for (let i = 0; i < 5; i++) await new Promise((r) => setTimeout(r, 0))
+    expect(container.querySelector('svg')).toBeTruthy()
+    expect(container.querySelector('[data-mw-entity="class:BankAccount"]')).toBeTruthy()
+    expect(container.querySelector('[data-mw-entity="class:Transaction"]')).toBeTruthy()
+    expect(container.querySelector('[data-mw-entity="rel:BankAccount->Transaction#0"]')).toBeTruthy()
+    // member rows are tagged through the view path too
+    expect(container.querySelector('[data-mw-member-class="BankAccount"]')).toBeTruthy()
+    // and pele's own chrome (cardinalities) stays untagged
+    expect(container.querySelector('.pele-cardinality[data-mw-entity]')).toBeNull()
+  })
+
+  // Member-edit parity (spec goal 1): pele's member rows are SVG <text> —
+  // the mermaid in-place `.nodeLabel` session can't attach, so the dblclick
+  // member edit must route to the overlay editor (same commit op) instead of
+  // silently no-oping.
+  it('edits a member through the overlay editor under pele', async () => {
+    const editor = new MermaidWysiwygEditor({ code: SAMPLE })
+    const view = new MermaidCanvasView({
+      editor,
+      container,
+      renderer: peleAdapter({ render: (src) => peleRender(src) }),
+      debounceMs: 0,
+    })
+    views.push(view)
+    for (let i = 0; i < 5; i++) await new Promise((r) => setTimeout(r, 0))
+    const row = container.querySelector('text.pele-member.pele-attribute[data-mw-member-line]')!
+    expect(row.textContent).toBe('+String owner')
+    row.dispatchEvent(new MouseEvent('dblclick', { bubbles: true, cancelable: true }))
+    // no in-place session attached inside the svg (that contract is HTML-only)
+    expect(container.querySelector('svg [contenteditable]')).toBeNull()
+    // the overlay editor opened, seeded with the member's current text
+    const overlay = container.querySelector('.mw-inplace-editor')!
+    expect(overlay).toBeTruthy()
+    expect(overlay.textContent).toBe('+String owner')
+    // commit renames the member; the source rewrites through cl.setMemberText
+    overlay.textContent = '+String ownerName'
+    overlay.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }))
+    expect(editor.code).toContain('+String ownerName')
+    // and the re-rendered svg shows the committed text, still correlated
+    for (let i = 0; i < 5; i++) await new Promise((r) => setTimeout(r, 0))
+    const renamed = container.querySelector('text.pele-member.pele-attribute[data-mw-member-line]')!
+    expect(renamed.textContent).toBe('+String ownerName')
+    expect(renamed.getAttribute('data-mw-member-class')).toBe('BankAccount')
+  })
+
+  // Degraded rows must not offer a member edit: dblclicking one cannot enter
+  // the member branch (the rows carry no `data-mw-member-line`), so no editor
+  // seeded with a member's text can ever appear — the dblclick falls through
+  // to the class entity and opens the class-rename editor instead.
+  it('offers no member edit for degraded member rows', async () => {
+    const editor = new MermaidWysiwygEditor({ code: 'classDiagram\n  class A {\n    +foo(\n    +bar)\n  }\n' })
+    const view = new MermaidCanvasView({
+      editor,
+      container,
+      renderer: peleAdapter({ render: (src) => peleRender(src) }),
+      debounceMs: 0,
+    })
+    views.push(view)
+    for (let i = 0; i < 5; i++) await new Promise((r) => setTimeout(r, 0))
+    const rows = [...container.querySelectorAll('text.pele-member')]
+    expect(rows).toHaveLength(2)
+    for (const row of rows) expect(row.hasAttribute('data-mw-member-line')).toBe(false)
+    rows[0].dispatchEvent(new MouseEvent('dblclick', { bubbles: true, cancelable: true }))
+    // the ONLY editor that opens is the class rename (seeded with the class
+    // id via the entity hit) — never a member edit seeded with member text
+    const overlay = container.querySelector('.mw-inplace-editor')!
+    expect(overlay).toBeTruthy()
+    expect(overlay.textContent).toBe('A')
+  })
+
+  // Step 5 style spot-check: pele's class renderer keeps `style A fill:#f00`
+  // (verified against pele@1.13.0) — the rendered SVG must visibly change, and
+  // the styled class must still correlate. Note pele@1.13.0 DROPS classDef /
+  // `class A bad` styling for class diagrams (its parser mis-reads the
+  // statement), so this spot-check pins the form that actually survives.
+  it('keeps inline style styling visible under pele', async () => {
+    const code = 'classDiagram\n  A --> B\n  style A fill:#f00\n'
+    const editor = new MermaidWysiwygEditor({ code })
+    const view = new MermaidCanvasView({
+      editor,
+      container,
+      renderer: peleAdapter({ render: (src) => peleRender(src) }),
+      debounceMs: 0,
+    })
+    views.push(view)
+    for (let i = 0; i < 5; i++) await new Promise((r) => setTimeout(r, 0))
+    expect(container.querySelector('svg')).toBeTruthy()
+    const rect = container.querySelector('[data-mw-entity="class:A"] rect')
+    expect(rect).toBeTruthy()
+    expect(rect!.getAttribute('style')).toContain('fill:#f00')
+  })
+})

From 948b997e90337dcee57f92028e341a309de46e8e Mon Sep 17 00:00:00 2001
From: Casey Gollan <hello@caseyagollan.com>
Date: Sun, 1 Nov 2026 17:42:25 -0500
Subject: [PATCH 16/21] feat(dom): pele er correlator

---
 packages/dom/src/correlate.pele.er.ts       | 189 +++++++++
 packages/dom/src/index.ts                   |   1 +
 packages/dom/src/view.ts                    |   7 +-
 packages/dom/test/correlate-pele-er.test.ts | 423 ++++++++++++++++++++
 4 files changed, 618 insertions(+), 2 deletions(-)
 create mode 100644 packages/dom/src/correlate.pele.er.ts
 create mode 100644 packages/dom/test/correlate-pele-er.test.ts

diff --git a/packages/dom/src/correlate.pele.er.ts b/packages/dom/src/correlate.pele.er.ts
new file mode 100644
index 0000000..d24ced7
--- /dev/null
+++ b/packages/dom/src/correlate.pele.er.ts
@@ -0,0 +1,189 @@
+import type { ErGraph } from '@visimer/core'
+import { addEdgeHitOverlay, type Correlation } from './correlate'
+import { decodeEntities } from './correlate.pele'
+
+/**
+ * Correlate pele's rendered er-diagram SVG with the semantic graph.
+ * Strategy: pele's `data-id` attributes first for entities (pele keys them by
+ * the entity's DISPLAY LABEL, not core's `entity:` id — core's `NAME[alias]`
+ * decl syntax re-labels an entity), then a count-checked leftover zip.
+ * Duplicate display labels are inherently ambiguous for label-keyed matching,
+ * so the colliding entities degrade up front and are excluded from the zip.
+ * Relationships match `g.pele-edge.pele-er-*` by document-order count-check
+ * against core's `erel` list — pele's `id_entity-…` data-id scheme embeds each
+ * entity's label and internal index, so underscore-bearing labels make
+ * right-parsing ambiguous and the scheme is treated as a hint, never proof.
+ * Attribute rows carry no data-id — pele renders `text.pele-er-*` cells per
+ * row, zipped count-checked per entity under mermaid's supplementary tag
+ * contract (`data-mw-attr-entity` / `data-mw-attr-line`). Anything ambiguous
+ * or count-mismatched degrades to view-only instead of pairing a wrong
+ * element.
+ */
+export function correlatePeleEr(svg: SVGSVGElement, graph: ErGraph): Correlation {
+  const nodes = new Map<string, SVGGElement>()
+  const edges = new Map<string, SVGElement>()
+  const edgeLabels = new Map<string, SVGGElement>()
+  const failed: string[] = []
+
+  const dataId = (el: Element) => el.getAttribute('data-id')
+  // pele entity-encodes data-id values (`&quot;`, `&#65;`, ...) — compare the
+  // decoded label against the DOM-decoded attribute (and the raw one)
+  const matchesLabel = (el: Element, label: string) => {
+    const dom = dataId(el)
+    return dom === label || dom === decodeEntities(label)
+  }
+
+  // --- entities: pele stamps the entity's label in data-id on
+  // g.pele-node.pele-entity. Core's `NAME[alias]` decl syntax can give TWO
+  // entities one display label — label-keyed matching is then ambiguous by
+  // construction, so the colliding entities degrade up front and never enter
+  // the leftover zip either (zipping entities that display identically could
+  // cross-pair them). pele paints the alias as the box text but keeps the
+  // NAME in data-id, so a re-labeled entity misses the label pass and is
+  // recovered by the count-checked zip below.
+  const entityEls = [...svg.querySelectorAll<SVGGElement>('g.pele-node.pele-entity')]
+  const labelCount = new Map<string, number>()
+  for (const e of graph.entities) {
+    const label = decodeEntities(e.label)
+    labelCount.set(label, (labelCount.get(label) ?? 0) + 1)
+  }
+  const claimed = new Set<Element>()
+  const unmatched: typeof graph.entities = []
+  for (const e of graph.entities) {
+    if ((labelCount.get(decodeEntities(e.label)) ?? 0) > 1) {
+      // duplicate display label — degrade, never pair
+      failed.push(e.entityId)
+      continue
+    }
+    const fits = entityEls.filter((el) => !claimed.has(el) && matchesLabel(el, e.label))
+    if (fits.length === 1) {
+      claimed.add(fits[0])
+      nodes.set(e.entityId, fits[0])
+      fits[0].setAttribute('data-mw-entity', e.entityId)
+    } else {
+      // 0 = pele didn't render the label as-is (alias case); >1 = pele
+      // rendered the label more than once (ambiguous) — both go to the zip
+      // or degrade below
+      unmatched.push(e)
+    }
+  }
+
+  // leftovers on both sides: equal counts → zip in DOM order, else degrade.
+  // Invariant relied on for the positional pairing: pele emits its entity
+  // groups in its model's first-mention order, which equals core's
+  // entity-array order for the same source (both parsers walk the lines
+  // top-down and key entities by first mention) — so the i-th unmatched
+  // entity is the i-th unclaimed group. If pele ever reorders its nodes, the
+  // label pass still handles the non-aliased case and the count check keeps
+  // the zip from firing on partial renders.
+  const unclaimedEntityEls = entityEls.filter((el) => !claimed.has(el))
+  if (unmatched.length > 0 && unmatched.length === unclaimedEntityEls.length) {
+    unmatched.forEach((e, i) => {
+      nodes.set(e.entityId, unclaimedEntityEls[i])
+      unclaimedEntityEls[i].setAttribute('data-mw-entity', e.entityId)
+    })
+  } else {
+    for (const e of unmatched) failed.push(e.entityId)
+  }
+
+  // --- attribute rows: pele renders each attribute as up to four
+  // `text.pele-er-*` cells (type, name, keys, comment — empties are skipped)
+  // inside g.pele-er-attributes, with NO data-id. All cells of a row share
+  // one y, and pele emits rows top-to-bottom in attribute order. Group the
+  // texts per row by y, zip count-checked against core's attributes for the
+  // same entity under mermaid's supplementary tag contract — data-mw-attr-
+  // entity carries the entity's RAW id (mermaid's correlateEr tags
+  // `entity.id` and the view's attr-edit routing looks it up in
+  // er.entityById), data-mw-attr-line the attribute's line index. Any count
+  // disagreement means the row→attribute mapping could shift onto the wrong
+  // line, so the rows degrade — untagged, view-only — while the entity box
+  // itself stays correlated and selectable. pele's chrome (row stripes in
+  // g.pele-er-stripes, the path.pele-er-divider, the pele-label title) sits
+  // outside this selector and is never tagged.
+  for (const e of graph.entities) {
+    const el = nodes.get(e.entityId)
+    if (!el || !e.attributes.length) continue
+    const rows = new Map<string, SVGTextElement[]>()
+    for (const t of el.querySelectorAll<SVGTextElement>('g.pele-er-attributes > text')) {
+      const y = t.getAttribute('y') ?? ''
+      const row = rows.get(y) ?? []
+      row.push(t)
+      rows.set(y, row)
+    }
+    const rowList = [...rows.values()]
+    if (rowList.length !== e.attributes.length) continue
+    e.attributes.forEach((attr, i) => {
+      for (const t of rowList[i]) {
+        t.setAttribute('data-mw-attr-entity', e.id)
+        t.setAttribute('data-mw-attr-line', String(attr.lineIndex))
+      }
+    })
+  }
+
+  // --- relationships: pele renders one g.pele-edge per relationship, classed
+  // pele-er-identifying (`--`) or pele-er-non-identifying (`..`), with data-id
+  // `id_entity-<label>-<idx>_entity-<label>-<idx>_<n>`. The scheme embeds each
+  // entity's label and internal index, so underscore-bearing labels make
+  // right-parsing ambiguous (`id_entity-A_B-0_…` may be `A_B -> C` or
+  // `A -> B_C`) — treat the id as a HINT only and match by document-order
+  // count-check against core's erel list (order + count is truth). pele emits
+  // relationships in source order, which equals core's relation-array order
+  // for the same source. A count disagreement means the zip could shift
+  // pairings — degrade every relationship rather than risk mis-zipping.
+  const domEdges = [
+    ...svg.querySelectorAll<SVGGElement>(
+      'g.pele-edge.pele-er-identifying, g.pele-edge.pele-er-non-identifying',
+    ),
+  ]
+  if (domEdges.length === graph.relations.length) {
+    graph.relations.forEach((r, i) => {
+      // the first <path> is the visible line; pele-marker paths/circles are
+      // the crow's-foot ornaments
+      const path = domEdges[i].querySelector<SVGPathElement>('path:not(.pele-marker)')
+      if (!path) {
+        failed.push(r.entityId)
+        return
+      }
+      edges.set(r.entityId, path)
+      path.setAttribute('data-mw-entity', r.entityId)
+      addEdgeHitOverlay(path, r.entityId)
+    })
+  } else {
+    for (const r of graph.relations) failed.push(r.entityId)
+  }
+
+  // --- edge labels: pele renders label groups for relationships it draws a
+  // role text for, with the same data-id as their edge group. Match through
+  // the relationship's claimed edge group (anchored by the document-order
+  // zip above, never by parsing the id); a count disagreement degrades every
+  // label (unmapped) instead of shifting them onto the wrong relationship —
+  // the relationship entity itself may still correlate.
+  const labelEls = [...svg.querySelectorAll<SVGGElement>('g.pele-edge-label')]
+  const labeledRelations = graph.relations.filter(
+    (r) => r.label !== null && r.label !== '' && edges.has(r.entityId),
+  )
+  if (labelEls.length === labeledRelations.length && labelEls.length > 0) {
+    const byEdgeDataId = new Map<string, SVGGElement>()
+    let unique = true
+    for (const el of labelEls) {
+      const id = dataId(el)
+      if (!id || byEdgeDataId.has(id)) {
+        unique = false
+        break
+      }
+      byEdgeDataId.set(id, el)
+    }
+    if (unique) {
+      for (const r of labeledRelations) {
+        const edgeId = edges.get(r.entityId)!.closest('g.pele-edge')?.getAttribute('data-id') ?? null
+        const label = edgeId ? byEdgeDataId.get(edgeId) : undefined
+        if (label) {
+          edgeLabels.set(r.entityId, label)
+          label.setAttribute('data-mw-entity', r.entityId)
+        }
+      }
+    }
+  }
+
+  return { nodes, edges, edgeLabels, failed }
+}
diff --git a/packages/dom/src/index.ts b/packages/dom/src/index.ts
index 6f6bc92..2c7e9af 100644
--- a/packages/dom/src/index.ts
+++ b/packages/dom/src/index.ts
@@ -4,4 +4,5 @@ export { correlateFlowchart, correlateSequence, type Correlation, type SequenceC
 export { correlatePeleFlowchart } from './correlate.pele'
 export { correlatePeleClass } from './correlate.pele.class'
 export { correlatePeleState } from './correlate.pele.state'
+export { correlatePeleEr } from './correlate.pele.er'
 export { Popover, type PopoverAction, type PopoverPanelItem } from './popover'
diff --git a/packages/dom/src/view.ts b/packages/dom/src/view.ts
index dc50aa1..3f952bf 100644
--- a/packages/dom/src/view.ts
+++ b/packages/dom/src/view.ts
@@ -36,6 +36,7 @@ import { mermaidAdapter, type RendererAdapter } from './renderer'
 import { correlatePeleFlowchart } from './correlate.pele'
 import { correlatePeleClass } from './correlate.pele.class'
 import { correlatePeleState } from './correlate.pele.state'
+import { correlatePeleEr } from './correlate.pele.er'
 
 /** default swatches offered in the color panels (works on light and dark themes) */
 export const COLOR_PALETTE = ['#ef4444', '#f97316', '#eab308', '#22c55e', '#06b6d4', '#6366f1', '#d946ef', '#64748b']
@@ -919,7 +920,7 @@ export class MermaidCanvasView {
     if (!svg) return
     const { flowchart, sequence, state, classGraph, er } = this.editor.result
     const isPele = this.renderer.id === 'pele'
-    // Under pele, flowcharts, state and class diagrams correlate through
+    // Under pele, flowcharts, state, class and er diagrams correlate through
     // their own modules; every other diagram slot stays view-only, and
     // sequence correlation plus the visibility retry are mermaid-only.
     if (isPele) {
@@ -929,7 +930,9 @@ export class MermaidCanvasView {
           ? correlatePeleState(svg, state)
           : classGraph
             ? correlatePeleClass(svg, classGraph)
-            : null
+            : er
+              ? correlatePeleEr(svg, er)
+              : null
     } else {
       this.correlation = flowchart
         ? correlateFlowchart(svg, flowchart)
diff --git a/packages/dom/test/correlate-pele-er.test.ts b/packages/dom/test/correlate-pele-er.test.ts
new file mode 100644
index 0000000..bf37215
--- /dev/null
+++ b/packages/dom/test/correlate-pele-er.test.ts
@@ -0,0 +1,423 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { render as peleRender } from 'pele'
+import { MermaidWysiwygEditor, type ErGraph } from '@visimer/core'
+import { correlatePeleEr } from '../src/correlate.pele.er'
+import { MermaidCanvasView, peleAdapter } from '../src'
+
+// jsdom has no CSS.escape (browsers do)
+if (typeof (globalThis as { CSS?: unknown }).CSS === 'undefined') {
+  ;(globalThis as { CSS?: { escape(s: string): string } }).CSS = {
+    escape: (s: string) => s.replace(/[^a-zA-Z0-9_-]/g, (c) => `\\${c}`),
+  }
+}
+
+// jsdom has no canvas: pele probes for one to measure text, and jsdom's
+// getContext raises a noisy "not implemented" error. Return null so pele falls
+// back to its built-in metrics table (the assertions here are structural, not
+// pixel-precise).
+HTMLCanvasElement.prototype.getContext = (() => null) as typeof HTMLCanvasElement.prototype.getContext
+
+const hosts: HTMLElement[] = []
+
+const SAMPLE = `erDiagram
+  CUSTOMER ||--o{ ORDER : places
+  CUSTOMER {
+    string name
+    int id
+  }
+  ORDER ||--|{ LINEITEM : contains
+`
+
+/** render a code string with real pele, correlate it against core's er graph */
+function correlate(code: string) {
+  const editor = new MermaidWysiwygEditor({ code })
+  const graph = editor.result.er
+  if (!graph) throw new Error('code did not parse as an er diagram')
+  const host = document.createElement('div')
+  document.body.appendChild(host)
+  hosts.push(host)
+  host.innerHTML = peleRender(code).svg
+  const svg = host.querySelector('svg')!
+  return { svg, graph, result: correlatePeleEr(svg, graph) }
+}
+
+/** minimal ErGraph for synthetic-DOM tests */
+function fakeGraph(entities: Array<{ id: string; label?: string; attributes?: string[] }>, relations: Array<{ source: string; target: string; label?: string }> = []): ErGraph {
+  return {
+    headerLine: 0,
+    entities: entities.map((e) => ({
+      entityId: `entity:${e.id}`,
+      id: e.id,
+      label: e.label ?? e.id,
+      decl: null,
+      block: null,
+      attributes: (e.attributes ?? []).map((text, i) => ({
+        lineIndex: i + 1,
+        text,
+        textSpan: { start: 0, end: text.length },
+      })),
+      refLines: [],
+      firstRefLine: 0,
+    })),
+    entityById: new Map(entities.map((e) => [e.id, {
+      entityId: `entity:${e.id}`,
+      id: e.id,
+      label: e.label ?? e.id,
+      decl: null,
+      block: null,
+      attributes: (e.attributes ?? []).map((text, i) => ({
+        lineIndex: i + 1,
+        text,
+        textSpan: { start: 0, end: text.length },
+      })),
+      refLines: [],
+      firstRefLine: 0,
+    }])),
+    relations: relations.map((r, i) => ({
+      entityId: `erel:${r.source}->${r.target}#${i}`,
+      source: r.source,
+      target: r.target,
+      lineIndex: i + 1,
+      stmt: {},
+      label: r.label ?? '',
+      order: i,
+    })),
+    statements: new Map(),
+    lastContentLine: 0,
+  } as unknown as ErGraph
+}
+
+afterEach(() => {
+  for (const host of hosts.splice(0)) host.remove()
+})
+
+describe('correlatePeleEr', () => {
+  it('correlates entities, attribute rows, relationships and labels', () => {
+    const { result, svg, graph } = correlate(SAMPLE)
+
+    // every entity lands on its pele-entity group — pele keys data-id by the
+    // entity's label (not core's `entity:` id), tagged with its entity id
+    for (const name of ['CUSTOMER', 'ORDER', 'LINEITEM'] as const) {
+      const el = result.nodes.get(`entity:${name}`)!
+      expect(el).toBeTruthy()
+      expect(el).toBe(svg.querySelector(`g.pele-entity[data-id="${name}"]`))
+      expect(el.getAttribute('data-mw-entity')).toBe(`entity:${name}`)
+    }
+    expect(result.failed).toEqual([])
+
+    // attribute rows are tagged mirroring mermaid's supplementary contract:
+    // data-mw-attr-entity carries the entity's RAW id (the view's attr-edit
+    // routing looks it up in er.entityById), data-mw-attr-line the line index
+    const box = svg.querySelector('g.pele-entity[data-id="CUSTOMER"]')!
+    const texts = [...box.querySelectorAll('g.pele-er-attributes text')]
+    expect(texts).toHaveLength(4) // 2 rows x (type + name)
+    const customer = graph.entityById.get('CUSTOMER')!
+    expect(customer.attributes).toHaveLength(2)
+    // pele lays each row out on one y: group the texts per row
+    const rowYs = [...new Set(texts.map((t) => t.getAttribute('y')))]
+    expect(rowYs).toHaveLength(2)
+    for (let i = 0; i < 2; i++) {
+      const row = texts.filter((t) => t.getAttribute('y') === rowYs[i])
+      const attr = customer.attributes[i]
+      for (const t of row) {
+        expect(t.getAttribute('data-mw-attr-entity')).toBe('CUSTOMER')
+        expect(t.getAttribute('data-mw-attr-line')).toBe(String(attr.lineIndex))
+      }
+    }
+    // name and type both carry the row tags
+    const byY = (y: string) => texts.filter((t) => t.getAttribute('y') === y)
+    expect(byY(rowYs[0]).map((t) => t.textContent).sort()).toEqual(['name', 'string'])
+    expect(byY(rowYs[1]).map((t) => t.textContent).sort()).toEqual(['id', 'int'])
+
+    // pele's own chrome (stripes, divider, the entity label) is never tagged
+    expect(box.querySelectorAll('g.pele-er-stripes rect').length).toBeGreaterThan(0)
+    for (const scenery of [
+      ...box.querySelectorAll('g.pele-er-stripes rect'),
+      ...box.querySelectorAll('path.pele-er-divider'),
+      ...box.querySelectorAll('text.pele-label'),
+    ]) {
+      expect(scenery.hasAttribute('data-mw-entity')).toBe(false)
+      expect(scenery.hasAttribute('data-mw-attr-line')).toBe(false)
+    }
+
+    // relationships correlate to their pele-edge group's inner path — pele's
+    // `id_entity-…` data-id scheme is a hint only; document-order count-check
+    // against core's erel list is the truth
+    const relId = 'erel:CUSTOMER->ORDER#0'
+    const path = result.edges.get(relId)!
+    expect(path).toBeTruthy()
+    expect(path.tagName.toLowerCase()).toBe('path')
+    expect(path.classList.contains('pele-marker')).toBe(false)
+    expect(path.getAttribute('data-mw-entity')).toBe(relId)
+    expect(path.closest('g.pele-edge')?.classList.contains('pele-er-identifying')).toBe(true)
+    // the transparent hit-overlay sibling clone exists for the visible path
+    const overlay = path.parentElement!.querySelector(`[data-mw-hit-overlay="${relId}"]`)
+    expect(overlay).toBeTruthy()
+    expect(overlay!.getAttribute('d')).toBe(path.getAttribute('d'))
+    expect(result.edges.get('erel:ORDER->LINEITEM#0')).toBeTruthy()
+
+    // the label group carries the same data-id as its edge group
+    const label = result.edgeLabels.get(relId)!
+    expect(label).toBe(
+      svg.querySelector('g.pele-edge-label[data-id="id_entity-CUSTOMER-0_entity-ORDER-1_0"]'),
+    )
+    expect(label.getAttribute('data-mw-entity')).toBe(relId)
+    expect(label.textContent).toContain('places')
+  })
+
+  it('degrades duplicate-label entities (core alias syntax) instead of mis-pairing', () => {
+    // core's decl syntax `NAME[alias]` re-labels an entity — `A[X]` and `B[X]`
+    // are two entities sharing one display label. Label-keyed matching is
+    // inherently ambiguous for them: BOTH degrade to view-only, never pair
+    // (not even positionally).
+    const { result, svg } = correlate('erDiagram\n  A[X]\n  B[X]\n  A ||--o{ B : r\n')
+    expect(svg.querySelectorAll('g.pele-entity')).toHaveLength(2)
+    expect(result.nodes.size).toBe(0)
+    expect(result.failed).toEqual(['entity:A', 'entity:B'])
+    for (const el of svg.querySelectorAll('g.pele-entity')) {
+      expect(el.hasAttribute('data-mw-entity')).toBe(false)
+    }
+    // no attribute rows can be tagged for degraded entities
+    expect(svg.querySelectorAll('[data-mw-attr-line]')).toHaveLength(0)
+    // the relationship itself is unaffected — document-order zip vs core's
+    // erel list is independent of entity correlation
+    expect(result.edges.size).toBe(1)
+    expect(result.failed.filter((f) => f.startsWith('erel:'))).toEqual([])
+  })
+
+  it('degrades attribute rows (not the entity) when pele rendered a different count', () => {
+    const editor = new MermaidWysiwygEditor({ code: SAMPLE })
+    const graph = editor.result.er!
+    const host = document.createElement('div')
+    document.body.appendChild(host)
+    hosts.push(host)
+    host.innerHTML = peleRender(SAMPLE).svg
+    const svg = host.querySelector('svg')!
+    // pele rendered one more attribute row than core has — inject a foreign
+    // row (same y as an existing row's texts would merge, so give it its own y)
+    const attrs = svg.querySelector('g.pele-entity[data-id="CUSTOMER"] g.pele-er-attributes')!
+    attrs.insertAdjacentHTML(
+      'beforeend',
+      '<text class="pele-er-type" x="0" y="999">stray</text><text class="pele-er-name" x="0" y="999">row</text>',
+    )
+    const result = correlatePeleEr(svg, graph)
+    // the entity itself still correlates
+    expect(result.nodes.get('entity:CUSTOMER')).toBe(svg.querySelector('g.pele-entity[data-id="CUSTOMER"]'))
+    expect(result.nodes.get('entity:CUSTOMER')!.getAttribute('data-mw-entity')).toBe('entity:CUSTOMER')
+    // but not one attribute row on it is tagged — a shifted zip would edit
+    // the wrong attribute line
+    for (const t of attrs.querySelectorAll('text')) {
+      expect(t.hasAttribute('data-mw-attr-entity')).toBe(false)
+      expect(t.hasAttribute('data-mw-attr-line')).toBe(false)
+    }
+    // the other entities and the relationships are unaffected
+    expect(result.nodes.get('entity:ORDER')).toBeTruthy()
+    expect(result.edges.size).toBe(2)
+    expect(result.failed).toEqual([])
+  })
+
+  it('degrades relationships when the document-order count disagrees', () => {
+    const editor = new MermaidWysiwygEditor({ code: SAMPLE })
+    const graph = editor.result.er!
+    const host = document.createElement('div')
+    document.body.appendChild(host)
+    hosts.push(host)
+    host.innerHTML = peleRender(SAMPLE).svg
+    const svg = host.querySelector('svg')!
+    // core has two relationships, pele rendered one more — inject a foreign
+    // edge group; the count check must degrade every relation rather than
+    // shift the zip onto the wrong line
+    svg.querySelector('g.pele-edges')!.insertAdjacentHTML(
+      'beforeend',
+      '<g class="pele-edge pele-er-identifying" data-id="id_entity-CUSTOMER-0_entity-LINEITEM-2_9"><path d="M0,0L10,10"/><path class="pele-marker" d="M1,1"/></g>',
+    )
+    const result = correlatePeleEr(svg, graph)
+    expect(result.edges.size).toBe(0)
+    expect(result.failed).toEqual(['erel:CUSTOMER->ORDER#0', 'erel:ORDER->LINEITEM#0'])
+    for (const path of svg.querySelectorAll('g.pele-edge path')) {
+      expect(path.hasAttribute('data-mw-entity')).toBe(false)
+    }
+    // labels degrade with their edges (no claimed edge to match against)
+    expect(result.edgeLabels.size).toBe(0)
+    // entities and attribute rows still correlate
+    expect(result.nodes.size).toBe(3)
+    expect(svg.querySelectorAll('[data-mw-attr-line]').length).toBeGreaterThan(0)
+  })
+
+  it('correlates non-identifying (`..`) relationships alongside identifying ones', () => {
+    const { result, svg } = correlate('erDiagram\n  A ||--o{ B : solid\n  A ||..o{ B : dashed\n')
+    const groups = [...svg.querySelectorAll('g.pele-edge.pele-er-identifying, g.pele-edge.pele-er-non-identifying')]
+    expect(groups).toHaveLength(2)
+    expect(groups[0].classList.contains('pele-er-identifying')).toBe(true)
+    expect(groups[1].classList.contains('pele-er-non-identifying')).toBe(true)
+    expect(result.edges.size).toBe(2)
+    expect(result.failed).toEqual([])
+    for (const id of ['erel:A->B#0', 'erel:A->B#1'] as const) {
+      const path = result.edges.get(id)!
+      expect(path.classList.contains('pele-marker')).toBe(false)
+      expect(path.getAttribute('data-mw-entity')).toBe(id)
+    }
+    expect(result.edgeLabels.size).toBe(2)
+  })
+
+  it('matches entity data-ids through pele entity encoding', () => {
+    // pele entity-encodes data-id values; the graph label arrives encoded, the
+    // DOM attribute decodes it. Core er names are [\w-]+, so this is a no-op
+    // in practice — pinned so it stays that way.
+    const host = document.createElement('div')
+    hosts.push(host)
+    host.innerHTML =
+      '<svg><g class="pele-nodes">' +
+      '<g class="pele-node pele-entity" data-id="A"><rect/></g>' +
+      '</g></svg>'
+    const svg = host.querySelector('svg')!
+    const result = correlatePeleEr(svg, fakeGraph([{ id: 'A', label: 'A' }]))
+    expect(result.nodes.get('entity:A')).toBe(svg.querySelector('[data-id="A"]'))
+    expect(result.nodes.get('entity:A')!.getAttribute('data-mw-entity')).toBe('entity:A')
+    expect(result.failed).toEqual([])
+  })
+
+  it('degrades entities when counts disagree with no positional rescue', () => {
+    // core has two entities, pele rendered only one. The leftover zip needs
+    // equal counts; here they disagree, so BOTH degrade — a positional pair
+    // could cross onto the wrong entity when labels disagree.
+    const host = document.createElement('div')
+    hosts.push(host)
+    host.innerHTML =
+      '<svg><g class="pele-nodes"><g class="pele-node pele-entity" data-id="X"><rect/></g></g></svg>'
+    const svg = host.querySelector('svg')!
+    const result = correlatePeleEr(svg, fakeGraph([{ id: 'P', label: 'P' }, { id: 'Q', label: 'Q' }]))
+    expect(result.nodes.size).toBe(0)
+    expect(result.failed).toEqual(['entity:P', 'entity:Q'])
+    expect(svg.querySelector('[data-id="X"]')!.hasAttribute('data-mw-entity')).toBe(false)
+  })
+
+  it('degrades an entity whose label fits more than one unclaimed pele group', () => {
+    // two pele groups share one data-id (should not happen on real pele
+    // output, but if a release ever duplicates them, matching by label would
+    // be ambiguous) — degrade instead of picking either
+    const host = document.createElement('div')
+    hosts.push(host)
+    host.innerHTML =
+      '<svg><g class="pele-nodes">' +
+      '<g class="pele-node pele-entity" data-id="A"><rect/></g>' +
+      '<g class="pele-node pele-entity" data-id="A"><rect/></g>' +
+      '</g></svg>'
+    const svg = host.querySelector('svg')!
+    const result = correlatePeleEr(svg, fakeGraph([{ id: 'A' }]))
+    expect(result.nodes.size).toBe(0)
+    expect(result.failed).toEqual(['entity:A'])
+    for (const el of svg.querySelectorAll('g.pele-entity')) {
+      expect(el.hasAttribute('data-mw-entity')).toBe(false)
+    }
+  })
+
+  it('zips a leftover entity in DOM order when its label is absent from pele\u2019s data-ids', () => {
+    // core's alias syntax re-labels `A` to `X`; pele keeps the NAME in
+    // data-id and paints the alias as the box text, so the label pass misses
+    // and the (count-checked) leftover zip pairs the one unmatched entity
+    // with the one unclaimed group
+    const host = document.createElement('div')
+    hosts.push(host)
+    host.innerHTML =
+      '<svg><g class="pele-nodes">' +
+      '<g class="pele-node pele-entity" data-id="A"><rect/></g>' +
+      '<g class="pele-node pele-entity" data-id="B"><rect/></g>' +
+      '</g></svg>'
+    const svg = host.querySelector('svg')!
+    const result = correlatePeleEr(svg, fakeGraph([{ id: 'A', label: 'X' }, { id: 'B' }]))
+    expect(result.nodes.get('entity:B')).toBe(svg.querySelector('[data-id="B"]'))
+    expect(result.nodes.get('entity:A')).toBe(svg.querySelector('[data-id="A"]'))
+    expect(result.failed).toEqual([])
+  })
+})
+
+describe('view dispatch', () => {
+  let container: HTMLElement
+  let views: MermaidCanvasView[]
+
+  beforeEach(() => {
+    container = document.createElement('div')
+    document.body.appendChild(container)
+    views = []
+  })
+
+  afterEach(() => {
+    for (const view of views) view.destroy()
+    container.remove()
+  })
+
+  it('dispatches er diagrams through the pele correlator', async () => {
+    const editor = new MermaidWysiwygEditor({ code: SAMPLE })
+    const view = new MermaidCanvasView({
+      editor,
+      container,
+      renderer: peleAdapter({ render: (src) => peleRender(src) }),
+      debounceMs: 0,
+    })
+    views.push(view)
+    // drain microtasks and the macrotask queue so the render lands
+    for (let i = 0; i < 5; i++) await new Promise((r) => setTimeout(r, 0))
+    expect(container.querySelector('svg')).toBeTruthy()
+    for (const id of ['entity:CUSTOMER', 'entity:ORDER', 'entity:LINEITEM'] as const) {
+      expect(container.querySelector(`[data-mw-entity="${id}"]`)).toBeTruthy()
+    }
+    expect(container.querySelector('[data-mw-entity="erel:CUSTOMER->ORDER#0"]')).toBeTruthy()
+    // attribute rows are tagged through the view path too
+    expect(container.querySelector('[data-mw-attr-entity="CUSTOMER"]')).toBeTruthy()
+    // and pele's own chrome (stripes) stays untagged
+    expect(container.querySelector('.pele-er-stripes rect[data-mw-attr-line]')).toBeNull()
+  })
+
+  // Attribute-edit parity: pele's attribute cells are SVG <text> — the tags
+  // must route dblclicks to the overlay editor with the er.setAttributeText
+  // commit op (mermaid's HTML cells take the same branch).
+  it('edits an attribute through the overlay editor under pele', async () => {
+    const editor = new MermaidWysiwygEditor({ code: SAMPLE })
+    const view = new MermaidCanvasView({
+      editor,
+      container,
+      renderer: peleAdapter({ render: (src) => peleRender(src) }),
+      debounceMs: 0,
+    })
+    views.push(view)
+    for (let i = 0; i < 5; i++) await new Promise((r) => setTimeout(r, 0))
+    const cell = container.querySelector('text.pele-er-name[data-mw-attr-line]')!
+    expect(cell).toBeTruthy()
+    cell.dispatchEvent(new MouseEvent('dblclick', { bubbles: true, cancelable: true }))
+    // the overlay editor opened, seeded with the attribute's full line text
+    const overlay = container.querySelector('.mw-inplace-editor')!
+    expect(overlay).toBeTruthy()
+    expect(overlay.textContent).toBe('string name')
+    // commit rewrites the source through er.setAttributeText
+    overlay.textContent = 'string fullName'
+    overlay.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }))
+    expect(editor.code).toContain('string fullName')
+    // and the re-rendered svg shows the committed text, still correlated
+    for (let i = 0; i < 5; i++) await new Promise((r) => setTimeout(r, 0))
+    const renamed = container.querySelector('text.pele-er-name[data-mw-attr-line]')!
+    expect(renamed.textContent).toBe('fullName')
+    expect(renamed.getAttribute('data-mw-attr-entity')).toBe('CUSTOMER')
+  })
+
+  // Step 5 style spot-check: pele's er renderer keeps `style A fill:#f00`
+  // (verified against pele@1.13.0) — the rendered SVG must visibly change, and
+  // the styled entity must still correlate.
+  it('keeps inline style styling visible under pele', async () => {
+    const code = 'erDiagram\n  A ||--o{ B : r\n  style A fill:#f00\n'
+    const editor = new MermaidWysiwygEditor({ code })
+    const view = new MermaidCanvasView({
+      editor,
+      container,
+      renderer: peleAdapter({ render: (src) => peleRender(src) }),
+      debounceMs: 0,
+    })
+    views.push(view)
+    for (let i = 0; i < 5; i++) await new Promise((r) => setTimeout(r, 0))
+    expect(container.querySelector('svg')).toBeTruthy()
+    const rect = container.querySelector('[data-mw-entity="entity:A"] rect')
+    expect(rect).toBeTruthy()
+    expect(rect!.getAttribute('style')).toContain('fill:#f00')
+  })
+})

From e38017295fd8145bd0325d02d4d379b9ab501462 Mon Sep 17 00:00:00 2001
From: Casey Gollan <hello@caseyagollan.com>
Date: Sun, 1 Nov 2026 17:50:56 -0500
Subject: [PATCH 17/21] feat(dom): pele pie correlator

---
 packages/dom/src/correlate.pele.pie.ts       |  73 ++++++
 packages/dom/src/index.ts                    |   1 +
 packages/dom/src/view.ts                     |  17 +-
 packages/dom/test/correlate-pele-pie.test.ts | 227 +++++++++++++++++++
 packages/dom/test/correlate-pele.test.ts     |   6 +-
 5 files changed, 316 insertions(+), 8 deletions(-)
 create mode 100644 packages/dom/src/correlate.pele.pie.ts
 create mode 100644 packages/dom/test/correlate-pele-pie.test.ts

diff --git a/packages/dom/src/correlate.pele.pie.ts b/packages/dom/src/correlate.pele.pie.ts
new file mode 100644
index 0000000..01e4461
--- /dev/null
+++ b/packages/dom/src/correlate.pele.pie.ts
@@ -0,0 +1,73 @@
+import type { PieGraph } from '@visimer/core'
+import type { Correlation } from './correlate'
+import { decodeEntities } from './correlate.pele'
+
+/**
+ * Correlate pele's rendered pie SVG with the semantic graph.
+ * Strategy: data-id matching only, no order dependence — pele sorts slices by
+ * value before drawing, but BOTH the slices (`path.pele-slice[data-id=<label>]`)
+ * and the legend rows (`g.pele-legend-item[data-id=<label>]`) are keyed by the
+ * slice's DISPLAY LABEL, so the same entity id pairs both sides. pele keeps
+ * one slice per label, so two core slices sharing a display label can never be
+ * distinguished: they degrade up front, along with their legend rows, instead
+ * of the first one claiming pele's single rendered slice. A slice whose label
+ * fits no (or more than one) unclaimed path degrades to view-only rather than
+ * pairing a wrong element. A missing legend row degrades silently — the slice
+ * path is the interaction target and stays correlated.
+ */
+export function correlatePelePie(svg: SVGSVGElement, graph: PieGraph): Correlation {
+  const nodes = new Map<string, SVGGElement>()
+  const edges = new Map<string, SVGElement>()
+  const edgeLabels = new Map<string, SVGGElement>()
+  const failed: string[] = []
+
+  const dataId = (el: Element) => el.getAttribute('data-id')
+  // pele entity-encodes data-id values (`&quot;`, `&#65;`, ...) — compare the
+  // decoded label against the DOM-decoded attribute (and the raw one)
+  const matchesLabel = (el: Element, label: string) => {
+    const dom = dataId(el)
+    return dom === label || dom === decodeEntities(label)
+  }
+
+  const sliceEls = [...svg.querySelectorAll<SVGGElement>('path.pele-slice')]
+  const legendEls = [...svg.querySelectorAll<SVGGElement>('g.pele-legend-item')]
+  const claimedLegends = new Set<Element>()
+
+  // duplicate display labels are ambiguous by construction (pele renders one
+  // slice per label) — count them up front so colliding slices degrade
+  // instead of the first claiming pele's shared path
+  const labelCount = new Map<string, number>()
+  for (const s of graph.slices) {
+    const label = decodeEntities(s.label)
+    labelCount.set(label, (labelCount.get(label) ?? 0) + 1)
+  }
+
+  for (const slice of graph.slices) {
+    if ((labelCount.get(decodeEntities(slice.label)) ?? 0) > 1) {
+      // duplicate display label — degrade, never pair
+      failed.push(slice.entityId)
+      continue
+    }
+    const fits = sliceEls.filter((el) => matchesLabel(el, slice.label))
+    if (fits.length === 1) {
+      const el = fits[0]
+      nodes.set(slice.entityId, el)
+      el.setAttribute('data-mw-entity', slice.entityId)
+      // legend rows share the slice's data-id — tag them with the same
+      // entity id; a legend miss degrades silently (unmapped)
+      for (const legend of legendEls) {
+        if (!claimedLegends.has(legend) && matchesLabel(legend, slice.label)) {
+          claimedLegends.add(legend)
+          legend.setAttribute('data-mw-entity', slice.entityId)
+        }
+      }
+    } else {
+      // 0 = pele didn't render the slice (zero-value slices render nothing);
+      // >1 = pele rendered the label more than once (ambiguous) — both
+      // degrade rather than risk a wrong pairing
+      failed.push(slice.entityId)
+    }
+  }
+
+  return { nodes, edges, edgeLabels, failed }
+}
diff --git a/packages/dom/src/index.ts b/packages/dom/src/index.ts
index 2c7e9af..f731922 100644
--- a/packages/dom/src/index.ts
+++ b/packages/dom/src/index.ts
@@ -5,4 +5,5 @@ export { correlatePeleFlowchart } from './correlate.pele'
 export { correlatePeleClass } from './correlate.pele.class'
 export { correlatePeleState } from './correlate.pele.state'
 export { correlatePeleEr } from './correlate.pele.er'
+export { correlatePelePie } from './correlate.pele.pie'
 export { Popover, type PopoverAction, type PopoverPanelItem } from './popover'
diff --git a/packages/dom/src/view.ts b/packages/dom/src/view.ts
index 3f952bf..3061447 100644
--- a/packages/dom/src/view.ts
+++ b/packages/dom/src/view.ts
@@ -37,6 +37,7 @@ import { correlatePeleFlowchart } from './correlate.pele'
 import { correlatePeleClass } from './correlate.pele.class'
 import { correlatePeleState } from './correlate.pele.state'
 import { correlatePeleEr } from './correlate.pele.er'
+import { correlatePelePie } from './correlate.pele.pie'
 
 /** default swatches offered in the color panels (works on light and dark themes) */
 export const COLOR_PALETTE = ['#ef4444', '#f97316', '#eab308', '#22c55e', '#06b6d4', '#6366f1', '#d946ef', '#64748b']
@@ -918,11 +919,11 @@ export class MermaidCanvasView {
   private bindSvg() {
     const svg = this.svg
     if (!svg) return
-    const { flowchart, sequence, state, classGraph, er } = this.editor.result
+    const { flowchart, sequence, state, classGraph, er, pie } = this.editor.result
     const isPele = this.renderer.id === 'pele'
-    // Under pele, flowcharts, state, class and er diagrams correlate through
-    // their own modules; every other diagram slot stays view-only, and
-    // sequence correlation plus the visibility retry are mermaid-only.
+    // Under pele, flowcharts, state, class, er and pie diagrams correlate
+    // through their own modules; every other diagram slot stays view-only,
+    // and sequence correlation plus the visibility retry are mermaid-only.
     if (isPele) {
       this.correlation = flowchart
         ? correlatePeleFlowchart(svg, flowchart)
@@ -932,7 +933,9 @@ export class MermaidCanvasView {
             ? correlatePeleClass(svg, classGraph)
             : er
               ? correlatePeleEr(svg, er)
-              : null
+              : pie
+                ? correlatePelePie(svg, pie)
+                : null
     } else {
       this.correlation = flowchart
         ? correlateFlowchart(svg, flowchart)
@@ -942,8 +945,8 @@ export class MermaidCanvasView {
             ? correlateClass(svg, classGraph)
             : er
               ? correlateEr(svg, er)
-              : this.editor.result.pie
-                ? correlatePie(svg, this.editor.result.pie)
+              : pie
+                ? correlatePie(svg, pie)
                 : this.editor.result.gantt
                   ? correlateGantt(svg, this.editor.result.gantt)
                   : this.editor.result.lineItems
diff --git a/packages/dom/test/correlate-pele-pie.test.ts b/packages/dom/test/correlate-pele-pie.test.ts
new file mode 100644
index 0000000..f226571
--- /dev/null
+++ b/packages/dom/test/correlate-pele-pie.test.ts
@@ -0,0 +1,227 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { render as peleRender } from 'pele'
+import { MermaidWysiwygEditor, type PieGraph } from '@visimer/core'
+import { correlatePelePie } from '../src/correlate.pele.pie'
+import { MermaidCanvasView, peleAdapter } from '../src'
+
+// jsdom has no CSS.escape (browsers do)
+if (typeof (globalThis as { CSS?: unknown }).CSS === 'undefined') {
+  ;(globalThis as { CSS?: { escape(s: string): string } }).CSS = {
+    escape: (s: string) => s.replace(/[^a-zA-Z0-9_-]/g, (c) => `\\${c}`),
+  }
+}
+
+// jsdom has no canvas: pele probes for one to measure text, and jsdom's
+// getContext raises a noisy "not implemented" error. Return null so pele falls
+// back to its built-in metrics table (the assertions here are structural, not
+// pixel-precise).
+HTMLCanvasElement.prototype.getContext = (() => null) as typeof HTMLCanvasElement.prototype.getContext
+
+const hosts: HTMLElement[] = []
+
+const SAMPLE = `pie title Pets
+  "cat": 40
+  "dog": 45
+  "fish": 15
+`
+
+/** render a code string with real pele, correlate it against core's pie graph */
+function correlate(code: string) {
+  const editor = new MermaidWysiwygEditor({ code })
+  const graph = editor.result.pie
+  if (!graph) throw new Error('code did not parse as a pie chart')
+  const host = document.createElement('div')
+  document.body.appendChild(host)
+  hosts.push(host)
+  host.innerHTML = peleRender(code).svg
+  const svg = host.querySelector('svg')!
+  return { svg, graph, result: correlatePelePie(svg, graph) }
+}
+
+/** mount code through the full view with a pele adapter */
+async function mountWithView(container: HTMLElement, code: string, options?: Record<string, unknown>) {
+  const editor = new MermaidWysiwygEditor({ code })
+  const view = new MermaidCanvasView({
+    editor,
+    container,
+    renderer: peleAdapter({ render: (src, opts) => peleRender(src, opts) }, options),
+    debounceMs: 0,
+  })
+  // drain microtasks and the macrotask queue so the render lands
+  for (let i = 0; i < 5; i++) await new Promise((r) => setTimeout(r, 0))
+  return { editor, view }
+}
+
+/** minimal PieGraph for synthetic-DOM tests */
+function fakeGraph(slices: Array<{ label: string; value?: number }>): PieGraph {
+  return {
+    headerLine: 0,
+    showData: false,
+    slices: slices.map((s, i) => ({
+      entityId: `slice:${i + 1}`,
+      label: s.label,
+      value: s.value ?? 10,
+      lineIndex: i + 1,
+      labelSpan: { start: 0, end: s.label.length },
+      valueSpan: { start: 0, end: 2 },
+    })),
+    lastContentLine: slices.length,
+  } as unknown as PieGraph
+}
+
+function syntheticSvg(markup: string): SVGSVGElement {
+  const host = document.createElement('div')
+  document.body.appendChild(host)
+  hosts.push(host)
+  host.innerHTML = `<svg>${markup}</svg>`
+  return host.querySelector('svg')!
+}
+
+afterEach(() => {
+  for (const host of hosts.splice(0)) host.remove()
+})
+
+describe('correlatePelePie', () => {
+  it('correlates every slice and its legend row by data-id', () => {
+    const { result, svg, graph } = correlate(SAMPLE)
+
+    expect(graph.slices).toHaveLength(3)
+    // every slice lands on its pele-slice path — pele keys data-id by the
+    // slice's label (not core's `slice:` id), tagged with its entity id
+    for (const slice of graph.slices) {
+      const el = result.nodes.get(slice.entityId)!
+      expect(el).toBeTruthy()
+      expect(el.tagName.toLowerCase()).toBe('path')
+      expect(el.classList.contains('pele-slice')).toBe(true)
+      expect(el.getAttribute('data-id')).toBe(slice.label)
+      expect(el.getAttribute('data-mw-entity')).toBe(slice.entityId)
+      // the legend row carries the same entity id
+      const legend = svg.querySelector(`g.pele-legend-item[data-id="${slice.label}"]`)
+      expect(legend).toBeTruthy()
+      expect(legend!.getAttribute('data-mw-entity')).toBe(slice.entityId)
+    }
+    expect(result.failed).toEqual([])
+    expect(result.edges.size).toBe(0)
+    expect(result.edgeLabels.size).toBe(0)
+  })
+
+  it('matches entity-encoded labels through pele encoding', () => {
+    // pele entity-encodes data-id values; the graph label arrives encoded
+    // (`a&amp;b`), the DOM attribute decodes it (`a&b`) — compare decoded
+    const { result, svg } = correlate('pie title Enc\n  "a&amp;b": 40\n  "dog": 45\n')
+    const slice = result.nodes.get('slice:1')!
+    expect(slice).toBeTruthy()
+    // the DOM attribute decodes pele's `a&amp;b` to `a&b`
+    expect(slice.getAttribute('data-id')).toBe('a&b')
+    expect(slice.getAttribute('data-mw-entity')).toBe('slice:1')
+    const legend = [...svg.querySelectorAll('g.pele-legend-item')].find(
+      (el) => el.getAttribute('data-id') === 'a&b',
+    )!
+    expect(legend.getAttribute('data-mw-entity')).toBe('slice:1')
+    expect(result.failed).toEqual([])
+  })
+
+  it('degrades duplicate slice labels and their legend rows instead of mis-pairing', () => {
+    // two core slices share the display label "cat" — label-keyed matching is
+    // inherently ambiguous (pele keeps one slice per label), so BOTH degrade
+    // to view-only and neither slice nor its legend row is ever tagged. The
+    // unambiguous "dog" slice still correlates.
+    const { result, svg } = correlate('pie title Dup\n  "cat": 40\n  "cat": 20\n  "dog": 15\n')
+    expect(result.nodes.size).toBe(1)
+    expect(result.nodes.get('slice:3')).toBe(svg.querySelector('path.pele-slice[data-id="dog"]'))
+    expect(result.failed).toEqual(['slice:1', 'slice:2'])
+    // neither colliding slice nor its legend row is tagged
+    for (const el of svg.querySelectorAll('[data-id="cat"]')) {
+      expect(el.hasAttribute('data-mw-entity')).toBe(false)
+    }
+    expect(svg.querySelector('g.pele-legend-item[data-id="dog"]')!.getAttribute('data-mw-entity')).toBe('slice:3')
+  })
+
+  it('degrades a slice whose label fits more than one unclaimed pele path', () => {
+    // two pele paths share one data-id (should not happen on real pele
+    // output, but if a release ever duplicates them, matching by label would
+    // be ambiguous) — degrade instead of picking either
+    const svg = syntheticSvg(
+      '<g class="pele-slices">' +
+        '<path class="pele-slice" data-id="cat" d="M0,0"/>' +
+        '<path class="pele-slice" data-id="cat" d="M1,1"/>' +
+        '</g>',
+    )
+    const result = correlatePelePie(svg, fakeGraph([{ label: 'cat' }]))
+    expect(result.nodes.size).toBe(0)
+    expect(result.failed).toEqual(['slice:1'])
+    for (const el of svg.querySelectorAll('path.pele-slice')) {
+      expect(el.hasAttribute('data-mw-entity')).toBe(false)
+    }
+  })
+
+  it('degrades a slice pele never rendered a path for', () => {
+    // core has two slices, pele rendered one path (e.g. a zero-value slice is
+    // skipped by pele) — the missing one degrades to view-only, the rendered
+    // one still correlates
+    const svg = syntheticSvg('<g class="pele-slices"><path class="pele-slice" data-id="cat" d="M0,0"/></g>')
+    const result = correlatePelePie(svg, fakeGraph([{ label: 'cat' }, { label: 'dog' }]))
+    expect(result.nodes.get('slice:1')).toBeTruthy()
+    expect(result.failed).toEqual(['slice:2'])
+    expect(svg.querySelector('path.pele-slice')!.getAttribute('data-mw-entity')).toBe('slice:1')
+  })
+
+  it('never tags pele scenery outside the slice/legend selectors', () => {
+    // the empty-pie circle pele renders when no slice has a value, and the
+    // percent/label texts, are chrome — never tagged
+    const svg = syntheticSvg(
+      '<g class="pele-slices"><circle class="pele-slice" r="10"/></g>' +
+        '<g class="pele-legend"><g class="pele-legend-item" data-id="cat"><rect/></g></g>',
+    )
+    const result = correlatePelePie(svg, fakeGraph([{ label: 'cat' }]))
+    // the circle carries no data-id, so the slice degrades; the legend row is
+    // only tagged alongside its claimed slice
+    expect(result.nodes.size).toBe(0)
+    expect(result.failed).toEqual(['slice:1'])
+    expect(svg.querySelector('g.pele-legend-item')!.hasAttribute('data-mw-entity')).toBe(false)
+  })
+})
+
+describe('view dispatch', () => {
+  let container: HTMLElement
+
+  beforeEach(() => {
+    container = document.createElement('div')
+    document.body.appendChild(container)
+  })
+
+  afterEach(() => {
+    container.remove()
+  })
+
+  it('dispatches pie charts through the pele correlator', async () => {
+    const { view } = await mountWithView(container, SAMPLE)
+    expect(container.querySelector('svg')).toBeTruthy()
+    for (const label of ['cat', 'dog', 'fish'] as const) {
+      expect(container.querySelector(`path.pele-slice[data-id="${label}"][data-mw-entity]`)).toBeTruthy()
+      expect(container.querySelector(`g.pele-legend-item[data-id="${label}"][data-mw-entity]`)).toBeTruthy()
+    }
+    expect(container.querySelector('[data-mw-entity="slice:2"]')).toBeTruthy()
+    view.destroy()
+  })
+
+  // Step 5 style spot-check: pele maps mermaid's `pie1..pie8` themeVariables
+  // onto `--pele-series-1..8` (verified against pele@1.13.0) — a configured
+  // slice color must land visibly in the rendered SVG, and the styled slice
+  // must still correlate.
+  it('round-trips a configured slice color visibly under pele', async () => {
+    const { editor, view } = await mountWithView(container, SAMPLE, {
+      config: { themeVariables: { pie1: '#ff0000' } },
+    })
+    expect(container.querySelector('svg')).toBeTruthy()
+    // pele paints the series palette onto the root svg's style attribute
+    expect(container.querySelector('svg')!.getAttribute('style')).toContain('--pele-series-1:#ff0000')
+    // the styled (first) slice still correlates after the re-render
+    const styled = container.querySelector('path.pele-slice[data-id="cat"]')!
+    expect(styled).toBeTruthy()
+    expect(styled.getAttribute('data-mw-entity')).toBe('slice:1')
+    expect(editor.result.pie!.slices[0].entityId).toBe('slice:1')
+    view.destroy()
+  })
+})
diff --git a/packages/dom/test/correlate-pele.test.ts b/packages/dom/test/correlate-pele.test.ts
index c158604..c1d44cd 100644
--- a/packages/dom/test/correlate-pele.test.ts
+++ b/packages/dom/test/correlate-pele.test.ts
@@ -325,7 +325,11 @@ describe('view dispatch', () => {
   })
 
   it('renders non-flowchart slots view-only under pele', async () => {
-    const editor = new MermaidWysiwygEditor({ code: 'pie title Pets\n  "cat": 40\n  "dog": 60\n' })
+    // gantt has no pele correlator yet — pie does (correlate-pele-pie.test.ts),
+    // so the view-only fallback is pinned with a slot that still lacks one
+    const editor = new MermaidWysiwygEditor({
+      code: 'gantt\n  dateFormat YYYY-MM-DD\n  section S\n  Task :a1, 2024-01-01, 1d\n',
+    })
     const view = new MermaidCanvasView({
       editor,
       container,

From 9b57024453bbc255a40e32271baf85399a8cc6ab Mon Sep 17 00:00:00 2001
From: Casey Gollan <hello@caseyagollan.com>
Date: Sun, 1 Nov 2026 17:54:50 -0500
Subject: [PATCH 18/21] feat(dom): pele gantt correlator

---
 packages/dom/src/correlate.pele.gantt.ts      |  34 +++
 packages/dom/src/index.ts                     |   1 +
 packages/dom/src/view.ts                      |  14 +-
 .../dom/test/correlate-pele-gantt.test.ts     | 211 ++++++++++++++++++
 packages/dom/test/correlate-pele.test.ts      |   6 +-
 5 files changed, 258 insertions(+), 8 deletions(-)
 create mode 100644 packages/dom/src/correlate.pele.gantt.ts
 create mode 100644 packages/dom/test/correlate-pele-gantt.test.ts

diff --git a/packages/dom/src/correlate.pele.gantt.ts b/packages/dom/src/correlate.pele.gantt.ts
new file mode 100644
index 0000000..781e444
--- /dev/null
+++ b/packages/dom/src/correlate.pele.gantt.ts
@@ -0,0 +1,34 @@
+import type { GanttGraph } from '@visimer/core'
+import type { Correlation } from './correlate'
+
+/**
+ * Correlate pele's rendered gantt SVG with the semantic graph.
+ * Strategy: count-checked order zip only. pele renders one `g.pele-task` per
+ * task in document order (core's tasks array order) — milestones and status
+ * variants included. Core has no source ids (entities are `task:<lineIndex>`),
+ * and pele's `data-id` holds the task's mermaid source id when given or a
+ * generated `taskN` otherwise — so `data-id` is NOT a match key here, unlike
+ * the other pele correlators. A count disagreement means the zip could shift
+ * pairings — degrade every task rather than risk mis-zipping. Sections (bands
+ * and labels) and the grid are scenery core does not model — never tagged,
+ * matching mermaid's correlateGantt.
+ */
+export function correlatePeleGantt(svg: SVGSVGElement, graph: GanttGraph): Correlation {
+  const nodes = new Map<string, SVGGElement>()
+  const edges = new Map<string, SVGElement>()
+  const edgeLabels = new Map<string, SVGGElement>()
+  const failed: string[] = []
+
+  // class-filtered sweep: only g.pele-task groups participate (the grid is
+  // its own g.pele-grid group and can never be claimed)
+  const taskEls = [...svg.querySelectorAll<SVGGElement>('g.pele-task')]
+  if (taskEls.length === graph.tasks.length) {
+    graph.tasks.forEach((t, i) => {
+      nodes.set(t.entityId, taskEls[i])
+      taskEls[i].setAttribute('data-mw-entity', t.entityId)
+    })
+  } else {
+    for (const t of graph.tasks) failed.push(t.entityId)
+  }
+  return { nodes, edges, edgeLabels, failed }
+}
diff --git a/packages/dom/src/index.ts b/packages/dom/src/index.ts
index f731922..9122d59 100644
--- a/packages/dom/src/index.ts
+++ b/packages/dom/src/index.ts
@@ -6,4 +6,5 @@ export { correlatePeleClass } from './correlate.pele.class'
 export { correlatePeleState } from './correlate.pele.state'
 export { correlatePeleEr } from './correlate.pele.er'
 export { correlatePelePie } from './correlate.pele.pie'
+export { correlatePeleGantt } from './correlate.pele.gantt'
 export { Popover, type PopoverAction, type PopoverPanelItem } from './popover'
diff --git a/packages/dom/src/view.ts b/packages/dom/src/view.ts
index 3061447..1f08823 100644
--- a/packages/dom/src/view.ts
+++ b/packages/dom/src/view.ts
@@ -38,6 +38,7 @@ import { correlatePeleClass } from './correlate.pele.class'
 import { correlatePeleState } from './correlate.pele.state'
 import { correlatePeleEr } from './correlate.pele.er'
 import { correlatePelePie } from './correlate.pele.pie'
+import { correlatePeleGantt } from './correlate.pele.gantt'
 
 /** default swatches offered in the color panels (works on light and dark themes) */
 export const COLOR_PALETTE = ['#ef4444', '#f97316', '#eab308', '#22c55e', '#06b6d4', '#6366f1', '#d946ef', '#64748b']
@@ -919,11 +920,12 @@ export class MermaidCanvasView {
   private bindSvg() {
     const svg = this.svg
     if (!svg) return
-    const { flowchart, sequence, state, classGraph, er, pie } = this.editor.result
+    const { flowchart, sequence, state, classGraph, er, pie, gantt } = this.editor.result
     const isPele = this.renderer.id === 'pele'
-    // Under pele, flowcharts, state, class, er and pie diagrams correlate
-    // through their own modules; every other diagram slot stays view-only,
-    // and sequence correlation plus the visibility retry are mermaid-only.
+    // Under pele, flowcharts, state, class, er, pie and gantt diagrams
+    // correlate through their own modules; every other diagram slot stays
+    // view-only, and sequence correlation plus the visibility retry are
+    // mermaid-only.
     if (isPele) {
       this.correlation = flowchart
         ? correlatePeleFlowchart(svg, flowchart)
@@ -935,7 +937,9 @@ export class MermaidCanvasView {
               ? correlatePeleEr(svg, er)
               : pie
                 ? correlatePelePie(svg, pie)
-                : null
+                : gantt
+                  ? correlatePeleGantt(svg, gantt)
+                  : null
     } else {
       this.correlation = flowchart
         ? correlateFlowchart(svg, flowchart)
diff --git a/packages/dom/test/correlate-pele-gantt.test.ts b/packages/dom/test/correlate-pele-gantt.test.ts
new file mode 100644
index 0000000..4086688
--- /dev/null
+++ b/packages/dom/test/correlate-pele-gantt.test.ts
@@ -0,0 +1,211 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { render as peleRender } from 'pele'
+import { MermaidWysiwygEditor, type GanttGraph } from '@visimer/core'
+import { correlatePeleGantt } from '../src/correlate.pele.gantt'
+import { MermaidCanvasView, peleAdapter } from '../src'
+
+// jsdom has no canvas: pele probes for one to measure text, and jsdom's
+// getContext raises a noisy "not implemented" error. Return null so pele falls
+// back to its built-in metrics table (the assertions here are structural, not
+// pixel-precise).
+HTMLCanvasElement.prototype.getContext = (() => null) as typeof HTMLCanvasElement.prototype.getContext
+
+const hosts: HTMLElement[] = []
+
+const SAMPLE = `gantt
+  dateFormat YYYY-MM-DD
+  section Design
+  Spec: a1, 2026-01-01, 10d
+  Review: milestone, 2026-01-15, 0d
+  section Build
+  Code: 2026-01-16, 20d
+`
+
+/** render a code string with real pele, correlate it against core's gantt graph */
+function correlate(code: string) {
+  const editor = new MermaidWysiwygEditor({ code })
+  const graph = editor.result.gantt
+  if (!graph) throw new Error('code did not parse as a gantt chart')
+  const host = document.createElement('div')
+  document.body.appendChild(host)
+  hosts.push(host)
+  host.innerHTML = peleRender(code).svg
+  const svg = host.querySelector('svg')!
+  return { svg, graph, result: correlatePeleGantt(svg, graph) }
+}
+
+/** mount code through the full view with a pele adapter */
+async function mountWithView(container: HTMLElement, code: string) {
+  const editor = new MermaidWysiwygEditor({ code })
+  const view = new MermaidCanvasView({
+    editor,
+    container,
+    renderer: peleAdapter({ render: (src, opts) => peleRender(src, opts) }),
+    debounceMs: 0,
+  })
+  // drain microtasks and the macrotask queue so the render lands
+  for (let i = 0; i < 5; i++) await new Promise((r) => setTimeout(r, 0))
+  return { editor, view }
+}
+
+/** minimal GanttGraph for synthetic-DOM tests */
+function fakeGraph(taskCount: number): GanttGraph {
+  return {
+    headerLine: 0,
+    tasks: Array.from({ length: taskCount }, (_, i) => ({
+      entityId: `task:${i + 1}`,
+      name: `T${i + 1}`,
+      meta: '1d',
+      lineIndex: i + 1,
+      nameSpan: { start: 0, end: 2 },
+      metaSpan: { start: 3, end: 5 },
+      section: null,
+    })),
+    sections: [],
+    lastContentLine: taskCount,
+  } as unknown as GanttGraph
+}
+
+function syntheticSvg(markup: string): SVGSVGElement {
+  const host = document.createElement('div')
+  document.body.appendChild(host)
+  hosts.push(host)
+  host.innerHTML = `<svg>${markup}</svg>`
+  return host.querySelector('svg')!
+}
+
+afterEach(() => {
+  for (const host of hosts.splice(0)) host.remove()
+})
+
+describe('correlatePeleGantt', () => {
+  it('order-zips core tasks onto g.pele-task groups', () => {
+    const { result, svg, graph } = correlate(SAMPLE)
+
+    // core models Spec, Review (milestone) and Code as `task:<lineIndex>`
+    // entities in document order; pele renders one g.pele-task per task in
+    // the same order (milestones included)
+    expect(graph.tasks.map((t) => t.entityId)).toEqual(['task:3', 'task:4', 'task:6'])
+    const taskEls = [...svg.querySelectorAll<SVGGElement>('g.pele-task')]
+    expect(taskEls).toHaveLength(graph.tasks.length)
+    graph.tasks.forEach((task, i) => {
+      const el = result.nodes.get(task.entityId)!
+      expect(el).toBeTruthy()
+      expect(el).toBe(taskEls[i])
+      expect(el.classList.contains('pele-task')).toBe(true)
+      expect(el.getAttribute('data-mw-entity')).toBe(task.entityId)
+    })
+    // the milestone task correlates same as any other task
+    const milestone = result.nodes.get('task:4')!
+    expect(milestone.classList.contains('pele-milestone')).toBe(true)
+    expect(result.failed).toEqual([])
+    expect(result.edges.size).toBe(0)
+    expect(result.edgeLabels.size).toBe(0)
+  })
+
+  it('never tags scenery: sections, section labels and gridlines', () => {
+    const { result, svg } = correlate(SAMPLE)
+    expect(result.nodes.size).toBe(3)
+    // pele draws section bands, their labels and the grid as scenery — core
+    // does not model sections as entities, so none of it is ever tagged
+    for (const el of svg.querySelectorAll(
+      'rect.pele-section, text.pele-section-label, g.pele-grid, g.pele-grid *',
+    )) {
+      expect(el.hasAttribute('data-mw-entity')).toBe(false)
+    }
+  })
+
+  it('degrades every task when pele drops one (count mismatch)', () => {
+    // core has three tasks, pele rendered two groups (e.g. pele skipped a
+    // task) — a zip would shift every later pairing, so ALL tasks degrade to
+    // view-only instead of mis-correlating
+    const svg = syntheticSvg(
+      '<g class="pele-tasks">' +
+        '<g class="pele-task" data-id="a1"></g>' +
+        '<g class="pele-task" data-id="task1"></g>' +
+        '</g>',
+    )
+    const result = correlatePeleGantt(svg, fakeGraph(3))
+    expect(result.nodes.size).toBe(0)
+    expect(result.failed).toEqual(['task:1', 'task:2', 'task:3'])
+    for (const el of svg.querySelectorAll('g.pele-task')) {
+      expect(el.hasAttribute('data-mw-entity')).toBe(false)
+    }
+  })
+
+  it('degrades every task when pele renders more groups than core tasks', () => {
+    const svg = syntheticSvg(
+      '<g class="pele-tasks">' +
+        '<g class="pele-task" data-id="a1"></g>' +
+        '<g class="pele-task" data-id="a2"></g>' +
+        '</g>',
+    )
+    const result = correlatePeleGantt(svg, fakeGraph(1))
+    expect(result.nodes.size).toBe(0)
+    expect(result.failed).toEqual(['task:1'])
+    for (const el of svg.querySelectorAll('g.pele-task')) {
+      expect(el.hasAttribute('data-mw-entity')).toBe(false)
+    }
+  })
+
+  it('class-filters the sweep: non-task lookalikes are never claimed', () => {
+    // a milestone variant plus a stray non-task element that carries a
+    // pele-task-looking data-id — only g.pele-task groups participate
+    const svg = syntheticSvg(
+      '<g class="pele-grid"><g data-id="a1"></g></g>' +
+        '<g class="pele-tasks"><g class="pele-task pele-milestone" data-id="a1"></g></g>',
+    )
+    const result = correlatePeleGantt(svg, fakeGraph(1))
+    expect(result.nodes.get('task:1')).toBe(svg.querySelector('g.pele-task'))
+    expect(result.failed).toEqual([])
+  })
+
+  // Step 5 style spot-check: task status flags land as classes on the
+  // g.pele-task group itself (verified against pele@1.13.0) — a status edit
+  // must round-trip visibly as a class change, and the styled task must still
+  // correlate after the re-render.
+  it('round-trips a task status op visibly and keeps the task correlated', () => {
+    const { result, svg } = correlate(`gantt
+  dateFormat YYYY-MM-DD
+  section S
+  A: done, a1, 2026-01-01, 5d
+  B: active, 2026-01-02, 5d
+  C: crit, 2026-01-03, 5d
+`)
+    expect(result.nodes.size).toBe(3)
+    expect(result.nodes.get('task:3')!.classList.contains('pele-done')).toBe(true)
+    expect(result.nodes.get('task:4')!.classList.contains('pele-active')).toBe(true)
+    expect(result.nodes.get('task:5')!.classList.contains('pele-crit')).toBe(true)
+    // every styled task group is still tagged with its entity id
+    for (const el of svg.querySelectorAll('g.pele-task')) {
+      expect(el.getAttribute('data-mw-entity')).toBeTruthy()
+    }
+  })
+})
+
+describe('view dispatch', () => {
+  let container: HTMLElement
+
+  beforeEach(() => {
+    container = document.createElement('div')
+    document.body.appendChild(container)
+  })
+
+  afterEach(() => {
+    container.remove()
+  })
+
+  it('dispatches gantt charts through the pele correlator', async () => {
+    const { view } = await mountWithView(container, SAMPLE)
+    expect(container.querySelector('svg')).toBeTruthy()
+    const taskEls = container.querySelectorAll('g.pele-task[data-mw-entity]')
+    expect(taskEls.length).toBeGreaterThan(0)
+    expect(container.querySelector('[data-mw-entity="task:3"]')).toBeTruthy()
+    expect(container.querySelector('[data-mw-entity="task:6"]')).toBeTruthy()
+    // scenery stays untagged through the full view too
+    expect(container.querySelector('rect.pele-section[data-mw-entity]')).toBeNull()
+    expect(container.querySelector('g.pele-grid[data-mw-entity]')).toBeNull()
+    view.destroy()
+  })
+})
diff --git a/packages/dom/test/correlate-pele.test.ts b/packages/dom/test/correlate-pele.test.ts
index c1d44cd..8aa3b6b 100644
--- a/packages/dom/test/correlate-pele.test.ts
+++ b/packages/dom/test/correlate-pele.test.ts
@@ -325,10 +325,10 @@ describe('view dispatch', () => {
   })
 
   it('renders non-flowchart slots view-only under pele', async () => {
-    // gantt has no pele correlator yet — pie does (correlate-pele-pie.test.ts),
-    // so the view-only fallback is pinned with a slot that still lacks one
+    // sequence has no pele correlator (its correlation is mermaid-only) —
+    // the view-only fallback is pinned with a slot that still lacks one
     const editor = new MermaidWysiwygEditor({
-      code: 'gantt\n  dateFormat YYYY-MM-DD\n  section S\n  Task :a1, 2024-01-01, 1d\n',
+      code: 'sequenceDiagram\n  Alice->>Bob: Hi\n',
     })
     const view = new MermaidCanvasView({
       editor,

From 91d1e25fb4589c63c7841727800ee9541ae65de7 Mon Sep 17 00:00:00 2001
From: Casey Gollan <hello@caseyagollan.com>
Date: Sun, 1 Nov 2026 18:14:10 -0500
Subject: [PATCH 19/21] feat(dom): pele line-items correlator

---
 packages/dom/src/correlate.pele.lineitems.ts  | 347 +++++++++++
 packages/dom/src/index.ts                     |   1 +
 packages/dom/src/view.ts                      |  15 +-
 .../dom/test/correlate-pele-lineitems.test.ts | 579 ++++++++++++++++++
 4 files changed, 936 insertions(+), 6 deletions(-)
 create mode 100644 packages/dom/src/correlate.pele.lineitems.ts
 create mode 100644 packages/dom/test/correlate-pele-lineitems.test.ts

diff --git a/packages/dom/src/correlate.pele.lineitems.ts b/packages/dom/src/correlate.pele.lineitems.ts
new file mode 100644
index 0000000..15d22ce
--- /dev/null
+++ b/packages/dom/src/correlate.pele.lineitems.ts
@@ -0,0 +1,347 @@
+import type { LineItem, LineItemsGraph } from '@visimer/core'
+import type { Correlation } from './correlate'
+import { decodeEntities } from './correlate.pele'
+
+/**
+ * Per-type match surface, pinned by probing pele@1.13.0 with the playground
+ * sample strings (probe preserved alongside the task brief). Each type lists
+ * the class-filtered candidate groups a line item may anchor to; pele reuses
+ * class names across semantic layers, so a bare `[data-id]` sweep is never
+ * safe (gantt lesson).
+ *
+ * Match strategy per item: first-class `data-id` compare (with
+ * `decodeEntities`) where pele stamps a meaningful id; a text fallback against
+ * the group's OWN label texts for groups whose data-id is a generated or
+ * unrelated id (kanban card ids, packet bit ranges, timeline events, radar
+ * legends, c4 display names, ...); optionally standalone text elements
+ * (diagram titles, which pele renders outside any candidate group).
+ */
+interface TypeSurface {
+  /** candidate anchor groups, class-filtered */
+  selectors: string[]
+  /** also allow title-like text elements outside any candidate group */
+  standaloneText?: boolean
+  /** derive an extra data-id key from the source line (sankey `A->B` links) */
+  linkKeys?: 'sankey'
+}
+
+const SURFACES: Record<string, TypeSurface> = {
+  // cards g.pele-node.pele-card[data-id=<cardId|label>], columns
+  // g.pele-cluster.pele-column[data-id] — card labels wrap across several
+  // text.pele-label elements; column labels are text.pele-cluster-label (card
+  // labels nest inside the column group)
+  kanban: { selectors: ['g.pele-node.pele-card', 'g.pele-cluster.pele-column'] },
+  // commits g.pele-commit.pele-commit-<kind>[data-id=<commitId|generated>],
+  // branches g.pele-branch[data-id] — commit circles also show their id as text
+  gitgraph: { selectors: ['g.pele-commit', 'g.pele-branch'] },
+  // tasks g.pele-node.pele-task[data-id=<taskText>], sections
+  // g.pele-cluster.pele-section[data-id], title text.pele-title (no data-id,
+  // outside any group)
+  journey: { selectors: ['g.pele-node.pele-task', 'g.pele-cluster.pele-section'], standaloneText: true },
+  // periods g.pele-node.pele-period[data-id=<periodText>]; events carry NO
+  // data-id (their label text is the only surface) and nest inside periods
+  timeline: { selectors: ['g.pele-node.pele-period', 'g.pele-node.pele-event'], standaloneText: true },
+  // links path.pele-sankey-link[data-id=<A>-><B>]; node rects/labels are node
+  // scenery a link line must not claim (its matchText is only the source name)
+  sankey: { selectors: ['path.pele-sankey-link'], linkKeys: 'sankey' },
+  // nodes g.pele-node[data-id=<nodeText>], except the root: pele stamps
+  // data-id="root" and the label text carries the actual root label
+  mindmap: { selectors: ['g.pele-node'] },
+  // sections/leaves g.pele-node.pele-section|pele-leaf[data-id=<name>]
+  treemap: { selectors: ['g.pele-node'] },
+  // fields g.pele-node[data-id=<bit range>] with the field name as label text
+  packet: { selectors: ['g.pele-node'] },
+  // axis labels g.pele-axis-label[data-id=<axisId>] (text = axis name), curve
+  // legends g.pele-legend-item[data-id=<curveId>] (text = curve name); curve
+  // paths carry data-id only, never a match text — not matchable
+  radar: { selectors: ['g.pele-axis-label', 'g.pele-legend-item'] },
+  // only the title line has a matchable surface: text.pele-title, standalone
+  xychart: { selectors: [], standaloneText: true },
+  // services g.pele-node.pele-service[data-id=<serviceId>] (label text = display
+  // name), groups g.pele-cluster[data-id=<groupId>] (label text = display name)
+  architecture: { selectors: ['g.pele-node.pele-service', 'g.pele-cluster'] },
+  // requirements/elements g.pele-node.pele-requirement|pele-element[data-id=<name>]
+  requirement: { selectors: ['g.pele-node'] },
+  // c4 nodes g.pele-node[data-id=<actorId>] with the display name as label text;
+  // Rel labels are not item surfaces (duplicate texts degrade anyway)
+  c4: { selectors: ['g.pele-node'] },
+  // blocks g.pele-node[data-id=<blockId>] (shaped blocks show their label text),
+  // container blocks g.pele-cluster[data-id]
+  block: { selectors: ['g.pele-node', 'g.pele-cluster'] },
+  // points circle.pele-point[data-id=<pointText>]; quadrant tiles are scenery
+  quadrant: { selectors: ['circle.pele-point'] },
+}
+
+/**
+ * Collapse ascii whitespace and trim it from the ends — with an ASCII-only
+ * charset, because NBSP is CONTENT here: block diagram labels are `&nbsp;`
+ * runs, and a bare `.trim()` would strip them (it treats \u00a0 as whitespace).
+ */
+function norm(s: string): string {
+  return s.replace(/[\t\n\f\r ]+/g, ' ').replace(/^[\t\n\f\r ]+|[\t\n\f\r ]+$/g, '')
+}
+
+/** normalized DOM attribute / text — the parser has already decoded entities */
+function domKey(s: string | null): string | null {
+  return s === null ? null : norm(s)
+}
+
+/** normalized graph-side key — pele bakes entity encodings into source ids */
+function graphKey(s: string): string {
+  // `&nbsp;` is a real character in labels (block diagram `&nbsp;` runs), but
+  // the shared decodeEntities pins it as pass-through (its data-id contract is
+  // tested) — decode it here first. `&amp;nbsp;` is unaffected: the replace
+  // never matches it and the shared decoder restores the literal.
+  return norm(decodeEntities(s.replace(/&nbsp;/g, '\u00a0')))
+}
+
+/**
+ * Parse the first two CSV fields of a sankey-beta line into pele's link
+ * data-id `<A>-><B>`. Handles double-quoted fields (commas inside quotes);
+ * single-quoted names stay verbatim — pele keeps them in the data-id too.
+ */
+function sankeyLinkKey(text: string): string | null {
+  const fields: string[] = []
+  let i = 0
+  while (i < text.length && fields.length < 2) {
+    if (text[i] === '"') {
+      const end = text.indexOf('"', i + 1)
+      if (end === -1) return null
+      fields.push(text.slice(i + 1, end))
+      const comma = text.indexOf(',', end)
+      if (comma === -1) break
+      i = comma + 1
+    } else {
+      const end = text.indexOf(',', i)
+      if (end === -1) {
+        fields.push(text.slice(i))
+        break
+      }
+      fields.push(text.slice(i, end))
+      i = end + 1
+    }
+  }
+  const [src, tgt] = fields
+  return src && tgt ? `${norm(src)}->${norm(tgt)}` : null
+}
+
+interface Candidate {
+  el: Element
+  dataId: string | null
+  /** normalized label text (per label class, joined for wrapped labels) → a representative text element */
+  textKeys: Map<string, Element>
+}
+
+/**
+ * pele wraps long labels two ways: as sibling text elements (kanban cards)
+ * and as tspans inside one text element (c4 nodes — where the wrap point
+ * swallows the space: "Banking" | "System" concatenates to "BankingSystem").
+ * Re-insert the separator on both wrap kinds, then normalize.
+ */
+function textElementContent(t: Element): string {
+  const tspans = t.querySelectorAll('tspan')
+  return tspans.length ? [...tspans].map((ts) => ts.textContent ?? '').join(' ') : (t.textContent ?? '')
+}
+
+/**
+ * Collect a candidate group's OWN label keys: descendant `text` elements whose
+ * closest candidate ancestor is the group itself. Card labels nest inside
+ * kanban columns and event texts inside timeline periods — the innermost group
+ * owns its texts, so a container can never claim a nested item's label.
+ * Wrapped labels (same-class text siblings, or tspans within one text) are
+ * re-joined per class with spaces.
+ */
+function textKeysOf(el: Element, allSelectors: string): Map<string, Element> {
+  const byClass = new Map<string, Element[]>()
+  for (const t of el.querySelectorAll('text')) {
+    if (t.closest(allSelectors) !== el) continue
+    const cls = t.getAttribute('class') ?? ''
+    const list = byClass.get(cls) ?? []
+    list.push(t)
+    byClass.set(cls, list)
+  }
+  const keys = new Map<string, Element>()
+  for (const [cls, texts] of byClass) {
+    const joined = norm(texts.map(textElementContent).join(' '))
+    if (joined) keys.set(joined, texts[0])
+  }
+  return keys
+}
+
+/**
+ * Tag a hit and re-enable pointer events exactly like mermaid's
+ * correlateLineItems: an explicit 'auto' wins over an ancestor 'none'.
+ */
+function claim(el: Element, entityId: string, textEl: Element | null): void {
+  el.setAttribute('data-mw-entity', entityId)
+  if (textEl && textEl !== el) textEl.setAttribute('data-mw-entity', entityId)
+  for (const target of new Set([el, textEl].filter((t): t is Element => t !== null))) {
+    const style = (target as HTMLElement | SVGElement).style
+    if (style) style.pointerEvents = 'auto'
+  }
+}
+
+/**
+ * Correlate pele's rendered line-item SVGs (the long tail of chart-style
+ * diagram types) with the semantic graph. Mermaid's generic correlator matches
+ * `item.matchText` against leaf text elements and re-enables pointer-events on
+ * hits; this port keeps that approach but prefers pele's first-class
+ * `data-id` stamps and degrades instead of mis-pairing:
+ *
+ * - an item whose match key is shared by several items degrades (duplicate
+ *   item text is unverifiable against the DOM — both sides go view-only);
+ * - an item whose key matches several unclaimed candidates is ambiguous and
+ *   degrades;
+ * - a candidate already claimed by another item can never be claimed twice.
+ */
+export function correlatePeleLineItems(svg: SVGSVGElement, graph: LineItemsGraph): Correlation {
+  const nodes = new Map<string, SVGGElement>()
+  const edges = new Map<string, SVGElement>()
+  const edgeLabels = new Map<string, SVGGElement>()
+  const failed: string[] = []
+
+  const surface = SURFACES[graph.typeId] ?? { selectors: ['g.pele-node', 'g.pele-cluster'] }
+
+  // --- candidates: one class-filtered sweep per surface selector
+  const allSelectors = surface.selectors.join(', ')
+  const candidateEls = new Set<Element>()
+  for (const sel of surface.selectors) {
+    for (const el of svg.querySelectorAll<Element>(sel)) candidateEls.add(el)
+  }
+  const candidates: Candidate[] = [...candidateEls].map((el) => ({
+    el,
+    dataId: domKey(el.getAttribute('data-id')),
+    textKeys: allSelectors ? textKeysOf(el, allSelectors) : new Map(),
+  }))
+  const claimed = new Set<Element>()
+
+  // --- per-item keys. matchText drives the data-id and text passes; sankey
+  // items additionally derive their exact link key from the source line.
+  const itemKeys = new Map<string, string[]>()
+  for (const item of graph.items) {
+    const keys: string[] = []
+    if (surface.linkKeys === 'sankey') {
+      const link = sankeyLinkKey(item.text)
+      if (link) keys.push(norm(link))
+    }
+    if (item.matchText) keys.push(graphKey(item.matchText))
+    itemKeys.set(item.entityId, keys)
+  }
+
+  // items that matched (anchor) or finally degraded; unresolved items still
+  // try their keys on the next pass
+  const anchors = new Map<string, Element>()
+  const resolved = new Set<string>()
+
+  /** key → unresolved items presenting it on this pass */
+  const itemsByKey = (presented: (item: LineItem) => string[]): Map<string, LineItem[]> => {
+    const map = new Map<string, LineItem[]>()
+    for (const item of graph.items) {
+      if (resolved.has(item.entityId)) continue
+      for (const key of presented(item)) {
+        const list = map.get(key) ?? []
+        list.push(item)
+        map.set(key, list)
+      }
+    }
+    return map
+  }
+
+  /**
+   * Run one matching pass. `finder` returns the unclaimed candidate hits whose
+   * key equals `key`. An item resolves when any of its keys matches uniquely;
+   * duplicate-item keys and multi-candidate keys block (degrade) instead of
+   * guessing. The key→items snapshot is taken at pass start and does not
+   * re-consult `resolved` mid-pass, so an item blocked by a duplicate key can
+   * still be rescued by one of its distinct keys later in the same pass
+   * (sankey: four lines share the source name "Bio-conversion" but each has a
+   * unique `A->B` link key) — the duplicate marking alone never claims
+   * anything, so the outcome is order-independent and never mis-pairs.
+   */
+  const runPass = (
+    presented: (item: LineItem) => string[],
+    finder: (key: string) => Array<{ el: Element; textEl: Element | null }>,
+  ): void => {
+    for (const [key, items] of itemsByKey(presented)) {
+      if (items.length > 1) {
+        // duplicate item text within one type: degrade BOTH sides — zipping
+        // identical labels against identical groups is unverifiable
+        for (const item of items) resolved.add(item.entityId)
+        continue
+      }
+      const item = items[0]
+      const hits = finder(key)
+      if (hits.length === 0) continue // key miss — a later pass may still find it
+      if (hits.length > 1 || claimed.has(hits[0].el)) {
+        // ambiguous surface, or the only matching element is already another
+        // item's — never guess, never double-tag
+        resolved.add(item.entityId)
+        continue
+      }
+      const hit = hits[0]
+      claimed.add(hit.el)
+      claim(hit.el, item.entityId, hit.textEl)
+      anchors.set(item.entityId, hit.el)
+      resolved.add(item.entityId)
+    }
+  }
+
+  // pass 1: first-class data-id compare (raw or entity-decoded)
+  runPass(
+    (item) => itemKeys.get(item.entityId) ?? [],
+    (key) =>
+      candidates
+        .filter((c) => !claimed.has(c.el) && (c.dataId === key || c.dataId === graphKey(key)))
+        .map((c) => ({ el: c.el, textEl: null })),
+  )
+
+  // pass 2: text fallback against the candidates' own label texts
+  runPass(
+    (item) => (item.matchText ? [graphKey(item.matchText)] : []),
+    (key) => {
+      const hits: Array<{ el: Element; textEl: Element | null }> = []
+      for (const c of candidates) {
+        if (claimed.has(c.el)) continue
+        const textEl = c.textKeys.get(key)
+        if (textEl) hits.push({ el: c.el, textEl })
+      }
+      return hits
+    },
+  )
+
+  // pass 3: standalone texts (titles) — text elements outside any candidate
+  // group, anchored to a small enclosing group exactly like mermaid's
+  // correlateLineItems
+  if (surface.standaloneText) {
+    const standalone: Array<{ el: Element; anchor: Element; key: string }> = []
+    for (const t of svg.querySelectorAll('text')) {
+      if (allSelectors && t.closest(allSelectors) !== null) continue
+      const key = domKey(textElementContent(t))
+      if (!key) continue
+      const parent = t.closest('g')
+      const anchor =
+        parent && parent !== svg && (parent.textContent?.trim().length ?? 0) <= key.length + 24
+          ? parent
+          : t
+      standalone.push({ el: t, anchor, key })
+    }
+    runPass(
+      (item) => (item.matchText ? [graphKey(item.matchText)] : []),
+      (key) =>
+        standalone
+          .filter((s) => !claimed.has(s.anchor) && s.key === key)
+          .map((s) => ({ el: s.anchor, textEl: s.el })),
+    )
+  }
+
+  for (const item of graph.items) {
+    const anchor = anchors.get(item.entityId)
+    if (anchor) {
+      nodes.set(item.entityId, anchor as SVGGElement)
+    } else {
+      failed.push(item.entityId)
+    }
+  }
+
+  return { nodes, edges, edgeLabels, failed }
+}
diff --git a/packages/dom/src/index.ts b/packages/dom/src/index.ts
index 9122d59..8304912 100644
--- a/packages/dom/src/index.ts
+++ b/packages/dom/src/index.ts
@@ -7,4 +7,5 @@ export { correlatePeleState } from './correlate.pele.state'
 export { correlatePeleEr } from './correlate.pele.er'
 export { correlatePelePie } from './correlate.pele.pie'
 export { correlatePeleGantt } from './correlate.pele.gantt'
+export { correlatePeleLineItems } from './correlate.pele.lineitems'
 export { Popover, type PopoverAction, type PopoverPanelItem } from './popover'
diff --git a/packages/dom/src/view.ts b/packages/dom/src/view.ts
index 1f08823..3019dd5 100644
--- a/packages/dom/src/view.ts
+++ b/packages/dom/src/view.ts
@@ -39,6 +39,7 @@ import { correlatePeleState } from './correlate.pele.state'
 import { correlatePeleEr } from './correlate.pele.er'
 import { correlatePelePie } from './correlate.pele.pie'
 import { correlatePeleGantt } from './correlate.pele.gantt'
+import { correlatePeleLineItems } from './correlate.pele.lineitems'
 
 /** default swatches offered in the color panels (works on light and dark themes) */
 export const COLOR_PALETTE = ['#ef4444', '#f97316', '#eab308', '#22c55e', '#06b6d4', '#6366f1', '#d946ef', '#64748b']
@@ -920,12 +921,12 @@ export class MermaidCanvasView {
   private bindSvg() {
     const svg = this.svg
     if (!svg) return
-    const { flowchart, sequence, state, classGraph, er, pie, gantt } = this.editor.result
+    const { flowchart, sequence, state, classGraph, er, pie, gantt, lineItems } = this.editor.result
     const isPele = this.renderer.id === 'pele'
-    // Under pele, flowcharts, state, class, er, pie and gantt diagrams
-    // correlate through their own modules; every other diagram slot stays
-    // view-only, and sequence correlation plus the visibility retry are
-    // mermaid-only.
+    // Under pele, flowcharts, state, class, er, pie, gantt and the line-item
+    // chart types correlate through their own modules; every other diagram
+    // slot stays view-only, and sequence correlation plus the visibility
+    // retry are mermaid-only.
     if (isPele) {
       this.correlation = flowchart
         ? correlatePeleFlowchart(svg, flowchart)
@@ -939,7 +940,9 @@ export class MermaidCanvasView {
                 ? correlatePelePie(svg, pie)
                 : gantt
                   ? correlatePeleGantt(svg, gantt)
-                  : null
+                  : lineItems
+                    ? correlatePeleLineItems(svg, lineItems)
+                    : null
     } else {
       this.correlation = flowchart
         ? correlateFlowchart(svg, flowchart)
diff --git a/packages/dom/test/correlate-pele-lineitems.test.ts b/packages/dom/test/correlate-pele-lineitems.test.ts
new file mode 100644
index 0000000..466cfa4
--- /dev/null
+++ b/packages/dom/test/correlate-pele-lineitems.test.ts
@@ -0,0 +1,579 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { render as peleRender } from 'pele'
+import { MermaidWysiwygEditor, type LineItemsGraph } from '@visimer/core'
+import { correlatePeleLineItems } from '../src/correlate.pele.lineitems'
+import { MermaidCanvasView, peleAdapter } from '../src'
+
+// jsdom has no CSS.escape (browsers do)
+if (typeof (globalThis as { CSS?: unknown }).CSS === 'undefined') {
+  ;(globalThis as { CSS?: { escape(s: string): string } }).CSS = {
+    escape: (s: string) => s.replace(/[^a-zA-Z0-9_-]/g, (c) => `\\${c}`),
+  }
+}
+
+// jsdom has no canvas: pele probes for one to measure text, and jsdom's
+// getContext raises a noisy "not implemented" error. Return null so pele falls
+// back to its built-in metrics table (the assertions here are structural, not
+// pixel-precise).
+HTMLCanvasElement.prototype.getContext = (() => null) as typeof HTMLCanvasElement.prototype.getContext
+
+const hosts: HTMLElement[] = []
+
+// playground sample strings (apps/js-playground/src/samples.ts) — core-parseable
+// and pele-renderable; the selectors below are pinned by probing pele@1.13.0
+// with exactly these strings (see task-6 report).
+const SAMPLES: Record<string, string> = {
+  kanban: `kanban
+  Todo
+    [Create Documentation]
+    docs[Create Blog about the new diagram]
+  [In progress]
+    id6[Create renderer so that it works in all cases]
+  id9[Ready for deploy]
+    id8[Design grammar]
+`,
+  gitgraph: `gitGraph
+  commit
+  commit
+  branch develop
+  checkout develop
+  commit
+  commit
+  checkout main
+  merge develop
+  commit
+`,
+  journey: `journey
+  title My working day
+  section Go to work
+    Make tea: 5: Me
+    Go upstairs: 3: Me
+    Do work: 1: Me, Cat
+  section Go home
+    Go downstairs: 5: Me
+    Sit down: 5: Me
+`,
+  timeline: `timeline
+  title History of Social Media Platform
+  2002 : LinkedIn
+  2004 : Facebook
+       : Google
+  2005 : YouTube
+  2006 : Twitter
+`,
+  sankey: `sankey-beta
+Agricultural 'waste',Bio-conversion,124.729
+Bio-conversion,Liquid,0.597
+Bio-conversion,Losses,26.862
+Bio-conversion,Solid,280.322
+Bio-conversion,Gas,81.144
+`,
+  mindmap: `mindmap
+  root((visimer))
+    Parsing
+      Lossless CST
+      Statement classifier
+    Editing
+      Semantic ops
+      Minimal diffs
+    Rendering
+      Mermaid SVG
+      Interaction overlay
+`,
+  treemap: `treemap-beta
+"Products"
+    "Electronics"
+        "Phones": 50
+        "Laptops": 30
+    "Furniture"
+        "Chairs": 20
+        "Tables": 15
+`,
+  packet: `packet-beta
+0-15: "Source Port"
+16-31: "Destination Port"
+32-63: "Sequence Number"
+64-95: "Acknowledgment Number"
+`,
+  radar: `radar-beta
+  title Grades
+  axis m["Math"], s["Science"], e["English"]
+  axis h["History"], g["Geography"], a["Art"]
+  curve alice["Alice"]{85, 90, 80, 70, 75, 90}
+  curve bob["Bob"]{70, 75, 85, 80, 90, 85}
+  max 100
+  min 0
+`,
+  xychart: `xychart-beta
+  title "Sales Revenue"
+  x-axis [jan, feb, mar, apr, may, jun]
+  y-axis "Revenue (in $)" 4000 --> 11000
+  bar [5000, 6000, 7500, 8200, 9500, 10500]
+  line [5000, 6000, 7500, 8200, 9500, 10500]
+`,
+  architecture: `architecture-beta
+  group api(cloud)[API]
+
+  service db(database)[Database] in api
+  service disk1(disk)[Storage] in api
+  service disk2(disk)[Storage] in api
+  service server(server)[Server] in api
+
+  db:L -- R:server
+  disk1:T -- B:server
+  disk2:T -- B:db
+`,
+  requirement: `requirementDiagram
+  requirement test_req {
+    id: 1
+    text: the test text.
+    risk: high
+    verifymethod: test
+  }
+  element test_entity {
+    type: simulation
+  }
+  test_entity - satisfies -> test_req
+`,
+  c4: `C4Context
+  title System Context diagram for Internet Banking System
+  Person(customerA, "Banking Customer A", "A customer of the bank.")
+  System(SystemAA, "Internet Banking System", "Allows customers to check accounts.")
+  System_Ext(SystemE, "Mainframe Banking System", "Stores core banking information.")
+  Rel(customerA, SystemAA, "Uses")
+  Rel(SystemAA, SystemE, "Uses")
+`,
+  block: `block-beta
+columns 1
+  db(("DB"))
+  blockArrowId6<["&nbsp;&nbsp;&nbsp;"]>(down)
+  block:ID
+    A
+    B["A wide one in the middle"]
+    C
+  end
+  space
+  D
+  ID --> D
+  C --> D
+  style B fill:#969,stroke:#333,stroke-width:4px
+`,
+  quadrant: `quadrantChart
+  title Reach and engagement of campaigns
+  x-axis Low Reach --> High Reach
+  y-axis Low Engagement --> High Engagement
+  quadrant-1 We should expand
+  quadrant-2 Need to promote
+  quadrant-3 Re-evaluate
+  quadrant-4 May be improved
+  Campaign A: [0.3, 0.6]
+  Campaign B: [0.45, 0.23]
+  Campaign C: [0.57, 0.69]
+`,
+}
+
+/** render a code string with real pele, correlate it against core's lineItems graph */
+function correlate(code: string) {
+  const editor = new MermaidWysiwygEditor({ code })
+  const graph = editor.result.lineItems
+  if (!graph) throw new Error('code did not produce a lineItems graph')
+  const host = document.createElement('div')
+  document.body.appendChild(host)
+  hosts.push(host)
+  host.innerHTML = peleRender(code).svg
+  const svg = host.querySelector('svg')!
+  return { svg, graph, result: correlatePeleLineItems(svg, graph) }
+}
+
+/** item ids for 1-based source lines (entity ids are `item:<lineIndex>`) */
+const ids = (from: number, to: number) =>
+  Array.from({ length: to - from + 1 }, (_, i) => `item:${from + i}`)
+
+/** mount code through the full view with a pele adapter */
+async function mountWithView(container: HTMLElement, code: string) {
+  const editor = new MermaidWysiwygEditor({ code })
+  const view = new MermaidCanvasView({
+    editor,
+    container,
+    renderer: peleAdapter({ render: (src, opts) => peleRender(src, opts) }),
+    debounceMs: 0,
+  })
+  // drain microtasks and the macrotask queue so the render lands
+  for (let i = 0; i < 5; i++) await new Promise((r) => setTimeout(r, 0))
+  return { editor, view }
+}
+
+function syntheticSvg(markup: string): SVGSVGElement {
+  const host = document.createElement('div')
+  document.body.appendChild(host)
+  hosts.push(host)
+  host.innerHTML = `<svg>${markup}</svg>`
+  return host.querySelector('svg')!
+}
+
+function fakeGraph(typeId: string, items: Array<{ id: string; matchText: string | null }>): LineItemsGraph {
+  return {
+    typeId,
+    headerLine: 0,
+    items: items.map((it, i) => ({
+      entityId: it.id,
+      text: it.matchText ?? `line ${i}`,
+      matchText: it.matchText,
+      lineIndex: i + 1,
+    })),
+    lastContentLine: items.length,
+    addTemplate: 'x',
+  } as unknown as LineItemsGraph
+}
+
+afterEach(() => {
+  for (const host of hosts.splice(0)) host.remove()
+})
+
+describe('correlatePeleLineItems — per-type fixtures (playground samples, pele@1.13.0 surface)', () => {
+  it('kanban: cards and columns by data-id, id-less cards and bracket columns by label text', () => {
+    const { result, svg, graph } = correlate(SAMPLES.kanban)
+    // 7 statement lines, every one has a matchText
+    expect(graph.items.map((i) => i.entityId)).toEqual(ids(1, 7))
+    expect(result.failed).toEqual([])
+    expect(result.nodes.size).toBe(7)
+    // column by data-id (item text "Todo" == column id)
+    expect(result.nodes.get('item:1')!.getAttribute('data-id')).toBe('Todo')
+    // card with no explicit id: the label IS the id
+    expect(result.nodes.get('item:2')!.getAttribute('data-id')).toBe('Create Documentation')
+    // card `docs[...]`: data-id is the card id, the label text wraps across
+    // two text.pele-label elements — matched via the joined label text
+    expect(result.nodes.get('item:3')!.getAttribute('data-id')).toBe('docs')
+    // bracket column `[In progress]`
+    expect(result.nodes.get('item:4')!.getAttribute('data-id')).toBe('In progress')
+    // wrapped label across two lines again
+    expect(result.nodes.get('item:5')!.getAttribute('data-id')).toBe('id6')
+    // `id9[Ready for deploy]` renders as a COLUMN whose visible label is the
+    // bracket text (data-id is the card id) — matched via its cluster label
+    expect(result.nodes.get('item:6')!.classList.contains('pele-column')).toBe(true)
+    expect(result.nodes.get('item:7')!.getAttribute('data-id')).toBe('id8')
+    // mermaid parity: hits get pointer-events re-enabled
+    expect(result.nodes.get('item:2')!.style.pointerEvents).toBe('auto')
+    // card counts (text.pele-count) and nothing else outside the groups is tagged
+    for (const el of svg.querySelectorAll('text.pele-count')) {
+      expect(el.hasAttribute('data-mw-entity')).toBe(false)
+    }
+  })
+
+  it('gitgraph: unique branch references match g.pele-branch; repeated references and id-less commits degrade', () => {
+    const { result, svg, graph } = correlate(SAMPLES.gitgraph)
+    // items: commits (null matchText), branch/checkout/merge (branch name)
+    expect(graph.items.map((i) => i.entityId)).toEqual(ids(1, 9))
+    // `checkout main` is the ONLY item referencing main → the branch correlates
+    expect(result.nodes.get('item:7')!.classList.contains('pele-branch')).toBe(true)
+    expect(result.nodes.get('item:7')!.getAttribute('data-id')).toBe('main')
+    // `branch develop` / `checkout develop` / `merge develop` all resolve to the
+    // same branch surface — duplicate item text degrades BOTH sides, never mis-pairs
+    expect(result.failed).toEqual([...ids(1, 6), 'item:8', 'item:9'])
+    expect(result.nodes.get('item:3')).toBeUndefined()
+    for (const el of svg.querySelectorAll('g.pele-commit')) {
+      expect(el.hasAttribute('data-mw-entity')).toBe(false)
+    }
+    expect(svg.querySelectorAll('g.pele-branch[data-mw-entity]')).toHaveLength(1)
+  })
+
+  it('journey: tasks and sections by data-id, title via standalone text', () => {
+    const { result, svg, graph } = correlate(SAMPLES.journey)
+    expect(graph.items.map((i) => i.entityId)).toEqual(ids(1, 8))
+    expect(result.failed).toEqual([])
+    expect(result.nodes.size).toBe(8)
+    expect(result.nodes.get('item:2')!.getAttribute('data-id')).toBe('Go to work')
+    expect(result.nodes.get('item:3')!.getAttribute('data-id')).toBe('Make tea')
+    expect(result.nodes.get('item:6')!.getAttribute('data-id')).toBe('Go home')
+    // the title text (no data-id) is tagged through its anchor
+    const title = svg.querySelector('text.pele-title')!
+    expect(title.closest('[data-mw-entity]')!.getAttribute('data-mw-entity')).toBe('item:1')
+    // the actor legend is scenery core does not model — never tagged
+    for (const el of svg.querySelectorAll('g.pele-legend-item')) {
+      expect(el.hasAttribute('data-mw-entity')).toBe(false)
+    }
+  })
+
+  it('timeline: events by label text (no data-id); period nodes stay untagged scenery', () => {
+    const { result, svg, graph } = correlate(SAMPLES.timeline)
+    expect(graph.items.map((i) => i.entityId)).toEqual(ids(1, 6))
+    expect(result.failed).toEqual([])
+    expect(result.nodes.size).toBe(6)
+    // the title correlates through its text
+    expect(svg.querySelector('text.pele-title')!.closest('[data-mw-entity]')!.getAttribute('data-mw-entity')).toBe('item:1')
+    // events carry no data-id — matched by their label text, anchored on the event group
+    const event = result.nodes.get('item:2')!
+    expect(event.classList.contains('pele-event')).toBe(true)
+    expect(event.textContent).toContain('LinkedIn')
+    expect(result.nodes.get('item:4')!.textContent).toContain('Google')
+    // pele-period nodes (data-id = the period label) are never claimed by event items
+    for (const el of svg.querySelectorAll('g.pele-period')) {
+      expect(el.hasAttribute('data-mw-entity')).toBe(false)
+    }
+  })
+
+  it('sankey: link lines derive their A->B key and match path.pele-sankey-link data-ids', () => {
+    const { result, svg, graph } = correlate(SAMPLES.sankey)
+    expect(graph.items.map((i) => i.entityId)).toEqual(ids(1, 5))
+    expect(result.failed).toEqual([])
+    expect(result.nodes.size).toBe(5)
+    expect(result.nodes.get('item:1')!.getAttribute('data-id')).toBe("Agricultural 'waste'->Bio-conversion")
+    expect(result.nodes.get('item:3')!.getAttribute('data-id')).toBe('Bio-conversion->Losses')
+    expect(result.nodes.get('item:1')!.tagName.toLowerCase()).toBe('path')
+    // node rects and labels are node scenery — link items never claim them
+    for (const el of svg.querySelectorAll('rect.pele-sankey-node, g.pele-label')) {
+      expect(el.hasAttribute('data-mw-entity')).toBe(false)
+    }
+  })
+
+  it('mindmap: nodes by data-id, the root via its label text (data-id is the generic "root")', () => {
+    const { result, svg, graph } = correlate(SAMPLES.mindmap)
+    expect(graph.items.map((i) => i.entityId)).toEqual(ids(1, 10))
+    expect(result.failed).toEqual([])
+    expect(result.nodes.size).toBe(10)
+    expect(result.nodes.get('item:2')!.getAttribute('data-id')).toBe('Parsing')
+    expect(result.nodes.get('item:3')!.getAttribute('data-id')).toBe('Lossless CST')
+    // root((visimer)): pele stamps data-id="root", the label is "visimer"
+    const root = result.nodes.get('item:1')!
+    expect(root.getAttribute('data-id')).toBe('root')
+    expect(root.classList.contains('pele-root')).toBe(true)
+    // branch wrapper groups are scenery — never tagged
+    for (const el of svg.querySelectorAll('g.pele-branch')) {
+      expect(el.hasAttribute('data-mw-entity')).toBe(false)
+    }
+  })
+
+  it('treemap: sections and leaves by data-id', () => {
+    const { result, svg, graph } = correlate(SAMPLES.treemap)
+    expect(graph.items.map((i) => i.entityId)).toEqual(ids(1, 7))
+    expect(result.failed).toEqual([])
+    expect(result.nodes.size).toBe(7)
+    expect(result.nodes.get('item:1')!.getAttribute('data-id')).toBe('Products')
+    expect(result.nodes.get('item:3')!.getAttribute('data-id')).toBe('Phones')
+    expect(result.nodes.get('item:6')!.getAttribute('data-id')).toBe('Chairs')
+  })
+
+  it('packet: fields by their label text (data-id is the bit range)', () => {
+    const { result, graph } = correlate(SAMPLES.packet)
+    expect(graph.items.map((i) => i.entityId)).toEqual(ids(1, 4))
+    expect(result.failed).toEqual([])
+    expect(result.nodes.size).toBe(4)
+    expect(result.nodes.get('item:1')!.getAttribute('data-id')).toBe('0-15')
+    expect(result.nodes.get('item:1')!.textContent).toContain('Source Port')
+    expect(result.nodes.get('item:4')!.getAttribute('data-id')).toBe('64-95')
+  })
+
+  it('radar: axis labels by axis text, curves via their legend entry; title and max/min degrade', () => {
+    const { result, svg, graph } = correlate(SAMPLES.radar)
+    expect(graph.items.map((i) => i.entityId)).toEqual(ids(1, 7))
+    // `title Grades` has no quoted match text (radar extracts quoted strings
+    // only), same for `max 100` / `min 0` — code-only
+    expect(result.failed).toEqual(['item:1', 'item:6', 'item:7'])
+    expect(result.nodes.size).toBe(4)
+    // `axis m["Math"], ...` — one line, first quoted label is the match text
+    expect(result.nodes.get('item:2')!.getAttribute('data-id')).toBe('m')
+    expect(result.nodes.get('item:3')!.getAttribute('data-id')).toBe('h')
+    // `curve alice["Alice"]`: the curve path carries data-id "alice" (different
+    // case, no text) — the legend entry is the matchable text surface
+    expect(result.nodes.get('item:4')!.classList.contains('pele-legend-item')).toBe(true)
+    expect(result.nodes.get('item:4')!.getAttribute('data-id')).toBe('alice')
+    expect(result.nodes.get('item:5')!.getAttribute('data-id')).toBe('bob')
+    // curve paths are never claimed (their data-id never equals the match text)
+    expect(svg.querySelectorAll('path.pele-curve[data-mw-entity]')).toHaveLength(0)
+  })
+
+  it('xychart: only the title line has a matchable surface', () => {
+    const { result, graph } = correlate(SAMPLES.xychart)
+    expect(graph.items.map((i) => i.entityId)).toEqual(ids(1, 5))
+    // x/y-axis, bar and line statements have no matchText — code-only
+    expect(result.failed).toEqual(ids(2, 5))
+    expect(result.nodes.size).toBe(1)
+  })
+
+  it('architecture: services and groups by label text; duplicated service labels degrade', () => {
+    const { result, svg, graph } = correlate(SAMPLES.architecture)
+    // group, 4 services, 3 edges
+    expect(graph.items.map((i) => i.entityId)).toEqual([...ids(1, 1), ...ids(3, 6), ...ids(8, 10)])
+    // core's architecture extractor yields the SHAPE keyword (firstBracketed
+    // prefers the parens: "cloud", "database", "disk", "server"), not the
+    // display name — so only the `server` line (whose shape keyword coincides
+    // with pele's data-id) correlates; the display names and the `disk` pair
+    // (duplicate key) degrade rather than mis-pair
+    expect(result.failed).toEqual(['item:1', 'item:3', 'item:4', 'item:5', 'item:8', 'item:9', 'item:10'])
+    expect(result.nodes.size).toBe(1)
+    expect(result.nodes.get('item:6')!.getAttribute('data-id')).toBe('server')
+    // no display-name text ever claims a node (matchText is the shape keyword)
+    expect(svg.querySelector('g.pele-node[data-id="db"]')!.hasAttribute('data-mw-entity')).toBe(false)
+    // edges have no matchText — no edge groups tagged
+    expect(svg.querySelectorAll('g.pele-edge[data-mw-entity]')).toHaveLength(0)
+  })
+
+  it('requirement: requirements and elements by data-id; field rows and the relationship degrade', () => {
+    const { result, svg, graph } = correlate(SAMPLES.requirement)
+    expect(result.nodes.size).toBe(2)
+    expect(result.nodes.get('item:1')!.getAttribute('data-id')).toBe('test_req')
+    expect(result.nodes.get('item:1')!.classList.contains('pele-requirement')).toBe(true)
+    expect(result.nodes.get('item:7')!.getAttribute('data-id')).toBe('test_entity')
+    // field rows (`id: 1`, ...) and the relationship line have no matchable name
+    const expectedFailed = graph.items
+      .filter((i) => !['item:1', 'item:7'].includes(i.entityId))
+      .map((i) => i.entityId)
+    expect(result.failed).toEqual(expectedFailed)
+    expect(svg.querySelectorAll('g.pele-edge[data-mw-entity]')).toHaveLength(0)
+  })
+
+  it('c4: persons/systems by their display name; duplicate "Uses" relationship labels degrade', () => {
+    const { result, svg, graph } = correlate(SAMPLES.c4)
+    expect(result.nodes.size).toBe(3)
+    expect(result.nodes.get('item:2')!.getAttribute('data-id')).toBe('customerA')
+    expect(result.nodes.get('item:3')!.getAttribute('data-id')).toBe('SystemAA')
+    expect(result.nodes.get('item:4')!.getAttribute('data-id')).toBe('SystemE')
+    // both Rel lines render a label "Uses" — duplicate item text, degrade BOTH
+    const expectedFailed = graph.items
+      .filter((i) => !['item:2', 'item:3', 'item:4'].includes(i.entityId))
+      .map((i) => i.entityId)
+    expect(result.failed).toEqual(expectedFailed)
+    expect(svg.querySelectorAll('g.pele-edge[data-mw-entity], g.pele-edge-label[data-mw-entity]')).toHaveLength(0)
+  })
+
+  it('block: single-word and bracketed blocks by data-id, shaped blocks by label text', () => {
+    const { result, svg, graph } = correlate(SAMPLES.block)
+    expect(result.nodes.size).toBe(6)
+    // A, B, C, D are plain data-id matches (B's match text is its label, but its
+    // data-id "B" is matched through the label text)
+    expect(result.nodes.get('item:5')!.getAttribute('data-id')).toBe('A')
+    expect(result.nodes.get('item:6')!.getAttribute('data-id')).toBe('B')
+    expect(result.nodes.get('item:10')!.getAttribute('data-id')).toBe('D')
+    // db(("DB")): data-id is "db", label text "DB"
+    expect(result.nodes.get('item:2')!.getAttribute('data-id')).toBe('db')
+    // blockArrowId6's label is literally "&nbsp;" entities — decoded on both sides
+    expect(result.nodes.get('item:3')!.getAttribute('data-id')).toBe('blockArrowId6')
+    // `columns 1`, `block:ID`, `space`, edges and the style line degrade
+    const expectedFailed = graph.items
+      .filter((i) => !ids(2, 3).concat(ids(5, 7), ['item:10']).includes(i.entityId))
+      .map((i) => i.entityId)
+    expect(result.failed).toEqual(expectedFailed)
+    // the `block:ID` cluster has no item with a matchable name — never tagged
+    expect(svg.querySelector('g.pele-cluster[data-id="ID"]')!.hasAttribute('data-mw-entity')).toBe(false)
+  })
+
+  it('quadrant: points by data-id; axes and quadrant titles have no matchText', () => {
+    const { result, svg, graph } = correlate(SAMPLES.quadrant)
+    expect(result.nodes.size).toBe(3)
+    expect(result.nodes.get('item:8')!.getAttribute('data-id')).toBe('Campaign A')
+    expect(result.nodes.get('item:9')!.getAttribute('data-id')).toBe('Campaign B')
+    expect(result.nodes.get('item:10')!.getAttribute('data-id')).toBe('Campaign C')
+    const expectedFailed = graph.items.filter((i) => !ids(8, 10).includes(i.entityId)).map((i) => i.entityId)
+    expect(result.failed).toEqual(expectedFailed)
+    // quadrant background tiles are scenery — never tagged
+    for (const el of svg.querySelectorAll('g.pele-quadrant')) {
+      expect(el.hasAttribute('data-mw-entity')).toBe(false)
+    }
+  })
+})
+
+describe('correlatePeleLineItems — adversarial', () => {
+  it('duplicate kanban card text degrades BOTH cards — never mis-pairs', () => {
+    const { result, svg } = correlate(`kanban
+  Col
+    a[Same]
+    b[Same]
+`)
+    // the column still correlates; the two identically-named cards do not
+    expect(result.nodes.size).toBe(1)
+    expect(result.failed).toEqual(['item:2', 'item:3'])
+    for (const el of svg.querySelectorAll('g.pele-card')) {
+      expect(el.hasAttribute('data-mw-entity')).toBe(false)
+    }
+  })
+
+  it('one item matching two candidate groups is ambiguous — degrades instead of guessing', () => {
+    const svg = syntheticSvg(
+      '<g class="pele-node" data-id="x1"><text>Dup</text></g>' +
+        '<g class="pele-node" data-id="x2"><text>Dup</text></g>',
+    )
+    const result = correlatePeleLineItems(svg, fakeGraph('mindmap', [{ id: 'item:1', matchText: 'Dup' }]))
+    expect(result.nodes.size).toBe(0)
+    expect(result.failed).toEqual(['item:1'])
+    for (const el of svg.querySelectorAll('g.pele-node')) {
+      expect(el.hasAttribute('data-mw-entity')).toBe(false)
+    }
+  })
+
+  it('class-filters the sweep: text outside the type\u2019s candidate groups is never claimed', () => {
+    // a stray text in a non-candidate group plus an unrelated pele-node — a
+    // mindmap item must only ever land on g.pele-node, so the stray stays free
+    const svg = syntheticSvg(
+      '<g class="pele-branch"><text>Parsing</text></g>' +
+        '<g class="pele-node" data-id="Other"><text>Other</text></g>',
+    )
+    const result = correlatePeleLineItems(svg, fakeGraph('mindmap', [{ id: 'item:1', matchText: 'Parsing' }]))
+    expect(result.nodes.size).toBe(0)
+    expect(result.failed).toEqual(['item:1'])
+    expect(svg.querySelector('g.pele-branch text')!.hasAttribute('data-mw-entity')).toBe(false)
+  })
+
+  it('items with null matchText are code-only and never claim anything', () => {
+    const svg = syntheticSvg('<g class="pele-node" data-id="a"><text>hello</text></g>')
+    const result = correlatePeleLineItems(svg, fakeGraph('mindmap', [{ id: 'item:1', matchText: null }]))
+    expect(result.nodes.size).toBe(0)
+    expect(result.failed).toEqual(['item:1'])
+    expect(svg.querySelector('g.pele-node')!.hasAttribute('data-mw-entity')).toBe(false)
+  })
+
+  it('a claimed element is exclusive: a second item whose only hit is taken degrades', () => {
+    // two items, keys "a" (data-id hit) and "a" again via text on the same group
+    const svg = syntheticSvg('<g class="pele-node" data-id="a"><text>b</text></g>')
+    const result = correlatePeleLineItems(
+      svg,
+      fakeGraph('block', [
+        { id: 'item:1', matchText: 'a' },
+        { id: 'item:2', matchText: 'b' },
+      ]),
+    )
+    // item:1 claims the group by data-id; item:2's text hit is the same,
+    // already-claimed group — degrades rather than double-tagging
+    expect(result.nodes.get('item:1')).toBeTruthy()
+    expect(result.failed).toEqual(['item:2'])
+  })
+})
+
+describe('view dispatch + style spot-check', () => {
+  let container: HTMLElement
+
+  beforeEach(() => {
+    container = document.createElement('div')
+    document.body.appendChild(container)
+  })
+
+  afterEach(() => {
+    container.remove()
+  })
+
+  it('dispatches line-item types through the pele correlator', async () => {
+    const { view } = await mountWithView(container, SAMPLES.kanban)
+    expect(container.querySelector('svg')).toBeTruthy()
+    const cards = container.querySelectorAll('g.pele-card[data-mw-entity]')
+    expect(cards.length).toBeGreaterThan(0)
+    expect(container.querySelector('[data-mw-entity="item:3"]')).toBeTruthy()
+    // columns and cards both tagged, counts never
+    expect(container.querySelector('g.pele-column[data-mw-entity]')).toBeTruthy()
+    expect(container.querySelector('text.pele-count[data-mw-entity]')).toBeNull()
+    view.destroy()
+  })
+
+  it('style op round-trips: selecting a kanban card marks it visibly and it stays correlated', async () => {
+    const { editor, view } = await mountWithView(container, SAMPLES.kanban)
+    const card = container.querySelector('g.pele-card[data-mw-entity="item:2"]')!
+    expect(card).toBeTruthy()
+    // click the card through the view's real click path
+    card.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+    expect(editor.selection).toEqual(['item:2'])
+    // the selection style op lands on the same element the correlator tagged
+    expect(card.classList.contains('mw-selected')).toBe(true)
+    // and the correlation survives (the element is still the tagged anchor)
+    expect(container.querySelector('[data-mw-entity="item:2"]')).toBe(card)
+    view.destroy()
+  })
+})

From 8a4f4f4605b38fac8502b0e6d7105475c355e366 Mon Sep 17 00:00:00 2001
From: Casey Gollan <hello@caseyagollan.com>
Date: Sun, 1 Nov 2026 18:40:38 -0500
Subject: [PATCH 20/21] feat(dom): pele sequence correlator

---
 packages/dom/src/correlate.pele.sequence.ts   | 194 ++++++
 packages/dom/src/correlate.ts                 |   6 +-
 packages/dom/src/index.ts                     |   1 +
 packages/dom/src/view.ts                      |  43 +-
 .../dom/test/correlate-pele-sequence.test.ts  | 567 ++++++++++++++++++
 packages/dom/test/correlate-pele.test.ts      |  10 +-
 6 files changed, 798 insertions(+), 23 deletions(-)
 create mode 100644 packages/dom/src/correlate.pele.sequence.ts
 create mode 100644 packages/dom/test/correlate-pele-sequence.test.ts

diff --git a/packages/dom/src/correlate.pele.sequence.ts b/packages/dom/src/correlate.pele.sequence.ts
new file mode 100644
index 0000000..a58ffb7
--- /dev/null
+++ b/packages/dom/src/correlate.pele.sequence.ts
@@ -0,0 +1,194 @@
+import type { SequenceGraph } from '@visimer/core'
+import { addEdgeHitOverlay, type SequenceCorrelation } from './correlate'
+import { decodeEntities } from './correlate.pele'
+
+/**
+ * Correlate pele's rendered sequence-diagram SVG with the semantic graph.
+ *
+ * Surface (probed against pele@1.13.0, see the test file's sample strings):
+ * - actors are `g.pele-node.pele-actor.pele-actor-<kind>[data-id=<id>]` —
+ *   TWO groups per participant (a top box and a bottom twin carrying the
+ *   extra `pele-actor-footer` class), stamped with the participant's id
+ * - lifelines are `path.pele-lifeline[data-id=<id>]`, keyed by their own
+ *   data-id (unlike mermaid, which stamps nothing and must match by geometry)
+ * - messages are `g.pele-edge.pele-message[data-id=i<N>]` with their labels
+ *   in `g.pele-edge-label[data-id=<same i<N>]`; notes are
+ *   `g.pele-note[data-id=i<N>]` with their text inside the group
+ *
+ * The `i<N>` counter is GLOBAL across messages, notes and activations and is
+ * non-contiguous per kind (e.g. messages i0, i2, i6 around note i4), so the
+ * ids are HINTS ONLY and are never used as event match keys — events zip by
+ * document order, count-checked, mirroring mermaid's correlateSequence.
+ *
+ * Pele renders messages and notes in two separate DOM layers (all messages
+ * before all notes, whatever their source interleaving), so a cross-kind
+ * document merge can never reproduce core's event order. The machinery
+ * therefore mirrors correlateSequence exactly: messages zip against message
+ * groups and notes against note groups, each count-checked — a kind whose
+ * counts disagree degrades entirely rather than risk a shifted pairing.
+ *
+ * Lifelines are matched by data-id but only when the svg is laid out, the
+ * same guard mermaid's correlator enforces: on a hidden mount every
+ * `getBoundingClientRect` is zero, so the view's visibility retry contract
+ * (empty lifelines ⇒ re-correlate on reveal) stays intact.
+ *
+ * Scenery core has no entity for is never tagged: `rect.pele-activation`
+ * (which shares the participant's data-id!), destroy marks and `g.pele-frame`
+ * fragments — clicking them selects nothing.
+ */
+export function correlatePeleSequence(svg: SVGSVGElement, graph: SequenceGraph): SequenceCorrelation {
+  const participants = new Map<string, Element[]>()
+  const lifelines = new Map<string, SVGGeometryElement>()
+  const events = new Map<string, Element>()
+  const eventTexts = new Map<string, Element>()
+  const failed: string[] = []
+
+  const dataId = (el: Element) => el.getAttribute('data-id')
+  // pele bakes entity encodings (`&quot;`, `&#65;`, ...) into data-id values;
+  // the graph side may still be encoded while the attribute is not
+  const matchesId = (elId: string | null, id: string) => elId === id || elId === decodeEntities(id)
+
+  // --- participants: sweep ONLY g.pele-node.pele-actor groups (both twins).
+  // The sweep must be class-filtered: rect.pele-activation carries the same
+  // data-id as its participant but must never be claimed.
+  const actorEls = [...svg.querySelectorAll<SVGGElement>('g.pele-node.pele-actor[data-id]')]
+  const claimedActors = new Set<Element>()
+  const unmatchedParticipants: SequenceGraph['participants'] = []
+  for (const p of graph.participants) {
+    const els = actorEls.filter((e) => !claimedActors.has(e) && matchesId(dataId(e), p.id))
+    if (els.length) {
+      for (const el of els) {
+        claimedActors.add(el)
+        el.setAttribute('data-mw-entity', p.entityId)
+      }
+      participants.set(p.entityId, els)
+    } else {
+      unmatchedParticipants.push(p)
+    }
+  }
+  // leftover: pele may stamp generated ids core cannot name. Zip the
+  // leftovers only when the unclaimed groups form exactly as many twin
+  // buckets as there are unmatched participants — anything else is
+  // unverifiable and degrades (never mis-pairs).
+  if (unmatchedParticipants.length) {
+    const buckets = new Map<string, Element[]>()
+    for (const el of actorEls) {
+      if (claimedActors.has(el)) continue
+      const id = dataId(el) ?? ''
+      const list = buckets.get(id) ?? []
+      list.push(el)
+      buckets.set(id, list)
+    }
+    const bucketList = [...buckets.values()]
+    if (bucketList.length === unmatchedParticipants.length && bucketList.every((b) => b.length === 2)) {
+      bucketList.forEach((els, i) => {
+        const p = unmatchedParticipants[i]
+        for (const el of els) el.setAttribute('data-mw-entity', p.entityId)
+        participants.set(p.entityId, els)
+      })
+    } else {
+      for (const p of unmatchedParticipants) failed.push(p.entityId)
+    }
+  }
+
+  // --- lifelines: by their own data-id, but only once laid out — a hidden
+  // mount must leave the slot empty so the view's visibility retry re-runs
+  // correlation on reveal (same predicate as correlateSequence's guard)
+  if (svg.getBoundingClientRect().width !== 0) {
+    const lifelineEls = [...svg.querySelectorAll<SVGPathElement>('path.pele-lifeline[data-id]')]
+    for (const p of graph.participants) {
+      const el = lifelineEls.find((e) => matchesId(dataId(e), p.id))
+      if (el) lifelines.set(p.entityId, el)
+    }
+  }
+
+  // --- events: per-kind count-checked order zips (see the doc comment for
+  // why pele's layered DOM rules out a cross-kind merge)
+  type SeqEvent = SequenceGraph['events'][number]
+  const coreMessages = graph.events.filter((e) => e.kind === 'message')
+  const coreNotes = graph.events.filter((e) => e.kind === 'note')
+  const messageEls = [...svg.querySelectorAll<SVGGElement>('g.pele-edge.pele-message')]
+  const noteEls = [...svg.querySelectorAll<SVGGElement>('g.pele-note')]
+
+  /** claimed messages in document order, for the label pass below */
+  const claimedMessages: Array<{ ev: SeqEvent; el: Element }> = []
+
+  if (messageEls.length === coreMessages.length) {
+    coreMessages.forEach((ev, i) => {
+      const el = messageEls[i]
+      // the first path is the message line; the arrow marker follows
+      const line = el.querySelector('path')
+      const primary = line ?? el
+      events.set(ev.entityId, primary)
+      el.setAttribute('data-mw-entity', ev.entityId)
+      if (primary !== el) primary.setAttribute('data-mw-entity', ev.entityId)
+      if (line) addEdgeHitOverlay(line, ev.entityId)
+      claimedMessages.push({ ev, el })
+    })
+  } else {
+    for (const ev of coreMessages) failed.push(ev.entityId)
+  }
+
+  if (noteEls.length === coreNotes.length) {
+    coreNotes.forEach((ev, i) => {
+      const el = noteEls[i]
+      const rect = el.querySelector('rect')
+      const text = el.querySelector('text')
+      const primary = rect ?? el
+      events.set(ev.entityId, primary)
+      eventTexts.set(ev.entityId, text ?? primary)
+      el.setAttribute('data-mw-entity', ev.entityId)
+      if (primary !== el) primary.setAttribute('data-mw-entity', ev.entityId)
+      if (text && text !== primary) text.setAttribute('data-mw-entity', ev.entityId)
+    })
+  } else {
+    for (const ev of coreNotes) failed.push(ev.entityId)
+  }
+
+  // --- message labels: pair each g.pele-edge-label to its message group by
+  // equal data-id when unambiguous (exactly one label and exactly one group
+  // share the id); the leftovers fall back to a count-checked document-order
+  // zip. Label misses degrade silently — the message itself may still have
+  // correlated (mermaid's correlator treats label misses the same way).
+  const labelEls = [...svg.querySelectorAll<SVGGElement>('g.pele-edge-label')]
+  const labelsById = new Map<string, Element[]>()
+  for (const el of labelEls) {
+    const id = dataId(el)
+    if (id === null) continue
+    const list = labelsById.get(id) ?? []
+    list.push(el)
+    labelsById.set(id, list)
+  }
+  const messagesById = new Map<string, number>()
+  for (const { el } of claimedMessages) {
+    const id = dataId(el)
+    if (id !== null) messagesById.set(id, (messagesById.get(id) ?? 0) + 1)
+  }
+  const pairLabel = (msg: { ev: SeqEvent; el: Element }, label: Element): void => {
+    const text = label.querySelector('text')
+    const primary = text ?? label
+    eventTexts.set(msg.ev.entityId, primary)
+    label.setAttribute('data-mw-entity', msg.ev.entityId)
+    if (primary !== label) primary.setAttribute('data-mw-entity', msg.ev.entityId)
+  }
+  const unpairedMessages: Array<{ ev: SeqEvent; el: Element }> = []
+  const claimedLabels = new Set<Element>()
+  for (const msg of claimedMessages) {
+    const id = dataId(msg.el)
+    const labels = id === null ? [] : labelsById.get(id) ?? []
+    // unambiguous: no other message group shares the id, and exactly one
+    // label carries it
+    if (id !== null && (messagesById.get(id) ?? 0) === 1 && labels.length === 1) {
+      claimedLabels.add(labels[0])
+      pairLabel(msg, labels[0])
+    } else {
+      unpairedMessages.push(msg)
+    }
+  }
+  const unpairedLabels = labelEls.filter((l) => !claimedLabels.has(l))
+  if (unpairedLabels.length === unpairedMessages.length) {
+    unpairedMessages.forEach((msg, i) => pairLabel(msg, unpairedLabels[i]))
+  }
+
+  return { participants, lifelines, events, eventTexts, failed }
+}
diff --git a/packages/dom/src/correlate.ts b/packages/dom/src/correlate.ts
index 983dd3b..2fb7d47 100644
--- a/packages/dom/src/correlate.ts
+++ b/packages/dom/src/correlate.ts
@@ -464,8 +464,8 @@ export function correlateLineItems(svg: SVGSVGElement, graph: LineItemsGraph): C
 export interface SequenceCorrelation {
   /** participant entity id → every SVG element belonging to it (top + bottom boxes) */
   participants: Map<string, Element[]>
-  /** participant entity id → lifeline <line> element */
-  lifelines: Map<string, SVGLineElement>
+  /** participant entity id → its lifeline element (`<line>` under mermaid, `<path>` under pele) */
+  lifelines: Map<string, SVGGeometryElement>
   /** event entity id → primary element (message line / note rect) */
   events: Map<string, Element>
   /** event entity id → its text element */
@@ -480,7 +480,7 @@ export interface SequenceCorrelation {
  */
 export function correlateSequence(svg: SVGSVGElement, graph: SequenceGraph): SequenceCorrelation {
   const participants = new Map<string, Element[]>()
-  const lifelines = new Map<string, SVGLineElement>()
+  const lifelines = new Map<string, SVGGeometryElement>()
   const events = new Map<string, Element>()
   const eventTexts = new Map<string, Element>()
   const failed: string[] = []
diff --git a/packages/dom/src/index.ts b/packages/dom/src/index.ts
index 8304912..1fadb0e 100644
--- a/packages/dom/src/index.ts
+++ b/packages/dom/src/index.ts
@@ -8,4 +8,5 @@ export { correlatePeleEr } from './correlate.pele.er'
 export { correlatePelePie } from './correlate.pele.pie'
 export { correlatePeleGantt } from './correlate.pele.gantt'
 export { correlatePeleLineItems } from './correlate.pele.lineitems'
+export { correlatePeleSequence } from './correlate.pele.sequence'
 export { Popover, type PopoverAction, type PopoverPanelItem } from './popover'
diff --git a/packages/dom/src/view.ts b/packages/dom/src/view.ts
index 3019dd5..848406f 100644
--- a/packages/dom/src/view.ts
+++ b/packages/dom/src/view.ts
@@ -38,6 +38,7 @@ import { correlatePeleClass } from './correlate.pele.class'
 import { correlatePeleState } from './correlate.pele.state'
 import { correlatePeleEr } from './correlate.pele.er'
 import { correlatePelePie } from './correlate.pele.pie'
+import { correlatePeleSequence } from './correlate.pele.sequence'
 import { correlatePeleGantt } from './correlate.pele.gantt'
 import { correlatePeleLineItems } from './correlate.pele.lineitems'
 
@@ -359,10 +360,11 @@ export class MermaidCanvasView {
   /**
    * Re-runs sequence correlation (not `bindSvg`, which would double-register
    * every pointer/click handler) once a hidden-mount SVG becomes visible.
-   * Sequence correlation matches lifelines by geometry, and
-   * `getBoundingClientRect` returns all zeros for a `display:none` ancestor,
-   * so the initial pass skips lifeline correlation and this observer picks
-   * it up on reveal.
+   * Both correlators skip lifelines under a zero-width svg (mermaid matches
+   * them by geometry outright; pele matches by data-id but keeps the same
+   * hidden-mount contract), and `getBoundingClientRect` returns all zeros
+   * for a `display:none` ancestor, so the initial pass leaves the lifelines
+   * slot empty and this observer picks it up on reveal.
    */
   private visibilityRetryObserver: IntersectionObserver | null = null
   private popoverFollowRaf = 0
@@ -923,10 +925,10 @@ export class MermaidCanvasView {
     if (!svg) return
     const { flowchart, sequence, state, classGraph, er, pie, gantt, lineItems } = this.editor.result
     const isPele = this.renderer.id === 'pele'
-    // Under pele, flowcharts, state, class, er, pie, gantt and the line-item
-    // chart types correlate through their own modules; every other diagram
-    // slot stays view-only, and sequence correlation plus the visibility
-    // retry are mermaid-only.
+    // Under pele, every diagram slot correlates through its own pele module
+    // (flowchart, state, class, er, pie, gantt, line items, and sequence via
+    // correlatePeleSequence — sequence correlation also fills the
+    // seqCorrelation slot and arms the visibility retry like mermaid's).
     if (isPele) {
       this.correlation = flowchart
         ? correlatePeleFlowchart(svg, flowchart)
@@ -960,9 +962,13 @@ export class MermaidCanvasView {
                     ? correlateLineItems(svg, this.editor.result.lineItems)
                     : null
     }
-    this.seqCorrelation = !isPele && sequence ? correlateSequence(svg, sequence) : null
+    this.seqCorrelation = sequence
+      ? isPele
+        ? correlatePeleSequence(svg, sequence)
+        : correlateSequence(svg, sequence)
+      : null
     this.clearLifelineUi()
-    this.armVisibilityRetry(svg, isPele ? null : sequence)
+    this.armVisibilityRetry(svg, sequence, isPele ? correlatePeleSequence : correlateSequence)
 
     svg.addEventListener('click', (e) => this.onSvgClick(e))
     svg.addEventListener('dblclick', (e) => this.onSvgDblClick(e))
@@ -1001,14 +1007,18 @@ export class MermaidCanvasView {
     this.applySelectionStyles()
   }
 
-  private armVisibilityRetry(svg: SVGSVGElement, sequence: SequenceGraph | null): void {
+  private armVisibilityRetry(
+    svg: SVGSVGElement,
+    sequence: SequenceGraph | null,
+    correlate: (svg: SVGSVGElement, graph: SequenceGraph) => SequenceCorrelation = correlateSequence,
+  ): void {
     this.visibilityRetryObserver?.disconnect()
     this.visibilityRetryObserver = null
     if (!sequence) return
     // Key retry off the correlation result: an empty lifelines map is the
-    // hidden-mount case (the same predicate the guard in correlate.ts
-    // enforces). Avoids re-checking bbox with inverted polarity in two
-    // files.
+    // hidden-mount case (the same predicate the correlators enforce —
+    // both mermaid's and pele's leave the slot empty under a zero-width
+    // svg). Avoids re-checking bbox with inverted polarity in two files.
     if (this.seqCorrelation && this.seqCorrelation.lifelines.size > 0) return
     if (typeof IntersectionObserver === 'undefined') return
     this.visibilityRetryObserver = new IntersectionObserver((entries) => {
@@ -1020,8 +1030,9 @@ export class MermaidCanvasView {
       this.visibilityRetryObserver?.disconnect()
       this.visibilityRetryObserver = null
       // Re-run correlation only; bindSvg's addEventListener block would
-      // double-register every pointer/click handler.
-      if (this.svg === svg) this.seqCorrelation = correlateSequence(svg, sequence)
+      // double-register every pointer/click handler. The correlator is
+      // whichever one the current renderer needs (pele under pele).
+      if (this.svg === svg) this.seqCorrelation = correlate(svg, sequence)
     })
     this.visibilityRetryObserver.observe(svg)
   }
diff --git a/packages/dom/test/correlate-pele-sequence.test.ts b/packages/dom/test/correlate-pele-sequence.test.ts
new file mode 100644
index 0000000..37fc162
--- /dev/null
+++ b/packages/dom/test/correlate-pele-sequence.test.ts
@@ -0,0 +1,567 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { render as peleRender } from 'pele'
+import { MermaidWysiwygEditor, type SequenceGraph } from '@visimer/core'
+import { correlatePeleSequence } from '../src/correlate.pele.sequence'
+import { MermaidCanvasView, peleAdapter } from '../src'
+
+// jsdom has no CSS.escape (browsers do)
+if (typeof (globalThis as { CSS?: unknown }).CSS === 'undefined') {
+  ;(globalThis as { CSS?: { escape(s: string): string } }).CSS = {
+    escape: (s: string) => s.replace(/[^a-zA-Z0-9_-]/g, (c) => `\\${c}`),
+  }
+}
+
+// jsdom has no canvas: pele probes for one to measure text, and jsdom's
+// getContext raises a noisy "not implemented" error. Return null so pele falls
+// back to its built-in metrics table (the assertions here are structural, not
+// pixel-precise).
+HTMLCanvasElement.prototype.getContext = (() => null) as typeof HTMLCanvasElement.prototype.getContext
+
+// probe's sequence sample (task-7 brief) — pele@1.13.0 renders it as:
+// messages i0 (Hello), i2 (Hi), i6 (Ping); note i4 (greeting); the i<N>
+// counter is global across messages AND notes and skips activation statements
+// (i1, i3, i5), so the ids are non-contiguous per kind and are HINTS ONLY.
+const SAMPLE = `sequenceDiagram
+  participant Alice
+  actor Bob
+  Alice->>Bob: Hello
+  activate Bob
+  Bob-->>Alice: Hi
+  deactivate Bob
+  Note over Alice,Bob: greeting
+  loop Daily
+    Alice->>Bob: Ping
+  end
+`
+
+// the same sample with a note inserted after the first message — every message
+// i<N> AFTER the insertion point shifts (probed: messages i0, i3, i7 with
+// notes i2, i5). Pins that the count-checked order zip pairs by document
+// order, never by the i<N> ids.
+const INSERTED = `sequenceDiagram
+  participant Alice
+  actor Bob
+  Alice->>Bob: Hello
+  activate Bob
+  Note over Bob: inserted
+  Bob-->>Alice: Hi
+  deactivate Bob
+  Note over Alice,Bob: greeting
+  loop Daily
+    Alice->>Bob: Ping
+  end
+`
+
+const hosts: HTMLElement[] = []
+
+/** render a code string with real pele and correlate it against core's graph */
+function correlate(code: string, opts: { visible?: boolean } = {}) {
+  const editor = new MermaidWysiwygEditor({ code })
+  const graph = editor.result.sequence
+  if (!graph) throw new Error('code did not produce a sequence graph')
+  const host = document.createElement('div')
+  document.body.appendChild(host)
+  hosts.push(host)
+  host.innerHTML = peleRender(code).svg
+  const svg = host.querySelector('svg')!
+  if (opts.visible !== false) stampWidth(svg, 400)
+  return { svg, graph, result: correlatePeleSequence(svg, graph) }
+}
+
+/**
+ * jsdom never lays elements out, so `getBoundingClientRect` is always zero —
+ * the correlator's lifeline guard (mirroring mermaid's) reads the svg root's
+ * width. Stamp a non-zero width to exercise the visible path, or 0 for the
+ * hidden-mount path.
+ */
+function stampWidth(svg: SVGSVGElement, width: number) {
+  Object.defineProperty(svg, 'getBoundingClientRect', {
+    value: () => ({
+      left: 0,
+      right: width,
+      top: 0,
+      bottom: 400,
+      width,
+      height: 400,
+      x: 0,
+      y: 0,
+      toJSON: () => ({}),
+    }),
+    configurable: true,
+  })
+}
+
+function syntheticSvg(markup: string): SVGSVGElement {
+  const host = document.createElement('div')
+  document.body.appendChild(host)
+  hosts.push(host)
+  host.innerHTML = `<svg>${markup}</svg>`
+  return host.querySelector('svg')!
+}
+
+/** core-shaped graph for synthetic fixtures (entity ids: participant:/event:) */
+function fakeGraph(participants: string[], events: Array<'message' | 'note'>): SequenceGraph {
+  return {
+    participants: participants.map((id) => ({
+      entityId: `participant:${id}`,
+      id,
+      label: id,
+      ptype: 'participant',
+      decl: null,
+      order: 0,
+    })),
+    events: events.map((kind, i) => ({
+      kind,
+      entityId: `event:${i + 1}`,
+      lineIndex: i + 1,
+      stmt: {},
+    })),
+  } as unknown as SequenceGraph
+}
+
+afterEach(() => {
+  for (const host of hosts.splice(0)) host.remove()
+})
+
+describe('correlatePeleSequence (pele@1.13.0 surface, probed sample)', () => {
+  it('correlates participants (both actor twins, participant and actor kinds) by data-id', () => {
+    const { result, svg } = correlate(SAMPLE)
+    expect(result.failed).toEqual([])
+    expect(result.participants.size).toBe(2)
+    // BOTH twins — the pele-actor-footer bottom box and the top box — are
+    // stored per participant and carry the participant: tag
+    for (const id of ['Alice', 'Bob']) {
+      const twins = [...svg.querySelectorAll(`g.pele-actor[data-id="${id}"]`)]
+      expect(twins).toHaveLength(2)
+      const stored = result.participants.get(`participant:${id}`)!
+      expect(stored).toHaveLength(2)
+      expect(stored).toEqual(expect.arrayContaining(twins))
+      for (const t of twins) expect(t.getAttribute('data-mw-entity')).toBe(`participant:${id}`)
+    }
+    // the declared participant and the actor kind both land in participants
+    expect(svg.querySelectorAll('.pele-actor-participant, .pele-actor-actor')).toHaveLength(4)
+    // exactly one footer twin per participant
+    expect(svg.querySelectorAll('g.pele-actor.pele-actor-footer[data-mw-entity]')).toHaveLength(2)
+  })
+
+  it('fills the lifelines slot with path.pele-lifeline by its own data-id', () => {
+    const { result, svg } = correlate(SAMPLE)
+    expect(result.lifelines.size).toBe(2)
+    expect(result.lifelines.get('participant:Alice')).toBe(svg.querySelector('path.pele-lifeline[data-id="Alice"]'))
+    expect(result.lifelines.get('participant:Bob')).toBe(svg.querySelector('path.pele-lifeline[data-id="Bob"]'))
+    // lifelines are an interaction surface, not entity surfaces — like
+    // mermaid's correlator, they carry no data-mw-entity
+    for (const el of svg.querySelectorAll('path.pele-lifeline')) {
+      expect(el.hasAttribute('data-mw-entity')).toBe(false)
+    }
+  })
+
+  it('correlates messages and notes by per-kind document order against core events', () => {
+    const { result, svg, graph } = correlate(SAMPLE)
+    // core: event:3 Hello (message), event:5 Hi (message), event:7 greeting
+    // (note), event:9 Ping (message)
+    expect(graph.events.map((e) => `${e.kind.slice(0, 3)}@${e.entityId}`)).toEqual([
+      'mes@event:3',
+      'mes@event:5',
+      'not@event:7',
+      'mes@event:9',
+    ])
+    expect(result.failed).toEqual([])
+    expect(result.events.size).toBe(4)
+    // messages land on the inner <path> of the right pele-message group (the
+    // marker carries pele-marker, the hit overlay data-mw-hit-overlay)
+    const msgLine = (id: string) =>
+      svg.querySelector(`g.pele-message[data-id="${id}"] path:not([data-mw-hit-overlay]):not(.pele-marker)`)
+    expect(result.events.get('event:3')).toBe(msgLine('i0'))
+    expect(result.events.get('event:5')).toBe(msgLine('i2'))
+    expect(result.events.get('event:9')).toBe(msgLine('i6'))
+    // the note lands on the note group's rect
+    expect(result.events.get('event:7')).toBe(svg.querySelector('g.pele-note[data-id="i4"] > rect'))
+    // every event element is tagged with its entity id
+    for (const id of ['event:3', 'event:5', 'event:7', 'event:9']) {
+      expect(svg.querySelectorAll(`[data-mw-entity="${id}"]`).length).toBeGreaterThan(0)
+    }
+    // message labels pair to their message group by the shared data-id; the
+    // note's text lives inside the note group
+    expect(result.eventTexts.get('event:3')?.textContent).toBe('Hello')
+    expect(result.eventTexts.get('event:5')?.textContent).toBe('Hi')
+    expect(result.eventTexts.get('event:9')?.textContent).toBe('Ping')
+    expect(result.eventTexts.get('event:7')?.textContent).toBe('greeting')
+    // the message line gets the transparent hit-overlay sibling, like
+    // mermaid's correlators
+    const overlay = svg.querySelector('[data-mw-hit-overlay="event:3"]')
+    expect(overlay).toBeTruthy()
+    expect(overlay!.getAttribute('d')).toBe(result.events.get('event:3')!.getAttribute('d'))
+  })
+
+  it('never tags scenery: activations, destroy marks and fragments carry no entity', () => {
+    const { result, svg } = correlate(SAMPLE)
+    // rect.pele-activation shares the participant's data-id — the participant
+    // sweep only covers g.pele-node.pele-actor groups, so the activation rect
+    // itself stays untagged and selects nothing
+    for (const el of svg.querySelectorAll('rect.pele-activation')) {
+      expect(el.hasAttribute('data-mw-entity')).toBe(false)
+      expect(el.closest('[data-mw-entity]')).toBeNull()
+    }
+    // g.pele-frame (fragments) and its children are scenery
+    for (const el of svg.querySelectorAll('g.pele-frame')) {
+      expect(el.hasAttribute('data-mw-entity')).toBe(false)
+      expect(el.closest('[data-mw-entity]')).toBeNull()
+      for (const child of el.querySelectorAll('*')) {
+        expect(child.hasAttribute('data-mw-entity')).toBe(false)
+      }
+    }
+    // the lifelines / activations / frames layers contain no tagged element
+    // at all beyond what the events themselves own (none of them live there)
+    expect(svg.querySelectorAll('.pele-lifelines [data-mw-entity]')).toHaveLength(0)
+    expect(svg.querySelectorAll('.pele-activations [data-mw-entity]')).toHaveLength(0)
+    expect(svg.querySelectorAll('.pele-frames [data-mw-entity]')).toHaveLength(0)
+    // result completeness is pinned above; nothing failed
+    expect(result.failed).toEqual([])
+  })
+
+  it('adversarial: a note inserted mid-sequence shifts message i<N> ids, the order zip still pairs', () => {
+    const { result, svg, graph } = correlate(INSERTED)
+    // core: event:3 Hello, event:5 note(inserted), event:6 Hi, event:8
+    // note(greeting), event:10 Ping
+    expect(graph.events.map((e) => e.entityId)).toEqual(['event:3', 'event:5', 'event:6', 'event:8', 'event:10'])
+    expect(graph.events.map((e) => e.kind)).toEqual(['message', 'note', 'message', 'note', 'message'])
+    // the fixture really shifts the ids: messages render i0, i3, i7 (not
+    // i0, i2, i6) and notes i2, i5 — pin the shift so the pairing assertions
+    // below are proving order-matching, not id-matching
+    expect([...svg.querySelectorAll('g.pele-message')].map((g) => g.getAttribute('data-id'))).toEqual([
+      'i0',
+      'i3',
+      'i7',
+    ])
+    expect([...svg.querySelectorAll('g.pele-note')].map((g) => g.getAttribute('data-id'))).toEqual(['i2', 'i5'])
+    // the zip pairs by document order within each kind, not by the shifted ids
+    const msgLine = (id: string) =>
+      svg.querySelector(`g.pele-message[data-id="${id}"] path:not([data-mw-hit-overlay]):not(.pele-marker)`)
+    expect(result.failed).toEqual([])
+    expect(result.events.get('event:3')).toBe(msgLine('i0'))
+    expect(result.events.get('event:6')).toBe(msgLine('i3'))
+    expect(result.events.get('event:10')).toBe(msgLine('i7'))
+    expect(result.events.get('event:5')).toBe(svg.querySelector('g.pele-note[data-id="i2"] > rect'))
+    expect(result.events.get('event:8')).toBe(svg.querySelector('g.pele-note[data-id="i5"] > rect'))
+    // texts follow the same order pairing (labels share the shifted ids yet
+    // pair by group data-id equality; notes by their inner text)
+    expect(result.eventTexts.get('event:3')?.textContent).toBe('Hello')
+    expect(result.eventTexts.get('event:5')?.textContent).toBe('inserted')
+    expect(result.eventTexts.get('event:6')?.textContent).toBe('Hi')
+    expect(result.eventTexts.get('event:8')?.textContent).toBe('greeting')
+    expect(result.eventTexts.get('event:10')?.textContent).toBe('Ping')
+  })
+
+  it('leaves lifelines empty under a hidden mount (zero-width svg) and correlates everything else', () => {
+    // mirrors mermaid's correlateSequence guard: an unlaid-out svg must not
+    // correlate lifelines — the view's visibility retry re-correlates on
+    // reveal (see the view-level test below)
+    const { result } = correlate(SAMPLE, { visible: false })
+    expect(result.lifelines.size).toBe(0)
+    expect(result.participants.size).toBe(2)
+    expect(result.events.size).toBe(4)
+    expect(result.eventTexts.size).toBe(4)
+    expect(result.failed).toEqual([])
+  })
+
+  it('never tags destroy marks, and a destroyed participant keeps its single remaining twin', () => {
+    const code = `sequenceDiagram
+  participant Alice
+  participant Bob
+  Alice->>Bob: Hello
+  destroy Bob
+  Bob-->>Alice: never
+`
+    const { result, svg } = correlate(code)
+    expect(result.failed).toEqual([])
+    expect(result.events.size).toBe(2)
+    // pele renders the destroy mark as g.pele-destroys > path.pele-destroy —
+    // core has no entity for it, so it must select nothing
+    const marks = svg.querySelectorAll('.pele-destroy, .pele-destroys')
+    expect(marks.length).toBeGreaterThan(0)
+    for (const el of marks) {
+      expect(el.hasAttribute('data-mw-entity')).toBe(false)
+      expect(el.closest('[data-mw-entity]')).toBeNull()
+    }
+    // the destroyed participant renders only its top box — the data-id pass
+    // still stores that single twin, so selection and popover keep working
+    expect(svg.querySelectorAll('g.pele-actor[data-id="Bob"]')).toHaveLength(1)
+    expect(result.participants.get('participant:Bob')!).toHaveLength(1)
+    expect(result.participants.get('participant:Alice')!).toHaveLength(2)
+  })
+
+  it('degrades a kind whose counts disagree to view-only instead of mis-zipping (synthetic)', () => {
+    const svg = syntheticSvg(`
+      <g class="pele-nodes">
+        <g class="pele-node pele-actor pele-actor-footer" data-id="A"><rect/></g>
+        <g class="pele-node pele-actor" data-id="A"><rect/></g>
+      </g>
+      <g class="pele-edges">
+        <g class="pele-edge pele-message" data-id="i0"><path d="M0,0H10"/></g>
+        <g class="pele-edge pele-message" data-id="i2"><path d="M0,5H10"/></g>
+      </g>
+      <g class="pele-edge-labels">
+        <g class="pele-edge-label" data-id="i0"><text>hello</text></g>
+        <g class="pele-edge-label" data-id="i2"><text>bye</text></g>
+      </g>
+      <g class="pele-notes">
+        <g class="pele-note" data-id="i1"><rect/><text class="pele-label">note</text></g>
+      </g>`)
+    stampWidth(svg, 400)
+    // two rendered messages but only one message event: a zip would pair the
+    // second message with nothing — every message degrades instead
+    const graph = fakeGraph(['A'], ['message', 'note'])
+    const result = correlatePeleSequence(svg, graph)
+    expect(result.failed).toEqual(['event:1'])
+    expect(result.events.has('event:1')).toBe(false)
+    expect(result.eventTexts.has('event:1')).toBe(false)
+    // nothing in the message/label layers is tagged
+    expect(svg.querySelectorAll('.pele-edges [data-mw-entity]')).toHaveLength(0)
+    expect(svg.querySelectorAll('.pele-edge-labels [data-mw-entity]')).toHaveLength(0)
+    // the well-counted note still correlates
+    expect(result.events.get('event:2')).toBe(svg.querySelector('g.pele-note > rect'))
+    expect(result.eventTexts.get('event:2')?.textContent).toBe('note')
+  })
+
+  it('zips message labels by document order when data-id pairing is unavailable (synthetic)', () => {
+    const svg = syntheticSvg(`
+      <g class="pele-edges">
+        <g class="pele-edge pele-message"><path d="M0,0H10"/></g>
+        <g class="pele-edge pele-message"><path d="M0,5H10"/></g>
+      </g>
+      <g class="pele-edge-labels">
+        <g class="pele-edge-label"><text>hello</text></g>
+        <g class="pele-edge-label"><text>bye</text></g>
+      </g>`)
+    stampWidth(svg, 400)
+    const graph = fakeGraph([], ['message', 'message'])
+    const result = correlatePeleSequence(svg, graph)
+    expect(result.failed).toEqual([])
+    // no data-id to pair on — the count-checked document-order fallback zips
+    expect(result.eventTexts.get('event:1')?.textContent).toBe('hello')
+    expect(result.eventTexts.get('event:2')?.textContent).toBe('bye')
+    expect(result.eventTexts.get('event:1')?.getAttribute('data-mw-entity')).toBe('event:1')
+    expect(result.eventTexts.get('event:2')?.getAttribute('data-mw-entity')).toBe('event:2')
+  })
+
+  it('zips leftover participants by twin buckets, count-checked (synthetic)', () => {
+    const svg = syntheticSvg(`
+      <g class="pele-nodes">
+        <g class="pele-node pele-actor pele-actor-footer" data-id="gen1"><rect/></g>
+        <g class="pele-node pele-actor pele-actor-footer" data-id="gen2"><rect/></g>
+        <g class="pele-node pele-actor" data-id="gen1"><rect/></g>
+        <g class="pele-node pele-actor" data-id="gen2"><rect/></g>
+      </g>`)
+    stampWidth(svg, 400)
+    // pele stamps generated ids core cannot name: equal counts of unmatched
+    // participants and unclaimed twin buckets zip in document order
+    const result = correlatePeleSequence(svg, fakeGraph(['P1', 'P2'], []))
+    expect(result.failed).toEqual([])
+    const p1 = result.participants.get('participant:P1')!
+    const p2 = result.participants.get('participant:P2')!
+    expect(p1).toHaveLength(2)
+    expect(p2).toHaveLength(2)
+    expect(p1.every((el) => el.getAttribute('data-id') === 'gen1')).toBe(true)
+    expect(p2.every((el) => el.getAttribute('data-id') === 'gen2')).toBe(true)
+    expect(p1[0].getAttribute('data-mw-entity')).toBe('participant:P1')
+    expect(p2[0].getAttribute('data-mw-entity')).toBe('participant:P2')
+  })
+
+  it('degrades leftover participants whose twin buckets do not add up (synthetic)', () => {
+    const svg = syntheticSvg(`
+      <g class="pele-nodes">
+        <g class="pele-node pele-actor pele-actor-footer" data-id="gen1"><rect/></g>
+        <g class="pele-node pele-actor" data-id="gen1"><rect/></g>
+        <g class="pele-node pele-actor" data-id="gen2"><rect/></g>
+      </g>`)
+    stampWidth(svg, 400)
+    // three unclaimed groups — no twin structure to key a zip on: both
+    // participants degrade rather than risk a mis-pair
+    const result = correlatePeleSequence(svg, fakeGraph(['P1', 'P2'], []))
+    expect(result.failed).toEqual(['participant:P1', 'participant:P2'])
+    expect(result.participants.size).toBe(0)
+    expect(svg.querySelectorAll('[data-mw-entity]')).toHaveLength(0)
+  })
+})
+
+describe('pele sequence through the view (lifeline UI, visibility retry, label edit)', () => {
+  type IOCallback = (entries: Array<{ intersectionRatio: number }>) => void
+  type ObserverRecord = { target: Element | null; fire(ratio: number): void; disconnected: boolean }
+  let observers: ObserverRecord[]
+  let restoreIO: () => void
+  let container: HTMLElement
+  let view: MermaidCanvasView | undefined
+
+  function installIntersectionObserverStub() {
+    const Original = (globalThis as { IntersectionObserver?: unknown }).IntersectionObserver
+    class StubObserver {
+      private record: ObserverRecord
+      constructor(cb: IOCallback) {
+        this.record = {
+          target: null,
+          fire: (ratio: number) => cb([{ intersectionRatio: ratio }]),
+          disconnected: false,
+        }
+        observers.push(this.record)
+      }
+      observe(el: Element) {
+        this.record.target = el
+      }
+      disconnect() {
+        this.record.disconnected = true
+      }
+      unobserve() {}
+      takeRecords() {
+        return []
+      }
+    }
+    ;(globalThis as { IntersectionObserver?: unknown }).IntersectionObserver = StubObserver as unknown
+    return () => {
+      ;(globalThis as { IntersectionObserver?: unknown }).IntersectionObserver = Original
+    }
+  }
+
+  const flush = async () => {
+    for (let i = 0; i < 5; i++) await new Promise((r) => setTimeout(r, 0))
+  }
+
+  beforeEach(() => {
+    observers = []
+    restoreIO = installIntersectionObserverStub()
+    container = document.createElement('div')
+    document.body.appendChild(container)
+    hosts.push(container)
+  })
+
+  afterEach(() => {
+    view?.destroy()
+    restoreIO()
+    for (const host of hosts.splice(0)) host.remove()
+  })
+
+  it('renders the sample under pele, arms the visibility retry for sequence on a hidden mount, and re-correlates on reveal', async () => {
+    const editor = new MermaidWysiwygEditor({ code: SAMPLE })
+    view = new MermaidCanvasView({
+      editor,
+      container,
+      renderer: peleAdapter({ render: (src) => peleRender(src) }),
+      debounceMs: 0,
+    })
+    await flush()
+
+    const svg = container.querySelector('svg')!
+    expect(svg).toBeTruthy()
+    const seq = view as unknown as {
+      seqCorrelation: {
+        participants: Map<string, Element[]>
+        lifelines: Map<string, Element>
+        events: Map<string, Element>
+        eventTexts: Map<string, Element>
+        failed: string[]
+      } | null
+      visibilityRetryObserver: unknown
+    }
+
+    // entities tagged in the live DOM
+    expect(container.querySelectorAll('[data-mw-entity="participant:Alice"]')).toHaveLength(2)
+    expect(container.querySelectorAll('[data-mw-entity="event:3"]').length).toBeGreaterThan(0)
+    expect(container.querySelectorAll('[data-mw-entity="event:7"]').length).toBeGreaterThan(0)
+
+    // hidden mount (jsdom lays nothing out — zero-width svg): everything but
+    // lifelines correlates, and the visibility retry is ARMED for sequence
+    expect(seq.seqCorrelation!.failed).toEqual([])
+    expect(seq.seqCorrelation!.participants.size).toBe(2)
+    expect(seq.seqCorrelation!.events.size).toBe(4)
+    expect(seq.seqCorrelation!.lifelines.size).toBe(0)
+    expect(observers.length).toBe(1)
+    expect(observers[0].target).toBe(svg)
+    expect(seq.visibilityRetryObserver).not.toBeNull()
+
+    // reveal: the svg now has geometry; the one-shot fires and re-correlates
+    // through the PELE correlator — lifelines fill from path[data-id] (the
+    // mermaid correlator would find no line.actor-line and leave them empty)
+    stampWidth(svg, 400)
+    observers[0].fire(0.5)
+    expect(seq.seqCorrelation!.lifelines.size).toBe(2)
+    expect(seq.seqCorrelation!.lifelines.get('participant:Alice')?.classList.contains('pele-lifeline')).toBe(true)
+    expect(seq.seqCorrelation!.events.size).toBe(4)
+    // the one-shot consumed itself
+    expect(seq.visibilityRetryObserver).toBeNull()
+    expect(observers[0].disconnected).toBe(true)
+  })
+
+  it('does not re-arm after a re-render once lifelines correlated (visible mount)', async () => {
+    const editor = new MermaidWysiwygEditor({ code: SAMPLE })
+    view = new MermaidCanvasView({
+      editor,
+      container,
+      renderer: peleAdapter({ render: (src) => peleRender(src) }),
+      debounceMs: 0,
+    })
+    await flush()
+    const seq = view as unknown as {
+      seqCorrelation: { lifelines: Map<string, Element> } | null
+      visibilityRetryObserver: unknown
+    }
+    // hidden first pass armed the retry (jsdom lays nothing out)
+    expect(observers).toHaveLength(1)
+    expect(seq.seqCorrelation!.lifelines.size).toBe(0)
+
+    // make the environment "visible": every svg root now reports real
+    // geometry, so the re-render correlates lifelines on the first pass
+    const rect = {
+      left: 0,
+      right: 400,
+      top: 0,
+      bottom: 400,
+      width: 400,
+      height: 400,
+      x: 0,
+      y: 0,
+      toJSON: () => ({}),
+    }
+    const spy = vi.spyOn(SVGSVGElement.prototype, 'getBoundingClientRect').mockReturnValue(rect as DOMRect)
+    try {
+      editor.setCode(SAMPLE + ' ', 'external')
+      await flush()
+    } finally {
+      spy.mockRestore()
+    }
+    // the second render correlated lifelines and did NOT arm a new retry:
+    // the first observer is the only one ever, and it was disconnected
+    expect(observers).toHaveLength(1)
+    expect(observers[0].disconnected).toBe(true)
+    expect(seq.seqCorrelation!.lifelines.size).toBe(2)
+    expect(seq.visibilityRetryObserver).toBeNull()
+  })
+
+  it("round-trips a note text edit through the view's sequence machinery (style ops stop-and-ruled: core has none)", async () => {
+    const editor = new MermaidWysiwygEditor({ code: SAMPLE })
+    view = new MermaidCanvasView({
+      editor,
+      container,
+      renderer: peleAdapter({ render: (src) => peleRender(src) }),
+      debounceMs: 0,
+    })
+    await flush()
+
+    // the sequence "edit text" op is the closest visible round-trip to a
+    // style op (core defines no seq style op — see report). The overlay
+    // editor anchors on the note's eventTexts element.
+    view.editEntityLabel('event:7')
+    const overlay = container.querySelector<HTMLElement>('.mw-inplace-editor')!
+    expect(overlay).not.toBeNull()
+    expect(overlay.textContent).toBe('greeting')
+    overlay.textContent = 'salutations'
+    overlay.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }))
+    expect(editor.code).toContain('salutations')
+    await flush()
+
+    // the re-render re-correlated: the note still tags, its text updated
+    expect(container.querySelector('[data-mw-entity="event:7"]')).toBeTruthy()
+    const svg = container.querySelector('svg')!
+    expect(svg.textContent).toContain('salutations')
+  })
+})
diff --git a/packages/dom/test/correlate-pele.test.ts b/packages/dom/test/correlate-pele.test.ts
index 8aa3b6b..c10679c 100644
--- a/packages/dom/test/correlate-pele.test.ts
+++ b/packages/dom/test/correlate-pele.test.ts
@@ -324,9 +324,10 @@ describe('view dispatch', () => {
     expect(container.querySelector('[data-mw-entity="node:A"]')).toBeTruthy()
   })
 
-  it('renders non-flowchart slots view-only under pele', async () => {
-    // sequence has no pele correlator (its correlation is mermaid-only) —
-    // the view-only fallback is pinned with a slot that still lacks one
+  it('dispatches sequence diagrams through the pele sequence correlator', async () => {
+    // sequence used to be the one view-only slot under pele (its correlation
+    // was mermaid-only, pre task-7); now it dispatches through
+    // correlatePeleSequence like every other slot
     const editor = new MermaidWysiwygEditor({
       code: 'sequenceDiagram\n  Alice->>Bob: Hi\n',
     })
@@ -339,6 +340,7 @@ describe('view dispatch', () => {
     views.push(view)
     await flush()
     expect(container.querySelector('svg')).toBeTruthy()
-    expect(container.querySelectorAll('[data-mw-entity]')).toHaveLength(0)
+    expect(container.querySelectorAll('[data-mw-entity="participant:Alice"]')).toHaveLength(2)
+    expect(container.querySelector('[data-mw-entity="event:1"]')).toBeTruthy()
   })
 })

From 7ab3d8125884d1322600793e3c4c57a3f4605dbc Mon Sep 17 00:00:00 2001
From: Casey Gollan <hello@caseyagollan.com>
Date: Sun, 1 Nov 2026 18:46:23 -0500
Subject: [PATCH 21/21] =?UTF-8?q?docs:=20pele=20full-coverage=20=E2=80=94?=
 =?UTF-8?q?=20notice,=20testing=20map,=20readme?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md                                   |  3 ++-
 TESTING.md                                  | 14 +++++++++-----
 apps/playground/src/App.tsx                 |  5 +++--
 packages/dom/src/correlate.pele.sequence.ts |  2 +-
 4 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 5cebf1d..557cfb6 100644
--- a/README.md
+++ b/README.md
@@ -101,7 +101,7 @@ pnpm install && pnpm dev   # playground at http://localhost:5173
 | [block](https://mermaid.js.org/syntax/block.html) | ✅ | ✅ | ❌ |
 | [zenuml](https://mermaid.js.org/syntax/zenuml.html) | ✅ | ❌ | ❌ |
 
-**Item editing** is select, edit in place, add, and delete; **structural editing** adds connect, reorder, and restyle. Every type round-trips losslessly and syncs selection between code and canvas, including view-only zenuml (an external plugin).
+**Item editing** is select, edit in place, add, and delete; **structural editing** adds connect, reorder, and restyle. Every type round-trips losslessly and syncs selection between code and canvas, including view-only zenuml (an external plugin). All editable types also work when rendering through Pele (`peleAdapter` in `@visimer/dom`) — most edit fully there; a few gitgraph/architecture/c4 items remain view-only pending follow-up, and zenuml is Mermaid-only since it is an external plugin.
 
 ## Packages
 
@@ -122,6 +122,7 @@ Some other editor? Implement the adapter, it's about forty lines.
 ## Architecture
 - Leverages the native Mermaid.js renderer for visualizing the Mermaid diagram true to how it’s intended. We just overlay/add point-edit functionality on top.
 - We map the rendered SVG elements back to a Concrete Syntax Tree (CST) representation, which we can then use to edit only the parts of the Mermaid source that need updating (without affecting the rest of the file).
+- The canvas renders through a swappable renderer seam: bring your own `mermaid` instance, or render via Pele by passing a `peleAdapter` (from `@visimer/dom`). Every editable diagram type works under both renderers — under Pele a few gitgraph/architecture/c4 items remain view-only pending follow-up, and zenuml is a Mermaid-only external plugin.
 
 ## Design
 
diff --git a/TESTING.md b/TESTING.md
index 037fd68..bb2450a 100644
--- a/TESTING.md
+++ b/TESTING.md
@@ -14,7 +14,8 @@ test exercises the seam.
 | CodeMirror binding | `@visimer/codemirror` against a real CodeMirror 6 `EditorView` | `packages/codemirror/test/binding.test.ts` (jsdom): engine ops → view, view edits → engine, decorations in the DOM, caret → entity selection, engine-authoritative undo, teardown | A |
 | Monaco binding | `@visimer/monaco` against the structural editor interface it binds | `packages/monaco/test/binding.test.ts`: fake implementing exactly the bound surface (both sync directions, decorations, caret reasons, undo keys, dispose), plus a compile-time conformance check that real `monaco-editor` types satisfy the interface | B |
 | Canvas render loop (what makes `@visimer/dom` re-render) | The triggers and the guards on them: source changes, config changes, and the webfont-settled re-measure that keeps labels from being clipped on a cold load | `packages/dom/test/fonts.test.ts` drives a real `MermaidCanvasView` over a fake mermaid and a stubbed `FontFaceSet`: re-renders once when fonts land late, never when they were already there, never after `destroy()`, never where the document exposes no font set | B |
-| SVG correlation (dom package ↔ Mermaid's rendered DOM) | Third-party dependency seam: correlators key off Mermaid's internal SVG structure, which can shift between Mermaid releases | None automated. Verified manually in the playground across all 23 diagram types | uncovered |
+| SVG correlation — mermaid side (dom package ↔ Mermaid's rendered DOM) | Third-party dependency seam: correlators key off Mermaid's internal SVG structure, which can shift between Mermaid releases | None automated. Verified manually in the playground across all 23 diagram types | uncovered |
+| SVG correlation — pele side (dom package ↔ pele's rendered SVG) | Third-party dependency seam: pele correlators key off pele's internal SVG structure | `packages/dom/test/correlate-pele*.test.ts` (~100 fixture tests, one suite per correlation family group; jsdom; pele's metrics fallback) render real pele SVG — flowchart, sequence, state, class, ER, pie, gantt, and the 15 line-item types — and assert entities were tagged, ambiguous matches degraded (never mis-paired), scenery left untagged, and edits round-tripped visibly through the view | A |
 | Canvas interaction layer (popovers, drag, in-place editing) | `@visimer/dom` gestures compiled to engine ops | None automated. Verified manually in the playground | uncovered |
 | React bindings | `@visimer/react` hooks/components over core events | None automated. Thin subscription layer; exercised manually via the playground | uncovered |
 
@@ -23,8 +24,11 @@ test exercises the seam.
 What the current suite cannot catch:
 
 - **A Mermaid upgrade that shifts the rendered SVG structure.** This is the
-  highest-risk seam. Correlators fail soft (elements degrade to view-only),
-  so the failure is silent feature loss, not a crash. Closing it needs a
+  highest-risk seam on the Mermaid side. Correlators fail soft (elements
+  degrade to view-only), so the failure is silent feature loss, not a crash.
+  The pele side of this seam is now covered: every diagram family has a
+  real-render fixture suite (`correlate-pele*.test.ts`) asserting entities
+  were tagged and degraded sanely. Closing the Mermaid side still needs a
   real-browser rung (vitest browser mode or Playwright) that renders real
   Mermaid per diagram type and asserts entities were tagged; jsdom cannot
   provide it because Mermaid layout requires real text measurement.
@@ -38,8 +42,8 @@ What the current suite cannot catch:
 - **React render-loop regressions** (stale subscriptions, effect ordering).
   Would need @testing-library/react coverage.
 
-The playground doubles as the manual harness for all three: every editable
-type has a sample, and the toolbar/popovers exercise the gesture surface.
+The playground doubles as the manual harness for the uncovered seams: every
+editable type has a sample, and the toolbar/popovers exercise the gesture surface.
 
 ## Running
 
diff --git a/apps/playground/src/App.tsx b/apps/playground/src/App.tsx
index f6fcda3..ae3e543 100644
--- a/apps/playground/src/App.tsx
+++ b/apps/playground/src/App.tsx
@@ -257,8 +257,9 @@ function Workspace({ code, theme, readOnly, renderer }: { code: string; theme: s
         </div>
         {renderer === 'pele' && (
           <div className="notice" role="note">
-            <strong>Pele</strong> renders flowcharts only as far as editing goes: flowcharts are
-            editable, every other diagram type renders view-only, and zenuml is unsupported.
+            <strong>Pele</strong> renderer: every editable diagram type renders here and is
+            editable, except zenuml (external plugin — Pele restriction). A few legacy
+            correlator gaps stay view-only (some gitgraph/architecture/c4 items).
           </div>
         )}
         <MermaidCanvas
diff --git a/packages/dom/src/correlate.pele.sequence.ts b/packages/dom/src/correlate.pele.sequence.ts
index a58ffb7..738d897 100644
--- a/packages/dom/src/correlate.pele.sequence.ts
+++ b/packages/dom/src/correlate.pele.sequence.ts
@@ -32,7 +32,7 @@ import { decodeEntities } from './correlate.pele'
  * `getBoundingClientRect` is zero, so the view's visibility retry contract
  * (empty lifelines ⇒ re-correlate on reveal) stays intact.
  *
- * Scenery core has no entity for is never tagged: `rect.pele-activation`
+ * Scenery (which core has no entity for) is never tagged: `rect.pele-activation`
  * (which shares the participant's data-id!), destroy marks and `g.pele-frame`
  * fragments — clicking them selects nothing.
  */