# Save Current Tab as New Config — Tech Spec

Product spec: `specs/APP-3704/PRODUCT.md`

## Problem

There is no code path to convert a live tab's pane tree into a `TabConfig` TOML. The existing `PaneTemplateType::try_from(PaneNodeSnapshot)` in `launch_configs/launch_config.rs` converts snapshots to the launch config format but drops non-terminal panes entirely and produces a `PaneTemplateType`, not a `TabConfig`.

## Relevant Code

- `app/src/tab_configs/session_config.rs:174` — `tab_config_from_pane_snapshot` (new)
- `app/src/tab_configs/session_config.rs:194` — `snapshot_to_flat_panes` helper (new)
- `app/src/tab_configs/session_config.rs:144` — `write_tab_config` (updated signature)
- `app/src/tab_configs/tab_config.rs` — `TabConfig`, `TabConfigPaneNode`, `TabConfigPaneType`
- `app/src/pane_group/mod.rs:2029` — `PaneGroup::snapshot()` returns `PaneNodeSnapshot`
- `app/src/app_state.rs` — `PaneNodeSnapshot`, `LeafContents`, `TerminalPaneSnapshot`, `BranchSnapshot`
- `app/src/tab.rs:340` — `save_config_menu_items` (new)
- `app/src/workspace/action.rs:561` — `WorkspaceAction::SaveCurrentTabAsNewConfig`
- `app/src/workspace/view.rs:4969` — `save_current_tab_as_new_config` handler (new)
- `app/src/workspace/view.rs:16831` — action dispatch
- `app/src/user_config/mod.rs` — `find_unused_toml_path`, `tab_configs_dir`

## Current State

**Snapshot infrastructure:** `PaneGroup::snapshot()` recursively walks the pane tree and produces a `PaneNodeSnapshot` with `Branch` and `Leaf` variants. Leaf snapshots carry `LeafContents` which is `Terminal(TerminalPaneSnapshot)`, `Notebook(...)`, `Code(...)`, etc. `TerminalPaneSnapshot` includes `cwd: Option<String>` and `is_active: bool`.

**Tab config serialization:** `TabConfig` derives both `Serialize` and `Deserialize` (added in APP-3575). `write_tab_config` in `session_config.rs` serializes via `toml::to_string_pretty` and writes to disk.

**Tab right-click menu:** Built in `TabData::menu_items()` with four sections: session sharing, modify tab, close tab, and color. Each section is a separate method returning `Vec<MenuItem<WorkspaceAction>>`.

**Open-in-editor pattern:** `create_and_open_new_tab_config` writes a file, resolves the editor target via `EditorSettings`, and calls `open_file_with_target`.

## Changes

### 1. `tab_config_from_pane_snapshot` and `snapshot_to_flat_panes`

Added to `app/src/tab_configs/session_config.rs`. Public function `tab_config_from_pane_snapshot` accepts `&PaneNodeSnapshot`, optional title, and optional color. It delegates to a private recursive helper `snapshot_to_flat_panes` that walks the tree with a `&mut usize` counter for ID generation (`"p1"`, `"p2"`, …).

Branch nodes: reserve their ID, recurse into children to collect child IDs, then insert the split node before the children in the flat list (root-first ordering via `panes.insert(insert_pos, ...)`).

Terminal leaves: extract `cwd` from `TerminalPaneSnapshot.cwd`, set `pane_type = Terminal`, set `is_focused = Some(true)` only when focused (otherwise `None` — omitted from TOML).

Non-terminal leaves: produce a terminal pane with no `cwd`, preserving the split layout.

Returns `TabConfig { name: "My Tab Config", title: custom_title, color, panes, params: HashMap::new() }`.

### 2. `write_tab_config` generalized

Signature changed to accept `base_name: &str` instead of hardcoding `"startup_config"`. Call site in `handle_session_config_completed` updated to pass `"startup_config"`. The new save handler passes `"my_tab_config"`.

