projmux 0.6.7 → 0.7.1

package/docs/theme-palette.md

@@ -1,28 +1,34 @@
 # Theme Palette
 
-This document records the built-in fallback palette that native projmux UI
-surfaces use before project or global theme settings exist. The source of
-truth in code is `internal/theme/palette.go`.
+This document records the implemented theme contract and the built-in
+fallback palette that native projmux UI surfaces use when no global user theme
+is configured. The source of truth for current fallback values in code is
+`internal/theme/palette.go`, and the source of truth for the resolver and the
+semantic role map is `internal/theme/resolve.go`.
 
 ## Scope
 
-The fallback palette is a semantic token layer. Theme settings resolve project
-and global config into the resolver-facing token inventory below, then fall
-back to the built-in values from `internal/theme/palette.go`.
+The fallback palette is a semantic token layer. The effective theme is a global
+user theme resolved from `~/.config/projmux/config.toml`, followed by the
+built-in fallback values from `internal/theme/palette.go`. The resolver derives
+a semantic role map (`RenderRoles` for tmux chrome, `ANSIRoles` for native ANSI
+surfaces) from the effective theme, and renderers consume those roles instead of
+bare palette literals.
 
 - Native picker truecolor SGR tokens.
 - Native sidebar and chip-strip 256-color SGR tokens.
 - Tmux statusbar and generated-config color tokens.
 - Settings/action/state/trust/attention helper tokens.
 
-Renderer adapters apply resolver-backed background/foreground colors to native
-picker frame chrome and to tmux status/window background tokens when an
-`EffectiveTheme` is supplied by the caller. Fallback-sourced fields still
-render through the historical constants so built-in default output remains
-byte-identical. Settings and native project picker surfaces load `[theme]`
-values from global and project config through the shared effective-theme source.
-Theme marketplace/import/export and Visual palette reselection remain out of
-scope.
+Renderer adapters apply resolver-backed background and `chrome_foreground`
+colors to native picker frame chrome and to tmux status/window background tokens
+when an `EffectiveTheme` is supplied by the caller. Fallback-sourced foreground,
+status, and state fields still render through their historical constants, while
+pane and popup backgrounds may intentionally inherit the terminal default.
+Project `.projmux/config.toml` `[theme]` is deprecated and ignored: it is not an
+effective theme source, and the resolver and Settings treat any leftover project
+`[theme]` keys as inert migration data. Theme
+marketplace/import/export and Visual palette reselection remain out of scope.
 
 ## Resolver Token Inventory
 
@@ -32,22 +38,38 @@ onto these stable names:
 
 | Token | Meaning | Shared surfaces |
 | --- | --- | --- |
-| `background` | base popup/sidebar/status surface background | native picker, frame titlebar, notify sidebar, settings popup, statusbar |
-| `surface` | raised or inactive chrome surface | frame titlebar, chips, switch cards, settings popup |
+| `background` | inactive pane body background | tmux inactive panes via `window-style` |
+| `surface` | popup/native frame base background | tmux popup body, native picker rows, frame titlebar/rule, settings popup |
+| `status_background` | bottom status bar background | tmux `status-style` background |
 | `surface_active` | selected/current row or active chip surface | native picker current row, frame chips, statusbar active window |
-| `foreground` | primary readable text | native picker, titlebar, statusbar, notify sidebar, settings popup |
+| `chrome_foreground` | app chrome readable text | native picker frame/title/search chrome, tmux status/window foregrounds, popup body style |
+| `text_primary` | primary content text | settings/info rows and native terminal-rendered content text |
+| `foreground` | legacy alias/fill for split foreground tokens | accepted in config for compatibility; Settings uses `text_primary` / `chrome_foreground` |
 | `muted` | secondary text, divider, disabled or stale details | picker metadata, titlebar rule, notify age/stale, settings descriptions |
 | `accent` | pointer, primary action, highlight, active affordance | native picker pointer/highlight, settings actions, chips |
 | `critical` | destructive/error/critical state | settings remove/quit, notify critical badge, statusbar critical usage |
 | `warning` | progress, pending, warning, busy state | AI busy/thinking indicators, notify pending title, usage warning |
