@sailfish-ai/recorder 1.12.4 → 1.12.6

package/dist/recording.js

@@ -5,6 +5,7 @@ import { getCallerLocation, getCallerLocationFromTrace, } from "./sourceLocation
 import suppressConsoleLogsDuringCall from "./suppressConsoleLogsDuringCall";
 import { yieldToMain } from "./scheduler";
 import { buildMaskInputFn, makeMaskTextFn } from "./privacyMask";
+import { looksLikeCreditCard, looksLikeSsn, redactCreditCard, redactSsn, redactDob, } from "./canvas/piiDetect";
 // 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
@@ -27,7 +28,7 @@ const RRWEB_ALL_INPUT_TYPES = {
     select: true,
     password: true,
 };
-import { getCachedHrefNoQuery, initializeWebSocket, sendEvent } from "./websocket";
+import { getCachedHrefNoQuery, initializeWebSocket, isTransportSaturated, sendEvent, wsSendBinary, } from "./websocket";
 // Module-level reference to rrweb record, populated after dynamic import
 let _record = null;
 const MASK_CLASS = "sailfishSanitize";
@@ -92,20 +93,25 @@ export function maskInputFn(text, node) {
     // 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/,
-    };
+    //
+    // A13: the credit-card / SSN / DOB detectors and partial-mask formats now
+    // live in canvas/piiDetect so the canvas text path and this input masker
+    // share one implementation. Behavior here is unchanged: rrweb already chose
+    // to mask, so we always emit a masked value (the record* flags are NOT
+    // consulted here — they gate the canvas content-detection path, not rrweb's
+    // own masking decision). `looksLikeCreditCard` additionally Luhn-checks the
+    // candidate run, so a 16-digit non-card input now falls through to the
+    // explicit data-cc / autocomplete checks or the full-asterisk fallback.
     if (node.hasAttribute("data-cc") ||
         (node.getAttribute("autocomplete")?.startsWith("cc-") ?? false) ||
-        patterns.creditCard.test(text)) {
-        return "**** **** **** " + text.slice(-4);
+        looksLikeCreditCard(text)) {
+        return redactCreditCard(text);
     }
-    else if (node.hasAttribute("data-ssn") || patterns.ssn.test(text)) {
-        return "***-**-" + text.slice(-4);
+    else if (node.hasAttribute("data-ssn") || looksLikeSsn(text)) {
+        return redactSsn(text);
     }
     else if (node.hasAttribute("data-dob")) {
-        return "**/**/" + text.slice(-4);
+        return redactDob(text);
     }
     return "*".repeat(text.length);
 }
@@ -415,6 +421,12 @@ backendApi, apiKey, sessionId, envValue, deferRecordingStart = true, useWsWorker
                     blockSelector,
                     maskTextClass: captureSettings.maskTextClass ?? MASK_CLASS,
                     recordDOM: false, // after spread so it can't be overridden
+                    // rrweb's legacy webp-snapshot canvas path is ALWAYS off — the
+                    // Sailfish pixel recorder (gated by captureSettings.recordCanvas,
+                    // below) is the only canvas capture. Hardcoded false AFTER the spread
+                    // so the `recordCanvas` flag (which drives the Sailfish pipeline) can
+                    // never re-enable rrweb's own canvas snapshotting.
+                    recordCanvas: false,
                 });
                 const snapshotStartTime = Date.now();
                 const serializedDoc = await chunkedSnapshot(document, mirror, {
@@ -486,8 +498,105 @@ backendApi, apiKey, sessionId, envValue, deferRecordingStart = true, useWsWorker
                     maskTextSelector,
                     blockSelector,
                     maskTextClass: captureSettings.maskTextClass ?? MASK_CLASS,
+                    // rrweb's legacy webp-snapshot canvas path is ALWAYS off (after the
+                    // spread so a server `recordCanvas` flag can't re-enable it). The
+                    // Sailfish pixel recorder below is the only canvas capture.
+                    recordCanvas: false,
                 });
             }
