@serge-ai/react 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Superstellar LLC
+
+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,95 @@
+# @serge-ai/react
+
+> **No cookies. No localStorage by default. No consent banner required.** ePrivacy Art. 5(3) compliant by construction.
+
+React integration for [Serge](https://serge.ai) — drop-in `<Analytics />` and `<DetectionPixel />` components for catching AI-agent sessions on your site.
+
+```sh
+pnpm add @serge-ai/react
+# or
+npm install @serge-ai/react
+```
+
+For Next.js App Router consumers → use **[`@serge-ai/nextjs`](https://www.npmjs.com/package/@serge-ai/nextjs)** instead — it auto-tracks route changes via `usePathname` / `useSearchParams`.
+
+For vanilla JS / Vue / Svelte → use **[`@serge-ai/js`](https://www.npmjs.com/package/@serge-ai/js)**.
+
+## Quick start
+
+```tsx
+import { Analytics, DetectionPixel, track } from '@serge-ai/react'
+
+export function App() {
+  return (
+    <>
+      <Analytics token="srg_pub_xxxxxxxxxxxxxxxxxxxxxxxxxx" />
+      <DetectionPixel token="srg_pub_xxxxxxxxxxxxxxxxxxxxxxxxxx" />
+      <button onClick={() => track('signup_clicked')}>Sign up</button>
+    </>
+  )
+}
+```
+
+`<Analytics />` catches JS-driven agents (browser extensions, browser-use, Operator, ChatGPT Atlas, Claude Computer Use). `<DetectionPixel />` catches HTML-only agents that don't execute JS (ChatGPT-User, Claude-User, GPTBot, ClaudeBot, PerplexityBot). The pixel is what makes Serge see traffic that PostHog, GA4, and Hotjar miss entirely.
+
+## Components
+
+### `<Analytics />`
+
+Drop-in component. Calls `init()` once on mount, returns `null`.
+
+```tsx
+<Analytics
+  token="srg_pub_xxx"
+  apiBase="https://serge.ai"  // optional first-party proxy override
+  debug={false}                // optional
+  requireConsent={false}       // optional
+/>
+```
+
+Re-renders only re-call `init()` if the `token` changes. Other config edits require a remount — the tracker's runtime state is module-level and changing flags mid-session produces unpredictable behavior.
+
+### `<DetectionPixel />`
+
+Renders an invisible 1×1 GIF that catches non-JS agents. Drop next to `<Analytics />`.
+
+```tsx
+<DetectionPixel
+  token="srg_pub_xxx"
+  apiBase="https://serge.ai"   // optional
+/>
+```
+
+The image fetch fires from the agent direct to the Serge ingest endpoint with the agent's `User-Agent` intact. Serge's server matches the UA against known agent patterns (ChatGPT-User, Claude-User, GPTBot, ClaudeBot, PerplexityBot, …), validates the `Referer` against your registered domain, then writes the hit to your dashboard. **No competing analytics SDK ships this.**
+
+## API re-exports
+
+```tsx
+import { init, track, consent, pageview } from '@serge-ai/react'
+```
+
+These are re-exports from `@serge-ai/js` so consumers can import everything from one path. See **[`@serge-ai/js` docs](https://www.npmjs.com/package/@serge-ai/js)** for the full reference.
+
+## SSR safety
+
+Every browser-API access is guarded inside `useEffect`. Components are marked `'use client'`. Safe to import from server components, RSC layouts, Edge runtimes.
+
+## Why no `<TrackerProvider>` / `useTracker()` hook?
+
+PostHog tried both patterns; the convergent industry pattern is the singleton `init()` + import-anywhere model (Sentry, Mixpanel, Amplitude, Segment all do this). The provider+hook adds context-render overhead without giving the consumer anything they couldn't get from the singleton import. We dropped them in 0.2.0.
+
+## Why no `identify()`?
+
+Serge measures **agent sessions**, not end-users. Per-user identity is anti-goal for cookieless agent analytics. See `@serge-ai/js` README for the reasoning.
+
+## React versions
+
+`react@^18 || ^19` (peer dependency). Works in both 18 and 19.
+
+## Bundle size
+
+Under 6 KB gzipped (excluding `react` and `@serge-ai/js`, which the host already provides). [`size-limit`](https://github.com/ai/size-limit) enforces this in CI.
+
+## License
+
+MIT © Superstellar LLC. See [LICENSE](./LICENSE).

package/dist/index.cjs

@@ -0,0 +1,4 @@
+"use client";
+'use strict';var react=require('react'),js=require('@serge-ai/js'),jsxRuntime=require('react/jsx-runtime');function u({token:e,...t}){return react.useEffect(()=>{js.init(e,t);},[e]),null}var r={position:"absolute",width:1,height:1,opacity:0,pointerEvents:"none",border:"none"};function y({token:e,apiBase:t}){let n=`${(t??"https://serge.ai").replace(/\/$/,"")}/api/ingest/pixel?s=${encodeURIComponent(e)}`;return jsxRuntime.jsx("img",{src:n,width:1,height:1,alt:"","aria-hidden":"true",loading:"eager",decoding:"async",referrerPolicy:"no-referrer-when-downgrade",style:r})}
+Object.defineProperty(exports,"consent",{enumerable:true,get:function(){return js.consent}});Object.defineProperty(exports,"init",{enumerable:true,get:function(){return js.init}});Object.defineProperty(exports,"pageview",{enumerable:true,get:function(){return js.pageview}});Object.defineProperty(exports,"track",{enumerable:true,get:function(){return js.track}});exports.Analytics=u;exports.DetectionPixel=y;//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.tsx"],"names":["Analytics","token","options","useEffect","init","PIXEL_STYLE","DetectionPixel","apiBase","src","jsx"],"mappings":"2GAwEO,SAASA,EAAU,CAAE,KAAA,CAAAC,CAAAA,CAAO,GAAGC,CAAQ,CAAA,CAAyB,CACrE,OAAAC,eAAAA,CAAU,IAAM,CACdC,OAAAA,CAAKH,EAAOC,CAAO,EAErB,CAAA,CAAG,CAACD,CAAK,CAAC,EAEH,IACT,CAkCA,IAAMI,CAAAA,CAA6B,CACjC,SAAU,UAAA,CACV,KAAA,CAAO,CAAA,CACP,MAAA,CAAQ,CAAA,CACR,OAAA,CAAS,EACT,aAAA,CAAe,MAAA,CACf,OAAQ,MACV,CAAA,CAEO,SAASC,CAAAA,CAAe,CAAE,KAAA,CAAAL,CAAAA,CAAO,OAAA,CAAAM,CAAQ,EAA2C,CAEzF,IAAMC,EAAM,CAAA,EAAA,CADED,CAAAA,EAAW,oBAAoB,OAAA,CAAQ,KAAA,CAAO,EAAE,CAC3C,CAAA,oBAAA,EAAuB,kBAAA,CAAmBN,CAAK,CAAC,CAAA,CAAA,CACnE,OAEEQ,cAAAA,CAAC,KAAA,CAAA,CACC,IAAKD,CAAAA,CACL,KAAA,CAAO,CAAA,CACP,MAAA,CAAQ,CAAA,CACR,GAAA,CAAI,GACJ,aAAA,CAAY,MAAA,CACZ,QAAQ,OAAA,CACR,QAAA,CAAS,QACT,cAAA,CAAe,4BAAA,CACf,KAAA,CAAOH,CAAAA,CACT,CAEJ","file":"index.cjs","sourcesContent":["/**\n * @serge-ai/react — React integration.\n *\n * Two components, both safe for SSR (no module-level browser access,\n * all side effects inside `useEffect`):\n *\n * 1. `<Analytics />` — drop in once at the root of your app to capture\n *    JS-driven agent sessions (snippet equivalent):\n *\n *      import { Analytics } from '@serge-ai/react'\n *      export default function App() {\n *        return (\n *          <>\n *            <Analytics token=\"srg_pub_xxx\" />\n *            <YourApp />\n *          </>\n *        )\n *      }\n *\n * 2. `<DetectionPixel />` — drop next to `<Analytics />` to also catch\n *    non-JS agents (ChatGPT-User, Claude-User, GPTBot, ClaudeBot,\n *    PerplexityBot — agents that fetch HTML and follow `<img>` but\n *    don't execute JS). Renders an invisible 1×1 GIF pointing at our\n *    server. The image fetch fires from the agent direct to serge.ai\n *    with the agent's User-Agent intact:\n *\n *      <Analytics token=\"srg_pub_xxx\" />\n *      <DetectionPixel token=\"srg_pub_xxx\" />\n *\n *    PostHog has no equivalent — JS-only collection is the industry\n *    standard. Serge ships the pixel on purpose because non-JS agents\n *    are a meaningful and growing share of agent traffic.\n *\n * Re-exports the core `track` / `consent` / `pageview` so consumers\n * can import everything from the React subpath if they prefer one\n * import path. (`identify` is intentionally NOT exported — Serge\n * classifies sessions, not end-users; per-user identity is anti-goal\n * for cookieless agent analytics.)\n */\n\n'use client'\n\nimport { useEffect, type CSSProperties } from 'react'\nimport {\n  init,\n  track,\n  consent,\n  pageview,\n  type InitOptions,\n  type ConsentValue,\n} from '@serge-ai/js'\n\nexport { init, track, consent, pageview }\nexport type { InitOptions, ConsentValue }\n\n/* ── <Analytics /> ────────────────────────────────────────────────\n *\n * Calls `init()` once on mount with the props as the token + options,\n * returns nothing renderable. Same shape as @vercel/analytics' drop-in\n * pattern — match it exactly so consumers swapping between SDKs see\n * the same component contract.\n *\n * Re-renders only re-call `init()` if the token changes. Other config\n * edits (debug, requireConsent) require a remount — the tracker's\n * runtime state is module-level, and changing flags mid-session\n * produces unpredictable behavior. */\n\nexport interface AnalyticsProps extends InitOptions {\n  /** Public token from the Serge dashboard (`srg_pub_*`). */\n  token: string\n}\n\nexport function Analytics({ token, ...options }: AnalyticsProps): null {\n  useEffect(() => {\n    init(token, options)\n    /* eslint-disable-next-line react-hooks/exhaustive-deps -- intentional: only token triggers re-init */\n  }, [token])\n\n  return null\n}\n\n/* ── <DetectionPixel /> ───────────────────────────────────────────\n *\n * Renders a 1×1 invisible `<img>` whose `src` points at the Serge\n * pixel ingest endpoint. Non-JS agents (HTML-only crawlers) follow\n * the `<img>` reference and trigger the request — Serge captures\n * their User-Agent and records the visit.\n *\n * Implementation notes:\n *   - The image is positioned absolutely with size-1 + opacity-0 so\n *     it doesn't take any visible space or affect layout.\n *   - `aria-hidden=\"true\"` + empty `alt=\"\"` keeps it invisible to\n *     assistive tech.\n *   - `loading=\"eager\"` so it fires immediately on render — lazy\n *     loading would defeat the detection purpose entirely.\n *   - `referrerPolicy=\"no-referrer-when-downgrade\"` matches what\n *     serge.ai itself uses; lets the server validate the Referer\n *     against the registered domain.\n *\n * Pre-existing endpoint at /api/ingest/pixel — see\n * app/api/ingest/pixel/route.ts. Server-side validation: site_id\n * shape, UA matched against known agent regex, per-IP+per-site rate\n * limit, Referer-host vs registered domain. The customer's site only\n * needs to be in their workspace's registered domains for hits to\n * land in their dashboard. */\n\nexport interface DetectionPixelProps {\n  /** Public token from the Serge dashboard (`srg_pub_*`). */\n  token: string\n  /** Origin of the Serge ingest API. Defaults to `https://serge.ai`. */\n  apiBase?: string\n}\n\nconst PIXEL_STYLE: CSSProperties = {\n  position: 'absolute',\n  width: 1,\n  height: 1,\n  opacity: 0,\n  pointerEvents: 'none',\n  border: 'none',\n}\n\nexport function DetectionPixel({ token, apiBase }: DetectionPixelProps): React.JSX.Element {\n  const base = (apiBase ?? 'https://serge.ai').replace(/\\/$/, '')\n  const src = `${base}/api/ingest/pixel?s=${encodeURIComponent(token)}`\n  return (\n    /* eslint-disable-next-line @next/next/no-img-element -- a tracking pixel must be a literal <img>; alt=\"\" makes it intentionally decorative. */\n    <img\n      src={src}\n      width={1}\n      height={1}\n      alt=\"\"\n      aria-hidden=\"true\"\n      loading=\"eager\"\n      decoding=\"async\"\n      referrerPolicy=\"no-referrer-when-downgrade\"\n      style={PIXEL_STYLE}\n    />\n  )\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,57 @@
+import { InitOptions } from '@serge-ai/js';
+export { ConsentValue, InitOptions, consent, init, pageview, track } from '@serge-ai/js';
+
+/**
+ * @serge-ai/react — React integration.
+ *
+ * Two components, both safe for SSR (no module-level browser access,
+ * all side effects inside `useEffect`):
+ *
+ * 1. `<Analytics />` — drop in once at the root of your app to capture
+ *    JS-driven agent sessions (snippet equivalent):
+ *
+ *      import { Analytics } from '@serge-ai/react'
+ *      export default function App() {
+ *        return (
+ *          <>
+ *            <Analytics token="srg_pub_xxx" />
+ *            <YourApp />
+ *          </>
+ *        )
+ *      }
+ *
+ * 2. `<DetectionPixel />` — drop next to `<Analytics />` to also catch
+ *    non-JS agents (ChatGPT-User, Claude-User, GPTBot, ClaudeBot,
+ *    PerplexityBot — agents that fetch HTML and follow `<img>` but
+ *    don't execute JS). Renders an invisible 1×1 GIF pointing at our
+ *    server. The image fetch fires from the agent direct to serge.ai
+ *    with the agent's User-Agent intact:
+ *
+ *      <Analytics token="srg_pub_xxx" />
+ *      <DetectionPixel token="srg_pub_xxx" />
+ *
+ *    PostHog has no equivalent — JS-only collection is the industry
+ *    standard. Serge ships the pixel on purpose because non-JS agents
+ *    are a meaningful and growing share of agent traffic.
+ *
+ * Re-exports the core `track` / `consent` / `pageview` so consumers
+ * can import everything from the React subpath if they prefer one
+ * import path. (`identify` is intentionally NOT exported — Serge
+ * classifies sessions, not end-users; per-user identity is anti-goal
+ * for cookieless agent analytics.)
+ */
+
+interface AnalyticsProps extends InitOptions {
+    /** Public token from the Serge dashboard (`srg_pub_*`). */
+    token: string;
+}
+declare function Analytics({ token, ...options }: AnalyticsProps): null;
+interface DetectionPixelProps {
+    /** Public token from the Serge dashboard (`srg_pub_*`). */
+    token: string;
+    /** Origin of the Serge ingest API. Defaults to `https://serge.ai`. */
+    apiBase?: string;
+}
+declare function DetectionPixel({ token, apiBase }: DetectionPixelProps): React.JSX.Element;
+
+export { Analytics, type AnalyticsProps, DetectionPixel, type DetectionPixelProps };

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+import { InitOptions } from '@serge-ai/js';
+export { ConsentValue, InitOptions, consent, init, pageview, track } from '@serge-ai/js';
+
+/**
+ * @serge-ai/react — React integration.
+ *
+ * Two components, both safe for SSR (no module-level browser access,
+ * all side effects inside `useEffect`):
+ *
+ * 1. `<Analytics />` — drop in once at the root of your app to capture
+ *    JS-driven agent sessions (snippet equivalent):
+ *
+ *      import { Analytics } from '@serge-ai/react'
+ *      export default function App() {
+ *        return (
+ *          <>
+ *            <Analytics token="srg_pub_xxx" />
+ *            <YourApp />
+ *          </>
+ *        )
+ *      }
+ *
+ * 2. `<DetectionPixel />` — drop next to `<Analytics />` to also catch
+ *    non-JS agents (ChatGPT-User, Claude-User, GPTBot, ClaudeBot,
+ *    PerplexityBot — agents that fetch HTML and follow `<img>` but
+ *    don't execute JS). Renders an invisible 1×1 GIF pointing at our
+ *    server. The image fetch fires from the agent direct to serge.ai
+ *    with the agent's User-Agent intact:
+ *
+ *      <Analytics token="srg_pub_xxx" />
+ *      <DetectionPixel token="srg_pub_xxx" />
+ *
+ *    PostHog has no equivalent — JS-only collection is the industry
+ *    standard. Serge ships the pixel on purpose because non-JS agents
+ *    are a meaningful and growing share of agent traffic.
+ *
+ * Re-exports the core `track` / `consent` / `pageview` so consumers
+ * can import everything from the React subpath if they prefer one
+ * import path. (`identify` is intentionally NOT exported — Serge
+ * classifies sessions, not end-users; per-user identity is anti-goal
+ * for cookieless agent analytics.)
+ */
+
+interface AnalyticsProps extends InitOptions {
+    /** Public token from the Serge dashboard (`srg_pub_*`). */
+    token: string;
+}
+declare function Analytics({ token, ...options }: AnalyticsProps): null;
+interface DetectionPixelProps {
+    /** Public token from the Serge dashboard (`srg_pub_*`). */
+    token: string;
+    /** Origin of the Serge ingest API. Defaults to `https://serge.ai`. */
+    apiBase?: string;
+}
+declare function DetectionPixel({ token, apiBase }: DetectionPixelProps): React.JSX.Element;
+
+export { Analytics, type AnalyticsProps, DetectionPixel, type DetectionPixelProps };

package/dist/index.js

@@ -0,0 +1,4 @@
+"use client";
+import {useEffect}from'react';import {init}from'@serge-ai/js';export{consent,init,pageview,track}from'@serge-ai/js';import {jsx}from'react/jsx-runtime';function u({token:e,...t}){return useEffect(()=>{init(e,t);},[e]),null}var r={position:"absolute",width:1,height:1,opacity:0,pointerEvents:"none",border:"none"};function y({token:e,apiBase:t}){let n=`${(t??"https://serge.ai").replace(/\/$/,"")}/api/ingest/pixel?s=${encodeURIComponent(e)}`;return jsx("img",{src:n,width:1,height:1,alt:"","aria-hidden":"true",loading:"eager",decoding:"async",referrerPolicy:"no-referrer-when-downgrade",style:r})}
+export{u as Analytics,y as DetectionPixel};//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.tsx"],"names":["Analytics","token","options","useEffect","init","PIXEL_STYLE","DetectionPixel","apiBase","src","jsx"],"mappings":"wJAwEO,SAASA,EAAU,CAAE,KAAA,CAAAC,CAAAA,CAAO,GAAGC,CAAQ,CAAA,CAAyB,CACrE,OAAAC,SAAAA,CAAU,IAAM,CACdC,IAAAA,CAAKH,EAAOC,CAAO,EAErB,CAAA,CAAG,CAACD,CAAK,CAAC,EAEH,IACT,CAkCA,IAAMI,CAAAA,CAA6B,CACjC,SAAU,UAAA,CACV,KAAA,CAAO,CAAA,CACP,MAAA,CAAQ,CAAA,CACR,OAAA,CAAS,EACT,aAAA,CAAe,MAAA,CACf,OAAQ,MACV,CAAA,CAEO,SAASC,CAAAA,CAAe,CAAE,KAAA,CAAAL,CAAAA,CAAO,OAAA,CAAAM,CAAQ,EAA2C,CAEzF,IAAMC,EAAM,CAAA,EAAA,CADED,CAAAA,EAAW,oBAAoB,OAAA,CAAQ,KAAA,CAAO,EAAE,CAC3C,CAAA,oBAAA,EAAuB,kBAAA,CAAmBN,CAAK,CAAC,CAAA,CAAA,CACnE,OAEEQ,GAAAA,CAAC,KAAA,CAAA,CACC,IAAKD,CAAAA,CACL,KAAA,CAAO,CAAA,CACP,MAAA,CAAQ,CAAA,CACR,GAAA,CAAI,GACJ,aAAA,CAAY,MAAA,CACZ,QAAQ,OAAA,CACR,QAAA,CAAS,QACT,cAAA,CAAe,4BAAA,CACf,KAAA,CAAOH,CAAAA,CACT,CAEJ","file":"index.js","sourcesContent":["/**\n * @serge-ai/react — React integration.\n *\n * Two components, both safe for SSR (no module-level browser access,\n * all side effects inside `useEffect`):\n *\n * 1. `<Analytics />` — drop in once at the root of your app to capture\n *    JS-driven agent sessions (snippet equivalent):\n *\n *      import { Analytics } from '@serge-ai/react'\n *      export default function App() {\n *        return (\n *          <>\n *            <Analytics token=\"srg_pub_xxx\" />\n *            <YourApp />\n *          </>\n *        )\n *      }\n *\n * 2. `<DetectionPixel />` — drop next to `<Analytics />` to also catch\n *    non-JS agents (ChatGPT-User, Claude-User, GPTBot, ClaudeBot,\n *    PerplexityBot — agents that fetch HTML and follow `<img>` but\n *    don't execute JS). Renders an invisible 1×1 GIF pointing at our\n *    server. The image fetch fires from the agent direct to serge.ai\n *    with the agent's User-Agent intact:\n *\n *      <Analytics token=\"srg_pub_xxx\" />\n *      <DetectionPixel token=\"srg_pub_xxx\" />\n *\n *    PostHog has no equivalent — JS-only collection is the industry\n *    standard. Serge ships the pixel on purpose because non-JS agents\n *    are a meaningful and growing share of agent traffic.\n *\n * Re-exports the core `track` / `consent` / `pageview` so consumers\n * can import everything from the React subpath if they prefer one\n * import path. (`identify` is intentionally NOT exported — Serge\n * classifies sessions, not end-users; per-user identity is anti-goal\n * for cookieless agent analytics.)\n */\n\n'use client'\n\nimport { useEffect, type CSSProperties } from 'react'\nimport {\n  init,\n  track,\n  consent,\n  pageview,\n  type InitOptions,\n  type ConsentValue,\n} from '@serge-ai/js'\n\nexport { init, track, consent, pageview }\nexport type { InitOptions, ConsentValue }\n\n/* ── <Analytics /> ────────────────────────────────────────────────\n *\n * Calls `init()` once on mount with the props as the token + options,\n * returns nothing renderable. Same shape as @vercel/analytics' drop-in\n * pattern — match it exactly so consumers swapping between SDKs see\n * the same component contract.\n *\n * Re-renders only re-call `init()` if the token changes. Other config\n * edits (debug, requireConsent) require a remount — the tracker's\n * runtime state is module-level, and changing flags mid-session\n * produces unpredictable behavior. */\n\nexport interface AnalyticsProps extends InitOptions {\n  /** Public token from the Serge dashboard (`srg_pub_*`). */\n  token: string\n}\n\nexport function Analytics({ token, ...options }: AnalyticsProps): null {\n  useEffect(() => {\n    init(token, options)\n    /* eslint-disable-next-line react-hooks/exhaustive-deps -- intentional: only token triggers re-init */\n  }, [token])\n\n  return null\n}\n\n/* ── <DetectionPixel /> ───────────────────────────────────────────\n *\n * Renders a 1×1 invisible `<img>` whose `src` points at the Serge\n * pixel ingest endpoint. Non-JS agents (HTML-only crawlers) follow\n * the `<img>` reference and trigger the request — Serge captures\n * their User-Agent and records the visit.\n *\n * Implementation notes:\n *   - The image is positioned absolutely with size-1 + opacity-0 so\n *     it doesn't take any visible space or affect layout.\n *   - `aria-hidden=\"true\"` + empty `alt=\"\"` keeps it invisible to\n *     assistive tech.\n *   - `loading=\"eager\"` so it fires immediately on render — lazy\n *     loading would defeat the detection purpose entirely.\n *   - `referrerPolicy=\"no-referrer-when-downgrade\"` matches what\n *     serge.ai itself uses; lets the server validate the Referer\n *     against the registered domain.\n *\n * Pre-existing endpoint at /api/ingest/pixel — see\n * app/api/ingest/pixel/route.ts. Server-side validation: site_id\n * shape, UA matched against known agent regex, per-IP+per-site rate\n * limit, Referer-host vs registered domain. The customer's site only\n * needs to be in their workspace's registered domains for hits to\n * land in their dashboard. */\n\nexport interface DetectionPixelProps {\n  /** Public token from the Serge dashboard (`srg_pub_*`). */\n  token: string\n  /** Origin of the Serge ingest API. Defaults to `https://serge.ai`. */\n  apiBase?: string\n}\n\nconst PIXEL_STYLE: CSSProperties = {\n  position: 'absolute',\n  width: 1,\n  height: 1,\n  opacity: 0,\n  pointerEvents: 'none',\n  border: 'none',\n}\n\nexport function DetectionPixel({ token, apiBase }: DetectionPixelProps): React.JSX.Element {\n  const base = (apiBase ?? 'https://serge.ai').replace(/\\/$/, '')\n  const src = `${base}/api/ingest/pixel?s=${encodeURIComponent(token)}`\n  return (\n    /* eslint-disable-next-line @next/next/no-img-element -- a tracking pixel must be a literal <img>; alt=\"\" makes it intentionally decorative. */\n    <img\n      src={src}\n      width={1}\n      height={1}\n      alt=\"\"\n      aria-hidden=\"true\"\n      loading=\"eager\"\n      decoding=\"async\"\n      referrerPolicy=\"no-referrer-when-downgrade\"\n      style={PIXEL_STYLE}\n    />\n  )\n}\n"]}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@serge-ai/react",
+  "version": "0.2.0",
+  "description": "Serge for React — drop-in <Analytics /> + <DetectionPixel /> components for catching AI-agent sessions on your site.",
+  "license": "MIT",
+  "homepage": "https://serge.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SuperstellarLLC/heyserge.git",
+    "directory": "packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/SuperstellarLLC/heyserge/issues"
+  },
+  "keywords": [
+    "react",
+    "analytics",
+    "tracking",
+    "agent",
+    "ai-agent",
+    "ssr",
+    "cookieless"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@serge-ai/js": "0.2.0"
+  },
+  "peerDependencies": {
+    "react": "^18 || ^19"
+  },
+  "devDependencies": {
+    "@size-limit/preset-small-lib": "^11.1.0",
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "size-limit": "^11.1.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.8.2",
+    "vitest": "^3.1.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run --config ./vitest.config.ts --passWithNoTests",
+    "typecheck": "tsc --noEmit",
+    "size": "size-limit"
+  }
+}