@sailfish-ai/recorder 1.11.5 → 1.12.4

package/dist/recording.js

@@ -4,6 +4,29 @@ import { Complete, DomContentEventId, DomContentSource, Loading, PerformanceMetr
 import { getCallerLocation, getCallerLocationFromTrace, } from "./sourceLocation";
 import suppressConsoleLogsDuringCall from "./suppressConsoleLogsDuringCall";
 import { yieldToMain } from "./scheduler";
+import { buildMaskInputFn, makeMaskTextFn } from "./privacyMask";
+// rrweb's full set of input-type / tag keys — used to expand
+// maskInputOptions to all-on when admin set a maskInputSelector, so rrweb
+// routes every input through our wrapper which then enforces precise
+// per-element rules.
+const RRWEB_ALL_INPUT_TYPES = {
+    color: true,
+    date: true,
+    "datetime-local": true,
+    email: true,
+    month: true,
+    number: true,
+    range: true,
+    search: true,
+    tel: true,
+    text: true,
+    time: true,
+    url: true,
+    week: true,
+    textarea: true,
+    select: true,
+    password: true,
+};
 import { getCachedHrefNoQuery, initializeWebSocket, sendEvent } from "./websocket";
 // Module-level reference to rrweb record, populated after dynamic import
 let _record = null;
@@ -58,19 +81,22 @@ function zE_safe(...args) {
 // ─────────────────────────────────────────────────────────────────────────────
 // Recorder logic
 // ─────────────────────────────────────────────────────────────────────────────
-function maskInputFn(text, node) {
+export function maskInputFn(text, node) {
     if (node.type === "hidden") {
         return "";
     }
+    // rrweb only calls this fn when it has already decided to mask this input
+    // (maskInputOptions[type] matched, or maskInputSelector matched, or the
+    // element is under maskTextClass). When we run, we MUST return a masked
+    // value — returning raw text silently defeats rrweb's masking decision and
+    // leaks user input to the WS payload. Specific PII formats keep their
+    // length-preserving partial masks for player readability; everything else
+    // falls back to a full-asterisk mask (matching rrweb's built-in default).
     const patterns = {
         creditCard: /\b(?:\d[ -]*?){13,16}\b/,
         ssn: /\b\d{3}-\d{2}-\d{4}\b/,
     };
-    const MASK_CLASS = "mask";
-    if (node.closest(`.${MASK_CLASS}`)) {
-        return "*".repeat(text.length);
-    }
-    else if (node.hasAttribute("data-cc") ||
+    if (node.hasAttribute("data-cc") ||
         (node.getAttribute("autocomplete")?.startsWith("cc-") ?? false) ||
         patterns.creditCard.test(text)) {
         return "**** **** **** " + text.slice(-4);
@@ -81,7 +107,7 @@ function maskInputFn(text, node) {
     else if (node.hasAttribute("data-dob")) {
         return "**/**/" + text.slice(-4);
     }
-    return text;
+    return "*".repeat(text.length);
 }
 // Cached sessionStorage values — avoids per-call sessionStorage reads on the hot path
 let _ssCacheDirty = true;
@@ -325,6 +351,36 @@ backendApi, apiKey, sessionId, envValue, deferRecordingStart = true, useWsWorker
             _record = record;
             // Yield before rrweb record() — the heaviest synchronous operation
             await yieldToMain();
+            // Effective Form Privacy Rule options. Empty strings from the server
+            // collapse to undefined so rrweb / our walker can short-circuit.
+            const unmaskSelector = captureSettings.unmaskSelector || undefined;
+            const blockSelector = captureSettings.blockSelector || undefined;
+            const maskTextSelector = captureSettings.maskTextSelector || undefined;
+            const maskInputSelector = captureSettings.maskInputSelector || undefined;
+            // ── Admin's intended maskInputOptions ──
+            // No floor: when admin's maskInputOptions is empty (every checkbox
+            // unticked), no type-based masking applies. unmaskSelector and
+            // maskInputSelector still work independently. "Off means off."
+            const adminMaskInputOptions = {
+                ...(captureSettings.maskInputOptions ?? {}),
+            };
+            // ── rrweb-facing maskInputOptions ──
+            // rrweb's input observer only consults maskInputOptions[type]; it has
+            // no concept of maskInputSelector. When admin set one, expand to all-on
+            // so rrweb calls our wrapper for every input — the wrapper then enforces
+            // the precise per-element decision (type match OR selector match,
+            // exempted by unmaskSelector). Without a selector, keep the original
+            // narrow set so unconfigured types stay raw at rrweb's level.
+            const effectiveMaskInputOptions = maskInputSelector
+                ? { ...RRWEB_ALL_INPUT_TYPES }
+                : adminMaskInputOptions;
+            const effectiveMaskInputFn = buildMaskInputFn({
+                baseFn: maskInputFn,
+                unmaskSelector,
+                maskInputSelector,
+                adminMaskInputOptions,
+            });
+            const effectiveMaskTextFn = makeMaskTextFn(unmaskSelector);
             if (chunkSnapshot) {
                 // ── Chunked snapshot mode ──────────────────────────────────────
                 // Instead of rrweb's synchronous full-DOM snapshot (which blocks
@@ -348,9 +404,15 @@ backendApi, apiKey, sessionId, envValue, deferRecordingStart = true, useWsWorker
                             emitWithContext(event);
                         }
                     },
-                    maskInputOptions: { text: true },
-                    maskInputFn,
                     ...captureSettings,
+                    // Placed AFTER spread so captureSettings keys can't bypass the
+                    // unmask shim or the {text:true} floor.
+                    maskInputOptions: effectiveMaskInputOptions,
+                    maskInputFn: effectiveMaskInputFn,
+                    maskTextFn: effectiveMaskTextFn,
+                    maskInputSelector,
+                    maskTextSelector,
+                    blockSelector,
                     maskTextClass: captureSettings.maskTextClass ?? MASK_CLASS,
                     recordDOM: false, // after spread so it can't be overridden
                 });
@@ -359,9 +421,14 @@ backendApi, apiKey, sessionId, envValue, deferRecordingStart = true, useWsWorker
                     chunkSize: 500,
                     maxChunkMs: 16,
                     blockClass: captureSettings.blockClass,
-                    blockSelector: captureSettings.blockSelector,
+                    blockSelector,
                     maskTextClass: captureSettings.maskTextClass ?? MASK_CLASS,
-                    maskTextSelector: captureSettings.maskTextSelector,
+                    maskTextSelector,
+                    maskInputSelector,
+                    maskInputOptions: effectiveMaskInputOptions,
+                    maskInputFn: effectiveMaskInputFn,
+                    maskTextFn: effectiveMaskTextFn,
+                    unmaskSelector,
                 });
                 if (serializedDoc) {
                     // Emit Meta event
@@ -411,9 +478,13 @@ backendApi, apiKey, sessionId, envValue, deferRecordingStart = true, useWsWorker
                     emit(event) {
                         emitWithContext(event);
                     },
-                    maskInputOptions: { text: true },
-                    maskInputFn,
                     ...captureSettings,
+                    maskInputOptions: effectiveMaskInputOptions,
+                    maskInputFn: effectiveMaskInputFn,
+                    maskTextFn: effectiveMaskTextFn,
+                    maskInputSelector,
+                    maskTextSelector,
+                    blockSelector,
                     maskTextClass: captureSettings.maskTextClass ?? MASK_CLASS,
                 });
             }

