@embedpdf/web 3.0.0-next.5 → 3.0.0-next.7

package/dist/index.cjs

@@ -235,7 +235,847 @@ function sanitizeExternalUri(uri, allowedSchemes = DEFAULT_ALLOWED_SCHEMES) {
 	}
 }
 //#endregion
+//#region src/painted-image.ts
+/**
+* Bind a raster source to an <img> without ever painting its incomplete-image
+* placeholder. The source becomes visible on load; retained coverage is
+* released only after the browser has had one full frame to present it.
+*
+* Call this from the framework's pre-paint mount hook and invoke the returned
+* cleanup on unmount. Keeping this DOM lifecycle here lets every framework
+* adapter remain a ref plus one bind/unbind hook.
+*/
+function bindPaintedImage(image, source, callbacks) {
+	const controller = new AbortController();
+	let revoke;
+	let frame = 0;
+	let painted = false;
+	image.style.visibility = "hidden";
+	const onLoad = () => {
+		image.style.visibility = "visible";
+		frame = requestAnimationFrame(() => {
+			frame = requestAnimationFrame(() => {
+				frame = 0;
+				painted = true;
+				callbacks.onPainted();
+			});
+		});
+	};
+	image.addEventListener("load", onLoad, { once: true });
+	source.objectUrl(controller.signal).then((objectUrl) => {
+		if (controller.signal.aborted) {
+			objectUrl.revoke();
+			return;
+		}
+		revoke = objectUrl.revoke;
+		image.src = objectUrl.url;
+	}, () => {});
+	return () => {
+		controller.abort();
+		if (frame) cancelAnimationFrame(frame);
+		image.removeEventListener("load", onLoad);
+		image.style.visibility = "hidden";
+		image.removeAttribute("src");
+		revoke?.();
+		if (painted) callbacks.onUnpainted();
+	};
+}
+//#endregion
+//#region src/feedback.ts
+const vibrate = (pattern) => {
+	if (typeof navigator !== "undefined") navigator.vibrate?.(pattern);
+};
+/**
+* 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.
+*/
+const vibrationFeedback = {
+	selection: () => vibrate(8),
+	impact: (weight = "light") => vibrate(weight === "heavy" ? 30 : weight === "medium" ? 20 : 10),
+	notify: (kind) => vibrate(kind === "error" ? [
+		12,
+		60,
+		12,
+		60,
+		12
+	] : kind === "warning" ? [
+		15,
+		70,
+		15
+	] : [
+		10,
+		50,
+		10
+	])
+};
+/**
+* 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.
+*/
+const wkFeedback = (handlerName, fallback = vibrationFeedback) => {
+	const handler = () => {
+		if (typeof window === "undefined") return void 0;
+		return window.webkit?.messageHandlers?.[handlerName];
+	};
+	return {
+		selection: () => {
+			const h = handler();
+			if (h) h.postMessage({ family: "selection" });
+			else fallback.selection();
+		},
+		impact: (weight = "light") => {
+			const h = handler();
+			if (h) h.postMessage({
+				family: "impact",
+				weight
+			});
+			else fallback.impact(weight);
+		},
+		notify: (kind) => {
+			const h = handler();
+			if (h) h.postMessage({
+				family: "notify",
+				kind
+			});
+			else fallback.notify(kind);
+		}
+	};
+};
+//#endregion
+//#region src/wheel.ts
+/** The per-notch step for discrete wheels — the zoom buttons' ratio. */
+const NOTCH = 1.2;
+/** Zoom factor for a ctrl/cmd wheel event (the caller decides zoom vs pan). */
+function wheelZoomFactor(e) {
+	if (e.deltaMode !== 0) return Math.pow(NOTCH, -Math.sign(e.deltaY));
+	if (e.ctrlKey) {
+		if (Math.abs(e.deltaY) >= 100) return Math.pow(NOTCH, -Math.sign(e.deltaY));
+		return Math.exp(-e.deltaY / 100);
+	}
+	return Math.exp(-e.deltaY * .0015);
+}
+//#endregion
+//#region src/stage-gestures.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.
+*/
+/**
+* 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.
+*/
+function computeReleaseVelocity(samples, now, windowMs = 100) {
+	let firstIdx = -1;
+	for (let i = 0; i < samples.length; i++) if (now - samples[i].t <= windowMs) {
+		firstIdx = i;
+		break;
+	}
+	if (firstIdx < 0 || firstIdx === samples.length - 1) return null;
+	const first = samples[firstIdx];
+	const last = samples[samples.length - 1];
+	const dt = last.t - first.t;
+	if (dt < 10) return null;
+	return {
+		vx: (last.x - first.x) / dt * 1e3,
+		vy: (last.y - first.y) / dt * 1e3
+	};
+}
+/** Attach the gesture controller to a Stage container. Returns the detach fn. */
+function createStageGestureController(el, host, options) {
+	const zoomGestures = options.zoomGestures ?? true;
+	const wheelZoom = options.wheelZoomFactor ?? wheelZoomFactor;
+	const sink = options.sink ?? null;
+	const LONG_PRESS_MS = options.longPressMs ?? 450;
+	const SLOP = options.tapSlopPx ?? 10;
+	const DOUBLE_TAP_MS = options.doubleTapMs ?? 300;
+	const DOUBLE_TAP_RADIUS = 25;
+	const FLING_MIN = options.flingMinVelocity ?? 50;
+	const MIN_PINCH_SPAN = 20;
+	const PINCH_RELEASE_GRACE_MS = 160;
+	const SETTLE_SPEED = .12;
+	const pointers = /* @__PURE__ */ new Map();
+	let mode = "idle";
+	let began = false;
+	let suppressTap = false;
+	let touchToolGesture = false;
+	let downEvent = null;
+	let longPressTimer = null;
+	let panId = -1;
+	let panArmed = true;
+	let panGraceUntil = 0;
+	let graceSample = {
+		t: 0,
+		x: 0,
+		y: 0
+	};
+	let lastTouchAt = -Infinity;
+	let frame = 0;
+	let dirty = false;
+	let lastApplied = {
+		x: 0,
+		y: 0
+	};
+	let lastSpan = 0;
+	let trail = [];
+	let spanTrail = [];
+	let lastTapT = 0;
+	let lastTapX = 0;
+	let lastTapY = 0;
+	let mLast = 0;
+	let mX = 0;
+	let mY = 0;
+	let mCount = 0;
+	const clickCount = (e) => {
+		const now = Date.now();
+		mCount = now - mLast <= 400 && Math.hypot(e.clientX - mX, e.clientY - mY) <= 6 ? mCount + 1 : 1;
+		mLast = now;
+		mX = e.clientX;
+		mY = e.clientY;
+		return mCount;
+	};
+	const vpt = (clientX, clientY) => {
+		const r = el.getBoundingClientRect();
+		return {
+			x: clientX - r.left,
+			y: clientY - r.top
+		};
+	};
+	const touches = () => {
+		const out = [];
+		pointers.forEach((p) => {
+			if (p.kind === "touch") out.push(p);
+		});
+		return out;
+	};
+	const clearLongPress = () => {
+		if (longPressTimer !== null) {
+			clearTimeout(longPressTimer);
+			longPressTimer = null;
+		}
+	};
+	const stopFrames = () => {
+		if (frame) {
+			cancelAnimationFrame(frame);
+			frame = 0;
+		}
+	};
+	const begin = (elastic = false) => {
+		if (!began) {
+			began = true;
+			host.beginGesture(elastic ? { elastic: true } : void 0);
+		}
+	};
+	const end = () => {
+		if (began) {
+			began = false;
+			host.endGesture();
+		}
+	};
+	const toIdle = () => {
+		mode = "idle";
+		downEvent = null;
+		touchToolGesture = false;
+		trail = [];
+		spanTrail = [];
+		dirty = false;
+		panId = -1;
+		panArmed = true;
+		panGraceUntil = 0;
+		clearLongPress();
+		stopFrames();
+	};
+	const pushSample = (x, y) => {
+		trail.push({
+			t: performance.now(),
+			x,
+			y
+		});
+		if (trail.length > 16) trail.shift();
+	};
+	const maybeFling = () => {
+		const v = computeReleaseVelocity(trail, performance.now());
+		if (v && Math.hypot(v.vx, v.vy) >= FLING_MIN) host.fling(v.vx, v.vy);
+	};
+	const flushPanTo = (x, y) => {
+		const dx = x - lastApplied.x;
+		const dy = y - lastApplied.y;
+		if (dx !== 0 || dy !== 0) host.panBy(dx, dy);
+		lastApplied = {
+			x,
+			y
+		};
+		dirty = false;
+	};
+	const flushPinch = (ax, ay, bx, by) => {
+		const cx = (ax + bx) / 2;
+		const cy = (ay + by) / 2;
+		const span = Math.hypot(ax - bx, ay - by);
+		const dx = cx - lastApplied.x;
+		const dy = cy - lastApplied.y;
+		if (dx !== 0 || dy !== 0) host.panBy(dx, dy);
+		if (zoomGestures && span > MIN_PINCH_SPAN && lastSpan > MIN_PINCH_SPAN && span !== lastSpan) host.zoomAround(vpt(cx, cy), span / lastSpan);
+		pushSample(cx, cy);
+		spanTrail.push({
+			t: performance.now(),
+			x: span,
+			y: 0
+		});
+		if (spanTrail.length > 16) spanTrail.shift();
+		lastApplied = {
+			x: cx,
+			y: cy
+		};
+		lastSpan = span;
+		dirty = false;
+	};
+	const tick = () => {
+		frame = 0;
+		if (mode === "pan" || mode === "mousedrag") {
+			const p = pointers.get(panId);
+			if (p && dirty) flushPanTo(p.x, p.y);
+			frame = requestAnimationFrame(tick);
+		} else if (mode === "pinch") {
+			const [a, b] = touches();
+			if (a && b && dirty) flushPinch(a.x, a.y, b.x, b.y);
+			frame = requestAnimationFrame(tick);
+		}
+	};
+	const ensureFrames = () => {
+		if (!frame) frame = requestAnimationFrame(tick);
+	};
+	const enterPinch = () => {
+		const [a, b] = touches();
+		if (!a || !b) return;
+		mode = "pinch";
+		lastApplied = {
+			x: (a.x + b.x) / 2,
+			y: (a.y + b.y) / 2
+		};
+		lastSpan = Math.hypot(a.x - b.x, a.y - b.y);
+		trail = [];
+		dirty = false;
+		ensureFrames();
+	};
+	const onLongPress = () => {
+		longPressTimer = null;
+		if (mode !== "pending" || !downEvent || !sink) return;
+		end();
+		mode = "tool";
+		touchToolGesture = true;
+		sink.longPress(downEvent);
+	};
+	const onDown = (e) => {
+		const kind = e.pointerType || "mouse";
+		if (kind === "touch") lastTouchAt = performance.now();
+		if (kind !== "touch") {
+			if (kind === "mouse" && e.button !== 0) return;
+			if (mode !== "idle") return;
+			pointers.set(e.pointerId, {
+				id: e.pointerId,
+				kind,
+				x: e.clientX,
+				y: e.clientY,
+				downX: e.clientX,
+				downY: e.clientY
+			});
+			if (sink) {
+				mode = "tool";
+				sink.down(e, clickCount(e));
+			} else {
+				mode = "mousedrag";
+				begin();
+				panId = e.pointerId;
+				lastApplied = {
+					x: e.clientX,
+					y: e.clientY
+				};
+				ensureFrames();
+			}
+			return;
+		}
+		switch (mode) {
+			case "idle": {
+				pointers.set(e.pointerId, {
+					id: e.pointerId,
+					kind,
+					x: e.clientX,
+					y: e.clientY,
+					downX: e.clientX,
+					downY: e.clientY
+				});
+				const moving = host.cameraInMotion();
+				if (!moving && sink?.claimsPoint?.(e)) {
+					mode = "tool";
+					touchToolGesture = true;
+					sink.down(e, 1);
+					break;
+				}
+				mode = "pending";
+				downEvent = e;
+				suppressTap = moving;
+				begin(true);
+				trail = [];
+				pushSample(e.clientX, e.clientY);
+				clearLongPress();
+				if (sink && !suppressTap) longPressTimer = setTimeout(onLongPress, LONG_PRESS_MS);
+				break;
+			}
+			case "pending":
+			case "pan":
+				pointers.set(e.pointerId, {
+					id: e.pointerId,
+					kind,
+					x: e.clientX,
+					y: e.clientY,
+					downX: e.clientX,
+					downY: e.clientY
+				});
+				clearLongPress();
+				enterPinch();
+				break;
+			case "tool":
+				if (!touchToolGesture) return;
+				sink?.cancel(e);
+				touchToolGesture = false;
+				pointers.set(e.pointerId, {
+					id: e.pointerId,
+					kind,
+					x: e.clientX,
+					y: e.clientY,
+					downX: e.clientX,
+					downY: e.clientY
+				});
+				begin(true);
+				enterPinch();
+				break;
+			case "pinch":
+			case "mousedrag": return;
+		}
+	};
+	const onWindowMove = (e) => {
+		const p = pointers.get(e.pointerId);
+		if (!p) return;
+		if (p.kind === "touch") lastTouchAt = performance.now();
+		p.x = e.clientX;
+		p.y = e.clientY;
+		switch (mode) {
+			case "pending":
+				pushSample(p.x, p.y);
+				if (Math.hypot(p.x - p.downX, p.y - p.downY) > SLOP) {
+					clearLongPress();
+					mode = "pan";
+					panId = p.id;
+					lastApplied = {
+						x: p.x,
+						y: p.y
+					};
+					ensureFrames();
+				}
+				break;
+			case "pan":
+				if (p.id !== panId) break;
+				if (!panArmed) {
+					const nowT = performance.now();
+					if (nowT < panGraceUntil) {
+						const dt = nowT - graceSample.t;
+						if (dt >= 8) {
+							const speed = Math.hypot(p.x - graceSample.x, p.y - graceSample.y) / dt;
+							graceSample = {
+								t: nowT,
+								x: p.x,
+								y: p.y
+							};
+							if (speed < SETTLE_SPEED) panGraceUntil = 0;
+						}
+						p.downX = p.x;
+						p.downY = p.y;
+						break;
+					}
+					if (Math.hypot(p.x - p.downX, p.y - p.downY) <= SLOP) break;
+					panArmed = true;
+					lastApplied = {
+						x: p.x,
+						y: p.y
+					};
+					trail = [];
+					spanTrail = [];
+				}
+				pushSample(p.x, p.y);
+				dirty = true;
+				break;
+			case "pinch":
+				dirty = true;
+				break;
+			case "tool":
+				sink?.move(e);
+				break;
+			case "mousedrag":
+				if (p.id === panId) dirty = true;
+				break;
+			case "idle": break;
+		}
+	};
+	const onHoverMove = (e) => {
+		if (mode === "idle" && sink) sink.hover(e);
+	};
+	const backToSingleFinger = () => {
+		const rest = touches();
+		if (rest.length !== 1) return false;
+		mode = "pan";
+		panId = rest[0].id;
+		panArmed = false;
+		panGraceUntil = performance.now() + PINCH_RELEASE_GRACE_MS;
+		graceSample = {
+			t: performance.now(),
+			x: rest[0].x,
+			y: rest[0].y
+		};
+		rest[0].downX = rest[0].x;
+		rest[0].downY = rest[0].y;
+		lastApplied = {
+			x: rest[0].x,
+			y: rest[0].y
+		};
+		trail = [];
+		dirty = false;
+		return true;
+	};
+	const onUp = (e) => {
+		const p = pointers.get(e.pointerId);
+		if (!p) return;
+		if (p.kind === "touch") lastTouchAt = performance.now();
+		pointers.delete(e.pointerId);
+		switch (mode) {
+			case "pending": {
+				clearLongPress();
+				end();
+				const now = performance.now();
+				const isDouble = now - lastTapT <= DOUBLE_TAP_MS && Math.hypot(e.clientX - lastTapX, e.clientY - lastTapY) <= DOUBLE_TAP_RADIUS;
+				if (suppressTap) lastTapT = 0;
+				else if (zoomGestures && isDouble) {
+					lastTapT = 0;
+					host.doubleTapZoom(vpt(e.clientX, e.clientY));
+				} else {
+					lastTapT = now;
+					lastTapX = e.clientX;
+					lastTapY = e.clientY;
+					if (sink && downEvent) {
+						sink.down(downEvent, 1);
+						sink.up(e);
+					}
+				}
+				toIdle();
+				break;
+			}
+			case "pan":
+				if (!panArmed) {
+					const now = performance.now();
+					const v = computeReleaseVelocity(trail, now);
+					const vs = computeReleaseVelocity(spanTrail, now);
+					end();
+					if (v) {
+						const speed = Math.hypot(v.vx, v.vy);
+						if (speed >= FLING_MIN && speed > Math.abs(vs?.vx ?? 0)) host.fling(v.vx, v.vy);
+					}
+					toIdle();
+					break;
+				}
+				flushPanTo(e.clientX, e.clientY);
+				pushSample(e.clientX, e.clientY);
+				end();
+				maybeFling();
+				toIdle();
+				break;
+			case "pinch": {
+				const rest = touches();
+				if (rest.length === 1) {
+					mode = "pan";
+					panId = rest[0].id;
+					panArmed = false;
+					panGraceUntil = performance.now() + PINCH_RELEASE_GRACE_MS;
+					graceSample = {
+						t: performance.now(),
+						x: rest[0].x,
+						y: rest[0].y
+					};
+					rest[0].downX = rest[0].x;
+					rest[0].downY = rest[0].y;
+					lastApplied = {
+						x: rest[0].x,
+						y: rest[0].y
+					};
+					dirty = false;
+					break;
+				}
+				end();
+				maybeFling();
+				toIdle();
+				break;
+			}
+			case "tool":
+				sink?.up(e);
+				toIdle();
+				break;
+			case "mousedrag":
+				if (p.id !== panId) break;
+				flushPanTo(e.clientX, e.clientY);
+				end();
+				toIdle();
+				break;
+			case "idle": break;
+		}
+	};
+	const onCancel = (e) => {
+		if (!pointers.get(e.pointerId)) return;
+		pointers.delete(e.pointerId);
+		if (mode === "tool") {
+			sink?.cancel(e);
+			toIdle();
+			return;
+		}
+		if (mode === "pinch" && backToSingleFinger()) return;
+		end();
+		toIdle();
+	};
+	const onWheel = (e) => {
+		e.preventDefault();
+		if (zoomGestures && (e.ctrlKey || e.metaKey)) host.zoomAround(vpt(e.clientX, e.clientY), wheelZoom(e));
+		else {
+			const dx = e.shiftKey ? e.deltaY : e.deltaX;
+			const dy = e.shiftKey ? e.deltaX : e.deltaY;
+			host.panBy(-dx, -dy);
+		}
+	};
+	let lastScale = 1;
+	const onGestureStart = (e) => {
+		e.preventDefault();
+		lastScale = e.scale ?? 1;
+	};
+	const onGestureChange = (e) => {
+		e.preventDefault();
+		if (touches().length > 0 || performance.now() - lastTouchAt < 500) return;
+		const g = e;
+		const scale = g.scale ?? 1;
+		if (zoomGestures && scale > 0) host.zoomAround(vpt(g.clientX, g.clientY), scale / lastScale);
+		lastScale = scale;
+	};
+	el.addEventListener("pointerdown", onDown);
+	el.addEventListener("pointermove", onHoverMove);
+	window.addEventListener("pointermove", onWindowMove);
+	window.addEventListener("pointerup", onUp);
+	window.addEventListener("pointercancel", onCancel);
+	el.addEventListener("wheel", onWheel, { passive: false });
+	const hasGestureEvents = "GestureEvent" in window;
+	if (hasGestureEvents) {
+		el.addEventListener("gesturestart", onGestureStart);
+		el.addEventListener("gesturechange", onGestureChange);
+		el.addEventListener("gestureend", onGestureStart);
+	}
+	return () => {
+		el.removeEventListener("pointerdown", onDown);
+		el.removeEventListener("pointermove", onHoverMove);
+		window.removeEventListener("pointermove", onWindowMove);
+		window.removeEventListener("pointerup", onUp);
+		window.removeEventListener("pointercancel", onCancel);
+		el.removeEventListener("wheel", onWheel);
+		if (hasGestureEvents) {
+			el.removeEventListener("gesturestart", onGestureStart);
+			el.removeEventListener("gesturechange", onGestureChange);
+			el.removeEventListener("gestureend", onGestureStart);
+		}
+		clearLongPress();
+		stopFrames();
+		end();
+	};
+}
+//#endregion
+//#region src/selection-handles.ts
+/** Bind one handle element. Returns the detach fn. */
+function attachSelectionHandle(el, options) {
+	let active = null;
+	const onMove = (e) => {
+		if (!active || e.pointerId !== active.pointerId) return;
+		active.session.move({
+			x: active.base.x + (e.clientX - active.baseClient.x),
+			y: active.base.y + (e.clientY - active.baseClient.y)
+		});
+	};
+	const onUp = (e) => {
+		if (!active || e.pointerId !== active.pointerId) return;
+		const s = active.session;
+		active = null;
+		s.end();
+	};
+	const onDown = (e) => {
+		if (active) return;
+		const armed = options.arm();
+		if (!armed) return;
+		e.preventDefault();
+		e.stopPropagation();
+		try {
+			el.setPointerCapture(e.pointerId);
+		} catch {}
+		active = {
+			session: armed.session,
+			base: armed.base,
+			baseClient: {
+				x: e.clientX,
+				y: e.clientY
+			},
+			pointerId: e.pointerId
+		};
+	};
+	el.addEventListener("pointerdown", onDown);
+	el.addEventListener("pointermove", onMove);
+	el.addEventListener("pointerup", onUp);
+	el.addEventListener("pointercancel", onUp);
+	return () => {
+		el.removeEventListener("pointerdown", onDown);
+		el.removeEventListener("pointermove", onMove);
+		el.removeEventListener("pointerup", onUp);
+		el.removeEventListener("pointercancel", onUp);
+		active = null;
+	};
+}
+//#endregion
+//#region src/stage-surface.ts
+/**
+* Stage surface binding — everything DOM about attaching one element to one
+* stage lens, shared by every framework adapter (React, Angular, …) so the
+* binding can never drift between them:
+*
+*   • ResizeObserver → `setViewport` (the shell only reports; placement is the
+*     stage plugin's job)
+*   • device-pixel-ratio observation → `setDevicePixelRatio` (dppx changes
+*     re-subscribe, since the media query's value itself moves)
+*   • pointer-sample normalization — the ONE place a PointerEvent becomes a
+*     page-resolved, source-stamped sample for the interaction hub
+*   • the gesture controller (wheel, Safari trackpad gestures, synthesized
+*     touch physics) from `./stage-gestures`
+*
+* The framework adapters keep only their reactive glue: refs/effects, page
+* surfaces, cursor-style subscription, overlay slots.
+*
+* Dependency note: like the gesture controller, this module speaks to the
+* stage and the hub through STRUCTURAL interfaces ({@link StageSurfaceHost},
+* {@link StageSurfaceHub}) — satisfied by `StageCapability` and
+* `InteractionCapability`, imported by neither. @embedpdf/web stays free of
+* plugin imports, per the layering law.
+*
+* Browser-only by nature (ResizeObserver, matchMedia): call from a mounted
+* effect / browser platform check, exactly like the gesture controller.
+*/
+/** Attach the full surface binding. Returns the detach fn. */
+function createStageSurface(el, stage, options = {}) {
+	const hub = options.hub ?? null;
+	const cleanups = [];
+	const setViewport = () => stage.setViewport({
+		width: el.clientWidth,
+		height: el.clientHeight
+	});
+	const ro = new ResizeObserver(setViewport);
+	ro.observe(el);
+	setViewport();
+	cleanups.push(() => ro.disconnect());
+	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();
+	cleanups.push(() => mq?.removeEventListener("change", reportDpr));
+	const sampleOf = (phase, e, clickCount = 1, gesture) => {
+		const r = el.getBoundingClientRect();
+		const viewport = {
+			x: e.clientX - r.left,
+			y: e.clientY - r.top
+		};
+		return {
+			phase,
+			viewport,
+			page: stage.pageAt(viewport) ?? void 0,
+			project: (pon) => stage.pointOnPage(pon, viewport),
+			modifiers: {
+				shift: e.shiftKey,
+				alt: e.altKey,
+				ctrl: e.ctrlKey,
+				meta: e.metaKey
+			},
+			clickCount,
+			pointerType: e.pointerType || "mouse",
+			...gesture ? { gesture } : {},
+			...options.source ? { source: options.source } : {}
+		};
+	};
+	const forward = (phase, e, clickCount = 1, gesture) => {
+		hub?.dispatch(sampleOf(phase, e, clickCount, gesture));
+	};
+	const sink = hub ? {
+		down: (e, clickCount) => forward("down", e, clickCount),
+		move: (e) => forward("move", e),
+		up: (e) => forward("up", e),
+		cancel: (e) => forward("cancel", e),
+		hover: (e) => forward("move", e),
+		longPress: (e) => forward("down", e, 2, "long-press"),
+		claimsPoint: (e) => !!hub.activeTool().touchDirect || hub.wouldClaimTouch(sampleOf("down", e))
+	} : null;
+	cleanups.push(createStageGestureController(el, stage, {
+		zoomGestures: options.zoomGestures,
+		wheelZoomFactor: options.wheelZoomFactor,
+		sink
+	}));
+	return () => {
+		for (const fn of cleanups) fn();
+	};
+}
+//#endregion
+exports.attachSelectionHandle = attachSelectionHandle;
+exports.bindPaintedImage = bindPaintedImage;
+exports.computeReleaseVelocity = computeReleaseVelocity;
 exports.copySelection = copySelection;
+exports.createStageGestureController = createStageGestureController;
+exports.createStageSurface = createStageSurface;
 exports.observeClientGeometry = observeClientGeometry;
 exports.pickFile = pickFile;
 exports.pickImageFile = pickImageFile;
@@ -244,6 +1084,9 @@ exports.projectAnchoredTarget = projectAnchoredTarget;
 exports.sanitizeExternalUri = sanitizeExternalUri;
 exports.saveFile = saveFile;
 exports.svgCursor = svgCursor;
+exports.vibrationFeedback = vibrationFeedback;
+exports.wheelZoomFactor = wheelZoomFactor;
 exports.wireSelectionClipboard = wireSelectionClipboard;
+exports.wkFeedback = wkFeedback;
 
 //# sourceMappingURL=index.cjs.map