projmux 0.4.5 → 0.4.7

package/docs/native-picker-no-fzf-poc.md

@@ -0,0 +1,228 @@
+# Native Picker Engine
+
+This note tracks the native picker engine. Native is the default picker backend,
+while the `internal/ui/fzf` backend remains available as an explicit fallback.
+
+The fzf compatibility surface for the native engine is tracked in
+[native-picker-parity.md](native-picker-parity.md).
+
+## What This Covers
+
+- `internal/ui/picker` is the backend-neutral contract for native picker rows,
+  actions, filtering, and typed-query prompts.
+- `internal/ui/projmuxpicker` is the projmux-specific native picker surface for
+  frame, redraw updates, theme tokens, ANSI width/truncation,
+  prompt/footer/list rendering, and preview pane layout. The POC keeps `picker`
+  responsible for backend routing, keyboard input, filtering, preview command
+  execution, and result contracts, while moving visual composition into
+  `projmuxpicker` so projmux can evolve a native picker design without coupling
+  every visual tweak to the fzf adapter.
+- `internal/ui/fzf` now owns the adapter between fzf's legacy option/result
+  shape and the backend-neutral `picker.Options` contract. App code should
+  describe picker intent as rows, actions, preview commands, and initial focus;
+  the fzf adapter is responsible for translating that into `--expect`,
+  `--bind execute-silent(...)`, `+refresh-preview`, and `start:pos(N)`.
+- `intfzf.NewPickerRunner()` wraps fzf behind the same `picker.Runner`
+  interface as the native runner. This is the current DI boundary for swapping
+  picker engines while keeping fzf available.
+- Settings > Labs > Picker Engine stores the backend selection in
+  `~/.config/projmux/picker-backend` and updates the live tmux environment so
+  new picker popups can switch between `fzf` and `native` without restarting
+  the app server.
+- Native is the default backend. `PROJMUX_PICKER_BACKEND=fzf` remains an
+  explicit environment override and takes priority over the saved Labs setting.
+- Picker flows covered by the native path include AI picker/settings, shell
+  update prompt, settings hub sections, switch settings/add-pin, the main
+  project switcher list, recent sessions, and notify sidebar.
+- The native picker supports ranked fuzzy search/filter, arrow-key selection in
+  normal CSI and tmux application-cursor modes, Enter, Esc, Ctrl-C, Backspace,
+  Ctrl-U, Ctrl-W, PageUp/PageDown, Home/End, modified CSI keys, custom expect
+  keys such as Ctrl-X/Alt-P, printable expect keys such as notify `x`, control
+  expect keys such as notify `Ctrl-X`, `start:pos(N)` initial focus, preview
+  command output, preview cycle command bindings, and sidebar focus command
+  bindings.
+- FZF-style movement keys are supported for native selection: `Ctrl-N` moves
+  down, while `Ctrl-P` and `Ctrl-K` move up unless the app claims the key as a
+  custom action.
+- Typed-query prompts support cursor-aware insertion/deletion with a visible
+  prompt cursor, Left/Right, Ctrl-A/E, Delete, Backspace, Ctrl-U, and Ctrl-W
+  for settings path entry.
+- The native key parser recognizes the app's CSI-u keybind-probe sequences
+  such as `ESC [ 9005 u` for `Alt-1`, plus generic modified CSI-u forms such as
+  `ESC [ 115 ; 7 u` for `Ctrl-Alt-S`.
+- Native interactive picker screens use an alternate screen lifecycle to better
+  match fzf fullscreen behavior and restore the tmux pane after exit. Frame
+  updates and screen exit both return to column 0 before emitting terminal
+  control sequences, and screen exit resets styles plus clears the alternate
+  buffer from the home cursor before restore. This keeps restore/update escapes
+  and selected-session handoff output from visually trailing the bottom border
+  in tmux/script captures. Native also gives real TTY screen restore a short
+  settle window before returning to callers that may immediately draw a tmux
+  session.
+- Native interactive picker screens render inside a full-screen border frame to
+  match the app's fzf `--height 100% --border` surface more closely.
+- Popup-toggle commands use tmux `display-popup -B` when the native backend is
+  active so the native picker owns the visible frame and does not double-draw
+  with tmux's outer popup border.
+- Native Alt-1 sidebar popups use the same responsive width calculation as fzf
+  with a smaller native-only minimum, so the borderless native frame is not
+  wider than the existing fzf sidebar surface on normal terminals.
+- Native Alt-2 notify sidebar popups keep the fzf baseline width contract
+  (`24%`, minimum `64`) while still letting the native picker own the frame.
+- Native sidebar popups reserve two rows at the bottom for the tmux statusbar
+  area instead of using the full client height.
+- Simple native lists use the available terminal height after header, prompt,
+  footer, and preview reservations instead of a fixed page-sized viewport.
+- Navigation-only native lists mirror fzf `--disabled --no-input`: the input
+  prompt is hidden, printable non-action keys do not alter the query, and
+  expect/action keys still work.
+- Native frame content now uses the full inner border width so prompt/list/footer
+  separators reach the right border like fzf.
+- Native frames can render an optional picker-owned titlebar row below the top
+  border when `picker.Options.Title` is set; empty titles keep the default frame
+  unchanged. The native Alt-1 project sidebar uses this for a `Projects`
+  titlebar.
+- Native width/truncation uses terminal cell width for Korean/CJK text, emoji,
+  and combining marks instead of raw rune count, so localized project names and
+  decorated notify headers do not push the right frame border out of alignment.
+- Searchable native pickers draw an explicit `Search` label and a muted
+  separator under the prompt/count line so the query area reads as distinct
+  chrome rather than the first row of the list. Footer, down-preview, and
+  multi-line card gaps share the same `projmuxpicker` separator primitive for a
+  more consistent native surface.
+- Native interactive mode enables SGR mouse reporting while the alternate screen
+  is active. Primary click applies the clicked row, release events are ignored,
+  mouse wheel moves selection up/down, and reporting is disabled again during
+  screen restore.
+- When terminal size detection is unavailable, native picker falls back to a
+  conservative 80x24 terminal instead of assuming a wider surface. Interactive
+  tmux popups still use the detected popup size when `stty size` is available.
+- Simple and multi-line native rows share the same projmux current-row style and
+  pointer marker rather than falling back to terminal inverse video for simple
+  pickers.
+- Selected multi-line rows use the same pointer-width `▌` continuation marker
+  as the first selected project line, so switch/session/notify cards read as one
+  focused block.
+- Pointer and continuation markers render inside the current-row gutter style so
+  selected cards do not visually break between the marker and row content.
+- Native redraws use terminal synchronized-update wrappers and coalesced
+  row-diff updates after the first frame. The frame/redraw renderer lives in
+  `projmuxpicker` rather than the backend loop, skips unchanged frames, and
+  avoids a trailing newline after the bottom border. This reduces visible
+  keyboard-navigation flicker and prevents exact-height popups from scrolling
+  the top border off screen.
+- Native preview panes normalize tabs and control bytes before horizontal
+  clipping, preventing long preview rows from wrapping and consuming extra
+  vertical viewport rows in Alt-3/session popups.
+- Native sidebar list scrollbars use the fixed list viewport as their track and
+  measure multi-line cards in rendered rows, so the thumb does not shrink or
+  jump when card heights vary.
+- Switch picker git branch badges are capped more tightly for the native card
+  surface, so inactive branch backgrounds do not dominate narrow Alt-1 sidebar
+  rows.
+- Native selection changes render their frame diff before running sidebar focus
+  commands, so tmux focus/switch side effects do not delay the visible picker
+  movement.
+- In app TTY contexts, the native picker opens the controlling terminal
+  (`/dev/tty`) before entering raw mode. This avoids stdin/stdout mismatch and
+  line-mode escape leakage such as arrow keys appearing as `^[[`.
+- Raw TTY reads keep polling briefly across empty reads while decoding
+  escape-key sequences, so split arrow/Alt key bytes are consumed by the picker
+  instead of leaking into the query or parent shell.
+
+## Experimental Boundaries
+
+- The `projmuxpicker` package is intended as a foundation that can be carried
+  forward, along with the fzf-to-picker adapter boundary in `internal/ui/fzf`.
+  Its frame, row, preview, theme, ANSI, and redraw modules are foundation code;
+  Docker sandbox scripts and dependency-policy notes remain support
+  scaffolding.
+- Switch and sessions preview panes are native previews for the concrete
+  projmux option shapes. Wide right-side preview windows render beside the
+  list, and sidebar-style `down,25%,border-top` previews render below the list
+  without a synthetic preview title row, using fzf-measured percent sizing.
+  Preview rows are padded by `projmuxpicker` to the full preview surface width
+  before the outer frame is applied, which keeps split/down preview columns
+  visually stable during redraws.
+  The full fzf preview-window grammar remains outside this POC surface.
+- Preview cycle state is covered in Docker e2e against real tmux sessions: the
+  switch and sessions popup flows type a filtered query, send `Right` and
+  `Alt-Down`, and assert the stored preview window/pane cursor for the selected
+  session.
+- Public doctor dependency policy remains separate from picker backend
+  selection. Native is the default picker backend, and fzf remains available as
+  an explicit fallback.
+
+## Interactive No-fzf Sandbox
+
+Use this when you want to enter a Docker container and experience this build
+directly without `fzf`. It builds the no-fzf dependency image, mounts this
+worktree, builds `projmux` inside the container, creates sample projects under
+`/workspace/projects`, stores the native picker backend in the sandbox config,
+writes a tmux config with the same backend in the tmux server environment, and
+launches `projmux shell`. It also forces UTF-8 locale inside the container. This
+uses `wt path` instead of `wt run` because `docker run -it` needs the current
+terminal TTY:
+
+```sh
+bash "$(wt path poc/native-picker-no-fzf)/scripts/poc-native-picker-no-fzf-sandbox.sh"
+```
+
+Inside the tmux shell, try:
+
+```sh
+projmux switch
+projmux settings
+projmux doctor --json
+```
+
+Manual UX checks for the Docker sandbox:
+
+- Alt-1 opens with the top border/title visible, not clipped.
+- Vertical borders stay continuous while moving Up/Down.
+- Alt-1 closes the sidebar immediately when pressed again.
+- Alt-2, Alt-3, Alt-4, and Alt-5 open their matching native popups and close
+  on the same Alt key immediately.
+- Arrow keys move selection without leaking `^[[` text into the query.
+
+`fzf` is intentionally not installed in the image.
+
+## Automated No-fzf Docker E2E Command
+
+Run this from the repository root. It builds a Go 1.24 Trixie no-fzf
+dependency image from `test/docker/no-fzf-poc.Dockerfile`, including Go module
+cache, then mounts the repository into an isolated `--network none` container,
+builds `projmux`, asserts `fzf` is not on `PATH`, runs the focused native-picker
+tests, stores the native backend through Settings > Labs, verifies the saved
+backend works without an env override, exercises `projmux switch --ui=sidebar`
+search/selection under a container PTY,
+exercises `projmux switch --ui=popup` and `projmux sessions --ui=popup` against
+existing tmux sessions under a wide 150x30 PTY, sends `Right` and `Alt-Down`
+once to smoke the preview-cycle bindings, asserts those popup flows stay on the
+right-side preview layout instead of falling back to inline preview, asserts the
+explicit `Search` chrome across the searchable native picker surfaces, launches
+`projmux shell` under a container PTY, verifies
+that it creates a tmux session, verifies immediate launch-key close behavior for
+Alt-1 through Alt-5 native popup surfaces, exercises `notify list --ui=sidebar`
+with the printable `x` expect key, and exercises the settings picker under a PTY
+using Enter and arrow-key navigation through the native backend. Settings flows
+must keep stderr clean in the no-tmux-server container; tmux no-server noise is
+treated as an e2e failure.
+
+Short tmux-friendly form:
+
+```sh
+wt run poc/native-picker-no-fzf -- scripts/poc-native-picker-no-fzf-e2e.sh
+```
+
+The script contains the Docker image build and isolated `docker run` command:
+
+```sh
+scripts/poc-native-picker-no-fzf-e2e.sh
+```
+
+To compare another base image without editing the repo, override the build arg:
+
+```sh
+PROJMUX_POC_NO_FZF_BASE_IMAGE=golang:1.24-bookworm bash "$(wt path poc/native-picker-no-fzf)/scripts/poc-native-picker-no-fzf-sandbox.sh"
+```

