@embedpdf/react 3.0.0-next.13 → 3.0.0-next.15

package/dist/selection.js

@@ -1,24 +1,30 @@
-import "./rolldown-runtime-BBjsoOtd.js";
-import { shallowArray, useCapability, useKernelValue, useOptionalCapability, usePage, useSelector } from "./runtime.js";
-import { Anchored } from "./anchored.js";
+import { D as useViewerSettings, E as useSelector, O as devWarn, S as useOptionalCapability, f as useCapability, p as useCapabilityEvent, u as shallowArray, w as usePage, x as useKernelValue } from "./runtime-B6xcPsEb.js";
+import { n as stateHook, t as settingsHook } from "./state-CbgxhwLA.js";
+import { Anchored, useOptionalProjectorBinding } from "./anchored.js";
+import { n as useStageToken } from "./stage-scope-D7ZeNduT.js";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { attachSelectionHandle, copySelection, mixAccent, paint, quadInPixels, samePageBounds, sameSelectionEndpoints, svgPoints, wireSelectionClipboard } from "@embedpdf/web";
 import { useEffect, useMemo, useRef, useState } from "react";
-import { attachSelectionHandle, copySelection, wireSelectionClipboard } from "@embedpdf/web";
-import { StageToken } from "@embedpdf/plugin-stage/contract";
-import { textQuadEquals } from "@embedpdf/core-geometry";
-import { HANDLE_BAR, HANDLE_HEAD, HANDLE_PAD, SelectionToken, createSelectionHandleDrag, selectionHandleGeom } from "@embedpdf/plugin-selection";
-import { SelectionToken as SelectionToken$1 } from "@embedpdf/plugin-selection/internal";
+import { HANDLE_BAR, HANDLE_HEAD, HANDLE_PAD, SelectionToken, armSelectionHandle, selectionHandleEndpointsOf, selectionHandleGeom, selectionHandleViewOf, selectionState } from "@embedpdf/plugin-selection";
+import { SelectionToken as SelectionToken$1 } from "@embedpdf/plugin-selection/contract/host";
 export * from "@embedpdf/plugin-selection";
 //#region src/selection.tsx
-function SelectionLayer({ color = "rgba(33, 150, 243, 0.35)" }) {
+/**
+* The highlight of the selected text on one page, in the selection plugin's
+* `color` setting; the `--epdf-text-selection` CSS variable wins over it.
+*/
+function SelectionLayer() {
 	const page = usePage();
 	const selection = useCapability(SelectionToken$1);
-	const segments = useSelector(SelectionToken$1, (c) => c.segmentsForPage(page.pon), shallowArray);
-	const visible = useSelector(SelectionToken$1, (c) => c.highlightVisible());
+	const segments = useSelector(SelectionToken$1, (selection) => selection.listSegments(page.ref), shallowArray);
+	const visible = useSelector(SelectionToken$1, (selection) => selection.isHighlightVisible());
+	const color = useSelectionSettings((settings) => settings.color);
+	const accent = useViewerSettings((settings) => settings.accent);
 	useEffect(() => {
-		selection.ensurePage(page.pon);
-	}, [selection, page.pon]);
+		selection.ensureLoaded(page.ref);
+	}, [selection, page.ref]);
 	if (!visible) return null;
+	const fill = paint("text-selection", color ?? mixAccent("text-selection", accent));
 	return /* @__PURE__ */ jsx("svg", {
 		style: {
 			position: "absolute",
@@ -28,47 +34,45 @@ function SelectionLayer({ color = "rgba(33, 150, 243, 0.35)" }) {
 			overflow: "visible",
 			pointerEvents: "none"
 		},
-		children: segments.map((s, i) => {
-			return /* @__PURE__ */ jsx("polygon", {
-				points: [
-					s.quad.upperStart,
-					s.quad.upperEnd,
-					s.quad.lowerEnd,
-					s.quad.lowerStart
-				].map((p) => page.transform.toPixels(p)).map((p) => `${p.x},${p.y}`).join(" "),
-				fill: color
-			}, i);
-		})
+		children: segments.map((segment, i) => /* @__PURE__ */ jsx("polygon", {
+			points: svgPoints(quadInPixels(segment.quad, page.transform)),
+			style: { fill }
+		}, i))
 	});
 }
-/** The PUBLIC selection capability (select(), readText(), canCopy(), …) for
+/** The public selection capability (select(), readText(), canCopy(), …) for
 *  app chrome — toolbars, context menus, automation. */
 function useSelection() {
 	return useCapability(SelectionToken);
 }