-
-AI semantic status badges use renderer-only state roles layered on top of that
-inventory: `progress`, `success`, and `action_required`. The fallback contract
-is progress yellow, success green, action-required amber-orange. These roles are
-separate from notify queue severity and desktop notification urgency; an AI
-approval row can be `critical` in the notify queue while the live status badge
-uses `action_required`, not red. `critical` remains reserved for error, failure,
-destructive, over-limit, or risk states.
+| `progress` | in-progress / working state color | AI progress badge, statusbar progress, state.progress |
+| `success` | completed / success state color | AI success badge, state.success |
+| `action_required` | AI needs-input/approval badge color | AI action-required badge (independent of `critical`) |
+| `pane_active_bg` | active-pane background tint | active-pane window-active-style tint (tmux pane chrome) |
+| `focus` | active-pane border color | active-pane border (tmux pane chrome) |
+
+`text_primary` and `chrome_foreground` split the old broad foreground behavior:
+changing primary content text no longer repaints frame/title/search/border/status
+chrome as a side effect. The legacy `foreground` key remains readable; it fills
+both split fields unless either split field is explicitly set.
+
+`progress`, `success`, and `action_required` are public `[theme]` keys, no
+longer renderer-only candidates. The fallback contract is progress yellow,
+success green, action-required amber-orange. These roles are separate from
+notify queue severity and desktop notification urgency; an AI approval row can
+be `critical` in the notify queue while the live status badge uses
+`action_required`, not red. `action_required` is independent of `critical`:
+repainting `critical` never changes it. `critical` remains reserved for error,
+failure, destructive, over-limit, or risk states. `pane_active_bg` and `focus`
+are also public keys driving the active-pane tint and border (tmux-only pane
+chrome, with no ANSI/native role).
 
 Renderer-only role names such as `accent.ai`, `state.progress`, `git.branch`,
 and trust colors remain in `internal/theme/palette.go` until Phase 2+ maps each
@@ -56,28 +78,31 @@ native picker, frame titlebar, chips, statusbar, notify sidebar, and settings
 popup all consume a shared effective token set instead of independently
 choosing colors.
 
-Font is not part of this universal token inventory. `font_family` and
-`font_size` are resolved as terminal capability/profile hints: projmux can
-store and display the desired value, but tmux/ANSI rendering cannot force a
-font family or size across terminal emulators. In environments without a
-supported terminal font adapter, projmux reports the desired font as
-`not applied` instead of treating storage as a successful font change.
+Font is not part of this token inventory. The earlier `font_family` and
+`font_size` theme keys were removed in Phase 1b: tmux/ANSI rendering cannot
+force a font family or size across terminal emulators, so the values never
+applied to the terminal. Leftover font keys in an existing config are accepted
+but ignored. See `docs/upgrading.md`.
 
 ## Mapping Policy
 
 Native picker rows can emit truecolor SGR, while tmux statusbar/config strings
-must use tmux color specs. The resolver therefore carries both forms for each
-color token.
+accept tmux style color specs. The resolver therefore carries exact hex plus a
+256-color approximation for renderer paths that still need it.
 
 Rules:
 
 - Truecolor tokens keep exact `#RRGGBB` values and can be converted to
   foreground/background SGR fragments such as `38;2;R;G;B` or `48;2;R;G;B`.
-- Tmux tokens keep `colourN` strings where tmux owns rendering.
-- The built-in `projmux-dark` fallback uses the established ANSI and tmux
-  tokens from `internal/theme/palette.go` to preserve current output.
-- Explicit `#RRGGBB` overrides keep exact truecolor and derive the closest
-  xterm 256-color `colourN` token for tmux surfaces.
+- Tmux style roles use exact `#RRGGBB` for explicit theme/preset colors and
+  keep historical `colourN` strings only for fallback literals. Generated tmux
+  config declares `xterm*:RGB` in `terminal-features` so capable terminals render
+  those exact colors instead of tmux downsampling them to xterm-256 colors.
+- The built-in `projmux` fallback keeps text/accent/state tokens from the
+  established palette while pane and popup backgrounds ride the terminal
+  default.
+- Explicit `#RRGGBB` overrides also retain the closest xterm 256-color
+  `colourN` token for 256-color-only renderer roles.
 - Native chip/sidebar badge tokens use 256-color SGR when they intentionally
   mirror tmux colors.
 - Output compatibility wins inside this baseline. For example, the kube
@@ -88,32 +113,63 @@ Rules:
 
 ## Resolver Contract
 
