agentic-mermaid 0.1.1 → 0.2.0

package/docs/testing-strategy.md

@@ -10,6 +10,27 @@ For the *definition* of "good looking" and the determinism guarantees, see
 [`quality.md`](./quality.md). For mutation specifics, see
 [`mutation-testing.md`](./mutation-testing.md). For the layout/visual
 contracts, see [`layout-characterization/README.md`](./layout-characterization/README.md).
+The current measured complexity-aware and registry-derived interaction
+portfolio is specified in
+[`project/complexity-aware-test-portfolio-plan.md`](./project/complexity-aware-test-portfolio-plan.md);
+its immutable before and content-addressed candidate reports live under
+`eval/test-portfolio/`.
+
+## Local CI parity
+
+Run `bun run quality:check` to execute the complete GitHub **Quality gates**
+job locally. The command installs the frozen dependency graph and then runs
+the dependency audit, font and website regeneration checks, evidence
+freshness, sketch and whole-corpus audits, lint, repository-wide typechecking,
+hero freshness, and the golden-drift guard. The workflow calls this same
+entry point, so the local list and CI list cannot diverge.
+
+Run `bun run evidence:check` for the narrower generated-evidence audit. It
+executes every receipt-backed gallery plus palette-performance provenance,
+continues after failures, and reports all stale artifacts together. Evidence
+receipts hash their exact local source/fixture graph and the transitive Bun
+lockfile closure of packages imported by that graph. Unrelated tools that are
+present elsewhere in `bun.lock` do not invalidate visual evidence.
 
 ## The central problem: this is a partly non-testable program
 
@@ -40,7 +61,7 @@ audit-clean").
 | **Derived (golden)** | Output matches a previously-blessed artifact | ASCII goldens, SVG snapshots, contact sheets, screenshot baselines |
 | **Derived (differential)** | Our output agrees with an external reference corpus | mermaid-docs corpus, MermaidSeqBench, upstream-suite bench |
 | **Metamorphic** | Related inputs produce related outputs (no ground truth needed) | round-trip idempotence, cross-process/cross-runtime determinism |
-| **Pseudo / adequacy** | The *tests themselves* are strong enough | Stryker mutation lanes, sabotage suite |
+| **Pseudo / fault sensitivity** | Selected seeded faults make the intended tests fail | incremental Stryker gate, sabotage suite |
 | **Heuristic / perceptual** | Geometry falls inside human-plausible bounds | `measureQuality`/`checkQuality`, ugly-detector, layout rubric, heuristic-tracker |
 | **Human / model** | Subjective quality on the axis nothing else covers | LLM-as-judge (periodic), manual visual review |
 
@@ -60,7 +81,7 @@ citizenship matrix. For an agent-native product the docs, schemas, CLI
 help, and `llms.txt` *are* runtime surface (Loop 14), so they are tested
 like code, not treated as prose.
 
-**Runs:** every PR (`bun test src/__tests__/`).
+**Runs:** every PR (`bun run test`, including the canonical 30-second per-test budget).
 **Does not prove:** that the diagram is *visually* good. `verify.ok` is
 structural only — stated repeatedly because it has burned us (the Auth
 Flow episode, Loop 15).
@@ -78,13 +99,51 @@ independent spec:
   golden never moves silently.
 
 **Runs:** ASCII/SVG goldens per PR. The browser/screenshot e2e suite also runs
