projmux 0.9.0 → 0.10.0

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

@@ -1,227 +0,0 @@
-# Native Picker Engine
-
-This note tracks the native picker engine. Native is the only picker backend.
-
-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 compatibility option/result shape.
-  Built-in fallback colors are centralized as semantic tokens in
-  `internal/theme/palette.go`; see [theme-palette.md](theme-palette.md) for the
-  current inventory and truecolor to tmux 256-color mapping policy.
-- `internal/ui/pickercompat` remains an internal compatibility mapper between
-  the old option/result shape and the backend-neutral `picker.Options`
-  contract. It is not a runtime backend. App code should
-  describe picker intent as rows, actions, preview commands, and initial focus,
-  then route through the native picker.
-- Settings > Labs remains available for Live system resources and Project
-  Hooks, but picker backend/source information has been retired.
-- 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 `a`/`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` and
-  `Ctrl-J` move down, while `Ctrl-P` and `Ctrl-K` move up unless the app claims
-  the key as a custom action. Up/down-family movement wraps at list boundaries;
-  PageUp/PageDown and Home/End remain clamped or explicit jumps.
-- 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 keeps legacy parser-fixture coverage for app-specific
-  modified-key escapes, plus generic modified forms such as `ESC [ 115 ; 7 u`
-  for `Ctrl-Alt-S`. This is backend parser parity, not a product fallback
-  route.
-- 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. Non-empty titles use a distinct neutral titlebar surface with rule
-  fill and a divider row separating the title section from the search/content
-  section. 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 mouse down focuses the row under the cursor, primary mouse
-  up applies it, 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 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 compatibility option/result mapping in
-  `internal/ui/pickercompat`.
-  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 no longer includes an external picker binary.
-
-## 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-4, Alt-5, and Alt-7 open their matching native popups and close
-  on the same Alt key immediately.
-- Alt-3 opens Recent Windows.
-- 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.25 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, opens Settings > Labs with legacy `fzf` env/file values, verifies native
-operation without a Labs picker-source row or config rewrite, 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

