From 9cc3d6a88b094eaf41abb807ca5ba57bf82c7862 Mon Sep 17 00:00:00 2001
From: grootbro <vadim@ravefox.dev>
Date: Mon, 7 Sep 2026 18:26:13 +0700
Subject: [PATCH 1/2] feat(web): opt-in session replay via
 @openpanel/web/replay

Stop dynamically importing ./replay from the main SDK entry so bundlers
no longer emit rrweb for apps that never enable replay. Consumers that
want recording pass startReplayRecorder as sessionReplay.recorder; the
script-tag build still loads op1-replay.js from the CDN.
---
 .../docs/(tracking)/session-replay.mdx        |   5 +-
 apps/public/content/guides/session-replay.mdx |   4 +
 packages/sdks/web/package.json                |   7 +-
 packages/sdks/web/src/index.ts                | 155 +++++++++++-------
 .../web/src/resolve-replay-recorder.test.ts   |  44 +++++
 .../sdks/web/src/resolve-replay-recorder.ts   |  48 ++++++
 packages/sdks/web/tsup.config.ts              |  37 +----
 packages/sdks/web/vitest.config.ts            |  10 ++
 tooling/publish/publish.ts                    |  39 +++--
 9 files changed, 243 insertions(+), 106 deletions(-)
 create mode 100644 packages/sdks/web/src/resolve-replay-recorder.test.ts
 create mode 100644 packages/sdks/web/src/resolve-replay-recorder.ts
 create mode 100644 packages/sdks/web/vitest.config.ts

diff --git a/apps/public/content/docs/(tracking)/session-replay.mdx b/apps/public/content/docs/(tracking)/session-replay.mdx
index ef6e3019f..3fcf41a49 100644
--- a/apps/public/content/docs/(tracking)/session-replay.mdx
+++ b/apps/public/content/docs/(tracking)/session-replay.mdx
@@ -50,23 +50,26 @@ Add `sessionReplay` to your `init` call. The replay script loads automatically f
 
 ```ts title="op.ts"
 import { OpenPanel } from '@openpanel/web';
+import { startReplayRecorder } from '@openpanel/web/replay';
 
 const op = new OpenPanel({
   clientId: 'YOUR_CLIENT_ID',
   trackScreenViews: true,
   sessionReplay: {
     enabled: true,
+    recorder: startReplayRecorder,
   },
 });
 ```
 
-With the npm package, the replay module is a dynamic import code-split by your bundler. It is never included in your main bundle when session replay is disabled.
+Pass `recorder` from `@openpanel/web/replay` when enabling replay in the npm package. That keeps rrweb out of apps that never import the subpath. Script-tag installs still load `op1-replay.js` from the CDN automatically.
 
 ## Options
 
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `enabled` | `boolean` | `false` | Enable session replay recording |
+| `recorder` | `function` | — | Required for the npm package: pass `startReplayRecorder` from `@openpanel/web/replay`. Not needed for script-tag installs |
 | `maskAllInputs` | `boolean` | `true` | Mask all input field values |
 | `maskAllText` | `boolean` | `true` | Mask all text content in the recording |
 | `unmaskTextSelector` | `string` | — | CSS selector for elements whose text should NOT be masked when `maskAllText` is true |
diff --git a/apps/public/content/guides/session-replay.mdx b/apps/public/content/guides/session-replay.mdx
index e52fade13..81252f0ec 100644
--- a/apps/public/content/guides/session-replay.mdx
+++ b/apps/public/content/guides/session-replay.mdx
@@ -80,6 +80,7 @@ The replay script (`op1-replay.js`) is fetched automatically alongside the main
 
 ```ts title="op.ts"
 import { OpenPanel } from '@openpanel/web';
+import { startReplayRecorder } from '@openpanel/web/replay';
 
 const op = new OpenPanel({
   clientId: 'YOUR_CLIENT_ID',
@@ -87,10 +88,13 @@ const op = new OpenPanel({
   trackOutgoingLinks: true,
   sessionReplay: {
     enabled: true,
+    recorder: startReplayRecorder,
   },
 });
 ```
 
