@sailfish-ai/recorder 1.12.5 → 1.12.7

package/dist/canvas/patchWebGPU.js

@@ -0,0 +1,361 @@
+/**
+ * WebGPU command capture via object-graph proxying — capture-side port of the
+ * validated bench core (test-applications/canvas-recorder-bench/src/capture/
+ * patchWebGPU.ts; webgpu_recorder lineage). navigator.gpu and every object
+ * reachable from it (adapter, device, queue, encoders, pipelines, textures,
+ * views...) are wrapped in recording proxies. Method calls/property hops are
+ * logged as meta-ops with interned result ids; descriptors serialize as JSON
+ * with {__sfRef} markers for object references; buffer payloads ride the
+ * typed-array tag.
+ *
+ * Replay (player-side, NOT ported here) re-executes the op list against a
+ * fresh adapter/device with the recorded canvas context bound to the replay
+ * target. Deterministic on the same GPU; pixel keyframes remain the bit-exact
+ * truth (hybrid).
+ *
+ * SDK adaptations: SSR-safe installation, DiscardSink short-circuit (video
+ * demotion keeps dirtiness with zero serialize cost), swapGPUSink for the
+ * manager, replayGPU dropped (player concern).
+ */
+import { DIRTY_OP, DiscardSink } from "./protocol";
+import { BufferSink, serializeTypedArray, TYPED_ARRAY_KINDS } from "./protocol";
+/** Cap a single serialized buffer payload (writeBuffer/writeTexture data, nested
+ * descriptor arrays) so one big upload can't push a frame past the 8 MiB
+ * transport cap (canvasManager MAX_FRAME_BYTES) — which would DROP THE WHOLE
+ * frame (draws + submit), breaking replay/pick. Mirror patchGL's texture cap:
+ * report `buffer-too-large` and degrade that frame to a keyframe. [audit HIGH] */
+const MAX_GPU_RAW_BYTES = 7 * 1024 * 1024;
+const OP_ROOT = "__gpuroot";
+const OP_CTX = "__gpuctx";
+const OP_CALL = "__gpu";
+const OP_PROP = "__gpuprop";
+let installed = false;
+let autoConfig = null;
+/**
+ * A10 (WebGPU) — device-loss notifier. WebGPU has no contextlost event; instead
+ * each GPUDevice exposes a `lost` promise that resolves when the device is lost
+ * (and is never re-created — the app must request a new device). The manager
+ * registers a callback here; we resolve it the first time any recorded device's
+ * `lost` promise settles, and again (with restored=true) once a NEW device is
+ * acquired afterwards. `reason === "destroyed"` (explicit device.destroy()) is
+ * NOT a loss to recover from and is ignored.
+ */
+let deviceLostNotify = null;
+let sawDeviceAfterLoss = false;
+let deviceLostFired = false;
+export function setGPUDeviceLostNotifier(fn) {
+    deviceLostNotify = fn;
+    sawDeviceAfterLoss = false;
+    deviceLostFired = false;
+}
+function watchDeviceLost(device) {
+    const lost = device.lost;
+    if (!lost || typeof lost.then !== "function")
+        return;
+    // A NEW device after a prior loss = the app recovered.
+    if (deviceLostFired && !sawDeviceAfterLoss) {
+        sawDeviceAfterLoss = true;
+        try {
+            deviceLostNotify?.(false);
+        }
+        catch { /* never break host app */ }
+    }
+    lost.then((info) => {
+        // Explicit destroy() is intentional teardown, not a recoverable loss.
+        if (info && info.reason === "destroyed")
+            return;
+        if (deviceLostFired)
+            return;
+        deviceLostFired = true;
+        try {
+            deviceLostNotify?.(true);
+        }
+        catch { /* never break host app */ }
+    }).catch(() => { });
+}
+/** single global stream — WebGPU's object graph is page-scoped, not per-canvas */
+let sink = null;
+let nowFn = () => 0;
+let cpu = 0;
+// 3M base keeps WebGPU object ids clear of patchGL's object (1M) and asset (2M)
+// ranges, so the two recorders' ids never collide if a stream is ever merged. [audit LOW]
+let nextId = 3_000_000;
+let rootEmitted = false;
+let recordedCanvas = null;
+let attachedCanvas = null;
+const idOf = new WeakMap();
+const proxyOf = new WeakMap();
+const targetOf = new WeakMap();
+function emit(op) {
+    sink?.onOp(op);
+}
+function intern(obj) {
+    let id = idOf.get(obj);
+    if (id === undefined) {
+        id = nextId++;
+        idOf.set(obj, id);
+    }
+    return id;
+}
+function deproxy(v) {
+    if (v && typeof v === "object" && targetOf.has(v))
+        return targetOf.get(v);
+    return v;
+}
+/**
+ * WebIDL brand checks reject Proxy-wrapped platform objects, including ones
+ * NESTED inside descriptors ({device}, {layout}, render-pass views...) —
+ * native calls need the real objects all the way down.
+ */
+function deepDeproxy(v) {
+    if (!v || typeof v !== "object")
+        return v;
+    if (targetOf.has(v))
+        return targetOf.get(v);
+    if (ArrayBuffer.isView(v) || v instanceof ArrayBuffer)
+        return v;
+    if (Array.isArray(v)) {
+        let changed = false;
+        const out = v.map((x) => {
+            const d = deepDeproxy(x);
+            if (d !== x)
+                changed = true;
+            return d;
+        });
+        return changed ? out : v;
+    }
+    const proto = Object.getPrototypeOf(v);
+    if (proto === Object.prototype || proto === null) {
+        let changed = false;
+        const out = {};
+        for (const [k, val] of Object.entries(v)) {
+            const d = deepDeproxy(val);
+            if (d !== val)
+                changed = true;
+            out[k] = d;
+        }
+        return changed ? out : v;
+    }
+    return v;
+}
+// SerializedArg has no dedicated descriptor variant; descriptors are carried
+// as a string arg prefixed so replay can tell them from plain strings.
+const JSON_PREFIX = "json:";
+function serializeGPUArg(a) {
+    if (a === null || a === undefined)
+        return null;
+    switch (typeof a) {
+        case "number": return Number.isFinite(a) ? a : 0;
+        case "string": return a;
+        case "boolean": return a;
+        case "object": break;
+        default: return { $: "unsupported", kind: typeof a };
+    }
+    const raw = deproxy(a);
+    if (ArrayBuffer.isView(raw) || raw instanceof ArrayBuffer) {
+        if (raw.byteLength > MAX_GPU_RAW_BYTES) {
+            return { $: "unsupported", kind: "buffer-too-large" };
+        }
+        return serializeTypedArray(raw);
+    }
+    const ref = idOf.get(raw);
+    if (ref !== undefined)
+        return { $: "obj", id: ref };
+    // descriptor object/array: JSON with embedded object refs
+    try {
+        const json = JSON.stringify(raw, (_k, v) => {
+            if (v && typeof v === "object") {
+                const t = deproxy(v);
+                const r = idOf.get(t);
+                if (r !== undefined)
+                    return { __sfRef: r };
+                if (ArrayBuffer.isView(t)) {
+                    const view = t;
+                    if (view.byteLength > MAX_GPU_RAW_BYTES)
+                        return { __sfUnsupported: "buffer-too-large" };
+                    // Tag the element kind so the player reconstructs the EXACT typed-array
+                    // type (else an integer array is corrupted to Float32). [audit MEDIUM]
+                    const k = TYPED_ARRAY_KINDS.findIndex((c) => view instanceof c);
+                    if (k < 0)
+                        return { __sfUnsupported: "typed-array-kind" }; // BigInt64Array etc.
+                    return { __sfTa: Array.from(view), __sfK: k };
+                }
+                return t === v ? v : t;
+            }
+            return v;
+        });
+        return JSON_PREFIX + json;
+    }
+    catch {
+        return { $: "unsupported", kind: raw.constructor?.name ?? "object" };
+    }
+}
+const serializeArgWire = serializeGPUArg;
+function shouldProxyResult(v) {
+    if (!v || typeof v !== "object")
+        return false;
+    const name = v.constructor?.name ?? "";
+    return name.startsWith("GPU");
+}
+function wrap(obj) {
+    const existing = proxyOf.get(obj);
+    if (existing)
+        return existing;
+    // A10: arm device-loss watching the first time we wrap a GPUDevice.
+    if (obj.constructor?.name === "GPUDevice") {
+        watchDeviceLost(obj);
+    }
+    const proxy = new Proxy(obj, {
+        get(target, prop, _receiver) {
+            const v = Reflect.get(target, prop, target);
+            if (typeof prop === "symbol")
+                return v;
+            if (typeof v === "function") {
+                return (...args) => {
+                    const t0 = performance.now();
+                    const nativeArgs = args.map(deepDeproxy);
+                    const result = v.apply(target, nativeArgs);
+                    if (sink instanceof DiscardSink) {
+                        // Video-mode dirtiness only: keep wrapping for graph consistency,
+                        // skip serialization + emission entirely.
+                        sink.onOp(DIRTY_OP);
+                        if (result && typeof result === "object" && typeof result.then === "function") {
+                            return result.then((val) => val && typeof val === "object" && shouldProxyResult(val) ? (intern(val), wrap(val)) : val);
+                        }
+                        return shouldProxyResult(result) ? (intern(result), wrap(result)) : result;
+                    }
+                    if (sink) {
+                        const tId = intern(target);
+                        if (result && typeof result === "object" && typeof result.then === "function") {
+                            const rid = nextId++;
+                            emit({
+                                t: nowFn(), op: OP_CALL, objcall: true,
+                                args: [tId, String(prop), rid, ...args.map(serializeArgWire)],
+                            });
+                            cpu += performance.now() - t0;
+                            return result.then((val) => {
+                                if (val && typeof val === "object") {
+                                    idOf.set(val, rid);
+                                    return wrap(val);
+                                }
+                                return val;
+                            });
+                        }
+                        let rid = 0;
+                        if (shouldProxyResult(result))
+                            rid = intern(result);
+                        emit({
+                            t: nowFn(), op: OP_CALL, objcall: true,
+                            args: [tId, String(prop), rid, ...args.map(serializeArgWire)],
+                        });
+                        cpu += performance.now() - t0;
+                        if (shouldProxyResult(result))
+                            return wrap(result);
+                        return result;
+                    }
+                    if (result && typeof result === "object" && typeof result.then === "function") {
+                        return result.then((val) => val && typeof val === "object" && shouldProxyResult(val) ? (intern(val), wrap(val)) : val);
+                    }
+                    return shouldProxyResult(result) ? (intern(result), wrap(result)) : result;
+                };
+            }
+            if (shouldProxyResult(v)) {
+                const known = idOf.has(v);
+                const rid = intern(v);
+                if (!known && sink && !(sink instanceof DiscardSink)) {
+                    emit({ t: nowFn(), op: OP_PROP, objcall: true, args: [intern(target), String(prop), rid] });
+                }
+                return wrap(v);
+            }
+            return v;
+        },
+    });
+    proxyOf.set(obj, proxy);
+    targetOf.set(proxy, obj);
+    return proxy;
+}
+export function setGPUAutoAttach(config) {
+    autoConfig = config;
+    if (config) {
+        nowFn = config.now;
+        if (!sink) {
+            sink = new BufferSink();
+            rootEmitted = false;
+        }
+    }
+}
+export function pruneUnboundGPURecorders() {
+    if (sink instanceof BufferSink && !attachedCanvas) {
+        if (!recordedCanvas)
+            sink = null; // nothing GPU happened this run
+    }
+}
+/** The canvas (if any) that created a webgpu context while armed. */
+export function getGPURecordedCanvas() {
+    return recordedCanvas;
+}
+export function installGPUHooks() {
+    if (installed)
+        return;
+    installed = true;
+    if (typeof navigator === "undefined" || !("gpu" in navigator))
+        return;
+    const realGpu = navigator.gpu;
+    Object.defineProperty(navigator, "gpu", {
+        configurable: true,
+        get() {
+            if (autoConfig || sink) {
+                if (!rootEmitted) {
+                    rootEmitted = true;
+                    const rid = intern(realGpu);
+                    emit({ t: nowFn(), op: OP_ROOT, args: [rid] });
+                }
+                return wrap(realGpu);
+            }
+            return realGpu;
+        },
+    });
+    // canvas.getContext('webgpu') -> proxied context (chained over prior patches)
+    if (typeof HTMLCanvasElement === "undefined")
+        return;
+    const origGetContext = HTMLCanvasElement.prototype.getContext;
+    HTMLCanvasElement.prototype.getContext = function (type, attrs) {
+        const result = origGetContext.call(this, type, attrs);
+        if (type === "webgpu" && result && (autoConfig || sink)) {
+            recordedCanvas = this;
+            const known = idOf.has(result);
+            const rid = intern(result);
+            if (!known)
+                emit({ t: nowFn(), op: OP_CTX, args: [rid] });
+            return wrap(result);
+        }
+        return result;
+    };
+}
+export function attachGPURecorder(canvas, strategySink, now) {
+    if (recordedCanvas !== canvas || !sink)
+        return null;
+    attachedCanvas = canvas;
+    nowFn = now;
+    const buffered = sink;
+    sink = strategySink;
+    if (buffered instanceof BufferSink) {
+        for (const op of buffered.ops)
+            strategySink.onOp(op);
+        for (const n of buffered.notes)
+            strategySink.note(n);
+    }
+    return {
+        detach() {
+            sink = null;
+            attachedCanvas = null;
+            recordedCanvas = null;
+        },
+        cpuMs: () => cpu,
+    };
+}
+/** Swap the page-global GPU sink (manager demotion path). */
+export function swapGPUSink(s) {
+    if (sink)
+        sink = s;
+}

