react-auto-tracking 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hank Lin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# react-auto-tracking
+
+Global user interaction tracking for React apps (16–19). Captures clicks, form events, and ambient events via DOM event delegation with automatic React fiber introspection.
+
+## Features
+
+- **Zero-config** — works with any React 16–19 app, no provider or HOC needed
+- **Fiber introspection** — automatically resolves the nearest React component name and props
+- **Smart filtering** — only tracks interactive elements (buttons, links, ARIA roles, elements with React handlers)
+- **Three event categories** — Pointer (click), Form (input/change/focus/blur), Ambient (scroll/keydown/keyup)
+- **Listener options** — debounce, throttle, once, CSS selector filtering
+- **Tree-shakeable** — ESM + CJS, zero runtime dependencies
+
+## Install
+
+```bash
+npm install react-auto-tracking
+```
+
+## Quick Start
+
+```ts
+import { init } from 'react-auto-tracking'
+
+const tracker = init()
+
+// Track all clicks on interactive elements
+const unsubscribe = tracker.on('click', (event) => {
+  console.log(event.targetElement.tagName)   // 'BUTTON'
+  console.log(event.fiber?.componentName)    // 'SubmitButton'
+  console.log(event.fiber?.props)            // { variant: 'primary', onClick: [Function] }
+})
+
+// Clean up
+unsubscribe()     // remove this listener
+tracker.destroy() // remove all listeners and DOM bindings
+```
+
+## API
+
+### `init(config?): Tracker`
+
+Creates a tracker instance.
+
+```ts
+const tracker = init({
+  enabled: true,           // toggle tracking on/off
+  ignoreSelectors: ['.no-track', '[data-private]'],
+  debug: false,            // log events to console.debug
+})
+```
+
+### `tracker.on(eventType, callback, options?): unsubscribe`
+
+Register a listener for a DOM event type. Returns an unsubscribe function.
+
+```ts
+// Basic
+tracker.on('click', (event) => { ... })
+
+// With options
+tracker.on('scroll', handler, { throttle: 200 })
+tracker.on('input', handler, { debounce: 300 })
+tracker.on('click', handler, { once: true })
+tracker.on('click', handler, { selector: 'nav a' })
+```
+
+Multiple listeners can be registered for the same event type — each fires independently, similar to `addEventListener`.
+
+### `tracker.getLastEvent(): TrackEvent | null`
+
+Returns the most recent tracked event, or `null` if none. Useful with `visibilitychange` or `beforeunload` to capture the last interaction before the user leaves:
+
+```ts
+document.addEventListener('visibilitychange', () => {
+  if (document.visibilityState === 'hidden') {
+    const last = tracker.getLastEvent()
+    if (last) {
+      navigator.sendBeacon('/analytics', JSON.stringify({
+        component: last.fiber?.componentName,
+        element: last.targetElement.tagName,
+      }))
+    }
+  }
+})
+```
+
+### `tracker.destroy()`
+
+Removes all listeners and DOM event bindings. The tracker instance is inert after this call.
+
+## TrackEvent
+
+Each callback receives a `TrackEvent`:
+
+```ts
+interface TrackEvent {
+  nativeEvent: Event     // original DOM event
+  targetElement: Element // resolved trackable element (may differ from nativeEvent.target)
+  fiber: FiberInfo | null
+}
+
+interface FiberInfo {
+  componentName: string | null              // nearest React component
+  props: Readonly<Record<string, unknown>>  // component props (original types, not stringified)
+}
+```
+
+The library intentionally keeps `TrackEvent` minimal — use `nativeEvent` and `targetElement` to extract any DOM information you need, and `fiber.props` to access rich, typed data from React components (avoiding the `[object Object]` problem of HTML `data-*` attributes).
+
+## Event Categories
+
+| Category | Events | Behavior |
+|----------|--------|----------|
+| **Pointer** | `click`, `touchstart`, `touchend` | Walks DOM ancestors to find interactive element (button, link, ARIA role, React handler) |
+| **Form** | `input`, `change`, `focus`, `blur`, `submit` | Tracks target directly, skips disabled elements |
+| **Ambient** | `scroll`, `keydown`, `keyup`, `copy`, `paste`, `resize`, `popstate`, `hashchange` | Tracks target directly, does not skip disabled |
+
+## How It Works
+
+1. **DOM delegation** — attaches a single capture-phase listener per event type on `document`
+2. **Filtering** — determines if the target (or ancestor) is interactive based on HTML semantics, ARIA roles, or React fiber props
+3. **Fiber resolution** — finds the nearest React component and extracts its name and props
+4. **Dispatch** — invokes all registered callbacks with the `TrackEvent`
+
+Capture phase (`addEventListener(..., true)`) ensures events are caught even if `stopPropagation()` is called downstream.
+
+## Development
+
+```bash
+pnpm install
+pnpm test            # run tests
+pnpm test:watch      # watch mode
+pnpm test:coverage   # coverage report (80% threshold)
+pnpm lint            # oxlint
+pnpm format          # oxfmt (write)
+pnpm format:check    # oxfmt (check only)
+pnpm typecheck       # tsc --noEmit
+pnpm build           # ESM + CJS + .d.ts via tsdown
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,415 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+//#region src/filter/event-categories.ts
+const EventCategory = {
+	Pointer: "pointer",
+	Form: "form",
+	Ambient: "ambient"
+};
+const EVENT_HANDLER_MAP = {
+	click: [
+		"onClick",
+		"onMouseDown",
+		"onMouseUp",
+		"onPointerDown",
+		"onPointerUp"
+	],
+	touchstart: ["onTouchStart"],
+	touchend: ["onTouchEnd"],
+	input: ["onChange", "onInput"],
+	change: ["onChange"],
+	focus: ["onFocus"],
+	blur: ["onBlur"],
+	submit: ["onSubmit"],
+	scroll: ["onScroll"],
+	keydown: ["onKeyDown"],
+	keyup: ["onKeyUp"],
+	copy: ["onCopy"],
+	paste: ["onPaste"]
+};
+const CATEGORY_MAP = {
+	click: EventCategory.Pointer,
+	touchstart: EventCategory.Pointer,
+	touchend: EventCategory.Pointer,
+	input: EventCategory.Form,
+	change: EventCategory.Form,
+	focus: EventCategory.Form,
+	blur: EventCategory.Form,
+	submit: EventCategory.Form,
+	scroll: EventCategory.Ambient,
+	keydown: EventCategory.Ambient,
+	keyup: EventCategory.Ambient,
+	copy: EventCategory.Ambient,
+	paste: EventCategory.Ambient,
+	resize: EventCategory.Ambient,
+	popstate: EventCategory.Ambient,
+	hashchange: EventCategory.Ambient
+};
+function getEventCategory(eventType) {
+	return CATEGORY_MAP[eventType] ?? EventCategory.Ambient;
+}
+function getHandlersForEvent(eventType) {
+	return EVENT_HANDLER_MAP[eventType] ?? [];
+}
+
+//#endregion
+//#region src/extract/fiber.ts
+const FIBER_PREFIXES = ["__reactFiber$", "__reactInternalInstance$"];
+const MAX_PARENT_DEPTH = 10;
+let cachedKey = null;
+function resolveFiber(element) {
+	let current = element;
+	let depth = 0;
+	while (current !== null && depth <= MAX_PARENT_DEPTH) {
+		const fiber = getFiberFromElement(current);
+		if (fiber !== null) return fiber;
+		current = current.parentElement;
+		depth++;
+	}
+	return null;
+}
+function getFiberFromElement(element) {
+	if (cachedKey !== null) {
+		const fiber = element[cachedKey];
+		if (fiber != null) return fiber;
+		return null;
+	}
+	for (const key of Object.keys(element)) for (const prefix of FIBER_PREFIXES) if (key.startsWith(prefix)) {
+		cachedKey = key;
+		return element[key];
+	}
+	return null;
+}
+const MAX_STACK_DEPTH = 50;
+function extractFiberInfo(rawFiber) {
+	if (rawFiber === null) return null;
+	const fiber = rawFiber;
+	return {
+		componentName: findNearestComponentName(fiber),
+		props: fiber.memoizedProps ?? {}
+	};
+}
+function findNearestComponentName(fiber) {
+	let current = fiber.return;
+	let depth = 0;
+	while (current !== null && depth < MAX_STACK_DEPTH) {
+		const name = getComponentName(current);
+		if (name !== null) return name;
+		current = current.return;
+		depth++;
+	}
+	return null;
+}
+function getComponentName(fiber) {
+	const type = fiber.type;
+	if (typeof type === "string") return null;
+	if (typeof type === "function") return type.displayName ?? type.name ?? null;
+	return null;
+}
+
+//#endregion
+//#region src/utils/safe-matches.ts
+function safeMatches(element, selector) {
+	try {
+		return element.matches(selector);
+	} catch {
+		return false;
+	}
+}
+
+//#endregion
+//#region src/filter/filter-engine.ts
+const INTERACTIVE_TAGS = new Set([
+	"BUTTON",
+	"A",
+	"INPUT",
+	"SELECT",
+	"TEXTAREA",
+	"SUMMARY",
+	"DETAILS"
+]);
+const INTERACTIVE_ROLES = new Set([
+	"button",
+	"link",
+	"menuitem",
+	"tab",
+	"checkbox",
+	"radio",
+	"combobox",
+	"listbox",
+	"option",
+	"switch",
+	"slider",
+	"spinbutton",
+	"menuitemcheckbox",
+	"menuitemradio",
+	"treeitem",
+	"gridcell",
+	"textbox",
+	"searchbox"
+]);
+const MAX_ANCESTOR_DEPTH = 10;
+function findTrackableElement(params) {
+	const { target, ignoreSelectors, eventType } = params;
+	switch (getEventCategory(eventType)) {
+		case EventCategory.Pointer: return findPointerTarget(target, ignoreSelectors, eventType);
+		case EventCategory.Form: return findFormTarget(target, ignoreSelectors);
+		case EventCategory.Ambient: return findAmbientTarget(target, ignoreSelectors);
+	}
+}
+function findPointerTarget(target, ignoreSelectors, eventType) {
+	let current = target;
+	let depth = 0;
+	while (current !== null && depth <= MAX_ANCESTOR_DEPTH) {
+		if (isIgnored(current, ignoreSelectors)) return null;
+		if (isDisabled(current)) return null;
+		const rawFiber = findInteractiveFiber(current, eventType);
+		if (rawFiber !== void 0) return {
+			element: current,
+			fiber: extractFiberInfo(rawFiber)
+		};
+		current = current.parentElement;
+		depth++;
+	}
+	return null;
+}
+function findFormTarget(target, ignoreSelectors) {
+	if (isIgnored(target, ignoreSelectors)) return null;
+	if (isDisabled(target)) return null;
+	return {
+		element: target,
+		fiber: extractFiberInfo(resolveFiber(target))
+	};
+}
+function findAmbientTarget(target, ignoreSelectors) {
+	if (isIgnored(target, ignoreSelectors)) return null;
+	return {
+		element: target,
+		fiber: extractFiberInfo(resolveFiber(target))
+	};
+}
+/**
+* Returns the raw fiber if the element is interactive, or undefined if not.
+* null means "interactive but no fiber found" (semantic tag / ARIA role).
+*/
+function findInteractiveFiber(el, eventType) {
+	if (INTERACTIVE_TAGS.has(el.tagName)) return resolveFiber(el);
+	const role = el.getAttribute("role");
+	if (role !== null && INTERACTIVE_ROLES.has(role)) return resolveFiber(el);
+	const handlers = getHandlersForEvent(eventType);
+	if (handlers.length > 0) {
+		const fiber = resolveFiber(el);
+		if (fiber !== null) {
+			const props = fiber.memoizedProps;
+			if (props !== null && props !== void 0) {
+				for (const handler of handlers) if (typeof props[handler] === "function") return fiber;
+			}
+		}
+	}
+}
+function isIgnored(element, ignoreSelectors) {
+	return ignoreSelectors.some((selector) => safeMatches(element, selector));
+}
+function isDisabled(el) {
+	return el.hasAttribute("disabled") || el.getAttribute("aria-disabled") === "true";
+}
+
+//#endregion
+//#region src/utils/debounce.ts
+function debounce(fn, ms) {
+	let timeoutId = null;
+	const debounced = (...args) => {
+		if (timeoutId !== null) clearTimeout(timeoutId);
+		timeoutId = setTimeout(() => {
+			timeoutId = null;
+			fn(...args);
+		}, ms);
+	};
+	debounced.cancel = () => {
+		if (timeoutId !== null) {
+			clearTimeout(timeoutId);
+			timeoutId = null;
+		}
+	};
+	return debounced;
+}
+
+//#endregion
+//#region src/utils/throttle.ts
+function throttle(fn, ms) {
+	let lastCallTime = 0;
+	let timeoutId = null;
+	let lastArgs = null;
+	const throttled = (...args) => {
+		const now = Date.now();
+		const elapsed = now - lastCallTime;
+		if (elapsed >= ms) {
+			lastCallTime = now;
+			fn(...args);
+		} else {
+			lastArgs = args;
+			if (timeoutId === null) timeoutId = setTimeout(() => {
+				timeoutId = null;
+				lastCallTime = Date.now();
+				if (lastArgs !== null) {
+					fn(...lastArgs);
+					lastArgs = null;
+				}
+			}, ms - elapsed);
+		}
+	};
+	throttled.cancel = () => {
+		if (timeoutId !== null) {
+			clearTimeout(timeoutId);
+			timeoutId = null;
+		}
+		lastArgs = null;
+	};
+	return throttled;
+}
+
+//#endregion
+//#region src/core/registry.ts
+function createRegistry() {
+	let entries = [];
+	function createEntry(eventType, callback, options) {
+		const wrappedCallback = wrapCallback(callback, options);
+		const entry = {
+			eventType,
+			wrappedCallback,
+			options,
+			unsubscribe: () => {
+				wrappedCallback.cancel?.();
+				entries = entries.filter((e) => e !== entry);
+			}
+		};
+		return entry;
+	}
+	return {
+		add(eventType, callback, options) {
+			const entry = createEntry(eventType, callback, options);
+			entries = [...entries, entry];
+			return entry.unsubscribe;
+		},
+		invoke(event) {
+			for (const entry of entries) {
+				if (entry.eventType !== event.nativeEvent.type) continue;
+				if (entry.options.selector != null) {
+					if (!safeMatches(event.targetElement, entry.options.selector)) continue;
+				}
+				entry.wrappedCallback(event);
+				if (entry.options.once === true) entry.unsubscribe();
+			}
+		},
+		getEventTypes() {
+			return new Set(entries.map((e) => e.eventType));
+		},
+		clear() {
+			for (const entry of entries) entry.wrappedCallback.cancel?.();
+			entries = [];
+		}
+	};
+}
+function wrapCallback(callback, options) {
+	if (options.debounce != null) return debounce(callback, options.debounce);
+	if (options.throttle != null) return throttle(callback, options.throttle);
+	return callback;
+}
+
+//#endregion
+//#region src/core/pipeline.ts
+function createPipeline(config) {
+	const registry = createRegistry();
+	let lastEvent = null;
+	return {
+		handleEvent(domEvent) {
+			const target = domEvent.target;
+			if (!(target instanceof Element)) return;
+			const result = findTrackableElement({
+				target,
+				ignoreSelectors: config.ignoreSelectors,
+				eventType: domEvent.type
+			});
+			if (result === null) return;
+			const trackEvent = {
+				nativeEvent: domEvent,
+				targetElement: result.element,
+				fiber: result.fiber
+			};
+			registry.invoke(trackEvent);
+			lastEvent = trackEvent;
+		},
+		getLastEvent() {
+			return lastEvent;
+		},
+		addListener(eventType, callback, options) {
+			return registry.add(eventType, callback, options);
+		},
+		getEventTypes() {
+			return registry.getEventTypes();
+		},
+		clear() {
+			registry.clear();
+		}
+	};
+}
+
+//#endregion
+//#region src/core/tracker.ts
+function createTracker(config) {
+	const enabled = config?.enabled ?? true;
+	const ignoreSelectors = config?.ignoreSelectors ?? [];
+	const debug = config?.debug ?? false;
+	if (!enabled) return {
+		on: () => () => {},
+		getLastEvent: () => null,
+		destroy: () => {}
+	};
+	const pipeline = createPipeline({ ignoreSelectors });
+	const domListeners = /* @__PURE__ */ new Map();
+	let destroyed = false;
+	function ensureDomListener(eventType) {
+		if (domListeners.has(eventType)) return;
+		const handler = (event) => {
+			pipeline.handleEvent(event);
+			if (debug) {
+				const lastEvent = pipeline.getLastEvent();
+				if (lastEvent?.nativeEvent === event) console.debug("[react-auto-tracking]", lastEvent);
+			}
+		};
+		document.addEventListener(eventType, handler, true);
+		domListeners.set(eventType, handler);
+	}
+	function removeDomListener(eventType) {
+		const handler = domListeners.get(eventType);
+		if (handler === void 0) return;
+		if (!pipeline.getEventTypes().has(eventType)) {
+			document.removeEventListener(eventType, handler, true);
+			domListeners.delete(eventType);
+		}
+	}
+	return {
+		on(eventType, callback, options) {
+			if (destroyed) return () => {};
+			ensureDomListener(eventType);
+			const unsub = pipeline.addListener(eventType, callback, options ?? {});
+			return () => {
+				unsub();
+				removeDomListener(eventType);
+			};
+		},
+		getLastEvent() {
+			return pipeline.getLastEvent();
+		},
+		destroy() {
+			if (destroyed) return;
+			destroyed = true;
+			pipeline.clear();
+			for (const [eventType, handler] of domListeners) document.removeEventListener(eventType, handler, true);
+			domListeners.clear();
+		}
+	};
+}
+
+//#endregion
+exports.init = createTracker;

package/dist/index.d.cts

@@ -0,0 +1,33 @@
+//#region src/types.d.ts
+interface TrackerConfig {
+  readonly enabled?: boolean;
+  readonly ignoreSelectors?: readonly string[];
+  readonly debug?: boolean;
+}
+interface Tracker {
+  on(eventType: string, callback: TrackCallback, options?: ListenerOptions): () => void;
+  getLastEvent(): TrackEvent | null;
+  destroy(): void;
+}
+interface ListenerOptions {
+  readonly debounce?: number;
+  readonly throttle?: number;
+  readonly once?: boolean;
+  readonly selector?: string;
+}
+interface TrackEvent {
+  readonly nativeEvent: Event;
+  readonly targetElement: Element;
+  readonly fiber: FiberInfo | null;
+}
+interface FiberInfo {
+  readonly componentName: string | null;
+  readonly props: Readonly<Record<string, unknown>>;
+}
+type TrackCallback = (event: TrackEvent) => void;
+//#endregion
+//#region src/core/tracker.d.ts
+declare function createTracker(config?: TrackerConfig): Tracker;
+//#endregion
+export { type FiberInfo, type ListenerOptions, type TrackCallback, type TrackEvent, type Tracker, type TrackerConfig, createTracker as init };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/types.ts","../src/core/tracker.ts"],"mappings":";UAEiB,aAAA;EAAA,SACN,OAAA;EAAA,SACA,eAAA;EAAA,SACA,KAAA;AAAA;AAAA,UAGM,OAAA;EACf,EAAA,CAAG,SAAA,UAAmB,QAAA,EAAU,aAAA,EAAe,OAAA,GAAU,eAAA;EACzD,YAAA,IAAgB,UAAA;EAChB,OAAA;AAAA;AAAA,UAGe,eAAA;EAAA,SACN,QAAA;EAAA,SACA,QAAA;EAAA,SACA,IAAA;EAAA,SACA,QAAA;AAAA;AAAA,UAGM,UAAA;EAAA,SACN,WAAA,EAAa,KAAA;EAAA,SACb,aAAA,EAAe,OAAA;EAAA,SACf,KAAA,EAAO,SAAA;AAAA;AAAA,UAGD,SAAA;EAAA,SACN,aAAA;EAAA,SACA,KAAA,EAAO,QAAA,CAAS,MAAA;AAAA;AAAA,KAGf,aAAA,IAAiB,KAAA,EAAO,UAAA;;;iBC7BpB,aAAA,CAAc,MAAA,GAAS,aAAA,GAAgB,OAAA"}

package/dist/index.d.mts

@@ -0,0 +1,33 @@
+//#region src/types.d.ts
+interface TrackerConfig {
+  readonly enabled?: boolean;
+  readonly ignoreSelectors?: readonly string[];
+  readonly debug?: boolean;
+}
+interface Tracker {
+  on(eventType: string, callback: TrackCallback, options?: ListenerOptions): () => void;
+  getLastEvent(): TrackEvent | null;
+  destroy(): void;
+}
+interface ListenerOptions {
+  readonly debounce?: number;
+  readonly throttle?: number;
+  readonly once?: boolean;
+  readonly selector?: string;
+}
+interface TrackEvent {
+  readonly nativeEvent: Event;
+  readonly targetElement: Element;
+  readonly fiber: FiberInfo | null;
+}
+interface FiberInfo {
+  readonly componentName: string | null;
+  readonly props: Readonly<Record<string, unknown>>;
+}
+type TrackCallback = (event: TrackEvent) => void;
+//#endregion
+//#region src/core/tracker.d.ts
+declare function createTracker(config?: TrackerConfig): Tracker;
+//#endregion
+export { type FiberInfo, type ListenerOptions, type TrackCallback, type TrackEvent, type Tracker, type TrackerConfig, createTracker as init };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/core/tracker.ts"],"mappings":";UAEiB,aAAA;EAAA,SACN,OAAA;EAAA,SACA,eAAA;EAAA,SACA,KAAA;AAAA;AAAA,UAGM,OAAA;EACf,EAAA,CAAG,SAAA,UAAmB,QAAA,EAAU,aAAA,EAAe,OAAA,GAAU,eAAA;EACzD,YAAA,IAAgB,UAAA;EAChB,OAAA;AAAA;AAAA,UAGe,eAAA;EAAA,SACN,QAAA;EAAA,SACA,QAAA;EAAA,SACA,IAAA;EAAA,SACA,QAAA;AAAA;AAAA,UAGM,UAAA;EAAA,SACN,WAAA,EAAa,KAAA;EAAA,SACb,aAAA,EAAe,OAAA;EAAA,SACf,KAAA,EAAO,SAAA;AAAA;AAAA,UAGD,SAAA;EAAA,SACN,aAAA;EAAA,SACA,KAAA,EAAO,QAAA,CAAS,MAAA;AAAA;AAAA,KAGf,aAAA,IAAiB,KAAA,EAAO,UAAA;;;iBC7BpB,aAAA,CAAc,MAAA,GAAS,aAAA,GAAgB,OAAA"}

package/dist/index.mjs

@@ -0,0 +1,414 @@
+//#region src/filter/event-categories.ts
+const EventCategory = {
+	Pointer: "pointer",
+	Form: "form",
+	Ambient: "ambient"
+};
+const EVENT_HANDLER_MAP = {
+	click: [
+		"onClick",
+		"onMouseDown",
+		"onMouseUp",
+		"onPointerDown",
+		"onPointerUp"
+	],
+	touchstart: ["onTouchStart"],
+	touchend: ["onTouchEnd"],
+	input: ["onChange", "onInput"],
+	change: ["onChange"],
+	focus: ["onFocus"],
+	blur: ["onBlur"],
+	submit: ["onSubmit"],
+	scroll: ["onScroll"],
+	keydown: ["onKeyDown"],
+	keyup: ["onKeyUp"],
+	copy: ["onCopy"],
+	paste: ["onPaste"]
+};
+const CATEGORY_MAP = {
+	click: EventCategory.Pointer,
+	touchstart: EventCategory.Pointer,
+	touchend: EventCategory.Pointer,
+	input: EventCategory.Form,
+	change: EventCategory.Form,
+	focus: EventCategory.Form,
+	blur: EventCategory.Form,
+	submit: EventCategory.Form,
+	scroll: EventCategory.Ambient,
+	keydown: EventCategory.Ambient,
+	keyup: EventCategory.Ambient,
+	copy: EventCategory.Ambient,
+	paste: EventCategory.Ambient,
+	resize: EventCategory.Ambient,
+	popstate: EventCategory.Ambient,
+	hashchange: EventCategory.Ambient
+};
+function getEventCategory(eventType) {
+	return CATEGORY_MAP[eventType] ?? EventCategory.Ambient;
+}
+function getHandlersForEvent(eventType) {
+	return EVENT_HANDLER_MAP[eventType] ?? [];
+}
+
+//#endregion
+//#region src/extract/fiber.ts
+const FIBER_PREFIXES = ["__reactFiber$", "__reactInternalInstance$"];
+const MAX_PARENT_DEPTH = 10;
+let cachedKey = null;
+function resolveFiber(element) {
+	let current = element;
+	let depth = 0;
+	while (current !== null && depth <= MAX_PARENT_DEPTH) {
+		const fiber = getFiberFromElement(current);
+		if (fiber !== null) return fiber;
+		current = current.parentElement;
+		depth++;
+	}
+	return null;
+}
+function getFiberFromElement(element) {
+	if (cachedKey !== null) {
+		const fiber = element[cachedKey];
+		if (fiber != null) return fiber;
+		return null;
+	}
+	for (const key of Object.keys(element)) for (const prefix of FIBER_PREFIXES) if (key.startsWith(prefix)) {
+		cachedKey = key;
+		return element[key];
+	}
+	return null;
+}
+const MAX_STACK_DEPTH = 50;
+function extractFiberInfo(rawFiber) {
+	if (rawFiber === null) return null;
+	const fiber = rawFiber;
+	return {
+		componentName: findNearestComponentName(fiber),
+		props: fiber.memoizedProps ?? {}
+	};
+}
+function findNearestComponentName(fiber) {
+	let current = fiber.return;
+	let depth = 0;
+	while (current !== null && depth < MAX_STACK_DEPTH) {
+		const name = getComponentName(current);
+		if (name !== null) return name;
+		current = current.return;
+		depth++;
+	}
+	return null;
+}
+function getComponentName(fiber) {
+	const type = fiber.type;
+	if (typeof type === "string") return null;
+	if (typeof type === "function") return type.displayName ?? type.name ?? null;
+	return null;
+}
+
+//#endregion
+//#region src/utils/safe-matches.ts
+function safeMatches(element, selector) {
+	try {
+		return element.matches(selector);
+	} catch {
+		return false;
+	}
+}
+
+//#endregion
+//#region src/filter/filter-engine.ts
+const INTERACTIVE_TAGS = new Set([
+	"BUTTON",
+	"A",
+	"INPUT",
+	"SELECT",
+	"TEXTAREA",
+	"SUMMARY",
+	"DETAILS"
+]);
+const INTERACTIVE_ROLES = new Set([
+	"button",
+	"link",
+	"menuitem",
+	"tab",
+	"checkbox",
+	"radio",
+	"combobox",
+	"listbox",
+	"option",
+	"switch",
+	"slider",
+	"spinbutton",
+	"menuitemcheckbox",
+	"menuitemradio",
+	"treeitem",
+	"gridcell",
+	"textbox",
+	"searchbox"
+]);
+const MAX_ANCESTOR_DEPTH = 10;
+function findTrackableElement(params) {
+	const { target, ignoreSelectors, eventType } = params;
+	switch (getEventCategory(eventType)) {
+		case EventCategory.Pointer: return findPointerTarget(target, ignoreSelectors, eventType);
+		case EventCategory.Form: return findFormTarget(target, ignoreSelectors);
+		case EventCategory.Ambient: return findAmbientTarget(target, ignoreSelectors);
+	}
+}
+function findPointerTarget(target, ignoreSelectors, eventType) {
+	let current = target;
+	let depth = 0;
+	while (current !== null && depth <= MAX_ANCESTOR_DEPTH) {
+		if (isIgnored(current, ignoreSelectors)) return null;
+		if (isDisabled(current)) return null;
+		const rawFiber = findInteractiveFiber(current, eventType);
+		if (rawFiber !== void 0) return {
+			element: current,
+			fiber: extractFiberInfo(rawFiber)
+		};
+		current = current.parentElement;
+		depth++;
+	}
+	return null;
+}
+function findFormTarget(target, ignoreSelectors) {
+	if (isIgnored(target, ignoreSelectors)) return null;
+	if (isDisabled(target)) return null;
+	return {
+		element: target,
+		fiber: extractFiberInfo(resolveFiber(target))
+	};
+}
+function findAmbientTarget(target, ignoreSelectors) {
+	if (isIgnored(target, ignoreSelectors)) return null;
+	return {
+		element: target,
+		fiber: extractFiberInfo(resolveFiber(target))
+	};
+}
+/**
+* Returns the raw fiber if the element is interactive, or undefined if not.
+* null means "interactive but no fiber found" (semantic tag / ARIA role).
+*/
+function findInteractiveFiber(el, eventType) {
+	if (INTERACTIVE_TAGS.has(el.tagName)) return resolveFiber(el);
+	const role = el.getAttribute("role");
+	if (role !== null && INTERACTIVE_ROLES.has(role)) return resolveFiber(el);
+	const handlers = getHandlersForEvent(eventType);
+	if (handlers.length > 0) {
+		const fiber = resolveFiber(el);
+		if (fiber !== null) {
+			const props = fiber.memoizedProps;
+			if (props !== null && props !== void 0) {
+				for (const handler of handlers) if (typeof props[handler] === "function") return fiber;
+			}
+		}
+	}
+}
+function isIgnored(element, ignoreSelectors) {
+	return ignoreSelectors.some((selector) => safeMatches(element, selector));
+}
+function isDisabled(el) {
+	return el.hasAttribute("disabled") || el.getAttribute("aria-disabled") === "true";
+}
+
+//#endregion
+//#region src/utils/debounce.ts
+function debounce(fn, ms) {
+	let timeoutId = null;
+	const debounced = (...args) => {
+		if (timeoutId !== null) clearTimeout(timeoutId);
+		timeoutId = setTimeout(() => {
+			timeoutId = null;
+			fn(...args);
+		}, ms);
+	};
+	debounced.cancel = () => {
+		if (timeoutId !== null) {
+			clearTimeout(timeoutId);
+			timeoutId = null;
+		}
+	};
+	return debounced;
+}
+
+//#endregion
+//#region src/utils/throttle.ts
+function throttle(fn, ms) {
+	let lastCallTime = 0;
+	let timeoutId = null;
+	let lastArgs = null;
+	const throttled = (...args) => {
+		const now = Date.now();
+		const elapsed = now - lastCallTime;
+		if (elapsed >= ms) {
+			lastCallTime = now;
+			fn(...args);
+		} else {
+			lastArgs = args;
+			if (timeoutId === null) timeoutId = setTimeout(() => {
+				timeoutId = null;
+				lastCallTime = Date.now();
+				if (lastArgs !== null) {
+					fn(...lastArgs);
+					lastArgs = null;
+				}
+			}, ms - elapsed);
+		}
+	};
+	throttled.cancel = () => {
+		if (timeoutId !== null) {
+			clearTimeout(timeoutId);
+			timeoutId = null;
+		}
+		lastArgs = null;
+	};
+	return throttled;
+}
+
+//#endregion
+//#region src/core/registry.ts
+function createRegistry() {
+	let entries = [];
+	function createEntry(eventType, callback, options) {
+		const wrappedCallback = wrapCallback(callback, options);
+		const entry = {
+			eventType,
+			wrappedCallback,
+			options,
+			unsubscribe: () => {
+				wrappedCallback.cancel?.();
+				entries = entries.filter((e) => e !== entry);
+			}
+		};
+		return entry;
+	}
+	return {
+		add(eventType, callback, options) {
+			const entry = createEntry(eventType, callback, options);
+			entries = [...entries, entry];
+			return entry.unsubscribe;
+		},
+		invoke(event) {
+			for (const entry of entries) {
+				if (entry.eventType !== event.nativeEvent.type) continue;
+				if (entry.options.selector != null) {
+					if (!safeMatches(event.targetElement, entry.options.selector)) continue;
+				}
+				entry.wrappedCallback(event);
+				if (entry.options.once === true) entry.unsubscribe();
+			}
+		},
+		getEventTypes() {
+			return new Set(entries.map((e) => e.eventType));
+		},
+		clear() {
+			for (const entry of entries) entry.wrappedCallback.cancel?.();
+			entries = [];
+		}
+	};
+}
+function wrapCallback(callback, options) {
+	if (options.debounce != null) return debounce(callback, options.debounce);
+	if (options.throttle != null) return throttle(callback, options.throttle);
+	return callback;
+}
+
+//#endregion
+//#region src/core/pipeline.ts
+function createPipeline(config) {
+	const registry = createRegistry();
+	let lastEvent = null;
+	return {
+		handleEvent(domEvent) {
+			const target = domEvent.target;
+			if (!(target instanceof Element)) return;
+			const result = findTrackableElement({
+				target,
+				ignoreSelectors: config.ignoreSelectors,
+				eventType: domEvent.type
+			});
+			if (result === null) return;
+			const trackEvent = {
+				nativeEvent: domEvent,
+				targetElement: result.element,
+				fiber: result.fiber
+			};
+			registry.invoke(trackEvent);
+			lastEvent = trackEvent;
+		},
+		getLastEvent() {
+			return lastEvent;
+		},
+		addListener(eventType, callback, options) {
+			return registry.add(eventType, callback, options);
+		},
+		getEventTypes() {
+			return registry.getEventTypes();
+		},
+		clear() {
+			registry.clear();
+		}
+	};
+}
+
+//#endregion
+//#region src/core/tracker.ts
+function createTracker(config) {
+	const enabled = config?.enabled ?? true;
+	const ignoreSelectors = config?.ignoreSelectors ?? [];
+	const debug = config?.debug ?? false;
+	if (!enabled) return {
+		on: () => () => {},
+		getLastEvent: () => null,
+		destroy: () => {}
+	};
+	const pipeline = createPipeline({ ignoreSelectors });
+	const domListeners = /* @__PURE__ */ new Map();
+	let destroyed = false;
+	function ensureDomListener(eventType) {
+		if (domListeners.has(eventType)) return;
+		const handler = (event) => {
+			pipeline.handleEvent(event);
+			if (debug) {
+				const lastEvent = pipeline.getLastEvent();
+				if (lastEvent?.nativeEvent === event) console.debug("[react-auto-tracking]", lastEvent);
+			}
+		};
+		document.addEventListener(eventType, handler, true);
+		domListeners.set(eventType, handler);
+	}
+	function removeDomListener(eventType) {
+		const handler = domListeners.get(eventType);
+		if (handler === void 0) return;
+		if (!pipeline.getEventTypes().has(eventType)) {
+			document.removeEventListener(eventType, handler, true);
+			domListeners.delete(eventType);
+		}
+	}
+	return {
+		on(eventType, callback, options) {
+			if (destroyed) return () => {};
+			ensureDomListener(eventType);
+			const unsub = pipeline.addListener(eventType, callback, options ?? {});
+			return () => {
+				unsub();
+				removeDomListener(eventType);
+			};
+		},
+		getLastEvent() {
+			return pipeline.getLastEvent();
+		},
+		destroy() {
+			if (destroyed) return;
+			destroyed = true;
+			pipeline.clear();
+			for (const [eventType, handler] of domListeners) document.removeEventListener(eventType, handler, true);
+			domListeners.clear();
+		}
+	};
+}
+
+//#endregion
+export { createTracker as init };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/filter/event-categories.ts","../src/extract/fiber.ts","../src/utils/safe-matches.ts","../src/filter/filter-engine.ts","../src/utils/debounce.ts","../src/utils/throttle.ts","../src/core/registry.ts","../src/core/pipeline.ts","../src/core/tracker.ts"],"sourcesContent":["export const EventCategory = {\n  Pointer: 'pointer',\n  Form: 'form',\n  Ambient: 'ambient',\n} as const\n\nexport type EventCategory = (typeof EventCategory)[keyof typeof EventCategory]\n\n// Maps DOM event types to React handler prop names used to detect interactivity.\n// For click, we include mouse/pointer handlers because an element with only\n// onMouseDown (no onClick) is still interactive from a tracking perspective.\nconst EVENT_HANDLER_MAP: Readonly<Record<string, readonly string[]>> = {\n  // Pointer — includes related mouse/pointer handlers to catch all interactive patterns\n  click: ['onClick', 'onMouseDown', 'onMouseUp', 'onPointerDown', 'onPointerUp'],\n  touchstart: ['onTouchStart'],\n  touchend: ['onTouchEnd'],\n\n  // Form\n  input: ['onChange', 'onInput'],\n  change: ['onChange'],\n  focus: ['onFocus'],\n  blur: ['onBlur'],\n  submit: ['onSubmit'],\n\n  // Ambient\n  scroll: ['onScroll'],\n  keydown: ['onKeyDown'],\n  keyup: ['onKeyUp'],\n  copy: ['onCopy'],\n  paste: ['onPaste'],\n}\n\nconst CATEGORY_MAP: Readonly<Record<string, EventCategory>> = {\n  click: EventCategory.Pointer,\n  touchstart: EventCategory.Pointer,\n  touchend: EventCategory.Pointer,\n\n  input: EventCategory.Form,\n  change: EventCategory.Form,\n  focus: EventCategory.Form,\n  blur: EventCategory.Form,\n  submit: EventCategory.Form,\n\n  scroll: EventCategory.Ambient,\n  keydown: EventCategory.Ambient,\n  keyup: EventCategory.Ambient,\n  copy: EventCategory.Ambient,\n  paste: EventCategory.Ambient,\n  resize: EventCategory.Ambient,\n  popstate: EventCategory.Ambient,\n  hashchange: EventCategory.Ambient,\n}\n\nexport function getEventCategory(eventType: string): EventCategory {\n  return CATEGORY_MAP[eventType] ?? EventCategory.Ambient\n}\n\nexport function getHandlersForEvent(eventType: string): readonly string[] {\n  return EVENT_HANDLER_MAP[eventType] ?? []\n}\n","import type { FiberInfo } from '../types'\n\n// === Resolver: DOM element → raw fiber node ===\n\nconst FIBER_PREFIXES = ['__reactFiber$', '__reactInternalInstance$'] as const\nconst MAX_PARENT_DEPTH = 10\n\nlet cachedKey: string | null = null\n\nexport function resolveFiber(element: Element): object | null {\n  let current: Element | null = element\n  let depth = 0\n\n  while (current !== null && depth <= MAX_PARENT_DEPTH) {\n    const fiber = getFiberFromElement(current)\n    if (fiber !== null) {\n      return fiber\n    }\n    current = current.parentElement\n    depth++\n  }\n\n  return null\n}\n\nfunction getFiberFromElement(element: Element): object | null {\n  if (cachedKey !== null) {\n    const fiber = (element as any)[cachedKey]\n    if (fiber != null) return fiber as object\n    return null\n  }\n\n  for (const key of Object.keys(element)) {\n    for (const prefix of FIBER_PREFIXES) {\n      if (key.startsWith(prefix)) {\n        cachedKey = key\n        return (element as any)[key] as object\n      }\n    }\n  }\n\n  return null\n}\n\nexport function resetFiberKeyCache(): void {\n  cachedKey = null\n}\n\n// === Extractor: raw fiber node → FiberInfo ===\n\nconst MAX_STACK_DEPTH = 50\n\ninterface FiberNode {\n  type: unknown\n  memoizedProps: Record<string, unknown> | null\n  return: FiberNode | null\n}\n\nexport function extractFiberInfo(rawFiber: object | null): FiberInfo | null {\n  if (rawFiber === null) return null\n\n  const fiber = rawFiber as FiberNode\n  return {\n    componentName: findNearestComponentName(fiber),\n    props: fiber.memoizedProps ?? {},\n  }\n}\n\nfunction findNearestComponentName(fiber: FiberNode): string | null {\n  let current: FiberNode | null = fiber.return\n  let depth = 0\n\n  while (current !== null && depth < MAX_STACK_DEPTH) {\n    const name = getComponentName(current)\n    if (name !== null) return name\n    current = current.return\n    depth++\n  }\n\n  return null\n}\n\nfunction getComponentName(fiber: FiberNode): string | null {\n  const type = fiber.type\n  if (typeof type === 'string') return null\n  if (typeof type === 'function') {\n    return (type as any).displayName ?? type.name ?? null\n  }\n  return null\n}\n","export function safeMatches(element: Element, selector: string): boolean {\n  try {\n    return element.matches(selector)\n  } catch {\n    return false\n  }\n}\n","import type { FiberInfo } from '../types'\nimport { getEventCategory, getHandlersForEvent, EventCategory } from './event-categories'\nimport { resolveFiber, extractFiberInfo } from '../extract/fiber'\nimport { safeMatches } from '../utils/safe-matches'\n\nconst INTERACTIVE_TAGS = new Set([\n  'BUTTON',\n  'A',\n  'INPUT',\n  'SELECT',\n  'TEXTAREA',\n  'SUMMARY',\n  'DETAILS',\n])\n\nconst INTERACTIVE_ROLES = new Set([\n  // Original widget roles\n  'button',\n  'link',\n  'menuitem',\n  'tab',\n  'checkbox',\n  'radio',\n  'combobox',\n  'listbox',\n  'option',\n  'switch',\n  'slider',\n  'spinbutton',\n  // Composite widget variants\n  'menuitemcheckbox',\n  'menuitemradio',\n  'treeitem',\n  'gridcell',\n  // Input widget roles\n  'textbox',\n  'searchbox',\n])\n\nconst MAX_ANCESTOR_DEPTH = 10\n\nexport interface FilterResult {\n  readonly element: Element\n  readonly fiber: FiberInfo | null\n}\n\ninterface FindTrackableParams {\n  readonly target: Element\n  readonly ignoreSelectors: readonly string[]\n  readonly eventType: string\n}\n\nexport function findTrackableElement(params: FindTrackableParams): FilterResult | null {\n  const { target, ignoreSelectors, eventType } = params\n  const category = getEventCategory(eventType)\n\n  switch (category) {\n    case EventCategory.Pointer:\n      return findPointerTarget(target, ignoreSelectors, eventType)\n    case EventCategory.Form:\n      return findFormTarget(target, ignoreSelectors)\n    case EventCategory.Ambient:\n      return findAmbientTarget(target, ignoreSelectors)\n  }\n}\n\nfunction findPointerTarget(\n  target: Element,\n  ignoreSelectors: readonly string[],\n  eventType: string,\n): FilterResult | null {\n  let current: Element | null = target\n  let depth = 0\n\n  while (current !== null && depth <= MAX_ANCESTOR_DEPTH) {\n    if (isIgnored(current, ignoreSelectors)) return null\n    if (isDisabled(current)) return null\n\n    const rawFiber = findInteractiveFiber(current, eventType)\n    if (rawFiber !== undefined) {\n      return { element: current, fiber: extractFiberInfo(rawFiber) }\n    }\n\n    current = current.parentElement\n    depth++\n  }\n\n  return null\n}\n\nfunction findFormTarget(target: Element, ignoreSelectors: readonly string[]): FilterResult | null {\n  if (isIgnored(target, ignoreSelectors)) return null\n  if (isDisabled(target)) return null\n  return { element: target, fiber: extractFiberInfo(resolveFiber(target)) }\n}\n\nfunction findAmbientTarget(\n  target: Element,\n  ignoreSelectors: readonly string[],\n): FilterResult | null {\n  if (isIgnored(target, ignoreSelectors)) return null\n  return { element: target, fiber: extractFiberInfo(resolveFiber(target)) }\n}\n\n/**\n * Returns the raw fiber if the element is interactive, or undefined if not.\n * null means \"interactive but no fiber found\" (semantic tag / ARIA role).\n */\nfunction findInteractiveFiber(el: Element, eventType: string): object | null | undefined {\n  // 1. Semantic tag\n  if (INTERACTIVE_TAGS.has(el.tagName)) return resolveFiber(el)\n\n  // 2. ARIA role\n  const role = el.getAttribute('role')\n  if (role !== null && INTERACTIVE_ROLES.has(role)) return resolveFiber(el)\n\n  // 3. React event handler via fiber\n  const handlers = getHandlersForEvent(eventType)\n  if (handlers.length > 0) {\n    const fiber = resolveFiber(el)\n    if (fiber !== null) {\n      const props = (fiber as any).memoizedProps\n      if (props !== null && props !== undefined) {\n        for (const handler of handlers) {\n          if (typeof props[handler] === 'function') return fiber\n        }\n      }\n    }\n  }\n\n  return undefined\n}\n\nexport function isIgnored(element: Element, ignoreSelectors: readonly string[]): boolean {\n  return ignoreSelectors.some((selector) => safeMatches(element, selector))\n}\n\nexport function isDisabled(el: Element): boolean {\n  return el.hasAttribute('disabled') || el.getAttribute('aria-disabled') === 'true'\n}\n","// eslint-disable-next-line @typescript-eslint/no-explicit-any\ninterface DebouncedFn<T extends (...args: any[]) => void> {\n  (...args: Parameters<T>): void\n  cancel(): void\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function debounce<T extends (...args: any[]) => void>(fn: T, ms: number): DebouncedFn<T> {\n  let timeoutId: ReturnType<typeof setTimeout> | null = null\n\n  const debounced = (...args: Parameters<T>): void => {\n    if (timeoutId !== null) {\n      clearTimeout(timeoutId)\n    }\n    timeoutId = setTimeout(() => {\n      timeoutId = null\n      fn(...args)\n    }, ms)\n  }\n\n  debounced.cancel = (): void => {\n    if (timeoutId !== null) {\n      clearTimeout(timeoutId)\n      timeoutId = null\n    }\n  }\n\n  return debounced\n}\n","// eslint-disable-next-line @typescript-eslint/no-explicit-any\ninterface ThrottledFn<T extends (...args: any[]) => void> {\n  (...args: Parameters<T>): void\n  cancel(): void\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function throttle<T extends (...args: any[]) => void>(fn: T, ms: number): ThrottledFn<T> {\n  let lastCallTime = 0\n  let timeoutId: ReturnType<typeof setTimeout> | null = null\n  let lastArgs: Parameters<T> | null = null\n\n  const throttled = (...args: Parameters<T>): void => {\n    const now = Date.now()\n    const elapsed = now - lastCallTime\n\n    if (elapsed >= ms) {\n      lastCallTime = now\n      fn(...args)\n    } else {\n      lastArgs = args\n      if (timeoutId === null) {\n        timeoutId = setTimeout(() => {\n          timeoutId = null\n          lastCallTime = Date.now()\n          if (lastArgs !== null) {\n            fn(...lastArgs)\n            lastArgs = null\n          }\n        }, ms - elapsed)\n      }\n    }\n  }\n\n  throttled.cancel = (): void => {\n    if (timeoutId !== null) {\n      clearTimeout(timeoutId)\n      timeoutId = null\n    }\n    lastArgs = null\n  }\n\n  return throttled\n}\n","import type { TrackEvent, TrackCallback, ListenerOptions } from '../types'\nimport { debounce } from '../utils/debounce'\nimport { throttle } from '../utils/throttle'\nimport { safeMatches } from '../utils/safe-matches'\n\ninterface RegistryEntry {\n  readonly eventType: string\n  readonly wrappedCallback: TrackCallback & { cancel?: () => void }\n  readonly options: ListenerOptions\n  readonly unsubscribe: () => void\n}\n\nexport interface Registry {\n  add(eventType: string, callback: TrackCallback, options: ListenerOptions): () => void\n  invoke(event: TrackEvent): void\n  getEventTypes(): Set<string>\n  clear(): void\n}\n\nexport function createRegistry(): Registry {\n  let entries: RegistryEntry[] = []\n\n  function createEntry(\n    eventType: string,\n    callback: TrackCallback,\n    options: ListenerOptions,\n  ): RegistryEntry {\n    const wrappedCallback = wrapCallback(callback, options)\n    const entry: RegistryEntry = {\n      eventType,\n      wrappedCallback,\n      options,\n      unsubscribe: () => {\n        wrappedCallback.cancel?.()\n        entries = entries.filter((e) => e !== entry)\n      },\n    }\n    return entry\n  }\n\n  return {\n    add(eventType: string, callback: TrackCallback, options: ListenerOptions): () => void {\n      const entry = createEntry(eventType, callback, options)\n      entries = [...entries, entry]\n      return entry.unsubscribe\n    },\n\n    invoke(event: TrackEvent): void {\n      for (const entry of entries) {\n        if (entry.eventType !== event.nativeEvent.type) continue\n\n        if (entry.options.selector != null) {\n          if (!safeMatches(event.targetElement, entry.options.selector)) {\n            continue\n          }\n        }\n\n        entry.wrappedCallback(event)\n\n        // once: auto-unsubscribe after first fire\n        if (entry.options.once === true) {\n          entry.unsubscribe()\n        }\n      }\n    },\n\n    getEventTypes(): Set<string> {\n      return new Set(entries.map((e) => e.eventType))\n    },\n\n    clear(): void {\n      for (const entry of entries) {\n        entry.wrappedCallback.cancel?.()\n      }\n      entries = []\n    },\n  }\n}\n\nfunction wrapCallback(\n  callback: TrackCallback,\n  options: ListenerOptions,\n): TrackCallback & { cancel?: () => void } {\n  if (options.debounce != null) {\n    return debounce(callback, options.debounce)\n  }\n  if (options.throttle != null) {\n    return throttle(callback, options.throttle)\n  }\n  return callback\n}\n","import type { TrackEvent, TrackCallback, ListenerOptions } from '../types'\nimport { findTrackableElement } from '../filter/filter-engine'\nimport { createRegistry } from './registry'\n\nexport interface Pipeline {\n  handleEvent(domEvent: Event): void\n  getLastEvent(): TrackEvent | null\n  addListener(eventType: string, callback: TrackCallback, options: ListenerOptions): () => void\n  getEventTypes(): Set<string>\n  clear(): void\n}\n\nexport interface PipelineConfig {\n  readonly ignoreSelectors: readonly string[]\n}\n\nexport function createPipeline(config: PipelineConfig): Pipeline {\n  const registry = createRegistry()\n  let lastEvent: TrackEvent | null = null\n\n  return {\n    handleEvent(domEvent: Event): void {\n      const target = domEvent.target\n      if (!(target instanceof Element)) return\n\n      const result = findTrackableElement({\n        target,\n        ignoreSelectors: config.ignoreSelectors,\n        eventType: domEvent.type,\n      })\n      if (result === null) return\n\n      const trackEvent: TrackEvent = {\n        nativeEvent: domEvent,\n        targetElement: result.element,\n        fiber: result.fiber,\n      }\n\n      registry.invoke(trackEvent)\n      lastEvent = trackEvent\n    },\n\n    getLastEvent(): TrackEvent | null {\n      return lastEvent\n    },\n\n    addListener(eventType: string, callback: TrackCallback, options: ListenerOptions): () => void {\n      return registry.add(eventType, callback, options)\n    },\n\n    getEventTypes(): Set<string> {\n      return registry.getEventTypes()\n    },\n\n    clear(): void {\n      registry.clear()\n    },\n  }\n}\n","import type { Tracker, TrackerConfig, TrackCallback, ListenerOptions } from '../types'\nimport { createPipeline } from './pipeline'\n\nexport function createTracker(config?: TrackerConfig): Tracker {\n  const enabled = config?.enabled ?? true\n  const ignoreSelectors = config?.ignoreSelectors ?? []\n  const debug = config?.debug ?? false\n\n  if (!enabled) {\n    return {\n      on: () => () => {},\n      getLastEvent: () => null,\n      destroy: () => {},\n    }\n  }\n\n  const pipeline = createPipeline({ ignoreSelectors })\n  const domListeners = new Map<string, (event: Event) => void>()\n  let destroyed = false\n\n  // Lazily attaches one capture-phase listener per event type on document.\n  // Multiple on() calls for the same type share a single DOM listener;\n  // the pipeline fans out to all registered callbacks internally.\n  function ensureDomListener(eventType: string): void {\n    if (domListeners.has(eventType)) return\n\n    const handler = (event: Event): void => {\n      pipeline.handleEvent(event)\n\n      if (debug) {\n        const lastEvent = pipeline.getLastEvent()\n        if (lastEvent?.nativeEvent === event) {\n          console.debug('[react-auto-tracking]', lastEvent)\n        }\n      }\n    }\n\n    document.addEventListener(eventType, handler, true)\n    domListeners.set(eventType, handler)\n  }\n\n  function removeDomListener(eventType: string): void {\n    const handler = domListeners.get(eventType)\n    if (handler === undefined) return\n\n    // Only remove if no more listeners for this type\n    if (!pipeline.getEventTypes().has(eventType)) {\n      document.removeEventListener(eventType, handler, true)\n      domListeners.delete(eventType)\n    }\n  }\n\n  return {\n    on(eventType: string, callback: TrackCallback, options?: ListenerOptions): () => void {\n      if (destroyed) return () => {}\n\n      ensureDomListener(eventType)\n      const unsub = pipeline.addListener(eventType, callback, options ?? {})\n\n      return () => {\n        unsub()\n        removeDomListener(eventType)\n      }\n    },\n\n    getLastEvent() {\n      return pipeline.getLastEvent()\n    },\n\n    destroy(): void {\n      if (destroyed) return\n      destroyed = true\n\n      pipeline.clear()\n\n      for (const [eventType, handler] of domListeners) {\n        document.removeEventListener(eventType, handler, true)\n      }\n      domListeners.clear()\n    },\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "react-auto-tracking",
+  "version": "0.1.0",
+  "description": "Global user interaction tracking for React.js",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "oxlint src/",
+    "format": "oxfmt --write src/",
+    "format:check": "oxfmt --check src/",
+    "typecheck": "tsc --noEmit",
+    "check": "pnpm lint && pnpm format:check && pnpm typecheck"
+  },
+  "simple-git-hooks": {
+    "pre-push": "pnpm check"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "react",
+    "tracking",
+    "analytics",
+    "interaction",
+    "fiber"
+  ],
+  "devDependencies": {
+    "@changesets/cli": "^2.29.8",
+    "@vitest/coverage-v8": "^4.0.18",
+    "jsdom": "^28.1.0",
+    "oxfmt": "^0.32.0",
+    "oxlint": "^1.47.0",
+    "simple-git-hooks": "^2.13.1",
+    "tsdown": "^0.20.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}