feat(ui): seamless session switching without dockview layout flash (#395)

This commit is contained in:
Carlos Florêncio
2026-03-08 21:50:32 +00:00
committed by GitHub
parent ddcd101762
commit e2fae8f8cf
6 changed files with 241 additions and 43 deletions
@@ -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 (
<div className="flex-1 min-h-0">
<div
className="flex-1 min-h-0"
aria-busy={isRestoringLayout}
style={{
opacity: isRestoringLayout ? 0 : 1,
pointerEvents: isRestoringLayout ? "none" : undefined,
transition: isRestoringLayout ? "none" : "opacity 60ms ease-out",
}}
>
<PreviewController sessionId={effectiveSessionId} hasDevScript={hasDevScript} />
<DockviewReact
theme={themeKandev}
+4 -1
View File
@@ -92,8 +92,11 @@ export function usePortalSlot(
container.removeChild(entry.element);
}
};
// sessionId in deps: when session changes, session-scoped panels re-acquire
// fresh portals (old ones were released by releaseBySession in the store action).
// Global panels pass sessionId=undefined so this is a no-op for them.
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [panelId]);
}, [panelId, sessionId]);
return containerRef;
}
@@ -0,0 +1,104 @@
/**
* Session switch logic for dockview layout management.
*
* Handles both a "fast path" (skip fromJSON when layout structure matches)
* and a "slow path" (full layout rebuild via fromJSON).
*/
import type { DockviewApi, SerializedDockview } from "dockview-react";
import { getSessionLayout } from "@/lib/local-storage";
import { applyLayoutFixups } from "./dockview-layout-builders";
import { fromDockviewApi, savedLayoutMatchesLive, layoutStructuresMatch } from "./layout-manager";
import type { LayoutState, LayoutGroupIds } from "./layout-manager";
export type SessionSwitchParams = {
api: DockviewApi;
oldSessionId: string | null;
newSessionId: string;
safeWidth: number;
safeHeight: number;
buildDefault: (api: DockviewApi) => 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);
}
+8 -34
View File
@@ -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<string, number>
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 });
@@ -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<string, number>();
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const panels = (serialized as any).panels as
| Record<string, { contentComponent?: string }>
| 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<string, number>();
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);
}
@@ -45,6 +45,9 @@ export type { LayoutGroupIds } from "./applier";
// Merger
export { mergeCurrentPanelsIntoPreset } from "./merger";
// Comparator
export { layoutStructuresMatch, savedLayoutMatchesLive } from "./comparator";
// Intent
export {
INTENT_PLAN,