# Workspace Split Pane Plan

## Purpose

Capture the agreed design for workspace-owned split terminals so the feature can be implemented later without redoing scope and architecture decisions.

## Agreed Scope

- Split layouts belong to the workspace, not the screen.
- A workspace may only be actively presented on one screen at a time.
- Split layouts should be visible the same way when that workspace is opened on another monitor.
- Nested splits are supported.
- Any two tabs may be joined into a split.
- Closing a pane causes its sibling to expand.
- Split layout must survive relaunch.

## Non-Goals

- Simultaneous live rendering of the same workspace on multiple screens.
- Full multi-user or collaborative state sync.
- Arbitrary freeform pane layout. The model is tree-based binary splits.
- Solving all interaction polish in the first pass.

## Current Constraint

The current workspace model is flat:

- `WorkspaceController` owns `[TerminalSession]`
- one tab is active at a time
- `ContentView` renders exactly one active `SwiftTermView`

This means split panes are not an additive UI feature. They require a workspace model refactor.

## Recommended Model

Do not model splits as "adjacent tabs with special behavior" internally.

Instead:

1. A workspace owns ordered top-level tabs.
2. Each top-level tab owns a pane tree.
3. Pane tree leaves own `TerminalSession` instances.
4. Pane tree internal nodes represent binary splits.
5. The tab bar can visually present grouped/joined tabs based on the active tab's pane composition.

This keeps the domain model clean while still allowing the desired visual metaphor.

## Proposed Domain Types

```swift
typealias WorkspaceTabID = UUID
typealias PaneID = UUID

struct WorkspaceTab: Identifiable, Equatable, Codable {
    var id: WorkspaceTabID
    var rootPane: PaneNode
    var selectedPaneID: PaneID?
    var titleMode: WorkspaceTabTitleMode
}

enum PaneNode: Equatable, Codable, Identifiable {
    case leaf(PaneLeaf)
    case split(PaneSplit)

    var id: PaneID { ... }
}

struct PaneLeaf: Equatable, Codable, Identifiable {
    var id: PaneID
    var sessionID: UUID
}

struct PaneSplit: Equatable, Codable, Identifiable {
    var id: PaneID
    var axis: SplitAxis
    var ratio: Double
    var first: PaneNode
    var second: PaneNode
}

enum SplitAxis: String, Codable {
    case horizontal
    case vertical
}
```

Notes:

- `ratio` should be persisted so user-adjusted divider positions survive relaunch.
- `selectedPaneID` allows focus-based commands such as split active pane, close active pane, and move focus.
- The persisted model should store session identity separately from runtime AppKit/SwiftTerm objects.

## Runtime Ownership

Global:

- workspace summaries
- workspace ordering
- workspace-to-screen assignment
- hotkeys

Workspace:

- ordered top-level tabs
- active top-level tab
- per-tab pane tree
- active/selected pane
- terminal sessions for pane leaves

Screen:

- which workspace is assigned
- notch open/close state
- geometry and transitions

This remains aligned with the existing workspace architecture.

## Persistence Strategy

Split layout must survive relaunch, so workspace persistence needs to grow beyond summary metadata.

Recommended approach:

1. Keep `WorkspaceSummary` for list metadata only.
2. Introduce a persisted `WorkspaceDocument` or `WorkspaceSnapshot` per workspace.
3. Persist:
   - top-level tabs
   - pane tree
   - active tab ID
   - selected pane ID
   - divider ratios
4. Do not attempt to persist shell process contents.
5. On relaunch, recreate sessions for pane leaves and restore layout structure only.

Important distinction:

- layout persistence is required
- terminal process continuity is not

## UI Model

### Main Content

The active top-level tab renders as a recursive split tree.

- leaf node -> one `SwiftTermView`
- split node -> `HSplitView`/`VSplitView` equivalent SwiftUI container with draggable divider

### Tab Bar

Top-level tabs remain the primary navigation unit.

Visual behavior:

- a normal unsplit tab looks like today
- a joined/split tab should look grouped
- grouped tabs should expose child pane titles visually inside the tab item

Recommended first-pass appearance:

- one outer tab pill per top-level tab
- inside that pill, show compact child title chips for each leaf pane
- highlight the selected pane's chip

This gives the "tabs are joined" feel without making pane leaves first-class top-level tabs in the data model.

## Command Model

New actions likely needed:

