# Terminal E2E artifacts

`zig build terminal-e2e` runs `tools/terminal_e2e.py` against the compiled `mim`
binary and writes ignored artifacts under `.zig-cache/terminal-e2e/<scenario>/`.

Matrix input profiles:

- `ios-default-qwertz-space-path` means the scenario may use only letters,
  Shift+letters, and Space from the default iOS software keyboard. Shift is easy
  to reach on iOS; Esc, Ctrl, Alt, function keys, arrow keys, and symbol-layer
  punctuation should not appear in this profile. Use this for primary mobile
  workflows.
- `attached-keyboard` is allowed to cover Esc, arrows, Home/End, punctuation, and
  other physical-key aliases.

Artifact roles:

- `manifest.tsv`: stable scenario facts, hashes, bare-LF status, seen ANSI roles,
  and artifact list.
- `visible-controls.normalized.txt`: primary semantic failure artifact. It shows
  CR as `␍`, LF as `␊`, ESC as `␛`, tabs as `⇥`, and normalizes volatile temp
  paths.
- `transcript.txt`: semantic terminal grid after escape/control interpretation,
  including debug-only role markers such as `☻` for a cursor cell and `░` for
  selection.
- `screenshot.svg` and `terminal.html`: browser-viewable visual evidence. SVG
  includes color swatches for seen cursor/current-line/status/selection roles.
- `widths.tsv`: per-line semantic width report used to catch viewport overflow.
- `raw.bin`: exact PTY bytes for low-level debugging.

Golden policy:

- Investigate before updating any expected artifact or assertion.
- Prefer semantic artifacts (`manifest.tsv`, `visible-controls.normalized.txt`,
  `transcript.txt`, `widths.tsv`) for assertions; visual artifacts explain what a
  user would see.
- Updating artifacts is safe only after the change is intentional and the receipt
  names the changed UI/control-byte behavior.
- Adding a mobile scenario must preserve the `ios-default-qwertz-space-path`
  contract unless the issue explicitly targets attached keyboards.
- Bare LF in raw-mode terminal output is a regression unless a scenario explicitly
  proves a non-raw stream. Raw-mode rendering should use CRLF to avoid diagonal
  terminal skew.
- Generated artifacts must remain under ignored build output and must not dirty a
  clean source tree.