agentic-mermaid 0.4.1 → 0.5.3

package/docs/mcp-http-transport.md

@@ -2,9 +2,9 @@
 
 `agentic-mermaid-mcp` defaults to stdio for local MCP clients. Use HTTP/SSE only when a client needs a reachable endpoint or when PNG artifacts should be fetched by file/URL instead of returned as large base64 strings.
 
-> Looking for a zero-setup endpoint? A **hosted** MCP already runs at `https://agentic-mermaid.dev/mcp` (`claude mcp add --transport http agentic-mermaid https://agentic-mermaid.dev/mcp`). It is a different implementation — stateless Streamable HTTP, Cloudflare-backed, tools `execute`/`describe_sdk`/`render_svg`/`render_ascii`/`render_png`/`verify`/`describe`/`mutate`/`build`, inputs capped at 64KB, and no file/URL PNG artifacts (base64 only). See the [as-built record](./project/archive/hosted-mcp-cloudflare-plan.md). Run the local server below when you need file/URL artifacts, larger inputs, offline use, or your own auth.
+> Looking for a zero-setup endpoint? A **hosted** MCP already runs at `https://agentic-mermaid.dev/mcp` (`claude mcp add --transport http agentic-mermaid https://agentic-mermaid.dev/mcp`). It is a different implementation — stateless Streamable HTTP, Cloudflare-backed, inputs capped at 64KB, and no file/URL PNG artifacts (base64 only) — with the tools <!-- BEGIN GENERATED: hosted-mcp-tools -->`execute`, `describe_sdk`, `render_svg`, `render_ascii`, `render_png`, `verify`, `describe`, `mutate`, and `build`<!-- END GENERATED: hosted-mcp-tools -->. See the [as-built record](./project/archive/hosted-mcp-cloudflare-plan.md). Run the local server below when you need file/URL artifacts, larger inputs, offline use, or your own auth.
 >
-> **Protocol versions.** The hosted endpoint is dual-era: it serves the handshake-based revisions `2024-11-05`, `2025-03-26`, `2025-06-18`, and `2025-11-25`, and the stateless `2026-07-28` revision that replaces the `initialize` handshake with per-request `_meta` and a mandatory `server/discover`. Clients need do nothing special — send whatever revision you speak in `MCP-Protocol-Version`, and an unsupported one comes back as `-32022` listing the versions we accept. One precision worth stating: `2024-11-05` here is protocol-*version* support only. A client using the 2024-11-05-era HTTP+SSE *transport* (opening with `GET` and expecting an `endpoint` event) receives 405 and cannot connect; that entry exists for Streamable HTTP clients that negotiate the older protocol version. The local server below still pins `2024-11-05`, matching its own SSE transport.
+> **Protocol versions.** The hosted endpoint is dual-era: it accepts <!-- BEGIN GENERATED: hosted-protocol-versions -->`2025-03-26`, `2025-06-18`, `2025-11-25`, and `2026-07-28`<!-- END GENERATED: hosted-protocol-versions -->. Every revision before `2026-07-28` is handshake-based; `2026-07-28` is the stateless revision that replaces the `initialize` handshake with per-request `_meta` and a mandatory `server/discover`. Clients need do nothing special — send whatever revision you speak in `MCP-Protocol-Version`, and an unsupported one comes back as `-32022` listing the versions we accept. The hosted endpoint does not accept `2024-11-05`: that revision is the HTTP+SSE *transport* (opening with `GET` and expecting an `endpoint` event), and a client using it receives 405. The local server below accepts <!-- BEGIN GENERATED: stdio-protocol-versions -->`2024-11-05`, `2025-06-18`, `2025-11-25`, and `2026-07-28`<!-- END GENERATED: stdio-protocol-versions --> over stdio and <!-- BEGIN GENERATED: http-sse-protocol-versions -->`2024-11-05`<!-- END GENERATED: http-sse-protocol-versions --> over its HTTP+SSE transport.
 >
 > **Privacy and caching:** every hosted call (`execute`, `render_*`, `verify`, `describe`, `mutate`, `build`) sends your diagram source or code to the agentic-mermaid.dev server. Successful deterministic pure-tool results may be reused by a private server-side Workers Cache for up to 24 hours; `execute`, `mutate`, and `build` bypass it. The JSON-RPC HTTP response itself is always `cache-control: no-store`; `x-agentic-mermaid-compute-cache` reports `hit`, `miss`, `mixed`, `bypass`, or `disabled`. For diagrams that must not leave your machine, use the library, the CLI, or the local stdio/HTTP server on this page — the pipeline is fully local and needs no network.
 