-/** Structural equality for the selection's menu anchor — keeps the menu from
-*  re-rendering on unrelated dispatches (the capability returns a fresh
-*  object each call). */
-const sameMenuAnchor = (a, b) => {
-	if (a === b) return true;
-	if (!a || !b) return false;
-	return a.pon === b.pon && a.bounds.x === b.bounds.x && a.bounds.y === b.bounds.y && a.bounds.width === b.bounds.width && a.bounds.height === b.bounds.height;
-};
+/** Subscribe to one selection event for the mounted lifetime: `useSelectionEvent((selection) => selection.onCommitted, handler)`. */
+function useSelectionEvent(select, handler) {
+	useCapabilityEvent(SelectionToken, select, handler);
+}
+/**
+* The selection's state: whether anything is selected, whether the user is
+* still selecting, the character range and the pages it's on (the page's State
+* table, declared once in `selectionState`). Takes a selector, re-renders only
+* when what it returns changes, and returns the empty state without a document.
+*/
+const useSelectionState = stateHook(selectionState);
+/** The selection settings (`dragThreshold`, `color`, `handles`), with or without a document. Takes a selector. */
+const useSelectionSettings = settingsHook(SelectionToken);
 /**
-* Floats over the current TEXT selection (one anchor regardless of
+* Floats over the current text selection (one anchor regardless of
 * cross-page selection; it rides the gesture's end page) — and only once the
-* selection SETTLES: hidden while `isSelecting()` (mid-drag), it appears at
+* selection settles: hidden while a gesture is active (mid-drag), it appears at
 * pointer-up; programmatic selections show immediately (born settled). Works
 * under `<Stage>` (mount in the overlay slot) and `<PageView>` alike — the
 * surface provides the projection. Compose the contents from hooks:
 * `useSelection()` for copy/clear, `useAnnotation()` for
 * `markupFromSelection('highlight')`, `copySelection` for the clipboard.
 * For live-follow UI during the drag, compose `<Anchored>` with
-* `menuAnchor()` yourself — the primitive carries no policy.
+* `getAnchor()` yourself — the primitive carries no policy.
 */
 function SelectionMenu({ children, gap = 8, placement = "top" }) {
-	const selecting = useSelector(SelectionToken, (c) => c.isSelecting());
-	const anchor = useSelector(SelectionToken, (c) => c.menuAnchor(), sameMenuAnchor);
+	const selecting = useSelectionState((state) => state.isSelecting);
+	const anchor = useSelector(SelectionToken, (selection) => selection.getAnchor(), samePageBounds);
 	if (selecting || !anchor) return null;
 	return /* @__PURE__ */ jsx(Anchored, {
 		anchor,
@@ -77,60 +81,37 @@ function SelectionMenu({ children, gap = 8, placement = "top" }) {
 		children
 	});
 }
-const sameEndpoints = (a, b) => {
-	if (a === b) return true;
-	if (!a || !b) return false;
-	return a.start.pon === b.start.pon && a.end.pon === b.end.pon && a.start.advance === b.start.advance && a.end.advance === b.end.advance && textQuadEquals(a.start.glyphQuad, b.start.glyphQuad) && textQuadEquals(a.end.glyphQuad, b.end.glyphQuad);
-};
-/** The plugin's structural view over this Stage: point-exact projection in,
-*  page resolution out. (`pageRectToScreen` is the AABB projector — upright
-*  overlays only — and would collapse exactly the orientation handles need.) */
-const handleView = (stage) => ({
-	toOverlay: (pon, pt) => {
-		const world = stage.pageToWorld(pon, pt);
-		return world ? stage.toScreen(world) : null;
-	},
-	pageAt: (overlay) => stage.pageAt(overlay),
-	pointOnPage: (pon, overlay) => stage.pointOnPage(pon, overlay)
-});
 /**
 * iOS-style draggable selection handles. Each is drawn the way the platform
-* draws them: a thin caret BAR that forms the selection's own start/end edge
+* draws them: a thin caret bar that forms the selection's own start/end edge
 * — the boundary glyph's oriented edge, so rotated text and rotated pages
 * carry the handle with them — capped by a screen-constant circle, above the
 * first line at the start, below the last line at the end.
 *
-* On touch, where a caret drag isn't available, the handles ARE the way to
+* On touch, where a caret drag isn't available, the handles are the way to
 * grow or shrink a selection: a long-press selects a word, then each handle
-* extends from the OPPOSITE endpoint, snapping to glyphs and crossing pages
-* exactly like a pointer drag — it rides the same `beginAt`/`extendTo`
+* extends from the opposite endpoint, snapping to glyphs and crossing pages
+* exactly like a pointer drag — it rides the same `beginGestureAt`/`extendTo`
 * gesture path, so highlights, menus, and commit signals all behave
 * identically. Mount in the `<Stage>` overlay slot next to `<SelectionMenu>`;
 * outside a Stage it renders nothing (a `PageView` has no camera to project
 * through). Pointer-isolated, so grabbing a handle never pans the stage.
+* Painted in the plugin's `handles` setting, which the
+* `--epdf-text-selection-handle` and `--epdf-text-selection-handle-shadow` CSS
+* variables override.
 */
-function SelectionHandles({ color = "#2196f3", token = StageToken }) {
+function SelectionHandles({ token: explicitToken } = {}) {
+	const token = useStageToken(explicitToken);
 	const host = useCapability(SelectionToken$1);
 	const stage = useOptionalCapability(token);
-	const selecting = useSelector(SelectionToken, (c) => c.isSelecting());
-	const visible = useSelector(SelectionToken$1, (c) => c.highlightVisible());
-	const endpoints = useSelector(SelectionToken$1, (c) => {
-		const s = c.snapshot();
-		if (!s.start || !s.end) return null;
-		return {
-			start: {
-				pon: s.start.pon,
-				glyphQuad: s.start.glyphQuad,
-				advance: s.start.advance
-			},
-			end: {
-				pon: s.end.pon,
-				glyphQuad: s.end.glyphQuad,
-				advance: s.end.advance
-			}
-		};
-	}, sameEndpoints);
-	useKernelValue(() => stage?.visiblePages() ?? null);
+	const surface = useOptionalProjectorBinding();
+	if (!surface || surface.projector.space !== "overlay") devWarn("selection-handles-outside-stage", "<SelectionHandles> renders nothing here: mount it in the <Stage> overlay slot (a <PageView> has no camera to project the handles through).");
+	const selecting = useSelectionState((state) => state.isSelecting);
+	const visible = useSelector(SelectionToken$1, (selection) => selection.isHighlightVisible());
+	const handles = useSelectionSettings((settings) => settings.handles);
+	const accent = useViewerSettings((settings) => settings.accent);
+	const endpoints = useSelector(SelectionToken$1, (selection) => selectionHandleEndpointsOf(selection.getSnapshot()), sameSelectionEndpoints);
+	useKernelValue(() => stage?.listVisiblePages() ?? null);
 	const [dragging, setDragging] = useState(null);
 	const armSource = useRef(null);
 	armSource.current = stage && endpoints ? {
@@ -139,28 +120,22 @@ function SelectionHandles({ color = "#2196f3", token = StageToken }) {
 	} : null;
 	const bindHandle = useMemo(() => {
 		const detach = {};
-		const make = (role) => (el) => {
+		const make = (role) => (element) => {
 			detach[role]?.();
 			delete detach[role];
-			if (!el) return;
-			detach[role] = attachSelectionHandle(el, { arm: () => {
+			if (!element) return;
+			detach[role] = attachSelectionHandle(element, { arm: () => {
 				const src = armSource.current;
 				if (!src) return null;
-				const view = handleView(src.stage);
-				const geom = selectionHandleGeom(view, src.endpoints[role], role);
-				if (!geom) return null;
-				const opposite = src.endpoints[role === "start" ? "end" : "start"];
-				const drag = createSelectionHandleDrag(host, view, opposite, src.endpoints[role].pon);
+				const armed = armSelectionHandle(host, selectionHandleViewOf(src.stage), src.endpoints, role);
+				if (!armed) return null;
 				setDragging(role);
 				return {
-					base: {
-						x: (geom.bar.from.x + geom.bar.to.x) / 2,
-						y: (geom.bar.from.y + geom.bar.to.y) / 2
-					},
+					base: armed.base,
 					session: {
-						move: drag.move,
+						move: armed.drag.move,
 						end: () => {
-							drag.end();
+							armed.drag.end();
 							setDragging(null);
 						}
 					}
@@ -174,22 +149,24 @@ function SelectionHandles({ color = "#2196f3", token = StageToken }) {
 	}, [host]);
 	if (!stage || !endpoints || !visible) return null;
 	if (selecting && !dragging) return null;
-	const view = handleView(stage);
+	const view = selectionHandleViewOf(stage);
+	const color = paint("text-selection-handle", handles.color ?? accent);
+	const shadow = paint("text-selection-handle-shadow", handles.shadow);
 	const renderHandle = (role) => {
-		const geom = selectionHandleGeom(view, endpoints[role], role);
-		if (!geom) return null;
+		const geometry = selectionHandleGeom(view, endpoints[role], role);
+		if (!geometry) return null;
 		const barTop = HANDLE_PAD + (role === "start" ? HANDLE_HEAD : 0);
 		const pivotX = HANDLE_PAD + HANDLE_BAR / 2;
 		return /* @__PURE__ */ jsxs("div", {
 			ref: bindHandle[role],
 			style: {
 				position: "absolute",
-				left: geom.bar.from.x - pivotX,
-				top: geom.bar.from.y - barTop,
+				left: geometry.bar.from.x - pivotX,
+				top: geometry.bar.from.y - barTop,
 				width: HANDLE_BAR + 2 * HANDLE_PAD,
-				height: geom.length + HANDLE_HEAD + 2 * HANDLE_PAD,
-				...geom.upright ? null : {
-					transform: `rotate(${geom.rotation}deg)`,
+				height: geometry.length + HANDLE_HEAD + 2 * HANDLE_PAD,
+				...geometry.upright ? null : {
+					transform: `rotate(${geometry.rotation}deg)`,
 					transformOrigin: `${pivotX}px ${barTop}px`
 				},
 				touchAction: "none",
@@ -201,36 +178,52 @@ function SelectionHandles({ color = "#2196f3", token = StageToken }) {
 				left: HANDLE_PAD,
 				top: barTop,
 				width: HANDLE_BAR,
-				height: geom.length,
+				height: geometry.length,
 				background: color,
 				borderRadius: HANDLE_BAR / 2
 			} }), /* @__PURE__ */ jsx("div", { style: {
 				position: "absolute",
 				left: pivotX - HANDLE_HEAD / 2,
-				top: role === "start" ? HANDLE_PAD : HANDLE_PAD + geom.length,
+				top: role === "start" ? HANDLE_PAD : HANDLE_PAD + geometry.length,
 				width: HANDLE_HEAD,
 				height: HANDLE_HEAD,
 				borderRadius: "50%",
 				background: color,
-				boxShadow: "0 1px 4px rgba(0, 0, 0, 0.35)"
+				boxShadow: shadow
 			} })]
 		}, role);
 	};
 	return /* @__PURE__ */ jsxs(Fragment, { children: [renderHandle("start"), renderHandle("end")] });
 }
 /**
-* Mount ONCE per viewer to wire clipboard copy: prefetches the selected text
+* Mount once per viewer to wire clipboard copy: prefetches the selected text
 * when the selection settles, answers the native `copy` event synchronously,
 * and falls back to the async Clipboard API for ctrl/cmd+C when the page has
-* no DOM selection. Renders nothing. For a toolbar Copy button, call
-* `copySelection(useSelection())` from its click handler instead.
+* no DOM selection. A selection the user may not copy isn't copied, and
+* `onRefused` is called. Renders nothing, and wires nothing until a document
+* is ready. For a toolbar Copy button, call `copySelection(useSelection())`
+* from its click handler instead.
 */
-function SelectionClipboard({ prefetch } = {}) {
-	const selection = useCapability(SelectionToken);
-	useEffect(() => wireSelectionClipboard(selection, prefetch === void 0 ? {} : { prefetch }), [selection, prefetch]);
+function SelectionClipboard({ prefetch, onRefused, target } = {}) {
+	const selection = useOptionalCapability(SelectionToken);
+	const refused = useRef(onRefused);
+	refused.current = onRefused;
+	useEffect(() => {
+		const element = target ? target.current : void 0;
+		if (!selection || element === null) return;
+		return wireSelectionClipboard(selection, {
+			...prefetch === void 0 ? {} : { prefetch },
+			...element ? { target: element } : {},
+			onRefused: () => refused.current?.()
+		});
+	}, [
+		selection,
+		prefetch,
+		target
+	]);
 	return null;
 }
 //#endregion
-export { SelectionClipboard, SelectionHandles, SelectionLayer, SelectionMenu, copySelection, useSelection };
+export { SelectionClipboard, SelectionHandles, SelectionLayer, SelectionMenu, copySelection, useSelection, useSelectionEvent, useSelectionSettings, useSelectionState };
 
 //# sourceMappingURL=selection.js.map

package/dist/selection.js.map

@@ -1 +1 @@
-{"version":3,"file":"selection.js","names":["SelectionHostToken"],"sources":["../src/selection.tsx"],"sourcesContent":["/**\n * The React surface for @embedpdf/plugin-selection.\n *\n * <SelectionLayer> is a dumb renderer: it warms the page's geometry on mount,\n * reads the content-space highlight rects from the capability, and paints them —\n * mapping each rect through PageContext.toPixels (the same path markers use).\n * Zero pointer handling here; that's the PagePointerSource + the hub.\n *\n * The layer resolves the HOST lens (`/internal`: geometry warming, the\n * highlight handshake) — the adapter is exactly what that entry exists for.\n * `useSelection()` hands app code the PUBLIC lens only.\n */\n\n// One-line-per-feature: registration travels with the UI.\nexport * from '@embedpdf/plugin-selection';\n// The clipboard side effect lives in @embedpdf/web (the plugin is DOM-free);\n// re-exported here so app code has one import for the whole feature.\nexport { copySelection } from '@embedpdf/web';\nimport * as React from 'react';\nimport { useEffect, useMemo, useRef, useState } from 'react';\nimport { textQuadEquals } from '@embedpdf/core-geometry';\nimport type { CapabilityToken } from '@embedpdf/core';\nimport {\n  HANDLE_BAR,\n  HANDLE_HEAD,\n  HANDLE_PAD,\n  SelectionToken,\n  createSelectionHandleDrag,\n  selectionHandleGeom,\n  type SelectionHandleEndpoint,\n  type SelectionHandleView,\n  type SelectionMenuAnchor,\n} from '@embedpdf/plugin-selection';\nimport { SelectionToken as SelectionHostToken } from '@embedpdf/plugin-selection/internal';\nimport { StageToken, type StageCapability } from '@embedpdf/plugin-stage/contract';\nimport {\n  attachSelectionHandle,\n  wireSelectionClipboard,\n  type SelectionClipboardOptions,\n} from '@embedpdf/web';\nimport { Anchored, type AnchoredPlacement } from './anchored';\nimport {\n  shallowArray,\n  useCapability,\n  useKernelValue,\n  useOptionalCapability,\n  usePage,\n  useSelector,\n} from './runtime';\n\nexport interface SelectionLayerProps {\n  /** Highlight colour (default: translucent blue). */\n  color?: string;\n}\n\nexport function SelectionLayer({ color = 'rgba(33, 150, 243, 0.35)' }: SelectionLayerProps) {\n  const page = usePage();\n  const selection = useCapability(SelectionHostToken);\n  const segments = useSelector(\n    SelectionHostToken,\n    (c) => c.segmentsForPage(page.pon),\n    shallowArray,\n  );\n  // A consumer (e.g. a markup tool drawing its own preview) can take over the\n  // selection visual; when it does, we render nothing so the two never overlap.\n  const visible = useSelector(SelectionHostToken, (c) => c.highlightVisible());\n\n  // Warm this page's text geometry as soon as it's on screen, so the first\n  // pointer-down can hit-test without waiting on the engine round-trip.\n  // (A no-op without doc.text.select — nothing warms, nothing renders.)\n  useEffect(() => {\n    selection.ensurePage(page.pon);\n  }, [selection, page.pon]);\n\n  if (!visible) return null;\n\n  return (\n    <svg\n      style={{\n        position: 'absolute',\n        inset: 0,\n        width: '100%',\n        height: '100%',\n        overflow: 'visible',\n        pointerEvents: 'none',\n      }}\n    >\n      {segments.map((s, i) => {\n        // content space → un-rotated content view px (rides the page's CSS\n        // rotation). An affine map, so mapping the four corners is exact —\n        // upright segments render pixel-identical to the old div-per-rect.\n        const ring = [s.quad.upperStart, s.quad.upperEnd, s.quad.lowerEnd, s.quad.lowerStart].map(\n          (p) => page.transform.toPixels(p),\n        );\n        return (\n          <polygon key={i} points={ring.map((p) => `${p.x},${p.y}`).join(' ')} fill={color} />\n        );\n      })}\n    </svg>\n  );\n}\n\n/** The PUBLIC selection capability (select(), readText(), canCopy(), …) for\n *  app chrome — toolbars, context menus, automation. */\nexport function useSelection() {\n  return useCapability(SelectionToken);\n}\n\n/** Structural equality for the selection's menu anchor — keeps the menu from\n *  re-rendering on unrelated dispatches (the capability returns a fresh\n *  object each call). */\nconst sameMenuAnchor = (\n  a: SelectionMenuAnchor | null,\n  b: SelectionMenuAnchor | null,\n): boolean => {\n  if (a === b) return true;\n  if (!a || !b) return false;\n  return (\n    a.pon === b.pon &&\n    a.bounds.x === b.bounds.x &&\n    a.bounds.y === b.bounds.y &&\n    a.bounds.width === b.bounds.width &&\n    a.bounds.height === b.bounds.height\n  );\n};\n\nexport interface SelectionMenuProps {\n  children: React.ReactNode;\n  /** Gap in screen px between the selection and the menu (default 8). */\n  gap?: number;\n  /** Where to place the menu relative to the selection. Default 'top'. */\n  placement?: AnchoredPlacement;\n}\n\n/**\n * Floats over the current TEXT selection (one anchor regardless of\n * cross-page selection; it rides the gesture's end page) — and only once the\n * selection SETTLES: hidden while `isSelecting()` (mid-drag), it appears at\n * pointer-up; programmatic selections show immediately (born settled). Works\n * under `<Stage>` (mount in the overlay slot) and `<PageView>` alike — the\n * surface provides the projection. Compose the contents from hooks:\n * `useSelection()` for copy/clear, `useAnnotation()` for\n * `markupFromSelection('highlight')`, `copySelection` for the clipboard.\n * For live-follow UI during the drag, compose `<Anchored>` with\n * `menuAnchor()` yourself — the primitive carries no policy.\n */\nexport function SelectionMenu({ children, gap = 8, placement = 'top' }: SelectionMenuProps) {\n  const selecting = useSelector(SelectionToken, (c) => c.isSelecting());\n  const anchor = useSelector(SelectionToken, (c) => c.menuAnchor(), sameMenuAnchor);\n  if (selecting || !anchor) return null;\n  return (\n    <Anchored anchor={anchor} placement={placement} gap={gap}>\n      {children}\n    </Anchored>\n  );\n}\n\n// ── selection handles (the touch affordance) ────────────────────────────────\n//\n// Policy lives out of this file, per the layering razor: the geometry and the\n// drag session are `@embedpdf/plugin-selection`'s pure `handles` module (one\n// source for every adapter), the native listener mechanics are\n// `@embedpdf/web`'s `attachSelectionHandle` (the down-shield timing subtlety\n// lives ONCE), and this component keeps what only React can do —\n// subscriptions, markup, theming.\n\ninterface Endpoints {\n  start: SelectionHandleEndpoint;\n  end: SelectionHandleEndpoint;\n}\nconst sameEndpoints = (a: Endpoints | null, b: Endpoints | null): boolean => {\n  if (a === b) return true;\n  if (!a || !b) return false;\n  return (\n    a.start.pon === b.start.pon &&\n    a.end.pon === b.end.pon &&\n    a.start.advance === b.start.advance &&\n    a.end.advance === b.end.advance &&\n    // corner-wise, so a boundary that ROTATES without moving its bounding box\n    // still re-renders (an AABB comparison would call that \"unchanged\")\n    textQuadEquals(a.start.glyphQuad, b.start.glyphQuad) &&\n    textQuadEquals(a.end.glyphQuad, b.end.glyphQuad)\n  );\n};\n\n/** The plugin's structural view over this Stage: point-exact projection in,\n *  page resolution out. (`pageRectToScreen` is the AABB projector — upright\n *  overlays only — and would collapse exactly the orientation handles need.) */\nconst handleView = (stage: StageCapability): SelectionHandleView => ({\n  toOverlay: (pon, pt) => {\n    const world = stage.pageToWorld(pon, pt);\n    return world ? stage.toScreen(world) : null;\n  },\n  pageAt: (overlay) => stage.pageAt(overlay),\n  pointOnPage: (pon, overlay) => stage.pointOnPage(pon, overlay),\n});\n\nexport interface SelectionHandlesProps {\n  /** Handle colour (default: the selection blue). */\n  color?: string;\n  /** The stage lens hosting this overlay (default: the main StageToken). */\n  token?: CapabilityToken<StageCapability>;\n}\n\n/**\n * iOS-style draggable selection handles. Each is drawn the way the platform\n * draws them: a thin caret BAR that forms the selection's own start/end edge\n * — the boundary glyph's oriented edge, so rotated text and rotated pages\n * carry the handle with them — capped by a screen-constant circle, above the\n * first line at the start, below the last line at the end.\n *\n * On touch, where a caret drag isn't available, the handles ARE the way to\n * grow or shrink a selection: a long-press selects a word, then each handle\n * extends from the OPPOSITE endpoint, snapping to glyphs and crossing pages\n * exactly like a pointer drag — it rides the same `beginAt`/`extendTo`\n * gesture path, so highlights, menus, and commit signals all behave\n * identically. Mount in the `<Stage>` overlay slot next to `<SelectionMenu>`;\n * outside a Stage it renders nothing (a `PageView` has no camera to project\n * through). Pointer-isolated, so grabbing a handle never pans the stage.\n */\nexport function SelectionHandles({ color = '#2196f3', token = StageToken }: SelectionHandlesProps) {\n  const host = useCapability(SelectionHostToken);\n  const stage = useOptionalCapability(token);\n  const selecting = useSelector(SelectionToken, (c) => c.isSelecting());\n  const visible = useSelector(SelectionHostToken, (c) => c.highlightVisible());\n  const endpoints = useSelector(\n    SelectionHostToken,\n    (c): Endpoints | null => {\n      const s = c.snapshot();\n      if (!s.start || !s.end) return null;\n      return {\n        start: { pon: s.start.pon, glyphQuad: s.start.glyphQuad, advance: s.start.advance },\n        end: { pon: s.end.pon, glyphQuad: s.end.glyphQuad, advance: s.end.advance },\n      };\n    },\n    sameEndpoints,\n  );\n  // The handles are positioned by PROJECTING the endpoint corners through the\n  // camera, so they must re-render whenever the camera moves — visiblePages is\n  // the stage's reference-stable revision for exactly that (the same value the\n  // page surfaces re-render on, so handle and highlight move in one commit).\n  useKernelValue(() => stage?.visiblePages() ?? null);\n  const [dragging, setDragging] = useState<'start' | 'end' | null>(null);\n  // The web binder's `arm` must read the CURRENT endpoints/stage at pointer\n  // down, not the ones captured when the listener attached — a stable ref\n  // callback with a live arm-source is the standard escape from that.\n  const armSource = useRef<{ stage: StageCapability; endpoints: Endpoints } | null>(null);\n  armSource.current = stage && endpoints ? { stage, endpoints } : null;\n  const bindHandle = useMemo(() => {\n    const detach: Partial<Record<'start' | 'end', () => void>> = {};\n    const make = (role: 'start' | 'end') => (el: HTMLDivElement | null) => {\n      detach[role]?.();\n      delete detach[role];\n      if (!el) return;\n      detach[role] = attachSelectionHandle(el, {\n        arm: () => {\n          const src = armSource.current;\n          if (!src) return null;\n          const view = handleView(src.stage);\n          const geom = selectionHandleGeom(view, src.endpoints[role], role);\n          if (!geom) return null;\n          const opposite = src.endpoints[role === 'start' ? 'end' : 'start'];\n          const drag = createSelectionHandleDrag(\n            host,\n            view,\n            opposite,\n            src.endpoints[role].pon,\n          );\n          setDragging(role);\n          return {\n            // the point the user grabbed: the bar's midpoint\n            base: {\n              x: (geom.bar.from.x + geom.bar.to.x) / 2,\n              y: (geom.bar.from.y + geom.bar.to.y) / 2,\n            },\n            session: {\n              move: drag.move,\n              end: () => {\n                drag.end(); // settle → menu reappears, onCommit fires\n                setDragging(null);\n              },\n            },\n          };\n        },\n      });\n    };\n    return { start: make('start'), end: make('end') };\n  }, [host]);\n\n  if (!stage || !endpoints || !visible) return null;\n  // Hidden while a pointer drag-select is in flight (like the menu) — but a\n  // HANDLE drag is itself a selection gesture, so it keeps its handles.\n  if (selecting && !dragging) return null;\n  const view = handleView(stage);\n\n  const renderHandle = (role: 'start' | 'end') => {\n    const geom = selectionHandleGeom(view, endpoints[role], role);\n    if (!geom) return null; // endpoint page not laid out right now\n    // The shell is laid out UPRIGHT in its own frame — bar of the edge's\n    // length, head stacked above (start) or below (end) — then rotated onto\n    // the projected edge. The pivot is the bar's ascent-side tip, the one\n    // point that must land exactly on the glyph corner.\n    const barTop = HANDLE_PAD + (role === 'start' ? HANDLE_HEAD : 0);\n    const pivotX = HANDLE_PAD + HANDLE_BAR / 2;\n    return (\n      <div\n        key={role}\n        ref={bindHandle[role]}\n        style={{\n          position: 'absolute',\n          left: geom.bar.from.x - pivotX,\n          top: geom.bar.from.y - barTop,\n          width: HANDLE_BAR + 2 * HANDLE_PAD,\n          height: geom.length + HANDLE_HEAD + 2 * HANDLE_PAD,\n          // Upright text carries NO transform — pixel-identical to an\n          // axis-aligned box (the geometry's float-noise guard decides).\n          ...(geom.upright\n            ? null\n            : {\n                transform: `rotate(${geom.rotation}deg)`,\n                transformOrigin: `${pivotX}px ${barTop}px`,\n              }),\n          touchAction: 'none',\n          cursor: 'grab',\n          pointerEvents: 'auto',\n        }}\n      >\n        {/* the caret bar — the selection's own edge, spanning the glyph's ink\n            height (which is why it stays the text's height at any tilt) */}\n        <div\n          style={{\n            position: 'absolute',\n            left: HANDLE_PAD,\n            top: barTop,\n            width: HANDLE_BAR,\n            height: geom.length,\n            background: color,\n            borderRadius: HANDLE_BAR / 2,\n          }}\n        />\n        {/* the head — flush against the bar, beyond the ascent at the start and\n            past the baseline at the end, in the TEXT's frame */}\n        <div\n          style={{\n            position: 'absolute',\n            left: pivotX - HANDLE_HEAD / 2,\n            top: role === 'start' ? HANDLE_PAD : HANDLE_PAD + geom.length,\n            width: HANDLE_HEAD,\n            height: HANDLE_HEAD,\n            borderRadius: '50%',\n            background: color,\n            boxShadow: '0 1px 4px rgba(0, 0, 0, 0.35)',\n          }}\n        />\n      </div>\n    );\n  };\n\n  return (\n    <>\n      {renderHandle('start')}\n      {renderHandle('end')}\n    </>\n  );\n}\n\n\nexport type SelectionClipboardProps = Pick<SelectionClipboardOptions, 'prefetch'>;\n\n/**\n * Mount ONCE per viewer to wire clipboard copy: prefetches the selected text\n * when the selection settles, answers the native `copy` event synchronously,\n * and falls back to the async Clipboard API for ctrl/cmd+C when the page has\n * no DOM selection. Renders nothing. For a toolbar Copy button, call\n * `copySelection(useSelection())` from its click handler instead.\n */\nexport function SelectionClipboard({ prefetch }: SelectionClipboardProps = {}) {\n  const selection = useCapability(SelectionToken);\n  useEffect(\n    () => wireSelectionClipboard(selection, prefetch === undefined ? {} : { prefetch }),\n    [selection, prefetch],\n  );\n  return null;\n}\n"],"mappings":"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"}
+{"version":3,"file":"selection.js","names":["SelectionHostToken"],"sources":["../src/selection.tsx"],"sourcesContent":["/**\n * The React surface for @embedpdf/plugin-selection.\n *\n * <SelectionLayer> is a dumb renderer: it warms the page's geometry on mount,\n * reads the page-space highlight rects from the capability, and paints them —\n * mapping each rect through PageContext.toPixels (the same path markers use),\n * in the plugin's `color` setting, which the `--epdf-text-selection` CSS\n * variable overrides. Zero pointer handling here; that's the\n * PagePointerSource + the hub.\n *\n * The layer resolves the host lens (`/contract/host`: geometry warming, the\n * highlight handshake) — the adapter is exactly what that entry exists for.\n * `useSelection()` hands app code the public lens only.\n */\n\n// One-line-per-feature: registration travels with the UI.\nexport * from '@embedpdf/plugin-selection';\n// The clipboard side effect lives in @embedpdf/web (the plugin is DOM-free);\n// re-exported here so app code has one import for the whole feature.\nexport { copySelection } from '@embedpdf/web';\nimport * as React from 'react';\nimport { useEffect, useMemo, useRef, useState, type RefObject } from 'react';\nimport type { CapabilityToken, EventHook } from '@embedpdf/core';\nimport {\n  HANDLE_BAR,\n  HANDLE_HEAD,\n  HANDLE_PAD,\n  SelectionToken,\n  armSelectionHandle,\n  selectionHandleEndpointsOf,\n  selectionHandleGeom,\n  selectionHandleViewOf,\n  selectionState,\n  type SelectionHandleEndpoints,\n  type SelectionCapability,\n} from '@embedpdf/plugin-selection';\nimport { SelectionToken as SelectionHostToken } from '@embedpdf/plugin-selection/contract/host';\nimport type { StageCapability } from '@embedpdf/plugin-stage/contract';\nimport {\n  attachSelectionHandle,\n  mixAccent,\n  paint,\n  quadInPixels,\n  samePageBounds,\n  sameSelectionEndpoints,\n  svgPoints,\n  wireSelectionClipboard,\n  type SelectionClipboardOptions,\n} from '@embedpdf/web';\nimport { Anchored, useOptionalProjectorBinding, type AnchoredPlacement } from './anchored';\nimport { devWarn } from './dev';\nimport { useStageToken } from './stage-scope';\nimport {\n  shallowArray,\n  useCapability,\n  useCapabilityEvent,\n  useKernelValue,\n  useOptionalCapability,\n  usePage,\n  useSelector,\n  useViewerSettings,\n} from './runtime';\nimport { settingsHook, stateHook } from './state';\n\n/**\n * The highlight of the selected text on one page, in the selection plugin's\n * `color` setting; the `--epdf-text-selection` CSS variable wins over it.\n */\nexport function SelectionLayer() {\n  const page = usePage();\n  const selection = useCapability(SelectionHostToken);\n  const segments = useSelector(\n    SelectionHostToken,\n    (selection) => selection.listSegments(page.ref),\n    shallowArray,\n  );\n  // A consumer (e.g. a markup tool drawing its own preview) can take over the\n  // selection visual; when it does, we render nothing so the two never overlap.\n  const visible = useSelector(SelectionHostToken, (selection) => selection.isHighlightVisible());\n  const color = useSelectionSettings((settings) => settings.color);\n  // An unset color follows the viewer's accent, behind the `--epdf-accent` variable.\n  const accent = useViewerSettings((settings) => settings.accent);\n\n  // Warm this page's text geometry as soon as it's on screen, so the first\n  // pointer-down can hit-test without waiting on the engine round-trip.\n  // (A no-op without doc.text.select — nothing warms, nothing renders.)\n  useEffect(() => {\n    void selection.ensureLoaded(page.ref);\n  }, [selection, page.ref]);\n\n  if (!visible) return null;\n\n  // Unset, the color is the accent at 35%, the accent variables included.\n  const fill = paint('text-selection', color ?? mixAccent('text-selection', accent));\n\n  return (\n    <svg\n      style={{\n        position: 'absolute',\n        inset: 0,\n        width: '100%',\n        height: '100%',\n        overflow: 'visible',\n        pointerEvents: 'none',\n      }}\n    >\n      {segments.map((segment, i) => (\n        // Page space → the page layer's pixels, which ride the page's CSS\n        // rotation: mapping the four corners is exact, for turned text too.\n        <polygon\n          key={i}\n          points={svgPoints(quadInPixels(segment.quad, page.transform))}\n          // In `style`: an SVG attribute doesn't read var().\n          style={{ fill }}\n        />\n      ))}\n    </svg>\n  );\n}\n\n/** The public selection capability (select(), readText(), canCopy(), …) for\n *  app chrome — toolbars, context menus, automation. */\nexport function useSelection() {\n  return useCapability(SelectionToken);\n}\n\n/** Subscribe to one selection event for the mounted lifetime: `useSelectionEvent((selection) => selection.onCommitted, handler)`. */\nexport function useSelectionEvent<T>(\n  select: (selection: SelectionCapability) => EventHook<T>,\n  handler: (event: T) => void,\n): void {\n  useCapabilityEvent(SelectionToken, select, handler);\n}\n\n/**\n * The selection's state: whether anything is selected, whether the user is\n * still selecting, the character range and the pages it's on (the page's State\n * table, declared once in `selectionState`). Takes a selector, re-renders only\n * when what it returns changes, and returns the empty state without a document.\n */\nexport const useSelectionState = stateHook(selectionState);\n\n/** The selection settings (`dragThreshold`, `color`, `handles`), with or without a document. Takes a selector. */\nexport const useSelectionSettings = settingsHook(SelectionToken);\n\nexport interface SelectionMenuProps {\n  children: React.ReactNode;\n  /** Gap in screen px between the selection and the menu (default 8). */\n  gap?: number;\n  /** Where to place the menu relative to the selection. Default 'top'. */\n  placement?: AnchoredPlacement;\n}\n\n/**\n * Floats over the current text selection (one anchor regardless of\n * cross-page selection; it rides the gesture's end page) — and only once the\n * selection settles: hidden while a gesture is active (mid-drag), it appears at\n * pointer-up; programmatic selections show immediately (born settled). Works\n * under `<Stage>` (mount in the overlay slot) and `<PageView>` alike — the\n * surface provides the projection. Compose the contents from hooks:\n * `useSelection()` for copy/clear, `useAnnotation()` for\n * `markupFromSelection('highlight')`, `copySelection` for the clipboard.\n * For live-follow UI during the drag, compose `<Anchored>` with\n * `getAnchor()` yourself — the primitive carries no policy.\n */\nexport function SelectionMenu({ children, gap = 8, placement = 'top' }: SelectionMenuProps) {\n  const selecting = useSelectionState((state) => state.isSelecting);\n  // The capability returns a fresh anchor on every read: compare by value, so\n  // the menu re-renders only when the selection moved.\n  const anchor = useSelector(SelectionToken, (selection) => selection.getAnchor(), samePageBounds);\n  if (selecting || !anchor) return null;\n  return (\n    <Anchored anchor={anchor} placement={placement} gap={gap}>\n      {children}\n    </Anchored>\n  );\n}\n\n// ── selection handles (the touch affordance) ────────────────────────────────\n//\n// Policy lives out of this file, per the layering razor: the view over the\n// Stage, the endpoints, the geometry and the armed drag are\n// `@embedpdf/plugin-selection`'s pure `handles` module (one source for every\n// adapter), the native listener mechanics are\n// `@embedpdf/web`'s `attachSelectionHandle` (the down-shield timing subtlety\n// lives once), and this component keeps what only React can do —\n// subscriptions, markup, theming.\n\nexport interface SelectionHandlesProps {\n  /** The stage lens hosting this overlay (default: the enclosing `<Stage>`'s lens). */\n  token?: CapabilityToken<StageCapability>;\n}\n\n/**\n * iOS-style draggable selection handles. Each is drawn the way the platform\n * draws them: a thin caret bar that forms the selection's own start/end edge\n * — the boundary glyph's oriented edge, so rotated text and rotated pages\n * carry the handle with them — capped by a screen-constant circle, above the\n * first line at the start, below the last line at the end.\n *\n * On touch, where a caret drag isn't available, the handles are the way to\n * grow or shrink a selection: a long-press selects a word, then each handle\n * extends from the opposite endpoint, snapping to glyphs and crossing pages\n * exactly like a pointer drag — it rides the same `beginGestureAt`/`extendTo`\n * gesture path, so highlights, menus, and commit signals all behave\n * identically. Mount in the `<Stage>` overlay slot next to `<SelectionMenu>`;\n * outside a Stage it renders nothing (a `PageView` has no camera to project\n * through). Pointer-isolated, so grabbing a handle never pans the stage.\n * Painted in the plugin's `handles` setting, which the\n * `--epdf-text-selection-handle` and `--epdf-text-selection-handle-shadow` CSS\n * variables override.\n */\nexport function SelectionHandles({ token: explicitToken }: SelectionHandlesProps = {}) {\n  const token = useStageToken(explicitToken);\n  const host = useCapability(SelectionHostToken);\n  const stage = useOptionalCapability(token);\n  // Outside a Stage there is no camera to project through: say so instead of\n  // rendering nothing silently.\n  const surface = useOptionalProjectorBinding();\n  if (!surface || surface.projector.space !== 'overlay') {\n    devWarn(\n      'selection-handles-outside-stage',\n      '<SelectionHandles> renders nothing here: mount it in the <Stage> overlay slot ' +\n        '(a <PageView> has no camera to project the handles through).',\n    );\n  }\n  const selecting = useSelectionState((state) => state.isSelecting);\n  const visible = useSelector(SelectionHostToken, (selection) => selection.isHighlightVisible());\n  const handles = useSelectionSettings((settings) => settings.handles);\n  const accent = useViewerSettings((settings) => settings.accent);\n  const endpoints = useSelector(\n    SelectionHostToken,\n    (selection) => selectionHandleEndpointsOf(selection.getSnapshot()),\n    sameSelectionEndpoints,\n  );\n  // The handles are positioned by projecting the endpoint corners through the\n  // camera, so they must re-render whenever the camera moves — visiblePages is\n  // the stage's reference-stable revision for exactly that (the same value the\n  // page surfaces re-render on, so handle and highlight move in one commit).\n  useKernelValue(() => stage?.listVisiblePages() ?? null);\n  const [dragging, setDragging] = useState<'start' | 'end' | null>(null);\n  // The web binder's `arm` must read the current endpoints/stage at pointer\n  // down, not the ones captured when the listener attached — a stable ref\n  // callback with a live arm-source is the standard escape from that.\n  const armSource = useRef<{ stage: StageCapability; endpoints: SelectionHandleEndpoints } | null>(\n    null,\n  );\n  armSource.current = stage && endpoints ? { stage, endpoints } : null;\n  const bindHandle = useMemo(() => {\n    const detach: Partial<Record<'start' | 'end', () => void>> = {};\n    const make = (role: 'start' | 'end') => (element: HTMLDivElement | null) => {\n      detach[role]?.();\n      delete detach[role];\n      if (!element) return;\n      detach[role] = attachSelectionHandle(element, {\n        arm: () => {\n          const src = armSource.current;\n          if (!src) return null;\n          const armed = armSelectionHandle(\n            host,\n            selectionHandleViewOf(src.stage),\n            src.endpoints,\n            role,\n          );\n          if (!armed) return null;\n          setDragging(role);\n          return {\n            // the point the user grabbed: the bar's midpoint\n            base: armed.base,\n            session: {\n              move: armed.drag.move,\n              end: () => {\n                armed.drag.end(); // settle → menu reappears, onCommitted fires\n                setDragging(null);\n              },\n            },\n          };\n        },\n      });\n    };\n    return { start: make('start'), end: make('end') };\n  }, [host]);\n\n  if (!stage || !endpoints || !visible) return null;\n  // Hidden while a pointer drag-select is in flight (like the menu) — but a\n  // handle drag is itself a selection gesture, so it keeps its handles.\n  if (selecting && !dragging) return null;\n  const view = selectionHandleViewOf(stage);\n  // Each is its CSS variable first, then the setting; an unset color is the accent.\n  const color = paint('text-selection-handle', handles.color ?? accent);\n  const shadow = paint('text-selection-handle-shadow', handles.shadow);\n\n  const renderHandle = (role: 'start' | 'end') => {\n    const geometry = selectionHandleGeom(view, endpoints[role], role);\n    if (!geometry) return null; // endpoint page not laid out right now\n    // The shell is laid out upright in its own frame — bar of the edge's\n    // length, head stacked above (start) or below (end) — then rotated onto\n    // the projected edge. The pivot is the bar's ascent-side tip, the one\n    // point that must land exactly on the glyph corner.\n    const barTop = HANDLE_PAD + (role === 'start' ? HANDLE_HEAD : 0);\n    const pivotX = HANDLE_PAD + HANDLE_BAR / 2;\n    return (\n      <div\n        key={role}\n        ref={bindHandle[role]}\n        style={{\n          position: 'absolute',\n          left: geometry.bar.from.x - pivotX,\n          top: geometry.bar.from.y - barTop,\n          width: HANDLE_BAR + 2 * HANDLE_PAD,\n          height: geometry.length + HANDLE_HEAD + 2 * HANDLE_PAD,\n          // Upright text carries no transform — pixel-identical to an\n          // axis-aligned box (the geometry's float-noise guard decides).\n          ...(geometry.upright\n            ? null\n            : {\n                transform: `rotate(${geometry.rotation}deg)`,\n                transformOrigin: `${pivotX}px ${barTop}px`,\n              }),\n          touchAction: 'none',\n          cursor: 'grab',\n          pointerEvents: 'auto',\n        }}\n      >\n        {/* the caret bar — the selection's own edge, spanning the glyph's ink\n            height (which is why it stays the text's height at any tilt) */}\n        <div\n          style={{\n            position: 'absolute',\n            left: HANDLE_PAD,\n            top: barTop,\n            width: HANDLE_BAR,\n            height: geometry.length,\n            background: color,\n            borderRadius: HANDLE_BAR / 2,\n          }}\n        />\n        {/* the head — flush against the bar, beyond the ascent at the start and\n            past the baseline at the end, in the TEXT's frame */}\n        <div\n          style={{\n            position: 'absolute',\n            left: pivotX - HANDLE_HEAD / 2,\n            top: role === 'start' ? HANDLE_PAD : HANDLE_PAD + geometry.length,\n            width: HANDLE_HEAD,\n            height: HANDLE_HEAD,\n            borderRadius: '50%',\n            background: color,\n            boxShadow: shadow,\n          }}\n        />\n      </div>\n    );\n  };\n\n  return (\n    <>\n      {renderHandle('start')}\n      {renderHandle('end')}\n    </>\n  );\n}\n\nexport interface SelectionClipboardProps\n  extends Pick<SelectionClipboardOptions, 'prefetch' | 'onRefused'> {\n  /**\n   * Copy only while focus is inside this element, for a page with more than one viewer.\n   * Default: anywhere on the page.\n   */\n  target?: RefObject<HTMLElement | null>;\n}\n\n/**\n * Mount once per viewer to wire clipboard copy: prefetches the selected text\n * when the selection settles, answers the native `copy` event synchronously,\n * and falls back to the async Clipboard API for ctrl/cmd+C when the page has\n * no DOM selection. A selection the user may not copy isn't copied, and\n * `onRefused` is called. Renders nothing, and wires nothing until a document\n * is ready. For a toolbar Copy button, call `copySelection(useSelection())`\n * from its click handler instead.\n */\nexport function SelectionClipboard({ prefetch, onRefused, target }: SelectionClipboardProps = {}) {\n  const selection = useOptionalCapability(SelectionToken);\n  // The latest callback, so a new function each render doesn't wire the clipboard again.\n  const refused = useRef(onRefused);\n  refused.current = onRefused;\n  useEffect(() => {\n    // The element mounts before this effect runs, so its ref is set by now.\n    const element = target ? target.current : undefined;\n    if (!selection || element === null) return;\n    return wireSelectionClipboard(selection, {\n      ...(prefetch === undefined ? {} : { prefetch }),\n      ...(element ? { target: element } : {}),\n      onRefused: () => refused.current?.(),\n    });\n  }, [selection, prefetch, target]);\n  return null;\n}\n"],"mappings":"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"}

package/dist/shell.cjs

@@ -1,25 +1,37 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("./rolldown-runtime-DDXJien1.cjs");
-const require_runtime = require("./runtime.cjs");
+const require_runtime = require("./runtime-fzpGv78v.cjs");
+const require_state = require("./state-CsfZy_Eq.cjs");
+let _embedpdf_web = require("@embedpdf/web");
 let react = require("react");
 let _embedpdf_plugin_shell = require("@embedpdf/plugin-shell");
 //#region src/shell.ts
-/** The raw capability — throws without a document; for gated subtrees. */
+/** The shell capability: open and close panels, dialogs and menus. Without a document its methods throw `not-ready`. */
 function useShell() {
 	return require_runtime.useCapability(_embedpdf_plugin_shell.ShellToken);
 }
-/** One named surface (panel / modal / overlay), bound to this subtree's
-*  document. Reads as closed — and intents no-op — while no document is open. */
+/** Subscribe to one shell event for the mounted lifetime: `useShellEvent((shell) => shell.onSurfaceOpened, handler)`. */
+function useShellEvent(select, handler) {
+	require_runtime.useCapabilityEvent(_embedpdf_plugin_shell.ShellToken, select, handler);
+}
+/**
+* Which panels, dialogs and menus are open (the page's State table, declared
+* once in `shellState`). Takes a selector, and re-renders only when what it
+* returns changes. Without a document nothing is open.
+*/
+const useShellState = require_state.stateHook(_embedpdf_plugin_shell.shellState);
+const NO_PROPS = Object.freeze({});
+/** One named surface (panel, dialog, overlay) of this subtree's document. Reads as closed, and its verbs do nothing, while no document is open. */
 function useSurface(id) {
 	const shell = require_runtime.useOptionalCapability(_embedpdf_plugin_shell.ShellToken);
-	const isOpen = require_runtime.useOptionalSelector(_embedpdf_plugin_shell.ShellToken, (s) => s.isOpen(id), false);
-	const props = require_runtime.useOptionalSelector(_embedpdf_plugin_shell.ShellToken, (s) => s.surfaceProps(id), void 0);
+	const isOpen = require_runtime.useOptionalSelector(_embedpdf_plugin_shell.ShellToken, (shell) => shell.isOpen(id), false);
+	const props = require_runtime.useOptionalSelector(_embedpdf_plugin_shell.ShellToken, (shell) => shell.getSurface(id)?.props ?? NO_PROPS, NO_PROPS);
 	return (0, react.useMemo)(() => ({
 		isOpen,
 		props,
-		open: (opts) => shell?.open(id, opts),
+		open: (options) => shell?.open(id, options),
 		close: () => shell?.close(id),
-		toggle: (opts) => shell?.toggle(id, opts)
+		toggle: (options) => shell?.toggle(id, options)
 	}), [
 		shell,
 		id,
@@ -27,24 +39,27 @@ function useSurface(id) {
 		props
 	]);
 }
-const NO_MENUS = [];
-const stringArrayEqual = (a, b) => a === b || a.length === b.length && a.every((x, i) => x === b[i]);
-/** The dropdown-menu stack for this subtree's document (empty without one). */
-function useMenus() {
+/**
+* Put the cursor in `ref`'s element when the surface `id` asks for it: on every
+* `open(id, { focus: true })`, a command whose panel says `focus` among them, and
+* when the element mounts while the request is up (the panel opened, or its code
+* loaded, because of it). A plain open never moves it. `select` selects an input's
+* text, so typing replaces it. Reads the surface of this subtree's document; use
+* it in the component that renders the element.
+*/
+function useSurfaceFocus(id, ref, options = {}) {
 	const shell = require_runtime.useOptionalCapability(_embedpdf_plugin_shell.ShellToken);
-	const open = require_runtime.useOptionalSelector(_embedpdf_plugin_shell.ShellToken, (s) => s.openMenus(), NO_MENUS, stringArrayEqual);
-	return (0, react.useMemo)(() => ({
-		open,
-		isOpen: (id) => open.includes(id),
-		toggle: (id) => shell?.toggleMenu(id),
-		close: (id) => shell?.closeMenu(id),
-		closeAll: () => shell?.closeAllMenus()
-	}), [shell, open]);
+	const request = require_runtime.useOptionalSelector(_embedpdf_plugin_shell.ShellToken, (current) => current.getSurface(id)?.focusRequest ?? 0, 0);
+	const [follower] = (0, react.useState)(_embedpdf_web.createSurfaceFocusFollower);
+	const select = options.select ?? false;
+	(0, react.useEffect)(() => follower.follow(ref.current, shell, request, { select }));
 }
 //#endregion
-exports.useMenus = useMenus;
 exports.useShell = useShell;
+exports.useShellEvent = useShellEvent;
+exports.useShellState = useShellState;
 exports.useSurface = useSurface;
+exports.useSurfaceFocus = useSurfaceFocus;
 Object.keys(_embedpdf_plugin_shell).forEach(function(k) {
 	if (k !== "default" && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
 		enumerable: true,

package/dist/shell.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"shell.cjs","names":["useCapability","ShellToken","useOptionalCapability","useOptionalSelector"],"sources":["../src/shell.ts"],"sourcesContent":["/**\n * The React surface for @embedpdf/plugin-shell. The app owns every\n * surface's DOM; these hooks bind its open/closed state to the kernel so\n * commands can drive it and applications can restore it.\n *\n * These hooks are TOTAL: shell state is document-scoped, and chrome that uses\n * it (panel buttons, mode bands, menu anchors) stays mounted across the\n * empty-workspace state. With no document, surfaces read as closed, menus as\n * none, and intents no-op — mirroring how command execution `tryGet`s the\n * shell. Use the raw capability (`useShell`) when you need fail-fast access\n * inside a <DocumentGate>.\n */\n\n// One-line-per-feature: registration travels with the UI.\nexport * from '@embedpdf/plugin-shell';\nimport { useMemo } from 'react';\nimport { ShellToken } from '@embedpdf/plugin-shell';\nimport type { OpenSurfaceOptions, ShellCapability } from '@embedpdf/plugin-shell';\nimport { useCapability, useOptionalCapability, useOptionalSelector } from './runtime';\n\n/** The raw capability — throws without a document; for gated subtrees. */\nexport function useShell(): ShellCapability {\n  return useCapability(ShellToken);\n}\n\nexport interface SurfaceHandle {\n  readonly isOpen: boolean;\n  readonly props: Readonly<Record<string, unknown>> | undefined;\n  open(opts?: OpenSurfaceOptions): void;\n  close(): void;\n  toggle(opts?: OpenSurfaceOptions): void;\n}\n\n/** One named surface (panel / modal / overlay), bound to this subtree's\n *  document. Reads as closed — and intents no-op — while no document is open. */\nexport function useSurface(id: string): SurfaceHandle {\n  const shell = useOptionalCapability(ShellToken);\n  const isOpen = useOptionalSelector(ShellToken, (s) => s.isOpen(id), false);\n  const props = useOptionalSelector(ShellToken, (s) => s.surfaceProps(id), undefined);\n  return useMemo(\n    () => ({\n      isOpen,\n      props,\n      open: (opts?: OpenSurfaceOptions) => shell?.open(id, opts),\n      close: () => shell?.close(id),\n      toggle: (opts?: OpenSurfaceOptions) => shell?.toggle(id, opts),\n    }),\n    [shell, id, isOpen, props],\n  );\n}\n\nexport interface MenusHandle {\n  readonly open: readonly string[];\n  isOpen(id: string): boolean;\n  toggle(id: string): void;\n  close(id: string): void;\n  closeAll(): void;\n}\n\nconst NO_MENUS: readonly string[] = [];\nconst stringArrayEqual = (a: readonly string[], b: readonly string[]) =>\n  a === b || (a.length === b.length && a.every((x, i) => x === b[i]));\n\n/** The dropdown-menu stack for this subtree's document (empty without one). */\nexport function useMenus(): MenusHandle {\n  const shell = useOptionalCapability(ShellToken);\n  const open = useOptionalSelector(ShellToken, (s) => s.openMenus(), NO_MENUS, stringArrayEqual);\n  return useMemo(\n    () => ({\n      open,\n      isOpen: (id: string) => open.includes(id),\n      toggle: (id: string) => shell?.toggleMenu(id),\n      close: (id: string) => shell?.closeMenu(id),\n      closeAll: () => shell?.closeAllMenus(),\n    }),\n    [shell, open],\n  );\n}\n"],"mappings":";;;;;;;AAqBA,SAAgB,WAA4B;CAC1C,OAAOA,gBAAAA,cAAcC,uBAAAA,UAAU;AACjC;;;AAYA,SAAgB,WAAW,IAA2B;CACpD,MAAM,QAAQC,gBAAAA,sBAAsBD,uBAAAA,UAAU;CAC9C,MAAM,SAASE,gBAAAA,oBAAoBF,uBAAAA,aAAa,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK;CACzE,MAAM,QAAQE,gBAAAA,oBAAoBF,uBAAAA,aAAa,MAAM,EAAE,aAAa,EAAE,GAAG,KAAA,CAAS;CAClF,QAAA,GAAA,MAAA,QAAA,QACS;EACL;EACA;EACA,OAAO,SAA8B,OAAO,KAAK,IAAI,IAAI;EACzD,aAAa,OAAO,MAAM,EAAE;EAC5B,SAAS,SAA8B,OAAO,OAAO,IAAI,IAAI;CAC/D,IACA;EAAC;EAAO;EAAI;EAAQ;CAAK,CAC3B;AACF;AAUA,MAAM,WAA8B,CAAC;AACrC,MAAM,oBAAoB,GAAsB,MAC9C,MAAM,KAAM,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,GAAG,MAAM,MAAM,EAAE,EAAE;;AAGnE,SAAgB,WAAwB;CACtC,MAAM,QAAQC,gBAAAA,sBAAsBD,uBAAAA,UAAU;CAC9C,MAAM,OAAOE,gBAAAA,oBAAoBF,uBAAAA,aAAa,MAAM,EAAE,UAAU,GAAG,UAAU,gBAAgB;CAC7F,QAAA,GAAA,MAAA,QAAA,QACS;EACL;EACA,SAAS,OAAe,KAAK,SAAS,EAAE;EACxC,SAAS,OAAe,OAAO,WAAW,EAAE;EAC5C,QAAQ,OAAe,OAAO,UAAU,EAAE;EAC1C,gBAAgB,OAAO,cAAc;CACvC,IACA,CAAC,OAAO,IAAI,CACd;AACF"}
+{"version":3,"file":"shell.cjs","names":["useCapability","ShellToken","stateHook","shellState","useOptionalCapability","useOptionalSelector","createSurfaceFocusFollower"],"sources":["../src/shell.ts"],"sourcesContent":["/**\n * The React surface for @embedpdf/plugin-shell. The app owns every\n * surface's DOM; these hooks bind its open/closed state to the kernel so\n * commands can drive it and applications can restore it.\n *\n * The state hooks work without a document: shell state is document-scoped,\n * and chrome that uses it (panel buttons, menu anchors) stays mounted across\n * the empty workspace. With no document every surface reads as closed, no menu\n * as open, and `useSurface`'s verbs do nothing. `useShell()` then returns the\n * stand-in, whose methods throw `not-ready`.\n */\n\n// One-line-per-feature: registration travels with the UI.\nexport * from '@embedpdf/plugin-shell';\nimport { useEffect, useMemo, useState, type RefObject } from 'react';\nimport { ShellToken, shellState } from '@embedpdf/plugin-shell';\nimport type { OpenSurfaceOptions, ShellCapability, SurfaceProps } from '@embedpdf/plugin-shell';\nimport type { EventHook } from '@embedpdf/core';\nimport { createSurfaceFocusFollower, type SurfaceFocusOptions } from '@embedpdf/web';\nimport {\n  useCapability,\n  useCapabilityEvent,\n  useOptionalCapability,\n  useOptionalSelector,\n} from './runtime';\nimport { stateHook } from './state';\n\n/** The shell capability: open and close panels, dialogs and menus. Without a document its methods throw `not-ready`. */\nexport function useShell(): ShellCapability {\n  return useCapability(ShellToken);\n}\n\n/** Subscribe to one shell event for the mounted lifetime: `useShellEvent((shell) => shell.onSurfaceOpened, handler)`. */\nexport function useShellEvent<T>(\n  select: (shell: ShellCapability) => EventHook<T>,\n  handler: (event: T) => void,\n): void {\n  useCapabilityEvent(ShellToken, select, handler);\n}\n\n/**\n * Which panels, dialogs and menus are open (the page's State table, declared\n * once in `shellState`). Takes a selector, and re-renders only when what it\n * returns changes. Without a document nothing is open.\n */\nexport const useShellState = stateHook(shellState);\n\nexport interface SurfaceHandle {\n  readonly isOpen: boolean;\n  /** The props the surface was opened with, or updated to; empty when it has none. */\n  readonly props: SurfaceProps;\n  open(options?: OpenSurfaceOptions): void;\n  close(): void;\n  toggle(options?: OpenSurfaceOptions): void;\n}\n\nconst NO_PROPS: SurfaceProps = Object.freeze({});\n\n/** One named surface (panel, dialog, overlay) of this subtree's document. Reads as closed, and its verbs do nothing, while no document is open. */\nexport function useSurface(id: string): SurfaceHandle {\n  const shell = useOptionalCapability(ShellToken);\n  const isOpen = useOptionalSelector(ShellToken, (shell) => shell.isOpen(id), false);\n  const props = useOptionalSelector(\n    ShellToken,\n    (shell) => shell.getSurface(id)?.props ?? NO_PROPS,\n    NO_PROPS,\n  );\n  return useMemo(\n    () => ({\n      isOpen,\n      props,\n      open: (options?: OpenSurfaceOptions) => shell?.open(id, options),\n      close: () => shell?.close(id),\n      toggle: (options?: OpenSurfaceOptions) => shell?.toggle(id, options),\n    }),\n    [shell, id, isOpen, props],\n  );\n}\n\nexport type { SurfaceFocusOptions };\n\n/**\n * Put the cursor in `ref`'s element when the surface `id` asks for it: on every\n * `open(id, { focus: true })`, a command whose panel says `focus` among them, and\n * when the element mounts while the request is up (the panel opened, or its code\n * loaded, because of it). A plain open never moves it. `select` selects an input's\n * text, so typing replaces it. Reads the surface of this subtree's document; use\n * it in the component that renders the element.\n */\nexport function useSurfaceFocus(\n  id: string,\n  ref: RefObject<HTMLElement | null>,\n  options: SurfaceFocusOptions = {},\n): void {\n  const shell = useOptionalCapability(ShellToken);\n  const request = useOptionalSelector(\n    ShellToken,\n    (current) => current.getSurface(id)?.focusRequest ?? 0,\n    0,\n  );\n  const [follower] = useState(createSurfaceFocusFollower);\n  const select = options.select ?? false;\n  // After every render, so an element that has just appeared is seen, and after the layout\n  // effects, so a panel's frame has placed and shown it (a sheet's layer is hidden until then).\n  useEffect(() => follower.follow(ref.current, shell, request, { select }));\n}\n"],"mappings":";;;;;;;;;AA4BA,SAAgB,WAA4B;CAC1C,OAAOA,gBAAAA,cAAcC,uBAAAA,UAAU;AACjC;;AAGA,SAAgB,cACd,QACA,SACM;CACN,gBAAA,mBAAmBA,uBAAAA,YAAY,QAAQ,OAAO;AAChD;;;;;;AAOA,MAAa,gBAAgBC,cAAAA,UAAUC,uBAAAA,UAAU;AAWjD,MAAM,WAAyB,OAAO,OAAO,CAAC,CAAC;;AAG/C,SAAgB,WAAW,IAA2B;CACpD,MAAM,QAAQC,gBAAAA,sBAAsBH,uBAAAA,UAAU;CAC9C,MAAM,SAASI,gBAAAA,oBAAoBJ,uBAAAA,aAAa,UAAU,MAAM,OAAO,EAAE,GAAG,KAAK;CACjF,MAAM,QAAQI,gBAAAA,oBACZJ,uBAAAA,aACC,UAAU,MAAM,WAAW,EAAE,CAAC,EAAE,SAAS,UAC1C,QACF;CACA,QAAA,GAAA,MAAA,QAAA,QACS;EACL;EACA;EACA,OAAO,YAAiC,OAAO,KAAK,IAAI,OAAO;EAC/D,aAAa,OAAO,MAAM,EAAE;EAC5B,SAAS,YAAiC,OAAO,OAAO,IAAI,OAAO;CACrE,IACA;EAAC;EAAO;EAAI;EAAQ;CAAK,CAC3B;AACF;;;;;;;;;AAYA,SAAgB,gBACd,IACA,KACA,UAA+B,CAAC,GAC1B;CACN,MAAM,QAAQG,gBAAAA,sBAAsBH,uBAAAA,UAAU;CAC9C,MAAM,UAAUI,gBAAAA,oBACdJ,uBAAAA,aACC,YAAY,QAAQ,WAAW,EAAE,CAAC,EAAE,gBAAgB,GACrD,CACF;CACA,MAAM,CAAC,aAAA,GAAA,MAAA,SAAA,CAAqBK,cAAAA,0BAA0B;CACtD,MAAM,SAAS,QAAQ,UAAU;CAGjC,CAAA,GAAA,MAAA,UAAA,OAAgB,SAAS,OAAO,IAAI,SAAS,OAAO,SAAS,EAAE,OAAO,CAAC,CAAC;AAC1E"}

package/dist/shell.d.cts

@@ -1,27 +1,42 @@
-import { OpenSurfaceOptions, ShellCapability } from "@embedpdf/plugin-shell";
+import { n as StateHook } from "./state-0K1I5cM4.cjs";
+import { EventHook } from "@embedpdf/core";
+import { RefObject } from "react";
+import { SurfaceFocusOptions } from "@embedpdf/web";
+import { OpenSurfaceOptions, ShellCapability, SurfaceProps } from "@embedpdf/plugin-shell";
 export * from "@embedpdf/plugin-shell";
 //#region src/shell.d.ts
-/** The raw capability — throws without a document; for gated subtrees. */
+/** The shell capability: open and close panels, dialogs and menus. Without a document its methods throw `not-ready`. */
 declare function useShell(): ShellCapability;
+/** Subscribe to one shell event for the mounted lifetime: `useShellEvent((shell) => shell.onSurfaceOpened, handler)`. */
+declare function useShellEvent<T>(select: (shell: ShellCapability) => EventHook<T>, handler: (event: T) => void): void;
+/**
+ * Which panels, dialogs and menus are open (the page's State table, declared
+ * once in `shellState`). Takes a selector, and re-renders only when what it
+ * returns changes. Without a document nothing is open.
+ */
+declare const useShellState: StateHook<{
+  openSurfaces: readonly import("@embedpdf/plugin-shell").SurfaceState[];
+  openMenus: readonly string[];
+}>;
 interface SurfaceHandle {
   readonly isOpen: boolean;
-  readonly props: Readonly<Record<string, unknown>> | undefined;
-  open(opts?: OpenSurfaceOptions): void;
+  /** The props the surface was opened with, or updated to; empty when it has none. */
+  readonly props: SurfaceProps;
+  open(options?: OpenSurfaceOptions): void;
   close(): void;
-  toggle(opts?: OpenSurfaceOptions): void;
+  toggle(options?: OpenSurfaceOptions): void;
 }
-/** One named surface (panel / modal / overlay), bound to this subtree's
- *  document. Reads as closed — and intents no-op — while no document is open. */
+/** One named surface (panel, dialog, overlay) of this subtree's document. Reads as closed, and its verbs do nothing, while no document is open. */
 declare function useSurface(id: string): SurfaceHandle;
-interface MenusHandle {
-  readonly open: readonly string[];
-  isOpen(id: string): boolean;
-  toggle(id: string): void;
-  close(id: string): void;
-  closeAll(): void;
-}
-/** The dropdown-menu stack for this subtree's document (empty without one). */
-declare function useMenus(): MenusHandle;
+/**
+ * Put the cursor in `ref`'s element when the surface `id` asks for it: on every
+ * `open(id, { focus: true })`, a command whose panel says `focus` among them, and
+ * when the element mounts while the request is up (the panel opened, or its code
+ * loaded, because of it). A plain open never moves it. `select` selects an input's
+ * text, so typing replaces it. Reads the surface of this subtree's document; use
+ * it in the component that renders the element.
+ */
+declare function useSurfaceFocus(id: string, ref: RefObject<HTMLElement | null>, options?: SurfaceFocusOptions): void;
 //#endregion
-export { MenusHandle, SurfaceHandle, useMenus, useShell, useSurface };
+export { type SurfaceFocusOptions, SurfaceHandle, useShell, useShellEvent, useShellState, useSurface, useSurfaceFocus };
 //# sourceMappingURL=shell.d.cts.map