@embedpdf/web 3.0.0-next.6 → 3.0.0-next.8

package/dist/index.d.ts

@@ -239,5 +239,323 @@ interface PaintedImageCallbacks {
  */
 declare function bindPaintedImage(image: HTMLImageElement, source: ObjectUrlImageSource, callbacks: PaintedImageCallbacks): () => void;
 //#endregion
-export { type AnchorTarget, type AnchoredPlacement, type AnchoredPoint, type AnchoredPosition, type AnchoredRect, type ClipboardSelectionSource, type ObjectUrlImageSource, type PaintedImageCallbacks, type PickFileOptions, type SelectionClipboardOptions, type SvgCursorOptions, type ViewProjector, bindPaintedImage, copySelection, observeClientGeometry, pickFile, pickImageFile, positionAnchoredRect, projectAnchoredTarget, sanitizeExternalUri, saveFile, svgCursor, wireSelectionClipboard };
+//#region src/feedback.d.ts
+/**
+ * Platform-feedback providers — the browser implementations of the interaction
+ * hub's haptic port (structurally `PlatformFeedback` from
+ * `@embedpdf/plugin-interaction`; declared structurally here so this package
+ * stays plugin-free, per the layering law).
+ *
+ * Honesty about reach: `navigator.vibrate` works on Android browsers and is
+ * NOT implemented in iOS Safari — there the default provider is a silent
+ * no-op until Apple ships a haptics API. (The community switch-control hacks
+ * were evaluated and deliberately NOT shipped: Apple patched programmatic
+ * triggering in iOS 26.5, leaving only tap-on-control tricks that don't fit a
+ * viewer's gesture moments.) The real iPhone haptic today comes through a
+ * native shell: a WKWebView embedder installs a script message handler and
+ * passes {@link wkFeedback} (or their own provider) instead.
+ */
+/** Structural twin of plugin-interaction's `PlatformFeedback`. */
+interface WebPlatformFeedback {
+  selection(): void;
+  impact(weight?: 'light' | 'medium' | 'heavy'): void;
+  notify(kind: 'success' | 'warning' | 'error'): void;
+}
+/**
+ * The default web provider: the Vibration API, mapped onto the three haptic
+ * families (selection = the shortest tick; impact scales with weight; notify
+ * uses patterns). A no-op wherever vibration is unsupported — notably iOS
+ * Safari — so it is always safe to install.
+ */
+declare const vibrationFeedback: WebPlatformFeedback;
+/**
+ * A provider for native iOS shells: forwards each call to a WKWebView script
+ * message handler the HOST APP installed under `handlerName` — an explicit
+ * contract between the embedder and their own app, never a global this library
+ * sniffs on its own. The message shape is
+ * `{ family: 'selection' } | { family: 'impact', weight } | { family: 'notify', kind }`;
+ * the native side maps families onto the matching `UIFeedbackGenerator`.
+ * Calls fall back to `fallback` (default: {@link vibrationFeedback}) when the
+ * handler is absent, so one provider serves a hybrid web/app deployment.
+ */
+declare const wkFeedback: (handlerName: string, fallback?: WebPlatformFeedback) => WebPlatformFeedback;
+//#endregion
+//#region src/stage-gestures.d.ts
+/**
+ * Stage gesture controller — the ONE DOM input binding for a Stage surface,
+ * shared by every framework adapter (React, Angular, …) so the feel can never
+ * drift between them.
+ *
+ * The premise (see the stage plugin's camera doctrine): desktop inputs arrive
+ * with physics already applied by the OS — momentum lives in the wheel stream,
+ * a trackpad pinch is one pre-arbitrated gesture stream. Touch arrives RAW:
+ * with `touch-action: none` the platform scroller is out of the loop, so the
+ * ballistics (velocity → fling) and the arbitration (is this contact a scroll,
+ * a pinch, a tap, or a tool gesture?) must be synthesized here.
+ *
+ * Arbitration is MODALITY-AWARE:
+ *   - touch  — navigation-first: one finger pans (whatever tool is armed), two
+ *     fingers pinch-zoom around their centroid, release velocity flings, a tap
+ *     forwards as a click, a double-tap zoom-toggles, a long-press hands the
+ *     gesture to the interaction hub (text selection), and a second finger
+ *     landing mid-tool-gesture CANCELS it into a pinch (the Notes/Procreate
+ *     convention).
+ *   - mouse/pen — tool-first, exactly the pre-existing behavior: with a hub,
+ *     every down/move/up forwards (pan is the pan tool's job); without one,
+ *     dragging pans. Wheel and Safari-trackpad gesture events are unchanged.
+ *
+ * Camera writes are rAF-COALESCED: pointer events only update gesture state;
+ * one animation-frame tick applies at most one pan and one zoom per frame,
+ * inside the host's begin/endGesture transaction. Events may arrive at 120 Hz;
+ * the camera moves at display rate.
+ *
+ * Dependency note: this module speaks to the stage through the STRUCTURAL
+ * {@link StageGestureHost} interface (satisfied by `StageCapability`) and to
+ * the interaction hub through {@link StageGestureSink} (a closure the adapter
+ * builds) — @embedpdf/web stays free of plugin imports, per the layering law.
+ */
+type StagePointerKind = 'mouse' | 'pen' | 'touch';
+/** What the controller needs from the camera — `StageCapability` satisfies it. */
+interface StageGestureHost {
+  panBy(dxScreen: number, dyScreen: number): void;
+  zoomAround(screenPt: {
+    x: number;
+    y: number;
+  }, factor: number): void;
+  beginGesture(options?: {
+    elastic?: boolean;
+  }): void;
+  endGesture(): void;
+  /** Momentum pan from a release velocity in screen px/s. */
+  fling(velocityX: number, velocityY: number): void;
+  /** True while a tween/fling runs — a touch-down then is a "catch", not a tap. */
+  cameraInMotion(): boolean;
+  doubleTapZoom(screenPt: {
+    x: number;
+    y: number;
+  }): void;
+}
+/**
+ * Where non-navigation gestures go — the adapter's bridge to the interaction
+ * hub. Every callback receives the ORIGINAL PointerEvent so the adapter can
+ * resolve pages/points exactly as it always has. Omit the sink entirely for a
+ * hub-less (built-in pan) stage.
+ */
+interface StageGestureSink {
+  down(e: PointerEvent, clickCount: number): void;
+  move(e: PointerEvent): void;
+  up(e: PointerEvent): void;
+  /** The gesture was taken over by navigation (second finger → pinch) or
+   *  cancelled by the system — abort, don't commit. */
+  cancel(e: PointerEvent): void;
+  /** Pointer travel with no gesture in flight — cursor feedback. */
+  hover(e: PointerEvent): void;
+  /** A touch press held still: hand the gesture to the hub (the adapter
+   *  typically forwards it as a word-select down). Subsequent move/up arrive
+   *  via {@link move}/{@link up}. */
+  longPress(e: PointerEvent): void;
+  /**
+   * Touch-consent pre-flight, asked at touch-down BEFORE the contact is
+   * classified: does a tool have standing to own this contact? True when the
+   * armed tool takes fingers wholesale (a drawing tool) or something under
+   * the point claims its drags (a selected annotation's body or handles).
+   * True routes the whole contact to {@link down}/{@link move}/{@link up} —
+   * where a second finger still cancels it into a pinch. Must be a pure
+   * read. Absent = never; the contact navigates.
+   */
+  claimsPoint?(e: PointerEvent): boolean;
+}
+/** The wheel fields the zoom classifier reads (see `./wheel`'s `WheelSample`). */
+interface StageWheelSample {
+  deltaY: number;
+  deltaMode: number;
+  ctrlKey: boolean;
+  metaKey: boolean;
+}
+interface StageGestureOptions {
+  /** Ambient zoom (wheel-zoom, pinch-zoom, double-tap zoom). Off: zoom wheels
+   *  fall through to pan and pinches pan without zooming — but are still
+   *  swallowed, never page-zooming the browser. Default true. */
+  zoomGestures?: boolean;
+  /** The wheel → zoom-factor classifier. Defaults to this package's
+   *  `wheelZoomFactor` (browser wheel classification lives HERE, with the rest
+   *  of the browser input handling); inject to override or to fake in tests. */
+  wheelZoomFactor?: (sample: StageWheelSample) => number;
+  /** Tool routing for non-navigation gestures; omit for built-in-pan stages. */
+  sink?: StageGestureSink | null;
+  /** Touch press duration that becomes a long-press (ms). Default 450. */
+  longPressMs?: number;
+  /** Finger travel below which a touch stays a tap/press (px). Default 10. */
+  tapSlopPx?: number;
+  /** Max gap between taps for a double-tap (ms). Default 300. */
+  doubleTapMs?: number;
+  /** Release speed below which no fling starts (px/s). Default 50. */
+  flingMinVelocity?: number;
+}
+/**
+ * Release velocity from a trail of pointer samples: the mean velocity over the
+ * trailing `windowMs` (first-to-last inside the window). Null when the trail is
+ * too thin or too stale to trust — the standard "held still, then let go"
+ * case, which must NOT fling. Pure; exported for tests.
+ */
+declare function computeReleaseVelocity(samples: ReadonlyArray<{
+  t: number;
+  x: number;
+  y: number;
+}>, now: number, windowMs?: number): {
+  vx: number;
+  vy: number;
+} | null;
+/** Attach the gesture controller to a Stage container. Returns the detach fn. */
+declare function createStageGestureController(el: HTMLElement, host: StageGestureHost, options: StageGestureOptions): () => void;
+//#endregion
+//#region src/selection-handles.d.ts
+/**
+ * Selection-handle DOM binding — the listener mechanics of dragging one
+ * handle element, shared by every framework adapter (the policy — geometry
+ * and the drag session — lives in `@embedpdf/plugin-selection`'s pure
+ * `handles` module; this file never imports it, per the layering law:
+ * structural interfaces only).
+ *
+ * The load-bearing subtlety this module owns: the pointer-DOWN shield must be
+ * a NATIVE listener. The stage's gesture controller listens natively on the
+ * container, so a framework-synthetic stopPropagation (React runs its
+ * handlers at the root, AFTER the container's native ones) would be too late
+ * — the stage would already be panning underneath the handle drag. Once the
+ * down is captured here, movement tracks by CLIENT DELTAS from the handle's
+ * own base point: no DOM geometry reads, and the client↔overlay conversion
+ * cancels out.
+ */
+interface SurfacePoint$1 {
+  x: number;
+  y: number;
+}
+/** The armed drag the adapter hands back — plugin-selection's
+ *  `SelectionHandleDragSession` satisfies it. */
+interface SelectionHandleSession {
+  move(overlay: SurfacePoint$1): void;
+  end(): void;
+}
+interface AttachSelectionHandleOptions {
+  /**
+   * Called at pointer-down to arm a drag: return the drag session plus the
+   * handle's current BASE point in overlay space (the bar's midpoint — the
+   * point the user grabbed). Return null to decline (endpoint vanished, page
+   * not laid out) — the press then does nothing and nothing is captured.
+   */
+  arm(): {
+    base: SurfacePoint$1;
+    session: SelectionHandleSession;
+  } | null;
+}
+/** Bind one handle element. Returns the detach fn. */
+declare function attachSelectionHandle(el: HTMLElement, options: AttachSelectionHandleOptions): () => void;
+//#endregion
+//#region src/stage-surface.d.ts
+interface SurfacePoint {
+  x: number;
+  y: number;
+}
+/** What the binding needs from the stage — `StageCapability` satisfies it. */
+interface StageSurfaceHost extends StageGestureHost {
+  setViewport(size: {
+    width: number;
+    height: number;
+  }): void;
+  setDevicePixelRatio(ratio: number): void;
+  /** Viewport point → the page under it (with per-page display context), or null over a gap. */
+  pageAt(screen: SurfacePoint): {
+    pon: number;
+    point: SurfacePoint;
+    scale?: number;
+    rotation?: 0 | 90 | 180 | 270;
+    zoom?: number;
+  } | null;
+  /** Viewport point → a SPECIFIC page's content space, unclamped (frame-stable projection). */
+  pointOnPage(pon: number, screen: SurfacePoint): SurfacePoint | null;
+}
+/**
+ * The page-resolved sample the binding hands the hub — structurally a
+ * `PointerSample` (plugin-interaction). `source` carries the lens identity so
+ * the hub can route lens-scoped handlers; with several stages on one document,
+ * a drag on one lens must never be captured by another lens's handler.
+ */
+interface StageSurfaceSample {
+  phase: 'down' | 'move' | 'up' | 'cancel';
+  viewport: SurfacePoint;
+  page?: {
+    pon: number;
+    point: SurfacePoint;
+    scale?: number;
+    rotation?: 0 | 90 | 180 | 270;
+    zoom?: number;
+  };
+  project: (pon: number) => SurfacePoint | null;
+  modifiers: {
+    shift: boolean;
+    alt: boolean;
+    ctrl: boolean;
+    meta: boolean;
+  };
+  clickCount: number;
+  pointerType: 'mouse' | 'pen' | 'touch';
+  gesture?: 'long-press';
+  source?: string;
+}
+/** What the binding needs from the interaction hub — `InteractionCapability` satisfies it. */
+interface StageSurfaceHub {
+  dispatch(sample: StageSurfaceSample): void;
+  activeTool(): {
+    touchDirect?: boolean;
+  };
+  wouldClaimTouch(sample: StageSurfaceSample): boolean;
+}
+interface StageSurfaceOptions {
+  /** Route pointer input to the interaction hub (page-resolved samples) instead
+   *  of built-in drag-to-pan. Omit/null for a hub-less stage. */
+  hub?: StageSurfaceHub | null;
+  /** The lens identity stamped on every sample (`StageCapability.lensId()`),
+   *  so lens-scoped handlers only see their own stage's input. */
+  source?: string;
+  /** Ambient zoom gestures (see {@link StageGestureOptions}). Default true. */
+  zoomGestures?: boolean;
+  /** Override the wheel → zoom-factor classifier (defaults to `./wheel`). */
+  wheelZoomFactor?: (sample: StageWheelSample) => number;
+}
+/** Attach the full surface binding. Returns the detach fn. */
+declare function createStageSurface(el: HTMLElement, stage: StageSurfaceHost, options?: StageSurfaceOptions): () => void;
+//#endregion
+//#region src/wheel.d.ts
+/**
+ * Wheel-input classification for ambient zoom — pure, so every framework
+ * adapter shares one feel and the mapping is unit-testable.
+ *
+ * A ctrl/cmd wheel event is one of three physically different inputs that
+ * happen to share an event type, each with its own unit system:
+ *
+ *   • trackpad PINCH — browsers (Chrome/Edge/Firefox) synthesize ctrl+wheel
+ *     px-deltas scaled to the de-facto convention that `exp(-Δ/100)` tracks
+ *     the physical finger scale 1:1. Anything weaker feels dead (the content
+ *     must track the fingers — the Figma/maps feel).
+ *   • mouse NOTCHES — coarse steps: ±100/±120 px in Chrome, lines/pages mode
+ *     in Firefox. The pinch mapping would triple per click; a notch instead
+ *     steps by 1.2, the same ratio as the zoom buttons.
+ *   • cmd + continuous SCROLL — real scroll px, big and streaming (with
+ *     momentum): a gentle scrub coefficient. A cmd+mouse notch (±120 px)
+ *     lands within 0.3% of the 1.2 button step, so it needs no special case.
+ *
+ * (Safari never synthesizes ctrl+wheel for pinch — it fires proprietary
+ * gesture events with an absolute scale; that wiring lives in the adapters.)
+ */
+interface WheelSample {
+  deltaY: number;
+  /** WheelEvent.deltaMode: 0 = pixels, 1 = lines, 2 = pages. */
+  deltaMode: number;
+  ctrlKey: boolean;
+  metaKey: boolean;
+}
+/** Zoom factor for a ctrl/cmd wheel event (the caller decides zoom vs pan). */
+declare function wheelZoomFactor(e: WheelSample): number;
+//#endregion
+export { type AnchorTarget, type AnchoredPlacement, type AnchoredPoint, type AnchoredPosition, type AnchoredRect, type AttachSelectionHandleOptions, type ClipboardSelectionSource, type ObjectUrlImageSource, type PaintedImageCallbacks, type PickFileOptions, type SelectionClipboardOptions, type SelectionHandleSession, type StageGestureHost, type StageGestureOptions, type StageGestureSink, type StagePointerKind, type StageSurfaceHost, type StageSurfaceHub, type StageSurfaceOptions, type StageSurfaceSample, type StageWheelSample, type SvgCursorOptions, type ViewProjector, type WebPlatformFeedback, type WheelSample, attachSelectionHandle, bindPaintedImage, computeReleaseVelocity, copySelection, createStageGestureController, createStageSurface, observeClientGeometry, pickFile, pickImageFile, positionAnchoredRect, projectAnchoredTarget, sanitizeExternalUri, saveFile, svgCursor, vibrationFeedback, wheelZoomFactor, wireSelectionClipboard, wkFeedback };
 //# sourceMappingURL=index.d.ts.map