@embedpdf/react 3.0.0-next.6 → 3.0.0-next.7

package/dist/selection.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"selection.cjs","names":["usePage","useCapability","SelectionHostToken","useSelector","shallowArray","SelectionToken","Anchored"],"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.pageToContent (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 } from 'react';\nimport { SelectionToken, type SelectionMenuAnchor } from '@embedpdf/plugin-selection';\nimport { SelectionToken as SelectionHostToken } from '@embedpdf/plugin-selection/internal';\nimport { wireSelectionClipboard, type SelectionClipboardOptions } from '@embedpdf/web';\nimport { Anchored, type AnchoredPlacement } from './anchored';\nimport { shallowArray, useCapability, usePage, useSelector } 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.pageToContent(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\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":";;;;;;;;;;;AA+BA,SAAgB,eAAe,EAAE,QAAQ,8BAAmD;CAC1F,MAAM,OAAOA,gBAAAA,QAAQ;CACrB,MAAM,YAAYC,gBAAAA,cAAcC,oCAAAA,cAAkB;CAClD,MAAM,WAAWC,gBAAAA,YACfD,oCAAAA,iBACC,MAAM,EAAE,gBAAgB,KAAK,GAAG,GACjCE,gBAAAA,YACF;CAGA,MAAM,UAAUD,gBAAAA,YAAYD,oCAAAA,iBAAqB,MAAM,EAAE,iBAAiB,CAAC;CAK3E,CAAA,GAAA,MAAA,UAAA,OAAgB;EACd,UAAU,WAAW,KAAK,GAAG;CAC/B,GAAG,CAAC,WAAW,KAAK,GAAG,CAAC;CAExB,IAAI,CAAC,SAAS,OAAO;CAErB,OACE,iBAAA,GAAA,kBAAA,IAAA,CAAC,OAAD;EACE,OAAO;GACL,UAAU;GACV,OAAO;GACP,OAAO;GACP,QAAQ;GACR,UAAU;GACV,eAAe;EACjB;EAEC,UAAA,SAAS,KAAK,GAAG,MAAM;GAOtB,OACE,iBAAA,GAAA,kBAAA,IAAA,CAAC,WAAD;IAAiB,QAJN;KAAC,EAAE,KAAK;KAAY,EAAE,KAAK;KAAU,EAAE,KAAK;KAAU,EAAE,KAAK;IAAU,CAAC,CAAC,KACnF,MAAM,KAAK,UAAU,cAAc,CAAC,CAGT,CAAC,CAAC,KAAK,MAAM,GAAG,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,KAAK,GAAG;IAAG,MAAM;GAAQ,GAArE,CAAqE;EAEvF,CAAC;CACE,CAAA;AAET;;;AAIA,SAAgB,eAAe;CAC7B,OAAOD,gBAAAA,cAAcI,2BAAAA,cAAc;AACrC;;;;AAKA,MAAM,kBACJ,GACA,MACY;CACZ,IAAI,MAAM,GAAG,OAAO;CACpB,IAAI,CAAC,KAAK,CAAC,GAAG,OAAO;CACrB,OACE,EAAE,QAAQ,EAAE,OACZ,EAAE,OAAO,MAAM,EAAE,OAAO,KACxB,EAAE,OAAO,MAAM,EAAE,OAAO,KACxB,EAAE,OAAO,UAAU,EAAE,OAAO,SAC5B,EAAE,OAAO,WAAW,EAAE,OAAO;AAEjC;;;;;;;;;;;;;AAsBA,SAAgB,cAAc,EAAE,UAAU,MAAM,GAAG,YAAY,SAA6B;CAC1F,MAAM,YAAYF,gBAAAA,YAAYE,2BAAAA,iBAAiB,MAAM,EAAE,YAAY,CAAC;CACpE,MAAM,SAASF,gBAAAA,YAAYE,2BAAAA,iBAAiB,MAAM,EAAE,WAAW,GAAG,cAAc;CAChF,IAAI,aAAa,CAAC,QAAQ,OAAO;CACjC,OACE,iBAAA,GAAA,kBAAA,IAAA,CAACC,iBAAAA,UAAD;EAAkB;EAAmB;EAAgB;EAClD;CACO,CAAA;AAEd;;;;;;;;AAWA,SAAgB,mBAAmB,EAAE,aAAsC,CAAC,GAAG;CAC7E,MAAM,YAAYL,gBAAAA,cAAcI,2BAAAA,cAAc;CAC9C,CAAA,GAAA,MAAA,UAAA,QAAA,GAAA,cAAA,uBAAA,CAC+B,WAAW,aAAa,KAAA,IAAY,CAAC,IAAI,EAAE,SAAS,CAAC,GAClF,CAAC,WAAW,QAAQ,CACtB;CACA,OAAO;AACT"}
+{"version":3,"file":"selection.cjs","names":["usePage","useCapability","SelectionHostToken","useSelector","shallowArray","SelectionToken","Anchored","StageToken","useOptionalCapability","HANDLE_PAD","HANDLE_HEAD","HANDLE_BAR"],"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.pageToContent (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';\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.pageToContent(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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"}