@@ -24,14 +24,14 @@ The local `/sse` + `/message` pair is the MCP SSE session transport: `POST /mess
 Loopback/local development:
 
 ```sh
-npx -y agentic-mermaid-mcp --transport http --host 127.0.0.1 --port 3000 \
+npx -y agentic-mermaid mcp --transport http --host 127.0.0.1 --port 3000 \
   --artifact-dir .agentic-mermaid-artifacts
 ```
 
 Remote binding requires a bearer token:
 
 ```sh
-npx -y agentic-mermaid-mcp --transport http --host 0.0.0.0 --port 3000 \
+npx -y agentic-mermaid mcp --transport http --host 0.0.0.0 --port 3000 \
   --artifact-dir .agentic-mermaid-artifacts \
   --auth-token "$AGENTIC_MERMAID_MCP_TOKEN"
 ```
@@ -88,7 +88,7 @@ Response shape:
     "content": [
       {
         "type": "text",
-        "text": "{\"ok\":true,\"png_base64\":\"iVBORw0KGgo...\",\"warnings\":[]}"
+        "text": "{\"ok\":true,\"png_base64\":\"iVBORw0KGgo…\",\"receipt\":{\"version\":2,\"output\":\"png\",…},\"runtime\":{\"engine\":\"resvg\",\"binding\":\"napi\",…},\"warnings\":[]}"
       }
     ],
     "isError": false
@@ -96,7 +96,7 @@ Response shape:
 }
 ```
 
-`warnings` always appears. `PNG_FONT_COVERAGE` names missing CJK/emoji coverage and points to `fontDirs`/`loadSystemFonts`; source configuration diagnostics use the same deterministic warning envelope.
+`receipt` is the render request receipt (request/appearance digests plus the capability and execution decisions) and `runtime` records rasterizer provenance (engine, binding, font sources, reproducibility); both are also present on file and URL responses. `warnings` always appears. `PNG_FONT_COVERAGE` names missing CJK/emoji coverage and points to `fontDirs`/`loadSystemFonts`; source configuration diagnostics use the same deterministic warning envelope.
 
 ### File output
 
@@ -127,7 +127,10 @@ Response shape (`content[0].text` is JSON):
     "mimeType": "image/png",
     "bytes": 12345,
     "sha256": "64 lowercase hex characters"
-  }
+  },
+  "receipt": { "version": 2, "output": "png", … },
+  "runtime": { "engine": "resvg", "binding": "napi", … },
+  "warnings": []
 }
 ```
 
@@ -162,7 +165,10 @@ Response shape (`content[0].text` is JSON):
     "mimeType": "image/png",
     "bytes": 12345,
     "sha256": "64 lowercase hex characters"
-  }
+  },
+  "receipt": { "version": 2, "output": "png", … },
+  "runtime": { "engine": "resvg", "binding": "napi", … },
+  "warnings": []
 }
 ```
 

package/docs/quality.md

@@ -2,37 +2,42 @@
 
 A diagram is considered **good looking** when it satisfies, in order:
 
