feat(dashboard): rebuild tabs + split-pane layout on dockview, default on

[aterrylu]

Summary

Rebuilds the terminal tabs + split-pane layout on dockview and makes it the default. This retires three hand-rolled subsystems — the binary-tree layout (layoutTree.ts), the detached-terminal overlay (SessionMountLayer), and the hidden groups workspace-swap — in favour of a dockview-react dock that owns the pane topology. Implements ADR-047.

The layout system has been a long-standing source of fragility (manual getBoundingClientRect + ResizeObserver + rAF geometry sync, an invisible workspace-swap on sidebar click). This is the rip-and-replace Terry called for.

Problem

graph TD
  subgraph Before["Before — hand-rolled (fragile)"]
    A1["Zustand binary-tree layout<br/>(source of truth)"] --> A2["PaneSlot rects<br/>(getBoundingClientRect)"]
    A2 -->|"ResizeObserver + rAF + setTick"| A3["SessionMountLayer<br/>detached overlay"]
    A3 -->|"fly position:absolute divs<br/>over slot rects"| A4["xterm terminals"]
  end
  subgraph After["After — dockview (single source of truth)"]
    B1["Zustand: activePane + bound workspaces"] -->|"navigation only"| B2["DockviewLayout"]
    B2 -->|"owns topology"| B3["dockview dock<br/>renderer: 'always'"]
    B3 -->|"keeps xterm mounted (keep-alive)"| B4["xterm terminals"]
  end

Loading

• Detached-overlay geometry desynced on resize-during-load / sidebar toggle / fast drag — no single geometry source of truth.
• Hidden groups workspace-swap: clicking a sidebar agent in another group silently swapped your whole visible layout, with near-zero affordance.

Solution

dockview's renderer: 'always' keeps every terminal's xterm DOM mounted across tab switches — eliminating the manual rect-flying overlay, the single most fragile piece. DockviewLayout owns the pane topology; the store keeps only activePane + the bound-workspace maps.

Interaction model

• Click = navigate. Clicking a sidebar agent (or Org Chart / Templates / Schedules / New Agent) opens it solo in its own group.
• Drag = compose. Dragging into the pane area builds a tab or split, and that arrangement is saved as a bound workspace. Clicking any member later restores the whole group; it persists across reloads, and a cold reload restores exactly what you were last viewing. Works from both flat and hierarchical sidebar views.

sequenceDiagram
  participant U as User
  participant DV as DockviewLayout
  participant Z as Zustand (persisted)
  U->>DV: drag Agent B onto Agent A's pane
  DV->>DV: addPanel (compose tab/split)
  DV->>Z: bind workspace {paneIds:[A,B], serialized: toJSON()}
  U->>DV: click Agent C (non-member)
  DV->>DV: show C solo
  U->>DV: click Agent A (member)
  DV->>Z: lookup A's workspace
  DV->>DV: fromJSON(serialized) → restore [A,B]

Loading

Chrome polish: tab titles aligned to the sidebar size; faint active-tab outline (matches the app hairline divider); edge-to-edge terminals; dockview's redundant per-group tab-overflow dropdown hidden; and no phantom split overlay when dragging the highlighted tab (you can't split a pane against itself — handled via onWillShowOverlay).

Two terminal bugs fixed (both regressions the migration surfaced)

Both are the same species — the retired abstraction left a load-bearing assumption behind:

1. Sidebar active-highlight flicker while moving/splitting tabs. dockview fires many transient onDidActivePanelChange events as it rebuilds groups mid-drag; each was mirrored into activePane, walking the highlight between agents. Fix: gate the writeback during an internal drag (onWillDragPanel/onWillDragGroup) and apply only the final active panel on dragend.
2. Terminal idle self-shrink. useTerminal inferred "is this pane visible?" from container.offsetWidth > 0 — true under the old overlay (hidden = 0×0) but false under dockview, which hides panels with visibility:hidden at full size. The guard never tripped → every terminal held a WebGL context → context-loss storm on idle → the addon recreated without re-fitting → an unguarded floor()-based fit() baked the drift into a shrink. Fix: forward dockview's authoritative props.api.isVisible so hidden panels get a real display:none (re-arms the guard for free). Hardened: never send degenerate (cols≤2/rows≤1) resizes to the PTY; re-fit on a settled frame after a WebGL context recreate; skip redundant refits.

Testing

• make check green: biome + tsc + 613 server tests + 327 dashboard tests (added store unit tests for the dockview switchPane path).
• Headless Playwright against the live dev server with real agents, verifying:

Scenario	Result
Click = solo (1 tab)	✓
Drag = compose (1→2 tabs) + bind workspace	✓
Click away → click back = restore group	✓
Cold reload restores last-viewed arrangement	✓
Hidden tab gets real display:none (keep-alive preserved)	✓
Drag highlighted tab → no phantom split overlay; other agent → overlay shows	✓
Drag works in both flat + hierarchical sidebar views	✓

Risks & rollout

• Default flips to dockview. The legacy engine remains behind the layoutEngine flag ('legacy' | 'dockview') as a fallback; the legacy code is untouched, not deleted.
• Reload-on-restore tradeoff: restoring a bound workspace re-mounts its panels (terminals reattach to their PTY — no scrollback loss beyond a reattach). Accepted by Terry as the keep-alive tradeoff for workspace switching.
• Follow-ups (not blocking): (1) a Settings UI toggle to switch engines without editing persisted state — currently only the flag exists; (2) internal-tab-move workspace re-serialization is in place, but deleting the legacy tree/overlay code is a later phase per the ADR.

Alternatives considered

flexlayout-react (runner-up — keep-alive default, lighter, but less polished) and keeping react-resizable-panels (splits-only, doesn't replace the overlay). Full shortlist + rationale in ADR-047 / docs/RESEARCH.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MGMW4cbhv5Le8wka7Th8bS

[nox-0x]

Approving — the dockview rewrite is solid: renderer: 'always' keep-alive correctly replaces the detached overlay, the writeback guards (suppressWriteback, internalDragActive, appliedActiveId) cleanly cut the activation-loop classes that would otherwise plague this kind of bridge, the legacy engine stays intact behind the flag, and the two terminal bugs (highlight flicker, idle self-shrink) have well-reasoned fixes with degenerate-resize and post-WebGL-recreate re-fit backstops. Store unit tests pin both engines on their own terms.

Two non-blocking follow-ups posted inline:

• Stale TEMP(preview-only) comment at store.ts:799 tells the reader to revert the default to legacy, which contradicts the PR's stated intent ("default on") — and ADR-047 itself still phases the flip into PR-5 with default legacy. Reconcile the comment + ADR.
• pruneDead doesn't garbage-collect dvWorkspaces — dead session ids stick in the bindings and the serialized blob, so restoring an old workspace can resurrect a panel for a killed agent that won't get re-pruned until the next sessions update. UX bug, not a crash; can land as a follow-up.