@embedpdf/plugin-selection 3.0.0-next.14 → 3.0.0-next.16

package/dist/index.js

@@ -1,77 +1,784 @@
-import { i as createSelectionCapability, n as selectionReducer, r as createTextSelectHandler, t as initialSelectionState } from "./reducer-DbKtk9Xl.js";
-import { t as SelectionToken$1 } from "./types-BVUcOsCh.js";
-import { SelectionToken } from "./contract.js";
-import { definePlugin } from "@embedpdf/core";
-import { FeedbackToken, InteractionToken } from "@embedpdf/plugin-interaction/contract";
-import { textQuadEdge } from "@embedpdf/core-geometry";
-//#region src/selection.plugin.ts
+import { n as SelectionToken, t as SELECTION_DEFAULTS } from "./contract-DBXA64ep.js";
+import { SelectionToken as SelectionToken$1 } from "./contract/host.js";
+import { PluginError, definePlugin, defineState, memo, memoByKey } from "@embedpdf/core";
+import { FeedbackToken, InteractionToken } from "@embedpdf/plugin-interaction/contract/host";
+import { boundsOfRects, quadBounds, quadEdge } from "@embedpdf/core-geometry";
+import { sliceText, toPageRef } from "@embedpdf/engine-core/runtime";
+//#region src/handler.ts
+const CURSOR_TOKEN = "selection-text";
 /**
-* Text selection — document-scoped, requires the interaction hub. In `init` it
-* registers ITS pointer handler with the hub; the hub owns the pointer stream
-* and arbitration. Works with `<Stage>` or a standalone `<PageView>` — selection
-* only needs the page coordinate context + the engine's text geometry.
+* The text-selection pointer handler. It is live only under tools that enable the
+* `'text-select'` tag (the built-in `pointer` tool does; `pan` does not — so
+* switching to pan disables text selection with zero special-casing here).
 *
-* Registry/content invalidation is wired inside the capability itself
-* (revision watch + document event subscription), so headless/programmatic
-* use gets the same reconciliation as the full viewer.
+*  - single click        → deselect; records an anchor but selects nothing until
+*                          the pointer moves past the drag threshold (Chrome/Acrobat feel)
+*  - single-click + drag → caret selection from the anchor (extends across pages)
+*  - double-click        → select the word
+*  - triple-click        → select the visual line
+*  - down off-text       → deselect, and don't capture (so it can't block)
+*  - hover               → I-beam only when over text, else the pointer cursor
+*/
+function createTextSelectHandler(selection, interaction, feedback, options = {}) {
+	const dragThreshold = options.dragThreshold ?? (() => SELECTION_DEFAULTS.dragThreshold);
+	let anchor = null;
+	let dragging = false;
+	return {
+		id: "text-select",
+		priority: 60,
+		enabledFor: (tool) => tool.enables.has("text-select"),
+		onDown: (sample) => {
+			anchor = null;
+			dragging = false;
+			if (!sample.page) return false;
+			if (!selection.canSelect()) return false;
+			const { ref: page, point } = sample.page;
+			const clicks = sample.clickCount ?? 1;
+			selection.beginGesture();
+			if (clicks >= 3) {
+				selection.selectLineAt(page, point);
+				return true;
+			}
+			if (clicks === 2) {
+				if (selection.selectWordAt(page, point) && sample.gesture === "long-press") feedback?.selection();
+				return true;
+			}
+			selection.clear();
+			if (!selection.isOverText(page, point)) {
+				selection.endGesture();
+				return false;
+			}
+			anchor = {
+				page,
+				point,
+				viewportX: sample.viewport.x,
+				viewportY: sample.viewport.y
+			};
+			return true;
+		},
+		onMove: (sample) => {
+			if (!sample.page || !anchor) return;
+			if (!dragging) {
+				if (Math.hypot(sample.viewport.x - anchor.viewportX, sample.viewport.y - anchor.viewportY) < dragThreshold()) return;
+				dragging = true;
+				selection.beginGestureAt(anchor.page, anchor.point);
+			}
+			selection.extendTo(sample.page.ref, sample.page.point);
+		},
+		onUp: () => {
+			anchor = null;
+			dragging = false;
+			selection.endGesture();
+		},
+		onCancel: () => {
+			anchor = null;
+			dragging = false;
+			selection.clear();
+			selection.endGesture();
+		},
+		onHover: (sample) => {
+			if (!sample.page) {
+				interaction.claimCursor(CURSOR_TOKEN, null);
+				return;
+			}
+			selection.ensureLoaded(sample.page.ref);
+			const overText = selection.isOverText(sample.page.ref, sample.page.point);
+			interaction.claimCursor(CURSOR_TOKEN, overText ? "text" : null, 10);
+		}
+	};
+}
+//#endregion
+//#region src/connect.ts
+/**
+* Register the text-select pointer handler with the interaction hub, which
+* owns the pointer stream and arbitration. Platform feedback (haptics) is
+* optional: without it (headless setups) the handler never buzzes. The
+* handler reads the drag threshold at each press, so a settings change applies
+* to the next gesture.
+*/
+function connectSelection(ctx, selection) {
+	const interaction = ctx.get(InteractionToken);
+	const feedback = ctx.tryGet(FeedbackToken) ?? void 0;
+	const settings = ctx.settings();
+	ctx.cleanup(interaction.registerHandler(createTextSelectHandler(selection, interaction, feedback, { dragThreshold: () => settings.get().dragThreshold })));
+}
+//#endregion
+//#region src/model.ts
+const initialSelectionState = () => ({
+	selection: null,
+	segments: {},
+	highlightHidden: false,
+	selecting: false
+});
+const samePosition = (left, right) => left.glyph === right.glyph && left.page.objectNumber === right.page.objectNumber;
+const sameRange = (left, right) => left === right || left !== null && right !== null && samePosition(left.anchor, right.anchor) && samePosition(left.focus, right.focus);
+const sameQuad = (left, right) => [
+	"upperLeft",
+	"upperRight",
+	"lowerLeft",
+	"lowerRight"
+].every((corner) => left[corner].x === right[corner].x && left[corner].y === right[corner].y);
+const sameSegments = (left, right) => left === right || left.length === right.length && left.every((segment, index) => segment.advance === right[index].advance && sameQuad(segment.quad, right[index].quad));
+/**
+* Replace the range and its segments. A page whose segments are unchanged
+* keeps its previous array, so per-page reads stay reference-stable, and a
+* recompute that changes nothing returns the same state.
+*/
+function setSelection(state, selection, segments) {
+	const pages = Object.keys(segments).map(Number);
+	let segmentsChanged = pages.length !== Object.keys(state.segments).length;
+	const merged = {};
+	for (const pageObjectNumber of pages) {
+		const previous = state.segments[pageObjectNumber];
+		const next = segments[pageObjectNumber];
+		if (previous && sameSegments(previous, next)) merged[pageObjectNumber] = previous;
+		else {
+			merged[pageObjectNumber] = next;
+			segmentsChanged = true;
+		}
+	}
+	const rangeChanged = !sameRange(state.selection, selection);
+	if (!rangeChanged && !segmentsChanged) return state;
+	return {
+		...state,
+		selection: rangeChanged ? selection : state.selection,
+		segments: segmentsChanged ? merged : state.segments
+	};
+}
+function clearSelection(state) {
+	return state.selection === null && Object.keys(state.segments).length === 0 ? state : {
+		...state,
+		selection: null,
+		segments: {}
+	};
+}
+const setHighlightHidden = (state, hidden) => state.highlightHidden === hidden ? state : {
+	...state,
+	highlightHidden: hidden
+};
+const setSelecting = (state, selecting) => state.selecting === selecting ? state : {
+	...state,
+	selecting
+};
+/**
+* The pages whose content (and so character space) a confirmed event
+* changed: applied redactions, flattened pages, and pages an annotation
+* flatten painted into (a free-text note becomes page text). Null for every
+* other event.
+*/
+function contentChangedPagesOf(event) {
+	if (event.type === "annotations.flattened") return event.results.some((result) => result.status === "applied") ? [event.page] : null;
+	if (event.type !== "redaction.applied" && event.type !== "pages.flattened") return null;
+	const pages = event.results.filter((result) => result.status === "applied").map((result) => result.page);
+	return pages.length > 0 ? pages : null;
+}
+//#endregion
+//#region src/controller.ts
+const SELECT_SCOPE = "doc.text.select";
+const COPY_SCOPE = "doc.text.copy";
+const EMPTY_SEGMENTS = Object.freeze([]);
+const EMPTY_PAGES = Object.freeze([]);
+const EMPTY_RECTS = Object.freeze([]);
+/** How many page-text reads a `readText` keeps in flight at once. */
+const TEXT_READ_CONCURRENCY = 8;
+/** An open-ended focus: settles to the page's real last character once its geometry loads. */
+const OPEN_END = Number.MAX_SAFE_INTEGER;
+/**
+* The selection controller.
+*
+* State holds the range and its derived page-space segments. Engine data
+* lives outside state:
+*
+*   - text geometry is a page mirror: PDF-space snapshots loaded on demand,
+*     re-read when a confirmed event changes a page's content (redaction
+*     apply, flatten) and dropped when a page is deleted. Page-space
+*     geometry is derived from a snapshot and the page's current layout, so
+*     a view rotation re-derives without asking the engine again.
+*   - `textSnapshots` holds per-page text promises for `readText`, dropped
+*     on the same content changes and when a page leaves the registry.
+*
+* `recompute` rebuilds the segments of every loaded page in the span and
+* warms the rest, which recompute when their geometry arrives. The change
+* and clear events are derived from state changes in one place.
+*
+* Selection is cross-page: glyphs are ordered globally by (page index,
+* glyph), so a drag from page 2 into page 4 selects the tail of 2, all of 3,
+* and the head of 4. Stored endpoints are clamped once their page's geometry
+* is known, which is how `selectAll`'s open end settles.
+*
+* The settings belong to the plugin registration; the pointer handler reads
+* the drag threshold from them, and the framework layers read the colors.
+*/
+function createSelectionController(ctx) {
+	const settings = ctx.settings();
+	const changed = ctx.events.source();
+	const committed = ctx.events.source();
+	const cleared = ctx.events.source();
+	const textSnapshots = /* @__PURE__ */ new Map();
+	const state = () => ctx.state.get();
+	const canSelect = () => ctx.allows(SELECT_SCOPE);
+	const canCopy = () => ctx.allows(COPY_SCOPE);
+	const pageIndexOf = (page) => ctx.getPage(page)?.index ?? -1;
+	const pageAtIndex = (index) => ctx.document()?.pages[index]?.ref;
+	const geometry = ctx.pageMirror({
+		name: "geometry",
+		load: (doc, page) => doc.page(page).text.layout(),
+		affected: contentChangedPagesOf,
+		changed: ({ cause }) => {
+			if (cause !== "load") return;
+			const current = state().selection;
+			if (current) recompute(current);
+		}
+	});
+	/** A page's snapshot while it is loaded and current: a page whose re-read
+	*  failed has no geometry, exactly as {@link SelectionHostCapability.isLoaded} says. */
+	const snapshotOf = (page) => geometry.getStatus(page) === "ready" ? geometry.get(page) : void 0;
+	/** A page's text layout while it is loaded and current. */
+	const geometryFor = snapshotOf;
+	const glyphAt = (layout, point) => layout.charAt(point);
+	/** Warm a page's geometry; the returned promise never rejects (see the host contract). */
+	function ensureLoaded(page) {
+		if (!canSelect() || !ctx.getPage(page)) return Promise.resolve();
+		return geometry.ensureLoaded(page).catch(() => {});
+	}
+	function orderedEnds(selection) {
+		const anchorPageIndex = pageIndexOf(selection.anchor.page);
+		const focusPageIndex = pageIndexOf(selection.focus.page);
+		return anchorPageIndex < focusPageIndex || anchorPageIndex === focusPageIndex && selection.anchor.glyph <= selection.focus.glyph ? {
+			start: selection.anchor,
+			end: selection.focus,
+			direction: "forward"
+		} : {
+			start: selection.focus,
+			end: selection.anchor,
+			direction: "backward"
+		};
+	}
+	/** Clamp a position into its page's real character range once geometry is known. */
+	function clampPosition(position) {
+		const textLayout = geometryFor(position.page);
+		if (!textLayout) return position;
+		const max = Math.max(textLayout.charCount - 1, 0);
+		const glyph = Math.max(0, Math.min(position.glyph, max));
+		return glyph === position.glyph ? position : {
+			page: position.page,
+			glyph
+		};
+	}
+	/** Rebuild merged line segments for every loaded page in the span; warm the
+	*  rest. Clears when an endpoint's page has left the registry: a range
+	*  across a structural edit is meaningless. */
+	function recompute(selection) {
+		const clamped = {
+			anchor: clampPosition(selection.anchor),
+			focus: clampPosition(selection.focus)
+		};
+		const { start, end } = orderedEnds(clamped);
+		const startPageIndex = pageIndexOf(start.page);
+		const endPageIndex = pageIndexOf(end.page);
+		if (startPageIndex < 0 || endPageIndex < 0) {
+			ctx.state.update(clearSelection);
+			return;
+		}
+		const segments = {};
+		for (let i = startPageIndex; i <= endPageIndex; i++) {
+			const page = pageAtIndex(i);
+			if (!page) continue;
+			const textLayout = geometryFor(page);
+			if (!textLayout) {
+				ensureLoaded(page);
+				continue;
+			}
+			const from = i === startPageIndex ? start.glyph : 0;
+			const to = i === endPageIndex ? end.glyph : textLayout.charCount - 1;
+			segments[page.objectNumber] = textLayout.segments({
+				start: from,
+				count: to - from + 1
+			});
+		}
+		ctx.state.update(setSelection, clamped, segments);
+	}
+	const readModel = memo(() => [
+		state().selection,
+		state().segments,
+		ctx.document()?.revision ?? 0
+	], (selection, segments) => buildReadModel(selection, segments));
+	function buildReadModel(selection, segments) {
+		const pagesWithSegments = Object.keys(segments).map((key) => toPageRef(Number(key))).filter((page) => (segments[page.objectNumber]?.length ?? 0) > 0).sort((left, right) => pageIndexOf(left) - pageIndexOf(right));
+		const snapshotPages = pagesWithSegments.map((page) => ({
+			page,
+			segments: segments[page.objectNumber]
+		}));
+		const pages = pagesWithSegments.length ? pagesWithSegments : EMPTY_PAGES;
+		if (!selection) return {
+			snapshot: {
+				pages: snapshotPages,
+				start: null,
+				end: null,
+				direction: "forward",
+				range: null
+			},
+			pages,
+			anchor: null
+		};
+		const { start, end, direction } = orderedEnds(selection);
+		const snapshot = {
+			pages: snapshotPages,
+			start: endpointFor(segments, start, "start"),
+			end: endpointFor(segments, end, "end"),
+			direction,
+			range: {
+				start: {
+					page: start.page,
+					index: start.glyph
+				},
+				end: {
+					page: end.page,
+					index: end.glyph + 1
+				}
+			}
+		};
+		const endBounds = unionOf(segments[end.page.objectNumber]);
+		let anchor = endBounds ? {
+			page: end.page,
+			bounds: endBounds
+		} : null;
+		const last = pagesWithSegments[pagesWithSegments.length - 1];
+		if (!anchor && last) anchor = {
+			page: last,
+			bounds: unionOf(segments[last.objectNumber])
+		};
+		return {
+			snapshot,
+			pages,
+			anchor
+		};
+	}
+	function endpointFor(segmentsByPage, position, which) {
+		const segments = segmentsByPage[position.page.objectNumber] ?? EMPTY_SEGMENTS;
+		if (!segments.length) return null;
+		const segment = which === "start" ? segments[0] : segments[segments.length - 1];
+		const textLayout = geometryFor(position.page);
+		const cell = textLayout ? textLayout.charQuad(position.glyph) : null;
+		if (textLayout && cell) return {
+			page: position.page,
+			glyphQuad: cell,
+			advance: segment.advance,
+			rect: quadBounds(cell)
+		};
+		return {
+			page: position.page,
+			glyphQuad: segment.quad,
+			advance: segment.advance,
+			rect: segment.rect
+		};
+	}
+	const unionOf = (segments) => segments ? boundsOfRects(segments.map((segment) => segment.rect)) : null;
+	/** A page's segment boxes, the same array until that page's segments change. */
+	const rectsOf = memoByKey((pageObjectNumber) => [state().segments[pageObjectNumber]], (_pageObjectNumber, segments) => (segments ?? EMPTY_SEGMENTS).map((segment) => segment.rect));
+	ctx.state.onChange(({ previous, next }) => {
+		if (previous.selection === next.selection && previous.segments === next.segments) return;
+		const model = readModel();
+		changed.emit({
+			range: model.snapshot.range,
+			pages: model.pages
+		});
+		if (previous.selection !== null && next.selection === null) cleared.emit({});
+	});
+	function select(input) {
+		ctx.assertAllowed(SELECT_SCOPE, "selection.select");
+		const range = "page" in input ? {
+			start: {
+				page: input.page,
+				index: input.start
+			},
+			end: {
+				page: input.page,
+				index: input.start + input.count
+			}
+		} : input;
+		ctx.assertPageRef(range.start.page);
+		ctx.assertPageRef(range.end.page);
+		const startPageIndex = pageIndexOf(range.start.page);
+		let endPageIndex = pageIndexOf(range.end.page);
+		let endCharIndex = range.end.index;
+		if (endPageIndex < startPageIndex || endPageIndex === startPageIndex && endCharIndex <= range.start.index) {
+			ctx.state.update(clearSelection);
+			return;
+		}
+		if (endCharIndex === 0) {
+			endPageIndex -= 1;
+			if (endPageIndex < startPageIndex) {
+				ctx.state.update(clearSelection);
+				return;
+			}
+			endCharIndex = OPEN_END;
+		}
+		const focusPage = pageAtIndex(endPageIndex);
+		if (!focusPage) return;
+		recompute({
+			anchor: {
+				page: range.start.page,
+				glyph: Math.max(0, range.start.index)
+			},
+			focus: {
+				page: focusPage,
+				glyph: endCharIndex - 1
+			}
+		});
+	}
+	function selectAll() {
+		ctx.assertAllowed(SELECT_SCOPE, "selection.selectAll");
+		const pages = ctx.document()?.pages ?? [];
+		if (pages.length === 0) return;
+		recompute({
+			anchor: {
+				page: pages[0].ref,
+				glyph: 0
+			},
+			focus: {
+				page: pages[pages.length - 1].ref,
+				glyph: OPEN_END
+			}
+		});
+	}
+	function selectPage(target) {
+		ctx.assertAllowed(SELECT_SCOPE, "selection.selectPage");
+		const page = ctx.pageOf(target).ref;
+		recompute({
+			anchor: {
+				page,
+				glyph: 0
+			},
+			focus: {
+				page,
+				glyph: OPEN_END
+			}
+		});
+	}
+	/** Word / line around a point. Returns whether a span actually engaged
+	*  (geometry present and a glyph under the point): the fact haptics and
+	*  other success-gated feedback key on, so nothing buzzes over blank space. */
+	function selectSpanAt(target, point, expand) {
+		ctx.assertAllowed(SELECT_SCOPE, `selection.select${expand === "word" ? "WordAt" : "LineAt"}`);
+		const page = ctx.pageOf(target).ref;
+		const textLayout = geometryFor(page);
+		if (!textLayout) return false;
+		const glyph = glyphAt(textLayout, point);
+		if (glyph == null) return false;
+		const span = expand === "word" ? textLayout.wordAt(glyph) : textLayout.lineAt(glyph);
+		if (!span) return false;
+		recompute({
+			anchor: {
+				page,
+				glyph: span.start
+			},
+			focus: {
+				page,
+				glyph: span.start + span.count - 1
+			}
+		});
+		return true;
+	}
+	function extendTo(target, point) {
+		ctx.assertAllowed(SELECT_SCOPE, "selection.extendTo");
+		const page = ctx.pageOf(target).ref;
+		const current = state().selection;
+		if (!current) return;
+		const textLayout = geometryFor(page);
+		if (!textLayout) {
+			ensureLoaded(page);
+			return;
+		}
+		const glyph = glyphAt(textLayout, point);
+		if (glyph == null) return;
+		recompute({
+			anchor: current.anchor,
+			focus: {
+				page,
+				glyph
+			}
+		});
+	}
+	/** Per-page text snapshot, cached as a promise so concurrent readers share
+	*  one fetch. Rejections are evicted: a refused or failed read must not
+	*  poison the cache for a later authorized call. */
+	function pageText(page) {
+		const key = page.objectNumber;
+		const cached = textSnapshots.get(key);
+		if (cached) return cached;
+		const pending = Promise.resolve(ctx.doc.page(page).text.get());
+		textSnapshots.set(key, pending);
+		pending.catch(() => {
+			if (textSnapshots.get(key) === pending) textSnapshots.delete(key);
+		});
+		return pending;
+	}
+	async function readText(options) {
+		ctx.assertAllowed(COPY_SCOPE, "selection.readText");
+		const range = readModel().snapshot.range;
+		return range ? readRange(range, options) : "";
+	}
+	async function readTextInRange(range, options) {
+		ctx.assertAllowed(COPY_SCOPE, "selection.readTextInRange");
+		return readRange(range, options);
+	}
+	/** A range's text, read a few pages at a time. Cancelling stops the wait at
+	*  once; the page reads it started finish into the cache, which other
+	*  readers share. */
+	async function readRange(range, options) {
+		ctx.assertPageRef(range.start.page);
+		ctx.assertPageRef(range.end.page);
+		const startPageIndex = pageIndexOf(range.start.page);
+		let endPageIndex = pageIndexOf(range.end.page);
+		let endCharIndex = range.end.index;
+		if (endPageIndex < startPageIndex || endPageIndex === startPageIndex && endCharIndex <= range.start.index) return "";
+		if (endCharIndex === 0) {
+			endPageIndex -= 1;
+			endCharIndex = OPEN_END;
+		}
+		const spans = [];
+		for (let i = startPageIndex; i <= endPageIndex; i++) {
+			const page = pageAtIndex(i);
+			if (!page) continue;
+			spans.push({
+				page,
+				from: i === startPageIndex ? Math.max(0, range.start.index) : 0,
+				to: i === endPageIndex ? endCharIndex : OPEN_END
+			});
+		}
+		const signal = options?.signal;
+		const parts = new Array(spans.length);
+		for (let base = 0; base < spans.length; base += TEXT_READ_CONCURRENCY) {
+			if (signal?.aborted) throw new PluginError("operation-cancelled", "selection", "reading the text was cancelled");
+			const batch = spans.slice(base, base + TEXT_READ_CONCURRENCY);
+			(await ctx.cancellable(signal, Promise.all(batch.map((span) => pageText(span.page))))).forEach((snapshot, index) => {
+				const { from, to } = batch[index];
+				parts[base + index] = sliceText(snapshot, {
+					start: from,
+					count: to - from
+				});
+			});
+		}
+		return parts.join("\n");
+	}
+	/** Structural registry change (rotate/move/delete/insert): drop the text of
+	*  pages that left, then recompute. Rotation re-derives page-space geometry
+	*  through the layout key; a deleted endpoint page clears through
+	*  recompute's registry check. */
+	function onPagesUpdated() {
+		const alive = new Set((ctx.document()?.pages ?? []).map((info) => info.ref.objectNumber));
+		for (const pageObjectNumber of [...textSnapshots.keys()]) if (!alive.has(pageObjectNumber)) textSnapshots.delete(pageObjectNumber);
+		const current = state().selection;
+		if (current) recompute(current);
+	}
+	/** Page content changed: the pages' text is stale, and a live range points
+	*  into a character space that no longer exists, so it clears. The
+	*  geometry mirror re-reads those pages itself. */
+	function onContentChanged(pages) {
+		for (const page of pages) textSnapshots.delete(page.objectNumber);
+		ctx.state.update(clearSelection);
+	}
+	const setGesture = (active) => ctx.state.update(setSelecting, active);
+	/** A page's segments, by its ref or its index: a page that isn't in the document has none. */
+	const segmentsOn = (target) => {
+		const page = ctx.getPage(target);
+		return page ? state().segments[page.ref.objectNumber] ?? EMPTY_SEGMENTS : EMPTY_SEGMENTS;
+	};
+	const api = {
+		...settings.api,
+		canSelect,
+		canCopy,
+		select,
+		selectAll,
+		selectPage,
+		selectWordAt: (page, point) => selectSpanAt(page, point, "word"),
+		selectLineAt: (page, point) => selectSpanAt(page, point, "line"),
+		extendTo,
+		clear: () => ctx.state.update(clearSelection),
+		hasSelection: () => state().selection != null,
+		isSelecting: () => state().selecting,
+		getSnapshot: () => readModel().snapshot,
+		getRange: () => readModel().snapshot.range,
+		listSelectedPages: () => readModel().pages,
+		listSegments: segmentsOn,
+		listRects: (target) => {
+			const page = ctx.getPage(target);
+			return page ? rectsOf(page.ref.objectNumber) : EMPTY_RECTS;
+		},
+		getAnchor: () => readModel().anchor,
+		readText,
+		readTextInRange,
+		onChanged: changed.on,
+		onCommitted: committed.on,
+		onCleared: cleared.on,
+		ensureLoaded,
+		isLoaded: (page) => geometry.getStatus(page) === "ready",
+		isOverText: (page, point) => {
+			const textLayout = geometryFor(page);
+			return textLayout ? glyphAt(textLayout, point) != null : false;
+		},
+		beginGesture: () => setGesture(true),
+		beginGestureAt: (page, point) => {
+			if (!canSelect()) return false;
+			const textLayout = geometryFor(page);
+			if (!textLayout) return false;
+			const glyph = glyphAt(textLayout, point);
+			if (glyph == null) return false;
+			setGesture(true);
+			recompute({
+				anchor: {
+					page,
+					glyph
+				},
+				focus: {
+					page,
+					glyph
+				}
+			});
+			return true;
+		},
+		endGesture: () => {
+			setGesture(false);
+			const range = readModel().snapshot.range;
+			if (range) committed.emit({ range });
+		},
+		setHighlightVisible: (visible) => ctx.state.update(setHighlightHidden, !visible),
+		isHighlightVisible: () => !state().highlightHidden
+	};
+	return {
+		api,
+		connect() {
+			ctx.watch(() => ctx.document()?.revision ?? 0, onPagesUpdated);
+			ctx.listen(ctx.doc.events, (event) => {
+				const pages = contentChangedPagesOf(event);
+				if (pages) onContentChanged(pages);
+			});
+			connectSelection(ctx, api);
+		}
+	};
+}
+//#endregion
+//#region src/selection.plugin.ts
+/**
+* Text selection: document-scoped, requires the interaction hub, whose
+* pointer stream drives the selection's own handler. Works with `<Stage>`
+* or a standalone `<PageView>`: selection only needs the page coordinate
+* context and the engine's text geometry. Platform feedback (haptics) is
+* optional. `config` is the settings the app registers, over
+* {@link SELECTION_DEFAULTS}.
 */
