regular-layout 0.0.1

package/src/common/calculate_split.ts

@@ -0,0 +1,53 @@
+import { calculate_intersection } from "./calculate_intersect";
+import { insert_child } from "./insert_child";
+import {
+	SPLIT_EDGE_TOLERANCE,
+	type Layout,
+	type LayoutPath,
+} from "./layout_config";
+
+export function calculate_split(
+	col: number,
+	row: number,
+	panel: Layout,
+	slot: string,
+	config: LayoutPath,
+): LayoutPath {
+	if (
+		config.column_offset < SPLIT_EDGE_TOLERANCE ||
+		config.column_offset > 1 - SPLIT_EDGE_TOLERANCE
+	) {
+		if (config.orientation === "vertical") {
+			const new_panel = insert_child(panel, slot, [
+				...config.path,
+				config.column_offset < SPLIT_EDGE_TOLERANCE ? 0 : 1,
+			]);
+
+			config = calculate_intersection(col, row, new_panel, false);
+		} else {
+			const new_panel = insert_child(panel, slot, config.path);
+			config = calculate_intersection(col, row, new_panel, false);
+		}
+	}
+
+	if (
+		(config.row_offset < SPLIT_EDGE_TOLERANCE &&
+			config.row_offset < config.column_offset) ||
+		(config.row_offset > 1 - SPLIT_EDGE_TOLERANCE &&
+			config.row_offset > config.column_offset)
+	) {
+		if (config.orientation === "horizontal") {
+			const new_panel = insert_child(panel, slot, [
+				...config.path,
+				config.row_offset < SPLIT_EDGE_TOLERANCE ? 0 : 1,
+			]);
+
+			config = calculate_intersection(col, row, new_panel, false);
+		} else {
+			const new_panel = insert_child(panel, slot, config.path);
+			config = calculate_intersection(col, row, new_panel, false);
+		}
+	}
+
+	return config;
+}

package/src/common/flatten.ts

@@ -0,0 +1,57 @@
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ░░░░░░░░▄▀░█▀▄░█▀▀░█▀▀░█░█░█░░░█▀█░█▀▄░░░░░█░░░█▀█░█░█░█▀█░█░█░▀█▀░▀▄░░░░░░░░
+// ░░░░░░░▀▄░░█▀▄░█▀▀░█░█░█░█░█░░░█▀█░█▀▄░▀▀▀░█░░░█▀█░░█░░█░█░█░█░░█░░░▄▀░░░░░░░
+// ░░░░░░░░░▀░▀░▀░▀▀▀░▀▀▀░▀▀▀░▀▀▀░▀░▀░▀░▀░░░░░▀▀▀░▀░▀░░▀░░▀▀▀░▀▀▀░░▀░░▀░░░░░░░░░
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃  *  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 } from "./layout_config.ts";
+
+/**
+ * Flattens the layout tree by merging parent and child split panels that have
+ * the same orientation and type.
+ *
+ * When a split panel contains a child split panel with the same orientation,
+ * they are merged into a single split panel. The sizes array is scaled
+ * correctly to maintain proportions.
+ *
+ * @param layout - The layout tree to flatten
+ * @returns A new flattened layout tree (original is not mutated).
+ */
+export function flatten(layout: Layout): Layout {
+	if (layout.type === "child-panel") {
+		return layout;
+	}
+
+	const flattenedChildren: Layout[] = [];
+	const flattenedSizes: number[] = [];
+	for (let i = 0; i < layout.children.length; i++) {
+		const child = layout.children[i];
+		const childSize = layout.sizes[i];
+		const flattenedChild = flatten(child);
+
+		if (
+			flattenedChild.type === "split-panel" &&
+			flattenedChild.orientation === layout.orientation
+		) {
+			for (let j = 0; j < flattenedChild.children.length; j++) {
+				flattenedChildren.push(flattenedChild.children[j]);
+				flattenedSizes.push(flattenedChild.sizes[j] * childSize);
+			}
+		} else {
+			flattenedChildren.push(flattenedChild);
+			flattenedSizes.push(childSize);
+		}
+	}
+
+	return {
+		type: "split-panel",
+		orientation: layout.orientation,
+		children: flattenedChildren,
+		sizes: flattenedSizes,
+	};
+}

package/src/common/generate_grid.ts

