rdbms-playground/docs/handoff/20260611-handoff-64.md

Session handoff — 2026-06-11 (64)

Sixty-fourth handover. Continues from handoff-63 (ADR-0046 sidebar/nav). This session closed two unrelated, website-screencast-enabling Gitea issues: #24 (vi-style load-picker navigation) and #22 (in-app demonstration overlay layer — its own ADR-0047, built end to end across three phases + a restyle).

§1. State at handoff

Branch: main. HEAD 2d0f4b2 plus an uncommitted docs finalization (ADR-0047 status → implemented, README index, this handoff — see §6). Push is the user's step.

Tests: 2290 passing / 0 failing / 0 skipped / 1 ignored (the 1 ignored is the long-standing friendly doctest). Clippy clean (nursery, all targets). +27 over the handoff-63 baseline of 2263.

This session's commits:

2d0f4b2 feat(ui): flat filled rectangles for demo overlays (#22, ADR-0047 D4)
241f60c feat(ui): demo-mode step-caption stealth buffer (#22, ADR-0047 D3/D4)
2584e76 feat(ui): demo-mode keystroke badges (#22, ADR-0047 D2/D4/D5)
f879d54 feat(cli): --demo demonstration mode flag + app plumbing (#22, ADR-0047 D1)
e9eb1b1 docs: ADR-0047 — demonstration overlay layer for casts/teaching (#22)
638b4c9 feat(app): vi-style j/k/g/G navigation in the load picker (#24)

Issues closed: #24 (vi nav) and #22 (demo overlays) — close #22 once the docs finalization commit lands.

§2. #24 — vi-style load-picker navigation (commit 638b4c9)

Purely additive to the ADR-0015 load picker (handle_load_picker_key, LoadPickerSubMode::List): j/k mirror Down/Up (bounds- respecting, no wrap), g/G jump to first/last. Existing keys (↑↓/Enter/Esc/b) unchanged; the footer hint is left as-is at the user's request (the new keys are not advertised). No ADR (additive). Motivation: autocast (the website cast driver) can only send typeable characters — not arrow keys — so the projects demo needs j/k to drive the picker. Tests: load_picker_jk_navigates_like_arrows, load_picker_g_jumps_to_first_and_last (test-first).

§3. #22 — ADR-0047 demonstration overlay layer (read the ADR)

An in-app demonstration mode (--demo flag / RDBMS_PLAYGROUND_DEMO env, off by default, zero footprint when off) that renders two transient overlays so autocast screencasts — and live teaching, and a future guided-lesson system — can show otherwise-invisible interactions.

• Phase A (f879d54): --demo + env → App.demo_mode, threaded through run_loop like --no-undo. --help line mentions only the visible badges; the Ctrl+] caption trigger is kept low-profile (user decision, D6).
• Phase B (2584e76): automatic keystroke badges ([TAB]/[ENTER]/[UP]/…) over a fixed set of glyph-less keys — pure demo_badge_label(&KeyEvent), set in App::update before the modal gate (so they fire over the load picker), expired by a ~1.5 s runtime timer. The timer extends the event loop's time-boxed-recv via a new pure nearest_deadline helper; the rewrite tracks Instant deadlines and was verified not to regress the ADR-0027 indicator debounce. New App.last_output_area: Rect (set in render_output_panel) anchors the overlays.
• Phase C (241f60c): the stealth Ctrl+] caption buffer — Ctrl+] (byte 0x1D → Char('5')+CONTROL, verified vs crossterm 0.29) toggles an invisible buffer; typed chars accumulate without touching input/output, Backspace edits, other keys inert, a second Ctrl+] commits (empty commit dismisses). In pure-sync App::update, intercepted before the modal gate; an ordinary keystroke clears a visible caption.
• Restyle (2d0f4b2): the overlays render as flat filled yellow rectangles (no border glyphs, one-cell text margin) — user decision, deliberately unlike the bordered panels so they pop. Shared fill_overlay_rect (borderless Block fill + inset Paragraph).

Placement: both float at the output panel's inner bottom-right, drawn last over modals, badge stacked directly above the caption when both show; caption wraps to ≤ 3 lines then ellipsises; clamp/ skip guard for tiny terminals.

Process: ADR-first (user chose), pre-build /runda (10 findings, folded in) + whole-implementation /runda (PASS, no blockers). Every fork user-confirmed via mockups/questions, incl. the two post-draft follow-ups: Ctrl+] trigger (over Ctrl+!, which autocast cannot send — not a single ASCII byte) and wrap-to-3-line captions.

§4. Two things to know about the implementation

1. Ownership split (intentional, mirrors input/input_indicator): demo_caption/demo_caption_capturing/demo_caption_buffer are driven by App::update (input); demo_badge is set by App::update but its expiry is timed by the runtime (demo_badge_seq bumps so a repeated key restarts the timer).
2. Ctrl-C is inert while capturing — by spec ("every other key is inert"); exit capture with Ctrl+]. User-acknowledged; flagged in the ADR. The only behaviour worth a second look if it ever annoys.

§5. Honest coverage note

Everything testable is tested (label fn, full caption FSM incl. over-modal + demo-off, nearest_deadline, all rendering, CLI parse/env). The only untested wiring is inside run_loop (the badge-timer arm/clear and app.demo_mode = demo_mode) — run_loop is not unit-testable (terminal + DB + channels), exactly the posture the existing IndicatorDebounce already takes. A future Tier-4 PTY harness (ADR-0008 TT4, still unwired) would close it.

§6. How to take over

1. Read handoffs 62 → 63 → 64, CLAUDE.md, docs/requirements.md, docs/adr/README.md, and ADR-0047 (fully landed).
2. Pending: the docs finalization commit (ADR-0047 status → implemented; README index; this handoff). Commit as docs: session handoff 64 + ADR-0047 implemented (#22/#24) (the user confirms commit messages). Then close #22 on Gitea.
3. For demo-overlay work: App has demo_mode, demo_badge, demo_badge_seq, demo_caption, demo_caption_capturing, demo_caption_buffer, last_output_area. Rendering: render_demo_overlays / render_badge_box / render_caption_box / fill_overlay_rect in ui.rs; colours DEMO_OVERLAY_FG/BG in theme.rs; key handling handle_demo_caption_key + the top-of- handle_key gate; timer in runtime.rs (nearest_deadline, DEMO_BADGE_TTL).

§7. Remaining open landscape (from handoff-63, minus the closed items)

1. Wire the overlays into the website casts — casts.mjs on the website branch can now emit ^]/text/^] for captions and rely on automatic badges. Website-branch follow-up (OOS for #22's app scope).
2. TT5 CI — 2290 green, no pipeline yet.
3. SD1 seed then H2 hint — the unblockers for A1 app-commands; own ADRs.
4. V2/S3 multi-result tabs / V4 journal — larger output-model redesign, own ADR.
5. C3a modify relationship — small (drop+add covers it).
6. Tutorial/lesson system — acknowledged in scope; needs its own ADR; ADR-0047's overlay primitive is what it will reuse.

Run a cargo sweep at some point — target/ grew across this build-heavy session.