mim/tools/TERMINAL_E2E.md

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>/. It is the canonical local gate for terminal rendering/input/panel/workflow slices (NS10). Run it after zig build, zig build test, and zig build v1-smoke when a change can affect terminal-visible behavior; pure protocol/headless or docs-only changes may use cheaper checks unless their claim is terminal-visible.

The command is expected to finish in seconds on a normal development machine (current matrix target: under 30s). A timeout or nonzero exit should be treated as a product regression or harness bug, not a flaky benchmark: inspect the scenario artifact directory named in the failure output.

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.
• keystrokes.tsv: logical user key-event count and raw byte count for scenario payloads. A CSI sequence such as PageDown counts as one attached-key event while still recording all raw bytes sent.
• saved-files.tsv: per-file hashes/byte counts for scenarios that assert more than the launched file, such as multi-file coding workflows.
• e2e-prelude.trace (scenario temp dir only when needed): harness-only trace lines consumed before raw-mode input to seed deterministic provider fixtures; this is not a runtime config surface.
• raw.bin: exact PTY bytes for low-level debugging.

Failure triage:

1. Start with the scenario directory reported by the command.
2. Read manifest.tsv for hashes, CR/LF status, ANSI roles, key budget, and artifact list.
3. Read visible-controls.normalized.txt for visible ␍, ␊, ␛, and path normalized raw terminal evidence.
4. Read transcript.txt, widths.tsv, keystrokes.tsv, and any saved-files.tsv for semantic assertions before inspecting screenshots.
5. Use screenshot.svg/terminal.html to explain what a user would see.

Golden policy:

• Investigate before updating any expected artifact or assertion.
• Prefer semantic artifacts (manifest.tsv, visible-controls.normalized.txt, transcript.txt, widths.tsv, keystrokes.tsv, saved-files.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.
• Scenario max_key_events budgets are regression guards for workflow burden, not speed benchmarks. Raise a budget only after explaining the intentional workflow change in the receipt.
• Generated artifacts must remain under ignored build output and must not dirty a clean source tree.