@activescott/analytics 0.2.0 → 0.3.0

package/README.md

@@ -20,34 +20,52 @@ release a matching minor of this package.
 
 Mount it where loader data is available (in React Router v7, that means `App`,
 not `Layout` — `Layout` renders with undefined loader data on error
-boundaries, and error pages intentionally get no pageview):
+boundaries, and error pages intentionally get no pageview).
+
+For zero bundle cost when disabled, use `LazyPostHogProvider`: it renders
+null unless enabled with a key, otherwise suspense-loads the initialized
+tree with posthog-js in its own chunk. Mount it as a STABLE SIBLING of your
+UI — never as a conditional wrapper around it, which would remount the whole
+subtree once the chunk loads:
 
 ```tsx
 // app/root.tsx
-import { PostHogProvider } from "@activescott/analytics"
+import { LazyPostHogProvider } from "@activescott/analytics"
 
 export function App() {
-  const { posthogKey, user } = useLoaderData<typeof loader>()
-  // Dynamic-import the provider module only when a key is configured so
-  // disabled/self-host installs pay zero bundle cost for posthog-js.
-  ...
+  const { posthogKey, isAdmin, user } = useLoaderData<typeof loader>()
+  return (
+    <>
+      <LazyPostHogProvider
+        enabled={posthogKey !== "" && !isAdmin}
+        apiKey={posthogKey || undefined}
+        options={{ api_host: "/ph", ui_host: "https://us.posthog.com" }}
+        user={user ? { distinctId: user.id } : undefined}
+      />
+      <Outlet />
+    </>
+  )
 }
 ```
 
 Identify by stable id only — never pass emails, phone numbers, or other PII in
-`properties` unless your privacy policy explicitly covers it:
+`properties` unless your privacy policy explicitly covers it.
+
+`PostHogProvider` (same props plus `children`) remains for apps that prefer
+a static import and a wrapping provider.
+
+### Custom events
+
+Capture through `captureAnalyticsEvent` or the `useAnalyticsCapture` hook —
+both read the client the provider registers on init, so they work anywhere
+without a provider ancestor, and drop while disabled or still loading:
 
 ```tsx
-<PostHogProvider
-  apiKey={posthogKey}
-  options={{ api_host: "/ph", ui_host: "https://us.posthog.com" }}
-  user={user ? { distinctId: user.id } : undefined}
->
-  ...
-</PostHogProvider>
-```
+import { useAnalyticsCapture } from "@activescott/analytics"
 
-With no `apiKey` the provider renders children with zero PostHog code paths.
+const capture = useAnalyticsCapture()
+capture("search_results_shown", { result_count: 2 })
+```
 
 ### 2. Add the reverse proxy route
 
@@ -86,6 +104,14 @@ That's it! PostHog will now:
 - Identify logged-in users by id
 - Receive events through your own domain (`/ph/*`)
 
+### Deriving sibling origins
+
+`@activescott/analytics/hosts` exports the pure helpers `posthogAssetsHost`
+and `posthogUiHost`, which map a PostHog API origin to its assets and app-UI
+siblings (`<region>.i.posthog.com` → `<region>-assets.i.posthog.com` /
+`<region>.posthog.com`; anything else passes through unchanged) — so a
+deployment carries one host knob instead of three.
+
 ## Versioning
 
 Independent plain-npm versions with git tags of the form `analytics@<version>`

package/dist/capture-client.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Registry bridging the initialized posthog-js client to code that cannot
+ * (or should not) sit under the provider's React context.
+ *
+ * LazyPostHogProvider mounts childless as a stable sibling of the app UI —
+ * conditionally wrapping UI would remount the subtree when the chunk loads —
+ * so custom events cannot reach the client through context. Instead the
+ * registrar inside the initialized tree publishes the bound capture here on
+ * mount (and clears it on unmount); captureAnalyticsEvent and
+ * useAnalyticsCapture read it back. Unregistered (disabled, or not yet
+ * loaded) captures are dropped, never queued: analytics must not delay
+ * interaction.
+ */
+export type AnalyticsCapture = (event: string, properties?: Record<string, unknown>) => void;
+/**
+ * Publishes (or clears, with null) the bound capture function. Called by the
+ * registrar inside the initialized provider tree; package-internal.
+ */
+export declare function setCaptureClient(implementation: AnalyticsCapture | null): void;
+/**
+ * Fire-and-forget event capture. Drops when analytics is disabled or the
+ * client has not initialized yet, and never throws: a capture failure must
+ * not break the UI.
+ */
+export declare function captureAnalyticsEvent(event: string, properties?: Record<string, unknown>): void;
+//# sourceMappingURL=capture-client.d.ts.map