-per PR — it is the `e2e` job in `ci.yml` (`needs: test`), which installs
-Chromium and runs `browser.test.ts` (screenshot diff), the CLI/security e2e,
-and the single-binary e2e. The broad contact sheets are not on the per-PR gate.
+per PR — it is the five-lane `e2e` matrix in `ci.yml` (`needs: test`), including
+an installed-tarball consumer run at the advertised Node 22 floor. Its
+browser lane installs Chromium and runs `browser.test.ts` (screenshot diff)
+plus the security contracts and the explicitly enabled theme/style/accessibility
+browser suites. The browser lane builds the gitignored `website/public` tree once
+before those contracts serve it (`browser.test.ts` builds only the separate root
+`editor.html`). Each browser contract file then runs in its own Bun process so its
+Chromium/server hooks cannot overlap and exhaust a constrained hosted runner. The
+package and CI both invoke `e2e/run-browser-contracts.ts`, whose canonical file
+list also fails if any contract executes zero positive tests, while independent
+lanes run the CLI/single-binary, dist-artifact, and tarball-consumer suites.
+Broad contact-sheet rendering is periodic/triggered rather than a per-PR sweep;
+the committed citizenship manifest and pending review state remain cheap
+per-PR contracts. Structured human review is recommended for visual releases
+and remains hash-bound when recorded, but it is advisory rather than a package-publication gate.
 **Does not prove:** that a *changed* golden is an improvement — only that
 change was noticed. Judging the change still needs a human or the
 before/after harness (`eval/layout-compare`).
 
+## 2a. Registry-derived combinatorial conformance
+
+`render-conformance-plan.test.ts` replaces the former exhaustive
+family × Look × Palette docs-example matrix. The new family registry,
+Style registries and mandatory family conformance profiles generate:
+
+- exhaustive pure Look × Palette resolution;
+- pairwise real-render coverage across family, Look, Palette, security,
+  background polarity and six complexity strata;
+- higher-strength Look/Palette/background, family/backend/complexity,
+  palette-sensitive role, external-reference and contact-sheet obligations;
+- a separate SVG/PNG/ASCII/Unicode portfolio with every-family Unicode stress.
+
+An independently implemented tuple enumerator must report zero missing
+obligations. Fake/removed-family, precedence, strict-reference, transparency,
+seed and terminal sabotage probes guard fault sensitivity. A new `DiagramKind`
+cannot compile without its minimal, representative, dense, text-stress,
+family-risk and eval-corpus-outlier conformance material.
+
+**Runs:** executable conformance and the bounded fault probes run per PR. The
+larger citizenship/interaction/outlier contact sheets run when visual inputs
+change, during periodic design review, or before release.
+**Does not prove:** an unrendered three-way family/Look/Palette combination is
+beautiful. The exact retained obligations are published by the candidate
+report rather than implied by the word “exhaustive.”
+
 ## 3. Derived oracles — differential corpora
 
 The strongest defense against our own blind spots is testing against
@@ -94,10 +153,12 @@ sources we did not write:
   documentation; gates parse, verify, and round-trip.
 - **MermaidSeqBench** (132 IBM-curated sequence diagrams) — parse rate,
   structured-vs-opaque split, verify rate, round-trip stability.
-- **upstream-suite bench** (`eval/mermaid-upstream-suite-bench/`, 658
-  imported cases from a *pinned* upstream commit) — with a **ratchet**
-  (`ratchet.json`) that fails the build if coverage drops or per-family
-  local-gap budgets grow.
+- **upstream-suite bench** (`eval/mermaid-upstream-suite-bench/`, 736
+  executable cases / 746 imported blocks from pinned upstream commits) — with
+  a **ratchet** (`ratchet.json`) that fails the build if coverage drops or
+  per-family local-gap budgets grow. Mindmap/GitGraph use their declared
+  `f3dea583…` compatibility revision and account for all 26/69 official spec
+  blocks in a dedicated executable oracle.
 
 These exist because our hand-written fixtures encode what we already knew
 the parser modeled. Upstream examples are "adversarial in exactly the
@@ -125,7 +186,9 @@ must agree." This sidesteps the oracle problem without a human:
   suite).
 - **Determinism** — three separate processes produce byte-identical layout
   JSON; Bun and Node produce byte-identical JSON on the same source; ASCII
