regular-layout 0.3.0 → 0.4.0

package/dist/layout/calculate_edge.d.ts

@@ -1,5 +1,5 @@
-import { type Physics } from "./constants";
-import type { Layout, LayoutPath } from "./types";
+import { type Physics } from "../core/constants";
+import type { Layout, LayoutPath } from "../core/types";
 /**
  * Calculates an insertion point (which may involve splitting a single
  * `"tab-layout"` into a new `"split-layout"`), based on the  cursor position.

package/dist/layout/calculate_intersect.d.ts

@@ -1,4 +1,4 @@
-import type { LayoutPath, LayoutDivider, Layout } from "./types.ts";
+import type { LayoutPath, LayoutDivider, Layout } from "../core/types.ts";
 /**
  * Determines which panel or divider is located at a given position in the
  * layout.

package/dist/layout/calculate_path.d.ts

@@ -1,4 +1,4 @@
-import type { Layout } from "./types.ts";
+import type { Layout } from "../core/types.ts";
 /**
  * Calculates the index path for a panel with the given name.
  *

package/dist/layout/calculate_presize_paths.d.ts

@@ -0,0 +1,10 @@
+import type { Layout, LayoutPath } from "../core/types.ts";
+/**
+ * Walks a layout tree and returns a {@link LayoutPath} for every visible
+ * panel, keyed by panel name. Each path's `column`/`row` are set to the
+ * center of the panel's view window, with offsets of 0.5.
+ *
+ * @param layout - The layout tree to walk.
+ * @returns A record mapping panel names to their layout paths.
+ */
+export declare function calculate_presize_paths(layout: Layout): Record<string, LayoutPath>;

package/dist/layout/flatten.d.ts

@@ -1,4 +1,4 @@
-import type { Layout } from "./types.ts";
+import type { Layout } from "../core/types.ts";
 /**
  * Flattens the layout tree by merging parent and child split panels that have
  * the same orientation and type.

package/dist/layout/generate_grid.d.ts

@@ -1,5 +1,5 @@
-import { type Physics } from "./constants.ts";
-import type { Layout } from "./types.ts";
+import { type Physics } from "../core/constants.ts";
+import type { Layout } from "../core/types.ts";
 /**
  * Generates CSS Grid styles to render a layout tree.
  * Creates grid-template-rows, grid-template-columns, and positioning rules for

package/dist/layout/generate_overlay.d.ts

@@ -1,2 +1,18 @@
-import type { LayoutPath } from "./types";
-export declare function updateOverlaySheet(slot: string, box: DOMRect, style: CSSStyleDeclaration, drag_target: LayoutPath | null, physics?: import("./constants").Physics): string;
+import type { LayoutPath, ViewWindow } from "../core/types";
+/**
+ * Converts a {@link ViewWindow} to element-relative pixel coordinates,
+ * accounting for padding and optionally CSS `gap` and child `margin`.
+ *
+ * @param window - The view window in normalized 0–1 coordinates.
+ * @param box - The element's bounding client rect.
+ * @param style - The element's computed style (for padding).
+ * @param margin - Optional child element's computed style (for margin inset).
+ * @returns Pixel coordinates relative to the element's border-box origin.
+ */
+export declare function viewWindowToLocalRect(window: ViewWindow, box: DOMRect, style: CSSStyleDeclaration, margin?: CSSStyleDeclaration): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export declare function updateOverlaySheet(slot: string, box: DOMRect, style: CSSStyleDeclaration, drag_target: LayoutPath | null, physics?: import("../core/constants").Physics, margin?: CSSStyleDeclaration): string;

package/dist/layout/insert_child.d.ts

