test-proxy-recorder 0.1.11 → 0.3.0

package/README.md

@@ -21,6 +21,7 @@ HTTP proxy server for recording and replaying network requests in testing. Works
 - [Complete Setup Guide](#complete-setup-guide)
 - [CLI Usage](#cli-usage)
 - [Playwright Integration](#playwright-integration)
+- [Next.js Integration](#nextjs-integration)
 - [Control Endpoint](#control-endpoint)
 - [Typical Workflow](#typical-workflow)
 - [Recording Format](#recording-format)
@@ -99,10 +100,10 @@ This marks recording files as binary, which causes long mock files to be collaps
 Create `e2e/global-teardown.ts`:
 
 ```typescript
-import { setProxyMode } from 'test-proxy-recorder';
+import { playwrightProxy } from 'test-proxy-recorder';
 
 async function globalTeardown() {
-  await setProxyMode('transparent').catch(err => { console.error(err) });
+  await playwrightProxy.teardown();
 }
 
 export default globalTeardown;
@@ -130,13 +131,11 @@ import { playwrightProxy } from 'test-proxy-recorder';
 
 test('example test with proxy', async ({ page }, testInfo) => {
   // Set proxy mode: 'record' to capture, 'replay' to use recordings
-  await playwrightProxy.before(testInfo, 'replay');
+  // This automatically sets up page.on('close') for cleanup
+  await playwrightProxy.before(page, testInfo, 'replay');
 
   await page.goto('/');
   await expect(page.getByText('Welcome')).toBeVisible();
-
-  // Always cleanup after test
-  await playwrightProxy.after(testInfo);
 });
 ```
 
@@ -145,13 +144,13 @@ test('example test with proxy', async ({ page }, testInfo) => {
 **First run (record mode)**:
 
 ```typescript
-await playwrightProxy.before(testInfo, 'record');
+await playwrightProxy.before(page, testInfo, 'record');
 ```
 
 **Subsequent runs (replay mode)**:
 
 ```typescript
-await playwrightProxy.before(testInfo, 'replay');
+await playwrightProxy.before(page, testInfo, 'replay');
 ```
 
 ## CLI Usage
@@ -184,6 +183,12 @@ test-proxy-recorder http://localhost:8000 http://localhost:9000 --port 8100
 
 ## Playwright Integration
 
+### Session Identification
+
+The proxy uses a **custom HTTP header** (`x-test-rcrd-id`) to identify recording sessions. This header is automatically set by the `playwrightProxy.before()` method and works seamlessly with Next.js and other server-side rendering frameworks.
+
+**Cookie fallback**: For backward compatibility, the proxy also supports cookie-based session identification, but the custom header is preferred.
+
 ### Basic Test Structure
 
 Every test using the proxy should follow this pattern:
@@ -193,40 +198,38 @@ import { test } from '@playwright/test';
 import { playwrightProxy } from 'test-proxy-recorder';
 
 test('test name', async ({ page }, testInfo) => {
-  // 1. Set mode BEFORE test actions
-  await playwrightProxy.before(testInfo, 'replay');
+  // Set mode BEFORE test actions
+  // This automatically sets the recording ID header and cleanup handler
+  await playwrightProxy.before(page, testInfo, 'replay');
 
-  // 2. Test code
+  // Test code
   await page.goto('/page');
-
-  // 3. Reset mode AFTER test completes
-  await playwrightProxy.after(testInfo);
+  // Test assertions...
 });
 ```
 
 ### Recording vs Replay
 
 ```typescript
+import { test } from '@playwright/test';
+import { playwrightProxy } from 'test-proxy-recorder';
+
 // Recording mode - captures API responses
 test('create user', async ({ page }, testInfo) => {
-  await playwrightProxy.before(testInfo, 'record');
+  await playwrightProxy.before(page, testInfo, 'record');
 
   await page.goto('/users/new');
   await page.fill('[name="username"]', 'testuser');
   await page.click('button[type="submit"]');
-
-  await playwrightProxy.after(testInfo);
 });
 
 // Replay mode - uses recorded responses
 test('create user', async ({ page }, testInfo) => {
-  await playwrightProxy.before(testInfo, 'replay');
+  await playwrightProxy.before(page, testInfo, 'replay');
 
   await page.goto('/users/new');
   await page.fill('[name="username"]', 'testuser');
   await page.click('button[type="submit"]');
-
-  await playwrightProxy.after(testInfo);
 });
 ```
 
@@ -244,10 +247,10 @@ Recording files are auto-generated from test names:
 Create `e2e/global-teardown.ts`:
 
 ```typescript
-import { setProxyMode } from 'test-proxy-recorder';
+import { playwrightProxy } from 'test-proxy-recorder';
 
 async function globalTeardown() {
-  await setProxyMode('transparent').catch(err => { console.error(err) });
+  await playwrightProxy.teardown();
 }
 
 export default globalTeardown;
@@ -265,6 +268,78 @@ export default defineConfig({
 });
 ```
 
+## Next.js Integration
+
+When testing Next.js applications with server-side rendering (SSR) or API routes, you need to ensure the recording ID header is forwarded to the proxy. The package provides helpers for this.
+
+### Option 1: Using Next.js Middleware (Recommended)
+
+Create or update `middleware.ts` in your Next.js project root:
+
+```typescript
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+import { setNextProxyHeaders } from 'test-proxy-recorder/nextjs';
+
+export function middleware(request: NextRequest) {
+  const response = NextResponse.next();
+
+  // Forward the recording ID header during tests
+  // Only runs in non-production or when TEST_PROXY_RECORDER_ENABLED=true
+  setNextProxyHeaders(request, response);
+
+  return response;
+}
+```
+
+**Environment Variables:**
+- Automatically skipped when `NODE_ENV=production`
+- Can be explicitly enabled in production with `TEST_PROXY_RECORDER_ENABLED=true`
+
+### Option 2: Manual Header Forwarding in API Routes
+
+For API routes or server components, manually include the header in fetch requests:
+
+```typescript
+// app/api/data/route.ts
+import { headers } from 'next/headers';
+import { createHeadersWithRecordingId } from 'test-proxy-recorder/nextjs';
+
+export async function GET() {
+  const requestHeaders = await headers();
+
+  const response = await fetch('http://localhost:8100/api/data', {
+    headers: createHeadersWithRecordingId(requestHeaders, {
+      'Content-Type': 'application/json',
+    })
+  });
+
+  return Response.json(await response.json());
+}
+```
+
+### Option 3: Using getRecordingId Helper
+
+For more control, extract the recording ID and use it manually:
+
+```typescript
+import { headers } from 'next/headers';
+import { getRecordingId, RECORDING_ID_HEADER } from 'test-proxy-recorder/nextjs';
+
+export async function GET() {
+  const recordingId = getRecordingId(await headers());
+
+  const response = await fetch('http://localhost:8100/api/data', {
+    headers: {
+      'Content-Type': 'application/json',
+      ...(recordingId && { [RECORDING_ID_HEADER]: recordingId })
+    }
+  });
+
+  return Response.json(await response.json());
+}
+```
+
 ## Control Endpoint
 
 The proxy exposes a control endpoint at `/__control` for programmatic mode switching.
@@ -401,19 +476,24 @@ class ProxyServer {
 ### Playwright Integration
 
 ```typescript
-import { playwrightProxy, setProxyMode } from 'test-proxy-recorder';
+import { playwrightProxy, setProxyMode, RECORDING_ID_HEADER } from 'test-proxy-recorder';
+import type { Page } from '@playwright/test';
 
 // Main helper for Playwright tests
 const playwrightProxy = {
-  // Set proxy mode before test
+  // Set proxy mode before test and configure page with recording ID header
+  // Automatically sets up page.on('close') handler for cleanup
   async before(
+    page: Page,
     testInfo: TestInfo,
     mode: 'record' | 'replay' | 'transparent',
     timeout?: number
   ): Promise<void>;
 
-  // Reset to transparent mode after test
-  async after(testInfo: TestInfo): Promise<void>;
+
+  // Global teardown - switches proxy to transparent mode
+  // Use in Playwright's globalTeardown configuration
+  async teardown(): Promise<void>;
 };
 
 // Direct mode control
@@ -422,6 +502,41 @@ async function setProxyMode(
   id?: string,
   timeout?: number
 ): Promise<void>;
+
+// Recording ID header constant
+const RECORDING_ID_HEADER: string; // 'x-test-rcrd-id'
+```
+
+### Next.js Integration
+
+**IMPORTANT**: Use the `/nextjs` import path to avoid webpack bundling issues in Next.js:
+
+```typescript
+import {
+  setNextProxyHeaders,
+  getRecordingId,
+  createHeadersWithRecordingId,
+  RECORDING_ID_HEADER
+} from 'test-proxy-recorder/nextjs';
+import type { NextRequest, NextResponse } from 'next/server';
+
+// Forward recording ID header in Next.js middleware
+// Automatically skipped in production unless TEST_PROXY_RECORDER_ENABLED=true
+function setNextProxyHeaders(
+  request: NextRequest,
+  response: NextResponse
+): void;
+
+// Get recording ID from request headers
+function getRecordingId(
+  requestHeaders: NextRequest | Headers
+): string | null;
+
+// Create headers object with recording ID for fetch requests
+function createHeadersWithRecordingId(
+  requestHeaders: NextRequest | Headers,
+  additionalHeaders?: Record<string, string>
+): Record<string, string>;
 ```
 
 ### Control Endpoint
@@ -438,6 +553,8 @@ async function setProxyMode(
 }
 ```
 
+**Note**: Switching to replay mode automatically resets session counters (clears served recordings tracker), allowing replay from the beginning.
+
 **Response**:
 
 ```typescript

package/dist/{index-Cx_Kflfl.d.cts → index-CVuiglPk.d.cts}

@@ -1,4 +1,4 @@
-import { TestInfo } from '@playwright/test';
+import { TestInfo, Page } from '@playwright/test';
 import http from 'node:http';
 
 declare const Modes: {
@@ -82,20 +82,23 @@ declare function startReplay(testInfo: PlaywrightTestInfo): Promise<void>;
 declare function stopProxy(testInfo: PlaywrightTestInfo): Promise<void>;
 /**
  * Playwright test fixture helper for managing proxy mode
- * Use this in beforeEach/afterEach hooks
+ * Use this in test functions with page.on('close') for automatic cleanup
  */
 declare const playwrightProxy: {
     /**
-     * Setup before test - sets the proxy mode
+     * Setup before test - sets the proxy mode and configures page with custom header
+     * Automatically sets up page.on('close') handler for cleanup
+     * @param page - Playwright page object
      * @param testInfo - Playwright test info object
      * @param mode - The proxy mode to use for this test
+     * @param timeout - Optional timeout in milliseconds
      */
-    before(testInfo: PlaywrightTestInfo, mode: Mode): Promise<void>;
+    before(page: Page, testInfo: PlaywrightTestInfo, mode: Mode, timeout?: number): Promise<void>;
     /**
-     * Cleanup after test - returns to transparent mode
-     * @param testInfo - Playwright test info object
+     * Global teardown - switches proxy to transparent mode
+     * Use this in Playwright's globalTeardown to ensure clean state
      */
-    after(testInfo: PlaywrightTestInfo): Promise<void>;
+    teardown(): Promise<void>;
 };
 
 export { type ControlRequest as C, type Mode as M, type PlaywrightTestInfo as P, type Recording as R, type WebSocketRecording as W, type RecordingSession as a, startRecording as b, startReplay as c, stopProxy as d, generateSessionId as g, playwrightProxy as p, setProxyMode as s };

package/dist/{index-Cx_Kflfl.d.ts → index-CVuiglPk.d.ts}

@@ -1,4 +1,4 @@
-import { TestInfo } from '@playwright/test';
+import { TestInfo, Page } from '@playwright/test';
 import http from 'node:http';
 
 declare const Modes: {
@@ -82,20 +82,23 @@ declare function startReplay(testInfo: PlaywrightTestInfo): Promise<void>;
 declare function stopProxy(testInfo: PlaywrightTestInfo): Promise<void>;
 /**
  * Playwright test fixture helper for managing proxy mode
- * Use this in beforeEach/afterEach hooks
+ * Use this in test functions with page.on('close') for automatic cleanup
  */
 declare const playwrightProxy: {
     /**
-     * Setup before test - sets the proxy mode
+     * Setup before test - sets the proxy mode and configures page with custom header
+     * Automatically sets up page.on('close') handler for cleanup
+     * @param page - Playwright page object
      * @param testInfo - Playwright test info object
      * @param mode - The proxy mode to use for this test
+     * @param timeout - Optional timeout in milliseconds
      */
-    before(testInfo: PlaywrightTestInfo, mode: Mode): Promise<void>;
+    before(page: Page, testInfo: PlaywrightTestInfo, mode: Mode, timeout?: number): Promise<void>;
     /**
-     * Cleanup after test - returns to transparent mode
-     * @param testInfo - Playwright test info object
+     * Global teardown - switches proxy to transparent mode
+     * Use this in Playwright's globalTeardown to ensure clean state
      */
-    after(testInfo: PlaywrightTestInfo): Promise<void>;
+    teardown(): Promise<void>;
 };
 
 export { type ControlRequest as C, type Mode as M, type PlaywrightTestInfo as P, type Recording as R, type WebSocketRecording as W, type RecordingSession as a, startRecording as b, startReplay as c, stopProxy as d, generateSessionId as g, playwrightProxy as p, setProxyMode as s };

package/dist/index.cjs

@@ -19,8 +19,6 @@ var crypto__default = /*#__PURE__*/_interopDefault(crypto);
 var path__default = /*#__PURE__*/_interopDefault(path);
 var filenamify2__default = /*#__PURE__*/_interopDefault(filenamify2);
 
-// src/ProxyServer.ts
-
 // src/constants.ts
 var DEFAULT_TIMEOUT_MS = 120 * 1e3;
 var HTTP_STATUS_BAD_GATEWAY = 502;
@@ -28,6 +26,7 @@ var HTTP_STATUS_OK = 200;
 var HTTP_STATUS_BAD_REQUEST = 400;
 var HTTP_STATUS_NOT_FOUND = 404;
 var CONTROL_ENDPOINT = "/__control";
+var RECORDING_ID_HEADER = "x-test-rcrd-id";
 
 // src/types.ts
 var Modes = {
@@ -200,7 +199,7 @@ var ProxyServer = class {
     return {
       "access-control-allow-origin": origin || "*",
       "access-control-allow-credentials": "true",
-      "access-control-allow-headers": req.headers["access-control-request-headers"] || "Origin, X-Requested-With, Content-Type, Accept, Authorization",
+      "access-control-allow-headers": req.headers["access-control-request-headers"] || `Origin, X-Requested-With, Content-Type, Accept, Authorization, ${RECORDING_ID_HEADER}`,
       "access-control-allow-methods": "GET, POST, PUT, DELETE, PATCH, OPTIONS",
       "access-control-expose-headers": "*"
     };
@@ -214,9 +213,22 @@ var ProxyServer = class {
     this.currentTargetIndex = (this.currentTargetIndex + 1) % this.targets.length;
     return target;
   }
+  /**
+   * Extract recording ID from custom HTTP header
+   * Used for concurrent replay session routing, especially with Next.js
+   * @param req The incoming HTTP request
+   * @returns The recording ID from header, or null if not found
+   */
+  getRecordingIdFromHeader(req) {
+    const headerValue = req.headers[RECORDING_ID_HEADER];
+    if (!headerValue) {
+      return null;
+    }
+    return Array.isArray(headerValue) ? headerValue[0] : headerValue;
+  }
   /**
    * Extract recording ID from request cookie
-   * Used for concurrent replay session routing
+   * Used for concurrent replay session routing (fallback method)
    * @param req The incoming HTTP request
    * @returns The recording ID from cookie, or null if not found
    */
@@ -228,6 +240,14 @@ var ProxyServer = class {
     const match = cookies.match(/proxy-recording-id=([^;]+)/);
     return match ? decodeURIComponent(match[1]) : null;
   }
+  /**
+   * Extract recording ID from request using custom header (preferred) or cookie (fallback)
+   * @param req The incoming HTTP request
+   * @returns The recording ID, or null if not found
+   */
+  getRecordingIdFromRequest(req) {
+    return this.getRecordingIdFromHeader(req) || this.getRecordingIdFromCookie(req);
+  }
   /**
    * Get or create a replay session state for a given recording ID
    * @param recordingId The recording ID to get/create session for
@@ -505,7 +525,7 @@ var ProxyServer = class {
     return true;
   }
   async handleReplayRequest(req, res) {
-    const recordingId = this.getRecordingIdFromCookie(req) || this.replayId;
+    const recordingId = this.getRecordingIdFromRequest(req) || this.replayId;
     if (!recordingId) {
       const corsHeaders = this.getCorsHeaders(req);
       res.writeHead(HTTP_STATUS_BAD_REQUEST, {
@@ -529,7 +549,11 @@ var ProxyServer = class {
       }
       const servedForThisKey = sessionState.servedRecordingIdsByKey.get(key);
       const host = req.headers.host || "unknown";
-      const recordsWithKey = session.recordings.filter((r) => r.key === key && r.response).toSorted((a, b) => a.recordingId - b.recordingId);
+      const recordsWithKey = session.recordings.filter((r) => r.key === key && r.response).toSorted((a, b) => {
+        const aSeq = a.sequence !== void 0 ? a.sequence : a.recordingId;
+        const bSeq = b.sequence !== void 0 ? b.sequence : b.recordingId;
+        return aSeq - bSeq;
+      });
       if (recordsWithKey.length === 0) {
         const errorMsg = `No recording found for ${key} at ${req.method} ${host}${req.url}`;
         console.error(`[REPLAY ERROR] ${errorMsg} (session: ${recordingId})`);
@@ -552,7 +576,7 @@ var ProxyServer = class {
       }
       const requestCount = servedForThisKey.size + 1;
       console.log(
-        `[REPLAY REQUEST #${requestCount}] ${req.method} ${req.url} (session: ${recordingId}, total: ${recordsWithKey.length}, served: ${servedForThisKey.size})`
+        `[replay request #${requestCount}] ${req.method} ${req.url} (session: ${recordingId}, total: ${recordsWithKey.length}, served: ${servedForThisKey.size})`
       );
       let record;
       for (const rec of recordsWithKey) {
@@ -569,7 +593,7 @@ var ProxyServer = class {
       }
       servedForThisKey.add(record.recordingId);
       console.log(
-        `[REPLAY SERVING] recordingId: ${record.recordingId}, session: ${recordingId}, body_len: ${record.response?.body?.length || 0}`
+        `[replay serving] recordingId: ${record.recordingId}, session: ${recordingId}, body_len: ${record.response?.body?.length || 0}`
       );
       if (!record.response) {
         throw new Error(
@@ -950,28 +974,78 @@ async function stopProxy(testInfo) {
 }
 var playwrightProxy = {
   /**
-   * Setup before test - sets the proxy mode
+   * Setup before test - sets the proxy mode and configures page with custom header
+   * Automatically sets up page.on('close') handler for cleanup
+   * @param page - Playwright page object
    * @param testInfo - Playwright test info object
    * @param mode - The proxy mode to use for this test
+   * @param timeout - Optional timeout in milliseconds
    */
-  async before(testInfo, mode) {
+  async before(page, testInfo, mode, timeout) {
     const sessionId = generateSessionId(testInfo);
-    console.log("Proxy setup:", { mode, sessionId });
-    await setProxyMode(mode, sessionId);
+    await page.setExtraHTTPHeaders({
+      [RECORDING_ID_HEADER]: sessionId
+    });
+    await setProxyMode(mode, sessionId, timeout);
+    page.on("close", async () => {
+      try {
+        await setProxyMode(Modes.replay, sessionId);
+        console.log(
+          `[Cleanup] Switched to transparent mode for session: ${sessionId}`
+        );
+      } catch (error) {
+        console.error("[Cleanup] Error during page close cleanup:", error);
+      }
+    });
   },
   /**
-   * Cleanup after test - returns to transparent mode
-   * @param testInfo - Playwright test info object
+   * Global teardown - switches proxy to transparent mode
+   * Use this in Playwright's globalTeardown to ensure clean state
    */
-  async after(testInfo) {
-    const sessionId = generateSessionId(testInfo);
-    await setProxyMode(Modes.transparent, sessionId);
+  async teardown() {
+    await setProxyMode(Modes.transparent);
   }
 };
 
+// src/nextjs/middleware.ts
+function isRecorderEnabled() {
+  const isProduction = process.env.NODE_ENV === "production";
+  const isExplicitlyEnabled = process.env.TEST_PROXY_RECORDER_ENABLED === "true" || Number.parseInt(process.env.TEST_PROXY_RECORDER_ENABLED || "") === 1;
+  return !isProduction || isExplicitlyEnabled;
+}
+function setNextProxyHeaders(request, response) {
+  if (!isRecorderEnabled()) {
+    return;
+  }
+  const recordingId = request.headers.get(RECORDING_ID_HEADER);
+  if (recordingId) {
+    response.headers.set(RECORDING_ID_HEADER, recordingId);
+  }
+}
+function getRecordingId(requestHeaders) {
+  if (requestHeaders instanceof Headers) {
+    return requestHeaders.get(RECORDING_ID_HEADER);
+  }
+  return requestHeaders.headers.get(RECORDING_ID_HEADER);
+}
+function createHeadersWithRecordingId(requestHeaders, additionalHeaders = {}) {
+  if (!isRecorderEnabled()) {
+    return additionalHeaders;
+  }
+  const recordingId = getRecordingId(requestHeaders);
+  return {
+    ...additionalHeaders,
+    ...recordingId && { [RECORDING_ID_HEADER]: recordingId }
+  };
+}
+
 exports.ProxyServer = ProxyServer;
+exports.RECORDING_ID_HEADER = RECORDING_ID_HEADER;
+exports.createHeadersWithRecordingId = createHeadersWithRecordingId;
 exports.generateSessionId = generateSessionId;
+exports.getRecordingId = getRecordingId;
 exports.playwrightProxy = playwrightProxy;
+exports.setNextProxyHeaders = setNextProxyHeaders;
 exports.setProxyMode = setProxyMode;
 exports.startRecording = startRecording;
 exports.startReplay = startReplay;

package/dist/index.d.cts

@@ -1,5 +1,6 @@
+export { RECORDING_ID_HEADER, createHeadersWithRecordingId, getRecordingId, setNextProxyHeaders } from './nextjs/index.cjs';
 import http from 'node:http';
-export { C as ControlRequest, M as Mode, P as PlaywrightTestInfo, R as Recording, a as RecordingSession, W as WebSocketRecording, g as generateSessionId, p as playwrightProxy, s as setProxyMode, b as startRecording, c as startReplay, d as stopProxy } from './index-Cx_Kflfl.cjs';
+export { C as ControlRequest, M as Mode, P as PlaywrightTestInfo, R as Recording, a as RecordingSession, W as WebSocketRecording, g as generateSessionId, p as playwrightProxy, s as setProxyMode, b as startRecording, c as startReplay, d as stopProxy } from './index-CVuiglPk.cjs';
 import '@playwright/test';
 
 declare class ProxyServer {
@@ -28,13 +29,26 @@ declare class ProxyServer {
     private getCorsHeaders;
     private addCorsHeaders;
     private getTarget;
+    /**
+     * Extract recording ID from custom HTTP header
+     * Used for concurrent replay session routing, especially with Next.js
+     * @param req The incoming HTTP request
+     * @returns The recording ID from header, or null if not found
+     */
+    private getRecordingIdFromHeader;
     /**
      * Extract recording ID from request cookie
-     * Used for concurrent replay session routing
+     * Used for concurrent replay session routing (fallback method)
      * @param req The incoming HTTP request
      * @returns The recording ID from cookie, or null if not found
      */
     private getRecordingIdFromCookie;
+    /**
+     * Extract recording ID from request using custom header (preferred) or cookie (fallback)
+     * @param req The incoming HTTP request
+     * @returns The recording ID, or null if not found
+     */
+    private getRecordingIdFromRequest;
     /**
      * Get or create a replay session state for a given recording ID
      * @param recordingId The recording ID to get/create session for

package/dist/index.d.ts

@@ -1,5 +1,6 @@
+export { RECORDING_ID_HEADER, createHeadersWithRecordingId, getRecordingId, setNextProxyHeaders } from './nextjs/index.js';
 import http from 'node:http';
-export { C as ControlRequest, M as Mode, P as PlaywrightTestInfo, R as Recording, a as RecordingSession, W as WebSocketRecording, g as generateSessionId, p as playwrightProxy, s as setProxyMode, b as startRecording, c as startReplay, d as stopProxy } from './index-Cx_Kflfl.js';
+export { C as ControlRequest, M as Mode, P as PlaywrightTestInfo, R as Recording, a as RecordingSession, W as WebSocketRecording, g as generateSessionId, p as playwrightProxy, s as setProxyMode, b as startRecording, c as startReplay, d as stopProxy } from './index-CVuiglPk.js';
 import '@playwright/test';
 
 declare class ProxyServer {
@@ -28,13 +29,26 @@ declare class ProxyServer {
     private getCorsHeaders;
     private addCorsHeaders;
     private getTarget;
+    /**
+     * Extract recording ID from custom HTTP header
+     * Used for concurrent replay session routing, especially with Next.js
+     * @param req The incoming HTTP request
+     * @returns The recording ID from header, or null if not found
+     */
+    private getRecordingIdFromHeader;
     /**
      * Extract recording ID from request cookie
-     * Used for concurrent replay session routing
+     * Used for concurrent replay session routing (fallback method)
      * @param req The incoming HTTP request
      * @returns The recording ID from cookie, or null if not found
      */
     private getRecordingIdFromCookie;
+    /**
+     * Extract recording ID from request using custom header (preferred) or cookie (fallback)
+     * @param req The incoming HTTP request
+     * @returns The recording ID, or null if not found
+     */
+    private getRecordingIdFromRequest;
     /**
      * Get or create a replay session state for a given recording ID
      * @param recordingId The recording ID to get/create session for

package/dist/index.mjs

@@ -7,8 +7,6 @@ import crypto from 'crypto';
 import path from 'path';
 import filenamify2 from 'filenamify';
 
-// src/ProxyServer.ts
-
 // src/constants.ts
 var DEFAULT_TIMEOUT_MS = 120 * 1e3;
 var HTTP_STATUS_BAD_GATEWAY = 502;
@@ -16,6 +14,7 @@ var HTTP_STATUS_OK = 200;
 var HTTP_STATUS_BAD_REQUEST = 400;
 var HTTP_STATUS_NOT_FOUND = 404;
 var CONTROL_ENDPOINT = "/__control";
+var RECORDING_ID_HEADER = "x-test-rcrd-id";
 
 // src/types.ts
 var Modes = {
@@ -188,7 +187,7 @@ var ProxyServer = class {
     return {
       "access-control-allow-origin": origin || "*",
       "access-control-allow-credentials": "true",
-      "access-control-allow-headers": req.headers["access-control-request-headers"] || "Origin, X-Requested-With, Content-Type, Accept, Authorization",
+      "access-control-allow-headers": req.headers["access-control-request-headers"] || `Origin, X-Requested-With, Content-Type, Accept, Authorization, ${RECORDING_ID_HEADER}`,
       "access-control-allow-methods": "GET, POST, PUT, DELETE, PATCH, OPTIONS",
       "access-control-expose-headers": "*"
     };
@@ -202,9 +201,22 @@ var ProxyServer = class {
     this.currentTargetIndex = (this.currentTargetIndex + 1) % this.targets.length;
     return target;
   }
+  /**
+   * Extract recording ID from custom HTTP header
+   * Used for concurrent replay session routing, especially with Next.js
+   * @param req The incoming HTTP request
+   * @returns The recording ID from header, or null if not found
+   */
+  getRecordingIdFromHeader(req) {
+    const headerValue = req.headers[RECORDING_ID_HEADER];
+    if (!headerValue) {
+      return null;
+    }
+    return Array.isArray(headerValue) ? headerValue[0] : headerValue;
+  }
   /**
    * Extract recording ID from request cookie
-   * Used for concurrent replay session routing
+   * Used for concurrent replay session routing (fallback method)
    * @param req The incoming HTTP request
    * @returns The recording ID from cookie, or null if not found
    */
@@ -216,6 +228,14 @@ var ProxyServer = class {
     const match = cookies.match(/proxy-recording-id=([^;]+)/);
     return match ? decodeURIComponent(match[1]) : null;
   }
+  /**
+   * Extract recording ID from request using custom header (preferred) or cookie (fallback)
+   * @param req The incoming HTTP request
+   * @returns The recording ID, or null if not found
+   */
+  getRecordingIdFromRequest(req) {
+    return this.getRecordingIdFromHeader(req) || this.getRecordingIdFromCookie(req);
+  }
   /**
    * Get or create a replay session state for a given recording ID
    * @param recordingId The recording ID to get/create session for
@@ -493,7 +513,7 @@ var ProxyServer = class {
     return true;
   }
   async handleReplayRequest(req, res) {
-    const recordingId = this.getRecordingIdFromCookie(req) || this.replayId;
+    const recordingId = this.getRecordingIdFromRequest(req) || this.replayId;
     if (!recordingId) {
       const corsHeaders = this.getCorsHeaders(req);
       res.writeHead(HTTP_STATUS_BAD_REQUEST, {
@@ -517,7 +537,11 @@ var ProxyServer = class {
       }
       const servedForThisKey = sessionState.servedRecordingIdsByKey.get(key);
       const host = req.headers.host || "unknown";
-      const recordsWithKey = session.recordings.filter((r) => r.key === key && r.response).toSorted((a, b) => a.recordingId - b.recordingId);
+      const recordsWithKey = session.recordings.filter((r) => r.key === key && r.response).toSorted((a, b) => {
+        const aSeq = a.sequence !== void 0 ? a.sequence : a.recordingId;
+        const bSeq = b.sequence !== void 0 ? b.sequence : b.recordingId;
+        return aSeq - bSeq;
+      });
       if (recordsWithKey.length === 0) {
         const errorMsg = `No recording found for ${key} at ${req.method} ${host}${req.url}`;
         console.error(`[REPLAY ERROR] ${errorMsg} (session: ${recordingId})`);
@@ -540,7 +564,7 @@ var ProxyServer = class {
       }
       const requestCount = servedForThisKey.size + 1;
       console.log(
-        `[REPLAY REQUEST #${requestCount}] ${req.method} ${req.url} (session: ${recordingId}, total: ${recordsWithKey.length}, served: ${servedForThisKey.size})`
+        `[replay request #${requestCount}] ${req.method} ${req.url} (session: ${recordingId}, total: ${recordsWithKey.length}, served: ${servedForThisKey.size})`
       );
       let record;
       for (const rec of recordsWithKey) {
@@ -557,7 +581,7 @@ var ProxyServer = class {
       }
       servedForThisKey.add(record.recordingId);
       console.log(
-        `[REPLAY SERVING] recordingId: ${record.recordingId}, session: ${recordingId}, body_len: ${record.response?.body?.length || 0}`
+        `[replay serving] recordingId: ${record.recordingId}, session: ${recordingId}, body_len: ${record.response?.body?.length || 0}`
       );
       if (!record.response) {
         throw new Error(
@@ -938,25 +962,71 @@ async function stopProxy(testInfo) {
 }
 var playwrightProxy = {
   /**
-   * Setup before test - sets the proxy mode
+   * Setup before test - sets the proxy mode and configures page with custom header
+   * Automatically sets up page.on('close') handler for cleanup
+   * @param page - Playwright page object
    * @param testInfo - Playwright test info object
    * @param mode - The proxy mode to use for this test
+   * @param timeout - Optional timeout in milliseconds
    */
-  async before(testInfo, mode) {
+  async before(page, testInfo, mode, timeout) {
     const sessionId = generateSessionId(testInfo);
-    console.log("Proxy setup:", { mode, sessionId });
-    await setProxyMode(mode, sessionId);
+    await page.setExtraHTTPHeaders({
+      [RECORDING_ID_HEADER]: sessionId
+    });
+    await setProxyMode(mode, sessionId, timeout);
+    page.on("close", async () => {
+      try {
+        await setProxyMode(Modes.replay, sessionId);
+        console.log(
+          `[Cleanup] Switched to transparent mode for session: ${sessionId}`
+        );
+      } catch (error) {
+        console.error("[Cleanup] Error during page close cleanup:", error);
+      }
+    });
   },
   /**
-   * Cleanup after test - returns to transparent mode
-   * @param testInfo - Playwright test info object
+   * Global teardown - switches proxy to transparent mode
+   * Use this in Playwright's globalTeardown to ensure clean state
    */
-  async after(testInfo) {
-    const sessionId = generateSessionId(testInfo);
-    await setProxyMode(Modes.transparent, sessionId);
+  async teardown() {
+    await setProxyMode(Modes.transparent);
   }
 };
 
-export { ProxyServer, generateSessionId, playwrightProxy, setProxyMode, startRecording, startReplay, stopProxy };
+// src/nextjs/middleware.ts
+function isRecorderEnabled() {
+  const isProduction = process.env.NODE_ENV === "production";
+  const isExplicitlyEnabled = process.env.TEST_PROXY_RECORDER_ENABLED === "true" || Number.parseInt(process.env.TEST_PROXY_RECORDER_ENABLED || "") === 1;
+  return !isProduction || isExplicitlyEnabled;
+}
+function setNextProxyHeaders(request, response) {
+  if (!isRecorderEnabled()) {
+    return;
+  }
+  const recordingId = request.headers.get(RECORDING_ID_HEADER);
+  if (recordingId) {
+    response.headers.set(RECORDING_ID_HEADER, recordingId);
+  }
+}
+function getRecordingId(requestHeaders) {
+  if (requestHeaders instanceof Headers) {
+    return requestHeaders.get(RECORDING_ID_HEADER);
+  }
+  return requestHeaders.headers.get(RECORDING_ID_HEADER);
+}
+function createHeadersWithRecordingId(requestHeaders, additionalHeaders = {}) {
+  if (!isRecorderEnabled()) {
+    return additionalHeaders;
+  }
+  const recordingId = getRecordingId(requestHeaders);
+  return {
+    ...additionalHeaders,
+    ...recordingId && { [RECORDING_ID_HEADER]: recordingId }
+  };
+}
+
+export { ProxyServer, RECORDING_ID_HEADER, createHeadersWithRecordingId, generateSessionId, getRecordingId, playwrightProxy, setNextProxyHeaders, setProxyMode, startRecording, startReplay, stopProxy };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/dist/nextjs/index.cjs

@@ -0,0 +1,43 @@
+'use strict';
+
+// src/constants.ts
+var RECORDING_ID_HEADER = "x-test-rcrd-id";
+
+// src/nextjs/middleware.ts
+function isRecorderEnabled() {
+  const isProduction = process.env.NODE_ENV === "production";
+  const isExplicitlyEnabled = process.env.TEST_PROXY_RECORDER_ENABLED === "true" || Number.parseInt(process.env.TEST_PROXY_RECORDER_ENABLED || "") === 1;
+  return !isProduction || isExplicitlyEnabled;
+}
+function setNextProxyHeaders(request, response) {
+  if (!isRecorderEnabled()) {
+    return;
+  }
+  const recordingId = request.headers.get(RECORDING_ID_HEADER);
+  if (recordingId) {
+    response.headers.set(RECORDING_ID_HEADER, recordingId);
+  }
+}
+function getRecordingId(requestHeaders) {
+  if (requestHeaders instanceof Headers) {
+    return requestHeaders.get(RECORDING_ID_HEADER);
+  }
+  return requestHeaders.headers.get(RECORDING_ID_HEADER);
+}
+function createHeadersWithRecordingId(requestHeaders, additionalHeaders = {}) {
+  if (!isRecorderEnabled()) {
+    return additionalHeaders;
+  }
+  const recordingId = getRecordingId(requestHeaders);
+  return {
+    ...additionalHeaders,
+    ...recordingId && { [RECORDING_ID_HEADER]: recordingId }
+  };
+}
+
+exports.RECORDING_ID_HEADER = RECORDING_ID_HEADER;
+exports.createHeadersWithRecordingId = createHeadersWithRecordingId;
+exports.getRecordingId = getRecordingId;
+exports.setNextProxyHeaders = setNextProxyHeaders;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/nextjs/index.d.cts

@@ -0,0 +1,89 @@
+declare const RECORDING_ID_HEADER = "x-test-rcrd-id";
+
+/**
+ * Minimal type for Next.js Request - compatible with next/server's NextRequest
+ * We define this locally to avoid requiring Next.js as a dependency
+ */
+interface NextJSRequest {
+    headers: Headers;
+}
+/**
+ * Minimal type for Next.js Response - compatible with next/server's NextResponse
+ * We define this locally to avoid requiring Next.js as a dependency
+ */
+interface NextJSResponse {
+    headers: Headers;
+}
+/**
+ * Next.js middleware helper for forwarding test proxy recording headers
+ * Automatically forwards the recording ID header from incoming requests to the proxy
+ * Only runs in non-production environments or when TEST_PROXY_RECORDER_ENABLED is set
+ *
+ * @example
+ * // middleware.ts
+ * import { NextResponse } from 'next/server';
+ * import type { NextRequest } from 'next/server';
+ * import { setNextProxyHeaders } from 'test-proxy-recorder/nextjs';
+ *
+ * export function middleware(request: NextRequest) {
+ *   const response = NextResponse.next();
+ *   // Only forwards headers in test/dev environments
+ *   setNextProxyHeaders(request, response);
+ *   return response;
+ * }
+ *
+ * @param request - Next.js request object (NextRequest from next/server)
+ * @param response - Next.js response object (NextResponse from next/server)
+ */
+declare function setNextProxyHeaders(request: NextJSRequest, response: NextJSResponse): void;
+/**
+ * Get the recording ID from the request if present
+ * Useful for manually adding the header to fetch requests in Next.js
+ *
+ * @example
+ * // In your API route or server component
+ * import { getRecordingId } from 'test-proxy-recorder/nextjs';
+ * import { headers } from 'next/headers';
+ *
+ * export async function GET() {
+ *   const recordingId = getRecordingId(headers());
+ *
+ *   const response = await fetch('http://localhost:8100/api/data', {
+ *     headers: {
+ *       ...(recordingId && { 'x-test-rcrd-id': recordingId })
+ *     }
+ *   });
+ *
+ *   return Response.json(await response.json());
+ * }
+ *
+ * @param requestHeaders - Next.js headers object or NextRequest from next/server
+ * @returns The recording ID if present, null otherwise
+ */
+declare function getRecordingId(requestHeaders: NextJSRequest | Headers): string | null;
+/**
+ * Create headers object with recording ID for fetch requests
+ * Use this helper when making fetch requests in Next.js to forward the recording ID
+ *
+ * @example
+ * // In your API route or server component
+ * import { createHeadersWithRecordingId } from 'test-proxy-recorder/nextjs';
+ * import { headers } from 'next/headers';
+ *
+ * export async function GET() {
+ *   const response = await fetch('http://localhost:8100/api/data', {
+ *     headers: createHeadersWithRecordingId(headers(), {
+ *       'Content-Type': 'application/json',
+ *     })
+ *   });
+ *
+ *   return Response.json(await response.json());
+ * }
+ *
+ * @param requestHeaders - Next.js headers object or NextRequest from next/server
+ * @param additionalHeaders - Optional additional headers to include
+ * @returns Headers object with recording ID if present
+ */
+declare function createHeadersWithRecordingId(requestHeaders: NextJSRequest | Headers, additionalHeaders?: Record<string, string>): Record<string, string>;
+
+export { type NextJSRequest, type NextJSResponse, RECORDING_ID_HEADER, createHeadersWithRecordingId, getRecordingId, setNextProxyHeaders };

package/dist/nextjs/index.d.ts

@@ -0,0 +1,89 @@
+declare const RECORDING_ID_HEADER = "x-test-rcrd-id";
+
+/**
+ * Minimal type for Next.js Request - compatible with next/server's NextRequest
+ * We define this locally to avoid requiring Next.js as a dependency
+ */
+interface NextJSRequest {
+    headers: Headers;
+}
+/**
+ * Minimal type for Next.js Response - compatible with next/server's NextResponse
+ * We define this locally to avoid requiring Next.js as a dependency
+ */
+interface NextJSResponse {
+    headers: Headers;
+}
+/**
+ * Next.js middleware helper for forwarding test proxy recording headers
+ * Automatically forwards the recording ID header from incoming requests to the proxy
+ * Only runs in non-production environments or when TEST_PROXY_RECORDER_ENABLED is set
+ *
+ * @example
+ * // middleware.ts
+ * import { NextResponse } from 'next/server';
+ * import type { NextRequest } from 'next/server';
+ * import { setNextProxyHeaders } from 'test-proxy-recorder/nextjs';
+ *
+ * export function middleware(request: NextRequest) {
+ *   const response = NextResponse.next();
+ *   // Only forwards headers in test/dev environments
+ *   setNextProxyHeaders(request, response);
+ *   return response;
+ * }
+ *
+ * @param request - Next.js request object (NextRequest from next/server)
+ * @param response - Next.js response object (NextResponse from next/server)
+ */
+declare function setNextProxyHeaders(request: NextJSRequest, response: NextJSResponse): void;
+/**
+ * Get the recording ID from the request if present
+ * Useful for manually adding the header to fetch requests in Next.js
+ *
+ * @example
+ * // In your API route or server component
+ * import { getRecordingId } from 'test-proxy-recorder/nextjs';
+ * import { headers } from 'next/headers';
+ *
+ * export async function GET() {
+ *   const recordingId = getRecordingId(headers());
+ *
+ *   const response = await fetch('http://localhost:8100/api/data', {
+ *     headers: {
+ *       ...(recordingId && { 'x-test-rcrd-id': recordingId })
+ *     }
+ *   });
+ *
+ *   return Response.json(await response.json());
+ * }
+ *
+ * @param requestHeaders - Next.js headers object or NextRequest from next/server
+ * @returns The recording ID if present, null otherwise
+ */
+declare function getRecordingId(requestHeaders: NextJSRequest | Headers): string | null;
+/**
+ * Create headers object with recording ID for fetch requests
+ * Use this helper when making fetch requests in Next.js to forward the recording ID
+ *
+ * @example
+ * // In your API route or server component
+ * import { createHeadersWithRecordingId } from 'test-proxy-recorder/nextjs';
+ * import { headers } from 'next/headers';
+ *
+ * export async function GET() {
+ *   const response = await fetch('http://localhost:8100/api/data', {
+ *     headers: createHeadersWithRecordingId(headers(), {
+ *       'Content-Type': 'application/json',
+ *     })
+ *   });
+ *
+ *   return Response.json(await response.json());
+ * }
+ *
+ * @param requestHeaders - Next.js headers object or NextRequest from next/server
+ * @param additionalHeaders - Optional additional headers to include
+ * @returns Headers object with recording ID if present
+ */
+declare function createHeadersWithRecordingId(requestHeaders: NextJSRequest | Headers, additionalHeaders?: Record<string, string>): Record<string, string>;
+
+export { type NextJSRequest, type NextJSResponse, RECORDING_ID_HEADER, createHeadersWithRecordingId, getRecordingId, setNextProxyHeaders };

package/dist/nextjs/index.mjs

@@ -0,0 +1,38 @@
+// src/constants.ts
+var RECORDING_ID_HEADER = "x-test-rcrd-id";
+
+// src/nextjs/middleware.ts
+function isRecorderEnabled() {
+  const isProduction = process.env.NODE_ENV === "production";
+  const isExplicitlyEnabled = process.env.TEST_PROXY_RECORDER_ENABLED === "true" || Number.parseInt(process.env.TEST_PROXY_RECORDER_ENABLED || "") === 1;
+  return !isProduction || isExplicitlyEnabled;
+}
+function setNextProxyHeaders(request, response) {
+  if (!isRecorderEnabled()) {
+    return;
+  }
+  const recordingId = request.headers.get(RECORDING_ID_HEADER);
+  if (recordingId) {
+    response.headers.set(RECORDING_ID_HEADER, recordingId);
+  }
+}
+function getRecordingId(requestHeaders) {
+  if (requestHeaders instanceof Headers) {
+    return requestHeaders.get(RECORDING_ID_HEADER);
+  }
+  return requestHeaders.headers.get(RECORDING_ID_HEADER);
+}
+function createHeadersWithRecordingId(requestHeaders, additionalHeaders = {}) {
+  if (!isRecorderEnabled()) {
+    return additionalHeaders;
+  }
+  const recordingId = getRecordingId(requestHeaders);
+  return {
+    ...additionalHeaders,
+    ...recordingId && { [RECORDING_ID_HEADER]: recordingId }
+  };
+}
+
+export { RECORDING_ID_HEADER, createHeadersWithRecordingId, getRecordingId, setNextProxyHeaders };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/playwright/index.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+// src/constants.ts
+var RECORDING_ID_HEADER = "x-test-rcrd-id";
+
 // src/types.ts
 var Modes = {
   transparent: "transparent",
@@ -86,22 +89,36 @@ async function stopProxy(testInfo) {
 }
 var playwrightProxy = {
   /**
-   * Setup before test - sets the proxy mode
+   * Setup before test - sets the proxy mode and configures page with custom header
+   * Automatically sets up page.on('close') handler for cleanup
+   * @param page - Playwright page object
    * @param testInfo - Playwright test info object
    * @param mode - The proxy mode to use for this test
+   * @param timeout - Optional timeout in milliseconds
    */
-  async before(testInfo, mode) {
+  async before(page, testInfo, mode, timeout) {
     const sessionId = generateSessionId(testInfo);
-    console.log("Proxy setup:", { mode, sessionId });
-    await setProxyMode(mode, sessionId);
+    await page.setExtraHTTPHeaders({
+      [RECORDING_ID_HEADER]: sessionId
+    });
+    await setProxyMode(mode, sessionId, timeout);
+    page.on("close", async () => {
+      try {
+        await setProxyMode(Modes.replay, sessionId);
+        console.log(
+          `[Cleanup] Switched to transparent mode for session: ${sessionId}`
+        );
+      } catch (error) {
+        console.error("[Cleanup] Error during page close cleanup:", error);
+      }
+    });
   },
   /**
-   * Cleanup after test - returns to transparent mode
-   * @param testInfo - Playwright test info object
+   * Global teardown - switches proxy to transparent mode
+   * Use this in Playwright's globalTeardown to ensure clean state
    */
-  async after(testInfo) {
-    const sessionId = generateSessionId(testInfo);
-    await setProxyMode(Modes.transparent, sessionId);
+  async teardown() {
+    await setProxyMode(Modes.transparent);
   }
 };
 

package/dist/playwright/index.d.cts

@@ -1,3 +1,3 @@
 import '@playwright/test';
-export { P as PlaywrightTestInfo, g as generateSessionId, p as playwrightProxy, s as setProxyMode, b as startRecording, c as startReplay, d as stopProxy } from '../index-Cx_Kflfl.cjs';
+export { P as PlaywrightTestInfo, g as generateSessionId, p as playwrightProxy, s as setProxyMode, b as startRecording, c as startReplay, d as stopProxy } from '../index-CVuiglPk.cjs';
 import 'node:http';

package/dist/playwright/index.d.ts

@@ -1,3 +1,3 @@
 import '@playwright/test';
-export { P as PlaywrightTestInfo, g as generateSessionId, p as playwrightProxy, s as setProxyMode, b as startRecording, c as startReplay, d as stopProxy } from '../index-Cx_Kflfl.js';
+export { P as PlaywrightTestInfo, g as generateSessionId, p as playwrightProxy, s as setProxyMode, b as startRecording, c as startReplay, d as stopProxy } from '../index-CVuiglPk.js';
 import 'node:http';

package/dist/playwright/index.mjs

@@ -1,3 +1,6 @@
+// src/constants.ts
+var RECORDING_ID_HEADER = "x-test-rcrd-id";
+
 // src/types.ts
 var Modes = {
   transparent: "transparent",
@@ -84,22 +87,36 @@ async function stopProxy(testInfo) {
 }
 var playwrightProxy = {
   /**
-   * Setup before test - sets the proxy mode
+   * Setup before test - sets the proxy mode and configures page with custom header
+   * Automatically sets up page.on('close') handler for cleanup
+   * @param page - Playwright page object
    * @param testInfo - Playwright test info object
    * @param mode - The proxy mode to use for this test
+   * @param timeout - Optional timeout in milliseconds
    */
-  async before(testInfo, mode) {
+  async before(page, testInfo, mode, timeout) {
     const sessionId = generateSessionId(testInfo);
-    console.log("Proxy setup:", { mode, sessionId });
-    await setProxyMode(mode, sessionId);
+    await page.setExtraHTTPHeaders({
+      [RECORDING_ID_HEADER]: sessionId
+    });
+    await setProxyMode(mode, sessionId, timeout);
+    page.on("close", async () => {
+      try {
+        await setProxyMode(Modes.replay, sessionId);
+        console.log(
+          `[Cleanup] Switched to transparent mode for session: ${sessionId}`
+        );
+      } catch (error) {
+        console.error("[Cleanup] Error during page close cleanup:", error);
+      }
+    });
   },
   /**
-   * Cleanup after test - returns to transparent mode
-   * @param testInfo - Playwright test info object
+   * Global teardown - switches proxy to transparent mode
+   * Use this in Playwright's globalTeardown to ensure clean state
    */
-  async after(testInfo) {
-    const sessionId = generateSessionId(testInfo);
-    await setProxyMode(Modes.transparent, sessionId);
+  async teardown() {
+    await setProxyMode(Modes.transparent);
   }
 };
 

package/dist/proxy.js

@@ -50,6 +50,7 @@ var HTTP_STATUS_OK = 200;
 var HTTP_STATUS_BAD_REQUEST = 400;
 var HTTP_STATUS_NOT_FOUND = 404;
 var CONTROL_ENDPOINT = "/__control";
+var RECORDING_ID_HEADER = "x-test-rcrd-id";
 
 // src/types.ts
 var Modes = {
@@ -222,7 +223,7 @@ var ProxyServer = class {
     return {
       "access-control-allow-origin": origin || "*",
       "access-control-allow-credentials": "true",
-      "access-control-allow-headers": req.headers["access-control-request-headers"] || "Origin, X-Requested-With, Content-Type, Accept, Authorization",
+      "access-control-allow-headers": req.headers["access-control-request-headers"] || `Origin, X-Requested-With, Content-Type, Accept, Authorization, ${RECORDING_ID_HEADER}`,
       "access-control-allow-methods": "GET, POST, PUT, DELETE, PATCH, OPTIONS",
       "access-control-expose-headers": "*"
     };
@@ -236,9 +237,22 @@ var ProxyServer = class {
     this.currentTargetIndex = (this.currentTargetIndex + 1) % this.targets.length;
     return target;
   }
+  /**
+   * Extract recording ID from custom HTTP header
+   * Used for concurrent replay session routing, especially with Next.js
+   * @param req The incoming HTTP request
+   * @returns The recording ID from header, or null if not found
+   */
+  getRecordingIdFromHeader(req) {
+    const headerValue = req.headers[RECORDING_ID_HEADER];
+    if (!headerValue) {
+      return null;
+    }
+    return Array.isArray(headerValue) ? headerValue[0] : headerValue;
+  }
   /**
    * Extract recording ID from request cookie
-   * Used for concurrent replay session routing
+   * Used for concurrent replay session routing (fallback method)
    * @param req The incoming HTTP request
    * @returns The recording ID from cookie, or null if not found
    */
@@ -250,6 +264,14 @@ var ProxyServer = class {
     const match = cookies.match(/proxy-recording-id=([^;]+)/);
     return match ? decodeURIComponent(match[1]) : null;
   }
+  /**
+   * Extract recording ID from request using custom header (preferred) or cookie (fallback)
+   * @param req The incoming HTTP request
+   * @returns The recording ID, or null if not found
+   */
+  getRecordingIdFromRequest(req) {
+    return this.getRecordingIdFromHeader(req) || this.getRecordingIdFromCookie(req);
+  }
   /**
    * Get or create a replay session state for a given recording ID
    * @param recordingId The recording ID to get/create session for
@@ -527,7 +549,7 @@ var ProxyServer = class {
     return true;
   }
   async handleReplayRequest(req, res) {
-    const recordingId = this.getRecordingIdFromCookie(req) || this.replayId;
+    const recordingId = this.getRecordingIdFromRequest(req) || this.replayId;
     if (!recordingId) {
       const corsHeaders = this.getCorsHeaders(req);
       res.writeHead(HTTP_STATUS_BAD_REQUEST, {
@@ -551,7 +573,11 @@ var ProxyServer = class {
       }
       const servedForThisKey = sessionState.servedRecordingIdsByKey.get(key);
       const host = req.headers.host || "unknown";
-      const recordsWithKey = session.recordings.filter((r) => r.key === key && r.response).toSorted((a, b) => a.recordingId - b.recordingId);
+      const recordsWithKey = session.recordings.filter((r) => r.key === key && r.response).toSorted((a, b) => {
+        const aSeq = a.sequence !== void 0 ? a.sequence : a.recordingId;
+        const bSeq = b.sequence !== void 0 ? b.sequence : b.recordingId;
+        return aSeq - bSeq;
+      });
       if (recordsWithKey.length === 0) {
         const errorMsg = `No recording found for ${key} at ${req.method} ${host}${req.url}`;
         console.error(`[REPLAY ERROR] ${errorMsg} (session: ${recordingId})`);
@@ -574,7 +600,7 @@ var ProxyServer = class {
       }
       const requestCount = servedForThisKey.size + 1;
       console.log(
-        `[REPLAY REQUEST #${requestCount}] ${req.method} ${req.url} (session: ${recordingId}, total: ${recordsWithKey.length}, served: ${servedForThisKey.size})`
+        `[replay request #${requestCount}] ${req.method} ${req.url} (session: ${recordingId}, total: ${recordsWithKey.length}, served: ${servedForThisKey.size})`
       );
       let record;
       for (const rec of recordsWithKey) {
@@ -591,7 +617,7 @@ var ProxyServer = class {
       }
       servedForThisKey.add(record.recordingId);
       console.log(
-        `[REPLAY SERVING] recordingId: ${record.recordingId}, session: ${recordingId}, body_len: ${record.response?.body?.length || 0}`
+        `[replay serving] recordingId: ${record.recordingId}, session: ${recordingId}, body_len: ${record.response?.body?.length || 0}`
       );
       if (!record.response) {
         throw new Error(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "test-proxy-recorder",
-  "version": "0.1.11",
+  "version": "0.3.0",
   "description": "HTTP proxy server for recording and replaying network requests in testing. Works seamlessly with Playwright testing framework.",
   "type": "module",
   "main": "dist/index.mjs",
@@ -15,6 +15,11 @@
       "require": "./dist/playwright/index.cjs",
       "types": "./dist/playwright/index.d.ts",
       "default": "./dist/playwright/index.mjs"
+    },
+    "./nextjs": {
+      "require": "./dist/nextjs/index.cjs",
+      "types": "./dist/nextjs/index.d.ts",
+      "default": "./dist/nextjs/index.mjs"
     }
   },
   "bin": {