Files
kandev/apps/web/lib/state/dockview-env-switch.ts
T
José Almeida f1bdc56892 feat(layout): roomier pane caps + remember user-set widths (#1005)
* refactor(layout): swap pane width caps for viewport-proportional runtime cap

Replace the hard 350px sidebar / 450px right caps with
max(800, viewport*0.7) so wide displays get a roomy file/terminal
panel and the sidebar can grow with the screen. Pinned minimum is
raised from 50px to 180px so panels don't collapse into unusable slivers.

Caps now live in lib/state/layout-manager/caps.ts; constants module
no longer exports per-column max-px constants.

* feat(layout): persist preferred pane widths, flush on unload, roomier tablet split

- Mirror sidebar / right widths into a sessionStorage pinned-defaults
  slot on every resize; seed brand-new task envs with those widths so
  the user's last-set sizes follow them across tasks.
- Re-apply the runtime cap to every pinned group on each ResizeObserver
  tick so a panel pinned to the old cap grows when the user widens the
  window (and re-clamps when they shrink it).
- Flush the debounced layout save on `beforeunload`, so a reload less
  than 300ms after the last drag doesn't lose the new width.
- Drop the tablet right-panel inner split minSize from 30/20 to 15/15
  so the files vs. terminal proportions match the loosened desktop feel.

* test(e2e): cover pane resize, persistence, and edge cases

Four spec files under apps/web/e2e/tests/layout/ exercise the runtime
cap and pinned-defaults persistence end-to-end via dockview's `.dv-sash`
drag handles and `window.__dockviewApi__`:

- pane-resize-right: drag past the old 450px cap, viewport-shrink
  re-clamp, reload + cross-env propagation of preferred width.
- pane-resize-sidebar: same coverage for the sidebar including
  toggle-off/on width retention.
- pane-persistence-tablet: localStorage round-trip for the tablet
  layout keys (`task-layout-tablet-v1`, `task-layout-right-v2`).
- pane-resize-edge-cases: double-click smoke, rapid drags +
  beforeunload flush, maximize round-trip, sash off-viewport, resize
  with sidebar hidden.

Adds e2e/helpers/dockview-resize.ts for the shared drag + width
read-out helpers.

* fix(layout): cap sidebar at 30% screen width, preserve legacy initial widths

- Split the runtime cap into a sidebar-specific function (max(350, vw*0.3))
  and the right-pane function (max(800, vw*0.7)). File-tree / task-list
  content rarely benefits from more than ~30% of the screen.
- Preserve legacy initial widths: getPinnedWidth now clamps the ratio-based
  default to the old hard limits (350 sidebar, 450 right) so a fresh task
  env opens at exactly the same width as before. Users can still drag past
  these via setConstraints — only the *initial* default is capped tightly.

* fix(layout): address PR review — narrow viewport, hidden sidebar, e2e flake

Bot-review fixups for #1005:

- caps: bound runtime caps by `viewport - VIEWPORT_RESERVE_PX` so the
  800px right-cap floor can't collapse the center column on narrow
  screens (Cubic P1).
- applier: respect `column.maxWidth` on the sidebar too, so the
  `compact` preset's 260px cap is honored at runtime (Cubic P2).
- dockview-store: skip the pinned-defaults mirror when the column is
  hidden — auto-sync infers sidebar from grid index 0, which is the
  center when sidebar is hidden, so an unguarded mirror would
  persist the center's width as the sidebar's (Greptile/Cubic P1).
- trackPinnedWidths: gate the auto-sync on `sidebarVisible` /
  `rightPanelsVisible` for the same reason.
- sizing: use `LAYOUT_RIGHT_RATIO` for non-sidebar columns instead of
  silently reusing the sidebar ratio (Greptile P2).
- e2e: tablet viewport bumped from 1024 → 700 (≥1024 is desktop, not
  tablet — the old viewport never rendered the tablet layout and
  every assertion timed out). Tests now also verify rendered panel
  proportions, not just the localStorage echo (CodeRabbit #2/#3).
- e2e helpers: throw on missing `.dv-sash` instead of returning `-1`
  (CodeRabbit #1); shared `openWideTask` extracted from three spec
  files (CodeRabbit #5); silent `return` in evaluate blocks
  replaced with `throw` for fail-fast (CodeRabbit #4).

* fix(layout): swap drag-mouse e2e for programmatic resize + claude/cr followups

Round 2 of PR review fixups:

- e2e: convert pane-resize-right/sidebar/edge-cases specs from
  `page.mouse` drag-by-delta to a programmatic `splitview.resizeView()`
  call. The mouse-drag approach was flaky in headless CI (5 chromium
  failures across shards 2-4); the programmatic path tests the same
  cap-enforcement and persistence contract without depending on
  pointer-events targeting through a 1px .dv-sash overlay.
- dockview-layout-setup: remove an unreachable guard in
  trackPinnedWidths — `rightIdx === 0 && sidebarVisible` cannot occur
  given the `sv.length < 2` early return (Claude).
- dockview-layout-setup: cancel any in-flight debounce timer in the
  setupLayoutPersistence disposer so a fire can't race with teardown
  and persist stale layout (CodeRabbit).
- constants: document why LAYOUT_SIDEBAR_RATIO and LAYOUT_RIGHT_RATIO
  are both 0.25 today — separate constants stay decoupled so a future
  tweak to one doesn't silently change the other (Claude).

* fix(layout): drop cross-env width propagation — defaults stay unchanged

User feedback: the initial sidebar width on a brand-new task should be
the same as it was before this PR (350px on typical viewports). The
plan's "propagate preferred widths across envs" feature changed that
in practice: after the first resize, every new task opened at the
resized width instead of the legacy default.

- Remove `getPinnedDefaults` / `setPinnedDefaults` helpers and the
  sessionStorage `kandev.dockview.pinned-defaults` slot.
- Drop the write-through in `setPinnedWidth` and the seed in
  `performBuildDefault`. `freshPinned` is back to `new Map()`, so a
  brand-new env always renders at the ratio-based default (same as
  before this PR, since `getPinnedWidth` already clamps the initial
  ratio to the legacy 350/450 hard caps).
- Per-env layout persistence still works via `setEnvLayout` — when a
  user resizes inside a task and switches back later, the width is
  restored. Only the cross-env *default* is no longer carried over.
- Remove e2e tests + helpers that exercised the propagation contract.
- Drop the flaky `rapid resizes persist across reload` edge test —
  too brittle around the debounce/beforeunload race.
- `LAYOUT_INITIAL_RATIO` introduced as the canonical name;
  `LAYOUT_SIDEBAR_RATIO` / `LAYOUT_RIGHT_RATIO` kept as deprecated
  aliases for backwards compatibility while sizing.ts dispatches.

* fix(layout): bump saved-layout storage keys to v2

Layouts saved by intermediate builds of this PR captured sidebar/right
widths beyond the legacy initial caps (when the larger runtime cap was
the only thing constraining serialized widths). Restoring those layouts
on the current build replays the over-wide widths, defeating the
"defaults stay the same" guarantee.

Bumping the storage key prefixes (`env-layout` → `env-layout-v2`,
`env-maximize` → `env-maximize-v2`, `dockview-layout-v1` →
`dockview-layout-v2`) invalidates legacy saves once on first open;
subsequent opens persist + restore under v2 normally. Existing users
lose stored column widths once and re-customize from defaults — a
one-time cost in exchange for the upgrade being clean.

* fix(layout): apply target env's widths after fast-path switch

Fast-path env switch (`tryFastEnvSwitch`) skips `fromJSON` for speed,
which means column widths carry over from the *outgoing* env. If a
user resized the sidebar to 480px in task A and then opens task B,
B inherits A's 480px sidebar — even with empty sessionStorage on
different dev-server ports, because the widths live in dockview's
in-memory grid state, not in storage.

Explicitly resize sidebar/right after the panel swap:
  - saved layout exists for target env → use its serialized sizes
  - no saved layout (brand-new env) → compute defaults via
    `getPinnedWidth` (legacy initial caps: 350 sidebar / 450 right)

* fix(layout): pass measured dims to fromJSON so widths don't grow on rescale

Even on a fresh dev instance with no prior storage, brand-new tasks
were opening with oversized sidebar/right widths. Root cause: applyLayout
fed `api.width` into toSerializedDockview, but `api.width` lags the live
container during the dockview mount sequence. fromJSON wrote a layout
sized for the stale width; the subsequent `api.layout(safeWidth, ...)`
in performBuildDefault's rAF rescaled the grid proportionally — and
without the old hard cap (350/450) clamping it, the sidebar grew past
its legacy default.

Pass the measured container dimensions through applyLayout into
toSerializedDockview so fromJSON's grid.width already matches the live
container. api.layout in the rAF is then a no-op, no rescale, and
sidebar/right open at exactly their legacy defaults.

Also applies to applyBuiltInPreset and applyCustomLayout for the same
flow.

* fix(layout): lock pinned column max width to current size, unlock on drag

The real reason brand-new tasks opened with oversized sidebar/right:
dockview's splitview rebalances pinned columns proportionally on every
`api.layout` call. After we relaxed setConstraints from the legacy
350/450 hard caps to viewport-proportional runtime caps (576/1344),
nothing clamped the rebalance — sidebar grew from 350 → ~450, right
from 450 → ~530 on the first ResizeObserver tick.

New invariant: pinned-column `maximumWidth` is locked to the column's
*current* width whenever the user is not actively dragging a sash. The
rebalance has zero room to grow.

- `applyLayout` / `applyLayoutFixups` set the lock as soon as fromJSON
  finishes — sidebar/right open at exactly their just-computed widths.
- `setupContainerResizeSync` re-applies the lock on every viewport
  ResizeObserver tick before and after `api.layout`.
- `setupSashDragCapToggle` listens for mousedown/mouseup on `.dv-sash`:
  on mousedown, widen the cap to the runtime viewport-proportional cap
  so the user can drag past the legacy default; on mouseup, snap the
  cap back to the new current width.

Also addresses Claude's latest review:
- caps.test.ts: rename "hits the 350px floor on roomy viewports" → "…
  when vw*0.3 falls below the minimum" (test name now matches assertion).
- dockview-resize.ts: drop the stale "pinned-defaults mirror" comment;
  guard the sidebar splitview index against the hidden-sidebar footgun.
- pane-resize-right.spec.ts: rename the reload test to mention the
  correct localStorage key (`dockview-layout-v2`).
- new `dockview-env-switch-pinned.test.ts` unit-tests applyPinned-
  ColumnSizes with a spy splitview — verifies sidebar/right are
  explicitly resized after a fast-path env switch.

* fix(layout): constrain all groups, loosen e2e resize cap, drop stale docs

Round of PR-review fixes:

- applier: `applyConstraintsToAllPanelGroups` replaces the previous
  first-only helper. The default right column has separate top + bottom
  groups; constraining only the first left the bottom group unbounded
  and let the column grow on rebalance via that group (cubic P2 +
  Claude regression).
- sizing: collapse `LAYOUT_SIDEBAR_RATIO` / `LAYOUT_RIGHT_RATIO`
  dispatch — they alias the same `LAYOUT_INITIAL_RATIO`, so the
  ternary was a silent no-op (Claude).
- sizing: doc — drop "widths seeded from pinned-defaults sessionStorage"
  reference; that feature was removed in fb3dbe4 (Claude).
- e2e/dockview-resize: the latest fix locks pinned-column maxWidth to
  current width, which clamps `sv.resizeView` in tests. Loosen the
  constraint to the same runtime cap the sash-drag handler uses on
  user mousedown — so cap-enforcement assertions still work end-to-end
  without burning the 10-minute CI timeout retrying clamped resizes.

* fix(layout): mirror viewportBound clamp in e2e test cap helper

Claude & cubic flagged that `resizeColumnViaSplitview`'s runtime-cap
computation skipped the `viewportBound(value, vw - 300)` step that
production caps go through. On narrow viewports (vw < ~1143px) the
helper's cap would exceed what dockview actually enforces, so
cap-clamp assertions would drift from real app behaviour.

Mirror the caps.ts logic exactly in the helper.

* fix(layout): pin-by-target, not lock-by-current — defeats the ratchet bug

My previous attempt (lock max=current width except during sash drag) was
fundamentally broken: any transient container shrink would lock the cap
at the smaller size, and dockview's proportional rebalance could never
restore the column. Under heavy ResizeObserver fluctuation on reload, the
sidebar marched all the way down to LAYOUT_PINNED_MIN_PX (180px).

New invariant: pinned-column max is the *runtime cap* (loose enough for
the user to drag past the legacy default), and a separate "target width"
is tracked per pinned column. After every `onDidLayoutChange` event the
column is force-restored to its target via `sv.resizeView`.

Target is updated only by explicit actions:
- `applyLayout` sets it to the computed default after `fromJSON`.
- `applyLayoutFixups` sets it to the just-restored width on saved-layout
  restore.
- `applyPinnedColumnSizes` (fast-path env switch) sets it to the saved /
  default width.
- The sash-drag handler sets it to the new width on mouseup.

`pinnedTargets` live in a new module `lib/state/layout-manager/pinned-targets.ts`.
`setPinnedTarget` / `getPinnedTarget` are exported from the layout-manager
barrel. An `enforcing` guard around `enforcePinnedTargets` prevents the
restore-via-resizeView from re-triggering itself.

E2E helper additions:
- `__persistDockviewLayout__` exposed on `window` (test seam) — calls the
  setupLayoutPersistence `persistNow` directly. `sv.resizeView` doesn't
  emit `onDidLayoutChange` in dockview 4.x, so the helper now force-flushes
  the layout after each programmatic resize. Without this, reload tests
  never saw a saved layout.
- `__setPinnedTarget__` exposed too so the helper can update the target
  after a programmatic resize, mirroring sash-drag mouseup.
- Dropped the brittle `data-panel-id` width assertion in the tablet
  persistence test; the localStorage round-trip is the persistence
  contract, and `react-resizable-panels`' internal DOM is version-dependent.

Local validation: all 15 layout e2e tests pass; full unit suite (2087)
green; format + lint + typecheck clean.

* fix(layout): pause target enforcement during sash drag + cleanup test seam

Three follow-ups from the latest review round:

- cubic P1: pause `enforcePinnedTargets` while the user is actively
  dragging a sash. Without this, an in-progress layout-change event
  during the drag would revert the in-flight resize before mouseup
  records the new target. The new `sashDragging` flag is set on
  mousedown over `.dv-sash` and cleared on mouseup.
- claude: clear `window.__persistDockviewLayout__` in the
  setupLayoutPersistence disposer so a remount can't be racing with a
  stale closure from the previous mount.
- claude: third unit test exercises the right column's saved-layout
  resize path (sv.length = 3 covering both pinned columns), now that
  the previous test bounded the loop at sv.length = 2 and only
  reached the sidebar.

* test(e2e): bump dockview-layout-v1 → v2 in plan-panel-indicator spec

The storage key was bumped from v1 → v2 in fb3dbe4 (drop cross-env
width propagation). The plan-panel-indicator spec was waiting for the
old `dockview-layout-v1` localStorage key to materialise after a
debounced save — that key is never written under v2, so the
waitForFunction always timed out.

* fix(layout): reset sashDragging on disposer + only track left-button drags

Two safety fixes for the module-scope `sashDragging` flag:

- claude: clear it in the setupSashDragCapToggle disposer. If the user
  starts dragging a sash and unmounts mid-drag (e.g. navigates away),
  the flag stayed `true` forever and `enforcePinnedTargets` would never
  fire again on the next mount.
- cubic P2: only set the flag on left-button mousedown. A right/middle
  click over a sash currently flipped it true, and the mouseup handler
  ignores non-left buttons — so the flag would stick and pause
  enforcement until a left mousedown→up cycle.

* fix(ui): preserve session mode selector state

* fix(ui): format fallback session mode labels
2026-05-24 11:26:56 +01:00

505 lines
18 KiB
TypeScript

/**
* Env switch logic for dockview layout management.
*
* Layouts are keyed by `taskEnvironmentId`. Sessions sharing an env reuse the
* same layout, so switching between same-env sessions is a no-op at the
* layout level (handled by the caller). Cross-env switches use either a
* "fast path" (skip fromJSON when the structure already matches) or a
* "slow path" (full layout rebuild via fromJSON).
*/
import type { DockviewApi, SerializedDockview } from "dockview-react";
import { getEnvLayout } from "@/lib/local-storage";
import { applyLayoutFixups } from "./dockview-layout-builders";
import { isLayoutShapeHealthy } from "./dockview-layout-health";
import {
fromDockviewApi,
savedLayoutMatchesLive,
layoutStructuresMatch,
getPinnedWidth,
getRootSplitview,
setPinnedTarget,
} from "./layout-manager";
import type { LayoutState, LayoutGroupIds } from "./layout-manager";
import { createDebugLogger, IS_DEBUG } from "@/lib/debug/log";
const debug = createDebugLogger("dockview:env-switch");
// eslint-disable-next-line @typescript-eslint/no-explicit-any
function snapshotGridShape(node: any, depth = 0): unknown {
if (!node || depth > 6) return null;
if (node.type === "leaf") {
return {
type: "leaf",
groupId: node.data?.id,
activeView: node.data?.activeView,
views: node.data?.views,
};
}
if (node.type === "branch" && Array.isArray(node.data)) {
return {
type: "branch",
orientation: node.orientation,
children: node.data.map((c: unknown) => snapshotGridShape(c, depth + 1)),
};
}
return null;
}
const EPHEMERAL_COMPONENTS = new Set([
"file-editor",
"browser",
"vscode",
"commit-detail",
"diff-viewer",
"pr-detail",
]);
/** Fetch the saved layout for an env, dropping it if its shape is corrupted. */
function getHealthyEnvLayout(envId: string): object | null {
const saved = getEnvLayout(envId);
if (!saved) return null;
return isLayoutShapeHealthy(saved) ? saved : null;
}
/** Check whether a serialized dockview layout contains ephemeral panels. */
function savedLayoutHasEphemeralPanels(serialized: SerializedDockview): boolean {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const panels = (serialized as any).panels as
| Record<string, { contentComponent?: string }>
| undefined;
if (!panels) return false;
return Object.values(panels).some((p) => EPHEMERAL_COMPONENTS.has(p.contentComponent ?? ""));
}
/** Walk the serialized grid tree collecting (groupId, activeView) for each leaf. */
function collectSavedActiveViews(
saved: SerializedDockview,
): Array<{ groupId: string; activeView: string }> {
const out: Array<{ groupId: string; activeView: string }> = [];
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const walk = (node: any): void => {
if (!node) return;
if (Array.isArray(node.data)) {
for (const child of node.data) walk(child);
return;
}
const data = node.data;
if (data?.id && data.activeView) out.push({ groupId: data.id, activeView: data.activeView });
};
// eslint-disable-next-line @typescript-eslint/no-explicit-any
walk((saved as any).grid?.root);
return out;
}
/**
* Restore each group's `activeView` from the saved layout. The fast path
* doesn't call `fromJSON`, so per-group active tabs would otherwise carry
* over from the outgoing env (e.g. Task B left "changes" focused in the
* right group, and switching back to Task A would still show "changes"
* even though Task A had "plan" active when it was last saved).
*
* The saved `activeGroup` is applied last so the resulting global focus
* matches what was persisted.
*/
function restoreSavedActiveViews(api: DockviewApi, saved: SerializedDockview): void {
const entries = collectSavedActiveViews(saved);
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const savedActiveGroup = (saved as any).activeGroup as string | undefined;
const ordered = savedActiveGroup
? [
...entries.filter((e) => e.groupId !== savedActiveGroup),
...entries.filter((e) => e.groupId === savedActiveGroup),
]
: entries;
for (const { groupId, activeView } of ordered) {
const group = api.groups.find((g) => g.id === groupId);
if (!group) continue;
const panel = group.panels.find((p) => p.id === activeView);
if (panel) {
try {
panel.api.setActive();
} catch {
/* panel may be in a transient state */
}
}
}
}
export type EnvSwitchParams = {
api: DockviewApi;
oldEnvId: string | null;
newEnvId: string;
/** Active session for the incoming env — used to keep the right session chat tab. */
activeSessionId: string | null;
safeWidth: number;
safeHeight: number;
buildDefault: (api: DockviewApi) => void;
getDefaultLayout: () => LayoutState;
};
/**
* Predicate matching panels that `removeEphemeralPanels` will close.
*
* Ephemeral panels (file-editors, diffs, commit-details, etc.) are env-scoped
* and never carry across switches. When `keepSessionId` is provided, chat
* panels for any other session are also removed so the old env's session tab
* doesn't bleed into the new env. Pulled out so `computeSurvivingIndex` can
* reuse the same survival rules without duplicating them.
*/
function shouldRemoveDuringSwitch(
panel: { id: string; api: { component: string } },
keepSessionId: string | null,
): boolean {
const comp = panel.api.component;
if (EPHEMERAL_COMPONENTS.has(comp)) return true;
if (
keepSessionId !== null &&
comp === "chat" &&
panel.id.startsWith("session:") &&
panel.id !== `session:${keepSessionId}`
) {
return true;
}
return false;
}
/**
* Close every panel that matches `shouldRemoveDuringSwitch`. Used to clear
* env-scoped ephemerals before the new env's panels are restored.
*/
function removeEphemeralPanels(api: DockviewApi, keepSessionId: string | null): void {
const toRemove = api.panels.filter((p) => shouldRemoveDuringSwitch(p, keepSessionId));
for (const p of toRemove) {
try {
p.api.close();
} catch {
/* panel may already be gone */
}
}
}
/**
* Replace stale session chat panels with the incoming active session.
*
* A "stale" session is any `session:*` panel whose id isn't
* `session:${keepSessionId}` — typically a phantom carried in from a saved
* layout whose session belongs to a different env (or has been deleted).
*
* Before closing the first stale panel, add the active session at the same
* (group, tab-index). This preserves the user's grouping when the stale was
* co-tabbed with non-session siblings (pr-detail, dragged file-editors,
* etc.) — without it, the siblings would be orphaned in a group with no
* session, and `useAutoSessionTab` would later add the active session as a
* fresh split next to the sidebar.
*
* File-editors/diffs/browser/etc. are NEVER touched here — they
* legitimately belong to this env's saved state.
*/
function replaceStaleSessionPanels(api: DockviewApi, keepSessionId: string | null): void {
const keepId = keepSessionId ? `session:${keepSessionId}` : null;
// keepId=null (sessionless task) → strips all session panels, unlike the
// fast path's shouldRemoveDuringSwitch which keeps them. In practice
// sessionless tasks should have no session panels; useAutoSessionTab
// re-adds the panel when a session arrives.
const stale = api.panels.filter(
(p) => p.api.component === "chat" && p.id.startsWith("session:") && p.id !== keepId,
);
// Anchor the active session to the first stale's (group, index) so co-tabbed
// siblings (pr-detail etc.) stay grouped with the agent tab. Skipped when:
// - no keepSessionId (sessionless task)
// - the active session panel already exists in the layout
// - the stale's group is missing from the live api (defensive)
//
// Limitation: if the saved layout had stale sessions in multiple groups
// (rare — requires multi-session contamination across env boundaries),
// only the first stale's group keeps its siblings. Sessions in other
// groups still close, orphaning anything co-tabbed with them. One active
// session can only re-anchor one group.
if (keepSessionId && !api.getPanel(`session:${keepSessionId}`) && stale.length > 0) {
const first = stale[0];
const groupId = first.group.id;
if (api.groups.some((g) => g.id === groupId)) {
const idx = first.group.panels.findIndex((p) => p.id === first.id);
addIncomingSessionPanel(api, keepSessionId, groupId, idx);
}
}
if (IS_DEBUG) {
debug("replaceStaleSessionPanels", {
keepSessionId,
livePanelIds: api.panels.map((p) => p.id),
removingIds: stale.map((p) => p.id),
});
}
for (const p of stale) {
try {
p.api.close();
} catch {
/* panel may already be gone */
}
}
}
/**
* Given the panels of a group and the id of the panel being replaced, return
* the target tab index for the replacement among the siblings that will
* survive `removeEphemeralPanels`. Returns -1 if the panel isn't in the group.
*/
function computeSurvivingIndex(
groupPanels: readonly { id: string; api: { component: string } }[],
outgoingPanelId: string | undefined,
keepSessionId: string | null,
): number {
if (!outgoingPanelId) return -1;
const idx = groupPanels.findIndex((p) => p.id === outgoingPanelId);
if (idx < 0) return -1;
let count = 0;
for (let i = 0; i < idx; i++) {
if (!shouldRemoveDuringSwitch(groupPanels[i], keepSessionId)) count++;
}
return count;
}
/**
* Fast path: check if we can skip `api.fromJSON()` because the layout
* structure hasn't changed. Returns group IDs if the fast path was taken,
* or null if a full rebuild is needed.
*/
function tryFastEnvSwitch(params: EnvSwitchParams): LayoutGroupIds | null {
const { api, newEnvId, activeSessionId, getDefaultLayout } = params;
const currentLayout = fromDockviewApi(api);
const saved = getHealthyEnvLayout(newEnvId);
let structuresMatch = false;
if (saved) {
structuresMatch = savedLayoutMatchesLive(currentLayout, saved as SerializedDockview);
} else {
structuresMatch = layoutStructuresMatch(currentLayout, getDefaultLayout());
}
if (!structuresMatch) {
if (IS_DEBUG) {
debug("tryFastEnvSwitch: structures do not match, falling back to slow path", {
newEnvId,
hasSaved: !!saved,
currentPanelIds: api.panels.map((p) => p.id),
});
}
return null;
}
if (saved && savedLayoutHasEphemeralPanels(saved as SerializedDockview)) {
debug("tryFastEnvSwitch: saved layout has ephemeral panels, falling back to slow path", {
newEnvId,
});
return null;
}
if (IS_DEBUG) {
debug("tryFastEnvSwitch: taking fast path", {
newEnvId,
activeSessionId,
hasSaved: !!saved,
currentPanelIds: api.panels.map((p) => p.id),
});
}
// Prefer the active session panel so multi-session tasks anchor the
// incoming panel to the group the user was looking at, not whichever
// session tab happens to come first in `api.panels` iteration order.
const isSessionPanel = (p: (typeof api.panels)[number]) =>
p.id.startsWith("session:") || p.api.component === "chat";
const outgoingSessionPanel =
api.panels.find((p) => isSessionPanel(p) && p.api.isActive) ?? api.panels.find(isSessionPanel);
const outgoingGroup = outgoingSessionPanel?.group;
const outgoingGroupId = outgoingGroup?.id;
// Capture the session's index among siblings that will survive
// `removeEphemeralPanels`, so the new session panel lands in the same tab
// slot. Without this, dockview appends and the agent tab drifts to the end
// of the group on every cross-task fast-path switch.
const outgoingIndex = outgoingGroup
? computeSurvivingIndex(outgoingGroup.panels, outgoingSessionPanel?.id, activeSessionId)
: -1;
removeEphemeralPanels(api, activeSessionId);
if (activeSessionId && !api.getPanel(`session:${activeSessionId}`)) {
addIncomingSessionPanel(api, activeSessionId, outgoingGroupId, outgoingIndex);
}
// The fast path skips `fromJSON`, so per-group active tabs from the
// outgoing env would otherwise persist into the incoming env. Reapply
// them from the saved layout to match what `fromJSON` would have done.
if (saved) restoreSavedActiveViews(api, saved as SerializedDockview);
// Column widths from the outgoing env stay live across the switch because
// we skipped fromJSON. Apply the target env's widths explicitly:
// - saved layout exists → use its serialized sizes
// - no saved layout (brand-new env) → compute fresh defaults via
// getPinnedWidth (ratio-based, clamped to legacy initial cap)
applyPinnedColumnSizes(api, saved as SerializedDockview | null, params.safeWidth);
api.layout(params.safeWidth, params.safeHeight);
return applyLayoutFixups(api);
}
/** Extract per-column sizes from a saved SerializedDockview grid root. */
function extractSavedColumnSizes(saved: SerializedDockview): number[] | null {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const root = (saved as any).grid?.root;
if (!root?.data || !Array.isArray(root.data)) return null;
// eslint-disable-next-line @typescript-eslint/no-explicit-any
return root.data.map((child: any) => (typeof child?.size === "number" ? child.size : NaN));
}
/** Compute the target width for a pinned column from saved sizes or fall
* back to the preset's ratio-based default. */
function targetPinnedWidth(
col: LayoutState["columns"][number],
index: number,
savedSizes: number[] | null,
totalWidth: number,
): number | undefined {
if (savedSizes && Number.isFinite(savedSizes[index])) return savedSizes[index];
return getPinnedWidth(col, totalWidth, undefined);
}
/**
* After a fast-path env switch, override the inherited column widths with
* the target env's values. Without this, the outgoing env's user-resized
* widths bleed into the new env — a brand-new task would open at whatever
* width the user last dragged the previous task's sidebar/right to.
*/
function applyPinnedColumnSizes(
api: DockviewApi,
saved: SerializedDockview | null,
totalWidth: number,
): void {
const sv = getRootSplitview(api);
if (!sv || sv.length < 2) return;
const savedSizes = saved ? extractSavedColumnSizes(saved) : null;
const liveLayout = fromDockviewApi(api);
for (let i = 0; i < liveLayout.columns.length && i < sv.length; i++) {
const col = liveLayout.columns[i];
if (col.id !== "sidebar" && col.id !== "right") continue;
const target = targetPinnedWidth(col, i, savedSizes, totalWidth);
if (typeof target !== "number" || target <= 0) continue;
try {
sv.resizeView(i, target);
// Update the pinned-target so enforcement keeps the new env's width
// through subsequent rebalances.
setPinnedTarget(col.id, target);
} catch {
/* dockview rejects out-of-range sizes — ignore */
}
}
}
/**
* Add the incoming task's session chat panel, restoring it to the same tab
* slot the outgoing session occupied within `outgoingGroupId` when possible.
*/
function addIncomingSessionPanel(
api: DockviewApi,
sessionId: string,
outgoingGroupId: string | undefined,
outgoingIndex: number,
): void {
let position: import("dockview-react").AddPanelOptions["position"];
if (outgoingGroupId && api.groups.some((g) => g.id === outgoingGroupId)) {
position =
outgoingIndex >= 0
? { referenceGroup: outgoingGroupId, index: outgoingIndex }
: { referenceGroup: outgoingGroupId };
} else if (api.getPanel("sidebar")) {
position = { direction: "right" as const, referencePanel: "sidebar" };
}
api.addPanel({
id: `session:${sessionId}`,
component: "chat",
tabComponent: "sessionTab",
title: "Agent",
params: { sessionId },
position,
});
}
/**
* Switch the dockview layout between task environments.
*
* Uses a fast path when layouts are structurally identical (common case),
* falling back to a full `api.fromJSON()` rebuild when they differ.
*
* The caller is responsible for saving the old env's layout and releasing
* env-scoped portals before calling this function.
*/
export function performEnvSwitch(params: EnvSwitchParams): LayoutGroupIds {
const { api, oldEnvId, newEnvId, activeSessionId, safeWidth, safeHeight, buildDefault } = params;
if (IS_DEBUG) {
debug("performEnvSwitch: entry", {
oldEnvId,
newEnvId,
activeSessionId,
livePanelIdsBefore: api.panels.map((p) => p.id),
});
}
const fastResult = tryFastEnvSwitch(params);
if (fastResult) {
if (IS_DEBUG) {
debug("performEnvSwitch: completed via fast path", {
newEnvId,
livePanelIdsAfter: api.panels.map((p) => p.id),
});
}
return fastResult;
}
const saved = getHealthyEnvLayout(newEnvId);
if (saved) {
try {
if (IS_DEBUG) {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const savedPanelIds = Object.keys((saved as any).panels ?? {});
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const savedShape = snapshotGridShape((saved as any).grid?.root);
debug("performEnvSwitch: slow path - calling api.fromJSON", {
newEnvId,
savedPanelIds,
savedShape,
});
}
api.fromJSON(saved as SerializedDockview);
// Saved layout may carry a stale session panel from a previously-deleted
// task (phantom). Replace stale session panels with the incoming active
// session in the same (group, tab-index), then close the stale ones —
// preserves grouping with co-tabbed siblings (pr-detail, dragged file
// editors, etc.). File editors/diffs/etc. on their own are legitimately
// part of this env's saved state and must NOT be touched.
// useAutoSessionTab will still no-op if the panel was just added here.
replaceStaleSessionPanels(api, activeSessionId);
api.layout(safeWidth, safeHeight);
if (IS_DEBUG) {
debug("performEnvSwitch: completed via slow path (fromJSON)", {
newEnvId,
livePanelIdsAfter: api.panels.map((p) => p.id),
});
}
return applyLayoutFixups(api);
} catch (err) {
console.warn("performEnvSwitch: fromJSON threw", err);
debug("performEnvSwitch: fromJSON threw, falling through to default", { newEnvId, err });
/* fall through to default layout build */
}
}
debug("performEnvSwitch: building default layout", { newEnvId, hasSaved: !!saved });
buildDefault(api);
api.layout(safeWidth, safeHeight);
if (IS_DEBUG) {
debug("performEnvSwitch: completed via default build", {
newEnvId,
livePanelIdsAfter: api.panels.map((p) => p.id),
});
}
return applyLayoutFixups(api);
}