@sailfish-ai/recorder 1.12.4 → 1.12.6

package/dist/types/canvas/protocol.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Shared canvas-recording protocol types + the SFCV binary frame format.
+ *
+ * Types are ported from the validated bench core
+ * (test-applications/canvas-recorder-bench/src/capture/patch2d.ts); the SFCV
+ * frame builder/parser implements the canvas-recording-pipeline contract §1:
+ *
+ *   bytes 0..3   magic "SFC1" (0x53 0x46 0x43 0x31)
+ *   bytes 4..7   u32 LE: headerLen
+ *   bytes 8..    header JSON (utf8, headerLen bytes)
+ *   rest         payload bytes
+ *
+ * SSR rule: nothing in this module touches window/document/navigator at
+ * module scope.
+ */
+export type SerializedArg = number | string | boolean | null | {
+    $: "asset";
+    id: number;
+} | {
+    $: "obj";
+    id: number;
+} | {
+    $: "arr";
+    v: number[];
+} | {
+    $: "imagedata";
+    id: number;
+}
+/** typed-array payload: k = index into TYPED_ARRAY_KINDS, b = raw bytes (copied at call time) */
+ | {
+    $: "ta";
+    k: number;
+    b: Uint8Array;
+} | {
+    $: "unsupported";
+    kind: string;
+};
+export declare const TYPED_ARRAY_KINDS: readonly [Int8ArrayConstructor, Uint8ArrayConstructor, Uint8ClampedArrayConstructor, Int16ArrayConstructor, Uint16ArrayConstructor, Int32ArrayConstructor, Uint32ArrayConstructor, Float32ArrayConstructor, Float64ArrayConstructor];
+/** Copy a typed array / ArrayBuffer into a serialized arg AT CALL TIME. */
+export declare function serializeTypedArray(v: ArrayBufferView | ArrayBuffer): SerializedArg;
+export declare function deserializeTypedArray(a: {
+    $: "ta";
+    k: number;
+    b: Uint8Array;
+}): ArrayBufferView;
+export interface RecordedOp {
+    /** EPOCH MILLISECONDS (contract §1 — rrweb-aligned clock). The codec's
+     * µs-delta encoding absorbs the large first delta. */
+    t: number;
+    op: string;
+    args: SerializedArg[];
+    /** property assignment rather than method call */
+    setter?: boolean;
+    /** interned-object creation: args = [factoryName, objId, ...factoryArgs] */
+    create?: boolean;
+    /** method call on interned object: args = [objId, method, ...callArgs] */
+    objcall?: boolean;
+    /** draw-site stamp id (Phase 3b) — set by __sfDrawSite, carried via the codec __site marker */
+    sfId?: string;
+}
+/** Asset payload captured for transmission + size accounting. */
+export interface CapturedAsset {
+    id: number;
+    kind: "image" | "imagedata";
+    /** time first referenced (epoch ms) */
+    t: number;
+    /** encoded size in bytes (webp for images, deflated raw for imagedata); resolves async */
+    bytes: number;
+    /** source dimensions (filled when the encode resolves) */
+    w?: number;
+    h?: number;
+    /** retained only when the recorder runs with retainAssets (worker relay path) */
+    bitmap?: ImageBitmap;
+    imageData?: ImageData;
+}
+/** Encoded-image result from the webp encoder (size always; bytes on demand). */
+export interface EncodedImage {
+    size: number;
+    bytes?: ArrayBuffer;
+}
+export type EncodeImageFn = (bitmap: ImageBitmap) => Promise<EncodedImage>;
+export interface AssetDataInfo {
+    id: number;
+    format: "webp" | "imagedata";
+    w: number;
+    h: number;
+    t: number;
+}
+export interface RecorderSink {
+    onOp(op: RecordedOp): void;
+    /** called when an asset finished encoding (size known) */
+    onAssetBytes(id: number, bytes: number, t: number): void;
+    note(msg: string): void;
+    /** SDK extension: encoded asset payload ready for an SFCV `asset` frame. */
+    onAssetData?(info: AssetDataInfo, payload: Uint8Array): void;
+    /** SDK extension: a dynamic VIDEO source was captured for a draw (governor signal). */
+    onVideoSource?(t: number): void;
+    /** SDK extension: a cross-origin/tainted image source could not be read back
+     * (canvas is tainted). `t` is the capture-time timestamp (same clock as ops).
+     * The manager emits an `op:"taint"` index event so the player can show a
+     * placeholder instead of a silent blank. Deduped manager-side per canvas. */
+    onTaint?(t: number): void;
+}
+export type AssetMode = "dataurl" | "cas";
+export interface StateFrame {
+    props: Record<string, SerializedArg>;
+    /** [a,b,c,d,e,f] */
+    transform: number[];
+}
+export interface StateSnapshot {
+    stack: StateFrame[];
+    current: StateFrame;
+}
+export declare class BufferSink implements RecorderSink {
+    ops: RecordedOp[];
+    assetEvents: {
+        id: number;
+        bytes: number;
+        t: number;
+    }[];
+    assetData: {
+        info: AssetDataInfo;
+        payload: Uint8Array;
+    }[];
+    notes: string[];
+    onOp(op: RecordedOp): void;
+    onAssetBytes(id: number, bytes: number, t: number): void;
+    onAssetData(info: AssetDataInfo, payload: Uint8Array): void;
+    note(m: string): void;
+}
+/**
+ * Video-mode dirtiness sink: keeps the patch recorder attached purely to
+ * drive the per-canvas dirty flag — every op is discarded with ZERO
+ * serialize/encode cost (recorders short-circuit on `instanceof DiscardSink`
+ * before serializing arguments).
+ */
+export declare class DiscardSink implements RecorderSink {
+    private onDirty;
+    constructor(onDirty: () => void);
+    onOp(_op: RecordedOp): void;
+    onAssetBytes(_id: number, _bytes: number, _t: number): void;
+    note(_m: string): void;
+}
+/** Shared zero-cost op handed to DiscardSink (its contents are never read). */
+export declare const DIRTY_OP: RecordedOp;
+export type SfcvKind = "commands" | "keyframe" | "asset" | "video-init" | "video-chunk";
+export interface SfcvHeader {
+    v: 1;
+    kind: SfcvKind;
+    sessionId: string;
+    pageVisitUuid: string;
+    /** rrweb mirror node id at start, as a string */
+    canvasId: string;
+    /** monotonically increasing PER CANVAS across all kinds */
+    seq: number;
+    /** epoch ms — same clock as rrweb event timestamps */
+    tMs: number;
+    /**
+     * payload byte length. SDK extension to contract §1: each stored .sfcv
+     * object is self-delimiting, so a CONCATENATION of frames (the GraphQL
+     * dataBase64 retrieval shape, contract §3) can be split without scanning
+     * payload bytes for magic. Absent => payload runs to end of buffer
+     * (single-frame compatibility).
+     */
+    pLen?: number;
+    meta?: Record<string, unknown>;
+}
+export declare function buildFrame(header: Omit<SfcvHeader, "pLen">, payload?: Uint8Array | ArrayBuffer | null): ArrayBuffer;
+export interface ParsedFrame {
+    header: SfcvHeader;
+    payload: Uint8Array;
+}
+/** Parse one frame or a concatenation of frames. Throws on corrupt input. */
+export declare function parseFrames(bytes: ArrayBuffer | Uint8Array): ParsedFrame[];
+/** Chunked base64 for ArrayBuffers (video-init decoder descriptions). */
+export declare function bytesToBase64(bytes: ArrayBuffer | Uint8Array): string;

