mermaid

Mermaid diagram source kept readable for agents

Install

docsloth component add @docsloth/mermaid@1.0.0

Live package: sha256:96b5e8ca9f6f9073fe60f842a095787824b89447f9314189b83d5505133d7a88 with 2 file digest(s); the catalog entry is generated from the built package, not a placeholder.

Props

The prop schema is normative in packages/contracts/component-props/mermaid.schema.json.

Example props generated from this schema:

{
  "code": "graph TD;\n  A[Start]-->B[Ship];"
}

Required props: code.

Example

Example document IR (the block the renderer consumes):

{
  "type": "mermaid",
  "props": {
    "code": "graph TD;\n  A[Start]-->B[Ship];"
  }
}

Renderer HTML (entities decoded and wrapped for display):

<div class="ds-mermaid" data-component="mermaid">
<pre class="mermaid" data-ds-mermaid>graph TD;
  A[Start]-->B[Ship];</pre>
<button type="button" class="ds-mermaid-copy" data-ds-copy data-markdown-ignore="true" aria-label="Copy diagram source">Copy</button>
</div>

Preview (interface-only; the markup above is the same output):

graph TD;
  A[Start]-->B[Ship];

The renderer resolves this component as a native block; the preview above is its real HTML output, and Markdown parity for native blocks is covered by the renderer test suite.

Specification

Generated from packages/contracts/component-specs/mermaid.md.

Contract

Packaged: this block ships as @docsloth/mermaid@1.0.0 — an installable component package (kind block, capability render.html, Apache-2.0) whose production props schema is packages/contracts/component-props/mermaid.schema.json and whose catalog entry is in packages/contracts/component-catalog.json. No protocol manifest fixture is published (manifest_fixture: null): the fixture models a packaged protocol runtime this block does not have.

Intended behavior

Pass diagram source through unchanged so a host-configured Mermaid renderer can draw it, while every reader still sees the source. HTML emits an inert <pre class="mermaid" data-ds-mermaid> whose text is the escaped source, plus a copy control. Markdown always emits the fenced mermaid code block, so agents never lose the diagram.

Failure and fallback

A missing or non-string code prop degrades the block to the labelled fallback. Hostile source is escaped in HTML and never becomes markup; a fenced copy survives verbatim in Markdown because fences are data, not page structure.

Required acceptance cases

No diagram renderer, network call or model call may run from the renderer; until a host renders it, the block must remain readable source. Source containing backticks or HTML must not break out of the fence or the <pre>. Also test empty data, loading, denied access, browser without JS, mobile 360px, keyboard navigation, dark mode and an explicit constrained agent tool call. The server independently authorizes capability requests; a package manifest cannot grant authority.

Data and maintenance

Data bindings resolve from a specific publication/release vector and permitted fact/evidence graph. Configuration edits create versioned component patches. Update invalidation uses dependency IDs, never indiscriminate whole-page regeneration. Human-owned props survive automatic updates unless invalidated with an explicit conflict. Missing optional resources leave an honest inert/readable fallback, not a broken page or fake success.

Cost and tools

Pure/local interaction must never invoke a model by accident. Any model, remote query or executor call must reserve approved budget before dispatch. Public visitors do not inherit owner resources. The component may call only named tools in its signed manifest with valid typed inputs. A cancelled job stops polling and closes resources. No component gets platform administration, raw credentials or an unlimited execution loop.

Native renderer block

packages/renderer renders a mermaid block from the document IR. HTML emits <pre class="mermaid" data-ds-mermaid> containing the escaped source and a copy button (data-ds-copy); the copy button is the only element marked data-markdown-ignore, and it stays in the accessibility tree because it is an interactive control. Markdown emits the fenced mermaid code block (fence length grown to survive backticks in the source) so agents always get the source.

Native block props

Example

{
  "type": "mermaid",
  "props": { "code": "graph TD;\n  A[Start]-->B[Ship];" }
}

Package manifest

No protocol fixture is published for this renderer-native block.

Sources