-1. **All Tier 1 structural checks pass.** No `EMPTY_DIAGRAM`, no
-   `EDGE_MISANCHORED`, no `OFF_CANVAS`, no `GROUP_BREACH`, no
-   `UNKNOWN_SHAPE`, no `LABEL_OVERFLOW` (default cap: 40 chars).
-   This is non-negotiable — fix the source before judging visuals.
+1. **All Tier 1 structural checks pass.** None of
+   <!-- BEGIN GENERATED: warning-codes:structural -->`EMPTY_DIAGRAM`, `EDGE_MISANCHORED`, `OFF_CANVAS`, `GROUP_BREACH`, `UNKNOWN_SHAPE`, `LABEL_OVERFLOW`, `UNRESOLVABLE_SCHEDULE`, `RENDER_FAILED`, `INTERNAL_ERROR`<!-- END GENERATED: warning-codes:structural -->
+   fires (`LABEL_OVERFLOW` default cap: 40 chars).
+   Resolve the reported structural or rendering failure before judging aesthetics.
 
 2. **Tier 2 geometric checks are within bounds.** `NODE_OVERLAP` count
    and `ROUTE_SELF_CROSS` count are advisory but not catastrophic. A
    diagram with a single intentional overlap (e.g., a self-loop) is
    still considered good. The `ROUTE_*` codes (`ROUTE_HITCH`,
    `ROUTE_UNEXPLAINED_BEND`, `ROUTE_LABEL_ON_SHARED_TRUNK`,
-   `ROUTE_CONTAINER_MISANCHOR`, `ROUTE_SHAPE_MISANCHOR`,
+   `ROUTE_SELF_LOOP_OCCUPANCY`, `ROUTE_CONTAINER_MISANCHOR`, `ROUTE_SHAPE_MISANCHOR`,
    `ROUTE_STALE_AFTER_NODE_MOVE`) should always be zero — they are
    route-contract tripwires (see `docs/design/system/route-contracts.md`), and
    any hit means the layout pipeline regressed, not the diagram.
+   <!-- complete: warning-codes:geometric -->
 
 3. **Perceptual metrics fall in the default `QualityBounds` band:**
 
    | metric | meaning | default |
    |---|---|---|
-   | `edgeCrossings` | pairs of edge segments that visually intersect | ≤ 5% of edge pairs |
-   | `labelLegibility` | fraction of node labels whose rendered length fits the node width | ≥ 85% |
+   | `edgeCrossings` | visible proper crossing incidences per logical edge pair and location | ≤ 5% of visible edge pairs |
+   | `labelLegibility` | fraction of measured visible labels whose retained text bounds fit their actual containing region | ≥ 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 |
+   | `labelConflicts` | counts of padded graph label pills intersecting another label, a node, or another visible route; reported for Flowchart and State | minimize after crossings in candidate selection; no default quality bound |
+   | `routeOverlaps` | Flowchart/State edge pairs sharing opposing-direction ink or same-endpoint parallel ink (parallel excludes self-loops) | reported separately from crossings; no default quality bound |
+   | `minimumNodeSpacing` | nearest gap between semantically distinct node/mark boxes; authored coincident Quadrant points and XY/Radar data 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.
+   These are computed by `measureQuality(layout)`; `checkQuality(layout)` applies
+   the configured bounds. `labelConflicts` is reported without a quality-bound
+   threshold, as is `routeOverlaps`. A low crossing count cannot establish
+   readability when routes instead share ambiguous collinear ink. These
+   measurements are **deterministic** and run on every PR.
 
 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
@@ -45,6 +50,123 @@ A diagram is considered **good looking** when it satisfies, in order:
    supports pre-release sign-off when explicitly run. See
    `eval/llm-judge/judge.ts`.
 