package/dist/canvas/piiDetect.js

@@ -0,0 +1,155 @@
+/**
+ * A13 — content-level PII detection + redaction shared between the rrweb input
+ * masker (`maskInputFn` in recording.tsx) and the canvas text path
+ * (`canvasPrivacy.ts`). Extracted so both call sites use ONE implementation of
+ * the credit-card / SSN / DOB detectors and their partial-mask formats.
+ *
+ * The "record*" flags are INVERTED privacy intent: `recordCreditCardInfo:false`
+ * means "do NOT record credit-card content" → redact it. A flag that is TRUE
+ * (or undefined → treated as record-everything for that type) leaves the
+ * matching content untouched. This mirrors the historical maskInputFn behavior,
+ * which always partial-masked detected CC/SSN content regardless of flags; here
+ * the canvas path gates on the flags so an account that explicitly opts INTO
+ * recording a PII type is honored.
+ *
+ * SSR rule: pure string functions, no window/document/navigator access. Safe to
+ * import at module scope anywhere.
+ */
+// ─── Detection patterns ──────────────────────────────────────────────────────
+/**
+ * 13–16 digit run, optionally separated by spaces/hyphens (matching the
+ * historical `maskInputFn` pattern). This is a CANDIDATE matcher only — a bare
+ * 16-digit number (a phone number, order id, SKU…) also matches, so callers
+ * combine it with `passesLuhn` to cut false positives.
+ */
+/** Cheap pre-check: PII detection can be skipped entirely for digit-free text. */
+const HAS_DIGIT = /\d/;
+const CREDIT_CARD_CANDIDATE = /\b(?:\d[ -]*?){13,16}\b/;
+const SSN_PATTERN = /\b\d{3}-\d{2}-\d{4}\b/;
+/**
+ * Date-of-birth: 1–2 digit day/month, a `/`, `-`, or `.` separator, and a 2–4
+ * digit year. Deliberately permissive (m/d/y and d/m/y both match) — this is a
+ * privacy backstop, not a calendar validator. Does NOT match an SSN (which uses
+ * the 3-2-4 grouping with hyphens only and is caught first by the SSN rule).
+ */
+const DOB_PATTERN = /\b\d{1,2}[/\-.]\d{1,2}[/\-.]\d{2,4}\b/;
+/** Global variants for multi-match redaction within a single string. */
+const CREDIT_CARD_CANDIDATE_G = /\b(?:\d[ -]*?){13,16}\b/g;
+const SSN_PATTERN_G = /\b\d{3}-\d{2}-\d{4}\b/g;
+const DOB_PATTERN_G = /\b\d{1,2}[/\-.]\d{1,2}[/\-.]\d{2,4}\b/g;
+/**
+ * Luhn checksum over the digits of a candidate credit-card string. Accepts the
+ * raw matched substring (may contain spaces/hyphens) OR a pre-stripped digit
+ * string. Returns false for anything without 13–16 digits so non-card numbers
+ * (phones, SKUs) that happen to match the candidate regex are rejected.
+ */
+export function passesLuhn(digits) {
+    // Strip any non-digit separators the candidate matcher allowed through.
+    let only = "";
+    for (let i = 0; i < digits.length; i++) {
+        const c = digits.charCodeAt(i);
+        if (c >= 48 && c <= 57)
+            only += digits[i];
+    }
+    const len = only.length;
+    if (len < 13 || len > 16)
+        return false;
+    let sum = 0;
+    let dbl = false;
+    // Walk right-to-left, doubling every second digit (Luhn).
+    for (let i = len - 1; i >= 0; i--) {
+        let d = only.charCodeAt(i) - 48;
+        if (dbl) {
+            d *= 2;
+            if (d > 9)
+                d -= 9;
+        }
+        sum += d;
+        dbl = !dbl;
+    }
+    return sum % 10 === 0;
+}
+/**
+ * True when `s` contains a 13–16 digit run that ALSO passes the Luhn check.
+ * The Luhn gate removes the vast majority of false positives (phone numbers,
+ * order ids) the bare digit-run regex would otherwise flag.
+ */
+export function looksLikeCreditCard(s) {
+    if (typeof s !== "string")
+        return false;
+    CREDIT_CARD_CANDIDATE_G.lastIndex = 0;
+    let m;
+    while ((m = CREDIT_CARD_CANDIDATE_G.exec(s)) !== null) {
+        if (passesLuhn(m[0]))
+            return true;
+        // Avoid an infinite loop on a zero-width match (cannot happen for this
+        // pattern, but defensive).
+        if (m.index === CREDIT_CARD_CANDIDATE_G.lastIndex)
+            CREDIT_CARD_CANDIDATE_G.lastIndex++;
+    }
+    return false;
+}
+/** True when `s` contains a `NNN-NN-NNNN` SSN-formatted run. */
+export function looksLikeSsn(s) {
+    if (typeof s !== "string")
+        return false;
+    return SSN_PATTERN.test(s);
+}
+/** True when `s` contains a `D/M/Y`-style date (any of `/ - .` separators). */
+export function looksLikeDob(s) {
+    if (typeof s !== "string")
+        return false;
+    return DOB_PATTERN.test(s);
+}
+// ─── Partial-mask formats (player-readable, length-stable-ish) ───────────────
+/** "**** **** **** "+last4 — the historical maskInputFn credit-card format. */
+export function redactCreditCard(s) {
+    return "**** **** **** " + s.slice(-4);
+}
+/** "***-**-"+last4 — the historical maskInputFn SSN format. */
+export function redactSsn(s) {
+    return "***-**-" + s.slice(-4);
+}
+/** DOB partial mask: two masked groups + "/" + last 4 chars. */
+export function redactDob(s) {
+    return "**/**/" + s.slice(-4);
+}
+/**
+ * Apply the partial-mask redactions to every PII match in `text`, but ONLY for
+ * the flags that are explicitly FALSE (privacy intent: "do not record this PII
+ * type"). A flag that is `true` or `undefined` leaves that PII type intact.
+ * Returns the original string when nothing matched or every relevant flag is on.
+ *
+ * Each enabled redactor replaces ALL of its matches in the string (a line like
+ * "DOB 01/02/1990 card 4111 1111 1111 1111" redacts both). Order:
+ * credit-card → SSN → DOB so a CC's internal digits are masked before the DOB
+ * pass scans (the partial-mask output contains no date-shaped runs).
+ */
+export function redactSensitiveContent(text, flags) {
+    if (typeof text !== "string" || text.length === 0)
+        return text;
+    // Hot-path fast-out: every PII pattern (CC/SSN/DOB) requires digits, so a
+    // string with no digit can never match. This keeps the THREE regex passes off
+    // the common case — chart labels, axis titles, button captions — which the 2D
+    // text path hits on every fillText/strokeText (respects the A34 hot-path work).
+    if (!HAS_DIGIT.test(text))
+        return text;
+    let out = text;
+    // Credit cards: replace each Luhn-valid candidate run.
+    if (flags.recordCreditCardInfo === false) {
+        CREDIT_CARD_CANDIDATE_G.lastIndex = 0;
+        out = out.replace(CREDIT_CARD_CANDIDATE_G, (match) => passesLuhn(match) ? redactCreditCard(match) : match);
+    }
+    // SSNs.
+    if (flags.recordSsn === false) {
+        SSN_PATTERN_G.lastIndex = 0;
+        out = out.replace(SSN_PATTERN_G, (match) => redactSsn(match));
+    }
+    // DOBs. Run last so the asterisk output of the CC/SSN passes (which contains
+    // no date-shaped digit runs) is never re-scanned into a DOB false positive.
+    if (flags.recordDob === false) {
+        DOB_PATTERN_G.lastIndex = 0;
+        out = out.replace(DOB_PATTERN_G, (match) => redactDob(match));
+    }
+    return out;
+}

