@releval/tracker 1.0.0-bootstrap.0

package/dist/react.cjs

@@ -0,0 +1,180 @@
+"use client";
+/*! @releval/tracker | Apache-2.0 | https://github.com/releval/tracker */
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_tracker = require("./tracker.cjs");
+let react = require("react");
+//#region src/react/SearchResults.ts
+const SearchResultsContext = (0, react.createContext)(null);
+/**
+* Declares which search produced the results rendered beneath it - the SPA
+* twin of `data-query-id` on a server-rendered results container. Result
+* components read it with {@link useSearchResults} (and
+* {@link useResultImpression} reads it automatically) instead of threading
+* `queryId` down as a prop.
+*
+* ```tsx
+* <SearchResults queryId={response.query_id} query={q}>
+*   {results.map((r, i) => <ResultCard key={r.sku} result={r} ordinal={i + 1} />)}
+* </SearchResults>
+* ```
+*/
+function SearchResults({ queryId, query, children }) {
+	const value = (0, react.useMemo)(() => ({
+		queryId,
+		query
+	}), [queryId, query]);
+	return (0, react.createElement)(SearchResultsContext.Provider, { value }, children);
+}
+/**
+* The current search context, or null outside a {@link SearchResults} (e.g. a
+* card rendered on a home page that did not come from a search).
+*/
+function useSearchResults() {
+	return (0, react.useContext)(SearchResultsContext);
+}
+//#endregion
+//#region src/react/context.ts
+/**
+* Holds the configured {@link Tracker} for a React tree. Provided by
+* {@link TrackerProvider} and read with {@link useTracker}.
+*/
+const TrackerContext = (0, react.createContext)(null);
+//#endregion
+//#region src/react/TrackerProvider.ts
+/**
+* Owns a {@link Tracker}'s lifecycle and exposes it to the tree via context.
+* Starts the tracker on mount and stops it on unmount, so components never
+* import a module singleton and the tracker is torn down cleanly.
+*
+* `options` (and `tracker`) are read ONCE on mount; later prop changes are
+* ignored. Update identity with `useTracker().setUserId(...)` rather than by
+* changing `options.userId`.
+*
+* @example
+* ```tsx
+* <TrackerProvider
+*   options={{ application: "my-app", siteId: "...", endpointHost: "..." }}
+*   onInit={(t) => t.addEnricher(abTestEnricher)}
+* >
+*   <App />
+* </TrackerProvider>
+* ```
+*/
+function TrackerProvider(props) {
+	const { children, onInit, autoStart = true } = props;
+	const [tracker] = (0, react.useState)(() => "tracker" in props && props.tracker ? props.tracker : new require_tracker.Tracker(props.options));
+	const onInitRef = (0, react.useRef)(onInit);
+	const initialized = (0, react.useRef)(false);
+	(0, react.useEffect)(() => {
+		if (!autoStart) return;
+		if (!initialized.current) {
+			var _onInitRef$current;
+			initialized.current = true;
+			(_onInitRef$current = onInitRef.current) === null || _onInitRef$current === void 0 || _onInitRef$current.call(onInitRef, tracker);
+		}
+		tracker.start();
+		return () => {
+			tracker.stop();
+		};
+	}, [tracker, autoStart]);
+	return (0, react.createElement)(TrackerContext.Provider, { value: tracker }, children);
+}
+/**
+* Returns the {@link Tracker} provided by the nearest {@link TrackerProvider}.
+* Throws when called outside a provider.
+*/
+function useTracker() {
+	const tracker = (0, react.useContext)(TrackerContext);
+	if (!tracker) throw new Error("useTracker must be used within a <TrackerProvider>. Wrap your app in <TrackerProvider options={{ application: '...' }}> ... </TrackerProvider>.");
+	return tracker;
+}
+//#endregion
+//#region src/react/useResultImpression.ts
+/**
+* Returns a callback ref that reports ONE canonical impression for the result
+* the first time its element becomes visible, attributed to the surrounding
+* {@link SearchResults} context.
+*
+* Fires once per query, not once per component instance: a new `queryId`
+* re-arms the hook, so a card that stays mounted across consecutive searches
+* is counted for each query. (A per-instance one-shot undercounts exactly the
+* products that are returned most often, inflating their CTR.) The Tracker
+* additionally dedupes impressions per `(queryId, objectId)` for its
+* lifetime, so remounted instances - virtualized lists, route re-entry -
+* cannot re-fire a pair this page already reported.
+*
+* Extra keys on `result` are persisted under the event's `event_attributes`
+* (see {@link ResultRef}). Changing only extras does not re-arm the
+* observer; the values current when the impression fires are sent.
+*
+* No-ops when there is no search context (nothing joinable to report), when
+* `disabled`, or where `IntersectionObserver` is unavailable.
+*
+* StrictMode-safe by construction: cleanup is driven by the callback ref
+* itself - React calls it with `null` on detach and re-invokes it when its
+* identity changes - not by an effect whose simulated unmount would
+* disconnect the observer without re-arming it.
+*
+* ```tsx
+* const ref = useResultImpression({ objectId: r.sku, ordinal });
+* return <article ref={ref}>...</article>;
+* ```
+*/
+function useResultImpression(result, options) {
+	var _options$disabled;
+	const tracker = useTracker();
+	const search = useSearchResults();
+	const firedForQuery = (0, react.useRef)(null);
+	const observerRef = (0, react.useRef)(null);
+	const latestResult = (0, react.useRef)(result);
+	latestResult.current = result;
+	const disabled = (_options$disabled = options === null || options === void 0 ? void 0 : options.disabled) !== null && _options$disabled !== void 0 ? _options$disabled : false;
+	const { objectId, ordinal } = result;
+	const queryId = search === null || search === void 0 ? void 0 : search.queryId;
+	const query = search === null || search === void 0 ? void 0 : search.query;
+	return (0, react.useCallback)((node) => {
+		var _observerRef$current;
+		(_observerRef$current = observerRef.current) === null || _observerRef$current === void 0 || _observerRef$current.disconnect();
+		observerRef.current = null;
+		if (!node || disabled || !queryId) return;
+		if (firedForQuery.current === queryId) return;
+		if (typeof IntersectionObserver === "undefined") return;
+		const observer = new IntersectionObserver((entries) => {
+			for (const entry of entries) {
+				if (!entry.isIntersecting) continue;
+				if (firedForQuery.current === queryId) continue;
+				firedForQuery.current = queryId;
+				const item = {
+					...latestResult.current,
+					objectId,
+					ordinal
+				};
+				tracker.trackResultImpression({
+					items: [item],
+					queryId,
+					query
+				});
+				observer.disconnect();
+				observerRef.current = null;
+			}
+		}, { threshold: 0 });
+		observer.observe(node);
+		observerRef.current = observer;
+	}, [
+		tracker,
+		objectId,
+		ordinal,
+		queryId,
+		query,
+		disabled
+	]);
+}
+//#endregion
+exports.SearchResults = SearchResults;
+exports.Tracker = require_tracker.Tracker;
+exports.TrackerProvider = TrackerProvider;
+exports.useResultImpression = useResultImpression;
+exports.useSearchResults = useSearchResults;
+exports.useTracker = useTracker;
+
+//# sourceMappingURL=react.cjs.map