+Import `startReplayRecorder` from `@openpanel/web/replay` and pass it as `recorder`. Apps that never import that subpath do not ship rrweb.
+
 With the npm package, the replay module is a dynamic import resolved by your bundler. It is automatically code-split from your main bundle—if you don't enable replay, the module is never included.
 
 ### Next.js
diff --git a/packages/sdks/web/package.json b/packages/sdks/web/package.json
index ae2ac5c0b..8ab05d9d1 100644
--- a/packages/sdks/web/package.json
+++ b/packages/sdks/web/package.json
@@ -8,7 +8,12 @@
   },
   "scripts": {
     "build": "rm -rf dist && tsup",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "exports": {
+    ".": "./index.ts",
+    "./replay": "./src/replay/index.ts"
   },
   "dependencies": {
     "@openpanel/sdk": "workspace:1.3.1-local",
diff --git a/packages/sdks/web/src/index.ts b/packages/sdks/web/src/index.ts
index 3493717f1..ad17c4ce0 100644
--- a/packages/sdks/web/src/index.ts
+++ b/packages/sdks/web/src/index.ts
@@ -3,9 +3,18 @@ import type {
   TrackProperties,
 } from '@openpanel/sdk';
 import { OpenPanel as OpenPanelBase } from '@openpanel/sdk';
+import {
+  resolveSessionReplayRecorder,
+  type SessionReplayRecorder,
+} from './resolve-replay-recorder';
 
 export type * from '@openpanel/sdk';
 export { OpenPanel as OpenPanelBase } from '@openpanel/sdk';
+export type {
+  SessionReplayChunkPayload,
+  SessionReplayRecorder,
+  SessionReplayRecorderConfig,
+} from './resolve-replay-recorder';
 
 export type SessionReplayOptions = {
   enabled: boolean;
@@ -31,10 +40,23 @@ export type SessionReplayOptions = {
   /**
    * URL to the replay recorder script.
    * Only used when loading the SDK via a script tag (IIFE / op1.js).
-   * When using the npm package with a bundler this option is ignored
-   * because the bundler resolves the replay module from the package.
+   * When using the npm package with a bundler this option is ignored —
+   * pass `recorder` from `@openpanel/web/replay` instead.
    */
   scriptUrl?: string;
+  /**
+   * Recorder implementation. Required for the npm / bundler build when
+   * `enabled` is true, so rrweb is only included when you import
+   * `@openpanel/web/replay`. The script-tag build loads the CDN
+   * recorder automatically when this is omitted.
+   *
+   * @example
+   * import { startReplayRecorder } from '@openpanel/web/replay'
+   * new OpenPanel({
+   *   sessionReplay: { enabled: true, recorder: startReplayRecorder },
+   * })
+   */
+  recorder?: SessionReplayRecorder;
 };
 
 // Injected at build time only in the IIFE (tracker) build.
@@ -42,7 +64,7 @@ export type SessionReplayOptions = {
 declare const __OPENPANEL_REPLAY_URL__: string | undefined;
 
 // Capture script element synchronously; currentScript is only set during sync execution.
-// Used by loadReplayModule() to derive the replay script URL in the IIFE build.
+// Used by loadIifeReplayRecorder() to derive the replay script URL in the IIFE build.
 const _replayScriptRef: HTMLScriptElement | null =
   typeof document !== 'undefined'
     ? (document.currentScript as HTMLScriptElement | null)
@@ -113,75 +135,84 @@ export class OpenPanel extends OpenPanelBase {
         const sampleRate = this.options.sessionReplay.sampleRate ?? 1;
         const sampled = Math.random() < sampleRate;
         if (sampled) {
-          this.loadReplayModule().then((mod) => {
-            if (!mod) {
-              return;
-            }
-            mod.startReplayRecorder(this.options.sessionReplay!, (chunk) => {
-              // Replay chunks go through send() and are queued when disabled or waitForProfile
-              // until ready() is called (base SDK also queues replay until sessionId is set).
-              this.send({
-                type: 'replay',
-                payload: {
-                  ...chunk,
-                  sessionId: this.sessionId,
-                },
-              });
-            });
-          });
+          void this.startSessionReplay();
         }
       }
     }
   }
 
   /**
-   * Load the replay recorder module.
-   *
-   * - **IIFE build (op1.js)**: `__OPENPANEL_REPLAY_URL__` is replaced at
-   *   build time with a CDN URL (e.g. `https://openpanel.dev/op1-replay.js`).
-   *   The user can also override it via `sessionReplay.scriptUrl`.
-   *   We load the IIFE replay script via a classic `<script>` tag which
-   *   avoids CORS issues (dynamic `import(url)` uses `cors` mode).
-   *   The IIFE exposes its exports on `window.__openpanel_replay`.
+   * Start session replay with either an explicit `recorder` (npm) or the
+   * CDN script (IIFE / op1.js). The library build never `import()`s
+   * `./replay`, so rrweb stays out of apps that do not opt in.
+   */
+  private async startSessionReplay(): Promise<void> {
+    const options = this.options.sessionReplay;
+    if (!options) {
+      return;
+    }
+
+    const recorder = await resolveSessionReplayRecorder({
+      recorder: options.recorder,
+      isIifeBuild: typeof __OPENPANEL_REPLAY_URL__ !== 'undefined',
+      loadIifeRecorder: () => this.loadIifeReplayRecorder(),
+    });
+
+    if (!recorder) {
+      console.warn(
+        '[OpenPanel] sessionReplay.enabled but no recorder was provided. Import startReplayRecorder from @openpanel/web/replay and pass it as sessionReplay.recorder.',
+      );
+      return;
+    }
+
+    recorder(options, (chunk) => {
+      // Replay chunks go through send() and are queued when disabled or waitForProfile
+      // until ready() is called (base SDK also queues replay until sessionId is set).
+      this.send({
+        type: 'replay',
+        payload: {
+          ...chunk,
+          sessionId: this.sessionId,
+        },
+      });
+    });
+  }
+
+  /**
+   * Load the IIFE replay recorder from the CDN (script-tag builds only).
    *
-   * - **Library build (npm)**: `__OPENPANEL_REPLAY_URL__` is `undefined`
-   *   (never replaced). We use `import('./replay')` which the host app's
-   *   bundler resolves and code-splits from the package source.
+   * `__OPENPANEL_REPLAY_URL__` is replaced at build time with a CDN URL
+   * (e.g. `https://openpanel.dev/op1-replay.js`). The user can also
+   * override it via `sessionReplay.scriptUrl`. Classic `<script>` avoids
+   * CORS issues that dynamic `import(url)` would hit. Exports land on
+   * `window.__openpanel_replay`.
    */
-  private async loadReplayModule(): Promise<typeof import('./replay') | null> {
+  private async loadIifeReplayRecorder(): Promise<SessionReplayRecorder | null> {
     try {
-      // typeof check avoids a ReferenceError when the constant is not
-      // defined (library build). tsup replaces the constant with a
-      // string literal only in the IIFE build, so this branch is
-      // dead-code-eliminated in the library build.
-      if (typeof __OPENPANEL_REPLAY_URL__ !== 'undefined') {
-        const scriptEl = _replayScriptRef;
-        const url =
-          this.options.sessionReplay?.scriptUrl ||
-          scriptEl?.src?.replace('.js', '-replay.js') ||
-          'https://openpanel.dev/op1-replay.js';
-
-        // Already loaded (e.g. user included the script manually)
-        if ((window as any).__openpanel_replay) {
-          return (window as any).__openpanel_replay;
-        }
-
-        // Load via classic <script> tag — no CORS restrictions
-        return new Promise((resolve) => {
-          const script = document.createElement('script');
-          script.src = url;
-          script.onload = () => {
-            resolve((window as any).__openpanel_replay ?? null);
-          };
-          script.onerror = () => {
-            console.warn('[OpenPanel] Failed to load replay script from', url);
-            resolve(null);
-          };
-          document.head.appendChild(script);
-        });
+      const scriptEl = _replayScriptRef;
+      const url =
+        this.options.sessionReplay?.scriptUrl ||
+        scriptEl?.src?.replace('.js', '-replay.js') ||
+        'https://openpanel.dev/op1-replay.js';
+
+      if ((window as any).__openpanel_replay?.startReplayRecorder) {
+        return (window as any).__openpanel_replay.startReplayRecorder;
       }
-      // Library / bundler context — resolved by the bundler
-      return await import('./replay');
+
+      return new Promise((resolve) => {
+        const script = document.createElement('script');
+        script.src = url;
+        script.onload = () => {
+          resolve(
+            (window as any).__openpanel_replay?.startReplayRecorder ?? null,
+          );
+        };
+        script.onerror = () => {
+          console.warn('[OpenPanel] Failed to load replay script from', url);
+          resolve(null);
+        };
+        document.head.appendChild(script);
+      });
     } catch (e) {
       console.warn('[OpenPanel] Failed to load replay module', e);
       return null;
diff --git a/packages/sdks/web/src/resolve-replay-recorder.test.ts b/packages/sdks/web/src/resolve-replay-recorder.test.ts
new file mode 100644
index 000000000..8818c448e
--- /dev/null
+++ b/packages/sdks/web/src/resolve-replay-recorder.test.ts
@@ -0,0 +1,44 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { resolveSessionReplayRecorder } from './resolve-replay-recorder';
+
+describe('resolveSessionReplayRecorder', () => {
+  it('prefers an explicit recorder so the host can opt into rrweb', async () => {
+    const recorder = vi.fn();
+    const loadIifeRecorder = vi.fn();
+
+    const resolved = await resolveSessionReplayRecorder({
+      recorder,
+      isIifeBuild: false,
+      loadIifeRecorder,
+    });
+
+    expect(resolved).toBe(recorder);
+    expect(loadIifeRecorder).not.toHaveBeenCalled();
+  });
+
+  it('loads the CDN script only for the IIFE build', async () => {
+    const recorder = vi.fn();
+    const loadIifeRecorder = vi.fn().mockResolvedValue(recorder);
+
+    const resolved = await resolveSessionReplayRecorder({
+      isIifeBuild: true,
+      loadIifeRecorder,
+    });
+
+    expect(loadIifeRecorder).toHaveBeenCalledOnce();
+    expect(resolved).toBe(recorder);
+  });
+
+  it('returns null in the library build when no recorder is provided', async () => {
+    const loadIifeRecorder = vi.fn();
+
+    const resolved = await resolveSessionReplayRecorder({
+      isIifeBuild: false,
+      loadIifeRecorder,
+    });
+
+    expect(resolved).toBeNull();
+    expect(loadIifeRecorder).not.toHaveBeenCalled();
+  });
+});
diff --git a/packages/sdks/web/src/resolve-replay-recorder.ts b/packages/sdks/web/src/resolve-replay-recorder.ts
new file mode 100644
index 000000000..fa83e7ab3
--- /dev/null
+++ b/packages/sdks/web/src/resolve-replay-recorder.ts
@@ -0,0 +1,48 @@
+export type SessionReplayRecorderConfig = {
+  maskAllInputs?: boolean;
+  maskAllText?: boolean;
+  unmaskTextSelector?: string;
+  blockSelector?: string;
+  blockClass?: string;
+  ignoreSelector?: string;
+  flushIntervalMs?: number;
+  maxEventsPerChunk?: number;
+  maxPayloadBytes?: number;
+};
+
+export type SessionReplayChunkPayload = {
+  chunk_index: number;
+  events_count: number;
+  is_full_snapshot: boolean;
+  started_at: string;
+  ended_at: string;
+  payload: string;
+};
+
+export type SessionReplayRecorder = (
+  config: SessionReplayRecorderConfig,
+  sendChunk: (payload: SessionReplayChunkPayload) => void,
+) => void;
+
+/**
+ * Decides how session replay starts.
+ *
+ * Library / bundler consumers must pass `recorder` (typically
+ * `startReplayRecorder` from `@openpanel/web/replay`) so rrweb is only
+ * pulled into a bundle that actually imports that subpath.
+ *
+ * The IIFE (script-tag) build still loads `op1-replay.js` from the CDN.
+ */
+export async function resolveSessionReplayRecorder(options: {
+  recorder?: SessionReplayRecorder;
+  isIifeBuild: boolean;
+  loadIifeRecorder: () => Promise<SessionReplayRecorder | null>;
+}): Promise<SessionReplayRecorder | null> {
+  if (options.recorder) {
+    return options.recorder;
+  }
+  if (options.isIifeBuild) {
+    return options.loadIifeRecorder();
+  }
+  return null;
+}
diff --git a/packages/sdks/web/tsup.config.ts b/packages/sdks/web/tsup.config.ts
index 6fe7cd606..263067088 100644
--- a/packages/sdks/web/tsup.config.ts
+++ b/packages/sdks/web/tsup.config.ts
@@ -1,14 +1,15 @@
 import { defineConfig } from 'tsup';
 
 export default defineConfig([
-  // Library build (npm package) — cjs + esm + dts
-  // Dynamic import('./replay') is preserved; the host app's bundler
-  // will code-split it into a separate chunk automatically.
+  // Library build (npm package) — cjs + esm + dts.
+  // Does not import `./replay`; consumers that want session replay import
+  // `@openpanel/web/replay` and pass `startReplayRecorder` as
+  // `sessionReplay.recorder`, so rrweb stays out of lean bundles.
   {
     entry: ['index.ts'],
     format: ['cjs', 'esm'],
     dts: true,
-    splitting: true,
+    splitting: false,
     sourcemap: false,
     clean: true,
     minify: true,
@@ -17,8 +18,6 @@ export default defineConfig([
   // __OPENPANEL_REPLAY_URL__ is injected at build time so the IIFE
   // knows to load the replay module from the CDN instead of a
   // relative import (which doesn't work in a standalone script).
-  // The replay module is excluded via an esbuild plugin so it is
-  // never bundled into op1.js — it will be loaded lazily via <script>.
   {
     entry: { 'src/tracker': 'src/tracker.ts' },
     format: ['iife'],
@@ -30,30 +29,9 @@ export default defineConfig([
         'https://openpanel.dev/op1-replay.js'
       ),
     },
-    esbuildPlugins: [
-      {
-        name: 'exclude-replay-from-iife',
-        setup(build) {
-          // Intercept any import that resolves to the replay module and
-          // return an empty object. The actual loading happens at runtime
-          // via a <script> tag (see loadReplayModule in index.ts).
-          build.onResolve(
-            { filter: /[/\\]replay([/\\]index)?(\.[jt]s)?$/ },
-            () => ({
-              path: 'replay-empty-stub',
-              namespace: 'replay-stub',
-            })
-          );
-          build.onLoad({ filter: /.*/, namespace: 'replay-stub' }, () => ({
-            contents: 'module.exports = {}',
-            loader: 'js',
-          }));
-        },
-      },
-    ],
   },
-  // Replay module — built as both ESM (npm) and IIFE (CDN).
-  // ESM  → consumed by the host-app's bundler via `import('./replay')`.
+  // Replay module — built as both ESM (npm subpath) and IIFE (CDN).
+  // ESM  → `@openpanel/web/replay`
   // IIFE → loaded at runtime via a classic <script> tag (no CORS issues).
   //        Exposes `window.__openpanel_replay`.
   // rrweb must be bundled in (noExternal) because browsers can't resolve
@@ -61,6 +39,7 @@ export default defineConfig([
   {
     entry: { 'src/replay': 'src/replay/index.ts' },
     format: ['esm', 'iife'],
+    dts: true,
     globalName: '__openpanel_replay',
     splitting: false,
     sourcemap: false,
diff --git a/packages/sdks/web/vitest.config.ts b/packages/sdks/web/vitest.config.ts
new file mode 100644
index 000000000..d4337343c
--- /dev/null
+++ b/packages/sdks/web/vitest.config.ts
@@ -0,0 +1,10 @@
+import * as path from 'node:path';
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    // Nested under packages/sdks — go up three levels to the repo test setup.
+    setupFiles: [path.resolve(__dirname, '../../../test/test-setup.ts')],
+    include: ['**/*.test.ts'],
+  },
+});
diff --git a/tooling/publish/publish.ts b/tooling/publish/publish.ts
index 2c957b88e..7c82588a7 100644
--- a/tooling/publish/publish.ts
+++ b/tooling/publish/publish.ts
@@ -154,22 +154,35 @@ const updatePackageJsonForRelease = (
       module: './dist/index.js',
       types: './dist/index.d.ts',
       files: ['dist', 'README.md', 'LICENSE'],
-      exports: restPkgJson.exports ?? {
-        '.': {
-          import: './dist/index.js',
-          require: './dist/index.cjs',
-          types: './dist/index.d.ts',
-        },
-        ...(name === '@openpanel/nextjs'
+      exports:
+        name === '@openpanel/web'
           ? {
-              './server': {
-                import: './dist/server.js',
-                require: './dist/server.cjs',
-                types: './dist/server.d.ts',
+              '.': {
+                import: './dist/index.js',
+                require: './dist/index.cjs',
+                types: './dist/index.d.ts',
+              },
+              './replay': {
+                import: './dist/src/replay.js',
+                types: './dist/src/replay.d.ts',
               },
             }
-          : {}),
-      },
+          : (restPkgJson.exports ?? {
+              '.': {
+                import: './dist/index.js',
+                require: './dist/index.cjs',
+                types: './dist/index.d.ts',
+              },
+              ...(name === '@openpanel/nextjs'
+                ? {
+                    './server': {
+                      import: './dist/server.js',
+                      require: './dist/server.cjs',
+                      types: './dist/server.d.ts',
+                    },
+                  }
+                : {}),
+            }),
     };
   }
 

From 399febfae83556feda41e2f245745b270702df6d Mon Sep 17 00:00:00 2001
From: grootbro <vadim@ravefox.dev>
Date: Mon, 7 Sep 2026 21:14:26 +0700
Subject: [PATCH 2/2] docs(web): clarify npm session replay requires explicit
 recorder

Remove the obsolete dynamic-import claim and note that @openpanel/web/replay
must be wired via sessionReplay.recorder.
---
 apps/public/content/guides/session-replay.mdx | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/apps/public/content/guides/session-replay.mdx b/apps/public/content/guides/session-replay.mdx
index 81252f0ec..9276fdda3 100644
--- a/apps/public/content/guides/session-replay.mdx
+++ b/apps/public/content/guides/session-replay.mdx
@@ -55,7 +55,7 @@ See the [Web SDK docs](/docs/sdks/web) or [Script tag docs](/docs/sdks/script) f
 
 ## Enable session replay [#enable]
 
-Session replay is **off by default**. Enable it by adding `sessionReplay: { enabled: true }` to your init config.
+Session replay is **off by default**. For the script tag, add `sessionReplay: { enabled: true }` to your init config. For the npm package, also import `@openpanel/web/replay` and pass `recorder` (see below).
 
 ### Script tag
 
@@ -95,8 +95,6 @@ const op = new OpenPanel({
 
 Import `startReplayRecorder` from `@openpanel/web/replay` and pass it as `recorder`. Apps that never import that subpath do not ship rrweb.
 
-With the npm package, the replay module is a dynamic import resolved by your bundler. It is automatically code-split from your main bundle—if you don't enable replay, the module is never included.
-
 ### Next.js
 
 For Next.js, enable replay in your `OpenPanelComponent`: