dockview-core 6.6.1 → 7.0.3

package/dist/esm/dockview/dockviewComponent.js

@@ -1,7 +1,6 @@
-import { getRelativeLocation, getGridLocation, orthogonal, } from '../gridview/gridview';
+import { getRelativeLocation, getGridLocation, orthogonal, Gridview, } from '../gridview/gridview';
 import { directionToPosition, } from '../dnd/droptarget';
-import { html5Backend, pointerBackend } from '../dnd/backend';
-import { tail, sequenceEquals, remove } from '../array';
+import { tail, sequenceEquals } from '../array';
 import { DockviewPanel } from './dockviewPanel';
 import { CompositeDisposable, Disposable } from '../lifecycle';
 import { Event, Emitter, addDisposableListener } from '../events';
@@ -11,29 +10,26 @@ import { DefaultDockviewDeserialzier } from './deserializer';
 import { DockviewUnhandledDragOverEvent, isGroupOptionsWithGroup, isGroupOptionsWithPanel, isPanelOptionsWithGroup, isPanelOptionsWithPanel, } from './options';
 import { BaseGrid, toTarget, } from '../gridview/baseComponentGridview';
 import { DockviewApi } from '../api/component.api';
-import { Orientation } from '../splitview/splitview';
+import { Orientation, Sizing } from '../splitview/splitview';
 import { DockviewDidDropEvent, DockviewWillDropEvent, } from './dockviewGroupPanelModel';
 import { DockviewWillShowOverlayLocationEvent, } from './events';
 import { DockviewGroupPanel } from './dockviewGroupPanel';
 import { DockviewPanelModel } from './dockviewPanelModel';
 import { getPanelData } from '../dnd/dataTransfer';
 import { Overlay } from '../overlay/overlay';
-import { addTestId, Classnames, getDockviewTheme, onDidWindowResizeEnd, onDidWindowMoveEnd, toggleClass, watchElementResize, } from '../dom';
-import { DockviewFloatingGroupPanel } from './dockviewFloatingGroupPanel';
+import { Classnames, getDockviewTheme, onDidWindowResizeEnd, onDidWindowMoveEnd, toggleClass, } from '../dom';
+import { FloatingTitleBar } from './components/titlebar/floatingTitleBar';
+import { assertModule, getRegisteredModules, isDockviewPackageLoaded, ModuleRegistry, } from './modules';
+import { AllModules } from './allModules';
 import { DEFAULT_FLOATING_GROUP_OVERFLOW_SIZE, DEFAULT_FLOATING_GROUP_POSITION, DESERIALIZATION_POPOUT_DELAY_MS, } from '../constants';
 import { OverlayRenderContainer, } from '../overlay/overlayRenderContainer';
 import { PopoutWindow } from '../popoutWindow';
 import { StrictEventsSequencing } from './strictEventsSequencing';
 import { PopupService } from './components/popupService';
-import { ContextMenuController } from './contextMenu';
 import { DropTargetAnchorContainer } from '../dnd/dropTargetAnchorContainer';
 import { themeAbyss } from './theme';
 import { ShellManager, } from './dockviewShell';
 import { DEFAULT_TAB_GROUP_COLORS, TabGroupColorPalette, } from './tabGroupAccent';
-const DEFAULT_ROOT_OVERLAY_MODEL = {
-    activationSize: { type: 'pixels', value: 10 },
-    size: { type: 'pixels', value: 20 },
-};
 function buildTabGroupColorPalette(options) {
     var _a;
     const entries = (_a = options.tabGroupColors) !== null && _a !== void 0 ? _a : DEFAULT_TAB_GROUP_COLORS;
@@ -54,7 +50,51 @@ function moveGroupWithoutDestroying(options) {
         });
     });
 }
