agentic-mermaid 0.1.1 → 0.2.0

package/README.md

@@ -12,7 +12,7 @@ It is forked from [`lukilabs/beautiful-mermaid`](https://github.com/lukilabs/bea
 
 [Live Demo & Samples](https://agentic-mermaid.dev/) · [Live Editor](https://agentic-mermaid.dev/editor)
 
-Docs: [docs index](./docs/) · [getting started](./docs/getting-started.md) · [agent guide](./Instructions_for_agents.md) · [agent API cookbook](./docs/agent-api-cookbook.md) · [design system](./DESIGN.md) · [skills](./skills/) · [fork differences](./docs/fork-differences.md) · [vs Mermaid & Beautiful Mermaid](./docs/comparison.md) · [changelog](./CHANGELOG.md)
+Docs: [docs index](./docs/) · [getting started](./docs/getting-started.md) · [agent guide](./Instructions_for_agents.md) · [agent API cookbook](./docs/agent-api-cookbook.md) · [design system](https://github.com/adewale/agentic-mermaid/blob/main/DESIGN.md) · [skills](./skills/) · [fork differences](./docs/fork-differences.md) · [vs Mermaid & Beautiful Mermaid](./docs/comparison.md) · [changelog](./CHANGELOG.md)
 
 </div>
 
@@ -25,27 +25,27 @@ Use it when you want to describe a diagram in plain language and get back someth
 | An agent to draft the diagram | Mermaid source plus a verified render path |
 | Beautiful defaults | Built-in looks such as `watercolor`, `blueprint`, `hand-drawn`, and `publication-figure` |
 | Brand fit | Style + Palette stacks and custom JSON palettes you can keep in your repo |
-| Safe edits later | `parseMermaid` → family narrower → `mutate` → `verifyMermaid` → `serializeMermaid` |
+| Safe edits later | `parseRegisteredMermaid` → family narrower → `mutate` → `verifyMermaid` → `serializeMermaid` |
 | Reviewable artifacts | SVG, PNG, ASCII, Unicode, and JSON layout from the same source |
 
 The agent workflow is the guardrail behind the polish: agents should not guess from pixels, concatenate strings, or regenerate whole diagrams when a structured edit is available.
 
 ## Highlights
 
-- **12 diagram families** — flowchart, state, architecture, sequence, class, ER, timeline, journey, XY chart, pie, quadrant, and Gantt.
-- **SVG, PNG, ASCII, Unicode, JSON** — one deterministic layout foundation for docs, decks, terminals, and agent workflows.
+- **Descriptor-registered diagram families** — built-ins and namespaced extensions share one discovery and capability contract.
+- **SVG, PNG, ASCII, Unicode, JSON** — one resolved request with explicit graphical, terminal, and positioned-layout projections.
 - **Synchronous, zero-DOM SVG renderer** — no Puppeteer, no browser flash.
-- **Composable styles** — `{ style: ['hand-drawn', 'dracula'] }` stacks a look over a palette; 15 full looks cover sketch, watercolor, blueprint, accessibility, print, operational, physical-media, architecture, and editorial/report use cases. Custom styles are plain JSON records any agent can author (`docs/style-authoring.md`). `seed` re-rolls the ink, never the layout.
-- **21 built-in themes + Shiki compatibility** — a theme is a palette-only style: theme from two colors or a VS Code theme.
-- **Agent-native editing** — typed mutation for all twelve renderable families (flowchart/state, sequence, timeline, class, ER, journey, architecture, XY chart, pie, quadrant, Gantt); source-level round-trip only for opaque fallbacks (unmodeled syntax).
-- **CLI + MCP + library** — `am`, `agentic-mermaid-mcp`, `agentic-mermaid`, and `agentic-mermaid/agent`.
+- **Composable styles** — `{ style: ['hand-drawn', 'dracula'] }` stacks a look over a palette; discoverable full looks cover sketch, watercolor, blueprint, accessibility, print, operational, physical-media, architecture, and editorial/report use cases. Custom styles are plain JSON records any agent can author (`docs/style-authoring.md`). `seed` re-rolls the ink, never the layout.
+- **Discoverable palettes + Shiki compatibility** — a theme is a palette-only style: discover the canonical catalog at runtime, theme from two colors, or adapt a VS Code theme.
+- **Agent-native editing** — typed mutation for every registered renderable family; source-level round-trip only for opaque fallbacks containing unmodeled syntax.
+- **CLI + MCP + library** — `am`, `agentic-mermaid-mcp`, `agentic-mermaid`, `agentic-mermaid/agent`, and the browser/workerd-safe `agentic-mermaid/agent/core`. Audit reports and trusted host-resource helpers remain repository tooling instead of published runtime entry points.
 
 ## Installation
 
 ```bash
 npm install agentic-mermaid       # or: bun add agentic-mermaid / pnpm add agentic-mermaid
-am --help
-agentic-mermaid-mcp
+npx --no-install agentic-mermaid --help
+npx --no-install agentic-mermaid mcp
 ```
 
 For repository development, install from source and run the Bun entrypoints:
@@ -60,10 +60,12 @@ bun run bin/agentic-mermaid-mcp.ts   # MCP stdio server
 ```
 
 > **ESM-only.** `agentic-mermaid` ships ES modules (there is no CommonJS build);
-> `require()` consumers should use dynamic `import()` instead. Requires Node ≥ 18.
+> `require()` consumers should use dynamic `import()` instead. Requires Node ≥ 22.
 >
-> The `am …` commands shown below assume the published bin. From a source
-> checkout, run them as `bun run bin/am.ts …` instead.
+> The `am …` examples below name the published bin. After a project-local npm
+> install, invoke it from a shell as `npx --no-install agentic-mermaid …` (or
+> from an npm script as `am …`). From a source checkout, use
+> `bun run bin/am.ts …` instead.
 
 ## Output quick starts
 
@@ -136,17 +138,17 @@ For multi-step MCP edits, connect `agentic-mermaid-mcp` and use Code Mode `execu
 
 Agentic Mermaid ships a Model Context Protocol server so MCP-capable agents can render and safely edit diagrams without shelling out.
 
-- **Self-hosted (default).** `agentic-mermaid-mcp` runs a stdio server exposing `execute` (Code Mode sandbox), `render_png`, and `describe`. Package runners can use `npx -y agentic-mermaid mcp`; the `mcp` argument routes the package-name binary to the same stdio server. Add `--transport http` for HTTP/SSE with managed PNG file/URL artifacts. See [`docs/mcp-http-transport.md`](./docs/mcp-http-transport.md) and [`docs/mcp-code-mode-rationale.md`](./docs/mcp-code-mode-rationale.md).
-- **Hosted.** A stateless Streamable HTTP endpoint is available at `https://agentic-mermaid.dev/mcp` (tools: `execute`, `render_svg`, `render_ascii`, `render_png`, `verify`, `describe`, `mutate`, `build`; 64 KB input caps). It is MCP JSON-RPC only, not a REST render API. Hosted `execute` runs the same `mermaid.*` facade in a Cloudflare Dynamic Worker isolate with no network; hosted PNG returns base64 only.
+- **Self-hosted (default).** `agentic-mermaid-mcp` runs a stdio server exposing `execute` (Code Mode sandbox), `describe_sdk` (one family's mutation schema on demand), `render_png`, and `describe`. Package runners can use `npx -y agentic-mermaid mcp`; the `mcp` argument routes the package-name binary to the same stdio server. Add `--transport http` for HTTP/SSE with managed PNG file/URL artifacts. See [`docs/mcp-http-transport.md`](./docs/mcp-http-transport.md) and [`docs/mcp-code-mode-rationale.md`](./docs/mcp-code-mode-rationale.md).
+- **Hosted.** A stateless Streamable HTTP endpoint is available at `https://agentic-mermaid.dev/mcp` (tools: `execute`, `describe_sdk`, `render_svg`, `render_ascii`, `render_png`, `verify`, `describe`, `mutate`, `build`; 64 KB input caps). Call `describe_sdk` for compact signatures or exact fields before authoring unfamiliar ops. It is MCP JSON-RPC only, not a REST render API. Hosted `execute` runs the same `mermaid.*` facade in a Cloudflare Dynamic Worker isolate with no network; hosted PNG returns base64 only.
 
 Local-first is the default posture: prefer the library, CLI, or a self-hosted MCP for anything sensitive, offline, larger than the hosted caps, or needing local PNG file/URL artifacts. The hosted endpoint is a public, unauthenticated convenience for zero-install render/verify/describe and bounded structured edits.
 
 ## Structured edit example
 
 ```ts
-import { parseMermaid, asFlowchart, mutate, verifyMermaid, serializeMermaid } from 'agentic-mermaid/agent'
+import { parseRegisteredMermaid, asFlowchart, mutate, verifyMermaid, serializeMermaid } from 'agentic-mermaid/agent'
 
-const parsed = parseMermaid('flowchart TD\n  API --> DB')
+const parsed = parseRegisteredMermaid('flowchart TD\n  API --> DB')
 if (!parsed.ok) throw new Error('parse failed')
 
 const flow = asFlowchart(parsed.value)
@@ -163,49 +165,40 @@ const source = serializeMermaid(next.value)
 
 Rules:
 
-- Use `asFlowchart` / `asState` / `asSequence` / `asTimeline` / `asClass` / `asEr` / `asJourney` / `asArchitecture` / `asXyChart` / `asPie` / `asQuadrant` / `asGantt` before mutating existing diagrams.
+- Use the matching exported `as<Family>` narrower before mutating an existing structured diagram.
 - Mutation ops use `kind`, not `type`.
 - Run `verifyMermaid` before every commit point.
 - Do not call `mutate` on opaque fallback bodies; the narrower returns `null` for unmodeled syntax.
 
 ## Supported diagram families
 
-| Family | Parse | Verify | Render | Structured mutate |
-|---|---:|---:|---:|---:|
-| Flowchart / state | ✓ | ✓ | SVG/PNG/ASCII | ✓ |
-| Sequence | ✓ | ✓ | SVG/PNG/ASCII | simple messages/participants |
-| Timeline | ✓ | ✓ | SVG/PNG/ASCII | ✓ |
-| Class | ✓ | ✓ | SVG/PNG/ASCII | ✓ |
-| ER | ✓ | ✓ | SVG/PNG/ASCII | ✓ |
-| Journey | ✓ | ✓ | SVG/PNG/ASCII | modeled subset (BUILD-15) |
-| XY chart | ✓ | ✓ | SVG/PNG/ASCII | modeled subset (BUILD-16) |
-| Pie | ✓ | ✓ | SVG/PNG/ASCII | ✓ |
-| Quadrant | ✓ | ✓ | SVG/PNG/ASCII | ✓ |
-| Architecture | ✓ | ✓ | SVG/PNG/ASCII | modeled subset (BUILD-17) |
-| Gantt | ✓ | ✓ | SVG/PNG/ASCII | sections/tasks; calendar directives ride along verbatim |
-
-See [diagram families](./docs/diagram-families.md) for examples and compatibility notes.
+Family support and its executable evidence are projected from the
+`FamilyDescriptor` registry into the generated
+[Section A capability report](https://github.com/adewale/agentic-mermaid/blob/main/docs/project/section-a-capability-report.md).
+See [diagram families](./docs/diagram-families.md) for syntax examples and
+compatibility notes.
 
 ## More documentation
 
-- [System architecture](./docs/design/system/README.md) — **start here** for how the engine works: the rendered three-stacks overview (dogfooded, drift-proof) routing to the design and route-contract docs.
+- [System architecture](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/system/README.md) — **start here** for the rendered resolved-request, family-descriptor, positioned-artifact, and output-security overview (dogfooded, drift-proof).
 - [API reference](./docs/api.md) — renderers, agent API, options, CLI/MCP pointers.
 - [Agent API cookbook](./docs/agent-api-cookbook.md) — practical recipes for agents.
 - [Theming](./docs/theming.md) — two-color themes, built-ins, Shiki compatibility.
 - [Custom style cookbook](./docs/custom-style-cookbook.md) — JSON style files, screenshots, schema usage, and CLI commands.
+- [Fonts in custom styles](./docs/custom-fonts.md) — font selection, SVG declarations, PNG directories, fallbacks, and browser usage.
 - [React integration](./docs/react.md) — zero-flash `useMemo` rendering.
 - [ASCII output](./docs/ascii.md) — terminal output, color modes, XY charts.
 - [Mermaid config](./docs/config.md) — frontmatter, init directives, runtime config.
 - [Features](./docs/features.md), [quality](./docs/quality.md), [security](./SECURITY.md), [fork differences](./docs/fork-differences.md).
-- [Adding diagram types](./docs/contributing/adding-diagram-types.md) for contributors.
+- [Adding diagram types](https://github.com/adewale/agentic-mermaid/blob/main/docs/contributing/adding-diagram-types.md) for contributors.
 
 ## Live editor and examples
 
 - [Examples](https://agentic-mermaid.dev/examples/) — supported families, Style + Palette combinations, and the rich shared examples corpus.
 - [Live editor](https://agentic-mermaid.dev/editor) — SVG/PNG exports and URL sharing.
-- [`examples/agent-loop.ts`](./examples/agent-loop.ts)
-- [`examples/mcp-vs-cli-complex-diagrams.ts`](./examples/mcp-vs-cli-complex-diagrams.ts)
-- [`examples/agent-improve-auth-flow.ts`](./examples/agent-improve-auth-flow.ts)
+- [`examples/agent-loop.ts`](https://github.com/adewale/agentic-mermaid/blob/main/examples/agent-loop.ts)
+- [`examples/mcp-vs-cli-complex-diagrams.ts`](https://github.com/adewale/agentic-mermaid/blob/main/examples/mcp-vs-cli-complex-diagrams.ts)
+- [`examples/agent-improve-auth-flow.ts`](https://github.com/adewale/agentic-mermaid/blob/main/examples/agent-improve-auth-flow.ts)
 
 ## Attribution
 

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,29 @@
+# Third-party notices
+
+## Material Design Icons (curated Architecture icon paths)
+
+A size-bounded subset of SVG path data in `src/architecture/icons.ts` is
+derived from **@iconify-json/mdi 1.2.3**, the Iconify packaging of Material
+Design Icons.
+
+- Source: <https://www.npmjs.com/package/@iconify-json/mdi/v/1.2.3>
+- Upstream project: <https://github.com/Templarian/MaterialDesign>
+- License: **Apache License 2.0**
+- Packaged license copy: [`LICENSES/Apache-2.0.txt`](LICENSES/Apache-2.0.txt)
+- Canonical license URL: <https://www.apache.org/licenses/LICENSE-2.0>
+
+Only curated path data is bundled. Agentic Mermaid does not fetch Iconify packs
+at runtime and does not bundle the full npm package. The published
+`@iconify-json/mdi@1.2.3` tarball contains no upstream `NOTICE` file to
+reproduce.
+
+## Mermaid pinned test specifications
+
+The revision-bound oracle vendors two upstream Mermaid test specifications at
+`eval/mermaid-upstream-suite-bench/upstream-f3dea583/` solely to verify the
+26/69-block provenance inventory offline.
+
+- Source: <https://github.com/mermaid-js/mermaid/tree/f3dea58385fd5c7dd1f4e9c9c1876751ae6943cc>
+- Copyright: © 2014–2022 Knut Sveidqvist
+- License: **MIT**
+- Repository license copy: `eval/mermaid-upstream-suite-bench/upstream-f3dea583/LICENSE.mermaid.txt` (the upstream specs are verification-only and excluded from the npm package)