@@ -0,0 +1,249 @@
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ░░░░░░░░▄▀░█▀▄░█▀▀░█▀▀░█░█░█░░░█▀█░█▀▄░░░░░█░░░█▀█░█░█░█▀█░█░█░▀█▀░▀▄░░░░░░░░
+// ░░░░░░░▀▄░░█▀▄░█▀▀░█░█░█░█░█░░░█▀█░█▀▄░▀▀▀░█░░░█▀█░░█░░█░█░█░█░░█░░░▄▀░░░░░░░
+// ░░░░░░░░░▀░▀░▀░▀▀▀░▀▀▀░▀▀▀░▀▀▀░▀░▀░▀░▀░░░░░▀▀▀░▀░▀░░▀░░▀▀▀░▀▀▀░░▀░░▀░░░░░░░░░
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃  *  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 { GRID_TRACK_COLLAPSE_TOLERANCE, type Layout } from "./layout_config.ts";
+import { remove_child } from "./remove_child.ts";
+
+interface GridCell {
+	child: string;
+	colStart: number;
+	colEnd: number;
+	rowStart: number;
+	rowEnd: number;
+}
+
+function dedupePositions(positions: number[]): number[] {
+	if (positions.length === 0) {
+		return [];
+	}
+
+	const sorted = positions.sort((a, b) => a - b);
+	const result = [sorted[0]];
+	for (let i = 1; i < sorted.length; i++) {
+		if (
+			Math.abs(sorted[i] - result[result.length - 1]) >
+			GRID_TRACK_COLLAPSE_TOLERANCE
+		) {
+			result.push(sorted[i]);
+		}
+	}
+
+	return result;
+}
+
+function collectTrackPositions(
+	panel: Layout,
+	orientation: "horizontal" | "vertical",
+	start: number,
+	end: number,
+): number[] {
+	if (panel.type === "child-panel") {
+		return [start, end];
+	}
+
+	if (panel.orientation === orientation) {
+		const positions: number[] = [start, end];
+		let current = start;
+		for (let i = 0; i < panel.children.length; i++) {
+			const size = panel.sizes[i];
+			const childPositions = collectTrackPositions(
+				panel.children[i],
+				orientation,
+				current,
+				current + size * (end - start),
+			);
+
+			positions.push(...childPositions);
+			current = current + size * (end - start);
+		}
+
+		return dedupePositions(positions);
+	} else {
+		const allPositions: number[] = [start, end];
+		for (const child of panel.children) {
+			const childPositions = collectTrackPositions(
+				child,
+				orientation,
+				start,
+				end,
+			);
+
+			allPositions.push(...childPositions);
+		}
+
+		return dedupePositions(allPositions);
+	}
+}
+
+function findTrackIndex(positions: number[], value: number): number {
+	for (let i = 0; i < positions.length; i++) {
+		if (Math.abs(positions[i] - value) < 0.0001) {
+			return i;
+		}
+	}
+
+	throw new Error(`Position ${value} not found in ${positions}`);
+}
+
+function buildCells(
+	panel: Layout,
+	colPositions: number[],
+	rowPositions: number[],
+	colStart: number,
+	colEnd: number,
+	rowStart: number,
+	rowEnd: number,
+): GridCell[] {
+	if (panel.type === "child-panel") {
+		return [
+			{
+				child: panel.child,
+				colStart: findTrackIndex(colPositions, colStart),
+				colEnd: findTrackIndex(colPositions, colEnd),
+				rowStart: findTrackIndex(rowPositions, rowStart),
+				rowEnd: findTrackIndex(rowPositions, rowEnd),
+			},
+		];
+	}
+
+	const cells: GridCell[] = [];
+	const { children, sizes, orientation } = panel;
+	if (orientation === "horizontal") {
+		let current = colStart;
+		for (let i = 0; i < children.length; i++) {
+			const next = current + sizes[i] * (colEnd - colStart);
+			cells.push(
+				...buildCells(
+					children[i],
+					colPositions,
+					rowPositions,
+					current,
+					next,
+					rowStart,
+					rowEnd,
+				),
+			);
+
+			current = next;
+		}
+	} else {
+		let current = rowStart;
+		for (let i = 0; i < children.length; i++) {
+			const next = current + sizes[i] * (rowEnd - rowStart);
+			cells.push(
+				...buildCells(
+					children[i],
+					colPositions,
+					rowPositions,
+					colStart,
+					colEnd,
+					current,
+					next,
+				),
+			);
+
+			current = next;
+		}
+	}
+
+	return cells;
+}
+
+const host_template = (rowTemplate: string, colTemplate: string) =>
+	`:host { display: grid; gap: 0px; grid-template-rows: ${rowTemplate}; grid-template-columns: ${colTemplate}; }`;
+
+const child_template = (slot: string, rowPart: string, colPart: string) =>
+	`:host ::slotted([slot=${slot}]) { grid-column: ${colPart}; grid-row: ${rowPart}; }`;
+
+/**
+ * Generates CSS Grid styles to render a layout tree.
+ * Creates grid-template-rows, grid-template-columns, and positioning rules for
+ * all child panels.
+ *
+ * @param layout - The layout tree to convert to CSS
+ * @param round - If true, rounds percentages to whole numbers. Useful for
+ * avoiding sub-pixel rendering issues. Defaults to false.
+ * @returns CSS string containing :host and ::slotted rules implementing the
+ * layout.
+ *
+ * @example
+ * ```typescript
+ * const layout = {
+ *   type: "split-panel",
+ *   orientation: "horizontal",
+ *   children: [
+ *     { type: "child-panel", child: "sidebar" },
+ *     { type: "child-panel", child: "main" }
+ *   ],
+ *   sizes: [0.25, 0.75]
+ * };
+ *
+ * const css = create_css_grid_layout(layout);
+ * // Returns CSS like:
+ * // :host { display: grid; grid-template-columns: 25% 75%; ... }
+ * // :host ::slotted([slot=sidebar]) { grid-column: 1; grid-row: 1; }
+ * // :host ::slotted([slot=main]) { grid-column: 2; grid-row: 1; }
+ * ```
+ */
+export function create_css_grid_layout(
+	layout: Layout,
+	round: boolean = false,
+	overlay?: [string, string],
+): string {
+	if (overlay) {
+		layout = remove_child(layout, overlay[0]);
+	}
+
+	if (layout.type === "child-panel") {
+		return `${host_template("100%", "100%")}\n${child_template(layout.child, "1", "1")}`;
+	}
+
+	const colPositions = collectTrackPositions(layout, "horizontal", 0, 1);
+	const colSizes: number[] = [];
+	for (let i = 0; i < colPositions.length - 1; i++) {
+		colSizes.push(colPositions[i + 1] - colPositions[i]);
+	}
+
+	const colTemplate = colSizes
+		.map((s) => `${round ? Math.round(s * 100) : s * 100}%`)
+		.join(" ");
+
+	const rowPositions = collectTrackPositions(layout, "vertical", 0, 1);
+	const rowSizes: number[] = [];
+	for (let i = 0; i < rowPositions.length - 1; i++) {
+		rowSizes.push(rowPositions[i + 1] - rowPositions[i]);
+	}
+
+	const rowTemplate = rowSizes
+		.map((s) => `${round ? Math.round(s * 100) : s * 100}%`)
+		.join(" ");
+
+	const cells = buildCells(layout, colPositions, rowPositions, 0, 1, 0, 1);
+	const css = [host_template(rowTemplate, colTemplate)];
+	for (const cell of cells) {
+		const colPart =
+			cell.colEnd - cell.colStart === 1
+				? `${cell.colStart + 1}`
+				: `${cell.colStart + 1} / ${cell.colEnd + 1}`;
+		const rowPart =
+			cell.rowEnd - cell.rowStart === 1
+				? `${cell.rowStart + 1}`
+				: `${cell.rowStart + 1} / ${cell.rowEnd + 1}`;
+
+		css.push(`${child_template(cell.child, rowPart, colPart)}`);
+		if (cell.child === overlay?.[1]) {
+			css.push(`${child_template(overlay[0], rowPart, colPart)}`);
+			css.push(`:host ::slotted([slot=${overlay[0]}]) { z-index: 1; }`);
+		}
+	}
+
+	return css.join("\n");
+}