### 3. `WorkspaceAction::SaveCurrentTabAsNewConfig(usize)`

Added at `workspace/action.rs:561`. Returns `false` in `should_save_app_state_on_action` — writing a config file doesn't change workspace state.

### 4. `save_config_menu_items` in `TabData`

Added at `tab.rs:340`. Static method gated behind `FeatureFlag::TabConfigs`. Returns a single "Save as new config" item dispatching `SaveCurrentTabAsNewConfig(index)`. Inserted in `menu_items()` between the close-tab section and the color section.

### 5. `save_current_tab_as_new_config` workspace handler

Added at `workspace/view.rs:4969`. Gated behind `#[cfg(feature = "local_fs")]` with a no-op stub for non-local-fs builds. Inline-imports `tab_config_from_pane_snapshot` and `write_tab_config` to match the existing inline import pattern used by `handle_session_config_completed`. Snapshots the tab's pane group, extracts custom title and color, builds the `TabConfig`, writes TOML to `~/.warp/tab_configs/my_tab_config.toml` (collision-safe), and opens the file in the user's editor via `resolve_file_target` + `open_file_with_target`.

Action dispatch wired at `workspace/view.rs:16831`.

## End-to-End Flow

1. User right-clicks a tab → `TabData::menu_items()` runs, includes "Save as new config" (flag-gated).
2. User clicks → `WorkspaceAction::SaveCurrentTabAsNewConfig(tab_index)` dispatched.
3. Workspace handler snapshots the tab's `PaneGroup` via `snapshot()`.
4. `tab_config_from_pane_snapshot` converts the `PaneNodeSnapshot` tree into a flat `TabConfig`.
5. `write_tab_config` serializes to TOML and writes to `~/.warp/tab_configs/my_tab_config.toml`.
6. The file is opened in the user's configured editor.
7. The filesystem watcher detects the new file and adds it to the `+` menu.

## Risks and Mitigations

**Non-terminal pane replacement:** Replacing non-terminal panes with empty terminals is lossy — the user might not expect an empty pane when reopening the config. Mitigated by opening the file in the editor immediately, so the user can see and adjust the result.

**Snapshot timing:** `PaneGroup::snapshot()` is synchronous and captures the current state at call time. If a shell is still initializing, `cwd` might be empty. This is the same risk as the existing launch config save flow, which is acceptable.

## Testing and Validation

### `tab_config_from_pane_snapshot` (unit tests in `session_config_tests.rs`)

- `snapshot_single_terminal_pane` — single leaf produces correct cwd, `is_focused = true`, ID `"p1"`.
- `snapshot_two_pane_horizontal_split` — split root `"p1"` + two leaf children `"p2"` and `"p3"` with correct cwds.
- `snapshot_2x2_grid` — 3 split nodes + 4 leaf nodes = 7 total panes, root is `"p1"`.
- `snapshot_non_terminal_leaf_replaced_with_terminal` — notebook pane replaced with `pane_type = Terminal`, `cwd = None`.
- `snapshot_preserves_custom_title_and_color` — title and color propagated to `TabConfig`.
- `snapshot_round_trip_toml` — `toml::to_string_pretty` → `toml::from_str` produces matching `TabConfig`.

### `write_tab_config` with custom base name

- `write_tab_config_custom_base_name` — base name `"my_tab_config"` writes to `my_tab_config.toml`.
- Existing `write_tab_config_creates_file_with_correct_naming` tests updated for new `base_name` parameter.

### Manual verification

- Build and run Warp, create a split layout, right-click → "Save as new config", verify the TOML, open from `+` menu.

## Follow-ups

- **"Save and update config":** Track which tab config a tab was opened from (store path on `TabData` or `PaneGroup`), and overwrite on save.
- **Agent/Cloud pane handling:** Currently all panes save as `type = "terminal"`. Once agent/cloud panes are more common, detect them from the snapshot and save `type = "agent"` or `type = "cloud"`.