agentic-mermaid 0.4.1 → 0.5.3

package/docs/ascii.md

@@ -2,6 +2,11 @@
 
 Agentic Mermaid can render Mermaid diagrams as terminal text. Unicode box drawing is the default; 7-bit ASCII is available for logs, email, CI output, and constrained terminals.
 
+Built-in terminal families use a [shared terminal compositor](https://github.com/adewale/agentic-mermaid/blob/main/docs/project/terminal-composition.md)
+for owned cell geometry. ASCII/Unicode alphabet selection and plain, ANSI or
+terminal HTML encoding derive from that drawing. SVG/PNG retain separate pixel
+geometry; family placement and routing retain their own constraints.
+
 ## Quick start
 
 ```ts
@@ -65,7 +70,40 @@ import { renderMermaidASCIIWithMeta } from 'agentic-mermaid/agent'
 const { ascii, regions, actions, warnings, routeParity } = renderMermaidASCIIWithMeta(source)
 ```
 
-`regions` includes best-effort terminal spans for load-bearing node labels, edge labels where mapped, participant/task/chart labels, and semantic containers such as clusters, sequence fragments, class compartments, chart plots, and radar rings. It is suitable for click mapping, but is not a full cell-by-cell box/edge hit-test tree. `actions` contains inert action metadata only; a host must decide whether and how to handle it. `routeParity` is an explicit V1 contract: ASCII/Unicode does not consume SVG route certificates directly; the converter seeds edges with shared `classifyRoutes()` route intent and the grid router maps that intent into terminal placement/routing. `warnings` reports structured degradation such as `ASCII_EDGE_REGION_UNMAPPED` when edge cell spans are not instrumented even though route drawing still follows the parity mapping.
+For built-in native terminal output, `regions` comes from the drawing retained
+by that render. `canvasRow`, column bounds and `rowSpan` describe a primary text
+occurrence or an explicitly allocated container/route rectangle. That rectangle
+can include empty cells. Use `ownedCellSpans` for exact occupied cells, including
+authored spaces and wide-character continuations; `occludedCellSpans`, when
+present, describes relationship coverage hidden behind opaque marks. Repeated
+labels retain separate element identities, and parent references include
+`parentId` and `parentKind`. These fields support cell-based hit testing without
+searching the rendered label text.
+
+`projectedText` preserves deliberately empty rows of its primary logical text
+occurrence, including leading and trailing rows. Separate occurrences do not
+acquire newlines merely because they are far apart on the canvas. Empty rows
+retain provenance without inventing occupied cells.
+
+Family parsing retains authored identities and endpoints. Shared display
+preparation neutralizes C0/C1 controls before pixel or cell fitting, while typed
+IDs, connector references and action targets remain exact. XML attribute
+serialization separately preserves identity whitespace. Sankey's CSV parser
+receives physical authored rows, including blank rows inside quoted labels.
+
+`actions` contains inert action metadata only; a host decides whether and how to
+handle it. `routeParity` records route intent and projection limits; it does not
+certify identical SVG/terminal paths or guarantee that every family layout can
+fit. Terminal drawing does not consume SVG route certificates directly.
+
+Inspect `warnings` for refused geometry and feature-specific projection losses.
+An edge region with ports is not evidence that its label was painted: check its
+owned/projected text and any collision diagnostic. Compound graph placement
+keeps child containers atomic within their parent; parallel/reciprocal allocation
+reserves physical ports and complete labels before routing. Bounded allocation
+can still fail, and a diagnostic must not be treated as a successful route.
+String-only extension hooks report `TERMINAL_OWNERSHIP_UNAVAILABLE`; metadata
+does not invent regions from their text.
 
 ## Reversing simple flowcharts
 
@@ -86,9 +124,7 @@ not for reconstructing arbitrary Mermaid source.
 ## Supported families
 
 Family support is registry-driven rather than maintained as a second list in
-this guide. Run `am capabilities --json` for live discovery; the generated
-[Section A capability matrix](./project/section-a-capability-report.md) records
-terminal projection support and named losses for every registered family.
+this guide. Run `am capabilities --json` for live discovery.
 
 Style appearance is projected to terminal colors and glyphs. Use a
 receipt-bearing render API to compare its `appearanceDigest` with graphical

package/docs/browser.md

@@ -6,12 +6,41 @@ the diagram source known before the page is served?**
 | Your case | Use | JS shipped |
 |---|---|---|
 | Source is fixed at publish time — blog post, docs page, README | [Pre-render before delivery](#framework-neutral-pre-rendering) | none |
-| Source is authored or edited in the page — editor, playground, user input | [Async family-loaded renderer](#async-family-loaded-esm) | 41 KB initial; 162 KB for a first Timeline render, gzip |
-| One classic script with a synchronous global matters more than transfer | [Compatibility bundle](#classic-one-file-compatibility-bundle) | 896 KB gzip |
+| Source is authored or edited in the page — editor, playground, user input | [Async family-loaded renderer](#async-family-loaded-esm) | loader plus the selected family and shared core |
+| Synchronous source-to-SVG without editing or terminal APIs | [Focused SVG entry](#focused-synchronous-svg) | SVG families and the default backend |
+| One classic script with a synchronous global matters more than transfer | [Compatibility bundle](#classic-one-file-compatibility-bundle) | complete renderer and library APIs |
 
 Most sites are the first row. `renderMermaidSVG` is synchronous and needs no DOM,
 so a static site never has to ship the renderer to a reader.
 
+## Focused synchronous SVG
+
+Use `agentic-mermaid/svg` when a consumer needs source-to-SVG rendering without
+the typed editing, terminal, or PNG APIs. It uses the same request, security,
+geometry and final-paint certification pipeline as the complete library, and
+offers `renderMermaidSVGWithReceipt` as well as the string projection:
+
+```ts
+import { renderMermaidSVGWithReceipt } from 'agentic-mermaid/svg'
+const { svg, receipt } = renderMermaidSVGWithReceipt('flowchart LR\n API --> DB', {
+  security: 'strict',
+})
+```
+
+This entry accepts Mermaid source strings. Parsed diagrams and extension
+registration remain on the complete library/agent entries. Palette changes use
+the default backend. To enable sketch looks synchronously, explicitly import
+`agentic-mermaid/svg/styles` before rendering with a sketch style. Browser
+bundlers can consume the same focused ESM entry. A second monolithic SVG bundle
+is deliberately not shipped: it would duplicate ELK in every npm installation.
+
+The async browser entry loads optional sketch backends on demand and also
+exports `renderMermaidSVGWithReceiptAsync`. An unloaded loader is not a usable
+renderer: compare the complete first-family request graph when choosing an entry.
+
+The hosted editor uses separate modules for rendering, verification, text output
+and PNG export. The standalone `bun run editor` build remains self-contained.
+
 ## Framework-neutral pre-rendering
 
 Pre-rendering is not tied to Alpine, React, or any other UI framework. The
@@ -291,6 +320,13 @@ artifact remains covered separately by the all-family browser contract.
 Keep `security: 'strict'` for authored or user-provided source, and insert the
 accepted result as parsed XML nodes as shown above. Do not assign renderer output
 to `innerHTML`: strict rendering and DOM insertion are separate trust boundaries.
+XML parsing is not a sanitizer; accept only the strict renderer's result.
+These DOMParser examples assume Trusted Types is not enforced. Under
+`require-trusted-types-for 'script'`, parsing is also a protected sink: supply
+the application's reviewed, narrowly scoped TrustedHTML adapter rather than
+adding a permissive default policy or disabling CSP. Server/build frameworks
+likewise need their own reviewed trusted-markup boundary.
+See [DOMParser's security and Trusted Types requirements](https://developer.mozilla.org/en-US/docs/Web/API/DOMParser/parseFromString#security_considerations).
 The integrity value pins the reviewed bytes as well as the version. When the
 package version changes, recompute it with:
 
@@ -391,9 +427,11 @@ file around the root export:
 
 1. **Separate catalog from runtime hooks.** Family ids, header detection,
    maturity, capabilities, and canonical examples must live in a browser-safe
-   catalog that imports no parser, layout, SVG, ASCII, or agent hooks. Today the
-   complete registry imports those hooks, which pulls the whole graph into a
-   nominally render-only bundle.
+   catalog that imports no parser, layout, SVG, ASCII, or agent hooks. The
+   complete registry imports those hooks and would pull the whole graph into a
+   nominally render-only bundle, so
+   `scripts/build/generate-browser-family-catalog.ts` generates a hook-free
+   catalog in `src/browser-lazy/generated/` instead.
 2. **Keep one source-normalization authority.** The loader must handle BOMs,
    frontmatter, init directives, comments, and accessibility directives with
    the same contract as server rendering. Refactor that contract so detection
@@ -431,8 +469,9 @@ filename:
 - initial and per-family request-count, raw, gzip, and Brotli budgets are
   recorded separately.
 
-`bun run build:browser:lazy` generates the exhaustive catalog, builds the
-chunks, and fails on dependency or size drift. `bun test
+`bun run build:browser:lazy` generates the exhaustive catalog and builds the
+chunks; `bun run check:browser-lazy`, which `bun run quality:check` runs once
+per CI run, fails on dependency or size drift. `bun test
 src/__tests__/browser-lazy.test.ts` proves all-family byte parity in-process;
 `bun test e2e/browser-bundle.e2e.test.ts --timeout 600000` proves the emitted
 HTTP module graph, strict-mode parity, non-ELK exclusion, and shared ELK caching

package/docs/choosing-a-diagram.md

@@ -0,0 +1,148 @@
+# Choosing a diagram family
+
+Start from the task the reader must perform. A diagram family is the result of
+that decision, not the starting point: the same deployment can be drawn as a
+flowchart, an architecture diagram, or a sequence diagram, and only the
+reader's question tells you which one is right. This page routes from task to
+family. Syntax and per-family caveats live in
+[`diagram-families.md`](./diagram-families.md); the authoritative list of what
+renders and what mutates is `am capabilities --json`, not this page.
+
+## Start from the reader's task
+
+<!-- complete: family-ids -->
+| The reader must | First choice | Reach for instead when |
+|---|---|---|
+| Follow steps and decisions to an outcome | Flowchart | The subject reacts to events rather than proceeding through steps: state |
+| See how a system moves between modes | State | The path is a linear procedure: flowchart |
+| Read who sends what to whom, in order | Sequence | Only dependency matters, not order: flowchart |
+| Read how protocol fields occupy bit addresses and word rows | Packet | Message order between actors matters: sequence |
+| Compare dated work with durations and dependencies | Gantt | There are no dates, only eras: timeline |
+| Track work by workflow stage, assignee, ticket, and priority | Kanban | Dates, durations, and dependencies matter: gantt |
+| Scan periods and what happened in each | Timeline | The story is one person's scored experience: journey; the history is commits and branches: gitGraph |
+| Judge how a process felt to the person in it | Journey | No actors or sentiment scores exist: timeline |
+| Trace where quantities go from stage to stage | Sankey | The amounts don't need to balance: flowchart with labeled edges |
+| Judge parts of one whole at one moment | Pie | Slices are many or nearly equal, or values change over time: xychart |
+| Compare value proportions within a hierarchy | Treemap | There is no hierarchy: pie; precise comparisons matter more than area: xychart |
+| Compare measured values across categories or time | XY chart | The values are shares of a single whole: pie |
+| Place options on two independent axes | Quadrant | Each option is scored on three or more criteria: radar |
+| Compare profiles across three or more shared criteria | Radar | There are exactly two criteria: quadrant |
+| See stored data and how records relate | ER | Behavior and methods matter, not storage: class |
+| See code structure, types, and inheritance | Class | Only the persistence shape matters: er |
+| Trace requirements to supporting elements and verification evidence | Requirement | The subject is software types and inheritance: class |
+| See services, their grouping, and physical links | Architecture | The flow is logical rather than deployed: flowchart |
+| Read a deliberately arranged grid of components and nested groups | Block | Connectivity should choose placement: flowchart; infrastructure ports matter: architecture |
+| Explain people, software responsibilities and nested system or deployment boundaries | C4 | The reader needs infrastructure ports and physical links: architecture; protocol timing: sequence |
+| Follow commits, branches, and merges | GitGraph | — |
+| Explore ideas radiating from one center | Mindmap | Branches share children (the structure is a graph, not a tree): flowchart |
+| Investigate contributing causes of one effect | Ishikawa | The branches are ideas without a cause-and-effect claim: mindmap |
+
+## Check the source shape first
+
+Some families make source order carry meaning, and a few enforce arithmetic.
+Know which constraints apply before you author:
+
+- **Order is the timeline.** Sequence messages, timeline periods, journey
+  tasks, and gantt tasks mean something by their position; a gantt task with no
+  explicit start chains from the task above it. Reordering is a first-class
+  edit in these families (`move_message`, `move_period`, `move_task`), not a
+  cut-and-paste.
+- **Sankey flows are an account.** An intermediate node that receives 100 and
+  emits 80 renders as if it carried 100, hiding the missing 20. Verification
+  names the unaccounted amount (`FLOW_IMBALANCE`); balance the links or add an
+  explicit remainder sink.
+- **Bar length is the value.** XY chart bars grow from zero, so an authored
+  `y-axis` range that excludes zero makes lengths lie; verification names the
+  baseline the bars start from (`BAR_RANGE_EXCLUDES_ZERO`), and a range that
+  leaves values outside it names them (`VALUES_OUTSIDE_RANGE`). Many long category
+  names do not all fit under a vertical chart; verification lists the ones the
+  axis does not draw (`LABELS_HIDDEN`), and a horizontal chart lists them down
+  the side.
+- **Values have domains.** Journey scores are finite numbers 1–5, quadrant
+  coordinates live in `[0, 1]`, pie values are positive, radar curves carry
+  one value per axis. Out-of-domain input falls back to a lossless opaque body
+  instead of a wrong render.
+- **Labels select typed edits in the data families.** Pie slices, quadrant
+  points, and radar axes and curves use labels as mutation selectors; typed
+  add/rename operations reject collisions. Existing source can still contain
+  duplicate labels, so make those identities unique before a label-addressed
+  edit. Sankey node labels are intentionally shared across links and identify
+  the same flow node.
+- **Terminal delivery is real delivery.** Every registered family renders
+  ASCII. A width the diagram cannot honestly meet throws `AsciiWidthError`
+  with the required width instead of squeezing the layout.
+- **C4 interactions have occurrence identity.** Repeated endpoint pairs are
+  separate interactions. Dynamic order and explicit indices survive, while
+  generated interaction selectors can change after structural edits; read the
+  successful result before the next edit. See [C4](https://github.com/adewale/agentic-mermaid/blob/0f05d39858d0061b79a0c99ef03a5c10d537ddaa/docs/design/families/c4.md).
+- **Bit addresses and grid cells carry meaning.** Packet ranges are inclusive;
+  descending bit numbering mirrors the display without changing field addresses.
+  Block source order, columns, spans, and spaces determine placement; connectors
+  do not rearrange that grid.
+- **Membership is authored data.** Kanban indentation places cards in columns;
+  Ishikawa starts with the effect and uses indentation for contributing causes;
+  Treemap parentage and numeric leaf values determine containment and area.
+  Use the family's typed movement operations to change membership deliberately.
+- **Requirement relations are typed traceability.** Containment, satisfaction,
+  verification, and the other relation kinds retain their own meaning and
+  endpoint orientation. Discover the family schema instead of borrowing
+  flowchart edge syntax.
+
+## Prefer the smallest structure that carries the meaning
+
+1. Start with the family's base statements: nodes and edges, states and
+   transitions, messages, tasks.
+2. Label what the reader would otherwise guess. Every exit of a multi-exit
+   decision carries its condition; verification cites the standards that
+   require it (`DECISION_BRANCH_UNLABELED`, from ISO 5807 and ANSI X3.5).
+3. Group only around real ownership: subgraphs, composite states, sections,
+   architecture groups. A box that answers "who owns this?" earns its border.
+4. Adjust direction after grouping, per subgraph where supported.
+5. Add classes and styles last. Brand color, typography, and texture belong to
+   the Style + Palette render options, not to the source.
+
+If the construct you want is not modeled, check whether another family owns
+that metaphor before bending this one. Source preservation does not establish
+render support: C4 refuses a partial drawing when a retained statement has no
+native interpretation. Check the family's documented disposition.
+
+## Defaults that mislead
+
+- A pie of six nearly equal slices asks the reader to compare angles, which
+  eyes do badly. Rank the values as xychart bars.
+- A flowchart standing in for a protocol misleads because arrows read as
+  causality, not time. Message order is what sequence diagrams encode.
+- A gantt without real dates is a timeline wearing a scheduler. The gantt
+  scheduler resolves calendars and dependencies; if nothing depends on
+  duration, timeline says the same thing with less machinery.
+- A mindmap can only draw a tree. The moment two branches need the same
+  child, move to a flowchart.
+- A timeline that smuggles in durations ("Q1–Q3: migration") usually wants to
+  be a gantt, where `after` and `until` make the dependency checkable.
+- A radar comparison is honest only when every curve shares the axes and the
+  scale; set `max`/`min` explicitly rather than letting one outlier stretch
+  the grid.
+- Today markers in gantt render only when the caller passes `ganttToday`;
+  relying on the wall clock would make the render non-reproducible, so there
+  is no implicit "today."
+
+## Verify what the family promised
+
+Choosing well is checkable. After authoring or editing, run `verifyMermaid`
+(or `am verify`):
+
+- **Tier 1 — structural:** <!-- 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 -->
+  must be empty before committing; they mean the source or render contract is
+  broken, not merely ugly.
+- **Tier 2 — geometric:** `NODE_OVERLAP` and route warnings flag layouts
+  worth a look; suppress them only when the geometry is intentional.
+- **Tier 3 — lint:** the codes cited above name the family-specific mistakes
+  this page warns about. Each code's page under
+  <https://agentic-mermaid.dev/warnings/> says what triggers it and how to
+  clear it.
+
+Two checks no lint sees: give the diagram a title or `accTitle` that states
+the reader's question, and read the ASCII render in a terminal once, because
+reviewers will.
+
+The reader's task picks the family; `verify` checks what the family promised.

package/docs/code-mode-impact.md

@@ -45,6 +45,7 @@ environment, `globalOutbound: null`, no subrequests, and a bounded CPU budget.
 The isolate configuration is the security boundary. The hardened SDK facade is
 kept for behavioural parity with the local server.
 
+<!-- complete: hosted-mcp-tools -->
 Hosted execution has a per-call cost, so common pure operations do not enter
 the sandbox. `render_svg`, `render_ascii`, `render_png`, `verify`, `describe`,
 and `describe_sdk` run as ordinary Worker calls whose successful deterministic