-Theme resolution is field-by-field after validating each layer:
+The effective theme resolves theme fields from:
 
-1. Project `.projmux/config.toml`
-2. Global `~/.config/projmux/config.toml`
-3. Built-in fallback preset `projmux-dark`
+1. Global `~/.config/projmux/config.toml`
+2. Built-in fallback preset `projmux`
 
 Rules:
 
-- Project values override global values for the same field.
-- Missing or `inherit` project values fall back to global values.
 - Missing global values fall back to built-in values.
-- A preset fills missing color tokens in its own layer.
-- Explicit color tokens in the same layer override preset colors.
-- An unknown preset invalidates only that layer and emits a warning.
-- An invalid color, `font_family`, or `font_size` invalidates only that layer
-  and emits a warning.
-- Every effective field reports `project`, `global`, or `fallback` as its
-  source label.
+- A preset fills missing color tokens in the global layer.
+- Explicit global color tokens override preset colors.
+- Legacy `foreground` fills `text_primary` and `chrome_foreground` unless either
+  split key is explicitly set.
+- An unknown preset invalidates only the global layer.
+- An invalid color invalidates only the global layer.
+- Every effective field reports `global` or `fallback` as its source label.
+
+### Terminal default sentinel
+
+The `background`, `surface`, `status_background`, `surface_active`, and
+`pane_active_bg` tokens accept the special value `default` ("Terminal default"
+in Settings). It pins that surface to the terminal background instead of a
+concrete color, even when a preset is selected:
+
+- Priority is **explicit `default` > preset fill > unset (fallback)**. Setting a
+  token to `default` overrides the preset's color for that token while leaving
+  every other token preset-filled.
+- On the tmux side the derived roles emit `bg=default` (for example
+  `window-style "bg=default"` from `background`, popup body style from
+  `surface`, `window-active-style "bg=default"` from `pane_active_bg`, and
+  `status-style bg=default` from `status_background`).
+- On the ANSI side the corresponding surface emits no background sequence (no
+  `48;2;…` / `48;5;…`), so the terminal background shows through.
+- `default` is only valid on `background` / `surface` / `status_background` /
+  `surface_active` / `pane_active_bg`. On any other token it is treated as an
+  invalid hex color and invalidates the global layer (same as any other invalid
+  color).
+
+Historical project `[theme]` values in `.projmux/config.toml` are migration
+data only. They are not a current or target source in this contract.
 
 Built-in preset config values are:
 
-- `projmux-dark`
-- `midnight`
+- `projmux`
+- `high-contrast`
+- `blue-hour`
+- `carbon-violet`
+- `ember`
 - `forest`
 - `rose`
-- `high-contrast`
+- `blue-hour` — dark theme tuned around a terminal blue accent; it uses a dark
+  blue-tinted inactive pane body, black popup surface, deep navy status bar,
+  and a deep indigo active pane tint.
+- `carbon-violet` — charcoal/violet dark theme with darker popup/status
+  surfaces and a black active pane tint.
+- `high-contrast` — black surfaces, white text, a dark blue active surface,
+  near-black active pane tint, vivid cyan focus, and bright
+  cyan/yellow/red/green state colors.
 
 ## Fallback Inventory
 
@@ -122,7 +178,7 @@ Chrome and text:
 | Role | Native SGR | Tmux |
 | --- | --- | --- |
 | `surface.active` | `48;2;44;56;61` with selected white text | window active `colour240` / `colour231` |
-| `surface.raised` | `48;2;24;34;38` with `216;224;228` text | window inactive `colour235` / `colour245` |
+| `surface.raised` | terminal-default background with `216;224;228` text | popup/native frame surface |
 | `text.primary` | `216;224;228` | `colour231` or `colour254` for identity text |
 | `text.secondary` | `164;176;182` | `colour245` |
 | `text.muted` | `117;132;140` or ANSI dim | `colour244`, `colour238`, `colour240` for low-signal blocks |
@@ -155,6 +211,25 @@ Surface-specific tokens:
 | Settings | add/type/open action, destructive remove/quit, back/cancel, info/read-only, dim description, root action/dim rows, trust trusted/stale/untrusted |
 | Switch picker cards | path metadata, active/inactive git branch badges aligned with statusbar git branch block colors, statusbar-like window tabs, inline attention/progress dots |
 
