@sailfish-ai/recorder 1.12.4 → 1.12.6

package/dist/canvas/canvasManager.js

@@ -0,0 +1,1949 @@
+/**
+ * Production canvas-recording controller (contract §5) — the SDK-side
+ * orchestrator over the ported bench capture core. NO driver loop: draw-call
+ * hooks set a per-canvas dirty flag and a queueMicrotask pump runs keyframe /
+ * video capture IN THE SAME TASK as the render (guardrail #6 — microtasks run
+ * before the task ends, so WebGPU textures and pdb:false WebGL buffers are
+ * still readable).
+ *
+ * Mode routing per canvas (bench commandCore lineage):
+ *   2d / webgl(2) / webgpu       -> commands + pixel keyframes (hybrid)
+ *   worker + canvas-worker shim  -> worker command relay
+ *   worker without shim          -> video capture of the placeholder
+ *   governor demotion            -> video capture (commands recorder kept
+ *                                   attached with a DiscardSink for dirtiness)
+ *   no WebCodecs                 -> keyframes-only
+ *
+ * All heavy bytes leave as SFCV binary frames via deps.sendBinary; index
+ * events (start/mode/stop/masked) ride the existing rrweb event pipeline via
+ * deps.addSailfishEvent (contract §2).
+ *
+ * SSR rule: no window/document/navigator access at module scope; everything
+ * installs inside startCanvasRecording().
+ */
+import { installAdapters, uninstallAdapters } from "./adapters";
+import { CommandEncoder, deflate } from "./codec";
+import { encodeBitmap, terminateImgEncoder } from "./encodeWorker";
+import { CanvasGovernor } from "./governor";
+import { KeyframeCapturer } from "./keyframes";
+import { attachRecorder, attachRecorderToContext, detachRecorderFromContext, getContextInfo, installCommandHooks, noteCtxPendingSiteId, pruneUnboundRecorders, releaseAutoRecorder, setAutoAttach, setContextCreatedNotifier, setUntracked2DContextNotifier, wasPreAttachMaskUsed, } from "./patch2d";
+import { attachGLRecorder, attachGLRecorderToContext, detachGLRecorderFromContext, installGLHooks, noteGLPendingSiteId, pruneUnboundGLRecorders, setGLAutoAttach, setUntrackedGLContextNotifier, } from "./patchGL";
+import { attachGPURecorder, installGPUHooks, pruneUnboundGPURecorders, setGPUAutoAttach, setGPUDeviceLostNotifier, swapGPUSink, } from "./patchWebGPU";
+import { BufferSink, DiscardSink, buildFrame, bytesToBase64, } from "./protocol";
+import { MediaRecorderCapture } from "./mediaRecorderCapture";
+import { VideoCapture } from "./videoCapture";
+import { getWorkerForCanvas, installWorkerRelay, pingWorkerShim, setWorkerAssociationNotifier, } from "./workerRelay";
+import { classifyCanvasPrivacy, DEFAULT_REDACT_STYLE, redactCanvasText, resolveRedactStyle, suppressReason, } from "./canvasPrivacy";
+import { resolveDeviceBudgets } from "./deviceClass";
+const DEFAULT_MASK_CLASS = "sailfishSanitize";
+/** backend rejects frames > 8 MiB (contract §3) — drop SDK-side */
+const MAX_FRAME_BYTES = 8 * 1024 * 1024;
+/** A30: SDK-side per-session canvas byte budget is now device-class scaled (see
+ * `resolveDeviceBudgets` → `state.budgets.sessionByteBudget`; desktop = 256 MiB,
+ * mobile = 96 MiB, low-end = 48 MiB). The backend backstop is 512 MiB. */
+/** [audit B3] The byte budget is enforced as a LEAKY BUCKET over this window
+ * rather than a lifetime total: `state.totalBytes` decays toward 0 at
+ * `sessionByteBudget / BUDGET_WINDOW_MS` bytes/ms, so it tracks RECENT upload
+ * volume. A burst that trips the budget pauses sending, but a subsequent quiet
+ * period drains it back under budget and capture RESUMES automatically — vs the
+ * old permanent latch that killed ALL canvas for the rest of the session after a
+ * single front-loaded burst. Bounds sustained cost while tolerating bursts. */
+const BUDGET_WINDOW_MS = 60_000;
+/** [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 function decayBytes(recentBytes, budget, windowMs, elapsedMs) {
+    if (elapsedMs <= 0 || budget <= 0 || windowMs <= 0)
+        return Math.max(0, recentBytes);
+    return Math.max(0, recentBytes - elapsedMs * (budget / windowMs));
+}
+/** command batch flush cadence (bench pattern) */
+const BATCH_MS = 1_000;
+/**
+ * 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 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 class VideoSlotPool {
+    max;
+    used = 0;
+    constructor(max = MAX_CONCURRENT_VIDEO_CANVASES) {
+        this.max = max;
+    }
+    /** @returns true if a slot was available and claimed. */
+    acquire() {
+        if (this.used >= this.max)
+            return false;
+        this.used++;
+        return true;
+    }
+    release() {
+        if (this.used > 0)
+            this.used--;
+    }
+    get inUse() {
+        return this.used;
+    }
+    get available() {
+        return this.max - this.used;
+    }
+}
+let state = null;
+/**
+ * A5 — canvas↔event clock alignment (VERIFIED, no runtime change needed).
+ *
+ * Canvas SFCV frame `tMs` is raw `Date.now()` (this `now`). The question was
+ * whether that aligns with the timeline the player reconstructs from the rrweb
+ * event stream — specifically `getMetaData().startTime`, which the player
+ * derives from `events[0].timestamp`.
+ *
+ * Traced through the recorder: every rrweb event's `timestamp` is OVERWRITTEN
+ * at emit time by rrweb's `wrapEvent`/emit (`@sailfish-rrweb/rrweb-record-only`,
+ * `R.timestamp = Bt()` where `let Bt = Date.now`). Our own SailfishCustom canvas
+ * index events (`op:"start"`/`mode`/`masked`/`stop`/`taint`) go through that
+ * same emit path, and the surrounding DOM/snapshot/perf/console events in
+ * recording.tsx all stamp `timestamp: Date.now()` too. So the player's
+ * `startTime` is in raw client `Date.now()` epoch-ms — the SAME clock and the
+ * SAME `Date.now()` source as canvas `tMs`.
+ *
+ * The `serverEstimated`/`clockSync` envelope is an ADDITIVE per-event field used
+ * for cross-device server-side ordering; it never replaces `timestamp`, and the
+ * player's canvas/DOM alignment math uses `timestamp`. Therefore canvas frames
+ * and DOM replay share one monotonic-enough wall clock and align without a frame
+ * header change. (If the player ever switches to anchoring on `serverEstimated`,
+ * the SFCV header would need `mono`+`off` so it can re-derive — flagged, not
+ * needed today.) See tests/canvasClockAlignment.test.ts for the guard.
+ */
+const now = () => Date.now();
+const encodeImage = (b) => encodeBitmap(b, 0.85, true);
+function noteOnce(m) {
+    if (!state || state.notes.has(m))
+        return;
+    state.notes.add(m);
+    try {
+        // eslint-disable-next-line no-console
+        console.debug?.("[Sailfish][canvas]", m);
+    }
+    catch { /* never break capture */ }
+}
+function emitEvent(payload) {
+    if (!state)
+        return;
+    try {
+        state.deps.addSailfishEvent(payload);
+    }
+    catch { /* never break the host app */ }
+}
+// ─── Frame emission ──────────────────────────────────────────────────────────
+function sendFrame(ctl, kind, meta, payload, 
+// BUGFIX (Phase 0.5 E2E, found on /charts): callers whose payload is
+// produced ASYNCHRONOUSLY after capture (keyframes: createImageBitmap +
+// worker webp encode, ~30ms) must pass the CAPTURE-time timestamp.
+// Stamping Date.now() at send time made the player anchor keyframe pixels
+// ~30ms late, silently dropping every op recorded in that window when
+// replay resumed from the keyframe (interaction redraws were lost).
+tMs = Date.now()) {
+    const s = state;
+    if (!s)
+        return;
+    const payloadLen = payload == null ? 0 : payload.byteLength;
+    if (payloadLen > MAX_FRAME_BYTES) {
+        noteOnce(`oversize ${kind} frame dropped (${payloadLen}B > 8MiB)`);
+        return;
+    }
+    // [audit B3] Leaky-bucket byte budget. Decay the recent-bytes counter, then gate
+    // this frame. Over budget → DROP it (and pause), but keep decaying every call so
+    // a quiet period drains the bucket and sending RESUMES automatically — no
+    // permanent session-wide kill. (Decay runs even while paused because the capture
+    // pump keeps calling sendFrame; dropped frames don't accrue bytes.)
+    const budget = s.budgets.sessionByteBudget;
+    if (s.lastBudgetTickMs > 0) {
+        s.totalBytes = decayBytes(s.totalBytes, budget, BUDGET_WINDOW_MS, tMs - s.lastBudgetTickMs);
+    }
+    // [audit B3-followup] Never let the tick REGRESS. A keyframe's sendFrame carries
+    // its capture-instant `tMs` but emits AFTER an async encode, so it can land with
+    // an older tMs than a command/video frame that already advanced the tick. A bare
+    // assignment would move the tick backwards, and the NEXT frame would then see an
+    // inflated elapsed and over-drain the bucket (weakening the cap). Monotonic max
+    // keeps decay honest; the older frame itself already decayed by ≤0 (no-op).
+    s.lastBudgetTickMs = Math.max(s.lastBudgetTickMs, tMs);
+    if (s.totalBytes > budget) {
+        if (!s.budgetExceeded) {
+            s.budgetExceeded = true;
+            noteOnce("per-session canvas byte budget exceeded — capture paused (auto-resumes as it drains)");
+        }
+        return;
+    }
+    if (s.budgetExceeded)
+        s.budgetExceeded = false; // drained back under budget → resume
+    const ids = s.deps.getContextIds();
+    const buf = buildFrame({
+        v: 1,
+        kind,
+        sessionId: ids.session_id ?? "",
+        pageVisitUuid: ids.page_visit_uuid ?? "",
+        canvasId: ctl.canvasId,
+        seq: ctl.seq++,
+        tMs,
+        meta,
+    }, payload);
+    try {
+        s.deps.sendBinary(buf);
+    }
+    catch {
+        return;
+    }
+    // [audit B3] Accrue into the leaky bucket. The gate above already decayed it and
+    // confirmed we were under budget; this frame's bytes may push it over, which
+    // pauses the NEXT frame until the bucket drains — transient backpressure, not a
+    // permanent stop.
+    s.totalBytes += buf.byteLength;
+}
+// ─── Same-task pump (guardrail #6) ───────────────────────────────────────────
+function markDirty(ctl) {
+    ctl.dirty = true;
+    ctl.everDirty = true;
+    if (!ctl.pumpScheduled) {
+        ctl.pumpScheduled = true;
+        queueMicrotask(() => pumpCanvas(ctl));
+    }
+}
+function pumpCanvas(ctl) {
+    ctl.pumpScheduled = false;
+    if (!state || ctl.stopped || !ctl.dirty)
+        return;
+    // A10: while the GPU context is lost, the canvas pixels are blank/garbage and
+    // the command stream references dead resources — capture nothing until it is
+    // restored.
+    if (ctl.contextLost) {
+        ctl.dirty = false;
+        return;
+    }
+    ctl.dirty = false;
+    const t = now();
+    // A24: detect a mid-session resize same-task with the render. For command/
+    // keyframe mode this emits a `resize` index event + forces a keyframe; for
+    // video mode VideoCapture.afterRender drives its own encoder restart, so we
+    // only keep lastW/lastH in sync here (no resize event for video).
+    maybeEmitResize(ctl, t);
+    // maskCanvasDraws / redact text: the app masked a draw. In command mode the
+    // keyframe capturer region-blanks the masked bboxes (recorder.maskedRegions),
+    // so keyframes are KEPT and pixel-perfect outside the masked regions — no
+    // teardown. Only a canvas already DEMOTED to video needs hard suppression here:
+    // video frames can't be cheaply region-blanked, and its command stream is a
+    // DiscardSink (no safe fallback). (A command-mode masked canvas never demotes —
+    // maybeDemote vetoes hasMaskedDraws.)
+    // [audit C-NEW-1] A masked op could not be region-bounded (degenerate
+    // transform / ctx.fill(path2d) / zero-area paint) — its pixels can't be safely
+    // blanked, so suppress pixel keyframes entirely (command-only replay) rather
+    // than leak them or blank the whole canvas.
+    if (ctl.recorder2d?.keyframeUnsafe && !ctl.pixelSuppressed) {
+        suppressPixelCapture(ctl);
+    }
+    if (ctl.recorder2d?.hasMaskedDraws && !ctl.pixelSuppressed && ctl.mode === "video") {
+        suppressPixelCapture(ctl);
+    }
+    if (ctl.mode === "video") {
+        // A41: a MediaRecorder-backed video controller self-paces from the
+        // captureStream track, so its afterRender is a no-op; a WebCodecs controller
+        // grabs a frame here. Exactly one backend is set.
+        ctl.video?.afterRender(t);
+        ctl.mediaRecorder?.afterRender(t);
+    }
+    else {
+        ctl.keyframes?.afterRender(t);
+    }
+    maybeDemote(ctl);
+}
+/**
+ * maskCanvasDraws — tear down pixel capture for a canvas whose recorder reported
+ * masked draws. Keyframes/video would otherwise capture the (real, painted)
+ * pixels of the sanitized region. The sanitized command stream remains the
+ * replay source; for a vector 2D canvas this is loss-free. One-shot.
+ */
+function suppressPixelCapture(ctl) {
+    ctl.pixelSuppressed = true;
+    ctl.keyframes = null;
+    if (ctl.video) {
+        void ctl.video.stop();
+        ctl.video = null;
+        releaseVideoSlot(ctl);
+    }
+    if (ctl.mediaRecorder) {
+        try {
+            void ctl.mediaRecorder.stop();
+        }
+        catch { /* already gone */ }
+        ctl.mediaRecorder = null;
+    }
+    if (ctl.mode === "video") {
+        // Rare: a canvas already demoted to video before the first maskCanvasDraws.
+        // Its command recorder is a DiscardSink, so there is no safe command stream
+        // to fall back to — stop capturing rather than risk leaking masked pixels.
+        ctl.mode = "none";
+        emitEvent({ op: "mode", canvasId: ctl.canvasId, mode: "none", reason: "maskCanvasDraws-pixel-suppressed" });
+    }
+    noteOnce("maskCanvasDraws used — pixel capture (keyframes/video) suppressed; sanitized command-only replay");
+}
+// ─── Command pipeline ────────────────────────────────────────────────────────
+function flushBatch(ctl, t) {
+    if (!ctl.encoder || ctl.encoder.ops === 0)
+        return;
+    const raw = ctl.encoder.takeBatch();
+    const z = deflate(raw);
+    // chain emission so command frames keep batch order even if deflates
+    // resolve out of order (seq is assigned at emission time)
+    ctl.flushChain = ctl.flushChain
+        .then(async () => {
+        const bytes = await z;
+        ctl.governor.addBytes(bytes.length);
+        sendFrame(ctl, "commands", { codec: "sfc-bin-1", compression: "deflate" }, bytes);
+        maybeDemote(ctl);
+    })
+        .catch(() => { });
+    void t;
+}
+function makeCommandSink(ctl) {
+    return {
+        onOp(op) {
+            // A10: drop ops issued while the GPU context is lost — they reference
+            // dead resources and would corrupt the command stream.
+            if (ctl.contextLost)
+                return;
+            ctl.encoder.encode(op);
+            ctl.governor.addOp(op.t);
+            if (ctl.batchStart === 0)
+                ctl.batchStart = op.t;
+            if (op.t - ctl.batchStart >= BATCH_MS) {
+                flushBatch(ctl, op.t);
+                ctl.batchStart = op.t;
+            }
+            else if (ctl.flushTimer === null) {
+                // BUGFIX (Phase 0.5 E2E, found on /idle): batches flushed only when a
+                // LATER op crossed the 1s boundary — a canvas that draws sparsely
+                // (one repaint per click, then silence) kept its final ops in the
+                // encoder forever and replay never saw the last interaction. A timer
+                // backstop flushes pending ops even when no further draw arrives.
+                ctl.flushTimer = setTimeout(() => {
+                    ctl.flushTimer = null;
+                    if (!ctl.stopped) {
+                        flushBatch(ctl, now());
+                        ctl.batchStart = 0;
+                    }
+                }, BATCH_MS + 100);
+            }
+            markDirty(ctl);
+        },
+        onAssetBytes() { },
+        onAssetData(info, payload) {
+            sendFrame(ctl, "asset", { assetId: info.id, format: info.format, w: info.w, h: info.h }, payload);
+        },
+        onVideoSource() {
+            ctl.governor.addVideoDraw();
+        },
+        onTaint(t) { emitTaint(ctl, t); },
+        note(m) { noteOnce(m); },
+    };
+}
+// ─── A40: structured tainted-asset marker ────────────────────────────────────
+/**
+ * A cross-origin/tainted image source was drawn and could not be read back, so
+ * its pixels never reach the player. Emit a per-canvas index event (deduped to
+ * at most once per canvas) so the player can render a placeholder instead of a
+ * silent blank. Mirrors the op:"masked" emission path. The `t` is the capture
+ * timestamp (same clock as every other op for this canvas).
+ */
+function emitTaint(ctl, t) {
+    if (ctl.taintEmitted)
+        return;
+    ctl.taintEmitted = true;
+    emitEvent({ op: "taint", canvasId: ctl.canvasId, t });
+}
+// ─── Governor demotion (Phase 2, contract §5) ────────────────────────────────
+function maybeDemote(ctl) {
+    if (ctl.mode !== "commands" || ctl.demoted || ctl.stopped || ctl.worker)
+        return;
+    // A13: a "redact" canvas must NEVER demote to video — video capture would
+    // ship the rendered (un-redacted) text PIXELS. Stay command-only forever; the
+    // text-redacted command stream is the only safe representation.
+    if (ctl.privacyMode === "redact")
+        return;
+    // maskCanvasDraws: a canvas with masked draws must stay command-only — video
+    // would capture the masked pixels. (pixelSuppressed is set the same frame.)
+    if (ctl.recorder2d?.hasMaskedDraws)
+        return;
+    const reason = ctl.governor.shouldDemote();
+    if (reason)
+        demote(ctl, reason);
+}
+function demote(ctl, reason) {
+    ctl.demoted = true;
+    flushBatch(ctl, now());
+    // Bridge the demotion gap (Phase 0.5 E2E, found on /2d-stress): the video
+    // encoder takes hundreds of ms to produce its first keyframe, leaving a
+    // replay hole between the last command batch and the first video frame.
+    // A keyframe at the boundary anchors it. demote() runs from the render
+    // pump or the flush chain — 2D buffers persist across tasks, and 2D is the
+    // only kind the byte/ops governor demotes in practice (GL/GPU default to
+    // keyframe pacing already).
+    ctl.keyframes?.takeKeyframe(now());
+    // Detach the command stream but keep the patch recorder attached with a
+    // DiscardSink: ops are dropped before serialization (zero encode cost) and
+    // only drive the dirty flag that paces video/keyframe capture.
+    const discard = new DiscardSink(() => markDirty(ctl));
+    if (ctl.recorder2d)
+        ctl.recorder2d.swapSink(discard);
+    if (ctl.recorderGL)
+        ctl.recorderGL.swapSink(discard);
+    if (ctl.recorderGPU)
+        swapGPUSink(discard);
+    // A30: on iOS-Safari WebCodecs is unreliable/absent — when the device profile
+    // prefers it, try the MediaRecorder backend (A41) FIRST and only fall through
+    // to the WebCodecs path if MediaRecorder can't start.
+    if (state?.budgets.preferMediaRecorder && tryStartMediaRecorder(ctl, reason)) {
+        return;
+    }
+    if (VideoCapture.supported()) {
+        // A25: only demote to a hardware encoder if a global slot is free. When the
+        // concurrent-encoder cap is reached, stay on the KEYFRAME tier (degrade,
+        // don't fail) — the command stream is already detached (DiscardSink above)
+        // and keyframes keep replay alive without consuming a codec session.
+        if (!tryAcquireVideoSlot(ctl)) {
+            ctl.mode = "none";
+            noteOnce(`video-encoder cap (${state?.budgets.maxConcurrentVideo ?? MAX_CONCURRENT_VIDEO_CANVASES}) reached — canvas kept on keyframes`);
+            emitEvent({
+                op: "mode",
+                canvasId: ctl.canvasId,
+                mode: "none",
+                reason: `${reason} (video-encoder cap reached — keyframes only)`,
+            });
+            return;
+        }
+        ctl.mode = "video";
+        emitEvent({ op: "mode", canvasId: ctl.canvasId, mode: "video", reason });
+        const video = makeVideo(ctl, false);
+        ctl.video = video;
+        void video.start().then((ok) => {
+            if (!ok && !ctl.stopped) {
+                ctl.video = null;
+                releaseVideoSlot(ctl); // A25: hand the slot back on start failure
+                ctl.mode = "none"; // keyframes-only fallback
+                emitEvent({ op: "mode", canvasId: ctl.canvasId, mode: "none", reason: "video-start-failed" });
+            }
+        });
+    }
+    else if (tryStartMediaRecorder(ctl, reason)) {
+        // A41: No WebCodecs but MediaRecorder + captureStream are available
+        // (Safari < 26) — capture via MediaRecorder instead of keyframe-only.
+        // tryStartMediaRecorder set mode/video index event + acquired the slot.
+    }
+    else {
+        // No WebCodecs and no usable MediaRecorder (or the cap is reached):
+        // keyframes-only mode.
+        ctl.mode = "none";
+        emitEvent({ op: "mode", canvasId: ctl.canvasId, mode: "none", reason: `${reason} (no WebCodecs — keyframes only)` });
+    }
+}
+// ─── Capture builders ────────────────────────────────────────────────────────
+function makeKeyframes(ctl) {
+    return new KeyframeCapturer(ctl.canvas, () => (ctl.recorder2d && !ctl.demoted ? ctl.recorder2d.snapshotState() : null), 
+    // kf.tMs (capture instant) — NOT send time; see sendFrame's tMs note.
+    (kf) => sendFrame(ctl, "keyframe", { format: "webp", w: kf.w, h: kf.h, state: kf.state }, kf.bytes, kf.tMs), noteOnce, 
+    // Region-blank source: the 2D recorder's accumulated masked-content bboxes
+    // (maskCanvasDraws / redact-mode text). Empty for GL/GPU (no per-op masking).
+    () => ctl.recorder2d?.maskedRegions ?? []);
+}
+/**
+ * A27 — if this canvas pre-existed the SDK (present at the initial sweep), take
+ * a single ground-truth keyframe of its already-painted pixels so static
+ * content has an initial anchor even if the canvas never redraws. Consumes the
+ * preExisting marker so a re-tracked canvas (e.g. after context-loss reattach)
+ * does not re-shoot it. No-op for canvases discovered after the sweep, for
+ * controllers with no keyframe capturer (video/none/worker), when the canvas
+ * has a zero-size / unreadable context, or when pre-attach masking occurred (the
+ * shot could leak un-blanked masked pixels — A27 safety). Never throws.
+ */
+function maybeInitialKeyframe(ctl) {
+    const s = state;
+    if (!s || !ctl.keyframes)
+        return;
+    if (wasPreAttachMaskUsed(ctl.canvas))
+        return; // could leak pre-attach masked pixels [audit A27/H2]
+    if (!s.preExisting.has(ctl.canvas))
+        return;
+    s.preExisting.delete(ctl.canvas);
+    try {
+        ctl.keyframes.initialKeyframe(now());
+    }
+    catch { /* never break the host app */ }
+}
+/**
+ * A25 — try to claim one of the global video-encoder slots for this controller.
+ * Returns true and marks the controller if a slot was free; false (leaving the
+ * controller on the keyframe tier) when the per-session cap is reached.
+ * Idempotent for an already-holding controller (re-claim is a no-op true).
+ */
+function tryAcquireVideoSlot(ctl) {
+    const s = state;
+    if (!s)
+        return false;
+    if (ctl.hasVideoSlot)
+        return true;
+    if (!s.videoSlots.acquire())
+        return false;
+    ctl.hasVideoSlot = true;
+    return true;
+}
+/** A25 — release this controller's video slot back to the pool. Idempotent:
+ * only releases when the controller actually held a slot, so a teardown after
+ * a stop (or a double teardown) never under-counts the pool. */
+function releaseVideoSlot(ctl) {
+    if (!ctl.hasVideoSlot)
+        return;
+    ctl.hasVideoSlot = false;
+    state?.videoSlots.release();
+}
+function makeVideo(ctl, intervalPaced) {
+    return new VideoCapture(ctl.canvas, now, {
+        onInit: (codec, description) => sendFrame(ctl, "video-init", { codec, description: description ? bytesToBase64(description) : null }, null),
+        onChunk: (key, timestampUs, data) => sendFrame(ctl, "video-chunk", { key, timestampUs }, data),
+        note: noteOnce,
+        // A11: pause frame production while the transport buffer is saturated.
+        isTransportSaturated: state?.deps.isTransportSaturated
+            ? () => !!state?.deps.isTransportSaturated?.()
+            : undefined,
+    }, { intervalPaced });
+}
+/**
+ * A41 — build a MediaRecorder fallback capturer wired to the SFCV frame
+ * pipeline. The init frame carries `codec:"mediarecorder"` + the recorder's
+ * negotiated `mimeType` (no binary payload); each chunk frame carries
+ * `codec:"mediarecorder"` + a monotonic `seq` with one MediaRecorder Blob's
+ * bytes as payload (first webm chunk holds the init segment — order preserved
+ * by the capturer's emission chain). Matches the player-side contract exactly.
+ */
+function makeMediaRecorder(ctl) {
+    return new MediaRecorderCapture(ctl.canvas, {
+        onInit: (mimeType, w, h) => sendFrame(ctl, "video-init", { codec: "mediarecorder", mimeType, w, h }, null),
+        onChunk: (seq, data) => sendFrame(ctl, "video-chunk", { codec: "mediarecorder", seq }, data),
+        note: noteOnce,
+    });
+}
+/**
+ * A41 — try to start MediaRecorder fallback video for a controller that would
+ * otherwise degrade to keyframe-only (WebCodecs absent). Acquires an A25 video
+ * slot first (MediaRecorder is a real encoder backend too). Returns true if the
+ * recorder started; false leaves the controller untouched for the caller to
+ * fall back to keyframe-only. Emits the op:"mode" video index event on success.
+ */
+function tryStartMediaRecorder(ctl, reason) {
+    if (!MediaRecorderCapture.supported())
+        return false;
+    if (!tryAcquireVideoSlot(ctl)) {
+        noteOnce(`video-encoder cap (${state?.budgets.maxConcurrentVideo ?? MAX_CONCURRENT_VIDEO_CANVASES}) reached — canvas kept on keyframes`);
+        return false;
+    }
+    const mr = makeMediaRecorder(ctl);
+    ctl.mediaRecorder = mr;
+    ctl.mode = "video";
+    emitEvent({ op: "mode", canvasId: ctl.canvasId, mode: "video", reason: `${reason} (MediaRecorder fallback)` });
+    void mr.start().then((ok) => {
+        if (!ok && !ctl.stopped) {
+            ctl.mediaRecorder = null;
+            releaseVideoSlot(ctl);
+            ctl.mode = "none"; // keyframes-only fallback
+            emitEvent({ op: "mode", canvasId: ctl.canvasId, mode: "none", reason: "mediarecorder-start-failed" });
+        }
+    });
+    return true;
+}
+function baseController(canvas, canvasId, contextType, mode, privacyMode = "normal") {
+    return {
+        canvas,
+        canvasId,
+        contextType,
+        mode,
+        privacyMode,
+        seq: 0,
+        dirty: false,
+        everDirty: false,
+        pumpScheduled: false,
+        flushTimer: null,
+        stopped: false,
+        demoted: false,
+        hasVideoSlot: false,
+        contextLost: false,
+        taintEmitted: false,
+        lastW: canvas.width,
+        lastH: canvas.height,
+        removeContextLossListeners: null,
+        governor: new CanvasGovernor(now, state?.budgets?.governor),
+        encoder: null,
+        batchStart: 0,
+        flushChain: Promise.resolve(),
+        keyframes: null,
+        video: null,
+        mediaRecorder: null,
+        recorder2d: null,
+        recorderGL: null,
+        recorderGPU: null,
+        worker: null,
+        workerDone: null,
+        removeWorkerListener: null,
+        pixelSuppressed: false,
+    };
+}
+function dpr() {
+    return typeof window !== "undefined" ? window.devicePixelRatio : 1;
+}
+function emitStart(ctl) {
+    ctl.lastW = ctl.canvas.width;
+    ctl.lastH = ctl.canvas.height;
+    emitEvent({
+        op: "start",
+        canvasId: ctl.canvasId,
+        contextType: ctl.contextType,
+        mode: ctl.mode,
+        w: ctl.canvas.width,
+        h: ctl.canvas.height,
+        dpr: dpr(),
+    });
+}
+/**
+ * A24 (command/keyframe mode): the canvas was resized mid-session. Video-mode
+ * controllers handle this inside VideoCapture (encoder restart); for command/
+ * keyframe streams the player learns the new size from a `resize` index event
+ * (new dims + DPR) plus a forced keyframe at the new size. Cheap and idempotent
+ * — only fires when the dimensions actually changed.
+ */
+function maybeEmitResize(ctl, t) {
+    const w = ctl.canvas.width;
+    const h = ctl.canvas.height;
+    if (w === ctl.lastW && h === ctl.lastH)
+        return;
+    ctl.lastW = w;
+    ctl.lastH = h;
+    if (ctl.mode === "video")
+        return; // handled by VideoCapture.requestRestart
+    emitEvent({ op: "resize", canvasId: ctl.canvasId, w, h, dpr: dpr() });
+    // [audit B1] A masked draw THIS frame may have an UNCOMPUTABLE bbox
+    // (keyframeUnsafe: ctx.fill(Path2D) / degenerate CTM / zero-area) — its pixels
+    // can't be region-blanked. The resize keyframe below would ship them in full,
+    // and the resetMaskedRegions() that follows clears the keyframeUnsafe latch
+    // BEFORE pumpCanvas's own suppression check (which runs AFTER this function) can
+    // act on it — so the leak would also disable all future suppression. Evaluate
+    // suppression HERE, first: tear down pixel capture and skip the leaking keyframe.
+    // (The computable-region case is still handled by takeKeyframe blanking
+    // maskedRegions below. [audit H-NEW-1])
+    if (ctl.recorder2d?.keyframeUnsafe && !ctl.pixelSuppressed) {
+        suppressPixelCapture(ctl);
+    }
+    // Force a fresh keyframe so replay re-anchors at the new size — UNLESS pixel
+    // capture is now suppressed (command-only replay). Take it BEFORE resetting
+    // masked regions: a masked draw may have happened THIS frame after the resize
+    // (the `canvas.width=` clear-then-redraw idiom), and its region must still blank
+    // this keyframe — resetting first would leak it. [audit H-NEW-1]
+    if (!ctl.pixelSuppressed)
+        ctl.keyframes?.takeKeyframe(t);
+    // Now drop the (old-size) accumulated regions so they don't over-blank or
+    // accumulate forever on a canvas that "clears" via resize. [audit H2]
+    ctl.recorder2d?.resetMaskedRegions();
+}
+// ─── Canvas discovery & routing ──────────────────────────────────────────────
+function isMasked(canvas, maskSelector) {
+    try {
+        return !!canvas.closest(maskSelector);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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 function collectMalformedSelectors(settings) {
+    if (typeof document === "undefined")
+        return [];
+    const named = [
+        ["maskTextSelector", settings.maskTextSelector],
+        ["blockSelector", settings.blockSelector],
+        ["unmaskSelector", settings.unmaskSelector],
+    ];
+    const bad = [];
+    for (const [name, sel] of named) {
+        if (!sel)
+            continue;
+        try {
+            document.querySelector(sel);
+        }
+        catch {
+            bad.push(name);
+        }
+    }
+    return bad;
+}
+function derivePrivacySettings(settings) {
+    const nz = (s) => (s && s.length > 0 ? s : undefined);
+    return {
+        maskCanvasClass: settings.maskCanvasClass,
+        maskTextClass: nz(settings.maskTextClass),
+        maskTextSelector: nz(settings.maskTextSelector),
+        blockSelector: nz(settings.blockSelector),
+        unmaskSelector: nz(settings.unmaskSelector),
+        maskCanvasText: settings.maskCanvasText,
+        recordSsn: settings.recordSsn,
+        recordCreditCardInfo: settings.recordCreditCardInfo,
+        recordDob: settings.recordDob,
+    };
+}
+/** A13 — the content-detection flags used for normal-mode drawn-text redaction. */
+function deriveContentFlags(settings) {
+    return {
+        recordSsn: settings.recordSsn,
+        recordCreditCardInfo: settings.recordCreditCardInfo,
+        recordDob: settings.recordDob,
+    };
+}
+/**
+ * A13 — classify a canvas's privacy mode against the active privacy framework.
+ * Thin wrapper over classifyCanvasPrivacy so call sites read cleanly.
+ */
+function classify(canvas) {
+    if (!state)
+        return "normal";
+    return classifyCanvasPrivacy(canvas, state.privacySettings);
+}
+/**
+ * A13 — true when at least one content-detection flag is OFF (privacy intent:
+ * "do not record this PII type"), so normal-mode canvases should still scan
+ * drawn text. When every flag is on (or unset), no normal-mode redaction is
+ * needed and the controller is built WITHOUT a textRedactor (zero hot-path cost).
+ */
+function contentDetectionActive() {
+    const f = state?.contentFlags;
+    if (!f)
+        return false;
+    return (f.recordCreditCardInfo === false ||
+        f.recordSsn === false ||
+        f.recordDob === false);
+}
+/**
+ * A13 — build the text redactor installed on a controller's ContextRecorder.
+ * "redact" canvases get a full mask of every drawn string; "normal" canvases
+ * get content-detection redaction ONLY when a flag is off (else undefined so
+ * the recorder's hot path is untouched). "suppress" never reaches here.
+ */
+function makeTextRedactor(mode) {
+    if (mode === "redact") {
+        return (text) => redactCanvasText(text, "redact", {});
+    }
+    if (mode === "normal" && contentDetectionActive()) {
+        const flags = state.contentFlags;
+        return (text) => redactCanvasText(text, "normal", flags);
+    }
+    return undefined;
+}
+/**
+ * A13 — emit the op:"masked" index event for a suppressed canvas, carrying a
+ * `reason` ("block"|"mask") where determinable so the player and debugging
+ * can tell a block selector apart from the legacy mask-canvas class.
+ */
+function emitMasked(canvas, canvasId) {
+    const reason = state
+        ? suppressReason(canvas, state.privacySettings)
+        : undefined;
+    const payload = { op: "masked", canvasId };
+    if (reason)
+        payload.reason = reason;
+    emitEvent(payload);
+    // A13: remember this canvas as suppressed so A6 re-eval can RE-ARM it if the
+    // privacy rule is later removed (normal/redact mid-session).
+    state?.suppressed.add(canvas);
+}
+/**
+ * A13 — a "redact" canvas whose text lives in PIXELS (WebGL / WebGPU draw glyph
+ * geometry; worker / OffscreenCanvas serializes its own batches with no DOM to
+ * classify) CANNOT have its text redacted via 2D fillText arg masking. For those
+ * we ESCALATE redact → suppress: record nothing rather than leak rendered text
+ * pixels. Returns the effective mode to build the controller in.
+ */
+function escalateRedactIfPixelText(mode, contextType) {
+    if (mode !== "redact")
+        return mode;
+    if (contextType === "webgl" ||
+        contextType === "webgl2" ||
+        contextType === "experimental-webgl" ||
+        contextType === "webgpu" ||
+        contextType === "worker") {
+        noteOnce(`redact canvas with pixel-only text (${contextType}) — escalated to suppress`);
+        return "suppress";
+    }
+    return mode;
+}
+/** Resolve the rrweb mirror id, retrying briefly (new nodes get ids once the
+ * mutation that added them is serialized). */
+function resolveCanvasId(canvas) {
+    return new Promise((resolve) => {
+        let tries = 0;
+        const attempt = () => {
+            if (!state || state.stopped)
+                return resolve(null);
+            let id = -1;
+            try {
+                id = state.deps.mirror.getId(canvas);
+            }
+            catch { /* mirror unavailable */ }
+            if (typeof id === "number" && id >= 0)
+                return resolve(String(id));
+            if (++tries > 30) {
+                noteOnce("canvas never received an rrweb mirror id — not recorded");
+                return resolve(null);
+            }
+            setTimeout(attempt, 300);
+        };
+        attempt();
+    });
+}
+/**
+ * A13 — re-arm a canvas whose privacy classification changed in a way that
+ * requires a fresh controller (suppress→normal/redact, or normal↔redact). Drops
+ * the `handled`/`suppressed` markers so the next `considerCanvas` re-discovers
+ * and rebuilds it in the new mode. Safe to call for a connected canvas only.
+ */
+function rearmCanvas(canvas) {
+    const s = state;
+    if (!s || s.stopped)
+        return;
+    s.handled.delete(canvas);
+    s.suppressed.delete(canvas);
+    // Re-discover via the normal path (resolves context + classifies + builds).
+    considerCanvas(canvas);
+}
+/**
+ * A6 + A13 — dynamic privacy re-evaluation. Privacy selectors (mask-canvas,
+ * block, maskText, unmask) may apply to a canvas OR any
+ * ancestor MID-SESSION (a privacy toggle adds/removes a class, an unmask region
+ * is added). This re-classifies every TRACKED canvas AND every
+ * SUPPRESSED canvas after a relevant mutation and applies any transition:
+ *
+ *   tracked → suppress      : teardown, emit op:"masked", remember as suppressed
+ *   tracked normal ↔ redact : teardown + RE-ARM (rebuild in the new mode — the
+ *                             recorder's redactor + pixel-capture config differ)
+ *   suppressed → normal/redact : RE-ARM (re-discover + start recording) — fixes
+ *                             the one-way freeze where an unmasked canvas stayed
+ *                             permanently off.
+ *
+ * The previous A6 implementation only handled tracked→suppress and left a
+ * canvas permanently `handled`; A13 makes every transition bidirectional.
+ */
+function reevaluateAllMasking() {
+    const s = state;
+    if (!s || s.stopped)
+        return;
+    // 1. Tracked canvases: reclassify and apply transitions. Snapshot first —
+    //    teardown/rearm mutate s.controllers.
+    for (const ctl of [...s.controllers.values()]) {
+        if (ctl.stopped)
+            continue;
+        const canvas = ctl.canvas;
+        const nextMode = classifyCanvasPrivacy(canvas, s.privacySettings);
+        if (nextMode === "suppress") {
+            const canvasId = ctl.canvasId;
+            teardownController(ctl);
+            s.handled.add(canvas);
+            emitMasked(canvas, canvasId); // records in suppressed + emits reason
+            continue;
+        }
+        if (nextMode !== ctl.privacyMode) {
+            // normal ↔ redact transition: the recorder's text redactor and pixel
+            // capture (keyframes/video, demote eligibility) all differ between modes.
+            // Tear down and rebuild fresh in the new mode rather than mutate a live
+            // recorder in place (simpler + correct: a redact→normal canvas re-enables
+            // keyframes, a normal→redact canvas suppresses them and re-installs the
+            // full-mask redactor).
+            teardownController(ctl);
+            if (canvas.isConnected)
+                rearmCanvas(canvas);
+        }
+    }
+    // 2. Suppressed canvases: re-arm any that are no longer suppressed (the
+    //    privacy rule was removed mid-session). Snapshot the set — rearmCanvas
+    //    mutates it.
+    for (const canvas of [...s.suppressed]) {
+        if (!canvas.isConnected) {
+            s.suppressed.delete(canvas);
+            continue;
+        }
+        const nextMode = classifyCanvasPrivacy(canvas, s.privacySettings);
+        if (nextMode !== "suppress") {
+            rearmCanvas(canvas);
+        }
+    }
+}
+/**
+ * A22 — a canvas left the DOM. If it was tracked, tear down its controller so
+ * the recorder, video-encoder worker, and keyframe scratch canvas are released
+ * instead of leaking for the rest of the session. A move (remove+add in the
+ * same batch) leaves the canvas still connected — skip those so a relocated
+ * canvas keeps recording. A genuinely removed canvas is also un-`handled` so a
+ * later re-attach re-discovers it fresh (consistent with the disconnected-
+ * canvas policy in considerCanvas).
+ */
+function onCanvasRemoved(canvas) {
+    const s = state;
+    if (!s || s.stopped)
+        return;
+    if (canvas.isConnected)
+        return; // moved within the DOM, not removed
+    const ctl = s.controllers.get(canvas);
+    if (ctl) {
+        // Best-effort terminal flush is intentionally skipped: a removed canvas's
+        // GPU/2D buffers are gone, so flushing would emit garbage. We still emit
+        // op:"stop" so the player knows the stream ended here.
+        const canvasId = ctl.canvasId;
+        teardownController(ctl);
+        emitEvent({ op: "stop", canvasId });
+    }
+    // Allow re-discovery if it comes back.
+    s.handled.delete(canvas);
+    s.suppressed.delete(canvas); // A13: no longer a candidate for re-arm
+}
+function considerCanvas(canvas) {
+    const s = state;
+    if (!s || s.stopped || s.handled.has(canvas))
+        return;
+    // Invisible canvases record NOTHING (Phase 0.5 E2E, found on /editor):
+    // canvases outside the document — Konva hit canvases, framework buffer
+    // canvases — are never user-visible, never receive an rrweb mirror id
+    // (resolveCanvasId would spin for 9s), and recording them wastes customer
+    // bytes. Their auto recorder is released so a constantly-redrawing hit
+    // canvas cannot grow an unbounded BufferSink. Deliberately NOT marked
+    // handled: if the canvas is attached to the DOM later, the
+    // MutationObserver re-considers it (pre-attach pixels arrive via the
+    // first keyframe after attach).
+    if (!canvas.isConnected) {
+        releaseAutoRecorder(canvas);
+        noteOnce("disconnected canvas skipped — recorded only if attached to the document");
+        return;
+    }
+    // A13: classify against the full privacy framework (unmask > block/
+    // mask-canvas > maskText > normal). "suppress" tears down here with an
+    // op:"masked" index event (reason where determinable).
+    const mode = classify(canvas);
+    if (mode === "suppress") {
+        s.handled.add(canvas);
+        void resolveCanvasId(canvas).then((id) => {
+            if (id != null)
+                emitMasked(canvas, id);
+        });
+        return;
+    }
+    const worker = getWorkerForCanvas(canvas);
+    const info = getContextInfo(canvas);
+    // No known context yet — wait for the getContext auto-attach path, a
+    // worker association, or first untracked-context activity.
+    if (!worker && !info)
+        return;
+    s.handled.add(canvas);
+    void resolveCanvasId(canvas).then((canvasId) => {
+        if (canvasId == null || !state || state.stopped)
+            return;
+        if (worker) {
+            // A13: a worker/OffscreenCanvas serializes its own batches with no DOM —
+            // reliable worker-side text redaction + keyframe suppression is hard, so a
+            // worker canvas that classifies "redact" is ESCALATED to suppress (record
+            // nothing). "normal" worker canvases record as today.
+            if (mode === "redact") {
+                noteOnce("redact worker/offscreen canvas — escalated to suppress (no DOM to redact)");
+                emitMasked(canvas, canvasId);
+                return;
+            }
+            void buildWorkerController(canvas, canvasId, worker);
+        }
+        else if (info.type === "2d") {
+            build2DController(canvas, canvasId, null, mode);
+        }
+        else if (info.type === "webgl" || info.type === "webgl2" || info.type === "experimental-webgl") {
+            // A13: GL text is rendered glyph geometry (pixels), not redactable
+            // fillText args — a "redact" GL canvas escalates to suppress.
+            const eff = escalateRedactIfPixelText(mode, info.type);
+            if (eff === "suppress") {
+                emitMasked(canvas, canvasId);
+                return;
+            }
+            buildGLController(canvas, canvasId, info.type, null, eff);
+        }
+        else if (info.type === "webgpu") {
+            // A13: WebGPU text is also pixels — "redact" escalates to suppress.
+            const eff = escalateRedactIfPixelText(mode, "webgpu");
+            if (eff === "suppress") {
+                emitMasked(canvas, canvasId);
+                return;
+            }
+            buildGPUController(canvas, canvasId, eff);
+        }
+        else {
+            // bitmaprenderer etc. — no command hooks, no dirty signal: not captured.
+            const ctl = baseController(canvas, canvasId, "unknown", "none");
+            state.controllers.set(canvas, ctl);
+            emitStart(ctl);
+            noteOnce(`unsupported context type "${info.type}" — not captured`);
+        }
+    });
+}
+function build2DController(canvas, canvasId, preAttached, privacyMode = "normal") {
+    const s = state;
+    if (!s || s.stopped)
+        return;
+    const ctl = baseController(canvas, canvasId, "2d", "commands", privacyMode);
+    ctl.encoder = new CommandEncoder();
+    const sink = makeCommandSink(ctl);
+    let rec = preAttached;
+    if (rec) {
+        rec.swapSink(sink); // drains the temporary BufferSink
+    }
+    else {
+        rec = attachRecorder(canvas, sink, now, "cas", encodeImage, { retainAssets: false });
+    }
+    if (!rec) {
+        ctl.mode = "none";
+        noteOnce("canvas has no readable 2D context — nothing recorded");
+    }
+    // A13: install the privacy text redactor on the recorder. "redact" masks all
+    // drawn text; "normal" content-detects when a record* flag is off; otherwise
+    // undefined (hot path untouched). P1: the resolved global redaction style drives
+    // how masked text/shapes are baked (per-call maskCanvasDraws overrides it).
+    if (rec) {
+        rec.textRedactor = makeTextRedactor(privacyMode);
+        rec.redactStyle = s.redactStyle;
+    }
+    ctl.recorder2d = rec;
+    // P1: a "redact" 2D canvas now KEEPS keyframes — the masked TEXT regions are
+    // blanked on every keyframe (region-blanking via recorder.maskedRegions), so
+    // real text pixels never ship while the rest of the canvas stays pixel-perfect.
+    // It still never demotes to video (maybeDemote vetoes redact) because video
+    // frames can't be region-blanked. (GL/GPU/worker redact canvases — whose text
+    // is pixels — escalate to suppress upstream in escalateRedactIfPixelText.)
+    ctl.keyframes = makeKeyframes(ctl);
+    s.controllers.set(canvas, ctl);
+    emitStart(ctl);
+    maybeInitialKeyframe(ctl); // A27 (no-op when keyframes suppressed)
+}
+function buildGLController(canvas, canvasId, rawType, preAttachedCtx, privacyMode = "normal") {
+    const s = state;
+    if (!s || s.stopped)
+        return;
+    const contextType = rawType === "experimental-webgl" ? "webgl" : rawType;
+    // A13: a "redact" GL canvas escalates to suppress upstream (GL text is
+    // pixels). If one slips through, escalate here too — never build a redact GL
+    // controller (it could not redact glyph geometry).
+    if (escalateRedactIfPixelText(privacyMode, contextType) === "suppress") {
+        emitMasked(canvas, canvasId);
+        return;
+    }
+    const ctl = baseController(canvas, canvasId, contextType, "commands", privacyMode);
+    ctl.encoder = new CommandEncoder();
+    const sink = makeCommandSink(ctl);
+    let rec;
+    if (preAttachedCtx) {
+        rec = attachGLRecorderToContext(preAttachedCtx, sink, now);
+    }
+    else {
+        rec = attachGLRecorder(canvas, rawType, sink, now);
+    }
+    if (!rec) {
+        ctl.mode = "none";
+        noteOnce("GL context not reachable — nothing recorded");
+    }
+    ctl.recorderGL = rec;
+    ctl.keyframes = makeKeyframes(ctl);
+    installGLContextLossHandling(ctl); // A10
+    s.controllers.set(canvas, ctl);
+    emitStart(ctl);
+    maybeInitialKeyframe(ctl); // A27
+}
+/**
+ * A10 (WebGL) — context-loss recovery. A GPU reset / driver crash / tab
+ * backgrounding fires `webglcontextlost` on the canvas; without handling, the
+ * recorder keeps emitting ops that reference dead GL objects (garbage replay)
+ * and never re-keys after restore. We:
+ *   - on lost: preventDefault (REQUIRED for the browser to later fire
+ *     `webglcontextrestored`), mark the controller contextLost (pump + command
+ *     sink drop everything), flush the pending batch, emit op:"context-lost".
+ *   - on restored: attach a FRESH GL recorder to the restored context (interned
+ *     object ids reset — the app re-creates its GL resources after restore and
+ *     those creation calls are captured anew), clear contextLost, emit
+ *     op:"context-restored", and force a keyframe so the stream re-anchors.
+ */
+function installGLContextLossHandling(ctl) {
+    const canvas = ctl.canvas;
+    const onLost = (e) => {
+        // Without preventDefault the context is NOT restorable (spec).
+        try {
+            e.preventDefault();
+        }
+        catch { /* best effort */ }
+        if (ctl.stopped || ctl.contextLost)
+            return;
+        ctl.contextLost = true;
+        try {
+            flushBatch(ctl, now());
+        }
+        catch { /* best effort */ }
+        emitEvent({ op: "context-lost", canvasId: ctl.canvasId });
+    };
+    const onRestored = () => {
+        if (ctl.stopped || !ctl.contextLost)
+            return;
+        // Re-attach a fresh recorder to the restored context.
+        try {
+            if (ctl.recorderGL?.rawCtx)
+                detachGLRecorderFromContext(ctl.recorderGL.rawCtx);
+        }
+        catch { /* best effort */ }
+        const rawType = ctl.contextType === "webgl2" ? "webgl2" : "webgl";
+        const rec = attachGLRecorder(canvas, rawType, makeCommandSink(ctl), now);
+        ctl.recorderGL = rec;
+        ctl.contextLost = false;
+        emitEvent({ op: "context-restored", canvasId: ctl.canvasId, w: canvas.width, h: canvas.height, dpr: dpr() });
+        // Force a fresh keyframe once the context is live again so replay re-keys.
+        ctl.everDirty = true;
+        markDirty(ctl);
+        ctl.keyframes?.onInteraction(now()); // request a near-term keyframe in-task
+    };
+    canvas.addEventListener("webglcontextlost", onLost, false);
+    canvas.addEventListener("webglcontextrestored", onRestored, false);
+    ctl.removeContextLossListeners = () => {
+        canvas.removeEventListener("webglcontextlost", onLost, false);
+        canvas.removeEventListener("webglcontextrestored", onRestored, false);
+    };
+}
+function buildGPUController(canvas, canvasId, privacyMode = "normal") {
+    const s = state;
+    if (!s || s.stopped)
+        return;
+    // A13: WebGPU text is pixels — a "redact" GPU canvas escalates to suppress.
+    if (escalateRedactIfPixelText(privacyMode, "webgpu") === "suppress") {
+        emitMasked(canvas, canvasId);
+        return;
+    }
+    const ctl = baseController(canvas, canvasId, "webgpu", "commands", privacyMode);
+    ctl.encoder = new CommandEncoder();
+    const rec = attachGPURecorder(canvas, makeCommandSink(ctl), now);
+    if (!rec) {
+        // GPU stream is page-global (one canvas per page in this increment), or
+        // the pipeline predates recording. Timer-paced readback of a GPU canvas
+        // is exactly the guardrail-#6 hazard, so there is no safe fallback here.
+        ctl.mode = "none";
+        noteOnce("WebGPU recorder not armed for this canvas — nothing recorded");
+    }
+    ctl.recorderGPU = rec;
+    ctl.keyframes = makeKeyframes(ctl);
+    installGPUContextLossHandling(ctl); // A10
+    s.controllers.set(canvas, ctl);
+    emitStart(ctl);
+    maybeInitialKeyframe(ctl); // A27
+}
+/**
+ * A10 (WebGPU) — device-loss recovery. WebGPU has no contextlost event; the
+ * device's `lost` promise is watched in patchWebGPU and reported here. On loss
+ * we mark the controller contextLost (pump + command sink drop everything) and
+ * emit op:"context-lost"; when the app acquires a NEW device the notifier fires
+ * with lost=false and we clear the state, emit op:"context-restored", and force
+ * a keyframe so replay re-anchors. The GPU stream is page-global in this
+ * increment, so a single controller owns the notifier.
+ */
+function installGPUContextLossHandling(ctl) {
+    setGPUDeviceLostNotifier((lost) => {
+        if (ctl.stopped)
+            return;
+        if (lost) {
+            if (ctl.contextLost)
+                return;
+            ctl.contextLost = true;
+            try {
+                flushBatch(ctl, now());
+            }
+            catch { /* best effort */ }
+            emitEvent({ op: "context-lost", canvasId: ctl.canvasId });
+        }
+        else {
+            if (!ctl.contextLost)
+                return;
+            ctl.contextLost = false;
+            emitEvent({
+                op: "context-restored",
+                canvasId: ctl.canvasId,
+                w: ctl.canvas.width,
+                h: ctl.canvas.height,
+                dpr: dpr(),
+            });
+            ctl.everDirty = true;
+            markDirty(ctl);
+            ctl.keyframes?.onInteraction(now());
+        }
+    });
+    ctl.removeContextLossListeners = () => setGPUDeviceLostNotifier(null);
+}
+async function buildWorkerController(canvas, canvasId, worker) {
+    const hasShim = await pingWorkerShim(worker);
+    const s = state;
+    if (!s || s.stopped)
+        return;
+    if (hasShim) {
+        const ctl = baseController(canvas, canvasId, "worker", "commands");
+        ctl.worker = worker;
+        let resolveDone;
+        ctl.workerDone = new Promise((r) => { resolveDone = r; });
+        const onMsg = (e) => {
+            const m = e.data;
+            if (m?.type === "sf-record-done")
+                resolveDone(m);
+            else if (m?.type === "sf-record-noctx") {
+                // Shim present but the worker has no 2D context to record (GL/GPU
+                // worker canvases): fall back to interval-paced video of the
+                // placeholder, exactly like the no-shim path (contract §5).
+                if (!ctl.stopped && ctl.mode === "commands" && !ctl.video && !ctl.mediaRecorder) {
+                    // A25: respect the global encoder cap — a worker placeholder canvas
+                    // also spins a real VideoEncoder, so degrade to keyframe-only when no
+                    // slot is free.
+                    const canVideo = VideoCapture.supported() && tryAcquireVideoSlot(ctl);
+                    if (VideoCapture.supported() && !canVideo) {
+                        noteOnce(`video-encoder cap (${state?.budgets.maxConcurrentVideo ?? MAX_CONCURRENT_VIDEO_CANVASES}) reached — worker canvas kept on keyframes`);
+                    }
+                    if (canVideo) {
+                        ctl.mode = "video";
+                        emitEvent({ op: "mode", canvasId: ctl.canvasId, mode: "video", reason: "worker-no-2d-context" });
+                        const video = makeVideo(ctl, true);
+                        ctl.video = video;
+                        void video.start().then((ok) => {
+                            if (!ok && !ctl.stopped) {
+                                ctl.video = null;
+                                releaseVideoSlot(ctl); // A25
+                                ctl.mode = "none";
+                                emitEvent({ op: "mode", canvasId: ctl.canvasId, mode: "none", reason: "video-start-failed" });
+                            }
+                        });
+                    }
+                    else if (!VideoCapture.supported() && tryStartMediaRecorder(ctl, "worker-no-2d-context")) {
+                        // A41: WebCodecs absent — MediaRecorder fallback for the worker
+                        // placeholder. tryStartMediaRecorder set mode/index event + slot.
+                    }
+                    else {
+                        ctl.mode = "none";
+                        emitEvent({ op: "mode", canvasId: ctl.canvasId, mode: "none", reason: "worker-no-2d-context" });
+                    }
+                }
+            }
+            else if (m?.type === "sf-record-batch") {
+                // live-streamed worker command batch (already deflated worker-side)
+                sendFrame(ctl, "commands", { codec: "sfc-bin-1", compression: "deflate" }, new Uint8Array(m.deflated), m.tMs);
+                ctl.governor.addBytes(m.deflated.byteLength);
+            }
+        };
+        worker.addEventListener("message", onMsg);
+        ctl.removeWorkerListener = () => worker.removeEventListener("message", onMsg);
+        try {
+            // A13: forward the data-sensitivity flags so the worker redacts CC/SSN/DOB
+            // in its own drawn-text args (selector suppression was already applied
+            // main-thread; a worker reaching here is "normal" mode). The worker
+            // installs a text redactor only when a flag is actually off.
+            worker.postMessage({ type: "sf-record-start", contentFlags: s.contentFlags });
+        }
+        catch {
+            noteOnce("worker postMessage failed — worker canvas not recorded");
+        }
+        s.controllers.set(canvas, ctl);
+        emitStart(ctl);
+        return;
+    }
+    // No shim in the worker: fall back to interval-paced video capture of the
+    // placeholder (its committed frame persists like an image — safe to read
+    // outside the rendering task).
+    const ctl = baseController(canvas, canvasId, "worker", "none");
+    s.controllers.set(canvas, ctl);
+    // A25: a no-shim worker placeholder still drives a real VideoEncoder, so it
+    // must hold a global slot. When WebCodecs is unavailable OR the cap is reached
+    // there is no command/keyframe fallback for a worker placeholder (no draw
+    // hooks, no readable main-thread context).
+    if (VideoCapture.supported() && tryAcquireVideoSlot(ctl)) {
+        ctl.mode = "video";
+        const video = makeVideo(ctl, true);
+        ctl.video = video;
+        void video.start().then((ok) => {
+            if (!ok && !ctl.stopped) {
+                ctl.video = null;
+                releaseVideoSlot(ctl); // A25
+                ctl.mode = "none";
+                emitEvent({ op: "mode", canvasId: ctl.canvasId, mode: "none", reason: "video-start-failed" });
+            }
+        });
+    }
+    else if (VideoCapture.supported()) {
+        noteOnce(`video-encoder cap (${state?.budgets.maxConcurrentVideo ?? MAX_CONCURRENT_VIDEO_CANVASES}) reached — worker placeholder canvas not captured`);
+    }
+    else if (tryStartMediaRecorder(ctl, "worker-no-shim")) {
+        // A41: WebCodecs absent (Safari < 26) but MediaRecorder + captureStream
+        // available — capture the worker placeholder via MediaRecorder instead.
+        // tryStartMediaRecorder set mode/index event + slot.
+    }
+    else {
+        noteOnce("worker canvas without shim and no usable video backend — not captured");
+    }
+    emitStart(ctl);
+}
+// ─── Untracked-context discovery (contexts created before hooks installed) ──
+function onUntracked2D(ctx) {
+    const s = state;
+    if (!s || s.stopped || s.seenContexts.has(ctx))
+        return;
+    s.seenContexts.add(ctx);
+    const canvas = ctx.canvas;
+    if (!(canvas instanceof HTMLCanvasElement))
+        return; // OffscreenCanvas buffer ctx
+    if (!canvas.isConnected)
+        return; // framework buffer canvas — content arrives via per-draw assets
+    if (s.handled.has(canvas))
+        return;
+    // A13: classify against the privacy framework. "suppress" tears down here.
+    const mode = classify(canvas);
+    if (mode === "suppress") {
+        s.handled.add(canvas);
+        void resolveCanvasId(canvas).then((id) => {
+            if (id != null)
+                emitMasked(canvas, id);
+        });
+        return;
+    }
+    s.handled.add(canvas);
+    // Buffer from this moment; the controller swaps the real sink in once the
+    // mirror id resolves.
+    const rec = attachRecorderToContext(ctx, new BufferSink(), now, "cas", encodeImage, { retainAssets: false });
+    void resolveCanvasId(canvas).then((canvasId) => {
+        if (canvasId == null || !state || state.stopped) {
+            detachRecorderFromContext(ctx);
+            return;
+        }
+        build2DController(canvas, canvasId, rec, mode);
+    });
+}
+function onUntrackedGL(ctx) {
+    const s = state;
+    if (!s || s.stopped || s.seenContexts.has(ctx))
+        return;
+    s.seenContexts.add(ctx);
+    const canvas = ctx.canvas;
+    if (!(canvas instanceof HTMLCanvasElement))
+        return;
+    if (!canvas.isConnected)
+        return;
+    if (s.handled.has(canvas))
+        return;
+    // A13: classify. "suppress" (block/mask) AND "redact" both tear down a
+    // GL canvas — GL text is pixels, so redact escalates to suppress here too.
+    const mode = classify(canvas);
+    const rawTypeEarly = typeof WebGL2RenderingContext !== "undefined" && ctx instanceof WebGL2RenderingContext
+        ? "webgl2"
+        : "webgl";
+    if (mode === "suppress" || escalateRedactIfPixelText(mode, rawTypeEarly) === "suppress") {
+        s.handled.add(canvas);
+        void resolveCanvasId(canvas).then((id) => {
+            if (id != null)
+                emitMasked(canvas, id);
+        });
+        return;
+    }
+    s.handled.add(canvas);
+    const rawType = rawTypeEarly;
+    const buffer = new BufferSink();
+    const rec = attachGLRecorderToContext(ctx, buffer, now);
+    void resolveCanvasId(canvas).then((canvasId) => {
+        if (canvasId == null || !state || state.stopped) {
+            detachGLRecorderFromContext(ctx);
+            return;
+        }
+        const s2 = state;
+        const ctl = baseController(canvas, canvasId, rawType, "commands", mode);
+        ctl.encoder = new CommandEncoder();
+        rec.swapSink(makeCommandSink(ctl));
+        ctl.recorderGL = rec;
+        ctl.keyframes = makeKeyframes(ctl);
+        installGLContextLossHandling(ctl); // A10
+        s2.controllers.set(canvas, ctl);
+        emitStart(ctl);
+        maybeInitialKeyframe(ctl); // A27
+    });
+}
+// ─── Lifecycle ───────────────────────────────────────────────────────────────
+export function startCanvasRecording(deps) {
+    if (typeof window === "undefined" || typeof document === "undefined")
+        return; // SSR
+    if (state)
+        return;
+    const maskClass = deps.settings.maskCanvasClass || DEFAULT_MASK_CLASS;
+    // A30: resolve device-class budgets once (SSR-safe; desktop profile under SSR).
+    const budgets = resolveDeviceBudgets();
+    state = {
+        deps,
+        maskSelector: `.${maskClass}, [data-sf-mask]`,
+        privacySettings: derivePrivacySettings(deps.settings),
+        contentFlags: deriveContentFlags(deps.settings),
+        redactStyle: resolveRedactStyle(DEFAULT_REDACT_STYLE, deps.settings.canvasRedactStyle),
+        budgets,
+        controllers: new Map(),
+        handled: new WeakSet(),
+        suppressed: new Set(),
+        preExisting: new WeakSet(),
+        seenContexts: new WeakSet(),
+        observer: null,
+        removeListeners: [],
+        totalBytes: 0,
+        budgetExceeded: false,
+        lastBudgetTickMs: 0,
+        notes: new Set(),
+        stopped: false,
+        videoSlots: new VideoSlotPool(budgets.maxConcurrentVideo),
+    };
+    // [audit B7] Warn (once, after `state` exists) about any malformed privacy
+    // selector — it fails safe (under-masks) at runtime, so without this the
+    // operator gets no signal that a block/mask/unmask rule is silently disabled.
+    for (const name of collectMalformedSelectors(deps.settings)) {
+        noteOnce(`malformed canvas privacy selector "${name}" is invalid and will not match — that privacy rule is disabled`);
+    }
+    // 1. Install + ARM all hooks BEFORE scanning, so contexts created from here
+    //    on buffer their creation-time ops (shader compiles, gradients...).
+    installCommandHooks();
+    installGLHooks();
+    installGPUHooks();
+    installWorkerRelay();
+    setAutoAttach({ now, assetMode: "cas", encodeImage, retainAssets: false });
+    setGLAutoAttach({ now });
+    setGPUAutoAttach({ now });
+    setContextCreatedNotifier((canvas) => {
+        // let getContext return (and the auto recorder bind) before routing
+        queueMicrotask(() => considerCanvas(canvas));
+    });
+    setUntracked2DContextNotifier(onUntracked2D);
+    setUntrackedGLContextNotifier(onUntrackedGL);
+    setWorkerAssociationNotifier((canvas) => considerCanvas(canvas));
+    // 1d. Draw-site click-to-code hook (Phase 3b, contract §8). Build-time
+    // stamping rewrites canvas call sites to `__sfds(ctx, id).method(...)`,
+    // whose helper invokes globalThis.__sfDrawSite(ctx, id) — identity
+    // passthrough that tags the recorded op for the matching context. Cheap
+    // (two WeakMap lookups), synchronous, removed at stop. No-op for unrecorded
+    // contexts (incl. WebGPU in this increment).
+    const g = globalThis;
+    g.__sfDrawSite = (o, id) => {
+        if (o && typeof o === "object") {
+            if (!noteCtxPendingSiteId(o, id))
+                noteGLPendingSiteId(o, id);
+        }
+        return o;
+    };
+    // 1e. Framework semantic adapters (Phase 4, contract §9): on pointerdown
+    // over a recorded canvas, the registered framework (Konva/Fabric/Chart.js/
+    // Three/Pixi) resolves the clicked logical object and emits op:"hit". The
+    // customer registers instances via the exported register* helpers.
+    installAdapters({
+        canvasIdFor: (canvas) => state?.controllers.get(canvas)?.canvasId ?? null,
+        emitHit: (payload) => emitEvent(payload),
+        now,
+    });
+    // 2. Interactions: forced keyframes / video boost (dirty-gated downstream).
+    const onInteraction = () => {
+        const s = state;
+        if (!s || s.stopped)
+            return;
+        const t = now();
+        for (const ctl of s.controllers.values()) {
+            if (ctl.stopped)
+                continue;
+            if (ctl.mode === "video") {
+                ctl.video?.onInteraction(t);
+                ctl.mediaRecorder?.onInteraction(t);
+            }
+            else
+                ctl.keyframes?.onInteraction(t);
+        }
+    };
+    window.addEventListener("pointerdown", onInteraction, { capture: true, passive: true });
+    window.addEventListener("keydown", onInteraction, { capture: true, passive: true });
+    state.removeListeners.push(() => {
+        window.removeEventListener("pointerdown", onInteraction, { capture: true });
+        window.removeEventListener("keydown", onInteraction, { capture: true });
+    });
+    // 3. Discovery: initial scan + MutationObserver for added canvases. Late
+    //    context creation is covered by the getContext notifier; contexts that
+    //    predate the hooks surface on their first draw (untracked notifiers).
+    const observer = new MutationObserver((muts) => {
+        let maskMayHaveChanged = false;
+        for (const m of muts) {
+            if (m.type === "attributes") {
+                // A6 + A13: a class / data-sf-mask / id / style / data-* change anywhere
+                // may change the privacy classification of a tracked OR suppressed
+                // canvas (on the canvas itself or any ancestor) — the new privacy
+                // selectors (block/maskText/unmask) can key off id, data-*, style, etc.
+                // Defer the re-check to once per batch (it scans only the small
+                // tracked-controller + suppressed sets).
+                maskMayHaveChanged = true;
+                continue;
+            }
+            m.addedNodes.forEach((node) => {
+                if (!(node instanceof Element))
+                    return;
+                if (node instanceof HTMLCanvasElement)
+                    considerCanvas(node);
+                else
+                    node.querySelectorAll("canvas").forEach((c) => considerCanvas(c));
+            });
+            // A22: a tracked canvas removed from the DOM must have its controller
+            // torn down (recorder stopped, video worker terminated, scratch canvas
+            // released) or it leaks for the rest of the session. Handle the canvas
+            // itself and any canvases nested inside a removed subtree.
+            m.removedNodes.forEach((node) => {
+                if (!(node instanceof Element))
+                    return;
+                if (node instanceof HTMLCanvasElement)
+                    onCanvasRemoved(node);
+                else
+                    node.querySelectorAll("canvas").forEach((c) => onCanvasRemoved(c));
+            });
+        }
+        if (maskMayHaveChanged)
+            reevaluateAllMasking();
+    });
+    observer.observe(document.documentElement, {
+        childList: true,
+        subtree: true,
+        // A13: observe ALL attribute mutations subtree-wide (no attributeFilter).
+        // The A6 filter was ["class","data-sf-mask"], but the privacy framework now
+        // honors arbitrary admin selectors (block/maskText/unmask) that may key off
+        // id, style, role, or any data-* attribute — a filtered observer would miss
+        // a privacy toggle implemented as e.g. `data-privacy="on"` or an id swap.
+        // COST: the observer callback fires on every attribute write anywhere in the
+        // document, but the work per batch is gated to a single boolean + one
+        // deferred reevaluateAllMasking() that scans only the small tracked +
+        // suppressed canvas sets (typically 0-handful of canvases). attributeOldValue
+        // is NOT requested, so the records stay minimal. This is the documented
+        // trade-off: correctness for arbitrary selectors over a narrow filter.
+        attributes: true,
+    });
+    state.observer = observer;
+    // A27: mark every canvas present at load as pre-existing BEFORE routing it,
+    // so its controller takes a one-shot keyframe of already-painted pixels even
+    // if it never redraws. Marking happens here (not inside considerCanvas) so it
+    // applies ONLY to the initial sweep — canvases added later go through the
+    // MutationObserver / getContext paths and are covered by live keyframe pacing.
+    document.querySelectorAll("canvas").forEach((c) => {
+        state.preExisting.add(c);
+        considerCanvas(c);
+    });
+}
+/**
+ * A22 / A6: synchronous teardown of one controller WITHOUT a final flush —
+ * used when the canvas was removed from the DOM (A22) or masked mid-session
+ * (A6). Stops the recorder, aborts the video encoder worker (no flush — the
+ * content is gone or must not be recorded), disposes the keyframe scratch
+ * canvas, detaches the patch recorder, removes any worker listener, and drops
+ * the controller from state.controllers. Idempotent and best-effort: every
+ * step is guarded so a teardown failure never breaks the host app.
+ */
+function teardownController(ctl) {
+    if (ctl.stopped) {
+        state?.controllers.delete(ctl.canvas);
+        return;
+    }
+    ctl.stopped = true;
+    try {
+        if (ctl.flushTimer !== null) {
+            clearTimeout(ctl.flushTimer);
+            ctl.flushTimer = null;
+        }
+    }
+    catch { /* best effort */ }
+    try {
+        ctl.removeContextLossListeners?.();
+    }
+    catch { /* best effort */ }
+    ctl.removeContextLossListeners = null;
+    try {
+        ctl.video?.abort();
+    }
+    catch { /* best effort */ }
+    ctl.video = null;
+    try {
+        ctl.mediaRecorder?.abort();
+    }
+    catch { /* best effort */ } // A41
+    ctl.mediaRecorder = null;
+    releaseVideoSlot(ctl); // A25: free the encoder slot for another canvas
+    try {
+        ctl.keyframes?.dispose();
+    }
+    catch { /* best effort */ }
+    ctl.keyframes = null;
+    // Worker-relay controllers: tell the worker to stop recording (we discard its
+    // result — this is a non-flushing teardown) and drop our message listener.
+    if (ctl.worker) {
+        try {
+            ctl.worker.postMessage({ type: "sf-record-stop" });
+        }
+        catch { /* worker gone */ }
+    }
+    try {
+        ctl.removeWorkerListener?.();
+    }
+    catch { /* best effort */ }
+    ctl.removeWorkerListener = null;
+    try {
+        if (ctl.recorder2d)
+            detachRecorderFromContext(ctl.recorder2d.rawCtx);
+    }
+    catch { /* best effort */ }
+    try {
+        if (ctl.recorderGL?.rawCtx)
+            detachGLRecorderFromContext(ctl.recorderGL.rawCtx);
+    }
+    catch { /* best effort */ }
+    try {
+        ctl.recorderGPU?.detach();
+    }
+    catch { /* best effort */ }
+    state?.controllers.delete(ctl.canvas);
+}
+/** [audit C1] Upper bound on a single recorder.settle() at teardown. The 2D CAS
+ * `encodeImage` path awaits an encode-worker reply with no timeout of its own, so
+ * a silently-dropped worker message would otherwise deadlock the clean stop. Match
+ * the existing worker-stop bound (5 s). */
+const SETTLE_TIMEOUT_MS = 5000;
+/** [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 function settleOrTimeout(p, ms) {
+    return Promise.race([
+        p.catch(() => { }),
+        new Promise((resolve) => setTimeout(resolve, ms)),
+    ]);
+}
+async function stopController(ctl, t) {
+    if (ctl.stopped)
+        return;
+    ctl.stopped = true;
+    // A10: drop context-loss listeners (GL element listeners / GPU notifier).
+    try {
+        ctl.removeContextLossListeners?.();
+    }
+    catch { /* best effort */ }
+    ctl.removeContextLossListeners = null;
+    if (ctl.flushTimer !== null) {
+        clearTimeout(ctl.flushTimer);
+        ctl.flushTimer = null;
+    }
+    if (ctl.worker && ctl.workerDone) {
+        try {
+            ctl.worker.postMessage({ type: "sf-record-stop" });
+        }
+        catch { /* worker gone */ }
+        const m = await Promise.race([
+            ctl.workerDone,
+            new Promise((r) => setTimeout(() => r(null), 5000)),
+        ]);
+        ctl.removeWorkerListener?.();
+        if (m)
+            await convertWorkerResult(ctl, m);
+        if (ctl.video)
+            await ctl.video.stop(); // worker noctx video fallback
+        if (ctl.mediaRecorder)
+            await ctl.mediaRecorder.stop(); // A41 worker fallback
+    }
+    else {
+        flushBatch(ctl, t);
+        if (ctl.video)
+            await ctl.video.stop();
+        if (ctl.mediaRecorder)
+            await ctl.mediaRecorder.stop(); // A41: flush final chunk
+        if (ctl.keyframes) {
+            if (ctl.everDirty)
+                ctl.keyframes.takeKeyframe(t); // final keyframe
+            await ctl.keyframes.stop(t);
+        }
+        // [audit B12] DETACH BEFORE settle. settle() is async; while it awaits pending
+        // asset encodes the context is still live, so a draw landing in that window
+        // would record a NEW op (never flushed → lost) and push a NEW texture-encode
+        // whose asset could ship AFTER this stop frame (orphan). Detaching first stops
+        // recording, so the subsequent settle only drains already-captured assets.
+        if (ctl.recorder2d) {
+            detachRecorderFromContext(ctl.recorder2d.rawCtx);
+            // [audit C2] A 2D draw can land during the awaited video/keyframe stops above
+            // (after the first flushBatch), recording an op into the encoder that would
+            // otherwise never be flushed. Detach has now stopped new recording, so flush
+            // those trailing ops (no-op when the encoder is empty). Keeps detach AFTER the
+            // final keyframe so masked-region tracking still blanks correctly (B12).
+            flushBatch(ctl, t);
+            // [audit C1] bound settle so a dropped encode-worker message can't deadlock stop.
+            await settleOrTimeout(ctl.recorder2d.settle(), SETTLE_TIMEOUT_MS);
+        }
+        if (ctl.recorderGL) {
+            if (ctl.recorderGL.rawCtx)
+                detachGLRecorderFromContext(ctl.recorderGL.rawCtx);
+            await settleOrTimeout(ctl.recorderGL.settle(), SETTLE_TIMEOUT_MS); // ship pending GL texture assets
+        }
+        ctl.recorderGPU?.detach();
+        await ctl.flushChain;
+    }
+    releaseVideoSlot(ctl); // A25: free the encoder slot at clean stop
+    emitEvent({ op: "stop", canvasId: ctl.canvasId });
+}
+async function convertWorkerResult(ctl, m) {
+    for (const note of m.notes ?? [])
+        noteOnce(`worker: ${note}`);
+    for (const batch of m.batches ?? []) {
+        try {
+            const z = await deflate(batch);
+            sendFrame(ctl, "commands", { codec: "sfc-bin-1", compression: "deflate" }, z);
+        }
+        catch { /* drop batch */ }
+    }
+    for (const a of m.assets ?? []) {
+        try {
+            if (a.bitmap) {
+                const w = a.w ?? a.bitmap.width;
+                const h = a.h ?? a.bitmap.height;
+                const r = await encodeBitmap(a.bitmap, 0.85, true); // transfers the bitmap
+                if (r.bytes)
+                    sendFrame(ctl, "asset", { assetId: a.id, format: "webp", w, h }, r.bytes);
+            }
+            else if (a.imageData) {
+                const d = a.imageData;
+                const z = await deflate(new Uint8Array(d.data.buffer, d.data.byteOffset, d.data.byteLength));
+                sendFrame(ctl, "asset", { assetId: a.id, format: "imagedata", w: d.width, h: d.height }, z);
+            }
+        }
+        catch { /* drop asset */ }
+    }
+}
+/** Flush + final keyframes + op:"stop" per canvas; idempotent. Prototype
+ * patches stay installed but inert (contract §5). */
+export async function stopCanvasRecording() {
+    const s = state;
+    if (!s || s.stopped)
+        return;
+    s.stopped = true;
+    // disarm discovery + auto-attach (patches remain, recorders release below)
+    setAutoAttach(null);
+    setGLAutoAttach(null);
+    setGPUAutoAttach(null);
+    setGPUDeviceLostNotifier(null); // A10
+    setContextCreatedNotifier(null);
+    setUntracked2DContextNotifier(null);
+    setUntrackedGLContextNotifier(null);
+    setWorkerAssociationNotifier(null);
+    // remove the draw-site hook so stamped app code resumes identity passthrough
+    delete globalThis.__sfDrawSite;
+    uninstallAdapters();
+    s.observer?.disconnect();
+    for (const remove of s.removeListeners) {
+        try {
+            remove();
+        }
+        catch { /* already removed */ }
+    }
+    const t = now();
+    await Promise.all([...s.controllers.values()].map((ctl) => stopController(ctl, t).catch(() => { })));
+    pruneUnboundRecorders();
+    pruneUnboundGLRecorders();
+    pruneUnboundGPURecorders();
+    terminateImgEncoder();
+    state = null;
+}
+/**
+ * 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 async function flushAllCanvas() {
+    const s = state;
+    if (!s || s.stopped)
+        return;
+    const t = now();
+    const drains = [];
+    for (const ctl of s.controllers.values()) {
+        if (ctl.stopped)
+            continue;
+        // Flush pending command batch (worker controllers stream their batches
+        // live and have no local encoder buffer, so flushBatch is a no-op there).
+        try {
+            flushBatch(ctl, t);
+        }
+        catch { /* never break the host app */ }
+        // Drain the video encoder tail without tearing it down.
+        if (ctl.video) {
+            drains.push(ctl.video.flush().catch(() => { }));
+        }
+        // A41: drain the MediaRecorder fallback's pending chunk too.
+        if (ctl.mediaRecorder) {
+            drains.push(ctl.mediaRecorder.flush().catch(() => { }));
+        }
+        // Settle the command flush chain so deflated batches reach sendBinary.
+        drains.push(ctl.flushChain.catch(() => { }));
+    }
+    await Promise.all(drains).catch(() => { });
+}
+/** Test/diagnostic hook. */
+export function isCanvasRecordingActive() {
+    return state != null && !state.stopped;
+}
+/**
+ * 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 const __canvasManagerTestHooks = {
+    /** Spin up a minimal session state (no DOM scan / hooks) for slot testing. */
+    initState(deps) {
+        state = {
+            deps,
+            maskSelector: ".sailfishSanitize, [data-sf-mask]",
+            privacySettings: derivePrivacySettings(deps.settings),
+            contentFlags: deriveContentFlags(deps.settings),
+            redactStyle: resolveRedactStyle(DEFAULT_REDACT_STYLE, deps.settings.canvasRedactStyle),
+            budgets: resolveDeviceBudgets(),
+            controllers: new Map(),
+            handled: new WeakSet(),
+            suppressed: new Set(),
+            preExisting: new WeakSet(),
+            seenContexts: new WeakSet(),
+            observer: null,
+            removeListeners: [],
+            totalBytes: 0,
+            budgetExceeded: false,
+            lastBudgetTickMs: 0,
+            notes: new Set(),
+            stopped: false,
+            videoSlots: new VideoSlotPool(resolveDeviceBudgets().maxConcurrentVideo),
+        };
+    },
+    /** Register a synthetic command-mode 2D controller (no recorder/keyframes). */
+    addController(canvas, canvasId, privacyMode = "normal") {
+        const ctl = baseController(canvas, canvasId, "2d", "commands", privacyMode);
+        state.controllers.set(canvas, ctl);
+        return ctl;
+    },
+    // ── A13 privacy test hooks ──────────────────────────────────────────────
+    /** Classify a canvas against the current session's privacy settings. */
+    classify(canvas) {
+        return classify(canvas);
+    },
+    /** Build the text redactor a controller in `mode` would install. */
+    makeTextRedactor(mode) {
+        return makeTextRedactor(mode);
+    },
+    /** Run the real A6/A13 privacy re-evaluation pass. */
+    reevaluate() {
+        reevaluateAllMasking();
+    },
+    /** Escalation decision for pixel-text contexts (GL/GPU/worker). */
+    escalate(mode, contextType) {
+        return escalateRedactIfPixelText(mode, contextType);
+    },
+    /** Whether a canvas is currently tracked by a controller. */
+    isTracked(canvas) {
+        return !!state?.controllers.get(canvas);
+    },
+    /** Whether a canvas is in the suppressed (re-arm candidate) set. */
+    isSuppressed(canvas) {
+        return !!state?.suppressed.has(canvas);
+    },
+    /** Mark a canvas suppressed (as the discovery path would). */
+    markSuppressed(canvas) {
+        state?.handled.add(canvas);
+        state?.suppressed.add(canvas);
+    },
+    /** Read a controller's current privacy mode + whether keyframes are armed. */
+    controllerPrivacy(ctl) {
+        return { mode: ctl.privacyMode, hasKeyframes: ctl.keyframes != null };
+    },
+    /** Run the real maybeDemote path (respects the redact no-demote rule). */
+    tryDemote(ctl) {
+        maybeDemote(ctl);
+    },
+    /** Run the real maybeEmitResize on a controller — drives the B1 resize +
+     * keyframeUnsafe leak path (suppress-before-keyframe ordering). */
+    emitResize(ctl) {
+        maybeEmitResize(ctl, now());
+    },
+    /**
+     * 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, canvasId, privacyMode) {
+        const fakeRec = {
+            swapSink: () => { },
+            textRedactor: undefined,
+            rawCtx: {},
+        };
+        build2DController(canvas, canvasId, fakeRec, privacyMode);
+        return {
+            ctl: state?.controllers.get(canvas),
+            redactor: fakeRec.textRedactor,
+        };
+    },
+    /** Run the real governor-demotion path on a controller. */
+    demote(ctl, reason = "bytes") {
+        demote(ctl, reason);
+    },
+    /** Run the real (non-flushing) teardown, which frees the controller's slot. */
+    teardown(ctl) {
+        teardownController(ctl);
+    },
+    /** Current per-session slot usage. */
+    slotsInUse() {
+        return state?.videoSlots.inUse ?? -1;
+    },
+    controllerHasSlot(ctl) {
+        return ctl.hasVideoSlot;
+    },
+    reset() {
+        state = null;
+    },
+};