package/dist/capture-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-client.d.ts","sourceRoot":"","sources":["../src/capture-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAC7B,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KACjC,IAAI,CAAA;AAIT;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,cAAc,EAAE,gBAAgB,GAAG,IAAI,GACtC,IAAI,CAEN;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,IAAI,CAMN"}

package/dist/capture-client.js

@@ -0,0 +1,35 @@
+/**
+ * Registry bridging the initialized posthog-js client to code that cannot
+ * (or should not) sit under the provider's React context.
+ *
+ * LazyPostHogProvider mounts childless as a stable sibling of the app UI —
+ * conditionally wrapping UI would remount the subtree when the chunk loads —
+ * so custom events cannot reach the client through context. Instead the
+ * registrar inside the initialized tree publishes the bound capture here on
+ * mount (and clears it on unmount); captureAnalyticsEvent and
+ * useAnalyticsCapture read it back. Unregistered (disabled, or not yet
+ * loaded) captures are dropped, never queued: analytics must not delay
+ * interaction.
+ */
+let captureImplementation = null;
+/**
+ * Publishes (or clears, with null) the bound capture function. Called by the
+ * registrar inside the initialized provider tree; package-internal.
+ */
+export function setCaptureClient(implementation) {
+    captureImplementation = implementation;
+}
+/**
+ * Fire-and-forget event capture. Drops when analytics is disabled or the
+ * client has not initialized yet, and never throws: a capture failure must
+ * not break the UI.
+ */
+export function captureAnalyticsEvent(event, properties) {
+    try {
+        captureImplementation?.(event, properties);
+    }
+    catch {
+        // Dropped by design.
+    }
+}
+//# sourceMappingURL=capture-client.js.map

package/dist/capture-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-client.js","sourceRoot":"","sources":["../src/capture-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,IAAI,qBAAqB,GAA4B,IAAI,CAAA;AAEzD;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,cAAuC;IAEvC,qBAAqB,GAAG,cAAc,CAAA;AACxC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAa,EACb,UAAoC;IAEpC,IAAI,CAAC;QACH,qBAAqB,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,qBAAqB;IACvB,CAAC;AACH,CAAC"}

package/dist/capture-registrar.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Publishes the initialized client's bound capture into the module registry
+ * (and clears it on unmount) so captureAnalyticsEvent / useAnalyticsCapture
+ * work without a provider ancestor. Renders nothing; mount once inside the
+ * initialized provider tree.
+ */
+export declare function CaptureRegistrar(): null;
+//# sourceMappingURL=capture-registrar.d.ts.map

package/dist/capture-registrar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-registrar.d.ts","sourceRoot":"","sources":["../src/capture-registrar.tsx"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,wBAAgB,gBAAgB,SAa/B"}

package/dist/capture-registrar.js

@@ -0,0 +1,20 @@
+import { useEffect } from "react";
+import { usePostHog } from "posthog-js/react";
+import { setCaptureClient } from "./capture-client.js";
+/**
+ * Publishes the initialized client's bound capture into the module registry
+ * (and clears it on unmount) so captureAnalyticsEvent / useAnalyticsCapture
+ * work without a provider ancestor. Renders nothing; mount once inside the
+ * initialized provider tree.
+ */
+export function CaptureRegistrar() {
+    const posthog = usePostHog();
+    useEffect(() => {
+        setCaptureClient((event, properties) => posthog.capture(event, properties));
+        return () => {
+            setCaptureClient(null);
+        };
+    }, [posthog]);
+    return null;
+}
+//# sourceMappingURL=capture-registrar.js.map

