# The visual language: component reference

This is the trusted v2 vocabulary. Author JSON data, not HTML, JavaScript, CSS, or imports. The bridge validates unknown fields and bounds. Full contract: `lib/conversation.mjs` in the kit.

A conversation opens with `{ "title": "…", "units": […] }`. It can initially contain only one completed thought. Every unit has a stable `id` (1–64 letters, digits, `_`, `-`) and one of the five types below. The server supplies its `version`; do not author that field.

## Prose: establish meaning

```json
{"id":"premise","type":"prose","heading":"No reply is not the same as no effect","text":"The café may have accepted your order even though its confirmation never reached your phone."}
```

Use for a premise, definition or a short responsive explanation. Heading is optional (120 characters); text is required (1600). A sentence is often better than a diagram. Do not break a paragraph into decorative cards or publish an entire essay as one unit.

## Comparison: align a consequential difference

```json
{"id":"contrast","type":"comparison","label":"What each side knows","columns":["Your phone","The café"],"rows":[{"label":"Order","values":["Confirmation missing","Order accepted"]},{"label":"Certainty","values":["Cannot infer the outcome from silence","Can look up the accepted order"]}]}
```

Use for two alternatives, perspectives, or before/after states with corresponding attributes. Label: 120 characters; exactly two column labels (80 each); 1–8 rows with a label (80) and two text values (300 each). Good comparisons align the same property across columns. Unrelated prose in two boxes is not a comparison. Do not imply temporal order or causality merely by putting alternatives next to each other.

## Flow: explain a relationship

```json
{"id":"path","type":"flow","label":"A request can succeed before its reply is lost","nodes":[{"id":"phone","label":"Phone","detail":"Sends order","tone":"sage"},{"id":"cafe","label":"Café","detail":"Accepts order"},{"id":"reply","label":"Lost reply","detail":"Phone sees timeout","tone":"rose"}],"edges":[{"from":"phone","to":"cafe","label":"request arrives"},{"from":"cafe","to":"reply","label":"confirmation"}]}
```

Use for a process, cause/effect or dependency. Name what each arrow means. Prefer 2–4 nodes in left-to-right order and adjacent edges; complex cyclic graphs need a different representation, not a tangle of arrows. Bounds: 1–6 nodes, 0–12 edges; label 120; node label 60/detail 100; edge label 60. Tones: `ink`, `sage`, `ochre`, `rose`. Color is emphasis, never the only carrier of meaning. Don't use a flow when the real point is a contrast or quantity.

## Annotation: make the important detail explicit

```json
{"id":"insight","type":"annotation","target":"path","label":"Silence doesn't undo the order","text":"The timeout changes what the phone knows. It does not reverse the café's action.","tone":"ochre"}
```

Use to interpret, qualify or highlight an existing unit, particularly after a human answer. Target must be another unit that remains present in the final state; position the annotation nearby. Label: 80, text: 800, optional tone as above. Do not merely repeat the diagram caption. If removing its target, remove or retarget the annotation in the same edit.

## Prompt: invite a consequential response in context

```json
{"id":"prediction","type":"prompt","question":{"prompt":"What could another send do?","choices":[{"id":"one","label":"Still one order"},{"id":"two","label":"Create a second order"},{"id":"unsure","label":"Something is missing"}],"reasoning":{"label":"Talk me through what Retry means to you.","required":true}}}
```

Use after the thought it addresses. Ask only when the answer can affect what you explain next. A prediction exposes a mental model; a choice exposes a tradeoff; free text exposes an unexpected interpretation. Include uncertainty when a forced choice would misrepresent the person. Avoid turning every thought into a quiz.

At least one control is required. Question prompt: 300 characters. Optional choices: 2–6 `{id,label,detail?}` (label 100/detail 200). Optional reasoning: `{label,required}` (label 150; response 4000). Optional slider:

```json
{"id":"duration","label":"How long without a connection?","min":1,"max":14,"step":1,"value":3,"unit":"days"}
```

A slider belongs only to a meaningful numeric scale, never a decorative confidence ritual. Response fields are `choice`, `slider`, `reasoning`, not the slider metadata ID.

One accepted answer per prompt definition. The definition version changes when its content changes, not when other thoughts arrive. Ask a new question with a new ID when it is a new conversational turn. Preserve earlier answers; do not relabel them as answers to a different question.

## Small edits

An edit file contains an array, applied atomically against the expected conversation revision:

```json
[
  {"op":"put","unit":{"id":"insight","type":"annotation","target":"path","label":"Your distinction matters","text":"An explanation authored from the actual answer goes here."},"after":"path"},
  {"op":"move","id":"prediction","after":"insight"}
]
```

`put` replaces an existing unit of the same type or appends a new one. Optional `after` positions it after an existing ID; `null` places it first. Without `after`, an existing unit keeps its position. `move` requires `after`. `remove` takes an `id`. Maximum 32 operations per edit, 80 live units, 2000 committed changes, 2 MB persisted conversation, 64 KiB request. Failed/stale edits change nothing.

Do not use `put` on an unchanged prompt merely to animate it. Type changes need a new ID. Removing/readding an ID does not reset its version. IDs, conversation revisions, prompt versions, input-event IDs, and stream cursors have different meanings.

## Composition, not a fixed lesson

- **Request/retry:** premise → compare phone/café knowledge → flow → prediction → responsive annotation.
- **Stale cache:** premise → compare source/cached copy → flow of a read → ask about freshness requirements → revise the tradeoff.
- **Product choice:** short goal → aligned alternatives → ask which cost matters → annotate the choice and expose a constraint.

These are patterns, not scripts. Source examples under `examples/conversation-*.json` are labeled sample compositions. Never claim an example follow-up represents a response to real input.
