fix(tui): support image paste shortcuts across layouts

[needsbuilder]

Summary

• add platform-specific image-paste chords while keeping Ctrl+V primary on macOS and documenting that terminals may consume Command+V
• normalize modified Korean Dubeolsik Kitty input without swallowing unmodified or Shift-only text
• widen generated hotkey docs and runtime key arrays safely
• replay the intended change from closed fix(tui): support image paste shortcuts across layouts #3999 onto current dev

Review mapping

• changelog contract: fixed in both coding-agent and TUI ## [Unreleased]
• macOS super+v reachability: retained as secondary; Ctrl+V is primary and README qualifies terminal forwarding
• Shift-only normalization: fixed with an alt/ctrl/super requirement and regression test
• matchesKey/parseKey generalization: deferred because no current default path is affected
• Kitty terminal assumption: deterministic compatibility-jamo protocol coverage added; no claim of manual terminal/IME verification

Verification

• bun test packages/tui/test/keys.test.ts packages/coding-agent/test/custom-editor-keybindings.test.ts packages/coding-agent/test/keybindings-audit.test.ts — 95 pass, 0 fail, 1041 assertions
• bun --cwd=packages/tui run check — clean
• bun --cwd=packages/coding-agent run check — typecheck clean; one pre-existing unrelated smithery KEYS warning
• bun --cwd=packages/coding-agent run generate-hotkeys-docs --check — clean
• check:runtime canonicalization failure reproduces unchanged on origin/dev
• git diff --check origin/dev...HEAD — clean

Historical PR: #3999

[needsbuilder]

Readiness evidence snapshot

• observedAt: 2026-08-08T07:03:49Z
• historicalPr: #3999
• head.ref: fix/dev-image-paste-shortcuts
• headSha: f15a130ff8563668a336b14eca9306a28e8660c6
• base.ref: dev
• baseSha: 998dd506b059f4ebc319322ad57bc8858887237b
• mergeability: MERGEABLE
• reviewDecision: no CHANGES_REQUESTED
• findings: required changelogs, macOS key truthfulness, and Shift-only input correctness fixed; inactive parser generalization deferred with rationale
• tests: 95 pass / 0 fail / 1041 assertions; TUI and coding-agent typechecks clean; hotkey docs synchronized; diff check clean
• known base issue: SDK canonicalization runtime gate fails identically on current dev
• Dev CI run: 31245308246 → action_required
• Public site sync run: 31245308238 → action_required
• exitState: READY_AWAITING_OWNER_ACTION
• ownerNextAction: approve exact-head Actions and review; merge only after terminal-green
• invalidatesOn: head-or-base-change

No label or unrelated PR metadata was changed.

[needsbuilder]

Base-refresh evidence: current dev moved to 1d2e3ccd2af571ad640151643161cf260555f008, so the branch was merged normally, revalidated, and pushed as head 78b59ba229a8aa487a58069b8c05ee6c2c113a6b.

• PR remains OPEN, targets dev, and is mergeable with no Changes requested.
• Focused keybinding suites — 95 pass, 0 fail, 1041 assertions.
• TUI and coding-agent package checks passed; coding-agent retains one pre-existing unused KEYS warning.
• git diff --check — clean.
• Exact-head Dev CI 31246082588 and Public site sync 31246082585 are action_required.

No Actions approval or merge was performed.

[needsbuilder]

Final convergence snapshot 2026-08-08T07:28:29.287Z: head 517c15c95b3853aec6f77271d8b4367feac1ef1c, base dev 6ff7845cc4697b3ff3c32e28d1dd7c53c9cbd7d0, OPEN and mergeable, no Changes requested. Revalidation: 95 focused tests / 1041 assertions, TUI and coding-agent checks clean, diff check clean. Exact-head owner gates: Dev CI 31246213592 and Public site sync 31246213615, both action_required. No approval or merge performed.

[Yeachan-Heo]

Contributor ledger — REPAIR LANE. GitHub reports CONFLICTING / DIRTY; the base is stale. Rebase and resolve conflicts before review. Preserve the documented Ctrl+V-primary macOS contract, avoid treating Command+V as guaranteed terminal input, and rerun the keybinding/hotkey generation coverage on the resolved head.

