punkshell/goals/G-013-raw-mode-default.md

G-013 Raw mode as the repl's default input mode

Status: proposed Scope: src/modules/punk/repl-999999.0a1.0.tm, src/modules/punk/console-999999.0a1.0.tm Goal: a repl launched without explicit mode configuration starts in raw input mode with a clean display - every per-keystroke debug emission behind its own repl-operable toggle - and raw editing covers the line-mode essentials (history navigation, cursor movement). Acceptance: a default launch lands in raw mode with line mode still selectable; with debug toggles at their defaults (off unless stored configuration via ::punk::config says otherwise - see G-014), typing/editing/submitting a command emits no cursor-positioned debug output; the per-keystroke add_chunk frame and the right-hand live editbuf view are gated separately, each toggleable from within a running repl; arrow-key history navigation and left/right cursor movement work in raw mode (current stubs replaced); the marked-line debugrepl output form is retained and works on terminals without cursor addressing (e.g. vt52); the debugrepl first-word activation mechanism is reviewed and the keep/replace outcome (e.g. a proper Tcl command that interp hide can restrict in subshells) is recorded in the detail file; on tcl 8.6 a background-initiated terminal query at an idle raw-mode prompt succeeds (the residue scenario fail-fast-guarded in punk::console 0.7.1).

Context

Line mode is today's default because on Windows it gives OS-provided line editing and arrow-key history for free. Raw mode is the intended default, blocked by (1) debug output emitted with cursor-move sequences, and (2) unfinished raw editor features. Beyond display polish, flipping the default retires the last known reader-cooperation hole on tcl 8.6: terminal queries fired while the line-mode reader is armed at an idle prompt are hostage-prone by design (punk::console 0.7.1 made this fail fast rather than hang; raw default makes it work). It also removes the line-mode type-ahead-loss window during terminal-query raw cycling (#review, repl-999999.0a1.0.tm ~1677).

Debug emission inventory (as of repl 0.2.2)

1. add_chunk top-left frame (repl ~1145-1173) - per-keystroke framed dump of the overtype::renderline merge, painted at row 2 col 1. Currently ungated. This is definitely a debug feature: it gets its own toggle, operable from within a running repl, default off.
2. Right-hand live editbuf view (console_editbufview, repl ~2043, called ~2315) - currently ungated. An important development aid for per-keystroke features (e.g. command completion - now goal G-044, for which this goal's raw editor essentials are the prerequisite) and stays available, but behind its own separate gate. Its startup default should ultimately come from stored configuration via ::punk::config (see G-014) - toml-backed, independently configurable per named subshell - with off as the built-in fallback. Longer term, with the G-001 backend framework in place (achieved 2026-07-11), this live view could be streamed off-console instead - e.g. over udp to a monitoring app, or to a tk text-widget system acting as a pseudo terminal.
3. console_debugview (repl ~1976) - already gated (debug_repl > 0).
4. Marked-line form (debug_repl_emit, repl ~2566-2599, debug_repl > 100) - emits prefixed lines before the command result via the debugreport pseudo-channel, no cursor addressing. Retained as the baseline debug form for simple terminals (vt52, other console systems we implement) where complex terminal interaction is unavailable or unwanted.

debugrepl activation review

Current mechanism: first word "debugrepl" in the submitted command is intercepted before eval; bare/N/cancel manipulate a oneshot decrementing counter whose thresholds (>0, >100) select display layers. Review whether first-word interception is worth retaining or whether a proper Tcl command is better: a real command can be restricted in subshells via interp hide (aligns with G-003/G-009 restriction mechanisms), and named toggles would replace the magic thresholds now that gates are separate. Whatever the outcome, the marked-line output form itself stays (see inventory item 4).

Approach notes

• Cursor save/restore is a single slot, not a stack: the code already mixes cursorsave_ and plain move_emitblock variants to avoid collisions (comment at repl ~2031). Toggleable frames need one coherent cursor-bookkeeping policy.
• The raw chunk path calls punk::console::get_size per keystroke to position the rhs frames (repl ~2296-2308, acknowledged 1+ms). Cache the size with explicit invalidation; avoid any per-keystroke terminal query when no debug view is on.
• Raw editor stubs to replace: arrow-right/up and esc currently just rputs debug notices (repl ~2477-2492); history navigation and cursor movement are the parity items.
• The editbuf supports literal tab entry (tab is content, not only a UI gesture) - a standing constraint that G-044's completion-activation scheme must preserve (completion triggering cannot exclusively claim plain Tab).
• Toggle startup defaults resolve through ::punk::config stored configuration when available (G-014); built-in defaults apply when no configuration exists.

Alternatives considered

• Keeping line mode as default and making idle-prompt queries cooperate with the 8.6 parked reader - rejected: the 8.6 console driver parks a cooked ReadConsole that a raw flip cannot rescue (established 2026-07-05); cooperation is not achievable there, only fail-fast.