package/src/common/generate_overlay.ts

@@ -0,0 +1,25 @@
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ░░░░░░░░▄▀░█▀▄░█▀▀░█▀▀░█░█░█░░░█▀█░█▀▄░░░░░█░░░█▀█░█░█░█▀█░█░█░▀█▀░▀▄░░░░░░░░
+// ░░░░░░░▀▄░░█▀▄░█▀▀░█░█░█░█░█░░░█▀█░█▀▄░▀▀▀░█░░░█▀█░░█░░█░█░█░█░░█░░░▄▀░░░░░░░
+// ░░░░░░░░░▀░▀░▀░▀▀▀░▀▀▀░▀▀▀░▀▀▀░▀░▀░▀░▀░░░░░▀▀▀░▀░▀░░▀░░▀▀▀░▀▀▀░░▀░░▀░░░░░░░░░
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃  *  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 { LayoutPath } from "./layout_config";
+
+export function updateOverlaySheet({
+	view_window: { row_start, row_end, col_start, col_end },
+	box,
+}: LayoutPath<DOMRect>) {
+	const margin = 0;
+	const top = row_start * box.height + margin / 2;
+	const left = col_start * box.width + margin / 2;
+	const height = (row_end - row_start) * box.height - margin;
+	const width = (col_end - col_start) * box.width - margin;
+	const css = `position:absolute!important;z-index:1;top:${top}px;left:${left}px;height:${height}px;width:${width}px;`;
+	return `::slotted(:not([slot])){${css}}`;
+}

