projmux 0.4.6 → 0.4.7

package/docs/agent-workflow.md

@@ -37,7 +37,7 @@
   actions, and `focus` dispatch diagnostics for session fallback, unresolved
   targets, window fallback, pane fallback, explicit id failures, and
   notify-only fallback.
-- Picker focused unit coverage includes backend-neutral picker item/action mapping, fzf adapter output, native title-focused filtering, numeric selection, and shared close actions.
+- Picker focused unit coverage includes backend-neutral picker item/action mapping, fzf adapter output, native title-focused filtering, numeric selection, shared close actions, saved picker backend config, Settings Labs backend switching, environment override precedence, compact multi-line metadata gutters aligned to the project-name column, proportional native scrollbar thumb rendering, fixed split-preview and sidebar list viewports with scrollbar tracks, preview tab/control normalization before width clipping, optional native frame titlebars, titled native Alt-1 sidebar chrome, statusbar-preserving sidebar popup height, native-only compact project sidebar popup sizing, and notify sidebar popup sizing that preserves the fzf minimum/ratio baseline.
 - `make test-integration`: Docker-backed Linux integration smoke with real `tmux`, `fzf`, `git`, and `stty`; covers `doctor`, tmux config print/install/apply, and notify queue CRUD against isolated HOME/XDG paths.
 - `make test-install-smoke`: Docker-backed source install smoke; covers `make install`, atomic binary replacement, `tmux apply` against a live `projmux` socket, and post-install notify queue initialization.
 - `make test-e2e`: Docker-backed real-tmux workflow smoke for session/pane setup, app config sourcing, reply-state notify reconciliation, focus notify fallback, and status notify rendering with contextual project/state/agent badges. Host-only terminal, WSL, macOS, and GUI notification behavior remains outside Docker; see [docs/testing.md](testing.md).

package/docs/architecture.md

@@ -44,8 +44,8 @@ Responsibilities:
 Picker data is modeled independently from fzf rows. The app builds
 backend-neutral `picker.Item` values (`Title`, `Value`, `SearchText`,
 `MetaLines`, `Badges`, `PreviewTarget`) and then adapts them to the selected
-backend. `fzf` remains the default, stable backend; the native backend is
-opt-in through `PROJMUX_PICKER_BACKEND=native` while it reaches full parity.
+backend. Native is the default backend, while `PROJMUX_PICKER_BACKEND=fzf`
+keeps the external fzf backend available as an explicit fallback.
 
 Responsibilities:
 - rows for popup and sidebar views

package/docs/cli.md

@@ -54,17 +54,15 @@ projmux switch toggle-tag | toggle-pin | kill | settings | preview
 projmux switch cycle-pane | cycle-window | sidebar-focus
 ```
 
-Project picker. With no positional argument, opens the fzf-driven popup or
-sidebar (depending on entry helper). With a path, jumps directly. The
+Project picker. With no positional argument, opens the configured picker popup
+or sidebar (depending on entry helper). With a path, jumps directly. The
 sub-verbs are entry hooks invoked by tmux keybindings (e.g.
 `sidebar-focus` is wired to the sidebar's focus binding so navigation keeps
 the active session in sync).
 
-`PROJMUX_PICKER_BACKEND=native` opts the switcher into the experimental native
-picker backend. fzf remains the default and the only backend with full preview
-pane, sidebar focus, and key-action parity. Native currently provides
-multiline card rendering, title-focused search, numeric selection, and the
-shared close-action contract.
+Settings > Labs > Picker Engine can switch between the default native picker
+backend and the external fzf fallback. `PROJMUX_PICKER_BACKEND=fzf` is supported
+as an environment override and takes priority over the saved Labs setting.
 
 ## setup
 
@@ -179,11 +177,11 @@ projmux notify reconcile [--json]
   reply badges that do not queue because no AI agent is attached, live AI
   reply panes missing a queue entry, matched AI reply entries, and stale
   queue entries whose live pane no longer matches. `--ui=sidebar` opens the
-  compact interactive notify list where Enter focuses and acks a target, `a`
-  acks the selected row, and `Ctrl-A` clears all; opening or navigating the
+  compact interactive notify list where Enter focuses and acks a target, `x`
+  acks the selected row, and `Ctrl-X` clears all; opening or navigating the
   sidebar does not ack. The sidebar uses two-line cards with notification text
-  first and compact age/project/window/pane metadata below, while keeping ids,
-  source, severity, and target details searchable.
+  first and compact age/project/window/pane metadata below. Hidden queue ids
+  remain action values, but the sidebar has no search input.
 - `ack <id>` removes one entry; `--all` flushes the queue.
 - `reconcile` — walks `tmux list-panes -a` and back-fills entries for
   panes whose attention state is `reply` AND whose AI agent option is
@@ -222,9 +220,11 @@ projmux status usage  [--max-width N] [--force|-f]
 projmux status notify [--max-width N]
 ```
 
