projmux 0.9.0 → 0.10.1

package/docs/statusbar.md

@@ -68,7 +68,8 @@ row 1  [#S]  #{pane_current_path}  ⎈ <ctx>/<ns>  <git>  CPU 12%  MEM 41%  
   without dominating the status row. Window tab indexes stay left of each tab,
   and tab titles are centered in a fixed-width trim so long active pane names
   do not resize the status row.
-- `Settings > Labs > Live system resources` adds the compact `CPU N%  MEM N%`
+- `Settings > Labs > Live system resources` adds the compact
+  `CPU N%  MEM N%`
   segment between git and the clock on macOS, Linux, and WSL. It is global,
   default off, and updates with tmux's existing five-second status interval.
   CPU and memory are host-scoped telemetry, not pane, window, project, or
@@ -76,8 +77,13 @@ row 1  [#S]  #{pane_current_path}  ⎈ <ctx>/<ns>  <git>  CPU 12%  MEM 41%  
   normal below 70%, warning at 70–89%, and critical at 90% or above; memory is
   normal below 75%, warning at 75–89%, and critical at 90% or above. Normal and
   unavailable (`--`) values use the secondary status-text role, warnings use
-  the warning role, and critical values use the bold critical role. Styling one
-  value never promotes the other value.
+  the warning role, and critical values use the bold critical role. Severity
+  words are omitted. Each percent value, including `%`, occupies one fixed
+  four-column slot (`  9%`, ` 15%`, `100%`, or ` --%`), so styling or changing
+  either metric cannot move the following segment. Styling one value never
+  promotes the other value. The Resource Inspector uses this same classifier
+  and semantic roles for host and attributed CPU/memory while rendering
+  unavailable metrics as `--` without severity suffixes.
   Linux CPU is the aggregate delta from `/proc/stat`; memory is
   `(MemTotal - MemAvailable) / MemTotal` from `/proc/meminfo`. macOS CPU uses
   the aggregate Mach host tick delta; memory is total physical memory minus
@@ -116,16 +122,16 @@ bind-key -n MouseDown1Status if-shell -F "#{==:#{mouse_status_range},window}" \
 
 ## Range catalogue
 
-| Range id | Row | Click action                              | Keyboard      |
-| -------- | --- | ----------------------------------------- | ------------- |
-| `session` | 0 | `projmux tmux popup-toggle sessionizer-sidebar` | `prefix s s` |
-| `pwd`     | 0 | show a native-framed current-path popup; no clipboard or tmux buffer copy | `prefix s p`  |
-| `kube`    | 0 | `projmux tmux popup-toggle sessionizer`   | `prefix s k`  |
-| `git`     | 0 | `projmux tmux popup-toggle sessionizer`   | `prefix s g`  |
-| `settings` | 0 | `projmux tmux popup-toggle --client <tty> ai-split-settings` | mouse only; `prefix s s` remains `session` |
-| `resources` | 0 | `projmux tmux popup-toggle --client <tty> resource-inspector` | mouse or custom `Resources:Open`; no default key |
-| `usage`   | 1 | show a native-framed usage HUD popup from cached usage state | `prefix s u`  |
-| `notify`  | 1 | `projmux focus --target <newest> --source status-bar --kind segment-click [--client <tty>]`, then ack on focus success | `prefix s n`  |
+| Range id | Generated row | Click action                              | Keyboard      |
+| -------- | ------------- | ----------------------------------------- | ------------- |
+| `notify`  | `status-format[0]` | `projmux focus --target <newest> --source status-bar --kind segment-click [--client <tty>]`, then ack on focus success | `prefix s n`  |
+| `usage`   | `status-format[0]` | show a native-framed usage HUD popup from cached usage state | `prefix s u`  |
+| `session` | `status-format[1]` | `projmux tmux popup-toggle sessionizer-sidebar` | `prefix s s` |
+| `pwd`     | `status-format[1]` | show a native-framed current-path popup; no clipboard or tmux buffer copy | `prefix s p`  |
+| `kube`    | `status-format[1]` | `projmux tmux popup-toggle sessionizer`   | `prefix s k`  |
+| `git`     | `status-format[1]` | `projmux tmux popup-toggle sessionizer`   | `prefix s g`  |
+| `resources` | `status-format[1]` | `projmux tmux popup-toggle --client <tty> resource-inspector` | mouse or custom `Resources:Open`; no default key |
+| `settings` | `status-format[1]` | `projmux tmux popup-toggle --client <tty> ai-split-settings` | mouse only; `prefix s s` remains `session` |
 
 `notify` reads the pending queue only. For a live pane-state view that is
 independent of queued reminders, use `projmux attention list`. To explain why
@@ -155,7 +161,11 @@ Antigravity rows keep conversation-local `context` separate from account
 `quota/<exact upstream bucket ID>` rows; the popup displays an absolute reset
 when provided and otherwise the exact optional relative reset seconds. Opaque
 bucket IDs are escaped for terminal/tmux safety and are never assigned a
-`5h`/`weekly` cadence.
+`5h`/`weekly` cadence. Claude retains aggregate `5h`/`weekly` rows alongside
+typed named/model `limits[]` rows in this popup: model-scoped rows display the
+exact upstream group plus model display identity with a bounded terminal-safe
+label, reset, and per-row age. The compact status line excludes every Claude
+named/model row and continues to use only the aggregate official windows.
 Session State inspection lives under `Projects > Sessions > State`; global
 Settings > Session State is settings-only and the statusbar no longer exposes a
 duplicate State button.
@@ -169,7 +179,8 @@ does not leave terminal key state behind. The usage popup uses the same
 single-payload print and plain Enter-close pattern. It shows the authoritative
 last collect timestamp when present, falls back to the cache file mtime when
 needed, and keeps stale sync metadata muted instead of escalating it to a
-warning color.
+warning color. Percent-only named rows do not synthesize `USED`, `LIMIT`, or
+`LEFT` counts.
 The notification HUD detail surface opens the right-side notification popup
 through the notify sidebar action, showing the grouped pane/session inbox with
 collapsed group rows and the same attention-tinted title. When notification
@@ -273,9 +284,8 @@ updates the matching live tmux option
 (`@projmux_statusbar_decoration_cwd`, `_git`, or `_notify`) when run inside
 tmux. The legacy `~/.config/projmux/statusbar-decoration` and
 `@projmux_statusbar_decoration` remain fallback defaults for older configs.
-Appearance also shows the effective desired theme font. This is a status row,
-not a font editor: tmux status strings and ANSI output cannot force terminal
-font family or size, so unsupported environments report `not applied`.
+Settings > Theme controls the bottom status bar background through
+`status_background`; `surface` controls popup and native frame backgrounds.
 
 Settings > Labs controls the experimental live resource segment. Its saved
 value is `~/.config/projmux/live-resources`; changing it inside tmux updates

package/docs/tmux-surface-inventory.md

@@ -18,7 +18,6 @@ Primary production sources:
 Support and fixture sources:
 
 - `test/`
-- `scripts/poc-native-picker-no-fzf-*.sh`
 - current docs that describe generated tmux snippets
 
 Useful inventory searches:

package/docs/upgrading.md

@@ -40,6 +40,27 @@ still requires an explicit `PROJMUX_INSTALLER=github-release`.
 
 ## Behavior Changes
 
+### Terminal init command removed
+
+The deprecated top-level `projmux init` command and its legacy-only
+`--dry-run` flag have been removed. Use the exact replacement
+`projmux setup terminal`; it previews by default, and accepts `--apply`,
+`--config <path>`, and `--allow-symlink` when those behaviors are needed.
+
+### Pane rename keymap action ID removed
+
+The deprecated `rename-pane-topic` keybinding action ID has been removed. If
+`~/.config/projmux/keymap.toml` still contains
+`[bindings.rename-pane-topic]`, rename that table to
+`[bindings.rename-pane-label]` before running Settings or
+`projmux tmux apply`. Projmux now rejects the stale table with that exact
+replacement instead of silently applying its keys to the user-label action.
+
+This removal does not change `projmux ai topic set/clear`: those advanced CLI
+commands continue to write only AI topic and manual-ownership state. User pane
+rename continues to write only the pane label, and raw pane title remains an
+independent fallback.
+
 ### Theme is now global-only
 
 Theme is a global user preference. The effective theme resolves from the global
@@ -95,13 +116,14 @@ through separate terminal preset variants.
 
 ### Pane body vs popup backgrounds
 
-The general (pane) background and the popup/chrome background are now driven by
-separate public tokens. The pane body follows `background` (unset keeps the
-terminal default), while the status bar, native popup bodies, and the
-settings/notify/recent/picker frames follow `surface`. Because the `surface`
-fallback equals `background`, leaving both unset looks exactly as before; set
-them to different values to make popups read as a distinct surface from the pane
-body.
+The general pane, bottom status bar, and popup/native frame backgrounds are now
+driven by separate public tokens. The pane body follows `background` (unset
+keeps the terminal default), the status bar follows `status_background`, and
+native popup bodies plus the settings/notify/recent/picker frames follow
+`surface`. Because the `surface` fallback equals `background`, leaving those two
+unset looks exactly as before; set `surface` separately to make popups read as a
+distinct surface from the pane body. Set `status_background` separately to
+repaint only the bottom status bar.
 
 ### Theme font keys removed
 

package/docs/usage-tracking.md

@@ -11,12 +11,17 @@ requests such as `projmux usage --model claude`, `--model codex`, or
 still collect and render that provider even when it is disabled.
 
 Claude and Codex adapters read the upstream's own account view. Antigravity
-reads only the official managed statusline payload: `context_window` remains a
-conversation-local fullness gauge, while each `quota` map entry is a separate
-account row. Projmux preserves the upstream bucket ID and never guesses that an
-undocumented ID means `5h` or `weekly`. It does not infer quota, cadence, reset
-timestamps, or account limits from screen scraping, tokens, history,
-OAuth/cache files, or binary strings.
+reads only the official managed statusline payload: `context_window` remains
+private conversation-local diagnostic metadata, while each valid `quota` map
+entry is a separate account row. Projmux preserves the upstream bucket ID and
+never guesses that an undocumented ID means `5h` or `weekly`. It does not infer
+quota, cadence, reset timestamps, or account limits from screen scraping,
+tokens, history, OAuth/cache files, or binary strings.
+
+Claude keeps the canonical aggregate `five_hour` and `seven_day` rows and also
+preserves structurally valid typed `limits[]` rows as named account quotas for
+inspection surfaces. These named rows never participate in the ambient status
+projection.
 
 ## Adapters
 
@@ -45,6 +50,23 @@ floor.
 - A clean 200 resets the consecutive counter.
 - `--force` (BackoffResetter) clears the persisted state and attempts
   the call regardless of streak.
+- Canonical `five_hour` and `seven_day` blocks remain `5h` and `weekly`.
+  Each valid typed `limits[]` row becomes `window=quota` with the exact opaque
+  `group` copied to `bucket`. The snapshot also preserves `kind`, `severity`,
+  `is_active`, and nullable `scope`, model ID, and surface metadata; percent and
+  reset remain the authoritative common snapshot fields.
+- A model-scoped quota renders as `quota/<group> · <model display name>` in
+  text and popup inspection. Control characters and tmux format introducers are
+  escaped and the display label is bounded, while the stored identity remains
+  byte-for-byte unchanged. No model-family inference, aliasing, aggregation, or
+  percentage-to-count derivation is performed.
+- `limits[]` is capped at 64 rows and required field presence/types are checked
+  explicitly. A malformed container or row fails that adapter collection so the
+  manager retains the complete last-known-good Claude slice. A valid
+  aggregate-only response succeeds and therefore removes obsolete named rows.
+- Null legacy top-level model hints and unknown experiment keys are ignored.
+  Billing/credit blocks such as `extra_usage` and `spend` are not ingested or
+  rendered.
 
 ### Codex (`internal/core/usage/adapters/codex`)
 
@@ -74,12 +96,12 @@ read.
 
 Local managed-statusline sidecars. No network or credential reads.
 
-- `context_window.used_percentage` becomes the conversation-local `context`
-  row and retains the conversation ID in its sidecar. The legacy string
-  percentage remains a compatibility fallback.
+- `context_window.used_percentage` and its conversation ID remain in the
+  private context sidecar for hook/notify diagnostics. They do not become
+  Usage snapshots. The legacy string percentage remains a writer fallback.
 - The official `quota` map is sorted by its exact bucket ID. Each valid bucket
   becomes `window=quota`, `bucket=<upstream ID>` and renders as
-  `quota/<upstream ID>` beside, never instead of, `ctx`.
+  `quota/<upstream ID>` on account-inspection surfaces.
 - Used percent is `100 * (1 - remaining_fraction)`. Non-finite or values
   outside `[0,1]`, empty IDs, null/disabled entries, and negative relative
   resets are ignored safely.
@@ -89,8 +111,8 @@ Local managed-statusline sidecars. No network or credential reads.
 - Context and quota use independent private sidecars. A context-only payload
   does not erase the last quota observation. An explicit empty/null quota map
   records no buckets; the manager's existing rule still preserves prior model
-  rows when an adapter returns zero total rows, while any returned context row
-  causes the normal full-model replacement.
+  rows when an adapter returns zero total rows. Context never participates in
+  that account-row replacement decision.
 
 ## Snapshot store
 
@@ -101,7 +123,9 @@ ${PROJMUX_USAGE_STATE_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/projmux/usage}/
 JSON document keyed by adapter, recording:
 
 - per-window `Snapshot{Model, Window, Bucket, Pct, Limit, ResetsAt,
-  ResetInSeconds, UpdatedAt}`; `Bucket` is populated only for `window=quota`
+  ResetInSeconds, UpdatedAt, NamedQuota}`; `Bucket` is populated only for
+  `window=quota`, and `NamedQuota` is populated only when an upstream typed
+  named-quota contract supplies the metadata
 - per-adapter `last_collect` timestamp (drives the throttle)
 - per-adapter `Backoff{Until, Consecutive}` (drives the cooldown)
 
@@ -126,8 +150,8 @@ Enabled agents, filters by window, and renders the tab-aligned table:
 ```
 MODEL        WINDOW                 PCT  RESETS_AT                 RESET_IN  STALE
 claude       5h                     80%  2026-05-07T14:00:00+09:00 -
-antigravity  context                14%  -                         -
 antigravity  quota/gemini-weekly    6%   2026-07-06T16:50:32+09:00 560580s
+claude       quota/group-redacted · Model Redacted Alpha  38%  2031-02-03T15:05:06+09:00  -  *
 ```
 
 `STALE` is `*` when `now - UpdatedAt > 10m`. A `--json` payload returns
@@ -144,9 +168,11 @@ provider rows and prints a short Settings hint. `--json` returns an
 empty array. Explicit `--model claude`, `--model codex` and
 `--model antigravity` bypass the enabled-agent filter for read-only
 inspection and collect/render only the requested adapter. Antigravity reports
-its conversation-local `context` row separately from zero or more account
-`quota/<bucket-id>` rows. `--window quota` selects only account buckets;
-`--window weekly` never matches an opaque quota bucket named `weekly`.
+zero or more account `quota/<bucket-id>` rows. Legacy cached `window=context`
+rows are suppressed in text and JSON output. `--window quota` selects only
+account buckets; `--window weekly` never matches an opaque quota bucket named
+`weekly`. `--window context` remains an accepted compatibility filter and
+returns no Usage rows.
 
 ### `projmux status usage`
 
@@ -162,12 +188,19 @@ are swallowed unless `PROJMUX_USAGE_DEBUG` is set. Then it loads the
 cache, filters to the same enabled-agent scope, and renders. If no AI
 agents are enabled, the status segment emits nothing.
 
+The HUD first derives an ambient projection separate from lossless account
+snapshots. Canonical `5h`/`weekly` rows are eligible for every provider;
+Antigravity's exact `quota/gemini-weekly` identity is projected as `weekly`
+without rewriting the cache. Context, `3p-weekly`, and unknown quota buckets
+do not participate in status width. Claude `limits[]` named/model rows are also
+excluded; only its aggregate official `5h` and `weekly` rows reach the HUD.
+
 Output degrades through six tiers as `--max-width` shrinks:
 
 1. Long form with last-sync age + bars: `Claude (3m) 5h [████████░░]
-   80% · weekly [...]   Antigravity ctx [...] · quota/gemini-weekly [...]`
+   80% · weekly [...]   Antigravity weekly [...]`
 2. Drop the age indicator (legacy long form).
-3. Drop the weekly bar.
+3. Keep one primary bar per provider (`5h`, or `weekly` when 5h is absent).
 4. Drop bars entirely (`Claude 5h:80% weekly:30%`).
 5. Single-letter labels (`C 5h:80% weekly:30%`).
 6. Hard rune-truncate with trailing `…`.
@@ -186,6 +219,17 @@ sync metadata to the same enabled-agent scope as the ambient HUD. This keeps
 tmux click path a structured table with aligned rows, right-aligned numeric
 values, dim unavailable cells, amber usage at 80%, and red usage at 95%.
 
+The popup suppresses legacy cached context rows while preserving every valid
+named quota ID, reset, and freshness value. Its columns are data-driven: when
+no displayed row has authoritative absolute token counts, `USED`, `LIMIT`, and
+`LEFT` are omitted together. If any row has real counts, all three columns are
+shown; percent-only rows use unavailable cells. Counts are never derived from
+percentages.
+
+Named Claude rows use the same bounded, injection-safe label as text output and
+include their reset plus per-row `AGE`. JSON retains exact opaque group/model
+identity, nullable scope fields, `updated_at`, and the derived `stale` flag.
+
 The popup sync line uses the maximum authoritative `LastCollect` timestamp from
 the cache. If that field is unavailable, it falls back to the snapshots file
 mtime. The sync line turns amber when the timestamp is more than 60 seconds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projmux",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "tmux project session manager",
   "license": "MIT",
   "homepage": "https://github.com/crevissepartners/projmux#readme",
@@ -28,9 +28,9 @@
     "package:npm:pack": "scripts/package-npm.sh --pack"
   },
   "optionalDependencies": {
-    "@projmux/linux-x64": "0.9.0",
-    "@projmux/linux-arm64": "0.9.0",
-    "@projmux/darwin-x64": "0.9.0",
-    "@projmux/darwin-arm64": "0.9.0"
+    "@projmux/linux-x64": "0.10.1",
+    "@projmux/linux-arm64": "0.10.1",
+    "@projmux/darwin-x64": "0.10.1",
+    "@projmux/darwin-arm64": "0.10.1"
   }
 }

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"
-```