+Active-pane focus: tmux draws a single shared border between adjacent panes, so
+a full active-pane rectangle (e.g. tinting the whole active pane edge-to-edge)
+is not guaranteed. Active focus is instead reinforced by the `pane-border-status
+top` topic line, an active-pane border (`pane-active-border-style`, fallback
+cyan `colour51`, the public `focus` token), and a subtle dark background tint
+applied via `window-active-style` (fallback `colour234` — one tone darker than
+the base `colour235` so the active pane visibly sinks; the public `pane_active_bg`
+token). Inactive panes keep the terminal default background via `window-style
+"bg=default"` unless the public `background` token is set.
+
+Pane body vs popup vs status background: the general pane body, popup/native
+frame background, and bottom status bar are derived from separate public tokens.
+The pane body follows `background` (tmux `window-style`; unset keeps
+`bg=default`), popup/native frames follow `surface`, and the bottom status bar
+follows `status_background` (tmux `status-style`; unset keeps `colour235`).
+Built-in presets fill `status_background` from their surface color to preserve
+the old look, but an explicit `surface` override no longer repaints the bottom
+status line.
+
 ## Current Literal Inventory
 
 After the Phase 3 token pass, raw color values intentionally remain in:

package/docs/upgrading.md

@@ -30,6 +30,83 @@ the current latest release tag in `update-skip.json`; the prompt appears again
 when the cached latest tag changes. For `source` and unknown installer sources,
 Upgrade prints guidance and continues shell entry without applying anything.
 
+## Behavior Changes
+
+### Theme is now global-only
+
+Theme is a global user preference. The effective theme resolves from the global
+`[theme]` in `~/.config/projmux/config.toml` plus a built-in fallback preset.
+
+If you previously set a `[theme]` section in a project's `.projmux/config.toml`,
+it is now **deprecated and ignored** — it no longer overrides the global theme
+and does not affect the native picker, statusbar, popups, or any tmux chrome.
+The project `[theme]` keys are left in the file untouched (no warning, no
+removal); they simply have no effect.
+
+To restore your previous look, copy the values into the global
+`~/.config/projmux/config.toml` `[theme]` section, or edit them through
+Settings > Theme. Settings no longer exposes a Project theme editor, and the
+separate Effective theme view has been merged into the Global theme view: each
+token row now shows its resolved value inline, with unset tokens shown as their
+dimmed `(fallback)` value.
+
+### Foreground split
+
+The old broad `foreground` theme key is now split into two clearer public keys:
+`text_primary` for primary native content text, and `chrome_foreground` for
+frame/title/search/status/window chrome foreground roles. Existing global
+`foreground` values still work as a legacy alias/fill and will feed both split
+roles unless either new key is set explicitly. Settings shows and writes the new
+split names instead of encouraging new `foreground` writes.
+
+If your previous `foreground` override made both content and chrome change
+together, you do not need to migrate immediately. To tune them separately, copy
+the value into `text_primary` and/or `chrome_foreground`, then remove
+`foreground` when you no longer need the compatibility fill.
+
+### New public theme keys
+
+Seven new public `[theme]` keys are now available: `text_primary`,
+`chrome_foreground`, `progress`, `success`, `action_required` (AI/status
+colors), `pane_active_bg` (active-pane tint), and `focus` (active-pane border).
+Leaving a key unset keeps the historical built-in color; setting it repaints the
+matching role. `action_required` is independent of `critical` — repainting
+`critical` never changes it. The full public token set is documented in
+`docs/configuration.md` and `docs/theme-palette.md`.
+
+The active-pane tint (`pane_active_bg`) defaults to the terminal background in
+the built-in `projmux` preset; set it to a concrete color when the active pane
+should visibly sink. The active-pane border (`focus`) defaults to cyan
+`colour51`. Both apply only to tmux pane chrome.
+
+Built-in presets are intentionally small: `projmux`, `high-contrast`,
+`blue-hour`, `carbon-violet`, `ember`, `forest`, and `rose`. Terminal-default
+backgrounds are configured per token with the `default` sentinel rather than
+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.
+
+### Theme font keys removed
+
+The `[theme]` `font_family` and `font_size` keys were removed. They never
+applied to the terminal — tmux/ANSI rendering cannot force a font family or
+size across terminal emulators — so they only stored and displayed a desired
+value that was always reported as `not applied`.
+
+Leftover `font_family` / `font_size` keys in a global or project
+`config.toml` are accepted but ignored: they no longer parse into the theme,
+appear in Settings, or affect any surface. You can delete them at your
+convenience. Set your terminal font through your terminal emulator's own
+profile settings instead.
+
 ## npm Installs
 
 The recommended install path is:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projmux",