-- `git` — `#[bold,fg=colour16,bg=colour45] <branch> #[default]` for the
-  pane's `pane_current_path` (or the supplied path). Empty when not in a
-  repo.
+- `git` — `#[bold,fg=colour16,bg=colour45] <branch> <state> #[default]` for
+  the pane's `pane_current_path` (or the supplied path). Empty when not in a
+  repo. `<state>` is omitted when clean, otherwise it may include `*` for
+  local changes, `+N` staged entries, and `↑N`/`↓N` ahead/behind counts, with
+  compact per-token colors in tmux output.
 - `kube` — `⎈ <context>/<namespace>` segment. Reads
   `~/.cache/tmux/kube-segment-<session>.txt` first (TTL governed by
   `TMUX_KUBE_CACHE_TTL`, default `5s`). Picks up a per-session
@@ -301,7 +301,7 @@ entry into the notify queue.
 ## tmux
 
 ```
-projmux tmux popup-toggle <mode>
+projmux tmux popup-toggle [--client <key>] <mode>
 projmux tmux popup-switch
 projmux tmux popup-sessions
 projmux tmux popup-preview <session>
@@ -317,7 +317,8 @@ projmux tmux apply
 Helpers tmux's keybindings and the install pipeline call into. Modes
 accepted by `popup-toggle` mirror the historical sessionizer surface:
 `session-popup`, `sessionizer`, `sessionizer-sidebar`,
-`ai-split-picker-right`, `ai-split-picker-down`, `ai-split-settings`.
+`notify-sidebar`, `ai-split-picker-right`, `ai-split-picker-down`,
+`ai-split-settings`.
 `apply` reloads the live `-L projmux` server's config without restarting
 it; `make install` and `projmux upgrade` invoke it after replacing the
 binary.
@@ -402,18 +403,20 @@ flags with the top-level `switch` UX:
 - `attach auto [--keep=N] [--fallback=home|ephemeral]` — auto-attach to
   the most recent session, with bounded retention and a fallback policy.
 - `settings` — interactive configuration UI for the project picker, AI
-  splits, Status Bar cwd/git decoration, Project Root management, the
-  switcher's saved workdirs list, and About/Update status. In Project Picker,
-  `Project Root` manages the saved
+  splits, Icons & Decorations mode, Project Root management, the
+  switcher's saved workdirs list, Labs, and About/Update status. In Project
+  Picker, `Project Root` manages the saved
   primary root (`~/.config/projmux/projdir`) and displays whether the effective
   value comes from `PROJMUX_PROJDIR`, tmux `@projmux_projdir`, saved config, or
   no configured source. When no source is configured, the direct-set prompt
   starts with `$HOME` as an editable fallback, but `$HOME` is not used as the
   effective root unless saved. `Workdirs` remains separate: those entries are
-  additional search roots, not the primary root. Status Bar stores
+  additional search roots, not the primary root. Icons & Decorations stores
   `~/.config/projmux/statusbar-decoration` as `off` (default), `symbol`, or
-  `emoji` and updates the live tmux option when available. The About section
-  reads the cached update status without network access;
+  `emoji` and updates the live tmux option when available. Labs stores
+  `~/.config/projmux/picker-backend` as `native` (default) or `fzf` and updates
+  the live tmux `PROJMUX_PICKER_BACKEND` environment when available. The About
+  section reads the cached update status without network access;
   selecting Check Updates runs `projmux update check`, and Update Now runs
   `projmux update apply`. The same About section also lists the keybinding
   diagnostic path: zero-config first, `setup` for swallowed keys, `init` for

package/docs/configuration.md

@@ -51,7 +51,7 @@ The file is read only when no env root list is set.
 | `PROJMUX_USAGE_DEBUG` | When non-empty, prints adapter errors from `projmux status usage` to stderr. |
 | `PROJMUX_USAGE_LIMITS_PATH` | Deprecated. Read but ignored; limits now come from upstream APIs and local Codex rollout state. |
 | `PROJMUX_FOCUS_DEBUG` | When non-empty, `projmux focus` prints one telemetry line to stderr. |
-| `PROJMUX_PICKER_BACKEND` | Set to `native` to opt into the experimental native picker backend. `fzf` remains the default and stable backend. |
+| `PROJMUX_PICKER_BACKEND` | Override the picker backend. Native is the default; set `fzf` to use the external fzf backend. |
 | `PROJMUX_INSTALLER` | Installer source hint used by update flows. npm installs set this automatically; advanced release installs can set `github-release`. |
 
 Example:
@@ -100,13 +100,13 @@ ${PROJMUX_USAGE_STATE_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/projmux/usage}/
 See [Usage tracking](usage-tracking.md) for adapter behavior, throttling, and
 failure handling.
 
-## Status Bar Decoration
+## Decoration Mode
 
-Settings > Status Bar controls the optional cwd/git leading decoration:
+Settings > Icons & Decorations controls optional status and picker decoration:
 
 - `off` is the default and avoids icon-font assumptions.
-- `symbol` restores the Nerd Font-style folder/git icons.
-- `emoji` uses emoji decorators.
+- `symbol` restores the Nerd Font-style folder, GitHub, and bell icons.
+- `emoji` uses emoji decorators, including the notify sidebar header bell.
 
 The saved value lives at:
 

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

@@ -83,10 +83,11 @@ 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. `a` acks the selected row. `Ctrl-A` clears
+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; id/source/severity/target remain searchable.
+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

package/docs/picker-ui-plan.md

@@ -13,10 +13,10 @@ or session title, instead of matching every contextual preview line.
 The picker contract is split in two layers:
 
 - `internal/ui/picker` owns backend-neutral items, actions, preview metadata,
-  backend selection, title-focused filtering, and the opt-in native runner.
+  backend selection, title-focused filtering, and the default native runner.
 - `internal/ui/fzf` adapts that model into the historical fzf command line.
 
-The default fzf backend still sends one logical row per item:
+The fzf fallback backend sends one logical row per item:
 
 ```text
 <visible label>\t<selection value>