package/dist/react.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.cjs","names":["createContext","useMemo","createElement","useContext","createContext","useState","Tracker","useRef","createElement","useContext","useRef","useCallback"],"sources":["../src/react/SearchResults.ts","../src/react/context.ts","../src/react/TrackerProvider.ts","../src/react/useResultImpression.ts"],"sourcesContent":["import {\n  createContext,\n  createElement,\n  type ReactElement,\n  type ReactNode,\n  useContext,\n  useMemo,\n} from \"react\";\n\n/** The search that produced the results rendered beneath a {@link SearchResults}. */\nexport type SearchResultsValue = {\n  /** The server-issued `query_id` for the search. */\n  queryId: string;\n  /** The query text as the user entered it, if known. */\n  query?: string;\n};\n\nconst SearchResultsContext = createContext<SearchResultsValue | null>(null);\n\n/** Props for {@link SearchResults}. */\nexport type SearchResultsProps = SearchResultsValue & {\n  /** The results subtree this search context applies to. */\n  children?: ReactNode;\n};\n\n/**\n * Declares which search produced the results rendered beneath it - the SPA\n * twin of `data-query-id` on a server-rendered results container. Result\n * components read it with {@link useSearchResults} (and\n * {@link useResultImpression} reads it automatically) instead of threading\n * `queryId` down as a prop.\n *\n * ```tsx\n * <SearchResults queryId={response.query_id} query={q}>\n *   {results.map((r, i) => <ResultCard key={r.sku} result={r} ordinal={i + 1} />)}\n * </SearchResults>\n * ```\n */\nexport function SearchResults({\n  queryId,\n  query,\n  children,\n}: SearchResultsProps): ReactElement {\n  const value = useMemo(() => ({ queryId, query }), [queryId, query]);\n  return createElement(SearchResultsContext.Provider, { value }, children);\n}\n\n/**\n * The current search context, or null outside a {@link SearchResults} (e.g. a\n * card rendered on a home page that did not come from a search).\n */\nexport function useSearchResults(): SearchResultsValue | null {\n  return useContext(SearchResultsContext);\n}\n","import { createContext } from \"react\";\nimport type { Tracker } from \"../tracker\";\n\n/**\n * Holds the configured {@link Tracker} for a React tree. Provided by\n * {@link TrackerProvider} and read with {@link useTracker}.\n */\nexport const TrackerContext = createContext<Tracker | null>(null);\n","import {\n  createElement,\n  type ReactElement,\n  type ReactNode,\n  useContext,\n  useEffect,\n  useRef,\n  useState,\n} from \"react\";\nimport { Tracker, type TrackerOptions } from \"../tracker\";\nimport { TrackerContext } from \"./context\";\n\n/**\n * Props shared by both {@link TrackerProviderProps} variants (provide\n * `options` OR a pre-built `tracker`).\n */\nexport interface TrackerProviderBaseProps {\n  /**\n   * Runs exactly once, before the first `start()`. Do one-time wiring here:\n   * `addEnricher()`, `addSink()`. It is guarded so React StrictMode's\n   * double-mount cannot run the wiring twice.\n   */\n  onInit?: (tracker: Tracker) => void;\n  /**\n   * Call `start()` on mount and `stop()` on unmount. Defaults to `true`. Set\n   * `false` when an external owner controls the tracker lifecycle and the\n   * provider is only used to expose the instance via context.\n   */\n  autoStart?: boolean;\n  /** The tree that can read the tracker via {@link useTracker}. */\n  children?: ReactNode;\n}\n\n/**\n * Provide the tracker either by handing over an already-constructed instance\n * (`tracker`) or by passing `options` for the provider to construct. Exactly\n * one of the two is required.\n */\nexport type TrackerProviderProps =\n  | (TrackerProviderBaseProps & {\n      /** Options the provider constructs its own {@link Tracker} from. */\n      options: TrackerOptions;\n      /** Not allowed together with `options`. */\n      tracker?: never;\n    })\n  | (TrackerProviderBaseProps & {\n      /** A pre-built instance owned outside React, exposed via context. */\n      tracker: Tracker;\n      /** Not allowed together with `tracker`. */\n      options?: never;\n    });\n\n/**\n * Owns a {@link Tracker}'s lifecycle and exposes it to the tree via context.\n * Starts the tracker on mount and stops it on unmount, so components never\n * import a module singleton and the tracker is torn down cleanly.\n *\n * `options` (and `tracker`) are read ONCE on mount; later prop changes are\n * ignored. Update identity with `useTracker().setUserId(...)` rather than by\n * changing `options.userId`.\n *\n * @example\n * ```tsx\n * <TrackerProvider\n *   options={{ application: \"my-app\", siteId: \"...\", endpointHost: \"...\" }}\n *   onInit={(t) => t.addEnricher(abTestEnricher)}\n * >\n *   <App />\n * </TrackerProvider>\n * ```\n */\nexport function TrackerProvider(props: TrackerProviderProps): ReactElement {\n  const { children, onInit, autoStart = true } = props;\n\n  // Own the instance once. The lazy initializer keeps its identity stable across\n  // renders, so the context value never changes and consumers do not re-render.\n  const [tracker] = useState<Tracker>(() =>\n    \"tracker\" in props && props.tracker\n      ? props.tracker\n      : new Tracker((props as { options: TrackerOptions }).options),\n  );\n\n  // Capture the mount-time onInit; it runs once, so later identity changes are\n  // irrelevant and it never needs to be an effect dependency.\n  const onInitRef = useRef(onInit);\n  const initialized = useRef(false);\n\n  useEffect(() => {\n    if (!autoStart) return;\n    // StrictMode runs mount -> cleanup -> mount. onInit is ref-guarded to run\n    // once (one-time wiring such as addSink/addEnricher would otherwise run\n    // twice), while start()/stop() are restart-safe and idempotent - so the\n    // tracker ends started with the wiring applied exactly once.\n    if (!initialized.current) {\n      initialized.current = true;\n      onInitRef.current?.(tracker);\n    }\n    tracker.start();\n    return () => {\n      tracker.stop();\n    };\n  }, [tracker, autoStart]);\n\n  return createElement(TrackerContext.Provider, { value: tracker }, children);\n}\n\n/**\n * Returns the {@link Tracker} provided by the nearest {@link TrackerProvider}.\n * Throws when called outside a provider.\n */\nexport function useTracker(): Tracker {\n  const tracker = useContext(TrackerContext);\n  if (!tracker) {\n    throw new Error(\n      \"useTracker must be used within a <TrackerProvider>. Wrap your app in \" +\n        \"<TrackerProvider options={{ application: '...' }}> ... </TrackerProvider>.\",\n    );\n  }\n  return tracker;\n}\n","import { useCallback, useRef } from \"react\";\nimport type { ResultRef } from \"../tracker\";\nimport { useSearchResults } from \"./SearchResults\";\nimport { useTracker } from \"./TrackerProvider\";\n\n/** Options for {@link useResultImpression}. */\nexport type UseResultImpressionOptions = {\n  /** When true, no impression is observed or reported. */\n  disabled?: boolean;\n};\n\n/**\n * Returns a callback ref that reports ONE canonical impression for the result\n * the first time its element becomes visible, attributed to the surrounding\n * {@link SearchResults} context.\n *\n * Fires once per query, not once per component instance: a new `queryId`\n * re-arms the hook, so a card that stays mounted across consecutive searches\n * is counted for each query. (A per-instance one-shot undercounts exactly the\n * products that are returned most often, inflating their CTR.) The Tracker\n * additionally dedupes impressions per `(queryId, objectId)` for its\n * lifetime, so remounted instances - virtualized lists, route re-entry -\n * cannot re-fire a pair this page already reported.\n *\n * Extra keys on `result` are persisted under the event's `event_attributes`\n * (see {@link ResultRef}). Changing only extras does not re-arm the\n * observer; the values current when the impression fires are sent.\n *\n * No-ops when there is no search context (nothing joinable to report), when\n * `disabled`, or where `IntersectionObserver` is unavailable.\n *\n * StrictMode-safe by construction: cleanup is driven by the callback ref\n * itself - React calls it with `null` on detach and re-invokes it when its\n * identity changes - not by an effect whose simulated unmount would\n * disconnect the observer without re-arming it.\n *\n * ```tsx\n * const ref = useResultImpression({ objectId: r.sku, ordinal });\n * return <article ref={ref}>...</article>;\n * ```\n */\nexport function useResultImpression(\n  result: ResultRef,\n  options?: UseResultImpressionOptions,\n): (node: Element | null) => void {\n  const tracker = useTracker();\n  const search = useSearchResults();\n  const firedForQuery = useRef<string | null>(null);\n  const observerRef = useRef<IntersectionObserver | null>(null);\n  // Latest-value ref: extra keys on `result` ride into the fired impression\n  // without being callback deps (an inline extras literal would otherwise\n  // re-arm the observer every render). Identity-forming fields stay as deps.\n  const latestResult = useRef(result);\n  latestResult.current = result;\n\n  const disabled = options?.disabled ?? false;\n  const { objectId, ordinal } = result;\n  const queryId = search?.queryId;\n  const query = search?.query;\n\n  return useCallback(\n    (node: Element | null) => {\n      // Called with the node on attach and null on detach; also re-invoked\n      // when the callback identity changes (e.g. a new queryId arrives).\n      observerRef.current?.disconnect();\n      observerRef.current = null;\n\n      if (!node || disabled || !queryId) return;\n      if (firedForQuery.current === queryId) return;\n      if (typeof IntersectionObserver === \"undefined\") return;\n\n      const observer = new IntersectionObserver(\n        (entries) => {\n          for (const entry of entries) {\n            if (!entry.isIntersecting) continue;\n            if (firedForQuery.current === queryId) continue;\n            firedForQuery.current = queryId;\n\n            const item: ResultRef = {\n              ...latestResult.current,\n              objectId,\n              ordinal,\n            };\n            tracker.trackResultImpression({ items: [item], queryId, query });\n\n            observer.disconnect();\n            observerRef.current = null;\n          }\n        },\n        { threshold: 0 },\n      );\n      observer.observe(node);\n      observerRef.current = observer;\n    },\n    [tracker, objectId, ordinal, queryId, query, disabled],\n  );\n}\n"],"mappings":"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"}

