@sailfish-ai/recorder 1.12.5 → 1.12.6

package/dist/canvas/canvasPrivacy.js

@@ -0,0 +1,233 @@
+/**
+ * A13 — canvas privacy classification + text redaction. Brings canvas
+ * recording under the SAME selector-driven privacy framework rrweb uses for the
+ * DOM, plus content-level PII detection. (HIPAA is NOT a canvas suppression
+ * signal — a HIPAA account still records canvas; PHI is routed downstream.)
+ *
+ * Classification yields one of three modes per canvas:
+ *   "suppress" — record NOTHING (emit op:"masked"). block / mask-canvas.
+ *   "redact"   — record commands but mask ALL drawn text (→ asterisks/bar) and
+ *                blank the text's pixel region on every kept keyframe, so
+ *                rendered text never leaves the browser while the rest of the
+ *                canvas stays pixel-perfect. NON-text shapes/images are NOT
+ *                masked by redact — use maskCanvasDraws / whole-canvas suppress
+ *                for those. maskText{Class,Selector} / maskCanvasText.
+ *   "normal"   — record normally, with content-detection defense-in-depth on
+ *                text args when a record* flag is off.
+ *
+ * The selector matchers (`closestSafe` / `matchesSelectorSafe`) are reused from
+ * privacyMask.ts so a malformed admin selector fails SAFE (treated as no match,
+ * never throws into the host app / rrweb serializer).
+ *
+ * SSR rule: pure functions; the only DOM access is through the passed-in
+ * canvas element + the shared safe matchers (which guard their own calls).
+ */
+import { closestSafe, matchesSelectorSafe } from "../privacyMask";
+import { redactSensitiveContent, } from "./piiDetect";
+/** True when the app configured ANY DOM text masking (rrweb maskTextSelector or
+ * maskTextClass). Drives the mirror-DOM default: a privacy-conscious app that
+ * masks DOM text gets canvas text masked too unless it opts out
+ * (`maskCanvasText:false`). `derivePrivacySettings` only forwards explicitly-set
+ * (non-empty) selector/class values, so any truthy value here is real config. */
+function domTextMaskingConfigured(s) {
+    return !!(s.maskTextSelector || s.maskTextClass);
+}
+const DEFAULT_MASK_CLASS = "sailfishSanitize";
+/** The legacy mask-canvas selector: `.${maskCanvasClass}, [data-sf-mask]`. */
+export function maskCanvasSelector(settings) {
+    const cls = settings.maskCanvasClass || DEFAULT_MASK_CLASS;
+    return `.${cls}, [data-sf-mask]`;
+}
+/**
+ * Classify a canvas's privacy mode. PRECEDENCE (highest first):
+ *
+ *   1. unmaskSelector ancestor/self match            ⇒ "normal" (override)
+ *   2. blockSelector OR mask-canvas selector match   ⇒ "suppress"
+ *   3. maskTextClass (.class) OR maskTextSelector    ⇒ "redact"
+ *   3b. global maskCanvasText === true               ⇒ "redact"
+ *   3c. mirror-DOM (DOM text masking configured AND
+ *       maskCanvasText !== false)                    ⇒ "redact"
+ *   4. otherwise                                     ⇒ "normal"
+ *
+ * NOTE on HIPAA: a HIPAA-enabled account does NOT suppress canvas recording.
+ * Canvas still records; PHI separation happens downstream (the SDK's index
+ * events ride the rrweb event pipeline, which routes to the `phi.*` sinks via
+ * the backend `is_phi` decision, and binary frames store in the company bucket
+ * exactly like raw events). Developers prevent specific sensitive canvases from
+ * being captured with the mask/block selectors below — HIPAA is a routing flag,
+ * not a capture switch.
+ *
+ * Uses ancestor-aware `closestSafe` for class/block/unmask selectors (a privacy
+ * container masks every canvas inside it) and self-or-ancestor for maskText*.
+ * Every selector call is wrapped so a malformed admin selector fails SAFE: it
+ * simply does not match (a throw would crash the recorder; the explicit
+ * mask-canvas / block backstops remain effective).
+ */
+export function classifyCanvasPrivacy(canvas, settings) {
+    // 1. Unmask override — wins over block/mask.
+    if (closestSafe(canvas, settings.unmaskSelector))
+        return "normal";
+    // 2. Block selector OR the legacy mask-canvas selector ⇒ suppress.
+    if (closestSafe(canvas, settings.blockSelector))
+        return "suppress";
+    if (closestSafe(canvas, maskCanvasSelector(settings)))
+        return "suppress";
+    // 3. Text-redact tier. Precedence within the tier:
+    //   a. explicit per-canvas maskText class / selector match — explicit intent,
+    //      honored even when maskCanvasText is false.
+    //   b. global maskCanvasText === true — every canvas redacts text.
+    //   c. mirror-DOM default — DOM text masking configured AND not explicitly
+    //      disabled (maskCanvasText !== false) ⇒ redact canvas text too.
+    if (settings.maskTextClass && closestSafe(canvas, `.${settings.maskTextClass}`)) {
+        return "redact";
+    }
+    if (matchesSelectorSafe(canvas, settings.maskTextSelector) ||
+        closestSafe(canvas, settings.maskTextSelector)) {
+        return "redact";
+    }
+    if (settings.maskCanvasText === true)
+        return "redact";
+    if (settings.maskCanvasText !== false && domTextMaskingConfigured(settings)) {
+        return "redact";
+    }
+    // 4. No privacy rule applies.
+    return "normal";
+}
+/**
+ * Determine WHY a canvas was suppressed (for the op:"masked" reason field).
+ * Only meaningful when `classifyCanvasPrivacy` returned "suppress"; precedence
+ * matches the classifier (unmask override, then block, then mask-canvas).
+ * Returns undefined for non-suppress canvases.
+ */
+export function suppressReason(canvas, settings) {
+    if (closestSafe(canvas, settings.unmaskSelector))
+        return undefined;
+    if (closestSafe(canvas, settings.blockSelector))
+        return "block";
+    if (closestSafe(canvas, maskCanvasSelector(settings)))
+        return "mask";
+    return undefined;
+}
+/**
+ * Full length-preserving mask: every non-whitespace char → "*", whitespace
+ * kept. Mirrors rrweb's maskTextFn (privacyMask.makeMaskTextFn) so a redacted
+ * canvas string looks identical to a redacted DOM text node. Surrogate pairs
+ * (emoji) and combining marks are each non-whitespace code units, so they
+ * become "*" per UTF-16 unit — never throws, never leaks the original glyph.
+ */
+export function maskAllText(text) {
+    return text.replace(/\S/g, "*");
+}
+/**
+ * Redact a single drawn-text argument according to the canvas's privacy mode:
+ *   - "redact":  full mask (maskAllText) — drawn text is never legible.
+ *   - "normal":  content-detection redaction (redactSensitiveContent) gated on
+ *                the record* flags — defense-in-depth so CC/SSN/DOB that an app
+ *                paints into a non-masked canvas is still caught.
+ *   - "suppress": never reaches here (a suppressed canvas records no ops); the
+ *                input is returned unchanged as a defensive no-op.
+ *
+ * Non-string input (numbers, x/y coords passed as the 2nd/3rd fillText args)
+ * passes through untouched — only the FIRST string arg of fillText/strokeText
+ * is the rendered text, and the caller restricts redaction to that arg.
+ */
+export function redactCanvasText(text, mode, flags) {
+    if (typeof text !== "string")
+        return text;
+    if (mode === "redact")
+        return maskAllText(text);
+    if (mode === "normal")
+        return redactSensitiveContent(text, flags);
+    // mode === "suppress": should never be invoked, return unchanged.
+    return text;
+}
+/** Mirror-DOM defaults: text → length-preserving asterisks (looks like a masked
+ * DOM text node), shapes → same shape recolored (layout preserved). */
+export const DEFAULT_REDACT_STYLE = { text: "asterisks", shape: "color" };
+/** Dark neutral used everywhere a redaction is painted: recolored shapes + bars
+ * in the command stream AND the region-blanked keyframe pixels. A single source
+ * of truth keeps command replay and keyframe consistent. */
+export const REDACTION_COLOR = "#1f2433";
+/** Merge a per-call style override onto a base style (per-call wins; omitted
+ * fields inherit). `base` defaults to DEFAULT_REDACT_STYLE. Never mutates. */
+export function resolveRedactStyle(base, override) {
+    const b = base ?? DEFAULT_REDACT_STYLE;
+    if (!override)
+        return b;
+    return { text: override.text ?? b.text, shape: override.shape ?? b.shape };
+}
+/**
+ * Transform the four corners of a LOCAL-space box (x0,y0)-(x1,y1) by a 2D matrix
+ * and return its axis-aligned bounding box in DEVICE space. Handles a general
+ * CTM (rotation / skew), not just translate+scale — a rotated rect maps to the
+ * AABB enclosing all four rotated corners. `pad` (px, device space) is added on
+ * every side so a blanked region fully covers antialiased glyph/stroke edges.
+ * Returns null when the inputs are non-finite (never throws into the hot path).
+ */
+export function transformedBox(x0, y0, x1, y1, m, pad = 1) {
+    if (![x0, y0, x1, y1, m.a, m.b, m.c, m.d, m.e, m.f].every(Number.isFinite))
+        return null;
+    const px = (x, y) => m.a * x + m.c * y + m.e;
+    const py = (x, y) => m.b * x + m.d * y + m.f;
+    const xs = [px(x0, y0), px(x1, y0), px(x1, y1), px(x0, y1)];
+    const ys = [py(x0, y0), py(x1, y0), py(x1, y1), py(x0, y1)];
+    const minX = Math.min(...xs), maxX = Math.max(...xs);
+    const minY = Math.min(...ys), maxY = Math.max(...ys);
+    if (!Number.isFinite(minX) || !Number.isFinite(minY))
+        return null;
+    return { x: minX - pad, y: minY - pad, w: maxX - minX + 2 * pad, h: maxY - minY + 2 * pad };
+}
+/** Device-space AABB of a local-space rect (x,y,w,h) under transform `m`. */
+export function rectRegion(x, y, w, h, m) {
+    return transformedBox(x, y, x + w, y + h, m);
+}
+/**
+ * Compute a drawn-text bounding box in LOCAL (pre-transform) space from its
+ * measured metrics + alignment. textAlign shifts the box horizontally relative
+ * to the draw x (center → centered, right/end → left of x); textBaseline shifts
+ * it vertically relative to the draw y (top → below y, middle → centered,
+ * bottom → above y, default alphabetic → ascent above / descent below). The
+ * caller transforms this box to device space via `transformedBox`. start/end are
+ * treated as left/right (ltr assumption) — over-covering on rtl is harmless.
+ */
+export function textLocalBox(i) {
+    let left = i.x;
+    const align = i.align ?? "start";
+    if (align === "center")
+        left = i.x - i.width / 2;
+    else if (align === "right" || align === "end")
+        left = i.x - i.width;
+    const right = left + i.width;
+    const a = i.ascent, d = i.descent, h = a + d;
+    let top, bottom;
+    switch (i.baseline) {
+        case "top":
+        case "hanging":
+            top = i.y;
+            bottom = i.y + h;
+            break;
+        case "middle":
+            top = i.y - h / 2;
+            bottom = i.y + h / 2;
+            break;
+        case "bottom":
+        case "ideographic":
+            top = i.y - h;
+            bottom = i.y;
+            break;
+        default:
+            top = i.y - a;
+            bottom = i.y + d;
+            break; // alphabetic (default)
+    }
+    return { x0: left, y0: top, x1: right, y1: bottom };
+}
+/** Device-space AABB of a drawn-text box — measure (text-local) then transform.
+ * `pad` (device px) should be font-size-proportional at the call site: the box is
+ * built from the glyphs' ADVANCE width, but italic / script / emoji ink overhangs
+ * the advance (side bearings), so a 1px pad would under-cover and leak a sliver on
+ * the keyframe. Over-covering is privacy-safe. */
+export function textRegion(i, m, pad = 1) {
+    const b = textLocalBox(i);
+    return transformedBox(b.x0, b.y0, b.x1, b.y1, m, pad);
+}