package/dist/canvas/protocol.js

@@ -0,0 +1,122 @@
+/**
+ * Shared canvas-recording protocol types + the SFCV binary frame format.
+ *
+ * Types are ported from the validated bench core
+ * (test-applications/canvas-recorder-bench/src/capture/patch2d.ts); the SFCV
+ * frame builder/parser implements the canvas-recording-pipeline contract §1:
+ *
+ *   bytes 0..3   magic "SFC1" (0x53 0x46 0x43 0x31)
+ *   bytes 4..7   u32 LE: headerLen
+ *   bytes 8..    header JSON (utf8, headerLen bytes)
+ *   rest         payload bytes
+ *
+ * SSR rule: nothing in this module touches window/document/navigator at
+ * module scope.
+ */
+export const TYPED_ARRAY_KINDS = [
+    Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array,
+    Int32Array, Uint32Array, Float32Array, Float64Array,
+];
+/** Copy a typed array / ArrayBuffer into a serialized arg AT CALL TIME. */
+export function serializeTypedArray(v) {
+    if (v instanceof ArrayBuffer) {
+        return { $: "ta", k: 1, b: new Uint8Array(v.slice(0)) };
+    }
+    const k = TYPED_ARRAY_KINDS.findIndex((c) => v instanceof c);
+    if (k < 0)
+        return { $: "unsupported", kind: v.constructor?.name ?? "view" };
+    const bytes = new Uint8Array(v.buffer.slice(v.byteOffset, v.byteOffset + v.byteLength));
+    return { $: "ta", k, b: bytes };
+}
+export function deserializeTypedArray(a) {
+    const Ctor = TYPED_ARRAY_KINDS[a.k] ?? Uint8Array;
+    const buf = a.b.buffer.slice(a.b.byteOffset, a.b.byteOffset + a.b.byteLength);
+    return new Ctor(buf);
+}
+export class BufferSink {
+    ops = [];
+    assetEvents = [];
+    assetData = [];
+    notes = [];
+    onOp(op) { this.ops.push(op); }
+    onAssetBytes(id, bytes, t) { this.assetEvents.push({ id, bytes, t }); }
+    onAssetData(info, payload) { this.assetData.push({ info, payload }); }
+    note(m) { if (!this.notes.includes(m))
+        this.notes.push(m); }
+}
+/**
+ * Video-mode dirtiness sink: keeps the patch recorder attached purely to
+ * drive the per-canvas dirty flag — every op is discarded with ZERO
+ * serialize/encode cost (recorders short-circuit on `instanceof DiscardSink`
+ * before serializing arguments).
+ */
+export class DiscardSink {
+    onDirty;
+    constructor(onDirty) {
+        this.onDirty = onDirty;
+    }
+    onOp(_op) { this.onDirty(); }
+    onAssetBytes(_id, _bytes, _t) { }
+    note(_m) { }
+}
+/** Shared zero-cost op handed to DiscardSink (its contents are never read). */
+export const DIRTY_OP = { t: 0, op: "", args: [] };
+const utf8e = new TextEncoder();
+const utf8d = new TextDecoder();
+const MAGIC = [0x53, 0x46, 0x43, 0x31]; // "SFC1"
+export function buildFrame(header, payload) {
+    const payloadBytes = payload == null
+        ? new Uint8Array(0)
+        : payload instanceof ArrayBuffer
+            ? new Uint8Array(payload)
+            : payload;
+    const headerBytes = utf8e.encode(JSON.stringify({ ...header, pLen: payloadBytes.byteLength }));
+    const buf = new ArrayBuffer(8 + headerBytes.length + payloadBytes.byteLength);
+    const u8 = new Uint8Array(buf);
+    u8[0] = MAGIC[0];
+    u8[1] = MAGIC[1];
+    u8[2] = MAGIC[2];
+    u8[3] = MAGIC[3];
+    new DataView(buf).setUint32(4, headerBytes.length, true);
+    u8.set(headerBytes, 8);
+    u8.set(payloadBytes, 8 + headerBytes.length);
+    return buf;
+}
+/** Parse one frame or a concatenation of frames. Throws on corrupt input. */
+export function parseFrames(bytes) {
+    const u8 = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+    const view = new DataView(u8.buffer, u8.byteOffset, u8.byteLength);
+    const frames = [];
+    let pos = 0;
+    while (pos < u8.length) {
+        if (pos + 8 > u8.length)
+            throw new Error(`SFCV: truncated frame at ${pos}`);
+        if (u8[pos] !== MAGIC[0] || u8[pos + 1] !== MAGIC[1] || u8[pos + 2] !== MAGIC[2] || u8[pos + 3] !== MAGIC[3]) {
+            throw new Error(`SFCV: bad magic at ${pos}`);
+        }
+        const headerLen = view.getUint32(pos + 4, true);
+        const headerEnd = pos + 8 + headerLen;
+        if (headerEnd > u8.length)
+            throw new Error(`SFCV: truncated header at ${pos}`);
+        const header = JSON.parse(utf8d.decode(u8.subarray(pos + 8, headerEnd)));
+        if (header.v !== 1)
+            throw new Error(`SFCV: unsupported version ${header.v}`);
+        const pLen = typeof header.pLen === "number" ? header.pLen : u8.length - headerEnd;
+        const payloadEnd = headerEnd + pLen;
+        if (payloadEnd > u8.length)
+            throw new Error(`SFCV: truncated payload at ${pos}`);
+        frames.push({ header, payload: u8.slice(headerEnd, payloadEnd) });
+        pos = payloadEnd;
+    }
+    return frames;
+}
+/** Chunked base64 for ArrayBuffers (video-init decoder descriptions). */
+export function bytesToBase64(bytes) {
+    const u8 = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+    let s = "";
+    const CHUNK = 0x8000;
+    for (let i = 0; i < u8.length; i += CHUNK) {
+        s += String.fromCharCode.apply(null, u8.subarray(i, i + CHUNK));
+    }
+    return btoa(s);
+}