package/src/common/insert_child.ts

@@ -0,0 +1,129 @@
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ░░░░░░░░▄▀░█▀▄░█▀▀░█▀▀░█░█░█░░░█▀█░█▀▄░░░░░█░░░█▀█░█░█░█▀█░█░█░▀█▀░▀▄░░░░░░░░
+// ░░░░░░░▀▄░░█▀▄░█▀▀░█░█░█░█░█░░░█▀█░█▀▄░▀▀▀░█░░░█▀█░░█░░█░█░█░█░░█░░░▄▀░░░░░░░
+// ░░░░░░░░░▀░▀░▀░▀▀▀░▀▀▀░▀▀▀░▀▀▀░▀░▀░▀░▀░░░░░▀▀▀░▀░▀░░▀░░▀▀▀░▀▀▀░░▀░░▀░░░░░░░░░
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃  *  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 } from "./layout_config.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
+ * children.
+ *
+ * @param panel - The root layout tree to insert into
+ * @param child - Unique identifier for the new child panel
+ * @param path - Array of indices defining where to insert. Empty array inserts
+ * at root level.
+ * @param orientation - Orientation for newly created split panels. Defaults to
+ * "horizontal".
+ * @returns A new layout tree with the child inserted (original is not mutated).
+ */
+export function insert_child(
+	panel: Layout,
+	child: string,
+	path: number[],
+	orientation: "horizontal" | "vertical" = "horizontal",
+): Layout {
+	if (path.length === 0) {
+		// Insert at root level
+		if (panel.type === "child-panel") {
+			// Convert single child-panel to split-panel with two children
+			return {
+				type: "split-panel",
+				orientation,
+				children: [
+					panel,
+					{
+						type: "child-panel",
+						child,
+					},
+				],
+				sizes: [0.5, 0.5],
+			};
+		} else {
+			// Append to existing split-panel
+			const newChildren = [
+				...panel.children,
+				{
+					type: "child-panel",
+					child,
+				} as Layout,
+			];
+
+			const numChildren = newChildren.length;
+			const newSizes = Array(numChildren).fill(1 / numChildren);
+			return {
+				...panel,
+				children: newChildren,
+				sizes: newSizes,
+			};
+		}
+	}
+
+	// Navigate down the path
+	const [index, ...restPath] = path;
+	if (panel.type === "child-panel") {
+		// This shouldn't happen if path.length > 0, but handle it gracefully
+		// We need to split this child-panel
+		const newPanel: Layout = {
+			type: "split-panel",
+			orientation,
+			children: [panel],
+			sizes: [1],
+		};
+
+		return insert_child(newPanel, child, path, orientation);
+	}
+
+	if (restPath.length === 0 || index === panel.children.length) {
+		// Insert at this level at the specified index
+		const newChildren = [...panel.children];
+		newChildren.splice(index, 0, {
+			type: "child-panel",
+			child,
+		});
+
+		const numChildren = newChildren.length;
+		const newSizes = Array(numChildren).fill(1 / numChildren);
+		return {
+			...panel,
+			children: newChildren,
+			sizes: newSizes,
+		};
+	}
+
+	const targetChild = panel.children[index];
+	if (targetChild.type === "child-panel" && restPath.length > 0) {
+		// Need to split this child-panel
+		const oppositeOrientation =
+			panel.orientation === "horizontal" ? "vertical" : "horizontal";
+
+		const newSplitPanel = insert_child(
+			targetChild,
+			child,
+			restPath,
+			oppositeOrientation,
+		);
+
+		const newChildren = [...panel.children];
+		newChildren[index] = newSplitPanel;
+		return {
+			...panel,
+			children: newChildren,
+		};
+	}
+
+	const updatedChild = insert_child(targetChild, child, restPath, orientation);
+	const newChildren = [...panel.children];
+	newChildren[index] = updatedChild;
+	return {
+		...panel,
+		children: newChildren,
+	};
+}