package/dist/capture-registrar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-registrar.js","sourceRoot":"","sources":["../src/capture-registrar.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAEtD;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,OAAO,GAAG,UAAU,EAAE,CAAA;IAE5B,SAAS,CAAC,GAAG,EAAE;QACb,gBAAgB,CAAC,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,CACrC,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,UAAU,CAAC,CACnC,CAAA;QACD,OAAO,GAAG,EAAE;YACV,gBAAgB,CAAC,IAAI,CAAC,CAAA;QACxB,CAAC,CAAA;IACH,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAA;IAEb,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/hosts.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Derives the sibling PostHog origins from the configured API origin, so a
+ * deployment carries one host knob instead of three.
+ *
+ * PostHog cloud serves each region from `<region>.i.posthog.com` (events),
+ * `<region>-assets.i.posthog.com` (static assets) and `<region>.posthog.com`
+ * (app UI, the posthog-js `ui_host`). Any other origin — a self-hosted
+ * instance, a future region layout — is returned unchanged for both, which
+ * keeps proxy and client on the one configured host.
+ */
+/**
+ * Returns the static-assets origin for a PostHog API origin.
+ */
+export declare function posthogAssetsHost(apiHost: string): string;
+/**
+ * Returns the app-UI origin for a PostHog API origin (the `ui_host`
+ * posthog-js option).
+ */
+export declare function posthogUiHost(apiHost: string): string;
+//# sourceMappingURL=hosts.d.ts.map

package/dist/hosts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosts.d.ts","sourceRoot":"","sources":["../src/hosts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGzD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGrD"}

package/dist/hosts.js

@@ -0,0 +1,37 @@
+/**
+ * Derives the sibling PostHog origins from the configured API origin, so a
+ * deployment carries one host knob instead of three.
+ *
+ * PostHog cloud serves each region from `<region>.i.posthog.com` (events),
+ * `<region>-assets.i.posthog.com` (static assets) and `<region>.posthog.com`
+ * (app UI, the posthog-js `ui_host`). Any other origin — a self-hosted
+ * instance, a future region layout — is returned unchanged for both, which
+ * keeps proxy and client on the one configured host.
+ */
+/**
+ * Returns the static-assets origin for a PostHog API origin.
+ */
+export function posthogAssetsHost(apiHost) {
+    const region = posthogCloudRegion(apiHost);
+    return region ? `https://${region}-assets.i.posthog.com` : apiHost;
+}
+/**
+ * Returns the app-UI origin for a PostHog API origin (the `ui_host`
+ * posthog-js option).
+ */
+export function posthogUiHost(apiHost) {
+    const region = posthogCloudRegion(apiHost);
+    return region ? `https://${region}.posthog.com` : apiHost;
+}
+function posthogCloudRegion(apiHost) {
+    let hostname;
+    try {
+        hostname = new URL(apiHost).hostname;
+    }
+    catch {
+        return null;
+    }
+    const match = /^([a-z0-9-]+)\.i\.posthog\.com$/.exec(hostname);
+    return match ? match[1] : null;
+}
+//# sourceMappingURL=hosts.js.map

package/dist/hosts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosts.js","sourceRoot":"","sources":["../src/hosts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,MAAM,MAAM,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAA;IAC1C,OAAO,MAAM,CAAC,CAAC,CAAC,WAAW,MAAM,uBAAuB,CAAC,CAAC,CAAC,OAAO,CAAA;AACpE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,MAAM,MAAM,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAA;IAC1C,OAAO,MAAM,CAAC,CAAC,CAAC,WAAW,MAAM,cAAc,CAAC,CAAC,CAAC,OAAO,CAAA;AAC3D,CAAC;AAED,SAAS,kBAAkB,CAAC,OAAe;IACzC,IAAI,QAAgB,CAAA;IACpB,IAAI,CAAC;QACH,QAAQ,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAA;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;IACD,MAAM,KAAK,GAAG,iCAAiC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IAC9D,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;AAChC,CAAC"}

package/dist/index.d.ts

@@ -1,4 +1,7 @@
 export { PostHogProvider } from "./post-hog-provider.js";
 export { PostHogPageviewTracker } from "./post-hog-pageview-tracker.js";
 export { PostHogIdentifier } from "./post-hog-identifier.js";
+export { LazyPostHogProvider, type LazyPostHogProviderProps, } from "./post-hog-lazy-provider.js";
+export { captureAnalyticsEvent, type AnalyticsCapture, } from "./capture-client.js";
+export { useAnalyticsCapture } from "./use-analytics-capture.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAA;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAA;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,EACL,mBAAmB,EACnB,KAAK,wBAAwB,GAC9B,MAAM,6BAA6B,CAAA;AACpC,OAAO,EACL,qBAAqB,EACrB,KAAK,gBAAgB,GACtB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA"}

package/dist/index.js

@@ -1,4 +1,7 @@
 export { PostHogProvider } from "./post-hog-provider.js";
 export { PostHogPageviewTracker } from "./post-hog-pageview-tracker.js";
 export { PostHogIdentifier } from "./post-hog-identifier.js";
