@sailfish-ai/recorder 1.11.0 → 1.11.3

package/README.md

@@ -140,6 +140,7 @@ await initRecorder({
 | `deferRecording` | `boolean` | `true` | Defers the initial DOM snapshot until after first paint / idle. |
 | `chunkSnapshot` | `boolean` | `false` | Yield to the browser every 500 nodes during the initial snapshot (smoother on very large pages). |
 | `useWsWorker` | `boolean` | `true` | Run the WebSocket sender in a Web Worker. Disable if your CSP blocks `worker-src blob:`. |
+| `capturePerformanceMetrics` | `boolean` | `true` | Capture FCP / LCP / TBT / DCL / LOAD per `page_visit_uuid` via the performance plugin. Set `false` to skip — the plugin is dynamically imported, so opting out also skips loading `web-vitals` and the observers. |
 | `reportIssueShortcuts` | `ShortcutsConfig` | — | Custom keyboard shortcuts for the report-issue modal. |
 | `showEngTicketFieldsInReportIssueModalDefault` | `boolean` | `false` | Pre-expand Jira / Linear fields in the in-app issue modal. |
 
@@ -185,6 +186,98 @@ if (isFunctionSpanTrackingEnabled()) disableFunctionSpanTracking();
 enableFunctionSpanTracking();
 ```
 
+## Performance metrics
+
+The recorder automatically captures real-user performance metrics per page visit and emits them through the same WebSocket pipeline as everything else. No additional configuration is required; capture is skipped in Lighthouse / headless / WebDriver environments to avoid polluting synthetic audits.
+
+| Metric | Meaning | Source |
+|---|---|---|
+| **FCP** — First Contentful Paint | Time to first text/image paint. | `web-vitals` `onFCP` |
+| **LCP** — Largest Contentful Paint | Time to the largest above-the-fold element. Closest proxy for "content is visible". | `web-vitals` `onLCP` |
+| **TBT** — Total Blocking Time | Sum of blocking time from long tasks, emitted at `load`. | `PerformanceObserver({type:'longtask', buffered:true})` summing `max(0, duration − 50)` |
+| **DCL** — DOMContentLoaded | `navigation.domContentLoadedEventEnd` (ms since `timeOrigin`). | Navigation Timing Level 2 |
+| **LOAD** — load event | `navigation.loadEventEnd` (ms since `timeOrigin`). | Navigation Timing Level 2 |
+
+FCP and LCP re-emit on SPA soft-navigations (via `web-vitals`' native history-API / BFCache support) — each emission is keyed to the current `page_visit_uuid`. TBT, DCL, and LOAD fire once per hard load.
+
+Events arrive on the recorder WebSocket with `type: 28` (the numeric id reserved for performance metrics — see `backend/sailfish/rrweb/enums.py` on the Sailfish backend) and the shape:
+
+```json
+{
+  "type": 28,
+  "timestamp": 1700000000000,
+  "sessionId": "<session_id>",
+  "page_visit_uuid": "<uuid>",
+  "href": "https://example.com/path",
+  "data": {
+    "plugin": "@sailfish-rrweb/rrweb/performance@1",
+    "payload": {
+      "metric": "FCP" | "LCP" | "TBT" | "DCL" | "LOAD",
+      "value": 1234.5,
+      "rating": "good" | "needs-improvement" | "poor",
+      "navigationType": "navigate" | "reload" | "back-forward" | "back-forward-cache" | "prerender" | "restore",
+      "pageVisitUuid": "<uuid>",
+      "href": "https://example.com/path",
+      "timestamp": 1700000000000
+    }
+  }
+}
+```
+
+### Disabling capture
+
+Pass `capturePerformanceMetrics: false` to `initRecorder` to skip the plugin entirely. Because the plugin code is dynamically imported, this also avoids loading `web-vitals` and the long-task observer:
+
+```ts
+initRecorder({
+  apiKey: "YOUR_API_KEY",
+  capturePerformanceMetrics: false,
+});
+```
+
+### Benchmarking the plugin's overhead
+
+`scripts/bench-perf.js` loads the same page twice — once with capture on, once with capture off — under headless Chrome, and reports CPU, JS heap, FCP/LCP, long-task time, and total load time side-by-side.
+
+#### One-time app change (required before running the bench)
+
+The bench needs a way to flip capture on/off without rebuilding your app between variants. Wire `?sf_perf=off` in your `initRecorder` call so the URL controls the option — paste this where you call `initRecorder`:
+
+```ts
+const capturePerformanceMetrics =
+  new URLSearchParams(window.location.search).get("sf_perf") !== "off";
+
+initRecorder({
+  apiKey: "YOUR_API_KEY",
+  // …your other options…
+  capturePerformanceMetrics,
+});
+```
+
+Anything other than `?sf_perf=off` (including the param being absent) leaves capture enabled, so day-to-day usage is unaffected. The toggle exists only so the bench can switch variants by URL.
+
+#### Run the bench
+
+```bash
+# 1. Start your app's dev server (separate terminal). Default port 3000.
+npm run start
+
+# 2. Run the bench (defaults to http://localhost:3000, 5 runs/variant):
+cd veritas/jsts-frontend
+npm install                         # first time only — installs puppeteer
+npm run bench-perf
+
+# Override URL or sample count:
+npm run bench-perf -- --url http://localhost:3000/some/page --runs 10
+
+# Watch the runs in a real browser window (slower, useful for sanity-checking):
+npm run bench-perf -- --headed
+```
+
+Output is a table of medians, p95, and Δ% between the two variants for: wall load time, DCL, load event, FCP, LCP, long-task total, long-task blocking (the TBT proxy), CDP `TaskDuration` / `ScriptDuration` / `LayoutDuration`, and `usedJSHeapSize` (MB).
+
+Sample interpretation: a Δ ≤ noise (typically ±5% on the smaller numbers, ±2 MB on heap) means the plugin is essentially free; anything larger is a regression worth profiling.
+
 ## Framework examples
 
 ### React / Vite
@@ -311,4 +404,5 @@ ReferenceError: localStorage is not defined
 
 ## License
 
+
 Proprietary. See [sailfishqa.com/terms](https://sailfishqa.com) for terms of service.

package/dist/chunks/{chunkSerializer-ZzIoYlP2.js → chunkSerializer-CV4nkb5-.js}

@@ -1,4 +1,4 @@
-import { y as e } from "./index-Dq_tjmkZ.js";
+import { y as e } from "./index-BynFTRFv.js";
 async function chunkedSnapshot(t, n, o = {}) {
   const s = o.chunkSize ?? 500, r = o.maxChunkMs ?? 16, { blockClass: c, blockSelector: a, maskTextClass: i, maskTextSelector: d } = o;
   let u = 100001, l = 0, N = performance.now();

package/dist/chunks/{chunkSerializer-CRDpgzTs.js → chunkSerializer-jzbHv2wf.js}

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const e = require("./index-BQn1Q-2-.js");
+const e = require("./index-BP-kNUGS.js");
 exports.chunkedSnapshot = async function chunkedSnapshot(t, n, o = {}) {
   const s = o.chunkSize ?? 500, r = o.maxChunkMs ?? 16, { blockClass: c, blockSelector: a, maskTextClass: i, maskTextSelector: d } = o;
   let u = 100001, l = 0, N = performance.now();