agentic-mermaid 0.1.2 → 0.2.0

package/docs/ascii.md

@@ -0,0 +1,113 @@
+# ASCII and terminal output
+
+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.
+
+## Quick start
+
+```ts
+import { renderMermaidASCII } from 'agentic-mermaid/agent'
+
+const unicode = renderMermaidASCII(`flowchart LR
+  API --> DB`)
+const ascii = renderMermaidASCII(`flowchart LR
+  API --> DB`, { useAscii: true })
+```
+
+CLI:
+
+```bash
+am render diagram.mmd --format ascii
+am render diagram.mmd --format unicode
+```
+
+## Options
+
+`AsciiRenderOptions` extends the canonical shared `RenderOptions` used by SVG
+and PNG, so Style stacks, colors, font choice, security policy, and other
+shared request fields enter through the same boundary. Call
+`sharedRenderOptionsJsonSchema()` for the machine-readable shared field set.
+The options below are terminal-specific.
+
+```ts
+renderMermaidASCII(source, {
+  useAscii: true,
+  paddingX: 4,
+  paddingY: 2,
+  boxBorderPadding: 1,
+  colorMode: 'none',
+  targetWidth: 80,
+})
+```
+
+| Option | Type | Default | Meaning |
+|---|---|---:|---|
+| `useAscii` | `boolean` | `false` | Use `+`, `-`, `|` instead of Unicode box drawing. |
+| `paddingX` | `number` | `5` | Horizontal spacing between boxes. |
+| `paddingY` | `number` | `5` | Vertical spacing between layers. |
+| `boxBorderPadding` | `number` | `1` | Padding inside node boxes. |
+| `colorMode` | `string` | `'auto'` | `'none'`, `'auto'`, `'ansi16'`, `'ansi256'`, `'truecolor'`, or `'html'`. |
+| `theme` | `Partial<AsciiTheme>` | — | Override terminal colors. |
+| `maxWidth` | `number` | — | Deprecated best-effort label wrapping; the canvas may exceed it. |
+| `targetWidth` | `number` | — | Hard maximum in terminal display cells; impossible geometry throws `AsciiWidthError` with code `ASCII_TARGET_WIDTH_IMPOSSIBLE`. |
+
+HTML is an escaped terminal projection, selected programmatically with
+`renderMermaidASCII(source, { colorMode: 'html' })`. It is not a standalone
+`am render --format` value; CLI discovery advertises only directly supported
+artifact formats.
+
+## ASCII with metadata
+
+Agents and TUIs can use `renderMermaidASCIIWithMeta` to map terminal cells back to diagram regions:
+
+```ts
+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.
+
+## Reversing simple flowcharts
+
+```ts
+import { asciiToMermaid } from 'agentic-mermaid/agent'
+
+const result = asciiToMermaid(ascii)
+if (result.ok) {
+  const source = result.value // reconstructed Mermaid source
+}
+```
+
+`asciiToMermaid` returns a `Result<string, ParseError[]>`: `result.value` holds the
+Mermaid source on success, and `result.error` lists parse errors (e.g. `NO_BOXES`)
+otherwise. This is best-effort and lossy. It is useful for simple linear flowcharts,
+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.
+
+Style appearance is projected to terminal colors and glyphs. Use a
+receipt-bearing render API to compare its `appearanceDigest` with graphical
+outputs, and inspect projection diagnostics when a graphical feature has no
+terminal equivalent. `colorMode: 'auto'` disables color for non-TTY output,
+`TERM=dumb`, and `NO_COLOR` before considering color-depth hints.
+
+PNG output is separate: use `renderMermaidPNG(source)` or `am render --format png --output file.png` when a raster artifact is required.
+
+## XY charts
+
+XY charts render to a compact terminal plot:
+
+```ts
+const chart = renderMermaidASCII(`xychart-beta
+  title "Latency"
+  x-axis [p50, p95, p99]
+  y-axis "ms" 0 --> 500
+  line [50, 180, 420]`)
+```
+
+Use SVG or PNG for publication-quality chart artifacts; use ASCII/Unicode for terminal summaries and agent-visible evidence.

package/docs/code-mode-impact.md

@@ -0,0 +1,214 @@
+# Code Mode in Agentic Mermaid: impact, comparison, and costs
+
+Agentic Mermaid uses Code Mode to keep a diagram edit inside one execution:
+parse the source, narrow it to a mutable family, apply typed operations, verify
+the result, and serialize only after verification passes. This changes both
+the model-facing boundary and the execution boundary. The model writes a small
+algorithm instead of relaying each intermediate diagram through another tool
+call, while the server retains the trusted diagram lineage needed to reject
+forged or invalid edits.
+
+This document uses **local Code Mode** for the self-hosted MCP process running
+on the agent's machine and **hosted Code Mode** for the public
+`https://agentic-mermaid.dev/mcp` endpoint. Cloudflare calls the same split
+client-side and server-side Code Mode. The names describe where the sandbox
+runs, not where the model runs.
+
+## Local Code Mode
+
+The local `agentic-mermaid-mcp` exposes `execute(code)`, which runs synchronous
+JavaScript against the typed `mermaid.*` SDK in a hardened `node:vm` context.
+The execution can retain parsed diagrams between SDK calls, so the model does
+not have to copy an intermediate representation into another JSON request.
+That matters because Agentic Mermaid's mutation checks depend on provenance:
+SDK results are read-only, and structured changes must pass through
+`mermaid.mutate`.
+
+Running beside the agent also keeps diagram source local and avoids hosted
+compute charges. The local server can return managed PNG files or URLs through
+its direct `render_png` helper, while multi-step editing remains in `execute`.
+The [MCP Code Mode rationale](./mcp-code-mode-rationale.md) explains why those
+helpers stay narrow rather than recreating the full SDK as individual tools.
+
+Progressive SDK discovery removed the largest client-side cost. The initial
+`execute` declaration now contains the core SDK, while
+`describe_sdk({ family, detail })` returns the mutation schema for one diagram
+family. An agent that already knows an operation can skip discovery; an agent
+handling an unfamiliar family can request compact signatures or exact fields.
+
+## Hosted Code Mode
+
+The hosted endpoint puts the sandbox behind the MCP server, so an ordinary MCP
+client gets Code Mode without shipping its own execution environment. Each
+hosted `execute` runs in a Cloudflare Dynamic Worker configured with an empty
+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.
+
+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
+results can be reused by the private server-side Workers Cache. The JSON-RPC
+HTTP responses remain `cache-control: no-store`.
+Declarative `mutate` and `build` apply typed operation lists through the same
+mutation core and verify before returning source. They give smaller models a
+direct path for routine edits while reserving `execute` for control flow that
+the operation list cannot express.
+
+Local and hosted Code Mode share the same `mermaid.*` facade. Differential
+tests compare result envelopes, errors, trace behaviour, read-only enforcement,
+and serialization across both runtimes. The
+[hosted MCP as-built record](./project/archive/hosted-mcp-cloudflare-plan.md) documents
+the remaining runtime differences and abuse controls.
+
+## Measured effect
+
+[PR #157](https://github.com/adewale/agentic-mermaid/pull/157) measured the
+serialized declarations and tool lists with `o200k_base`. These counts are a
+stable before-and-after proxy, not a provider billing claim.
+
+| Model-facing surface | Before | After | Tokens saved |
+|---|---:|---:|---:|
+| `execute` SDK declaration | 10,527 | 903 | 9,624 (91.4%) |
+| Local `tools/list` | 11,781 | 1,840 | 9,941 (84.4%) |
+| Hosted `tools/list` | 15,646 | 2,969 | 12,677 (81.0%) |
+
+The median complete family schema is 495 tokens. A hosted client that loads the
+initial tool list and then requests that schema consumes 3,464 tokens, 77.9%
+less than the old hosted list. The largest family, flowchart, brings the total
+to 4,928 tokens, which is still 68.5% lower. Compact signature responses have a
+113-token median.
+
+The same PR ran four schema-sensitive edits against the exact before and after
+hosted tool lists. Each proposed mutation was replayed through the real
+`applyOps` implementation and checked against semantic facts.
+
+| Model | Before task-correct | After task-correct | After discovery |
+|---|---:|---:|---:|
+| `gpt-5.4-mini` | 3/4 | 4/4 | 4/4 |
+| `gpt-5.3-codex-spark` | 4/4 | 4/4 | 4/4 |
+| **Combined** | **7/8** | **8/8** | **8/8** |
+
+All 16 mutations across both conditions applied successfully. The one incorrect
+before-case omitted a requested Architecture edge label; the after-case kept
+it. The combined four-case prompt fell from 16,048 to 5,833 tokens, a 63.7%
+reduction even though the test prompt included all four family responses at
+once. A normal request discloses one family.
+
+This eval is evidence for the discovery change, not a broad model-quality
+claim. It covers four tasks and two small models. Larger task sets, more model
+families, and production latency measurements remain separate work.
+
+## Comparison with Cloudflare and Anthropic
+
+Agentic Mermaid applies Code Mode to a pure diagram library. Cloudflare and
+Anthropic apply the same technique to general tool catalogs, where generated
+code may call remote services and carry data between them. That scope
+difference explains most of the implementation differences.
+
+| Dimension | Agentic Mermaid | Cloudflare | Anthropic |
+|---|---|---|---|
+| Primary scope | One deterministic diagram SDK | MCP tools and large APIs | General tool catalogs |
+| Discovery | `describe_sdk` for one diagram family | Typed connectors, or `search` over an OpenAPI document | Tool Search, or filesystem-shaped tool definitions |
+| Model-written code | Synchronous JavaScript | Asynchronous JavaScript | Python in Programmatic Tool Calling |
+| Execution | Local `node:vm` or hosted Dynamic Worker | Dynamic Worker isolate | Anthropic Code Execution sandbox |
+| Calls made from code | Pure in-process SDK calls | MCP calls or an authenticated request callback | Developer-provided tools |
+| External effects | None beyond returned diagram artifacts | Allowed through host-controlled bindings and authorization | Allowed for tools that opt into programmatic calling |
+| Persistent state | None | Durable runtime options are available | Filesystem state and reusable skills are possible |
+
+### Cloudflare
+
+Cloudflare's first Code Mode implementation converted connected MCP tools into
+a TypeScript API and ran the model's JavaScript in a Dynamic Worker. Its current
+MCP patterns cover both a single `code` tool, where the complete generated API
+fits in the tool description, and `search` plus `execute`, where a large
+OpenAPI document stays inside the discovery sandbox. Authentication remains in
+the host callback rather than entering generated code.
+
+That general implementation supports asynchronous calls, remote APIs,
+authorization and, in the durable runtime, pause-and-resume approval. Agentic
+Mermaid does not need those facilities because its SDK calls are synchronous,
+pure, and confined to one diagram transaction. It does use the same Dynamic
+Worker substrate for hosted isolation, but it does not depend on
+`@cloudflare/codemode`.
+
+Cloudflare measured its server-side `search` and `execute` surface at roughly
+1,000 tokens for more than 2,500 API endpoints, 99.9% fewer than direct MCP
+definitions. Agentic Mermaid's percentage is not directly comparable because
+its catalog is smaller and its hosted tool list retains more direct helpers.
+
+Sources: [original Code Mode design](https://blog.cloudflare.com/code-mode/),
+[server-side API implementation](https://blog.cloudflare.com/code-mode-mcp/),
+and [current MCP server patterns](https://developers.cloudflare.com/agents/model-context-protocol/codemode/).
+
+### Anthropic
+
+Anthropic's November 2025 architecture generated a filesystem-like tree of MCP
+tool definitions so an agent could inspect only the files it needed. It also
+proposed a `search_tools` alternative with selectable detail levels. The code
+execution environment could filter large results, retain intermediate state,
+and pass data between tools without putting that data into the model context.
+
+Anthropic later shipped the mechanism as Tool Search and Programmatic Tool
+Calling. Deferred tools stay out of the initial prompt, while Python running in
+the Code Execution sandbox can pause for an allowed tool, process the result,
+and continue without sending that result through another model inference.
+Anthropic reported an 85% token reduction for Tool Search in a large catalog,
+along with accuracy gains on its MCP evaluations.
+
+Agentic Mermaid's `describe_sdk` follows the same progressive-disclosure
+principle but uses a family key instead of general search. Its execution model
+is intentionally smaller: no filesystem, no persistence, no arbitrary tool
+catalog, and no asynchronous callback loop.
+
+Sources: [Code execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp)
+and [advanced tool use](https://www.anthropic.com/engineering/advanced-tool-use).
+
+## Costs and limits
+
+Progressive discovery moves schema tokens out of the initial prompt, but an
+unfamiliar edit now needs a `describe_sdk` call before `mutate`, `build`, or
+`execute`. That extra round trip is wasted on a small catalog whose definitions
+are used in every session. It pays off here because most diagram tasks use one
+registered family, and the old declarations devoted 93.1% of the hosted tool-list
+tokens to the full SDK and repeated mutation menus.
+
+Code execution also adds work that a direct tool does not need. A one-shot
+render, verification, or straightforward operation list should use the hosted
+direct tools. Models, especially smaller ones, can make JavaScript mistakes or
+violate the SDK's provenance and serialization rules; `mutate` and `build`
+exist because those failures were observed in practice.
+
+The local and hosted sandboxes have deliberate constraints:
+
+- Code Mode is synchronous. It rejects `async`/`await`, Promise jobs, dynamic
+  imports, finalizers, and queued microtasks.
+- Sandbox code has no filesystem, external network, environment variables, or
+  persistent workspace.
+- Local `node:vm` is hardened but is not an operating-system or container
+  security boundary. It is a local tool for trusted use.
+- Hosted execution contacts a billable Dynamic Worker on every call. Worker
+  Loader IDs are content-addressed so identical code can reuse a warm isolate,
+  while direct tools and their private compute cache keep routine work off that
+  path.
+- Hosted `execute` responses are never compute-cached: Code Mode exposes time
+  and randomness, so retaining the first result would violate its observable
+  contract.
+- Local timeouts use wall-clock time, while hosted limits use CPU time. Warm
+  hosted isolates can retain module globals, hosted output is capped, and
+  hosted PNG bytes are not part of the cross-runtime byte-determinism contract.
+
+Keeping intermediate results outside model context is useful only when code
+can decide what to discard. If the model must inspect each intermediate result
+to make a semantic judgment, direct calls may be more appropriate. Anthropic
+makes the same distinction for simple lookups and tasks where Claude should see
+all intermediate data.
+
+## Decision
+
+Because Agentic Mermaid's useful unit of work is a verified diagram
+transaction rather than a general agent computer, its Code Mode surface can
+stay narrow. The model receives the core SDK, requests one family schema when
+needed, and returns reviewable Mermaid source only after the same verifier used
+by the library and CLI has accepted it. That verified source is the outcome by
+which the extra sandbox and discovery call should be judged.

package/docs/comparison.md

@@ -0,0 +1,106 @@
+# Mermaid, Beautiful Mermaid, and Agentic Mermaid
+
+Use this page to decide which of the three projects fits your task. The
+table maps what each one can do; the sections after it name what only each
+one does, and the final section tells you which to install for common jobs.
+
+- **[Mermaid](https://github.com/mermaid-js/mermaid)** (`mermaid`) is the
+  original. It defines the grammar that both other projects implement,
+  supports roughly 25 diagram types, and is rendered natively by GitHub,
+  GitLab, Notion, and Obsidian — which is why most diagrams-as-text you will
+  encounter are written in its language.
+- **[Beautiful Mermaid](https://github.com/lukilabs/beautiful-mermaid)**
+  (`beautiful-mermaid`, by Craft) re-implements Mermaid rendering as a
+  synchronous TypeScript library: it computes layout itself and emits SVG
+  strings, so it runs in Node, Bun, or an edge function with no browser and
+  no Puppeteer. Its theming derives a full palette from two colors and
+  accepts Shiki/VS Code themes directly, and it renders to ASCII/Unicode for
+  terminals. It is the foundation this fork is built on.
+- **Agentic Mermaid** (`agentic-mermaid`, this repo) extends Beautiful
+  Mermaid for programs that edit diagrams — AI agents foremost. It adds a
+  typed parse → mutate → verify → serialize loop, byte-identical output
+  across runs, structured verification, and CLI/MCP surfaces. The trade is explicit: the checked registry covers a focused subset of Mermaid's
+  broader catalogue in exchange for the guarantee that parsing and re-serializing
+  a diagram never drops syntax.
+
+Facts below reflect Mermaid 11.16.0 and the upstream `beautiful-mermaid`
+repository as of mid-2026; both projects move quickly, so check their
+changelogs for the current state.
+
+## At a glance
+
+| | Mermaid | Beautiful Mermaid | Agentic Mermaid |
+|---|---|---|---|
+| Primary job | Define and render the diagram language everywhere | Fast, beautiful, browserless rendering | Agent-safe diagram *editing* plus rendering |
+| Runtime | Browser DOM (Node via Puppeteer/`mermaid-cli`) | Pure TypeScript, zero DOM, synchronous | Pure TypeScript, zero DOM, synchronous |
+| Diagram types | Broad Mermaid catalogue, including newer experimental families | Flowchart, state, sequence, class, ER, and XY chart | Registry-backed subset listed by `am capabilities --json` |
+| Output formats | SVG (PNG/PDF via CLI tooling) | SVG, ASCII/Unicode | SVG, PNG (offline resvg), ASCII/Unicode, JSON layout |
+| Theming | Theme config + CSS | Two-color foundation, 15+ named themes, Shiki/VS Code compatibility, live CSS-variable switching | Style + Palette stacks: named looks, palette-only styles, custom JSON records, and deterministic seeds |
+| Parse to a typed AST for editing | — (internal parser, not an editing API) | — (render-only API) | ✅ `parseRegisteredMermaid` → typed `ValidDiagram` |
+| Typed mutation | — | — | ✅ every registered family, structured-or-opaque and never lossy |
+| Structural verification | — | — | ✅ 3 warning tiers + perceptual quality metrics, all families |
+| Deterministic output | Not a goal (browser/layout variance) | Mostly stable, not a tested guarantee | ✅ byte-identical across runs/processes, CI-gated |
+| Round-trip guarantee (parse → serialize keeps your source) | — | — | ✅ verbatim for unmodeled syntax, canonical for structured bodies |
+| CLI | `mermaid-cli` (`mmdc`, Puppeteer-based) | — | `am` (render/verify/mutate/batch/preview/…, single-binary build) |
+| MCP / agent surface | Official hosted MCP (validation, PNG, Mermaid Chart integration) | — | Local Code Mode MCP (`execute`, `describe_sdk`, `render_png`, `describe`) plus hosted `/mcp` (`execute`, progressive schema discovery, render/verify/describe, `mutate`/`build`), `llms.txt`, agent skill |
+| Interactivity (click handlers, animations) | ✅ | Partial (tooltips) | Inherited where upstream has it; not a focus |
+| Ecosystem & docs | Vast — the de-facto standard, GitHub/GitLab/Notion render it natively | Growing, popular for terminal/AI use | Small; this repo |
+
+## What each does that the others don't
+
+**Only Mermaid:** the full diagram-type catalogue (gantt, mindmap, gitgraph,
+sankey, and the 11.x additions like kanban, radar, treemap, venn, wardley,
+treeview, event modeling); native rendering inside GitHub, GitLab, Notion,
+Obsidian, and hundreds of tools; the grammar itself — both other projects
+implement *Mermaid's* language, and compatibility with Mermaid is the
+correctness bar they measure against.
+
+**Only Beautiful Mermaid (vs Mermaid):** synchronous, dependency-light
+rendering with no browser; a deliberate two-color theming foundation with
+enriched palettes and Shiki theme compatibility; ASCII/Unicode terminal
+output. Agentic Mermaid inherits all of this — it is upstream's work, and
+credit belongs there.
+
+**Only Agentic Mermaid:** the typed editing loop. `parseRegisteredMermaid` returns a
+sealed IR; family narrowers (`asFlowchart` … `asXyChart`) expose typed
+mutation ops; `verifyMermaid` returns structured warnings instead of asking
+an agent to eyeball pixels; `serializeMermaid` round-trips losslessly
+(structured-or-opaque: anything the parser doesn't model is preserved
+verbatim, never silently dropped). Plus offline PNG, JSON layout, an `am`
+CLI built for agents (exit codes, JSONL batch, `capabilities --json`
+self-discovery), a local Code Mode MCP server, a bounded hosted MCP endpoint
+for zero-install render/verify/describe and structured edits, and tested
+byte-identical determinism. Neither upstream project needed any of this: both serve humans who write
+diagrams once, while this surface serves programs that edit them repeatedly.
+
+## Mindmap/GitGraph and the terminal ecosystem
+
+The checked fixtures follow the official [Mindmap](https://mermaid.ai/open-source/syntax/mindmap.html) and [GitGraph](https://mermaid.ai/open-source/syntax/gitgraph.html) syntax pages and render from the same authored source in Mermaid 11.16.0 and Agentic Mermaid. See the captioned [Mindmap comparison](./design/families/mindmap.md#visual-evidence) and [GitGraph comparison](./design/families/gitgraph.md#visual-evidence). Compare semantic structure—labels, shapes, hierarchy, lanes, commits, parentage, tags, and bounds—not pixels, because the layout/style engines differ.
+
+[AlexanderGrooff/mermaid-ascii](https://github.com/AlexanderGrooff/mermaid-ascii) 1.4.0 does not currently implement either family. Replaying the documented CLI against the same fixtures exits 1 with:
+
+```text
+unsupported graph type 'mindmap'. Supported types: graph TD, graph TB, graph LR, flowchart TD, flowchart TB, flowchart LR
+unsupported graph type 'gitGraph'. Supported types: graph TD, graph TB, graph LR, flowchart TD, flowchart TB, flowchart LR
+```
+
+Its [diagram coverage issue #74](https://github.com/AlexanderGrooff/mermaid-ascii/issues/74) tracks additional families. This is a capability difference, not a claim that an unsupported render is visually worse.
+
+## Choosing
+
+- Rendering inside a web app, or you need a family absent from `am capabilities --json` → **Mermaid**.
+- Fast, beautiful SVG/ASCII rendering of the core families in
+  Node/Bun/terminal, render-only → **Beautiful Mermaid**.
+- An AI agent (or any program) needs to *edit* diagrams safely, verify them
+  structurally, or guarantee reproducible output in CI → **Agentic Mermaid**.
+
+## Compatibility notes
+
+Agentic Mermaid aims to parse what Mermaid parses for its supported
+families and to reject what Mermaid rejects (e.g. ER cardinality tokens
+match Mermaid's lexer exactly). Where this fork's renderer accepts a
+construct it cannot model for editing, the diagram still parses, renders,
+verifies, and round-trips — it just doesn't expose typed mutation for the
+unmodeled part. Upstream-relevant fixes are extracted into small PRs back to
+`lukilabs/beautiful-mermaid` per the
+[upstreaming strategy](./fork-differences.md#upstreaming-strategy).