package/dist/types/chunkSerializer.d.ts

@@ -6,6 +6,10 @@ export interface ChunkMirror {
     hasNode(node: Node): boolean;
     getId(node: Node): number;
 }
+/** Per-input-type mask toggles. Keys match rrweb's MaskInputOptions. */
+export interface ChunkMaskInputOptions {
+    [inputType: string]: boolean | undefined;
+}
 export interface ChunkOptions {
     /** Yield after this many nodes (default: 500) */
     chunkSize?: number;
@@ -19,6 +23,16 @@ export interface ChunkOptions {
     maskTextClass?: string;
     /** rrweb maskTextSelector — CSS selector for masked text containers */
     maskTextSelector?: string | null;
+    /** CSS selector for inputs whose values should be masked. */
+    maskInputSelector?: string | null;
+    /** Per-input-type toggles (text, password, email, …). */
+    maskInputOptions?: ChunkMaskInputOptions;
+    /** Optional override for input-value masking. Receives raw value + node. */
+    maskInputFn?: (text: string, element: HTMLElement) => string;
+    /** Optional override for text-node masking. Receives raw text + parent. */
+    maskTextFn?: (text: string, element: HTMLElement | null) => string;
+    /** CSS selector that exempts ancestors from any masking/blocking. */
+    unmaskSelector?: string | null;
 }
 /**
  * Async chunked DOM serializer. Walks the document tree producing an

package/dist/types/clockSync.d.ts

@@ -0,0 +1,70 @@
+export interface TimeSyncSample {
+    clientSendMonoMs: number;
+    clientReceiveMonoMs: number;
+    serverReceiveWallMs: number;
+    serverSendWallMs: number;
+    rttMs: number;
+    estimatedOffsetMs: number;
+    browserWallAtSyncMs: number;
+}
+export interface TimeSyncResponseBody {
+    requestId: string;
+    serverReceivedAtMs: number;
+    serverSentAtMs: number;
+}
+export interface ClockSyncMetadata {
+    offsetMs: number | null;
+    rttMs: number | null;
+    syncAgeMs: number | null;
+}
+export interface PendingTimeSyncRequest {
+    requestId: string;
+    clientSendMonoMs: number;
+}
+export declare function monotonicNow(): number;
+export declare function timeOriginMs(): number;
+declare class ClockSyncManager {
+    private samples;
+    private pending;
+    private estimatedOffsetMs;
+    private bestRttMs;
+    private lastSyncMonoMs;
+    beginSync(requestId: string): PendingTimeSyncRequest;
+    abandonSync(requestId: string): void;
+    recordTimeSyncResponse(body: TimeSyncResponseBody): TimeSyncSample | null;
+    estimateServerTime(monoMs: number): number | null;
+    getSyncMetadata(): ClockSyncMetadata;
+    getBrowserClockSkewMs(): number | null;
+    reset(): void;
+    private pruneSamples;
+    private recompute;
+}
+export declare function getClockSyncManager(): ClockSyncManager;
+export declare function estimateServerTime(monoMs: number): number | null;
+export declare function getClockSyncMetadata(): ClockSyncMetadata;
+export declare function buildEventTimeEnvelope(capturedMonoMs: number, capturedWallMs: number): {
+    client: {
+        wallTimeMs: number;
+        monotonicMs: number;
+        timeOriginMs: number;
+    };
+    serverEstimated: {
+        eventTimeMs: number | null;
+        offsetMs: number | null;
+        rttMs: number | null;
+        syncAgeMs: number | null;
+    };
+};
+export declare function captureClientTime(): {
+    wallTimeMs: number;
+    monotonicMs: number;
+    timeOriginMs: number;
+};
+export declare const __testing: {
+    reset: () => void;
+    MAX_USABLE_RTT_MS: number;
+    BEST_SAMPLE_COUNT: number;
+    HAS_WINDOW: boolean;
+    HAS_PERFORMANCE: boolean;
+};
+export {};

package/dist/types/inAppReportIssueModal/integrations.d.ts

@@ -11,6 +11,7 @@ export declare function fetchIntegrationData(apiKey: string, backendApi: string)
 export declare function refreshIntegrationData(apiKey: string, backendApi: string): Promise<EngineeringTicketIntegration | null>;
 export declare function populateSelectOptions(selectElement: HTMLSelectElement, options: any[], defaultValue?: string): void;
 export declare function populatePriorityOptions(selectElement: HTMLSelectElement, provider: string, defaultPriority?: number): void;
+export declare function pickDefaultActiveSprint(sprints: any[], projectId: string, projects: any[]): any | null;
 export declare function populateSprintOptions(selectElement: HTMLSelectElement, sprints: any[], currentValue?: string): void;
 export declare function getSprintFieldId(): string;
 export declare function updateIssueTypeOptions(selectElement: HTMLSelectElement, projectId: string): void;

package/dist/types/inAppReportIssueModal/state.d.ts

@@ -5,8 +5,10 @@ export declare let recordingStartTime: number | null;
 export declare let recordingEndTime: number | null;
 export declare let timerInterval: ReturnType<typeof setInterval> | null;
 export declare let isRecording: boolean;
+export declare let sprintDefaulted: boolean;
 export declare function setCurrentState(state: IssueReportState): void;
 export declare function resetState(): void;
+export declare function setSprintDefaulted(value: boolean): void;
 export declare function setRecordingStartTime(time: number | null): void;
 export declare function setRecordingEndTime(time: number | null): void;
 export declare function setTimerInterval(interval: ReturnType<typeof setInterval> | null): void;

package/dist/types/index.d.ts

@@ -1,12 +1,13 @@
 import type { LogRecordOptions } from "@sailfish-rrweb/rrweb-plugin-console-record";
 import type { ShortcutsConfig } from "./inAppReportIssueModal";
-import { CaptureSettings } from "./types";
+import { CaptureSettings, MaskInputOptions } from "./types";
 export declare const STORAGE_VERSION = 1;
 export declare const DEFAULT_CAPTURE_SETTINGS: CaptureSettings;
 export declare const DEFAULT_CONSOLE_RECORDING_SETTINGS: LogRecordOptions;
+export declare function toAbsoluteUrl(url: string): string;
 export declare function matchUrlWithWildcard(input: unknown, patterns: string[]): boolean;
 export declare function createSkipHeadersPropagationChecker(domainsToNotPropagateHeaderTo?: string[], domainsToPropagateHeaderTo?: string[]): (url: string) => boolean;
-export declare function startRecording({ apiKey, backendApi, domainsToPropagateHeaderTo, domainsToNotPropagateHeaderTo, serviceVersion, serviceIdentifier, gitSha, serviceAdditionalMetadata, enableIpTracking, captureStreamingResponseBody, captureResponseBodyMaxMb, captureStreamPrefixKb, captureStreamTimeoutMs, enableFiberTracking, deferRecording, deferRecordingStart, chunkSnapshot, useWsWorker, capturePerformanceMetrics, maskTextClass, library, headlessRecording, }: {
+export declare function startRecording({ apiKey, backendApi, domainsToPropagateHeaderTo, domainsToNotPropagateHeaderTo, serviceVersion, serviceIdentifier, gitSha, serviceAdditionalMetadata, enableIpTracking, captureStreamingResponseBody, captureResponseBodyMaxMb, captureStreamPrefixKb, captureStreamTimeoutMs, enableFiberTracking, deferRecording, deferRecordingStart, chunkSnapshot, useWsWorker, capturePerformanceMetrics, maskTextClass, maskInputSelector, maskTextSelector, blockSelector, unmaskSelector, maskInputOptions, library, headlessRecording, }: {
     apiKey: string;
     backendApi?: string;
     domainsToPropagateHeaderTo?: string[];
@@ -29,6 +30,11 @@ export declare function startRecording({ apiKey, backendApi, domainsToPropagateH
     useWsWorker?: boolean;
     capturePerformanceMetrics?: boolean;
     maskTextClass?: string;
+    maskInputSelector?: string;
+    maskTextSelector?: string;
+    blockSelector?: string;
+    unmaskSelector?: string;
+    maskInputOptions?: MaskInputOptions;
     headlessRecording?: boolean;
 }): Promise<void>;
 export declare const initRecorder: (options: {
@@ -99,6 +105,14 @@ export declare const initRecorder: (options: {
      * @default false
      */
     headlessRecording?: boolean;
+    /**
+     * Enable internal debug console logs for diagnosing recorder bugs
+     * (e.g. duplicate page_visit_uuid mints, missed URL changes). Off by
+     * default so customer integrations see no console noise. Sailfish's
+     * own FE may set this to true to surface mint events with stack traces.
+     * @default false
+     */
+    enableInternalDebugLogs?: boolean;
 }) => Promise<void>;
 export * from "./graphql";
 export { openReportIssueModal } from "./inAppReportIssueModal";