package/dist/types/canvas/videoCapture.d.ts

@@ -0,0 +1,67 @@
+export interface VideoCaptureOut {
+    /** decoder config known — emit the SFCV video-init frame */
+    onInit(codec: string, description: ArrayBuffer | null): void;
+    /** encoded chunk — emit an SFCV video-chunk frame */
+    onChunk(key: boolean, timestampUs: number, data: ArrayBuffer): void;
+    note(msg: string): void;
+    /** A11 backpressure: true when the transport's send buffer is saturated, so
+     * afterRender SKIPS producing a new VideoFrame until it drains. Optional — when
+     * absent, frame production is never throttled. */
+    isTransportSaturated?(): boolean;
+}
+export declare class VideoCapture {
+    private canvas;
+    private now;
+    private out;
+    private opts?;
+    private client;
+    private configured;
+    private failed;
+    private stopped;
+    private lastFrame;
+    private lastKey;
+    private boostUntil;
+    private configuredW;
+    private configuredH;
+    private intervalId;
+    /** A11: dedupe the "throttled" note to once per saturation episode */
+    private throttledNoted;
+    /** A24: an encoder restart at the new canvas size is in flight */
+    private restarting;
+    /** A24: force the next captured frame to a keyframe (after a restart) */
+    private forceKeyNext;
+    static supported(): boolean;
+    constructor(canvas: HTMLCanvasElement, now: () => number, out: VideoCaptureOut, opts?: {
+        intervalPaced?: boolean;
+    });
+    /** Resolves true when the encoder configured; false -> keyframes-only fallback. */
+    start(): Promise<boolean>;
+    onInteraction(tMs: number): void;
+    /** Same-task capture: invoked by the manager's microtask pump right after
+     * the scene rendered. Dirty-by-construction — only called when a frame was
+     * drawn (or on the interval for placeholder canvases). */
+    afterRender(t: number): void;
+    /**
+     * A24: restart the encoder at the canvas's current dimensions after a
+     * mid-stream resize. The old encoder is torn down (its locked-size frames are
+     * no longer valid) and a fresh one is configured for the new size; the new
+     * encoder's first chunk re-emits the decoder config (onInit) so the player
+     * re-initializes, and the next captured frame is forced to a keyframe. Skips
+     * if already restarting, stopped, or the new size is zero.
+     */
+    private requestRestart;
+    /** Non-terminal drain (visibilitychange:hidden on mobile, where the OS may
+     * kill the tab without a reliable pagehide): push the encoder's queued frames
+     * out as chunks WITHOUT tearing down, so capture resumes if the tab returns.
+     * No-op once stopped. */
+    flush(): Promise<void>;
+    /**
+     * A22 / A6 / A10: immediate teardown WITHOUT flushing — used when the canvas
+     * was removed from the DOM, masked mid-session, or its GPU context was lost.
+     * Flushing would emit chunks for content that is gone/garbage, so we just
+     * terminate the encoder worker and stop. Idempotent.
+     */
+    abort(): void;
+    /** Flush the encoder (remaining chunks stream through onChunk) and tear down. */
+    stop(): Promise<void>;
+}

package/dist/types/canvas/workerRelay.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Main-thread registry for canvases whose control was transferred to a
+ * worker, plus the AUTO-ASSOCIATION patches the bench left to the build
+ * plugin (contract §5):
+ *
+ *  - HTMLCanvasElement.prototype.transferControlToOffscreen is patched to
+ *    remember which OffscreenCanvas came from which canvas element.
+ *  - Worker.prototype.postMessage is patched to map canvas -> worker when an
+ *    OffscreenCanvas from a tracked canvas appears in the transfer list.
+ *
+ * Worker-side recording additionally requires the customer to import
+ * `@sailfish-ai/recorder/canvas-worker` in the worker (the shim). The
+ * manager pings the worker (sf-record-ping/pong) to detect the shim; absent
+ * a pong, the canvas falls back to video capture of the placeholder.
+ *
+ * SSR rule: nothing here touches window/document at module scope — patches
+ * install inside installWorkerRelay().
+ */
+/** Manager subscription: fires when a canvas->worker link is discovered. */
+export declare function setWorkerAssociationNotifier(fn: ((canvas: HTMLCanvasElement, worker: Worker) => void) | null): void;
+export declare function installWorkerRelay(): void;
+export declare function registerWorkerCanvas(canvas: HTMLCanvasElement, worker: Worker): void;
+export declare function getWorkerForCanvas(canvas: HTMLCanvasElement): Worker | undefined;
+export declare function unregisterWorkerCanvas(canvas: HTMLCanvasElement): void;
+/**
+ * Detect the worker-side shim: resolves true iff the worker answers
+ * sf-record-ping with sf-record-pong within `timeoutMs`.
+ */
+export declare function pingWorkerShim(worker: Worker, timeoutMs?: number): Promise<boolean>;