@@ -1,4 +1,4 @@
-import type { Layout, LayoutPathTraversal } from "./types.ts";
+import type { Layout, LayoutPathTraversal } from "../core/types.ts";
 /**
  * Inserts a new child panel into the layout tree at a specified location.
  * Creates a split panel if necessary and redistributes sizes equally among all

package/dist/layout/redistribute_panel_sizes.d.ts

@@ -1,4 +1,4 @@
-import type { Layout, LayoutPathTraversal } from "./types.ts";
+import type { Layout, LayoutPathTraversal } from "../core/types.ts";
 /**
  * Adjusts panel sizes during a drag operation on a divider.
  *
@@ -16,4 +16,4 @@ import type { Layout, LayoutPathTraversal } from "./types.ts";
  * @returns A new layout tree with updated sizes (original is not mutated).
  * ```
  */
-export declare function redistribute_panel_sizes(panel: Layout, path: LayoutPathTraversal, delta: number | undefined, physics?: import("./constants.ts").Physics): Layout;
+export declare function redistribute_panel_sizes(panel: Layout, path: LayoutPathTraversal, delta: number | undefined, physics?: import("../core/constants.ts").Physics): Layout;

package/dist/layout/remove_child.d.ts

@@ -1,4 +1,4 @@
-import type { Layout } from "./types.ts";
+import type { Layout } from "../core/types.ts";
 /**
  * Removes a child panel from the layout tree by its name.
  *

package/dist/model/overlay_controller.d.ts

@@ -0,0 +1,34 @@
+import type { Layout, LayoutPath, OverlayMode } from "../core/types.ts";
+import type { Physics } from "../core/constants.ts";
+import type { PresizeQueue } from "./presize_queue.ts";
+export interface OverlayHost {
+    readonly panel: Layout;
+    readonly physics: Physics;
+    readonly stylesheet: CSSStyleSheet;
+    readonly presizeQueue: PresizeQueue;
+    relativeCoordinates(event: {
+        clientX: number;
+        clientY: number;
+    }, recalculate: boolean): [number, number, DOMRect, CSSStyleDeclaration];
+    restore(layout: Layout, isFlattened?: boolean): Promise<void>;
+    querySelector(selectors: string): Element | null;
+    dispatchEvent(event: Event): boolean;
+}
+/**
+ * Manages overlay state during drag-and-drop panel rearrangement.
+ *
+ * Handles rendering a preview of where a dragged panel would land,
+ * and committing or cancelling the placement when the drag ends.
+ */
+export declare class OverlayController {
+    private _host;
+    constructor(_host: OverlayHost);
+    set(event: {
+        clientX: number;
+        clientY: number;
+    }, { slot }: LayoutPath, className?: string, mode?: OverlayMode): Promise<void>;
+    clear(event: {
+        clientX: number;
+        clientY: number;
+    } | null, { slot, layout }: LayoutPath, className?: string): Promise<void>;
+}

package/dist/model/presize_queue.d.ts

@@ -0,0 +1,17 @@
+import type { Layout } from "../core/types.ts";
+/**
+ * Manages cancelable pre-resize gating for layout updates.
+ *
+ * Before each layout change, a cancelable `resize-before` event is dispatched
+ * on the target. If the event is cancelled via `preventDefault()`, the update
+ * is suspended until {@link resume} is called. Concurrent updates are queued
+ * and processed sequentially.
+ */
+export declare class PresizeQueue {
+    #private;
+    private _target;
+    private _eventName;
+    constructor(_target: EventTarget, _eventName: string);
+    run(layout: Layout, fn: () => void): Promise<void>;
+    resume(): void;
+}

package/dist/regular-layout-tab.d.ts