-  and PNG output hash-stable across 10+ repeated runs.
+  and PNG output hash-stable across 10+ repeated runs. CI builds the Node bundle
+  before the unit shards so the Bun↔Node contracts cannot silently skip in a
+  clean checkout.
 - **Layout/faithfulness relations** — `property-layout-metamorphic.test.ts`
   formalizes relations that were previously implicit: determinism (same source
   ⇒ identical metrics), node-id **relabeling invariance** (ids carry no
@@ -148,14 +211,15 @@ default seed `20260702`). A red property in CI is therefore a real,
 reproducible counterexample — never a seed lottery. The 2026-07 audit caught
 three suites flaking on rolled seeds (the route-contracts certificate property
 at ~1 CI run in 7, issue #83; the parser Cartesian-product property; both now
-pin the exact seed that exposed their bug, scoped via save/restore so the
-global policy survives them).
+pin the exact seed that exposed their bug through per-assert options, without
+mutating process-global configuration).
 
 - Reproduce a specific roll: `AM_FC_SEED=<int> bun test <file>`.
-- Finder mode (deliberate randomness): `AM_FC_SEED=random bun test src/__tests__/`.
+- Finder mode (deliberate randomness): `AM_FC_SEED=random bun run test`.
 - The policy is itself gated: `fc-seed-policy.test.ts` fails if the preload is
