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

package/dist/index.cjs

@@ -1,105 +1,256 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_contract = require("./contract-B3tBU_U9.cjs");
+const require_contract = require("./contract-yO6QKpba.cjs");
+const require_contract_host = require("./contract/host.cjs");
 let _embedpdf_core = require("@embedpdf/core");
-//#region src/capability.ts
+//#region src/model.ts
+/** A document starts on `pointer`; the controller then activates the `defaultTool` setting. */
+const initialInteractionState = () => ({
+	activeToolId: "pointer",
+	toolStack: [],
+	cursor: "default"
+});
+/** Activate a tool and forget every pushed one. */
+function activateTool(state, toolId) {
+	if (state.activeToolId === toolId && state.toolStack.length === 0) return state;
+	return {
+		...state,
+		activeToolId: toolId,
+		toolStack: []
+	};
+}
+/** Activate a tool for a moment, saving the active one for {@link popTool}. */
+function pushTool(state, toolId) {
+	return {
+		...state,
+		toolStack: [...state.toolStack, state.activeToolId],
+		activeToolId: toolId
+	};
+}
+/** Activate the tool saved last; an empty stack changes nothing. */
+function popTool(state) {
+	if (state.toolStack.length === 0) return state;
+	return {
+		...state,
+		toolStack: state.toolStack.slice(0, -1),
+		activeToolId: state.toolStack[state.toolStack.length - 1]
+	};
+}
+function setCursor(state, cursor) {
+	return state.cursor === cursor ? state : {
+		...state,
+		cursor
+	};
+}
+/**
+* The two built-in tools. Features add tools via `registerTool`. `enables`
+* is the composition seam:
+*   pointer → text selection + annotation editing + marquee selection
+*   pan     → scrolling (contributed by Stage) + annotation editing, no text select
+* Both carry `form-fill` and `link-nav`: filling forms and following links is
+* the resting state of a viewer (Acrobat's hand tool does both).
+*/
+const builtinTools = () => [{
+	id: "pointer",
+	cursor: "default",
+	enables: /* @__PURE__ */ new Set([
+		"text-select",
+		"annotation-edit",
+		"annotation-marquee",
+		"form-fill",
+		"link-nav"
+	])
+}, {
+	id: "pan",
+	cursor: "grab",
+	gapCursor: "grab",
+	enables: /* @__PURE__ */ new Set([
+		"scroll",
+		"annotation-edit",
+		"form-fill",
+		"link-nav"
+	])
+}];
+//#endregion
+//#region src/controller.ts
+/** A tool's own pointer methods take a press before every handler a plugin registers. */
+const OWN_POINTER_PRIORITY = 1e3;
+const NO_TAGS = /* @__PURE__ */ new Set();
 /**
-* The interaction hub. Tools + handlers + the captured-gesture owner + cursor
-* claims live in this closure (runtime registries, not serializable state); the
-* reducer state holds only the active tool id and the resolved cursor, so the UI
-* can react to them. The router (`dispatch`) is the heart: on down, the first
-* eligible handler (by priority) to return true OWNS the gesture; move/up route
-* to it; with no owner, move is hover (cursor feedback).
+* The interaction hub. Tools, handlers, the captured-gesture owner and cursor
+* claims are registries in this closure; the state holds only the active
+* tool, the tool stack and the resolved cursor, so UI can react. Registering
+* or removing a tool wakes readers with `ctx.notify()`.
 *
-* Cursor arbitration, top to bottom: the highest-priority CLAIM (hover feedback
-* — 'move' over an annotation, 'text' over text) → over a page, the tool's
-* declared cursor → over a gap, the tool's `gapCursor` (default the neutral
-* arrow). The winning KEYWORD (claim or base, never gap) is then restyled
-* through the armed tool's skin when it maps that keyword. One resolver, so an
-* image cursor can never shadow hover feedback or outlive the page under the
-* pointer.
+* Cursor arbitration, top to bottom: the highest-priority claim (hover
+* feedback) → over a page, the tool's declared cursor → over a gap, the
+* tool's `gapCursor`. The winning keyword is replaced through the active
+* tool's cursors (`setToolCursor`) when they name that keyword.
 */