[Yeachan-Heo]

OWNER_CONFIRMATION_REQUIRED

Exact head reviewed: 517c15c95b3853aec6f77271d8b4367feac1ef1c; current dev is 911910d96f9bd3f45920cd9c9243dbb4894e2e70 (the PR records base 6ff7845cc4697b3ff3c32e28d1dd7c53c9cbd7d0).

Merge is not authorized. The contributor has an active repair lane (2026-08-09 03:54 UTC) reporting GitHub CONFLICTING / DIRTY and directing a rebase/conflict resolution. I will not duplicate that owner. Exact-head Actions are also not green: Dev CI 31246213592 and Public site sync 31246213615 are both action_required.

Required re-review point after the owner publishes a replacement head: the current implementation configures only macOS ctrl+v/super+v, Windows ctrl+v/alt+v, and Linux ctrl+v; CustomEditor dispatches only configured app.clipboard.pasteImage keys. No Shift+Insert image-paste binding or test is present in this snapshot. The exact-head TUI keys suite passed 54/54; coding-agent focused suites could not load the snapshot native addon (environment failures not attributed to this PR), and no live PTY/TUI evidence was supplied.

Linked issue #3999 is closed, but its closure does not satisfy the unresolved merge, CI, or shortcut-coverage gates.

Signed-off-by: GJC red-team reviewer gjc@local

[needsbuilder]

Repair lane resolved: rebased onto current dev (dc13439be) and revalidated.

Conflict resolution — one changelog conflict. Dev's inserted version headers had pulled the branch entry into the released ## [0.12.16] section, so it now sits under ## [Unreleased] ### Fixed. No released section was edited.

Contract preserved after resolution — Ctrl+V stays the macOS primary chord and Command+V is not treated as guaranteed terminal input; Windows continues to accept Ctrl+V and Alt+V. scripts/generate-hotkeys-docs.ts regenerates clean against the resolved head (no diff).

Verification for head 4b22df698 against base dc13439be:

• bun test packages/coding-agent/test/custom-editor-keybindings.test.ts packages/coding-agent/test/keybindings-audit.test.ts packages/tui/test/keys.test.ts — 95 pass, 0 fail, 1041 assertions.
• bun --cwd=packages/tui run check and bun --cwd=packages/coding-agent run check — Biome and TypeScript clean.
• git diff --check — clean.

GitHub now reports MERGEABLE (was CONFLICTING/DIRTY). No Actions approval or merge was performed.

[Yeachan-Heo]

REQUEST_CHANGES — reviewed exact head 4b22df69822e18fe04989c28cf0827aa1eab9feb against refreshed origin/dev 427cef2a82fe15d790b63c9f0872f32c8b632d2d. The PR head is not based on the refreshed base (merge base 95c00d09e7f68fc39469c185a4019385f331676b), so its green checks do not validate the current integration target. GitHub reports the stale head clean, but that is not a substitute for testing an updated head.

Please rebase/update this external contributor branch onto current origin/dev, regenerate/verify the hotkey document, and re-run the affected check, TUI key parser, and custom-editor keybinding jobs before re-requesting review.

I inspected the full 10-file diff, key parser and dispatch contracts, generated-doc source/output, exact ancestry, contributor permissions, and all PR discussion/automation surfaces; no unresolved inline, review, Codex, or bot findings were present. The new Korean Kitty fallback itself is appropriately fail-closed (modified-only, exact modifier match, no base-layout metadata, releases excluded), and the changed exact-head CI jobs are green. Local virtual-merge test execution was blocked by this checkout lacking @gajae-code/natives; no product files remain modified.

—
[repo owner's gaebal-gajae (clawdbot) 🦞]

[needsbuilder]

Rebased onto current dev and force-pushed head a30fc935c. Regenerated and verified docs/keybindings.md. Local verification passed:

• bun --cwd packages/coding-agent run generate-hotkeys-docs --check
• bun test packages/tui/test/keys.test.ts packages/coding-agent/test/custom-editor-keybindings.test.ts packages/coding-agent/test/keybindings-audit.test.ts (95 pass)
• bun --cwd packages/coding-agent run check

Ready for exact-head re-review.