# Mermaid, pseudocode, text trees, and diff

Status: connected to `describe`/`render` and the MCP tools `describe_display`/`render_display`. These four forms are **built-in capabilities** and do not accept external expression libraries, components, or custom Adapters. HTML retains its extension mechanism.

## Discovery and calls

Call `describe_display({ "form": "tree" })` for the form's complete schema and examples, then call `render_display` with `{ "form": "tree", "content": ... }`. The other form names are `mermaid`, `pseudocode`, and `diff`.

Discovery is optional when the contract is already known. Native content accepts no `element`, `props`, or layout coordinates. The tool repairs within its supported scope rather than asking the agent to adjust layout manually.

## Text trees

```json
{"form":"tree","content":{"roots":[{"label":"src","children":[{"label":"commands"},{"label":"rendering"}]}]}}
```

- Preserve parent/child relationships and sibling order, using `├─`, `└─`, and `│` for hierarchy.
- Prefer word boundaries when wrapping long labels, falling back to Unicode grapheme boundaries. Do not split emoji sequences or combining characters, or discard original spaces.
- `↪` marks continuation of the same label, not a new child node. Checks cover actual output width, structural prefixes, and reconstruction of the original text from the line map.
- At most 300 nodes, 16 levels, and 2048 characters per label. If the width cannot accommodate hierarchy prefixes, fail explicitly instead of compressing semantics.

## Pseudocode

```json
{"form":"pseudocode","content":{"statements":[{"kind":"if","condition":"content changed","then":[{"kind":"step","text":"save content"}],"else":[{"kind":"step","text":"return cache"}]}]}}
```

- Built-in constructs are `step`, `if` with then/optional else, and `while` with body. This is explicit structured pseudocode, not a parser for arbitrary programming languages.
- The tool generates indentation, `else`, `end if`, and `end while`. A condition or step's continuation uses `↪` and does not become a new statement.
- Preserve conditions, branch ownership, and order. Limits are 200 statements, 12 nested levels, and 2048 characters per text segment.

## diff

```json
{"form":"diff","content":{"filename":"save.txt","before":"save content\n","after":"check cache\nsave content\n"}}
```

- Inputs are the original before/after strings. The optional filename is a patch label only; no file at that path is read or modified.
- Generate a standard unified patch, apply it to before in memory, and require the exact after string, including CRLF and final-newline behavior.
- `.diff` is the applicable patch; its bytes do not change for layout. `.display.txt` is a wrappable view explicitly marked **not an applicable patch** and must not be applied as one.
- The view retains addition/deletion markers and hunk context. Continuations use `↪`; tabs and CR are visualized as `⇥` and `␍`. Tool-generated equals-sign separators are omitted from the view but retained in the original patch.
- Each side supports at most 1000 lines and 100000 characters. Patch verification does not modify actual project files.

## Mermaid

```json
{"form":"mermaid","content":{"nodes":[{"id":"a","label":"Request"},{"id":"b","label":"Allowed?","shape":"decision"}],"edges":[{"from":"a","to":"b","label":"check","kind":"flow"}]}}
```

- The built-in scope is **flowchart**, including ordinary/decision nodes, branches, and flow/dependency/association/feedback relations, with at most 30 nodes and 60 relations. Other grammars such as sequenceDiagram and arbitrary raw Mermaid source are not currently accepted as input.
- Generate Mermaid source and render it with pinned Mermaid and local Chromium. Inspect actual SVG labels, relation endpoints/types, node and label overlap, occlusion near arrowheads, paths through unrelated nodes, and canvas dimensions.
- Repair may adjust spacing, label wrapping, and renderer-owned layout direction. An explicitly supplied `direction: "LR" | "TD"` is preserved. When omitted, the tool may choose between LR and TD without changing relation identity or direction.
- A visible `[feedback]` marker distinguishes feedback from ordinary dependencies while retaining the original label. Titles are included in source metadata and the SVG title.
- The delivered `.svg` is the verified display artifact; `.mmd` contains its source. Each has its own hash. There is no silent PNG or HTML fallback.
- Serialized SVG is checked for standalone XML validity and reopened for inspection. Path crossing checks use finite sampling, and arrowhead checks use conservative regions; this is not a mathematical proof for arbitrary curves.

## Environments, budgets, and results

- Text trees, pseudocode, and diff need no Chromium. They use Unicode display-width calculations and grapheme segmentation. The default is 120 columns; the Host can set `terminalColumns` to 24–240, or use `SHOW_ME_TERMINAL_COLUMNS` for MCP.
- MCP cannot infer the user's actual window width from stdio. Evidence covers the declared width only. A future Pi plugin can supply measured dimensions; current checks do not establish acceptance in every terminal.
- Mermaid requires local Chromium. If `SHOW_ME_CHROMIUM_BIN` is explicitly set but unavailable, report an environment failure rather than silently choosing another browser. Actual version and viewport are recorded in evidence.
- `maxRepairs` defaults to 3, with an allowed range of 0–8. Text usually needs one wrapping repair; Mermaid performs bounded reflow from geometry feedback. Exhausted budgets or unresolved size constraints produce `not-ready`, not content deletion or a form change.
- Input depth, size, and output line counts are bounded. Control characters are not accepted as ordinary text; diff retains tabs, CR, and LF in the original patch.
- `ready` means the relevant checks passed in the declared environment. A different client's relayout of Mermaid source does not inherit the SVG's acceptance result.

## MCP delivery

Text artifacts are saved as `.txt`; shorter content is also returned in safe fenced text. Diff additionally delivers the original `.diff`; Mermaid delivers SVG and MMD. Large text is kept in full in files rather than truncated and presented as complete.

All forms use the same `ready`/`not-ready` result contract, recording repair attempts, remaining defects, environment, and artifact hashes. HTML may still use user expression libraries; these four forms have empty `libraries` evidence.

## Validation and demonstration

```bash
npm test
npm run render:native-demo
```

Examples are written to `artifacts/native-*`. Regressions cover Unicode wrapping, branches and loops, patch application, special characters and all four relation kinds, oversized Mermaid repair, and text MCP operation without a browser. Generated artifacts are excluded from Git.