feat(load[progress]): animated progress spinner for tmuxp load (#1020)

Adds real-time build feedback to `tmuxp load` via an animated
terminal spinner that shows window/pane creation progress. The
spinner runs in a background thread during the build phase only,
stopping cleanly before interactive prompts or tmux attach.

**Builder callbacks**: Four optional callbacks on `WorkspaceBuilder`
(`on_progress`, `on_before_script`, `on_script_output`,
`on_build_event`) decouple progress reporting from build logic,
emitting structured lifecycle events at each build milestone.

**Spinner and BuildTree** (`cli/_progress.py`): `Spinner` handles
ANSI-aware terminal output with atexit cursor restoration and a
scrolling panel for `before_script` output. `BuildTree` tracks
build state and provides template context for format tokens
(`{bar}`, `{progress}`, `{window}`, `{pane_index}`, etc.).

**Five built-in presets**: `default`, `minimal`, `window`, `pane`,
`verbose` — selectable via `--progress-format` or
`TMUXP_PROGRESS_FORMAT`.

**CLI flags**: `--progress-format`, `--progress-lines`,
`--no-progress` with corresponding `TMUXP_PROGRESS*` env vars.
Non-TTY environments automatically disable the spinner.

**Graceful degradation**: `--no-progress` path wraps session
summary access in try/except so killing the session after attach
does not crash.

Author: tony

CHANGES

@@ -35,6 +35,22 @@ $ pipx install --suffix=@next 'tmuxp' --pip-args '\--pre' --force
 _Notes on the upcoming release will go here._
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### What's new
+
+#### Animated progress spinner for `tmuxp load` (#1020)
+
+The `load` command now shows an animated spinner with real-time build progress
+as windows and panes are created. Five built-in presets control the display
+format (`default`, `minimal`, `window`, `pane`, `verbose`), and custom format
+strings are supported via `--progress-format` or `TMUXP_PROGRESS_FORMAT`.
+
+- `--progress-lines N` / `TMUXP_PROGRESS_LINES`: Control how many lines of
+  `before_script` output appear in the spinner panel (default: 3). Use `0` to
+  hide the panel, `-1` for unlimited (capped to terminal height).
+- `--no-progress` / `TMUXP_PROGRESS=0`: Disable the spinner entirely.
+- During `before_script` execution, the progress bar shows a marching animation
+  and ⏸ icon.
+
 ## tmuxp 1.66.0 (2026-03-08)
 
 ### Bug fixes

docs/api/cli/index.md

@@ -16,6 +16,7 @@ freeze
 import_config
 load
 ls
+progress
 search
 shell
 utils

docs/api/cli/progress.md

@@ -0,0 +1,8 @@
+# tmuxp progress - `tmuxp.cli._progress`
+
+```{eval-rst}
+.. automodule:: tmuxp.cli._progress
+   :members:
+   :show-inheritance:
+   :undoc-members:
+```

docs/cli/load.md

@@ -152,3 +152,104 @@ $ tmuxp load [filename] --log-file [log_filename]
 ```console
 $ tmuxp --log-level [LEVEL] load [filename] --log-file [log_filename]
 ```
+
+## Progress display
+
+When loading a workspace, tmuxp shows an animated spinner with build progress. The spinner updates as windows and panes are created, giving real-time feedback during session builds.
+
+### Presets
+
+Five built-in presets control the spinner format:
+
+| Preset | Format |
+|--------|--------|
+| `default` | `Loading workspace: {session} {bar} {progress} {window}` |
+| `minimal` | `Loading workspace: {session} [{window_progress}]` |
+| `window` | `Loading workspace: {session} {window_bar} {window_progress_rel}` |
+| `pane` | `Loading workspace: {session} {pane_bar} {session_pane_progress}` |
+| `verbose` | `Loading workspace: {session} [window {window_index} of {window_total} · pane {pane_index} of {pane_total}] {window}` |
+
+Select a preset with `--progress-format`:
+
+```console
+$ tmuxp load --progress-format minimal myproject
+```
+
+Or via environment variable:
+
+```console
+$ TMUXP_PROGRESS_FORMAT=verbose tmuxp load myproject
+```
+
+### Custom format tokens
+
+Use a custom format string with any of the available tokens:
+
+| Token | Description |
+|-------|-------------|
+| `{session}` | Session name |
+| `{window}` | Current window name |
+| `{window_index}` | Current window number (1-based) |
+| `{window_total}` | Total number of windows |
+| `{window_progress}` | Window fraction (e.g. `1/3`) |
+| `{window_progress_rel}` | Completed windows fraction (e.g. `1/3`) |
+| `{windows_done}` | Number of completed windows |
+| `{windows_remaining}` | Number of remaining windows |
+| `{pane_index}` | Current pane number in the window |
+| `{pane_total}` | Total panes in the current window |
+| `{pane_progress}` | Pane fraction (e.g. `2/4`) |
+| `{progress}` | Combined progress (e.g. `1/3 win · 2/4 pane`) |
+| `{session_pane_progress}` | Panes completed across the session (e.g. `5/10`) |
+| `{overall_percent}` | Pane-based completion percentage (0–100) |
+| `{bar}` | Composite progress bar |
+| `{pane_bar}` | Pane-based progress bar |
+| `{window_bar}` | Window-based progress bar |
+| `{status_icon}` | Status icon (⏸ during before_script) |
+
+Example:
+
+```console
+$ tmuxp load --progress-format "{session} {bar} {overall_percent}%" myproject
+```
+
+### Panel lines
+
+The spinner shows script output in a panel below the spinner line. Control the panel height with `--progress-lines`:
+
+Hide the panel entirely (script output goes to stdout):
+
+```console
+$ tmuxp load --progress-lines 0 myproject
+```
+
+Show unlimited lines (capped to terminal height):
+
+```console
+$ tmuxp load --progress-lines -1 myproject
+```
+
+Set a custom height (default is 3):
+
+```console
+$ tmuxp load --progress-lines 5 myproject
+```
+
+### Disabling progress
+
+Disable the animated spinner entirely:
+
+```console
+$ tmuxp load --no-progress myproject
+```
+
+Or via environment variable:
+
+```console
+$ TMUXP_PROGRESS=0 tmuxp load myproject
+```
+
+When progress is disabled, logging flows normally to the terminal and no spinner is rendered.
+
+### Before-script behavior
+
+During `before_script` execution, the progress bar shows a marching animation and a ⏸ status icon, indicating that tmuxp is waiting for the script to finish before continuing with pane creation.

docs/configuration/environmental-variables.md

@@ -24,3 +24,54 @@ building sessions. For this case you can override it here.
 ```console
 $ env LIBTMUX_TMUX_FORMAT_SEPARATOR='__SEP__' tmuxp load [session]
 ```
+
+(TMUXP_PROGRESS)=
+
+## `TMUXP_PROGRESS`
+
+Master on/off switch for the animated progress spinner during `tmuxp load`.
+Defaults to `1` (enabled). Set to `0` to disable:
+
+```console
+$ TMUXP_PROGRESS=0 tmuxp load myproject
+```
+
+Equivalent to the `--no-progress` CLI flag.
+
+(TMUXP_PROGRESS_FORMAT)=
+
+## `TMUXP_PROGRESS_FORMAT`
+
+Set the spinner line format. Accepts a preset name (`default`, `minimal`, `window`, `pane`, `verbose`) or a custom format string with tokens like `{session}`, `{bar}`, `{progress}`:
+
+```console
+$ TMUXP_PROGRESS_FORMAT=minimal tmuxp load myproject
+```
+
+Custom format example:
+
+```console
+$ TMUXP_PROGRESS_FORMAT="{session} {bar} {overall_percent}%" tmuxp load myproject
+```
+
+Equivalent to the `--progress-format` CLI flag.
+
+(TMUXP_PROGRESS_LINES)=
+
+## `TMUXP_PROGRESS_LINES`
+
+Number of script-output lines shown in the spinner panel. Defaults to `3`.
+
+Set to `0` to hide the panel entirely (script output goes to stdout):
+
+```console
+$ TMUXP_PROGRESS_LINES=0 tmuxp load myproject
+```
+
+Set to `-1` for unlimited lines (capped to terminal height):
+
+```console
+$ TMUXP_PROGRESS_LINES=-1 tmuxp load myproject
+```
+
+Equivalent to the `--progress-lines` CLI flag.

src/tmuxp/_internal/colors.py

@@ -610,6 +610,7 @@ def get_color_mode(color_arg: str | None = None) -> ColorMode:
 # ANSI styling utilities (originally from click, via utils.py)
 
 _ansi_re = re.compile(r"\033\[[;?0-9]*[a-zA-Z]")
+ANSI_SEQ_RE = _ansi_re
 
 
 def strip_ansi(value: str) -> str:

src/tmuxp/cli/_colors.py

@@ -12,6 +12,7 @@
 import logging
 
 from tmuxp._internal.colors import (
+    ANSI_SEQ_RE,
     ColorMode,
     Colors,
     UnknownStyleColor,
@@ -25,6 +26,7 @@
 logger = logging.getLogger(__name__)
 
 __all__ = [
+    "ANSI_SEQ_RE",
     "ColorMode",
     "Colors",
     "UnknownStyleColor",