@embedpdf/plugin-selection 3.0.0-next.3 → 3.0.0-next.5

package/dist/types-DtWaZIsm.d.ts

@@ -0,0 +1,286 @@
+import { PageObjectNumber } from "@embedpdf/core";
+import { Mat2D, Point, Rect, TextQuad } from "@embedpdf/core-geometry";
+import { PageGeometrySnapshot, PageTextLayout, PdfPoint, PdfQuad, PdfRect, PdfTextSegment } from "@embedpdf/engine-core/runtime";
+//#region src/geometry.d.ts
+/**
+ * One merged visual line of a selection, in content space — the structural
+ * twin of the engine's `PdfTextSegment`. `quad` carries frame-geometric
+ * corner semantics (upper = ascent side, start = the frame's −x); `advance`
+ * is the READING direction along the baseline (+1 = toward `end`), derived
+ * from the glyph sequence — geometry and bidi stay separate concerns.
+ * `rect` is the content-space AABB.
+ */
+interface SelectionSegment {
+  quad: TextQuad;
+  rect: Rect;
+  advance: 1 | -1;
+}
+/** A page's cached selection geometry: the canonical layout + the seam. */
+interface SelectionPageGeometry {
+  layout: PageTextLayout;
+  toContent: Mat2D<'pdf', 'content'>;
+  fromContent: Mat2D<'content', 'pdf'>;
+}
+/**
+ * Build a page's selection geometry. Page display rotation does NOT enter
+ * here — the overlay rides the page's CSS rotation, so content space stays
+ * un-rotated (the crop-relative y-flip is the only conversion; zoom = 1,
+ * the viewer's zoom is applied later by `PageTransform.pageToContent`).
+ */
+declare function buildSelectionPageGeometry(snapshot: PageGeometrySnapshot, crop: PdfRect, rotation: 0 | 90 | 180 | 270, userUnit: number): SelectionPageGeometry;
+/** A content-space pointer point in the layout's PDF space. */
+declare function contentPointToPdf(geom: SelectionPageGeometry, p: Point): PdfPoint;
+/**
+ * A canonical PDF quad in content space. Engine quads carry frame-geometric
+ * slot semantics (`p1..p4` = upper-start, upper-end, lower-start,
+ * lower-end) — a trusted producer, so the y-flip maps corners straight onto
+ * their names; imported-annotation normalization does NOT apply here.
+ */
+declare function toContentTextQuad(geom: SelectionPageGeometry, quad: PdfQuad): TextQuad;
+/** A canonical segment in content space (`rect` recomputed from the mapped
+ *  quad so the pair can never drift). */
+declare function toContentSegment(geom: SelectionPageGeometry, segment: PdfTextSegment): SelectionSegment;
+//#endregion
+//#region src/types.d.ts
+/**
+ * A position in a page's CHARACTER space — the space the engine's geometry
+ * runs tile (`PageGeometryRun.charStart`) and search hits address
+ * (`SearchMatch.charStart`). NOT a string offset into extracted text; the
+ * two spaces are joined by the engine's `charMap` (see engine-core
+ * `text/charmap.ts`), which `readText()` applies for you.
+ */
+interface TextPosition {
+  pon: PageObjectNumber;
+  /** Character index, 0-based. */
+  index: number;
+}
+/**
+ * A half-open range in character space: `start` inclusive, `end` exclusive,
+ * in document order (`start` at or before `end`). `end.index` may be 0 to
+ * end a range exactly at a page boundary.
+ */
+interface TextRange {
+  start: TextPosition;
+  end: TextPosition;
+}
+/**
+ * What {@link SelectionCapability.select} accepts: a cross-page
+ * {@link TextRange}, or a single-page span — the shape of a search hit, so
+ * `select({ pon: hit.pageObjectNumber, start: hit.charStart, count: hit.charCount })`
+ * needs no conversion.
+ */
+type SelectionRangeInput = TextRange | {
+  pon: PageObjectNumber;
+  start: number;
+  count: number;
+};
+/** A glyph address: a page + a flat character index within that page. */
+interface GlyphPointer {
+  pon: PageObjectNumber;
+  glyph: number;
+}
+/** Anchor = where the drag began, focus = the current end. Inclusive. */
+interface SelectionRange {
+  anchor: GlyphPointer;
+  focus: GlyphPointer;
+}
+/**
+ * A selection boundary, anchored to the boundary GLYPH's own oriented cell.
+ * `advance` is the reading direction of the segment it belongs to (+1 = the
+ * frame's +x), so caret consumers place at the trailing edge without
+ * re-deriving bidi from geometry. `rect` is the AABB (scroll targets).
+ */
+interface SelectionEndpoint {
+  pon: PageObjectNumber;
+  glyphQuad: TextQuad;
+  advance: 1 | -1;
+  rect: Rect;
+}
+/** The selection's floating-UI anchor: a page + the selection's union box on
+ *  it, in CONTENT space. See {@link SelectionCapability.menuAnchor}. */
+interface SelectionMenuAnchor {
+  pon: PageObjectNumber;
+  bounds: Rect;
+}
+interface SelectionSnapshot {
+  /** Per-page canonical segments — the ONE geometry consumers act on.
+   *  Boxes are derived views (`segment.rect`, or `rectsForPage()`). */
+  pages: Array<{
+    pon: PageObjectNumber;
+    segments: SelectionSegment[];
+  }>;
+  start: SelectionEndpoint | null;
+  end: SelectionEndpoint | null;
+  direction: 'forward' | 'backward';
+  /**
+   * The selection as a half-open character range in document order — a
+   * valid {@link SelectionCapability.select} input (persist and restore).
+   * Null when nothing is selected. Until a boundary page's text geometry
+   * has loaded, its index may still exceed the page's character count
+   * (`selectAll` settles as geometry arrives); consumers of the range
+   * (`select`, `readText`) clamp, so round-tripping is always safe.
+   */
+  range: TextRange | null;
+}
+interface SelectionState {
+  selection: SelectionRange | null;
+  /** Derived per-line segments per page, in CONTENT space (y-down, PDF units). */
+  segments: Record<number, SelectionSegment[]>;
+  /** Pages whose text geometry has loaded (so the layer re-renders when ready). */
+  loaded: Record<number, boolean>;
+  /** When a consumer owns the selection visual (e.g. a markup tool draws its own
+   *  preview), the default highlight rects are suppressed. */
+  highlightHidden: boolean;
+  /** A selection GESTURE is in flight (drag / double- / triple-click, between
+   *  pointer-down and pointer-up). A readable FACT, not an event: derived
+   *  recomputes (page load, rotate, move) never touch it, and programmatic
+   *  selections are born settled. Consumers apply policy (e.g. a menu hides
+   *  while true). */
+  selecting: boolean;
+}
+type SelectionAction = {
+  type: 'PAGE_LOADED';
+  pon: PageObjectNumber;
+} | {
+  type: 'SET';
+  selection: SelectionRange;
+  segments: Record<number, SelectionSegment[]>;
+} | {
+  type: 'CLEAR';
+} | {
+  type: 'SET_HIGHLIGHT_HIDDEN';
+  hidden: boolean;
+} | {
+  type: 'SET_SELECTING';
+  selecting: boolean;
+};
+/**
+ * The PUBLIC selection API — the documented, stable surface for application
+ * code (toolbars, context menus, automation). Resolve it with the token
+ * re-exported from the package root (`@embedpdf/plugin-selection`).
+ *
+ * The permission model: GEOMETRY enables selection (`doc.text.select`),
+ * TEXT enables extraction (`doc.text.copy`) — neither implies the other.
+ * Everything here except `readText()` works with the select scope alone, so
+ * a deployment can allow selecting and highlighting while denying copy.
+ *
+ * Framework-only plumbing (pointer-gesture intents, geometry warming, the
+ * highlight-visibility handshake) lives on {@link SelectionHostCapability},
+ * reachable only through `@embedpdf/plugin-selection/internal`. Both are
+ * the SAME runtime object — two typed lenses on one token.
+ */
+interface SelectionCapability {
+  /** Whether this caller may create selections at all (`doc.text.select`).
+   *  Authorization only — not "is something selected" ({@link hasSelection})
+   *  and not geometry readiness (a host concern). */
+  canSelect(): boolean;
+  /** Whether this caller may extract literal text (`doc.text.copy`) —
+   *  gates {@link readText} and any copy UI. */
+  canCopy(): boolean;
+  /**
+   * Select a range programmatically — the same path gestures use, so the
+   * highlight, `onChange`, and markup bridges all behave identically. An
+   * empty range clears. Throws the engine's `PermissionDenied` when
+   * `doc.text.select` is not granted (gate UI with {@link canSelect}).
+   */
+  select(range: SelectionRangeInput): void;
+  /** Select every character of the document. Same gating as {@link select}. */
+  selectAll(): void;
+  /** Clear the selection. Always allowed. */
+  clear(): void;
+  /** Coherent read-model: per-page segments, endpoints, direction, and the
+   *  half-open {@link TextRange} (a valid {@link select} input). */
+  snapshot(): SelectionSnapshot;
+  /**
+   * Whether a selection GESTURE is in flight (drag, double- or triple-click
+   * — between pointer-down and pointer-up). Programmatic {@link select} /
+   * {@link selectAll} never set it (a programmatic selection is born
+   * settled), and derived recomputes (page geometry loading, rotate, move)
+   * never touch it. THE fact selection-scoped UI applies policy to — e.g.
+   * `<SelectionMenu>` hides while true and appears at pointer-up.
+   */
+  isSelecting(): boolean;
+  /**
+   * Where selection-scoped floating UI should attach: the union box of the
+   * selection's segments on its END page (where the gesture finished),
+   * falling back to the last page with materialized segments while a
+   * boundary page's geometry is still loading. One anchor regardless of
+   * cross-page selection — the shape every anchored-overlay consumer
+   * positions on. Null when nothing is selected (or nothing has
+   * materialized yet).
+   */
+  menuAnchor(): SelectionMenuAnchor | null;
+  hasSelection(): boolean;
+  /** The pages the current selection covers (those with at least one
+   *  segment) — so a cross-page action (e.g. markup creation) can fan out
+   *  per page. */
+  selectedPages(): PageObjectNumber[];
+  /** Per-line oriented segments for a page, in content space — build your
+   *  own highlight layer from these. */
+  segmentsForPage(pon: PageObjectNumber): SelectionSegment[];
+  /** The segments' AABBs — for consumers that genuinely want boxes (scroll,
+   *  conservative regions). Never a substitute for the oriented quads in
+   *  geometry that gets drawn or persisted. */
+  rectsForPage(pon: PageObjectNumber): Rect[];
+  /**
+   * The selected text. Fetches each selected page's text snapshot (cached
+   * per page, immutable per content version) and slices it by the
+   * selection's character range through the engine's `charMap` — at most
+   * one text read per page per content version, amortized across every
+   * call. Pages are joined with `\n`. Resolves `''` when nothing is
+   * selected; rejects with `PermissionDenied` when `doc.text.copy` is not
+   * granted. Clipboard writes are deliberately NOT here — this package is
+   * DOM-free; use `@embedpdf/web`'s clipboard helpers (or your platform's)
+   * on top of this.
+   */
+  readText(): Promise<string>;
+  /** Fires whenever the selection segments change (drag-extend, programmatic
+   *  select, recompute) — for live preview. Returns an unsubscriber. */
+  onChange(cb: () => void): () => void;
+  /** Fires when a selection gesture ends (pointer-up) — the commit point
+   *  consumers (markup creation, copy prefetch) act on. */
+  onCommit(cb: () => void): () => void;
+}
+/**
+ * The HOST (framework) surface: what render layers, the interaction hub,
+ * and sibling plugins need on top of the public lens. Import the token from
+ * `@embedpdf/plugin-selection/internal`, never from application code. All
+ * point-based functions are gesture vocabulary (`…At` = point-addressed);
+ * the programmatic equivalent is the public range-based {@link
+ * SelectionCapability.select}. Every function here is INERT (no requests,
+ * no state) when `canSelect()` is false — the pointer handler needs no
+ * permission special-casing.
+ */
+interface SelectionHostCapability extends SelectionCapability {
+  /** Warm a page's text geometry (idempotent; no-op without
+   *  `doc.text.select`). Layers call this when a page mounts. */
+  ensurePage(pon: PageObjectNumber): void;
+  isLoaded(pon: PageObjectNumber): boolean;
+  /** Is a content-space point on (or near) text? Drives the I-beam cursor. */
+  isOverText(pon: PageObjectNumber, point: Point): boolean;
+  /** Begin a caret selection at a page point. Returns false if not near any
+   *  text — the caller deselects instead of capturing. */
+  beginAt(pon: PageObjectNumber, point: Point): boolean;
+  /** Double-click: select the word around the point. */
+  selectWordAt(pon: PageObjectNumber, point: Point): void;
+  /** Triple-click: select the whole visual line around the point. */
+  selectLineAt(pon: PageObjectNumber, point: Point): void;
+  /** Extend the current selection to a page point (drag). */
+  extendTo(pon: PageObjectNumber, point: Point): void;
+  /** The gesture ended (pointer-up) → notify `onCommit` consumers. */
+  end(): void;
+  /** Suppress / restore the default highlight visual (a consumer drawing its
+   *  own preview — the markup ghost). */
+  setHighlightVisible(visible: boolean): void;
+  highlightVisible(): boolean;
+}
+/**
+ * The selection capability token. Typed to the full
+ * {@link SelectionHostCapability} for this module and `/internal`; the
+ * package root re-exports the SAME token narrowed to
+ * {@link SelectionCapability}.
+ */
+declare const SelectionToken: import("@embedpdf/core").CapabilityToken<SelectionHostCapability>;
+//#endregion
+export { contentPointToPdf as _, SelectionHostCapability as a, SelectionRangeInput as c, SelectionToken as d, TextPosition as f, buildSelectionPageGeometry as g, SelectionSegment as h, SelectionEndpoint as i, SelectionSnapshot as l, SelectionPageGeometry as m, SelectionAction as n, SelectionMenuAnchor as o, TextRange as p, SelectionCapability as r, SelectionRange as s, GlyphPointer as t, SelectionState as u, toContentSegment as v, toContentTextQuad as y };
+//# sourceMappingURL=types-DtWaZIsm.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@embedpdf/plugin-selection",
-  "version": "3.0.0-next.3",
+  "version": "3.0.0-next.5",
   "private": false,
   "description": "Text selection: reads engine text geometry (PDF y-up), bridges it to viewer content space, hit-tests glyphs, and renders highlight rects. The first client of the interaction hub.",
   "type": "module",
@@ -12,16 +12,20 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./internal": {
+      "import": "./dist/internal.js",
+      "require": "./dist/internal.cjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [
     "dist"
   ],
   "dependencies": {
-    "@embedpdf/core": "3.0.0-next.3",
-    "@embedpdf/core-geometry": "3.0.0-next.3",
-    "@embedpdf/engine-core": "3.0.0-next.3",
-    "@embedpdf/plugin-interaction": "3.0.0-next.3"
+    "@embedpdf/core": "3.0.0-next.5",
+    "@embedpdf/plugin-interaction": "3.0.0-next.5",
+    "@embedpdf/engine-core": "3.0.0-next.5",
+    "@embedpdf/core-geometry": "3.0.0-next.5"
   },
   "devDependencies": {
     "typescript": "^5.0.0",