package/dist/types/privacyMask.d.ts

@@ -0,0 +1,46 @@
+/** Match the shape of rrweb's MaskInputOptions — only the keys we care about. */
+export interface MaskInputOptionsLike {
+    [typeOrTag: string]: boolean | undefined;
+}
+/**
+ * Safe ancestor-match check. A malformed selector — typo'd by an admin in
+ * the Form Privacy Rules UI — would otherwise throw from `closest()` and
+ * crash rrweb's serializer mid-walk. Under-masking is better than dropping
+ * the session.
+ */
+export declare function closestSafe(el: HTMLElement | null, selector?: string): boolean;
+/** Element.matches with try/catch for malformed selectors. */
+export declare function matchesSelectorSafe(el: HTMLElement, selector?: string): boolean;
+/**
+ * Build the maskInputFn we hand to rrweb. rrweb only calls maskInputFn after
+ * its own check on `maskInputOptions[tagName] || maskInputOptions[type]` —
+ * it has NO `maskInputSelector` concept. To honor admin-set
+ * `maskInputSelector` in normal record() mode, callers expand the
+ * rrweb-facing `maskInputOptions` to all-true so rrweb routes EVERY input
+ * through this fn. This function then enforces the real per-element decision:
+ *
+ *   1. unmaskSelector match → raw (admin opted this subtree out)
+ *   2. type in admin-intent maskInputOptions OR maskInputSelector match → mask
+ *   3. otherwise → raw (admin didn't configure this field for masking)
+ *
+ * `baseFn` produces the masked string (PII-specific last-4 CC/SSN/DOB, or
+ * a full-asterisk fallback).
+ */
+export declare function buildMaskInputFn(opts: {
+    baseFn: (text: string, node: HTMLElement) => string;
+    unmaskSelector?: string;
+    maskInputSelector?: string;
+    /** ORIGINAL admin intent — NOT the all-on expansion sent to rrweb. */
+    adminMaskInputOptions: MaskInputOptionsLike;
+}): (text: string, node: HTMLElement) => string;
+/**
+ * @deprecated Use buildMaskInputFn. Kept so older test imports keep working
+ * during the transition.
+ */
+export declare function wrapMaskInputFn(baseFn: (text: string, node: HTMLElement) => string, unmaskSelector?: string): (text: string, node: HTMLElement) => string;
+/**
+ * Default maskTextFn — replaces every non-whitespace char with "*",
+ * matching rrweb's built-in behavior. Wrapped so that nodes under
+ * `unmaskSelector` skip masking.
+ */
+export declare function makeMaskTextFn(unmaskSelector?: string): (text: string, element: HTMLElement | null) => string;

package/dist/types/recording.d.ts

@@ -1,5 +1,6 @@
 import type { LogRecordOptions } from "@sailfish-rrweb/rrweb-plugin-console-record";
 import type { WsHandle } from "./websocket";
+export declare function maskInputFn(text: string, node: HTMLElement): string;
 /** Call after writing to sessionStorage keys used by getUrlAndStoredUuids(). */
 export declare function invalidateUrlCache(): void;
 export declare const getUrlAndStoredUuids: () => {

package/dist/types/types.d.ts

@@ -1,3 +1,21 @@
+export type MaskInputOptions = Partial<{
+    color: boolean;
+    date: boolean;
+    "datetime-local": boolean;
+    email: boolean;
+    month: boolean;
+    number: boolean;
+    range: boolean;
+    search: boolean;
+    tel: boolean;
+    text: boolean;
+    time: boolean;
+    url: boolean;
+    week: boolean;
+    textarea: boolean;
+    select: boolean;
+    password: boolean;
+}>;
 export interface CaptureSettings {
     recordCanvas: boolean;
     recordCrossOriginIframes: boolean;
@@ -12,6 +30,11 @@ export interface CaptureSettings {
     textEditThrottleEnabled?: boolean;
     enableFiberTracking?: boolean;
     maskTextClass?: string;
+    maskInputSelector?: string;
+    maskTextSelector?: string;
+    blockSelector?: string;
+    unmaskSelector?: string;
+    maskInputOptions?: MaskInputOptions;
 }
 export interface ConsoleRecordSettings {
     level: string[];

package/dist/types/websocket.d.ts

@@ -3,6 +3,7 @@ export interface WsHandle {
     readyState: number;
     close: () => void;
 }
+export declare function requestTimeSync(): void;
 type NavigationCallback = () => void;
 /** Register a callback to be invoked immediately on pushState/replaceState/popstate/hashchange. */
 export declare function onNavigationChange(cb: NavigationCallback): void;

package/dist/websocket.js

@@ -1,4 +1,5 @@
 import ReconnectingWebSocket from "reconnecting-websocket";
+import { buildEventTimeEnvelope, getClockSyncManager, monotonicNow, timeOriginMs, } from "./clockSync";
 import { readDebugFlag } from "./env";
 import { deleteEventsByIds, getAllIndexedEvents, saveEventsToIDB, } from "./eventStore";
 import { deleteNotifyMessageById, getAllNotifyMessages, saveNotifyMessageToIDB, } from "./notifyEventStore";
@@ -96,6 +97,95 @@ let webSocket = null;
 let isDraining = false;
 let inFlightFlush = null;
 let flushIntervalId = null;
+// ─── Time sync state ─────────────────────────────────────────────────────────
+// Periodic re-sync of the browser→server clock offset. The first burst
+// happens in handleWsOpen so events flushed from IDB on reconnect get a
+// reasonable estimate immediately.
+const TIME_SYNC_INTERVAL_MS = 60 * 1000;
+const TIME_SYNC_OPEN_BURST_COUNT = 3;
+const TIME_SYNC_OPEN_BURST_SPACING_MS = 250;
+let timeSyncIntervalId = null;
+let _timeSyncRequestCounter = 0;
+function makeTimeSyncRequestId() {
+    _timeSyncRequestCounter += 1;
+    return `ts-${_timeSyncRequestCounter}-${Math.random().toString(36).slice(2, 10)}`;
+}
+// Fire one NTP-style request through the existing socket. Response will be
+// dispatched in handleWsMessage when "time-sync-response" arrives.
+export function requestTimeSync() {
+    if (!isWebSocketOpen(webSocket))
+        return;
+    const mgr = getClockSyncManager();
+    const requestId = makeTimeSyncRequestId();
+    mgr.beginSync(requestId);
+    const ok = wsSendPayload({
+        type: "time-sync-request",
+        requestId,
+        clientSentAtMs: Date.now(),
+    });
+    if (!ok)
+        mgr.abandonSync(requestId);
+}
+function startTimeSyncInterval() {
+    if (timeSyncIntervalId != null || typeof window === "undefined")
+        return;
+    timeSyncIntervalId = window.setInterval(() => {
+        requestTimeSync();
+    }, TIME_SYNC_INTERVAL_MS);
+}
+function stopTimeSyncInterval() {
+    if (timeSyncIntervalId != null && typeof window !== "undefined") {
+        window.clearInterval(timeSyncIntervalId);
+        timeSyncIntervalId = null;
+    }
+}
+function kickoffTimeSyncBurst() {
+    if (typeof window === "undefined")
+        return;
+    for (let i = 0; i < TIME_SYNC_OPEN_BURST_COUNT; i++) {
+        window.setTimeout(requestTimeSync, i * TIME_SYNC_OPEN_BURST_SPACING_MS);
+    }
+}
+// ─── Event time-sync enrichment ──────────────────────────────────────────────
+// Stamps client.{wallTime,monotonic,timeOrigin} and serverEstimated.* onto an
+// outbound event.
+//
+// Idempotent for client.*: if the capture site already populated
+// client.monotonicMs we keep that timing as-is.
+//
+// Re-evaluating for serverEstimated.*: if the envelope was attached when no
+// sync sample had landed yet (eventTimeMs === null), and an offset is now
+// available, recompute. This is the common page-load case — events fire in
+// the first few hundred ms before the first time-sync-request gets a reply,
+// get queued to IDB with a null estimate, then are flushed once the WS is
+// open and the offset is known. Without this, those events would carry
+// eventTimeMs=null forever.
+//
+// Cross-page-load events (different performance.timeOrigin from the current
+// context) are skipped — the captured monotonicMs is in a different domain
+// than the current offset, so re-deriving would produce garbage.
+function enrichEventWithTimeSync(event) {
+    if (!event || typeof event !== "object")
+        return;
+    if (event.client && event.client.monotonicMs != null) {
+        const sameContext = event.client.timeOriginMs == null ||
+            Math.abs(event.client.timeOriginMs - timeOriginMs()) <= 1;
+        if (!sameContext)
+            return;
+        const env = buildEventTimeEnvelope(event.client.monotonicMs, event.client.wallTimeMs ?? Date.now());
+        if (!event.serverEstimated) {
+            event.serverEstimated = env.serverEstimated;
+        }
+        else if (event.serverEstimated.eventTimeMs == null &&
+            env.serverEstimated.eventTimeMs != null) {
+            event.serverEstimated = env.serverEstimated;
+        }
+        return;
+    }
+    const env = buildEventTimeEnvelope(monotonicNow(), Date.now());
+    event.client = env.client;
+    event.serverEstimated = env.serverEstimated;
+}
 // ─── Cached window.location.href ──────────────────────────────────────────────
 // Updated on navigation events (popstate, hashchange, pushState, replaceState)
 // instead of reading the DOM property on every sendEvent() call.
@@ -404,6 +494,11 @@ export async function flushBufferedEvents() {
                 const eventsToSend = batch.map((e) => {
                     if (!e.data.appUrl)
                         e.data.appUrl = getCachedHref();
+                    // Re-derive serverEstimated against the now-current offset. Most
+                    // page-load events were queued before the first sync sample landed,
+                    // baking eventTimeMs=null into their envelope; this is the only
+                    // chance to give them a real estimate before they leave the SDK.
+                    enrichEventWithTimeSync(e.data);
                     return e.data;
                 });
                 const idsToDelete = batch
@@ -435,6 +530,7 @@ export function sendEvent(event) {
     // Mutate in place — event is ephemeral, avoids object spread allocation
     if (!event.app_url)
         event.app_url = getCachedHref();
+    enrichEventWithTimeSync(event);
     if (isDraining || !isWebSocketOpen(webSocket)) {
         queueEventForIDB(event);
         return;
@@ -470,18 +566,32 @@ function handleWsOpen() {
             void flushBufferedEvents();
         }, 2000);
     })();
+    // Seed the clock-offset estimate immediately so subsequent events get a
+    // real serverEstimated.eventTimeMs instead of nulls.
+    kickoffTimeSyncBurst();
+    startTimeSyncInterval();
 }
 function handleWsClose() {
     if (flushIntervalId != null) {
         clearInterval(flushIntervalId);
         flushIntervalId = null;
     }
+    stopTimeSyncInterval();
     if (DEBUG)
         console.log("[Sailfish] WebSocket closed");
 }
 function handleWsMessage(rawData) {
     try {
         const data = JSON.parse(rawData);
+        // Handle NTP-style time-sync handshake reply from backend
+        if (data.type === "time-sync-response") {
+            getClockSyncManager().recordTimeSyncResponse({
+                requestId: data.requestId,
+                serverReceivedAtMs: data.serverReceivedAtMs,
+                serverSentAtMs: data.serverSentAtMs,
+            });
+            return;
+        }
         // Handle function span tracking control messages from backend
         if (data.type === "funcSpanTrackingControl") {
             if (DEBUG) {
@@ -695,6 +805,7 @@ export function sendMessage(message) {
     // Mutate in place — avoids object spread allocation
     if (!message.app_url)
         message.app_url = getCachedHref();
+    enrichEventWithTimeSync(message);
     if (isDraining || !isWebSocketOpen(webSocket)) {
         saveNotifyMessageToIDB(JSON.stringify(message));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sailfish-ai/recorder",
-  "version": "1.11.5",
+  "version": "1.12.4",
   "publishPublicly": true,
   "publishToCdn": {
     "jsdelivr": true,