package/src/common/layout_config.ts

@@ -0,0 +1,127 @@
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ░░░░░░░░▄▀░█▀▄░█▀▀░█▀▀░█░█░█░░░█▀█░█▀▄░░░░░█░░░█▀█░█░█░█▀█░█░█░▀█▀░▀▄░░░░░░░░
+// ░░░░░░░▀▄░░█▀▄░█▀▀░█░█░█░█░█░░░█▀█░█▀▄░▀▀▀░█░░░█▀█░░█░░█░█░█░█░░█░░░▄▀░░░░░░░
+// ░░░░░░░░░▀░▀░▀░▀▀▀░▀▀▀░▀▀▀░▀▀▀░▀░▀░▀░▀░░░░░▀▀▀░▀░▀░░▀░░▀▀▀░▀▀▀░░▀░░▀░░░░░░░░░
+// ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃  *  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). *  ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+/**
+ * The percentage of the maximum resize distance that will be clamped.
+ *
+ */
+export const MINIMUM_REDISTRIBUTION_SIZE_THRESHOLD = 0.15;
+
+/**
+ * Threshold from panel edge that is considered a split vs drop action.
+ */
+export const SPLIT_EDGE_TOLERANCE = 0.15;
+
+/**
+ * Tolerance threshold for considering two grid track positions as identical.
+ *
+ * When collecting and deduplicating track positions, any positions closer than
+ * this value are treated as the same position to avoid redundant grid tracks.
+ */
+export const GRID_TRACK_COLLAPSE_TOLERANCE = 0.0001;
+
+/**
+ * The representation of a CSS grid, in JSON form.
+ */
+export type Layout = SplitLayout | TabLayout;
+
+/**
+ * The orientation (of a `SplitPanel`).
+ */
+export type Orientation = "horizontal" | "vertical";
+
+/**
+ * A logical rectange in percent-coordinates (of a (1, 1) square).
+ */
+export interface ViewWindow {
+	row_start: number;
+	row_end: number;
+	col_start: number;
+	col_end: number;
+}
+
+/**
+ * A split panel that divides space among multiple child layouts
+ * .
+ * Child panels are arranged either horizontally (side by side) or vertically
+ * (stacked), via the `orientation` property `"horizzontal"` and `"vertical"`
+ * (respectively).
+ */
+export interface SplitLayout {
+	type: "split-panel";
+	children: Layout[];
+	sizes: number[];
+	orientation: Orientation;
+}
+
+/**
+ * A leaf panel node that contains a single named child element.
+ */
+export interface TabLayout {
+	type: "child-panel";
+	child: string;
+}
+
+/**
+ * Represents a draggable divider between two panels in the layout.
+ *
+ * Used for hit detection.
+ */
+export interface LayoutDivider {
+	path: number[];
+	view_window: ViewWindow;
+	type: Orientation;
+}
+
+/**
+ * Represents a panel location result from hit detection.
+ *
+ * Contains both the panel identifier and its grid position in relative units.
+ * The generic parameter `T` allows DOM-only properties (e.g. `DOMRect`) to be
+ * shared in this cross-platform module.
+ */
+export interface LayoutPath<T = undefined> {
+	type: "layout-path";
+	slot: string;
+	path: number[];
+	view_window: ViewWindow;
+	column_offset: number;
+	row_offset: number;
+	orientation: Orientation;
+	box: T;
+}
+
+/**
+ * Recursively iterates over all child panel names in the layout tree, yielding
+ * panel names in depth-first order.
+ *
+ * @param panel - The layout tree to iterate over
+ * @returns Generator yielding child panel names
+ */
+export function* iter_panel_children(panel: Layout): Generator<string> {
+	if (panel.type === "split-panel") {
+		for (const child of panel.children) {
+			yield* iter_panel_children(child);
+		}
+	} else {
+		yield panel.child;
+	}
+}
+
+/**
+ * An empty `Layout` with no panels.
+ */
+export const EMPTY_PANEL: Layout = {
+	type: "split-panel",
+	orientation: "horizontal",
+	sizes: [],
+	children: [],
+};