package/dist/canvas/codec.js

@@ -0,0 +1,314 @@
+/** Stable opcode table: union of 2D methods, tracked props, and meta ops. */
+export const OPCODES = [
+    "__frame", "__create", "__objcall",
+    // methods
+    "arc", "arcTo", "beginPath", "bezierCurveTo", "clearRect", "clip", "closePath",
+    "drawImage", "ellipse", "fill", "fillRect", "fillText", "lineTo", "moveTo",
+    "putImageData", "quadraticCurveTo", "rect", "reset", "resetTransform", "restore",
+    "rotate", "roundRect", "save", "scale", "setLineDash", "setTransform", "stroke",
+    "strokeRect", "strokeText", "transform", "translate", "drawFocusIfNeeded",
+    // tracked props (setter ops)
+    "fillStyle", "strokeStyle", "globalAlpha", "globalCompositeOperation",
+    "lineWidth", "lineCap", "lineJoin", "miterLimit", "lineDashOffset",
+    "font", "textAlign", "textBaseline", "direction",
+    "shadowBlur", "shadowColor", "shadowOffsetX", "shadowOffsetY",
+    "imageSmoothingEnabled", "imageSmoothingQuality", "filter", "letterSpacing", "wordSpacing",
+    // hot WebGL ops (rare ones ride the string-table fallback)
+    "useProgram", "bindBuffer", "bindTexture", "bindVertexArray", "bindFramebuffer",
+    "bufferData", "bufferSubData", "uniform1f", "uniform1i", "uniform2f", "uniform3f",
+    "uniform4f", "uniform1fv", "uniform2fv", "uniform3fv", "uniform4fv",
+    "uniformMatrix3fv", "uniformMatrix4fv", "vertexAttribPointer", "enableVertexAttribArray",
+    "drawArrays", "drawElements", "drawArraysInstanced", "drawElementsInstanced",
+    "enable", "disable", "depthFunc", "depthMask", "blendFunc", "blendFuncSeparate",
+    "blendEquation", "cullFace", "frontFace", "viewport", "scissor", "clearColor",
+    "clearDepth", "clearStencil", "activeTexture", "texParameteri", "texImage2D",
+    "texSubImage2D", "pixelStorei", "colorMask", "stencilFunc", "stencilOp", "stencilMask",
+    "polygonOffset",
+    // meta: per-op draw-site stamp marker (Phase 3b)
+    "__site",
+];
+const OP_INDEX = new Map(OPCODES.map((o, i) => [o, i]));
+const OP_UNKNOWN = 255;
+const SETTER_BIT = 0x80; // ops fit in 7 bits; high bit marks property-set
+// arg tags
+const T_F64 = 0, T_VARINT = 1, T_STR = 2, T_STR_REF = 3, T_TRUE = 4, T_FALSE = 5, T_NULL = 6, T_ASSET = 7, T_OBJ = 8, T_ARR = 9, T_IMAGEDATA = 10, T_UNSUPPORTED = 11, T_TYPED = 12;
+class ByteWriter {
+    buf = new Uint8Array(64 * 1024);
+    len = 0;
+    view = new DataView(this.buf.buffer);
+    ensure(n) {
+        if (this.len + n <= this.buf.length)
+            return;
+        const next = new Uint8Array(Math.max(this.buf.length * 2, this.len + n));
+        next.set(this.buf.subarray(0, this.len));
+        this.buf = next;
+        this.view = new DataView(next.buffer);
+    }
+    u8(v) { this.ensure(1); this.buf[this.len++] = v & 0xff; }
+    varint(v) {
+        // zigzag for possibly-negative ints
+        let z = v < 0 ? -v * 2 - 1 : v * 2;
+        this.ensure(10);
+        while (z >= 0x80) {
+            this.buf[this.len++] = (z & 0x7f) | 0x80;
+            z = Math.floor(z / 128);
+        }
+        this.buf[this.len++] = z;
+    }
+    f64(v) { this.ensure(8); this.view.setFloat64(this.len, v, true); this.len += 8; }
+    bytes(b) { this.ensure(b.length); this.buf.set(b, this.len); this.len += b.length; }
+    take() { const out = this.buf.slice(0, this.len); this.len = 0; return out; }
+    get size() { return this.len; }
+}
+class ByteReader {
+    buf;
+    view;
+    pos = 0;
+    constructor(buf) {
+        this.buf = buf;
+        this.view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+    }
+    get done() { return this.pos >= this.buf.length; }
+    u8() { return this.buf[this.pos++]; }
+    varint() {
+        let shift = 1, z = 0, b;
+        do {
+            b = this.buf[this.pos++];
+            z += (b & 0x7f) * shift;
+            shift *= 128;
+        } while (b & 0x80);
+        return z % 2 === 1 ? -(z + 1) / 2 : z / 2;
+    }
+    f64() { const v = this.view.getFloat64(this.pos, true); this.pos += 8; return v; }
+    bytes(n) { const b = this.buf.subarray(this.pos, this.pos + n); this.pos += n; return b; }
+}
+const utf8e = new TextEncoder();
+const utf8d = new TextDecoder();
+export class CommandEncoder {
+    w = new ByteWriter();
+    strings = new Map();
+    lastTUs = 0;
+    /** count of ops in current batch */
+    ops = 0;
+    encode(op) {
+        // frame/time delta marker whenever timestamp advances. Deltas are between
+        // ROUNDED absolute µs values so rounding error never accumulates.
+        const tUs = Math.round(op.t * 1000);
+        if (tUs !== this.lastTUs) {
+            this.w.u8(OP_INDEX.get("__frame"));
+            this.w.varint(tUs - this.lastTUs);
+            this.lastTUs = tUs;
+        }
+        if (op.sfId) {
+            this.w.u8(OP_INDEX.get("__site"));
+            this.str(op.sfId);
+        }
+        const code = OP_INDEX.get(op.op);
+        if (code === undefined) {
+            this.w.u8(OP_UNKNOWN);
+            this.str(op.op);
+        }
+        else {
+            this.w.u8(op.setter ? code | SETTER_BIT : code);
+        }
+        this.w.varint(op.args.length);
+        for (const a of op.args)
+            this.arg(a);
+        this.ops++;
+    }
+    str(s) {
+        const ref = this.strings.get(s);
+        if (ref !== undefined) {
+            this.w.u8(T_STR_REF);
+            this.w.varint(ref);
+            return;
+        }
+        const id = this.strings.size;
+        this.strings.set(s, id);
+        const b = utf8e.encode(s);
+        this.w.u8(T_STR);
+        this.w.varint(b.length);
+        this.w.bytes(b);
+    }
+    arg(a) {
+        if (a === null) {
+            this.w.u8(T_NULL);
+            return;
+        }
+        switch (typeof a) {
+            case "number":
+                if (Number.isInteger(a) && Math.abs(a) < 2 ** 30) {
+                    this.w.u8(T_VARINT);
+                    this.w.varint(a);
+                }
+                else {
+                    this.w.u8(T_F64);
+                    this.w.f64(a);
+                }
+                return;
+            case "string":
+                this.str(a);
+                return;
+            case "boolean":
+                this.w.u8(a ? T_TRUE : T_FALSE);
+                return;
+        }
+        if ("$" in a) {
+            switch (a.$) {
+                case "asset":
+                    this.w.u8(T_ASSET);
+                    this.w.varint(a.id);
+                    return;
+                case "obj":
+                    this.w.u8(T_OBJ);
+                    this.w.varint(a.id);
+                    return;
+                case "imagedata":
+                    this.w.u8(T_IMAGEDATA);
+                    this.w.varint(a.id);
+                    return;
+                case "arr":
+                    this.w.u8(T_ARR);
+                    this.w.varint(a.v.length);
+                    for (const n of a.v)
+                        this.w.f64(n);
+                    return;
+                case "ta":
+                    this.w.u8(T_TYPED);
+                    this.w.u8(a.k);
+                    this.w.varint(a.b.length);
+                    this.w.bytes(a.b);
+                    return;
+                case "unsupported":
+                    this.w.u8(T_UNSUPPORTED);
+                    this.str(a.kind);
+                    return;
+            }
+        }
+        this.w.u8(T_NULL);
+    }
+    /** Flush current batch as raw (uncompressed) bytes. */
+    takeBatch() {
+        this.ops = 0;
+        // [audit B2] Reset the string table + time base so EACH batch is
+        // SELF-CONTAINED. Batches are flushed, persisted, and DROPPED independently —
+        // both the durable store (canvasFrameStore.pruneToBudget) and the memory ring
+        // (websocket pushBinaryRing) evict the OLDEST buffered frames under pressure,
+        // i.e. interior command batches. If string-refs or time-deltas spanned
+        // batches, one dropped interior batch would desync the string table and clock
+        // of every batch after it (wrong colors/fonts, mis-attributed click-to-code,
+        // ops anchored to the wrong keyframe). Self-contained batches re-emit a few
+        // strings per flush + an absolute time anchor — a small cost for decode that
+        // is robust to gaps / loss / reorder. (decodeCommands resets per batch too.)
+        this.strings.clear();
+        this.lastTUs = 0;
+        return this.w.take();
+    }
+}
+export function decodeCommands(batches) {
+    const ops = [];
+    for (const batch of batches) {
+        // [audit B2] Each batch is self-contained — its own string table + absolute
+        // time anchor — so a dropped/pruned/corrupt batch can't skew the string-refs
+        // or timestamps of any other batch. (The encoder resets both per takeBatch.)
+        const strings = [];
+        let t = 0;
+        const r = new ByteReader(batch);
+        const readStr = () => {
+            const tag = r.u8();
+            if (tag === T_STR_REF)
+                return strings[r.varint()];
+            const len = r.varint();
+            const s = utf8d.decode(r.bytes(len));
+            strings.push(s);
+            return s;
+        };
+        const readArg = () => {
+            const tag = r.u8();
+            switch (tag) {
+                case T_F64: return r.f64();
+                case T_VARINT: return r.varint();
+                case T_STR:
+                case T_STR_REF: {
+                    r.pos--;
+                    return readStr();
+                }
+                case T_TRUE: return true;
+                case T_FALSE: return false;
+                case T_NULL: return null;
+                case T_ASSET: return { $: "asset", id: r.varint() };
+                case T_OBJ: return { $: "obj", id: r.varint() };
+                case T_IMAGEDATA: return { $: "imagedata", id: r.varint() };
+                case T_ARR: {
+                    const n = r.varint();
+                    const v = [];
+                    for (let i = 0; i < n; i++)
+                        v.push(r.f64());
+                    return { $: "arr", v };
+                }
+                case T_TYPED: {
+                    const k = r.u8();
+                    const len = r.varint();
+                    return { $: "ta", k, b: r.bytes(len).slice(0) };
+                }
+                case T_UNSUPPORTED: return { $: "unsupported", kind: readStr() };
+                default: return null;
+            }
+        };
+        let pendingSfId;
+        while (!r.done) {
+            const raw = r.u8();
+            if ((raw & 0x7f) === OP_INDEX.get("__frame") && !(raw & SETTER_BIT)) {
+                t += r.varint() / 1000;
+                continue;
+            }
+            if ((raw & 0x7f) === OP_INDEX.get("__site") && !(raw & SETTER_BIT)) {
+                pendingSfId = readStr();
+                continue;
+            }
+            let opName;
+            let setter = false;
+            if (raw === OP_UNKNOWN) {
+                opName = readStr();
+            }
+            else {
+                setter = !!(raw & SETTER_BIT);
+                opName = OPCODES[raw & 0x7f] ?? `op${raw & 0x7f}`;
+            }
+            const argc = r.varint();
+            const args = [];
+            for (let i = 0; i < argc; i++)
+                args.push(readArg());
+            const op = { t, op: opName, args };
+            if (pendingSfId !== undefined) {
+                op.sfId = pendingSfId;
+                pendingSfId = undefined;
+            }
+            if (setter)
+                op.setter = true;
+            if (opName === "__create")
+                op.create = true;
+            if (opName === "__objcall")
+                op.objcall = true;
+            ops.push(op);
+        }
+    }
+    return ops;
+}
+// Port adaptation: the bench piped through Blob.stream(); writing directly to
+// the (De)CompressionStream produces identical bytes and also works in
+// environments whose Blob lacks .stream() (e.g. jsdom). Identical wire format.
+async function pipeThrough(ts, data) {
+    const copy = new Uint8Array(data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength));
+    const consumed = new Response(ts.readable).arrayBuffer();
+    const writer = ts.writable.getWriter();
+    await writer.write(copy);
+    await writer.close();
+    return new Uint8Array(await consumed);
+}
+export async function deflate(data) {
+    return pipeThrough(new CompressionStream("deflate"), data);
+}
+export async function inflate(data) {
+    return pipeThrough(new DecompressionStream("deflate"), data);
+}

