megaprompt for terminal from scratch

terminal-megaprompt

DEVELOPER TASK SPEC (FOR DEVIN)
Project: Build a real Linux terminal emulator “from scratch” inside repo andrewgcodes/mochi.
Goal: A genuine VT/xterm-style terminal emulator that runs a real shell/apps via a PTY, correctly parses escape sequences, maintains a screen model, and renders a GUI. No wrapping an existing terminal widget/library/implementation.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
0) NON-NEGOTIABLE RULES (READ FIRST)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
R0.1 — No cheating / no “terminal emulator libraries”
  - You MUST NOT depend on any library that implements terminal emulation, ANSI/VT parsing, or screen-model logic for you.
  - Examples of forbidden dependencies (non-exhaustive):
    - libvte / VTE (GTK terminal widget)
    - libtsm, kmscon, weston terminal pieces
    - termwiz, vt100 crates, ansi_term-like parsers (if they parse and apply sequences)
    - embedding xterm/rxvt/alacritty/kitty/wezterm code or linking them
  - You MAY use libraries for:
    - window creation/event handling (e.g., SDL2, GLFW, winit, XCB, Wayland-client)
    - rendering (OpenGL/Vulkan/wgpu), image loading
    - font rasterization and shaping (FreeType, HarfBuzz)
    - clipboard integration
    - unicode data tables (width tables, segmentation), BUT you must still implement terminal rules yourself.

R0.2 — No placeholders, no “TODO stubs”, no fake behavior
  - Every feature you claim is supported MUST be implemented end-to-end.
  - If a capability is not implemented, document it explicitly as “NOT SUPPORTED YET”.

R0.3 — Documentation is mandatory and continuous
  - As you code, write docs and inline comments. Keep modules self-explanatory.
  - Maintain a “living spec” documenting:
    - supported escape sequences
    - semantics and corner cases
    - compatibility claims (what level of VT/xterm you target)
    - known gaps and planned work

R0.4 — Iterative development with MANY PRs
  - Work in small, coherent milestones.
  - Open many PRs to keep reviewable chunks and reduce risk.
  - Each PR MUST include:
    - code + tests + docs updated
    - clear description of what changed
    - how to run tests / reproduce

R0.5 — Online research is required
  - Before implementing each major capability (PTY, CSI parsing, OSC, alt-screen, mouse modes, etc.), consult authoritative docs and summarize findings in docs/research/.

R0.6 — Plan, execute, revisit plan
  - Start with a written plan and update it as reality changes.
  - No assumptions: verify behavior via references + empirical tests.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1) HIGH-LEVEL DELIVERABLES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Deliverable D1: “mochi-term” (name can vary) terminal emulator application
  - Runs on Linux (Wayland and/or X11; choose a concrete target and document it).
  - Spawns a child shell attached to a PTY (default: user’s $SHELL or /bin/bash).
  - Correctly handles interactive apps: vim/nvim, htop, less, man, tmux, ssh (at least basic usability).
  - Implements a robust VT/xterm subset with correct screen state management.
  - Supports:
      - UTF-8 text
      - resizing (SIGWINCH to child)
      - scrollback
      - selection + clipboard copy/paste
      - colors: 16 + 256 + truecolor
      - cursor styles/visibility
      - alternate screen
      - bracketed paste
      - mouse reporting modes used by common TUI apps
      - OSC window title; OSC 8 hyperlinks; OSC 52 clipboard (with security controls)
  - Includes a terminfo entry (TERM=mochi or TERM=xterm-256color; document strategy).

Deliverable D2: Headless test harness
  - A “terminal core” library that can run without a GUI:
      input bytes → parse → mutate screen model → produce deterministic snapshot
  - Used for unit tests + golden tests + fuzz tests.
  - CI can run these tests reliably.