@@ -1,4 +1,4 @@
-import type { TabLayout } from "./layout/types.ts";
+import type { TabLayout } from "./core/types.ts";
 import type { RegularLayout } from "./regular-layout.ts";
 /**
  * A custom HTML element representing an individual tab in a tab panel.

package/dist/regular-layout.d.ts

@@ -1,5 +1,5 @@
-import type { LayoutPath, Layout, TabLayout, OverlayMode, Orientation, LayoutPathTraversal } from "./layout/types.ts";
-import { type PhysicsUpdate, type Physics } from "./layout/constants.ts";
+import type { LayoutPath, Layout, TabLayout, OverlayMode, Orientation, LayoutPathTraversal, ViewWindow } from "./core/types.ts";
+import { type PhysicsUpdate, type Physics } from "./core/constants.ts";
 /**
  * An interface which models the fields of `PointerEvent` that
  * `<regular-layour>` actually uses, making it easier to sub out with an
@@ -67,6 +67,8 @@ export declare class RegularLayout extends HTMLElement {
     private _cursor_override;
     private _dimensions?;
     private _physics;
+    private _presizeQueue;
+    private _overlayController;
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -99,7 +101,7 @@ export declare class RegularLayout extends HTMLElement {
      *     the target, "absolute" positions the panel absolutely. Defaults to
      *     "absolute".
      */
-    setOverlayState: (event: PointerEventCoordinates, { slot }: LayoutPath, className?: string, mode?: OverlayMode) => void;
+    setOverlayState: (event: PointerEventCoordinates, target: LayoutPath, className?: string, mode?: OverlayMode) => Promise<void>;
     /**
      * Clears the overlay state and commits the panel placement.
      *
@@ -112,7 +114,7 @@ export declare class RegularLayout extends HTMLElement {
      * @param mode - Overlay rendering mode that was used, must match the mode
      *     passed to `setOverlayState`. Defaults to "absolute".
      */
-    clearOverlayState: (event: PointerEventCoordinates | null, { slot, layout }: LayoutPath, className?: string) => void;
+    clearOverlayState: (event: PointerEventCoordinates | null, target: LayoutPath, className?: string) => Promise<void>;
     /**
      * Inserts a new panel into the layout at a specified path.
      *
@@ -124,13 +126,13 @@ export declare class RegularLayout extends HTMLElement {
      *     the new `SplitPanel` _if_ there is an option of orientation (e.g. if
      *     the layout had no pre-existing `SplitPanel`)
      */
-    insertPanel: (name: string, path?: LayoutPathTraversal, split?: boolean | Orientation) => void;
+    insertPanel: (name: string, path?: LayoutPathTraversal, split?: boolean | Orientation) => Promise<void>;
     /**
      * Removes a panel from the layout by name.
      *
      * @param name - Name of the panel to remove
      */
-    removePanel: (name: string) => void;
+    removePanel: (name: string) => Promise<void>;
     /**
      * Retrieves a panel by name from the layout tree.
      *
@@ -142,20 +144,36 @@ export declare class RegularLayout extends HTMLElement {
     /**
      * Clears the entire layout, unslotting all panels.
      */
-    clear: () => void;
+    clear: () => Promise<void>;
+    /**
+     * Restores the layout from a saved state synchronously, without
+     * dispatching the `regular-layout-before-resize` event.
+     *
+     * @param layout - The layout tree to restore
+     */
+    restoreSync: (layout: Layout, _is_flattened?: boolean) => void;
     /**
      * Restores the layout from a saved state.
      *
+     * Before applying, dispatches a cancelable `regular-layout-before-resize`
+     * event. If the event is cancelled via `preventDefault()`, the layout
+     * update is suspended until {@link resumeResize} is called.
+     *
      * @param layout - The layout tree to restore
      *
      * @example
      * ```typescript
      * const layout = document.querySelector('regular-layout');
      * const savedState = JSON.parse(localStorage.getItem('layout'));
-     * layout.restore(savedState);
+     * await layout.restore(savedState);
      * ```
      */
-    restore: (layout: Layout, _is_flattened?: boolean) => void;
+    restore: (layout: Layout, _is_flattened?: boolean) => Promise<void>;
+    /**
+     * Resumes a layout update that was suspended by cancelling the
+     * `regular-layout-before-resize` event.
+     */
+    resumeResize: () => void;
     /**
      * Serializes the current layout state, which can be restored via `restore`.
      *
@@ -195,6 +213,15 @@ export declare class RegularLayout extends HTMLElement {
      *   - box: The layout element's bounding rectangle
      */
     relativeCoordinates: (event: PointerEventCoordinates, recalculate_bounds?: boolean) => [number, number, DOMRect, CSSStyleDeclaration];
