13 files changed, 1009 insertions, 0 deletions
diff --git a/apps/web/src/selection/attributes.ts b/apps/web/src/selection/attributes.ts
new file mode 100644
index 00000000..a1aee842
--- /dev/null
+++ b/apps/web/src/selection/attributes.ts
@@ -0,0 +1 @@
+export const SELECTABLE_ITEM_ATTRIBUTE = "data-selectable-item";
diff --git a/apps/web/src/selection/context.tsx b/apps/web/src/selection/context.tsx
new file mode 100644
index 00000000..8e87aa40
--- /dev/null
+++ b/apps/web/src/selection/context.tsx
@@ -0,0 +1,52 @@
+"use client";
+
+import { createContext, useContext } from "react";
+
+interface SelectionContextValue {
+	selectedIds: string[];
+	anchorId: string | null;
+	highlightedId: string | null;
+	isBoxSelecting: boolean;
+	isSelected: (id: string) => boolean;
+	clearSelection: () => void;
+	handleItemClick: ({
+		event,
+		id,
+	}: {
+		event: React.MouseEvent<HTMLDivElement> | React.KeyboardEvent<HTMLDivElement>;
+		id: string;
+	}) => void;
+	handleItemMouseDown: ({
+		event,
+		id,
+	}: {
+		event: React.MouseEvent<HTMLDivElement>;
+		id: string;
+	}) => void;
+	registerItem: (id: string, element: HTMLElement | null) => void;
+}
+
+export const SelectionContext = createContext<SelectionContextValue | null>(null);
+
+export function useSelectionContext() {
+	const context = useContext(SelectionContext);
+
+	if (!context) {
+		throw new Error("useSelectionContext must be used within SelectableSurface");
+	}
+
+	return context;
+}
+
+export function useSelection() {
+	const { selectedIds, anchorId, highlightedId, isSelected, clearSelection } =
+		useSelectionContext();
+
+	return {
+		selectedIds,
+		anchorId,
+		highlightedId,
+		isSelected,
+		clearSelection,
+	};
+}
diff --git a/apps/web/src/selection/editor-selection.ts b/apps/web/src/selection/editor-selection.ts
new file mode 100644
index 00000000..21ab6466
--- /dev/null
+++ b/apps/web/src/selection/editor-selection.ts
@@ -0,0 +1,25 @@
+import type { SelectedKeyframeRef } from "@/animation/types";
+import type { ElementRef } from "@/timeline/types";
+
+export interface SelectedMaskPointSelection {
+	trackId: string;
+	elementId: string;
+	maskId: string;
+	pointIds: string[];
+}
+
+export interface EditorSelectionSnapshot {
+	selectedElements: ElementRef[];
+	selectedKeyframes: SelectedKeyframeRef[];
+	keyframeSelectionAnchor: SelectedKeyframeRef | null;
+	selectedMaskPoints: SelectedMaskPointSelection | null;
+}
+
+export interface EditorSelectionPatch {
+	selectedElements?: ElementRef[];
+	selectedKeyframes?: SelectedKeyframeRef[];
+	keyframeSelectionAnchor?: SelectedKeyframeRef | null;
+	selectedMaskPoints?: SelectedMaskPointSelection | null;
+}
+
+export type EditorSelectionKind = "mask-points" | "keyframes" | "elements";
diff --git a/apps/web/src/selection/hit-testing.ts b/apps/web/src/selection/hit-testing.ts
new file mode 100644
index 00000000..d8186238
--- /dev/null
+++ b/apps/web/src/selection/hit-testing.ts
@@ -0,0 +1,50 @@
+function isIntersecting({
+	selectionRect,
+	itemRect,
+}: {
+	selectionRect: DOMRect;
+	itemRect: DOMRect;
+}) {
+	return !(
+		itemRect.right < selectionRect.left ||
+		itemRect.left > selectionRect.right ||
+		itemRect.bottom < selectionRect.top ||
+		itemRect.top > selectionRect.bottom
+	);
+}
+
+function createSelectionRect({
+	startPos,
+	currentPos,
+}: {
+	startPos: { x: number; y: number };
+	currentPos: { x: number; y: number };
+}) {
+	return new DOMRect(
+		Math.min(startPos.x, currentPos.x),
+		Math.min(startPos.y, currentPos.y),
+		Math.abs(currentPos.x - startPos.x),
+		Math.abs(currentPos.y - startPos.y),
+	);
+}
+
+export function resolveElementIntersections({
+	startPos,
+	currentPos,
+	elements,
+}: {
+	startPos: { x: number; y: number };
+	currentPos: { x: number; y: number };
+	elements: Map<string, HTMLElement>;
+}) {
+	const selectionRect = createSelectionRect({ startPos, currentPos });
+
+	return [...elements.entries()]
+		.filter(([, element]) =>
+			isIntersecting({
+				selectionRect,
+				itemRect: element.getBoundingClientRect(),
+			}),
+		)
+		.map(([id]) => id);
+}
diff --git a/apps/web/src/selection/hooks/use-box-select.ts b/apps/web/src/selection/hooks/use-box-select.ts
new file mode 100644
index 00000000..90a584b5
--- /dev/null
+++ b/apps/web/src/selection/hooks/use-box-select.ts
@@ -0,0 +1,170 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import type {
+	BoxSelectionSnapshot,
+	ResolveIntersections,
+} from "@/selection/types";
+
+interface SelectionBoxState<TId> extends BoxSelectionSnapshot<TId> {
+	startPos: { x: number; y: number };
+	currentPos: { x: number; y: number };
+	isActive: boolean;
+	isAdditive: boolean;
+}
+
+export function useBoxSelect<TId>({
+	containerRef,
+	resolveIntersections,
+	selectedIds,
+	anchorId,
+	onSelectionChange,
+	shouldStartSelection,
+	getIsAdditiveSelection,
+	isEnabled = true,
+}: {
+	containerRef: React.RefObject<HTMLElement | null>;
+	resolveIntersections: ResolveIntersections<TId>;
+	selectedIds: TId[];
+	anchorId: TId | null;
+	onSelectionChange: (state: {
+		intersectedIds: TId[];
+		initialSelectedIds: TId[];
+		initialAnchorId: TId | null;
+		isAdditive: boolean;
+	}) => void;
+	shouldStartSelection?: (event: React.MouseEvent<Element>) => boolean;
+	getIsAdditiveSelection?: (event: React.MouseEvent<Element>) => boolean;
+	isEnabled?: boolean;
+}) {
+	const [selectionBox, setSelectionBox] =
+		useState<SelectionBoxState<TId> | null>(null);
+	const justFinishedSelectingRef = useRef(false);
+	const shouldStartSelectionCheck = shouldStartSelection ?? (() => true);
+	const getIsAdditiveSelectionCheck =
+		getIsAdditiveSelection ??
+		((event: React.MouseEvent<Element>) => event.ctrlKey || event.metaKey);
+
+	const handleMouseDown = useCallback(
+		(event: React.MouseEvent<Element>) => {
+			const canStartSelection = shouldStartSelectionCheck(event);
+			if (!isEnabled || event.button !== 0 || !canStartSelection) {
+				return;
+			}
+
+			setSelectionBox({
+				startPos: { x: event.clientX, y: event.clientY },
+				currentPos: { x: event.clientX, y: event.clientY },
+				isActive: false,
+				isAdditive: getIsAdditiveSelectionCheck(event),
+				initialSelectedIds: selectedIds,
+				initialAnchorId: anchorId,
+			});
+		},
+		[
+			anchorId,
+			getIsAdditiveSelectionCheck,
+			isEnabled,
+			selectedIds,
+			shouldStartSelectionCheck,
+		],
+	);
+
+	const updateSelection = useCallback(
+		({
+			startPos,
+			currentPos,
+			isAdditive,
+			initialSelectedIds,
+			initialAnchorId,
+		}: SelectionBoxState<TId>) => {
+			const intersectedIds = resolveIntersections({
+				startPos,
+				currentPos,
+			});
+			onSelectionChange({
+				intersectedIds,
+				initialSelectedIds,
+				initialAnchorId,
+				isAdditive,
+			});
+		},
+		[onSelectionChange, resolveIntersections],
+	);
+
+	useEffect(() => {
+		if (!selectionBox) {
+			return;
+		}
+
+		const handleMouseMove = ({ clientX, clientY }: MouseEvent) => {
+			const deltaX = Math.abs(clientX - selectionBox.startPos.x);
+			const deltaY = Math.abs(clientY - selectionBox.startPos.y);
+			const nextSelectionBox = {
+				...selectionBox,
+				currentPos: { x: clientX, y: clientY },
+				isActive: deltaX > 5 || deltaY > 5 || selectionBox.isActive,
+			};
+
+			setSelectionBox(nextSelectionBox);
+
+			if (!nextSelectionBox.isActive) {
+				return;
+			}
+
+			updateSelection(nextSelectionBox);
+		};
+
+		const handleMouseUp = () => {
+			if (selectionBox.isActive) {
+				justFinishedSelectingRef.current = true;
+				requestAnimationFrame(() => {
+					justFinishedSelectingRef.current = false;
+				});
+			}
+
+			setSelectionBox(null);
+		};
+
+		window.addEventListener("mousemove", handleMouseMove);
+		window.addEventListener("mouseup", handleMouseUp);
+
+		return () => {
+			window.removeEventListener("mousemove", handleMouseMove);
+			window.removeEventListener("mouseup", handleMouseUp);
+		};
+	}, [selectionBox, updateSelection]);
+
+	useEffect(() => {
+		if (!selectionBox) {
+			return;
+		}
+
+		const previousBodyUserSelect = document.body.style.userSelect;
+		const previousContainerUserSelect =
+			containerRef.current?.style.userSelect ?? "";
+
+		document.body.style.userSelect = "none";
+		if (containerRef.current) {
+			containerRef.current.style.userSelect = "none";
+		}
+
+		return () => {
+			document.body.style.userSelect = previousBodyUserSelect;
+			if (containerRef.current) {
+				containerRef.current.style.userSelect = previousContainerUserSelect;
+			}
+		};
+	}, [containerRef, selectionBox]);
+
+	const shouldIgnoreClick = useCallback(() => {
+		return justFinishedSelectingRef.current;
+	}, []);
+
+	return {
+		selectionBox,
+		handleMouseDown,
+		isSelecting: selectionBox?.isActive ?? false,
+		shouldIgnoreClick,
+	};
+}
diff --git a/apps/web/src/selection/hooks/use-selection-scope.ts b/apps/web/src/selection/hooks/use-selection-scope.ts
new file mode 100644
index 00000000..ad4d2ce8
--- /dev/null
+++ b/apps/web/src/selection/hooks/use-selection-scope.ts
@@ -0,0 +1,28 @@
+import { useEffect, useRef } from "react";
+import { useSelectionContext } from "@/selection/context";
+import { activateScope, type ScopeEntry } from "@/selection/scope";
+
+export function useSelectionScope() {
+	const { selectedIds, clearSelection } = useSelectionContext();
+	const hasSelectionRef = useRef(selectedIds.length > 0);
+	const clearSelectionRef = useRef(clearSelection);
+	const hasSelection = selectedIds.length > 0;
+
+	hasSelectionRef.current = hasSelection;
+	clearSelectionRef.current = clearSelection;
+
+	const entryRef = useRef<ScopeEntry>({
+		hasSelection: () => hasSelectionRef.current,
+		clear: () => {
+			clearSelectionRef.current();
+		},
+	});
+
+	useEffect(() => {
+		if (!hasSelection) {
+			return;
+		}
+
+		return activateScope({ entry: entryRef.current });
+	}, [hasSelection]);
+}
diff --git a/apps/web/src/selection/index.ts b/apps/web/src/selection/index.ts
new file mode 100644
index 00000000..9d62731b
--- /dev/null
+++ b/apps/web/src/selection/index.ts
@@ -0,0 +1,4 @@
+export { SelectableItem } from "@/selection/selectable-item";
+export { SelectableSurface } from "@/selection/selectable-surface";
+export { useSelection } from "@/selection/context";
+export { useSelectionScope } from "@/selection/hooks/use-selection-scope";
diff --git a/apps/web/src/selection/scope.ts b/apps/web/src/selection/scope.ts
new file mode 100644
index 00000000..22c7710c
--- /dev/null
+++ b/apps/web/src/selection/scope.ts
@@ -0,0 +1,30 @@
+export type ScopeEntry = {
+	hasSelection: () => boolean;
+	clear: () => void;
+	clearActive?: () => void;
+};
+
+let activeScope: ScopeEntry | null = null;
+
+export function activateScope({ entry }: { entry: ScopeEntry }): () => void {
+	if (activeScope && activeScope !== entry) {
+		activeScope.clear();
+	}
+
+	activeScope = entry;
+
+	return () => {
+		if (activeScope === entry) {
+			activeScope = null;
+		}
+	};
+}
+
+export function clearActiveScope(): boolean {
+	if (!activeScope?.hasSelection()) {
+		return false;
+	}
+
+	(activeScope.clearActive ?? activeScope.clear)();
+	return true;
+}
diff --git a/apps/web/src/selection/selectable-item.tsx b/apps/web/src/selection/selectable-item.tsx
new file mode 100644
index 00000000..cc9e1dbf
--- /dev/null
+++ b/apps/web/src/selection/selectable-item.tsx
@@ -0,0 +1,107 @@
+"use client";
+
+import { forwardRef, useCallback } from "react";
+import { useSelectionContext } from "@/selection/context";
+import { SELECTABLE_ITEM_ATTRIBUTE } from "@/selection/attributes";
+import type { SelectableItemProps } from "@/selection/types";
+import { cn } from "@/utils/ui";
+
+function setForwardedRef<T>(ref: React.ForwardedRef<T>, value: T | null) {
+	if (typeof ref === "function") {
+		ref(value);
+		return;
+	}
+
+	if (ref) {
+		ref.current = value;
+	}
+}
+
+export const SelectableItem = forwardRef<HTMLDivElement, SelectableItemProps>(
+	function SelectableItem(
+		{
+			id,
+			children,
+			className,
+			onClick,
+			onKeyDown,
+			onMouseDown,
+			onContextMenu,
+			tabIndex,
+			...rest
+		}: SelectableItemProps,
+		forwardedRef,
+	) {
+		const {
+			highlightedId,
+			isBoxSelecting,
+			isSelected,
+			handleItemClick,
+			handleItemMouseDown,
+			registerItem,
+		} = useSelectionContext();
+		const isItemSelected = isSelected(id);
+		const isItemHighlighted = highlightedId === id;
+		const stateClassName = cn(
+			"relative",
+			isBoxSelecting && "pointer-events-none",
+			isItemSelected && "ring-1 ring-primary rounded-sm bg-primary/10",
+			isItemHighlighted &&
+				(isItemSelected
+					? "rounded-sm shadow-[0_0_0_1px_hsl(var(--primary))]"
+					: "ring-1 ring-primary/60 rounded-sm bg-primary/5"),
+		);
+
+		const handleRef = useCallback(
+			(element: HTMLDivElement | null) => {
+				registerItem(id, element);
+				setForwardedRef(forwardedRef, element);
+			},
+			[forwardedRef, id, registerItem],
+		);
+
+		return (
+			<div
+				ref={handleRef}
+				className={cn(stateClassName, className)}
+				{...{ [SELECTABLE_ITEM_ATTRIBUTE]: "true" }}
+				role="option"
+				aria-selected={isItemSelected}
+				tabIndex={tabIndex ?? 0}
+				onClick={(event) => {
+					onClick?.(event);
+					if (event.defaultPrevented) {
+						return;
+					}
+
+					handleItemClick({ event, id });
+				}}
+				onMouseDown={(event) => {
+					onMouseDown?.(event);
+					if (event.defaultPrevented) {
+						return;
+					}
+
+					handleItemMouseDown({ event, id });
+				}}
+				onKeyDown={(event) => {
+					onKeyDown?.(event);
+					if (event.defaultPrevented || event.target !== event.currentTarget) {
+						return;
+					}
+
+					if (event.key !== "Enter" && event.key !== " ") {
+						return;
+					}
+
+					event.preventDefault();
+					handleItemClick({ event, id });
+				}}
+				onContextMenu={onContextMenu}
+				{...rest}
+			>
+				{children}
+			</div>
+		);
+	},
+);
diff --git a/apps/web/src/selection/selectable-surface.tsx b/apps/web/src/selection/selectable-surface.tsx
new file mode 100644
index 00000000..24166daf
--- /dev/null
+++ b/apps/web/src/selection/selectable-surface.tsx
@@ -0,0 +1,288 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { SelectionBox } from "@/selection/selection-box";
+import { SelectionContext } from "@/selection/context";
+import { SELECTABLE_ITEM_ATTRIBUTE } from "@/selection/attributes";
+import { resolveElementIntersections } from "@/selection/hit-testing";
+import {
+	applyBoxSelection,
+	clearSelection,
+	isSelected as getIsSelected,
+	pruneSelection,
+	replaceSelection,
+	selectRange,
+	toggleSelection,
+} from "@/selection/state";
+import type {
+	SelectableSurfaceProps,
+	SelectionState,
+} from "@/selection/types";
+import { useBoxSelect } from "@/selection/hooks/use-box-select";
+import { cn } from "@/utils/ui";
+
+export function SelectableSurface({
+	orderedIds,
+	children,
+	className,
+	ariaLabel = "Selectable items",
+	revealId = null,
+	onRevealComplete,
+	onSelectionChange,
+}: SelectableSurfaceProps) {
+	const [selectionState, setSelectionState] = useState<SelectionState>(() =>
+		clearSelection(),
+	);
+	const [highlightedId, setHighlightedId] = useState<string | null>(null);
+	const containerRef = useRef<HTMLDivElement>(null);
+	const itemElementsRef = useRef<Map<string, HTMLElement>>(new Map());
+
+	const registerItem = useCallback(
+		(id: string, element: HTMLElement | null) => {
+			if (element) {
+				itemElementsRef.current.set(id, element);
+			} else {
+				itemElementsRef.current.delete(id);
+			}
+		},
+		[],
+	);
+
+	const getSelectableElements = useCallback(() => {
+		return itemElementsRef.current;
+	}, []);
+
+	const getItemElement = useCallback((id: string) => {
+		return itemElementsRef.current.get(id) ?? null;
+	}, []);
+	const shouldStartSelection = useCallback(
+		(event: React.MouseEvent<Element>) => {
+			return !(
+				event.target instanceof Element &&
+				event.target.closest(`[${SELECTABLE_ITEM_ATTRIBUTE}='true']`)
+			);
+		},
+		[],
+	);
+	const resolveIntersections = useCallback(
+		({
+			startPos,
+			currentPos,
+		}: {
+			startPos: { x: number; y: number };
+			currentPos: { x: number; y: number };
+		}) => {
+			return resolveElementIntersections({
+				startPos,
+				currentPos,
+				elements: getSelectableElements(),
+			});
+		},
+		[getSelectableElements],
+	);
+
+	const clearSelectionState = useCallback(() => {
+		setSelectionState(clearSelection());
+	}, []);
+
+	const selectedIdSet = useMemo(
+		() => new Set(selectionState.selectedIds),
+		[selectionState.selectedIds],
+	);
+
+	const isSelected = useCallback(
+		(id: string) => selectedIdSet.has(id),
+		[selectedIdSet],
+	);
+
+	const handleItemClick = useCallback(
+		({
+			event,
+			id,
+		}: {
+			event:
+				| React.MouseEvent<HTMLDivElement>
+				| React.KeyboardEvent<HTMLDivElement>;
+			id: string;
+		}) => {
+			setSelectionState((state) => {
+				const isToggleSelection = event.ctrlKey || event.metaKey;
+
+				if (event.shiftKey) {
+					return selectRange({
+						state,
+						orderedIds,
+						targetId: id,
+						isAdditive: isToggleSelection,
+					});
+				}
+
+				if (isToggleSelection) {
+					return toggleSelection({
+						state,
+						id,
+					});
+				}
+
+				return replaceSelection({
+					ids: [id],
+					anchorId: id,
+				});
+			});
+		},
+		[orderedIds],
+	);
+
+	const selectUnselectedItem = useCallback((id: string) => {
+		setSelectionState((state) => {
+			if (getIsSelected({ state, id })) {
+				return state;
+			}
+
+			return replaceSelection({ ids: [id], anchorId: id });
+		});
+	}, []);
+
+	const handleItemMouseDown = useCallback(
+		({
+			event,
+			id,
+		}: {
+			event: React.MouseEvent<HTMLDivElement>;
+			id: string;
+		}) => {
+			if (event.button !== 2) {
+				return;
+			}
+
+			selectUnselectedItem(id);
+		},
+		[selectUnselectedItem],
+	);
+
+	const handleBoxSelectionChange = useCallback(
+		(change: Parameters<typeof applyBoxSelection>[0]) => {
+			setSelectionState(applyBoxSelection(change));
+		},
+		[],
+	);
+
+	const { selectionBox, handleMouseDown, shouldIgnoreClick } = useBoxSelect({
+		containerRef,
+		resolveIntersections,
+		selectedIds: selectionState.selectedIds,
+		anchorId: selectionState.anchorId,
+		onSelectionChange: handleBoxSelectionChange,
+		shouldStartSelection,
+	});
+
+	const handleBackgroundClick = useCallback(
+		(event: React.MouseEvent<HTMLDivElement>) => {
+			const clickedSelectableItem =
+				event.target instanceof Element &&
+				event.target.closest(`[${SELECTABLE_ITEM_ATTRIBUTE}='true']`);
+			const isIgnoringClick = shouldIgnoreClick();
+			if (clickedSelectableItem || isIgnoringClick) {
+				return;
+			}
+
+			clearSelectionState();
+		},
+		[clearSelectionState, shouldIgnoreClick],
+	);
+
+	const handleBackgroundKeyDown = useCallback(
+		(event: React.KeyboardEvent<HTMLDivElement>) => {
+			if (event.target !== event.currentTarget) {
+				return;
+			}
+
+			if (event.key !== "Enter" && event.key !== " " && event.key !== "Escape") {
+				return;
+			}
+
+			event.preventDefault();
+			clearSelectionState();
+		},
+		[clearSelectionState],
+	);
+
+	useEffect(() => {
+		setSelectionState((state) =>
+			pruneSelection({
+				state,
+				orderedIds,
+			}),
+		);
+	}, [orderedIds]);
+
+	useEffect(() => {
+		onSelectionChange?.(selectionState);
+	}, [onSelectionChange, selectionState]);
+
+	useEffect(() => {
+		if (!revealId) {
+			return;
+		}
+
+		setHighlightedId(revealId);
+		getItemElement(revealId)?.scrollIntoView({ block: "center" });
+
+		const timer = setTimeout(() => {
+			setHighlightedId(null);
+			onRevealComplete?.();
+		}, 1500);
+
+		return () => clearTimeout(timer);
+	}, [getItemElement, onRevealComplete, revealId]);
+
+	const isBoxSelecting = selectionBox?.isActive ?? false;
+
+	const contextValue = useMemo(() => {
+		return {
+			selectedIds: selectionState.selectedIds,
+			anchorId: selectionState.anchorId,
+			highlightedId,
+			isBoxSelecting,
+			isSelected,
+			clearSelection: clearSelectionState,
+			handleItemClick,
+			handleItemMouseDown,
+			registerItem,
+		};
+	}, [
+		clearSelectionState,
+		handleItemClick,
+		handleItemMouseDown,
+		highlightedId,
+		isBoxSelecting,
+		isSelected,
+		registerItem,
+		selectionState.anchorId,
+		selectionState.selectedIds,
+	]);
+
+	return (
+		<SelectionContext.Provider value={contextValue}>
+			<div
+				ref={containerRef}
+				className={cn("relative min-h-full", className)}
+				role="listbox"
+				aria-label={ariaLabel}
+				aria-multiselectable="true"
+				tabIndex={0}
+				onMouseDown={handleMouseDown}
+				onClick={handleBackgroundClick}
+				onKeyDown={handleBackgroundKeyDown}
+			>
+				{children}
+				<SelectionBox
+					startPos={selectionBox?.startPos ?? null}
+					currentPos={selectionBox?.currentPos ?? null}
+					containerRef={containerRef}
+					isActive={selectionBox?.isActive ?? false}
+				/>
+			</div>
+		</SelectionContext.Provider>
+	);
+}
diff --git a/apps/web/src/selection/selection-box.tsx b/apps/web/src/selection/selection-box.tsx
new file mode 100644
index 00000000..e30f574d
--- /dev/null
+++ b/apps/web/src/selection/selection-box.tsx
@@ -0,0 +1,50 @@
+"use client";
+
+import { useMemo } from "react";
+
+interface SelectionBoxProps {
+	startPos: { x: number; y: number } | null;
+	currentPos: { x: number; y: number } | null;
+	containerRef: React.RefObject<HTMLElement | null>;
+	isActive: boolean;
+}
+
+export function SelectionBox({
+	startPos,
+	currentPos,
+	containerRef,
+	isActive,
+}: SelectionBoxProps) {
+	const selectionBoxStyle = useMemo(() => {
+		if (!isActive || !startPos || !currentPos || !containerRef.current) {
+			return null;
+		}
+
+		const containerRect = containerRef.current.getBoundingClientRect();
+		const startX = startPos.x - containerRect.left;
+		const startY = startPos.y - containerRect.top;
+		const currentX = currentPos.x - containerRect.left;
+		const currentY = currentPos.y - containerRect.top;
+
+		const left = Math.min(startX, currentX);
+		const top = Math.min(startY, currentY);
+		const width = Math.abs(currentX - startX);
+		const height = Math.abs(currentY - startY);
+
+		return {
+			left: `${left}px`,
+			top: `${top}px`,
+			width: `${width}px`,
+			height: `${height}px`,
+		};
+	}, [containerRef, currentPos, isActive, startPos]);
+
+	if (!selectionBoxStyle) return null;
+
+	return (
+		<div
+			style={selectionBoxStyle}
+			className="border-foreground/50 bg-foreground/5 pointer-events-none absolute z-50 border"
+		/>
+	);
+}
diff --git a/apps/web/src/selection/state.ts b/apps/web/src/selection/state.ts
new file mode 100644
index 00000000..b44578a1
--- /dev/null
+++ b/apps/web/src/selection/state.ts
@@ -0,0 +1,165 @@
+import type {
+	BoxSelectionChange,
+	SelectionState,
+} from "@/selection/types";
+
+function dedupeIds({ ids }: { ids: string[] }) {
+	return [...new Set(ids)];
+}
+
+function getRangeIds({
+	orderedIds,
+	anchorId,
+	targetId,
+}: {
+	orderedIds: string[];
+	anchorId: string;
+	targetId: string;
+}) {
+	const anchorIndex = orderedIds.indexOf(anchorId);
+	const targetIndex = orderedIds.indexOf(targetId);
+
+	if (anchorIndex === -1 || targetIndex === -1) {
+		return [targetId];
+	}
+
+	const rangeStart = Math.min(anchorIndex, targetIndex);
+	const rangeEnd = Math.max(anchorIndex, targetIndex);
+	return orderedIds.slice(rangeStart, rangeEnd + 1);
+}
+
+export function replaceSelection({
+	ids,
+	anchorId,
+}: {
+	ids: string[];
+	anchorId?: string | null;
+}): SelectionState {
+	const selectedIds = dedupeIds({ ids });
+	return {
+		selectedIds,
+		anchorId: anchorId ?? selectedIds[selectedIds.length - 1] ?? null,
+	};
+}
+
+export function clearSelection(): SelectionState {
+	return {
+		selectedIds: [],
+		anchorId: null,
+	};
+}
+
+export function pruneSelection({
+	state,
+	orderedIds,
+}: {
+	state: SelectionState;
+	orderedIds: string[];
+}): SelectionState {
+	const validIds = new Set(orderedIds);
+	const selectedIds = state.selectedIds.filter((id) => validIds.has(id));
+	const anchorId =
+		state.anchorId && validIds.has(state.anchorId)
+			? state.anchorId
+			: selectedIds[selectedIds.length - 1] ?? null;
+	const isUnchanged =
+		selectedIds.length === state.selectedIds.length &&
+		anchorId === state.anchorId;
+
+	if (isUnchanged) {
+		return state;
+	}
+
+	return {
+		selectedIds,
+		anchorId,
+	};
+}
+
+export function isSelected({
+	state,
+	id,
+}: {
+	state: SelectionState;
+	id: string;
+}) {
+	return state.selectedIds.includes(id);
+}
+
+export function toggleSelection({
+	state,
+	id,
+}: {
+	state: SelectionState;
+	id: string;
+}): SelectionState {
+	if (isSelected({ state, id })) {
+		const selectedIds = state.selectedIds.filter((selectedId) => selectedId !== id);
+		const anchorId =
+			state.anchorId === id
+				? selectedIds[selectedIds.length - 1] ?? null
+				: state.anchorId;
+		return replaceSelection({
+			ids: selectedIds,
+			anchorId,
+		});
+	}
+
+	return replaceSelection({
+		ids: [...state.selectedIds, id],
+		anchorId: id,
+	});
+}
+
+export function selectRange({
+	state,
+	orderedIds,
+	targetId,
+	isAdditive,
+}: {
+	state: SelectionState;
+	orderedIds: string[];
+	targetId: string;
+	isAdditive: boolean;
+}): SelectionState {
+	const anchorId =
+		state.anchorId ??
+		state.selectedIds[state.selectedIds.length - 1] ??
+		targetId;
+	const rangeIds = getRangeIds({
+		orderedIds,
+		anchorId,
+		targetId,
+	});
+	const selectedIds = isAdditive
+		? dedupeIds({
+				ids: [...state.selectedIds, ...rangeIds],
+			})
+		: rangeIds;
+
+	return replaceSelection({
+		ids: selectedIds,
+		anchorId,
+	});
+}
+
+export function applyBoxSelection({
+	intersectedIds,
+	initialSelectedIds,
+	initialAnchorId,
+	isAdditive,
+}: BoxSelectionChange): SelectionState {
+	const selectedIds = isAdditive
+		? dedupeIds({
+				ids: [...initialSelectedIds, ...intersectedIds],
+			})
+		: intersectedIds;
+	const anchorId = isAdditive
+		? initialAnchorId ?? intersectedIds[intersectedIds.length - 1] ?? null
+		: intersectedIds[intersectedIds.length - 1] ?? null;
+
+	return replaceSelection({
+		ids: selectedIds,
+		anchorId,
+	});
+}
diff --git a/apps/web/src/selection/types.ts b/apps/web/src/selection/types.ts
new file mode 100644
index 00000000..31520788
--- /dev/null
+++ b/apps/web/src/selection/types.ts
@@ -0,0 +1,39 @@
+export interface SelectionState {
+	selectedIds: string[];
+	anchorId: string | null;
+}
+
+export interface BoxSelectionSnapshot<TId = string> {
+	initialSelectedIds: TId[];
+	initialAnchorId: TId | null;
+}
+
+export interface BoxSelectionChange<TId = string>
+	extends BoxSelectionSnapshot<TId> {
+	intersectedIds: TId[];
+	isAdditive: boolean;
+}
+
+export type ResolveIntersections<TId = string> = ({
+	startPos,
+	currentPos,
+}: {
+	startPos: { x: number; y: number };
+	currentPos: { x: number; y: number };
+}) => TId[];
+
+export interface SelectableSurfaceProps {
+	orderedIds: string[];
+	children: React.ReactNode;
+	className?: string;
+	ariaLabel?: string;
+	revealId?: string | null;
+	onRevealComplete?: () => void;
+	onSelectionChange?: (state: SelectionState) => void;
+}
+
+export interface SelectableItemProps
+	extends React.HTMLAttributes<HTMLDivElement> {
+	id: string;
+	children: React.ReactNode;
+}