@jarenjs/mermaid 0.34.0

package/README.md

@@ -0,0 +1,282 @@
+# @jarenjs/mermaid
+
+A native, **headless** Mermaid clone: diagrams-as-code parsed to a
+geometry-free JSON AST and rendered as **pure-vnode SVG** through
+[`@jarenjs/view`](../../packages/view) — no `innerHTML`, no browser, no
+runtime dependency on mermaid.js. It is architecturally native to the
+Jaren stack: parse-once/compile-to-closures, structurally shared,
+content-hash-keyed, and **bidirectional** (`parseMermaid` ⇄
+`toMermaid`).
+
+Like [`@jarenjs/md`](../md), it ships in **two layers**: a pure engine
+(text ⇄ AST ⇄ vnode) that knows only the vnode shape, and a visual
+component that packages it for an `@jarenjs/app` host.
+
+## Format in one glance
+
+```js
+import { parseMermaid, toMermaid, renderMermaid } from '@jarenjs/mermaid';
+
+const doc = parseMermaid(`flowchart TD
+  A[Start] --> B{OK?}
+  B -->|yes| C((Done))`);
+
+doc.diagram;        // 'flowchart'
+doc.ast.nodes[1];   // { id: 'B', label: 'OK?', shape: 'diamond' }
+toMermaid(doc);     // canonical text — parseMermaid(toMermaid(doc)) deep-equals doc.ast
+renderMermaid(doc); // ['svg', { viewBox, … }, …]  — a pure-vnode SVG, error-safe
+```
+
+The AST is **geometry-free**: layout is a separate pass, so the AST is a
+faithful semantic model — a directed graph, an ordered interaction, a
+finite state machine — that other engines project. This is the two-layer
+pipeline, drawn in Mermaid (and rendered by this engine on the website):
+
+```mermaid
+flowchart LR
+  S[source text] --> P[parseMermaid]
+  P --> D[DiagramDocument<br/>geometry-free AST]
+  D --> L[layoutDiagram]
+  L --> R[diagramToVnode]
+  R --> V[SVG vnode]
+  D --> T[toMermaid]
+  T --> S
+```
+
+## Usage
+
+**Parse / print / compile (pure):**
+
+```js
+import { parseMermaid, toMermaid, compileMermaid } from '@jarenjs/mermaid';
+
+const c = compileMermaid(source);   // parse once; cached projections
+c.doc;                              // the DiagramDocument
+c.toVnode();                        // pure-vnode SVG (reference-stable)
+c.toSvgString();                    // standalone SVG string — SSR, no browser
+c.toText();                         // canonical Mermaid (toMermaid)
+c.toLayout();                       // the PositionedDiagram — pure geometry
+                                    // (nodes x/y/w/h, routed edges); null for
+                                    // types without a layout. The rendered
+                                    // SVG also marks every node/edge with
+                                    // data-id / data-edge+data-from+data-to,
+                                    // so editors hit-test without re-layout.
+```
+
+**Render pipeline:**
+
+```mermaid
+sequenceDiagram
+  participant H as host
+  participant E as engine
+  participant V as @jarenjs/view
+  H->>E: renderMermaid(source)
+  E->>E: parse → layout → render
+  E-->>H: SVG vnode
+  H->>V: patch(vnode)
+  note over V: O(change) diff, keyed by content hash
+```
+
+**Component (host):**
+
+```js
+import { createMermaidComponent } from '@jarenjs/mermaid/component';
+const mermaid = createMermaidComponent();
+createApp(appDoc, {
+  effects: { ...mermaid.effects },                       // mermaid-render, mermaid-load
+  viewModel: (state) => ({ ...state, diagram: mermaid.view(state.source) }),
+});
+```
+
+**Markdown plugin** — a `mermaid` fence renders inline, SSR-safe:
+
+```js
+import { parseMarkdown, mdToVnode } from '@jarenjs/md';
+import { mermaidPlugin } from '@jarenjs/mermaid/plugin';
+const plugins = [mermaidPlugin()];
+mdToVnode(parseMarkdown(md, { plugins }), { plugins }); // fence → inline <svg>
+```
+
+## The AST node types
+
+```mermaid
+classDiagram
+  class DiagramDocument {
+    +String $mermaid
+    +String diagram
+    +Object config
+    +Object ast
+    +Object meta
+  }
+  class FlowNode {
+    +String id
+    +String label
+    +String shape
+  }
+  class FlowEdge {
+    +String from
+    +String to
+    +String stroke
+  }
+  DiagramDocument <|-- FlowNode
+  DiagramDocument <|-- FlowEdge
+```
+
+## Bidirectional semantic model
+
+The geometry-free AST doubles as a reusable domain model, projected
+both ways by plain JSLT stylesheets — no code, just documents. The
+flagship: a `stateDiagram-v2` projects via
+`stylesheets/state-to-workflow.jslt.json` into an executable machine
+(the `@jarenjs/flow` jaren-fsm superset shape `{ initial, states,
+transitions }`, validated by `schemas/jaren-workflow.schema.json`),
+with a transition label's UML parts parsed for it: `event [guard] /
+effect` become the machine's event, guard and `{ "run": effect }`
+descriptor. The reverse stylesheet plus `toMermaid` turns a machine
+back into editable diagram text — string guards round-trip exactly,
+structured members print as documented `[…]` placeholders.
+
+The same arrow exists for dataflow: `flowchart-to-dag.jslt.json`
+projects a flowchart into a jaren-dag **skeleton** (task stubs named by
+node id, edge labels becoming ports), and `dag-to-flowchart.jslt.json`
+draws a real dag document as a flowchart — one shape per node kind,
+ports and selects on the edge labels. Acyclicity stays `compileDag`'s
+job; the projection just draws.
+
+```mermaid
+flowchart LR
+  M[Mermaid text] --> A[state AST]
+  A -->|state-to-workflow.jslt| W[machine / FSM]
+  W -->|workflow-to-state.jslt| A2[state AST]
+  A2 -->|toMermaid| M
+  F[flowchart AST] -->|flowchart-to-dag.jslt| D[jaren-dag]
+  D -->|dag-to-flowchart.jslt| F
+```
+
+## Diagram coverage
+
+Fully laid out: **flowchart**, **sequence**, **state** (through the
+flowchart engine via an adapter — states as rounded nodes, `[*]` as a
+filled start dot and an end ring, verbatim transition labels on the
+edges; composite states stay flattened in v1). Structured panels /
+chart: **class**, **ER**, **gantt**, **pie**. Parse-accepted with an
+honest "not yet laid out" placeholder: mindmap, gitGraph, journey,
+timeline, quadrantChart, requirement. The benchmark's coverage scorecard reports this
+without hiding gaps.
+
+
+## Styling, notes and interaction
+
+**`classDef` / `class` / `style` now paint.** The parser always recorded them;
+nothing consumed them, so a styled node rendered exactly like an unstyled one.
+They resolve per node in Mermaid's own precedence — classDef in application
+order, then a per-node `style` — and reach the shape as SVG attributes:
+
+```mermaid
+flowchart LR
+  A["input"] --> B["result"]
+  classDef good fill:#dcfce7,stroke:#16a34a
+  class B good
+```
+
+**`note` is a built-in class.** Mermaid has no flowchart note, and a diagram
+that cannot annotate a node loses exactly what an ASCII drawing used to carry
+in a margin comment. Rather than invent syntax, apply the standard `class`
+statement and the node is themed from the same `note*` tokens the sequence
+renderer uses — dashed border, note fill, following light/dark:
+
+```mermaid
+flowchart LR
+  K["@jarenjs/core"] --> E["engine"]
+  N["pure kernel: no I/O, deterministic"]
+  K -.- N
+  class N note
+```
+
+A dotted link to a note-classed node reads as an annotation, and the document
+stays valid Mermaid that any other tool can still parse — no dialect, no
+compatibility cost.
+
+**The label stays readable on whatever fill you pick.** A `fill` you name is a
+constant — it does not follow light/dark — so the ink over it must not follow
+the theme either, or a pale box under a dark theme gets pale text and the
+label vanishes into it. The ink is derived from the fill's measured contrast
+instead, and is guaranteed to clear WCAG AA for any colour. Name a `color`
+yourself and that always wins.
+
+**Pan, zoom and touch are opt-in.** `mermaidPlugin({ interactive: true })`
+adds a `hydrate` that attaches to the finished SVG; the render is unchanged
+and server output is byte-identical either way, so a page that does not ask
+for it never loads the module.
+
+```javascript
+createMdComponent({ plugins: [mermaidPlugin({ theme: 'host', interactive: true })] });
+```
+
+The interaction rules are chosen so a figure never fights the page it sits in:
+
+| gesture | behaviour |
+|---|---|
+| plain wheel | **scrolls the page** — hijacking it is how embedded viewers ruin a document |
+| ctrl/⌘ + wheel | zooms toward the pointer |
+| one-finger drag | pans **only once zoomed in**; at rest the swipe is the page's, and `touch-action` is switched to say so |
+| two fingers | always pinch-zooms |
+| double-click / tap | zooms in, or resets when already zoomed |
+| keyboard | `+` `-` `0` and arrows, on a focusable figure with an aria-label |
+
+Everything runs on the SVG's `viewBox` — four numbers changing. Nothing
+re-renders, nothing re-parses, and the view is clamped so it can never be
+panned off its own canvas.
+
+Pie rendering delegates to [`@jarenjs/charts`](../charts) (the pie
+engine's single home) — the emitted SVG is unchanged; mermaid passes
+its class names, palette and theme through the render options.
+
+## Performance (measured)
+
+Node v22.22.2, 2026-07-19, `npm run benchmark:mermaid` (run it
+yourself). Mermaid has **two** parsers, so there are two honest
+head-to-heads:
+
+- **`@mermaid-js/parser`** is the standalone **Langium** parser — it
+  covers only the grammars migrated off Jison (pie, gitGraph, …) and
+  **cannot parse flowchart or sequence**. The overlapping type is
+  **pie**, where `@jarenjs/mermaid` is comparable (~0.003–0.006 ms/op
+  either way).
+- **Flowchart and sequence** are still parsed by Mermaid's original
+  in-tree **Jison** grammars inside the full `mermaid` package (not by
+  `@mermaid-js/parser`). Against `mermaid.parse()` (DOM-coupled, run
+  under jsdom), `@jarenjs/mermaid` parses the same sources **roughly two
+  orders of magnitude faster**:
+
+| flowchart/sequence parse (ms/op) | jaren-mermaid | mermaid.parse (Jison) |
+|---|---|---|
+| flowchart ~5 nodes | ~0.04 | ~10 |
+| sequence ~5 nodes | ~0.02 | ~1.4 |
+| flowchart ~25 nodes | ~0.09 | ~7 |
+| sequence ~25 nodes | ~0.05 | ~4 |
+
+(`mermaid.parse` is async and runs the whole parse front-end — type
+detection + Jison + validation — so it is heavy and noisy; these are
+representative, not a bare-grammar microbenchmark.)
+
+The headless **parse → layout → SVG string** rows are jaren-only
+(<!--bm:mermaid.svgMs-->~0.46 ms for a 25-node flowchart, ~1.4 ms at 100 nodes<!--/bm-->): mermaid.js
+needs a browser DOM (`getBBox`) to render, so there is no fair
+full-render head-to-head — producing a complete standalone SVG in pure
+Node is a capability it lacks.
+
+## Design notes
+
+- **Two layers, one-way arrow.** The engine imports only `@jarenjs/core`
+  and `@jarenjs/view` (shared SVG builders from `@jarenjs/view/helpers`,
+  `hashContent` from core); the component adds the app glue. The Markdown
+  plugin lives on the md→mermaid arrow with no cycle.
+- **CSP-safe.** No `eval`, no `new Function`, no `innerHTML`. Text and
+  attributes are escaped by the view serializer.
+- **Structural sharing.** Same source → reference-equal vnode; a small
+  source change re-emits only affected sub-scenes; block vnodes carry
+  content-hash keys.
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) and
+[docs/MERMAID-FORMAT.md](docs/MERMAID-FORMAT.md).

package/dist/types/ast.d.ts

@@ -0,0 +1,210 @@
+/**
+ * @file The Mermaid AST vocabulary: node constructors and walkers.
+ *
+ * Every node is a plain JSON object born from a constructor so that all
+ * nodes of a type share one hidden class — property access stays
+ * monomorphic and the structural hash is deterministic (MERMAID-FORMAT
+ * §4). The AST is deliberately **geometry-free**:
+ * layout is a separate pass, so the AST is a faithful, lossless
+ * semantic model of the diagram's *meaning* — a directed graph
+ * (flowchart), an ordered interaction (sequence), a finite state machine
+ * (state) — that other engines project via JSLT without ever seeing a
+ * coordinate.
+ *
+ * Member order is fixed per constructor; keep it stable so the FNV-1a
+ * hash of `JSON.stringify` is reproducible and the round-trip printer
+ * (`to-mermaid.js`) is a fixed point.
+ */
+/** The diagram-document format version this package produces. */
+export declare const MERMAID_VERSION = "0.1";
+export type DiagramDocument = {
+    /**
+     * format version
+     */
+    $mermaid: string;
+    /**
+     * diagram type (`flowchart`, `sequence`, …)
+     */
+    diagram: string;
+    /**
+     * plain-JSON config (theme, per-type options)
+     */
+    config: any;
+    /**
+     * the type-specific, geometry-free AST
+     */
+    ast: any;
+    meta: {
+        hash: string;
+        direction: string | null;
+        title: string | null;
+    };
+};
+/**
+ * @typedef {object} DiagramDocument
+ * @property {string} $mermaid format version
+ * @property {string} diagram diagram type (`flowchart`, `sequence`, …)
+ * @property {any} config plain-JSON config (theme, per-type options)
+ * @property {any} ast the type-specific, geometry-free AST
+ * @property {{ hash: string, direction: string|null, title: string|null }} meta
+ */
+/**
+ * Assemble the shared DiagramDocument envelope. Fresh per parse,
+ * never mutated after return — share-friendly for JSLT/patch.
+ * @param {string} diagram
+ * @param {any} config
+ * @param {any} ast
+ * @param {{ hash: string, direction: string|null, title: string|null }} meta
+ * @returns {DiagramDocument}
+ */
+export declare function diagramDocument(diagram: string, config: any, ast: any, meta: {
+    hash: string;
+    direction: string | null;
+    title: string | null;
+}): DiagramDocument;
+export type FlowShape = 'rect' | 'round' | 'stadium' | 'subroutine' | 'cylinder' | 'circle' | 'doublecircle' | 'diamond' | 'hexagon' | 'parallelogram' | 'parallelogram_alt' | 'trapezoid' | 'trapezoid_alt' | 'asymmetric';
+/**
+ * @typedef {'rect'|'round'|'stadium'|'subroutine'|'cylinder'|'circle'
+ *   |'doublecircle'|'diamond'|'hexagon'|'parallelogram'|'parallelogram_alt'
+ *   |'trapezoid'|'trapezoid_alt'|'asymmetric'} FlowShape
+ */
+/**
+ * A flowchart vertex.
+ * @param {string} id
+ * @param {string} label
+ * @param {FlowShape} shape
+ * @returns {{ id: string, label: string, shape: FlowShape }}
+ */
+export declare function flowNode(id: string, label: string, shape: FlowShape): {
+    id: string;
+    label: string;
+    shape: FlowShape;
+};
+/**
+ * A flowchart edge (link). `stroke` is the line style, `head`/`tail`
+ * the endpoint markers, `length` the dash count (preserved so the
+ * canonical printer is a fixed point), `label` the optional edge text.
+ * @param {string} from
+ * @param {string} to
+ * @param {'solid'|'thick'|'dotted'} stroke
+ * @param {'none'|'arrow'|'circle'|'cross'} head
+ * @param {'none'|'arrow'|'circle'|'cross'} tail
+ * @param {number} length
+ * @param {string|null} label
+ * @returns {object}
+ */
+export declare function flowEdge(from: string, to: string, stroke: 'solid' | 'thick' | 'dotted', head: 'none' | 'arrow' | 'circle' | 'cross', tail: 'none' | 'arrow' | 'circle' | 'cross', length: number, label: string | null): object;
+/**
+ * A subgraph grouping.
+ * @param {string} id
+ * @param {string} label
+ * @param {string|null} direction
+ * @param {string[]} nodes ids of member nodes
+ * @returns {object}
+ */
+export declare function flowSubgraph(id: string, label: string, direction: string | null, nodes: string[]): object;
+/**
+ * A `classDef` style class.
+ * @param {string} name
+ * @param {string} styles semicolon-separated CSS declarations
+ * @returns {object}
+ */
+export declare function flowClassDef(name: string, styles: string): object;
+/**
+ * A `class`/`:::` assignment of a style class to a node.
+ * @param {string} node
+ * @param {string} name
+ * @returns {object}
+ */
+export declare function flowClass(node: string, name: string): object;
+/**
+ * A `style` inline-style assignment to a node.
+ * @param {string} node
+ * @param {string} styles
+ * @returns {object}
+ */
+export declare function flowStyle(node: string, styles: string): object;
+/**
+ * The flowchart AST root.
+ * @param {string} direction
+ * @param {object[]} nodes
+ * @param {object[]} edges
+ * @param {object[]} subgraphs
+ * @param {object[]} classDefs
+ * @param {object[]} classes
+ * @param {object[]} styles
+ * @returns {object}
+ */
+export declare function flowchartAst(direction: string, nodes: object[], edges: object[], subgraphs: object[], classDefs: object[], classes: object[], styles: object[]): object;
+/**
+ * A declared participant/actor.
+ * @param {string} id
+ * @param {string} label
+ * @param {'participant'|'actor'} kind
+ * @returns {object}
+ */
+export declare function seqParticipant(id: string, label: string, kind: 'participant' | 'actor'): object;
+/**
+ * A message statement.
+ * @param {string} from
+ * @param {string} to
+ * @param {string} text
+ * @param {'solid'|'dotted'} line
+ * @param {'arrow'|'open'|'cross'|'point'} head
+ * @param {'activate'|'deactivate'|null} activation `+`/`-` shorthand
+ * @returns {object}
+ */
+export declare function seqMessage(from: string, to: string, text: string, line: 'solid' | 'dotted', head: 'arrow' | 'open' | 'cross' | 'point', activation: 'activate' | 'deactivate' | null): object;
+/**
+ * A note statement.
+ * @param {'left of'|'right of'|'over'} placement
+ * @param {string[]} actors
+ * @param {string} text
+ * @returns {object}
+ */
+export declare function seqNote(placement: 'left of' | 'right of' | 'over', actors: string[], text: string): object;
+/**
+ * An explicit activate/deactivate statement.
+ * @param {'activate'|'deactivate'} kind
+ * @param {string} actor
+ * @returns {object}
+ */
+export declare function seqActivation(kind: 'activate' | 'deactivate', actor: string): object;
+/**
+ * A block statement (loop/opt/alt/par/critical/break). Single-branch
+ * blocks (loop/opt/critical/break) carry one branch; alt/par carry one
+ * per `else`/`and` section. `branches` is always present so the shape
+ * is monomorphic.
+ * @param {'loop'|'opt'|'alt'|'par'|'critical'|'break'} blockType
+ * @param {{ label: string, statements: object[] }[]} branches
+ * @returns {object}
+ */
+export declare function seqBlock(blockType: 'loop' | 'opt' | 'alt' | 'par' | 'critical' | 'break', branches: {
+    label: string;
+    statements: object[];
+}[]): object;
+/**
+ * The sequence AST root.
+ * @param {object[]} participants explicitly declared participants
+ * @param {object[]} statements ordered interaction statements
+ * @param {boolean} autonumber
+ * @returns {object}
+ */
+export declare function sequenceAst(participants: object[], statements: object[], autonumber: boolean): object;
+/**
+ * A geometry-free "lines" AST for diagram types that parse-accept but
+ * are not yet laid out (the secondary types). Preserves the raw body
+ * lines so `toMermaid` round-trips and the coverage scorecard can be
+ * honest.
+ * @param {string} diagram
+ * @param {string[]} lines
+ * @returns {object}
+ */
+export declare function rawAst(diagram: string, lines: string[]): object;
+/**
+ * Walk the ordered statements of a sequence AST (descending into block
+ * branches), calling `visitor(stmt)` pre-order.
+ * @param {object[]} statements
+ * @param {(stmt: any) => void} visitor
+ */
+export declare function walkSequence(statements: object[], visitor: (stmt: any) => void): void;

package/dist/types/component/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @file The Mermaid VISUAL COMPONENT — part two of the package.
+ *
+ * Everything below this line is presentation glue; the engine
+ * (`@jarenjs/mermaid`) neither knows nor needs any of it. Mirrors
+ * `@jarenjs/md`'s `createMdComponent` field-for-field:
+ *
+ *  - `createMermaidComponent()` — a memoized `view()` projection for
+ *    `@jarenjs/app` viewModels (reference-stable, so an unchanged source
+ *    patches in O(1) — the O(change) contract), `effects` entries for
+ *    the app effect registry (`mermaid-render`, `mermaid-load`), and a
+ *    `hydrate()` pass kept for API symmetry (a no-op in v1: the render is
+ *    already complete);
+ *  - `styles/mermaid.css` — the component stylesheet.
+ *
+ * The boundary is one-way: the component imports the engine, never the
+ * reverse.
+ */
+export type MermaidComponentOptions = {
+    /**
+     * theme name or override object
+     */
+    theme?: any;
+    /**
+     * LRU size for the source-string memo (default 32)
+     */
+    memoLimit?: number;
+    /**
+     * base URL for `mermaid-load`
+     */
+    base?: string | URL;
+    /**
+     * fetch implementation for `mermaid-load`
+     */
+    fetch?: typeof globalThis.fetch;
+    onHydrateError?: (err: any) => void;
+};
+export type MermaidComponent = {
+    /**
+     * memoized compile
+     */
+    compile: (source: string) => any;
+    /**
+     * memoized vnode projection
+     */
+    view: (sourceOrDoc: any) => any;
+    effects: Record<string, (props: any, dispatch: any) => any>;
+    /**
+     * no-op in v1
+     */
+    hydrate: (container: any) => void;
+};
+/**
+ * @typedef {object} MermaidComponentOptions
+ * @property {any} [theme] theme name or override object
+ * @property {number} [memoLimit] LRU size for the source-string memo (default 32)
+ * @property {string | URL} [base] base URL for `mermaid-load`
+ * @property {typeof globalThis.fetch} [fetch] fetch implementation for `mermaid-load`
+ * @property {(err: any) => void} [onHydrateError]
+ */
+/**
+ * @typedef {object} MermaidComponent
+ * @property {(source: string) => any} compile memoized compile
+ * @property {(sourceOrDoc: any) => any} view memoized vnode projection
+ * @property {Record<string, (props: any, dispatch: any) => any>} effects
+ * @property {(container: any) => void} hydrate no-op in v1
+ */
+/**
+ * Create the Mermaid component.
+ *
+ * @example
+ * const mermaid = createMermaidComponent();
+ * createApp(appDoc, {
+ *   effects: { ...mermaid.effects },
+ *   viewModel: (state) => ({ ...state, diagram: mermaid.view(state.source) }),
+ * });
+ *
+ * @param {MermaidComponentOptions} [options]
+ * @returns {MermaidComponent}
+ */
+export declare function createMermaidComponent(options?: MermaidComponentOptions): MermaidComponent;

package/dist/types/errors.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @file The engine's one error type. Parsers raise it with a 1-based
+ * `line`/`column`; the render path (`diagramToVnode`/`renderMermaid`)
+ * catches it and emits a clear error vnode instead of throwing, so
+ * rendering is always total.
+ */
+export declare class MermaidParseError extends Error {
+    /** @type {number} */
+    line: number;
+    /** @type {number} */
+    column: number;
+    /**
+     * @param {string} message
+     * @param {number} [line] 1-based line number
+     * @param {number} [column] 1-based column number
+     */
+    constructor(message: string, line?: number, column?: number);
+}
+/**
+ * The `fail(message, position)` idiom from `packages/json/src/path.js`,
+ * adapted to line/column. Throws; never returns.
+ * @param {string} message
+ * @param {number} line
+ * @param {number} [column]
+ * @returns {never}
+ */
+export declare function fail(message: string, line: number, column?: number): never;