+            // ── Sailfish canvas recording (SFCV pipeline) — opt-in ──────────────
+            // Dynamic import keeps the capture core out of the main bundle path.
+            if (captureSettings.recordCanvas) {
+                try {
+                    const { startCanvasRecording, stopCanvasRecording, flushAllCanvas, isCanvasRecordingActive, } = await import("./canvas/canvasManager");
+                    // Same deps object is reused for the initial start AND for re-arming
+                    // after a bfcache restore (A35), so settings/deps stay identical.
+                    const canvasDeps = {
+                        // A13: forward the full privacy framework into the canvas pipeline
+                        // so canvas masking honors the SAME selectors/flags as rrweb DOM
+                        // masking, plus the content-detection flags. (HIPAA is NOT a canvas
+                        // suppression signal — it routes PHI downstream; canvas still
+                        // records, devs use the mask/block selectors to exclude content.)
+                        settings: {
+                            maskCanvasClass: captureSettings.maskCanvasClass,
+                            maskTextClass: captureSettings.maskTextClass,
+                            maskTextSelector: captureSettings.maskTextSelector,
+                            blockSelector: captureSettings.blockSelector,
+                            unmaskSelector: captureSettings.unmaskSelector,
+                            // P1/masking-P2: global canvas text masking + redaction style.
+                            // maskCanvasText unset → mirror-DOM default (mask canvas text when DOM
+                            // text masking is configured). The backend setting is a NULLABLE
+                            // tri-state Boolean; `?? undefined` maps GraphQL null → unset so the
+                            // classifier's mirror-DOM default still applies, while preserving an
+                            // explicit `false` (opt-out) and `true` (force). canvasRedactStyle
+                            // defaults to asterisks + color.
+                            maskCanvasText: captureSettings.maskCanvasText ?? undefined,
+                            canvasRedactStyle: captureSettings.canvasRedactStyle,
+                            recordSsn: captureSettings.recordSsn,
+                            recordCreditCardInfo: captureSettings.recordCreditCardInfo,
+                            recordDob: captureSettings.recordDob,
+                            recordRealName: captureSettings.recordRealName,
+                            recordPassword: captureSettings.recordPassword,
+                        },
+                        mirror: record.mirror,
+                        addSailfishEvent: (payload) => {
+                            _record?.addSailfishEvent(EventType.SailfishCustom, {
+                                ...payload,
+                                tag: "sf-canvas",
+                            });
+                        },
+                        sendBinary: wsSendBinary,
+                        getContextIds: () => ({
+                            session_id: sessionId,
+                            page_visit_uuid: getUrlAndStoredUuids().page_visit_uuid,
+                        }),
+                        // A11 transport backpressure: pause canvas video frame production
+                        // while the WebSocket send buffer is saturated.
+                        isTransportSaturated,
+                    };
+                    startCanvasRecording(canvasDeps);
+                    // A23: NON-terminal flush on visibilitychange:"hidden". On mobile a
+                    // tab/app switch fires visibilitychange(hidden) and the OS may kill
+                    // the tab WITHOUT a reliable pagehide, losing the last ≤1s command
+                    // batch + encoder tail. Flush (but do NOT stop) so recording resumes
+                    // if the tab returns. Wrapped so it never throws into host-app code.
+                    const onVisibilityHidden = () => {
+                        try {
+                            if (document.visibilityState === "hidden") {
+                                void flushAllCanvas();
+                            }
+                        }
+                        catch {
+                            /* never break the host app */
+                        }
+                    };
+                    document.addEventListener("visibilitychange", onVisibilityHidden);
+                    // Recording ends with the page — flush batches, final keyframes,
+                    // op:"stop" events (stopCanvasRecording is idempotent). On bfcache
+                    // entry (pagehide persisted) this still stops; pageshow re-arms.
+                    window.addEventListener("pagehide", () => {
+                        void stopCanvasRecording();
+                    });
+                    // A35: re-arm on bfcache restore. When the page enters bfcache the
+                    // pagehide above stops canvas recording (terminal); without this the
+                    // canvas stays off for the rest of the restored page's life even
+                    // though the rest of the SDK keeps running. On pageshow(persisted),
+                    // restart via the SAME start path. Guard against double-start.
+                    window.addEventListener("pageshow", (event) => {
+                        try {
+                            if (event.persisted && !isCanvasRecordingActive()) {
+                                startCanvasRecording(canvasDeps);
+                            }
+                        }
+                        catch (rearmError) {
+                            console.warn("[Sailfish] canvas recording failed to re-arm after bfcache restore:", rearmError);
+                        }
+                    });
+                }
+                catch (canvasError) {
+                    console.warn("[Sailfish] canvas recording failed to start:", canvasError);
+                }
+            }
         };
         if (deferRecordingStart) {
             // Deterministic deferral: start heavy work only after page load completes,

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

@@ -0,0 +1,71 @@
+/**
+ * Phase 4 — framework semantic adapters (contract §9).
+ *
+ * Canvas pixels know WHERE a click landed (the pick buffer resolves that to a
+ * draw command / source line). Frameworks additionally know WHAT logical
+ * object the user clicked: a Konva "Upgrade CTA" shape, a Chart.js datapoint,
+ * a Three.js mesh. These adapters capture that semantic target on pointerdown
+ * and emit it as a `sf-canvas` op:"hit" index event:
+ *
+ *   {tag:"sf-canvas", op:"hit", canvasId, t, x, y,
+ *    target:{framework, label, objectType?, path?}}
+ *
+ * The SDK cannot import the customer's framework (three/konva/fabric/pixi/
+ * chart.js), so the customer (or a future build plugin) registers their live
+ * instance via the exported register* helpers below — each returns an
+ * unregister fn for component teardown. A window-global fallback covers
+ * script-tag (UMD) usage where the framework publishes a global.
+ *
+ * Every adapter callback is try/catch'd: a framework hiccup never breaks
+ * recording. SSR-safe: no window/document access at module scope.
+ */
+export interface SemanticTarget {
+    framework: "konva" | "fabric" | "chartjs" | "three" | "pixi";
+    /** human/logical label: Konva name|id, Chart "dataset[i]", three mesh name, ... */
+    label: string;
+    /** framework object type (Konva className, fabric type, chart type, ...) */
+    objectType?: string;
+    /** optional path/uuid for deeper identity */
+    path?: string;
+    /** [creation-site stamping — Layer A & B] build-time stamp id of the object's
+     *  creation site; resolves to file:line via the EXISTING stamp manifest.
+     *  Layer A stamps `new X()` sites; Layer B stamps object-PRODUCING calls
+     *  (`load`/`loadAsync`/`parse`/`parseAsync`/`clone`/`copy`) — the build rewrites
+     *  them to `__sfcreate(() => EXPR.method(args), id)`, whose helper calls
+     *  `globalThis.__sfCreateFrom(result, id)` so the produced object subtree is
+     *  marked with the producer's call-site id (see markSubtree below). */
+    createId?: string;
+    /** @deprecated Layer-B scaffolding field, no longer populated or read (build-time
+     *  marking replaced runtime stack capture). Retained only so player/payload types
+     *  that reference it do not break; SDK code never sets or reads it. */
+    createStack?: string[];
+    /** [Layer D — CAPTURE ONLY; backend resolve is phased] Chart.js datum position.
+     *  Today the chart instance's createId (its `new Chart(...)` site) resolves the
+     *  click; configRef is for a future dataset-definition resolver. */
+    configRef?: {
+        datasetIndex: number;
+        index?: number;
+    };
+}
+/** Konva: hit-test the stage's hit graph; label from node name()/id()/class. */
+export declare function registerKonvaStage(stage: unknown): () => void;
+/** Fabric: findTarget(ev) on the canvas; label from object name/id/type. */
+export declare function registerFabricCanvas(fabricCanvas: unknown): () => void;
+/** Chart.js: getElementsAtEventForMode -> "datasetLabel[index]". */
+export declare function registerChart(chart: unknown): () => void;
+/**
+ * Three.js: raycast on pointerdown. The customer passes their THREE namespace
+ * (the SDK must not bundle three) plus the scene/camera/renderer.
+ */
+export declare function registerThreeScene(scene: unknown, camera: unknown, renderer: unknown, three: unknown): () => void;
+/** PixiJS (v8): hit-test the event boundary; label from object label/name. */
+export declare function registerPixiApp(app: unknown): () => void;
+export interface AdapterDeps {
+    /** recorded canvas -> its canvasId (null if not recorded) */
+    canvasIdFor: (canvas: HTMLCanvasElement) => string | null;
+    /** emit a sf-canvas index event (tag added downstream) */
+    emitHit: (payload: Record<string, unknown>) => void;
+    now: () => number;
+}
+export declare function installAdapters(d: AdapterDeps): void;
+export declare function uninstallAdapters(): void;

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

@@ -0,0 +1,273 @@
+import { CommandEncoder } from "./codec";
+import { CanvasGovernor, type DemoteReason } from "./governor";
+import { KeyframeCapturer } from "./keyframes";
+import { type ContextRecorder } from "./patch2d";
+import { type GLRecorder } from "./patchGL";
+import { type GPURecorderHandle } from "./patchWebGPU";
+import { MediaRecorderCapture } from "./mediaRecorderCapture";
+import { VideoCapture } from "./videoCapture";
+import { type CanvasPrivacyMode, type RedactStyle } from "./canvasPrivacy";
+/** [audit B3] Decay a leaky-bucket byte counter by `elapsedMs` at a drain rate of
+ * `budget / windowMs` bytes/ms (never below 0). Exported for tests. */
+export declare function decayBytes(recentBytes: number, budget: number, windowMs: number, elapsedMs: number): number;
+/**
+ * A25 — global cap on simultaneously active hardware video encoders. Each
+ * video-mode canvas spins its own `VideoEncoder` (one codec session per
+ * encoder); a page with many heavy canvases can exhaust the OS's limited pool
+ * of codec sessions, after which every further `configure()` fails and ALL
+ * video capture silently dies. We cap the number of concurrent video-mode
+ * controllers PER SESSION: a canvas that would demote to video while the cap is
+ * reached stays on the KEYFRAME tier instead (degrade, don't fail). A slot frees
+ * when a video controller stops / tears down, and the next demotion can claim it.
+ */
+export declare const MAX_CONCURRENT_VIDEO_CANVASES = 4;
+/**
+ * A25 — the per-session pool of concurrent video-encoder slots. A fresh pool is
+ * created in each `startCanvasRecording` (so the cap is per-session, not global
+ * across the page's lifetime). `acquire` hands out at most `max` slots;
+ * `release` returns one and is idempotent at the boundaries (never drops below
+ * zero). The manager tracks per-controller ownership separately so a double
+ * teardown cannot over-release.
+ */
+export declare class VideoSlotPool {
+    private max;
+    private used;
+    constructor(max?: number);
+    /** @returns true if a slot was available and claimed. */
+    acquire(): boolean;
+    release(): void;
+    get inUse(): number;
+    get available(): number;
+}
+export interface CanvasRecorderSettings {
+    /** canvases matching `.${maskCanvasClass}`, `[data-sf-mask]`, or inside a
+     * masked subtree record NOTHING (default "sailfishSanitize") */
+    maskCanvasClass?: string;
+    /** rrweb maskTextClass — canvases under it REDACT drawn text (full mask) */
+    maskTextClass?: string;
+    /** rrweb maskTextSelector — canvases matching it REDACT drawn text */
+    maskTextSelector?: string;
+    /** rrweb blockSelector — canvases under it record NOTHING (suppress) */
+    blockSelector?: string;
+    /** rrweb unmaskSelector — OVERRIDE: forces normal recording (wins over block/mask) */
+    unmaskSelector?: string;
+    /**
+     * P1 — global 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 is configured, canvas text is masked too). See
+     * `CanvasPrivacySettings.maskCanvasText`.
+     */
+    maskCanvasText?: boolean;
+    /** P1 — global redaction style (text asterisks|bar, shape color|block|remove).
+     * Defaults to {text:"asterisks", shape:"color"}; per-call `maskCanvasDraws`
+     * options override it. */
+    canvasRedactStyle?: Partial<RedactStyle>;
+    recordSsn?: boolean;
+    recordCreditCardInfo?: boolean;
+    recordDob?: boolean;
+    recordRealName?: boolean;
+    recordPassword?: boolean;
+}
+export interface CanvasRecorderDeps {
+    settings: CanvasRecorderSettings;
+    /** rrweb mirror — canvasId is the mirror node id at start (contract §1) */
+    mirror: {
+        getId(node: Node): number;
+    };
+    /** emits an index event through the rrweb pipeline; the caller adds
+     * tag:"sf-canvas" + EventType.SailfishCustom (contract §2) */
+    addSailfishEvent: (payload: Record<string, unknown>) => void;
+    /** ships one SFCV frame (websocket wsSendBinary) */
+    sendBinary: (buf: ArrayBuffer) => void;
+    /** current session/page-visit identifiers for frame headers */
+    getContextIds: () => {
+        session_id?: string | null;
+        page_visit_uuid?: string | null;
+    };
+    /** A11 backpressure: true when the transport's send buffer is saturated, so
+     * video capture pauses producing frames until it drains. Optional — when
+     * absent (or omitted by the host wiring), frame production is never throttled. */
+    isTransportSaturated?: () => boolean;
+}
+type Mode = "commands" | "video" | "none";
+interface WorkerDoneMsg {
+    type: "sf-record-done";
+    batches: Uint8Array[];
+    chunks: {
+        tMs: number;
+        bytes: number;
+    }[];
+    cpuMs: number;
+    notes: string[];
+    assets: {
+        id: number;
+        kind: "image" | "imagedata";
+        t: number;
+        bytes: number;
+        w?: number;
+        h?: number;
+        bitmap?: ImageBitmap;
+        imageData?: ImageData;
+    }[];
+}
+interface Controller {
+    canvas: HTMLCanvasElement;
+    canvasId: string;
+    contextType: string;
+    mode: Mode;
+    /**
+     * A13 — privacy mode for this canvas. "normal" records as usual (with
+     * content-detection on drawn text); "redact" masks ALL drawn text AND
+     * suppresses pixel capture (keyframes/video) so rendered text never leaves
+     * the browser, and never demotes to video. ("suppress" canvases never get a
+     * controller — they are torn down / never built.) Carried on the controller
+     * so A6 re-eval can detect a privacy-mode TRANSITION mid-session.
+     */
+    privacyMode: CanvasPrivacyMode;
+    seq: number;
+    dirty: boolean;
+    everDirty: boolean;
+    pumpScheduled: boolean;
+    flushTimer: number | null;
+    stopped: boolean;
+    demoted: boolean;
+    /** A25: this controller currently holds one of the global video-encoder
+     * slots. Set when it acquires a slot (demotion / worker-video), cleared when
+     * the slot is released (teardown / stop / video-start failure). Makes slot
+     * release idempotent so a double teardown never under-counts the pool. */
+    hasVideoSlot: boolean;
+    /** A10: GPU context (WebGL/WebGPU) is currently lost — drop all capture until
+     * it is restored, so we never record garbage from a dead context. */
+    contextLost: boolean;
+    /** A40: a tainted (cross-origin) source was drawn — emit op:"taint" once. */
+    taintEmitted: boolean;
+    /** A24: last canvas dimensions emitted via op:"start"/op:"resize" — a change
+     * mid-session re-emits dims + DPR and forces a keyframe (command/keyframe
+     * mode) so the player learns the new size. */
+    lastW: number;
+    lastH: number;
+    /** A10: remove the webglcontextlost/restored (or device.lost) listeners on
+     * teardown. */
+    removeContextLossListeners: (() => void) | null;
+    governor: CanvasGovernor;
+    encoder: CommandEncoder | null;
+    batchStart: number;
+    flushChain: Promise<void>;
+    keyframes: KeyframeCapturer | null;
+    video: VideoCapture | null;
+    /** A41: MediaRecorder fallback capture (Safari < 26: MediaRecorder present,
+     * WebCodecs absent). Mutually exclusive with `video` — a video-mode canvas
+     * uses exactly one encoder backend. */
+    mediaRecorder: MediaRecorderCapture | null;
+    recorder2d: ContextRecorder | null;
+    recorderGL: GLRecorder | null;
+    recorderGPU: GPURecorderHandle | null;
+    worker: Worker | null;
+    workerDone: Promise<WorkerDoneMsg> | null;
+    removeWorkerListener: (() => void) | null;
+    /**
+     * maskCanvasDraws: set once the app has wrapped any draw in `maskCanvasDraws`.
+     * Pixel capture (keyframes + video) is torn down because those masked draws
+     * painted real pixels; replay falls back to the sanitized command stream.
+     */
+    pixelSuppressed: boolean;
+}
+/**
+ * A13 — project the recorder settings onto the classifier's privacy-settings
+ * shape. Empty-string selectors (the backend's "rule disabled" sentinel) are
+ * coerced to undefined so closestSafe/matchesSelectorSafe treat them as "no
+ * rule" rather than matching the empty selector.
+ */
+/**
+ * [audit B7] Return the NAMES of configured privacy selectors that are malformed
+ * (throw in `document.querySelector`). The matchers (closestSafe/
+ * matchesSelectorSafe) fail SAFE — a selector that throws in `el.matches()`/
+ * `el.closest()` simply doesn't match, so a typo in a block/mask/unmask selector
+ * silently DISABLES that rule (under-masking) with no signal. Surfacing the bad
+ * selector names in the recorder notes warns the operator without changing the
+ * fail-safe runtime behavior. SSR-guarded (no document on the server → []).
+ * Pure + exported so it's testable without the module's session state.
+ */
+export declare function collectMalformedSelectors(settings: CanvasRecorderSettings): string[];
+export declare function startCanvasRecording(deps: CanvasRecorderDeps): void;
+/** [audit C1] Await a settle() but never longer than `ms`, and never reject — a
+ * stuck/failed final encode must not hang or abort the rest of teardown. A late
+ * asset that resolves after the timeout still ships best-effort (or is dropped by
+ * sendFrame's `!state` guard once the session is fully gone). */
+export declare function settleOrTimeout(p: Promise<void>, ms: number): Promise<unknown>;
+/** Flush + final keyframes + op:"stop" per canvas; idempotent. Prototype
+ * patches stay installed but inert (contract §5). */
+export declare function stopCanvasRecording(): Promise<void>;
+/**
+ * A23: NON-terminal flush — flush every controller's pending command batch
+ * (the same flush the BATCH_MS timer / flushBatch does) and request each active
+ * video encoder to drain its queued frames. Recording stays armed and resumes
+ * normally if the page returns.
+ *
+ * Wired to visibilitychange:"hidden": on mobile a tab/app switch fires
+ * visibilitychange(hidden) and the OS may kill the tab WITHOUT a reliable
+ * pagehide, losing the last ≤1s command batch and the encoder tail. This pushes
+ * that data out while the page is still alive. Idempotent and safe to call
+ * repeatedly; a no-op when recording is inactive.
+ */
+export declare function flushAllCanvas(): Promise<void>;
+/** Test/diagnostic hook. */
+export declare function isCanvasRecordingActive(): boolean;
+/**
+ * A25 — test-only hooks for the concurrent-video-encoder cap. Exposes the real
+ * `demote` decision path and slot accounting so a unit test can drive N+1
+ * demotions deterministically WITHOUT spawning hardware encoders (the test
+ * stubs `VideoCapture`). NOT part of the public SDK surface — tree-shaken from
+ * production bundles since nothing in the app imports it. Each helper is a thin
+ * wrapper over the same internal functions the live discovery path uses, so the
+ * test exercises production behavior, not a parallel reimplementation.
+ */
+export declare const __canvasManagerTestHooks: {
+    /** Spin up a minimal session state (no DOM scan / hooks) for slot testing. */
+    initState(deps: CanvasRecorderDeps): void;
+    /** Register a synthetic command-mode 2D controller (no recorder/keyframes). */
+    addController(canvas: HTMLCanvasElement, canvasId: string, privacyMode?: CanvasPrivacyMode): Controller;
+    /** Classify a canvas against the current session's privacy settings. */
+    classify(canvas: HTMLCanvasElement): CanvasPrivacyMode;
+    /** Build the text redactor a controller in `mode` would install. */
+    makeTextRedactor(mode: CanvasPrivacyMode): ((text: string) => string) | undefined;
+    /** Run the real A6/A13 privacy re-evaluation pass. */
+    reevaluate(): void;
+    /** Escalation decision for pixel-text contexts (GL/GPU/worker). */
+    escalate(mode: CanvasPrivacyMode, contextType: string): CanvasPrivacyMode;
+    /** Whether a canvas is currently tracked by a controller. */
+    isTracked(canvas: HTMLCanvasElement): boolean;
+    /** Whether a canvas is in the suppressed (re-arm candidate) set. */
+    isSuppressed(canvas: HTMLCanvasElement): boolean;
+    /** Mark a canvas suppressed (as the discovery path would). */
+    markSuppressed(canvas: HTMLCanvasElement): void;
+    /** Read a controller's current privacy mode + whether keyframes are armed. */
+    controllerPrivacy(ctl: Controller): {
+        mode: CanvasPrivacyMode;
+        hasKeyframes: boolean;
+    };
+    /** Run the real maybeDemote path (respects the redact no-demote rule). */
+    tryDemote(ctl: Controller): void;
+    /** Run the real maybeEmitResize on a controller — drives the B1 resize +
+     * keyframeUnsafe leak path (suppress-before-keyframe ordering). */
+    emitResize(ctl: Controller): void;
+    /**
+     * Drive the REAL build2DController with a fake pre-attached recorder so the
+     * keyframe-suppression + redactor-installation behavior can be asserted
+     * without a live 2D context (jsdom has none). Returns the built controller
+     * plus the redactor the recorder received.
+     */
+    build2DWithFakeRecorder(canvas: HTMLCanvasElement, canvasId: string, privacyMode: CanvasPrivacyMode): {
+        ctl: Controller | undefined;
+        redactor: ((t: string) => string) | undefined;
+    };
+    /** Run the real governor-demotion path on a controller. */
+    demote(ctl: Controller, reason?: DemoteReason): void;
+    /** Run the real (non-flushing) teardown, which frees the controller's slot. */
+    teardown(ctl: Controller): void;
+    /** Current per-session slot usage. */
+    slotsInUse(): number;
+    controllerHasSlot(ctl: Controller): boolean;
+    reset(): void;
+};
+export {};