package/dist/react.d.cts

@@ -0,0 +1,139 @@
+/*! @releval/tracker | Apache-2.0 | https://github.com/releval/tracker */
+import { S as EventPosition, _ as Sink, a as TrackResultClickOptions, b as EventAttributes, c as TrackSearchOptions, d as TrackerOptions, i as ResultRef, l as Tracker, o as TrackResultEventOptions, s as TrackResultImpressionOptions, u as TrackerBaseOptions, v as Enricher, w as Logger, x as EventObject, y as Event } from "./ResultImpressionCollector.cjs";
+import { ReactElement, ReactNode } from "react";
+//#region src/react/SearchResults.d.ts
+/** The search that produced the results rendered beneath a {@link SearchResults}. */
+type SearchResultsValue = {
+  /** The server-issued `query_id` for the search. */
+  queryId: string;
+  /** The query text as the user entered it, if known. */
+  query?: string;
+};
+/** Props for {@link SearchResults}. */
+type SearchResultsProps = SearchResultsValue & {
+  /** The results subtree this search context applies to. */
+  children?: ReactNode;
+};
+/**
+ * Declares which search produced the results rendered beneath it - the SPA
+ * twin of `data-query-id` on a server-rendered results container. Result
+ * components read it with {@link useSearchResults} (and
+ * {@link useResultImpression} reads it automatically) instead of threading
+ * `queryId` down as a prop.
+ *
+ * ```tsx
+ * <SearchResults queryId={response.query_id} query={q}>
+ *   {results.map((r, i) => <ResultCard key={r.sku} result={r} ordinal={i + 1} />)}
+ * </SearchResults>
+ * ```
+ */
+declare function SearchResults({ queryId, query, children }: SearchResultsProps): ReactElement;
+/**
+ * The current search context, or null outside a {@link SearchResults} (e.g. a
+ * card rendered on a home page that did not come from a search).
+ */
+declare function useSearchResults(): SearchResultsValue | null;
+//#endregion
+//#region src/react/TrackerProvider.d.ts
+/**
+ * Props shared by both {@link TrackerProviderProps} variants (provide
+ * `options` OR a pre-built `tracker`).
+ */
+interface TrackerProviderBaseProps {
+  /**
+   * Runs exactly once, before the first `start()`. Do one-time wiring here:
+   * `addEnricher()`, `addSink()`. It is guarded so React StrictMode's
+   * double-mount cannot run the wiring twice.
+   */
+  onInit?: (tracker: Tracker) => void;
+  /**
+   * Call `start()` on mount and `stop()` on unmount. Defaults to `true`. Set
+   * `false` when an external owner controls the tracker lifecycle and the
+   * provider is only used to expose the instance via context.
+   */
+  autoStart?: boolean;
+  /** The tree that can read the tracker via {@link useTracker}. */
+  children?: ReactNode;
+}
+/**
+ * Provide the tracker either by handing over an already-constructed instance
+ * (`tracker`) or by passing `options` for the provider to construct. Exactly
+ * one of the two is required.
+ */
+type TrackerProviderProps = (TrackerProviderBaseProps & {
+  /** Options the provider constructs its own {@link Tracker} from. */
+  options: TrackerOptions;
+  /** Not allowed together with `options`. */
+  tracker?: never;
+}) | (TrackerProviderBaseProps & {
+  /** A pre-built instance owned outside React, exposed via context. */
+  tracker: Tracker;
+  /** Not allowed together with `tracker`. */
+  options?: never;
+});
+/**
+ * Owns a {@link Tracker}'s lifecycle and exposes it to the tree via context.
+ * Starts the tracker on mount and stops it on unmount, so components never
+ * import a module singleton and the tracker is torn down cleanly.
+ *
+ * `options` (and `tracker`) are read ONCE on mount; later prop changes are
+ * ignored. Update identity with `useTracker().setUserId(...)` rather than by
+ * changing `options.userId`.
+ *
+ * @example
+ * ```tsx
+ * <TrackerProvider
+ *   options={{ application: "my-app", siteId: "...", endpointHost: "..." }}
+ *   onInit={(t) => t.addEnricher(abTestEnricher)}
+ * >
+ *   <App />
+ * </TrackerProvider>
+ * ```
+ */
+declare function TrackerProvider(props: TrackerProviderProps): ReactElement;
+/**
+ * Returns the {@link Tracker} provided by the nearest {@link TrackerProvider}.
+ * Throws when called outside a provider.
+ */
+declare function useTracker(): Tracker;
+//#endregion
+//#region src/react/useResultImpression.d.ts
+/** Options for {@link useResultImpression}. */
+type UseResultImpressionOptions = {
+  /** When true, no impression is observed or reported. */
+  disabled?: boolean;
+};
+/**
+ * Returns a callback ref that reports ONE canonical impression for the result
+ * the first time its element becomes visible, attributed to the surrounding
+ * {@link SearchResults} context.
+ *
+ * Fires once per query, not once per component instance: a new `queryId`
+ * re-arms the hook, so a card that stays mounted across consecutive searches
+ * is counted for each query. (A per-instance one-shot undercounts exactly the
+ * products that are returned most often, inflating their CTR.) The Tracker
+ * additionally dedupes impressions per `(queryId, objectId)` for its
+ * lifetime, so remounted instances - virtualized lists, route re-entry -
+ * cannot re-fire a pair this page already reported.
+ *
+ * Extra keys on `result` are persisted under the event's `event_attributes`
+ * (see {@link ResultRef}). Changing only extras does not re-arm the
+ * observer; the values current when the impression fires are sent.
+ *
+ * No-ops when there is no search context (nothing joinable to report), when
+ * `disabled`, or where `IntersectionObserver` is unavailable.
+ *
+ * StrictMode-safe by construction: cleanup is driven by the callback ref
+ * itself - React calls it with `null` on detach and re-invokes it when its
+ * identity changes - not by an effect whose simulated unmount would
+ * disconnect the observer without re-arming it.
+ *
+ * ```tsx
+ * const ref = useResultImpression({ objectId: r.sku, ordinal });
+ * return <article ref={ref}>...</article>;
+ * ```
+ */
+declare function useResultImpression(result: ResultRef, options?: UseResultImpressionOptions): (node: Element | null) => void;
+//#endregion
+export { type Enricher, type Event, type EventAttributes, type EventObject, type EventPosition, type Logger, type ResultRef, SearchResults, type SearchResultsProps, type SearchResultsValue, type Sink, type TrackResultClickOptions, type TrackResultEventOptions, type TrackResultImpressionOptions, type TrackSearchOptions, Tracker, type TrackerBaseOptions, type TrackerOptions, TrackerProvider, type TrackerProviderBaseProps, type TrackerProviderProps, type UseResultImpressionOptions, useResultImpression, useSearchResults, useTracker };
+//# sourceMappingURL=react.d.cts.map

