@harness-fe/runtime 3.2.0 → 3.3.0

package/dist/client.d.ts

@@ -28,6 +28,13 @@ export interface ClientOptions {
      * by visitorId). Propagated by HarnessScript via window.__HARNESS_FE__.userId.
      */
     userId?: string;
+    /**
+     * How often (in ms) rrweb should emit a fresh FullSnapshot baseline.
+     * Defaults to 30 minutes. Set to 0 to disable periodic baselines (the
+     * recorder still emits one at start() and one per ws reconnect).
+     * See {@link RrwebRecorderOptions.checkoutEveryNms} for the trade-off.
+     */
+    rrwebCheckoutEveryNms?: number;
 }
 export { tryInheritFromParent } from './parent-inherit.js';
 export type { ParentInheritance } from './parent-inherit.js';

package/dist/client.js

@@ -90,7 +90,10 @@ export class RuntimeClient {
     }
     pageLoadSent = false;
     ctx = { capture: getCaptureStore() };
-    recorder = new RrwebRecorder((chunk) => this.sendEvent(EVENT_NAME.RRWEB, chunk));
+    // Initialized in constructor (parameter property `opts` isn't readable at
+    // class-field-initializer time — field initializers run before parameter
+    // property assignment).
+    recorder;
     reconnectAttempts = 0;
     closed = false;
     static MAX_OUTBOX_FRAMES = 500;