@@ -1,155 +0,0 @@
-# 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 | `pickercompat.PickerOptions`; `TestNativeRunnerFiltersAndSelectsByNumber`; `TestFilterItemsSearchesHiddenValueWhenNoSearchKey` |
-| plain fzf candidates without structured entries | compat option call shape | Covered | `pickercompat.PickerOptions`; `TestPickerOptionsFromCompatPickerMapsCandidatesWhenEntriesAreEmpty` |
-| 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 | `pickercompat.PickerOptions`; `TestNativeInteractiveSupportsCustomExpectKeys` |
-| printable expect keys | notify sidebar `a` ack and `x` non-critical clear | 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 modified-key encoding | legacy parser fixtures, Ghostty/kitty-style modified keys | Covered | native handles app-specific parser fixtures, generic modified letters/digits, and non-text keys such as Enter/Esc/Backspace/Tab; this is backend parity, not product fallback guidance; `TestNativeInteractiveSupportsCSIuAppKeyBindings` |
-| `execute-silent(...)+refresh-preview` | switch/session preview cycling | Covered for command execution and rerender loop | `pickercompat.PickerOptions`/`pickercompat.OptionsFromPicker`; `TestNativeInteractiveRunsCustomActionCommandAndRefreshes`; `TestPickerOptionsMapsCompatBindingsToContractActions`; Docker no-fzf e2e sends `Right` and `Alt-Down` before selection |
-| action-local/event-backed mutable refresh | notify sidebar `a` ack and `x` non-critical clear; notify sidebar queue-write event refresh; switch sidebar `Ctrl-X` kill | Covered for in-session row/live-state refresh without picker restart | `picker.Action.Mutate` returns a `DeferredUpdate`, notify queue-write events trigger the same `DeferredUpdate` path after an event arrives, and both reuse the native frame diff renderer plus value-then-clamp selection preservation; `TestNativeInteractiveCustomActionMutatesItemsAndRefreshes`; `TestNativeInteractiveCustomActionRefreshPreservesSelectedValue`; `TestNativeInteractiveDeferredUpdateTriggerRefreshesRepeatedly`; notify sidebar app tests assert one picker invocation with refreshed rows/live state and event subscription; switch sidebar kill app tests assert one native picker invocation with refreshed rows/preview and previous-live-session guard preservation |
-| `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 | `pickercompat.PickerOptions`/`pickercompat.OptionsFromPicker`; `TestPickerOptionsFromCompatPickerMapsStartPosToInitialIndex`; `TestPickerOptionsMapsCompatBindingsToContractActions` |
-| `--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; up/down movement wraps at list boundaries while PageUp/PageDown and Home/End remain clamped or explicit jumps; app TTY `/dev/tty` fallback; raw TTY EOF polling keeps split ESC sequences from leaking into the query; `TestNativeInteractiveWrapsPreviousNavigationKeys`; `TestNativeInteractiveWrapsNextNavigationKeys`; `TestNativeInteractiveJumpNavigationRemainsClamped` |
-| mouse support | optional fzf mouse picker interaction | Partially covered | native enables SGR mouse reporting in interactive alternate-screen mode, primary mouse down focuses the clicked row, primary mouse up applies it, and wheel input moves selection; drag gestures remain outside this POC; `TestNativeInteractiveSelectsOnMouseRelease`; `TestNativeInteractiveMouseDownOnlyFocuses`; `TestNativeInteractiveIgnoresMouseReleaseBeforeDown`; `TestNativeInteractiveSupportsMouseWheelSelection`; Docker no-fzf e2e clicks the AI settings row under a PTY |
-| fzf navigation keys | interactive selection in searchable lists | Covered | native maps modified-key `Ctrl-J` plus `Ctrl-N` to down and `Ctrl-P`/`Ctrl-K` to up when not claimed by a custom action; up/down-family movement is safe on empty lists; raw LF remains Enter for PTY compatibility; `TestNativeInteractiveSupportsFZFNavigationKeys`; `TestNativeInteractiveNavigationKeysAreNoopForEmptyList` |
-| 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` |
-| picker-owned app background | native picker frame interior | Covered for renderer-owned cells | `ThemeFromEffective` applies built-in fallback and explicit effective `surface` / `chrome_foreground` SGR to the native frame, and frame rows resume the app style after embedded resets so content padding, empty no-footer rows, footer rows, scrollbars, and preview gaps do not leak terminal default background; `TestThemeFromEffectiveFallbackPaintsFrameBackground`; `TestRendererFrameBackgroundResumesAfterContentResetBeforePadding`; `TestNativeInteractiveNoFooterBlankRowsUseThemeBackground`; `TestNativeInteractiveSplitPreviewGapsUseThemeBackground`; `TestNativeInteractiveSettingsAIBadgeStyleLongPreviewClampsFrameRows` |
-| 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; tmux 3.4 per-command `display-popup -s` is used for the popup body style, setting `bg` from `surface` and `fg` from `chrome_foreground` so tmux's blank/pre-draw popup body matches the native picker surface before the app renderer paints; no global `popup-style`, `popup-border-style`, shell pane background, `default-style`, `window-style`, OSC background, or status/window palette options are changed; 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`; `TestAppRunTmuxPopupToggleUsesNativePopupBodyStyleFromEffectiveTheme`; `TestBuildPopupToggleWithPickerBackendStylesNativeOnly`; `TestBuildDisplayPopupArgsAddsBodyStyle`; `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 section below the top border, titlebar text/divider/chip gaps inherit the frame `surface` / `chrome_foreground` instead of a separate titlebar overlay ANSI layer, 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 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/pickercompat` remains as the internal compatibility option/result
-  mapper from older app option shapes to `picker.Options` for the native
-  backend. It is not a runtime backend. This keeps app code closer to a
-  DI-style picker contract instead of embedding binding strings at each call
-  site.
-- Settings > Labs remains available for Live system resources and Project
-  Hooks, but no longer exposes picker backend/source information. Deprecated
-  saved/env backend values remain read-compatible and normalize to native.
-- The split lets projmux grow a first-party picker design independently from
-  the compatibility option/result mapper.
-
-## Frame Chrome ANSI
-
-Native picker frame chrome is normalized in `internal/ui/projmuxpicker`.
-Titlebar text, title dividers, and chip-strip gaps inherit the frame
-`surface` / `chrome_foreground` instead of applying a second titlebar overlay ANSI layer;
-chip bodies can still carry active/inactive/disabled tones. Search prompt and
-footer separators fill the available frame width, and header, row, footer, and
-preview lines close any active SGR style before padding or frame borders can
-inherit it. This phase does not add popup modes or change the `popup-toggle`
-contract; native popups still rely on the existing borderless tmux popup path.
-
-## 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 compat-to-native
-  bridge 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 and Docker no-fzf coverage assert only Live system
-  resources and Project Hooks are visible. The Docker smoke starts with legacy
-  `fzf` env/file values, verifies Settings still uses native without fzf, and
-  confirms the compatibility file is read without being rewritten.
-- `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; app tests cover
-  queue-write event subscription and picker tests cover repeated
-  event-triggered deferred refresh. Docker no-fzf e2e pushes a notification,
-  presses printable expect key `a`, 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 mouse down focuses
-  the clicked row, primary mouse up applies it, and wheel input moves selection.
-  Drag gestures and the full fzf mouse grammar are follow-up work.
-- The public doctor/docs dependency policy no longer includes an external
-  picker binary.
-- 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/picker-ui-plan.md

@@ -1,91 +0,0 @@
-# Picker UI Plan
-
-## Goal
-
-The project switcher needs a rich native picker surface. The target interaction
-is a card-like list where each item can show a title plus small contextual lines
-such as session state, window/pane summary, branch, or path. Search should stay
-focused on stable identity text, especially the project or session title,
-instead of matching every contextual preview line.
-
-## Current Contract
-
-The picker contract is split in two layers:
-
-- `internal/ui/picker` owns backend-neutral items, actions, preview metadata,
-  title-focused filtering, and the native runner.
-- `internal/ui/pickercompat` is an internal compatibility option/result shape
-  for older app call sites. It is not a runtime backend, and product flows do
-  not execute the external fzf binary.
-
-## fzf Capability Check
-
-This section is historical context. Earlier design work evaluated fzf because it
-supported multi-line items with `--read0`, where a single item can contain
-newline characters when input records are NUL-delimited.
-
-The simple fzf option path is not enough for the desired search behavior:
-
-- `--read0` can display multi-line items.
-- `--nth` can restrict search to selected fields.
-- `--with-nth` can transform the displayed fields.
-- In practice, once `--with-nth` is used to show a card field, fzf searches the
-  transformed visible text. Context lines become searchable.
-
-So fzf can support "multi-line cards", but not "multi-line cards with title-only
-search" through a small option-only extension while preserving the current
-selection contract.
-
-## Viable Paths
-
-### 1. fzf card approximation
-
-Use `--read0` and NUL-delimited multi-line entries. This is the smallest change,
-but contextual card text will participate in search unless the visible card is
-kept title-only. This does not meet the intended search model.
-
-This path is retired and is not supported.
-
-### 2. fzf custom filtering
-
-Run fzf in a more controlled mode where query changes reload a filtered list
-from `projmux`, and `projmux` performs title-focused matching. This keeps fzf as
-the renderer but moves filtering into the app.
-
-Tradeoffs:
-
-- More shell quoting and reload complexity.
-- More edge cases around selection identity and tracking.
-- Still constrained by fzf's list layout and event model.
-
-This bridge path is retired and is not supported.
-
-### 3. Native picker TUI
-
-Introduce a picker abstraction and implement a native terminal UI for card rows,
-title-focused search, stable selection identity, and app-owned key handling.
-
-This best matches the desired product direction:
-
-- card rows are first-class data, not encoded fzf strings
-- search fields are explicit
-- preview/context fields can be visible but non-searchable
-- future key behavior can be tested without relying on fzf internals
-
-## Implemented Direction
-
-Do not extend the retired fzf row format again. The previous hidden-field attempt
-showed that small fzf encoding changes can break selection and navigation in
-subtle ways.
-
-Current implementation:
-
-- Picker-domain model exists as `picker.Item` with `Title`, `Value`,
-  `SearchText`, `MetaLines`, `Badges`, and `PreviewTarget`.
-- `picker.Options` carries backend-neutral actions, preview metadata, prompt,
-  footer, initial query, and multiline intent.
-- Native is the picker backend and renders the popup/sidebar surfaces.
-- Native supports multiline item rendering, title-focused search via
-  `SearchText`, numeric selection, and shared close actions.
-- Switcher popup/sidebar use native preview panes, raw-key navigation, and
-  sidebar focus tracking.