package/docs/native-picker-parity.md

@@ -0,0 +1,145 @@
+# Native Picker fzf Parity Map
+
+This audit note reverse-engineers the subset of fzf behavior that projmux
+currently uses and maps it to native picker evidence. It supports the default
+native picker engine and is not a public dependency-policy change.
+
+## App fzf Surface
+
+| fzf surface | projmux usage | Native status | Evidence |
+| --- | --- | --- | --- |
+| `--prompt` | AI, settings, shell update, switch, sessions, notify | Covered | `renderNativeInteractive`, `renderNative`; `TestNativePromptLineIncludesInlineMatchCount` |
+| prompt/list separation | native searchable picker chrome | Covered | native renders an explicit `Search` header label plus a separator under searchable prompt/count lines; `TestNativeInteractiveSeparatesSearchHeaderFromList`; Docker no-fzf e2e asserts the `Search` header in Settings, AI settings, mouse-click, switch sidebar, switch popup, sessions popup, and shell Alt-1 PTY logs |
+| `--height 100%` / `--border` | all interactive picker screens | Covered for fullscreen rounded border frame | `renderNativeFrame`; screen-height list budgeting; conservative 80x24 fallback only when terminal size detection is unavailable; `TestNativeInteractiveRendersBorderFrame`; `TestNativeInteractiveUsesAvailableHeightForSimpleLists` |
+| `--header` | AI, settings, shell update, notify | Covered | `renderNativeInteractive`, `renderNative`; settings native tests |
+| `--footer` / `--footer-border line` | AI, settings, shell update, switch, sessions, notify | Covered for interactive native screens | `renderNativeInteractive` reserves bottom footer space and renders a separator line; `TestNativeInteractiveRendersFooterAtBottom` |
+| `--ansi` | colored row labels from render package | Covered | native writes row labels directly, strips ANSI escapes from default search text, restores selected-row styling after embedded ANSI resets, and measures rendered cell width for Korean/CJK text, emoji, and combining marks; `TestFilterItemsIgnoresANSIEscapeSequences`; `TestNativeInteractiveUsesCurrentStyleForSimpleSelection`; `TestVisibleLenUsesTerminalCellWidth`; Docker e2e shows ANSI rows |
+| hidden value after tab delimiter | all picker selections and default fzf matching | Covered by `picker.Item.Value` and default search text | `fzf.PickerOptions`; `TestNativeRunnerFiltersAndSelectsByNumber`; `TestFilterItemsSearchesHiddenValueWhenNoSearchKey` |
+| plain fzf candidates without structured entries | legacy runner call shape | Covered | `fzf.PickerOptions`; `TestPickerOptionsFromFZFMapsCandidatesWhenEntriesAreEmpty` |
+| search key filtering (`--nth`/reload filter file) | switch/sessions/notify entries | Covered by `Item.SearchText` with fzf reload order preservation | `FilterItems`; `TestFilterItemsUsesSearchTextNotMetadata`; `TestFilterItemsPreservesSearchKeyOrder` |
+| default `--smart-case` matching | all searchable picker rows | Covered | native filter keeps lower-case queries case-insensitive and uppercase queries case-sensitive; `TestFilterItemsUsesFZFSmartCase` |
+| fzf match highlighting | searchable simple picker rows | Covered for non-search-key simple rows | native highlights matched visible label runes while preserving embedded ANSI style; search-key reload lists intentionally keep fzf disabled-filter rendering without match highlights; `TestNativeInteractiveHighlightsSimpleQueryMatches`; `TestNativeInteractiveDoesNotHighlightSearchKeyReloadLists` |
+| `--disabled --no-input` | navigation-only notify sidebar | Covered | native suppresses prompt/query editing and ignores printable non-action input; `TestNativeInteractiveDisableSearchIgnoresPrintableInput`; Docker no-fzf e2e asserts notify prompt is hidden |
+| fuzzy result ranking | simple non-search-key picker UX | Covered with fzf V2 dynamic scoring for normal app rows | `fuzzyScore`; `TestFilterItemsRanksBetterMatchesFirst`; `TestFilterItemsPrefersFZFBoundaryAndCamelCaseMatches`; `TestFuzzyScoreMatchesFZFV2ReferenceScores` |
+| `--scrollbar █` | long switch/session/settings lists | Covered for app lists | `nativeListLinesWithScrollbarRows`; proportional multi-row thumb rendering in `projmuxpicker`; split-preview and sidebar list viewports keep a fixed row budget and scrollbar track; multi-line cards use rendered-row scroll units; `TestNativeInteractiveUsesScrollbarForLongLists`; `TestListLinesWithScrollbarUsesProportionalThumb`; `TestListLinesWithScrollbarMovesThumbGradually`; `TestListLinesWithScrollbarRowsKeepsViewportTrack`; `TestRenderSplitPreviewRowsKeepsRequestedViewport`; `TestNativeListScrollbarUnitsUseRenderedRowsForMultiline`; `TestNativeInteractiveKeepsMultilineScrollbarOnViewportTrack` |
+| `--read0` multi-line rows | switch, sessions, notify | Covered | `Options.MultiLine`; `TestNativeInteractiveRendersFZFLikeMultilineSelection` |
+| `--gap --gap-line ─` | switch, sessions, notify multi-line rows | Covered for app multiline rows | `nativeGapLine`, row-budgeted range; `TestNativeInteractiveRendersMultilineGapLine`, `TestNativeVisibleRangeCountsMultilineRenderedRows` |
+| selected multi-line marker | selected switch/session/notify cards | Covered for app multiline rows | native uses the same compact pointer-width red `▌` gutter as the first selected project line, and metadata lines align to the project-name column without the old deeper indent; `nativeContinuation`; `TestNativeInteractiveRendersSelectedMultilineContinuationMarker`; `TestInteractiveRowLinesUsesCompactSelectedMetaIndent`; `TestInteractiveRowLinesAlignsUnselectedMetaWithProjectName` |
+| fzf current row colors | simple and multi-line rows | Covered for app rows | `nativeCurrentStart`, `nativePointer`; pointer/continuation gutter tokens carry the current-row background; `TestNativeSelectedContentKeepsCurrentStyleAfterReset`; `TestNativeInteractiveUsesCurrentStyleForSimpleSelection` |
+| `--expect` keys | Enter/Ctrl-X/Alt-P/notify keys | Covered | `fzf.PickerOptions`; `TestNativeInteractiveSupportsCustomExpectKeys` |
+| printable expect keys | notify sidebar `x` ack | Covered | `TestNativeInteractiveSupportsPrintableExpectKeys`; Docker no-fzf e2e |
+| control expect keys | notify sidebar `Ctrl-X`, settings `Ctrl-Alt-S` close | Covered | `TestNativeInteractiveSupportsControlExpectKeys`; `TestNativeInteractiveSupportsControlAltCloseKeys` |
+| close `--bind key:abort` | Esc, Ctrl-C, Alt-N, Ctrl-Alt-S variants | Covered | `CloseActions`; `TestNativeRunnerUsesSharedCloseActions` |
+| terminal CSI-u key encoding | app keybind probe sequences, Ghostty/kitty-style modified keys | Covered | native handles app-specific Alt keys, generic modified letters/digits, and non-text keys such as Enter/Esc/Backspace/Tab; `TestNativeInteractiveSupportsCSIuAppKeyBindings` |
+| `execute-silent(...)+refresh-preview` | switch/session preview cycling | Covered for command execution and rerender loop | `fzf.PickerOptions`/`fzf.OptionsFromPicker`; `TestNativeInteractiveRunsCustomActionCommandAndRefreshes`; `TestPickerOptionsMapsFZFBindingsToContractActions`; Docker no-fzf e2e sends `Right` and `Alt-Down` before selection |
+| `focus:execute-silent(...)` | switch sidebar focus | Covered | native renders the selection frame diff before running sidebar focus commands so movement stays visible before tmux focus side effects; `runNativeFocusAction`; `TestNativeInteractiveRunsFocusActionOnSelectionChange` |
+| `start:pos(N)` | switch sidebar initial row | Covered | `fzf.PickerOptions`/`fzf.OptionsFromPicker`; `TestPickerOptionsFromFZFMapsStartPosToInitialIndex`; `TestPickerOptionsMapsFZFBindingsToContractActions` |
+| `--preview` | switch, sessions | Covered by command output | `nativePreviewLines`; `TestNativeInteractiveRendersSelectedPreview` |
+| `--preview-window right,60%,border-left` | switch popup, sessions popup | Covered for projmux option shape | `renderNativeSplitPreview` renders a single-column left border without a synthetic title row, uses fzf-measured percent sizing, normalizes preview tabs/control bytes before clipping, and pads both panes to fixed row widths so long preview rows do not wrap into extra vertical rows; `TestNativeInteractiveRendersWidePreviewBesideList`; `TestNativePreviewWidthUsesPreviewWindowPercent`; `TestRenderSplitPreviewRowsPadsBothPanes`; `TestRenderSplitPreviewRowsNormalizesPreviewTabsBeforeTruncating` |
+| `--preview-window down,25%,border-top` | switch sidebar | Covered for projmux option shape | `renderNativeDownPreview` renders an immediate top border without a synthetic title row, uses fzf-measured percent sizing, and pads preview rows to the surface width; `TestNativeInteractiveRendersDownPreviewBelowList`; `TestNativePreviewHeightUsesPreviewWindowPercent`; `TestRenderDownPreviewPadsPreviewRows` |
+| preview scrolling | long switch/session preview output | Covered for keyboard preview scroll | `previewOffset`; `TestNativeInteractiveRendersPreviewOffset` |
+| `--query` | typed settings path defaults | Covered | `Options.InitialQuery`; settings tests |
+| `--print-query` accept-query mode | typed settings path prompts | Covered | `Options.AcceptQuery`; `TestNativeRunnerAcceptsTypedQuery` |
+| query cursor editing | typed settings path prompts | Covered | Left/Right, Ctrl-A/E, Delete, Backspace, Ctrl-U/W query editing plus visible prompt cursor; `TestNativeInteractiveEditsTypedQueryAtCursor`; `TestNativeInteractiveSupportsQueryLineEditingKeys`; `TestNativeInteractiveCtrlUDeletesBeforeCursor`; `TestNativePromptLineRendersQueryCursor` |
+| terminal arrow key variants | interactive selection in tmux/docker | Covered | CSI, SS3/application cursor, modified CSI tests; app TTY `/dev/tty` fallback; raw TTY EOF polling keeps split ESC sequences from leaking into the query |
+| mouse support | optional fzf mouse picker interaction | Partially covered | native enables SGR mouse reporting in interactive alternate-screen mode, primary click applies the clicked row, release events are ignored, and wheel input moves selection; drag gestures remain outside this POC; `TestNativeInteractiveSupportsMouseClickSelection`; `TestNativeInteractiveIgnoresMouseReleaseBeforeClick`; `TestNativeInteractiveSupportsMouseWheelSelection`; Docker no-fzf e2e clicks the AI settings row under a PTY |
+| fzf navigation keys | interactive selection in searchable lists | Covered | native maps CSI-u `Ctrl-J` plus `Ctrl-N` to down and `Ctrl-P`/`Ctrl-K` to up when not claimed by a custom action; raw LF remains Enter for PTY compatibility; `TestNativeInteractiveSupportsFZFNavigationKeys` |
+| alternate-screen lifecycle | fzf fullscreen picker screen restore | Covered | native frame updates and screen exit return to column 0 before terminal control sequences, screen exit resets styles plus clears the alternate buffer from the home cursor before restore, and real TTY restores get a short settle window before caller handoff; `nativeScreenEnter`; `TestNativeInteractiveUsesAlternateScreen`; `TestRenderFullFrameUpdateAlwaysHomesAndWritesFrame` |
+| frame content width | fzf border inner width | Covered | `ContentLayout` uses the frame inner width so separators and rows reach the right border; `TestRendererContentLayoutUsesFrameInnerWidth` |
+| tmux popup frame interaction | native picker popups launched through `popup-toggle` | Covered for native backend popups | `popup-toggle` passes tmux `display-popup -B` when `PROJMUX_PICKER_BACKEND=native`, so the native picker owns the visible frame instead of double-drawing with the tmux popup border; native Alt-1 uses a compact native-only minimum while fzf keeps the previous project sidebar minimum; Alt-1/Alt-2 sidebar heights reserve two bottom statusbar rows; Alt-2 notify sidebar keeps the fzf-like `24%` / min `64` baseline; `TestAppRunTmuxPopupToggleUsesBorderlessPopupForNativeBackend`; `TestSessionizerSidebarWidthKeepsFZFMinimum`; `TestSidebarPopupHeightLeavesStatusbarRows`; `TestNotifySidebarWidthMatchesFZFBaseline`; `TestAppRunTmuxPopupToggleKeepsNotifySidebarFZFSizingForNative` |
+| optional native titlebar | native picker popup frame | Covered for empty-title compatibility and opt-in titles | `picker.Options.Title`; `RenderFrameWithTitle`; `ContentLayoutWithTitle`; empty titles keep the prior frame unchanged, non-empty titles render in a picker-owned row below the top border, and the native Alt-1 project sidebar opts into `Projects`; `TestRendererRenderFrameWithTitleKeepsDefaultWhenTitleEmpty`; `TestRendererRenderFrameWithTitleUsesTitlebarRow`; `TestRendererContentLayoutWithTitleReservesTitlebarRow`; `TestNativeInteractiveRendersOptionalTitlebar`; `TestSwitchCommandNativeSidebarSetsTitle` |
+| redraw flicker/top clipping | keyboard navigation in exact-height tmux popup | Partially covered | native redraws use synchronized updates plus coalesced row diffs after the first frame, skip unchanged frames, render frame diffs before sidebar focus commands, frame rendering avoids trailing bottom-border CRLF, and screen exit clears the alternate buffer before restore; `TestNativeInteractiveWrapsRedrawsInSynchronizedUpdates`; `TestFrameUpdateRendererSkipsUnchangedFrame`; `TestFrameUpdateRendererCoalescesEachFrameUpdate`; `TestRendererRenderFrameUsesCRLFRowsForRawTTY`; `TestNativeInteractiveUsesAlternateScreen` |
+
+## Native Surface Architecture
+
+- `internal/ui/picker` remains the backend-neutral contract and owns fzf/native
+  routing, keyboard input, fuzzy filtering, action dispatch, preview command
+  execution, and result handling.
+- `internal/ui/projmuxpicker` owns projmux-native visual composition: frame,
+  redraw updates, ANSI width/truncation, theme tokens, prompt/footer/list
+  rendering, selected row styling, scrollbars/gap rows, and preview pane
+  geometry/rendering.
+- `internal/ui/fzf` owns the compatibility adapter in both directions:
+  `picker.Options` becomes fzf flags/bindings for fallback, and legacy
+  `fzf.Options` becomes `picker.Options` for the native backend. This keeps app
+  code closer to a DI-style picker contract instead of embedding fzf binding
+  strings at each call site.
+- `intfzf.NewPickerRunner()` adapts fzf to the same `picker.Runner` interface
+  as `picker.NativeRunner`, so follow-up branches can inject either backend at
+  a narrower boundary without deleting the existing fzf runner.
+- Settings > Labs > Picker Engine persists the selected backend in
+  `~/.config/projmux/picker-backend` and updates the live tmux server
+  environment through `PROJMUX_PICKER_BACKEND`, while direct environment
+  overrides still win over saved config. Native is the default when no saved
+  backend or override exists; `fzf` remains available as an explicit fallback.
+- The split lets projmux grow a first-party picker design independently from
+  the fzf compatibility adapter.
+
+## Verified Flows
+
+- `ai` picker/settings: native backend routing covered by app tests. Docker
+  no-fzf e2e also types `Codex` into `projmux ai settings` and verifies the
+  native simple picker writes the `codex` mode without fzf.
+- `shell` update prompt: native backend routing covered by shared fzf-to-native
+  adapter and settings-style typed prompt tests.
+- `settings`: native backend exercised in unit tests and Docker no-fzf e2e
+  using Enter plus arrow-key navigation under a PTY. The Docker e2e also fails
+  if the Settings flows write tmux no-server noise to stderr while running
+  outside tmux.
+- `settings > Labs`: unit-covered backend toggle writes
+  `~/.config/projmux/picker-backend`, updates the tmux global
+  `PROJMUX_PICKER_BACKEND`, and lets env override saved config.
+- `switch --ui=sidebar`: Docker no-fzf e2e creates sample projects, types
+  `bravo`, selects `bravo-web`, and confirms the opened tmux shell path.
+- `switch --ui=popup`: Docker no-fzf e2e creates existing tmux sessions using
+  the app's session naming convention, runs the picker under a 150x30 PTY,
+  types `bravo`, sends `Right` and `Alt-Down` to exercise preview window/pane
+  cycle, asserts the popup stays on the right-side preview layout instead of
+  inline preview, asserts the stored preview cursor, selects `bravo-web`, and
+  asserts tmux reports the selected session's active target on the expected
+  window with the expected pane path.
+- `sessions --ui=popup`: Docker no-fzf e2e creates existing tmux sessions,
+  runs the picker under a 150x30 PTY, types `bravo`, sends `Right` and
+  `Alt-Down` to exercise preview window/pane cycle, asserts the popup stays on
+  the right-side preview layout instead of inline preview, asserts the stored
+  preview cursor, selects `bravo-web`, and asserts tmux reports the selected
+  session's active target on the expected window with the expected pane path.
+- `notify sidebar`: native routing is unit-covered; Docker no-fzf e2e pushes a
+  notification, presses printable expect key `x`, and verifies the row is acked.
+
+## Experimental Boundaries
+
+- Preview-window parity is covered for the concrete projmux option shapes
+  (`right,60%,border-left` and `down,25%,border-top`) with fzf-measured percent
+  sizing. The full fzf preview-window grammar, threshold alternatives, sticky
+  headers, and offset expressions are intentionally outside this POC surface.
+- fzf V2 dynamic scoring is covered for normal app-length non-search-key
+  rows, including reference scores for boundary, delimiter, camelCase/number,
+  gap, and consecutive bonuses. Very large `query * row` matrices intentionally
+  fall back to the greedy scorer to avoid pathological memory use. Search-keyed
+  app pickers preserve fzf's `--disabled` reload order instead of score-sorting.
+- Mouse support is intentionally narrow in this POC: primary click applies the
+  clicked row, release events are ignored, and wheel input moves selection.
+  Drag gestures and the full fzf mouse grammar are follow-up work.
+- The public doctor/docs dependency policy is tracked separately from picker
+  backend selection. Native is the default picker backend, while fzf remains an
+  explicit fallback.
+- Draft PR: https://github.com/crevissepartners/projmux/pull/98.
+
+## Commands
+
+Automated no-fzf e2e:
+
+```sh
+wt run poc/native-picker-no-fzf -- scripts/poc-native-picker-no-fzf-e2e.sh
+```
+
+Interactive no-fzf sandbox:
+
+```sh
+bash "$(wt path poc/native-picker-no-fzf)/scripts/poc-native-picker-no-fzf-sandbox.sh"
+```
+
+Do not run the interactive sandbox through `wt run`: current `wt run` captures
+child stdio instead of forwarding the caller's TTY, so Docker cannot attach
+`-it` and terminal picker input will not behave like a real session.