Deliverable D3: Documentation + correctness evidence
  - docs/architecture.md
  - docs/escape-sequences.md (coverage matrix)
  - docs/testing.md
  - docs/security.md (OSC 52 and other potentially dangerous sequences)
  - docs/research/ notes with links and citations
  - A “compatibility report” showing test results (vttest + internal tests).

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
2) REPO INTEGRATION (FIRST ACTIONS)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 2.1 — Clone and inspect repo
  - Clone: https://github.com/andrewgcodes/mochi
  - Determine existing language/tooling.
  - If repo already uses a language/build system, prefer consistency.
  - If repo is empty or flexible, choose Rust for safety + testing + fuzzing OR C++ for low-level control.
  - Write an ADR:
      docs/adr/0001-terminal-language-and-stack.md
      Include: rationale, alternatives considered, exact dependencies.

Step 2.2 — Create a dedicated project area
  - Create /terminal or /apps/mochi-term or similar.
  - Keep terminal code isolated (it will be large).
  - Add top-level docs index: docs/terminal/README.md

Step 2.3 — Add CI early
  - GitHub Actions pipeline must at minimum:
      - build
      - run unit tests
      - run golden tests
      - run lint/format
  - Fuzzing can be nightly/optional but should exist.

Step 2.4 — Establish PR discipline
  - Add PR template: .github/pull_request_template.md
  - Add issue labels: terminal, parser, renderer, pty, tests, docs, security, performance
  - Each PR:
      - references a milestone issue
      - includes checklist (tests/docs)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
3) ARCHITECTURE REQUIREMENTS (MUST FOLLOW)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
You MUST implement a clean separation:

A) terminal-core (platform-independent)
  - Screen model:
      - primary screen grid
      - alternate screen grid
      - scrollback ring buffer
      - cursor state (position, style, visibility)
      - tab stops
      - margins/scroll region
      - mode flags (origin mode, wraparound, insert mode, etc.)
      - current rendition (SGR attributes)
  - Deterministic behavior:
      - Given the same byte stream, must produce identical snapshots.
  - No GUI types in this crate/module.

B) terminal-parser (platform-independent)
  - Stateful parser that converts bytes into semantic operations (“terminal actions”):
      - Print char(s)
      - Control char (LF/CR/BS/TAB/BEL)
      - CSI dispatch (with parsed params/intermediates/final)
      - OSC dispatch (with parsed command + payload)
      - ESC dispatch (non-CSI sequences)
      - DCS/APC/PM/SOS (can be stubbed ONLY if clearly unsupported, but MUST not crash; must consume correctly)
  - Parser must support incremental streaming: accept arbitrary chunk boundaries.
  - UTF-8 decoding must be correct; invalid sequences must be handled deterministically (replacement char rules must be documented).

C) pty + child process (Linux-specific)
  - PTY open/ownership/grant/unlock + slave open
  - Fork/exec child shell
  - Session/controlling terminal setup
  - Non-blocking IO + polling
  - Resize propagation (TIOCSWINSZ on PTY + SIGWINCH)
  - Signal handling for child exit

D) frontend (GUI)
  - Window + event loop (Wayland/X11)
  - Renderer draws terminal-core snapshot
  - Input:
      - keyboard → encode to terminal input sequences → write to PTY
      - mouse → encode reporting sequences when enabled → write to PTY
  - Clipboard integration:
      - selection copy
      - paste (with bracketed paste support)
      - OSC 52 (optional but required for “advanced” milestone)

E) app glue
  - config system (defaults; config file optional but recommended)
  - logging/tracing
  - “debug overlay” mode recommended (show cursor pos, modes, last parsed seq, FPS)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
4) MILESTONES AND PR PLAN (DO NOT SKIP)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
You must create a GitHub Issue for each milestone and implement via multiple PRs.

Milestone 0 — Project scaffolding (PRs: 2–4)
  PR0.1: Add terminal project skeleton + build tooling
    - create directories/modules
    - add formatting/linting rules
    - minimal “hello world” binary

  PR0.2: Add docs baseline + ADRs + initial plan
    - docs/terminal/README.md: scope, goals, non-goals
    - docs/architecture.md: module boundaries
    - docs/escape-sequences.md: initial “coverage matrix” with TODO list

  PR0.3: Add CI
    - build + unit tests + formatting + lint