+let _hasWarnedUsingCoreDirectly = false;
+/**
+ * `dockview-core` is an internal package. The public `dockview` package calls
+ * `markDockviewPackageLoaded()` on import; if that marker is absent the consumer
+ * is using `dockview-core` directly, so emit a one-time console warning
+ * steering them to `dockview`.
+ *
+ * Suppressed in production builds: it is a development-time nudge and most
+ * bundlers inline `process.env.NODE_ENV` so the branch is dropped entirely. The
+ * `typeof process` guard keeps this safe in plain browser/UMD contexts where
+ * `process` is undefined.
+ */
+function warnIfUsingCoreDirectly() {
+    var _a;
+    if (typeof process !== 'undefined' &&
+        ((_a = process.env) === null || _a === void 0 ? void 0 : _a.NODE_ENV) === 'production') {
+        return;
+    }
+    if (_hasWarnedUsingCoreDirectly || isDockviewPackageLoaded()) {
+        return;
+    }
+    _hasWarnedUsingCoreDirectly = true;
+    console.warn('dockview: do not use "dockview-core" directly — it is an internal ' +
+        'package. Use the "dockview" package, the JavaScript version of ' +
+        'dockview, instead. This notice is shown once.');
+}
 export class DockviewComponent extends BaseGrid {
+    fireDidCreateTabGroup(event) {
+        this._onDidCreateTabGroup.fire(event);
+    }
+    fireDidDestroyTabGroup(event) {
+        this._onDidDestroyTabGroup.fire(event);
+    }
+    fireDidAddPanelToTabGroup(event) {
+        this._onDidAddPanelToTabGroup.fire(event);
+    }
+    fireDidRemovePanelFromTabGroup(event) {
+        this._onDidRemovePanelFromTabGroup.fire(event);
+    }
+    fireDidTabGroupChange(event) {
+        this._onDidTabGroupChange.fire(event);
+    }
+    fireDidTabGroupCollapsedChange(event) {
+        this._onDidTabGroupCollapsedChange.fire(event);
+    }
     get orientation() {
         return this.gridview.orientation;
     }
@@ -89,17 +129,210 @@ export class DockviewComponent extends BaseGrid {
         return this._api;
     }
     get floatingGroups() {
-        return this._floatingGroups;
+        var _a, _b, _c;
+        return ((_c = (_b = (_a = this._moduleRegistry) === null || _a === void 0 ? void 0 : _a.services.floatingGroupService) === null || _b === void 0 ? void 0 : _b.floatingGroups) !== null && _c !== void 0 ? _c : []);
+    }
+    /**
+     * Boxes of the floating groups other than `exclude`, in coordinates
+     * relative to the floating overlay container. Supplied to a
+     * `transformFloatingGroupDrag` callback as `context.others` so it can
+     * align the dragged float against its siblings.
+     */
+    _gatherFloatingGroupBoxes(exclude) {
+        var _a;
+        const container = (_a = this._floatingOverlayHost) !== null && _a !== void 0 ? _a : this.gridview.element;
+        const containerRect = container.getBoundingClientRect();
+        return this.floatingGroups
+            .filter((floating) => floating.group !== exclude)
+            .map((floating) => {
+            const rect = floating.overlay.element.getBoundingClientRect();
+            return {
+                left: rect.left - containerRect.left,
+                top: rect.top - containerRect.top,
+                width: rect.width,
+                height: rect.height,
+            };
+        });
+    }
+    get _floatingGroupService() {
+        return this._moduleRegistry.services.floatingGroupService;
+    }
+    get _popoutWindowService() {
+        return this._moduleRegistry.services.popoutWindowService;
+    }
+    get _watermarkService() {
+        // Tier 1 module — optional. Callers must `?.`-guard so the module
+        // can be removed from AllModules without crashing the component.
+        return this._moduleRegistry.services.watermarkService;
+    }
+    get _edgeGroupService() {
+        return this._moduleRegistry.services.edgeGroupService;
+    }
+    get _rootDropTargetService() {
+        // Optional like every other module service — RootDropTargetModule can be
+        // removed from the registered set without crashing the component.
+        return this._moduleRegistry.services.rootDropTargetService;
+    }
+    get _advancedDnDService() {
+        // Optional — callers `?.`-guard so the module can be removed from
+        // AllModules. Absent ⇒ the onWill* hooks simply don't fire (≡ no
+        // subscriber), which is invisible to apps not customising DnD.
+        return this._moduleRegistry.services.advancedDnDService;
+    }
+    get headerActionsService() {
+        return this._moduleRegistry.services.headerActionsService;
+    }
+    isGridEmpty() {
+        return this.gridview.length === 0;
+    }
+    rootDropTargetOverrideTarget() {
+        var _a;
+        return (_a = this.rootDropTargetContainer) === null || _a === void 0 ? void 0 : _a.model;
+    }
+    dispatchUnhandledDragOver(nativeEvent, position) {
+        const event = new DockviewUnhandledDragOverEvent(nativeEvent, 'edge', position, getPanelData);
+        this._onUnhandledDragOver.fire(event);
+        return event.isAccepted;
+    }
+    // IAdvancedDnDHost — the emitters stay here so the public onWill* event
+    // shape is unchanged; AdvancedDnDService routes the per-group fires
+    // through these. Engine guards (e.g. disableDnd) run on the component
+    // ahead of the dispatch.
+    fireWillDragPanel(event) {
+        this._onWillDragPanel.fire(event);
+    }
+    fireWillDragGroup(event) {
+        this._onWillDragGroup.fire(event);
+    }
+    fireWillDrop(event) {
+        this._onWillDrop.fire(event);
+    }
+    fireWillShowOverlay(event) {
+        this._onWillShowOverlay.fire(event);
+    }
+    /**
+     * Resolve the custom group drag ghost (via the AdvancedDnD module), or
+     * `undefined` to fall back to the default chip. Returns `undefined` when
+     * the module is absent — the default ghost then renders.
+     */
+    buildGroupDragGhost(group) {
+        var _a;
+        return (_a = this._advancedDnDService) === null || _a === void 0 ? void 0 : _a.buildGroupDragGhost(group);
+    }
+    /**
+     * Resolve the app-supplied drop overlay model (via the AdvancedDnD module)
+     * for a group drop target, or `undefined` to keep the target's default.
+     */
+    resolveDropOverlayModel(location, group) {
+        var _a;
+        return (_a = this._advancedDnDService) === null || _a === void 0 ? void 0 : _a.resolveOverlayModel(location, group);
+    }
+    // IAccessibilityHost — keyboard docking reaches the AdvancedDnD preview +
+    // LiveRegion announcer through these so the service stays decoupled.
+    /** Outermost element — the shell (incl. edge groups) once built, else the gridview. */
+    get rootElement() {
+        var _a, _b;
+        return (_b = (_a = this._shellManager) === null || _a === void 0 ? void 0 : _a.element) !== null && _b !== void 0 ? _b : this.element;
+    }
+    /**
+     * The next / previous group in gridview (spatial) order, wrapping round.
+     * The keyboard accessibility module's focus navigation is built on this
+     * primitive — the only piece that needs the grid internals; the rest of
+     * the navigation logic lives in the AccessibilityService.
+     */
+    adjacentGroup(group, reverse) {
+        var _a;
+        // gridview traversal only covers grid groups; a floating/popout group
+        // isn't in the grid, so there's no adjacent grid group to step to.
+        if (group.api.location.type !== 'grid') {
+            return undefined;
+        }
+        const location = getGridLocation(group.element);
+        return ((_a = (reverse
+            ? this.gridview.previous(location)
+            : this.gridview.next(location))) === null || _a === void 0 ? void 0 : _a.view);
+    }
+    /**
+     * The nearest grid group in a spatial direction from `group`, by
+     * comparing group centre points. Floating and popout groups sit outside
+     * the grid's geometry and are ignored. Returns `undefined` when there is
+     * no group in that direction.
+     */
+    adjacentGroupInDirection(group, direction) {
+        if (group.api.location.type !== 'grid') {
+            return undefined;
+        }
+        const from = group.element.getBoundingClientRect();
+        const fromX = from.left + from.width / 2;
+        const fromY = from.top + from.height / 2;
+        let best;
+        let bestDistance = Number.POSITIVE_INFINITY;
+        for (const candidate of this.groups) {
+            if (candidate === group || candidate.api.location.type !== 'grid') {
+                continue;
+            }
+            const rect = candidate.element.getBoundingClientRect();
+            const dx = rect.left + rect.width / 2 - fromX;
+            const dy = rect.top + rect.height / 2 - fromY;
+            // Require the candidate to sit predominantly in the asked-for
+            // direction (dominant axis), so 'left' ignores a group that's
+            // mostly above/below.
+            const inDirection = direction === 'left'
+                ? dx < 0 && Math.abs(dx) >= Math.abs(dy)
+                : direction === 'right'
+                    ? dx > 0 && Math.abs(dx) >= Math.abs(dy)
+                    : direction === 'up'
+                        ? dy < 0 && Math.abs(dy) >= Math.abs(dx)
+                        : dy > 0 && Math.abs(dy) >= Math.abs(dx);
+            if (!inDirection) {
+                continue;
+            }
+            const distance = dx * dx + dy * dy;
+            if (distance < bestDistance) {
+                bestDistance = distance;
+                best = candidate;
+            }
+        }
+        return best;
+    }
+    showDropPreview(group, position) {
+        var _a, _b;
+        return ((_b = (_a = this._advancedDnDService) === null || _a === void 0 ? void 0 : _a.showPreviewOverlay(group, position)) !== null && _b !== void 0 ? _b : Disposable.NONE);
+    }
+    announce(message) {
+        var _a;
+        (_a = this._moduleRegistry.services.liveRegionService) === null || _a === void 0 ? void 0 : _a.announce(message);
+    }
+    dockPanel(panel, group, position) {
+        this.moveGroupOrPanel({
+            from: { groupId: panel.group.id, panelId: panel.id },
+            to: { group, position },
+        });
+    }
+    get contextMenuService() {
+        // Owned by ContextMenuModule — undefined when the module is not
+        // registered, so callers must `?.`-guard.
+        return this._moduleRegistry.services.contextMenuService;
+    }
+    get mountElement() {
+        return this.gridview.element;
+    }
+    hasVisibleGridGroup() {
+        return this.groups.some((group) => group.api.location.type === 'grid' && group.api.isVisible);
+    }
+    fireLayoutChange() {
+        this._bufferOnDidLayoutChange.fire();
     }
     /**
      * Promise that resolves when all popout groups from the last fromJSON call are restored.
      * Useful for tests that need to wait for delayed popout creation.
      */
     get popoutRestorationPromise() {
-        return this._popoutRestorationPromise;
+        var _a, _b;
+        return ((_b = (_a = this._popoutWindowService) === null || _a === void 0 ? void 0 : _a.restorationPromise) !== null && _b !== void 0 ? _b : Promise.resolve());
     }
     constructor(container, options) {
-        var _a, _b, _c, _d, _e, _f, _g;
+        var _a, _b, _c, _d, _e;
         super(container, {
             proportionalLayout: true,
             orientation: Orientation.HORIZONTAL,
@@ -113,8 +346,7 @@ export class DockviewComponent extends BaseGrid {
         });
         this.nextGroupId = sequentialNumberGenerator();
         this._deserializer = new DefaultDockviewDeserialzier(this);
-        this._watermark = null;
-        this._popoutPopupServices = new Map();
+        this._moduleRegistry = new ModuleRegistry();
         this._onWillDragPanel = new Emitter();
         this.onWillDragPanel = this._onWillDragPanel.event;
         this._onWillDragGroup = new Emitter();
@@ -123,10 +355,25 @@ export class DockviewComponent extends BaseGrid {
         this.onDidDrop = this._onDidDrop.event;
         this._onWillDrop = new Emitter();
         this.onWillDrop = this._onWillDrop.event;
+        // Transaction boundary bracketing each top-level structural mutation.
+        // Compound operations (e.g. a drag that relocates a panel) nest via the
+        // depth counter and bracket as a single transaction. See `mutation()`.
+        this._mutationDepth = 0;
+        // Current operation origin. Defaults to `'user'`; the DockviewApi boundary
+        // flips it to `'api'` for the duration of a programmatic call via
+        // `withOrigin`. Nested operations inherit the outermost origin (tracked by
+        // `_originDepth`, independent of mutation bracketing so it also covers
+        // active-panel changes that are not structural mutations).
+        this._origin = 'user';
+        this._originDepth = 0;
+        this._onWillMutateLayout = new Emitter();
+        this.onWillMutateLayout = this._onWillMutateLayout.event;
+        this._onDidMutateLayout = new Emitter();
+        this.onDidMutateLayout = this._onDidMutateLayout.event;
         this._onWillShowOverlay = new Emitter();
         this.onWillShowOverlay = this._onWillShowOverlay.event;
-        this._onUnhandledDragOverEvent = new Emitter();
-        this.onUnhandledDragOverEvent = this._onUnhandledDragOverEvent.event;
+        this._onUnhandledDragOver = new Emitter();
+        this.onUnhandledDragOver = this._onUnhandledDragOver.event;
         this._onDidRemovePanel = new Emitter();
         this.onDidRemovePanel = this._onDidRemovePanel.event;
         this._onDidAddPanel = new Emitter();
@@ -135,6 +382,10 @@ export class DockviewComponent extends BaseGrid {
         this.onDidPopoutGroupSizeChange = this._onDidPopoutGroupSizeChange.event;
         this._onDidPopoutGroupPositionChange = new Emitter();
         this.onDidPopoutGroupPositionChange = this._onDidPopoutGroupPositionChange.event;
+        this._onDidAddPopoutGroup = new Emitter();
+        this.onDidAddPopoutGroup = this._onDidAddPopoutGroup.event;
+        this._onDidRemovePopoutGroup = new Emitter();
+        this.onDidRemovePopoutGroup = this._onDidRemovePopoutGroup.event;
         this._onDidOpenPopoutWindowFail = new Emitter();
         this.onDidOpenPopoutWindowFail = this._onDidOpenPopoutWindowFail.event;
         this._onDidLayoutFromJSON = new Emitter();
@@ -158,12 +409,6 @@ export class DockviewComponent extends BaseGrid {
         this._onDidMaximizedGroupChange = new Emitter();
         this.onDidMaximizedGroupChange = this._onDidMaximizedGroupChange.event;
         this._inShellLayout = false;
-        this._edgeGroups = new Map();
-        this._edgeGroupDisposables = new Map();
-        this._floatingGroups = [];
-        this._popoutGroups = [];
-        this._popoutRestorationPromise = Promise.resolve();
-        this._popoutRestorationCleanups = new Set();
         this._onDidRemoveGroup = new Emitter();
         this.onDidRemoveGroup = this._onDidRemoveGroup.event;
         this._onDidAddGroup = new Emitter();
@@ -175,13 +420,43 @@ export class DockviewComponent extends BaseGrid {
         this._moving = false;
         this._options = options;
         this._tabGroupColorPalette = buildTabGroupColorPalette(options);
+        // Internal seam: defaults to the full set, but tests can supply a
+        // subset to assert every module is independently removable (and the
+        // opt-in module API will build on this later). Not part of the public
+        // options surface.
+        const explicitModules = options
+            .modules;
+        const modules = explicitModules !== null && explicitModules !== void 0 ? explicitModules : [
+            ...AllModules,
+            ...getRegisteredModules(),
+        ];
+        for (const module of modules) {
+            this._moduleRegistry.register(module);
+        }
+        this._moduleRegistry.initialize(this);
+        // Surface popout removal symmetrically with `onDidAddPopoutGroup`. The
+        // service is the single point every removal path funnels through — a
+        // genuine window close and an explicit removal alike — and it suppresses
+        // the event during component teardown.
+        const popoutWindowService = this._popoutWindowService;
+        if (popoutWindowService) {
+            this.addDisposables(popoutWindowService.onDidRemove((entry) => {
+                this._onDidRemovePopoutGroup.fire({
+                    id: entry.popoutGroup.id,
+                    group: entry.popoutGroup,
+                    window: entry.getWindow(),
+                });
+            }));
+        }
+        // Purely a developer warning (no functional effect): nudge anyone using
+        // the internal `dockview-core` package directly towards `dockview`.
+        warnIfUsingCoreDirectly();
         this.popupService = new PopupService(this.element);
-        this.contextMenuController = new ContextMenuController(this);
         this._api = new DockviewApi(this);
         // The shell always wraps the dockview element so edge groups can be
         // added at any time via addEdgeGroup() without re-parenting the DOM.
         this.disableResizing = true;
-        container.removeChild(this.element);
+        this.element.remove();
         this._shellManager = new ShellManager(container, this.element, (w, h) => this._layoutFromShell(w, h), (_d = (_c = options.theme) === null || _c === void 0 ? void 0 : _c.gap) !== null && _d !== void 0 ? _d : 0, (_e = options.theme) === null || _e === void 0 ? void 0 : _e.edgeGroupCollapsedSize);
         // The shell wraps the dockview element, so move the popup anchor
         // into the shell so overflow dropdowns in edge groups position correctly
@@ -198,69 +473,23 @@ export class DockviewComponent extends BaseGrid {
         this._floatingOverlayHost = document.createElement('div');
         this._floatingOverlayHost.className = 'dv-floating-overlay-host';
         this._shellManager.element.appendChild(this._floatingOverlayHost);
-        const rootCanDisplayOverlay = (event, position) => {
-            const data = getPanelData();
-            if (data) {
-                if (data.viewId !== this.id) {
-                    return false;
-                }
-                if (position === 'center') {
-                    // center drop target is only allowed if there are no panels in the grid
-                    // floating panels are allowed
-                    return this.gridview.length === 0;
-                }
-                return true;
-            }
-            if (position === 'center' && this.gridview.length !== 0) {
-                /**
-                 * for external events only show the four-corner drag overlays, disable
-                 * the center position so that external drag events can fall through to the group
-                 * and panel drop target handlers
-                 */
-                return false;
-            }
-            const firedEvent = new DockviewUnhandledDragOverEvent(event, 'edge', position, getPanelData);
-            this._onUnhandledDragOverEvent.fire(firedEvent);
-            return firedEvent.isAccepted;
-        };
-        this._rootDropTarget = html5Backend.createDropTarget(this.element, {
-            className: 'dv-drop-target-edge',
-            canDisplayOverlay: rootCanDisplayOverlay,
-            acceptedTargetZones: ['top', 'bottom', 'left', 'right', 'center'],
-            overlayModel: (_f = options.rootOverlayModel) !== null && _f !== void 0 ? _f : DEFAULT_ROOT_OVERLAY_MODEL,
-            getOverrideTarget: () => { var _a; return (_a = this.rootDropTargetContainer) === null || _a === void 0 ? void 0 : _a.model; },
-        });
-        this._rootPointerDropTarget = pointerBackend.createDropTarget(this.element, {
-            className: 'dv-drop-target-edge',
-            canDisplayOverlay: rootCanDisplayOverlay,
-            acceptedTargetZones: [
-                'top',
-                'bottom',
-                'left',
-                'right',
-                'center',
-            ],
-            overlayModel: (_g = options.rootOverlayModel) !== null && _g !== void 0 ? _g : DEFAULT_ROOT_OVERLAY_MODEL,
-            getOverrideTarget: () => { var _a; return (_a = this.rootDropTargetContainer) === null || _a === void 0 ? void 0 : _a.model; },
-        });
-        this.updateDropTargetModel(options);
         toggleClass(this.gridview.element, 'dv-dockview', true);
         toggleClass(this.element, 'dv-debug', !!options.debug);
         this.updateTheme();
-        this.updateWatermark();
         if (options.debug) {
             this.addDisposables(new StrictEventsSequencing(this));
         }
-        this.addDisposables(this.rootDropTargetContainer, this.overlayRenderContainer, this._onWillDragPanel, this._onWillDragGroup, this._onWillShowOverlay, this._onDidActivePanelChange, this._onDidAddPanel, this._onDidRemovePanel, this._onDidLayoutFromJSON, this._onDidDrop, this._onWillDrop, this._onDidMovePanel, this._onDidMovePanel.event(() => {
+        this.addDisposables(this.rootDropTargetContainer, this.overlayRenderContainer, this._onWillDragPanel, this._onWillDragGroup, this._onWillShowOverlay, this._onDidActivePanelChange, this._onDidAddPanel, this._onDidRemovePanel, this._onDidLayoutFromJSON, this._onDidDrop, this._onWillDrop, this._onWillMutateLayout, this._onDidMutateLayout, this._onDidMovePanel, this._onDidMovePanel.event(() => {
             /**
              * Update overlay positions after DOM layout completes to prevent 0×0 dimensions.
              * With defaultRenderer="always" this results in panel content not showing after move operations.
              * Debounced to avoid multiple calls when moving groups with multiple panels.
              */
             this.debouncedUpdateAllPositions();
-        }), this._onDidAddGroup, this._onDidRemoveGroup, this._onDidActiveGroupChange, this._onUnhandledDragOverEvent, this._onDidMaximizedGroupChange, this._onDidOptionsChange, this._onDidPopoutGroupSizeChange, this._onDidPopoutGroupPositionChange, this._onDidOpenPopoutWindowFail, this._onDidCreateTabGroup, this._onDidDestroyTabGroup, this._onDidAddPanelToTabGroup, this._onDidRemovePanelFromTabGroup, this._onDidTabGroupChange, this._onDidTabGroupCollapsedChange, this.onDidViewVisibilityChangeMicroTaskQueue(() => {
-            this.updateWatermark();
-        }), this.onDidAdd((event) => {
+        }), this._onDidAddGroup, this._onDidRemoveGroup, this._onDidActiveGroupChange, this._onUnhandledDragOver, this._onDidMaximizedGroupChange, this._onDidPopoutGroupSizeChange, this._onDidPopoutGroupPositionChange, this._onDidAddPopoutGroup, this._onDidRemovePopoutGroup, this._onDidOpenPopoutWindowFail, this._onDidCreateTabGroup, this._onDidDestroyTabGroup, this._onDidAddPanelToTabGroup, this._onDidRemovePanelFromTabGroup, this._onDidTabGroupChange, this._onDidTabGroupCollapsedChange, Event.any(this.onDidPopoutGroupSizeChange, this.onDidPopoutGroupPositionChange, this.onDidCreateTabGroup, this.onDidDestroyTabGroup, this.onDidAddPanelToTabGroup, this.onDidRemovePanelFromTabGroup, this.onDidTabGroupChange, this.onDidTabGroupCollapsedChange)(() => {
+            // Popout size/position and tab-group mutations persist as layout changes.
+            this.fireLayoutChange();
+        }), this._onDidOptionsChange, this.onDidAdd((event) => {
             if (!this._moving) {
                 this._onDidAddGroup.fire(event);
             }
@@ -277,84 +506,80 @@ export class DockviewComponent extends BaseGrid {
                 group: event.panel,
                 isMaximized: event.isMaximized,
             });
-        }), Event.any(this.onDidAdd, this.onDidRemove)(() => {
-            this.updateWatermark();
-        }), Event.any(this.onDidAddPanel, this.onDidRemovePanel, this.onDidAddGroup, this.onDidRemove, this.onDidRemoveGroup, this.onDidMovePanel, this.onDidActivePanelChange, this.onDidPopoutGroupPositionChange, this.onDidPopoutGroupSizeChange, this.onDidCreateTabGroup, this.onDidDestroyTabGroup, this.onDidAddPanelToTabGroup, this.onDidRemovePanelFromTabGroup, this.onDidTabGroupChange, this.onDidTabGroupCollapsedChange)(() => {
+        }), Event.any(this.onDidAddPanel, this.onDidRemovePanel, this.onDidAddGroup, this.onDidRemove, this.onDidRemoveGroup, this.onDidMovePanel, this.onDidActivePanelChange)(() => {
             this._bufferOnDidLayoutChange.fire();
         }), Disposable.from(() => {
             var _a;
-            // Cancel any pending popout-restoration timers scheduled by
-            // fromJSON so they don't open new browser windows after
-            // dispose, and resolve their promises so callers awaiting
-            // popoutRestorationPromise don't hang. See issue #851.
-            for (const cleanup of [...this._popoutRestorationCleanups]) {
-                cleanup();
-            }
-            this._popoutRestorationCleanups.clear();
-            // iterate over a copy of the array since .dispose() mutates the original array
-            for (const group of [...this._floatingGroups]) {
-                group.dispose();
-            }
-            // iterate over a copy of the array since .dispose() mutates the original array
-            for (const group of [...this._popoutGroups]) {
-                group.disposable.dispose();
-            }
+            // Registry disposes init() subscriptions then every module
+            // service that implements IDisposable. The order matters so
+            // init handlers stop firing into services about to be torn
+            // down. Includes popout-restoration timer cancellation that
+            // resolves promises so awaiters of popoutRestorationPromise
+            // don't hang. See issue #851.
+            this._moduleRegistry.dispose();
             (_a = this._shellManager) === null || _a === void 0 ? void 0 : _a.dispose();
-            for (const d of this._edgeGroupDisposables.values()) {
-                d.dispose();
-            }
-            this._edgeGroupDisposables.clear();
-        }), this._rootDropTarget, this._rootPointerDropTarget, Event.any(this._rootDropTarget.onWillShowOverlay, this._rootPointerDropTarget.onWillShowOverlay)((event) => {
-            if (this.gridview.length > 0 && event.position === 'center') {
-                // option only available when no panels in primary grid
-                return;
-            }
-            this._onWillShowOverlay.fire(new DockviewWillShowOverlayLocationEvent(event, {
-                kind: 'edge',
-                panel: undefined,
-                api: this._api,
-                group: undefined,
-                getData: getPanelData,
-            }));
-        }), Event.any(this._rootDropTarget.onDrop, this._rootPointerDropTarget.onDrop)((event) => {
-            var _a;
-            const willDropEvent = new DockviewWillDropEvent({
-                nativeEvent: event.nativeEvent,
-                position: event.position,
-                panel: undefined,
-                api: this._api,
-                group: undefined,
-                getData: getPanelData,
-                kind: 'edge',
-            });
-            this._onWillDrop.fire(willDropEvent);
-            if (willDropEvent.defaultPrevented) {
-                return;
-            }
-            const data = getPanelData();
-            if (data) {
-                this.moveGroupOrPanel({
-                    from: {
-                        groupId: data.groupId,
-                        panelId: (_a = data.panelId) !== null && _a !== void 0 ? _a : undefined,
-                    },
-                    to: {
-                        group: this.orthogonalize(event.position),
-                        position: 'center',
-                    },
-                });
-            }
-            else {
-                this._onDidDrop.fire(new DockviewDidDropEvent({
+        }));
+        // Root edge-drop wiring lives with its (optional) module — guard it so
+        // the module is independently removable.
+        const rootDropTarget = this._rootDropTargetService;
+        if (rootDropTarget) {
+            this.addDisposables(rootDropTarget.onWillShowOverlay((event) => {
+                if (this.gridview.length > 0 &&
+                    event.position === 'center') {
+                    // option only available when no panels in primary grid
+                    return;
+                }
+                this._onWillShowOverlay.fire(new DockviewWillShowOverlayLocationEvent(event, {
+                    kind: 'edge',
+                    panel: undefined,
+                    api: this._api,
+                    group: undefined,
+                    getData: getPanelData,
+                }));
+            }), rootDropTarget.onDrop((event) => {
+                var _a;
+                const willDropEvent = new DockviewWillDropEvent({
                     nativeEvent: event.nativeEvent,
                     position: event.position,
                     panel: undefined,
                     api: this._api,
                     group: undefined,
                     getData: getPanelData,
-                }));
-            }
-        }));
+                    kind: 'edge',
+                });
+                this._onWillDrop.fire(willDropEvent);
+                if (willDropEvent.defaultPrevented) {
+                    return;
+                }
+                const data = getPanelData();
+                if (data) {
+                    this.moveGroupOrPanel({
+                        from: {
+                            groupId: data.groupId,
+                            panelId: (_a = data.panelId) !== null && _a !== void 0 ? _a : undefined,
+                        },
+                        to: {
+                            group: this.orthogonalize(event.position),
+                            position: 'center',
+                        },
+                    });
+                }
+                else {
+                    this._onDidDrop.fire(new DockviewDidDropEvent({
+                        nativeEvent: event.nativeEvent,
+                        position: event.position,
+                        panel: undefined,
+                        api: this._api,
+                        group: undefined,
+                        getData: getPanelData,
+                    }));
+                }
+            }));
+        }
+        // Final module wiring: runs after the host is fully constructed.
+        // Modules subscribe to host events here so the component doesn't
+        // need to manually invoke them at scattered call sites.
+        this._moduleRegistry.postConstruct(this);
     }
     setVisible(panel, visible) {
         switch (panel.api.location.type) {
@@ -386,11 +611,29 @@ export class DockviewComponent extends BaseGrid {
      * and dismisses on events from that window.
      */
     getPopupServiceForGroup(group) {
-        var _a;
-        return (_a = this._popoutPopupServices.get(group.id)) !== null && _a !== void 0 ? _a : this.popupService;
+        var _a, _b;
+        return ((_b = (_a = this._popoutWindowService) === null || _a === void 0 ? void 0 : _a.getPopupService(group.id)) !== null && _b !== void 0 ? _b : this.popupService);
     }
     addPopoutGroup(itemToPopout, options) {
-        var _a, _b, _c, _d, _e, _f;
+        // The transaction brackets the synchronous structural change; the
+        // popout window opens asynchronously after it resolves.
+        return this.mutation('popout', () => this._doAddPopoutGroup(itemToPopout, options));
+    }
+    /** Enumerate the popout groups currently open in their own windows. */
+    getPopouts() {
+        var _a, _b;
+        return ((_b = (_a = this._popoutWindowService) === null || _a === void 0 ? void 0 : _a.entries.map((entry) => ({
+            id: entry.popoutGroup.id,
+            group: entry.popoutGroup,
+            window: entry.getWindow(),
+        }))) !== null && _b !== void 0 ? _b : []);
+    }
+    _doAddPopoutGroup(itemToPopout, options) {
+        var _a, _b, _c, _d, _e;
+        const service = assertModule(this._popoutWindowService, 'PopoutWindow', 'api.addPopoutGroup');
+        if (!service) {
+            return Promise.resolve(false);
+        }
         if (itemToPopout instanceof DockviewGroupPanel &&
             itemToPopout.model.location.type === 'edge') {
             // edge groups are permanent structural elements and cannot be popped out
@@ -416,16 +659,21 @@ export class DockviewComponent extends BaseGrid {
         }
         const box = getBox();
         const groupId = (_b = (_a = options === null || options === void 0 ? void 0 : options.overridePopoutGroup) === null || _a === void 0 ? void 0 : _a.id) !== null && _b !== void 0 ? _b : this.getNextGroupId();
+        // Resolve the configured popout URL once (per-call override → global
+        // option). Recorded on the entry / group locations so it survives
+        // serialization; the '/popout.html' default is applied only when
+        // actually opening the window, not baked into saved layouts.
+        const resolvedPopoutUrl = (_c = options === null || options === void 0 ? void 0 : options.popoutUrl) !== null && _c !== void 0 ? _c : (_d = this.options) === null || _d === void 0 ? void 0 : _d.popoutUrl;
         const _window = new PopoutWindow(`${this.id}-${groupId}`, // unique id
         theme !== null && theme !== void 0 ? theme : '', {
-            url: (_e = (_c = options === null || options === void 0 ? void 0 : options.popoutUrl) !== null && _c !== void 0 ? _c : (_d = this.options) === null || _d === void 0 ? void 0 : _d.popoutUrl) !== null && _e !== void 0 ? _e : '/popout.html',
+            url: resolvedPopoutUrl !== null && resolvedPopoutUrl !== void 0 ? resolvedPopoutUrl : '/popout.html',
             left: window.screenX + box.left,
             top: window.screenY + box.top,
             width: box.width,
             height: box.height,
             onDidOpen: options === null || options === void 0 ? void 0 : options.onDidOpen,
             onWillClose: options === null || options === void 0 ? void 0 : options.onWillClose,
-            nonce: (_f = this.options) === null || _f === void 0 ? void 0 : _f.nonce,
+            nonce: (_e = this.options) === null || _e === void 0 ? void 0 : _e.nonce,
         });
         const popoutWindowDisposable = new CompositeDisposable(_window, _window.onDidClose(() => {
             popoutWindowDisposable.dispose();
@@ -433,15 +681,13 @@ export class DockviewComponent extends BaseGrid {
         return _window
             .open()
             .then((popoutContainer) => {
-            var _a;
+            var _a, _b, _c, _d;
             if (_window.isDisposed) {
                 return false;
             }
-            const referenceGroup = (options === null || options === void 0 ? void 0 : options.referenceGroup)
-                ? options.referenceGroup
-                : itemToPopout instanceof DockviewPanel
-                    ? itemToPopout.group
-                    : itemToPopout;
+            const referenceGroup = (_a = options === null || options === void 0 ? void 0 : options.referenceGroup) !== null && _a !== void 0 ? _a : (itemToPopout instanceof DockviewPanel
+                ? itemToPopout.group
+                : itemToPopout);
             const referenceLocation = itemToPopout.api.location.type;
             /**
              * The group that is being added doesn't already exist within the DOM, the most likely occurrence
@@ -449,7 +695,12 @@ export class DockviewComponent extends BaseGrid {
              */
             const isGroupAddedToDom = referenceGroup.element.parentElement !== null;
             let group;
-            if (!isGroupAddedToDom) {
+            if (options === null || options === void 0 ? void 0 : options.overridePopoutGridview) {
+                // Restoring a multi-group window: the anchor group is
+                // already built inside the supplied gridview.
+                group = (_b = options.overridePopoutGroup) !== null && _b !== void 0 ? _b : referenceGroup;
+            }
+            else if (!isGroupAddedToDom) {
                 group = referenceGroup;
             }
             else if (options === null || options === void 0 ? void 0 : options.overridePopoutGroup) {
@@ -462,27 +713,46 @@ export class DockviewComponent extends BaseGrid {
                 }
             }
             if (popoutContainer === null) {
-                console.error('dockview: failed to create popout. perhaps you need to allow pop-ups for this website');
-                popoutWindowDisposable.dispose();
-                this._onDidOpenPopoutWindowFail.fire();
-                // if the popout window was blocked, we need to move the group back to the reference group
-                // and set it to visible
-                this.movingLock(() => moveGroupWithoutDestroying({
-                    from: group,
-                    to: referenceGroup,
-                }));
-                if (!referenceGroup.api.isVisible) {
-                    referenceGroup.api.setVisible(true);
-                }
+                this.handleBlockedPopout({
+                    group,
+                    referenceGroup,
+                    options,
+                    popoutWindowDisposable,
+                });
                 return false;
             }
             const gready = document.createElement('div');
             gready.className = 'dv-overlay-render-container';
             const overlayRenderContainer = new OverlayRenderContainer(gready, this);
             group.model.renderContainer = overlayRenderContainer;
-            group.layout(_window.window.innerWidth, _window.window.innerHeight);
+            // The popout window hosts its own gridview so it can grow into
+            // a nested splitview layout. The window starts with the single
+            // anchor group; further groups arrive via drag-and-drop. On
+            // restore a pre-populated gridview is supplied instead.
+            const popoutGridview = (_c = options === null || options === void 0 ? void 0 : options.overridePopoutGridview) !== null && _c !== void 0 ? _c : this.createNestedGridview();
+            if (!(options === null || options === void 0 ? void 0 : options.overridePopoutGridview)) {
+                popoutGridview.addView(group, Sizing.Distribute, [0]);
+            }
+            // Fill the popout window. Unlike the main grid (explicit px) and
+            // floating windows (CSS inside .dv-resize-container), the popout
+            // gridview has no sizing context, so without this it collapses
+            // to 0 height and nothing renders.
+            popoutGridview.element.style.width = '100%';
+            popoutGridview.element.style.height = '100%';
+            popoutGridview.layout(_window.window.innerWidth, _window.window.innerHeight);
+            // Guarded so the teardown's re-entrant paths (window close
+            // re-enters via the anchor's doRemoveGroup) never double-dispose.
+            let popoutGridviewDisposed = false;
+            const disposePopoutGridview = () => {
+                if (!popoutGridviewDisposed) {
+                    popoutGridviewDisposed = true;
+                    popoutGridview.dispose();
+                }
+            };
             let floatingBox;
-            if (!(options === null || options === void 0 ? void 0 : options.overridePopoutGroup) && isGroupAddedToDom) {
+            if (!(options === null || options === void 0 ? void 0 : options.overridePopoutGroup) &&
+                !(options === null || options === void 0 ? void 0 : options.overridePopoutGridview) &&
+                isGroupAddedToDom) {
                 if (itemToPopout instanceof DockviewPanel) {
                     this.movingLock(() => {
                         const panel = referenceGroup.model.removePanel(itemToPopout);
@@ -500,9 +770,9 @@ export class DockviewComponent extends BaseGrid {
                             break;
                         case 'floating':
                         case 'popout':
-                            floatingBox = (_a = this._floatingGroups
+                            floatingBox = (_d = this.floatingGroups
                                 .find((value) => value.group.api.id ===
-                                itemToPopout.api.id)) === null || _a === void 0 ? void 0 : _a.overlay.toJSON();
+                                itemToPopout.api.id)) === null || _d === void 0 ? void 0 : _d.overlay.toJSON();
                             this.removeGroup(referenceGroup);
                             break;
                     }
@@ -511,7 +781,7 @@ export class DockviewComponent extends BaseGrid {
             popoutContainer.classList.add('dv-dockview');
             popoutContainer.style.overflow = 'hidden';
             popoutContainer.appendChild(gready);
-            popoutContainer.appendChild(group.element);
+            popoutContainer.appendChild(popoutGridview.element);
             const anchor = document.createElement('div');
             const dropTargetContainer = new DropTargetAnchorContainer(anchor, { disabled: this.rootDropTargetContainer.disabled });
             popoutContainer.appendChild(anchor);
@@ -522,20 +792,42 @@ export class DockviewComponent extends BaseGrid {
             // their pointerdown/keydown listeners fire on the right
             // window for outside-click and Escape dismissal.
             const popoutPopupService = new PopupService(popoutContainer, _window.window);
-            this._popoutPopupServices.set(group.id, popoutPopupService);
+            service.setPopupService(group.id, popoutPopupService);
             popoutWindowDisposable.addDisposables(popoutPopupService, Disposable.from(() => {
-                this._popoutPopupServices.delete(group.id);
+                service.deletePopupService(group.id);
             }));
             group.model.location = {
                 type: 'popout',
                 getWindow: () => _window.window,
-                popoutUrl: options === null || options === void 0 ? void 0 : options.popoutUrl,
+                popoutUrl: resolvedPopoutUrl,
             };
+            if (options === null || options === void 0 ? void 0 : options.overridePopoutGridview) {
+                // Restored multi-group window. Wire every member (including
+                // the anchor) to this window's containers and popout
+                // location now that the gridview is attached and laid out —
+                // re-setting renderContainer forces a re-render at the right
+                // time so 'always'-rendered content positions in this
+                // window rather than where it was first created.
+                const members = this.groups.filter((candidate) => popoutGridview.element.contains(candidate.element));
+                for (const member of members) {
+                    member.model.renderContainer = overlayRenderContainer;
+                    member.model.dropTargetContainer = dropTargetContainer;
+                    member.model.location = {
+                        type: 'popout',
+                        getWindow: () => _window.window,
+                        popoutUrl: resolvedPopoutUrl,
+                    };
+                }
+            }
             if (isGroupAddedToDom &&
                 itemToPopout.api.location.type === 'grid') {
                 itemToPopout.api.setVisible(false);
             }
             this.doSetGroupAndPanelActive(group);
+            const resizeObserverDisposable = service.observeGridviewSize(_window, popoutGridview, overlayRenderContainer);
+            if (resizeObserverDisposable) {
+                popoutWindowDisposable.addDisposables(resizeObserverDisposable);
+            }
             popoutWindowDisposable.addDisposables(group.api.onDidActiveChange((event) => {
                 var _a;
                 if (event.isActive) {
@@ -545,20 +837,28 @@ export class DockviewComponent extends BaseGrid {
                 var _a;
                 (_a = _window.window) === null || _a === void 0 ? void 0 : _a.focus();
             }));
-            let returnedGroup;
+            // Holder so the close teardown (extracted below) can publish
+            // the group that was returned to the main grid back to the
+            // entry's `dispose()` contract.
+            const closeResult = {};
             const isValidReferenceGroup = isGroupAddedToDom &&
                 referenceGroup &&
                 this.getPanel(referenceGroup.id);
             const value = {
                 window: _window,
                 popoutGroup: group,
+                gridview: popoutGridview,
+                overlayRenderContainer,
+                dropTargetContainer,
+                getWindow: () => _window.window,
+                popoutUrl: resolvedPopoutUrl,
                 referenceGroup: isValidReferenceGroup
                     ? referenceGroup.id
                     : undefined,
                 disposable: {
                     dispose: () => {
                         popoutWindowDisposable.dispose();
-                        return returnedGroup;
+                        return closeResult.returnedGroup;
                     },
                 },
             };
@@ -575,73 +875,23 @@ export class DockviewComponent extends BaseGrid {
                     screenY: _window.window.screenX,
                     group,
                 });
-            }), 
-            /**
-             * ResizeObserver seems slow here, I do not know why but we don't need it
-             * since we can reply on the window resize event as we will occupy the full
-             * window dimensions
-             */
-            addDisposableListener(_window.window, 'resize', () => {
-                group.layout(_window.window.innerWidth, _window.window.innerHeight);
-            }), overlayRenderContainer, Disposable.from(() => {
-                if (this.isDisposed) {
-                    return; // cleanup may run after instance is disposed
-                }
-                if (isGroupAddedToDom &&
-                    this.getPanel(referenceGroup.id)) {
-                    this.movingLock(() => moveGroupWithoutDestroying({
-                        from: group,
-                        to: referenceGroup,
-                    }));
-                    if (!referenceGroup.api.isVisible) {
-                        referenceGroup.api.setVisible(true);
-                    }
-                    if (this.getPanel(group.id)) {
-                        this.doRemoveGroup(group, {
-                            skipPopoutAssociated: true,
-                        });
-                    }
-                }
-                else if (this.getPanel(group.id)) {
-                    group.model.renderContainer =
-                        this.overlayRenderContainer;
-                    group.model.dropTargetContainer =
-                        this.rootDropTargetContainer;
-                    returnedGroup = group;
-                    const alreadyRemoved = !this._popoutGroups.find((p) => p.popoutGroup === group);
-                    if (alreadyRemoved) {
-                        /**
-                         * If this popout group was explicitly removed then we shouldn't run the additional
-                         * steps. To tell if the running of this disposable is the result of this popout group
-                         * being explicitly removed we can check if this popout group is still referenced in
-                         * the `this._popoutGroups` list.
-                         */
-                        return;
-                    }
-                    if (floatingBox) {
-                        this.addFloatingGroup(group, {
-                            height: floatingBox.height,
-                            width: floatingBox.width,
-                            position: floatingBox,
-                        });
-                    }
-                    else {
-                        this.doRemoveGroup(group, {
-                            skipDispose: true,
-                            skipActive: true,
-                            skipPopoutReturn: true,
-                        });
-                        group.model.location = { type: 'grid' };
-                        this.movingLock(() => {
-                            // suppress group add events since the group already exists
-                            this.doAddGroup(group, [0]);
-                        });
-                    }
-                    this.doSetGroupAndPanelActive(group);
-                }
-            }));
-            this._popoutGroups.push(value);
-            this.updateWatermark();
+            }), addDisposableListener(_window.window, 'resize', () => {
+                popoutGridview.layout(_window.window.innerWidth, _window.window.innerHeight);
+            }), overlayRenderContainer, Disposable.from(() => this.disposePopoutWindow({
+                group,
+                referenceGroup,
+                popoutGridview,
+                isGroupAddedToDom,
+                floatingBox,
+                disposePopoutGridview,
+                closeResult,
+            })));
+            service.add(value);
+            this._onDidAddPopoutGroup.fire({
+                id: value.popoutGroup.id,
+                group: value.popoutGroup,
+                window: value.getWindow(),
+            });
             return true;
         })
             .catch((err) => {
@@ -649,8 +899,189 @@ export class DockviewComponent extends BaseGrid {
             return false;
         });
     }
+    /**
+     * The popout window was blocked (e.g. by the browser's popup blocker —
+     * common when restoring popouts on load). Fall back gracefully so the
+     * group(s) end up valid and visible in the main grid rather than as
+     * orphans that later crash clear()/remove().
+     */
+    handleBlockedPopout(params) {
+        const { group, referenceGroup, options, popoutWindowDisposable } = params;
+        console.error('dockview: failed to create popout. perhaps you need to allow pop-ups for this website');
+        popoutWindowDisposable.dispose();
+        this._onDidOpenPopoutWindowFail.fire();
+        if (options === null || options === void 0 ? void 0 : options.overridePopoutGridview) {
+            // Restoring a multi-group popout window: its nested gridview was
+            // built up-front but never attached to a window. Dock every member
+            // into the main grid so no group is lost, then discard the
+            // detached gridview.
+            const blockedGridview = options.overridePopoutGridview;
+            const members = this.groups.filter((candidate) => blockedGridview.element.contains(candidate.element));
+            for (const member of members) {
+                this.movingLock(() => {
+                    blockedGridview.remove(member);
+                    this.redockGroupToMainGrid(member);
+                });
+            }
+            blockedGridview.dispose();
+            if (referenceGroup && !referenceGroup.api.isVisible) {
+                referenceGroup.api.setVisible(true);
+            }
+            return;
+        }
+        if (group === referenceGroup) {
+            // No separate grid group to return to (e.g. restoring a popout
+            // straight from JSON) — dock this group into the main grid.
+            if (!this.gridview.element.contains(group.element)) {
+                this.movingLock(() => this.doAddGroup(group, [0]));
+                group.model.location = { type: 'grid' };
+            }
+        }
+        else {
+            // A fresh group was created for the popout — return its panels to
+            // the reference group and discard the now-empty popout group so it
+            // doesn't linger as an orphan.
+            this.movingLock(() => moveGroupWithoutDestroying({
+                from: group,
+                to: referenceGroup,
+            }));
+            if (group.model.size === 0 && this._groups.has(group.id)) {
+                group.dispose();
+                this._groups.delete(group.id);
+                this._onDidRemoveGroup.fire(group);
+            }
+        }
+        if (!referenceGroup.api.isVisible) {
+            referenceGroup.api.setVisible(true);
+        }
+    }
+    /**
+     * Wire a group that has been displaced from a floating / popout window back
+     * to the main grid's render & drop-target containers and dock it at the
+     * root. The caller is responsible for first detaching it from its old
+     * gridview — the detach strategy differs between the window-teardown path
+     * (`doRemoveGroup`) and the blocked-window path (`gridview.remove`).
+     */
+    redockGroupToMainGrid(group) {
+        group.model.renderContainer = this.overlayRenderContainer;
+        group.model.dropTargetContainer = this.rootDropTargetContainer;
+        group.model.location = { type: 'grid' };
+        this.doAddGroup(group, [0]);
+    }
+    /**
+     * Teardown for a popout window's `popoutWindowDisposable`. Runs when the
+     * window closes (by user, by `removeGroup`, or by component disposal):
+     * relocates every member group back to the main grid (or to a floating
+     * window when the anchor came from one), then disposes the nested gridview.
+     * `closeResult.returnedGroup` is read by the entry's `dispose()` contract.
+     */
+    disposePopoutWindow(params) {
+        var _a;
+        const { group, referenceGroup, popoutGridview, isGroupAddedToDom, floatingBox, disposePopoutGridview, closeResult, } = params;
+        if (this.isDisposed) {
+            // cleanup may run after instance is disposed; just tear down the
+            // nested gridview.
+            disposePopoutGridview();
+            return;
+        }
+        // Distinguish a genuine window close from an explicit `removeGroup`:
+        // the explicit-removal paths remove the service entry *before* this
+        // disposable runs. Key off the stable `popoutGridview` rather than the
+        // captured `group`, which may no longer be the window's anchor (it can
+        // have been dragged out, promoting another member to anchor).
+        const genuineClose = !!((_a = this._popoutWindowService) === null || _a === void 0 ? void 0 : _a.entries.find((entry) => entry.gridview === popoutGridview));
+        // The groups still living in this window, resolved from the gridview so
+        // a reassigned anchor doesn't hide surviving members.
+        const members = this.groups.filter((candidate) => popoutGridview.element.contains(candidate.element));
+        const anchorPresent = members.includes(group);
+        const anchorIsSoleMember = anchorPresent && members.length === 1;
+        // On a genuine close, relocate every member that ISN'T the captured
+        // anchor back to the main grid. The captured anchor (if still here) gets
+        // the reference-return / re-float treatment below. Explicit removal
+        // relocates via its own path, so the loop is skipped for it.
+        if (genuineClose) {
+            for (const member of members) {
+                if (member === group) {
+                    continue;
+                }
+                this.movingLock(() => {
+                    this.doRemoveGroup(member, {
+                        skipDispose: true,
+                        skipActive: true,
+                        skipPopoutReturn: true,
+                    });
+                    this.redockGroupToMainGrid(member);
+                });
+            }
+        }
+        if (anchorPresent &&
+            isGroupAddedToDom &&
+            this.getPanel(referenceGroup.id)) {
+            this.movingLock(() => moveGroupWithoutDestroying({
+                from: group,
+                to: referenceGroup,
+            }));
+            if (!referenceGroup.api.isVisible) {
+                referenceGroup.api.setVisible(true);
+            }
+            if (this.getPanel(group.id)) {
+                this.doRemoveGroup(group, {
+                    skipPopoutAssociated: true,
+                });
+            }
+        }
+        else if (anchorPresent && this.getPanel(group.id)) {
+            group.model.renderContainer = this.overlayRenderContainer;
+            group.model.dropTargetContainer = this.rootDropTargetContainer;
+            closeResult.returnedGroup = group;
+            if (!genuineClose) {
+                /**
+                 * If this popout group was explicitly removed then we shouldn't run the additional
+                 * steps. The explicit remover re-docks the returned group itself; here we only hand
+                 * it back (above) and tear down the nested gridview.
+                 */
+                disposePopoutGridview();
+                return;
+            }
+            // Re-float only restores the pre-popout state of a SINGLE popped-out
+            // group. A multi-group window must not be split (anchor re-floats
+            // while the rest dock to the grid), so dock the anchor to the grid
+            // alongside the other members once they're no longer alone.
+            if (floatingBox && anchorIsSoleMember) {
+                this.addFloatingGroup(group, {
+                    height: floatingBox.height,
+                    width: floatingBox.width,
+                    position: floatingBox,
+                });
+            }
+            else {
+                this.doRemoveGroup(group, {
+                    skipDispose: true,
+                    skipActive: true,
+                    skipPopoutReturn: true,
+                });
+                group.model.location = { type: 'grid' };
+                this.movingLock(() => {
+                    // suppress group add events since the group already exists
+                    this.doAddGroup(group, [0]);
+                });
+            }
+            this.doSetGroupAndPanelActive(group);
+        }
+        // All members have been relocated out; tear down the window's nested
+        // gridview (does not dispose the leaf views — their lifecycle stays
+        // with `_groups`).
+        disposePopoutGridview();
+    }
     addFloatingGroup(item, options) {
-        var _a, _b, _c, _d, _e, _f;
+        this.mutation('float', () => this._doAddFloatingGroup(item, options));
+    }
+    _doAddFloatingGroup(item, options) {
+        var _a;
+        const service = assertModule(this._floatingGroupService, 'FloatingGroup', 'api.addFloatingGroup');
+        if (!service) {
+            return;
+        }
         if (item instanceof DockviewGroupPanel &&
             item.model.location.type === 'edge') {
             // edge groups are permanent structural elements and cannot be floated
@@ -669,7 +1100,7 @@ export class DockviewComponent extends BaseGrid {
         }
         else {
             group = item;
-            const popoutReferenceGroupId = (_a = this._popoutGroups.find((_) => _.popoutGroup === group)) === null || _a === void 0 ? void 0 : _a.referenceGroup;
+            const popoutReferenceGroupId = (_a = this._popoutWindowService) === null || _a === void 0 ? void 0 : _a.findReferenceGroupId(group);
             const popoutReferenceGroup = popoutReferenceGroupId
                 ? this.getPanel(popoutReferenceGroupId)
                 : undefined;
@@ -750,65 +1181,87 @@ export class DockviewComponent extends BaseGrid {
             };
         }
         const anchoredBox = getAnchoredBox();
-        const overlay = new Overlay(Object.assign(Object.assign({ container: (_b = this._floatingOverlayHost) !== null && _b !== void 0 ? _b : this.gridview.element, content: group.element }, anchoredBox), { minimumInViewportWidth: this.options.floatingGroupBounds === 'boundedWithinViewport'
+        // The floating window hosts its own gridview so it can grow into a
+        // nested splitview layout. The window starts with the single anchor
+        // group; further groups are added via drag-and-drop.
+        const floatingGridview = this.createNestedGridview();
+        floatingGridview.addView(group, Sizing.Distribute, [0]);
+        this.mountFloatingWindow(floatingGridview, group, [group], anchoredBox, {
+            dragHandle: options === null || options === void 0 ? void 0 : options.dragHandle,
+            inDragMode: options === null || options === void 0 ? void 0 : options.inDragMode,
+            skipActiveGroup: options === null || options === void 0 ? void 0 : options.skipActiveGroup,
+        });
+    }
+    /**
+     * Build an empty gridview configured to match the main grid's styling, for
+     * hosting a nested layout inside a floating or popout window.
+     */
+    createNestedGridview(orientation = Orientation.HORIZONTAL) {
+        var _a, _b;
+        return new Gridview(true, this.options.hideBorders
+            ? { separatorBorder: 'transparent' }
+            : undefined, orientation, false, (_b = (_a = this.options.theme) === null || _a === void 0 ? void 0 : _a.gap) !== null && _b !== void 0 ? _b : 0);
+    }
+    /**
+     * Wrap a (populated) floating gridview in an overlay window: title bar /
+     * move handle, drag wiring, the floating-group service entry and the
+     * `floating` location tag for every member group.
+     */
+    mountFloatingWindow(floatingGridview, anchorGroup, members, anchoredBox, options) {
+        var _a, _b, _c, _d, _e, _f, _g, _h;
+        const service = assertModule(this._floatingGroupService, 'FloatingGroup', 'api.addFloatingGroup');
+        if (!service) {
+            return;
+        }
+        const dragHandleMode = (_b = (_a = options === null || options === void 0 ? void 0 : options.dragHandle) !== null && _a !== void 0 ? _a : this.options.floatingGroupDragHandle) !== null && _b !== void 0 ? _b : 'titlebar';
+        // `'titlebar'` renders a dedicated grab bar above the tab bar and uses
+        // it as the move handle; `'tabbar'` falls back to moving via the
+        // tab-bar void container.
+        const titleBar = dragHandleMode === 'titlebar'
+            ? new FloatingTitleBar(this, anchorGroup)
+            : undefined;
+        const overlay = new Overlay(Object.assign(Object.assign({ container: (_c = this._floatingOverlayHost) !== null && _c !== void 0 ? _c : this.gridview.element, content: floatingGridview.element, header: titleBar === null || titleBar === void 0 ? void 0 : titleBar.element }, anchoredBox), { minimumInViewportWidth: this.options.floatingGroupBounds === 'boundedWithinViewport'
                 ? undefined
-                : ((_d = (_c = this.options.floatingGroupBounds) === null || _c === void 0 ? void 0 : _c.minimumWidthWithinViewport) !== null && _d !== void 0 ? _d : DEFAULT_FLOATING_GROUP_OVERFLOW_SIZE), minimumInViewportHeight: this.options.floatingGroupBounds === 'boundedWithinViewport'
+                : ((_e = (_d = this.options.floatingGroupBounds) === null || _d === void 0 ? void 0 : _d.minimumWidthWithinViewport) !== null && _e !== void 0 ? _e : DEFAULT_FLOATING_GROUP_OVERFLOW_SIZE), minimumInViewportHeight: this.options.floatingGroupBounds === 'boundedWithinViewport'
                 ? undefined
-                : ((_f = (_e = this.options.floatingGroupBounds) === null || _e === void 0 ? void 0 : _e.minimumHeightWithinViewport) !== null && _f !== void 0 ? _f : DEFAULT_FLOATING_GROUP_OVERFLOW_SIZE) }));
-        const el = group.element.querySelector('.dv-void-container');
-        if (!el) {
+                : ((_g = (_f = this.options.floatingGroupBounds) === null || _f === void 0 ? void 0 : _f.minimumHeightWithinViewport) !== null && _g !== void 0 ? _g : DEFAULT_FLOATING_GROUP_OVERFLOW_SIZE), transformDragPosition: this.options.transformFloatingGroupDrag
+                ? (context) => this.options.transformFloatingGroupDrag({
+                    group: anchorGroup,
+                    proposed: context.proposed,
+                    container: context.container,
+                    others: context.others,
+                })
+                : undefined, getSiblingBoxes: () => this._gatherFloatingGroupBoxes(anchorGroup) }));
+        const dragHandle = (_h = titleBar === null || titleBar === void 0 ? void 0 : titleBar.element) !== null && _h !== void 0 ? _h : anchorGroup.element.querySelector('.dv-void-container');
+        if (!dragHandle) {
             throw new Error('dockview: failed to find drag handle');
         }
-        overlay.setupDrag(el, {
+        overlay.setupDrag(dragHandle, {
             inDragMode: typeof (options === null || options === void 0 ? void 0 : options.inDragMode) === 'boolean'
                 ? options.inDragMode
                 : false,
         });
-        const floatingGroupPanel = new DockviewFloatingGroupPanel(group, overlay);
-        const disposable = new CompositeDisposable(group.api.onDidActiveChange((event) => {
-            if (event.isActive) {
-                overlay.bringToFront();
-            }
-        }), (() => {
-            let lastWidth = -1;
-            let lastHeight = -1;
-            return watchElementResize(group.element, (entry) => {
-                const width = Math.round(entry.contentRect.width);
-                const height = Math.round(entry.contentRect.height);
-                if (width === lastWidth && height === lastHeight) {
-                    return;
-                }
-                lastWidth = width;
-                lastHeight = height;
-                group.layout(width, height); // let the group know it's size is changing so it can fire events to the panel
-            });
-        })());
-        floatingGroupPanel.addDisposables(overlay.onDidChange(() => {
-            // this is either a resize or a move
-            // to inform the panels .layout(...) the group with it's current size
-            // don't care about resize since the above watcher handles that
-            group.layout(group.width, group.height);
-        }), overlay.onDidChangeEnd(() => {
-            this._bufferOnDidLayoutChange.fire();
-        }), group.onDidChange((event) => {
-            overlay.setBounds({
-                height: event === null || event === void 0 ? void 0 : event.height,
-                width: event === null || event === void 0 ? void 0 : event.width,
-            });
-        }), {
-            dispose: () => {
-                disposable.dispose();
-                remove(this._floatingGroups, floatingGroupPanel);
-                group.model.location = { type: 'grid' };
-                this.updateWatermark();
-            },
-        });
-        this._floatingGroups.push(floatingGroupPanel);
-        group.model.location = { type: 'floating' };
+        const floatingGroupPanel = service.add(anchorGroup, overlay, floatingGridview);
+        if (titleBar) {
+            // Tie the title bar's lifetime to the floating window and surface
+            // its redock drag through the same public `onWillDragGroup` event
+            // the tab-bar handle uses. Register it so anchor reassignment (when
+            // the original anchor leaves a multi-group window) retargets the
+            // bar at a group that still lives here.
+            floatingGroupPanel.setTitleBar(titleBar);
+            floatingGroupPanel.addDisposables(titleBar, Disposable.from(() => floatingGroupPanel.setTitleBar(undefined)), titleBar.onDragStart((event) => {
+                this._onWillDragGroup.fire({
+                    nativeEvent: event,
+                    group: floatingGroupPanel.group,
+                });
+            }));
+        }
+        for (const member of members) {
+            member.model.location = { type: 'floating' };
+        }
         if (!(options === null || options === void 0 ? void 0 : options.skipActiveGroup)) {
-            this.doSetGroupAndPanelActive(group);
+            this.doSetGroupAndPanelActive(anchorGroup);
         }
-        this.updateWatermark();
     }
     orthogonalize(position, options) {
         this.gridview.normalize();
@@ -847,29 +1300,8 @@ export class DockviewComponent extends BaseGrid {
     updateOptions(options) {
         var _a, _b, _c, _d, _e;
         super.updateOptions(options);
-        if ('floatingGroupBounds' in options) {
-            for (const group of this._floatingGroups) {
-                switch (options.floatingGroupBounds) {
-                    case 'boundedWithinViewport':
-                        group.overlay.minimumInViewportHeight = undefined;
-                        group.overlay.minimumInViewportWidth = undefined;
-                        break;
-                    case undefined:
-                        group.overlay.minimumInViewportHeight =
-                            DEFAULT_FLOATING_GROUP_OVERFLOW_SIZE;
-                        group.overlay.minimumInViewportWidth =
-                            DEFAULT_FLOATING_GROUP_OVERFLOW_SIZE;
-                        break;
-                    default:
-                        group.overlay.minimumInViewportHeight =
-                            (_a = options.floatingGroupBounds) === null || _a === void 0 ? void 0 : _a.minimumHeightWithinViewport;
-                        group.overlay.minimumInViewportWidth =
-                            (_b = options.floatingGroupBounds) === null || _b === void 0 ? void 0 : _b.minimumWidthWithinViewport;
-                }
-                group.overlay.setBounds();
-            }
-        }
-        this.updateDropTargetModel(options);
+        (_a = this._floatingGroupService) === null || _a === void 0 ? void 0 : _a.updateBounds(options);
+        (_b = this._rootDropTargetService) === null || _b === void 0 ? void 0 : _b.setOptions(options);
         const oldDisableDnd = this.options.disableDnd;
         const oldDndStrategy = this.options.dndStrategy;
         this._options = Object.assign(Object.assign({}, this.options), options);
@@ -885,17 +1317,10 @@ export class DockviewComponent extends BaseGrid {
         if ('createRightHeaderActionComponent' in options ||
             'createLeftHeaderActionComponent' in options ||
             'createPrefixHeaderActionComponent' in options) {
-            for (const group of this.groups) {
-                group.model.updateHeaderActions();
-            }
+            (_c = this.headerActionsService) === null || _c === void 0 ? void 0 : _c.refreshAll();
         }
         if ('createWatermarkComponent' in options) {
-            if (this._watermark) {
-                this._watermark.element.parentElement.remove();
-                (_d = (_c = this._watermark).dispose) === null || _d === void 0 ? void 0 : _d.call(_c);
-                this._watermark = null;
-            }
-            this.updateWatermark();
+            (_d = this._watermarkService) === null || _d === void 0 ? void 0 : _d.refresh();
             for (const group of this.groups) {
                 group.model.refreshWatermark();
             }
@@ -912,6 +1337,7 @@ export class DockviewComponent extends BaseGrid {
         this._layoutFromShell(this.gridview.width, this.gridview.height);
     }
     layout(width, height, forceResize) {
+        var _a, _b;
         if (this._shellManager && !this._inShellLayout) {
             this._shellManager.layout(width, height);
         }
@@ -919,12 +1345,9 @@ export class DockviewComponent extends BaseGrid {
             super.layout(width, height, forceResize);
         }
         this._syncFloatingOverlayHost();
-        if (this._floatingGroups) {
-            for (const floating of this._floatingGroups) {
-                // ensure floting groups stay within visible boundaries
-                floating.overlay.setBounds();
-            }
-        }
+        // floatingGroupService may be undefined during super() (BaseGrid calls
+        // layout(0, 0) before subclass field initialisers run).
+        (_b = (_a = this._moduleRegistry) === null || _a === void 0 ? void 0 : _a.services.floatingGroupService) === null || _b === void 0 ? void 0 : _b.constrainBounds();
     }
     _syncFloatingOverlayHost() {
         if (!this._floatingOverlayHost || !this._shellManager) {
@@ -952,27 +1375,32 @@ export class DockviewComponent extends BaseGrid {
         }
     }
     addEdgeGroup(position, options) {
-        if (this._edgeGroups.has(position)) {
+        const service = assertModule(this._edgeGroupService, 'EdgeGroup', 'api.addEdgeGroup');
+        if (!service) {
+            throw new Error(`dockview: EdgeGroup module is not registered`);
+        }
+        if (service.has(position)) {
             throw new Error(`dockview: edge group already exists at position '${position}'`);
         }
-        const group = this.createGroup({ id: options.id });
-        group.model.location = { type: 'edge', position };
-        group.model.headerPosition = position;
-        this._edgeGroups.set(position, group);
-        this._onDidAddGroup.fire(group);
-        // Collapse when the group becomes empty
-        const autoCollapseDisposable = group.model.onDidRemovePanel(() => {
-            if (group.model.isEmpty) {
-                this.setEdgeGroupCollapsed(group, true);
-            }
+        return this.mutation('add', () => {
+            const group = this.createGroup({ id: options.id });
+            group.model.location = { type: 'edge', position };
+            group.model.headerPosition = position;
+            // Collapse when the group becomes empty
+            const autoCollapseDisposable = group.model.onDidRemovePanel(() => {
+                if (group.model.isEmpty) {
+                    this.setEdgeGroupCollapsed(group, true);
+                }
+            });
+            service.add(position, group, autoCollapseDisposable);
+            this._onDidAddGroup.fire(group);
+            this._shellManager.addEdgeView(position, options, group);
+            return group.api;
         });
-        this._edgeGroupDisposables.set(position, autoCollapseDisposable);
-        this._shellManager.addEdgeView(position, options, group);
-        return group.api;
     }
     getEdgeGroup(position) {
-        var _a;
-        return (_a = this._edgeGroups.get(position)) === null || _a === void 0 ? void 0 : _a.api;
+        var _a, _b;
+        return (_b = (_a = this._edgeGroupService) === null || _a === void 0 ? void 0 : _a.get(position)) === null || _b === void 0 ? void 0 : _b.api;
     }
     setEdgeGroupVisible(position, visible) {
         this._shellManager.setEdgeGroupVisible(position, visible);
@@ -981,54 +1409,54 @@ export class DockviewComponent extends BaseGrid {
         return this._shellManager.isEdgeGroupVisible(position);
     }
     removeEdgeGroup(position) {
-        var _a;
-        const group = this._edgeGroups.get(position);
+        const service = assertModule(this._edgeGroupService, 'EdgeGroup', 'api.removeEdgeGroup');
+        if (!service) {
+            return;
+        }
+        const group = service.get(position);
         if (!group) {
             throw new Error(`dockview: no edge group exists at position '${position}'`);
         }
-        // Remove panels inside the group first
-        for (const panel of [...group.panels]) {
-            this.removePanel(panel, {
-                removeEmptyGroup: false,
-                skipDispose: false,
-            });
-        }
-        // Dispose the auto-collapse listener
-        (_a = this._edgeGroupDisposables.get(position)) === null || _a === void 0 ? void 0 : _a.dispose();
-        this._edgeGroupDisposables.delete(position);
-        // Remove from the shell splitview
-        this._shellManager.removeEdgeView(position);
-        // Clean up group state
-        this._edgeGroups.delete(position);
-        group.dispose();
-        this._groups.delete(group.id);
-        this._onDidRemoveGroup.fire(group);
-    }
-    setEdgeGroupCollapsed(group, collapsed) {
-        for (const [position, edgeGroup] of this._edgeGroups) {
-            if (edgeGroup === group) {
-                if (this._shellManager.isEdgeGroupCollapsed(position) ===
-                    collapsed) {
-                    // Skip the splitview resize on a no-op: with non-zero
-                    // theme gap, redundant resizeView calls accumulate
-                    // rounding drift that gradually shrinks the group.
-                    return;
-                }
-                this._shellManager.setEdgeGroupCollapsed(position, collapsed);
-                edgeGroup.api._onDidCollapsedChange.fire({
-                    isCollapsed: collapsed,
+        // One transaction — the per-panel removals below nest via the depth
+        // counter, so consumers see a single edge-group removal.
+        this.mutation('remove', () => {
+            // Remove panels inside the group first
+            for (const panel of [...group.panels]) {
+                this.removePanel(panel, {
+                    removeEmptyGroup: false,
+                    skipDispose: false,
                 });
-                return;
             }
+            // Remove from the shell splitview
+            this._shellManager.removeEdgeView(position);
+            // Clean up service-tracked state + group itself
+            service.remove(position);
+            group.dispose();
+            this._groups.delete(group.id);
+            this._onDidRemoveGroup.fire(group);
+        });
+    }
+    setEdgeGroupCollapsed(group, collapsed) {
+        var _a;
+        const position = (_a = this._edgeGroupService) === null || _a === void 0 ? void 0 : _a.findPositionOf(group);
+        if (!position) {
+            return;
+        }
+        if (this._shellManager.isEdgeGroupCollapsed(position) === collapsed) {
+            // Skip the splitview resize on a no-op: with non-zero theme gap,
+            // redundant resizeView calls accumulate rounding drift that
+            // gradually shrinks the group.
+            return;
         }
+        this._shellManager.setEdgeGroupCollapsed(position, collapsed);
+        group.api._onDidCollapsedChange.fire({ isCollapsed: collapsed });
     }
     isEdgeGroupCollapsed(group) {
-        for (const [position, edgeGroup] of this._edgeGroups) {
-            if (edgeGroup === group) {
-                return this._shellManager.isEdgeGroupCollapsed(position);
-            }
-        }
-        return false;
+        var _a;
+        const position = (_a = this._edgeGroupService) === null || _a === void 0 ? void 0 : _a.findPositionOf(group);
+        return position
+            ? this._shellManager.isEdgeGroupCollapsed(position)
+            : false;
     }
     updateDragAndDropState() {
         // Update draggable state for all tabs and void containers
@@ -1092,32 +1520,18 @@ export class DockviewComponent extends BaseGrid {
      * @returns A JSON respresentation of the layout
      */
     toJSON() {
-        var _a;
+        var _a, _b, _c, _d, _e, _f, _g, _h;
         const data = this.gridview.serialize();
         const panels = this.panels.reduce((collection, panel) => {
             collection[panel.id] = panel.toJSON();
             return collection;
         }, {});
-        const floats = this._floatingGroups.map((group) => {
-            return {
-                data: group.group.toJSON(),
-                position: group.overlay.toJSON(),
-            };
-        });
-        const popoutGroups = this._popoutGroups.map((group) => {
-            return {
-                data: group.popoutGroup.toJSON(),
-                gridReferenceGroup: group.referenceGroup,
-                position: group.window.dimensions(),
-                url: group.popoutGroup.api.location.type === 'popout'
-                    ? group.popoutGroup.api.location.popoutUrl
-                    : undefined,
-            };
-        });
+        const floats = (_b = (_a = this._floatingGroupService) === null || _a === void 0 ? void 0 : _a.serialize()) !== null && _b !== void 0 ? _b : [];
+        const popoutGroups = (_d = (_c = this._popoutWindowService) === null || _c === void 0 ? void 0 : _c.serialize()) !== null && _d !== void 0 ? _d : [];
         const result = {
             grid: data,
             panels,
-            activeGroup: (_a = this.activeGroup) === null || _a === void 0 ? void 0 : _a.id,
+            activeGroup: (_e = this.activeGroup) === null || _e === void 0 ? void 0 : _e.id,
         };
         if (floats.length > 0) {
             result.floatingGroups = floats;
@@ -1125,10 +1539,11 @@ export class DockviewComponent extends BaseGrid {
         if (popoutGroups.length > 0) {
             result.popoutGroups = popoutGroups;
         }
-        if (this._edgeGroups.size > 0) {
+        const edgeEntries = (_g = (_f = this._edgeGroupService) === null || _f === void 0 ? void 0 : _f.entries()) !== null && _g !== void 0 ? _g : [];
+        if ((_h = this._edgeGroupService) === null || _h === void 0 ? void 0 : _h.hasAny()) {
             const shellSerialized = this._shellManager.toJSON();
             // Augment each entry with the serialized group state
-            for (const [position, group] of this._edgeGroups) {
+            for (const [position, group] of edgeEntries) {
                 const entry = shellSerialized[position];
                 if (entry) {
                     entry.group = group.toJSON();
@@ -1139,17 +1554,19 @@ export class DockviewComponent extends BaseGrid {
         return result;
     }
     fromJSON(data, options) {
-        var _a, _b, _c;
+        // One 'load' transaction for the whole deserialization — the many
+        // nested add/remove mutations join it via the depth counter.
+        this.mutation('load', () => this._doFromJSON(data, options));
+    }
+    _doFromJSON(data, options) {
+        var _a, _b, _c, _d, _e, _f, _g;
         // Cancel any popout-restoration timers queued by a previous fromJSON
-        // that haven't fired yet. Each cleanup also disposes the orphan group
-        // that was registered in _groups synchronously but never parented
-        // into a popout window — otherwise the upcoming clear() would call
-        // gridview.remove() on an unparented element and throw
-        // "Invalid grid element". See issue #1304.
-        for (const cleanup of [...this._popoutRestorationCleanups]) {
-            cleanup();
-        }
-        this._popoutRestorationCleanups.clear();
+        // that haven't fired yet. The cancel path also disposes orphan groups
+        // registered in _groups synchronously but never parented into a popout
+        // window — otherwise the upcoming clear() would call gridview.remove()
+        // on an unparented element and throw "Invalid grid element". See
+        // issue #1304.
+        (_a = this._popoutWindowService) === null || _a === void 0 ? void 0 : _a.cancelPendingRestorations();
         const existingPanels = new Map();
         let tempGroup;
         if (options === null || options === void 0 ? void 0 : options.reuseExistingPanels) {
@@ -1198,7 +1615,7 @@ export class DockviewComponent extends BaseGrid {
             const createGroupFromSerializedState = (data) => {
                 const { id, locked, hideHeader, headerPosition, views, activeView, } = data;
                 if (typeof id !== 'string') {
-                    throw new Error('dockview: group id must be of type string');
+                    throw new TypeError('dockview: group id must be of type string');
                 }
                 const group = this.createGroup({
                     id,
@@ -1266,138 +1683,23 @@ export class DockviewComponent extends BaseGrid {
             });
             this._layoutFromShell(width, height);
             if (data.edgeGroups) {
-                // Auto-create edge groups for positions in the serialized state
-                // that don't already have a group registered (e.g. when fromJSON
-                // is called before the user has called addEdgeGroup).
-                for (const _position of [
-                    'top',
-                    'bottom',
-                    'left',
-                    'right',
-                ]) {
-                    const fixedData = data.edgeGroups[_position];
-                    if (fixedData && !this._edgeGroups.has(_position)) {
-                        const groupState = fixedData.group;
-                        const id = (_a = groupState === null || groupState === void 0 ? void 0 : groupState.id) !== null && _a !== void 0 ? _a : `${_position}-group`;
-                        this.addEdgeGroup(_position, { id });
-                    }
-                }
-                // Restore panel contents of edge groups
-                for (const [position, edgeGroup] of this._edgeGroups) {
-                    const edgeData = data.edgeGroups[position];
-                    const groupState = edgeData === null || edgeData === void 0 ? void 0 : edgeData.group;
-                    if (groupState) {
-                        const { views, activeView } = groupState;
-                        const createdPanels = [];
-                        for (const panelId of views) {
-                            if (panels[panelId]) {
-                                const panel = this._deserializer.fromJSON(panels[panelId], edgeGroup);
-                                createdPanels.push(panel);
-                            }
-                        }
-                        for (let i = 0; i < createdPanels.length; i++) {
-                            const panel = createdPanels[i];
-                            const isActive = activeView === panel.id;
-                            edgeGroup.model.openPanel(panel, {
-                                skipSetActive: !isActive,
-                                skipSetGroupActive: true,
-                            });
-                        }
-                        // Restore tab groups before activating a fallback panel
-                        if (groupState.tabGroups &&
-                            groupState.tabGroups.length > 0) {
-                            edgeGroup.model.restoreTabGroups(groupState.tabGroups);
-                        }
-                        if (!edgeGroup.activePanel &&
-                            edgeGroup.panels.length > 0) {
-                            edgeGroup.model.openPanel(edgeGroup.panels[edgeGroup.panels.length - 1], { skipSetGroupActive: true });
-                        }
-                    }
-                }
-                this._shellManager.fromJSON(data.edgeGroups);
-            }
-            const serializedFloatingGroups = (_b = data.floatingGroups) !== null && _b !== void 0 ? _b : [];
-            for (const serializedFloatingGroup of serializedFloatingGroups) {
-                const { data, position } = serializedFloatingGroup;
-                const group = createGroupFromSerializedState(data);
-                this.addFloatingGroup(group, {
-                    position: position,
-                    width: position.width,
-                    height: position.height,
-                    skipRemoveGroup: true,
-                    inDragMode: false,
-                });
-            }
-            const serializedPopoutGroups = (_c = data.popoutGroups) !== null && _c !== void 0 ? _c : [];
-            // Create a promise that resolves when all popout groups are created
-            const popoutPromises = [];
-            // Queue popup group creation with delays to avoid browser blocking
-            serializedPopoutGroups.forEach((serializedPopoutGroup, index) => {
-                const { data, position, gridReferenceGroup, url } = serializedPopoutGroup;
-                const group = createGroupFromSerializedState(data);
-                // Add a small delay for each popup after the first to avoid browser popup blocking
-                const popoutPromise = new Promise((resolve) => {
-                    const cleanup = () => {
-                        this._popoutRestorationCleanups.delete(cleanup);
-                        clearTimeout(handle);
-                        // The group was registered in _groups synchronously
-                        // but the timer that would parent it into the popout
-                        // window never ran. Dispose the orphan here so the
-                        // next clear() doesn't trip over an unparented
-                        // element. See issue #1304.
-                        if (!this.isDisposed &&
-                            this._groups.has(group.id) &&
-                            group.element.parentElement === null) {
-                            for (const panel of [...group.panels]) {
-                                this.removePanel(panel, {
-                                    removeEmptyGroup: false,
-                                });
-                            }
-                            group.dispose();
-                            this._groups.delete(group.id);
-                            this._onDidRemoveGroup.fire(group);
-                        }
-                        resolve();
-                    };
-                    const handle = setTimeout(() => {
-                        this._popoutRestorationCleanups.delete(cleanup);
-                        // Guard against the component being disposed before
-                        // this timer fires. Under React StrictMode the
-                        // component is mounted -> disposed -> remounted, and
-                        // without this guard the first instance's queued
-                        // restoration would open a second popout window.
-                        // See issue #851.
-                        if (this.isDisposed) {
-                            resolve();
-                            return;
-                        }
-                        this.addPopoutGroup(group, {
-                            position: position !== null && position !== void 0 ? position : undefined,
-                            overridePopoutGroup: gridReferenceGroup
-                                ? group
-                                : undefined,
-                            referenceGroup: gridReferenceGroup
-                                ? this.getPanel(gridReferenceGroup)
-                                : undefined,
-                            popoutUrl: url,
-                        });
-                        resolve();
-                    }, index * DESERIALIZATION_POPOUT_DELAY_MS); // 100ms delay between each popup
-                    this._popoutRestorationCleanups.add(cleanup);
-                });
-                popoutPromises.push(popoutPromise);
-            });
-            // Store the promise for tests to wait on
-            this._popoutRestorationPromise = Promise.all(popoutPromises).then(() => void 0);
-            for (const floatingGroup of this._floatingGroups) {
-                floatingGroup.overlay.setBounds();
+                this.deserializeEdgeGroups(data.edgeGroups, panels);
             }
+            this.deserializeFloatingWindows((_b = data.floatingGroups) !== null && _b !== void 0 ? _b : [], createGroupFromSerializedState);
+            const popoutPromises = this.deserializePopoutWindows((_c = data.popoutGroups) !== null && _c !== void 0 ? _c : [], createGroupFromSerializedState);
+            (_d = this._popoutWindowService) === null || _d === void 0 ? void 0 : _d.finishRestoration(popoutPromises);
+            (_e = this._floatingGroupService) === null || _e === void 0 ? void 0 : _e.constrainBounds();
             if (typeof activeGroup === 'string') {
                 const panel = this.getPanel(activeGroup);
                 if (panel) {
                     this.doSetGroupAndPanelActive(panel);
                 }
             }
+            // `gridview.deserialize()` rebuilds the grid without firing the
+            // BaseGrid add events the watermark module reacts to, so the
+            // watermark mounted during `clear()` would otherwise persist over
+            // the restored layout. Re-evaluate now the layout is in place.
+            (_f = this._watermarkService) === null || _f === void 0 ? void 0 : _f.update();
         }
         catch (err) {
             console.error('dockview: failed to deserialize layout. Reverting changes', err);
@@ -1421,10 +1723,7 @@ export class DockviewComponent extends BaseGrid {
                 this._groups.delete(group.id);
                 this._onDidRemoveGroup.fire(group);
             }
-            // iterate over a reassigned array since original array will be modified
-            for (const floatingGroup of [...this._floatingGroups]) {
-                floatingGroup.dispose();
-            }
+            (_g = this._floatingGroupService) === null || _g === void 0 ? void 0 : _g.disposeAll();
             // fires clean-up events and clears the underlying HTML gridview.
             this.clear();
             /**
@@ -1434,16 +1733,178 @@ export class DockviewComponent extends BaseGrid {
              */
             throw err;
         }
-        this.updateWatermark();
         // Force position updates for always visible panels after DOM layout is complete
         this.debouncedUpdateAllPositions();
         this._onDidLayoutFromJSON.fire();
     }
+    /**
+     * Rebuild a floating / popout window's nested gridview from its serialized
+     * tree, collecting the member groups (in deserialization order) so the
+     * caller can mount or restore the window.
+     */
+    deserializeNestedGridview(grid, createGroup) {
+        const gridview = this.createNestedGridview(grid.orientation);
+        const members = [];
+        gridview.deserialize(grid, {
+            fromJSON: (node) => {
+                const group = createGroup(node.data);
+                members.push(group);
+                return group;
+            },
+        });
+        return { gridview, members };
+    }
+    deserializeEdgeGroups(edgeGroups, panels) {
+        var _a;
+        const edgeService = assertModule(this._edgeGroupService, 'EdgeGroup', 'fromJSON edge restoration');
+        if (!edgeService) {
+            return;
+        }
+        // Auto-create edge groups for positions in the serialized state that
+        // don't already have a group registered (e.g. when fromJSON is called
+        // before the user has called addEdgeGroup).
+        for (const _position of [
+            'top',
+            'bottom',
+            'left',
+            'right',
+        ]) {
+            const fixedData = edgeGroups[_position];
+            if (fixedData && !edgeService.has(_position)) {
+                const groupState = fixedData.group;
+                const id = (_a = groupState === null || groupState === void 0 ? void 0 : groupState.id) !== null && _a !== void 0 ? _a : `${_position}-group`;
+                this.addEdgeGroup(_position, { id });
+            }
+        }
+        // Restore panel contents of edge groups
+        for (const [position, edgeGroup] of edgeService.entries()) {
+            const edgeData = edgeGroups[position];
+            const groupState = edgeData === null || edgeData === void 0 ? void 0 : edgeData.group;
+            if (groupState) {
+                const { views, activeView } = groupState;
+                const createdPanels = [];
+                for (const panelId of views) {
+                    if (panels[panelId]) {
+                        const panel = this._deserializer.fromJSON(panels[panelId], edgeGroup);
+                        createdPanels.push(panel);
+                    }
+                }
+                for (const panel of createdPanels) {
+                    const isActive = activeView === panel.id;
+                    edgeGroup.model.openPanel(panel, {
+                        skipSetActive: !isActive,
+                        skipSetGroupActive: true,
+                    });
+                }
+                // Restore tab groups before activating a fallback panel
+                if (groupState.tabGroups && groupState.tabGroups.length > 0) {
+                    edgeGroup.model.restoreTabGroups(groupState.tabGroups);
+                }
+                if (!edgeGroup.activePanel && edgeGroup.panels.length > 0) {
+                    edgeGroup.model.openPanel(edgeGroup.panels[edgeGroup.panels.length - 1], { skipSetGroupActive: true });
+                }
+            }
+        }
+        this._shellManager.fromJSON(edgeGroups);
+    }
+    deserializeFloatingWindows(serialized, createGroup) {
+        for (const serializedFloatingGroup of serialized) {
+            const { data, grid, position } = serializedFloatingGroup;
+            if (grid) {
+                // Multi-group window: rebuild the window's nested gridview from
+                // its serialized tree.
+                const { gridview: floatingGridview, members } = this.deserializeNestedGridview(grid, createGroup);
+                if (members.length === 0) {
+                    continue;
+                }
+                this.mountFloatingWindow(floatingGridview, members[0], members, position, { inDragMode: false });
+            }
+            else if (data) {
+                const group = createGroup(data);
+                this.addFloatingGroup(group, {
+                    position: position,
+                    width: position.width,
+                    height: position.height,
+                    skipRemoveGroup: true,
+                    inDragMode: false,
+                });
+            }
+        }
+    }
+    deserializePopoutWindows(serialized, createGroup) {
+        const popoutService = serialized.length > 0
+            ? assertModule(this._popoutWindowService, 'PopoutWindow', 'fromJSON popout restoration')
+            : this._popoutWindowService;
+        if (!popoutService) {
+            return [];
+        }
+        // Queue popup group creation with delays to avoid browser blocking
+        return serialized.flatMap((serializedPopoutGroup, index) => {
+            const { data, grid, position, gridReferenceGroup, url } = serializedPopoutGroup;
+            // Multi-group popout windows rebuild their nested gridview from the
+            // serialized tree; single-group windows use the legacy single-group
+            // path.
+            let overridePopoutGridview;
+            let members = [];
+            if (grid) {
+                const built = this.deserializeNestedGridview(grid, createGroup);
+                overridePopoutGridview = built.gridview;
+                members = built.members;
+                if (members.length === 0) {
+                    // A serialized window with no groups: nothing to restore.
+                    // Mirror the floating path's guard and discard the empty
+                    // gridview rather than passing an undefined anchor to
+                    // addPopoutGroup.
+                    overridePopoutGridview.dispose();
+                    return [];
+                }
+            }
+            const group = grid ? members[0] : createGroup(data);
+            return popoutService.scheduleRestoration(index * DESERIALIZATION_POPOUT_DELAY_MS, () => {
+                this.addPopoutGroup(group, {
+                    position: position !== null && position !== void 0 ? position : undefined,
+                    overridePopoutGroup: gridReferenceGroup
+                        ? group
+                        : undefined,
+                    overridePopoutGridview,
+                    referenceGroup: gridReferenceGroup
+                        ? this.getPanel(gridReferenceGroup)
+                        : undefined,
+                    popoutUrl: url,
+                });
+            }, () => {
+                // The group was registered in _groups synchronously but the
+                // timer that would parent it into the popout window never
+                // ran. Dispose the orphan here so the next clear() doesn't
+                // trip over an unparented element. See issue #1304.
+                for (const orphan of members.length > 0
+                    ? members
+                    : [group]) {
+                    if (!this.isDisposed &&
+                        this._groups.has(orphan.id) &&
+                        orphan.element.parentElement === null) {
+                        for (const panel of [...orphan.panels]) {
+                            this.removePanel(panel, {
+                                removeEmptyGroup: false,
+                            });
+                        }
+                        orphan.dispose();
+                        this._groups.delete(orphan.id);
+                        this._onDidRemoveGroup.fire(orphan);
+                    }
+                }
+            });
+        });
+    }
     clear() {
+        this.mutation('clear', () => this._doClear());
+    }
+    _doClear() {
+        var _a;
         const groups = Array.from(this._groups.values()).map((_) => _.value);
         const hasActiveGroup = !!this.activeGroup;
         for (const group of groups) {
-            if ([...this._edgeGroups.values()].includes(group)) {
+            if ((_a = this._edgeGroupService) === null || _a === void 0 ? void 0 : _a.includes(group)) {
                 // Edge groups are structural - only clear their panels, not the group itself
                 const panels = [...group.panels];
                 for (const panel of panels) {
@@ -1460,14 +1921,21 @@ export class DockviewComponent extends BaseGrid {
         this.gridview.clear();
     }
     closeAllGroups() {
-        for (const entry of this._groups.entries()) {
-            const [_, group] = entry;
-            group.value.model.closeAllPanels();
-        }
+        // One transaction — the per-panel removals inside nest via the depth
+        // counter, so consumers (undo, announcements) see a single mutation.
+        this.mutation('remove', () => {
+            for (const entry of this._groups.entries()) {
+                const [_, group] = entry;
+                group.value.model.closeAllPanels();
+            }
+        });
     }
     addPanel(options) {
-        var _a, _b;
-        if (this.panels.find((_) => _.id === options.id)) {
+        return this.mutation('add', () => this._doAddPanel(options));
+    }
+    _doAddPanel(options) {
+        var _a, _b, _c, _d;
+        if (this.panels.some((_) => _.id === options.id)) {
             throw new Error(`dockview: panel with id ${options.id} already exists`);
         }
         let referenceGroup;
@@ -1486,18 +1954,24 @@ export class DockviewComponent extends BaseGrid {
                     : options.position.referencePanel;
                 index = options.position.index;
                 if (!referencePanel) {
-                    throw new Error(`dockview: referencePanel '${options.position.referencePanel}' does not exist`);
+                    const referenceId = typeof options.position.referencePanel === 'string'
+                        ? options.position.referencePanel
+                        : (_a = options.position.referencePanel) === null || _a === void 0 ? void 0 : _a.id;
+                    throw new Error(`dockview: referencePanel '${referenceId}' does not exist`);
                 }
                 referenceGroup = this.findGroup(referencePanel);
             }
             else if (isPanelOptionsWithGroup(options.position)) {
                 referenceGroup =
                     typeof options.position.referenceGroup === 'string'
-                        ? (_a = this._groups.get(options.position.referenceGroup)) === null || _a === void 0 ? void 0 : _a.value
+                        ? (_b = this._groups.get(options.position.referenceGroup)) === null || _b === void 0 ? void 0 : _b.value
                         : options.position.referenceGroup;
                 index = options.position.index;
                 if (!referenceGroup) {
-                    throw new Error(`dockview: referenceGroup '${options.position.referenceGroup}' does not exist`);
+                    const referenceId = typeof options.position.referenceGroup === 'string'
+                        ? options.position.referenceGroup
+                        : (_c = options.position.referenceGroup) === null || _c === void 0 ? void 0 : _c.id;
+                    throw new Error(`dockview: referenceGroup '${referenceId}' does not exist`);
                 }
             }
             else {
@@ -1523,7 +1997,7 @@ export class DockviewComponent extends BaseGrid {
         }
         let panel;
         if (referenceGroup) {
-            const target = toTarget(((_b = options.position) === null || _b === void 0 ? void 0 : _b.direction) || 'within');
+            const target = toTarget(((_d = options.position) === null || _d === void 0 ? void 0 : _d.direction) || 'within');
             if (options.floating) {
                 const group = this.createGroup();
                 this._onDidAddGroup.fire(group);
@@ -1605,9 +2079,17 @@ export class DockviewComponent extends BaseGrid {
         }
         return panel;
     }
-    removePanel(panel, options = {
-        removeEmptyGroup: true,
-    }) {
+    removePanel(panel, options) {
+        this.mutation('remove', () => {
+            var _a;
+            return this._doRemovePanel(panel, {
+                removeEmptyGroup: (_a = options === null || options === void 0 ? void 0 : options.removeEmptyGroup) !== null && _a !== void 0 ? _a : true,
+                skipDispose: options === null || options === void 0 ? void 0 : options.skipDispose,
+                skipSetActiveGroup: options === null || options === void 0 ? void 0 : options.skipSetActiveGroup,
+            });
+        });
+    }
+    _doRemovePanel(panel, options) {
         const group = panel.group;
         if (!group) {
             throw new Error(`dockview: cannot remove panel ${panel.id}. it's missing a group.`);
@@ -1629,50 +2111,38 @@ export class DockviewComponent extends BaseGrid {
         }
         return new Watermark();
     }
-    updateWatermark() {
-        var _a, _b;
-        if (this.groups.filter((x) => x.api.location.type === 'grid' && x.api.isVisible).length === 0) {
-            if (!this._watermark) {
-                this._watermark = this.createWatermarkComponent();
-                this._watermark.init({
-                    containerApi: new DockviewApi(this),
-                });
-                const watermarkContainer = document.createElement('div');
-                watermarkContainer.className = 'dv-watermark-container';
-                addTestId(watermarkContainer, 'watermark-component');
-                watermarkContainer.appendChild(this._watermark.element);
-                this.gridview.element.appendChild(watermarkContainer);
-            }
-        }
-        else if (this._watermark) {
-            this._watermark.element.parentElement.remove();
-            (_b = (_a = this._watermark).dispose) === null || _b === void 0 ? void 0 : _b.call(_a);
-            this._watermark = null;
-        }
-    }
     addGroup(options) {
-        var _a;
+        return this.mutation('add', () => this._doAddGroup(options));
+    }
+    _doAddGroup(options) {
+        var _a, _b, _c;
         if (options) {
             let referenceGroup;
             if (isGroupOptionsWithPanel(options)) {
                 const referencePanel = typeof options.referencePanel === 'string'
                     ? this.panels.find((panel) => panel.id === options.referencePanel)
                     : options.referencePanel;
+                const referencePanelId = typeof options.referencePanel === 'string'
+                    ? options.referencePanel
+                    : (_a = options.referencePanel) === null || _a === void 0 ? void 0 : _a.id;
                 if (!referencePanel) {
-                    throw new Error(`dockview: reference panel ${options.referencePanel} does not exist`);
+                    throw new Error(`dockview: reference panel ${referencePanelId} does not exist`);
                 }
                 referenceGroup = this.findGroup(referencePanel);
                 if (!referenceGroup) {
-                    throw new Error(`dockview: reference group for reference panel ${options.referencePanel} does not exist`);
+                    throw new Error(`dockview: reference group for reference panel ${referencePanelId} does not exist`);
                 }
             }
             else if (isGroupOptionsWithGroup(options)) {
                 referenceGroup =
                     typeof options.referenceGroup === 'string'
-                        ? (_a = this._groups.get(options.referenceGroup)) === null || _a === void 0 ? void 0 : _a.value
+                        ? (_b = this._groups.get(options.referenceGroup)) === null || _b === void 0 ? void 0 : _b.value
                         : options.referenceGroup;
                 if (!referenceGroup) {
-                    throw new Error(`dockview: reference group ${options.referenceGroup} does not exist`);
+                    const referenceId = typeof options.referenceGroup === 'string'
+                        ? options.referenceGroup
+                        : (_c = options.referenceGroup) === null || _c === void 0 ? void 0 : _c.id;
+                    throw new Error(`dockview: reference group ${referenceId} does not exist`);
                 }
             }
             else {
@@ -1710,12 +2180,71 @@ export class DockviewComponent extends BaseGrid {
             : Orientation.VERTICAL;
     }
     removeGroup(group, options) {
-        this.doRemoveGroup(group, options);
+        this.mutation('remove', () => this.doRemoveGroup(group, options));
+    }
+    /**
+     * Detach a single group from the nested gridview of its floating / popout
+     * window, keeping the window and its remaining members alive, and reassign
+     * the window's anchor if the detached group was it.
+     *
+     * @returns `true` if the group was detached from a multi-member window;
+     * `false` if `group` is not in a nested window, or is the window's only
+     * member — in which case the caller is responsible for disposing the whole
+     * window.
+     */
+    detachFromNestedWindow(group) {
+        var _a, _b;
+        const floating = (_a = this._floatingGroupService) === null || _a === void 0 ? void 0 : _a.findByGroup(group);
+        if (floating) {
+            const members = this.nestedWindowMembers(group);
+            if (members.length <= 1) {
+                return false;
+            }
+            floating.gridview.remove(group);
+            if (floating.group === group) {
+                // The anchor left; promote a remaining member.
+                floating.setAnchorGroup(members.find((m) => m !== group));
+            }
+            return true;
+        }
+        const popout = (_b = this._popoutWindowService) === null || _b === void 0 ? void 0 : _b.findByGroup(group);
+        if (popout) {
+            const members = this.nestedWindowMembers(group);
+            if (members.length <= 1) {
+                return false;
+            }
+            popout.gridview.remove(group);
+            if (popout.popoutGroup === group) {
+                // The anchor left; promote a remaining member.
+                popout.popoutGroup = members.find((m) => m !== group);
+            }
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Dispose a group and forget it: remove it from `_groups` and fire the
+     * removed event.
+     */
+    disposeGroupRecord(group) {
+        group.dispose();
+        this._groups.delete(group.id);
+        this._onDidRemoveGroup.fire(group);
+    }
+    /**
+     * When `removed` was the active group, fall the active selection back to
+     * the first remaining group (or clear it when none remain).
+     */
+    activateFallbackGroupIfRemoved(removed, skipActive) {
+        if (!skipActive && this._activeGroup === removed) {
+            const groups = Array.from(this._groups.values());
+            this.doSetGroupAndPanelActive(groups.length > 0 ? groups[0].value : undefined);
+        }
     }
     doRemoveGroup(group, options) {
-        var _a;
+        var _a, _b, _c, _d, _e;
         // Edge groups are permanent structural elements - never remove them from the layout
-        if ([...this._edgeGroups.values()].includes(group)) {
+        if ((_a = this._edgeGroupService) === null || _a === void 0 ? void 0 : _a.includes(group)) {
             return group;
         }
         const panels = [...group.panels]; // reassign since group panels will mutate
@@ -1723,64 +2252,99 @@ export class DockviewComponent extends BaseGrid {
             for (const panel of panels) {
                 this.removePanel(panel, {
                     removeEmptyGroup: false,
-                    skipDispose: (_a = options === null || options === void 0 ? void 0 : options.skipDispose) !== null && _a !== void 0 ? _a : false,
+                    skipDispose: (_b = options === null || options === void 0 ? void 0 : options.skipDispose) !== null && _b !== void 0 ? _b : false,
                 });
             }
         }
         const activePanel = this.activePanel;
         if (group.api.location.type === 'floating') {
-            const floatingGroup = this._floatingGroups.find((_) => _.group === group);
-            if (floatingGroup) {
-                if (!(options === null || options === void 0 ? void 0 : options.skipDispose)) {
-                    floatingGroup.group.dispose();
-                    this._groups.delete(group.id);
-                    this._onDidRemoveGroup.fire(group);
+            const floatingGroup = (_c = this._floatingGroupService) === null || _c === void 0 ? void 0 : _c.findByGroup(group);
+            if (!floatingGroup) {
+                throw new Error('dockview: failed to find floating group');
+            }
+            if (this.detachFromNestedWindow(group)) {
+                // The floating window hosts other groups and stays alive —
+                // finalize just this group.
+                if (options === null || options === void 0 ? void 0 : options.skipDispose) {
+                    // Relocation: reset location so the destination root can
+                    // re-tag it.
+                    group.model.location = { type: 'grid' };
                 }
-                remove(this._floatingGroups, floatingGroup);
-                floatingGroup.dispose();
-                if (!(options === null || options === void 0 ? void 0 : options.skipActive) && this._activeGroup === group) {
-                    const groups = Array.from(this._groups.values());
-                    this.doSetGroupAndPanelActive(groups.length > 0 ? groups[0].value : undefined);
+                else {
+                    this.disposeGroupRecord(group);
                 }
-                return floatingGroup.group;
+                this.activateFallbackGroupIfRemoved(group, options === null || options === void 0 ? void 0 : options.skipActive);
+                return group;
+            }
+            // Last group leaving — dispose the whole floating window.
+            if (!(options === null || options === void 0 ? void 0 : options.skipDispose)) {
+                this.disposeGroupRecord(group);
             }
-            throw new Error('dockview: failed to find floating group');
+            // floatingGroup.dispose() removes itself from the service array
+            floatingGroup.dispose();
+            this.activateFallbackGroupIfRemoved(group, options === null || options === void 0 ? void 0 : options.skipActive);
+            return group;
         }
         if (group.api.location.type === 'popout') {
-            const selectedGroup = this._popoutGroups.find((_) => _.popoutGroup === group);
-            if (selectedGroup) {
-                if (!(options === null || options === void 0 ? void 0 : options.skipDispose)) {
-                    if (!(options === null || options === void 0 ? void 0 : options.skipPopoutAssociated)) {
-                        const refGroup = selectedGroup.referenceGroup
-                            ? this.getPanel(selectedGroup.referenceGroup)
-                            : undefined;
-                        if (refGroup && refGroup.panels.length === 0) {
-                            this.removeGroup(refGroup);
-                        }
-                    }
-                    selectedGroup.popoutGroup.dispose();
-                    this._groups.delete(group.id);
-                    this._onDidRemoveGroup.fire(group);
+            const selectedGroup = (_d = this._popoutWindowService) === null || _d === void 0 ? void 0 : _d.findByGroup(group);
+            if (!selectedGroup) {
+                throw new Error('dockview: failed to find popout group');
+            }
+            if (this.detachFromNestedWindow(group)) {
+                // The popout window hosts other groups and stays alive —
+                // finalize just this group.
+                if (options === null || options === void 0 ? void 0 : options.skipDispose) {
+                    // Relocation: reset location so the destination root can
+                    // re-tag it.
+                    group.model.location = { type: 'grid' };
                 }
-                remove(this._popoutGroups, selectedGroup);
-                const removedGroup = selectedGroup.disposable.dispose();
-                if (!(options === null || options === void 0 ? void 0 : options.skipPopoutReturn) && removedGroup) {
-                    this.doAddGroup(removedGroup, [0]);
-                    this.doSetGroupAndPanelActive(removedGroup);
+                else {
+                    this.disposeGroupRecord(group);
                 }
-                if (!(options === null || options === void 0 ? void 0 : options.skipActive) && this._activeGroup === group) {
-                    const groups = Array.from(this._groups.values());
-                    this.doSetGroupAndPanelActive(groups.length > 0 ? groups[0].value : undefined);
+                this.activateFallbackGroupIfRemoved(group, options === null || options === void 0 ? void 0 : options.skipActive);
+                return group;
+            }
+            // Last group leaving — tear the whole popout window down.
+            if (!(options === null || options === void 0 ? void 0 : options.skipDispose)) {
+                if (!(options === null || options === void 0 ? void 0 : options.skipPopoutAssociated)) {
+                    const refGroup = selectedGroup.referenceGroup
+                        ? this.getPanel(selectedGroup.referenceGroup)
+                        : undefined;
+                    if ((refGroup === null || refGroup === void 0 ? void 0 : refGroup.panels.length) === 0) {
+                        this.removeGroup(refGroup);
+                    }
                 }
-                this.updateWatermark();
-                return selectedGroup.popoutGroup;
+                selectedGroup.popoutGroup.dispose();
+                this._groups.delete(group.id);
+                this._onDidRemoveGroup.fire(group);
             }
-            throw new Error('dockview: failed to find popout group');
+            (_e = this._popoutWindowService) === null || _e === void 0 ? void 0 : _e.remove(selectedGroup);
+            const removedGroup = selectedGroup.disposable.dispose();
+            if (!(options === null || options === void 0 ? void 0 : options.skipPopoutReturn) && removedGroup) {
+                this.doAddGroup(removedGroup, [0]);
+                this.doSetGroupAndPanelActive(removedGroup);
+            }
+            this.activateFallbackGroupIfRemoved(group, options === null || options === void 0 ? void 0 : options.skipActive);
+            return selectedGroup.popoutGroup;
+        }
+        // A `grid`-location group whose element isn't actually in the gridview
+        // is an orphan — e.g. a popout-destined group created during fromJSON
+        // whose window hasn't opened yet, swept up by clear()/a re-entrant
+        // fromJSON. `gridview.remove()` would throw "Invalid grid element", so
+        // dispose it directly.
+        if (!this.gridview.element.contains(group.element)) {
+            if (!(options === null || options === void 0 ? void 0 : options.skipDispose)) {
+                const item = this._groups.get(group.id);
+                item === null || item === void 0 ? void 0 : item.disposable.dispose();
+                this.disposeGroupRecord(group);
+            }
+            this.activateFallbackGroupIfRemoved(group, options === null || options === void 0 ? void 0 : options.skipActive);
+            return group;
         }
         const re = super.doRemoveGroup(group, options);
         if (!(options === null || options === void 0 ? void 0 : options.skipActive)) {
             if (this.activePanel !== activePanel) {
-                this._onDidActivePanelChange.fire(this.activePanel);
+                this.fireActivePanelChange(this.activePanel);
             }
         }
         return re;
@@ -1790,8 +2354,15 @@ export class DockviewComponent extends BaseGrid {
             cancelAnimationFrame(this._updatePositionsFrameId);
         }
         this._updatePositionsFrameId = requestAnimationFrame(() => {
+            var _a, _b;
             this._updatePositionsFrameId = undefined;
             this.overlayRenderContainer.updateAllPositions();
+            // Popout windows have their own render containers; reposition those
+            // too so panels moved/split within a popout are laid out (the main
+            // container only covers grid + floating, which share it).
+            for (const entry of (_b = (_a = this._popoutWindowService) === null || _a === void 0 ? void 0 : _a.entries) !== null && _b !== void 0 ? _b : []) {
+                entry.overlayRenderContainer.updateAllPositions();
+            }
         });
     }
     movingLock(func) {
@@ -1804,8 +2375,74 @@ export class DockviewComponent extends BaseGrid {
             this._moving = isMoving;
         }
     }
+    /**
+     * Bracket a structural mutation with `onWillMutateLayout` /
+     * `onDidMutateLayout`. Re-entrant: nested calls (a compound operation such
+     * as a drag that relocates a panel) join the outermost transaction, so the
+     * events fire exactly once around the whole operation. `kind` reflects the
+     * outermost mutation.
+     */
+    mutation(kind, func) {
+        const outer = this._mutationDepth === 0;
+        const origin = this._origin;
+        if (outer) {
+            this._onWillMutateLayout.fire({ kind, origin });
+        }
+        this._mutationDepth++;
+        try {
+            return func();
+        }
+        finally {
+            this._mutationDepth--;
+            if (outer) {
+                this._onDidMutateLayout.fire({ kind, origin });
+            }
+        }
+    }
+    /**
+     * The origin of the operation currently in progress (`'user'` by default).
+     * Read inside a `mutation()` or active-panel change to learn whether the
+     * change was driven by application code (via the {@link DockviewApi}) or a
+     * user gesture.
+     */
+    currentOrigin() {
+        return this._origin;
+    }
+    /**
+     * Run `func` with the operation origin set to `origin`, restoring the
+     * previous value afterwards. Used by the DockviewApi boundary to tag
+     * programmatic operations as `'api'`, and by user-gesture handlers to tag
+     * `'user'`. Only the outermost caller sets the origin — a nested call (or a
+     * call made while a mutation is already in flight) keeps whatever the
+     * enclosing operation established, so the trigger always wins.
+     */
+    withOrigin(origin, func) {
+        if (this._originDepth > 0 || this._mutationDepth > 0) {
+            return func();
+        }
+        const previous = this._origin;
+        this._origin = origin;
+        this._originDepth++;
+        try {
+            return func();
+        }
+        finally {
+            this._originDepth--;
+            this._origin = previous;
+        }
+    }
+    /**
+     * Fire `onDidActivePanelChange` with the panel and the current operation
+     * {@link DockviewOrigin}. Callers keep their own dedupe guards.
+     */
+    fireActivePanelChange(panel) {
+        this._onDidActivePanelChange.fire({ panel, origin: this._origin });
+    }
     moveGroupOrPanel(options) {
-        var _a;
+        this.mutation('move', () => this._doMoveGroupOrPanel(options));
+    }
+    _doMoveGroupOrPanel(options) {
+        var _a, _b;
         const destinationGroup = options.to.group;
         const sourceGroupId = options.from.groupId;
         const sourceItemId = options.from.panelId;
@@ -1886,15 +2523,20 @@ export class DockviewComponent extends BaseGrid {
              * Dropping a panel to the extremities of a group which will place that panel
              * into an adjacent group
              */
+            // The destination group may live in the main grid or in a floating
+            // window's nested gridview — resolve which root we are dropping
+            // into so locations/orientation are computed against it.
+            const destinationGridview = this.getGridviewForGroup(destinationGroup);
             const referenceLocation = getGridLocation(destinationGroup.element);
-            const targetLocation = getRelativeLocation(this.gridview.orientation, referenceLocation, destinationTarget);
+            const targetLocation = getRelativeLocation(destinationGridview.orientation, referenceLocation, destinationTarget);
             if (sourceGroup.size < 2) {
                 /**
                  * If we are moving from a group which only has one panel left we will consider
                  * moving the group itself rather than moving the panel into a newly created group
                  */
                 const [targetParentLocation, to] = tail(targetLocation);
-                if (sourceGroup.api.location.type === 'grid') {
+                if (sourceGroup.api.location.type === 'grid' &&
+                    destinationGridview === this.gridview) {
                     const sourceLocation = getGridLocation(sourceGroup.element);
                     const [sourceParentLocation, from] = tail(sourceLocation);
                     if (sequenceEquals(sourceParentLocation, targetParentLocation)) {
@@ -1909,9 +2551,11 @@ export class DockviewComponent extends BaseGrid {
                         return;
                     }
                 }
-                if (sourceGroup.api.location.type === 'popout') {
+                if (sourceGroup.api.location.type === 'popout' &&
+                    this.nestedWindowMembers(sourceGroup).length <= 1) {
                     /**
-                     * the source group is a popout group with a single panel
+                     * the source group is the only group in a popout window and
+                     * has a single panel
                      *
                      * 1. remove the panel from the group without triggering any events
                      * 2. remove the popout group — this may cascade-remove the empty
@@ -1919,15 +2563,21 @@ export class DockviewComponent extends BaseGrid {
                      *    doRemoveGroup for popout groups), which can shift grid indices
                      * 3. recompute the target location now that the grid is stable
                      * 4. create a new group at the recomputed location and add that panel
+                     *
+                     * Multi-group popout windows fall through to the generic
+                     * detach-and-re-add path so the window stays alive.
                      */
-                    const popoutGroup = this._popoutGroups.find((group) => group.popoutGroup === sourceGroup);
+                    const popoutGroup = (_b = this._popoutWindowService) === null || _b === void 0 ? void 0 : _b.findByGroup(sourceGroup);
+                    if (!popoutGroup) {
+                        return;
+                    }
                     const removedPanel = this.movingLock(() => popoutGroup.popoutGroup.model.removePanel(popoutGroup.popoutGroup.panels[0], {
                         skipSetActive: true,
                         skipSetActiveGroup: true,
                     }));
                     this.doRemoveGroup(sourceGroup, { skipActive: true });
-                    const updatedTargetLocation = getRelativeLocation(this.gridview.orientation, getGridLocation(destinationGroup.element), destinationTarget);
-                    const newGroup = this.createGroupAtLocation(updatedTargetLocation);
+                    const updatedTargetLocation = getRelativeLocation(destinationGridview.orientation, getGridLocation(destinationGroup.element), destinationTarget);
+                    const newGroup = this.createGroupAtLocation(updatedTargetLocation, undefined, undefined, destinationGridview);
                     this.movingLock(() => newGroup.model.openPanel(removedPanel, {
                         skipSetActive: true,
                     }));
@@ -1951,7 +2601,7 @@ export class DockviewComponent extends BaseGrid {
                     if (!removedPanel) {
                         throw new Error(`dockview: No panel with id ${sourceItemId}`);
                     }
-                    const newGroup = this.createGroupAtLocation(targetLocation);
+                    const newGroup = this.createGroupAtLocation(targetLocation, undefined, undefined, destinationGridview);
                     this.movingLock(() => newGroup.model.openPanel(removedPanel, {
                         skipSetGroupActive: true,
                     }));
@@ -1969,8 +2619,9 @@ export class DockviewComponent extends BaseGrid {
                 }));
                 // after deleting the group we need to re-evaulate the ref location
                 const updatedReferenceLocation = getGridLocation(destinationGroup.element);
-                const location = getRelativeLocation(this.gridview.orientation, updatedReferenceLocation, destinationTarget);
-                this.movingLock(() => this.doAddGroup(targetGroup, location));
+                const location = getRelativeLocation(destinationGridview.orientation, updatedReferenceLocation, destinationTarget);
+                this.movingLock(() => this.doAddGroup(targetGroup, location, undefined, destinationGridview));
+                this.setGroupLocationForRoot(targetGroup, destinationGridview);
                 this.doSetGroupAndPanelActive(targetGroup);
                 this._onDidMovePanel.fire({
                     panel: this.getGroupPanel(sourceItemId),
@@ -1989,8 +2640,8 @@ export class DockviewComponent extends BaseGrid {
                 if (!removedPanel) {
                     throw new Error(`dockview: No panel with id ${sourceItemId}`);
                 }
-                const dropLocation = getRelativeLocation(this.gridview.orientation, referenceLocation, destinationTarget);
-                const group = this.createGroupAtLocation(dropLocation);
+                const dropLocation = getRelativeLocation(destinationGridview.orientation, referenceLocation, destinationTarget);
+                const group = this.createGroupAtLocation(dropLocation, undefined, undefined, destinationGridview);
                 this.movingLock(() => group.model.openPanel(removedPanel, {
                     skipSetGroupActive: true,
                 }));
@@ -2085,6 +2736,21 @@ export class DockviewComponent extends BaseGrid {
         addPanelsToGroup(targetGroup);
     }
     moveGroup(options) {
+        this.mutation('move', () => this._doMoveGroup(options));
+    }
+    // Bracket maximize/restore as a 'maximize' transaction. The maximized node
+    // is serialized by the gridview (`SerializedGridview.maximizedNode`), so
+    // the state round-trips through toJSON/fromJSON and is restorable on undo.
+    // When the exit is a side-effect of another bracketed operation (e.g. a
+    // move that activates a different group) the depth counter folds it in.
+    maximizeGroup(panel) {
+        this.mutation('maximize', () => super.maximizeGroup(panel));
+    }
+    exitMaximizedGroup() {
+        this.mutation('maximize', () => super.exitMaximizedGroup());
+    }
+    _doMoveGroup(options) {
+        var _a, _b, _c;
         const from = options.from.group;
         const to = options.to.group;
         const target = options.to.position;
@@ -2165,6 +2831,13 @@ export class DockviewComponent extends BaseGrid {
                 }));
                 const movedPanels = this.movingLock(() => [...from.panels].map((p) => from.model.removePanel(p.id, { skipSetActive: true })));
                 source = this.createGroup();
+                // The new source group enters the layout via gridview.addView
+                // below, which bypasses doAddGroup and so doesn't fire
+                // BaseGrid._onDidAdd. Modules (TabGroupChips, etc.) drive
+                // per-group attachment off _onDidAddGroup, so we fire it
+                // explicitly here — matches the pattern in addFloatingGroup
+                // and addEdgeGroup.
+                this._onDidAddGroup.fire(source);
                 this.movingLock(() => {
                     for (const panel of movedPanels) {
                         source.model.openPanel(panel, {
@@ -2191,23 +2864,34 @@ export class DockviewComponent extends BaseGrid {
                         this.gridview.removeView(getGridLocation(from.element));
                         break;
                     case 'floating': {
-                        const selectedFloatingGroup = this._floatingGroups.find((x) => x.group === from);
+                        const selectedFloatingGroup = (_a = this._floatingGroupService) === null || _a === void 0 ? void 0 : _a.findByGroup(from);
                         if (!selectedFloatingGroup) {
                             throw new Error('dockview: failed to find floating group');
                         }
-                        selectedFloatingGroup.dispose();
+                        // Detach just this group from the floating window's
+                        // nested gridview, keeping the window (and its other
+                        // groups) alive. If it was the only member, dispose the
+                        // whole window.
+                        if (!this.detachFromNestedWindow(from)) {
+                            selectedFloatingGroup.dispose();
+                        }
                         break;
                     }
                     case 'popout': {
-                        const selectedPopoutGroup = this._popoutGroups.find((x) => x.popoutGroup === from);
+                        const selectedPopoutGroup = (_b = this._popoutWindowService) === null || _b === void 0 ? void 0 : _b.findByGroup(from);
                         if (!selectedPopoutGroup) {
                             throw new Error('dockview: failed to find popout group');
                         }
-                        // Remove from popout groups list to prevent automatic restoration
-                        const index = this._popoutGroups.indexOf(selectedPopoutGroup);
-                        if (index >= 0) {
-                            this._popoutGroups.splice(index, 1);
+                        // Detach just this group from the popout window's
+                        // nested gridview, keeping the window + its other groups
+                        // alive. Destination containers/location are applied by
+                        // the placement block below.
+                        if (this.detachFromNestedWindow(from)) {
+                            break;
                         }
+                        // Last group leaving — tear the window down. Remove from
+                        // the service first to prevent automatic restoration.
+                        (_c = this._popoutWindowService) === null || _c === void 0 ? void 0 : _c.remove(selectedPopoutGroup);
                         // Clean up the reference group (ghost) if it exists and is hidden
                         if (selectedPopoutGroup.referenceGroup) {
                             const referenceGroup = this.getPanel(selectedPopoutGroup.referenceGroup);
@@ -2218,34 +2902,25 @@ export class DockviewComponent extends BaseGrid {
                                 });
                             }
                         }
-                        // Manually dispose the window without triggering restoration
+                        // Dispose the window without triggering restoration. The
+                        // placement block below applies the destination
+                        // location and containers to `from`.
                         selectedPopoutGroup.window.dispose();
-                        // Update group's location and containers for target
-                        if (to.api.location.type === 'grid') {
-                            from.model.renderContainer =
-                                this.overlayRenderContainer;
-                            from.model.dropTargetContainer =
-                                this.rootDropTargetContainer;
-                            from.model.location = { type: 'grid' };
-                        }
-                        else if (to.api.location.type === 'floating') {
-                            from.model.renderContainer =
-                                this.overlayRenderContainer;
-                            from.model.dropTargetContainer =
-                                this.rootDropTargetContainer;
-                            from.model.location = { type: 'floating' };
-                        }
                         break;
                     }
                 }
             }
-            // For moves to grid locations
-            if (to.api.location.type === 'grid') {
+            // Place `source` next to `to`, in whichever gridview root `to`
+            // lives in. When `to` is inside a floating / popout window this
+            // splits that window's nested layout rather than spawning a new one.
+            if (to.api.location.type === 'grid' ||
+                to.api.location.type === 'floating' ||
+                to.api.location.type === 'popout') {
+                const destGridview = this.getGridviewForGroup(to);
                 const referenceLocation = getGridLocation(to.element);
-                const dropLocation = getRelativeLocation(this.gridview.orientation, referenceLocation, target);
-                // Add to grid for all moves targeting grid location
+                const dropLocation = getRelativeLocation(destGridview.orientation, referenceLocation, target);
                 let size;
-                switch (this.gridview.orientation) {
+                switch (destGridview.orientation) {
                     case Orientation.VERTICAL:
                         size =
                             referenceLocation.length % 2 == 0
@@ -2259,43 +2934,8 @@ export class DockviewComponent extends BaseGrid {
                                 : from.api.width;
                         break;
                 }
-                this.gridview.addView(source, size, dropLocation);
-            }
-            else if (to.api.location.type === 'floating') {
-                // For moves to floating locations, add as floating group
-                // Get the position/size from the target floating group
-                const targetFloatingGroup = this._floatingGroups.find((x) => x.group === to);
-                if (targetFloatingGroup) {
-                    const box = targetFloatingGroup.overlay.toJSON();
-                    // Calculate position based on available properties
-                    let left, top;
-                    if ('left' in box) {
-                        left = box.left + 50;
-                    }
-                    else if ('right' in box) {
-                        left = Math.max(0, box.right - box.width - 50);
-                    }
-                    else {
-                        left = 50; // Default fallback
-                    }
-                    if ('top' in box) {
-                        top = box.top + 50;
-                    }
-                    else if ('bottom' in box) {
-                        top = Math.max(0, box.bottom - box.height - 50);
-                    }
-                    else {
-                        top = 50; // Default fallback
-                    }
-                    this.addFloatingGroup(source, {
-                        height: box.height,
-                        width: box.width,
-                        position: {
-                            left,
-                            top,
-                        },
-                    });
-                }
+                destGridview.addView(source, size, dropLocation);
+                this.setGroupLocationForRoot(source, destGridview);
             }
         }
         source.panels.forEach((panel) => {
@@ -2316,14 +2956,16 @@ export class DockviewComponent extends BaseGrid {
         }
     }
     doSetGroupActive(group) {
+        var _a;
         super.doSetGroupActive(group);
         const activePanel = this.activePanel;
         if (!this._moving &&
-            activePanel !== this._onDidActivePanelChange.value) {
-            this._onDidActivePanelChange.fire(activePanel);
+            activePanel !== ((_a = this._onDidActivePanelChange.value) === null || _a === void 0 ? void 0 : _a.panel)) {
+            this.fireActivePanelChange(activePanel);
         }
     }
     doSetGroupAndPanelActive(group) {
+        var _a;
         super.doSetGroupActive(group);
         const activePanel = this.activePanel;
         if (group &&
@@ -2332,8 +2974,8 @@ export class DockviewComponent extends BaseGrid {
             this.exitMaximizedGroup();
         }
         if (!this._moving &&
-            activePanel !== this._onDidActivePanelChange.value) {
-            this._onDidActivePanelChange.fire(activePanel);
+            activePanel !== ((_a = this._onDidActivePanelChange.value) === null || _a === void 0 ? void 0 : _a.panel)) {
+            this.fireActivePanelChange(activePanel);
         }
     }
     getNextGroupId() {
@@ -2344,9 +2986,7 @@ export class DockviewComponent extends BaseGrid {
         return id;
     }
     createGroup(options) {
-        if (!options) {
-            options = {};
-        }
+        options !== null && options !== void 0 ? options : (options = {});
         let id = options === null || options === void 0 ? void 0 : options.id;
         if (id && this._groups.has(options.id)) {
             console.warn(`dockview: Duplicate group id ${options === null || options === void 0 ? void 0 : options.id}. reassigning group id to avoid errors`);
@@ -2362,9 +3002,11 @@ export class DockviewComponent extends BaseGrid {
         view.init({ params: {}, accessor: this });
         if (!this._groups.has(view.id)) {
             const disposable = new CompositeDisposable(view.model.onTabDragStart((event) => {
-                this._onWillDragPanel.fire(event);
+                var _a;
+                (_a = this._advancedDnDService) === null || _a === void 0 ? void 0 : _a.dispatchWillDragPanel(event);
             }), view.model.onGroupDragStart((event) => {
-                this._onWillDragGroup.fire(event);
+                var _a;
+                (_a = this._advancedDnDService) === null || _a === void 0 ? void 0 : _a.dispatchWillDragGroup(event);
             }), view.model.onMove((event) => {
                 const { groupId, itemId, target, index, tabGroupId } = event;
                 this.moveGroupOrPanel({
@@ -2382,15 +3024,19 @@ export class DockviewComponent extends BaseGrid {
             }), view.model.onDidDrop((event) => {
                 this._onDidDrop.fire(event);
             }), view.model.onWillDrop((event) => {
-                this._onWillDrop.fire(event);
+                var _a;
+                (_a = this._advancedDnDService) === null || _a === void 0 ? void 0 : _a.dispatchWillDrop(event);
             }), view.model.onWillShowOverlay((event) => {
+                var _a;
                 if (this.options.disableDnd) {
+                    // Engine policy — stays in core, ahead of any
+                    // customisation dispatch.
                     event.preventDefault();
                     return;
                 }
-                this._onWillShowOverlay.fire(event);
-            }), view.model.onUnhandledDragOverEvent((event) => {
-                this._onUnhandledDragOverEvent.fire(event);
+                (_a = this._advancedDnDService) === null || _a === void 0 ? void 0 : _a.dispatchWillShowOverlay(event);
+            }), view.model.onUnhandledDragOver((event) => {
+                this._onUnhandledDragOver.fire(event);
             }), view.model.onDidAddPanel((event) => {
                 if (this._moving) {
                     return;
@@ -2402,27 +3048,17 @@ export class DockviewComponent extends BaseGrid {
                 }
                 this._onDidRemovePanel.fire(event.panel);
             }), view.model.onDidActivePanelChange((event) => {
+                var _a;
                 if (this._moving) {
                     return;
                 }
                 if (event.panel !== this.activePanel) {
                     return;
                 }
-                if (this._onDidActivePanelChange.value !== event.panel) {
-                    this._onDidActivePanelChange.fire(event.panel);
-                }
-            }), view.model.onDidCreateTabGroup((e) => {
-                this._onDidCreateTabGroup.fire(e);
-            }), view.model.onDidDestroyTabGroup((e) => {
-                this._onDidDestroyTabGroup.fire(e);
-            }), view.model.onDidAddPanelToTabGroup((e) => {
-                this._onDidAddPanelToTabGroup.fire(e);
-            }), view.model.onDidRemovePanelFromTabGroup((e) => {
-                this._onDidRemovePanelFromTabGroup.fire(e);
-            }), view.model.onDidTabGroupChange((e) => {
-                this._onDidTabGroupChange.fire(e);
-            }), view.model.onDidTabGroupCollapsedChange((e) => {
-                this._onDidTabGroupCollapsedChange.fire(e);
+                if (((_a = this._onDidActivePanelChange.value) === null || _a === void 0 ? void 0 : _a.panel) !==
+                    event.panel) {
+                    this.fireActivePanelChange(event.panel);
+                }
             }), Event.any(view.model.onDidPanelTitleChange, view.model.onDidPanelParametersChange)(() => {
                 this._bufferOnDidLayoutChange.fire();
             }));
@@ -2450,11 +3086,73 @@ export class DockviewComponent extends BaseGrid {
         });
         return panel;
     }
-    createGroupAtLocation(location, size, options) {
+    createGroupAtLocation(location, size, options, gridview = this.gridview) {
         const group = this.createGroup(options);
-        this.doAddGroup(group, location, size);
+        this.doAddGroup(group, location, size, gridview);
+        this.setGroupLocationForRoot(group, gridview);
         return group;
     }
+    /**
+     * Tag a group with the location and render / drop-target containers
+     * matching the gridview root it now lives in: the main grid, a floating
+     * window (shares the main containers), or a popout window (uses its own
+     * window-local containers).
+     */
+    setGroupLocationForRoot(group, gridview) {
+        var _a;
+        const popout = (_a = this._popoutWindowService) === null || _a === void 0 ? void 0 : _a.entries.find((entry) => entry.gridview === gridview);
+        if (popout) {
+            if (group.model.renderContainer !== popout.overlayRenderContainer) {
+                group.model.renderContainer = popout.overlayRenderContainer;
+            }
+            group.model.dropTargetContainer = popout.dropTargetContainer;
+            group.model.location = {
+                type: 'popout',
+                getWindow: popout.getWindow,
+                popoutUrl: popout.popoutUrl,
+            };
+            return;
+        }
+        // grid / floating both render through the main containers
+        if (group.model.renderContainer !== this.overlayRenderContainer) {
+            group.model.renderContainer = this.overlayRenderContainer;
+        }
+        group.model.dropTargetContainer = this.rootDropTargetContainer;
+        group.model.location =
+            gridview === this.gridview
+                ? { type: 'grid' }
+                : { type: 'floating' };
+    }
+    /**
+     * Resolve which gridview root currently owns a group: the main grid, or
+     * the nested gridview of the floating / popout window it lives in.
+     */
+    getGridviewForGroup(group) {
+        var _a, _b;
+        const floating = (_a = this._floatingGroupService) === null || _a === void 0 ? void 0 : _a.findByGroup(group);
+        if (floating) {
+            return floating.gridview;
+        }
+        // Use findByGroup (anchor-identity OR containment) for symmetry with
+        // the floating branch — it also resolves an anchor whose element is
+        // briefly detached from the gridview during a move/restore.
+        const popout = (_b = this._popoutWindowService) === null || _b === void 0 ? void 0 : _b.findByGroup(group);
+        if (popout) {
+            return popout.gridview;
+        }
+        return this.gridview;
+    }
+    /**
+     * The groups that live within the same floating / popout window as `group`
+     * (including `group` itself). Empty when `group` is in the main grid.
+     */
+    nestedWindowMembers(group) {
+        const gridview = this.getGridviewForGroup(group);
+        if (gridview === this.gridview) {
+            return [];
+        }
+        return this.groups.filter((candidate) => gridview.element.contains(candidate.element));
+    }
     findGroup(panel) {
         var _a;
         return (_a = Array.from(this._groups.values()).find((group) => group.value.model.containsPanel(panel))) === null || _a === void 0 ? void 0 : _a.value;
@@ -2465,44 +3163,33 @@ export class DockviewComponent extends BaseGrid {
             ? rootOrientation
             : orthogonal(rootOrientation);
     }
-    updateDropTargetModel(options) {
-        if ('dndEdges' in options) {
-            const disabled = typeof options.dndEdges === 'boolean' &&
-                options.dndEdges === false;
-            this._rootDropTarget.disabled = disabled;
-            this._rootPointerDropTarget.disabled = disabled;
-            if (typeof options.dndEdges === 'object' &&
-                options.dndEdges !== null) {
-                this._rootDropTarget.setOverlayModel(options.dndEdges);
-                this._rootPointerDropTarget.setOverlayModel(options.dndEdges);
-            }
-            else {
-                this._rootDropTarget.setOverlayModel(DEFAULT_ROOT_OVERLAY_MODEL);
-                this._rootPointerDropTarget.setOverlayModel(DEFAULT_ROOT_OVERLAY_MODEL);
-            }
-        }
-        if ('rootOverlayModel' in options) {
-            this.updateDropTargetModel({ dndEdges: options.dndEdges });
-        }
-    }
     updateTheme() {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
         const theme = (_a = this._options.theme) !== null && _a !== void 0 ? _a : themeAbyss;
         // Apply the theme class only to the shell so edge groups and the
         // main grid both inherit its CSS custom properties via the cascade.
         // Re-declaring it on `.dv-dockview` would block consumer overrides
         // set on the shell from reaching the dockview subtree.
         (_b = this._shellThemeClassnames) === null || _b === void 0 ? void 0 : _b.setClassNames(theme.className);
-        this.gridview.margin = (_c = theme.gap) !== null && _c !== void 0 ? _c : 0;
-        (_d = this._shellManager) === null || _d === void 0 ? void 0 : _d.updateTheme((_e = theme.gap) !== null && _e !== void 0 ? _e : 0, (_f = theme.edgeGroupCollapsedSize) !== null && _f !== void 0 ? _f : 35);
-        if (theme.dndOverlayBorder !== undefined) {
-            this.element.style.setProperty('--dv-drag-over-border', theme.dndOverlayBorder);
-            (_g = this._shellManager) === null || _g === void 0 ? void 0 : _g.element.style.setProperty('--dv-drag-over-border', theme.dndOverlayBorder);
-        }
-        else {
+        const gap = (_c = theme.gap) !== null && _c !== void 0 ? _c : 0;
+        this.gridview.margin = gap;
+        // Floating / popout windows host their own nested gridviews; keep their
+        // gap in sync with the main grid when the theme changes at runtime.
+        for (const floating of this.floatingGroups) {
+            floating.gridview.margin = gap;
+        }
+        for (const entry of (_e = (_d = this._popoutWindowService) === null || _d === void 0 ? void 0 : _d.entries) !== null && _e !== void 0 ? _e : []) {
+            entry.gridview.margin = gap;
+        }
+        (_f = this._shellManager) === null || _f === void 0 ? void 0 : _f.updateTheme(gap, (_g = theme.edgeGroupCollapsedSize) !== null && _g !== void 0 ? _g : 35);
+        if (theme.dndOverlayBorder === undefined) {
             this.element.style.removeProperty('--dv-drag-over-border');
             (_h = this._shellManager) === null || _h === void 0 ? void 0 : _h.element.style.removeProperty('--dv-drag-over-border');
         }
+        else {
+            this.element.style.setProperty('--dv-drag-over-border', theme.dndOverlayBorder);
+            (_j = this._shellManager) === null || _j === void 0 ? void 0 : _j.element.style.setProperty('--dv-drag-over-border', theme.dndOverlayBorder);
+        }
         switch (theme.dndOverlayMounting) {
             case 'absolute':
                 this.rootDropTargetContainer.disabled = false;
@@ -2514,7 +3201,7 @@ export class DockviewComponent extends BaseGrid {
         }
         // Toggle a CSS class so theme stylesheets can scope pure-CSS
         // tab group indicator rules to the 'none' mode only.
-        const indicatorNone = ((_j = theme.tabGroupIndicator) !== null && _j !== void 0 ? _j : 'wrap') === 'none';
+        const indicatorNone = ((_k = theme.tabGroupIndicator) !== null && _k !== void 0 ? _k : 'wrap') === 'none';
         toggleClass(this.element, 'dv-tab-group-indicator-none', indicatorNone);
         if (this._shellManager) {
             toggleClass(this._shellManager.element, 'dv-tab-group-indicator-none', indicatorNone);