# First quality slice: controlled HTML sequence diagrams

Status: local implementation and tests are complete for this HTML slice. This document covers only HTML; see [built-in forms](native-forms.md) for the other four modes. Arbitrary component-library loading is not implemented.

## Interface

`createShowMe({ host, libraries, maxRepairs })` is the Host composition entry point and returns `describe(query)` and `render(request)`. The agent supplies no layout parameters. The Host defaults to at most three repairs, with an allowed budget of 0–8.

The MCP operations are `describe_display` and `render_display`. Legacy `render_visual` behavior remains available. For this slice, the new tool writes an HTML file and returns its local path, quality evidence, and content hash. Failures do not deliver an artifact marked as successful.

```json
{
  "form": "html",
  "content": {
    "title": "Request flow",
    "nodes": [
      { "id": "client", "element": "core/card@1.0.0", "props": { "title": "Client" } },
      { "id": "server", "element": "core/card@1.0.0", "props": { "title": "Server" } }
    ],
    "relations": [
      { "from": "client", "to": "server", "label": "Send a request and wait for its acknowledgement" }
    ]
  }
}
```

`describe_display` returns exact references, schemas, meanings, examples, supported forms, and content limits for enabled elements, with library/form filtering and pagination. Query `form: "html"` for this slice. The other four forms are also available but do not use user expression libraries.

## Supported scope

- 1–6 nodes in input order, with at most one forward directed relation between each adjacent pair. Groups, backward or non-adjacent connections, parallel relations, and custom relation types are outside this slice.
- Titles up to 256 characters, bodies up to 1024, and relation labels up to 256. Arbitrary HTML, CSS, and scripts are not accepted.
- User libraries define elements through declarative schemas and field bindings. Visual adaptation supports only built-in rounded/square shapes and neutral/info styles. Arbitrary user UI components or new drawing functions are not connected.
- The Host uses isolated headless Chromium, defaulting to 1280×800, device scale 1, and Arial/sans-serif. This slice loads no remote resources.
- HTML records the resulting layout. A narrower window does not inherit its quality guarantee; render again for the new environment.

Missing elements, invalid inputs, unsupported forms/structures, unavailable environments, or failed quality checks return `not-ready` with a specific reason. They do not silently switch to PNG or change semantics.

## Automatic repair and evidence

The first candidate uses baseline spacing. After fonts load, the browser measures actual node, text, arrow, and label rectangles. The core checks intersections between labels and arrows/nodes, expands the relevant gaps, and adjusts label height. It renders and checks again until success, budget exhaustion, or lack of progress.

Checks cover node overlap, text overflow, label/node/arrow occlusion, connectors crossing unrelated nodes, viewport overflow, and content/endpoint fidelity. Initial automatic repairs address label space only; other defects can be detected without a guarantee that they can be repaired.

After candidate checks pass, the Host reopens the **actual serialized HTML**, reinspects it, and only then delivers it. Evidence includes initial defects, actions, final defects, browser version, viewport, and the delivered content's SHA-256. Extension libraries cannot self-certify overall quality.

`ready` means these specific checks passed in the stated environment, not a universal aesthetic score or all-client acceptance. The agent provides business meaning; the core does not infer business correctness.

## Independent expression-library example

The [default library](../src/libraries/core.mjs) and [team library](../examples/team-library.mjs) use the same declaration contract. The team's service element maps `name` and `owner` to title and body, choosing supported component styles without modifying core source.

Libraries are supplied explicitly by the Host. MCP enables only the core library by default; the example script explicitly enables both. There is no dynamic download, global marketplace registration, or arbitrary module loading. The library contract remains an experimental first version.

```bash
npm ci
# Set SHOW_ME_CHROMIUM_BIN if Chromium is installed outside the default locations.
npm test
npm run render:quality-demo
```

The example writes `quality-sequence.html` and `quality-sequence.evidence.json` to `artifacts/`. Its first pass detects 3 label conflicts, reduced to 0 after 1 internal repair; the user does not change the input. Generated artifacts are excluded from Git.

## Remaining work

Arbitrary user components, general obstacle avoidance, browser cancellation/complex-task scheduling, and standalone Pi plugin distribution remain future work. Local rendering and MCP tests do not establish remote CI, release, or acceptance in every Pi window.