docs/superpowers/plans/2026-09-05-native-chord-ergonomics.md

Ref: main worktree-web-client-spec   Size: 4.7 KiB   History

# Native split chords and End feedback

The user reported that selecting a split direction is normally followed by host
selection, and that prefix + x flashes an unidentifiable menu. This hands-on
feedback authorizes a bounded ergonomic trial; it does not accept prior recordings.

## Scope and acceptance

- Prefix + v/b arms the focused pane for side-by-side/below insertion and opens
  the host picker immediately. No geometry or session changes before selection.
- Esc in the host picker closes it while retaining the pending direction;
  another Esc outside the picker cancels it. Prefix + Enter remains available.
- End uses a status on its originating pane while awaiting the daemon. It opens
  no progress modal. A shared-session refusal still offers Cancel first and
  explicit End for all clients, bound to the original attachment.
- Pending requests cannot be duplicated; late replies cannot steal an active
  picker, command, resize, drag or recovery menu. The daemon protocol is unchanged.

Opening inspection found the existing controller and pending request identity
sufficient; no preparatory refactor is needed. Closing cleanup removes the
obsolete progress-menu variant instead of introducing a popup delay or timer.
Existing save-failure visibility remains a priority in narrow pane headers.

Luna owns controller/frame changes and unit coverage; Terra reviews the input
and request-lifetime contracts. Root owns integration fixtures, independent
validation, the recording and delivery records. Reused session metadata confirms
the selected models. Test helpers must exercise the direct v/b-to-picker path
rather than sending an extra prefix + Enter afterward.

## Validation and delivery

Implemented, independently reviewed, validated and accepted for merge. The user
said “this is excellent” and authorized merging the native branch. This accepts
the current result without asserting a separate hands-on trial of this build.
Both binaries were built together in ReleaseSafe at
`dist/native-chord-release`. The final GUI is also installed in `zig-out/bin/muxg`
for the user's next launch; an already running window keeps its earlier image.

- Native unit tests passed: 22 core and 28 frame/painter tests.
- Full `make ci` passed, including ten agent scenarios and throughput.
- `make native-e2e` passed on the final frozen source. The real delayed-daemon
  cases assert no progress popup in modal state or centre framebuffer pixels,
  preserve request identity, and exercise command, focus, picker, resize, drag,
  replacement, detach and accepted-End transitions.
- Separate real Wayland lifecycle checks and 200%/100%/150%/200% scale transitions
  passed, including independent kernel PTY dimensions and passive pixels.
- `make native-stress` passed after CI and recording completed. Over 30.2 seconds,
  it read 104.8 MB, with frame p99 19.920 ms before reopen and 19.388 ms afterward.
  Input-to-painted maxima were 55.5 ms on the separate daemon and 55.4 ms on the
  shared daemon, 95 samples each. The 5 ms polling and observation overhead make
  these upper bounds. No budget changed and no speed improvement is claimed.

The final 23.8-second actual GUI recording has one continuous clip, no cuts or
audio, at 200% scale. It shows both direct split chords, cancellation, fast End,
a delayed End header and Cancel-first shared-session confirmation. Input is
ordinary SDL events; this is not a new compositor mouse-path demonstration.
Video review caught an obsolete extra-chord hint; it now shows only the split
direction while the insertion picker is open. A replacement picker retains the
pending-arm hint, so it cannot be mislabeled as insertion.

Two fixture setup mistakes were corrected without product changes: the first
shell-suite Wayland launch lost its compositor address when the harness isolated
its runtime directory, and the first recorder omitted PTY observer registration.
The complete native suite used its standard offscreen setup; separate Python
Wayland fixtures preserve the compositor address correctly. Initial and final
logs are retained. The owned fixtures and compositor are cleaned up separately
from the user's sessions and desktop. No new macOS or SSH transport claim is made.

Artifacts, final source/binary hashes and model metadata are in `chord-evidence/`
beside this thread's visualization files. The retained video is
`native-chord-trial.mp4`. User approval explicitly confirmed tailnet ownership
and publication of this recording after automatic approval review blocked the
new payload. The verified page is
<https://charizard.folk-amberjack.ts.net/chord-trial/>; all prior routes remain.
Publication authorization was separate from the subsequent result acceptance
and merge authorization recorded above.