+    /**
+     * Converts a {@link ViewWindow} (normalized 0–1 coordinates) to a
+     * `DOMRect` in screen pixels, accounting for padding and optionally
+     * CSS `gap` and child `margin`.
+     *
+     * @param window - The view window to convert.
+     * @returns A `DOMRect` representing the window in screen coordinates.
+     */
+    realCoordinates: (window: ViewWindow, child?: HTMLElement) => DOMRect;
     /**
      * Calculates the Euclidean distance in pixels between the current pointer
      * coordinates and a drag target's position within the layout.
@@ -206,6 +233,7 @@ export declare class RegularLayout extends HTMLElement {
      *     target.
      */
     diffCoordinates: (event: PointerEventCoordinates, drag_target: LayoutPath) => number;
+    private create_overlay_host;
     private onDblClick;
     private onPointerDown;
     private onPointerMove;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "regular-layout",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"description": "A regular CSS `grid` container",
 	"keywords": [],
 	"license": "Apache-2.0",
@@ -19,10 +19,10 @@
 	],
 	"scripts": {
 		"build": "tsx build.ts",
-		"build:watch": "tsx build.ts --watch",
+		"watch": "tsx build.ts --watch",
 		"clean": "rm -rf dist",
-		"test": "playwright test tests/integration tests/unit",
-		"test:perf": "playwright test --workers=1 ./benchmarks",
+		"test": "tsx test.ts",
+		"bench": "playwright test --workers=1 ./benchmarks",
 		"example": "tsx serve.ts",
 		"deploy": "tsx deploy.ts",
 		"lint": "biome lint src tests",
@@ -34,6 +34,7 @@
 		"@playwright/test": "^1.57.0",
 		"@types/node": "^22.10.5",
 		"esbuild": "^0.27.2",
+		"monocart-coverage-reports": "^2.12.2",
 		"tsx": "^4.21.0",
 		"typescript": "^5.9.3"
 	}

package/src/{layout → core}/constants.ts

