` output blocks  |
| `docs/shared.css`                               | Shared styles; includes `pre.terminal` class     |
| `scripts/ansi2html.ts`                       | ANSI-to-HTML converter (stdin to stdout)         |
| `docs/examples/dataviz/table.melker`            | Earthquake table                                 |
| `docs/examples/dataviz/sparkline.melker`        | True sparkline (height: 1, gap: 0)              |
| `docs/examples/dataviz/bars.melker`             | Magnitude vertical bar chart                     |
| `docs/examples/dataviz/boxplot.melker`          | Electricity price box plot                       |
| `docs/examples/dataviz/heatmap.melker`          | Weekly activity heatmap                          |
| `docs/examples/dataviz/tree.melker`             | Project file tree with extra columns             |
| `docs/examples/dataviz/connected.melker`        | Three connected views (boxplot + table + bars)   |
| `docs/examples/dataviz/grouped-bars.melker`     | Grouped bars (2024 vs 2025, Q1-Q3)               |
| `docs/examples/dataviz/isolines.melker`         | Heatmap with viridis color scale and isolines    |
| `docs/examples/dataviz/earthquakes.json`        | USGS-style earthquake GeoJSON (12 features)      |
| `docs/examples/dataviz/electricity-prices.json` | SE1-SE4 hourly prices (48 values each)           |
| `docs/examples/dataviz/activity.json`           | 5x8 office activity grid (Mon-Fri, 9am-4pm)     |
| `docs/examples/dataviz/files.json`              | Hierarchical file tree with sizes and types      |

## Code examples in the doc must match the real .melker files

Each section's code block is taken directly from the corresponding `.melker` file. The code-title uses the filename (e.g. `table.melker`, `bars.melker`). If a `.melker` file changes, the code block in the HTML must be updated to match. The hand-highlighted spans (``, `.attr`, `.str`, `.kw`, `.cmt`, `.num`) are applied manually.

## How to regenerate the `
` output blocks

### Prerequisites

A local web server must serve `docs/` on port 8888:

```bash
cd docs && python3 -m http.server 8888
```

### Running each example

Each `.melker` app uses `"net": ["samesite"]` in its policy and constructs fetch URLs with `new URL('file.json', $melker.url)`. When loaded from `http://localhost:8888/`, `samesite` expands to `localhost:8888`. Run with `--trust --stdout --color=always` and pipe through the ANSI-to-HTML converter:

```bash
run_example() {
  ./melker.ts "http://localhost:8888/examples/dataviz/$1" \
    --trust --stdout --stdout-width=80 --stdout-height=$2 --color=always --stdout-timeout=2000 \
    2>/dev/null | ./scripts/ansi2html.ts
}

run_example table.melker 20
run_example sparkline.melker 3
run_example bars.melker 12
run_example boxplot.melker 22
run_example heatmap.melker 10
run_example tree.melker 20
run_example connected.melker 22
run_example grouped-bars.melker 12
run_example isolines.melker 18
```

### Local .melker files

`sparkline.melker`, `grouped-bars.melker`, and `isolines.melker` can also be run locally (they use inline data or no network). The other examples fetch JSON via `new URL('file.json', $melker.url)` so the web server must be running.

### ANSI-to-HTML converter

`scripts/ansi2html.ts` reads ANSI-colored output from stdin and produces HTML:

- Parses 24-bit RGB SGR sequences (`\e[38;2;R;G;Bm` foreground, `\e[48;2;R;G;Bm` background)
- Merges consecutive characters with the same style into single `` elements
- Omits `background:rgb(0,0,0)` from spans (the default terminal background is set on the `
` element instead)
- Trims trailing spaces per line and trailing empty lines

### HTML integration

The converted output goes inside `
` blocks. The CSS class (in `shared.css`):

```css
pre.terminal {
  background: #000;
  color: #f9fafb;
  border-color: #333;
}
```

### Key stdout flags

| Flag                | Purpose                                                 |
|---------------------|---------------------------------------------------------|
| `--trust`           | Auto-accept policy (needed for URL-loaded apps)         |
| `--stdout`          | Render one frame to stdout and exit                     |
| `--stdout-width=N`  | Terminal width for layout                               |
| `--stdout-height=N` | Terminal height for layout                              |
| `--color=always`    | Force ANSI color output (for conversion to HTML spans)  |
| `--stdout-timeout=M`| Max ms to wait for async scripts (default 5000)         |

## Gotchas

- **`$melker.render()` required in async scripts**: `async="ready"` scripts run after the initial render. In stdout mode, the frame is captured after scripts complete, but only if the script calls `$melker.render()` to push updates.
- **`createState()` must be in a sync script block**: It must run before the first render. See `connected.melker`: two `