+export { LazyPostHogProvider, } from "./post-hog-lazy-provider.js";
+export { captureAnalyticsEvent, } from "./capture-client.js";
+export { useAnalyticsCapture } from "./use-analytics-capture.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAA;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAA;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,EACL,mBAAmB,GAEpB,MAAM,6BAA6B,CAAA;AACpC,OAAO,EACL,qBAAqB,GAEtB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA"}

package/dist/post-hog-init.d.ts

@@ -0,0 +1,19 @@
+import type { PostHogConfig } from "posthog-js";
+interface PostHogInitProps {
+    apiKey: string;
+    options?: Partial<PostHogConfig>;
+    user?: {
+        distinctId: string;
+        properties?: Record<string, unknown>;
+    };
+    children?: React.ReactNode;
+}
+/**
+ * The initialized PostHog tree: context provider, SPA pageview tracking,
+ * user identification, and capture registration. Lives in its own module so
+ * React.lazy splits it (and posthog-js with it) into a separate chunk —
+ * mount LazyPostHogProvider, not this, which guarantees the split point.
+ */
+export declare function PostHogInit({ apiKey, options, user, children, }: PostHogInitProps): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=post-hog-init.d.ts.map

package/dist/post-hog-init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-hog-init.d.ts","sourceRoot":"","sources":["../src/post-hog-init.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAM/C,UAAU,gBAAgB;IACxB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAA;IAChC,IAAI,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAA;IACnE,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC3B;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAC1B,MAAM,EACN,OAAO,EACP,IAAI,EACJ,QAAQ,GACT,EAAE,gBAAgB,+BAkBlB"}

package/dist/post-hog-init.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { PostHogProvider as PHProvider } from "posthog-js/react";
+import { PostHogIdentifier } from "./post-hog-identifier.js";
+import { PostHogPageviewTracker } from "./post-hog-pageview-tracker.js";
+import { CaptureRegistrar } from "./capture-registrar.js";
+/**
+ * The initialized PostHog tree: context provider, SPA pageview tracking,
+ * user identification, and capture registration. Lives in its own module so
+ * React.lazy splits it (and posthog-js with it) into a separate chunk —
+ * mount LazyPostHogProvider, not this, which guarantees the split point.
+ */
+export function PostHogInit({ apiKey, options, user, children, }) {
+    return (_jsxs(PHProvider, { apiKey: apiKey, options: {
+            ...options,
+            capture_pageview: false,
+        }, children: [_jsx(PostHogPageviewTracker, {}), _jsx(PostHogIdentifier, { distinctId: user?.distinctId, properties: user?.properties }), _jsx(CaptureRegistrar, {}), children] }));
+}
+//# sourceMappingURL=post-hog-init.js.map

package/dist/post-hog-init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-hog-init.js","sourceRoot":"","sources":["../src/post-hog-init.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,eAAe,IAAI,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAA;AACvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AASzD;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,EAC1B,MAAM,EACN,OAAO,EACP,IAAI,EACJ,QAAQ,GACS;IACjB,OAAO,CACL,MAAC,UAAU,IACT,MAAM,EAAE,MAAM,EACd,OAAO,EAAE;YACP,GAAG,OAAO;YACV,gBAAgB,EAAE,KAAK;SACxB,aAED,KAAC,sBAAsB,KAAG,EAC1B,KAAC,iBAAiB,IAChB,UAAU,EAAE,IAAI,EAAE,UAAU,EAC5B,UAAU,EAAE,IAAI,EAAE,UAAU,GAC5B,EACF,KAAC,gBAAgB,KAAG,EACnB,QAAQ,IACE,CACd,CAAA;AACH,CAAC"}

package/dist/post-hog-lazy-provider.d.ts

@@ -0,0 +1,29 @@
+import type { PostHogConfig } from "posthog-js";
+export interface LazyPostHogProviderProps {
+    /**
+     * Whether capture runs at all. The containing app decides — typically
+     * `apiKey` presence plus its own exclusions (e.g. admin traffic). When
+     * false (or with no key) this renders null with zero PostHog code paths,
+     * and the posthog-js chunk is never fetched.
+     */
+    enabled: boolean;
+    apiKey?: string;
+    options?: Partial<PostHogConfig>;
+    user?: {
+        distinctId: string;
+        properties?: Record<string, unknown>;
+    };
+}
+/**
+ * PostHog with zero bundle cost when disabled. Renders null unless enabled
+ * with a key; otherwise suspense-loads the initialized tree — posthog-js
+ * travels in its own chunk, fetched only then.
+ *
+ * Mount as a STABLE SIBLING of your UI (e.g. beside `<Outlet/>`), never as a
+ * conditional wrapper around it: swapping a wrapper in after the chunk loads
+ * remounts the whole subtree. Custom events go through captureAnalyticsEvent
+ * / useAnalyticsCapture (registered on init), so no context ancestor is
+ * needed.
+ */
+export declare function LazyPostHogProvider({ enabled, apiKey, options, user, }: LazyPostHogProviderProps): import("react").JSX.Element | null;
+//# sourceMappingURL=post-hog-lazy-provider.d.ts.map

