Bundle Mermaid so diagrams need no extra install

[chris-colinsky]

Closes #10.

What changes

A .mmd image no longer needs the Mermaid CLI, Node or Chromium. The repo now carries everything needed to build a deck.

• Mermaid is vendored in src/akceo/assets/vendor/mermaid/ (12.0.0). It comes with its license, notices for every package in the bundle, and a manifest with the version, npm integrity hash and SHA-256. A test checks the file against that SHA-256.
• Diagrams are checked at build time. mermaid.py runs Mermaid's own parse() in V8 through mini-racer, a new runtime dependency. V8 runs in a child process (python -m akceo.mermaid), because mini-racer can't interrupt async JavaScript: the child is killed if a diagram takes over 10 s, on Ctrl-C, and when the build ends, so a runaway parse can't hang the build. A syntax error stops the build and names the line in the .mmd file. That line is right even after %% comments, %%{init}%% lines and front matter, which Mermaid strips before parsing. YAML errors in front matter or @{…} shape data get their file line too, and a diagram over Mermaid's 50,000-character limit stops the build rather than drawing Mermaid's "too large" notice.
• The page can't reach outside itself. Every built page now carries a Content-Security-Policy (default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data:; font-src data:), so the browser refuses any outside load, whatever the syntax. Mermaid fetches label images while it draws, so nothing done to the SVG afterwards could stop that load.
• Diagrams that reach outside stop the build with a clear message. The build scans the whole source for links (click, link, links, $link, <a href>), images (img:, src, every srcset candidate, and similar) and CSS (url(), @import, including themeCSS in front matter or %%{init}%%) and names the line. Only # anchors and data: URIs pass. The page also drops any outside link from the drawn SVG.
• Diagrams are drawn in the page as inline SVG, sized from their viewBox so they fit the frame the same way an <img> does. Unframed diagrams use the theme's colors; framed ones keep Mermaid's defaults. Inline SVG leaves room for interactive diagrams later.
• akceo check deck.md runs every check a build runs and writes nothing.

Costs

• A deck with at least one diagram grows by about 5.6 MB. Decks without diagrams are unchanged.
• mini-racer is about 61 MB installed (a 15–22 MB download).
• A few errors only show when drawing, such as an invalid gantt date. The slide shows Mermaid's message instead of the diagram, and the other diagrams still draw.
• Because of the CSP, a web font or @import in a custom theme no longer loads, even online. None of the built-in themes use one. The docs now suggest installed fonts or a data: @font-face.

Licensing

The bundle includes code under MIT, ISC, BSD-3-Clause, Apache-2.0, MPL-2.0/Apache-2.0 (DOMPurify), Unlicense and EPL-2.0 (elkjs).

• pyproject.toml now has a combined license expression.
• The wheel includes the vendored LICENSE and THIRD_PARTY_NOTICES.
• The notices come from the pnpm-lock.yaml at Mermaid's release tag, so every version matches the bundle. They include langium, which @mermaid-js/parser compiles into its output.
• Every built deck with a diagram carries the full notices in a comment, including where to get the elkjs source.

Updating Mermaid

scripts/update_mermaid.py VERSION rewrites the vendor folder. It checks every download against npm's or the lockfile's integrity hash and needs nothing but Python. It follows optional dependencies too, and writes nothing until every step succeeds. It stops if Mermaid's parser package gains a devDependency it hasn't seen, if the walk misses a package the bundle certainly holds, or if a package has no license file. See the README in the vendor folder.

Testing

• uv run pytest: 168 passed. The Mermaid tests run the real parser, not a mock.
• ruff, ruff format --check, pyright and every pre-commit hook pass.
• Built wheel installed in a clean environment: akceo build and akceo check work on the demo.
• Headless Chrome, all as expected:
  • framed and unframed colors;
  • a tall diagram scaled to fit;
  • the error box for a bad gantt date;
  • diagrams on hidden slides draw at the same size as visible ones;
  • with the build check skipped, outside links and image sources are stripped and # links kept;
  • a failed diagram reads as plain text, without the image role;
  • under the CSP, the demo draws with no violations, and outside images from themeCSS, style= and <img> are refused while the diagram still draws;
  • a failing diagram before two good ones: both good ones draw, and no Mermaid error graphic is left in the page.