- split active pane horizontally
- split active pane vertically
- focus next pane
- focus previous pane
- close active pane
- resize focused split divider
- join tab A into tab B
- detach pane into new top-level tab

Semantics:

- joining any two tabs merges one tab's root pane into the other's tree
- the source top-level tab is removed
- the destination top-level tab remains
- sibling expansion on close is standard tree collapse

## Join Semantics

Joining any two tabs should work as:

1. Choose destination tab.
2. Choose source tab.
3. Replace destination root with a new split node:
   - first child = old destination root
   - second child = source root
4. Remove source tab from workspace order.
5. Select a predictable pane, preferably the source pane that was just added.

An explicit split axis should be required for the join action.

## Close Semantics

When closing a pane:

- if the pane has a sibling, the sibling expands into the parent's position
- if the pane was the only leaf in a top-level tab:
  - close the whole top-level tab if more than one tab exists
  - otherwise create a replacement shell pane, matching current single-tab safety behavior

## Focus Semantics

Pane focus must become explicit.

Recommended rules:

- mouse click focuses that pane
- splitting focuses the new pane
- joining focuses the moved-in pane
- closing a pane focuses the surviving sibling
- top-level tab switch restores the previously selected pane in that tab

## Migration Path

Implement in stages to reduce risk.

### Stage 1: Domain Refactor

- Replace flat workspace tabs with top-level tab objects.
- Introduce pane tree types.
- Keep only one leaf per tab initially so behavior is unchanged.

### Stage 2: Runtime Layout Rendering

- Render pane trees recursively in `ContentView`.
- Add active pane selection.
- Keep persistence off until runtime behavior is stable.

### Stage 3: Split Actions

- Split active pane horizontally/vertically.
- Close pane with sibling expansion.
- Basic focus movement.

### Stage 4: Joined Tab UI

- Update tab bar to show grouped child pane chips.
- Surface active pane clearly.

### Stage 5: Join / Unjoin Flows

- Join any two tabs with explicit axis choice.
- Support promoting a pane back to its own top-level tab if needed.

### Stage 6: Persistence

- Persist pane trees and top-level tab state.
- Recreate sessions on launch.

### Stage 7: Hotkeys and Polish

- Add pane-focused shortcuts.
- Add divider dragging polish.
- Improve visual grouped-tab affordances.

## Main Risks

### 1. Model complexity

The current flat `[TerminalSession]` model is simple. Tree-based layout introduces more state, more edge cases, and more focus semantics.

Mitigation:

- refactor the data model before touching complex UI
- keep top-level tabs and pane leaves distinct

### 2. SwiftTerm view ownership

`TerminalView` cannot be mounted in multiple places safely.

Mitigation:

- preserve current rule: only one active presenting screen per workspace
- keep one runtime `TerminalSession` per pane leaf

### 3. Persistence mismatch

Persisting layout is easy compared with persisting process state.

Mitigation:

- persist layout and selection only
- recreate shell sessions on launch

### 4. Joined-tab UX ambiguity

If grouped tabs are also used as pane chips, the interaction model can get confusing.

Mitigation:

- preserve top-level tabs as the real navigation unit
- use internal chips only as secondary indicators/actions

## Recommended First Implementation Boundary

The first deliverable should include:

- nested binary split trees
- active pane focus
- split and close pane actions
- sibling expansion
- grouped tab appearance
- join any two tabs
- persisted layout across relaunch
- same workspace layout when moved to another screen

The first deliverable should not include:

- simultaneous same-workspace rendering on multiple screens
- drag-and-drop tree editing
- restoring running shell process contents

## Files Likely Impacted

- `CommandNotch/CommandNotch/Models/WorkspaceController.swift`
- `CommandNotch/CommandNotch/Models/WorkspaceRegistry.swift`
- `CommandNotch/CommandNotch/Models/WorkspaceStore.swift`
- `CommandNotch/CommandNotch/ContentView.swift`
- `CommandNotch/CommandNotch/Components/TabBar.swift`
- `CommandNotch/CommandNotch/Models/TerminalSession.swift`
- workspace-related tests

Likely new files:

- pane tree domain types
- persisted workspace document types
- split-pane rendering view(s)
- pane-focused command helpers

## Decision Summary

The feature is feasible.

The correct architecture is:

- workspace-owned split tree
- top-level tabs remain the primary unit
- grouped tab visuals are a UI layer over the pane tree
- one presenting screen per workspace
- persisted layout, not persisted process contents

That is the implementation direction to use when this work is resumed.