package/dist/types/canvas/workerShim.d.ts

@@ -0,0 +1,10 @@
+/** Optional: explicitly register the OffscreenCanvas 2D context to record
+ * (the getContext patch normally does this automatically). */
+export declare function registerWorkerCanvasContext(ctx: {
+    getTransform(): DOMMatrix;
+}): void;
+/** Optional: keep the recorder clock in sync with a custom render time. */
+export declare function setWorkerNow(now: () => number): void;
+/** Install the relay message listener (call once at worker startup —
+ * importing this module inside a worker does it automatically). */
+export declare function installWorkerRecorder(): void;

package/dist/types/canvasFrameStore.d.ts

@@ -0,0 +1,23 @@
+export interface PersistedCanvasFrame {
+    id?: number;
+    timestamp: number;
+    bytes: number;
+    buf: ArrayBuffer;
+}
+/**
+ * Persist one binary canvas frame. Returns true if the frame was durably
+ * written, false if IDB is unavailable (caller should keep the memory-ring
+ * fallback). After a successful add, prunes oldest frames so the store stays
+ * under FRAME_STORE_MAX_BYTES.
+ */
+export declare function persistCanvasFrame(buf: ArrayBuffer): Promise<boolean>;
+/**
+ * Read all persisted frames in insertion order (ascending id), dropping any
+ * past the TTL and scheduling their background deletion. The returned `buf`s
+ * are ready to hand straight to the WS binary send path.
+ */
+export declare function readAllCanvasFrames(): Promise<PersistedCanvasFrame[]>;
+export declare function deleteCanvasFramesByIds(ids: number[]): Promise<void>;
+export declare function clearCanvasFrames(): Promise<void>;
+/** Diagnostics: total bytes currently persisted (0 when IDB unavailable). */
+export declare function countPersistedCanvasFrameBytes(): Promise<number>;

package/dist/types/graphql.d.ts

@@ -4,7 +4,7 @@ initialBackoff?: number, // Initial backoff in milliseconds
 backoffFactor?: number): Promise<GraphQLResponse<T>>;
 export declare function fetchCaptureSettings(apiKey: string, backendApi: string): Promise<GraphQLResponse<CaptureSettingsResponse>>;
 export declare function fetchFunctionSpanTrackingEnabled(apiKey: string, backendApi: string): Promise<GraphQLResponse<FunctionSpanTrackingEnabledResponse>>;
-export declare function startRecordingSession(apiKey: string, recordingId: string, backendApi: string, serviceIdentifier: string, serviceVersion?: string, mapUuid?: string, gitSha?: string, library?: string, serviceAdditionalMetadata?: Record<string, any>): Promise<GraphQLResponse<StartSessionResponse>>;
+export declare function startRecordingSession(apiKey: string, recordingId: string, backendApi: string, serviceIdentifier: string, serviceVersion?: string, mapUuid?: string, gitSha?: string, library?: string, serviceAdditionalMetadata?: Record<string, any>, gitOrg?: string, gitRepo?: string, gitProvider?: string): Promise<GraphQLResponse<StartSessionResponse>>;
 export declare function sendDomainsToNotPropagateHeaderTo(apiKey: string, domains: string[], backendApi: string): Promise<GraphQLResponse<void>>;
 export declare function createTriageFromRecorder(apiKey: string, backendApi: string, recordingSessionId: string, timestampStart: string, timestampEnd: string, description?: string, triageSource?: string): Promise<GraphQLResponse<CreateTriageResponse>>;
 export declare function fetchEngineeringTicketPlatformIntegrations(apiKey: string, backendApi: string): Promise<GraphQLResponse<GetEngineeringTicketPlatformIntegrationsFromApiKeyResponse>>;