• Ctrl-C during a build exits in about 0.2 s with no child process left.
• Breaking each new guard in turn (the CSP, the url() scan, the URL stand-in, the outside-reference scan) turns the tests red.

[Copilot]

Copilot review overview

🟡 Changes recommended

Runtime SVG URLs can violate self-contained output, and additional diagnostics, accessibility, and license-inventory issues remain.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 4

Open (4)

• License notices use dependency versions unlike the bundled build · New
• Rendered SVG can bypass self-contained output checks · New
• Failed diagrams retain stale accessible role and label · New
• Unknown-type diagnostics ignore parsed source-line mapping · New

What changed in this PR

Bundles Mermaid for self-contained diagram validation and browser rendering without Node or Chromium.

Changes:

• Adds V8-based Mermaid syntax checking and browser SVG rendering.
• Adds akceo check, dependency/package updates, and vendoring tooling.
• Updates tests, documentation, examples, and licensing metadata.

File	Description
.gitattributes	Marks Mermaid assets as vendored.
.pre-commit-config.yaml	Excludes vendored assets from hooks.
CHANGELOG.md	Records Mermaid and check-command changes.
CLAUDE.md	Updates repository guidance.
README.md	Documents bundled diagrams and checking.
docs/​how-it-works.md	Describes the revised pipeline.
docs/​syntax.md	Documents Mermaid behavior.
examples/​demo/​deck.md	Uses the Mermaid example.
examples/​demo/​flow.mmd	Adds the example diagram source.
examples/​demo/​speaker-notes.md	Updates demo narration.
pyproject.toml	Adds dependency and license metadata.
scripts/​update_mermaid.py	Adds Mermaid vendoring automation.
src/​akceo/​assets/​base.css	Styles rendered diagrams and errors.
src/​akceo/​assets/​diagrams.js	Renders Mermaid SVGs in-browser.
src/​akceo/​assets/​mermaid-shims.js	Provides build-time V8 shims.
src/​akceo/​assets/​page.html	Adds diagram-script placeholder.
src/​akceo/​assets/​vendor/​mermaid/​LICENSE	Includes Mermaid’s license.
src/​akceo/​assets/​vendor/​mermaid/​README.md	Documents vendored assets.
src/​akceo/​assets/​vendor/​mermaid/​THIRD_PARTY_NOTICES	Includes dependency notices.
src/​akceo/​assets/​vendor/​mermaid/​manifest.json	Records source and checksum metadata.
src/​akceo/​assets/​vendor/​mermaid/​mermaid.min.js	Vendors the Mermaid browser bundle.
src/​akceo/​cli.py	Adds the check command.
src/​akceo/​images.py	Removes external Mermaid CLI rendering.
src/​akceo/​mermaid.py	Adds parsing, diagnostics, and embedding.
src/​akceo/​render.py	Integrates diagram checking and output.
tests/​test_cli.py	Tests CLI and self-contained output.
tests/​test_images.py	Removes obsolete Mermaid CLI tests.
tests/​test_mermaid.py	Tests the new Mermaid integration.
tests/​test_render.py	Tests diagram markup rendering.
uv.lock	Locks the mini-racer dependency.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

The external-reference scanner rejects valid label text and misses later URLs in multi-candidate srcset attributes.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1

Open (1)

• Validate every srcset candidate, including after commas · New

Resolved since last review (4)

• Unknown-type diagnostics ignore parsed source-line mapping
• Failed diagrams retain stale accessible role and label
• Rendered SVG can bypass self-contained output checks
• License notices use dependency versions unlike the bundled build