package/dist/react.d.mts

@@ -0,0 +1,139 @@
+/*! @releval/tracker | Apache-2.0 | https://github.com/releval/tracker */
+import { S as EventPosition, _ as Sink, a as TrackResultClickOptions, b as EventAttributes, c as TrackSearchOptions, d as TrackerOptions, i as ResultRef, l as Tracker, o as TrackResultEventOptions, s as TrackResultImpressionOptions, u as TrackerBaseOptions, v as Enricher, w as Logger, x as EventObject, y as Event } from "./ResultImpressionCollector.mjs";
+import { ReactElement, ReactNode } from "react";
+//#region src/react/SearchResults.d.ts
+/** The search that produced the results rendered beneath a {@link SearchResults}. */
+type SearchResultsValue = {
+  /** The server-issued `query_id` for the search. */
+  queryId: string;
+  /** The query text as the user entered it, if known. */
+  query?: string;
+};
+/** Props for {@link SearchResults}. */
+type SearchResultsProps = SearchResultsValue & {
+  /** The results subtree this search context applies to. */
+  children?: ReactNode;
+};
+/**
+ * Declares which search produced the results rendered beneath it - the SPA
+ * twin of `data-query-id` on a server-rendered results container. Result
+ * components read it with {@link useSearchResults} (and
+ * {@link useResultImpression} reads it automatically) instead of threading
+ * `queryId` down as a prop.
+ *
+ * ```tsx
+ * <SearchResults queryId={response.query_id} query={q}>
+ *   {results.map((r, i) => <ResultCard key={r.sku} result={r} ordinal={i + 1} />)}
+ * </SearchResults>
+ * ```
+ */
+declare function SearchResults({ queryId, query, children }: SearchResultsProps): ReactElement;
+/**
+ * The current search context, or null outside a {@link SearchResults} (e.g. a
+ * card rendered on a home page that did not come from a search).
+ */
+declare function useSearchResults(): SearchResultsValue | null;
+//#endregion
+//#region src/react/TrackerProvider.d.ts
+/**
+ * Props shared by both {@link TrackerProviderProps} variants (provide
+ * `options` OR a pre-built `tracker`).
+ */
+interface TrackerProviderBaseProps {
+  /**
+   * Runs exactly once, before the first `start()`. Do one-time wiring here:
+   * `addEnricher()`, `addSink()`. It is guarded so React StrictMode's
+   * double-mount cannot run the wiring twice.
+   */
+  onInit?: (tracker: Tracker) => void;
+  /**
+   * Call `start()` on mount and `stop()` on unmount. Defaults to `true`. Set
+   * `false` when an external owner controls the tracker lifecycle and the
+   * provider is only used to expose the instance via context.
+   */
+  autoStart?: boolean;
+  /** The tree that can read the tracker via {@link useTracker}. */
+  children?: ReactNode;
+}
+/**
+ * Provide the tracker either by handing over an already-constructed instance
+ * (`tracker`) or by passing `options` for the provider to construct. Exactly
+ * one of the two is required.
+ */
+type TrackerProviderProps = (TrackerProviderBaseProps & {
+  /** Options the provider constructs its own {@link Tracker} from. */
+  options: TrackerOptions;
+  /** Not allowed together with `options`. */
+  tracker?: never;
+}) | (TrackerProviderBaseProps & {
+  /** A pre-built instance owned outside React, exposed via context. */
+  tracker: Tracker;
+  /** Not allowed together with `tracker`. */
+  options?: never;
+});
+/**
+ * Owns a {@link Tracker}'s lifecycle and exposes it to the tree via context.
+ * Starts the tracker on mount and stops it on unmount, so components never
+ * import a module singleton and the tracker is torn down cleanly.
+ *
+ * `options` (and `tracker`) are read ONCE on mount; later prop changes are
+ * ignored. Update identity with `useTracker().setUserId(...)` rather than by
+ * changing `options.userId`.
+ *
+ * @example
+ * ```tsx
+ * <TrackerProvider
+ *   options={{ application: "my-app", siteId: "...", endpointHost: "..." }}
+ *   onInit={(t) => t.addEnricher(abTestEnricher)}
+ * >
+ *   <App />
+ * </TrackerProvider>
+ * ```
+ */
+declare function TrackerProvider(props: TrackerProviderProps): ReactElement;
+/**
+ * Returns the {@link Tracker} provided by the nearest {@link TrackerProvider}.
+ * Throws when called outside a provider.
+ */
+declare function useTracker(): Tracker;
+//#endregion
+//#region src/react/useResultImpression.d.ts
+/** Options for {@link useResultImpression}. */
+type UseResultImpressionOptions = {
+  /** When true, no impression is observed or reported. */
+  disabled?: boolean;
+};
+/**
+ * Returns a callback ref that reports ONE canonical impression for the result
+ * the first time its element becomes visible, attributed to the surrounding
+ * {@link SearchResults} context.
+ *
+ * Fires once per query, not once per component instance: a new `queryId`
+ * re-arms the hook, so a card that stays mounted across consecutive searches
+ * is counted for each query. (A per-instance one-shot undercounts exactly the
+ * products that are returned most often, inflating their CTR.) The Tracker
+ * additionally dedupes impressions per `(queryId, objectId)` for its
+ * lifetime, so remounted instances - virtualized lists, route re-entry -
+ * cannot re-fire a pair this page already reported.
+ *
+ * Extra keys on `result` are persisted under the event's `event_attributes`
+ * (see {@link ResultRef}). Changing only extras does not re-arm the
+ * observer; the values current when the impression fires are sent.
+ *
+ * No-ops when there is no search context (nothing joinable to report), when
+ * `disabled`, or where `IntersectionObserver` is unavailable.
+ *
+ * StrictMode-safe by construction: cleanup is driven by the callback ref
+ * itself - React calls it with `null` on detach and re-invokes it when its
+ * identity changes - not by an effect whose simulated unmount would
+ * disconnect the observer without re-arming it.
+ *
+ * ```tsx
+ * const ref = useResultImpression({ objectId: r.sku, ordinal });
+ * return <article ref={ref}>...</article>;
+ * ```
+ */
+declare function useResultImpression(result: ResultRef, options?: UseResultImpressionOptions): (node: Element | null) => void;
+//#endregion
+export { type Enricher, type Event, type EventAttributes, type EventObject, type EventPosition, type Logger, type ResultRef, SearchResults, type SearchResultsProps, type SearchResultsValue, type Sink, type TrackResultClickOptions, type TrackResultEventOptions, type TrackResultImpressionOptions, type TrackSearchOptions, Tracker, type TrackerBaseOptions, type TrackerOptions, TrackerProvider, type TrackerProviderBaseProps, type TrackerProviderProps, type UseResultImpressionOptions, useResultImpression, useSearchResults, useTracker };
+//# sourceMappingURL=react.d.mts.map

