agentic-mermaid 0.1.1 → 0.2.0

package/docs/quality.md

@@ -25,18 +25,18 @@ A diagram is considered **good looking** when it satisfies, in order:
    | `labelLegibility` | fraction of node labels whose rendered length fits the node width | ≥ 85% |
    | `whitespaceBalance` | node area ÷ canvas area | 5%–55% (too sparse AND too dense lose) |
    | `labelEdgeProximity` | min pixel distance between any edge-label box and a non-attached node, another edge-label box, or another edge path (graph families; cross-family label/box occlusion is gated by `eval/overlap-audit` + `label-overlap-gate.test.ts`) | ≥ 4 px |
+   | `minimumNodeSpacing` | nearest gap between semantically distinct node/mark boxes; XY and Radar same-coordinate series adjacency/overlays are excluded | ≥ 8 px |
+   | `elementDensity` | nodes + edges per 10,000 canvas pixels | 0.02–6 |
+   | `minimumTextContrast` | WCAG contrast ratio between foreground and supplied background/surface colors; `null` when a requested paint cannot be resolved | ≥ 4.5:1 |
    | `aspectRatio` | canvas w/h | 0.2–5.0 |
 
    These are computed by `measureQuality(layout)` and gated by
    `checkQuality(layout)`. They are **deterministic** and cheap — they
    run on every PR.
 
-4. **LLM-as-judge median ≥ 4.0** on a stratified sample of the
-   mermaid-docs corpus (5 diagrams × 12 families = 60 samples) across
-   three axes. Since QUAL-1 the perceptual metrics cover every renderable
-   family (flowchart, state, sequence, timeline, class, ER, journey,
-   architecture, xychart, pie, quadrant, gantt), so judge sampling should now
-   include all twelve — not just the graph families — across:
+4. **LLM-as-judge median ≥ 4.0** on the configured stratified sample of the
+   Mermaid-docs corpus across three axes. Since QUAL-1, perceptual metrics and
+   judge sampling cover every registered renderer rather than only graph families:
    - **Readability** — labels legible, arrows clear, no overlap chaos
    - **Faithfulness** — every node and edge from the source is present
    - **Aesthetics** — balanced layout, professional feel
@@ -130,15 +130,24 @@ geometry assertions, screenshot/PNG review, or human inspection.
   | pie           | slice label boxes (legend anchor + approx bbox) | — | —                    |
   | quadrant      | plotted points                     | —            | quadrant regions     |
   | gantt         | task bars + milestone diamonds     | —            | section bands        |
+  | mindmap       | hierarchy nodes                    | parent links | —                    |
+  | gitgraph      | commits                            | parent links | —                    |
+  | radar         | curve vertices (one ring per axis) | —            | axis spokes/grid     |
 
-  Families with no structural relations (pie/quadrant/xychart/journey/gantt) carry an
+  Families with no structural relations (pie/quadrant/xychart/journey/gantt/radar) carry an
   honestly-empty `edges` array. Bounds is the family layout's canvas size.
 - **No font-substitution check.** Different OSes render different
   default fonts. Our `labelLegibility` heuristic uses a 7 px-per-char
   approximation; under condensed fonts it under-estimates fit.
-- **No quality-metric color-contrast score.** Runtime auto-contrast exists
-  for custom fills, but `measureQuality` does not include a separate WCAG
-  contrast metric. Promote to `TODO.md` only if it becomes release-gating.
+- **Contrast needs resolved paints.** `measureQuality(layout)` scores the crisp
+  default palette. For a custom style, pass `{ foreground, background,
+  surfaces }` as its second argument, or pass the actual rendered text/surface
+  associations as `textPairs`. Concrete named, hex, `rgb()`/`rgba()`, and
+  `hsl()`/`hsla()` paints—including alpha and `transparent`—are composited over
+  the supplied background. Any unresolved requested paint makes contrast
+  unmeasurable (`null`), and `checkQuality` reports a violation instead of
+  guessing or passing open. The generated visual-quality characterization reads
+  text and containing-surface paints from the rendered SVG.
 
 ## ASCII determinism
 
@@ -189,10 +198,10 @@ critic pass:
   declares family preference for browser consumers.
 
 What's tested:
-- `agent-png.test.ts` (6 tests) — PNG magic bytes, scale proportionality,
-  ValidDiagram input, background variation.
-- `agent-png-determinism.test.ts` (3 tests) — 5x same-input SHA-256
-  stability with a warm-up render to factor out napi init differences.
+- `agent-png.test.ts` — PNG magic bytes, scale proportionality,
+  ValidDiagram input, and background variation.
+- `agent-png-determinism.test.ts` — repeated same-input SHA-256 stability
+  with a warm-up render to factor out napi initialization differences.
   Plus length-stable defence against partial-buffer truncation
   masquerading as a hash collision.
 - `agent-determinism.test.ts` "cross-runtime PNG" — renders in bun,

package/docs/react.md

@@ -72,11 +72,11 @@ For client-only exports, use the live editor/browser's existing download path or
 For untrusted source, parse or verify before rendering:
 
 ```tsx
-import { parseMermaid, verifyMermaid, renderMermaidSVG } from 'agentic-mermaid/agent'
+import { parseRegisteredMermaid, verifyMermaid, renderMermaidSVG } from 'agentic-mermaid/agent'
 
 export function SafeDiagram({ source }: { source: string }) {
   const result = useMemo(() => {
-    const parsed = parseMermaid(source)
+    const parsed = parseRegisteredMermaid(source)
     if (!parsed.ok) return { ok: false, message: parsed.error.map(e => e.message).join('\n') }
 
     const verify = verifyMermaid(parsed.value)