Acceptance:
  - Repo builds in CI, tests run, docs exist.

Milestone 1 — PTY plumbing & smoke tests (PRs: 2–3)
  PR1.1: Implement PTY open + spawn child
    - a CLI-only “relay” program that attaches stdin/stdout to PTY (no GUI)
    - verifies child runs and interactive IO works
    - includes tests that spawn /bin/sh and run simple commands

  PR1.2: Resize + SIGWINCH correctness tests
    - set PTY size
    - run a child that prints $COLUMNS/$LINES or uses ioctl(TIOCGWINSZ) and verify updates

Acceptance:
  - Can run a shell via PTY and interact.
  - Resize updates child behavior.

Milestone 2 — Terminal core (screen model) + headless snapshots (PRs: 3–6)
  PR2.1: Implement screen grid, cells, cursor, basic printing
    - wrapping rules
    - newline/CR/BS/TAB
    - scrolling when cursor goes beyond bottom

  PR2.2: Scrollback buffer + viewport
    - implement ring buffer lines
    - define snapshot format (JSON/YAML) including attributes

  PR2.3: Headless runner
    - tool: feed bytes from file/stdin → output snapshot
    - deterministic snapshots used by tests

  PR2.4: Unit tests for line wrapping, scroll, tabs, backspace
    - include tricky cases and document expected behavior

Acceptance:
  - Headless runner can reproduce terminal state reliably.

Milestone 3 — Parser v1 (ESC/CSI basics) (PRs: 4–8)
  PR3.1: Parser state machine skeleton
    - NORMAL, ESC, CSI, OSC, DCS (even if minimal)
    - incremental streaming support
    - exhaustive tests for chunk boundary splits

  PR3.2: Implement essential CSI cursor movement + erase
    Required CSI:
      - CUU/CUD/CUF/CUB (A/B/C/D)
      - CUP/HVP (H/f)
      - CHA (G), VPA (d)
      - ED (J), EL (K)

  PR3.3: Implement SGR (m) basics
    - reset (0)
    - bold (1), faint (2 optional), italic (3), underline (4), inverse (7), hidden (8), strike (9)
    - 16-color: 30–37/40–47, bright 90–97/100–107
    - 256-color: 38;5;N / 48;5;N
    - truecolor: 38;2;R;G;B / 48;2;R;G;B
    - correct attribute reset semantics (22, 23, 24, 27, 28, 29, 39, 49)
    - document which SGR codes you support

  PR3.4: Golden tests for CSI + SGR
    - store input byte streams and expected snapshots
    - cover multiple chunk boundaries per test

Acceptance:
  - Headless: `printf` sequences produce correct screen state.
  - Basic color and cursor movement works.

Milestone 4 — Full-screen editing primitives (PRs: 4–10)
  Implement operations required by editors and vttest:
    - scroll region (DECSTBM: CSI t;b r)
    - insert/delete line (IL/DL: CSI L / CSI M)
    - insert/delete char (ICH/DCH: CSI @ / CSI P)
    - erase char (ECH: CSI X)
    - delete/insert column if you choose (optional; document)
    - save/restore cursor (DECSC/DECRC and/or CSI s / CSI u as supported)
    - origin mode + autowrap + insert mode + newline mode flags
    - tab set/clear (HTS, TBC)
    - reverse index (RI), index (IND), next line (NEL)

Testing requirements:
  - Unit tests for each primitive with edge cases (scroll region boundaries, insertion at margins, etc.)
  - Golden tests that replicate known sequences from docs/research.

Acceptance:
  - vim/nvim basic screen drawing works.
  - vttest “screen features” substantially pass (manual + partial automation).