@@ -100,12 +100,12 @@ Current implementation:
   `SearchText`, `MetaLines`, `Badges`, and `PreviewTarget`.
 - `picker.Options` carries backend-neutral actions, preview metadata, prompt,
   footer, initial query, and multiline intent.
-- fzf remains the default backend and renders the same popup/sidebar surfaces.
-- `PROJMUX_PICKER_BACKEND=native` opts into the native runner. It supports
+- Native is the default backend and renders the popup/sidebar surfaces.
+- `PROJMUX_PICKER_BACKEND=fzf` opts into the external fzf runner. Native supports
   multiline item rendering, title-focused search via `SearchText`, numeric
   selection, and shared close actions.
-- Switcher popup/sidebar still use the fzf backend for full preview and key
-  action parity. Native preview panes, raw-key navigation, and sidebar focus
-  tracking remain follow-up work.
+- Switcher popup/sidebar use the selected backend for preview and key action
+  parity, including native preview panes, raw-key navigation, and sidebar focus
+  tracking.
 
-fzf can stay as the stable fallback while the native picker reaches parity.
+fzf can stay as the stable fallback while the native picker continues to mature.

package/docs/roadmap.md

@@ -73,9 +73,9 @@ v0.4 shipped.
 
 - Picker-domain model separate from fzf row encoding (kept fzf as the
   stable fallback backend). Done in the 0.5 picker contract slice.
