[ADR] v1 full-screen widgets vs v2 region/framebuffer runtime — record the sunset/coexistence plan

[fissible]

Source: external review report, 2026-08-24 (notable exclusion #4)

Gap

Two architectures coexist with different event models:

• v1 full-screen one-shot widgets: action-list, table, confirm, alert — own the terminal, own their input loop, return via exit code
• v2 region/framebuffer world: shellframe_shell, panels, hitbox registry, diff-flush rendering

The README presents them seamlessly, but a contributor touching both pays the tax (two input paths, two trap conventions — see #43 (M3) — two mouse parsers — see #46 (M6)). There's no written statement of intent.

What it needs

An ADR in docs/ answering:

1. Is v1 a permanent "one-shot" tier (kept, maintained, documented as such) or a transitional layer to be re-implemented on v2 primitives?
2. If transitional: which widgets move first, and what's the compat promise for the $()/exit-code contract?
3. Which shared modules (input parsing, traps, sanitization, theming) are the canonical single implementation that both tiers must use — so [Bug] M3: Ctrl-C does not cleanly exit the v2 shell runtime #43 (M3)/[Bug] M6: SGR mouse parsing is unvalidated and duplicated (input.sh vs shell.sh) #46 (M6)/[Bug] H2: printf '%b' applied to caller-supplied text (escape injection) #42 (H2) fixes don't get done twice
4. Contributor guidance: "if you're adding a widget, build it on v2 unless…"

Also add a short "Architecture" section to README pointing at the ADR.

Effort: S
Deps: none — but should land before #46 (M6)/theming so those consolidate in the right direction

[fissible]

ADR drafted and accepted: docs/adr/0001 — both APIs kept (v1's standalone zero-runtime use is the adoption on-ramp), internals converge on shared primitives opportunistically, new interactive surfaces are v2-only, per-case migration trigger recorded. PM direction incorporated.