Milestone 5 — GUI renderer MVP (PRs: 3–7)
  PR5.1: Window creation + render loop
    - choose stack and document it (winit+wgpu or SDL2+OpenGL etc.)
    - render a static grid snapshot (no PTY)

  PR5.2: Font rendering
    - monospace font loading
    - rasterize glyphs
    - glyph cache (texture atlas)
    - draw cells with fg/bg and styles (bold/underline at minimum)

  PR5.3: Connect core snapshot → renderer
    - render cursor (block/bar/underline)
    - render selections overlay
    - handle resize: compute cols/rows from pixel size

Testing:
  - Include screenshot-based tests ONLY if deterministic; otherwise rely on headless snapshot tests.
  - At minimum: automated “render sanity” test that runs renderer for N frames without crash.

Acceptance:
  - A window displays a grid accurately from a snapshot file.

Milestone 6 — End-to-end interactive terminal (PRs: 4–8)
  PR6.1: Glue PTY IO into GUI event loop
    - poll PTY master
    - parse bytes → apply to core
    - damage tracking: only redraw changed regions if possible (performance)

  PR6.2: Keyboard input encoding
    - implement xterm-like key sequences:
      - arrows, home/end, pgup/pgdn, insert/delete
      - function keys F1–F12
      - modifiers (shift/alt/ctrl) behavior documented
    - ensure text input works with UTF-8

  PR6.3: Basic clipboard paste (GUI) and bracketed paste mode
    - bracketed paste enable/disable sequences
    - when enabled: wrap pasted text with bracketed paste sequences to child
    - security: sanitize or document

Acceptance:
  - You can open the app and use bash interactively.
  - Basic TUI apps run (htop, less).

Milestone 7 — Mouse + selection + scrollback UX (PRs: 4–10)
  Requirements:
    - Selection with mouse drag
    - Copy selection to clipboard
    - Scrollback with mouse wheel (without breaking alt screen)
    - Mouse reporting modes to apps:
        - X10 / VT200 / SGR 1006 (choose a subset but must support common TUIs)
    - Focus in/out events if enabled by app (optional but recommended)

Testing:
  - unit tests for selection mapping (cell coords to buffer)
  - manual test script: run `vim` + enable mouse, verify selection vs app mouse reporting.

Acceptance:
  - tmux mouse mode usable
  - selection + copy/paste works reliably

Milestone 8 — OSC support (title, hyperlinks, clipboard) (PRs: 4–12)
  Implement at minimum:
    - OSC 0/2: set window title
    - OSC 8: hyperlinks (render style, and on click open via system handler OR copy link)
    - OSC 52: clipboard set (base64 payload)
        - MUST implement security controls:
            - option to disable
            - max payload size
            - require explicit user enable or “trusted mode”
            - document behavior clearly

Testing:
  - golden tests for OSC parsing (including chunk boundary splits)
  - manual test for OSC 52 via a known script

Acceptance:
  - Title changes work.
  - Hyperlinks can be detected and interacted with.
  - OSC 52 works with safety controls.

Milestone 9 — Terminfo and ncurses compatibility (PRs: 2–6)
  Requirements:
    - Decide TERM strategy:
        Option A) Claim xterm-256color and implement enough to be truthful
        Option B) Provide TERM=mochi with a custom terminfo entry
    - Provide:
        - terminfo source file in repo (e.g., assets/terminfo/mochi.terminfo)
        - install instructions using `tic`
    - Validate with:
        - `infocmp`
        - basic curses demo apps
        - vttest runs

Acceptance:
  - Curses apps render correctly without needing hacks.

Milestone 10 — Hardening, correctness, performance (ongoing PRs)
  Requirements:
    - Fuzz parser (must not panic/crash; must not infinite loop)
    - Performance tests:
        - massive output (yes, cat large file)
        - fast scrolling
    - Memory: scrollback bounds
    - Robust handling of invalid sequences

