# Eve visual language: architecture

## 1. Status

Proposed architecture, prepared by `claude-mac-worker` on 2026-10-11. It implements the PRD [Eve visual language](https://docs.dev.oshunsynthetics.com/workspace?document=18decc67-a857-43a6-b2f2-211dbd313a59), which is in review and not yet approved. Nothing here is built. Requirement numbers VL-01 to VL-15 are the PRD's.

Its measurements are in [Layout and chart renderer comparison: measurements, 2026-10-11](https://docs.dev.oshunsynthetics.com/workspace?document=ca8aa9ad-7861-4108-adc5-b35f5c7a62f0). Statements about today's code come from the research document [Eve — Diagrams and visualizations](https://docs.dev.oshunsynthetics.com/workspace?document=03a53329-e0de-4d56-a600-518676760735), which was read from source and not run.

It sits under the approved [ADR-0083 successor](https://docs.dev.oshunsynthetics.com/workspace?document=a096a047-b6f8-4037-800e-6744517abffd) (revision 4) and changes none of its decisions.

## 2. The shape of it

One library holds everything that is the same on every surface. Each surface adds only a thin wrapper.

```
            model (stored, typed)
                    |
   validate -> lay out -> scene (positions, no pixels)
                    |
     +--------------+---------------+----------------+
     |              |               |                |
  SVG tree      text form      spoken form      glance steps
     |
 React wrapper / static SVG string
```

- **Model:** what is stored. One of the PRD's eight.
- **Scene:** the model after layout: every part with a position and size, every edge with its route. It holds no colours and no markup.
- **Outputs:** four pure functions of the model and scene. The picture, the text form, the spoken form and the glance steps therefore describe the same parts in the same order.

## 3. Decisions

### D1: one library, `libs/oshun/eve-visual`

Plain TypeScript with no React, no DOM and no network. It holds the model schemas and validators, the catalogue, layout, the scene, the SVG tree, the text form and the spoken form. It must run in a browser, in Node and in a web worker.

It is a new library, so it needs `project.json`, `package.json`, `tsconfig.json`, a path in `tsconfig.base.json`, real tests and a clean build and lint.

### D2: models are nodes of the approved UI contract

Each of the eight models is one node kind in the typed UI specification of the ADR-0083 successor, Decision 1, validated on the server and on the client with the same code. `eve-interactive-artifacts` UI.01 owns that contract; this family adds the eight node kinds to it and does not define a second one.

Every model carries: `schemaVersion`, `type` (a catalogue name), `title`, `headline`, the parts with stable identifiers, and an optional `source` (what it was read from, at which commit or revision, and when).

Labels are text. A model can hold no markup, no script and no address other than an Eve identifier.

### D3: how a visual is stored in a document

- **Blocks documents** gain a fourth block type, `visual`, beside `markdown`, `code` and `diagram` (`tools/eve-content/model.mjs`). Its source is the model as JSON.
- **In Markdown** a fenced block with the language `visual` becomes a visual block, by the same rule that turns a `mermaid` fence into a diagram block today. That is how agents write one.
- **Rich-text documents** gain a visual node holding the same JSON. They also gain table and image nodes (VL-03).
- **Presentations:** a slide's `composition` may hold a model in place of its own nodes and edges.
- **Existing `diagram` blocks are not rewritten.** A Mermaid block is converted to a model when it is read, for the kinds the models cover. The reader's existing "Diagram as text" code already extracts nodes and connections for eleven Mermaid kinds and is the starting point. A block that cannot be converted is drawn by Mermaid as today.

### D4: graph layout is ELK, layered, with right-angled routing

Measured on five graphs against dagre and Graphviz:

- ELK never routed an edge through an unrelated node. dagre did in four of five graphs (6, 8, 22 and 116 times). dagre is what Mermaid uses by default, which is the cause of gap G1.
- ELK had the fewest bends in every graph and no diagonal segments.
- ELK had the fewest crossings on the grouped 40-node graph (32, against 46 and 61) and at the size limit. Graphviz had slightly fewer on the two graphs without groups.

Graphviz stays as the engine that draws Graphviz DOT input (D9). dagre is not used.

Two findings shape the rest:

- **Time.** ELK took about 4.1 seconds at the size limit of 200 nodes and 500 edges, on a busy host. So layout never runs on a page's main thread. It runs in a web worker in the browser and on the server when a model is saved or produced, and the scene is kept, keyed by the model's hash, the layout version and the width class.
- **Width.** A 40-node graph came out 2,914 by 397 pixels. No engine fits that in a document column. So a graph above a threshold is shown first as an overview of its groups, and each group opens to its own detail. The direction (left to right, or top to bottom) is chosen from the width available. The threshold and ELK's aspect-ratio options are set by measurement in the first delivery task; this document does not guess them.

elkjs declares its licence as `EPL-2.0 OR GPL-3.0-or-later`. A licence review is required before it is adopted. If the review refuses it, Graphviz's right-angled mode is the measured fallback up to about 60 nodes (two to three times the bends, and 16.9 seconds at the limit).

### D5: the other seven layouts are our own

Sequence, time axis, matrix, tree, spatial canvas, image set and charts have simple, exact geometry. They are laid out by code in `eve-visual`, with no third-party engine, so their output is fully under the quality rules of VL-04. Tree layout may use `d3-hierarchy` if the first delivery task finds it better than our own; it was not measured.

### D6: charts are our own marks on `d3-scale` and `d3-shape`

Measured, drawing one 1,000-point line chart in Node with no DOM:

- Our own marks: 4.2 ms, identical output every run, 0.4 MB installed.
- Vega-Lite: works, 58.1 ms, 9.5 MB. Its grammar would also be a second specification language beside the approved contract.
- ECharts: works, but its output differs from run to run, which breaks hashing and image comparison. 63 MB installed.
- Observable Plot failed without a document, and Recharts through server rendering produced no chart, as tried.

Own marks also give one chart style, token colours and full control of the text form. The cost is that each chart type is written by us: six in tier 1.

### D7: one SVG tree, wrapped per surface

`eve-visual` returns a plain element tree. A surface turns it into what it needs:

| Surface | How it draws |
| --- | --- |
| Workspace reader and editors, reader chat | a React wrapper; replaces the direct Mermaid path for converted blocks |
| Assistant dock in web and admin | the same wrapper, through `libs/oshun/shell-assistant` |
| Desktop app | documents already reuse the web reader; the dock's own prose renderer gains the wrapper |
| Android, Workspace tab | the web view, unchanged |
| Android, Walk screen and notification | glance steps as native text, with a small picture of the current part drawn on the server (D10) |
| Docs Center and built presentations | their Python builders call a Node command, `eve-visual render`, at build time and embed the SVG string and the text form |

Interaction (select a part, pan, zoom, step through) lives in the React wrapper. Static surfaces get the picture and the text form.

### D8: colour from tokens

The SVG tree names roles (surface, line, emphasis, a series number), never colours. On the web a role resolves to a design-token CSS variable, so light and dark follow the page with no inversion filter. For a static export or a slide the tokens are resolved to values, once for light and once for dark. Series colours come from one validated palette with a second channel (shape or dash) so colour is never the only carrier.

### D9: other diagram languages

- **Mermaid:** converted where covered (D3), otherwise drawn by Mermaid. The Workspace and Docs Center move to one Mermaid version and one security level.
- **Graphviz DOT:** drawn by Graphviz compiled to WebAssembly, which ran in Node in the measurements.
- **PlantUML and D2:** each needs its own engine, which was not measured. They are drawn on the server in an isolated worker with no network. Until the task that proves this, they keep today's behaviour and show their source, with a statement that the picture is not available.
- **Uploaded SVG:** made safe on the server (no scripts, no external references, no event attributes) before it is shown in place.

### D10: spoken form and glance steps

`eve-visual` gives, for a model: `headline(model)`, `shape(model)`, and `walk(model)`, which is an ordered list of steps. Each step has the identifier of its part, a sentence, and what to show.

- The sentences come from templates per model, filled from the stored parts. That is the default and needs no model call.
- A language model may rephrase a sentence. The result is accepted only if every part name and every number in it is in the stored model; otherwise the template sentence is used.
- `libs/oshun/eve-voice` uses these for a visual block in place of today's 45-word summary: the headline is read in the flow, and the walk on request. Its command grammar gains "walk me through it", "next", "back", "again", "skip the diagram" and "show me later", all handled on the device.
- A question about the content goes to the existing reader voice route with the model as context.
- An image's description is spoken. Uploaded images keep their alt text; a visual's parts each have a description.
- The glance card shows the current step's sentence and a picture of that part and its immediate neighbours, drawn on the server and kept with the audio for offline use.
- "Show me later" writes a pin through the same outbox that carries spoken notes.

### D11: Eve's tool

The assistant gets one tool, `visual_propose`, that takes a catalogue type and returns a model. The catalogue supplies the tool's description of each type and when to choose it. The BFF validates the model, applies the size limits and lays it out before it is shown. A change to an existing visual is a patch that names parts by identifier. `presentation_propose_slide_edit` stops excluding diagram changes once slides use models.

### D12: derived diagrams

A reader is a function that returns a model and an observation record (ADR Decision 3):

| Reader | Reads | Runs |
| --- | --- | --- |
| Code structure | the Nx project graph | in a checkout, at a named commit |
| Database schema | table and relation metadata | read-only, time-limited, on a copy where heavy |
| Board | tasks and dependencies | through registered, authorized queries (ADR Decision 4) |
| Traces | recorded spans | from the trace store, bounded |

Each part carries the identifier of what it came from. A check compares the stamp with the source's current commit or revision to mark a diagram out of date. No reader takes a board lock or writes.

### D13: creative types

Storyboard and beat sheet are views over the ordered sequence. Shot list is a view over the matrix. Moodboard is a view over the image set. Their images are Eve media, under the existing media authorization. Tier 3 viewers are embedded by a `viewer` reference that names a studio viewer and an asset; the studio app draws it under its own authorization, and Eve shows the asset's description where the viewer is unavailable.

### D14: quality checks that run automatically

The spike's measures become tests on every scene in the corpus:

- no edge through an unrelated node; no overlapping nodes or groups; no node outside its group; every edge ends on its own nodes;
- every label inside its box and at or above the minimum text size;
- contrast of every role pair in light and dark;
- identical output for identical input.

Crossings and bends are reported, with a budget per corpus graph that a change may not worsen. Captured images of the corpus go to an independent reviewer.

## 4. Alternatives considered

- **Keep Mermaid as the source and add renderers beside it.** Rejected by Elikem's ruling 2: it leaves voice walk-through, editing by part and derived diagrams unsolved.
- **Adopt Vega-Lite or another chart grammar.** Rejected in D6: a second specification language, heavier, and slower, for six tier 1 chart types.
- **Adopt a node-graph canvas library for all graphs.** Not measured. Such a library draws and edits but does not lay out; layout would still be ELK. It is a candidate for the editable node graph in tier 3 only.
- **Draw everything on the server as images.** Rejected: no selection, no keyboard reach of parts, no theming with the page.
- **Let the model write SVG.** Rejected by the ADR: no generated markup in the trusted layer.

## 5. Not yet known

- ELK's timing in a browser worker, and its aspect-ratio and wrapping options.
- The overview threshold for large graphs.
- How many existing Mermaid blocks in Eve convert to a model, and how many stay on Mermaid.
- The engines for PlantUML and D2 and their cost.
- Whether `react-native` needs anything beyond text and a server-drawn picture for the glance card.
- The outcome of the elkjs licence review.

Each is answered by a named task in the delivery specification, which follows the PRD's approval.