+## Layout priorities and their limits
+
+Authored meaning and deterministic execution constrain every aesthetic choice:
+identities, endpoint markers, membership, labels and operation order must survive.
+An authored data coordinate is meaning, so separating coincident chart points to
+improve a spacing score is wrong. Resource admission also happens before layout;
+a work-limit refusal is not a poor aesthetic score.
+
+For automatic graph layout, apply the following order:
+
+1. **Feasibility and readable ownership:** finite in-bounds geometry, containment,
+   non-overlapping graph nodes, endpoints on the rendered outline, routes that
+   avoid unrelated nodes, and labels associated with their own route. Among
+   feasible candidates, prefer readable group titles.
+2. **Crossings, then soft label conflicts:** reduce crossings within the feasible
+   set. When crossing counts tie, prefer fewer padded label-conflict pairs.
+   These counts keep distinguishing layouts after minimum clearance reaches zero,
+   but reducing a soft overlap count cannot buy additional crossings. Hard
+   node-avoidance and own-label-association requirements still apply first.
+3. **Continuity and unnecessary bends:** prefer clear direct lanes; distinguish
+   unexplained detours from declared symmetric convergence.
+4. **Canonical ports:** prefer side midpoints or declared slots. An endpoint on
+   the correct outline is mandatory; the preferred point on that outline is a
+   softer choice and can yield to a simpler safe route.
+5. **Symmetry and alignment:** improve balance without silently trading away
+   higher-priority constraints. Bundle-owned convergence is an explicit route
+   policy, with justified bends excluded from the avoidable-bend metric.
+6. **Compactness, fill and aspect ratio:** use these as family-aware heuristics.
+   A data plot with sparse authored coordinates must not fail a graph box-fill
+   default; explicit caller bounds still apply.
+
+This is a policy order, not a claim that the current heuristic pipeline solves a
+global lexicographic optimum. Several older contracts pull in different
+directions:
+
+- Verification treats some overlap warnings as advisory, while the graph rubric
+  treats node overlap as hard. Graph final certification uses the stricter graph
+  contract; specialized plots need semantic overlap rules rather than a blanket
+  node-box rule.
+- Cosmetic straightening and tightening must preserve crossings. Repairs of hard
+  node avoidance or own-label association may need a crossing; their conditional
+  pass budgets require a measured higher-priority repair. A padded label-conflict
+  count is a separate soft preference, not an additional hard feasibility gate.
+- Symmetric fan-in can add geometric bends. The route classifier explains those
+  bends as convergence. This is a declared exception, not evidence that raw bend
+  count always decreases.
+- Equalizing node dimensions can temporarily move centers before alignment
+  passes. Its old per-pass promise to improve symmetry was false and has been
+  removed. Preparation and final aesthetic claims are different obligations.
+- A character-count `LABEL_OVERFLOW` guard does not measure rendered fit. Retained
+  prepared text and final containing bounds supply that evidence; missing
+  measurements produce an explicit quality warning.
+
+The pass runner enforces declared before/after metric budgets in production,
+including conditional allowances. Ordering, budgets and post-freeze contracts
+always apply; there is no audit flag that disables them. A duplicate-lane proposal may introduce at
+most one crossing per actual shared duplicate route pair it separates; unrelated
+bucket improvements cannot pay for that proposal. Preferred endpoint spacing or
+fewer bends alone cannot buy a crossing. Canonical ports may yield when the
+certifying route owner measurably repairs hard geometry, reduces crossings or
+removes bends.
+The graph engine independently certifies the
+final candidate before returning it, with at most four deterministic placement candidates
+and an explicit `LAYOUT_CERTIFICATION_FAILED` error on exhaustion. This certifies
+hard graph geometry, not minimum crossings or universal aesthetic quality.
+Within 64 nodes/groups and 128 edges, a certified graph with crossings or label
+conflicts may try one additional distinct strategy. Feasible candidates compare
+readable group titles, crossings, label-conflict pairs, avoidable bends,
+canonical endpoints, symmetry and area in that order.
+
+The engine first chooses a certified bundled placement using those existing
+strategies. Only the selected placement may then compare one completed generic
+unbundled route proposal, using the same ELK result and the same preference
+order. The decision to try this proposal reuses the selected placement's existing
+certification score, including the final comparison: unchanged selected geometry
+is not certified a second time. It does not explore an unbundled version of
+every placement strategy.
+Symmetric fan-in/fan-out routing remains enabled.
+Graphs containing parallel edges keep their specialized route owners and skip
+the generic unbundled proposal. A smaller proper-crossing count alone does not
+prove that duplicate endpoint lanes remain visibly distinct.
+
+The receipt's `preference.compared` entries retain the certified bundled
+placement scores. `preference.selectedScore` describes the actual final routes,
+and `preference.routing` records the selected placement's bundled/unbundled
+comparison, scores and deciding criterion.
+The receipt's `attempts` counts placement productions; the optional final route
+comparison is recorded separately.
+Clean graphs, equivalent strategies and larger inputs skip these comparisons;
+the upper bound is four placement pipelines plus one unbundled route pipeline,
+with the existing maximum of 16 ELK attempts. The unbundled proposal reuses the
+selected placement's ELK result. Search decisions use graph
+work counts, never elapsed time, so machine speed cannot change the drawing.
+These route comparisons apply to Flowchart and State, which retain the scored
+routes. Architecture uses the graph engine for placement and keeps its existing
+feasibility/title fallback before independently routing authored endpoint sides.
+The common positioning boundary also checks the final projection of every
+native family against the family rubric's hard geometry rules. Specialized
+layouters get one attempt and fail explicitly; their identical layout is not
+repeated as a pretend fallback. Verification and quality reuse that retained
+projection rather than positioning or projecting the artifact again.
+
+Route proposals, final ranking, pass budgets and public quality share the crossing predicate in
+`src/shared/edge-crossings.ts`. It excludes invisible shafts, endpoint contacts,
+tangencies and shared collinear ink. It counts each crossing location once per
+logical edge pair, including crossings far from a shared graph endpoint; route
+subdivision does not change the count. Endpoint tolerance is 0.01 physical
+pixels, independent of segment length. Public graph nodes, groups, paths, label
+anchors and canvas bounds retain subpixel coordinates so projection cannot erase
+this evidence or introduce a containment error.
+Invisible links may still have visible labels: those pills remain obstacles.
+Label-conflict counts share one implementation and the renderer's eight-pixel
+pill padding. A bundle certificate or matching text does not authorize two
+distinct labels to occupy the same space.
+Label/node conflicts use conservative node bounding rectangles; hard route/node
+avoidance retains its separate shape-aware contract.
+
 ## The rubric (used by both the LLM judge and the perceptual checker)
 
 ```
@@ -113,9 +235,10 @@ geometry assertions, screenshot/PNG review, or human inspection.
   (not bytes-only) for each. The adapters parse `d.canonicalSource` via the
   legacy per-family parser + layouter — the same geometry the SVG renderer draws
   — so an opaque-but-renderable body is still measured; an invalid opaque body
-  degrades to an empty layout instead of throwing. What `nodes` / `edges` /
+  fails explicitly with `FamilyLayoutError`; verification reports the failure. What `nodes` / `edges` /
   `groups` mean per family:
 
+  <!-- complete: family-ids -->
   | Family        | nodes                              | edges        | groups               |
   |---------------|------------------------------------|--------------|----------------------|
   | flowchart     | graph nodes (ELK)                  | graph edges  | subgraphs            |
@@ -133,12 +256,19 @@ geometry assertions, screenshot/PNG review, or human inspection.
   | mindmap       | hierarchy nodes                    | parent links | —                    |
   | gitgraph      | commits                            | parent links | —                    |
   | radar         | curve vertices (one ring per axis) | —            | axis spokes/grid     |
+  | sankey        | node rectangles | ribbon links (from/to) | —                    |
 
   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 font-substitution check.** Quality checks consume retained prepared pixel
+  text and renderer anchors; they do not guess width from character count.
+  `labelMeasurement` reports measured, unmeasured, hidden and semantic-only
+  labels, and missing visible-label evidence makes `checkQuality` warn. Painted
+  text in `layout.labels` participates without changing semantic node counts;
+  XYChart retains its point text and chart chrome there. Final canvas and
+  readability checks consume those retained bounds. A trusted
+  host measurement profile can improve pixel metrics, but neither that profile
+  nor a prepared block proves which font the display ultimately substituted.
 - **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

package/docs/react.md

@@ -1,29 +1,75 @@
 # React integration
 
-Agentic Mermaid renders synchronously to SVG strings, so React apps do not need iframe renderers, hidden browser sessions, or client-side Mermaid hydration.
+Browser-rendered React components should use the browser ESM entry. It loads the
+selected diagram family on demand and does not pull the Node/native package
+entry into a client bundle.
 
 ## Basic component
 
 ```tsx
