fix(webview): persist view state by stable id

Author: easonliang28

packages/types/src/vscode-extension-host.ts

@@ -621,6 +621,7 @@ export interface WebviewMessage {
 		| "openRuleFile"
 		| "openRulesDirectory"
 	text?: string
+	viewStateId?: string
 	taskId?: string
 	editedMessageContent?: string
 	tab?: "settings" | "history" | "mcp" | "modes" | "chat" | "marketplace" | "cloud"

src/core/webview/ClineProvider.ts

@@ -219,6 +219,12 @@ export class ClineProvider
 	 */
 	public readonly viewId: string
 
+	/**
+	 * Stable identifier for persisted per-view state keys.
+	 * Defaults to viewId until the webview reports its VS Code-persisted id.
+	 */
+	private viewStateId: string
+
 	/**
 	 * Local state buffer for this specific view instance.
 	 * Used to isolate mode, apiConfiguration, and other fields from the shared ContextProxy singleton
@@ -243,6 +249,7 @@ export class ClineProvider
 		// Initialize viewId based on renderContext and monotonically increasing instance identifier for uniqueness.
 		// activeInstances is used for visibility/iteration checks, so we keep tracking instances separately.
 		this.viewId = `${renderContext}-${ClineProvider.nextViewId++}`
+		this.viewStateId = this.viewId
 		ClineProvider.activeInstances.add(this)
 		this.currentWorkspacePath = getWorkspacePath()
 		this.pendingEditOperations = new PendingEditOperationStore(
@@ -423,10 +430,22 @@ export class ClineProvider
 
 	/**
 	 * Derive a view-specific ContextProxy key for persisting view-local state.
-	 * Uses the current viewId so each parallel tab restores its own values on recreation.
+	 * Uses a stable per-view id so each restored tab reads and writes its own values
+	 * independent of provider construction order.
 	 */
 	private viewStateKeyFor(key: "mode" | "currentApiConfigName" | "apiConfiguration"): string {
-		return `__view_state_${this.viewId}_${key}`
+		return `__view_state_${this.viewStateId}_${key}`
+	}
+
+	public async setViewStateId(viewStateId: string | undefined): Promise<void> {
+		const normalizedViewStateId = viewStateId?.trim()
+
+		if (!normalizedViewStateId || normalizedViewStateId === this.viewStateId) {
+			return
+		}
+
+		this.viewStateId = normalizedViewStateId.replace(/[^A-Za-z0-9_-]/g, "_")
+		await this.loadViewState()
 	}
 
 	/**
@@ -440,15 +459,18 @@ export class ClineProvider
 			const providerSettings = this.contextProxy.getProviderSettings()
 
 			// Try view-specific keys first, then fall back to shared keys for backward compatibility.
-			const getViewSpecificValue = (sharedKey: "mode" | "currentApiConfigName") => {
+			const getViewSpecificValue = (sharedKey: "mode" | "currentApiConfigName" | "apiConfiguration") => {
 				const viewKey = this.viewStateKeyFor(sharedKey)
-				return (this.contextProxy.getValue(viewKey as any) as any) ?? stateValues[sharedKey]
+				return (
+					(this.contextProxy.getValue(viewKey as any) as any) ??
+					(sharedKey === "apiConfiguration" ? providerSettings : stateValues[sharedKey])
+				)
 			}
 
 			this.viewLocalState = {
 				mode: getViewSpecificValue("mode"),
 				currentApiConfigName: getViewSpecificValue("currentApiConfigName"),
-				apiConfiguration: providerSettings,
+				apiConfiguration: getViewSpecificValue("apiConfiguration") ?? providerSettings,
 				customModePrompts: stateValues.customModePrompts,
 				modeApiConfigs: stateValues.modeApiConfigs,
 			}

src/core/webview/__tests__/ClineProvider.parallelMode.spec.ts

@@ -741,15 +741,16 @@ describe("ClineProvider - Parallel Mode Support", () => {
 			const provider = new ClineProvider(mockContext, mockOutputChannel, "sidebar", new ContextProxy(mockContext))
 
 			const contextProxySpy = vi.spyOn(provider.contextProxy, "setValue")
+			await (provider as any).setViewStateId("stable-sidebar-view")
 
 			await (provider as any).saveViewState("mode", "architect")
 
 			// Verify viewLocalState was updated
 			expect((provider as any).viewLocalState.mode).toBe("architect")
 
-			// saveViewState now uses view-specific key for mode/currentApiConfigName/apiConfiguration
-			const expectedViewKey = `__view_state_sidebar-${provider.viewId.split("-")[1]}_mode`
-			expect(contextProxySpy).toHaveBeenCalledWith(expectedViewKey, "architect")
+			// saveViewState uses the stable per-view id, not the construction-order viewId suffix.
+			expect(contextProxySpy).toHaveBeenCalledWith("__view_state_stable-sidebar-view_mode", "architect")
+			expect(contextProxySpy).not.toHaveBeenCalledWith(`__view_state_${provider.viewId}_mode`, expect.anything())
 
 			await provider.dispose()
 		})
@@ -859,6 +860,37 @@ describe("ClineProvider - Parallel Mode Support", () => {
 			await provider.dispose()
 		})
 
+		it("should restore mode, current API config name, and API configuration from stable per-view state", async () => {
+			const provider = new ClineProvider(mockContext, mockOutputChannel, "editor", new ContextProxy(mockContext))
+			const stableViewId = "stable-editor-tab-a"
+			const persistedApiConfiguration = {
+				apiProvider: "openrouter" as const,
+				openRouterModelId: "openrouter/anthropic/claude-sonnet-4",
+			}
+
+			await provider.contextProxy.setValue(`__view_state_${stableViewId}_mode` as any, "architect")
+			await provider.contextProxy.setValue(
+				`__view_state_${stableViewId}_currentApiConfigName` as any,
+				"profile-a",
+			)
+			await provider.contextProxy.setValue(
+				`__view_state_${stableViewId}_apiConfiguration` as any,
+				persistedApiConfiguration,
+			)
+			await provider.contextProxy.setValue("mode" as any, "debugger")
+			await provider.contextProxy.setValue("currentApiConfigName" as any, "profile-b")
+			await provider.contextProxy.setValue("apiConfiguration" as any, { apiProvider: "anthropic" })
+
+			await (provider as any).setViewStateId(stableViewId)
+			const state = await provider.getState()
+
+			expect(state.mode).toBe("architect")
+			expect(state.currentApiConfigName).toBe("profile-a")
+			expect(state.apiConfiguration).toMatchObject(persistedApiConfiguration)
+
+			await provider.dispose()
+		})
+
 		it("should log and keep existing viewLocalState when loadViewState fails", async () => {
 			const provider = new ClineProvider(mockContext, mockOutputChannel, "sidebar", new ContextProxy(mockContext))
 			const logSpy = vi.spyOn(provider as any, "log")

src/core/webview/webviewMessageHandler.ts

@@ -558,6 +558,8 @@ export const webviewMessageHandler = async (
 
 	switch (message.type) {
 		case "webviewDidLaunch":
+			await provider.setViewStateId(message.viewStateId)
+
 			// Load custom modes first
 			const customModes = await provider.customModesManager.getCustomModes()
 			await updateGlobalState("customModes", customModes)

webview-ui/src/App.tsx

@@ -191,7 +191,7 @@ const App = () => {
 	}, [telemetrySetting, telemetryKey, machineId, didHydrateState])
 
 	// Tell the extension that we are ready to receive messages.
-	useEffect(() => vscode.postMessage({ type: "webviewDidLaunch" }), [])
+	useEffect(() => vscode.postMessage({ type: "webviewDidLaunch", viewStateId: vscode.getViewStateId() }), [])
 
 	// Initialize source map support for better error reporting
 	useEffect(() => {

webview-ui/src/__tests__/App.spec.tsx

@@ -8,6 +8,7 @@ import AppWithProviders from "../App"
 vi.mock("@src/utils/vscode", () => ({
 	vscode: {
 		postMessage: vi.fn(),
+		getViewStateId: vi.fn(() => "test-view-state-id"),
 	},
 }))
 

webview-ui/src/context/ExtensionStateContext.tsx

@@ -489,7 +489,7 @@ export const ExtensionStateContextProvider: React.FC<{ children: React.ReactNode
 	}, [handleMessage])
 
 	useEffect(() => {
-		vscode.postMessage({ type: "webviewDidLaunch" })
+		vscode.postMessage({ type: "webviewDidLaunch", viewStateId: vscode.getViewStateId() })
 	}, [])
 
 	// Apply the configurable chat font size as a CSS variable. When unset, the

webview-ui/src/utils/vscode.ts

@@ -22,6 +22,31 @@ class VSCodeAPIWrapper {
 		}
 	}
 
+	private createViewStateId(): string {
+		if (typeof crypto !== "undefined" && "randomUUID" in crypto) {
+			return crypto.randomUUID()
+		}
+
+		return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`
+	}
+
+	public getViewStateId(): string {
+		const currentState = this.getState()
+		const stateObject =
+			currentState && typeof currentState === "object" && !Array.isArray(currentState)
+				? (currentState as Record<string, unknown>)
+				: {}
+		const existingViewStateId = stateObject.viewStateId
+
+		if (typeof existingViewStateId === "string" && existingViewStateId.length > 0) {
+			return existingViewStateId
+		}
+
+		const viewStateId = this.createViewStateId()
+		this.setState({ ...stateObject, viewStateId })
+		return viewStateId
+	}
+
 	/**
 	 * Post a message (i.e. send arbitrary data) to the owner of the webview.
 	 *
@@ -49,9 +74,11 @@ class VSCodeAPIWrapper {
 	public getState(): unknown | undefined {
 		if (this.vsCodeApi) {
 			return this.vsCodeApi.getState()
-		} else {
+		} else if (typeof localStorage?.getItem === "function") {
 			const state = localStorage.getItem("vscodeState")
 			return state ? JSON.parse(state) : undefined
+		} else {
+			return undefined
 		}
 	}
 
@@ -70,7 +97,9 @@ class VSCodeAPIWrapper {
 		if (this.vsCodeApi) {
 			return this.vsCodeApi.setState(newState)
 		} else {
-			localStorage.setItem("vscodeState", JSON.stringify(newState))
+			if (typeof localStorage?.setItem === "function") {
+				localStorage.setItem("vscodeState", JSON.stringify(newState))
+			}
 			return newState
 		}
 	}