@embedpdf/plugin-selection 3.0.0-next.13 → 3.0.0-next.15

package/dist/contract-DLs4vXVt.d.ts

@@ -0,0 +1,252 @@
+import { DeepPartial, EventHook, OperationOptions, PageRef, SettingsApi } from "@embedpdf/core";
+import { Point, Quad, Rect } from "@embedpdf/core-geometry";
+import { PdfTextSegment } from "@embedpdf/engine-core/runtime";
+//#region src/geometry.d.ts
+/**
+ * One merged visual line of a selection, as the engine's layout gives it.
+ * `quad` carries the corners, named in the line's own frame; `advance` is the
+ * reading direction along the baseline (+1 = toward the right end), derived
+ * from the glyph sequence, so geometry and bidi stay separate concerns.
+ * `rect` is its bounding box.
+ */
+type SelectionSegment = PdfTextSegment;
+//#endregion
+//#region src/token.d.ts
+declare const SelectionToken: import("@embedpdf/core").CapabilityToken<SelectionCapability>;
+//#endregion
+//#region src/contract.d.ts
+/**
+ * The selection plugin's settings. `selectionPlugin(config)` registers them
+ * over {@link SELECTION_DEFAULTS}, and `updateSettings()` changes them for
+ * every document while the app runs. The colors and the shadow can also come
+ * from CSS (`--epdf-text-selection`, `--epdf-text-selection-handle`,
+ * `--epdf-text-selection-handle-shadow`), which wins over the setting.
+ */
+interface SelectionSettings {
+  /** How far, in viewport pixels, the pointer travels before a press becomes a drag that selects. */
+  readonly dragThreshold: number;
+  /** The color of selected text: a CSS color, or `null` for the viewer's accent at 35%. */
+  readonly color: string | null;
+  /** The grips at the selection's ends, on touch screens. */
+  readonly handles: {
+    /** A CSS color, or `null` for the viewer's accent. */
+    readonly color: string | null;
+    /** A CSS `box-shadow`. */
+    readonly shadow: string;
+  };
+}
+/** What the selection settings are when the app registers none. */
+declare const SELECTION_DEFAULTS: SelectionSettings;
+/** What `selectionPlugin(config)` takes: any of the settings, merged over the defaults. */
+type SelectionConfig = DeepPartial<SelectionSettings>;
+/**
+ * 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 {
+  page: PageRef;
+  /** 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({ page: hit.page, start: hit.charStart, count: hit.charCount })`
+ * needs no conversion.
+ */
+type SelectionRangeInput = TextRange | {
+  page: PageRef;
+  start: number;
+  count: number;
+};
+/**
+ * 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 {
+  page: PageRef;
+  glyphQuad: Quad;
+  advance: 1 | -1;
+  rect: Rect;
+}
+/** Where selection-scoped floating UI attaches: a page + the selection's
+ *  union box on it, in page space. See {@link SelectionCapability.getAnchor}. */
+interface SelectionAnchor {
+  page: PageRef;
+  bounds: Rect;
+}
+interface SelectionSnapshot {
+  /** Per-page canonical segments — the one geometry consumers act on.
+   *  Boxes are derived views (`segment.rect`, or `listRects()`). */
+  readonly pages: readonly {
+    page: PageRef;
+    segments: readonly SelectionSegment[];
+  }[];
+  readonly start: SelectionEndpoint | null;
+  readonly end: SelectionEndpoint | null;
+  readonly 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`, `readTextInRange`) clamp, so round-tripping is always safe.
+   */
+  readonly range: TextRange | null;
+}
+/**
+ * The selection's range or segments changed: a gesture step, a programmatic
+ * select, a boundary page's text geometry arriving, or a clear. Selection is
+ * session state, so the event carries no document origin.
+ */
+interface SelectionChangedEvent {
+  readonly range: TextRange | null;
+  /** The pages that carry a segment right now. */
+  readonly pages: readonly PageRef[];
+}
+/** A selection gesture ended (pointer-up, handle release) with a selection in
+ *  place — the commit point markup creation and clipboard prefetch act on.
+ *  Never fires for programmatic selection. */
+interface SelectionCommittedEvent {
+  readonly range: TextRange;
+}
+/** The selection went from a range to nothing. */
+type SelectionClearedEvent = Record<string, never>;
+/**
+ * The public selection API — the documented, stable surface for application
+ * code (toolbars, context menus, automation).
+ *
+ * The permission model: geometry enables selection (`doc.text.select`),
+ * text enables extraction (`doc.text.copy`) — neither implies the other.
+ * Everything here except the `readText` pair works with the select scope
+ * alone, so a deployment can allow selecting and highlighting while denying
+ * copy. Writes without the scope throw `PluginError('permission-denied')`;
+ * gate UI with {@link canSelect} / {@link canCopy}.
+ *
+ * Every gesture has a programmatic twin: drag = {@link select} (or
+ * `beginGestureAt` + {@link extendTo} for point-driven code on the host
+ * lens), double-click = {@link selectWordAt}, triple-click =
+ * {@link selectLineAt}, handle drag = {@link extendTo}, click on empty space
+ * = {@link clear}, select-all = {@link selectAll}.
+ *
+ * A page argument is a `PageRef` or a zero-based index. A verb given a page
+ * that isn't in the document throws `not-found`; a read returns empty.
+ *
+ * The settings (`getSettings`, `updateSettings`, `resetSettings`,
+ * `onSettingsChanged`) belong to the plugin, not to a document: a change
+ * reaches every open document.
+ *
+ * Framework-only plumbing (gesture bracketing, geometry warming, the
+ * highlight-visibility handshake) lives on `SelectionHostCapability`,
+ * reachable through `@embedpdf/plugin-selection/contract/host`. Both are the
+ * same runtime object — two typed lenses on one token.
+ */
+interface SelectionCapability extends SettingsApi<SelectionSettings> {
+  /** Whether this caller may create selections at all (`doc.text.select`). */
+  canSelect(): boolean;
+  /** Whether this caller may extract literal text (`doc.text.copy`). */
+  canCopy(): boolean;
+  /**
+   * Select a range — the same path gestures use, so the highlight, events
+   * and markup bridges behave identically. An empty range clears. Throws
+   * `permission-denied` without `doc.text.select`, `not-found` for a page
+   * that is not in this document. Fires `onChanged`, or `onCleared`.
+   */
+  select(range: SelectionRangeInput): void;
+  /** Select every character of the document. Throws `permission-denied` without `doc.text.select`. */
+  selectAll(): void;
+  /**
+   * Select every character on one page. Throws `permission-denied` without
+   * `doc.text.select`, `not-found` for a page that is not in this document.
+   */
+  selectPage(page: PageRef | number): void;
+  /**
+   * Select the word around a page point. Returns false when the point has no
+   * selectable text (geometry not loaded yet, or no glyph there). Throws
+   * `permission-denied` without `doc.text.select`, `not-found` for a page that
+   * is not in this document.
+   */
+  selectWordAt(page: PageRef | number, point: Point): boolean;
+  /** Select the visual line around a page point. Same result and errors as {@link selectWordAt}. */
+  selectLineAt(page: PageRef | number, point: Point): boolean;
+  /**
+   * Extend the current selection to a page point (a drag step). No selection
+   * → no-op; a page whose geometry has not loaded is warmed and the extension
+   * lands when it arrives. Errors as {@link selectPage}.
+   */
+  extendTo(page: PageRef | number, point: Point): void;
+  /** Clear the selection. Always allowed. Fires `onCleared` when something was selected. */
+  clear(): void;
+  /** Whether anything is selected. */
+  hasSelection(): boolean;
+  /**
+   * Whether the user is still selecting: from the press of a drag, a
+   * double-click or a handle until it lifts. A selection made from code is
+   * never in progress.
+   */
+  isSelecting(): boolean;
+  /** Per-page segments, endpoints, direction and the range. Reference-stable
+   *  until the selection changes. */
+  getSnapshot(): SelectionSnapshot;
+  /** The selected character range, or null. */
+  getRange(): TextRange | null;
+  /** The pages the current selection covers (those with at least one
+   *  segment), in document order — so a cross-page action can fan out per page. */
+  listSelectedPages(): readonly PageRef[];
+  /** Per-line oriented segments for a page, in page space — build your own
+   *  highlight layer from these. Reference-stable per page. */
+  listSegments(page: PageRef | number): readonly 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. */
+  listRects(page: PageRef | number): readonly Rect[];
+  /**
+   * 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. Null when nothing is selected (or nothing has
+   * materialized yet).
+   */
+  getAnchor(): SelectionAnchor | null;
+  /**
+   * The selected text. Each page's text snapshot is fetched once per content
+   * version and sliced through the engine's `charMap`; pages are joined with
+   * `\n`. Resolves `''` when nothing is selected. Rejects `permission-denied`
+   * without `doc.text.copy`, and `operation-cancelled` when `options.signal`
+   * fires. Clipboard writes are deliberately not here — this package is
+   * DOM-free; use `@embedpdf/web`'s clipboard helpers.
+   */
+  readText(options?: OperationOptions): Promise<string>;
+  /**
+   * Text for any range, without touching the selection. Rejects as
+   * {@link readText} does, and `not-found` for a page that is not in this
+   * document.
+   */
+  readTextInRange(range: TextRange, options?: OperationOptions): Promise<string>;
+  /** The range or its segments changed, whoever changed them. */
+  readonly onChanged: EventHook<SelectionChangedEvent>;
+  /** A selection gesture ended with a selection in place. */
+  readonly onCommitted: EventHook<SelectionCommittedEvent>;
+  /** The selection went from a range to nothing: a clear, an empty range, or
+   *  its pages' content changed or left the document. */
+  readonly onCleared: EventHook<SelectionClearedEvent>;
+}
+//#endregion
+export { SelectionClearedEvent as a, SelectionEndpoint as c, SelectionSnapshot as d, TextPosition as f, SelectionSegment as h, SelectionChangedEvent as i, SelectionRangeInput as l, SelectionToken as m, SelectionAnchor as n, SelectionCommittedEvent as o, TextRange as p, SelectionCapability as r, SelectionConfig as s, SELECTION_DEFAULTS as t, SelectionSettings as u };
+//# sourceMappingURL=contract-DLs4vXVt.d.ts.map

package/dist/contract.cjs

@@ -1,7 +1,4 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-//#region src/contract.ts
-const SelectionToken = require("./types-D9kEBMFj.cjs").SelectionToken;
-//#endregion
-exports.SelectionToken = SelectionToken;
-
-//# sourceMappingURL=contract.cjs.map
+const require_contract = require("./contract-BUiw1d8F.cjs");
+exports.SELECTION_DEFAULTS = require_contract.SELECTION_DEFAULTS;
+exports.SelectionToken = require_contract.SelectionToken;

package/dist/contract.d.cts

@@ -1,7 +1,2 @@
-import { c as SelectionRangeInput, f as TextPosition, h as SelectionSegment, i as SelectionEndpoint, l as SelectionSnapshot, o as SelectionMenuAnchor, p as TextRange, r as SelectionCapability } from "./types-CUrUVl6K.cjs";
-import { CapabilityToken } from "@embedpdf/core";
-//#region src/contract.d.ts
-declare const SelectionToken: CapabilityToken<SelectionCapability>;
-//#endregion
-export { type SelectionCapability, type SelectionEndpoint, type SelectionMenuAnchor, type SelectionRangeInput, type SelectionSegment, type SelectionSnapshot, SelectionToken, type TextPosition, type TextRange };
-//# sourceMappingURL=contract.d.cts.map
+import { a as SelectionClearedEvent, c as SelectionEndpoint, d as SelectionSnapshot, f as TextPosition, h as SelectionSegment, i as SelectionChangedEvent, l as SelectionRangeInput, m as SelectionToken, n as SelectionAnchor, o as SelectionCommittedEvent, p as TextRange, r as SelectionCapability, s as SelectionConfig, t as SELECTION_DEFAULTS, u as SelectionSettings } from "./contract-DLs4vXVt.cjs";
+export { SELECTION_DEFAULTS, SelectionAnchor, SelectionCapability, SelectionChangedEvent, SelectionClearedEvent, SelectionCommittedEvent, SelectionConfig, SelectionEndpoint, SelectionRangeInput, type SelectionSegment, SelectionSettings, SelectionSnapshot, SelectionToken, TextPosition, TextRange };

package/dist/contract.d.ts

@@ -1,7 +1,2 @@
-import { c as SelectionRangeInput, f as TextPosition, h as SelectionSegment, i as SelectionEndpoint, l as SelectionSnapshot, o as SelectionMenuAnchor, p as TextRange, r as SelectionCapability } from "./types-CUrUVl6K.js";
-import { CapabilityToken } from "@embedpdf/core";
-//#region src/contract.d.ts
-declare const SelectionToken: CapabilityToken<SelectionCapability>;
-//#endregion
-export { type SelectionCapability, type SelectionEndpoint, type SelectionMenuAnchor, type SelectionRangeInput, type SelectionSegment, type SelectionSnapshot, SelectionToken, type TextPosition, type TextRange };
-//# sourceMappingURL=contract.d.ts.map
+import { a as SelectionClearedEvent, c as SelectionEndpoint, d as SelectionSnapshot, f as TextPosition, h as SelectionSegment, i as SelectionChangedEvent, l as SelectionRangeInput, m as SelectionToken, n as SelectionAnchor, o as SelectionCommittedEvent, p as TextRange, r as SelectionCapability, s as SelectionConfig, t as SELECTION_DEFAULTS, u as SelectionSettings } from "./contract-DLs4vXVt.js";
+export { SELECTION_DEFAULTS, SelectionAnchor, SelectionCapability, SelectionChangedEvent, SelectionClearedEvent, SelectionCommittedEvent, SelectionConfig, SelectionEndpoint, SelectionRangeInput, type SelectionSegment, SelectionSettings, SelectionSnapshot, SelectionToken, TextPosition, TextRange };

package/dist/contract.js

@@ -1,7 +1,2 @@
-import { t as SelectionToken$1 } from "./types-BVUcOsCh.js";
-//#region src/contract.ts
-const SelectionToken = SelectionToken$1;
-//#endregion
-export { SelectionToken };
-
-//# sourceMappingURL=contract.js.map
+import { n as SelectionToken, t as SELECTION_DEFAULTS } from "./contract-DBXA64ep.js";
+export { SELECTION_DEFAULTS, SelectionToken };

package/dist/host-contract-DO2aLU2e.d.ts

@@ -0,0 +1,34 @@
+import { r as SelectionCapability } from "./contract-DLs4vXVt.js";
+import { PageRef } from "@embedpdf/core";
+import { Point } from "@embedpdf/core-geometry";
+//#region src/host-contract.d.ts
+interface SelectionHostCapability extends SelectionCapability {
+  /** Warm a page's text geometry. Resolves once loaded; resolves immediately
+   *  (nothing requested) without `doc.text.select` or for an unknown page. A
+   *  failed read resolves too — the layer simply has nothing to paint. */
+  ensureLoaded(page: PageRef): Promise<void>;
+  /** Whether the page's text geometry is loaded and current. */
+  isLoaded(page: PageRef): boolean;
+  /** Is a page-space point on (or near) text? Drives the I-beam cursor. */
+  isOverText(page: PageRef, point: Point): boolean;
+  /**
+   * A pointer gesture that drives the selection opened (pointer-down). From
+   * here until {@link endGesture}, `isSelecting()` is true and
+   * selection-scoped UI hides. Programmatic writes never open a gesture.
+   */
+  beginGesture(): void;
+  /** Open a caret selection at a page point (the first drag step). Returns
+   *  false when the point has no text — the caller lets the gesture go. */
+  beginGestureAt(page: PageRef, point: Point): boolean;
+  /** The gesture ended (pointer-up). Settles first, then emits `onCommitted`
+   *  when a selection is in place. */
+  endGesture(): void;
+  /** Suppress / restore the default highlight visual (a consumer drawing its
+   *  own preview — the markup ghost). */
+  setHighlightVisible(visible: boolean): void;
+  isHighlightVisible(): boolean;
+}
+declare const SelectionToken: import("@embedpdf/core").CapabilityToken<SelectionHostCapability>;
+//#endregion
+export { SelectionToken as n, SelectionHostCapability as t };
+//# sourceMappingURL=host-contract-DO2aLU2e.d.ts.map

package/dist/host-contract-Ddo4PcJJ.d.cts

@@ -0,0 +1,34 @@
+import { r as SelectionCapability } from "./contract-DLs4vXVt.cjs";
+import { PageRef } from "@embedpdf/core";
+import { Point } from "@embedpdf/core-geometry";
+//#region src/host-contract.d.ts
+interface SelectionHostCapability extends SelectionCapability {
+  /** Warm a page's text geometry. Resolves once loaded; resolves immediately
+   *  (nothing requested) without `doc.text.select` or for an unknown page. A
+   *  failed read resolves too — the layer simply has nothing to paint. */
+  ensureLoaded(page: PageRef): Promise<void>;
+  /** Whether the page's text geometry is loaded and current. */
+  isLoaded(page: PageRef): boolean;
+  /** Is a page-space point on (or near) text? Drives the I-beam cursor. */
+  isOverText(page: PageRef, point: Point): boolean;
+  /**
+   * A pointer gesture that drives the selection opened (pointer-down). From
+   * here until {@link endGesture}, `isSelecting()` is true and
+   * selection-scoped UI hides. Programmatic writes never open a gesture.
+   */
+  beginGesture(): void;
+  /** Open a caret selection at a page point (the first drag step). Returns
+   *  false when the point has no text — the caller lets the gesture go. */
+  beginGestureAt(page: PageRef, point: Point): boolean;
+  /** The gesture ended (pointer-up). Settles first, then emits `onCommitted`
+   *  when a selection is in place. */
+  endGesture(): void;
+  /** Suppress / restore the default highlight visual (a consumer drawing its
+   *  own preview — the markup ghost). */
+  setHighlightVisible(visible: boolean): void;
+  isHighlightVisible(): boolean;
+}
+declare const SelectionToken: import("@embedpdf/core").CapabilityToken<SelectionHostCapability>;
+//#endregion
+export { SelectionToken as n, SelectionHostCapability as t };
+//# sourceMappingURL=host-contract-Ddo4PcJJ.d.cts.map