-- Opt-in native picker backend for multi-line card rows and
-  title-focused search. Done in the 0.5 picker contract slice via
-  `PROJMUX_PICKER_BACKEND=native`.
+- Native picker backend for multi-line card rows and title-focused search.
+  Done in the 0.5 picker contract slice, later promoted to the default picker
+  backend with `PROJMUX_PICKER_BACKEND=fzf` kept as the explicit fallback.
 - Port switcher popup/sidebar surfaces after parity tests cover
   selection, preview, and key actions.
 

package/docs/statusbar.md

@@ -27,7 +27,11 @@ row 1  #[range=user|notify] <notify HUD pill> #[norange]
   `isWindowListRangeToken` fallback is now defense-in-depth only.
   The session, pwd, kube, and git segments on this row are wrapped
   in `#[range=user|<id>]` ranges and dispatched through the projmux
-  handler.
+  handler. The git segment shows the current branch or detached commit,
+  then compact state indicators when available: `*` for local changes,
+  `+N` for staged entries, and `↑N`/`↓N` for ahead/behind counts. Each
+  state token gets its own compact foreground color while preserving the
+  existing branch block background.
 - Row 1 splits the line with `#[align=left]` (the pending AI notify
   queue, capped at 80
   cells) and `#[align=right]` (usage, capped at 120 cells). `notify` is the
@@ -73,8 +77,10 @@ The path popup uses a short title, one-line copy status, the current path, and
 an `Enter closes this popup` prompt. If the tmux buffer write fails, it keeps
 the same compact surface with `Current path` as the title and a copy-unavailable
 message. The notification HUD detail surface (`Alt-2` / `User2`) opens the
-right-side `Notifications` popup with newest-first rows; selecting a row still
-focuses and acknowledges that notification.
+right-side notification popup with newest-first rows. The popup itself is
+untitled; when decoration mode is `symbol` or `emoji`, the bell appears before
+the fzf header text instead. Selecting a row still focuses and acknowledges
+that notification.
 
 Empty `#{mouse_status_range}` (a click on whitespace) falls through to
 `select-window -t @<mouse_window>` when `--mouse-window` is non-empty,
@@ -128,10 +134,10 @@ emits a deterministic block per segment), regenerate, and re-apply:
 projmux tmux apply
 ```
 
-Settings > Status Bar > cwd/git leading decoration controls the optional
-prefix before the path and git branch. The persisted enum lives at
+Settings > Icons & Decorations controls the optional decoration mode used by
+the path, git branch, and notification sidebar header. The persisted enum lives at
 `~/.config/projmux/statusbar-decoration`; valid values are `off` (default,
-font-safe), `symbol` (Nerd Font-style folder/git icons), and `emoji`.
+font-safe), `symbol` (Nerd Font-style folder/GitHub/bell icons), and `emoji`.
 Settings also updates tmux `@projmux_statusbar_decoration` for the live
 server when run inside tmux.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projmux",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "tmux project session manager",
   "license": "MIT",
   "homepage": "https://github.com/crevissepartners/projmux#readme",
@@ -24,10 +24,10 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@projmux/darwin-arm64": "0.4.6",
-    "@projmux/darwin-x64": "0.4.6",
-    "@projmux/linux-arm64": "0.4.6",
-    "@projmux/linux-x64": "0.4.6"
+    "@projmux/darwin-arm64": "0.4.7",
+    "@projmux/darwin-x64": "0.4.7",
+    "@projmux/linux-arm64": "0.4.7",
+    "@projmux/linux-x64": "0.4.7"
   },
   "scripts": {
     "package:npm": "scripts/package-npm.sh",