@@ -109,6 +112,7 @@ export class RuntimeClient {
         const inheritedVisitor = tryInheritVisitorFromParent();
         this.visitorId = inheritedVisitor ?? getOrCreateVisitorId();
         publishVisitorIdToWindow(this.visitorId);
+        this.recorder = new RrwebRecorder((chunk) => this.sendEvent(EVENT_NAME.RRWEB, chunk), { checkoutEveryNms: opts.rrwebCheckoutEveryNms });
     }
     start() {
         const daemonUrl = this.opts.mcpUrl ?? `ws://127.0.0.1:${DEFAULT_WS_PORT}`;

package/dist/recording.d.ts

@@ -1,12 +1,27 @@
 import type { RrwebChunkPayload } from '@harness-fe/protocol';
 export { RRWEB_FULL_SNAPSHOT_TYPE, chunkHasFullSnapshot } from './rrweb-types.js';
+export interface RrwebRecorderOptions {
+    /**
+     * Force rrweb to emit a fresh FullSnapshot every N milliseconds. Caps how
+     * stale the most recent baseline can be, so window replays mid-session
+     * don't have to roll forward from a baseline that's potentially hours old.
+     *
+     * Set to `0` (or a negative number) to disable periodic baselines and
+     * rely solely on the start() baseline + reconnect baselines. Useful for
+     * extremely bandwidth-constrained deployments.
+     *
+     * @default 30 * 60 * 1000  (30 minutes)
+     */
+    checkoutEveryNms?: number;
+}
 export declare class RrwebRecorder {
     private readonly onChunk;
+    private readonly opts;
     private stopRecording?;
     private flushTimer?;
     private chunkSeq;
     private buffer;
-    constructor(onChunk: (chunk: RrwebChunkPayload) => void);
+    constructor(onChunk: (chunk: RrwebChunkPayload) => void, opts?: RrwebRecorderOptions);
     start(): void;
     stop(): void;
     /**

package/dist/recording.js

@@ -2,24 +2,38 @@ import { record } from 'rrweb';
 export { RRWEB_FULL_SNAPSHOT_TYPE, chunkHasFullSnapshot } from './rrweb-types.js';
 const FLUSH_MS = 5_000;
 const MAX_EVENTS = 200;
+// Default periodic-baseline cadence. Long-running sessions otherwise rely on
+// a single FullSnapshot at start() + one per ws reconnect, which makes
+// mid-session window replays expensive (rrweb has to roll forward all
+// incremental events back to the original baseline) and leaves a window of
+// vulnerability if the original baseline is ever evicted from the outbox.
+// 30 min is a deliberate middle ground: ~16 baselines per 8h session at
+// ~500KB each ≈ 8MB extra storage, which is acceptable for a dev tool.
+const DEFAULT_CHECKOUT_EVERY_MS = 30 * 60 * 1000;
 export class RrwebRecorder {
     onChunk;
+    opts;
     stopRecording;
     flushTimer;
     chunkSeq = 0;
     buffer = [];
-    constructor(onChunk) {
+    constructor(onChunk, opts = {}) {
         this.onChunk = onChunk;
+        this.opts = opts;
     }
     start() {
         if (this.stopRecording)
             return;
+        const checkoutEveryNms = this.opts.checkoutEveryNms ?? DEFAULT_CHECKOUT_EVERY_MS;
+        // rrweb interprets `checkoutEveryNms` falsy / undefined as "off".
+        // Pass undefined when disabled so we get the native off-path.
         this.stopRecording = record({
             emit: (event) => this.push(event),
             inlineImages: false,
             recordCanvas: false,
             collectFonts: false,
             maskAllInputs: false,
+            checkoutEveryNms: checkoutEveryNms > 0 ? checkoutEveryNms : undefined,
         });
         this.flushTimer = window.setInterval(() => this.flush(), FLUSH_MS);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harness-fe/runtime",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Browser-side SDK injected into the dev page. Connects to the MCP server via WebSocket and executes commands.",
   "type": "module",
   "license": "MIT",

package/src/client.ts

@@ -53,6 +53,13 @@ export interface ClientOptions {
      * by visitorId). Propagated by HarnessScript via window.__HARNESS_FE__.userId.
      */
     userId?: string;
+    /**
+     * How often (in ms) rrweb should emit a fresh FullSnapshot baseline.
+     * Defaults to 30 minutes. Set to 0 to disable periodic baselines (the
+     * recorder still emits one at start() and one per ws reconnect).
+     * See {@link RrwebRecorderOptions.checkoutEveryNms} for the trade-off.
+     */
+    rrwebCheckoutEveryNms?: number;
 }
 
 const TAB_ID_KEY = '__hfe_tab_id__';
@@ -137,7 +144,10 @@ export class RuntimeClient {
     }
     private pageLoadSent = false;
     private readonly ctx: CommandContext = { capture: getCaptureStore() };
-    private readonly recorder = new RrwebRecorder((chunk) => this.sendEvent(EVENT_NAME.RRWEB, chunk));
+    // Initialized in constructor (parameter property `opts` isn't readable at
+    // class-field-initializer time — field initializers run before parameter
+    // property assignment).
+    private readonly recorder: RrwebRecorder;
     private reconnectAttempts = 0;
     private closed = false;
     private static readonly MAX_OUTBOX_FRAMES = 500;
@@ -159,6 +169,10 @@ export class RuntimeClient {
         const inheritedVisitor = tryInheritVisitorFromParent();
         this.visitorId = inheritedVisitor ?? getOrCreateVisitorId();
         publishVisitorIdToWindow(this.visitorId);
+        this.recorder = new RrwebRecorder(
+            (chunk) => this.sendEvent(EVENT_NAME.RRWEB, chunk),
+            { checkoutEveryNms: opts.rrwebCheckoutEveryNms },
+        );
     }
 
 

package/src/recording.test.ts

@@ -0,0 +1,57 @@
+// @vitest-environment happy-dom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+// vi.mock is hoisted, so the spy refs need to be hoisted alongside it.
+const { recordSpy, takeFullSnapshotSpy } = vi.hoisted(() => {
+    const takeFullSnapshotSpy = vi.fn();
+    const recordSpy = vi.fn(() => () => { /* stop noop */ });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (recordSpy as any).takeFullSnapshot = takeFullSnapshotSpy;
+    return { recordSpy, takeFullSnapshotSpy };
+});
+
+vi.mock('rrweb', () => ({
+    record: recordSpy,
+    EventType: { Custom: 5 },
+}));
+
+import { RrwebRecorder } from './recording.js';
+
+afterEach(() => {
+    recordSpy.mockClear();
+    takeFullSnapshotSpy.mockClear();
+});
+
+describe('RrwebRecorder periodic baseline (checkoutEveryNms)', () => {
+    it('passes the default 30-minute interval to rrweb when no option supplied', () => {
+        const r = new RrwebRecorder(() => { /* noop */ });
+        r.start();
+        const call = recordSpy.mock.calls[0]?.[0] as { checkoutEveryNms?: number };
+        expect(call.checkoutEveryNms).toBe(30 * 60 * 1000);
+        r.stop();
+    });
+
+    it('honors an explicit interval', () => {
+        const r = new RrwebRecorder(() => { /* noop */ }, { checkoutEveryNms: 60_000 });
+        r.start();
+        const call = recordSpy.mock.calls[0]?.[0] as { checkoutEveryNms?: number };
+        expect(call.checkoutEveryNms).toBe(60_000);
+        r.stop();
+    });
+
+    it('disables periodic baselines when interval is 0', () => {
+        const r = new RrwebRecorder(() => { /* noop */ }, { checkoutEveryNms: 0 });
+        r.start();
+        const call = recordSpy.mock.calls[0]?.[0] as { checkoutEveryNms?: number };
+        expect(call.checkoutEveryNms).toBeUndefined();
+        r.stop();
+    });
+
+    it('disables periodic baselines for negative intervals', () => {
+        const r = new RrwebRecorder(() => { /* noop */ }, { checkoutEveryNms: -1 });
+        r.start();
+        const call = recordSpy.mock.calls[0]?.[0] as { checkoutEveryNms?: number };
+        expect(call.checkoutEveryNms).toBeUndefined();
+        r.stop();
+    });
+});

package/src/recording.ts

@@ -5,6 +5,29 @@ export { RRWEB_FULL_SNAPSHOT_TYPE, chunkHasFullSnapshot } from './rrweb-types.js
 
 const FLUSH_MS = 5_000;
 const MAX_EVENTS = 200;
+// Default periodic-baseline cadence. Long-running sessions otherwise rely on
+// a single FullSnapshot at start() + one per ws reconnect, which makes
+// mid-session window replays expensive (rrweb has to roll forward all
+// incremental events back to the original baseline) and leaves a window of
+// vulnerability if the original baseline is ever evicted from the outbox.
+// 30 min is a deliberate middle ground: ~16 baselines per 8h session at
+// ~500KB each ≈ 8MB extra storage, which is acceptable for a dev tool.
+const DEFAULT_CHECKOUT_EVERY_MS = 30 * 60 * 1000;
+
+export interface RrwebRecorderOptions {
+    /**
+     * Force rrweb to emit a fresh FullSnapshot every N milliseconds. Caps how
+     * stale the most recent baseline can be, so window replays mid-session
+     * don't have to roll forward from a baseline that's potentially hours old.
+     *
+     * Set to `0` (or a negative number) to disable periodic baselines and
+     * rely solely on the start() baseline + reconnect baselines. Useful for
+     * extremely bandwidth-constrained deployments.
+     *
+     * @default 30 * 60 * 1000  (30 minutes)
+     */
+    checkoutEveryNms?: number;
+}
 
 export class RrwebRecorder {
     private stopRecording?: () => void;
@@ -12,16 +35,23 @@ export class RrwebRecorder {
     private chunkSeq = 0;
     private buffer: unknown[] = [];
 
-    constructor(private readonly onChunk: (chunk: RrwebChunkPayload) => void) {}
+    constructor(
+        private readonly onChunk: (chunk: RrwebChunkPayload) => void,
+        private readonly opts: RrwebRecorderOptions = {},
+    ) {}
 
     start(): void {
         if (this.stopRecording) return;
+        const checkoutEveryNms = this.opts.checkoutEveryNms ?? DEFAULT_CHECKOUT_EVERY_MS;
+        // rrweb interprets `checkoutEveryNms` falsy / undefined as "off".
+        // Pass undefined when disabled so we get the native off-path.
         this.stopRecording = record({
             emit: (event: unknown) => this.push(event),
             inlineImages: false,
             recordCanvas: false,
             collectFonts: false,
             maskAllInputs: false,
+            checkoutEveryNms: checkoutEveryNms > 0 ? checkoutEveryNms : undefined,
         });
         this.flushTimer = window.setInterval(() => this.flush(), FLUSH_MS);
     }