package/docs/notify-queue.md

@@ -0,0 +1,200 @@
+# Notify queue
+
+`projmux` keeps a persistent JSON queue of pending AI notifications.
+`attention` is live tmux pane state; `notify` is the user's pending
+notification source of truth. The queue is derived from live state and user
+pushes, but an entry remains pending until explicit ack. Each entry can route
+the status-bar notify segment or notify sidebar to the originating tmux pane
+via `projmux focus`, and feeds the HUD pill rendered by
+`projmux status notify`.
+
+## File layout
+
+```
+${XDG_STATE_HOME:-$HOME/.local/state}/projmux/notify.json
+${XDG_STATE_HOME:-$HOME/.local/state}/projmux/notify.json.lock
+```
+
+The lock file is acquired via `O_CREATE|O_EXCL` with bounded retry
+(default ~200 attempts, 2ms–50ms jittered backoff) and a 30s
+stale-after window so a crashed writer never permanently wedges the
+queue.
+
+The queue file is a pretty-printed JSON array of `Notification`
+objects, sorted newest-first on read. `expires_at` is freshness metadata;
+expired entries are not filtered or deleted by `list`.
+
+## Data model
+
+`internal/core/notify`:
+
+```go
+type Notification struct {
+    ID        string    // stable key for dedupe / ack
+    Text      string    // capped at 80 runes
+    Severity  string    // info | warn | critical
+    Source    string    // ai | k8s | git | external
+    CreatedAt time.Time
+    ExpiresAt time.Time
+    Target            // session, window, pane, socket
+}
+
+type Target struct {
+    Socket  string  // tmux -L socket path; empty = default
+    Session string
+    Window  string  // optional; "" means session-only
+    Pane    string  // optional; "" means window-level
+}
+```
+
+Defaults: `DefaultTTL = 600s`, `MaxTextLength = 80`. TTL is retained as a
+freshness/display field, not a removal condition. `Severity` and
+`Source` are validated against the constants above; an invalid value
+returns `ErrInvalidSeverity` / `ErrInvalidSource` which the CLI maps to
+exit code 2.
+
+## CLI surface
+
+### push
+
+```
+projmux notify push --text <s> --target <SESSION[:WINDOW[.PANE]]>
+                    [--socket <s>] [--severity info|warn|critical]
+                    [--source ai|k8s|git|external]
+                    [--ttl <seconds>] [--id <s>] [--json]
+```
+
+Appends one entry. With `--id` an existing entry is overwritten in
+place (text + timestamp refresh), enabling idempotent producers like
+the AI reply-ready transition. `--ttl` accepts a positive integer
+number of seconds. `--json` prints `{id, queued}` for scripting.
+
+### list
+
+```
+projmux notify list [--live] [--json] [--limit N] [--ui table|sidebar]
+                    [--severity ...] [--source ...]
+```
+
+Newest-first pending queue entries. Default output is the tab-aligned
+table `ID AGE SEV SRC TARGET TEXT`. `--severity` / `--source` are
+repeatable filters. Without `--live`, this command reads only the queue and
+preserves the stable JSON array used by scripts.
+
+`--ui=sidebar` opens the notify queue as an interactive right-side list when
+run inside the tmux popup surface. Enter focuses the selected target pane and
+acks the row after focus succeeds. `x` acks the selected row. `Ctrl-X` clears
+all rows via `notify ack --all`. Rows are intentionally compact: the visible
+label keeps notification text first, then age, project, window, and pane
+metadata; hidden queue ids remain action values but the sidebar has no search
+input.
+
+`--live` adds a non-mutating explanation view that reads
+`tmux list-panes -a` and compares the queue with live reply-state panes. It
+does not push, ack, or otherwise repair anything. Human output keeps the
+queue table and adds a `STATE TARGET ID EXPLANATION TEXT` section; JSON
+output becomes `{queue, live, rows, errors}`. Typical states:
+
+- `live-manual-reply` — a live reply/green badge exists, but no queue entry
+  is expected because the pane has no AI agent metadata.
+- `live-ai-reply-queued` — a live AI reply pane has the matching actionable
+  queue entry.
+- `live-ai-reply-missing-queue` — a live AI reply pane lacks the derived
+  queue entry; run `projmux notify reconcile` to back-fill it.
+- `queue-stale` — an `ai:` queue entry exists, but the live pane no longer
+  matches reply+agent state; it remains pending until explicit ack.
+- `queue-only` — a non-AI/external queue entry is pending and has no live AI
+  reply-pane requirement.
+
+To inspect live pane attention without queue context, use
+`projmux attention list`.
+
+### ack
+
+```
+projmux notify ack <id>
+projmux notify ack --all
+```
+
+Removes one entry by id, or flushes the queue. `--all` returns the
+removed count.
+
+### reconcile
+
+```
+projmux notify reconcile [--json]
+```
+
+Walks `tmux list-panes -a -F` with the producer-key format (session,
+window id, pane id, attention state, AI state, agent, topic, socket
+path), then:
+
+- pushes/refreshes one `ai:<session>:<pane>` entry for every pane
+  whose attention state is `reply` AND whose agent option is non-empty;
+- reports every existing queue entry whose id starts with `ai:` and whose
+  pane no longer matches that condition as stale, without acking it.
+
+Soft-fails when tmux is not running (returns a populated `errors`
+field rather than a non-zero exit) so the post-install hook does not
+break. Run this as the recovery path when the on-disk queue has drifted
+from live pane state.
+
+Output: `reconcile: pushed N, acked M, kept K, stale S`.
+
+Ack behavior is intentionally queue-local: only `ack` removes explicit ids or
+flushes the queue. TTL is freshness metadata, and `reconcile` only repairs
+derived `ai:` entries. Manual attention badges without agent metadata remain
+live attention only.
+
+## Producer (AI reply-ready)
+
+`internal/app/notify_producer.go`. The attention state machine calls
+`PushReplyReady` when a pane flips to `reply`. The producer reads
+`@projmux_ai_pane_agent`, `@projmux_ai_pane_topic`, `#S`,
+`#{window_id}`, `#{pane_id}`, `#{socket_path}` off the pane and writes
+an entry with:
+
+- id: `ai:<session>:<pane>`
+- text: `<agent>: <topic>` (or `<agent>: ready` when no topic is set)
+- severity: `info`, source: `ai`, freshness TTL: 10 minutes
+
+When the pane leaves the reply state (manual `attention clear`,
+`status set idle`, or a window close), `AckReplyReady` intentionally does not
+remove the entry. The user consumes it through explicit ack. Store errors are
+swallowed so the live tmux UI never blocks on disk IO.
+
+Manual `projmux attention toggle` on a pane without an agent option
+does NOT push — the queue is intentionally AI-driven; reconcile honours
+the same contract.
+
+## Consumer (status-bar click)
+
+`internal/app/statusbar.go::handleNotify`. A click on the notify range
+or the `prefix s n` chord reads the newest queue entry and dispatches:
+
+```
+projmux focus --target <target> --source status-bar --kind segment-click [--socket <s>]
+```
+
+Outcomes:
+
+- **Focus succeeded** — ack the entry. Focus is the single consume path for
+  routed notification clicks.
+- **Focus exited 2 (target unresolved)** — keep the entry pending and toast
+  `notify target gone; ack to clear`.
+- **Other failure** — keep the entry, toast `focus failed: <reason>`
+  so the user can retry without losing the row.
+
+The handler never returns a non-zero error to tmux's `run-shell`; every
+failure becomes a `display-message` toast so a transient miss does not
+trigger a tmux error popup.
+
+## Render (status segment)
+
+`projmux status notify` is the HUD-style renderer wired to the tmux
+status interval. See [statusbar.md](statusbar.md) for the layout and
+degradation tiers. It shows the newest pending item as a single notification
+block with project, state, optional agent, text, age, and an extra-count
+marker. Window/pane ids remain routable metadata but are not displayed in the
+compact HUD. The renderer is silent on every failure mode (no store, list
+error, empty queue) so the status line never carries a stack trace.