package/dist/types/index.d.ts

@@ -1,13 +1,14 @@
 import type { LogRecordOptions } from "@sailfish-rrweb/rrweb-plugin-console-record";
 import type { ShortcutsConfig } from "./inAppReportIssueModal";
 import { CaptureSettings, MaskInputOptions } from "./types";
+import { type ShapeRedactStyle, type TextRedactStyle } from "./canvas/canvasPrivacy";
 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, maskInputSelector, maskTextSelector, blockSelector, unmaskSelector, maskInputOptions, 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, recordCanvas, maskCanvasClass, gitOrg, gitRepo, gitProvider, library, headlessRecording, }: {
     apiKey: string;
     backendApi?: string;
     domainsToPropagateHeaderTo?: string[];
@@ -35,6 +36,11 @@ export declare function startRecording({ apiKey, backendApi, domainsToPropagateH
     blockSelector?: string;
     unmaskSelector?: string;
     maskInputOptions?: MaskInputOptions;
+    recordCanvas?: boolean;
+    maskCanvasClass?: string;
+    gitOrg?: string;
+    gitRepo?: string;
+    gitProvider?: string;
     headlessRecording?: boolean;
 }): Promise<void>;
 export declare const initRecorder: (options: {
@@ -97,6 +103,32 @@ export declare const initRecorder: (options: {
     capturePerformanceMetrics?: boolean;
     showEngTicketFieldsInReportIssueModalDefault?: boolean;
     maskTextClass?: string;
+    /**
+     * Enable the Sailfish pixel-perfect **canvas** recorder (2D command stream +
+     * WebGL/WebGPU video + keyframes). A caller value wins over the dashboard
+     * Capture Setting. Off by default — see the Canvas Recording docs.
+     * Distinct from rrweb's legacy `recordCanvas` webp snapshotting, which this
+     * SDK force-disables; this option drives the Sailfish pipeline.
+     * @default false
+     */
+    recordCanvas?: boolean;
+    /**
+     * CSS class that EXCLUDES a `<canvas>` (or any ancestor) from canvas recording
+     * entirely — no commands, no keyframes, no video. Whole-canvas masking; for
+     * partial masking use `maskCanvasDraws()`.
+     * @default "sailfishSanitize"
+     */
+    maskCanvasClass?: string;
+    /**
+     * Click-to-code: optional git repo for this build, as a FALLBACK when the
+     * `@sailfish-ai/sf-map-utils` build plugin isn't used (the plugin auto-detects
+     * the git remote and is the preferred source). Sets the build's org/repo on the
+     * ServiceIdentifier so the replay user-journey shows org/repo + file:line
+     * deep-links per click. `gitProvider` is GITHUB | GITLAB | BITBUCKET.
+     */
+    gitOrg?: string;
+    gitRepo?: string;
+    gitProvider?: string;
     /**
      * When true, recording proceeds even inside headless / automated browser
      * environments (Puppeteer, Playwright, Cypress, etc.), bypassing the
@@ -117,6 +149,72 @@ export declare const initRecorder: (options: {
 export * from "./graphql";
 export { openReportIssueModal } from "./inAppReportIssueModal";
 export * from "./recording";
+/** Per-call redaction options for {@link maskCanvasDraws}. Each field overrides
+ * the global style (set via the `canvasRedactStyle` init option) for this block
+ * only; omitted fields inherit. */
+export interface MaskCanvasDrawsOptions {
+    /** How masked TEXT renders: `"asterisks"` (default — every char → `*`,
+     * length-preserving) or `"bar"` (a solid redaction bar over the text). */
+    text?: TextRedactStyle;
+    /** How masked SHAPES render: `"color"` (default — the SAME shape, recolored to
+     * the redaction color), `"block"` (a solid block over the shape's bounding
+     * box), or `"remove"` (drop the shape entirely, when the geometry itself is
+     * sensitive). */
+    shape?: ShapeRedactStyle;
+    /** Mask ONLY text inside the block; record shapes/geometry normally. */
+    keepShapes?: boolean;
+}
+/**
+ * Sanitize SPECIFIC content drawn into a `<canvas>`. Wrap the draw calls that
+ * paint sensitive data — geometry, shapes, text, images — and they are **redacted
+ * in place**: the recorded command stream draws a redaction *version of the same
+ * element* (shapes recolored to a dark redaction color by default, text rendered
+ * as length-preserving asterisks), and the masked regions are **blanked on every
+ * pixel keyframe** so the real pixels never leave the browser. Layout is
+ * preserved; content is hidden. Everything drawn OUTSIDE the wrapper records
+ * normally, and the canvas stays pixel-perfect outside the masked regions.
+ *
+ * This is the only way to mask *part* of a canvas. CSS-selector masking
+ * (`data-sf-mask` / `maskCanvasClass` / `maskTextSelector`) is whole-`<canvas>`
+ * only — a canvas has no sub-elements for a selector to target, so to redact one
+ * shape/region you wrap the draw calls themselves.
+ *
+ * The redaction style is configurable per call via `opts` (or globally via the
+ * `canvasRedactStyle` init option):
+ *   - `text`: `"asterisks"` (default) | `"bar"`
+ *   - `shape`: `"color"` (default, same shape recolored) | `"block"` | `"remove"`
+ *   - `keepShapes`: redact only text, leave shapes visible.
+ *
+ * Keep the wrapped draws **self-contained** (set the styles/transform you need
+ * inside it, or use `ctx.save()`/`ctx.restore()`): masked state setters
+ * (fill/stroke styles) are dropped, so a style you change inside but rely on
+ * *outside* won't carry over in replay.
+ *
+ * Safe no-op when canvas recording is off, or when this context isn't being
+ * recorded (snippet tier before attach, masked canvas, SSR): it just runs
+ * `draw()` and returns its result. 2D contexts only — for WebGL/WebGPU (whose
+ * content is pixels, not commands) exclude the whole canvas with `data-sf-mask`.
+ *
+ * @example
+ * import { maskCanvasDraws } from '@sailfish-ai/recorder';
+ *
+ * function render(ctx) {
+ *   ctx.fillStyle = '#0a0';
+ *   ctx.fillRect(0, 0, 800, 600);            // recorded
+ *
+ *   maskCanvasDraws(ctx, () => {             // redacted in place:
+ *     ctx.fillStyle = '#007BFF';
+ *     ctx.fillRect(rectX, rectY, w, h);      //   ← same rect, recolored to redaction color
+ *     drawJSTSGeometry(sensitivePolygon, ctx); //   ← polygon redacted in place
+ *     ctx.fillText(patientName, x, y);       //   ← "***********" (length preserved)
+ *   });
+ *
+ *   // drop the geometry entirely instead of recoloring it:
+ *   maskCanvasDraws(ctx, () => drawJSTSGeometry(secretShape, ctx), { shape: 'remove' });
+ * }
+ */
+export declare function maskCanvasDraws<T>(target: CanvasRenderingContext2D | HTMLCanvasElement, draw: () => T, opts?: MaskCanvasDrawsOptions): T;
+export { registerKonvaStage, registerFabricCanvas, registerChart, registerThreeScene, registerPixiApp, type SemanticTarget, } from "./canvas/adapters";
 export * from "./sendSailfishMessages";
 export { getOrSetSessionId } from "./session";
 export * from "./types";

package/dist/types/types.d.ts

@@ -17,7 +17,30 @@ export type MaskInputOptions = Partial<{
     password: boolean;
 }>;
 export interface CaptureSettings {
+    /**
+     * Enable the Sailfish canvas-recording pipeline (SFCV): command/keyframe/video
+     * capture of `<canvas>` content shipped as binary frames over the WebSocket.
+     * Default FALSE (opt-in). This is the single canvas-recording flag — settable
+     * via the dashboard / server payload, or the `initRecorder({ recordCanvas })`
+     * option. NB: rrweb's own legacy webp canvas snapshotting is ALWAYS
+     * force-disabled at the rrweb `record()` call, so `record()` never receives
+     * `recordCanvas: true`; this flag drives ONLY the Sailfish pipeline.
+     */
     recordCanvas: boolean;
+    /**
+     * @deprecated Backend wire field only (GraphQL `recordCanvasSf` / DB column
+     * `record_canvas_sf`). Read ONCE during settings assembly and mapped onto the
+     * unified `recordCanvas` above — never read elsewhere in the SDK. Kept so the
+     * server `captureSettingsFromApiKey` payload type-checks without renaming the
+     * backend field.
+     */
+    recordCanvasSf?: boolean;
+    /**
+     * Canvases matching `.${maskCanvasClass}`, `[data-sf-mask]`, or inside a
+     * masked subtree record NOTHING (an op:"masked" index event is emitted).
+     * Default "sailfishSanitize".
+     */
+    maskCanvasClass?: string;
     recordCrossOriginIframes: boolean;
     collectFonts: boolean;
     inlineImages: boolean;
@@ -35,6 +58,23 @@ export interface CaptureSettings {
     blockSelector?: string;
     unmaskSelector?: string;
     maskInputOptions?: MaskInputOptions;
+    /**
+     * Canvas text masking. `true` redacts drawn text on every recorded canvas;
+     * `false` opts out of the mirror-DOM default; unset = mirror-DOM (if DOM text
+     * masking — `maskTextSelector`/`maskTextClass` — is configured, canvas text is
+     * masked too). Independent of `maskCanvasClass` (which suppresses whole
+     * canvases).
+     */
+    maskCanvasText?: boolean;
+    /**
+     * Global canvas redaction style. Text → `"asterisks"` (default) | `"bar"`;
+     * shapes (maskCanvasDraws) → `"color"` (default, same shape recolored) |
+     * `"block"` | `"remove"`. Per-call `maskCanvasDraws` options override it.
+     */
+    canvasRedactStyle?: {
+        text?: "asterisks" | "bar";
+        shape?: "color" | "block" | "remove";
+    };
 }
 export interface ConsoleRecordSettings {
     level: string[];

package/dist/types/websocket.d.ts

@@ -3,6 +3,25 @@ export interface WsHandle {
     readyState: number;
     close: () => void;
 }
+/** Count of binary frames dropped from the ring (diagnostics). */
+export declare function getBinaryDropCount(): number;
+/**
+ * Current socket send-buffer depth in bytes (best effort). Worker path: the
+ * worker posts `bufferedAmount` on a light interval and we cache it. Direct
+ * path: read live. 0 when the socket is closed/unavailable.
+ */
+export declare function getBufferedAmount(): number;
+/** True when the socket's send buffer is over the saturation threshold —
+ * callers (canvas video capture) should pause producing new frames. */
+export declare function isTransportSaturated(): boolean;
+/**
+ * Send a binary frame (canvas SFCV) over the recording WebSocket.
+ * Direct path: webSocket.send(ArrayBuffer); worker path: transferred
+ * postMessage. When the socket is not open, the frame is buffered durably in
+ * IndexedDB (surviving reload) with a memory-ring fallback, and flushed on
+ * reconnect.
+ */
+export declare function wsSendBinary(buffer: ArrayBuffer): boolean;
 export declare function requestTimeSync(): void;
 type NavigationCallback = () => void;
 /** Register a callback to be invoked immediately on pushState/replaceState/popstate/hashchange. */