-  unwired; `zzz-fc-seed-policy-epilogue.test.ts` (alphabetically last) fails if
-  any suite wipes the pin instead of restoring it.
+  unwired and source-checks every test file so suite-specific seeds cannot use
+  process-global overrides in another shard; `zzz-fc-seed-policy-epilogue.test.ts`
+  also catches runtime drift within its own process.
 
 Pinning is for *holding* known ground; randomness is for *finding* new
 counterexamples ("an invariant enforced by a random property is a lottery,
@@ -166,37 +230,38 @@ swept across 48/24/12 seeds (scaled by runtime; 1,368 suite-runs total) with
 zero failures — the pin does not freeze a known-bad ticket, and the sweep is
 repeatable from the same knob.
 
-## 5. Pseudo-oracles — is the suite itself strong enough?
+## 5. Pseudo-oracles — do selected seeded faults make the suite fail?
 
-Tests can be green and still worthless. Two gates test the tests:
+Tests can be green while missing faults. Two bounded gates challenge selected
+behaviors:
 
-- **Mutation testing (Stryker)** — scoped to the high-value ASCII/route
-  core, ~20 named lanes (`stryker.*.config.json`). A *survived* mutant is a
-  test gap until classified. Documented baseline kill rates are 38–75%,
-  with a written survivor catalog and explicit "accepted" classifications
-  (performance guards, unreachable-by-convention). Mutation testing has
-  earned its keep: it falsified an audit assumption and found dead code the
-  unit tests couldn't.
+- **Incremental mutation testing (Stryker)** — mutates the small, pure
+  faithfulness counter on every PR. A full run takes about one minute and its
+  measured floor is enforced. Broader ASCII, route, and family configs remain
+  available as opt-in survivor harvests, not scheduled gates. A *survived*
+  mutant is a test gap until classified; the historical catalogs record
+  reviewed performance guards and unreachable-by-convention cases. Mutation
+  testing has earned its keep when focused: it falsified an audit assumption
+  and found dead code the unit tests couldn't.
 - **Sabotage suite** (`eval/sabotage/route-regressions.ts`) — deliberately
   reverts a fixed bug in a detached worktree and asserts the suite goes
-  **red**, proving the regression test actually bites.
-
-**Runs:** the broad route lanes are **scheduled nightly**
-(`nightly-route-mutation.yml`: routes, route-certificates, subgraph-routing,
-sabotage-routes — the ascii lane is manual-only), but every scheduled run since
-2026-06-19 has been cancelled at the 90-minute cap before producing a score
-(the unsharded routes lane alone exceeds it; PR #63 carries the sharding fix) —
-until that lands, regenerate scores locally. A narrow module takes 5–15 minutes
-locally; the full routes lane substantially longer. A **fast
-incremental lane** (`stryker.incremental.config.json`, the `mutation-incremental`
-CI job) mutates only the small pure faithfulness counter
-(`src/agent/structural-count.ts`) with a sub-second unit runner, so it gates
-**per-PR** (~1 min, measured 96% kill / break-threshold 90).
-**Why this matters:** line coverage is reported per-PR but is a weak
+  **red**, proving five named route/link regression tests actually bite.
+
+The broad scheduled mutation matrix was retired after 26 consecutive scheduled
+runs produced no success and its final repair grew to 39 coverage workers (41
+jobs total). The configs still
+emit useful local scores and JSON reports, but have no break floors and carry no
+acceptance authority. `docs/mutation-testing.md` records the commands, survivor
+history, retained operational evidence, and re-enrollment criteria.
+
+**Why this matters:** line coverage is reported per-PR as one merged LCOV
+artifact assembled from the three unit shards, but it is a weak
 adequacy signal — coverage is not strongly correlated with fault detection
 once suite size is controlled (Inozemtseva & Holmes, ICSE 2014), whereas
 mutant detection *is* correlated with real-fault detection (Just et al.,
-FSE 2014). The mutation score is the truer number; today it comes from local runs (the nightly lane times out — see above).
+FSE 2014). That supports focused mutation as one useful instrument, not mutation
+score as a universal truth. Behavioral, property, differential, sabotage,
+coverage, and mutation evidence answer different questions.
 
 ## 6. Heuristic / perceptual oracles — geometry inside human bounds
 
@@ -204,8 +269,8 @@ This is where we approximate aesthetics deterministically:
 
 - **`measureQuality` / `checkQuality`** — edge crossings, label
   legibility, whitespace balance, label-edge proximity, aspect ratio,
-  gated by `QualityBounds`. Cheap and deterministic; covers all twelve
-  renderable families via `RenderedLayout` adapters.
+  gated by `QualityBounds`. Cheap and deterministic; covers every registered
+  renderable family via `RenderedLayout` adapters.
 - **ugly-detector** (`eval/ugly-detector/`) — geometric defect detection:
   diagonal segments, floating endpoints, edges through nodes, hitches.
 - **layout rubric / visual-rubric** — hard violations (must be 0) plus soft
@@ -262,17 +327,51 @@ real judge run can.
 `ci.yml` is the source of truth for what gates each PR — read it rather than a
 table here, which would drift. In broad strokes:
 
-- **Per-PR (`ci.yml`):** the unit/property suite (`bun test src/__tests__/`) —
+- **Per-PR (`ci.yml`):** the three-shard unit/property suite (`bun run test`) —
   Tier-1 verify, goldens, the differential + faithfulness + metamorphic gates,
-  `measureQuality`/ugly-detector/layout-rubric, the heuristic-tracker ratchet,
-  the corpus/seqbench/upstream benches — plus type check, the hero check, the
-  golden-drift gate, the browser/CLI/binary e2e job, and the fast incremental
-  mutation lane.
-- **Nightly (`nightly-route-mutation.yml`):** the broad Stryker route lanes
-  and the sabotage suite (scheduled; currently cancelled at the timeout every
-  run — see §5).
-- **Manual / periodic:** `layout-compare` before/after, the benchmark vs
-  competitors, and the real LLM-as-judge run.
+  `measureQuality`/whole-corpus ugly-detector/layout-rubric, the heuristic-tracker ratchet,
+  the corpus/seqbench/upstream benches — plus the high/critical dependency audit,
+  type check, the hero check, the
+  golden-drift gate, the parallel browser/CLI/binary/fuzz e2e matrix, the fast
+  incremental mutation lane, and the independent focused sabotage lane. A final
+  `CI complete` job waits for the required test aggregate, every E2E matrix job,
+  and mutation, providing one protectable result that cannot turn green early.
+- **Manual / periodic:** opt-in broad Stryker survivor harvests,
+  `layout-compare` before/after, the benchmark vs competitors, and the real
+  LLM-as-judge run.
+
+## Boundary-contract matrix — lessons applied from the 2026-07 agent audit
+
+The PR #162 audit exposed a blind spot that family/layout coverage did not
+address: a contract could be correct in one helper and false at another public
+boundary. The review of
+[`adewale/testing-best-practices`](https://github.com/adewale/testing-best-practices)
+led to four concrete changes in how this suite treats those seams:
+
+| Risk boundary | Previous false confidence | Required evidence now |
+|---|---|---|
+| JSON-RPC wire lexemes | hosted integer example only | one shared exact-id codec; property tests over unsafe integer, decimal, exponent, batch, nested-id, sentinel-collision, and malformed-text cases; real local HTTP and installed stdio-bin checks |
+| CLI bootstrap/package | formatter helper unit test | walking-skeleton E2E against the real `am` and MCP source entrypoints in a copied checkout with Bun auto-install explicitly disabled |
+| cache before dispatch | normalized-key examples | non-idempotent `execute` is uncacheable; remaining keys retain the complete raw argument object so a warm valid request cannot mask an invalid one; warm-cache regression tests inject the collision |
+| docs/catalog claims | selected-subset presence checks | ordered exact equality against runtime registries, uniqueness, and existence of every catalog target; public `llms.txt` is checked after generation |
+| sequence semantics | global message count | one shared branch-aware message-context model feeds describe, facts, verify/layout and typed edits; unsupported nested semantics must emit a warning |
+| sockets/proxies/chunks | helper could return early | socket tests fail when bind/startup fails, proxy-origin SSE is read from the real stream, and split UTF-8 chunks are exercised at the byte boundary |
+
+These follow the research's trust-boundary lens, walking-skeleton smoke tests,
+property-based parser contracts, exact doc-sync, fault injection, and
+correctness-by-construction guidance. Shared validators/codecs/context models
+replace repeated per-layer checks; tests remain at the untyped HTTP/stdio/CLI
+boundaries where TypeScript cannot enforce the wire contract.
+
+The dated provenance and prevention analysis, including the reviews of PRs
+#157 and #160, is recorded in
+[`project/agent-interface-contract-audit-2026-07.md`](./project/agent-interface-contract-audit-2026-07.md).
+
+The validation rule for future cross-surface changes is: enumerate every
+public consumer first, then require at least one non-vacuous proof at the
+lowest honest tier and one shipped-boundary proof where packaging, transport,
+or generation can change the result. A test that silently returns because its
+environment is unavailable is not evidence for a CI-required capability.
 
 ## Why the suite is shaped this way
 
@@ -300,23 +399,32 @@ gates rather than adding new machinery:
    admittedly rough. The CI LLM mock's readability/aesthetics axes remain
    metric-derived (only its faithfulness axis is now independent), so it
    cannot validate those metrics — only a real periodic judge run can.
-2. The *broad* mutation lanes and sabotage are scheduled nightly but the
-   schedule has never completed a run (timeout — see §5); a fast incremental
-   lane gates the faithfulness counter per-PR, so most core modules' adequacy
-   is currently measured only by local runs. Line coverage is no
-   longer the per-PR headline (it is framed as a finder).
+2. Automatic mutation assurance is deliberately narrow: PR feedback uses the
+   fast incremental faithfulness-counter lane plus five focused sabotage probes.
+   Broad mutation configs are manual diagnostics because the retired scheduled
+   matrix did not justify its runner and maintenance cost. Line coverage is
+   framed as a finder, not a headline score.
 3. The benchmark is not on the PR gate (timing variance). Browser/screenshot
    e2e and the heuristic-tracker ratchet now are.
 4. Determinism is proven Bun↔Node on one architecture; cross-architecture
    byte equality is not asserted.
 5. `QualityBounds` thresholds are now provenance-tagged, but the `chosen`
    bands are still not validated against human-perception evidence.
-6. The snapshot drift sentinel warns but does not block.
+6. Golden movement still needs human judgment, but the snapshot drift sentinel
+   blocks unless the change is committed with the explicit `[approve-goldens]`
+   review token; the token proves acknowledgment, not visual quality.
 
 The deepest gap is structural, and `project/lessons-learned.md` (Loop 13)
 names it: every quality signal here is self-generated. The portfolio above
 produces breadth and internal consistency; it cannot substitute for a real
-external consumer.
+external consumer. One boundary is now an exception: the MCP transport is
+exercised by the reference `@modelcontextprotocol/sdk` client
+(`src/__tests__/mcp-client-interop.test.ts`, per
+`project/mcp-client-interop-verification-plan.md`) — a consumer we did not
+write — over a real socket (hosted) and a real subprocess (stdio). That
+closes the self-generated loop for the one boundary where a canonical
+external consumer exists off the shelf; every other signal above remains
+self-generated.
 
 ## References
 

package/docs/theming.md

@@ -1,9 +1,9 @@
-# Theming
+# Palettes and theming
 
 Agentic Mermaid themes start from a two-color contract (`bg`, `fg`) and can be enriched with optional semantic slots. This keeps diagrams usable in live editors, documentation pages, and agent-generated artifacts without requiring a large design-token object.
 
-> **Themes are styles.** Every built-in theme also registers as a
-> palette-only *style*, so its name works anywhere a style is accepted and
+> **Palette is the registry kind.** Every built-in theme registers as a
+> palette-only *style*, so its stable input name works anywhere a style is accepted and
 > composes with full looks by stacking: `{ style: ['hand-drawn', 'dracula'] }`
 > renders hand-drawn geometry with the Dracula palette. See
 > [docs/style-authoring.md](./style-authoring.md) for the full model.
@@ -64,36 +64,16 @@ const svg = renderMermaidSVG(source, {
 
 Because the generated SVG references variables directly, host pages can switch light/dark themes without re-rendering the diagram.
 
-## Built-in themes
-
-Agentic Mermaid ships **21 built-in themes**:
-
-- `paper`
-- `dusk`
-- `zinc-light`
-- `zinc-dark`
-- `tokyo-night`
-- `tokyo-night-storm`
-- `tokyo-night-light`
-- `catppuccin-mocha`
-- `catppuccin-latte`
-- `nord`
-- `nord-light`
-- `dracula`
-- `github-light`
-- `github-dark`
-- `solarized-light`
-- `solarized-dark`
-- `one-dark`
-- `salmon`
-- `salmon-dark`
-- `tufte`
-- `tufte-dark`
+## Built-in Palettes
+
+`theme` is not a registry kind; discovery returns `kind: "palette"`.
+Discover current Palette identities and stable input names with
+`knownStyleDescriptors()` or `am styles`; this guide does not copy the registry.
 
 ```ts
-import { THEMES, renderMermaidSVG } from 'agentic-mermaid'
+import { renderMermaidSVG } from 'agentic-mermaid'
 
-const svg = renderMermaidSVG(source, THEMES['tokyo-night'])
+const svg = renderMermaidSVG(source, { style: 'tokyo-night' })
 ```
 
 ## Custom themes
@@ -122,7 +102,7 @@ renderMermaidSVG(source, myTheme)
 
 Turn a Shiki or VS Code theme into a diagram palette:
 
-```ts
+```ts no-run
 import { fromShikiTheme, renderMermaidSVG } from 'agentic-mermaid'
 import githubDark from 'shiki/themes/github-dark.mjs'
 
@@ -147,7 +127,11 @@ For per-element emphasis, keep using Mermaid-native directives such as `classDef
 
 ## Security and fonts
 
-Default SVG output includes a Google Fonts `@import` for convenience. For offline, strict, or agent-generated artifacts, use either:
+Default SVG output can include Google Fonts `@import` rules. The selected font
+gets one only when it is a single plain family name; class and ER diagrams can
+also import JetBrains Mono for monospace labels. CSS-variable references and
+font stacks do not produce an import for the selected family. For offline,
+strict, or agent-generated artifacts, use either:
 
 ```ts
 renderMermaidSVG(source, { embedFontImport: false })
@@ -160,3 +144,6 @@ renderMermaidSVG(source, { security: 'strict' })
 ```
 
 `security: 'strict'` disables external-fetch references and is the recommended default for untrusted diagrams.
+
+For custom Style font selection, browser faces, PNG `fontDirs`, fallbacks, and
+output-surface differences, see [Fonts in custom styles](./custom-fonts.md).

package/examples/styles/catalog.json

@@ -0,0 +1,54 @@
+{
+  "version": 1,
+  "sample": "cupertino-prototype.mmd",
+  "examples": [
+    {
+      "id": "cupertino-prototype",
+      "style": "cupertino-prototype.style.json",
+      "screenshot": "cupertino-prototype.png",
+      "alt": "Documentation-only Cupertino-inspired public StyleSpec prototype",
+      "summary": "uses public role geometry, elevation, and inspect-only constraints to demonstrate concentric corner curves and rounded connector bends; it is not an Apple product, an endorsed implementation, or a built-in Agentic Mermaid Style.",
+      "docsOnly": true,
+      "renderOptions": { "shadow": true }
+    },
+    {
+      "id": "vercel-inspired-prototype",
+      "style": "vercel-inspired-prototype.style.json",
+      "sample": "vercel-inspired-prototype.mmd",
+      "screenshot": "vercel-inspired-prototype.png",
+      "alt": "Documentation-only Vercel-inspired public StyleSpec prototype",
+      "summary": "uses public role styles, XYChart category bindings, semantic slots, and inspect-only constraints; it is not a Vercel product, an endorsed implementation, or a built-in Agentic Mermaid Style.",
+      "docsOnly": true
+    },
+    {
+      "id": "cloudflare-workers-inspired-prototype",
+      "style": "cloudflare-workers-inspired-prototype.style.json",
+      "sample": "cloudflare-workers-inspired-prototype.mmd",
+      "screenshot": "cloudflare-workers-inspired-prototype.png",
+      "alt": "Documentation-only Cloudflare Workers-inspired public StyleSpec prototype",
+      "summary": "uses public role styles, Gantt section bindings, visible non-color cues, semantic slots, and inspect-only constraints; it is not a Cloudflare product, an endorsed implementation, or a built-in Agentic Mermaid Style.",
+      "docsOnly": true
+    },
+    {
+      "id": "transit-route-map",
+      "style": "transit-route-map.style.json",
+      "screenshot": "transit-route-map.png",
+      "alt": "Transit route map custom style",
+      "summary": "stresses thick connectors, rounded bends, compact station labels, and group labels."
+    },
+    {
+      "id": "mid-century-report",
+      "style": "mid-century-report.style.json",
+      "screenshot": "mid-century-report.png",
+      "alt": "Mid-century report custom style",
+      "summary": "uses palette, solid fills, typography, corners, and section bands without a custom renderer."
+    },
+    {
+      "id": "star-chart-atlas",
+      "style": "star-chart-atlas.style.json",
+      "screenshot": "star-chart-atlas.png",
+      "alt": "Star chart atlas custom style",
+      "summary": "tests dark-page tokens, grid backdrop, pale strokes, and serif labels."
+    }
+  ]
+}

package/examples/styles/cloudflare-workers-inspired-prototype.mmd

@@ -0,0 +1,9 @@
+gantt
+  title Workers delivery
+  dateFormat YYYY-MM-DD
+  section Edge
+    Route request :done, route, 2026-01-05, 2d
+    Deploy isolate :crit, deploy, after route, 3d
+  section Runtime
+    Execute worker :run, after deploy, 4d
+    Observe release :milestone, observe, after run, 0d

package/examples/styles/cloudflare-workers-inspired-prototype.style.json

@@ -0,0 +1,110 @@
+{
+  "$schema": "https://agentic-mermaid.dev/schemas/style-spec.schema.json",
+  "formatVersion": 1,
+  "name": "look:cloudflare-workers-inspired-prototype",
+  "blurb": "Documentation-only Cloudflare Workers-inspired prototype exercising public role styles, Gantt category bindings, non-color cues, and inspect-only constraints; not built in or endorsed.",
+  "colors": {
+    "bg": "#f5f1eb",
+    "fg": "#521000",
+    "line": "#835446",
+    "accent": "#ff4801",
+    "muted": "#835446",
+    "surface": "#fffbf5",
+    "border": "#ebd5c1"
+  },
+  "font": "Inter",
+  "stroke": "crisp",
+  "strokeWidth": 1.25,
+  "intent": "premium",
+  "roles": {
+    "node": {
+      "fontSize": 13,
+      "fontWeight": 500,
+      "paddingX": 22,
+      "paddingY": 12,
+      "cornerRadius": 8,
+      "lineWidth": 1,
+      "fillColor": "#fffbf5",
+      "borderColor": "#ebd5c1",
+      "textColor": "#521000"
+    },
+    "edge": {
+      "fontSize": 11,
+      "fontWeight": 400,
+      "letterSpacing": 0.1,
+      "lineWidth": 1.25,
+      "bendRadius": 10,
+      "strokeColor": "#835446",
+      "textColor": "#835446"
+    },
+    "group": {
+      "fontFamily": "Share Tech Mono",
+      "fontSize": 11,
+      "fontWeight": 400,
+      "letterSpacing": 0.6,
+      "textTransform": "uppercase",
+      "paddingX": 18,
+      "paddingY": 18,
+      "cornerRadius": 12,
+      "lineWidth": 1,
+      "fillColor": "rgba(255,72,1,0.04)",
+      "headerFillColor": "rgba(255,72,1,0.08)",
+      "borderColor": "#ebd5c1",
+      "textColor": "#835446"
+    },
+    "label": {
+      "fontSize": 11,
+      "fontWeight": 400,
+      "letterSpacing": 0.1,
+      "textColor": "#835446"
+    },
+    "group-header": {
+      "fontFamily": "Share Tech Mono",
+      "fontSize": 11,
+      "fontWeight": 700,
+      "letterSpacing": 0.5,
+      "textTransform": "uppercase",
+      "textColor": "#521000",
+      "fillColor": "rgba(255,72,1,0.08)",
+      "borderColor": "#ebd5c1",
+      "lineWidth": 1
+    },
+    "task": {
+      "fillColor": "#fff0e8",
+      "borderColor": "#c2410c",
+      "lineWidth": 1.5,
+      "cue": "outline"
+    },
+    "milestone": {
+      "fillColor": "#ff4801",
+      "borderColor": "#8a2600",
+      "lineWidth": 2,
+      "cue": "pattern"
+    }
+  },
+  "semanticSlots": {
+    "edge-work": {
+      "fillColor": "#fff0e8",
+      "borderColor": "#c2410c",
+      "strokeColor": "#c2410c",
+      "lineWidth": 1.5,
+      "cue": "outline"
+    },
+    "runtime-work": {
+      "fillColor": "#ff4801",
+      "borderColor": "#8a2600",
+      "strokeColor": "#8a2600",
+      "lineWidth": 2,
+      "cue": "pattern"
+    }
+  },
+  "bindings": [
+    { "channel": "category", "value": "Edge", "slot": "edge-work", "role": "task" },
+    { "channel": "category", "value": "Runtime", "slot": "runtime-work", "role": "task" },
+    { "channel": "category", "value": "Runtime", "slot": "runtime-work", "role": "milestone" }
+  ],
+  "constraints": [
+    { "kind": "contrast", "action": "warn", "minimum": 4.5 },
+    { "kind": "accent-area", "action": "warn", "maxFraction": 0.35 }
+  ]
+}

package/examples/styles/cupertino-prototype.mmd

@@ -0,0 +1,10 @@
+flowchart LR
+  subgraph Core["Routing core"]
+    Intake["Intake"] --> Validate{"Valid?"}
+    Validate -- yes --> Render["Render SVG"]
+    Validate -- no --> Repair["Repair source"]
+    Repair --> Validate
+  end
+  Render --> Export["Export PNG"]
+  Render --> Audit["Contrast audit"]
+  Audit --> Export