Acceptance:
  - No crashes under fuzzing and stress tests.
  - Acceptable interactive performance.

Milestone 11 — Polish + release artifact (PRs: 3–8)
  Requirements:
    - Config file support (font, size, colors, scrollback size, OSC52 enable)
    - README with usage
    - man page or --help doc
    - versioning + changelog
    - packaging instructions (optional)

Acceptance:
  - A user can install and run easily; docs clear.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
5) REQUIRED ESCAPE SEQUENCE COVERAGE (MINIMUM SET)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
You must maintain docs/escape-sequences.md with:
  - Sequence
  - Meaning
  - Implemented? (Yes/No)
  - Tests (unit/golden file)
  - Notes/known differences vs xterm

Minimum “must implement” set for real usability:
  C0 controls:
    - BEL, BS, HT, LF, VT/FF (treat as LF), CR, ESC
  ESC (non-CSI):
    - ESC 7 / ESC 8 (save/restore cursor) OR CSI s/u with correct behavior
    - ESC D (IND), ESC M (RI), ESC E (NEL), ESC H (HTS)
    - ESC ( B (ASCII charset at least)
    - DEC Special Graphics line-drawing (if you aim for good vttest compatibility)
  CSI:
    - Cursor movement: A B C D G d H f
    - Erase: J K X
    - Scroll region: r
    - Insert/delete: @ P L M
    - SGR: m (full color support per above)
    - Mode set/reset: h/l (including DEC private ?…)
        - at minimum: ?25 (cursor visible), ?1049 (alt screen), ?2004 (bracketed paste)
  OSC:
    - 0/2 title
    - 8 hyperlinks
    - 52 clipboard (with security)

For each DEC private mode you add, document and test it.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
6) DATA STRUCTURES AND BEHAVIORAL SPEC (CORE)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
You must implement and document:
  - Cell:
      - unicode scalar (or grapheme cluster policy; see below)
      - fg/bg color (indexed + RGB)
      - attrs: bold, italic, underline, inverse, faint, strike, hidden
      - hyperlink id (optional)
  - Line:
      - vector of cells sized to columns
      - line wrap flag (was this line soft-wrapped?)
  - Screen:
      - visible grid [rows x cols]
      - scroll region (top..bottom)
      - cursor state
      - saved cursor state(s) (main + alt)
  - Scrollback:
      - bounded ring of lines with styles preserved
  - Damage tracking:
      - mark dirty rects/lines per update for performance

Unicode rendering policy (must choose and document):
  - Option 1: Store per-cell “grapheme cluster” (string) and treat width via unicode width rules.
  - Option 2: Store codepoints plus combining marks in same cell.
  - MUST handle:
      - combining marks
      - wide characters (CJK)
      - emoji (at least reasonable handling; perfect ZWJ sequences are hard but attempt a principled approach)
  - Document known limitations precisely.

Wrapping policy:
  - autowrap mode on/off
  - behavior at last column (soft wrap vs overwrite)
  - CR/LF interactions
  - insert mode shifting

Alt screen:
  - separate buffer
  - entering alt screen should preserve main buffer+scrollback
  - leaving alt restores main view

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
7) TESTING REQUIREMENTS (VERY IMPORTANT)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
You must implement a layered testing strategy:

T1 — Unit tests (fast, lots)
  - terminal-core behavior:
      - printing + wrapping
      - scrolling + scroll region
      - insert/delete ops
      - SGR attribute state machine
      - cursor save/restore
  - terminal-parser:
      - parsing correctness
      - chunk boundaries
      - invalid sequences
      - OSC payload termination (BEL vs ST) handling
  - Selection logic:
      - mapping from mouse drag to buffer slices

T2 — Golden snapshot tests (deterministic)
  - For each major feature, store:
      - input bytes file (or inline) + expected snapshot JSON/YAML
  - Include tests where the input stream is split into random chunk sizes to ensure streaming correctness.

