merpeeps-mermaid-layout 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Merpeeps contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,235 @@
+# merpeeps-mermaid-layout
+
+**Save node positions and styling for Mermaid diagrams inside the diagram file
+— and render them.**
+
+A Mermaid layout plugin, plus the metadata format behind it. Part of the
+[Merpeeps project](https://github.com/sargeMonkey/merpeeps), which also provides a
+visual editor for placing the boxes in the first place.
+
+```bash
+npm install merpeeps-mermaid-layout
+```
+
+## The problem
+
+Mermaid has no coordinate system. Positions are derived by the layout engine at
+render time, so there is nowhere in the syntax to say *"this node goes here"*.
+Every visual editor built on Mermaid runs into the same wall, and each one
+invents its own private way to remember an arrangement — a sidecar file, a
+database row, a proprietary format. None of them interoperate, and the moment
+you leave that editor, the arrangement is gone.
+
+## The approach
+
+Put the metadata in the file, under an unknown YAML frontmatter key.
+
+```mermaid
+---
+title: Order fulfilment
+x-merpeeps:
+  spec: 1
+  layout:
+    engine: manual
+    nodes:
+      gw: { x: 60,  y: 130 }
+      db: { x: 300, y: 130 }
+---
+flowchart LR
+    gw[Gateway] --> db[(Database)]
+```
+
+Mermaid ignores frontmatter keys it does not recognise, so this file renders
+**byte-for-byte identically** to the same file without the `x-merpeeps` block. Your
+editor reads the positions; every other tool sees a perfectly ordinary Mermaid
+diagram; git sees a readable text diff.
+
+This is verified, not assumed — see [Verification](#verification).
+
+## Usage
+
+```js
+import { getPositions, setPositions, validate, strip } from 'merpeeps-mermaid-layout';
+
+const src = `flowchart LR\n    a[Start] --> b[End]\n`;
+
+// Remember an arrangement.
+const saved = setPositions(src, {
+  a: { x: 0,   y: 0 },
+  b: { x: 220, y: 0 },
+});
+
+// Read it back.
+getPositions(saved);        // → { a: { x: 0, y: 0 }, b: { x: 220, y: 0 } }
+
+// The diagram itself is untouched.
+strip(saved) === src;       // → true
+
+// Check the invariants without a renderer.
+validate(saved).ok;         // → true
+```
+
+### API
+
+| Function | Purpose |
+|---|---|
+| `getPositions(src)` | Node positions keyed by node id |
+| `setPositions(src, positions, opts?)` | Write positions, replacing any existing layout |
+| `getStyles(src)` / `setStyles(src, styles)` | Per-node fill, stroke, icon and so on |
+| `parse(src)` / `serialise(src, merpeeps, opts?)` | The raw metadata block |
+| `inject(src, patch)` | Deep-merge a partial update |
+| `strip(src)` | Remove all metadata — plain Mermaid again |
+| `bodyOf(src)` | Diagram body only, metadata removed |
+| `staleIds(src, knownIds)` | Positions whose node no longer exists |
+| `validate(src)` | Check the offline invariants |
+
+From `merpeeps-mermaid-layout/mermaid`:
+
+| Function | Purpose |
+|---|---|
+| `registerMerpeepsLayout(mermaid)` | Register the layout algorithm once |
+| `renderWithLayout(mermaid, id, src, el?)` | Render honouring stored positions and styling |
+| `applyNodeStyle(nodeEl, style)` | Paint one already-rendered node |
+| `styleSvg(svg, styles)` | Apply stored styling to a rendered SVG string |
+
+Full type definitions ship with the package.
+
+## Rendering at the stored positions
+
+Storing an arrangement is only half of it — something has to *draw* it. The
+package ships a mermaid layout plugin, so any mermaid-based viewer can honour a
+saved layout **and its styling** instead of re-deriving one:
+
+```js
+import mermaid from 'mermaid';
+import { registerMerpeepsLayout, renderWithLayout } from 'merpeeps-mermaid-layout/mermaid';
+
+registerMerpeepsLayout(mermaid);
+
+const { svg } = await renderWithLayout(mermaid, 'diagram-1', source);
+```
+
+`renderWithLayout` falls straight through to `mermaid.render` when a document
+stores no positions, or when it uses subgraphs (cluster bounds are not
+determined by node positions alone). Stored styling is applied on either path,
+so the result is never worse than stock mermaid.
+
+The layout selection is injected **in memory only** and never written to your
+file. A document that depends on a plugin being installed is exactly the
+lock-in this format exists to avoid.
+
+### Why it needs the `renderWithLayout` wrapper
+
+A registered mermaid layout algorithm receives a `LayoutData`, not the source
+text, and mermaid drops unknown frontmatter keys before that point — so the
+algorithm cannot read the Merpeeps block itself. It does receive `diagramId`, and the
+caller has both the id and the text, so the wrapper bridges the two. This was
+established by probing a live mermaid build, not by reading its types.
+
+### Styling
+
+Stored `fill`, `stroke`, `strokeWidth`, `dashed` and `text` are painted onto the
+rendered SVG rather than pushed through mermaid's `style`/`classDef` syntax.
+Writing style into the diagram body would change the file, and the whole point
+of Merpeeps is that presentation can be stored *without* touching what the diagram
+says.
+
+### Two carriers
+
+Frontmatter is the default and works for every diagram type. Some hosts strip
+frontmatter, so a comment carrier is available as a fallback:
+
+```js
+serialise(src, merpeeps, { carrier: 'comment' });
+// → …\n%% merpeeps1 {"spec":1,"layout":{…}}
+```
+
+Mermaid's `@{ ... }` node metadata was considered and rejected as the primary
+carrier: it is **flowchart-only**, unavailable in C4, architecture and the other
+graph types.
+
+## Guarantees
+
+1. **The body is never modified.** Writing metadata is byte-preserving; the
+   diagram text you wrote is the diagram text that stays on disk.
+2. **Writing twice converges.** No churn in git from repeated saves.
+3. **Nothing leaks into the rendered output.** No metadata token appears in the
+   SVG a stock renderer produces.
+4. **Stale entries are reported, never deleted.** Renaming a node in text does
+   not silently destroy the layout you arranged — `staleIds` tells you, and you
+   decide.
+
+## Verification
+
+The degradation claim is the one everything else depends on, so it is measured
+rather than asserted. The reference suite renders every Mermaid diagram type
+twice — once plain, once with metadata attached — in a real browser, and
+compares the results.
+
+Against **Mermaid 11.16.1**:
+
+| Claim | Result |
+|---|---|
+| Unknown frontmatter keys are ignored | ✅ every diagram type |
+| `%%` comments are ignored | ✅ every diagram type |
+| Extended file renders identically to the plain file | ✅ 30 / 30 renderable types |
+| No metadata reaches the rendered surface | ✅ zero leaks |
+
+Two details worth knowing if you build your own checker: leak detection must
+scan the *user-visible* text rather than the raw SVG, because short numeric
+tokens collide with floating-point path data; and a few diagram types are
+non-deterministic between renders, so a baseline has to be rendered twice before
+a difference can be blamed on your change.
+
+## Scope
+
+This package is the **storage contract** plus a renderer that honours it. It
+stores positions and can draw them; it does not *compute* them. That is
+deliberate — the value is in every tool agreeing on where an arrangement lives,
+and shipping a layout algorithm would only invite disagreement about which one
+is best. Bring your own layout, or a user's mouse.
+
+### Not an alternative to `@mermaid-js/layout-elk`
+
+Merpeeps registers through the same plugin interface as the official
+[`@mermaid-js/layout-elk`](https://www.npmjs.com/package/@mermaid-js/layout-elk)
+and [`@mermaid-js/layout-tidy-tree`](https://www.npmjs.com/package/@mermaid-js/layout-tidy-tree),
+which makes them look like competitors. They solve opposite halves of the
+problem:
+
+| | Official layout plugins | Merpeeps |
+|---|---|---|
+| Input | Graph structure | Stored coordinates |
+| Output | A computed arrangement | The arrangement that was saved |
+| Author intent | Cannot be expressed | Is the whole input |
+| Reads externally supplied positions | No | Yes, that is the point |
+| Size | 15 MB (elk) · 242 KB (tidy-tree) | 17 KB |
+
+ELK and tidy-tree are *better algorithms*. Merpeeps is *no algorithm* — it
+reproduces a decision a person already made. Use them together: let ELK do the
+first pass, move the few nodes it got wrong, and save the result.
+
+The format is specified in [`SPEC.md`](./SPEC.md). Implementations exist in
+JavaScript (this package) and C#, checked against a shared conformance suite so
+the two cannot drift apart.
+
+## Licence and names
+
+MIT — see [`LICENSE`](./LICENSE).
+
+**Not affiliated with, endorsed by, or sponsored by Mermaid Chart Inc. or the
+Mermaid open-source project.** "Mermaid" is used here only to describe the file
+format this tool reads and writes.
+
+---
+
+## Part of Merpeeps
+
+| | |
+|---|---|
+| [Repository](https://github.com/sargeMonkey/merpeeps) | Source, issues, and the full story |
+| [Visual editor](https://github.com/sargeMonkey/merpeeps/blob/main/docs/GUIDE.md) | A desktop app for placing the boxes — this package renders what it saves |
+| [SPEC.md](SPEC.md) | The stored format, and what a reader must do with it |
+
+MIT licensed. Not affiliated with, endorsed by, or sponsored by Mermaid Chart
+Inc. or the Mermaid open-source project.

package/SPEC.md

@@ -0,0 +1,252 @@
+# Merpeeps — format specification, v0.1 (draft)
+
+A **type-agnostic** sidecar layer for layout, style and semantics that rides
+inside ordinary Mermaid files and degrades gracefully in stock renderers.
+
+## Design constraints (empirically established)
+
+| Constraint | Evidence |
+|---|---|
+| `@{ }` per-node metadata is **flowchart-only** | mermaid `flowDb.ts` dispatch; not present in architecture/C4 grammars |
+| Unknown YAML frontmatter keys are silently ignored | verified: parse + render clean, mermaid 11.16.1 |
+| `%%` comments are always ignored | verified: parse + render clean |
+| Extension must not alter rendered output | verified: zero leak, identical node/edge counts |
+
+**Chosen carrier: YAML frontmatter under a single namespaced key.**
+Rationale: structured (mermaid already runs `js-yaml` over it), one block rather
+than scattered comments, trivially diffable, and type-agnostic — frontmatter is
+handled by mermaid's common preprocessor, not per-diagram grammars.
+
+`%%` comments are the **fallback carrier** for hosts that strip frontmatter
+(see §6).
+
+## 1. Shape
+
+```yaml
+---
+title: Payment flow              # untouched official key
+x-merpeeps:
+  spec: 1
+  layout:
+    nodes:
+      A: { x: 120, y: 80, w: 160, h: 60 }
+      B: { x: 300, y: 240 }
+    edges:
+      "A->B#0": { waypoints: [[200,150],[260,200]], labelT: 0.5 }
+    viewport: { x: 0, y: 0, zoom: 1 }
+    engine: manual              # manual | dagre | elk | fcose
+  style:
+    nodes:
+      A:
+        fill: "#dae8fc"       # any CSS colour
+        stroke: "#6c8ebf"
+        text: "#1a1a1a"
+        strokeWidth: 2
+        dashed: false
+        icon: gateway         # see §6b
+    edges:
+      "A->B#0": { stroke: "#6c8ebf", width: 2, dash: false }
+  semantics:
+    A: { kind: container, tech: "Node.js", team: platform, url: "…" }
+  extras: {}                     # reserved; preserved verbatim
+---
+flowchart TD
+  A[Start] --> B[End]
+```
+
+Every key is **optional**. A file carrying only `layout.nodes` is valid.
+
+## 2. Identity (the hard part)
+
+The spec joins to the diagram by **entity id**. Mermaid has no universal id
+concept, so each diagram type needs a small *identity adapter* — far smaller
+than a per-type editor.
+
+| Type family | Node identity | Edge identity |
+|---|---|---|
+| flowchart, class, state, ER | declared id | `"<src>-><dst>#<ordinal>"` |
+| sequence | participant id/alias | message ordinal `"#<n>"` |
+| C4, architecture | declared alias | `"<src>-><dst>#<ordinal>"` |
+| pie, venn, radar, xychart | label text (normalised) | n/a |
+| gantt, kanban, timeline | task/item id, else ordinal | n/a |
+| mindmap, treemap, treeView | path from root `"root/a/b"` | n/a |
+
+**Ordinal suffix** (`#0`) disambiguates parallel edges between the same pair.
+Ordinals are assigned in **source order** and are stable under edits that do not
+reorder statements.
+
+**Anonymous entities** get a synthetic, reserved id. A state diagram's `[*]`
+carries no id yet needs a position, and it means *start* in the source position
+but *end* in the target position — so it maps to two distinct ids, `__start` and
+`__end`, rather than one. Reserved ids use a `__` prefix, which mermaid's own
+grammars do not produce.
+
+**Rule:** an identity that no longer resolves is *retained, not deleted*, and
+flagged `stale` — so renaming a node in text never silently destroys its layout.
+
+## 3. Invariants (all machine-checkable)
+
+1. **Degradation** — stock Mermaid renders base and Merpeeps-extended source to the
+   same visible text and the same node/edge counts.
+2. **No leak** — no Merpeeps token appears in rendered output.
+3. **Round-trip** — `serialise(parse(x))` preserves every byte outside the
+   `x-merpeeps` block.
+4. **Idempotence** — applying `serialise(parse(·))` twice equals once.
+5. **Merge safety** — injecting into a file that already has frontmatter must
+   merge, never emit a second `---` block.
+6. **Unknown preservation** — unrecognised keys under `x-merpeeps` survive a
+   round-trip verbatim (forward compatibility).
+7. **Type agnosticism** — 1–6 hold for every Mermaid diagram type that renders.
+
+## 4. Versioning
+
+`spec` is an integer. A reader encountering `spec` greater than it understands
+MUST still render, MUST preserve the block verbatim, and SHOULD warn.
+
+## 5. Why `x-` prefix
+
+Reserves the namespace against future official mermaid frontmatter keys, mirroring
+the `x-` convention in OpenAPI/HTTP. If mermaid later blesses a layout key, Merpeeps
+migrates rather than collides.
+
+## 6. Fallback carrier
+
+Where frontmatter is stripped (some wikis, some markdown pipelines), the same
+document is emitted as a single comment line:
+
+```
+%% merpeeps1 {"layout":{"nodes":{"A":{"x":120,"y":80}}}}
+```
+
+Readers MUST accept either. Writers SHOULD prefer frontmatter.
+
+## 6b. Icon vocabulary
+`style.nodes.<id>.icon` names a glyph drawn in place of a plain box. This is among
+the most-requested node features in mermaid (#1723, 122 👍, open since 2020) and
+is not expressible in mermaid syntax, which is why it belongs here.
+
+### Core names
+
+Names with **no prefix** are the core vocabulary. They are stable, always
+available, and no pack may claim one:
+
+`server`, `database`, `storage`, `queue`, `cache`, `function`, `gateway`,
+`user`, `browser`, `mobile`, `shield`, `cloud`, `cog`
+
+The empty string means "no icon".
+
+### Pack names
+
+Everything else is `pack:name` — `aws:lambda`, `azure:sql`, `bpmn:gateway`. The
+prefix is what stops two independent packs colliding on `gateway`.
+
+```
+icon-name  = core-name / pack-id ":" local-name
+pack-id    = 1*( ALPHA / DIGIT / "-" )        ; lowercase
+local-name = 1*( ALPHA / DIGIT / "-" / "_" )  ; lowercase
+```
+
+A name with more than one `:` is invalid; readers MUST treat it as unknown
+rather than guessing at the intent.
+
+### What an unrecognised name means
+
+**A reader that does not recognise a name MUST draw the plain shape, MUST retain
+the name unchanged, and MUST NOT fail.**
+
+All three clauses carry weight:
+
+- **Draw the plain shape** — a missing pack degrades the picture, never the
+  document. This is also exactly what mermaid does with an unregistered icon
+  pack: the node renders as an ordinary box.
+- **Retain the name** — the same rule as unresolvable node ids in §2. Opening a
+  diagram on a machine without the AWS pack and saving it must not silently
+  strip every AWS icon from a colleague's work. Deletion is never the safe
+  default when the tool is the thing that is missing, not the data.
+- **Do not fail** — a document that will not open because of a decorative
+  reference is a worse outcome than one that opens plainer than intended.
+
+A reader SHOULD surface which packs are referenced but unavailable, so the
+degradation is visible rather than mysterious.
+
+### What packs may not do
+
+A pack MUST NOT define a core name, and MUST NOT redefine another pack's names.
+Where a pack is loaded that violates this, the core or incumbent definition wins
+and the conflict SHOULD be reported. Otherwise installing a pack could silently
+change how an existing diagram looks, which would make icons untrustworthy.
+
+Pack distribution is deliberately out of scope here. This section fixes only
+what a name *means*; how a pack reaches a reader is a tooling concern.
+
+## 6c. Layout constraints
+
+`layout.constraints` expresses arrangement as **relationships** rather than
+coordinates:
+
+```yaml
+layout:
+  constraints:
+    - same-rank: [api, cache]     # keep these on one layer
+    - order: [web, api, db]       # sequence them within their layer
+```
+
+### Why this and not coordinates
+
+Both express layout intent. They differ on what happens when they go stale, and
+that difference is the whole argument:
+
+| | When the diagram changes underneath it |
+|---|---|
+| `x: 10, y: 20` | describes nothing; the node lands somewhere wrong while the picture still looks plausible — **silently wrong** |
+| `same-rank: [a, b]` | stops applying; the engine lays out normally — **correct, just not hand-tuned** |
+
+Wrong-but-plausible is a worse failure than correct-but-ordinary, and it is a
+difference in kind rather than degree. A coordinate is presentational data that
+can *disagree with the graph*; a constraint is semantic and can only become
+irrelevant.
+
+Constraints are also sparse by nature — you state something about the two or
+three nodes you care about — where coordinates pull towards an entry per node,
+so there is far less to keep in step in the first place.
+
+This is what every durable text diagram language converged on independently:
+Graphviz, D2, TikZ and PlantUML all make relationship placement first-class and
+quarantine absolute coordinates into a separate opt-in mode. Mermaid's own
+most-upvoted layout request (#3723, "specify that two nodes should be at the same
+level", 82 👍, open since 2022) is asking for a rank constraint, not a coordinate
+map.
+
+### Tiers
+
+| Tier | Mechanism | When |
+|---|---|---|
+| 0 | nothing | the default; the engine arranges everything |
+| 1 | `layout.constraints` | **the recommended way to influence a layout** |
+| 2 | `layout.nodes` coordinates | pixel-perfect escape hatch, written only on an explicit request |
+
+Tier 2 is not deprecated — constraints cannot reproduce an arbitrary hand-dragged
+arrangement, and nothing else can. It is demoted, not removed.
+
+### Rules
+
+- **Stale ids are retained and reported, never removed.** A constraint naming a
+  node that no longer exists is inert. Deleting it would destroy intent the
+  moment someone renamed a node on a branch.
+- **A group with fewer than two surviving members does nothing.**
+- **`same-rank` moves the group to the deepest member's layer**, never the
+  shallowest. Pulling nodes upwards would place them above their own
+  predecessors and turn forward edges into back edges, which reads as a broken
+  diagram rather than an honoured constraint.
+- **`order` only sequences members that share a layer.** It expresses
+  left-to-right intent, not a demand to move nodes between layers.
+- **Constraint kinds a reader does not model MUST be retained verbatim.**
+  Partial knowledge is worse than none: a reader that parses the list and
+  re-emits only what it understands destroys a newer tool's work merely by
+  opening the file.
+
+## 7. Open questions (need human decision)
+
+- Should `semantics.kind` use a closed C4 vocabulary or be free-form?
+- Should edge waypoints be absolute or relative to endpoints?
+- Do we normalise colour to hex, or preserve author input?

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "merpeeps-mermaid-layout",
+  "version": "0.1.0",
+  "description": "Save node positions and styling for Mermaid diagrams inside the diagram file itself, and render them. A mermaid layout plugin plus the metadata format behind it.",
+  "keywords": [
+    "mermaid",
+    "mermaid-layout",
+    "mermaid-plugin",
+    "mermaid-diagram",
+    "layout",
+    "positions",
+    "diagram",
+    "flowchart",
+    "graph",
+    "frontmatter",
+    "visual-editor",
+    "merpeeps"
+  ],
+  "license": "MIT",
+  "author": "Merpeeps contributors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sargeMonkey/merpeeps.git",
+    "directory": "packages/merpeeps-mermaid-layout"
+  },
+  "homepage": "https://github.com/sargeMonkey/merpeeps#readme",
+  "bugs": {
+    "url": "https://github.com/sargeMonkey/merpeeps/issues"
+  },
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./mermaid": {
+      "types": "./src/mermaid-plugin.d.ts",
+      "default": "./src/mermaid-plugin.js"
+    }
+  },
+  "files": [
+    "src/",
+    "SPEC.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0"
+  },
+  "scripts": {
+    "test": "node --test",
+    "test:package": "node ../../oracle/package-consumer-test.mjs merpeeps-mermaid-layout",
+    "release:check": "npm test && npm run test:package",
+    "prepublishOnly": "npm run release:check"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "sideEffects": false
+}

package/src/index.d.ts

@@ -0,0 +1,98 @@
+/** A node's stored position, in diagram coordinates. */
+export interface Position {
+  x: number;
+  y: number;
+  /** Width. Omitted when the renderer's default is fine. */
+  w?: number;
+  /** Height. Omitted when the renderer's default is fine. */
+  h?: number;
+}
+
+/** Per-node presentation. All fields optional; unknown fields are preserved. */
+export interface NodeStyle {
+  fill?: string;
+  stroke?: string;
+  text?: string;
+  strokeWidth?: number;
+  dashed?: boolean;
+  icon?: string;
+  [key: string]: unknown;
+}
+
+/** The parsed `x-merpeeps` block. Unknown keys are preserved on write. */
+export interface MerpeepsBlock {
+  spec?: number;
+  layout?: {
+    nodes?: Record<string, Position>;
+    engine?: string;
+    [key: string]: unknown;
+  };
+  style?: {
+    nodes?: Record<string, NodeStyle>;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+
+export interface SplitResult {
+  /** Raw frontmatter text, or null when the document has none. */
+  fmText: string | null;
+  /** Parsed frontmatter mapping. Empty when absent or malformed. */
+  fm: Record<string, unknown>;
+  /** Everything after the frontmatter. */
+  body: string;
+}
+
+export interface SerialiseOptions {
+  /**
+   * `'frontmatter'` (default) writes under the `x-merpeeps` key.
+   * `'comment'` writes a `%% merpeeps1 {...}` line instead, for hosts that strip
+   * frontmatter.
+   */
+  carrier?: 'frontmatter' | 'comment';
+}
+
+export interface SetPositionsOptions {
+  /** Free-form note about what produced the layout. Defaults to `'manual'`. */
+  engine?: string;
+}
+
+export interface ValidationIssue {
+  rule: 'parse' | 'shape' | 'spec' | 'layout' | 'body' | 'idempotent';
+  message: string;
+}
+
+export interface ValidationResult {
+  ok: boolean;
+  issues: ValidationIssue[];
+}
+
+export declare const KEY: 'x-merpeeps';
+export declare const SPEC_VERSION: number;
+
+export declare function split(src: string): SplitResult;
+export declare function parse(src: string): MerpeepsBlock | null;
+export declare function serialise(
+  src: string,
+  merpeeps: MerpeepsBlock | null,
+  options?: SerialiseOptions,
+): string;
+export declare function inject(src: string, patch: MerpeepsBlock): string;
+export declare function strip(src: string): string;
+export declare function bodyOf(src: string): string;
+
+export declare function getPositions(src: string): Record<string, Position>;
+export declare function setPositions(
+  src: string,
+  positions: Record<string, Position>,
+  options?: SetPositionsOptions,
+): string;
+
+export declare function getStyles(src: string): Record<string, NodeStyle>;
+export declare function setStyles(
+  src: string,
+  styles: Record<string, NodeStyle>,
+): string;
+
+export declare function staleIds(src: string, knownIds: Iterable<string>): string[];
+export declare function validate(src: string): ValidationResult;

package/src/index.js

@@ -0,0 +1,310 @@
+// Merpeeps v0.1 — store layout, styling and semantics inside ordinary Mermaid files.
+//
+// The whole design rests on one property, verified against Mermaid 11.16.1:
+// an unknown key in YAML frontmatter is ignored by every diagram type, so the
+// metadata rides along invisibly and a stock renderer draws exactly the same
+// picture it would have drawn without it.
+//
+// Pure functions, no DOM, no renderer. Safe in Node and the browser.
+
+import * as yaml from 'js-yaml';
+
+/** The frontmatter key everything lives under. */
+export const KEY = 'x-merpeeps';
+
+/** Spec version written into new blocks. */
+export const SPEC_VERSION = 1;
+
+const FM = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+const COMMENT = /^%%[ \t]*merpeeps1[ \t]+(\{[\s\S]*?\})[ \t]*$/m;
+
+// Removal must consume the comment's own line terminator. Matching only the
+// line content leaves a blank line behind, so stripping metadata would not
+// restore the original body byte-for-byte — which is the one promise the
+// format cannot break.
+const COMMENT_LINE = /^%%[ \t]*merpeeps1[ \t]+\{[\s\S]*?\}[ \t]*(?:\r?\n|$)/m;
+
+// ---------------------------------------------------------------- carrier
+
+/**
+ * Split a Mermaid document into its frontmatter and body.
+ * A document with no frontmatter yields `{ fmText: null, fm: {}, body: src }`.
+ */
+export function split(src) {
+  assertString(src, 'src');
+  const m = src.match(FM);
+  if (!m) return { fmText: null, fm: {}, body: src };
+  let fm = {};
+  try {
+    const loaded = yaml.load(m[1]);
+    fm = loaded && typeof loaded === 'object' && !Array.isArray(loaded) ? loaded : {};
+  } catch {
+    fm = {};
+  }
+  return { fmText: m[1], fm, body: src.slice(m[0].length) };
+}
+
+/**
+ * Read the Merpeeps block: frontmatter first, then the `%% merpeeps1 {...}` fallback.
+ * Returns null when the document carries no metadata.
+ */
+export function parse(src) {
+  const { fm, body } = split(src);
+  if (fm && typeof fm === 'object' && fm[KEY] != null) return fm[KEY];
+
+  const c = body.match(COMMENT) ?? src.match(COMMENT);
+  if (c) {
+    try {
+      return JSON.parse(c[1]);
+    } catch {
+      /* malformed fallback: treat as absent rather than throwing */
+    }
+  }
+  return null;
+}
+
+/**
+ * Write an Merpeeps block into `src`, merging into any existing frontmatter.
+ *
+ * Never emits a second `---` block, and never alters the diagram body.
+ * Pass `merpeeps = null` to remove the block entirely.
+ */
+export function serialise(src, merpeeps, { carrier = 'frontmatter' } = {}) {
+  assertString(src, 'src');
+  const { fm, body } = split(src);
+
+  if (carrier === 'comment') {
+    // The comment carrier is self-contained, so a frontmatter copy of the
+    // block would be a second source of truth and is dropped — but the
+    // author's other frontmatter keys are not ours to discard.
+    const rest = { ...fm };
+    delete rest[KEY];
+    const head = withFrontmatter(rest, '');
+    const base = stripComment(body);
+    if (merpeeps == null) return `${head}${base}`;
+
+    // Separate only when the body does not already end with a newline.
+    // Trimming instead would delete trailing blank lines the author wrote.
+    const sep = base.length === 0 || base.endsWith('\n') ? '' : '\n';
+    return `${head}${base}${sep}%% merpeeps1 ${JSON.stringify(merpeeps)}\n`;
+  }
+
+  const next = { ...fm };
+  if (merpeeps == null) delete next[KEY];
+  else next[KEY] = merpeeps;
+  return withFrontmatter(next, stripComment(body));
+}
+
+/** Deep-merge `patch` into the existing Merpeeps block and write it back. */
+export function inject(src, patch) {
+  const cur = parse(src) ?? { spec: SPEC_VERSION };
+  return serialise(src, deepMerge(cur, patch));
+}
+
+/** The document with every Merpeeps carrier removed — plain Mermaid again. */
+export function strip(src) {
+  return serialise(src, null);
+}
+
+/** Body only, with any Merpeeps carrier removed. Used to prove byte-preservation. */
+export function bodyOf(src) {
+  return stripComment(split(src).body);
+}
+
+// ---------------------------------------------------------------- layout
+
+/**
+ * Node positions keyed by diagram node id, e.g. `{ a: { x: 0, y: 0 } }`.
+ * Returns an empty object when the document carries none.
+ */
+export function getPositions(src) {
+  const nodes = parse(src)?.layout?.nodes;
+  if (!nodes || typeof nodes !== 'object') return {};
+
+  const out = {};
+  for (const [id, raw] of Object.entries(nodes)) {
+    if (!raw || typeof raw !== 'object') continue;
+    const x = num(raw.x);
+    const y = num(raw.y);
+    if (x === null || y === null) continue;
+    const entry = { x, y };
+    if (num(raw.w) !== null) entry.w = num(raw.w);
+    if (num(raw.h) !== null) entry.h = num(raw.h);
+    out[id] = entry;
+  }
+  return out;
+}
+
+/**
+ * Write node positions, replacing any existing layout.
+ *
+ * Positions are *replaced* rather than merged, because merging would silently
+ * resurrect nodes the caller had deleted.
+ */
+export function setPositions(src, positions, { engine = 'manual' } = {}) {
+  assertPlainObject(positions, 'positions');
+
+  const nodes = {};
+  for (const [id, p] of Object.entries(positions)) {
+    if (!p || typeof p !== 'object') {
+      throw new TypeError(`position for "${id}" must be an object with x and y`);
+    }
+    const x = num(p.x);
+    const y = num(p.y);
+    if (x === null || y === null) {
+      throw new TypeError(`position for "${id}" needs finite numeric x and y`);
+    }
+    const entry = { x, y };
+    if (num(p.w) !== null) entry.w = num(p.w);
+    if (num(p.h) !== null) entry.h = num(p.h);
+    nodes[id] = entry;
+  }
+
+  const cur = parse(src) ?? {};
+  return serialise(src, {
+    ...cur,
+    spec: cur.spec ?? SPEC_VERSION,
+    layout: { ...cur.layout, nodes, engine },
+  });
+}
+
+/** Per-node presentation (fill, stroke, icon…), keyed by node id. */
+export function getStyles(src) {
+  const nodes = parse(src)?.style?.nodes;
+  return nodes && typeof nodes === 'object' ? { ...nodes } : {};
+}
+
+/** Write per-node presentation, replacing any existing style block. */
+export function setStyles(src, styles) {
+  assertPlainObject(styles, 'styles');
+  const cur = parse(src) ?? {};
+  return serialise(src, {
+    ...cur,
+    spec: cur.spec ?? SPEC_VERSION,
+    style: { ...cur.style, nodes: { ...styles } },
+  });
+}
+
+/**
+ * Positions whose node id no longer appears in `knownIds`.
+ *
+ * Stale entries are reported, never auto-deleted: renaming a node in text
+ * should not silently destroy the layout you spent time arranging.
+ */
+export function staleIds(src, knownIds) {
+  const known = new Set(knownIds ?? []);
+  return Object.keys(getPositions(src)).filter((id) => !known.has(id));
+}
+
+// ------------------------------------------------------------- validation
+
+/**
+ * Check the invariants that do not need a renderer.
+ *
+ * Returns `{ ok, issues }`. Rendering equivalence is the one invariant this
+ * cannot check offline — for that, render both documents and compare.
+ */
+export function validate(src) {
+  const issues = [];
+  const push = (rule, message) => issues.push({ rule, message });
+
+  let merpeeps = null;
+  try {
+    merpeeps = parse(src);
+  } catch (e) {
+    push('parse', `metadata could not be read: ${e.message}`);
+    return { ok: false, issues };
+  }
+
+  if (merpeeps == null) return { ok: true, issues };
+
+  if (typeof merpeeps !== 'object' || Array.isArray(merpeeps)) {
+    push('shape', 'the Merpeeps block must be a mapping');
+    return { ok: false, issues };
+  }
+  if (merpeeps.spec !== undefined && !Number.isInteger(merpeeps.spec)) {
+    push('spec', '"spec" must be an integer when present');
+  }
+
+  const nodes = merpeeps.layout?.nodes;
+  if (nodes !== undefined) {
+    if (!nodes || typeof nodes !== 'object' || Array.isArray(nodes)) {
+      push('layout', 'layout.nodes must be a mapping of id to position');
+    } else {
+      for (const [id, p] of Object.entries(nodes)) {
+        if (!p || typeof p !== 'object') {
+          push('layout', `layout.nodes["${id}"] must be an object`);
+          continue;
+        }
+        if (num(p.x) === null || num(p.y) === null) {
+          push('layout', `layout.nodes["${id}"] needs finite numeric x and y`);
+        }
+      }
+    }
+  }
+
+  // Body preservation is the promise the whole format rests on.
+  try {
+    if (bodyOf(serialise(src, merpeeps)) !== bodyOf(src)) {
+      push('body', 'rewriting the metadata would change the diagram body');
+    }
+  } catch (e) {
+    push('body', `round-trip failed: ${e.message}`);
+  }
+
+  // Writing twice must converge, or files churn on every save.
+  try {
+    const once = serialise(src, merpeeps);
+    if (serialise(once, parse(once)) !== once) {
+      push('idempotent', 'writing the metadata twice does not converge');
+    }
+  } catch (e) {
+    push('idempotent', `idempotence check failed: ${e.message}`);
+  }
+
+  return { ok: issues.length === 0, issues };
+}
+
+// ---------------------------------------------------------------- helpers
+
+function stripComment(body) {
+  // No blank-line collapsing here: rewriting the author's whitespace would be
+  // a body modification, and COMMENT_LINE already removes cleanly.
+  return body.replace(COMMENT_LINE, '');
+}
+
+function withFrontmatter(fm, body) {
+  const keys = Object.keys(fm ?? {});
+  if (keys.length === 0) return body;
+  const text = yaml.dump(fm, { lineWidth: -1, noRefs: true }).replace(/\s*$/, '');
+  return `---\n${text}\n---\n${body}`;
+}
+
+function deepMerge(a, b) {
+  if (a === null || typeof a !== 'object' || Array.isArray(a)) return b;
+  if (b === null || typeof b !== 'object' || Array.isArray(b)) return b;
+  const out = { ...a };
+  for (const [k, v] of Object.entries(b)) {
+    out[k] = k in a ? deepMerge(a[k], v) : v;
+  }
+  return out;
+}
+
+function num(v) {
+  if (typeof v === 'number') return Number.isFinite(v) ? v : null;
+  if (typeof v === 'string' && v.trim() !== '') {
+    const n = Number(v);
+    return Number.isFinite(n) ? n : null;
+  }
+  return null;
+}
+
+function assertString(v, name) {
+  if (typeof v !== 'string') throw new TypeError(`${name} must be a string`);
+}
+
+function assertPlainObject(v, name) {
+  if (!v || typeof v !== 'object' || Array.isArray(v)) {
+    throw new TypeError(`${name} must be an object`);
+  }
+}

package/src/mermaid-plugin.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Minimal shape of the mermaid API this plugin uses. Declared structurally so
+ * the package does not need a dependency on mermaid's own types.
+ */
+export interface MermaidLike {
+  registerLayoutLoaders(loaders: Array<{
+    name: string;
+    loader: () => Promise<unknown>;
+    algorithm?: string;
+  }>): void;
+  render(
+    id: string,
+    text: string,
+    container?: Element,
+  ): Promise<{ svg: string; bindFunctions?: (element: Element) => void }>;
+}
+
+export interface RenderResult {
+  svg: string;
+  bindFunctions?: (element: Element) => void;
+}
+
+/** The name this algorithm registers under (`config.layout`). */
+export declare const LAYOUT_NAME: 'merpeeps';
+
+/** Register the Merpeeps layout algorithm with a mermaid instance. */
+export declare function registerMerpeepsLayout<T extends MermaidLike>(mermaid: T): T;
+
+/**
+ * Render `text`, honouring any positions and styling stored in its Merpeeps block.
+ *
+ * Falls through to `mermaid.render` when the document stores no positions, or
+ * when it uses subgraphs, so the result is never worse than stock mermaid.
+ * Stored styling is applied on either path.
+ */
+export declare function renderWithLayout(
+  mermaid: MermaidLike,
+  id: string,
+  text: string,
+  container?: Element,
+): Promise<RenderResult>;
+
+/** Per-node presentation, as stored under `style.nodes`. */
+export interface NodeStyle {
+  fill?: string;
+  stroke?: string;
+  text?: string;
+  strokeWidth?: number;
+  dashed?: boolean;
+  icon?: string;
+  [key: string]: unknown;
+}
+
+/** Paint one already-rendered node element from a stored style. */
+export declare function applyNodeStyle(nodeEl: Element, style: NodeStyle): void;
+
+/**
+ * Apply stored styling to a rendered SVG string.
+ * Requires a DOM; returns the input unchanged when there is none.
+ */
+export declare function styleSvg(
+  svg: string,
+  styles: Record<string, NodeStyle>,
+): string;

package/src/mermaid-plugin.js

@@ -0,0 +1,321 @@
+// A mermaid layout plugin that draws diagrams at their stored Merpeeps positions.
+//
+// This is the piece that makes stored layout matter outside our own editor.
+// Register it once, and any mermaid-based viewer honours the arrangement a
+// human made, instead of re-deriving one at render time.
+//
+// How it has to work, and why:
+//
+// A registered layout algorithm receives a `LayoutData`, not the source text,
+// and mermaid deliberately drops unknown frontmatter keys before that point —
+// verified, not assumed (see oracle/layout-plugin-probe.mjs: `configHasMerpeeps`
+// and `layoutDataHasMerpeeps` are both false). So the algorithm cannot read the Merpeeps
+// block itself. What it *does* get is `diagramId`, and the caller knows both
+// the id and the text. `renderWithLayout` bridges that gap: it reads the
+// positions, parks them under the id, and hands the id to mermaid.
+//
+// Selecting this algorithm is done in memory, never written to disk, so the
+// file on disk stays an ordinary mermaid document that any stock viewer draws
+// normally.
+
+import * as yaml from 'js-yaml';
+import { getPositions, getStyles, split } from './index.js';
+
+/** The name this algorithm registers under (`config.layout`). */
+export const LAYOUT_NAME = 'merpeeps';
+
+/** Layout and styling parked for an in-flight render, keyed by diagram id. */
+const pending = new Map();
+
+/**
+ * Register the Merpeeps layout algorithm with a mermaid instance.
+ *
+ * ```js
+ * import mermaid from 'mermaid';
+ * import { registerMerpeepsLayout, renderWithLayout } from 'merpeeps-mermaid-layout/mermaid';
+ *
+ * registerMerpeepsLayout(mermaid);
+ * const { svg } = await renderWithLayout(mermaid, 'g1', source);
+ * ```
+ */
+export function registerMerpeepsLayout(mermaid) {
+  mermaid.registerLayoutLoaders([
+    { name: LAYOUT_NAME, loader: async () => ({ render }) },
+  ]);
+  return mermaid;
+}
+
+/**
+ * Render `text`, honouring any positions stored in its Merpeeps block.
+ *
+ * Falls straight through to `mermaid.render` when the document stores no
+ * positions, or when it uses subgraphs — see the note on groups below. In both
+ * cases you get mermaid's normal output, never a broken diagram.
+ */
+export async function renderWithLayout(mermaid, id, text, container) {
+  const positions = getPositions(text);
+  const styles = getStyles(text);
+
+  const hasPositions = Object.keys(positions).length > 0;
+  const hasStyles = Object.keys(styles).length > 0;
+
+  // Nothing stored, or a shape this algorithm does not handle: let mermaid do
+  // what it always does.
+  if (!hasPositions || hasGroups(text)) {
+    // Styling alone is still worth applying, and needs no custom layout.
+    const result = await mermaid.render(id, text, container);
+    return hasStyles ? { ...result, svg: styleSvg(result.svg, styles) } : result;
+  }
+
+  pending.set(id, { positions, styles });
+  try {
+    return await mermaid.render(id, selectLayout(text), container);
+  } finally {
+    pending.delete(id);
+  }
+}
+
+// ------------------------------------------------------------- the algorithm
+
+async function render(data4Layout, svg, helpers) {
+  const {
+    insertCluster, insertEdge, insertEdgeLabel, insertMarkers, insertNode,
+    positionEdgeLabel,
+  } = helpers;
+
+  const { positions: stored = {}, styles = {} } =
+    pending.get(data4Layout.diagramId) ?? {};
+  const nodeDb = {};
+  const clusterDb = {};
+
+  const element = svg.select('g');
+  insertMarkers(element, data4Layout.markers, data4Layout.type, data4Layout.diagramId);
+  const subGraphsEl = element.insert('g').attr('class', 'subgraphs');
+  const edgePaths = element.insert('g').attr('class', 'edgePaths');
+  const edgeLabels = element.insert('g').attr('class', 'edgeLabels');
+  const nodesEl = element.insert('g').attr('class', 'nodes');
+
+  // Insert first, then measure. A node's real size depends on its rendered
+  // label, so a stored width is a hint rather than the truth.
+  //
+  // The node objects are used as-is rather than copied: insertNode attaches an
+  // `intersect` function to the object it is handed, and insertEdge only clips
+  // an edge to the node outline when *both* endpoints expose one. Copying first
+  // loses it, and the arrowhead then lands on the node's centre — hidden
+  // underneath it, since nodes are drawn after edges.
+  await Promise.all(data4Layout.nodes.map(async (node) => {
+    if (node.isGroup) {
+      clusterDb[node.id] = node;
+      nodeDb[node.id] = node;
+      await insertCluster(subGraphsEl, node);
+      return;
+    }
+    nodeDb[node.id] = node;
+    const el = await insertNode(nodesEl, node, {
+      config: data4Layout.config,
+      dir: data4Layout.direction || 'TB',
+    });
+    const box = el.node().getBBox();
+    node.width = box.width;
+    node.height = box.height;
+    node.domId = el;
+
+    // Shapes that do not supply their own still need to clip somehow.
+    if (typeof node.intersect !== 'function') {
+      node.intersect = (point) => intersectRect(node, point);
+    }
+
+    if (styles[node.id]) applyNodeStyle(el.node(), styles[node.id]);
+  }));
+
+  place(data4Layout.nodes, nodeDb, stored);
+
+  // Nodes are drawn centred on the origin, so positioning is a translate.
+  for (const node of Object.values(nodeDb)) {
+    if (!node.domId) continue;
+    node.domId.attr('transform', `translate(${node.x}, ${node.y})`);
+  }
+
+  await Promise.all(data4Layout.edges.map(async (edge) => {
+    await insertEdgeLabel(edgeLabels, edge);
+
+    const startNode = nodeDb[edge.start ?? ''];
+    const endNode = nodeDb[edge.end ?? ''];
+    if (!startNode || !endNode) return;
+
+    // insertEdge discards the first and last point and re-derives them by
+    // intersecting against each node, so a two-point line leaves it nothing to
+    // work from and it throws. A midpoint is the minimum it can use.
+    const from = { x: startNode.x ?? 0, y: startNode.y ?? 0 };
+    const to = { x: endNode.x ?? 0, y: endNode.y ?? 0 };
+    const mid = { x: (from.x + to.x) / 2, y: (from.y + to.y) / 2 };
+
+    const withPath = { ...edge, points: [from, mid, to] };
+    const paths = insertEdge(
+      edgePaths, withPath, clusterDb, data4Layout.type,
+      startNode, endNode, data4Layout.diagramId,
+    );
+    positionEdgeLabel(withPath, paths);
+  }));
+}
+
+/**
+ * Apply stored coordinates, and give anything unpositioned a predictable spot
+ * below the rest rather than stacking it all on the origin.
+ *
+ * Merpeeps stores the top-left corner; mermaid positions by centre.
+ */
+function place(nodes, nodeDb, stored) {
+  let cursorX = 0;
+  let maxY = 0;
+  let anyStored = false;
+
+  for (const raw of nodes) {
+    const node = nodeDb[raw.id];
+    if (!node) continue;
+    const p = stored[raw.id];
+    if (!p) continue;
+
+    node.x = p.x + (node.width ?? 0) / 2;
+    node.y = p.y + (node.height ?? 0) / 2;
+    maxY = Math.max(maxY, p.y + (node.height ?? 0));
+    cursorX = Math.min(cursorX, p.x);
+    anyStored = true;
+  }
+
+  const fallbackY = (anyStored ? maxY : 0) + 60;
+  let fallbackX = anyStored ? cursorX : 0;
+
+  for (const raw of nodes) {
+    const node = nodeDb[raw.id];
+    if (!node || stored[raw.id]) continue;
+
+    node.x = fallbackX + (node.width ?? 0) / 2;
+    node.y = fallbackY + (node.height ?? 0) / 2;
+    fallbackX += (node.width ?? 0) + 40;
+  }
+}
+
+// ------------------------------------------------------------------ helpers
+
+// ------------------------------------------------------------------ styling
+
+/**
+ * Paint one node's outline and label from its stored style.
+ *
+ * Applied to the rendered SVG rather than pushed through mermaid's own
+ * `style`/`classDef` syntax, because writing style into the diagram body would
+ * change the file — and Merpeeps exists precisely so presentation can be stored
+ * *without* touching what the diagram says.
+ *
+ * Written as inline style properties with `important`, since mermaid's
+ * stylesheet targets the same elements by class and would otherwise win.
+ */
+export function applyNodeStyle(nodeEl, style) {
+  if (!nodeEl || !style) return;
+
+  const shapes = nodeEl.querySelectorAll(
+    'rect, circle, ellipse, polygon, path.basic, path.outer-path, path.node-bkg, path');
+
+  for (const shape of shapes) {
+    // Arrow markers and label glyphs live inside the node group too; painting
+    // them would smear the fill across text.
+    if (shape.closest('.label') || shape.closest('foreignObject')) continue;
+
+    if (style.fill) shape.style.setProperty('fill', style.fill, 'important');
+    if (style.stroke) shape.style.setProperty('stroke', style.stroke, 'important');
+    if (style.strokeWidth != null) {
+      shape.style.setProperty('stroke-width', `${style.strokeWidth}px`, 'important');
+    }
+    if (style.dashed) {
+      shape.style.setProperty('stroke-dasharray', '6 4', 'important');
+    }
+  }
+
+  if (style.text) {
+    for (const t of nodeEl.querySelectorAll('text, tspan, .nodeLabel, span, p')) {
+      t.style.setProperty('color', style.text, 'important');
+      t.style.setProperty('fill', style.text, 'important');
+    }
+  }
+}
+
+/**
+ * Apply stored styling to an already-rendered SVG string.
+ *
+ * Used on the fall-through paths, where mermaid did the layout and there is no
+ * plugin hook to paint through. Needs a DOM, so on a server it is a no-op
+ * rather than an error — the diagram is still correct, just unstyled.
+ */
+export function styleSvg(svg, styles) {
+  if (typeof document === 'undefined') return svg;
+
+  const host = document.createElement('div');
+  host.innerHTML = svg;
+
+  for (const [id, style] of Object.entries(styles)) {
+    for (const el of host.querySelectorAll('g.node')) {
+      // Mermaid prefixes and suffixes node ids (`flowchart-gw-3`), so match on
+      // the id as a whole segment rather than by substring.
+      if (!new RegExp(`(^|[-_])${escapeRe(id)}([-_]|$)`).test(el.id)) continue;
+      applyNodeStyle(el, style);
+    }
+  }
+  return host.innerHTML;
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Where the line from `point` to the node's centre crosses the node's box.
+ *
+ * Used only for shapes that do not attach their own `intersect`. This is the
+ * classic dagre-d3 rectangle intersection.
+ */
+function intersectRect(node, point) {
+  const dx = point.x - node.x;
+  const dy = point.y - node.y;
+  let w = (node.width ?? 0) / 2;
+  let h = (node.height ?? 0) / 2;
+
+  let sx;
+  let sy;
+  if (Math.abs(dy) * w > Math.abs(dx) * h) {
+    if (dy < 0) h = -h;
+    sx = dy === 0 ? 0 : (h * dx) / dy;
+    sy = h;
+  } else {
+    if (dx < 0) w = -w;
+    sx = w;
+    sy = dx === 0 ? 0 : (w * dy) / dx;
+  }
+  return { x: node.x + sx, y: node.y + sy };
+}
+
+/**
+ * Add `config.layout: merpeeps` to a copy of the source.
+ *
+ * Deliberately in memory only. Writing it to the file would make the document
+ * depend on this plugin being installed, which is exactly the lock-in Merpeeps
+ * exists to avoid.
+ */
+function selectLayout(text) {
+  const { fm, body } = split(text);
+  const next = {
+    ...fm,
+    config: { ...(fm.config ?? {}), layout: LAYOUT_NAME },
+  };
+  const head = yaml.dump(next, { lineWidth: -1, noRefs: true }).replace(/\s*$/, '');
+  return `---\n${head}\n---\n${body}`;
+}
+
+/**
+ * Subgraphs need cluster bounds derived from their children, which stored
+ * node positions alone do not determine. Rather than draw them wrongly, hand
+ * those diagrams back to mermaid's own layout.
+ */
+function hasGroups(text) {
+  return /^\s*subgraph\s/m.test(split(text).body);
+}