package/dist/selection.d.cts

@@ -1,6 +1,8 @@
 import { AnchoredPlacement as AnchoredPlacement$1 } from "./anchored.cjs";
 import * as React from "react";
 import { SelectionClipboardOptions, copySelection } from "@embedpdf/web";
+import { CapabilityToken } from "@embedpdf/core";
+import { StageCapability } from "@embedpdf/plugin-stage";
 export * from "@embedpdf/plugin-selection";
 //#region src/selection.d.ts
 interface SelectionLayerProps {
@@ -31,6 +33,29 @@ interface SelectionMenuProps {
  * `menuAnchor()` yourself — the primitive carries no policy.
  */
 declare function SelectionMenu({ children, gap, placement }: SelectionMenuProps): import("react/jsx-runtime").JSX.Element | null;
+interface SelectionHandlesProps {
+  /** Handle colour (default: the selection blue). */
+  color?: string;
+  /** The stage lens hosting this overlay (default: the main StageToken). */
+  token?: CapabilityToken<StageCapability>;
+}
+/**
+ * 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
+ * — 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
+ * 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`
+ * 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.
+ */
+declare function SelectionHandles({ color, token }: SelectionHandlesProps): import("react/jsx-runtime").JSX.Element | null;
 type SelectionClipboardProps = Pick<SelectionClipboardOptions, 'prefetch'>;
 /**
  * Mount ONCE per viewer to wire clipboard copy: prefetches the selected text
@@ -41,5 +66,5 @@ type SelectionClipboardProps = Pick<SelectionClipboardOptions, 'prefetch'>;
  */
 declare function SelectionClipboard({ prefetch }?: SelectionClipboardProps): null;
 //#endregion
-export { SelectionClipboard, SelectionClipboardProps, SelectionLayer, SelectionLayerProps, SelectionMenu, SelectionMenuProps, copySelection, useSelection };
+export { SelectionClipboard, SelectionClipboardProps, SelectionHandles, SelectionHandlesProps, SelectionLayer, SelectionLayerProps, SelectionMenu, SelectionMenuProps, copySelection, useSelection };
 //# sourceMappingURL=selection.d.cts.map

package/dist/selection.d.ts

@@ -1,6 +1,8 @@
 import { AnchoredPlacement as AnchoredPlacement$1 } from "./anchored.js";
+import { CapabilityToken } from "@embedpdf/core";
 import * as React from "react";
 import { SelectionClipboardOptions, copySelection } from "@embedpdf/web";
+import { StageCapability } from "@embedpdf/plugin-stage";
 export * from "@embedpdf/plugin-selection";
 //#region src/selection.d.ts
 interface SelectionLayerProps {
@@ -31,6 +33,29 @@ interface SelectionMenuProps {
  * `menuAnchor()` yourself — the primitive carries no policy.
  */
 declare function SelectionMenu({ children, gap, placement }: SelectionMenuProps): import("react/jsx-runtime").JSX.Element | null;
+interface SelectionHandlesProps {
+  /** Handle colour (default: the selection blue). */
+  color?: string;
+  /** The stage lens hosting this overlay (default: the main StageToken). */
+  token?: CapabilityToken<StageCapability>;
+}
+/**
+ * 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
+ * — 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
+ * 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`
+ * 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.
+ */
+declare function SelectionHandles({ color, token }: SelectionHandlesProps): import("react/jsx-runtime").JSX.Element | null;
 type SelectionClipboardProps = Pick<SelectionClipboardOptions, 'prefetch'>;
 /**
  * Mount ONCE per viewer to wire clipboard copy: prefetches the selected text
@@ -41,5 +66,5 @@ type SelectionClipboardProps = Pick<SelectionClipboardOptions, 'prefetch'>;
  */
 declare function SelectionClipboard({ prefetch }?: SelectionClipboardProps): null;
 //#endregion
-export { SelectionClipboard, SelectionClipboardProps, SelectionLayer, SelectionLayerProps, SelectionMenu, SelectionMenuProps, copySelection, useSelection };
+export { SelectionClipboard, SelectionClipboardProps, SelectionHandles, SelectionHandlesProps, SelectionLayer, SelectionLayerProps, SelectionMenu, SelectionMenuProps, copySelection, useSelection };
 //# sourceMappingURL=selection.d.ts.map

package/dist/selection.js

@@ -1,9 +1,11 @@
-import { shallowArray, useCapability, usePage, useSelector } from "./runtime.js";
+import { shallowArray, useCapability, useKernelValue, useOptionalCapability, usePage, useSelector } from "./runtime.js";
 import { Anchored } from "./anchored.js";
-import { jsx } from "react/jsx-runtime";
-import { useEffect } from "react";
-import { copySelection, wireSelectionClipboard } from "@embedpdf/web";
-import { SelectionToken } from "@embedpdf/plugin-selection";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { attachSelectionHandle, copySelection, wireSelectionClipboard } from "@embedpdf/web";
+import { StageToken } from "@embedpdf/plugin-stage";
+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";
 export * from "@embedpdf/plugin-selection";
 //#region src/selection.tsx
@@ -74,6 +76,147 @@ 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
+* — 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
+* 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`
+* 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.
+*/
+function SelectionHandles({ color = "#2196f3", token = StageToken }) {
+	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 [dragging, setDragging] = useState(null);
+	const armSource = useRef(null);
+	armSource.current = stage && endpoints ? {
+		stage,
+		endpoints
+	} : null;
+	const bindHandle = useMemo(() => {
+		const detach = {};
+		const make = (role) => (el) => {
+			detach[role]?.();
+			delete detach[role];
+			if (!el) return;
+			detach[role] = attachSelectionHandle(el, { 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);
+				setDragging(role);
+				return {
+					base: {
+						x: (geom.bar.from.x + geom.bar.to.x) / 2,
+						y: (geom.bar.from.y + geom.bar.to.y) / 2
+					},
+					session: {
+						move: drag.move,
+						end: () => {
+							drag.end();
+							setDragging(null);
+						}
+					}
+				};
+			} });
+		};
+		return {
+			start: make("start"),
+			end: make("end")
+		};
+	}, [host]);
+	if (!stage || !endpoints || !visible) return null;
+	if (selecting && !dragging) return null;
+	const view = handleView(stage);
+	const renderHandle = (role) => {
+		const geom = selectionHandleGeom(view, endpoints[role], role);
+		if (!geom) 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,
+				width: HANDLE_BAR + 2 * HANDLE_PAD,
+				height: geom.length + HANDLE_HEAD + 2 * HANDLE_PAD,
+				...geom.upright ? null : {
+					transform: `rotate(${geom.rotation}deg)`,
+					transformOrigin: `${pivotX}px ${barTop}px`
+				},
+				touchAction: "none",
+				cursor: "grab",
+				pointerEvents: "auto"
+			},
+			children: [/* @__PURE__ */ jsx("div", { style: {
+				position: "absolute",
+				left: HANDLE_PAD,
+				top: barTop,
+				width: HANDLE_BAR,
+				height: geom.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,
+				width: HANDLE_HEAD,
+				height: HANDLE_HEAD,
+				borderRadius: "50%",
+				background: color,
+				boxShadow: "0 1px 4px rgba(0, 0, 0, 0.35)"
+			} })]
+		}, role);
+	};
+	return /* @__PURE__ */ jsxs(Fragment, { children: [renderHandle("start"), renderHandle("end")] });
+}
 /**
 * Mount ONCE per viewer to wire clipboard copy: prefetches the selected text
 * when the selection settles, answers the native `copy` event synchronously,
@@ -87,6 +230,6 @@ function SelectionClipboard({ prefetch } = {}) {
 	return null;
 }
 //#endregion
-export { SelectionClipboard, SelectionLayer, SelectionMenu, copySelection, useSelection };
+export { SelectionClipboard, SelectionHandles, SelectionLayer, SelectionMenu, copySelection, useSelection };
 
 //# 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.pageToContent (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 } from 'react';\nimport { SelectionToken, type SelectionMenuAnchor } from '@embedpdf/plugin-selection';\nimport { SelectionToken as SelectionHostToken } from '@embedpdf/plugin-selection/internal';\nimport { wireSelectionClipboard, type SelectionClipboardOptions } from '@embedpdf/web';\nimport { Anchored, type AnchoredPlacement } from './anchored';\nimport { shallowArray, useCapability, usePage, useSelector } 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.pageToContent(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\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":";;;;;;;;;AA+BA,SAAgB,eAAe,EAAE,QAAQ,8BAAmD;CAC1F,MAAM,OAAO,QAAQ;CACrB,MAAM,YAAY,cAAcA,gBAAkB;CAClD,MAAM,WAAW,YACfA,mBACC,MAAM,EAAE,gBAAgB,KAAK,GAAG,GACjC,YACF;CAGA,MAAM,UAAU,YAAYA,mBAAqB,MAAM,EAAE,iBAAiB,CAAC;CAK3E,gBAAgB;EACd,UAAU,WAAW,KAAK,GAAG;CAC/B,GAAG,CAAC,WAAW,KAAK,GAAG,CAAC;CAExB,IAAI,CAAC,SAAS,OAAO;CAErB,OACE,oBAAC,OAAD;EACE,OAAO;GACL,UAAU;GACV,OAAO;GACP,OAAO;GACP,QAAQ;GACR,UAAU;GACV,eAAe;EACjB;EAEC,UAAA,SAAS,KAAK,GAAG,MAAM;GAOtB,OACE,oBAAC,WAAD;IAAiB,QAJN;KAAC,EAAE,KAAK;KAAY,EAAE,KAAK;KAAU,EAAE,KAAK;KAAU,EAAE,KAAK;IAAU,CAAC,CAAC,KACnF,MAAM,KAAK,UAAU,cAAc,CAAC,CAGT,CAAC,CAAC,KAAK,MAAM,GAAG,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,KAAK,GAAG;IAAG,MAAM;GAAQ,GAArE,CAAqE;EAEvF,CAAC;CACE,CAAA;AAET;;;AAIA,SAAgB,eAAe;CAC7B,OAAO,cAAc,cAAc;AACrC;;;;AAKA,MAAM,kBACJ,GACA,MACY;CACZ,IAAI,MAAM,GAAG,OAAO;CACpB,IAAI,CAAC,KAAK,CAAC,GAAG,OAAO;CACrB,OACE,EAAE,QAAQ,EAAE,OACZ,EAAE,OAAO,MAAM,EAAE,OAAO,KACxB,EAAE,OAAO,MAAM,EAAE,OAAO,KACxB,EAAE,OAAO,UAAU,EAAE,OAAO,SAC5B,EAAE,OAAO,WAAW,EAAE,OAAO;AAEjC;;;;;;;;;;;;;AAsBA,SAAgB,cAAc,EAAE,UAAU,MAAM,GAAG,YAAY,SAA6B;CAC1F,MAAM,YAAY,YAAY,iBAAiB,MAAM,EAAE,YAAY,CAAC;CACpE,MAAM,SAAS,YAAY,iBAAiB,MAAM,EAAE,WAAW,GAAG,cAAc;CAChF,IAAI,aAAa,CAAC,QAAQ,OAAO;CACjC,OACE,oBAAC,UAAD;EAAkB;EAAmB;EAAgB;EAClD;CACO,CAAA;AAEd;;;;;;;;AAWA,SAAgB,mBAAmB,EAAE,aAAsC,CAAC,GAAG;CAC7E,MAAM,YAAY,cAAc,cAAc;CAC9C,gBACQ,uBAAuB,WAAW,aAAa,KAAA,IAAY,CAAC,IAAI,EAAE,SAAS,CAAC,GAClF,CAAC,WAAW,QAAQ,CACtB;CACA,OAAO;AACT"}
+{"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.pageToContent (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';\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.pageToContent(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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"}

package/dist/stage.cjs

@@ -2,10 +2,10 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_rolldown_runtime = require("./rolldown-runtime-DDXJien1.cjs");
 const require_runtime = require("./runtime.cjs");
 const require_anchored = require("./anchored.cjs");
-const require_interaction = require("./interaction.cjs");
 let react_jsx_runtime = require("react/jsx-runtime");
 let react = require("react");
 react = require_rolldown_runtime.__toESM(react, 1);
+let _embedpdf_web = require("@embedpdf/web");
 let _embedpdf_plugin_stage = require("@embedpdf/plugin-stage");
 let _embedpdf_plugin_interaction = require("@embedpdf/plugin-interaction");
 //#region src/stage.tsx
@@ -19,7 +19,7 @@ function PageSurface({ documentId, page, frame, stage, render, chrome }) {
 	const top = page.screenY - frame.top;
 	const contentLeft = frame.left + (t.viewWidth - t.contentWidth) / 2;
 	const contentTop = frame.top + (t.viewHeight - t.contentHeight) / 2;
-	const ctx = (0, react.useMemo)(() => require_runtime.makePageContext(documentId, page.pon, page.pageIndex, frame, t, () => ref.current.getBoundingClientRect(), () => {
+	const ctx = (0, react.useMemo)(() => require_runtime.makePageContext(documentId, stage.lensId(), page.pon, page.pageIndex, frame, t, () => ref.current.getBoundingClientRect(), () => {
 		const live = stage.visiblePages().find((p) => p.pon === page.pon);
 		return live ? {
 			desiredDeviceWidth: live.transform.deviceWidth,
@@ -58,7 +58,7 @@ function PageSurface({ documentId, page, frame, stage, render, chrome }) {
 					top: frame.top,
 					width: t.viewWidth,
 					height: t.viewHeight,
-					boxShadow: "0 6px 18px rgba(0,0,0,.18)"
+					boxShadow: "var(--epdf-page-shadow, 0 6px 18px rgba(0,0,0,.18))"
 				} }),
 				/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 					ref,
@@ -80,7 +80,7 @@ function PageSurface({ documentId, page, frame, stage, render, chrome }) {
 		})
 	});
 }
-function Stage({ children, pageChrome, overlay, interaction = false, zoomGestures = true, token = _embedpdf_plugin_stage.StageToken, className, style }) {
+function Stage({ children, pageChrome, overlay, interaction = true, panFallback = true, zoomGestures = true, token = _embedpdf_plugin_stage.StageToken, className, style }) {
 	const stage = require_runtime.useCapability(token);
 	const ix = require_runtime.useOptionalCapability(_embedpdf_plugin_interaction.InteractionToken);
 	const useHub = interaction && !!ix;
@@ -119,153 +119,22 @@ function Stage({ children, pageChrome, overlay, interaction = false, zoomGesture
 	}), [projector, pages]);
 	(0, react.useEffect)(() => {
 		const el = ref.current;
-		const setVp = () => stage.setViewport({
-			width: el.clientWidth,
-			height: el.clientHeight
+		const detachSurface = (0, _embedpdf_web.createStageSurface)(el, stage, {
+			hub: useHub ? ix : null,
+			source: stage.lensId(),
+			zoomGestures
 		});
-		const ro = new ResizeObserver(setVp);
-		ro.observe(el);
-		setVp();
-		let mq = null;
-		const reportDpr = () => {
-			stage.setDevicePixelRatio(window.devicePixelRatio || 1);
-			mq?.removeEventListener("change", reportDpr);
-			mq = window.matchMedia(`(resolution: ${window.devicePixelRatio}dppx)`);
-			mq.addEventListener("change", reportDpr);
-		};
-		reportDpr();
-		const onWheel = (e) => {
-			e.preventDefault();
-			const r = el.getBoundingClientRect();
-			if (zoomGestures && (e.ctrlKey || e.metaKey)) stage.zoomAround({
-				x: e.clientX - r.left,
-				y: e.clientY - r.top
-			}, (0, _embedpdf_plugin_stage.wheelZoomFactor)(e));
-			else {
-				const dx = e.shiftKey ? e.deltaY : e.deltaX;
-				const dy = e.shiftKey ? e.deltaX : e.deltaY;
-				stage.panBy(-dx, -dy);
-			}
-		};
-		el.addEventListener("wheel", onWheel, { passive: false });
-		let lastScale = 1;
-		const onGestureStart = (e) => {
-			e.preventDefault();
-			lastScale = e.scale ?? 1;
-		};
-		const onGestureChange = (e) => {
-			e.preventDefault();
-			const g = e;
-			const scale = g.scale ?? 1;
-			if (zoomGestures && scale > 0) {
-				const r = el.getBoundingClientRect();
-				stage.zoomAround({
-					x: g.clientX - r.left,
-					y: g.clientY - r.top
-				}, scale / lastScale);
-			}
-			lastScale = scale;
-		};
-		const hasGestureEvents = "GestureEvent" in window;
-		if (hasGestureEvents) {
-			el.addEventListener("gesturestart", onGestureStart);
-			el.addEventListener("gesturechange", onGestureChange);
-			el.addEventListener("gestureend", onGestureStart);
-		}
-		const cleanups = [];
-		if (useHub && ix) {
-			const clicks = require_interaction.createClickCounter();
-			const forward = (phase, e, clickCount = 1) => {
-				const r = el.getBoundingClientRect();
-				const vpt = {
-					x: e.clientX - r.left,
-					y: e.clientY - r.top
-				};
-				ix.dispatch({
-					phase,
-					viewport: vpt,
-					page: stage.pageAt(vpt) ?? void 0,
-					project: (pon) => stage.pointOnPage(pon, vpt),
-					modifiers: {
-						shift: e.shiftKey,
-						alt: e.altKey,
-						ctrl: e.ctrlKey,
-						meta: e.metaKey
-					},
-					clickCount
-				});
-			};
-			let dragging = false;
-			const down = (e) => {
-				if (e.button !== 0) return;
-				dragging = true;
-				forward("down", e, clicks(Date.now(), e.clientX, e.clientY));
-			};
-			const hover = (e) => {
-				if (!dragging) forward("move", e);
-			};
-			const winMove = (e) => {
-				if (dragging) forward("move", e);
-			};
-			const up = (e) => {
-				if (!dragging) return;
-				dragging = false;
-				forward("up", e);
-			};
-			el.addEventListener("pointerdown", down);
-			el.addEventListener("pointermove", hover);
-			window.addEventListener("pointermove", winMove);
-			window.addEventListener("pointerup", up);
-			cleanups.push(() => {
-				el.removeEventListener("pointerdown", down);
-				el.removeEventListener("pointermove", hover);
-				window.removeEventListener("pointermove", winMove);
-				window.removeEventListener("pointerup", up);
-			});
-		} else {
-			let dragging = false;
-			let lx = 0;
-			let ly = 0;
-			const down = (e) => {
-				if (e.button !== 0) return;
-				dragging = true;
-				lx = e.clientX;
-				ly = e.clientY;
-			};
-			const move = (e) => {
-				if (!dragging) return;
-				stage.panBy(e.clientX - lx, e.clientY - ly);
-				lx = e.clientX;
-				ly = e.clientY;
-			};
-			const up = () => {
-				dragging = false;
-			};
-			el.addEventListener("pointerdown", down);
-			window.addEventListener("pointermove", move);
-			window.addEventListener("pointerup", up);
-			cleanups.push(() => {
-				el.removeEventListener("pointerdown", down);
-				window.removeEventListener("pointermove", move);
-				window.removeEventListener("pointerup", up);
-			});
-		}
+		const offScroll = useHub && ix ? ix.registerHandler((0, _embedpdf_plugin_stage.createScrollHandler)(stage, ix, { panFallback }), { source: stage.lensId() }) : null;
 		return () => {
-			ro.disconnect();
-			mq?.removeEventListener("change", reportDpr);
-			el.removeEventListener("wheel", onWheel);
-			if (hasGestureEvents) {
-				el.removeEventListener("gesturestart", onGestureStart);
-				el.removeEventListener("gesturechange", onGestureChange);
-				el.removeEventListener("gestureend", onGestureStart);
-			}
-			cleanups.forEach((fn) => fn());
+			offScroll?.();
+			detachSurface();
 		};
 	}, [
 		stage,
 		ix,
 		useHub,
-		zoomGestures
+		zoomGestures,
+		panFallback
 	]);
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 		ref,
@@ -284,7 +153,7 @@ function Stage({ children, pageChrome, overlay, interaction = false, zoomGesture
 			stage,
 			render: children,
 			chrome: pageChrome
-		}, p.pageIndex)), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_anchored.ProjectorProvider, {
+		}, p.pon)), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_anchored.ProjectorProvider, {
 			value: projectorBinding,
 			children: overlay
 		})]