From bbdb6557d9d76bf62518f945b171bd42fed078c0 Mon Sep 17 00:00:00 2001
From: wsp <mr.wanger2018@outlook.com>
Date: Sat, 10 Oct 2026 11:34:57 +0800
Subject: [PATCH] feat(ui): Add optional session panel overlay

Keep side-by-side layout as the default and apply layout preferences
immediately, with independently persisted split and overlay widths.

Preserve mounted pane content and transcript dimensions in overlay mode.
Resize and reposition the chat input to avoid the visible auxiliary pane,
and defer input width measurement during divider dragging.

Add localized appearance settings and focused layout regression tests.
---
 design-system/packages/ui/README.md           | 25 +++++
 .../components/SplitView/SplitView.meta.ts    |  3 +-
 .../components/SplitView/SplitView.module.css | 55 +++++++++++
 .../ui/src/components/SplitView/SplitView.tsx | 24 +++--
 .../ui/src/components/SplitView/index.ts      |  2 +-
 design-system/packages/ui/src/index.ts        |  2 +-
 .../packages/ui/tests/split-view.test.mjs     | 26 ++++++
 src/web-ui/src/app/scenes/SceneViewport.scss  |  1 +
 .../session/ChatPane.composer-layout.test.tsx | 49 ++++++++++
 .../src/app/scenes/session/ChatPane.tsx       | 22 +++--
 .../session/SessionScene.overlay.test.tsx     | 92 +++++++++++++++++++
 .../src/app/scenes/session/SessionScene.tsx   |  8 +-
 .../session/sessionPaneLayoutStore.test.ts    | 37 +++++++-
 .../scenes/session/sessionPaneLayoutStore.ts  | 30 +++++-
 .../AppearanceSettingsPage.test.tsx           |  1 +
 .../application/AppearanceSettingsPage.tsx    |  2 +
 .../SessionPanelSettingsSection.tsx           | 25 +++++
 .../app/scenes/settings/settingsRegistry.ts   |  5 +
 .../src/flow_chat/components/ChatInput.tsx    |  5 +
 .../design-system/SplitView.appearance.ts     |  1 +
 .../locales/en-US/settings/appearance.json    |  6 ++
 .../locales/zh-CN/settings/appearance.json    |  6 ++
 .../locales/zh-TW/settings/appearance.json    |  6 ++
 src/web-ui/src/shared/ui/SplitView.test.tsx   | 55 ++++++++++-
 24 files changed, 459 insertions(+), 29 deletions(-)
 create mode 100644 design-system/packages/ui/tests/split-view.test.mjs
 create mode 100644 src/web-ui/src/app/scenes/session/ChatPane.composer-layout.test.tsx
 create mode 100644 src/web-ui/src/app/scenes/session/SessionScene.overlay.test.tsx
 create mode 100644 src/web-ui/src/app/scenes/settings/pages/application/SessionPanelSettingsSection.tsx