-  "version": "0.6.7",
+  "version": "0.7.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.6.7",
-    "@projmux/linux-arm64": "0.6.7",
-    "@projmux/darwin-x64": "0.6.7",
-    "@projmux/darwin-arm64": "0.6.7"
+    "@projmux/linux-x64": "0.7.1",
+    "@projmux/linux-arm64": "0.7.1",
+    "@projmux/darwin-x64": "0.7.1",
+    "@projmux/darwin-arm64": "0.7.1"
   }
 }

package/docs/readme-hero-gif-recording.md

@@ -1,97 +0,0 @@
-# README Hero GIF Recording
-
-This recipe records the README hero GIF:
-
-- `docs/assets/projmux-ai-attention.gif`
-
-The maintained recorder is kept in the local dotfiles checkout at:
-
-```sh
-/home/es5h/dotfiles/bin/projmux/projmux-record-readme-gifs.py
-```
-
-## Prerequisites
-
-Install or verify these local tools before recording:
-
-- `python3`
-- `git`
-- `tmux`
-- `ffmpeg` and `ffprobe`
-- `Xvfb`
-- `openbox`
-- `ghostty`
-- `xdotool`
-- `xwininfo`
-- `script` from util-linux
-- authenticated `codex`
-
-Build the local projmux binary first:
-
-```sh
-make build
-```
-
-The script expects `.bin/projmux` by default. Override paths only when needed:
-
-```sh
-PROJMUX_RECORD_REPO=/path/to/projmux \
-PROJMUX_RECORD_BIN=/path/to/projmux \
-PROJMUX_RECORD_DISPLAY=117 \
-PROJMUX_RECORD_SCREEN=2560x1440x24 \
-PROJMUX_RECORD_KEEP_TMP=1 \
-python3 /home/es5h/dotfiles/bin/projmux/projmux-record-readme-gifs.py
-```
-
-For the normal checkout, run:
-
-```sh
-python3 /home/es5h/dotfiles/bin/projmux/projmux-record-readme-gifs.py
-```
-
-## Scenario Contract
-
-The recording uses a private demo home, XDG config/state dirs, demo git
-projects, and an isolated `CODEX_HOME`. It copies the local Codex auth/config
-into that isolated home, trusts the demo projects/hooks, and seeds usage cache
-data so the tmux status line shows the Codex HUD during the capture.
-
-The scenario records the AI attention flow:
-
-1. Start in `mobile-client` with no pending notification.
-2. Open the AI picker and launch a real Codex pane.
-3. Ask Codex to do a short task.
-4. Use the projmux sessionizer sidebar to move to `atlas-api`.
-5. Keep working in zsh while Codex finishes in the previous project.
-6. When the Codex completion notification exists, open the notification sidebar.
-7. Select the notification and return focus to the original Codex pane.
-
-## Visual Guardrails
-
-- Keep the native picker UI native. The script runs picker commands through
-  `script(1)` with a fixed PTY size so fzf/terminal UI rendering is captured
-  instead of degraded line-mode output.
-- Keep the terminal in zsh with the demo prompt so the project and git branch
-  are visible.
-- Keep the Codex usage HUD visible in the tmux status line.
-- Use the sessionizer sidebar for project movement in 4a.
-- Capture the Ghostty X11 window geometry with `xwininfo` and feed that exact
-  rectangle to ffmpeg. This prevents the GIF from drifting away from `(0, 0)`.
-
-## Verification
-
-After recording, inspect the resulting streams:
-
-```sh
-ffprobe -v error -select_streams v:0 \
-  -show_entries stream=width,height,nb_frames,duration \
-  -of default=noprint_wrappers=1 \
-  docs/assets/projmux-ai-attention.gif
-```
-
-Expected final shape is roughly 1110px wide and about 16-18 seconds, with the
-native picker, zsh prompt, Codex pane, notification sidebar, and usage HUD
-visible in the relevant frames.
-
-Set `PROJMUX_RECORD_KEEP_TMP=1` when you need to inspect intermediate MP4s,
-Ghostty logs, or palette files under `/tmp/projmux-readme-record-*`.