@sailfish-ai/recorder 1.12.4 → 1.12.6

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

@@ -0,0 +1,184 @@
+import { type SensitiveContentFlags } from "./piiDetect";
+export type CanvasPrivacyMode = "suppress" | "redact" | "normal";
+/** Why a canvas was suppressed — rides the op:"masked" index event so the
+ * player / debugging can distinguish a block selector from the legacy
+ * mask-canvas class. */
+export type SuppressReason = "block" | "mask";
+/**
+ * The privacy-relevant subset of CanvasRecorderSettings. Kept as its own
+ * interface so the classifier is unit-testable without constructing a full
+ * recorder settings object.
+ */
+export interface CanvasPrivacySettings {
+    /** legacy mask-canvas class (default "sailfishSanitize") — suppress */
+    maskCanvasClass?: string;
+    /** rrweb maskTextClass — redact drawn text */
+    maskTextClass?: string;
+    /** rrweb maskTextSelector — redact drawn text */
+    maskTextSelector?: string;
+    /** rrweb blockSelector — suppress */
+    blockSelector?: string;
+    /** rrweb unmaskSelector — override: force normal (wins over block/mask) */
+    unmaskSelector?: string;
+    /**
+     * Global canvas-text masking switch (the `maskCanvasText` init option).
+     *   true  — every recorded canvas redacts drawn text (independent of any
+     *           selector), regardless of DOM masking config.
+     *   false — opt OUT of the mirror-DOM default (DOM text masking does NOT
+     *           propagate to canvas text). Explicit per-canvas maskText* selector
+     *           matches still redact (matching a selector is explicit intent).
+     *   undefined — mirror-DOM default: if DOM text masking is configured
+     *           (`maskTextSelector` or `maskTextClass` set), canvas text is masked
+     *           too; otherwise normal.
+     */
+    maskCanvasText?: boolean;
+    recordSsn?: boolean;
+    recordCreditCardInfo?: boolean;
+    recordDob?: boolean;
+}
+/** The legacy mask-canvas selector: `.${maskCanvasClass}, [data-sf-mask]`. */
+export declare function maskCanvasSelector(settings: CanvasPrivacySettings): string;
+/**
+ * Classify a canvas's privacy mode. PRECEDENCE (highest first):
+ *
+ *   1. unmaskSelector ancestor/self match            ⇒ "normal" (override)
+ *   2. blockSelector OR mask-canvas selector match   ⇒ "suppress"
+ *   3. maskTextClass (.class) OR maskTextSelector    ⇒ "redact"
+ *   3b. global maskCanvasText === true               ⇒ "redact"
+ *   3c. mirror-DOM (DOM text masking configured AND
+ *       maskCanvasText !== false)                    ⇒ "redact"
+ *   4. otherwise                                     ⇒ "normal"
+ *
+ * NOTE on HIPAA: a HIPAA-enabled account does NOT suppress canvas recording.
+ * Canvas still records; PHI separation happens downstream (the SDK's index
+ * events ride the rrweb event pipeline, which routes to the `phi.*` sinks via
+ * the backend `is_phi` decision, and binary frames store in the company bucket
+ * exactly like raw events). Developers prevent specific sensitive canvases from
+ * being captured with the mask/block selectors below — HIPAA is a routing flag,
+ * not a capture switch.
+ *
+ * Uses ancestor-aware `closestSafe` for class/block/unmask selectors (a privacy
+ * container masks every canvas inside it) and self-or-ancestor for maskText*.
+ * Every selector call is wrapped so a malformed admin selector fails SAFE: it
+ * simply does not match (a throw would crash the recorder; the explicit
+ * mask-canvas / block backstops remain effective).
+ */
+export declare function classifyCanvasPrivacy(canvas: HTMLCanvasElement, settings: CanvasPrivacySettings): CanvasPrivacyMode;
+/**
+ * Determine WHY a canvas was suppressed (for the op:"masked" reason field).
+ * Only meaningful when `classifyCanvasPrivacy` returned "suppress"; precedence
+ * matches the classifier (unmask override, then block, then mask-canvas).
+ * Returns undefined for non-suppress canvases.
+ */
+export declare function suppressReason(canvas: HTMLCanvasElement, settings: CanvasPrivacySettings): SuppressReason | undefined;
+/**
+ * Full length-preserving mask: every non-whitespace char → "*", whitespace
+ * kept. Mirrors rrweb's maskTextFn (privacyMask.makeMaskTextFn) so a redacted
+ * canvas string looks identical to a redacted DOM text node. Surrogate pairs
+ * (emoji) and combining marks are each non-whitespace code units, so they
+ * become "*" per UTF-16 unit — never throws, never leaks the original glyph.
+ */
+export declare function maskAllText(text: string): string;
+/**
+ * Redact a single drawn-text argument according to the canvas's privacy mode:
+ *   - "redact":  full mask (maskAllText) — drawn text is never legible.
+ *   - "normal":  content-detection redaction (redactSensitiveContent) gated on
+ *                the record* flags — defense-in-depth so CC/SSN/DOB that an app
+ *                paints into a non-masked canvas is still caught.
+ *   - "suppress": never reaches here (a suppressed canvas records no ops); the
+ *                input is returned unchanged as a defensive no-op.
+ *
+ * Non-string input (numbers, x/y coords passed as the 2nd/3rd fillText args)
+ * passes through untouched — only the FIRST string arg of fillText/strokeText
+ * is the rendered text, and the caller restricts redaction to that arg.
+ */
+export declare function redactCanvasText(text: unknown, mode: CanvasPrivacyMode, flags: SensitiveContentFlags): unknown;
+/** How masked drawn text is represented. `asterisks` length-preserves (every
+ * non-space char → "*"); `bar` drops the glyphs and paints a solid redaction bar
+ * over the text's bounding box. */
+export type TextRedactStyle = "asterisks" | "bar";
+/** How a masked shape (rect / path fill-stroke / image) is represented.
+ *   `color`  — keep the SAME shape, but force its fill/stroke to REDACTION_COLOR
+ *              (preserves layout; hides content).
+ *   `block`  — drop the shape's geometry; paint one solid REDACTION_COLOR block
+ *              over its bounding box.
+ *   `remove` — drop the shape entirely (for when the geometry itself is
+ *              sensitive). The keyframe region is still blanked so the original
+ *              pixels never ship. */
+export type ShapeRedactStyle = "color" | "block" | "remove";
+export interface RedactStyle {
+    text: TextRedactStyle;
+    shape: ShapeRedactStyle;
+}
+/** Mirror-DOM defaults: text → length-preserving asterisks (looks like a masked
+ * DOM text node), shapes → same shape recolored (layout preserved). */
+export declare const DEFAULT_REDACT_STYLE: RedactStyle;
+/** Dark neutral used everywhere a redaction is painted: recolored shapes + bars
+ * in the command stream AND the region-blanked keyframe pixels. A single source
+ * of truth keeps command replay and keyframe consistent. */
+export declare const REDACTION_COLOR = "#1f2433";
+/** Merge a per-call style override onto a base style (per-call wins; omitted
+ * fields inherit). `base` defaults to DEFAULT_REDACT_STYLE. Never mutates. */
+export declare function resolveRedactStyle(base: RedactStyle | undefined, override?: Partial<RedactStyle> | null): RedactStyle;
+/** An axis-aligned rectangle in device (canvas-pixel) space — the unit of
+ * keyframe region-blanking. */
+export interface MaskRegion {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** The 6-tuple of a 2D affine transform (a DOMMatrix subset). */
+export interface Mat2D {
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+    e: number;
+    f: number;
+}
+/**
+ * Transform the four corners of a LOCAL-space box (x0,y0)-(x1,y1) by a 2D matrix
+ * and return its axis-aligned bounding box in DEVICE space. Handles a general
+ * CTM (rotation / skew), not just translate+scale — a rotated rect maps to the
+ * AABB enclosing all four rotated corners. `pad` (px, device space) is added on
+ * every side so a blanked region fully covers antialiased glyph/stroke edges.
+ * Returns null when the inputs are non-finite (never throws into the hot path).
+ */
+export declare function transformedBox(x0: number, y0: number, x1: number, y1: number, m: Mat2D, pad?: number): MaskRegion | null;
+/** Device-space AABB of a local-space rect (x,y,w,h) under transform `m`. */
+export declare function rectRegion(x: number, y: number, w: number, h: number, m: Mat2D): MaskRegion | null;
+/** Inputs to localize a drawn-text box: measured width + ascent/descent (from
+ * `measureText`), the draw origin (x,y), and the active `textAlign`/`textBaseline`
+ * which shift the box relative to (x,y). */
+export interface TextBoxInput {
+    width: number;
+    ascent: number;
+    descent: number;
+    x: number;
+    y: number;
+    align?: string;
+    baseline?: string;
+}
+/**
+ * Compute a drawn-text bounding box in LOCAL (pre-transform) space from its
+ * measured metrics + alignment. textAlign shifts the box horizontally relative
+ * to the draw x (center → centered, right/end → left of x); textBaseline shifts
+ * it vertically relative to the draw y (top → below y, middle → centered,
+ * bottom → above y, default alphabetic → ascent above / descent below). The
+ * caller transforms this box to device space via `transformedBox`. start/end are
+ * treated as left/right (ltr assumption) — over-covering on rtl is harmless.
+ */
+export declare function textLocalBox(i: TextBoxInput): {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+};
+/** Device-space AABB of a drawn-text box — measure (text-local) then transform.
+ * `pad` (device px) should be font-size-proportional at the call site: the box is
+ * built from the glyphs' ADVANCE width, but italic / script / emoji ink overhangs
+ * the advance (side bearings), so a 1px pad would under-cover and leak a sliver on
+ * the keyframe. Over-covering is privacy-safe. */
+export declare function textRegion(i: TextBoxInput, m: Mat2D, pad?: number): MaskRegion | null;
+export type { SensitiveContentFlags };

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

@@ -0,0 +1,27 @@
+/**
+ * Compact binary encoding for the canvas command stream — verbatim port of the
+ * validated bench codec (test-applications/canvas-recorder-bench/src/capture/codec.ts).
+ * Opcode table + varint/f64 args + string table, deflate-compressed in ~1s batches.
+ *
+ * Op timestamps are EPOCH MS (contract §1); the µs-delta encoding below
+ * handles the large first delta (deltas are between ROUNDED absolute µs
+ * values so rounding error never accumulates).
+ */
+import type { RecordedOp } from "./protocol";
+/** Stable opcode table: union of 2D methods, tracked props, and meta ops. */
+export declare const OPCODES: string[];
+export declare class CommandEncoder {
+    private w;
+    private strings;
+    private lastTUs;
+    /** count of ops in current batch */
+    ops: number;
+    encode(op: RecordedOp): void;
+    private str;
+    private arg;
+    /** Flush current batch as raw (uncompressed) bytes. */
+    takeBatch(): Uint8Array;
+}
+export declare function decodeCommands(batches: Uint8Array[]): RecordedOp[];
+export declare function deflate(data: Uint8Array): Promise<Uint8Array>;
+export declare function inflate(data: Uint8Array): Promise<Uint8Array>;

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

@@ -0,0 +1,40 @@
+/**
+ * A30 — device-class budgets. Canvas capture budgets/thresholds were sized for
+ * desktop; on a memory- or CPU-constrained mobile device the same budgets risk
+ * OOM / jank. This resolves a device class from `navigator` (hardware hints +
+ * UA) and returns scaled budgets: per-session byte budget, concurrent hardware
+ * video-encoder cap, governor demotion thresholds, and an iOS-Safari preference
+ * for the MediaRecorder path (WebCodecs is flaky/absent on older iOS).
+ *
+ * SSR rule: NO `navigator` access at module scope. `resolveDeviceBudgets()`
+ * reads the passed-in nav (tests) or the global `navigator` ONLY when present,
+ * and falls back to the desktop profile when neither exists (server render).
+ */
+import type { GovernorThresholds } from "./governor";
+export type DeviceClass = "desktop" | "mobile" | "mobile-lowend";
+export interface DeviceBudgets {
+    deviceClass: DeviceClass;
+    /** per-session canvas byte budget (SDK-side; backend has its own backstop) */
+    sessionByteBudget: number;
+    /** max concurrent hardware video encoders for this session */
+    maxConcurrentVideo: number;
+    /** governor demotion-threshold overrides (tighter on constrained devices) */
+    governor: Partial<GovernorThresholds>;
+    /** prefer the MediaRecorder backend over WebCodecs (iOS-Safari WebCodecs is
+     * unreliable / absent on older versions) */
+    preferMediaRecorder: boolean;
+}
+/** Desktop default — preserves the pre-A30 budgets exactly. */
+export declare const DESKTOP_BUDGETS: DeviceBudgets;
+/** The subset of `navigator` we read — all fields optional / best-effort. */
+export interface NavigatorHints {
+    userAgent?: string;
+    deviceMemory?: number;
+    hardwareConcurrency?: number;
+    maxTouchPoints?: number;
+}
+/**
+ * Resolve device budgets. Pass `nav` in tests; in the browser it defaults to the
+ * global `navigator`; under SSR (no navigator) it returns the desktop profile.
+ */
+export declare function resolveDeviceBudgets(nav?: NavigatorHints): DeviceBudgets;

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

@@ -0,0 +1,54 @@
+/**
+ * Inline-blob encode workers (webp image encoder + WebCodecs video encoder)
+ * and their promise/event clients. Ports of the bench workers
+ * (test-applications/canvas-recorder-bench/src/workers/{imgEncoder,videoEncoder}.worker.ts)
+ * as TEMPLATE-STRING sources so the vite lib build emits NO separate worker
+ * files — same precedent as WS_WORKER_CODE in src/websocket.tsx. Unlike the
+ * WS worker, this code may use modern JS: every browser with WebCodecs /
+ * OffscreenCanvas supports ES2020.
+ *
+ * SDK adaptation to the bench video worker: encoded chunk DATA is posted
+ * LIVE (transferred) instead of accumulated until stop, and the decoder
+ * config is posted once as `decoder-config` — the manager streams video-chunk
+ * / video-init SFCV frames as they are produced.
+ *
+ * SSR rule: workers are created lazily inside functions, never at module scope.
+ */
+export interface EncodedImage {
+    size: number;
+    bytes?: ArrayBuffer;
+}
+/** Encode a bitmap to webp in the worker. TRANSFERS (detaches) the bitmap. */
+export declare function encodeBitmap(bitmap: ImageBitmap, quality: number, wantBytes?: boolean): Promise<EncodedImage>;
+/** Tear down the shared image-encoder worker (manager stop path). */
+export declare function terminateImgEncoder(): void;
+export interface VideoEncoderEvents {
+    onDecoderConfig(codec: string, description: ArrayBuffer | null): void;
+    onChunk(data: ArrayBuffer, timestampUs: number, key: boolean): void;
+    onError(message: string): void;
+}
+export declare class VideoEncoderClient {
+    private events;
+    private worker;
+    private configured;
+    private doneResolve;
+    private flushResolve;
+    private configResolve;
+    constructor(events: VideoEncoderEvents);
+    get isConfigured(): boolean;
+    configure(cfg: {
+        width: number;
+        height: number;
+        bitrate: number;
+        codecs: string[];
+    }): Promise<boolean>;
+    /** TRANSFERS (closes) the frame. */
+    encodeFrame(frame: VideoFrame, key: boolean): void;
+    /** Non-terminal drain: flush queued frames out as chunks WITHOUT closing the
+     * encoder, so capture can resume. Resolves once the worker acks (or times
+     * out). Safe to call repeatedly. */
+    flush(timeoutMs?: number): Promise<void>;
+    /** Flush the encoder; resolves once all chunks have been delivered. */
+    stop(timeoutMs?: number): Promise<void>;
+    terminate(): void;
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Phase 2 live-demotion governor (contract §5): per-canvas counters that
+ * decide when a command stream is too heavy and the canvas should demote to
+ * video capture.
+ *
+ *  - POST-deflate command bytes: demote when the trailing 3s window carries
+ *    more than 512 KB/s (i.e. > 1536 KB total in the window).
+ *  - dynamic VIDEO-source drawImage: demote when more than 2 video-element
+ *    draws land within any trailing 1s window.
+ *  - ops per frame: demote when a single frame (ops sharing one timestamp)
+ *    exceeds 5000 ops.
+ */
+export interface GovernorThresholds {
+    /** post-deflate command bytes per second (default 512 KiB/s) */
+    maxBytesPerSec: number;
+    /** how long the byte rate must be sustained (default 3000 ms) */
+    sustainMs: number;
+    /** video-element drawImage calls per second (default 2/s) */
+    maxVideoDrawsPerSec: number;
+    /** ops within a single frame timestamp (default 5000) */
+    maxOpsPerFrame: number;
+}
+export declare const DEFAULT_GOVERNOR_THRESHOLDS: GovernorThresholds;
+export type DemoteReason = "bytes" | "video-source" | "ops";
+export declare class CanvasGovernor {
+    private now;
+    private thresholds;
+    private byteSamples;
+    private videoDraws;
+    private frameT;
+    private frameOps;
+    private opsExceeded;
+    constructor(now: () => number, thresholds?: Partial<GovernorThresholds>);
+    /** Record post-deflate bytes for a flushed command batch. */
+    addBytes(n: number): void;
+    /** Record one dynamic video-source drawImage capture. */
+    addVideoDraw(): void;
+    /** Record one recorded op (tMs = the op's frame timestamp). */
+    addOp(tMs: number): void;
+    /** Returns the demotion reason once a threshold trips, else null. */
+    shouldDemote(): DemoteReason | null;
+    private pruneBytes;
+    private pruneVideo;
+}

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

@@ -0,0 +1,81 @@
+/**
+ * Periodic pixel keyframes captured same-task — port of the bench hybrid
+ * strategy's takeKeyframe (test-applications/canvas-recorder-bench/src/
+ * capture/hybrid.ts). Keyframes are the bit-exact ground truth and the seek
+ * anchor; for 2D they also enable replay-from-keyframe (state snapshot rides
+ * the SFCV keyframe meta).
+ */
+import { type MaskRegion } from "./canvasPrivacy";
+import type { StateSnapshot } from "./protocol";
+export interface KeyframeOut {
+    tMs: number;
+    w: number;
+    h: number;
+    /** 2D shadow state (null for gl/gpu/worker sources) */
+    state: StateSnapshot | null;
+    /** webp bytes */
+    bytes: ArrayBuffer;
+}
+export declare class KeyframeCapturer {
+    private canvas;
+    private snapshotState;
+    private emit;
+    private note;
+    /**
+     * Masked-region source (maskCanvasDraws / redact-mode text). Each device-space
+     * bbox is filled with REDACTION_COLOR on the scratch copy BEFORE the keyframe
+     * is encoded, so the real pixels of masked content never ship — replay then
+     * draws the baked redaction (recolored shapes / asterisks / bars) from the
+     * command stream on top of the blanked keyframe. Defaults to none (GL/other
+     * sources have no per-op masking).
+     */
+    private getMaskedRegions;
+    private scratch;
+    private scratchCtx;
+    private lastKeyframe;
+    /** has the canvas actually rendered since the last keyframe? */
+    private dirtySinceKeyframe;
+    private interactionRequested;
+    private pending;
+    private stopped;
+    constructor(canvas: HTMLCanvasElement, snapshotState: () => StateSnapshot | null, emit: (kf: KeyframeOut) => void, note: (msg: string) => void, 
+    /**
+     * Masked-region source (maskCanvasDraws / redact-mode text). Each device-space
+     * bbox is filled with REDACTION_COLOR on the scratch copy BEFORE the keyframe
+     * is encoded, so the real pixels of masked content never ship — replay then
+     * draws the baked redaction (recolored shapes / asterisks / bars) from the
+     * command stream on top of the blanked keyframe. Defaults to none (GL/other
+     * sources have no per-op masking).
+     */
+    getMaskedRegions?: () => readonly MaskRegion[]);
+    onInteraction(tMs: number): void;
+    /**
+     * A27 — one-shot keyframe for a canvas that was already painted BEFORE the
+     * SDK loaded and may never redraw (a static pre-existing canvas). The normal
+     * keyframe pacing is dirty-gated (afterRender only runs after a draw), so a
+     * canvas that is painted once and then idle would never emit a keyframe and
+     * would replay blank. This forces a single ground-truth keyframe of the
+     * canvas's current pixels, independent of the dirty flag or the interval.
+     *
+     * Unlike afterRender this is NOT same-task with a render — but a STATIC
+     * pre-existing 2D canvas's committed pixels persist outside any rendering
+     * task (the guardrail-#6 hazard only affects pdb:false WebGL / task-scoped
+     * WebGPU textures, which are not what A27 targets). takeKeyframe's
+     * drawImage(canvas) copy throws on a zero-size canvas (caught -> no emit) and
+     * a masked/tainted canvas never reaches here (the manager only builds a
+     * controller for unmasked canvases, and a tainted readback simply fails the
+     * encode). Returns true if a keyframe copy was kicked off.
+     */
+    initialKeyframe(tMs: number): boolean;
+    /** Same-task keyframes: GPU-canvas-safe and never captures mid-draw. */
+    afterRender(tMs: number): void;
+    takeKeyframe(t: number): void;
+    /** Final keyframe (if dirty) + settle outstanding encodes. */
+    stop(finalT: number): Promise<void>;
+    /**
+     * A22 / A6: immediate disposal with NO final keyframe — used when the canvas
+     * was removed from the DOM or masked mid-session (its pixels are gone or must
+     * not be recorded). Releases the scratch keyframe canvas so it can be GC'd.
+     */
+    dispose(): void;
+}

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

@@ -0,0 +1,91 @@
+/**
+ * A41 — MediaRecorder fallback video capture (SDK half), for browsers that have
+ * NO WebCodecs (`VideoEncoder` / `VideoFrame`) but DO have `MediaRecorder` +
+ * `HTMLCanvasElement.captureStream` (notably Safari < 26). Without this, such a
+ * canvas would degrade to keyframe-only; here we capture continuous video via
+ * MediaRecorder instead.
+ *
+ * Wire contract (the player agent implements the exact mirror):
+ *   - ONE `video-init` SFCV frame, header
+ *       { kind:"video-init", codec:"mediarecorder", mimeType:<recorder.mimeType>, w, h }
+ *     (no binary payload).
+ *   - `video-chunk` SFCV frames, header { kind:"video-chunk", codec:"mediarecorder", seq }
+ *     each carrying ONE `MediaRecorder.ondataavailable` Blob's bytes as the
+ *     payload. The FIRST webm chunk holds the init segment, so ORDER MUST be
+ *     preserved (seq is monotonic, assigned in dataavailable order).
+ *
+ * Differences from VideoCapture (WebCodecs):
+ *   - No same-task readback hazard: MediaRecorder pulls frames off the
+ *     captureStream track itself, so there is no afterRender pixel grab and no
+ *     guardrail-#6 concern. The manager still calls afterRender for dirtiness
+ *     bookkeeping, but it is a no-op here.
+ *   - Chunk bytes are read from the Blob asynchronously (blob.arrayBuffer());
+ *     emission is chained so seq order is preserved even if reads resolve out
+ *     of order.
+ *
+ * SSR rule: nothing here touches window/document at module scope; capability
+ * detection and all DOM/Media access happen inside methods called from the
+ * manager (which itself only runs in the browser).
+ */
+export interface MediaRecorderCaptureOut {
+    /** decoder/container known — emit the SFCV video-init frame (no payload). */
+    onInit(mimeType: string, w: number, h: number): void;
+    /** one MediaRecorder Blob's bytes — emit an SFCV video-chunk frame. */
+    onChunk(seq: number, data: ArrayBuffer): void;
+    note(msg: string): void;
+}
+/**
+ * Feature detection (contract): MediaRecorder fallback is usable ONLY when
+ * `MediaRecorder`, `HTMLCanvasElement.prototype.captureStream`, and
+ * `MediaRecorder.isTypeSupported` for at least one candidate mime are present.
+ * Callers prefer WebCodecs and reach here only when WebCodecs is ABSENT.
+ */
+export declare function mediaRecorderSupported(): boolean;
+/** First candidate mime MediaRecorder claims to support, or null. */
+export declare function pickMime(): string | null;
+export declare class MediaRecorderCapture {
+    private canvas;
+    private out;
+    private recorder;
+    private stream;
+    private stopped;
+    private started;
+    private seq;
+    /** chain Blob -> bytes emission so seq order is preserved across async reads */
+    private emitChain;
+    constructor(canvas: HTMLCanvasElement, out: MediaRecorderCaptureOut);
+    static supported(): boolean;
+    /** Resolves true once the recorder started; false -> keyframes-only fallback. */
+    start(): Promise<boolean>;
+    /** A non-empty Blob from dataavailable. Read bytes async, emit in seq order. */
+    private onData;
+    /**
+     * The manager's microtask pump calls this after every render for dirtiness
+     * bookkeeping. MediaRecorder pulls frames off the captureStream track on its
+     * own, so this is intentionally a no-op (kept for VideoCapture parity). The
+     * `_t` mirrors VideoCapture.afterRender's signature.
+     */
+    afterRender(_t: number): void;
+    /** Interaction boost is a no-op: the captureStream fps is fixed and the
+     * recorder cannot be told to key on demand. Kept for VideoCapture parity. */
+    onInteraction(_tMs: number): void;
+    /**
+     * Non-terminal drain (visibilitychange:hidden): force the recorder to emit a
+     * chunk for everything buffered so far WITHOUT stopping, so capture resumes if
+     * the tab returns. Mirrors VideoCapture.flush(). No-op once stopped.
+     */
+    flush(): Promise<void>;
+    /**
+     * Terminal stop: flush the final chunk (requestData then stop fire a last
+     * dataavailable), settle the emission chain so the final bytes reach onChunk,
+     * then release the recorder + stream tracks. Idempotent.
+     */
+    stop(): Promise<void>;
+    /**
+     * Immediate teardown WITHOUT flushing (A22/A6/A10 parity): the canvas is gone
+     * or must not be recorded, so drop the recorder and stop the stream tracks
+     * without emitting the tail. Idempotent.
+     */
+    abort(): void;
+    private teardownStream;
+}

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

@@ -0,0 +1,75 @@
+/**
+ * Cross-context canvas object logging — the global creation log for
+ * CanvasGradient / CanvasPattern / Path2D objects.
+ *
+ * Gradients, patterns, and Path2Ds are OPAQUE: their stops/segments cannot be
+ * read back after construction, so they can only be captured by observing the
+ * factory call live. They may also be created on one context (or no context —
+ * Konva builds gradients on a hidden dummy context) and used on another, so
+ * creation is logged GLOBALLY here, and each recorder lazily emits its own
+ * copy into whichever command stream first references the object
+ * (patch2d.ts serializeFactoryObject).
+ *
+ * ROOT-CAUSE GUARDRAIL (Phase 0.5 E2E, found on /2d-objects): app scene code
+ * typically constructs these objects ONCE at startup — often before the SDK's
+ * settings fetch + session start complete and startCanvasRecording() installs
+ * the full capture hooks. Anything created in that gap is permanently
+ * unserializable ({$:"unsupported"}). This module is therefore dependency-free
+ * and cheap so index.tsx can install it SYNCHRONOUSLY at startRecording()
+ * entry (Phase 1 critical interceptors) whenever canvas recording is opted
+ * in — long before any network roundtrip.
+ *
+ * SSR rule (veritas/jsts-frontend/CLAUDE.md): no window/document/navigator or
+ * canvas globals at module scope; all installation happens inside the
+ * exported install functions, each guarded with typeof checks.
+ */
+export interface ObjectLog {
+    /** context factory name, or '__path2d' */
+    factory: string;
+    args: unknown[];
+    calls: {
+        method: string;
+        args: unknown[];
+    }[];
+    /** A26: set once the per-object calls[] cap was hit; further calls are
+     * dropped so a long-lived/reused gradient or Path2D cannot leak unbounded. */
+    callsCapped?: boolean;
+}
+/** factory-created object -> its construction + method-call history */
+export declare const objectLogs: WeakMap<object, ObjectLog>;
+/**
+ * A26 — per-object recorded-calls cap. Gradients/patterns/Path2Ds are normally
+ * built with a handful of stops/segments at construction; a few apps, though,
+ * reuse one long-lived object and keep appending to it for the whole session
+ * (e.g. a Path2D that accumulates points), growing `calls[]` without bound and
+ * leaking memory. We cap the recorded history: the first MAX_OBJECT_CALLS calls
+ * are kept (covering every realistic construction), and anything beyond is
+ * dropped with a one-time marker. Replay of the common case is unaffected.
+ */
+export declare const MAX_OBJECT_CALLS = 4096;
+/** Append a method call to an object's log, honoring the per-object cap. */
+export declare function pushObjectCall(log: ObjectLog | undefined, method: string, args: unknown[]): void;
+export declare const OBJECT_FACTORIES: readonly ["createLinearGradient", "createRadialGradient", "createConicGradient", "createPattern"];
+export declare const PATH_OPS: readonly ["addPath", "arc", "arcTo", "bezierCurveTo", "closePath", "ellipse", "lineTo", "moveTo", "quadraticCurveTo", "rect", "roundRect"];
+/** The unwrapped Path2D constructor (set once Path2D logging installs). */
+export declare function getNativePath2D(): typeof Path2D | null;
+/**
+ * Wrap the gradient/pattern factory methods of one 2D-context prototype
+ * (CanvasRenderingContext2D on the main thread, OffscreenCanvasRendering-
+ * Context2D inside workers) so every created object lands in `objectLogs`.
+ * Idempotent per prototype.
+ */
+export declare function installFactoryLoggingOnProto(protoObj: object): void;
+/**
+ * Wrap the realm-global object types: CanvasGradient.addColorStop appends to
+ * the creating factory's log; Path2D construction + segment ops are logged
+ * per instance (replayed via __create '__path2d' + __objcall when a path is
+ * first used on a recorded context). Idempotent.
+ */
+export declare function installSharedObjectLogging(): void;
+/**
+ * Early hook for the SDK entry path: arm all object logging on the main
+ * thread BEFORE app scene code constructs its gradients/patterns/paths.
+ * Safe to call multiple times; no-ops outside a browser realm.
+ */
+export declare function installEarlyObjectLogging(): void;