T3 — Integration tests (PTY-driven, still headless)
  - Spawn shell or small test program in PTY
  - Send keystrokes/commands
  - Capture PTY output and feed into terminal-core
  - Validate resulting snapshot contains expected content

T4 — Compatibility/manual test scripts (documented)
  - Provide scripts in scripts/tests/manual/:
      - vim test steps
      - tmux test steps
      - ssh test steps
      - vttest run instructions and what “pass” looks like

T5 — Fuzzing
  - Fuzz terminal-parser with random bytes.
  - Invariants:
      - no crash/panic
      - no infinite loop/hang
      - bounded memory growth under specified limits

T6 — Performance tests (at least basic)
  - Benchmark:
      - throughput of parsing and applying bytes
      - redraw time for full-screen updates
  - Document results and regressions.

CI must run T1 + T2 + T3 every PR. Fuzzing can be nightly but should exist.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
8) SECURITY REQUIREMENTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Must explicitly address:
  - OSC 52 clipboard exfiltration risk:
      - default OFF or require user opt-in
      - size limits
      - clear UI indicator when clipboard was set via OSC 52
  - OSC 8 hyperlinks:
      - ensure safe URL handling; do not auto-open without click
  - Title setting: safe and bounded
  - Denial-of-service:
      - extremely long escape sequences
      - unbounded scrollback
      - malformed UTF-8
  - Document everything in docs/security.md

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
9) IMPLEMENTATION GUIDELINES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
G9.1 — Keep the core deterministic
  - The GUI should not affect terminal state; it only renders snapshots.

G9.2 — Strict error handling
  - Any parse error should be handled and documented.
  - Never silently ignore without a documented rule.

G9.3 — Log and debug tooling
  - Implement structured logging for:
      - parsed sequences (optional sampling)
      - mode changes
      - resize events
  - Provide a debug overlay toggled by a keybinding.

G9.4 — Make behavior auditable
  - For each escape sequence you implement, include:
      - reference note in docs/research/
      - test coverage link

G9.5 — Continuous refactoring allowed, but keep PRs coherent
  - Small PRs, each with its own tests.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
10) DEFINITION OF DONE (ACCEPTANCE CHECKLIST)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
A release is acceptable when:
  - The terminal emulator launches and runs a shell via PTY.
  - “Core correctness”:
      - Cursor movement + erase + SGR + insert/delete + scroll region behave as documented.
      - UTF-8 works with wide chars and combining marks (document limitations).
  - “Real app usability”:
      - vim/nvim usable for editing
      - less/man usable
      - htop usable
      - tmux usable at least for basic splitting (mouse optional if documented)
  - “Testing”:
      - CI passes (unit + golden + PTY integration)
      - fuzzing exists and has been run for a meaningful duration
  - “Docs”:
      - architecture + escape sequence matrix + security doc are complete
      - terminfo strategy documented and validated
  - “No cheating”:
      - no forbidden deps
      - no copied terminal emulator code
      - evidence: dependency audit and explanation in docs/terminal/README.md

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
11) START NOW — EXACT FIRST WEEK EXECUTION PLAN (DO THIS)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Day 1:
  - Inspect repo, decide language/stack via ADR.
  - Create Milestone 0 issues.
  - Implement scaffolding PR0.1.
  - Write docs/terminal/README.md with scope and constraints.

Day 2:
  - Add CI PR0.3.
  - Implement PTY smoke program PR1.1 (CLI-only).
  - Add PTY unit/integration tests.

Day 3–4:
  - Implement terminal-core PR2.1 + PR2.2.
  - Add headless runner PR2.3.
  - Add unit tests PR2.4.

Day 5–7:
  - Implement parser skeleton PR3.1.
  - Implement CSI basics PR3.2.
  - Implement SGR PR3.3.
  - Add golden tests PR3.4.

Repeat weekly:
  - Revisit plan
  - Update docs/escape-sequences.md coverage
  - Add PRs steadily, never huge monolith PRs.

END OF SPEC