-import { useMemo } from 'react'
-import { renderMermaidSVG } from 'agentic-mermaid'
+'use client'
 
-export function MermaidDiagram({ source }: { source: string }) {
-  const svg = useMemo(
-    () => renderMermaidSVG(source, { security: 'strict' }),
-    [source],
-  )
+import { useEffect, useId, useRef, useState } from 'react'
+import { renderMermaidSVGAsync } from 'agentic-mermaid/browser/lazy'
 
-  return <div className="diagram" dangerouslySetInnerHTML={{ __html: svg }} />
+export function MermaidDiagram({ source }: { source: string }) {
+  const output = useRef<HTMLDivElement>(null)
+  const idPrefix = `diagram-${useId().replace(/[^a-zA-Z0-9_-]/g, '')}`
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState('')
+
+  useEffect(() => {
+    let current = true
+    const host = output.current
+    if (!host) return
+    host.replaceChildren()
+    setLoading(true)
+    setError('')
+    renderMermaidSVGAsync(source, { security: 'strict', idPrefix }).then(
+      result => {
+        if (!current) return
+        const parsed = new DOMParser().parseFromString(result, 'image/svg+xml')
+        if (parsed.querySelector('parsererror') || parsed.documentElement.localName !== 'svg') {
+          setError('Renderer returned invalid SVG')
+          setLoading(false)
+          return
+        }
+        host.replaceChildren(document.importNode(parsed.documentElement, true))
+        setLoading(false)
+        setError('')
+      },
+    ).catch(cause => {
+      if (!current) return
+      setError(cause instanceof Error ? cause.message : String(cause))
+      setLoading(false)
+    })
+    return () => { current = false }
+  }, [source, idPrefix])
+
+  return <>
+    {error && <pre role="alert">{error}</pre>}
+    <div ref={output} className="diagram diagram-surface" aria-busy={loading} />
+  </>
 }
 ```
 
-`security: 'strict'` removes external-fetch references and is the safest default for user- or agent-generated diagrams.
+`security: 'strict'` removes external-fetch references and is the safest default
+for user- or agent-generated diagrams. The cancellation guard prevents an older
+render from replacing a newer source after it resolves. The per-component
+`idPrefix` prevents collisions between SVG definitions in multiple diagrams.
+Insert only this renderer's strict output, not arbitrary SVG: XML parsing is
+not sanitization. Rendering policy and the host's DOM/CSP policy remain separate.
+
+This basic recipe assumes the host does not enforce Trusted Types. With
+`require-trusted-types-for 'script'`, `DOMParser.parseFromString` is also a
+protected sink: adapt insertion through the application's reviewed,
+narrowly scoped TrustedHTML policy. Do not add a permissive default policy or
+disable CSP to make the example work. See [`browser.md`](./browser.md).
 
 ## Theme from CSS variables
 
 ```tsx
-const svg = renderMermaidSVG(source, {
+const svg = await renderMermaidSVGAsync(source, {
   bg: 'var(--diagram-bg)',
   fg: 'var(--diagram-fg)',
   accent: 'var(--diagram-accent)',
@@ -55,7 +101,7 @@ Because the SVG keeps CSS variables in place, toggling `.dark` updates existing
 
 ## PNG export button
 
-PNG rendering returns bytes. In browser-oriented React apps, call the PNG helper from a server action/API route or other Node-capable boundary where `@resvg/resvg-js` is available.
+PNG rendering returns bytes. The native helper below needs a server action/API route or other Node-capable boundary where `@resvg/resvg-js` is available.
 
 ```ts
 import { renderMermaidPNG } from 'agentic-mermaid/agent'
@@ -65,31 +111,30 @@ export function renderDiagramPng(source: string) {
 }
 ```
 
-For client-only exports, use the live editor/browser's existing download path or post the source to a server endpoint.
+For client-only exports, the root `agentic-mermaid` entry also exports a
+host-injected browser PNG path: `renderMermaidPNGInBrowserWithReceipt(source,
+options, output, rasterize)` or the reusable
+`createMermaidBrowserPNGRenderer({ rasterize })`. No browser rasterizer ships
+with the library: the host supplies `rasterize(securedSvg, context)` (for
+example with Canvas/OffscreenCanvas), which must resolve to `{ png }` bytes at
+exactly `context.rasterDimensions` on `context.rasterBackground`, and may report
+`fontSources` and `diagnostics`. See [browser PNG details](./api-advanced.md#png-fonts-portability-and-rasterization). Otherwise, post
+the source to a server endpoint.
 
 ## Error handling
 
-For untrusted source, parse or verify before rendering:
-
-```tsx
-import { parseRegisteredMermaid, verifyMermaid, renderMermaidSVG } from 'agentic-mermaid/agent'
-
-export function SafeDiagram({ source }: { source: string }) {
-  const result = useMemo(() => {
-    const parsed = parseRegisteredMermaid(source)
-    if (!parsed.ok) return { ok: false, message: parsed.error.map(e => e.message).join('\n') }
+The component above reports parse and render failures through its `role="alert"`
+fallback. If a client workflow also needs structured parse/verify results, use
+the runtime-neutral agent entry; do not import the Node/native
+`agentic-mermaid/agent` entry into the browser bundle:
 
-    const verify = verifyMermaid(parsed.value)
-    if (!verify.ok) return { ok: false, message: verify.warnings.map(w => w.code).join(', ') }
-
-    return { ok: true, svg: renderMermaidSVG(parsed.value, { security: 'strict' }) }
-  }, [source])
-
-  if (!result.ok) return <pre>{result.message}</pre>
-  return <div dangerouslySetInnerHTML={{ __html: result.svg }} />
-}
+```ts
+import { parseRegisteredMermaid, verifyMermaid } from 'agentic-mermaid/agent/core'
 ```
 
+For server components, build steps, and API routes, the synchronous
+`renderMermaidSVG` export from `agentic-mermaid` remains appropriate.
+
 ## See also
 
 - [`api.md`](./api.md) for render options.

package/docs/style-authoring.md

@@ -98,6 +98,19 @@ not-applicable evidence; they never repaint or relayout. Transparent output has
 no known host backdrop, so contrast reports unmeasurable rather than inventing
 a ratio.
 
+Treemap retains explicit Scene text ink when deriving automatic category fills. Its
+shared palette chooses readable, page-visible and distinguishable colors
+together, before brand constraints inspect the Scene. Sketch labels that already
+read on the selected backend's page-colored halo do not constrain the cell fill.
+The actual graphical backend includes host overrides; layout models its nominal
+Style backend. Authored fills stay exact.
+The shared sketch backend still applies its existing page-halo readability
+policy to ink that does not read on that page.
+If bounded search cannot satisfy concrete ink/page choices, choose another text
+color or an explicit readable fill; the renderer reports that configuration
+limit. Unresolved and translucent inks retain their authored values without a
+contrast guarantee.
+
 ### Export and edit a built-in
 
 Built-ins dogfood this same record format. Export one with `getStyle`, validate
@@ -130,11 +143,8 @@ BrandPack registry is deliberately **not promoted**. Render-time semver ranges,
 dependency solving, ambient resource loading, and a second inheritance system
 remain absent.
 
-The generated [Section B capability report](./project/section-b-capability-report.md)
-accounts for every role leaf, private-face projection, role fallback, admitted
-family role/channel, and built-in export.
-The [all-family evidence sheet](./design/families/section-b-brand-evidence.png)
-shows one deliberately distinctive sentinel plus three holdout styles; its receipt
+The [reviewed all-family rendering golden](../src/__tests__/testdata/section-b-brand-evidence.png)
+shows one deliberately distinctive sentinel plus three holdout styles; its review record
 and honest hard-error baseline live in `eval/section-b-brand-evidence/`.
 
 Every field is optional in a reusable fragment, but the resolved final stack
@@ -162,7 +172,7 @@ accepted as a Style name.
   sets via `RenderOptions` colors or Mermaid `themeVariables` wins. The full
   precedence is one line: `defaults < style stack (left→right) <
   themeVariables < explicit color options`.
-- **Determinism.** All stochastic marks are seeded
+- **Determinism.** All stochastic artwork is seeded
   `hash(options.seed, stableNodeId, substream)`. Source, resolved options,
   frozen registry/capability/resource snapshots, runtime contract and seed fix
   the bytes. `seed` re-rolls wobble without moving layout. Opt-in caller or
@@ -241,12 +251,14 @@ layout-aware dialect) justifies code. Trusted hosts can implement and register
 a namespaced `StyleBackend`; selection is an in-process `HostBackendPolicy`,
 not serializable Style data or a CLI/MCP/editor field. Keep the determinism rule
 (seed in, bytes out). Backends never dispatch on diagram family — they see
-semantic scene marks and paint channels. A registered backend also declares
+semantic Scene parts and paint channels. Existing `SceneNode` and `*Mark` type
+names refer to those parts; see the [shared vocabulary](./api.md#vocabulary).
+A registered backend also declares
 feature/operation-level `PrimitiveCapabilityClaim`s for every core Scene
 primitive; registration rejects empty, duplicate, or cross-target claims so an
 extension cannot imply support it has not described. Registration then executes
 a frozen document fixture plus one exact witness for each declared first-party
-core primitive/feature/operation claim. It rejects a backend that varies
+core Scene primitive/feature/operation claim. It rejects a backend that varies
 identical `drawNode`/`render` calls, emits unsafe or malformed SVG, drops the
 document sentinels, or fails any claim-keyed witness. Namespaced extension claims
 with no core witness remain explicitly `unverified-extension`.
@@ -260,7 +272,7 @@ contract explicitly; no built-in compatibility default is borrowed by
 ```ts
 registerBackend(backend, {
   version: '1.0.0',
-  compatibility: { core: '^0.4.0', scene: '^2.0.0' },
+  compatibility: { core: '^0.5.0', scene: '^2.0.0' },
   provenance: { owner: 'acme-diagrams', source: 'application-startup' },
 })
 ```
@@ -330,7 +342,7 @@ bun test src/__tests__/styled-output.test.ts --timeout 30000   # determinism + g
 bun test src/__tests__/scene-fidelity.test.ts  # semantic/backend agreement
 ```
 
-Then render your style across every registered diagram type and *look at it small*
-— the poster/contact-sheet harness in `scripts/sketch-prototype/` is the
+Then render your style across every registered diagram family and *look at it small*
+— the optional research poster/contact-sheet harness in `scripts/sketch-prototype/` is the
 visual-review surface. A style ships when it is distinctive at a glance,
 legible at cell size, and honest to its intent.