package/dist/react.mjs

@@ -0,0 +1,174 @@
+"use client";
+/*! @releval/tracker | Apache-2.0 | https://github.com/releval/tracker */
+import { t as Tracker } from "./tracker.mjs";
+import { createContext, createElement, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+//#region src/react/SearchResults.ts
+const SearchResultsContext = createContext(null);
+/**
+* Declares which search produced the results rendered beneath it - the SPA
+* twin of `data-query-id` on a server-rendered results container. Result
+* components read it with {@link useSearchResults} (and
+* {@link useResultImpression} reads it automatically) instead of threading
+* `queryId` down as a prop.
+*
+* ```tsx
+* <SearchResults queryId={response.query_id} query={q}>
+*   {results.map((r, i) => <ResultCard key={r.sku} result={r} ordinal={i + 1} />)}
+* </SearchResults>
+* ```
+*/
+function SearchResults({ queryId, query, children }) {
+	const value = useMemo(() => ({
+		queryId,
+		query
+	}), [queryId, query]);
+	return createElement(SearchResultsContext.Provider, { value }, children);
+}
+/**
+* The current search context, or null outside a {@link SearchResults} (e.g. a
+* card rendered on a home page that did not come from a search).
+*/
+function useSearchResults() {
+	return useContext(SearchResultsContext);
+}
+//#endregion
+//#region src/react/context.ts
+/**
+* Holds the configured {@link Tracker} for a React tree. Provided by
+* {@link TrackerProvider} and read with {@link useTracker}.
+*/
+const TrackerContext = createContext(null);
+//#endregion
+//#region src/react/TrackerProvider.ts
+/**
+* Owns a {@link Tracker}'s lifecycle and exposes it to the tree via context.
+* Starts the tracker on mount and stops it on unmount, so components never
+* import a module singleton and the tracker is torn down cleanly.
+*
+* `options` (and `tracker`) are read ONCE on mount; later prop changes are
+* ignored. Update identity with `useTracker().setUserId(...)` rather than by
+* changing `options.userId`.
+*
+* @example
+* ```tsx
+* <TrackerProvider
+*   options={{ application: "my-app", siteId: "...", endpointHost: "..." }}
+*   onInit={(t) => t.addEnricher(abTestEnricher)}
+* >
+*   <App />
+* </TrackerProvider>
+* ```
+*/
+function TrackerProvider(props) {
+	const { children, onInit, autoStart = true } = props;
+	const [tracker] = useState(() => "tracker" in props && props.tracker ? props.tracker : new Tracker(props.options));
+	const onInitRef = useRef(onInit);
+	const initialized = useRef(false);
+	useEffect(() => {
+		if (!autoStart) return;
+		if (!initialized.current) {
+			var _onInitRef$current;
+			initialized.current = true;
+			(_onInitRef$current = onInitRef.current) === null || _onInitRef$current === void 0 || _onInitRef$current.call(onInitRef, tracker);
+		}
+		tracker.start();
+		return () => {
+			tracker.stop();
+		};
+	}, [tracker, autoStart]);
+	return createElement(TrackerContext.Provider, { value: tracker }, children);
+}
+/**
+* Returns the {@link Tracker} provided by the nearest {@link TrackerProvider}.
+* Throws when called outside a provider.
+*/
+function useTracker() {
+	const tracker = useContext(TrackerContext);
+	if (!tracker) throw new Error("useTracker must be used within a <TrackerProvider>. Wrap your app in <TrackerProvider options={{ application: '...' }}> ... </TrackerProvider>.");
+	return tracker;
+}
+//#endregion
+//#region src/react/useResultImpression.ts
+/**
+* Returns a callback ref that reports ONE canonical impression for the result
+* the first time its element becomes visible, attributed to the surrounding
+* {@link SearchResults} context.
+*
+* Fires once per query, not once per component instance: a new `queryId`
+* re-arms the hook, so a card that stays mounted across consecutive searches
+* is counted for each query. (A per-instance one-shot undercounts exactly the
+* products that are returned most often, inflating their CTR.) The Tracker
+* additionally dedupes impressions per `(queryId, objectId)` for its
+* lifetime, so remounted instances - virtualized lists, route re-entry -
+* cannot re-fire a pair this page already reported.
+*
+* Extra keys on `result` are persisted under the event's `event_attributes`
+* (see {@link ResultRef}). Changing only extras does not re-arm the
+* observer; the values current when the impression fires are sent.
+*
+* No-ops when there is no search context (nothing joinable to report), when
+* `disabled`, or where `IntersectionObserver` is unavailable.
+*
+* StrictMode-safe by construction: cleanup is driven by the callback ref
+* itself - React calls it with `null` on detach and re-invokes it when its
+* identity changes - not by an effect whose simulated unmount would
+* disconnect the observer without re-arming it.
+*
+* ```tsx
+* const ref = useResultImpression({ objectId: r.sku, ordinal });
+* return <article ref={ref}>...</article>;
+* ```
+*/
+function useResultImpression(result, options) {
+	var _options$disabled;
+	const tracker = useTracker();
+	const search = useSearchResults();
+	const firedForQuery = useRef(null);
+	const observerRef = useRef(null);
+	const latestResult = useRef(result);
+	latestResult.current = result;
+	const disabled = (_options$disabled = options === null || options === void 0 ? void 0 : options.disabled) !== null && _options$disabled !== void 0 ? _options$disabled : false;
+	const { objectId, ordinal } = result;
+	const queryId = search === null || search === void 0 ? void 0 : search.queryId;
+	const query = search === null || search === void 0 ? void 0 : search.query;
+	return useCallback((node) => {
+		var _observerRef$current;
+		(_observerRef$current = observerRef.current) === null || _observerRef$current === void 0 || _observerRef$current.disconnect();
+		observerRef.current = null;
+		if (!node || disabled || !queryId) return;
+		if (firedForQuery.current === queryId) return;
+		if (typeof IntersectionObserver === "undefined") return;
+		const observer = new IntersectionObserver((entries) => {
+			for (const entry of entries) {
+				if (!entry.isIntersecting) continue;
+				if (firedForQuery.current === queryId) continue;
+				firedForQuery.current = queryId;
+				const item = {
+					...latestResult.current,
+					objectId,
+					ordinal
+				};
+				tracker.trackResultImpression({
+					items: [item],
+					queryId,
+					query
+				});
+				observer.disconnect();
+				observerRef.current = null;
+			}
+		}, { threshold: 0 });
+		observer.observe(node);
+		observerRef.current = observer;
+	}, [
+		tracker,
+		objectId,
+		ordinal,
+		queryId,
+		query,
+		disabled
+	]);
+}
+//#endregion
+export { SearchResults, Tracker, TrackerProvider, useResultImpression, useSearchResults, useTracker };
+
+//# sourceMappingURL=react.mjs.map