From e2fae8f8cf5b725852f191252465d6e2d08a3537 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Flor=C3=AAncio?= Date: Sun, 8 Mar 2026 21:50:32 +0000 Subject: [PATCH] feat(ui): seamless session switching without dockview layout flash (#395) --- .../task/dockview-desktop-layout.tsx | 26 +++-- apps/web/lib/layout/panel-portal-host.tsx | 5 +- apps/web/lib/state/dockview-session-switch.ts | 104 ++++++++++++++++++ apps/web/lib/state/dockview-store.ts | 42 ++----- .../lib/state/layout-manager/comparator.ts | 104 ++++++++++++++++++ apps/web/lib/state/layout-manager/index.ts | 3 + 6 files changed, 241 insertions(+), 43 deletions(-) create mode 100644 apps/web/lib/state/dockview-session-switch.ts create mode 100644 apps/web/lib/state/layout-manager/comparator.ts 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,