-const selectionPlugin = () => definePlugin({
+const selectionPlugin = (config) => definePlugin({
 	id: "selection",
 	token: SelectionToken$1,
 	scope: "document",
 	requires: [InteractionToken],
 	optional: [FeedbackToken],
-	initialState: initialSelectionState,
-	reduce: selectionReducer,
-	capability: createSelectionCapability,
-	init: (ctx) => {
-		const interaction = ctx.get(InteractionToken);
-		const selection = ctx.get(SelectionToken$1);
-		const feedback = ctx.tryGet(FeedbackToken);
-		interaction.registerHandler(createTextSelectHandler(selection, interaction, feedback ?? void 0));
+	state: initialSelectionState,
+	settings: {
+		defaults: SELECTION_DEFAULTS,
+		registered: config
+	},
+	create: createSelectionController
+});
+//#endregion
+//#region src/state.ts
+/**
+* The selection page's State table as code: what `useSelectionState()`
+* returns, and the same fields in every other framework. The geometry is not
+* here: a layer reads its page's segments with `listSegments(page)`, so a
+* toolbar that only shows whether something is selected doesn't re-render for
+* every step of a drag.
+*/
+const selectionState = defineState(SelectionToken, {
+	read: (selection) => ({
+		hasSelection: selection.hasSelection(),
+		isSelecting: selection.isSelecting(),
+		range: selection.getRange(),
+		pages: selection.listSelectedPages()
+	}),
+	empty: {
+		hasSelection: false,
+		isSelecting: false,
+		range: null,
+		pages: []
 	}
 });
 //#endregion
 //#region src/handles.ts
 /**
-* Selection handles — the pure policy half (the `wheel.ts` convention).
+* Selection handles — the pure policy half.
 *
-* A handle IS the boundary glyph's leading (or trailing) edge: a segment
-* between two corners of the glyph's ORIENTED cell, with the grab head just
+* A handle is the boundary glyph's leading (or trailing) edge: a segment
+* between two corners of the glyph's oriented cell, with the grab head just
 * beyond the ascent at the start / past the baseline at the end. Bar length,
 * angle, and head all derive from that one segment, so rotated text and
 * rotated pages are carried by construction — the AABB never enters.
 *
 * Everything here is DOM-free and framework-free: geometry is pure given a
 * projector, and the drag session speaks the selection's own gesture verbs
-* (`beginAt`/`extendTo`/`end` — the same ones the pointer handler uses; a
-* handle drag IS a selection gesture, re-anchored). The framework adapters
+* (`beginGestureAt`/`extendTo`/`endGesture` — the same ones the pointer handler uses; a
+* handle drag is a selection gesture, re-anchored). The framework adapters
 * keep only subscriptions and markup; the DOM listener mechanics live in
 * `@embedpdf/web`'s `attachSelectionHandle`.
 *
-* The view dependency is STRUCTURAL (satisfied by five lines over
-* `StageCapability`) so this plugin stays stage-free — selection also runs
-* in stage-less hosts (`PageView`) — and the math tests run against a fake.
+* The view dependency is structural (`selectionHandleViewOf` builds it from
+* anything shaped like `StageCapability`) so this plugin stays stage-free —
+* selection also runs in stage-less hosts (`PageView`) — and the math tests
+* run against a fake.
 */
+/**
+* The handles' view over a Stage: point-exact projection in, page lookup out.
+* (The Stage's box projector, `pageRectToViewport`, is for upright overlays
+* and would lose the orientation a handle needs.)
+*/
+function selectionHandleViewOf(stage) {
+	return {
+		toOverlay: (page, point) => stage.pageToViewport(page, point),
+		pageAt: (overlay) => stage.getPageAt(overlay),
+		pointOnPage: (page, overlay) => stage.viewportToPage(page, overlay)
+	};
+}
+/**
+* The two ends of the selection in `snapshot` (`getSnapshot()`), or null
+* while nothing is selected. A new object on every call: compare with
+* `sameSelectionEndpoints` from `@embedpdf/web`.
+*/
+function selectionHandleEndpointsOf(snapshot) {
+	const { start, end } = snapshot;
+	if (!start || !end) return null;
+	return {
+		start: {
+			page: start.page,
+			glyphQuad: start.glyphQuad,
+			advance: start.advance
+		},
+		end: {
+			page: end.page,
+			glyphQuad: end.glyphQuad,
+			advance: end.advance
+		}
+	};
+}
 const HANDLE_HEAD = 12;
 const HANDLE_BAR = 2;
 const HANDLE_PAD = 14;
 /** Tilts within ~0.05° of upright render untransformed (float-noise guard —
 *  and the dominant case stays pixel-identical to an axis-aligned box). */
 const HANDLE_ROT_EPSILON = .05;
-const midpoint = (a, b) => ({
-	x: (a.x + b.x) / 2,
-	y: (a.y + b.y) / 2
+const midpoint = (from, to) => ({
+	x: (from.x + to.x) / 2,
+	y: (from.y + to.y) / 2
 });
 /**
 * The handle's geometry for one endpoint, in overlay space. Null when the
 * endpoint's page isn't laid out (or the cell is degenerate) — render nothing.
 */
-function selectionHandleGeom(view, ep, role) {
-	const leading = role === "start" ? ep.advance > 0 : ep.advance < 0;
-	const [upperPage, lowerPage] = textQuadEdge(ep.glyphQuad, leading ? "start" : "end");
-	const upper = view.toOverlay(ep.pon, upperPage);
-	const lower = view.toOverlay(ep.pon, lowerPage);
+function selectionHandleGeom(view, endpoint, role) {
+	const leading = role === "start" ? endpoint.advance > 0 : endpoint.advance < 0;
+	const [upperPage, lowerPage] = quadEdge(endpoint.glyphQuad, leading ? "left" : "right");
+	const upper = view.toOverlay(endpoint.page, upperPage);
+	const lower = view.toOverlay(endpoint.page, lowerPage);
 	if (!upper || !lower) return null;
 	const dx = lower.x - upper.x;
 	const dy = lower.y - upper.y;
@@ -100,7 +807,7 @@ function selectionHandleGeom(view, ep, role) {
 	};
 }
 /**
-* One armed handle drag. Dragging a handle extends from the OPPOSITE
+* One armed handle drag. Dragging a handle extends from the opposite
 * endpoint: the first movement re-roots the selection gesture at that
 * endpoint's cell centre, and every position then extends toward the pointer
 * — snapping to glyphs and crossing pages exactly like a pointer drag,
@@ -109,32 +816,46 @@ function selectionHandleGeom(view, ep, role) {
 * freezing at a page edge. `end()` commits only if the drag actually
 * re-rooted; an untouched press settles nothing.
 */
-function createSelectionHandleDrag(selection, view, opposite, draggedPon) {
-	const q = opposite.glyphQuad;
-	const anchorPoint = midpoint(midpoint(q.upperStart, q.lowerEnd), midpoint(q.upperEnd, q.lowerStart));
+function createSelectionHandleDrag(selection, view, opposite, draggedPage) {
+	const quad = opposite.glyphQuad;
+	const anchorPoint = midpoint(midpoint(quad.upperLeft, quad.lowerRight), midpoint(quad.upperRight, quad.lowerLeft));
 	let begun = false;
-	let lastPon = draggedPon;
+	let lastPage = draggedPage;
 	return {
 		move: (overlay) => {
 			if (!begun) {
-				if (!selection.beginAt(opposite.pon, anchorPoint)) return;
+				if (!selection.beginGestureAt(opposite.page, anchorPoint)) return;
 				begun = true;
 			}
 			const hit = view.pageAt(overlay);
 			if (hit) {
-				lastPon = hit.pon;
-				selection.extendTo(hit.pon, hit.point);
+				lastPage = hit.ref;
+				selection.extendTo(hit.ref, hit.point);
 			} else {
-				const p = view.pointOnPage(lastPon, overlay);
-				if (p) selection.extendTo(lastPon, p);
+				const point = view.pointOnPage(lastPage, overlay);
+				if (point) selection.extendTo(lastPage, point);
 			}
 		},
 		end: () => {
-			if (begun) selection.end();
+			if (begun) selection.endGesture();
 		}
 	};
 }
+/**
+* Arm a drag of the `role` handle at a press, with the view and the endpoints
+* as they are at that moment: it extends the selection from the opposite end.
+* Null when the handle's page isn't laid out.
+*/
+function armSelectionHandle(selection, view, endpoints, role) {
+	const geometry = selectionHandleGeom(view, endpoints[role], role);
+	if (!geometry) return null;
+	const opposite = endpoints[role === "start" ? "end" : "start"];
+	return {
+		base: midpoint(geometry.bar.from, geometry.bar.to),
+		drag: createSelectionHandleDrag(selection, view, opposite, endpoints[role].page)
+	};
+}
 //#endregion
-export { HANDLE_BAR, HANDLE_HEAD, HANDLE_PAD, SelectionToken, createSelectionHandleDrag, selectionHandleGeom, selectionPlugin };
+export { HANDLE_BAR, HANDLE_HEAD, HANDLE_PAD, SELECTION_DEFAULTS, SelectionToken, armSelectionHandle, createSelectionHandleDrag, selectionHandleEndpointsOf, selectionHandleGeom, selectionHandleViewOf, selectionPlugin, selectionState };
 
 //# sourceMappingURL=index.js.map