-function createInteractionCapability(ctx, builtinTools) {
+function createInteractionController(ctx, builtinTools) {
+	const settings = ctx.settings();
 	const tools = /* @__PURE__ */ new Map();
-	for (const t of builtinTools) tools.set(t.id, t);
+	/** The handler each tool with its own pointer methods brings, registered beside the plugins' handlers. */
+	const ownHandlers = /* @__PURE__ */ new Map();
+	/** Bumped on every tool registry change: the input of the tool list. */
+	let toolsVersion = 0;
 	const handlers = [];
+	const handlerSources = /* @__PURE__ */ new Map();
 	const claims = /* @__PURE__ */ new Map();
-	const cursorSkins = /* @__PURE__ */ new Map();
-	const toolCbs = /* @__PURE__ */ new Set();
+	const toolCursors = /* @__PURE__ */ new Map();
 	let owner = null;
+	/** The gesture `owner` took, as its events report it. */
+	let gesture = null;
+	/** Whether the last dispatched sample hit a page: gaps fall back to `gapCursor`. */
 	let overPage = false;
+	const toolChanged = ctx.events.source();
+	const gestureStarted = ctx.events.source();
+	const gestureEnded = ctx.events.source();
+	const gestureCancelled = ctx.events.source();
+	const cursorChanged = ctx.events.source();
+	ctx.state.onChange(({ previous, next }) => {
+		if (previous.cursor !== next.cursor) cursorChanged.emit({ cursor: next.cursor });
+	});
+	const state = () => ctx.state.get();
 	const toolOf = (id) => tools.get(id) ?? {
 		id,
 		cursor: "default",
-		enables: /* @__PURE__ */ new Set()
+		enables: NO_TAGS
 	};
-	const active = () => toolOf(ctx.getState().activeToolId);
+	const active = () => toolOf(state().activeToolId);
+	const listTools = (0, _embedpdf_core.memo)(() => [toolsVersion], (_version) => [...tools.values()]);
 	const resolveCursor = () => {
 		let top = null;
-		for (const c of claims.values()) if (!top || c.priority > top.priority) top = c;
+		for (const claim of claims.values()) if (!top || claim.priority > top.priority) top = claim;
 		const tool = active();
-		const skin = cursorSkins.get(tool.id);
-		if (top) return skin?.[top.cursor] ?? top.cursor;
+		const cursors = toolCursors.get(tool.id);
+		if (top) return cursors?.[top.cursor] ?? top.cursor;
 		if (!overPage) return tool.gapCursor ?? "default";
-		return skin?.[tool.cursor] ?? tool.cursor;
+		return cursors?.[tool.cursor] ?? tool.cursor;
 	};
-	const syncCursor = () => {
-		const next = resolveCursor();
-		if (next !== ctx.getState().cursor) ctx.dispatch({
-			type: "SET_CURSOR",
-			cursor: next
-		});
+	const syncCursor = () => ctx.state.update(setCursor, resolveCursor());
+	const removeHandler = (handler) => {
+		const index = handlers.indexOf(handler);
+		if (index >= 0) handlers.splice(index, 1);
+		handlerSources.delete(handler);
+		if (owner === handler) {
+			owner = null;
+			gesture = null;
+		}
 	};
-	const handlerSources = /* @__PURE__ */ new Map();
+	const addHandler = (handler, source) => {
+		handlers.push(handler);
+		if (source !== void 0) handlerSources.set(handler, source);
+		return () => removeHandler(handler);
+	};
+	/** Take a tool out of the registry, with the handler its pointer methods brought. */
+	const removeTool = (tool) => {
+		tools.delete(tool.id);
+		const handler = ownHandlers.get(tool);
+		ownHandlers.delete(tool);
+		if (handler) removeHandler(handler);
+	};
+	/**
+	* Put a tool in the registry without waking readers, and return the stored
+	* tool (tags filled in). A taken id is refused unless `replace`.
+	*/
+	const addTool = (input, replace) => {
+		const taken = tools.get(input.id);
+		if (taken && !replace) throw new _embedpdf_core.PluginError("conflict", "interaction", `tool '${input.id}' is already registered; pass { replace: true } to replace it`);
+		if (taken) removeTool(taken);
+		const tool = input.enables ? input : {
+			...input,
+			enables: NO_TAGS
+		};
+		tools.set(tool.id, tool);
+		const handler = ownPointerHandler(tool);
+		if (handler) {
+			ownHandlers.set(tool, handler);
+			addHandler(handler);
+		}
+		return tool;
+	};
+	const toolsChanged = () => {
+		toolsVersion += 1;
+		ctx.notify();
+	};
+	/** The registration's remover: it removes this registration only, never a later one with its id. */
+	const removerOf = (tool) => () => {
+		if (tools.get(tool.id) !== tool) return;
+		removeTool(tool);
+		toolCursors.delete(tool.id);
+		toolsChanged();
+	};
+	for (const tool of builtinTools) addTool(tool, true);
+	let removeSettingTools = settings.get().tools.map((tool) => removerOf(addTool(tool, true)));
+	settings.api.onSettingsChanged(({ changed }) => {
+		if (!changed.includes("tools")) return;
+		for (const remove of removeSettingTools) remove();
+		removeSettingTools = settings.get().tools.map((tool) => removerOf(addTool(tool, true)));
+		toolsChanged();
+	});
+	ctx.state.update(activateTool, settings.get().defaultTool);
+	syncCursor();
+	/** Lens scoping: a handler registered with a `source` only sees samples stamped with it. */
 	const eligible = (source) => {
 		const tool = active();
-		return handlers.filter((h) => {
-			const hs = handlerSources.get(h);
-			return hs === void 0 || source === void 0 || hs === source;
-		}).filter((h) => h.enabledFor(tool)).sort((a, b) => b.priority - a.priority);
+		return handlers.filter((handler) => {
+			const handlerSource = handlerSources.get(handler);
+			return handlerSource === void 0 || source === void 0 || handlerSource === source;
+		}).filter((handler) => handler.enabledFor(tool)).sort((left, right) => right.priority - left.priority);
 	};
-	return {
-		activeTool: active,
-		activeToolId: () => ctx.getState().activeToolId,
-		cursor: () => ctx.getState().cursor,
-		tools: () => [...tools.values()],
-		activateTool: (id) => {
-			if (!tools.has(id)) throw new Error(`[interaction] unknown tool '${id}'`);
-			owner = null;
-			claims.clear();
-			ctx.dispatch({
-				type: "SET_TOOL",
-				toolId: id
-			});
-			syncCursor();
-			toolCbs.forEach((cb) => cb());
-		},
-		onToolChange: (cb) => {
-			toolCbs.add(cb);
-			return () => toolCbs.delete(cb);
+	/**
+	* Activate a tool through `transition`. Every activation is announced,
+	* including activating the active tool again.
+	*/
+	function arm(id, transition) {
+		if (!tools.has(id)) throw new _embedpdf_core.PluginError("not-found", "interaction", `unknown tool '${id}'`);
+		const previousToolId = state().activeToolId;
+		owner = null;
+		gesture = null;
+		claims.clear();
+		ctx.state.update(transition);
+		syncCursor();
+		toolChanged.emit({
+			toolId: id,
+			previousToolId
+		});
+	}
+	return { api: {
+		...settings.api,
+		getActiveTool: active,
+		getActiveToolId: () => state().activeToolId,
+		getDefaultToolId: () => settings.get().defaultTool,
+		listTools,
+		getTool: (id) => tools.get(id) ?? null,
+		hasTool: (id) => tools.has(id),
+		activateTool: (id) => arm(id, (current) => activateTool(current, id)),
+		activateDefaultTool: () => {
+			const id = settings.get().defaultTool;
+			arm(id, (current) => activateTool(current, id));
 		},
-		registerTool: (tool) => {
-			tools.set(tool.id, tool);
-			return () => {
-				tools.delete(tool.id);
-				cursorSkins.delete(tool.id);
-			};
+		pushTool: (id) => arm(id, (current) => pushTool(current, id)),
+		popTool: () => {
+			const stack = state().toolStack;
+			if (stack.length === 0) return;
+			arm(stack[stack.length - 1], popTool);
 		},
-		setToolCursor: (id, skin) => {
-			if (skin === null) cursorSkins.delete(id);
-			else cursorSkins.set(id, skin);
+		setToolCursor: (id, cursors) => {
+			if (cursors === null) toolCursors.delete(id);
+			else toolCursors.set(id, cursors);
 			syncCursor();
 		},
-		registerHandler: (handler, options) => {
-			handlers.push(handler);
-			if (options?.source !== void 0) handlerSources.set(handler, options.source);
-			return () => {
-				const i = handlers.indexOf(handler);
-				if (i >= 0) handlers.splice(i, 1);
-				handlerSources.delete(handler);
-				if (owner === handler) owner = null;
-			};
+		registerTool: (tool, options) => {
+			const stored = addTool(tool, options?.replace ?? false);
+			toolsChanged();
+			return removerOf(stored);
 		},
-		setCursor: (token, cursor, priority = 0) => {
+		onToolChanged: toolChanged.on,
+		onGestureStarted: gestureStarted.on,
+		onGestureEnded: gestureEnded.on,
+		onGestureCancelled: gestureCancelled.on,
+		activeToolEnables: (behavior) => active().enables.has(behavior),
+		registerHandler: (handler, options) => addHandler(handler, options?.source),
+		claimCursor: (token, cursor, priority = 0) => {
 			if (cursor === null) claims.delete(token);
 			else claims.set(token, {
 				cursor,
@@ -107,11 +258,14 @@ function createInteractionCapability(ctx, builtinTools) {
 			});
 			syncCursor();
 		},
+		getCursor: () => state().cursor,
+		hasCursorClaim: () => claims.size > 0,
+		onCursorChanged: cursorChanged.on,
 		wouldClaimTouch: (sample) => {
-			for (const h of eligible(sample.source)) if (h.claimsTouch?.(sample)) return true;
+			for (const handler of eligible(sample.source)) if (handler.claimsTouch?.(sample)) return true;
 			return false;
 		},
-		dispatch: (sample) => {
+		dispatchPointer: (sample) => {
 			const nowOverPage = sample.page != null;
 			if (nowOverPage !== overPage) {
 				overPage = nowOverPage;
@@ -119,108 +273,140 @@ function createInteractionCapability(ctx, builtinTools) {
 			}
 			if (sample.phase === "down") {
 				owner = null;
-				for (const h of eligible(sample.source)) if (h.onDown(sample)) {
-					owner = h;
+				gesture = null;
+				for (const handler of eligible(sample.source)) if (handler.onDown(sample)) {
+					owner = handler;
+					gesture = {
+						toolId: state().activeToolId,
+						page: sample.page?.ref ?? null,
+						pointerType: sample.pointerType ?? "mouse"
+					};
+					gestureStarted.emit(gesture);
 					break;
 				}
 			} else if (sample.phase === "move") if (owner) owner.onMove?.(sample);
-			else for (const h of eligible(sample.source)) h.onHover?.(sample);
-			else if (sample.phase === "cancel") {
-				const o = owner;
-				owner = null;
-				if (o) (o.onCancel ?? o.onUp)?.call(o, sample);
-			} else {
-				owner?.onUp?.(sample);
+			else for (const handler of eligible(sample.source)) handler.onHover?.(sample);
+			else {
+				const captured = owner;
+				const taken = gesture;
 				owner = null;
+				gesture = null;
+				if (!captured || !taken) return;
+				if (sample.phase === "cancel") {
+					(captured.onCancel ?? captured.onUp)?.call(captured, sample);
+					gestureCancelled.emit(taken);
+				} else {
+					captured.onUp?.(sample);
+					gestureEnded.emit(taken);
+				}
 			}
 		}
+	} };
+}
+/**
+* The handler a tool's own pointer methods bring, or null for a tool without
+* them: it is live only while that tool is active, and turns samples into
+* {@link ToolPointerEvent}s in page coordinates. A gesture keeps the page it
+* started on, so a drag that leaves the page goes on in that page's
+* coordinates.
+*/
+function ownPointerHandler(tool) {
+	if (!tool.onPointerDown && !tool.onHover) return null;
+	let home = null;
+	let last = null;
+	const eventOf = (page, point, sample) => ({
+		page,
+		point,
+		modifiers: sample.modifiers,
+		pointerType: sample.pointerType ?? "mouse"
+	});
+	/** The sample on the gesture's page, or the last event when the source can't project it there. */
+	const follow = (sample) => {
+		if (!home) return null;
+		const point = require_contract_host.samplePointOn(sample, home);
+		if (point) last = eventOf(home, point, sample);
+		return last;
+	};
+	const end = (sample) => {
+		const event = follow(sample);
+		home = null;
+		last = null;
+		if (event) tool.onPointerUp?.(event);
+	};
+	return {
+		id: `tool:${tool.id}`,
+		priority: OWN_POINTER_PRIORITY,
+		enabledFor: (active) => active === tool,
+		onDown: (sample) => {
+			if (!sample.page || !tool.onPointerDown) return false;
+			const event = eventOf(sample.page.ref, sample.page.point, sample);
+			if (tool.onPointerDown(event) !== true) return false;
+			home = sample.page.ref;
+			last = event;
+			return true;
+		},
+		onMove: (sample) => {
+			const event = follow(sample);
+			if (event) tool.onPointerMove?.(event);
+		},
+		onUp: end,
+		onCancel: end,
+		onHover: (sample) => {
+			if (sample.page) tool.onHover?.(eventOf(sample.page.ref, sample.page.point, sample));
+		}
 	};
 }
 //#endregion
-//#region src/reducer.ts
-const initialInteractionState = (config) => ({
-	activeToolId: config.defaultTool ?? "pointer",
-	cursor: "default"
-});
-const interactionReducer = (state, action) => {
-	switch (action.type) {
-		case "SET_TOOL": return state.activeToolId === action.toolId ? state : {
-			...state,
-			activeToolId: action.toolId
-		};
-		case "SET_CURSOR": return state.cursor === action.cursor ? state : {
-			...state,
-			cursor: action.cursor
-		};
-		default: return state;
-	}
-};
-//#endregion
 //#region src/interaction.plugin.ts
 /**
-* The two built-in tools. Features ADD tools via `registerTool` (a draw tool, a
-* redact tool…). `enables` is the composition seam:
-*   pointer → text selection + annotation editing + annotation marquee selection
-*   pan     → scrolling (contributed by Stage) + annotation editing, NO text select
-*
-* Both carry `form-fill`: filling a form is the RESTING state of a viewer
-* (Acrobat's hand tool fills forms too), so widgets are fill-controls under the
-* default tools and only become geometry-editable under a form-design tool.
-* Both carry `link-nav` for the same reason: links navigate under the default
-* tools (Acrobat behaviour) and only become geometry-editable under the link
-* tool. Tags are opaque to the hub — without the form/link plugins they're inert.
+* The interaction hub: document-scoped, depends on nothing. Feature plugins
+* `require` this token; the Stage `optional`-ly contributes a scroll handler.
+* `config` is the settings the app registers, over {@link INTERACTION_DEFAULTS}.
 */
-const builtinTools = () => [{
-	id: "pointer",
-	cursor: "default",
-	enables: /* @__PURE__ */ new Set([
-		"text-select",
-		"annotation-edit",
-		"annotation-marquee",
-		"form-fill",
-		"link-nav"
-	])
-}, {
-	id: "pan",
-	cursor: "grab",
-	gapCursor: "grab",
-	enables: /* @__PURE__ */ new Set([
-		"scroll",
-		"annotation-edit",
-		"form-fill",
-		"link-nav"
-	])
-}];
-/**
-* The interaction hub plugin — document-scoped, depends on nothing. Every feature
-* plugin (selection, annotation, forms, redaction) `requires` this token; Stage
-* `optional`-ly contributes a scroll handler. Works with `<Stage>` or a standalone
-* `<PageView>` — it only routes page-space pointer samples.
-*/
-const interactionPlugin = (config = {}) => (0, _embedpdf_core.definePlugin)({
+const interactionPlugin = (config) => (0, _embedpdf_core.definePlugin)({
 	id: "interaction",
-	token: require_contract.InteractionToken,
+	token: require_contract_host.InteractionToken,
 	scope: "document",
-	initialState: () => initialInteractionState(config),
-	reduce: interactionReducer,
-	capability: (ctx) => createInteractionCapability(ctx, builtinTools())
+	state: initialInteractionState,
+	settings: {
+		defaults: require_contract.INTERACTION_DEFAULTS,
+		registered: config
+	},
+	create: (ctx) => createInteractionController(ctx, builtinTools())
+});
+//#endregion
+//#region src/state.ts
+/**
+* The tools page's State table as code: what `useInteractionState()` returns,
+* and the same fields in every other framework. With no document there is no
+* active tool and no tool to switch to.
+*/
+const interactionState = (0, _embedpdf_core.defineState)(require_contract.InteractionToken, {
+	read: (interaction) => ({
+		activeToolId: interaction.getActiveToolId(),
+		tools: interaction.listTools()
+	}),
+	empty: {
+		activeToolId: null,
+		tools: []
+	}
 });
 //#endregion
 //#region src/feedback.ts
 /**
-* Platform feedback (haptics) — the OUTPUT half of the interaction seam:
+* Platform feedback (haptics) — the output half of the interaction seam:
 * pointers come in, feedback goes back out to the device.
 *
-* ONE workspace-scoped provider, MANY consumers: any plugin lists
+* One workspace-scoped provider, many consumers: any plugin lists
 * {@link FeedbackToken} as an optional dependency and calls the capability at
-* its semantic moments (the selection handler on a long-press word-select; an
-* annotation pickup or a snap later). The plugin itself stays DOM-free — the
-* PROVIDER is injected from outside (`@embedpdf/web` ships `vibrationFeedback`
-* and a WKWebView bridge; native shells bring their own), exactly like the
-* stage's Scheduler seam: host dependencies enter through explicit injection,
-* never a hidden global.
+* its semantic moments (the selection handler on a long-press word-select).
+* The plugin itself stays DOM-free — the provider is injected from outside
+* (`@embedpdf/web` ships `vibrationFeedback` and a WKWebView bridge; native
+* shells bring their own), as the host's clock enters the kernel
+* (`createKernel({ clock })`): host dependencies enter through explicit
+* injection, never a hidden global.
 *
-* The vocabulary is deliberately the PLATFORM's haptic taxonomy — iOS's three
+* The vocabulary is deliberately the platform's haptic taxonomy — iOS's three
 * generator families, which Android mirrors in `HapticFeedbackConstants` and
 * the web approximates with vibration patterns — not app vocabulary. A verb
 * belongs here only if a provider would map it to a physically different
@@ -234,26 +420,21 @@ const NOOP = {
 	notify() {}
 };
 /**
-* Register the workspace's ONE feedback provider. Stateless: the capability IS
-* the provider (or the no-op).
+* Register the workspace's one feedback provider. Stateless: the capability
+* is the provider (or the no-op).
 */
 const feedbackPlugin = (options = {}) => (0, _embedpdf_core.definePlugin)({
 	id: "feedback",
 	scope: "workspace",
 	token: require_contract.FeedbackToken,
-	initialState: () => ({}),
-	reduce: (state) => state,
-	capability: () => options.provider ?? NOOP
+	create: () => ({ api: options.provider ?? NOOP })
 });
 //#endregion
 exports.FeedbackToken = require_contract.FeedbackToken;
+exports.INTERACTION_DEFAULTS = require_contract.INTERACTION_DEFAULTS;
 exports.InteractionToken = require_contract.InteractionToken;
-exports.builtinTools = builtinTools;
-exports.createInteractionCapability = createInteractionCapability;
 exports.feedbackPlugin = feedbackPlugin;
-exports.initialInteractionState = initialInteractionState;
 exports.interactionPlugin = interactionPlugin;
-exports.interactionReducer = interactionReducer;
-exports.samplePointOn = require_contract.samplePointOn;
+exports.interactionState = interactionState;
 
 //# sourceMappingURL=index.cjs.map