@harness-fe/runtime 3.2.0 → 3.4.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/index.d.ts

@@ -6,3 +6,5 @@
  */
 export { RuntimeClient, tryInheritFromParent } from './client.js';
 export type { ClientOptions, ParentInheritance } from './client.js';
+export { registerOverlayPlugin, getOverlayPlugins, subscribeOverlayPlugins, } from './pluginRegistry.js';
+export type { OverlayPlugin, OverlayPluginContext, OverlayPluginSelectedElement, OverlayPluginSelector, OverlayPluginLogs, OverlayPluginGetLogsOptions, } from './pluginRegistry.js';

package/dist/index.js

@@ -6,9 +6,17 @@
  */
 import { installOverlay } from './overlay.js';
 import { RuntimeClient, readInjectedConfig } from './client.js';
+import { registerOverlayPlugin, drainPluginQueue, } from './pluginRegistry.js';
+// Informational; keep in sync with package.json on release.
+const VERSION = '3.3.0';
 const w = window;
 if (typeof window !== 'undefined' && !w.__harness_fe_started__) {
     w.__harness_fe_started__ = true;
+    // Public global for runtime plugin registration. Works before or after the
+    // overlay mounts — the registry buffers and the overlay subscribes.
+    w.HarnessFE = { registerOverlayPlugin, version: VERSION };
+    // Drain any plugins queued before the runtime loaded.
+    drainPluginQueue(w.__HARNESS_FE_PLUGINS__);
     const cfg = readInjectedConfig();
     const client = new RuntimeClient(cfg);
     client.start();
@@ -21,3 +29,4 @@ if (typeof window !== 'undefined' && !w.__harness_fe_started__) {
     w.__hfe_session_id__ = client.sessionId;
 }
 export { RuntimeClient, tryInheritFromParent } from './client.js';
+export { registerOverlayPlugin, getOverlayPlugins, subscribeOverlayPlugins, } from './pluginRegistry.js';

package/dist/overlay.d.ts

@@ -14,6 +14,7 @@
  * or out. State machine: idle → info → (picker → question) → flash → idle.
  */
 import { type TaskAttachment } from '@harness-fe/protocol';
+import { type OverlayPluginLogs, type OverlayPluginGetLogsOptions } from './pluginRegistry.js';
 export interface OverlayClient {
     readonly projectId: string;
     readonly buildId?: string;
@@ -60,6 +61,14 @@ export declare function replayStrokes(ctx: CanvasRenderingContext2D, bgCanvas: H
  * Exported for testing.
  */
 export declare function finalizeAnnotation(): Promise<TaskAttachment | null>;
+/**
+ * Rasterize an element to a PNG TaskAttachment via snapdom. Returns null on
+ * failure (cross-origin, test env, …) so plugins can degrade gracefully.
+ * Exported for testing.
+ */
+export declare function captureElementPng(el: Element): Promise<TaskAttachment | null>;
+/** Read recent buffered logs for the plugin context. Redacts network by default. */
+export declare function collectLogs(opts?: OverlayPluginGetLogsOptions): OverlayPluginLogs;
 /**
  * Best-effort CSS path. Depth cap 12, id anchor short-circuits, ` >>> `
  * separates shadow-DOM boundaries.

package/dist/overlay.js

@@ -13,9 +13,14 @@
  * Single Shadow DOM root attached to <body>; host page styles never leak in
  * or out. State machine: idle → info → (picker → question) → flash → idle.
  */
-import { EVENT_NAME } from '@harness-fe/protocol';
+import { EVENT_NAME, } from '@harness-fe/protocol';
 import { snapdom } from '@zumer/snapdom';
 import { deriveDashboardUrl } from './dashboardUrl.js';
+import { getCaptureStore } from './capture.js';
+import { collectPageLoadSnapshot } from './snapshot.js';
+import { getOverlayPlugins, subscribeOverlayPlugins, } from './pluginRegistry.js';
+/** Repo URL surfaced in the overlay footer. */
+const GITHUB_URL = 'https://github.com/Morphicai/harness-fe';
 const HOST_ID = '__harness_fe_overlay__';
 const MAX_OUTER_HTML = 2048;
 // Internal instrumentation attributes injected by our build plugin. Must be
@@ -242,6 +247,8 @@ export function installOverlay(client) {
     let statusPollTimer;
     /** Flattened PNG from the annotate step; null if user skipped. */
     let pendingAttachment = null;
+    /** Set while the picker is collecting an element for a `requiresElement` plugin. */
+    let pluginAwaitingElement = null;
     const setState = (next) => {
         state = next;
         infoCard.style.display = next === 'info' ? 'flex' : 'none';
@@ -314,6 +321,17 @@ export function installOverlay(client) {
             return;
         lockedEl = hoveredEl;
         setHighlight(lockedEl);
+        // A plugin requested the element — hand it straight to its onClick and
+        // skip the report/question flow entirely.
+        if (pluginAwaitingElement) {
+            const plugin = pluginAwaitingElement;
+            pluginAwaitingElement = null;
+            const el = lockedEl;
+            lockedEl = null;
+            setState('idle');
+            void invokePlugin(plugin, el);
+            return;
+        }
         // Go straight to the question step. Screenshots are now opt-in via
         // the "Add screenshot" button inside the question panel — users
         // shouldn't have to draw on every report.
@@ -339,6 +357,7 @@ export function installOverlay(client) {
             else if (state === 'picker' || state === 'question') {
                 lockedEl = null;
                 pendingAttachment = null;
+                pluginAwaitingElement = null;
                 setState('info');
             }
             else if (state === 'info') {
@@ -425,6 +444,103 @@ export function installOverlay(client) {
         lines.push(`- daemon: ${client.getConnectionState()}`);
         return lines.join('\n') + '\n';
     };
+    // ─── Plugin support ──────────────────────────────────────────────────
+    const dashboardUrl = client.mcpUrl
+        ? deriveDashboardUrl({ mcpUrl: client.mcpUrl, sessionId: client.sessionId })
+        : undefined;
+    /** Brief transient toast anchored near the FAB. */
+    const showToast = (message, kind = 'ok') => {
+        const el = document.createElement('div');
+        el.className = 'hfe-toast';
+        el.dataset.kind = kind;
+        el.textContent = message;
+        root.appendChild(el);
+        requestAnimationFrame(() => { el.dataset.show = '1'; });
+        setTimeout(() => {
+            el.dataset.show = '';
+            setTimeout(() => el.remove(), 250);
+        }, 2400);
+    };
+    const buildPluginContext = (selectedEl) => {
+        const selectedElement = selectedEl
+            ? {
+                el: selectedEl,
+                selector: {
+                    comp: selectedEl.getAttribute('data-morphix-comp') ?? undefined,
+                    loc: selectedEl.getAttribute('data-morphix-loc') ?? undefined,
+                    css: buildCssPath(selectedEl),
+                },
+                outerHTML: truncate(stripInternalAttrs(selectedEl.outerHTML), MAX_OUTER_HTML),
+                rect: (() => {
+                    const r = selectedEl.getBoundingClientRect();
+                    return { x: r.x, y: r.y, width: r.width, height: r.height };
+                })(),
+            }
+            : undefined;
+        return {
+            projectId: client.projectId,
+            displayName: client.displayName,
+            buildId: client.buildId,
+            parentProjectId: client.parentProjectId,
+            sessionId: client.sessionId,
+            tabId: client.tabId,
+            visitorId: client.visitorId,
+            userId: client.userId,
+            url: location.href,
+            connectionState: client.getConnectionState(),
+            dashboardUrl,
+            selectedElement,
+            snapshotMarkdown: buildSnapshot,
+            snapshot: () => collectPageLoadSnapshot(client.sessionId),
+            getLogs: (opts) => collectLogs(opts),
+            captureScreenshot: (el) => captureElementPng(el ?? selectedEl ?? document.body),
+            query: client.query ? client.query.bind(client) : undefined,
+            copyToClipboard: (text) => copyText(text),
+            toast: showToast,
+        };
+    };
+    const invokePlugin = async (plugin, selectedEl) => {
+        try {
+            await plugin.onClick(buildPluginContext(selectedEl));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            showToast(`${plugin.label}: ${msg}`, 'error');
+        }
+    };
+    /** (Re)render the plugin button group in the info card. */
+    const renderPluginButtons = () => {
+        const slot = infoCard.querySelector('[data-role=plugin-actions]');
+        if (!slot)
+            return;
+        const list = getOverlayPlugins();
+        slot.innerHTML = '';
+        slot.style.display = list.length ? '' : 'none';
+        for (const plugin of list) {
+            const btn = document.createElement('button');
+            btn.className = 'secondary';
+            btn.type = 'button';
+            btn.dataset.pluginId = plugin.id;
+            btn.textContent = `${plugin.icon ? plugin.icon + ' ' : ''}${plugin.label}`;
+            btn.addEventListener('click', () => {
+                if (plugin.requiresElement) {
+                    pluginAwaitingElement = plugin;
+                    setState('picker');
+                }
+                else {
+                    setState('idle');
+                    void invokePlugin(plugin);
+                }
+            });
+            slot.appendChild(btn);
+        }
+    };
+    renderPluginButtons();
+    const unsubscribePlugins = subscribeOverlayPlugins(() => {
+        // Only the info card shows plugin buttons; re-render whenever the set changes.
+        renderPluginButtons();
+    });
+    void unsubscribePlugins; // overlay lives for the page lifetime; no teardown path
     // ─── Reports rendering ───────────────────────────────────────────────
     let editingTaskId = null;
     let deleteConfirmId = null;
@@ -653,9 +769,6 @@ export function installOverlay(client) {
     // the plugin / runtime config).
     {
         const dashboardBtn = infoCard.querySelector('[data-role=open-dashboard]');
-        const dashboardUrl = client.mcpUrl
-            ? deriveDashboardUrl({ mcpUrl: client.mcpUrl, sessionId: client.sessionId })
-            : undefined;
         if (dashboardUrl) {
             dashboardBtn.style.display = '';
             dashboardBtn.title = `Open ${dashboardUrl} in a new tab`;
@@ -671,6 +784,19 @@ export function installOverlay(client) {
             });
         }
     }
+    // GitHub promo link — anchor navigates natively; this fallback covers
+    // sandboxed iframes / popup blockers by copying the URL instead.
+    infoCard.querySelector('[data-role=github]').addEventListener('click', (ev) => {
+        try {
+            const opened = window.open(GITHUB_URL, '_blank', 'noopener,noreferrer');
+            if (opened)
+                ev.preventDefault();
+        }
+        catch {
+            ev.preventDefault();
+            void copyText(GITHUB_URL, ev.currentTarget);
+        }
+    });
     reportsCard.querySelector('[data-role=back]').addEventListener('click', () => setState('info'));
     reportsCard.querySelector('[data-role=close]').addEventListener('click', () => setState('idle'));
     reportsCard.querySelector('[data-role=refresh]').addEventListener('click', () => void refreshReports());
@@ -688,6 +814,7 @@ export function installOverlay(client) {
     }
     pickerBar.querySelector('[data-role=cancel]').addEventListener('click', () => {
         lockedEl = null;
+        pluginAwaitingElement = null;
         setState('info');
     });
     questionPanel.querySelector('[data-role=cancel]').addEventListener('click', () => {
@@ -1037,6 +1164,62 @@ export async function finalizeAnnotation() {
     resetAnnotateStrokes();
     return att;
 }
+// ─── Plugin helpers (screenshot / logs) ───────────────────────────────────
+/**
+ * Rasterize an element to a PNG TaskAttachment via snapdom. Returns null on
+ * failure (cross-origin, test env, …) so plugins can degrade gracefully.
+ * Exported for testing.
+ */
+export async function captureElementPng(el) {
+    try {
+        const result = await snapdom(el, { fast: true });
+        const canvas = await result.toCanvas();
+        const dataUrl = canvas.toDataURL('image/png', 0.85);
+        const base64 = dataUrl.replace(/^data:image\/png;base64,/, '');
+        return {
+            id: `att_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`,
+            kind: 'screenshot',
+            data: base64,
+            width: canvas.width || 1,
+            height: canvas.height || 1,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+const SENSITIVE_HEADER_RE = /^(authorization|cookie|set-cookie|proxy-authorization)$/i;
+/** Strip bodies + auth/cookie headers from a network entry. */
+function redactNetworkEntry(e) {
+    const out = { ...e };
+    delete out.requestBody;
+    delete out.responseBody;
+    delete out.requestBodyTruncated;
+    delete out.responseBodyTruncated;
+    for (const key of ['requestHeaders', 'responseHeaders']) {
+        const h = out[key];
+        if (h) {
+            const safe = {};
+            for (const [k, v] of Object.entries(h)) {
+                if (!SENSITIVE_HEADER_RE.test(k))
+                    safe[k] = v;
+            }
+            out[key] = safe;
+        }
+    }
+    return out;
+}
+/** Read recent buffered logs for the plugin context. Redacts network by default. */
+export function collectLogs(opts = {}) {
+    const store = getCaptureStore();
+    const redact = opts.redact !== false;
+    const network = store.network.tail(opts.network ?? 0);
+    return {
+        console: store.console.tail(opts.console ?? 0),
+        errors: store.errors.tail(opts.errors ?? 0),
+        network: redact ? network.map(redactNetworkEntry) : network,
+    };
+}
 // ─── DOM builders ────────────────────────────────────────────────────────
 function buildStyle() {
     const style = document.createElement('style');
@@ -1263,6 +1446,47 @@ function buildStyle() {
             border-color: rgba(52, 211, 153, 0.3);
         }
 
+        .info-card .plugin-actions {
+            display: flex;
+            flex-direction: column;
+            gap: 8px;
+            margin-top: 8px;
+            padding-top: 8px;
+            border-top: 1px solid rgba(255, 255, 255, 0.06);
+        }
+        .info-card .promo {
+            margin-top: 8px;
+            text-align: center;
+        }
+        .info-card .promo-link {
+            color: #a1a1aa;
+            font-size: 11px;
+            text-decoration: none;
+            opacity: 0.7;
+        }
+        .info-card .promo-link:hover { color: #f4f4f5; opacity: 1; }
+
+        .hfe-toast {
+            position: fixed;
+            bottom: 64px;
+            left: 50%;
+            transform: translate(-50%, 8px);
+            max-width: 320px;
+            padding: 8px 14px;
+            background: #111827;
+            color: #f4f4f5;
+            border: 1px solid rgba(255, 255, 255, 0.12);
+            border-radius: 10px;
+            font: 500 12px/1.4 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+            box-shadow: 0 6px 24px rgba(0, 0, 0, 0.4);
+            opacity: 0;
+            transition: opacity 0.2s ease, transform 0.2s ease;
+            z-index: 2147483647;
+            pointer-events: none;
+        }
+        .hfe-toast[data-show="1"] { opacity: 1; transform: translate(-50%, 0); }
+        .hfe-toast[data-kind="error"] { border-color: rgba(248, 113, 113, 0.4); color: #fca5a5; }
+
         .picker-bar {
             position: fixed;
             top: 12px;
@@ -1727,6 +1951,10 @@ function buildInfoCard() {
             <button class="secondary" data-role="view-reports" type="button">📁 My reports</button>
             <button class="secondary" data-role="copy-snapshot" type="button">📋 Copy snapshot</button>
         </div>
+        <div class="plugin-actions" data-role="plugin-actions" style="display:none"></div>
+        <div class="promo">
+            <a class="promo-link" data-role="github" href="${GITHUB_URL}" target="_blank" rel="noopener noreferrer">⭐ Harness-FE on GitHub</a>
+        </div>
     `;
     return card;
 }

package/dist/pluginRegistry.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Overlay plugin registry.
+ *
+ * Lets developers extend the in-page "H" overlay with their own action buttons
+ * — e.g. "send this scene to Slack" / "create a Jira issue" — without forking
+ * `@harness-fe/runtime`. A plugin is just a button label + an `onClick(ctx)`
+ * handler; the handler receives an {@link OverlayPluginContext} with on-demand,
+ * redaction-aware access to the current scene, logs, screenshot, and selected
+ * element.
+ *
+ * Registration order doesn't matter: plugins registered before the overlay
+ * mounts are buffered here, and the overlay subscribes so anything registered
+ * later renders immediately. See `index.ts` for the `window.HarnessFE` global
+ * and the `window.__HARNESS_FE_PLUGINS__` pre-boot queue.
+ */
+import type { PageLoadPayload, ConsoleEntry, NetworkEntry, ErrorEntry, TaskAttachment } from '@harness-fe/protocol';
+/** Selector descriptor for a picked element (mirrors TaskSubmitPayload.selector). */
+export interface OverlayPluginSelector {
+    /** Source location `file:line:col` from the build transform, if present. */
+    loc?: string;
+    /** Component display name from the build transform, if present. */
+    comp?: string;
+    /** Best-effort CSS path. */
+    css: string;
+}
+/** The element the user picked (only present for `requiresElement` plugins). */
+export interface OverlayPluginSelectedElement {
+    /** Live DOM node. */
+    el: Element;
+    selector: OverlayPluginSelector;
+    /** outerHTML with internal instrumentation attrs stripped + truncated. */
+    outerHTML: string;
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+export interface OverlayPluginLogs {
+    console: ConsoleEntry[];
+    network: NetworkEntry[];
+    errors: ErrorEntry[];
+}
+export interface OverlayPluginGetLogsOptions {
+    /** Max console entries (newest last). Default 0 — pass a count to include. */
+    console?: number;
+    /** Max network entries. Default 0. */
+    network?: number;
+    /** Max error entries. Default 0. */
+    errors?: number;
+    /**
+     * When `true` (the default), network entries are reduced to metadata:
+     * request/response bodies are dropped and `authorization` / `cookie`
+     * headers are stripped. Set `false` to receive raw entries — only do this
+     * when you control the destination, as bodies may contain secrets.
+     */
+    redact?: boolean;
+}
+/**
+ * Per-invocation context handed to a plugin's `onClick`. Getters are lazy: the
+ * snapshot / logs / screenshot are only computed when you call them, so a
+ * plugin pays for exactly what it uses.
+ */
+export interface OverlayPluginContext {
+    readonly projectId: string;
+    readonly displayName?: string;
+    readonly buildId?: string;
+    readonly parentProjectId?: string;
+    readonly sessionId: string;
+    readonly tabId: string;
+    readonly visitorId?: string;
+    readonly userId?: string;
+    /** `location.href` at click time. */
+    readonly url: string;
+    readonly connectionState: 'connecting' | 'open' | 'closed';
+    /** Deep link to this session in the daemon dashboard, if the address is known. */
+    readonly dashboardUrl?: string;
+    /** Present only for plugins declared with `requiresElement: true`. */
+    readonly selectedElement?: OverlayPluginSelectedElement;
+    /** Shareable markdown summary (project / build / session / tab / url / time / conn). */
+    snapshotMarkdown(): string;
+    /** Structured page-load snapshot: page / viewport / storage / performance. */
+    snapshot(): PageLoadPayload;
+    /** Recent buffered logs. Redacted by default — see {@link OverlayPluginGetLogsOptions}. */
+    getLogs(opts?: OverlayPluginGetLogsOptions): OverlayPluginLogs;
+    /** Rasterize an element (default: the picked element, else `document.body`) to a PNG attachment. */
+    captureScreenshot(el?: Element): Promise<TaskAttachment | null>;
+    /** Daemon RPC over the whitelisted channel (e.g. `tasks.mine`). Undefined if unavailable. */
+    query?: <TResult = unknown>(method: string, args?: unknown) => Promise<TResult>;
+    /** Copy text to the clipboard (best-effort). */
+    copyToClipboard(text: string): Promise<void>;
+    /** Show a brief feedback toast on the overlay. */
+    toast(message: string, kind?: 'ok' | 'error'): void;
+}
+export interface OverlayPlugin {
+    /** Unique id. Re-registering the same id replaces the previous plugin. */
+    id: string;
+    /** Button label shown in the info card. */
+    label: string;
+    /** Optional leading icon (emoji or single char). */
+    icon?: string;
+    /**
+     * When `true`, clicking the button first enters element-picker mode; the
+     * picked element is then available as `ctx.selectedElement` in `onClick`.
+     */
+    requiresElement?: boolean;
+    /** Invoked when the button is clicked. May be async; rejections are toasted. */
+    onClick(ctx: OverlayPluginContext): void | Promise<void>;
+}
+/**
+ * Register an overlay plugin. Returns an unregister function (handy for HMR
+ * cleanup). Registering an id that already exists replaces it.
+ */
+export declare function registerOverlayPlugin(plugin: OverlayPlugin): () => void;
+/** Current plugins, in registration order. */
+export declare function getOverlayPlugins(): OverlayPlugin[];
+/** Subscribe to registry changes (add / replace / remove). Returns an unsubscribe fn. */
+export declare function subscribeOverlayPlugins(fn: () => void): () => void;
+/**
+ * Drain a pre-boot queue of plugins. Developers whose script may run before the
+ * runtime loads can push plain plugin objects onto
+ * `window.__HARNESS_FE_PLUGINS__`; `index.ts` calls this once on boot.
+ */
+export declare function drainPluginQueue(queue: unknown): void;
+/** Test-only: clear all plugins and listeners. */
+export declare function __resetOverlayPlugins(): void;

package/dist/pluginRegistry.js

@@ -0,0 +1,80 @@
+/**
+ * Overlay plugin registry.
+ *
+ * Lets developers extend the in-page "H" overlay with their own action buttons
+ * — e.g. "send this scene to Slack" / "create a Jira issue" — without forking
+ * `@harness-fe/runtime`. A plugin is just a button label + an `onClick(ctx)`
+ * handler; the handler receives an {@link OverlayPluginContext} with on-demand,
+ * redaction-aware access to the current scene, logs, screenshot, and selected
+ * element.
+ *
+ * Registration order doesn't matter: plugins registered before the overlay
+ * mounts are buffered here, and the overlay subscribes so anything registered
+ * later renders immediately. See `index.ts` for the `window.HarnessFE` global
+ * and the `window.__HARNESS_FE_PLUGINS__` pre-boot queue.
+ */
+const plugins = new Map();
+const listeners = new Set();
+function notify() {
+    for (const fn of listeners) {
+        try {
+            fn();
+        }
+        catch {
+            /* a bad listener must not break registration */
+        }
+    }
+}
+/**
+ * Register an overlay plugin. Returns an unregister function (handy for HMR
+ * cleanup). Registering an id that already exists replaces it.
+ */
+export function registerOverlayPlugin(plugin) {
+    if (!plugin || typeof plugin.id !== 'string' || plugin.id === '') {
+        throw new Error('registerOverlayPlugin: plugin.id is required');
+    }
+    if (typeof plugin.onClick !== 'function') {
+        throw new Error(`registerOverlayPlugin: plugin "${plugin.id}" needs an onClick handler`);
+    }
+    plugins.set(plugin.id, plugin);
+    notify();
+    return () => {
+        if (plugins.get(plugin.id) === plugin) {
+            plugins.delete(plugin.id);
+            notify();
+        }
+    };
+}
+/** Current plugins, in registration order. */
+export function getOverlayPlugins() {
+    return [...plugins.values()];
+}
+/** Subscribe to registry changes (add / replace / remove). Returns an unsubscribe fn. */
+export function subscribeOverlayPlugins(fn) {
+    listeners.add(fn);
+    return () => {
+        listeners.delete(fn);
+    };
+}
+/**
+ * Drain a pre-boot queue of plugins. Developers whose script may run before the
+ * runtime loads can push plain plugin objects onto
+ * `window.__HARNESS_FE_PLUGINS__`; `index.ts` calls this once on boot.
+ */
+export function drainPluginQueue(queue) {
+    if (!Array.isArray(queue))
+        return;
+    for (const p of queue) {
+        try {
+            registerOverlayPlugin(p);
+        }
+        catch {
+            /* skip malformed queued entries */
+        }
+    }
+}
+/** Test-only: clear all plugins and listeners. */
+export function __resetOverlayPlugins() {
+    plugins.clear();
+    listeners.clear();
+}

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);
     }