@@ -110,8 +110,8 @@ export const DEFAULT_PHYSICS: Physics = Object.freeze({
 	SHOULD_ROUND: false,
 	OVERLAY_CLASSNAME: "overlay",
 	MINIMUM_REDISTRIBUTION_SIZE_THRESHOLD: 0.15,
-	SPLIT_EDGE_TOLERANCE: 0.25,
-	SPLIT_ROOT_EDGE_TOLERANCE: 0.01,
+	SPLIT_EDGE_TOLERANCE: 0.33,
+	SPLIT_ROOT_EDGE_TOLERANCE: 0.03,
 	GRID_TRACK_COLLAPSE_TOLERANCE: 0.001,
 	OVERLAY_DEFAULT: "absolute",
 	GRID_DIVIDER_SIZE: 6,

package/src/{layout → core}/types.ts

@@ -95,6 +95,13 @@ export interface LayoutPath {
 	layout: Layout;
 }
 
+/**
+ * The detail payload of the `regular-layout-before-resize` event.
+ */
+export interface PresizeDetail {
+	calculatePresizePaths(): Record<string, LayoutPath>;
+}
+
 /**
  * An empty `Layout` with no panels.
  */

package/src/extensions.ts

@@ -11,7 +11,7 @@
 
 import { RegularLayout } from "./regular-layout.ts";
 import { RegularLayoutFrame } from "./regular-layout-frame.ts";
-import type { Layout } from "./layout/types.ts";
+import type { Layout, PresizeDetail } from "./core/types.ts";
 import { RegularLayoutTab } from "./regular-layout-tab.ts";
 
 customElements.define("regular-layout", RegularLayout);
@@ -59,6 +59,12 @@ declare global {
 			options?: { signal: AbortSignal },
 		): void;
 
+		addEventListener(
+			name: "regular-layout-before-resize",
+			cb: (e: RegularLayoutPresizeEvent) => void,
+			options?: { signal: AbortSignal },
+		): void;
+
 		removeEventListener(
 			name: "regular-layout-update",
 			cb: (e: RegularLayoutEvent) => void,
@@ -68,7 +74,13 @@ declare global {
 			name: "regular-layout-before-update",
 			cb: (e: RegularLayoutEvent) => void,
 		): void;
+
+		removeEventListener(
+			name: "regular-layout-before-resize",
+			cb: (e: RegularLayoutPresizeEvent) => void,
+		): void;
 	}
 }
 
 export type RegularLayoutEvent = CustomEvent<Layout>;
+export type RegularLayoutPresizeEvent = CustomEvent<PresizeDetail>;

package/src/index.ts

@@ -59,10 +59,12 @@
  * @packageDocumentation
  */
 
-export type * from "./layout/types.ts";
+export type * from "./core/types.ts";
 
 export { RegularLayout } from "./regular-layout.ts";
 export { RegularLayoutFrame } from "./regular-layout-frame.ts";
 
+export type * from "./extensions.ts";
+
 // Side effects
 import "./extensions.ts";

package/src/layout/calculate_edge.ts

@@ -9,7 +9,7 @@
 // ┃  *  [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). *  ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-import { DEFAULT_PHYSICS, type Physics } from "./constants";
+import { DEFAULT_PHYSICS, type Physics } from "../core/constants";
 import { insert_child } from "./insert_child";
 import type {
 	Layout,
@@ -17,7 +17,7 @@ import type {
 	LayoutPathTraversal,
 	Orientation,
 	ViewWindow,
-} from "./types";
+} from "../core/types";
 
 /**
  * Calculates an insertion point (which may involve splitting a single

package/src/layout/calculate_intersect.ts

@@ -15,7 +15,7 @@ import type {
 	Layout,
 	ViewWindow,
 	LayoutPathTraversal,
-} from "./types.ts";
+} from "../core/types.ts";
 
 const VIEW_WINDOW = {
 	row_start: 0,
@@ -130,7 +130,10 @@ function calculate_intersection_recursive(
 		}
 
 		// Check if position falls within this child's bounds
-		if (position >= current_pos && position < next_pos) {
+		if (
+			position >= current_pos &&
+			(position < next_pos || i === panel.children.length - 1)
+		) {
 			return calculate_intersection_recursive(
 				column,
 				row,

package/src/layout/calculate_path.ts

@@ -9,7 +9,7 @@
 // ┃  *  [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). *  ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-import type { Layout, LayoutPathTraversal } from "./types.ts";
+import type { Layout, LayoutPathTraversal } from "../core/types.ts";
 
 /**
  * Calculates the index path for a panel with the given name.

package/src/layout/calculate_presize_paths.ts

@@ -0,0 +1,93 @@
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ░░░░░░░░▄▀░█▀▄░█▀▀░█▀▀░█░█░█░░░█▀█░█▀▄░░░░░█░░░█▀█░█░█░█▀█░█░█░▀█▀░▀▄░░░░░░░░
+// ░░░░░░░▀▄░░█▀▄░█▀▀░█░█░█░█░█░░░█▀█░█▀▄░▀▀▀░█░░░█▀█░░█░░█░█░█░█░░█░░░▄▀░░░░░░░
+// ░░░░░░░░░▀░▀░▀░▀▀▀░▀▀▀░▀▀▀░▀▀▀░▀░▀░▀░▀░░░░░▀▀▀░▀░▀░░▀░░▀▀▀░▀▀▀░░▀░░▀░░░░░░░░░
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃  *  Copyright (c) 2026, the Regular Layout Authors. This file is part  *  ┃
+// ┃  *  of the Regular Layout library, distributed under the terms of the  *  ┃
+// ┃  *  [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). *  ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+import type {
+	Layout,
+	LayoutPath,
+	Orientation,
+	ViewWindow,
+} from "../core/types.ts";
+
+/**
+ * Walks a layout tree and returns a {@link LayoutPath} for every visible
+ * panel, keyed by panel name. Each path's `column`/`row` are set to the
+ * center of the panel's view window, with offsets of 0.5.
+ *
+ * @param layout - The layout tree to walk.
+ * @returns A record mapping panel names to their layout paths.
+ */
+export function calculate_presize_paths(
+	layout: Layout,
+): Record<string, LayoutPath> {
+	const result: Record<string, LayoutPath> = {};
+	walk_layout(layout, result, [], null, {
+		row_start: 0,
+		row_end: 1,
+		col_start: 0,
+		col_end: 1,
+	});
+
+	return result;
+}
+
+function walk_layout(
+	layout: Layout,
+	result: Record<string, LayoutPath>,
+	path: number[],
+	parentOrientation: Orientation | null,
+	viewWindow: ViewWindow,
+): void {
+	if (layout.type === "tab-layout") {
+		const selected = layout.selected ?? 0;
+		const slot = layout.tabs[selected];
+		const col = (viewWindow.col_start + viewWindow.col_end) / 2;
+		const row = (viewWindow.row_start + viewWindow.row_end) / 2;
+		result[slot] = {
+			type: "layout-path",
+			layout,
+			slot,
+			path,
+			view_window: viewWindow,
+			is_edge: false,
+			column: col,
+			row: row,
+			column_offset: 0.5,
+			row_offset: 0.5,
+			orientation: parentOrientation || "horizontal",
+		};
+
+		return;
+	}
+
+	const isVertical = layout.orientation === "vertical";
+	const startKey = isVertical ? "row_start" : "col_start";
+	const endKey = isVertical ? "row_end" : "col_end";
+	let currentPos = viewWindow[startKey];
+	const totalSize = viewWindow[endKey] - viewWindow[startKey];
+	for (let i = 0; i < layout.children.length; i++) {
+		const nextPos = currentPos + totalSize * layout.sizes[i];
+		const childWindow: ViewWindow = {
+			...viewWindow,
+			[startKey]: currentPos,
+			[endKey]: nextPos,
+		};
+
+		walk_layout(
+			layout.children[i],
+			result,
+			[...path, i],
+			layout.orientation,
+			childWindow,
+		);
+
+		currentPos = nextPos;
+	}
+}

package/src/layout/flatten.ts

@@ -9,7 +9,7 @@
 // ┃  *  [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). *  ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-import type { Layout } from "./types.ts";
+import type { Layout } from "../core/types.ts";
 
 /**
  * Flattens the layout tree by merging parent and child split panels that have

package/src/layout/generate_grid.ts

@@ -9,8 +9,8 @@
 // ┃  *  [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). *  ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-import { DEFAULT_PHYSICS, type Physics } from "./constants.ts";
-import type { Layout } from "./types.ts";
+import { DEFAULT_PHYSICS, type Physics } from "../core/constants.ts";
+import type { Layout } from "../core/types.ts";
 
 interface GridCell {
 	child: string;

package/src/layout/generate_overlay.ts

@@ -9,8 +9,46 @@
 // ┃  *  [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). *  ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-import { DEFAULT_PHYSICS } from "./constants";
-import type { LayoutPath } from "./types";
+import { DEFAULT_PHYSICS } from "../core/constants";
+import type { LayoutPath, ViewWindow } from "../core/types";
+
+/**
+ * Converts a {@link ViewWindow} to element-relative pixel coordinates,
+ * accounting for padding and optionally CSS `gap` and child `margin`.
+ *
+ * @param window - The view window in normalized 0–1 coordinates.
+ * @param box - The element's bounding client rect.
+ * @param style - The element's computed style (for padding).
+ * @param margin - Optional child element's computed style (for margin inset).
+ * @returns Pixel coordinates relative to the element's border-box origin.
+ */
+export function viewWindowToLocalRect(
+	window: ViewWindow,
+	box: DOMRect,
+	style: CSSStyleDeclaration,
+	margin?: CSSStyleDeclaration,
+): { x: number; y: number; width: number; height: number } {
+	const paddingLeft = parseFloat(style.paddingLeft);
+	const paddingTop = parseFloat(style.paddingTop);
+	const contentWidth = box.width - paddingLeft - parseFloat(style.paddingRight);
+	const contentHeight =
+		box.height - paddingTop - parseFloat(style.paddingBottom);
+
+	const x = paddingLeft + window.col_start * contentWidth;
+	const y = paddingTop + window.row_start * contentHeight;
+	let width = (window.col_end - window.col_start) * contentWidth;
+	let height = (window.row_end - window.row_start) * contentHeight;
+	if (margin) {
+		const marginTop = parseFloat(margin.marginTop);
+		const marginRight = parseFloat(margin.marginRight);
+		const marginBottom = parseFloat(margin.marginBottom);
+		const marginLeft = parseFloat(margin.marginLeft);
+		width -= marginLeft + marginRight;
+		height -= marginTop + marginBottom;
+	}
+
+	return { x, y, width, height };
+}
 
 export function updateOverlaySheet(
 	slot: string,
@@ -18,25 +56,19 @@ export function updateOverlaySheet(
 	style: CSSStyleDeclaration,
 	drag_target: LayoutPath | null,
 	physics = DEFAULT_PHYSICS,
+	margin?: CSSStyleDeclaration,
 ) {
 	if (!drag_target) {
 		return `:host ::slotted([${physics.CHILD_ATTRIBUTE_NAME}="${slot}"]){display:none;}`;
 	}
 
-	const {
-		view_window: { row_start, row_end, col_start, col_end },
-	} = drag_target;
-
-	const box_height =
-		box.height - parseFloat(style.paddingTop) - parseFloat(style.paddingBottom);
-
-	const box_width =
-		box.width - parseFloat(style.paddingLeft) - parseFloat(style.paddingRight);
+	const local = viewWindowToLocalRect(
+		drag_target.view_window,
+		box,
+		style,
+		margin,
+	);
 
-	const top = row_start * box_height + parseFloat(style.paddingTop);
-	const left = col_start * box_width + parseFloat(style.paddingLeft);
-	const height = (row_end - row_start) * box_height;
-	const width = (col_end - col_start) * box_width;
-	const css = `display:flex;position:absolute!important;z-index:1;top:${top}px;left:${left}px;height:${height}px;width:${width}px;`;
+	const css = `display:flex;position:absolute!important;z-index:1;top:${local.y}px;left:${local.x}px;height:${local.height}px;width:${local.width}px;`;
 	return `::slotted([${physics.CHILD_ATTRIBUTE_NAME}="${slot}"]){${css}}`;
 }

package/src/layout/insert_child.ts

@@ -9,7 +9,7 @@
 // ┃  *  [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). *  ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-import type { Layout, LayoutPathTraversal } from "./types.ts";
+import type { Layout, LayoutPathTraversal } from "../core/types.ts";
 
 /**
  * Inserts a new child panel into the layout tree at a specified location.

package/src/layout/redistribute_panel_sizes.ts

@@ -9,8 +9,8 @@
 // ┃  *  [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). *  ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-import { DEFAULT_PHYSICS } from "./constants.ts";
-import type { Layout, LayoutPathTraversal } from "./types.ts";
+import { DEFAULT_PHYSICS } from "../core/constants.ts";
+import type { Layout, LayoutPathTraversal } from "../core/types.ts";
 
 /**
  * Adjusts panel sizes during a drag operation on a divider.