package/dist/canvas/deviceClass.js

@@ -0,0 +1,67 @@
+const MiB = 1024 * 1024;
+/** Desktop default — preserves the pre-A30 budgets exactly. */
+export const DESKTOP_BUDGETS = {
+    deviceClass: "desktop",
+    sessionByteBudget: 256 * MiB,
+    maxConcurrentVideo: 4,
+    governor: {},
+    preferMediaRecorder: false,
+};
+const MOBILE_BUDGETS = {
+    deviceClass: "mobile",
+    sessionByteBudget: 96 * MiB,
+    maxConcurrentVideo: 2,
+    governor: { maxBytesPerSec: 256 * 1024, maxOpsPerFrame: 3_000 },
+    preferMediaRecorder: false,
+};
+const MOBILE_LOWEND_BUDGETS = {
+    deviceClass: "mobile-lowend",
+    sessionByteBudget: 48 * MiB,
+    maxConcurrentVideo: 1,
+    governor: { maxBytesPerSec: 128 * 1024, maxOpsPerFrame: 2_000, maxVideoDrawsPerSec: 1 },
+    preferMediaRecorder: false,
+};
+/** Explicit iOS UA (iPhone / iPad / iPod). WebCodecs is unreliable/absent on
+ * older iOS, so these prefer the MediaRecorder backend. */
+function isExplicitIOS(n) {
+    return /iPhone|iPad|iPod/.test(n.userAgent ?? "");
+}
+/** iPadOS that reports a desktop "Macintosh" UA but exposes touch points. Treated
+ * as a MOBILE device for budgets, but NOT forced onto MediaRecorder: a genuine
+ * touch-screen Mac would false-positive this brittle heuristic and has perfectly
+ * good WebCodecs, and modern iPadOS WebCodecs is usable too. [audit A30-ipad] */
+function isIPadDesktopUA(n) {
+    return /Macintosh/.test(n.userAgent ?? "") && (n.maxTouchPoints ?? 0) > 1;
+}
+function isMobileUA(n) {
+    return /Mobi|Android|iPhone|iPad|iPod/.test(n.userAgent ?? "") || isIPadDesktopUA(n);
+}
+/**
+ * Resolve device budgets. Pass `nav` in tests; in the browser it defaults to the
+ * global `navigator`; under SSR (no navigator) it returns the desktop profile.
+ */
+export function resolveDeviceBudgets(nav) {
+    const n = nav ?? (typeof navigator !== "undefined" ? navigator : undefined);
+    if (!n)
+        return DESKTOP_BUDGETS;
+    const mem = n.deviceMemory;
+    const cores = n.hardwareConcurrency;
+    const lowMem = typeof mem === "number" && mem <= 2;
+    const lowCores = typeof cores === "number" && cores <= 4;
+    const ios = isExplicitIOS(n); // only explicit iOS forces MediaRecorder
+    let base;
+    if (isMobileUA(n)) {
+        // Low-end only when BOTH signals are constrained. A normal phone that reports
+        // 4 cores (or no deviceMemory at all, e.g. Safari) must NOT be forced to the
+        // harshest 48 MiB / single-encoder tier. [audit A30-cores]
+        base = lowMem && lowCores ? MOBILE_LOWEND_BUDGETS : MOBILE_BUDGETS;
+    }
+    else if (lowMem && lowCores) {
+        base = MOBILE_LOWEND_BUDGETS; // constrained desktop / VM / low-end laptop
+    }
+    else {
+        base = DESKTOP_BUDGETS;
+    }
+    // iOS prefers MediaRecorder regardless of tier (WebCodecs unreliable there).
+    return ios ? { ...base, preferMediaRecorder: true } : base;
+}