diff --git a/design-system/packages/ui/README.md b/design-system/packages/ui/README.md
index c7eaa22c86..b4f7593d3c 100644
--- a/design-system/packages/ui/README.md
+++ b/design-system/packages/ui/README.md
@@ -18,6 +18,31 @@ export function Example() {
 
 The package owns component anatomy, behavior, accessibility, and stable variants. It does not own theme selection persistence, product state, routes, locale resources, or platform APIs.
 
+## Pane layouts
+
+`SplitView` retains its primary and secondary content hosts across placement,
+visibility and `layout="split" | "overlay"` changes. Split layout is the default:
+`rightSize` controls the physical right slot. In overlay layout, `rightSize`
+controls the secondary pane on `secondarySide`, while the primary pane fills the
+container. `minLeftSize` reserves uncovered space in overlay layout; use zero
+when the secondary pane may cover the full width. The resize handle follows the
+secondary pane's inner edge and keeps keyboard and pointer directions aligned.
+
+This is a persistent, non-modal pane layout inside the component's isolated
+stacking context. It does not add a backdrop, focus trap or outside-click
+dismissal. Floating menus and dialogs within either pane continue to use the
+document overlay coordinator. Owners control visibility with `mode` and persist
+split and overlay sizes independently when those preferences differ.
+
+Place `SplitViewPrimaryDock` inside the primary content's positioned container
+for an absolute input or toolbar that must avoid the secondary overlay. Its
+width and placement follow the displayed pane size, including pointer drags and
+container clamping, without resizing the primary pane. The dock passes pointer
+events through; interactive children must enable pointer events. Keep
+`minLeftSize` large enough for the dock's controls; on narrow containers this
+reservation shrinks to half the available width. Dock contents stay mounted
+when visibility or placement changes.
+
 Floating dialog/sheet overlays, menu popovers, select/combobox popups and tooltips declare
 `data-openbitfun-native-webview-occlusion` on their rendered floating surface.
 Native hosts use its visible bounds to temporarily hide overlapping child views;
diff --git a/design-system/packages/ui/src/components/SplitView/SplitView.meta.ts b/design-system/packages/ui/src/components/SplitView/SplitView.meta.ts
index efdfb88699..795046fa2d 100644
--- a/design-system/packages/ui/src/components/SplitView/SplitView.meta.ts
+++ b/design-system/packages/ui/src/components/SplitView/SplitView.meta.ts
@@ -9,6 +9,7 @@ export const splitViewMeta = {
     { name: 'primary', type: 'ReactNode' },
     { name: 'secondary', type: 'ReactNode' },
     { name: 'mode', type: 'split | primary | secondary', defaultValue: 'split' },
+    { name: 'layout', type: 'split | overlay', defaultValue: 'split' },
     { name: 'secondarySide', type: 'left | right', defaultValue: 'right' },
     { name: 'rightSize', type: 'number' },
     { name: 'onRightSizeChange', type: '(size: number) => void' },
@@ -16,5 +17,5 @@ export const splitViewMeta = {
     { name: 'dividerLabel', type: 'string' },
   ],
   states: ['split', 'primary', 'secondary'],
-  tokens: ['color.border.subtle', 'color.surface.raised', 'color.accent.default', 'color.focus.ring', 'space.1', 'space.2', 'space.3', 'radius.lg'],
+  tokens: ['color.border.subtle', 'color.surface.raised', 'color.accent.default', 'color.focus.ring', 'space.1', 'space.2', 'space.3', 'radius.lg', 'shadow.overlay'],
 } as const satisfies ComponentMeta;
diff --git a/design-system/packages/ui/src/components/SplitView/SplitView.module.css b/design-system/packages/ui/src/components/SplitView/SplitView.module.css
index ed54d698af..df043ec55b 100644
--- a/design-system/packages/ui/src/components/SplitView/SplitView.module.css
+++ b/design-system/packages/ui/src/components/SplitView/SplitView.module.css
@@ -1,5 +1,6 @@
 @layer openbitfun.components {
   .root {
+    position: relative;
     display: grid;
     grid-template-columns: minmax(0, 1fr) var(--openbitfun-border-width-default) minmax(0, var(--_split-view-right-size));
     grid-template-areas: "primary divider secondary";
@@ -17,6 +18,60 @@
   .root[data-mode="primary"] { grid-template-columns: minmax(0, 1fr); grid-template-areas: "primary"; }
   .root[data-mode="secondary"] { grid-template-columns: minmax(0, 1fr); grid-template-areas: "secondary"; }
 
+  /* Overlay is local pane geometry, retaining the same mounted content hosts. */
+  .root[data-layout="overlay"]:not([data-mode="secondary"]) {
+    grid-template-columns: minmax(0, 1fr);
+    grid-template-areas: "primary";
+  }
+
+  .root[data-layout="overlay"] .primary { isolation: isolate; }
+
+  .primaryDock {
+    position: absolute;
+    inset-block: 0;
+    inset-inline-start: 0;
+    inline-size: 100%;
+    min-inline-size: 0;
+    pointer-events: none;
+  }
+
+  .root[data-layout="overlay"][data-mode="split"] > .primary .primaryDock {
+    inline-size: max(0px, calc(100% - var(--_split-view-right-size) - var(--openbitfun-border-width-default)));
+  }
+
+  .root[data-layout="overlay"][data-mode="split"][data-secondary-side="left"] > .primary .primaryDock {
+    inset-inline-start: calc(var(--_split-view-right-size) + var(--openbitfun-border-width-default));
+  }
+
+  .root[data-layout="overlay"][data-mode="split"] .secondary {
+    grid-area: auto;
+    position: absolute;
+    inset-block: 0;
+    inset-inline-end: 0;
+    inline-size: var(--_split-view-right-size);
+    isolation: isolate;
+    background: var(--openbitfun-color-surface-raised);
+    box-shadow: var(--openbitfun-shadow-overlay);
+  }
+
+  .root[data-layout="overlay"][data-mode="split"] .divider {
+    grid-area: auto;
+    position: absolute;
+    inset-block: 0;
+    inset-inline-end: var(--_split-view-right-size);
+    inline-size: var(--openbitfun-border-width-default);
+  }
+
+  .root[data-layout="overlay"][data-secondary-side="left"] .secondary {
+    inset-inline-start: 0;
+    inset-inline-end: auto;
+  }
+
+  .root[data-layout="overlay"][data-secondary-side="left"] .divider {
+    inset-inline-start: var(--_split-view-right-size);
+    inset-inline-end: auto;
+  }
+
   .pane {
     display: flex;
     flex-direction: column;
diff --git a/design-system/packages/ui/src/components/SplitView/SplitView.tsx b/design-system/packages/ui/src/components/SplitView/SplitView.tsx
index 92b1f23c91..d1c4536b6f 100644
--- a/design-system/packages/ui/src/components/SplitView/SplitView.tsx
+++ b/design-system/packages/ui/src/components/SplitView/SplitView.tsx
@@ -7,12 +7,19 @@ import styles from './SplitView.module.css';
 
 export type SplitViewMode = 'split' | 'primary' | 'secondary';
 
+/** Absolutely positioned primary content that stays clear of the secondary overlay. */
+export function SplitViewPrimaryDock({ className, children, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return <div {...props} className={classNames(styles.primaryDock, className)}
+    data-openbitfun-component="split-view" data-openbitfun-part="primaryDock">{children}</div>;
+}
+
 export interface SplitViewProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
   primary: ReactNode;
   secondary: ReactNode;
   mode?: SplitViewMode;
+  layout?: 'split' | 'overlay';
   secondarySide?: 'left' | 'right';
-  /** Physical right slot width. Swapping content never moves the divider. */
+  /** Physical right slot width in split layout; secondary width in overlay layout. */
   rightSize: number;
   minLeftSize?: number;
   minRightSize?: number;
@@ -34,7 +41,7 @@ function sizeBounds(width: number, dividerWidth: number, minLeft: number, minRig
 }
 
 export function SplitView({
-  primary, secondary, mode = 'split', secondarySide = 'right', rightSize,
+  primary, secondary, mode = 'split', layout = 'split', secondarySide = 'right', rightSize,
   minLeftSize = 0, minRightSize = 0, maxRightSize = Number.MAX_SAFE_INTEGER,
   defaultRightSize = rightSize, onRightSizeChange, onResizeStateChange,
   dividerLabel, dividerActions, primaryPaneProps, secondaryPaneProps,
@@ -59,6 +66,7 @@ export function SplitView({
   callbacks.current = { onRightSizeChange, onResizeStateChange };
   const bounds = width === null ? { min: minRightSize, max: maxRightSize }
     : sizeBounds(width, dividerWidth, minLeftSize, minRightSize, maxRightSize);
+  const resizeDirection = layout === 'overlay' && secondarySide === 'left' ? -1 : 1;
   const resolvedSize = Math.min(bounds.max, Math.max(bounds.min, rightSize));
   const resolvedSizeRef = useRef(resolvedSize);
   resolvedSizeRef.current = resolvedSize;
@@ -78,7 +86,7 @@ export function SplitView({
     observer?.observe(root);
     window.addEventListener('resize', measure);
     return () => { observer?.disconnect(); window.removeEventListener('resize', measure); };
-  }, [mode]);
+  }, [mode, layout]);
 
   const finishResize = useCallback((commit: boolean) => {
     const drag = dragRef.current;
@@ -95,7 +103,7 @@ export function SplitView({
     callbacks.current.onResizeStateChange?.(false);
   }, []);
 
-  useLayoutEffect(() => { finishResize(false); }, [mode, secondarySide, finishResize]);
+  useLayoutEffect(() => { finishResize(false); }, [mode, layout, secondarySide, finishResize]);
   useEffect(() => () => { finishResize(false); }, [finishResize]);
 
   useLayoutEffect(() => {
@@ -111,7 +119,7 @@ export function SplitView({
     const measuredWidth = rootRef.current?.getBoundingClientRect().width ?? 0;
     const currentBounds = measuredWidth > 0
       ? sizeBounds(measuredWidth, dividerWidth, minLeftSize, minRightSize, maxRightSize) : bounds;
-    const delta = drag.x - event.clientX;
+    const delta = (drag.x - event.clientX) * resizeDirection;
     drag.latest = Math.min(currentBounds.max, Math.max(currentBounds.min, drag.size + delta));
     if (frameRef.current !== null) return;
     frameRef.current = requestAnimationFrame(() => {
@@ -127,7 +135,7 @@ export function SplitView({
       className={classNames(styles.root, className)}
       style={{ ...style, '--_split-view-right-size': `${resolvedSize}px` } as CSSProperties}
       data-openbitfun-component="split-view" data-openbitfun-part="root"
-      data-mode={mode} data-secondary-side={secondarySide} data-resizing={resizing || undefined}
+      data-mode={mode} data-layout={layout} data-secondary-side={secondarySide} data-resizing={resizing || undefined}
       onKeyDown={event => {
         onKeyDown?.(event);
         if (event.defaultPrevented || event.key !== 'F6' || event.altKey || event.ctrlKey || event.metaKey) return;
@@ -149,7 +157,7 @@ export function SplitView({
       <div ref={dividerRef} className={styles.divider} data-openbitfun-component="split-view" data-openbitfun-part="divider" hidden={mode !== 'split'}>
         <div className={styles.resizeHandle} role="separator" tabIndex={mode === 'split' ? 0 : -1}
           data-openbitfun-component="split-view" data-openbitfun-part="resizeHandle"
-          aria-label={dividerLabel} aria-orientation="vertical" aria-controls={secondarySide === 'right' ? secondaryId : primaryId}
+          aria-label={dividerLabel} aria-orientation="vertical" aria-controls={layout === 'overlay' || secondarySide === 'right' ? secondaryId : primaryId}
           aria-valuemin={Math.round(bounds.min)} aria-valuemax={Math.round(bounds.max)} aria-valuenow={Math.round(resolvedSize)}
           onPointerDown={event => {
             if (event.button !== 0 || dragRef.current) return;
@@ -178,7 +186,7 @@ export function SplitView({
           onKeyDown={event => {
             let next: number;
             if (event.key === 'ArrowLeft' || event.key === 'ArrowRight') {
-              next = resolvedSize + (event.key === 'ArrowRight' ? -1 : 1) * (event.shiftKey ? 50 : 10);
+              next = resolvedSize + (event.key === 'ArrowRight' ? -1 : 1) * resizeDirection * (event.shiftKey ? 50 : 10);
             } else if (event.key === 'Escape' && dragRef.current) {
               event.preventDefault();
               event.stopPropagation();
diff --git a/design-system/packages/ui/src/components/SplitView/index.ts b/design-system/packages/ui/src/components/SplitView/index.ts
index e3f53d44b4..e8002cf950 100644
--- a/design-system/packages/ui/src/components/SplitView/index.ts
+++ b/design-system/packages/ui/src/components/SplitView/index.ts
@@ -1,2 +1,2 @@
-export { SplitView } from './SplitView';
+export { SplitView, SplitViewPrimaryDock } from './SplitView';
 export type { SplitViewProps, SplitViewMode } from './SplitView';
diff --git a/design-system/packages/ui/src/index.ts b/design-system/packages/ui/src/index.ts
index 19078bcdef..842ff7c1c1 100644
--- a/design-system/packages/ui/src/index.ts
+++ b/design-system/packages/ui/src/index.ts
@@ -304,5 +304,5 @@ export {
 } from "./primitives/ThemeRoot";
 
 export { LayersPlusIcon } from "./components/Icon";
-export { SplitView } from './components/SplitView';
+export { SplitView, SplitViewPrimaryDock } from './components/SplitView';
 export type { SplitViewProps, SplitViewMode } from './components/SplitView';
diff --git a/design-system/packages/ui/tests/split-view.test.mjs b/design-system/packages/ui/tests/split-view.test.mjs
new file mode 100644
index 0000000000..add6e6e05e
--- /dev/null
+++ b/design-system/packages/ui/tests/split-view.test.mjs
@@ -0,0 +1,26 @@
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import test from 'node:test';
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { SplitView, SplitViewPrimaryDock } from '../dist/index.js';
+
+test('SplitView publishes a stable primary dock without changing the transcript host', () => {
+  const markup = renderToStaticMarkup(createElement(SplitView, {
+    layout: 'overlay', rightSize: 500, onRightSizeChange() {}, dividerLabel: 'Resize',
+    primary: createElement('div', null,
+      createElement('section', { 'data-transcript': true }, 'History'),
+      createElement(SplitViewPrimaryDock, null, createElement('textarea', { defaultValue: 'Draft' }))),
+    secondary: createElement('iframe', { title: 'Browser' }),
+  }));
+  assert.match(markup, /data-openbitfun-part="primaryDock"><textarea>Draft<\/textarea>/);
+  assert.match(markup, /<section data-transcript="true">History<\/section>/);
+});
+
+test('the dock tracks displayed width only in overlay layout and leaves primary geometry full width', async () => {
+  const styles = await readFile(new URL('../src/components/SplitView/SplitView.module.css', import.meta.url), 'utf8');
+  assert.match(styles, /\.root\[data-layout="overlay"\]:not\(\[data-mode="secondary"\]\)\s*\{[^}]*grid-template-columns: minmax\(0, 1fr\)/);
+  assert.match(styles, /\.primaryDock\s*\{[^}]*position: absolute;[^}]*inline-size: 100%;[^}]*pointer-events: none;/);
+  assert.match(styles, /\.root\[data-layout="overlay"\]\[data-mode="split"\] > \.primary \.primaryDock\s*\{[^}]*inline-size: max\(0px, calc\(100% - var\(--_split-view-right-size\) - var\(--openbitfun-border-width-default\)\)\)/);
+  assert.match(styles, /\[data-secondary-side="left"\] > \.primary \.primaryDock\s*\{[^}]*inset-inline-start: calc\(var\(--_split-view-right-size\) \+ var\(--openbitfun-border-width-default\)\)/);
+});
diff --git a/src/web-ui/src/app/scenes/SceneViewport.scss b/src/web-ui/src/app/scenes/SceneViewport.scss
index 82ec7b7ed0..fd2daee9c1 100644
--- a/src/web-ui/src/app/scenes/SceneViewport.scss
+++ b/src/web-ui/src/app/scenes/SceneViewport.scss
@@ -18,6 +18,7 @@
   .openbitfun-workspace-body__scene-surface > &:has(
     > .openbitfun-scene-viewport__clip
     > .openbitfun-scene-viewport__scene--active
+    .openbitfun-session-scene:not(.openbitfun-session-scene--overlay)
     .openbitfun-session-scene__aux-pane:not(.openbitfun-session-scene__aux-pane--collapsed)
   ) {
     inline-size: calc(100% + var(--openbitfun-space-4));
diff --git a/src/web-ui/src/app/scenes/session/ChatPane.composer-layout.test.tsx b/src/web-ui/src/app/scenes/session/ChatPane.composer-layout.test.tsx
new file mode 100644
index 0000000000..d2e80757b7
--- /dev/null
+++ b/src/web-ui/src/app/scenes/session/ChatPane.composer-layout.test.tsx
@@ -0,0 +1,49 @@
+// @vitest-environment jsdom
+import React, { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { expect, it, vi } from 'vitest';
+import ChatPane from './ChatPane';
+
+vi.mock('@/flow_chat/components/modern/ModernFlowChatContainer', () => ({
+  ModernFlowChatContainer: () => <div data-testid="transcript" />,
+}));
+vi.mock('@/flow_chat/components/ChatInput', () => ({
+  ChatInput: ({ layoutResizeSuspended }: { layoutResizeSuspended: boolean }) => (
+    <textarea data-testid="composer" data-resize-suspended={layoutResizeSuspended} defaultValue="draft" />
+  ),
+}));
+vi.mock('./ChatFileDropOverlay', () => ({ ChatFileDropOverlay: () => null }));
+vi.mock('@/flow_chat/contexts/ConversationViewProvider', () => ({
+  ConversationViewProvider: ({ children }: { children: React.ReactNode }) => children,
+}));
+vi.mock('@/shared/utils/tabUtils', () => ({ createTab: vi.fn() }));
+vi.mock('@/shared/services/workbenchContentService', () => ({ openWorkbenchContent: vi.fn() }));
+vi.mock('@/flow_chat/store/FlowChatStore', () => ({ flowChatStore: {} }));
+vi.mock('@/flow_chat/session-drivers/sessionFileNavigation', () => ({ sessionWorkspaceId: vi.fn() }));
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+it('docks only the composer and forwards resize suspension without remounting the transcript or draft', () => {
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  try {
+    act(() => root.render(<ChatPane width={0} isFullscreen={false} showChatInput />));
+    const transcript = container.querySelector('[data-testid="transcript"]')!;
+    const composer = container.querySelector<HTMLTextAreaElement>('[data-testid="composer"]')!;
+    const dock = container.querySelector('[data-openbitfun-part="primaryDock"]')!;
+    expect(dock.contains(composer)).toBe(true);
+    expect(dock.contains(transcript)).toBe(false);
+    composer.value = 'unsent';
+    for (const isDragging of [true, false]) {
+      act(() => root.render(<ChatPane width={0} isFullscreen={false} showChatInput isDragging={isDragging} />));
+      expect(container.querySelector('[data-testid="transcript"]')).toBe(transcript);
+      expect(container.querySelector('[data-testid="composer"]')).toBe(composer);
+      expect(composer.value).toBe('unsent');
+      expect(composer.dataset.resizeSuspended).toBe(String(isDragging));
+    }
+  } finally {
+    act(() => root.unmount());
+    container.remove();
+  }
+});
diff --git a/src/web-ui/src/app/scenes/session/ChatPane.tsx b/src/web-ui/src/app/scenes/session/ChatPane.tsx
index d69b1c3656..8260ed892d 100644
--- a/src/web-ui/src/app/scenes/session/ChatPane.tsx
+++ b/src/web-ui/src/app/scenes/session/ChatPane.tsx
@@ -6,6 +6,7 @@
  */
 
 import React, { useCallback, memo, useRef, useState, useMemo, useContext } from 'react';
+import { SplitViewPrimaryDock } from '@openbitfun/ui';
 import { ChatFileDropOverlay } from './ChatFileDropOverlay';
 import type { FileDropPreview, FileDropPosition } from '@/shared/types/fileDropPreview';
 import { ModernFlowChatContainer as FlowChatContainer } from '../../../flow_chat/components/modern/ModernFlowChatContainer';
@@ -55,7 +56,7 @@ const ChatPaneInner: React.FC<ChatPaneProps> = ({
   isFullscreen,
   isSceneActive: hostActive = true,
   workspacePath,
-  isDragging: _isDragging = false,
+  isDragging = false,
   showChatInput = false,
   isRightPanelOpen = false,
   onToggleRightPanel,
@@ -143,14 +144,17 @@ const ChatPaneInner: React.FC<ChatPaneProps> = ({
         onTabOpen={handleTabOpen}
       />
       {showChatInput && (
-        <ChatInput
-          fileDropTargetRef={fileDropTargetRef}
-          onFileDragOverChange={setIsFileDragOver}
-          onFileDragPreviewChange={setFilePreview}
-          onFileDragPositionChange={updateFileDragPosition}
-          isSceneActive={isSceneActive}
-          registration={chatInputRegistration}
-        />
+        <SplitViewPrimaryDock>
+          <ChatInput
+            fileDropTargetRef={fileDropTargetRef}
+            onFileDragOverChange={setIsFileDragOver}
+            onFileDragPreviewChange={setFilePreview}
+            onFileDragPositionChange={updateFileDragPosition}
+            isSceneActive={isSceneActive}
+            layoutResizeSuspended={isDragging}
+            registration={chatInputRegistration}
+          />
+        </SplitViewPrimaryDock>
       )}
       {showChatInput && isSceneActive && isFileDragOver && (
         <ChatFileDropOverlay preview={filePreview} positionRef={fileDragPosition} />
diff --git a/src/web-ui/src/app/scenes/session/SessionScene.overlay.test.tsx b/src/web-ui/src/app/scenes/session/SessionScene.overlay.test.tsx
new file mode 100644
index 0000000000..71793dba09
--- /dev/null
+++ b/src/web-ui/src/app/scenes/session/SessionScene.overlay.test.tsx
@@ -0,0 +1,92 @@
+// @vitest-environment jsdom
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import SessionScene from './SessionScene';
+import { sessionPaneLayoutStore } from './sessionPaneLayoutStore';
+import SessionPanelSettingsSection from '../settings/pages/application/SessionPanelSettingsSection';
+
+const mocks = vi.hoisted(() => ({ selectLayout: null as null | ((value: string) => void) }));
+
+vi.mock('@openbitfun/ui', async importOriginal => ({
+  ...await importOriginal<typeof import('@openbitfun/ui')>(),
+  Select: ({ value, onValueChange }: { value: string; onValueChange: (value: string) => void }) => {
+    mocks.selectLayout = onValueChange;
+    return <output data-testid="layout-preference">{value}</output>;
+  },
+}));
+vi.mock('@/infrastructure/i18n', () => ({ useI18n: () => ({ t: (key: string) => key }) }));
+vi.mock('../../hooks/useApp', () => ({
+  useApp: () => ({ state: { layout: { bottomTerminalPanelCollapsed: true } }, updateBottomTerminalPanelHeight: vi.fn() }),
+}));
+vi.mock('./ChatPane', () => ({ default: () => <textarea data-testid="chat-draft" defaultValue="draft" /> }));
+vi.mock('./AuxPane', () => ({ default: () => <iframe title="Editor" /> }));
+vi.mock('./BottomTerminalPane', () => ({ default: () => null }));
+vi.mock('./sessionPanelLayout', () => ({ collapseSessionBottomTerminalPane: vi.fn(), expandSessionBottomTerminalPane: vi.fn() }));
+vi.mock('@/tools/terminal/services/terminalPanelPreferenceService', () => ({
+  getCachedTerminalPanelPosition: () => 'right',
+  onTerminalPanelPositionChange: () => () => {},
+  refreshTerminalPanelPosition: vi.fn(),
+}));
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+describe('session overlay layout integration', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+  const split = () => container.querySelector<HTMLElement>('[data-openbitfun-component="split-view"][data-openbitfun-part="root"]')!;
+
+  beforeEach(() => {
+    sessionPaneLayoutStore.setState(sessionPaneLayoutStore.getInitialState());
+    vi.stubGlobal('ResizeObserver', class { observe() {} disconnect() {} });
+    vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function () {
+      return { width: this.getAttribute('data-openbitfun-part') === 'divider' ? 1 : 1201 } as DOMRect;
+    });
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    sessionPaneLayoutStore.setState(sessionPaneLayoutStore.getInitialState());
+    localStorage.clear();
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it('applies the settings selection to a mounted scene and routes resizing to independent preferences', () => {
+    const pane = sessionPaneLayoutStore.getState();
+    pane.showContent();
+    pane.resizeRightPane(600);
+    pane.resizeOverlay(700);
+    act(() => root.render(<><SessionScene /><SessionPanelSettingsSection /></>));
+    const draft = container.querySelector<HTMLTextAreaElement>('[data-testid="chat-draft"]')!;
+    const editor = container.querySelector('iframe');
+    draft.value = 'unsent edit';
+    expect(split().getAttribute('data-layout')).toBe('split');
+    expect(split().style.getPropertyValue('--_split-view-right-size')).toBe('600px');
+
+    act(() => mocks.selectLayout!('overlay'));
+    expect(container.querySelector('.openbitfun-session-scene--overlay')).not.toBeNull();
+    expect(split().getAttribute('data-layout')).toBe('overlay');
+    expect(split().style.getPropertyValue('--_split-view-right-size')).toBe('700px');
+    const handle = container.querySelector<HTMLElement>('[role="separator"]')!;
+    act(() => handle.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowLeft', bubbles: true, cancelable: true })));
+    expect(sessionPaneLayoutStore.getState()).toMatchObject({ preferredOverlayWidth: 710, preferredRightPaneWidth: 600 });
+    act(() => pane.swapPanes());
+    expect(split().getAttribute('data-secondary-side')).toBe('left');
+    act(() => pane.hideContent());
+    expect(split().getAttribute('data-mode')).toBe('primary');
+    act(() => pane.showContent());
+    act(() => pane.maximizeContent());
+    expect(split().getAttribute('data-mode')).toBe('secondary');
+    act(() => mocks.selectLayout!('split'));
+    expect(split().getAttribute('data-mode')).toBe('secondary');
+    expect(split().style.getPropertyValue('--_split-view-right-size')).toBe('600px');
+    expect(container.querySelector('[data-testid="chat-draft"]')).toBe(draft);
+    expect(draft.value).toBe('unsent edit');
+    expect(container.querySelector('iframe')).toBe(editor);
+  });
+});
diff --git a/src/web-ui/src/app/scenes/session/SessionScene.tsx b/src/web-ui/src/app/scenes/session/SessionScene.tsx
index 3361fa46dd..a909ce56c3 100644
--- a/src/web-ui/src/app/scenes/session/SessionScene.tsx
+++ b/src/web-ui/src/app/scenes/session/SessionScene.tsx
@@ -65,7 +65,7 @@ const SessionScene: React.FC<SessionSceneProps> = ({ workspacePath, isEntering =
       frame = requestAnimationFrame(() => setIsContentSettling(false));
     });
     return () => cancelAnimationFrame(frame);
-  }, [pane.mode, pane.contentSide, pane.preferredRightPaneWidth]);
+  }, [pane.mode, pane.contentSide, pane.displayMode, pane.preferredRightPaneWidth, pane.preferredOverlayWidth]);
 
   useLayoutEffect(() => {
     const element = bottomTerminalPaneElementRef.current;
@@ -198,6 +198,7 @@ const SessionScene: React.FC<SessionSceneProps> = ({ workspacePath, isEntering =
       className={[
         'openbitfun-session-scene', isDragging && 'openbitfun-session-scene--dragging',
         isDraggingBottom && 'openbitfun-session-scene--dragging-bottom',
+        pane.displayMode === 'overlay' && 'openbitfun-session-scene--overlay',
         isTerminalDockedBottom && 'openbitfun-session-scene--terminal-bottom', isEntering && 'layout-entering',
       ].filter(Boolean).join(' ')}
       data-testid="session-scene" data-openbitfun-scene="session" data-openbitfun-part="root"
@@ -206,13 +207,14 @@ const SessionScene: React.FC<SessionSceneProps> = ({ workspacePath, isEntering =
       <div className="openbitfun-session-scene__main-row" data-openbitfun-scene="session" data-openbitfun-part="main">
         <SplitView
           mode={pane.mode === 'chat-only' ? 'primary' : pane.mode === 'content-only' ? 'secondary' : 'split'}
+          layout={pane.displayMode}
           secondarySide={pane.contentSide}
-          rightSize={pane.preferredRightPaneWidth}
+          rightSize={pane.displayMode === 'overlay' ? pane.preferredOverlayWidth : pane.preferredRightPaneWidth}
           minLeftSize={PANEL_COMMON_CONFIG.MIN_CENTER_WIDTH}
           minRightSize={RIGHT_PANEL_CONFIG.COMPACT_WIDTH}
           maxRightSize={RIGHT_PANEL_CONFIG.MAX_WIDTH}
           defaultRightSize={RIGHT_PANEL_CONFIG.COMFORTABLE_DEFAULT}
-          onRightSizeChange={pane.resizeRightPane}
+          onRightSizeChange={pane.displayMode === 'overlay' ? pane.resizeOverlay : pane.resizeRightPane}
           onResizeStateChange={setIsDraggingContent}
           dividerLabel={tPane('canvas.resizePanes')}
           primaryPaneProps={{ 'aria-label': tPane('canvas.chatPane') }}
diff --git a/src/web-ui/src/app/scenes/session/sessionPaneLayoutStore.test.ts b/src/web-ui/src/app/scenes/session/sessionPaneLayoutStore.test.ts
index d85fdce4b1..a7b8fbce06 100644
--- a/src/web-ui/src/app/scenes/session/sessionPaneLayoutStore.test.ts
+++ b/src/web-ui/src/app/scenes/session/sessionPaneLayoutStore.test.ts
@@ -8,6 +8,39 @@ function preferences(values: Record<string, string> = {}) {
 }
 
 describe('session pane layout', () => {
+  it('applies the local display preference immediately, retaining session modes and separate widths', () => {
+    const storage = preferences({ [STORAGE_KEYS.RIGHT_PANEL_LAST_WIDTH]: '640' });
+    const store = createSessionPaneLayoutStore(storage);
+    const pane = store.getState();
+    expect(pane.displayMode).toBe('split');
+    pane.activate('local', 'a');
+    pane.showContent();
+    pane.setDisplayMode('overlay');
+    pane.resizeOverlay(720);
+    pane.swapPanes();
+    pane.maximizeContent();
+    pane.setDisplayMode('split');
+    expect(selectSessionPaneMode(store.getState())).toBe('content-only');
+    expect(store.getState()).toMatchObject({ preferredRightPaneWidth: 640, preferredOverlayWidth: 720, contentSide: 'left' });
+    pane.activate('peer', 'a');
+    expect(store.getState().displayMode).toBe('split');
+    pane.setDisplayMode('overlay');
+    const reopened = createSessionPaneLayoutStore(storage).getState();
+    expect(reopened).toMatchObject({ displayMode: 'overlay', preferredRightPaneWidth: 640, preferredOverlayWidth: 720 });
+    expect(selectSessionPaneMode(reopened)).toBe('chat-only');
+    expect(storage.setItem.mock.calls.some(([key]) => key === STORAGE_KEYS.RIGHT_PANEL_LAST_WIDTH)).toBe(false);
+  });
+
+  it('falls back for unknown layout preferences without rewriting them', () => {
+    const storage = preferences({ 'openbitfun:sessionPaneDisplayMode': 'future', 'openbitfun:sessionOverlayWidth': 'invalid' });
+    const store = createSessionPaneLayoutStore(storage);
+    expect(store.getState().displayMode).toBe('split');
+    expect(store.getState().preferredOverlayWidth).toBeGreaterThan(0);
+    store.getState().resizeOverlay(Number.NaN);
+    store.getState().resizeOverlay(-1);
+    expect(storage.setItem).not.toHaveBeenCalled();
+  });
+
   it('swaps content without moving the divider, including hide and fullscreen round trips', () => {
     const storage = preferences({ [STORAGE_KEYS.RIGHT_PANEL_LAST_WIDTH]: '640' });
     const store = createSessionPaneLayoutStore(storage);
@@ -101,6 +134,8 @@ describe('session pane layout', () => {
     store.getState().showContent();
     store.getState().swapPanes();
     store.getState().resizeRightPane(620);
-    expect(store.getState()).toMatchObject({ contentSide: 'left', preferredRightPaneWidth: 620 });
+    store.getState().setDisplayMode('overlay');
+    store.getState().resizeOverlay(700);
+    expect(store.getState()).toMatchObject({ contentSide: 'left', preferredRightPaneWidth: 620, displayMode: 'overlay', preferredOverlayWidth: 700 });
   });
 });
diff --git a/src/web-ui/src/app/scenes/session/sessionPaneLayoutStore.ts b/src/web-ui/src/app/scenes/session/sessionPaneLayoutStore.ts
index 3695d00f64..2b32b2e133 100644
--- a/src/web-ui/src/app/scenes/session/sessionPaneLayoutStore.ts
+++ b/src/web-ui/src/app/scenes/session/sessionPaneLayoutStore.ts
@@ -5,6 +5,7 @@ import { RIGHT_PANEL_CONFIG, STORAGE_KEYS } from '../../layout/panelConfig';
 
 export type SessionPaneMode = 'chat-only' | 'split' | 'content-only';
 export type ContentPaneSide = 'left' | 'right';
+export type SessionPaneDisplayMode = 'split' | 'overlay';
 type PreferenceStorage = Pick<Storage, 'getItem' | 'setItem'>;
 
 export interface LegacySessionPaneLayout {
@@ -18,6 +19,10 @@ interface SessionPaneLayoutState {
   activeKey: string;
   modes: ReadonlyMap<string, SessionPaneMode>;
   contentSide: ContentPaneSide;
+  displayMode: SessionPaneDisplayMode;
+  preferredOverlayWidth: number;
+  setDisplayMode: (mode: SessionPaneDisplayMode) => void;
+  resizeOverlay: (width: number) => void;
   /** A physical slot preference, independent of which content occupies it. */
   preferredRightPaneWidth: number;
   activate: (surfaceId: string, sessionId: string | null) => void;
@@ -35,6 +40,8 @@ interface SessionPaneLayoutState {
 }
 
 const CONTENT_SIDE_KEY = 'openbitfun:sessionContentSide';
+const DISPLAY_MODE_KEY = 'openbitfun:sessionPaneDisplayMode';
+const OVERLAY_WIDTH_KEY = 'openbitfun:sessionOverlayWidth';
 const scopeKey = (surfaceId: string, sessionId: string | null) => surfaceScopedKey(surfaceId, sessionId);
 
 export const selectSessionPaneMode = (state: SessionPaneLayoutState): SessionPaneMode => (
@@ -65,6 +72,7 @@ export function createSessionPaneLayoutStore(storage = localPreferenceStorage())
     try { storage?.setItem(key, value); } catch { /* Layout remains usable without storage. */ }
   };
   const savedWidth = Number(read(STORAGE_KEYS.RIGHT_PANEL_LAST_WIDTH));
+  const savedOverlayWidth = Number(read(OVERLAY_WIDTH_KEY));
   const defaultWidth = typeof window !== 'undefined'
     ? Math.max(540, Math.min(800, Math.floor(window.innerWidth * 0.35)))
     : RIGHT_PANEL_CONFIG.COMFORTABLE_DEFAULT;
@@ -83,6 +91,21 @@ export function createSessionPaneLayoutStore(storage = localPreferenceStorage())
       activeKey: scopeKey('local', null),
       modes: new Map(),
       contentSide: read(CONTENT_SIDE_KEY) === 'left' ? 'left' : 'right',
+      displayMode: read(DISPLAY_MODE_KEY) === 'overlay' ? 'overlay' : 'split',
+      preferredOverlayWidth: Number.isFinite(savedOverlayWidth) && savedOverlayWidth > 0
+        ? normalizeWidth(savedOverlayWidth) : defaultWidth,
+      setDisplayMode: displayMode => {
+        if ((displayMode !== 'split' && displayMode !== 'overlay') || get().displayMode === displayMode) return;
+        write(DISPLAY_MODE_KEY, displayMode);
+        set({ displayMode });
+      },
+      resizeOverlay: width => {
+        if (!Number.isFinite(width) || width <= 0) return;
+        const preferredOverlayWidth = normalizeWidth(width);
+        if (get().preferredOverlayWidth === preferredOverlayWidth) return;
+        write(OVERLAY_WIDTH_KEY, String(preferredOverlayWidth));
+        set({ preferredOverlayWidth });
+      },
       preferredRightPaneWidth: Number.isFinite(savedWidth) && savedWidth > 0
         ? normalizeWidth(savedWidth) : defaultWidth,
       activate: (surfaceId, sessionId) => {
@@ -145,6 +168,9 @@ export function useSessionPaneLayout() {
   const mode = useStore(sessionPaneLayoutStore, selectSessionPaneMode);
   const contentSide = useStore(sessionPaneLayoutStore, state => state.contentSide);
   const preferredRightPaneWidth = useStore(sessionPaneLayoutStore, state => state.preferredRightPaneWidth);
-  const { showContent, hideContent, toggleContent, toggleMaximized, swapPanes, resizeRightPane } = sessionPaneLayoutStore.getState();
-  return { mode, contentSide, preferredRightPaneWidth, showContent, hideContent, toggleContent, toggleMaximized, swapPanes, resizeRightPane };
+  const displayMode = useStore(sessionPaneLayoutStore, state => state.displayMode);
+  const preferredOverlayWidth = useStore(sessionPaneLayoutStore, state => state.preferredOverlayWidth);
+  const { showContent, hideContent, toggleContent, toggleMaximized, swapPanes, resizeRightPane, resizeOverlay } = sessionPaneLayoutStore.getState();
+  return { mode, contentSide, displayMode, preferredOverlayWidth, preferredRightPaneWidth,
+    showContent, hideContent, toggleContent, toggleMaximized, swapPanes, resizeRightPane, resizeOverlay };
 }
diff --git a/src/web-ui/src/app/scenes/settings/pages/application/AppearanceSettingsPage.test.tsx b/src/web-ui/src/app/scenes/settings/pages/application/AppearanceSettingsPage.test.tsx
index 8f9d7f5507..ae2bc483c7 100644
--- a/src/web-ui/src/app/scenes/settings/pages/application/AppearanceSettingsPage.test.tsx
+++ b/src/web-ui/src/app/scenes/settings/pages/application/AppearanceSettingsPage.test.tsx
@@ -68,6 +68,7 @@ describe('AppearanceSettingsPage', () => {
     document.body.innerHTML = renderToStaticMarkup(<AppearanceSettingsPage />);
     expect(document.querySelector('[data-testid="appearance-package-config"]')).not.toBeNull();
     expect(document.querySelector('[data-testid="appearance-font-section"]')).not.toBeNull();
+    expect(document.querySelector('[aria-label="sessionPanel.displayMode"]')).not.toBeNull();
     expect(document.querySelector('[data-testid="appearance-language-select"]')).toBeNull();
     expect(document.querySelector('[data-testid="appearance-palette-select"]')).toBeNull();
     expect(document.querySelector('[data-testid="appearance-package-select"]')).toBeNull();
diff --git a/src/web-ui/src/app/scenes/settings/pages/application/AppearanceSettingsPage.tsx b/src/web-ui/src/app/scenes/settings/pages/application/AppearanceSettingsPage.tsx
index 64b52c4e33..5d4859d07b 100644
--- a/src/web-ui/src/app/scenes/settings/pages/application/AppearanceSettingsPage.tsx
+++ b/src/web-ui/src/app/scenes/settings/pages/application/AppearanceSettingsPage.tsx
@@ -7,6 +7,7 @@ import {
   ConfigPageSectionStack
 } from '@/infrastructure/config/components/common';
 import { FontPreferencePanel } from '@/infrastructure/font-preference';
+import SessionPanelSettingsSection from './SessionPanelSettingsSection';
 import React from 'react';
 import { useTranslation } from 'react-i18next';
 
@@ -28,6 +29,7 @@ const AppearanceSettingsPage: React.FC = () => {
         <ConfigPageSectionStack data-testid="appearance-settings">
           <AppearancePackageConfigSection />
           <FontPreferencePanel />
+          <SessionPanelSettingsSection />
         </ConfigPageSectionStack>
       </ConfigPageContent>
     </ConfigPageLayout>
diff --git a/src/web-ui/src/app/scenes/settings/pages/application/SessionPanelSettingsSection.tsx b/src/web-ui/src/app/scenes/settings/pages/application/SessionPanelSettingsSection.tsx
new file mode 100644
index 0000000000..c5bb77ba26
--- /dev/null
+++ b/src/web-ui/src/app/scenes/settings/pages/application/SessionPanelSettingsSection.tsx
@@ -0,0 +1,25 @@
+import { useStore } from 'zustand';
+import { Select } from '@openbitfun/ui';
+import { useI18n } from '@/infrastructure/i18n';
+import { ConfigPageRow, ConfigPageSection } from '@/infrastructure/config/components/common';
+import { sessionPaneLayoutStore, type SessionPaneDisplayMode } from '@/app/scenes/session/sessionPaneLayoutStore';
+
+export default function SessionPanelSettingsSection() {
+  const { t } = useI18n('settings/appearance');
+  const displayMode = useStore(sessionPaneLayoutStore, state => state.displayMode);
+  const setDisplayMode = useStore(sessionPaneLayoutStore, state => state.setDisplayMode);
+
+  return (
+    <ConfigPageSection title={t('sessionPanel.title')}>
+      <ConfigPageRow label={t('sessionPanel.displayMode')} align="center">
+        <Select size="sm" value={displayMode}
+          onValueChange={value => setDisplayMode(value as SessionPaneDisplayMode)}
+          options={[
+            { value: 'split', label: t('sessionPanel.split') },
+            { value: 'overlay', label: t('sessionPanel.overlay') },
+          ]}
+          aria-label={t('sessionPanel.displayMode')} />
+      </ConfigPageRow>
+    </ConfigPageSection>
+  );
+}
diff --git a/src/web-ui/src/app/scenes/settings/settingsRegistry.ts b/src/web-ui/src/app/scenes/settings/settingsRegistry.ts
index c4e72c4bc9..cbdb413768 100644
--- a/src/web-ui/src/app/scenes/settings/settingsRegistry.ts
+++ b/src/web-ui/src/app/scenes/settings/settingsRegistry.ts
@@ -87,6 +87,7 @@ export const SETTINGS_PAGE_MANIFESTS: readonly SettingsPageManifest[] = [
     keywords: [
       'theme', 'font', 'size', 'motion', 'animation',
       'appearance pack', 'skin', 'import',
+      'session', 'panel', 'layout', 'overlay',
     ],
     namespaces: ['settings/appearance', 'settings/application'],
     searchPhrases: [
@@ -95,6 +96,10 @@ export const SETTINGS_PAGE_MANIFESTS: readonly SettingsPageManifest[] = [
       phrase('settings/appearance', 'package.title'),
       phrase('settings/appearance', 'package.description'),
       phrase('settings/application', 'appearance.fontSize.title'),
+      phrase('settings/appearance', 'sessionPanel.title'),
+      phrase('settings/appearance', 'sessionPanel.displayMode'),
+      phrase('settings/appearance', 'sessionPanel.split'),
+      phrase('settings/appearance', 'sessionPanel.overlay'),
     ],
     load: () => import('./pages/application/AppearanceSettingsPage'),
   }),
diff --git a/src/web-ui/src/flow_chat/components/ChatInput.tsx b/src/web-ui/src/flow_chat/components/ChatInput.tsx
index d97401394b..ad2536d1fb 100644
--- a/src/web-ui/src/flow_chat/components/ChatInput.tsx
+++ b/src/web-ui/src/flow_chat/components/ChatInput.tsx
@@ -300,6 +300,8 @@ export interface ChatInputProps {
   presentation?: 'standard' | 'conversation';
   className?: string;
   isSceneActive?: boolean;
+  /** Defer expensive width measurement until the host's interactive resize settles. */
+  layoutResizeSuspended?: boolean;
   /** The host conversation area that accepts files for this composer. */
   fileDropTargetRef?: React.RefObject<HTMLElement | null>;
   onFileDragOverChange?: (isOver: boolean) => void;
@@ -512,6 +514,7 @@ interface ExternalFileIntakeRequest {
 export const ChatInput: React.FC<ChatInputProps> = ({
   className = '',
   isSceneActive = true,
+  layoutResizeSuspended = false,
   fileDropTargetRef,
   onFileDragOverChange,
   onFileDragPreviewChange,
@@ -1038,6 +1041,7 @@ export const ChatInput: React.FC<ChatInputProps> = ({
   }, [checkDomEmpty]);
 
   useEffect(() => {
+    if (layoutResizeSuspended) return;
     const containerEl = containerRef.current;
     const boxEl = containerEl?.querySelector('.openbitfun-chat-input__box') as HTMLElement | null;
     const actionsLeftEl = containerEl?.querySelector('.openbitfun-chat-input__actions-left') as HTMLElement | null;
@@ -1092,6 +1096,7 @@ export const ChatInput: React.FC<ChatInputProps> = ({
     currentImageCount,
     derivedState?.sendButtonMode,
     isMultiLine,
+    layoutResizeSuspended,
     refreshCapsuleInputWidth,
     showTargetSwitcher,
   ]);
diff --git a/src/web-ui/src/infrastructure/design-system/SplitView.appearance.ts b/src/web-ui/src/infrastructure/design-system/SplitView.appearance.ts
index 193a72aab5..b7b331efc3 100644
--- a/src/web-ui/src/infrastructure/design-system/SplitView.appearance.ts
+++ b/src/web-ui/src/infrastructure/design-system/SplitView.appearance.ts
@@ -6,6 +6,7 @@ export const splitViewAppearanceDescriptor: AppearanceSurfaceDescriptor = {
   parts: [
     { id: 'root', propertyProfile: 'layout' },
     { id: 'primary', propertyProfile: 'layout' },
+    { id: 'primaryDock', propertyProfile: 'layout' },
     { id: 'secondary', propertyProfile: 'layout' },
     { id: 'divider', propertyProfile: 'layout' },
     { id: 'resizeHandle', propertyProfile: 'layout' },
diff --git a/src/web-ui/src/locales/en-US/settings/appearance.json b/src/web-ui/src/locales/en-US/settings/appearance.json
index c7ba2e8288..f64b31cae1 100644
--- a/src/web-ui/src/locales/en-US/settings/appearance.json
+++ b/src/web-ui/src/locales/en-US/settings/appearance.json
@@ -1,6 +1,12 @@
 {
   "title": "Appearance",
   "subtitle": "Choose the interface language, theme, and text size",
+  "sessionPanel": {
+    "title": "Session panel",
+    "displayMode": "Panel layout",
+    "split": "Side by side",
+    "overlay": "Overlay"
+  },
   "package": {
     "title": "Appearance",
     "description": "Appearance packs are stored on this device; hover over a thumbnail to preview",
diff --git a/src/web-ui/src/locales/zh-CN/settings/appearance.json b/src/web-ui/src/locales/zh-CN/settings/appearance.json
index 238dec6423..0307053ee3 100644
--- a/src/web-ui/src/locales/zh-CN/settings/appearance.json
+++ b/src/web-ui/src/locales/zh-CN/settings/appearance.json
@@ -1,6 +1,12 @@
 {
   "title": "外观",
   "subtitle": "调整界面语言、主题与字体大小",
+  "sessionPanel": {
+    "title": "会话侧边面板",
+    "displayMode": "面板布局",
+    "split": "并排",
+    "overlay": "覆盖"
+  },
   "package": {
     "title": "外观",
     "description": "外观包保存在当前设备；悬停缩略图可预览",
diff --git a/src/web-ui/src/locales/zh-TW/settings/appearance.json b/src/web-ui/src/locales/zh-TW/settings/appearance.json
index 3b88cd697f..ca9044bb6b 100644
--- a/src/web-ui/src/locales/zh-TW/settings/appearance.json
+++ b/src/web-ui/src/locales/zh-TW/settings/appearance.json
@@ -1,6 +1,12 @@
 {
   "title": "外觀",
   "subtitle": "調整介面語言、主題與字體大小",
+  "sessionPanel": {
+    "title": "工作階段側邊面板",
+    "displayMode": "面板佈局",
+    "split": "並排",
+    "overlay": "覆蓋"
+  },
   "package": {
     "title": "外觀",
     "description": "外觀套件儲存在目前裝置；將游標停留在縮圖上可預覽",
diff --git a/src/web-ui/src/shared/ui/SplitView.test.tsx b/src/web-ui/src/shared/ui/SplitView.test.tsx
index 93c6ffb7d8..b0dd1c8579 100644
--- a/src/web-ui/src/shared/ui/SplitView.test.tsx
+++ b/src/web-ui/src/shared/ui/SplitView.test.tsx
@@ -2,7 +2,7 @@
 import React, { act } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { SplitView, type SplitViewProps } from '@openbitfun/ui';
+import { SplitView, SplitViewPrimaryDock, type SplitViewProps } from '@openbitfun/ui';
 
 globalThis.IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -15,7 +15,7 @@ describe('shared SplitView interaction contract', () => {
   let resizing: ReturnType<typeof vi.fn>;
   const part = (name: string) => container.querySelector<HTMLElement>(`[data-openbitfun-component="split-view"][data-openbitfun-part="${name}"]`)!;
   const render = (props: Partial<SplitViewProps> = {}) => act(() => root.render(<SplitView
-    primary={<textarea aria-label="Draft" defaultValue="unsent" />}
+    primary={<SplitViewPrimaryDock><textarea aria-label="Draft" defaultValue="unsent" /></SplitViewPrimaryDock>}
     secondary={<iframe title="Content" />}
     rightSize={400} minLeftSize={300} minRightSize={200}
     onRightSizeChange={changed} onResizeStateChange={resizing}
@@ -74,6 +74,34 @@ describe('shared SplitView interaction contract', () => {
     }
   });
 
+  it('retains edited content across live layout switches and overlay visibility changes', () => {
+    render();
+    const draft = container.querySelector('textarea')!;
+    const frame = container.querySelector('iframe')!;
+    draft.value = 'still editing';
+    for (const layout of ['overlay', 'split', 'overlay'] as const) {
+      for (const mode of ['split', 'primary', 'secondary', 'split'] as const) {
+        render({ layout, mode });
+        expect(part('root').getAttribute('data-layout')).toBe(layout);
+        expect(container.querySelector('textarea')).toBe(draft);
+        expect(draft.value).toBe('still editing');
+        expect(container.querySelector('iframe')).toBe(frame);
+        expect(part('primary').hidden).toBe(mode === 'secondary');
+        expect(part('secondary').hidden).toBe(mode === 'primary');
+      }
+    }
+  });
+
+  it.each(['left', 'right'] as const)('resizes the %s overlay from its inner edge', secondarySide => {
+    render({ layout: 'overlay', secondarySide, minLeftSize: 0 });
+    expect(part('resizeHandle').getAttribute('aria-controls')).toBe(part('secondary').id);
+    key(part('resizeHandle'), 'ArrowRight');
+    expect(changed).toHaveBeenLastCalledWith(secondarySide === 'left' ? 410 : 390);
+    pointer('pointerdown', 600);
+    pointer('pointerup', 650);
+    expect(changed).toHaveBeenLastCalledWith(secondarySide === 'left' ? 450 : 350);
+  });
+
   it('clamps display to a smaller container without overwriting the preferred width', () => {
     render({ rightSize: 600 });
     width = 701; act(() => resized());
@@ -83,6 +111,26 @@ describe('shared SplitView interaction contract', () => {
     expect(changed).not.toHaveBeenCalled();
   });
 
+  it('reserves uncovered overlay space for a stable primary dock through clamping and dragging', () => {
+    render({ layout: 'overlay', rightSize: 900, minLeftSize: 400 });
+    const dock = part('primaryDock');
+    const draft = container.querySelector('textarea')!;
+    expect(part('root').style.getPropertyValue('--_split-view-right-size')).toBe('600px');
+    width = 601; act(() => resized());
+    expect(part('root').style.getPropertyValue('--_split-view-right-size')).toBe('300px');
+    width = 1201; act(() => resized());
+    expect(part('root').style.getPropertyValue('--_split-view-right-size')).toBe('800px');
+    pointer('pointerdown', 400); pointer('pointermove', 500);
+    act(() => vi.advanceTimersByTime(16));
+    expect(part('root').style.getPropertyValue('--_split-view-right-size')).toBe('700px');
+    expect(part('primaryDock')).toBe(dock);
+    expect(container.querySelector('textarea')).toBe(draft);
+    pointer('pointercancel', 500);
+    render({ layout: 'overlay', secondarySide: 'left', mode: 'primary' });
+    expect(part('primaryDock')).toBe(dock);
+    expect(changed).not.toHaveBeenCalled();
+  });
+
   it('commits once at pointer release, even before the last animation frame', () => {
     render();
     document.body.style.cursor = 'crosshair'; document.body.style.userSelect = 'text';
@@ -96,11 +144,12 @@ describe('shared SplitView interaction contract', () => {
     expect(document.body.style.cursor).toBe('crosshair'); expect(document.body.style.userSelect).toBe('text');
   });
 
-  it.each(['pointercancel', 'lostpointercapture', 'Escape', 'mode'])('cancels without persisting on %s', reason => {
+  it.each(['pointercancel', 'lostpointercapture', 'Escape', 'mode', 'layout'])('cancels without persisting on %s', reason => {
     render(); pointer('pointerdown', 600); pointer('pointermove', 550);
     act(() => vi.advanceTimersByTime(16));
     if (reason === 'Escape') key(part('resizeHandle'), 'Escape');
     else if (reason === 'mode') render({ mode: 'secondary' });
+    else if (reason === 'layout') render({ layout: 'overlay' });
     else pointer(reason, 550);
     expect(changed).not.toHaveBeenCalled();
     expect(part('root').style.getPropertyValue('--_split-view-right-size')).toBe('400px');