diff --git a/apps/web/components/task/dockview-desktop-layout.tsx b/apps/web/components/task/dockview-desktop-layout.tsx
index d3a297e2c0..9c05ae2667 100644
--- a/apps/web/components/task/dockview-desktop-layout.tsx
+++ b/apps/web/components/task/dockview-desktop-layout.tsx
@@ -588,7 +588,7 @@ function setupPortalCleanup(api: DockviewReadyEvent["api"]) {
}
// ---------------------------------------------------------------------------
-// useSessionSwitchCleanup — releases session-scoped portals + triggers layout switch
+// useSessionSwitchCleanup — backup layout switch for external session changes
// ---------------------------------------------------------------------------
function useSessionSwitchCleanup(effectiveSessionId: string | null) {
@@ -603,12 +603,10 @@ function useSessionSwitchCleanup(effectiveSessionId: string | null) {
const oldSessionId = prevSessionRef.current;
prevSessionRef.current = effectiveSessionId;
- // Release session-scoped portals from the old session so stale
- // terminals, editors, etc. don't leak into the new session.
- if (oldSessionId) {
- panelPortalManager.releaseBySession(oldSessionId);
- }
-
+ // Portal cleanup is handled synchronously inside switchSessionLayout
+ // (in the dockview store action) before any fromJSON call. This hook
+ // serves as a backup for external session changes (e.g. WS-driven)
+ // that don't go through the sidebar/dropdown switch helpers.
if (effectiveSessionId) {
performLayoutSwitch(oldSessionId, effectiveSessionId);
}
@@ -701,8 +699,20 @@ export const DockviewDesktopLayout = memo(function DockviewDesktopLayout({
};
}, []);
+ // Visual masking: hide the dockview container during slow-path layout
+ // switches (full fromJSON rebuild) to prevent the old layout from flashing.
+ const isRestoringLayout = useDockviewStore((s) => s.isRestoringLayout);
+
return (
-
+
void;
+ getDefaultLayout: () => LayoutState;
+};
+
+/**
+ * Remove ephemeral panels (file-editors, diffs, commit-details) from the
+ * live layout. These are session-specific panels that shouldn't carry over.
+ */
+function removeEphemeralPanels(api: DockviewApi): void {
+ const toRemove = api.panels.filter((p) => {
+ const comp = p.api.component;
+ return (
+ comp === "file-editor" ||
+ comp === "diff-viewer" ||
+ comp === "commit-detail" ||
+ comp === "pr-detail"
+ );
+ });
+ for (const p of toRemove) {
+ try {
+ p.api.close();
+ } catch {
+ /* panel may already be gone */
+ }
+ }
+}
+
+/**
+ * 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 tryFastSessionSwitch(params: SessionSwitchParams): LayoutGroupIds | null {
+ const { api, newSessionId, getDefaultLayout } = params;
+ const currentLayout = fromDockviewApi(api);
+ const saved = getSessionLayout(newSessionId);
+
+ let structuresMatch = false;
+ if (saved) {
+ // Compare live layout against saved layout by structural component set
+ structuresMatch = savedLayoutMatchesLive(currentLayout, saved as SerializedDockview);
+ } else {
+ // No saved layout — target is the default; compare LayoutState structures
+ structuresMatch = layoutStructuresMatch(currentLayout, getDefaultLayout());
+ }
+
+ if (!structuresMatch) return null;
+
+ // Fast path: keep the grid structure, just clean up ephemeral panels.
+ // Session-scoped portals (terminal, browser, etc.) will be re-acquired
+ // via usePortalSlot's sessionId dependency change.
+ removeEphemeralPanels(api);
+ return applyLayoutFixups(api);
+}
+
+/**
+ * Switch the dockview layout between sessions.
+ *
+ * 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 session layout and releasing
+ * session-scoped portals before calling this function.
+ */
+export function performSessionSwitch(params: SessionSwitchParams): LayoutGroupIds {
+ const { api, newSessionId, safeWidth, safeHeight, buildDefault } = params;
+
+ // Try fast path: skip fromJSON when layout structure hasn't changed
+ const fastResult = tryFastSessionSwitch(params);
+ if (fastResult) return fastResult;
+
+ // Slow path: full layout rebuild via fromJSON
+ const saved = getSessionLayout(newSessionId);
+ if (saved) {
+ try {
+ api.fromJSON(saved as SerializedDockview);
+ api.layout(safeWidth, safeHeight);
+ return applyLayoutFixups(api);
+ } catch {
+ /* fall through */
+ }
+ }
+ buildDefault(api);
+ api.layout(safeWidth, safeHeight);
+ return applyLayoutFixups(api);
+}
diff --git a/apps/web/lib/state/dockview-store.ts b/apps/web/lib/state/dockview-store.ts
index d6ad212be5..3812da251f 100644
--- a/apps/web/lib/state/dockview-store.ts
+++ b/apps/web/lib/state/dockview-store.ts
@@ -1,7 +1,6 @@
import { create } from "zustand";
import type { DockviewApi, AddPanelOptions, SerializedDockview } from "dockview-react";
import {
- getSessionLayout,
setSessionLayout,
getSessionMaximizeState,
setSessionMaximizeState,
@@ -22,6 +21,7 @@ import {
mergeCurrentPanelsIntoPreset,
} from "./layout-manager";
import type { BuiltInPreset, LayoutState, LayoutGroupIds } from "./layout-manager";
+import { performSessionSwitch } from "./dockview-session-switch";
import {
injectIntentPanels,
applyActivePanelOverrides,
@@ -30,6 +30,7 @@ import {
import { buildFileStateActions } from "./dockview-file-state";
import { buildPanelActions, buildExtraPanelActions } from "./dockview-panel-actions";
import { preserveChatScrollDuringLayout } from "./dockview-scroll-preserve";
+import { panelPortalManager } from "@/lib/layout/panel-portal-manager";
// Re-export types and constants used by other modules
export type { BuiltInPreset } from "./layout-manager";
@@ -200,39 +201,6 @@ function captureLiveWidths(api: DockviewApi, set: StoreSet): Map
return useDockviewStore.getState().pinnedWidths;
}
-type SessionSwitchParams = {
- api: DockviewApi;
- oldSessionId: string | null;
- newSessionId: string;
- safeWidth: number;
- safeHeight: number;
- buildDefault: (api: DockviewApi) => void;
-};
-
-function performSessionSwitch(params: SessionSwitchParams): LayoutGroupIds {
- const { api, oldSessionId, newSessionId, safeWidth, safeHeight, buildDefault } = params;
- if (oldSessionId) {
- try {
- setSessionLayout(oldSessionId, api.toJSON());
- } catch {
- /* ignore */
- }
- }
- const saved = getSessionLayout(newSessionId);
- if (saved) {
- try {
- api.fromJSON(saved as SerializedDockview);
- api.layout(safeWidth, safeHeight);
- return applyLayoutFixups(api);
- } catch {
- /* fall through */
- }
- }
- buildDefault(api);
- api.layout(safeWidth, safeHeight);
- return applyLayoutFixups(api);
-}
-
function applyLayoutAndSet(
api: DockviewApi,
state: LayoutState,
@@ -458,6 +426,11 @@ function buildSessionSwitchAction(set: StoreSet, get: StoreGet) {
} catch {
/* ignore */
}
+ // Release session-scoped portals (terminals, editors, etc.) synchronously
+ // BEFORE rebuilding the layout so stale content doesn't flash in the new layout.
+ if (oldSessionId) {
+ panelPortalManager.releaseBySession(oldSessionId);
+ }
set({ isRestoringLayout: true, currentLayoutSessionId: newSessionId });
try {
if (restoreMaximizeFromStorage(api, newSessionId, set)) return;
@@ -468,6 +441,7 @@ function buildSessionSwitchAction(set: StoreSet, get: StoreGet) {
safeWidth: api.width,
safeHeight: api.height,
buildDefault: (a) => get().buildDefaultLayout(a),
+ getDefaultLayout: () => get().userDefaultLayout ?? getPresetLayout("default"),
});
set(ids);
set({ isRestoringLayout: false });
diff --git a/apps/web/lib/state/layout-manager/comparator.ts b/apps/web/lib/state/layout-manager/comparator.ts
new file mode 100644
index 0000000000..f26a80c500
--- /dev/null
+++ b/apps/web/lib/state/layout-manager/comparator.ts
@@ -0,0 +1,104 @@
+import type { SerializedDockview } from "dockview-react";
+import type { LayoutState, LayoutGroup } from "./types";
+import { filterEphemeral } from "./serializer";
+import { STRUCTURAL_COMPONENTS } from "./constants";
+
+/**
+ * Extract a structural fingerprint from a group: sorted component names.
+ * Ignores panel IDs, params, sizes — only the *kind* of panels matters.
+ */
+function groupFingerprint(group: LayoutGroup): string {
+ return group.panels
+ .map((p) => p.component)
+ .sort()
+ .join(",");
+}
+
+/**
+ * Check whether two LayoutStates have the same structural skeleton.
+ *
+ * Both layouts are filtered through `filterEphemeral` first so that
+ * transient panels (file-editors, diffs, commit-details) don't cause
+ * false mismatches.
+ *
+ * Two layouts match when:
+ * - Same number of columns, same column IDs in the same order
+ * - Each column has the same number of groups
+ * - Each group has the same set of panel component types
+ *
+ * Sizes, proportions, active panels, and panel params are ignored.
+ */
+export function layoutStructuresMatch(a: LayoutState, b: LayoutState): boolean {
+ const fa = filterEphemeral(a);
+ const fb = filterEphemeral(b);
+
+ if (fa.columns.length !== fb.columns.length) return false;
+
+ for (let i = 0; i < fa.columns.length; i++) {
+ const colA = fa.columns[i];
+ const colB = fb.columns[i];
+ if (colA.id !== colB.id) return false;
+ if (colA.groups.length !== colB.groups.length) return false;
+ for (let j = 0; j < colA.groups.length; j++) {
+ if (groupFingerprint(colA.groups[j]) !== groupFingerprint(colB.groups[j])) {
+ return false;
+ }
+ }
+ }
+
+ return true;
+}
+
+/**
+ * Build a component-count fingerprint from a SerializedDockview.
+ * Returns a sorted "component:count" string for structural comparison.
+ * Counts preserve multiplicity (e.g. two terminals ≠ one terminal).
+ */
+function componentCountsFromSerialized(serialized: SerializedDockview): string {
+ const counts = new Map();
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ const panels = (serialized as any).panels as
+ | Record
+ | undefined;
+ if (!panels) return "";
+ for (const p of Object.values(panels)) {
+ if (p.contentComponent && STRUCTURAL_COMPONENTS.has(p.contentComponent)) {
+ counts.set(p.contentComponent, (counts.get(p.contentComponent) ?? 0) + 1);
+ }
+ }
+ return [...counts.entries()]
+ .sort(([a], [b]) => a.localeCompare(b))
+ .map(([k, v]) => `${k}:${v}`)
+ .join(",");
+}
+
+/** Build a component-count fingerprint from a LayoutState (filtered). */
+function componentCountsFromLayout(state: LayoutState): string {
+ const counts = new Map();
+ const filtered = filterEphemeral(state);
+ for (const col of filtered.columns) {
+ for (const group of col.groups) {
+ for (const panel of group.panels) {
+ if (STRUCTURAL_COMPONENTS.has(panel.component)) {
+ counts.set(panel.component, (counts.get(panel.component) ?? 0) + 1);
+ }
+ }
+ }
+ }
+ return [...counts.entries()]
+ .sort(([a], [b]) => a.localeCompare(b))
+ .map(([k, v]) => `${k}:${v}`)
+ .join(",");
+}
+
+/**
+ * Quick check: do a live LayoutState and a saved SerializedDockview have
+ * the same structural panels (including multiplicity)?
+ *
+ * This is a weaker check than `layoutStructuresMatch` (doesn't verify
+ * column arrangement) but works without deserializing the grid tree.
+ * Counts are compared so two terminals ≠ one terminal.
+ */
+export function savedLayoutMatchesLive(live: LayoutState, saved: SerializedDockview): boolean {
+ return componentCountsFromLayout(live) === componentCountsFromSerialized(saved);
+}
diff --git a/apps/web/lib/state/layout-manager/index.ts b/apps/web/lib/state/layout-manager/index.ts
index 4ce29ccfb8..bd2d02b287 100644
--- a/apps/web/lib/state/layout-manager/index.ts
+++ b/apps/web/lib/state/layout-manager/index.ts
@@ -45,6 +45,9 @@ export type { LayoutGroupIds } from "./applier";
// Merger
export { mergeCurrentPanelsIntoPreset } from "./merger";
+// Comparator
+export { layoutStructuresMatch, savedLayoutMatchesLive } from "./comparator";
+
// Intent
export {
INTENT_PLAN,