package/dist/post-hog-lazy-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-hog-lazy-provider.d.ts","sourceRoot":"","sources":["../src/post-hog-lazy-provider.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAQ/C,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAA;IAChC,IAAI,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAA;CACpE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,OAAO,EACP,MAAM,EACN,OAAO,EACP,IAAI,GACL,EAAE,wBAAwB,sCAS1B"}

package/dist/post-hog-lazy-provider.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Suspense, lazy } from "react";
+const PostHogInit = lazy(() => import("./post-hog-init.js").then((module) => ({
+    default: module.PostHogInit,
+})));
+/**
+ * PostHog with zero bundle cost when disabled. Renders null unless enabled
+ * with a key; otherwise suspense-loads the initialized tree — posthog-js
+ * travels in its own chunk, fetched only then.
+ *
+ * Mount as a STABLE SIBLING of your UI (e.g. beside `<Outlet/>`), never as a
+ * conditional wrapper around it: swapping a wrapper in after the chunk loads
+ * remounts the whole subtree. Custom events go through captureAnalyticsEvent
+ * / useAnalyticsCapture (registered on init), so no context ancestor is
+ * needed.
+ */
+export function LazyPostHogProvider({ enabled, apiKey, options, user, }) {
+    if (!enabled || !apiKey) {
+        return null;
+    }
+    return (_jsx(Suspense, { fallback: null, children: _jsx(PostHogInit, { apiKey: apiKey, options: options, user: user }) }));
+}
+//# sourceMappingURL=post-hog-lazy-provider.js.map

package/dist/post-hog-lazy-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-hog-lazy-provider.js","sourceRoot":"","sources":["../src/post-hog-lazy-provider.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,OAAO,CAAA;AAGtC,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,CAC5B,MAAM,CAAC,oBAAoB,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC7C,OAAO,EAAE,MAAM,CAAC,WAAW;CAC5B,CAAC,CAAC,CACJ,CAAA;AAeD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAClC,OAAO,EACP,MAAM,EACN,OAAO,EACP,IAAI,GACqB;IACzB,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC;QACxB,OAAO,IAAI,CAAA;IACb,CAAC;IACD,OAAO,CACL,KAAC,QAAQ,IAAC,QAAQ,EAAE,IAAI,YACtB,KAAC,WAAW,IAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,GAAI,GACpD,CACZ,CAAA;AACH,CAAC"}

package/dist/post-hog-provider.d.ts

@@ -6,7 +6,7 @@ interface PostHogProviderProps {
         distinctId: string;
         properties?: Record<string, unknown>;
     };
-    children: React.ReactNode;
+    children?: React.ReactNode;
 }
 /**
  * All-in-one PostHog provider for React Router apps.

package/dist/post-hog-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"post-hog-provider.d.ts","sourceRoot":"","sources":["../src/post-hog-provider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAK/C,UAAU,oBAAoB;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAA;IAChC,IAAI,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAA;IACnE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,EAC9B,MAAM,EACN,OAAO,EACP,IAAI,EACJ,QAAQ,GACT,EAAE,oBAAoB,+BAqBtB"}
+{"version":3,"file":"post-hog-provider.d.ts","sourceRoot":"","sources":["../src/post-hog-provider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAK/C,UAAU,oBAAoB;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAA;IAChC,IAAI,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAA;IAKnE,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,EAC9B,MAAM,EACN,OAAO,EACP,IAAI,EACJ,QAAQ,GACT,EAAE,oBAAoB,+BAqBtB"}

package/dist/post-hog-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"post-hog-provider.js","sourceRoot":"","sources":["../src/post-hog-provider.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,eAAe,IAAI,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAA;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAS5D;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,EAC9B,MAAM,EACN,OAAO,EACP,IAAI,EACJ,QAAQ,GACa;IACrB,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,4BAAG,QAAQ,GAAI,CAAA;IACxB,CAAC;IAED,OAAO,CACL,MAAC,UAAU,IACT,MAAM,EAAE,MAAM,EACd,OAAO,EAAE;YACP,GAAG,OAAO;YACV,gBAAgB,EAAE,KAAK;SACxB,aAED,KAAC,sBAAsB,KAAG,EAC1B,KAAC,iBAAiB,IAChB,UAAU,EAAE,IAAI,EAAE,UAAU,EAC5B,UAAU,EAAE,IAAI,EAAE,UAAU,GAC5B,EACD,QAAQ,IACE,CACd,CAAA;AACH,CAAC"}
+{"version":3,"file":"post-hog-provider.js","sourceRoot":"","sources":["../src/post-hog-provider.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,eAAe,IAAI,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAA;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAa5D;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,EAC9B,MAAM,EACN,OAAO,EACP,IAAI,EACJ,QAAQ,GACa;IACrB,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,4BAAG,QAAQ,GAAI,CAAA;IACxB,CAAC;IAED,OAAO,CACL,MAAC,UAAU,IACT,MAAM,EAAE,MAAM,EACd,OAAO,EAAE;YACP,GAAG,OAAO;YACV,gBAAgB,EAAE,KAAK;SACxB,aAED,KAAC,sBAAsB,KAAG,EAC1B,KAAC,iBAAiB,IAChB,UAAU,EAAE,IAAI,EAAE,UAAU,EAC5B,UAAU,EAAE,IAAI,EAAE,UAAU,GAC5B,EACD,QAAQ,IACE,CACd,CAAA;AACH,CAAC"}

package/dist/use-analytics-capture.d.ts

@@ -0,0 +1,9 @@
+import { type AnalyticsCapture } from "./capture-client.js";
+/**
+ * Returns the analytics capture function. Stable across renders; backed by
+ * the initialized provider's registered client, so it works anywhere in the
+ * app without a provider ancestor. Drops events while analytics is disabled
+ * or the client chunk is still loading.
+ */
+export declare function useAnalyticsCapture(): AnalyticsCapture;
+//# sourceMappingURL=use-analytics-capture.d.ts.map

package/dist/use-analytics-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-analytics-capture.d.ts","sourceRoot":"","sources":["../src/use-analytics-capture.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,qBAAqB,CAAA;AAE5B;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,gBAAgB,CAItD"}

package/dist/use-analytics-capture.js

@@ -0,0 +1,14 @@
+import { useCallback } from "react";
+import { captureAnalyticsEvent, } from "./capture-client.js";
+/**
+ * Returns the analytics capture function. Stable across renders; backed by
+ * the initialized provider's registered client, so it works anywhere in the
+ * app without a provider ancestor. Drops events while analytics is disabled
+ * or the client chunk is still loading.
+ */
+export function useAnalyticsCapture() {
+    return useCallback((event, properties) => {
+        captureAnalyticsEvent(event, properties);
+    }, []);
+}
+//# sourceMappingURL=use-analytics-capture.js.map

package/dist/use-analytics-capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-analytics-capture.js","sourceRoot":"","sources":["../src/use-analytics-capture.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAA;AACnC,OAAO,EACL,qBAAqB,GAEtB,MAAM,qBAAqB,CAAA;AAE5B;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,WAAW,CAAC,CAAC,KAAa,EAAE,UAAoC,EAAE,EAAE;QACzE,qBAAqB,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;IAC1C,CAAC,EAAE,EAAE,CAAC,CAAA;AACR,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@activescott/analytics",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "PostHog analytics integration for React Router apps — provider, SPA pageview tracking, user identification, and reverse proxy helper",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,6 +13,10 @@
     "./proxy": {
       "types": "./dist/proxy.d.ts",
       "import": "./dist/proxy.js"
+    },
+    "./hosts": {
+      "types": "./dist/hosts.d.ts",
+      "import": "./dist/hosts.js"
     }
   },
   "files": [
@@ -35,7 +39,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/activescott/js-utils.git",
+    "url": "git+https://github.com/activescott/js-utils.git",
     "directory": "packages/analytics"
   },
   "peerDependencies": {
@@ -44,10 +48,14 @@
     "react-router": "^7.0.0"
   },
   "devDependencies": {
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
     "@types/node": "^22",
     "@types/react": "^19.2.14",
+    "jsdom": "^27.4.0",
     "posthog-js": "^1.351.4",
-    "react": "^19.2.4",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
     "react-router": "^7.10.1",
     "typescript": "^5.9.3",
     "vitest": "4.1.10"