@loxel.dev/pharos-browser 0.6.0

package/dist/replay/buffer.d.ts

@@ -0,0 +1,155 @@
+/** Mirrors rrweb's `EventType.FullSnapshot`. Pinned against the real enum in privacy-hooks.test.ts. */
+export declare const EVENT_TYPE_FULL_SNAPSHOT = 2;
+/** Mirrors rrweb's `EventType.Meta`. Pinned against the real enum in privacy-hooks.test.ts. */
+export declare const EVENT_TYPE_META = 4;
+export interface BufferedEvent {
+    type: number;
+    timestamp: number;
+    [key: string]: unknown;
+}
+export interface BufferStats {
+    bytes: number;
+    segments: number;
+    events: number;
+    evictedForAge: number;
+    evictedForBytes: number;
+    droppedBeforeFirstSnapshot: number;
+}
+export interface ReplayBufferOptions {
+    /** Hard ceiling in bytes. It WINS over `preRollMs`: a configured window is a request, not a guarantee. */
+    maxBytes: number;
+    preRollMs: number;
+    /** Byte accounting. Defaults to `JSON.stringify(event).length`; injectable so tests are exact. */
+    sizeOf?: (event: BufferedEvent) => number;
+    /** Called when the ceiling — not age — forced a segment out, so the recorder can record a degradation. */
+    onCeilingEviction?: () => void;
+    /**
+     * ALWAYS-ON SESSION REPLAY (issue #793): called exactly once, synchronously,
+     * the moment a checkpoint SUPERSEDES the segment before it — i.e. right
+     * after `append()` opens a new segment via a `FullSnapshot`, for whatever
+     * segment was open immediately before that arrived. NOT called for the
+     * very first segment of a session (there is nothing before it to close),
+     * and NOT called by eviction: a segment dropped for age or ceiling never
+     * closed, it was simply discarded, and `onCeilingEviction` already reports
+     * that separately.
+     *
+     * THIS IS WHAT MAKES A SESSION WITHOUT ANY ERROR STILL RECORDED. Before
+     * this hook the buffer was purely a ring the trigger coordinator read from
+     * on demand (`extract`); nothing ever consumed a segment on its own. A
+     * closed segment already begins with its own full snapshot — the
+     * checkpoint invariant this whole file exists to guarantee — so it needs
+     * no pre-roll or post-roll to be replayable: it already IS a window.
+     *
+     * The array handed back is a FRESH COPY of the segment's events, not the
+     * live internal array — unlike `extract()`'s return, whose ARRAY is fresh
+     * but whose EVENT OBJECTS are shared by reference on purpose. Here there is
+     * no reason to share even the array: the closed segment may still be
+     * retained in `this.segments` for pre-roll purposes (a trigger's
+     * `extract()` can still reach back into it), so handing out the buffer's
+     * OWN array would let a careless caller `push`/`shift` it and corrupt
+     * retained history exactly the way `extract()`'s own tests pin against.
+     */
+    onSegmentClosed?: (events: BufferedEvent[], startedAt: number) => void;
+}
+/**
+ * Whether an event array is replayable at all: it must open with a full
+ * snapshot, optionally preceded by the Meta event rrweb emits alongside it.
+ * Exported because it is BOTH the buffer's own fail-closed self-check and the
+ * assertion every window test makes.
+ */
+export declare function beginsWithSnapshot(events: readonly BufferedEvent[]): boolean;
+/**
+ * How far a held `Meta` may be from the `FullSnapshot` that claims it. rrweb
+ * emits the pair back-to-back inside one cycle, so a real gap is sub-millisecond
+ * and this bound has three orders of magnitude of headroom.
+ *
+ * A LARGE gap means the Meta's own snapshot never arrived — dropped by a
+ * privacy scrubber upstream, say, which is a real path in this very slice.
+ * Pinning a 19-second-old viewport onto a fresh snapshot tells the replayer a
+ * layout that may since have rotated or resized. A segment with no Meta is
+ * still replayable (`beginsWithSnapshot` accepts a bare snapshot) and the
+ * player falls back to a default viewport: a known-unknown beats
+ * confidently-wrong data.
+ */
+export declare const MAX_PENDING_META_AGE_MS = 1000;
+/**
+ * Default byte accounting: the event's UTF-8 SERIALIZED size, deliberately not
+ * `JSON.stringify(event).length`.
+ *
+ * `.length` counts UTF-16 code units, which UNDER-COUNTS every non-ASCII
+ * character — roughly 2.5x on a CJK page, 2x on emoji. Under-counting is the
+ * HARMFUL direction: the ceiling then admits more than it was told to, and the
+ * ceiling is the only thing standing between this recorder and eating a user's
+ * tab. So the default counts real bytes.
+ *
+ * NOTE: this measures SERIALIZED size, not JS heap footprint. The retained
+ * event objects cost several times this in the heap; `maxBytes` is a
+ * transport-size ceiling used as a proxy for memory.
+ *
+ * Exported because every buffer test injects `sizeOf`, which would otherwise
+ * leave the function that actually runs in production with no coverage at all.
+ */
+export declare function defaultSizeOf(event: BufferedEvent): number;
+export declare class ReplayBuffer {
+    private readonly maxBytes;
+    private readonly preRollMs;
+    private readonly sizeOf;
+    private readonly onCeilingEviction?;
+    private readonly onSegmentClosed?;
+    private segments;
+    /**
+     * rrweb emits Meta immediately before each FullSnapshot. Meta carries the
+     * viewport the replayer needs, so it belongs to the segment the snapshot
+     * OPENS, not the one it closes — hence a one-slot hold rather than an append.
+     */
+    private pendingMeta;
+    private newestTimestamp;
+    private totalBytes;
+    private evictedForAge;
+    private evictedForBytes;
+    private droppedBeforeFirstSnapshot;
+    constructor(opts: ReplayBufferOptions);
+    append(event: BufferedEvent): void;
+    private dropOldestSegment;
+    private evict;
+    /**
+     * The window `[triggeredAt - preRollMs, until]`, snapped BACK to the
+     * checkpoint at or before the pre-roll boundary. Returns `null` when no
+     * replayable window exists — the caller MUST NOT ship a window in that case.
+     */
+    extract(triggeredAt: number, until: number): BufferedEvent[] | null;
+    /**
+     * ALWAYS-ON SESSION REPLAY (issue #793 follow-up): the currently OPEN
+     * segment's events, exactly as they stand right now — a snapshot of a
+     * still-growing thing, not a closing of it. `null` when nothing has been
+     * appended yet (no segment exists at all).
+     *
+     * THIS IS WHAT MAKES A SHORT SESSION STILL RECORD SOMETHING. A segment
+     * otherwise only ships via `onSegmentClosed`, which fires exclusively when
+     * the NEXT checkpoint supersedes it — so a session shorter than one
+     * `checkpointIntervalMs` (15s at the defaults) never closes its first
+     * segment at all, and produced ZERO windows under `onSegmentClosed` alone.
+     * The recorder's unload path calls this instead, to ship whatever the open
+     * segment holds — the tail of every session, however short — WITHOUT
+     * closing it, restarting it, or forcing a new snapshot: the open segment
+     * already begins with its own full snapshot (this buffer's own invariant),
+     * so there is nothing to force.
+     *
+     * MAY BE CALLED ANY NUMBER OF TIMES, unlike `onSegmentClosed`'s one-shot
+     * notification — each call reflects the segment's CURRENT content, so a
+     * caller can tell whether it has grown since a previous call (the
+     * recorder does exactly this, to avoid re-shipping an unchanged segment on
+     * a second unload signal with nothing new in it).
+     *
+     * Returns a COPY, for the same reason `onSegmentClosed` does: the segment
+     * is still open and this buffer will keep appending to its OWN internal
+     * array, which a caller must not alias.
+     */
+    currentSegment(): {
+        events: BufferedEvent[];
+        startedAt: number;
+    } | null;
+    /** Discards everything. `stop()` calls this so a consent withdrawal leaves nothing to upload. */
+    clear(): void;
+    stats(): BufferStats;
+}

package/dist/replay/config.d.ts

@@ -0,0 +1,190 @@
+/**
+ * How an activation was produced. THIS IS THE ONLY THING THE RECORDER EVER
+ * LEARNS ABOUT THE KEYBOARD. No key value is read, stored or transmitted —
+ * a `keydown` listener sees passwords, and a recorder that stored key values
+ * would reintroduce the #792 leak through a channel no privacy marker covers.
+ */
+export type ActivationMode = 'pointer' | 'keyboard' | 'programmatic';
+/**
+ * `'checkpoint'` is issue #793's always-on design: a window shipped because a
+ * checkpoint segment closed, not because anything went wrong. It carries no
+ * `name`, always has `occurrences: 1` (there is no burst to collapse — see
+ * `triggers.ts`'s `checkpoint()`), and is produced independently of every
+ * other kind here, which all remain exactly what B1 shipped: something a
+ * caller told the recorder went wrong.
+ */
+export type TriggerKind = 'exception' | 'unhandledrejection' | 'manual' | 'checkpoint';
+/** What a caller hands the recorder when something went wrong. */
+export interface TriggerSource {
+    kind: TriggerKind;
+    /**
+     * `err.name` — a constructor name such as `"TypeError"`, never a message.
+     * Messages can carry user content and the recorder is not the place to
+     * decide that; the errors pillar already owns message sanitization.
+     */
+    name?: string;
+}
+/** What actually shipped, after de-duplication collapsed a burst into one window. */
+export interface TriggerInfo {
+    kind: TriggerKind;
+    name?: string;
+    /** Epoch ms of the FIRST trigger collapsed into this window. */
+    at: number;
+    /** How many trigger notifications this window absorbed. */
+    occurrences: number;
+    /** Epoch ms the window was extracted and handed to the sink. */
+    flushedAt: number;
+    /** True when the post-roll was cut short by an unload flush. */
+    unloaded: boolean;
+}
+export type DegradationReason = 'long-task' | 'recovery' | 'memory-ceiling';
+/**
+ * One recorded transition of the recorder's own health. Every transition is
+ * recorded WITH ITS REASON so a sparse replay is explained rather than
+ * looking like a bug (spec §7).
+ */
+export interface DegradationRecord {
+    /** Epoch ms of the FIRST event collapsed into this record. */
+    at: number;
+    level: number;
+    reason: DegradationReason;
+    checkpointIntervalMs: number;
+    mousemoveWaitMs: number;
+    /**
+     * How many events this record collapses — always 1 for a level transition,
+     * and for `memory-ceiling` the number of evicted segments, because the
+     * buffer evicts one segment at a time and a burst is rate-limited into one
+     * record (`budget.ts`). Without it, rate limiting would report 500 lost
+     * segments as one, and the counter that could correct it
+     * (`ReplayBuffer.stats().evictedForBytes`) never reaches a reader: the sink
+     * only ever sees a `ReplayWindow`. Same idea, and the same name, as
+     * `TriggerInfo.occurrences`.
+     */
+    occurrences: number;
+}
+export interface ResolvedRecorderConfig {
+    preRollMs: number;
+    postRollMs: number;
+    maxBytes: number;
+    pointerHz: number;
+    mousemoveWaitMs: number;
+    checkpointIntervalMs: number;
+}
+/**
+ * What the sink receives. `events` is an rrweb event array whose FIRST entry
+ * is a Meta or FullSnapshot event — see `buffer.ts` for the invariant that
+ * guarantees it.
+ */
+export interface ReplayWindow {
+    events: unknown[];
+    trigger: TriggerInfo;
+    degraded: DegradationRecord[];
+    config: ResolvedRecorderConfig;
+}
+/**
+ * B1 ships NO NETWORK CODE. It hands windows to this pluggable sink; slice B2
+ * replaces the sink with a real uploader without touching the recorder.
+ */
+export type Sink = (window: ReplayWindow) => void;
+/**
+ * Why the trigger coordinator dropped a window instead of shipping it. Both
+ * are B1 fail-closed returns in `triggers.ts` and both were entirely SILENT
+ * until slice B2 wired `onWindowDropped` (below) — no stat, no
+ * `DegradationRecord`, and the absorbed `occurrences` count discarded with
+ * them.
+ */
+export type WindowDropReason = 
+/** The buffer held no extractable snapshot, so nothing replayable existed. */
+'no-snapshot'
+/** Every event postdated the error, so the window was not that error's context. */
+ | 'fabricated-window';
+export interface RecorderOptions {
+    sink: Sink;
+    /**
+     * Notified when the coordinator drops a window instead of calling `sink`
+     * (see `WindowDropReason`).
+     *
+     * ADDED IN SLICE B2 (Task 9, requirement 3) AND ADDITIVE: absent, nothing
+     * changes and the drops stay silent exactly as B1 shipped them. B1's own
+     * comment on `RecorderHandle.trigger` invited this — "Slice B2, where an
+     * uploader gives it somewhere to go, should carry the reason and the
+     * absorbed count rather than a number." The uploader's `droppedWindows`
+     * (drops.ts) is that somewhere: without this hook the server's cumulative
+     * count omits every window B1 lost, and an operator reading
+     * `droppedWindows: 0` on a memory-pressured session is told nothing was
+     * lost when windows were.
+     *
+     * Called inside the coordinator's `contained()`, like the sink, so a
+     * throwing implementation cannot break the page.
+     */
+    onWindowDropped?: (reason: WindowDropReason) => void;
+    preRollMs?: number;
+    postRollMs?: number;
+    maxBytes?: number;
+    pointerHz?: number;
+    /** Injectable clock. Defaults to `Date.now`. */
+    now?: () => number;
+    /** Injectable idle scheduler. Defaults to `requestIdleCallback`, or `setTimeout(cb, 0)` where it does not exist. */
+    scheduleIdle?: (cb: () => void) => void;
+    /** Injectable timer pair, so tests drive the post-roll and checkpoint clocks deterministically. */
+    setTimer?: (cb: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+    /** Injectable listener target for the activation-modality listeners. Defaults to `document`. */
+    target?: EventTarget;
+    /**
+     * Injectable listener target for the page-lifecycle flush (`pagehide` and
+     * `visibilitychange`). Defaults to `globalThis` — the Window, which is the
+     * end of the propagation path for a Document-dispatched `visibilitychange`
+     * as well as the target of `pagehide`, so one target covers both.
+     */
+    lifecycleTarget?: EventTarget;
+    /** Injectable document, used to build surrogate elements for attribute scrubbing. Defaults to the global `document`. */
+    doc?: Document;
+}
+export interface RecorderStats {
+    snapshots: number;
+    bufferBytes: number;
+    segments: number;
+    /**
+     * Activation-modality listener invocations that performed real work — spec
+     * §7.1's fourth proxy, and `ModalityState.work` verbatim.
+     *
+     * RENAMED FROM `pointerWork` 2026-09-02, because that name was false:
+     * `interactions.ts` increments the counter on `keydown` and `pointerdown`
+     * as well as on a sampled `pointermove`, so a stat called "pointer work"
+     * reported keyboard work too. Nothing measured changed — the field is still
+     * the tracker's single counter — and the alternative (excluding `keydown`
+     * from it) was rejected because the proxy is meant to bound the recorder's
+     * TOTAL listener cost, and a recorder that omits its keyboard listener from
+     * its own cost report understates itself.
+     *
+     * A DELTA OVER THIS IS ONLY "PER POINTER EVENT" IF THE MEASURED WINDOW
+     * DISPATCHES NOTHING ELSE. The gate tests in budget-gate.test.ts dispatch
+     * `pointermove` alone and say so; a future test mixing event types must
+     * account for that or it will read a contaminated number.
+     */
+    interactionWork: number;
+    degradationLevel: number;
+}
+export interface RecorderHandle {
+    readonly config: ResolvedRecorderConfig;
+    /** Halts capture AND DISCARDS THE BUFFER. Any in-flight post-roll is abandoned. */
+    stop(): void;
+    trigger(source: TriggerSource): void;
+    /** Flushes the in-flight window immediately (unload). No-op when nothing is pending. */
+    flushNow(): void;
+    stats(): RecorderStats;
+}
+/**
+ * The hard memory ceiling, and IT WINS OVER CONFIGURED WINDOWS (spec §5): a
+ * configured pre-roll is a request, not a guarantee. When a page is heavy
+ * enough that the pre-roll does not fit, the buffer holds less and records a
+ * `memory-ceiling` degradation.
+ */
+export declare const MAX_BUFFER_BYTES: number;
+export declare const RECORDER_DEFAULTS: {
+    readonly preRollMs: 30000;
+    readonly postRollMs: 10000;
+    readonly pointerHz: 20;
+};
+export declare function resolveConfig(opts: Pick<RecorderOptions, 'preRollMs' | 'postRollMs' | 'maxBytes' | 'pointerHz'>): ResolvedRecorderConfig;

package/dist/replay/drops.d.ts

@@ -0,0 +1,46 @@
+/** Every way slice B2 can lose a whole window. */
+export type DropReason = 
+/** Encoded larger than `MAX_WINDOW_BYTES`; the server would 413 it. */
+'oversized'
+/** A POST that failed, rejected, or answered non-2xx. */
+ | 'delivery'
+/**
+ * IndexedDB refused the write FOR SPACE (`QuotaExceededError`) — either the
+ * oldest persisted window was evicted to make room, or the incoming one
+ * could not be stored even after that eviction.
+ */
+ | 'quota'
+/**
+ * The local store could not take the window for a reason that is NOT
+ * space: no `IndexedDB` in this host at all, `open()` throwing (a
+ * sandboxed iframe, a blocked storage partition), or a transaction dying.
+ *
+ * SPLIT OUT FROM `quota` IN FIX ROUND 1, because it was being labelled
+ * `quota` — including by requirement 5's own fixture, whose factory throws
+ * from `open()` and has nothing to do with space — and one branch was
+ * labelling a persistence failure `delivery`. `total()` was right either
+ * way, and nothing on the wire carries the breakdown, but this file
+ * documents the buckets as what a test and a future error channel assert
+ * on, so a label that does not mean what it says is a defect in the thing
+ * this module exists to be.
+ */
+ | 'storage'
+/** B1: the buffer held no extractable snapshot, so nothing replayable existed. */
+ | 'no-snapshot'
+/** B1: every event in the window postdated the error, so the window was not that error's context. */
+ | 'fabricated-window';
+export interface DropLedger {
+    note(reason: DropReason): void;
+    /** The cumulative number that goes on the wire as `droppedWindows`. */
+    total(): number;
+    /** Per-reason breakdown. Nothing on the wire carries it; tests and future error channels do. */
+    byReason(): Record<DropReason, number>;
+    /**
+     * Back to zero. Called on `stop()` (spec §3 decision 6): a count accrued
+     * BEFORE a consent withdrawal must not ride along on an upload made after
+     * one. Without this, `stop()` then `startRecording()` would attach the old
+     * session's losses to the new session's first envelope.
+     */
+    reset(): void;
+}
+export declare function createDropLedger(): DropLedger;

package/dist/replay/index.d.ts

@@ -0,0 +1,2 @@
+export { startRecording } from './recorder';
+export { SESSION_STORAGE_KEY, SESSION_DROPS_KEY, resolveSessionId, startReplayUpload, type ReplayUploadHandle, type ReplayUploadOptions, } from './wire';

package/dist/replay/index.js

@@ -0,0 +1,8 @@
+import"../index-c3taa3cg.js";
+export {
+  SESSION_DROPS_KEY,
+  SESSION_STORAGE_KEY,
+  resolveSessionId,
+  startRecording,
+  startReplayUpload
+};

package/dist/replay/interactions.d.ts

@@ -0,0 +1,48 @@
+import type { ActivationMode } from './config';
+export type InputModality = 'pointer' | 'keyboard';
+/**
+ * How long a recorded modality stays authoritative. Beyond this, an
+ * activation with no click-count is treated as programmatic — otherwise an
+ * `el.click()` minutes after a real mouse click would be reported as a
+ * pointer activation forever.
+ */
+export declare const ACTIVATION_MODALITY_TTL_MS = 500;
+/** The rrweb custom-event tag. Stable: B2 and B3 both match on it. */
+export declare const ACTIVATION_EVENT_TAG = "pharos-activation";
+export interface ActivationPayload {
+    mode: ActivationMode;
+}
+/**
+ * A SINGLE mutable record for the tracker's whole lifetime. Its identity never
+ * changes, which is the property the "zero allocation per pointer event"
+ * budget test asserts.
+ */
+export interface ModalityState {
+    modality: InputModality | null;
+    modalityAt: number;
+    pointerAt: number;
+    /** Listener invocations that performed real work — spec §7.1's fourth proxy. */
+    work: number;
+}
+export interface InteractionTracker {
+    readonly state: ModalityState;
+    setPointerIntervalMs(ms: number): void;
+    detach(): void;
+}
+/**
+ * Two independent signals, so neither is a single point of failure (spec §4.2):
+ * the tracked modality, and `event.detail` — which a keyboard-produced click
+ * reports as 0 while a pointer click reports a click-count.
+ */
+export declare function resolveActivationMode(input: {
+    modality: InputModality | null;
+    modalityAt: number;
+    at: number;
+    detail: number;
+}): ActivationMode;
+export declare function attachInteractions(opts: {
+    target: EventTarget;
+    now: () => number;
+    pointerIntervalMs: number;
+    emit: (payload: ActivationPayload) => void;
+}): InteractionTracker;

package/dist/replay/persist.d.ts

@@ -0,0 +1,75 @@
+import { type DropLedger } from './drops';
+/** Design §3 decision 6: undrained windows expire locally after 24h. */
+export declare const LOCAL_TTL_MS: number;
+/**
+ * Number of windows evicted by the quota-exceeded path (spec §7, "Error
+ * handling") ON THE DEFAULT LEDGER ONLY.
+ *
+ * TEST/DIAGNOSTIC SEAM. A caller that injected its own ledger — which the
+ * wired path always does — will see 0 here no matter how many evictions
+ * happened, because its evictions went to ITS ledger. Read
+ * `DropLedger.byReason().quota` for that. Kept under this name because
+ * Task 8's suite pins it and because "what did the default ledger evict" is
+ * still the right question for a caller that never injected one.
+ *
+ * Not reset by `clearPersisted`, which clears STORAGE, not counters.
+ */
+export declare function quotaDroppedWindows(): number;
+/**
+ * Resets the default ledger (Task 9, requirement 6).
+ *
+ * Task 8 deliberately left the counter un-reset by `clearPersisted`, which is
+ * right — clearing storage is not the same event as withdrawing consent — but
+ * it left an eviction count from BEFORE a consent withdrawal able to ride out
+ * on an upload made AFTER one. `stop()` is the event that must zero it, and
+ * `startReplayUpload` calls this from `stop()` alongside resetting the
+ * session ledger, so the rule holds whichever ledger a caller used.
+ */
+export declare function resetQuotaDroppedWindows(): void;
+/**
+ * Whether IndexedDB refused a write FOR SPACE, as opposed to any other storage
+ * failure. Matched on `name`, not `instanceof DOMException`: the error crosses
+ * a promise boundary out of this module and the constructor identity is not
+ * guaranteed across realms (an iframe, a test's fake), while the name is what
+ * the specification defines.
+ *
+ * EXPORTED, AND THAT IS THE POINT (final review, minor). `wire.ts` held a
+ * byte-identical copy under a different name — two predicates deciding the
+ * same question, which is this slice's own recurring finding. One
+ * implementation, two call sites; a change to what counts as "out of space"
+ * cannot now move on one path and not the other.
+ */
+export declare function isQuotaExceeded(err: unknown): boolean;
+/**
+ * Persists one window, keyed by an autoIncrement id (see the module doc
+ * comment for why not `insertedAt` itself). Expired records are purged first
+ * (`purgeExpired`). On `QuotaExceededError`, evicts the single OLDEST stored
+ * record (spec §7: "the oldest persisted window is dropped and counted in
+ * `droppedWindows`") and retries exactly once — a second failure propagates
+ * rather than looping, since a store that still won't accept a write after
+ * freeing space is not a retry problem.
+ */
+export declare function persistWindow(body: Uint8Array, meta: object, now?: () => number, indexedDB?: IDBFactory, drops?: DropLedger): Promise<void>;
+/**
+ * Drains every persisted window, oldest first. Each record is handled
+ * independently:
+ *
+ * - Older than `LOCAL_TTL_MS`: dropped without being sent (consent/TTL rule).
+ * - `send` resolves `true`: deleted, counted in the returned total.
+ * - `send` resolves `false` or rejects: left in place for the next attempt.
+ *
+ * Reads all records up front in one transaction, then performs deletes in
+ * their own transactions AFTER each `await send(...)` — an IndexedDB
+ * transaction auto-commits once its task queue empties, so holding one open
+ * across an awaited network call (a macrotask) would throw
+ * `TransactionInactiveError` on the delete that follows it.
+ */
+export declare function drainPersisted(send: (body: Uint8Array, meta: object) => Promise<boolean>, now?: () => number, indexedDB?: IDBFactory): Promise<number>;
+/**
+ * The consent primitive (spec §3 decision 6): removes every persisted
+ * window, unconditionally. Wired by the caller into `stop()` so withdrawing
+ * consent leaves nothing of the user's anywhere — this module does not call
+ * `stop()` itself (it has no recorder handle), so that wiring is the caller's
+ * job, not this function's.
+ */
+export declare function clearPersisted(indexedDB?: IDBFactory): Promise<void>;

package/dist/replay/privacy-hooks.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Attributes rrweb invents during serialization. They are not page content
+ * and must not be routed through `scrubAttribute`, which would mangle them.
+ *
+ * `_cssText` is rrweb's inlined `<style>` CONTENTS — a stylesheet, not a
+ * `style` attribute. Slice A's style scrubber parses `;`-separated
+ * declarations, not rules, so treating a stylesheet as one would mask quoted
+ * strings inside author CSS and corrupt the replay's rendering.
+ *
+ * DEFENCE IN DEPTH, NOT A LOAD-BEARING RULE, for the scrub pass below:
+ * `scrubAttribute` today applies the style scrubber only to an attribute
+ * literally named `style`, and none of the names in this set is a URL,
+ * value-bearing or `data-*` attribute, so routing them through it would in
+ * fact be a no-op. Deleting this skip therefore changes nothing observable
+ * today — it exists so that a future `scrubAttribute` that learns about
+ * `_cssText` or `rr_dataURL` cannot silently start mangling them. In
+ * `surrogateElement` the skip IS load-bearing: an invented attribute must not
+ * be allowed to influence slice A's sensitivity detection.
+ *
+ * Author CSS is not user content; a `content: "…"` templated from user data
+ * would leave, and that limitation is stated in apps/pharos/README.md's
+ * "What this does NOT catch".
+ *
+ * RECORDER CONSTRAINT — `rr_dataURL`. rrweb writes RENDERED CANVAS PIXELS
+ * into it, and under `inlineImages` the bytes of every image
+ * (rrweb-snapshot.js:1036-1072). That is arbitrarily sensitive content — a
+ * signature pad, an uploaded photo — and skipping it here means nothing
+ * scrubs it. It is unreachable today only because `recordCanvas` and
+ * `inlineImages` both default to false, so: THE RECORDER MUST NOT ENABLE
+ * `recordCanvas` OR `inlineImages` WHILE `rr_dataURL` IS IN THIS SET.
+ * Enabling either needs a decision first, because there is no partial scrub
+ * of a bitmap: the honest options are to keep the feature off, or to map
+ * `rr_dataURL` into `RENAMED_CONTENT_ATTRS` as a `src`, which sends it
+ * through `scrubUrl` and — `data:` being a non-http scheme — masks it
+ * wholesale, i.e. replays the canvas blank. Note that merely REMOVING it
+ * from this set does NOT create that backstop: `scrubAttribute` has no rule
+ * for the name `rr_dataURL` and returns it verbatim.
+ */
+export declare const RRWEB_INTERNAL_ATTRS: Set<string>;
+/** rrweb-snapshot's serialized node shape, narrowed to the parts we scrub. */
+export interface SerializedNode {
+    type: number;
+    tagName?: string;
+    attributes?: Record<string, unknown>;
+    childNodes?: SerializedNode[];
+    id?: number;
+    [key: string]: unknown;
+}
+export interface ScrubContext {
+    doc: Document;
+    /** rrweb's mirror lookup, so an attribute mutation can be judged against the live element. */
+    resolveNode: (id: number) => Node | null;
+}
+/**
+ * Whether a text node under `el` must be masked.
+ *
+ * The decision itself is `shouldMaskValueOf`'s — text and values resolve
+ * identically, and sharing one function is what stops them diverging.
+ *
+ * FAILS CLOSED on a null parent: rrweb hands `null` when a text node has no
+ * parent element, and an unattributable string is exactly the one we cannot
+ * reason about.
+ */
+export declare function shouldMaskTextOf(el: Element | null): boolean;
+/**
+ * rrweb's `maskTextFn`. Because the recorder sets `maskTextSelector: '*'`,
+ * rrweb calls this for EVERY text node, which makes this function the single
+ * decision point — exactly what spec §6 requires. rrweb only ever invokes
+ * `maskTextFn` for nodes it has already decided to mask, so without the `'*'`
+ * selector this hook would never see a sensitivity-detected element and the
+ * policy would silently diverge.
+ */
+export declare function maskTextHook(text: string, el: HTMLElement | null): string;
+/**
+ * rrweb's `maskInputFn`. Unconditional: a value is something the user typed,
+ * and slice A masks it regardless of markers or detection (spec §3.3). The
+ * element argument is accepted and ignored on purpose — there is no branch to
+ * add here, and adding one would be a re-implementation.
+ */
+export declare function maskInputHook(text: string, _el: HTMLElement): string;
+/**
+ * A detached element carrying the serialized node's own tag and attributes.
+ *
+ * `scrubAttribute` needs an `Element` only to run `isSensitiveField`, which
+ * reads `tagName`, `type`, `autocomplete`, `name`, `id` and `aria-label` — all
+ * present in the serialized attributes. So a surrogate built from the event
+ * itself is exact, and needs no lookup into rrweb's mirror (which would fail
+ * for nodes already removed from the document).
+ */
+export declare function surrogateElement(tagName: string, attributes: Record<string, unknown>, doc: Document): Element | null;
+/** Scrubs one serialized element's attributes in place, then recurses. */
+export declare function scrubSerializedNode(node: SerializedNode, doc: Document): void;
+/**
+ * Scrubs an emitted rrweb event's attributes IN PLACE and returns it.
+ *
+ * rrweb has no attribute hook and does not scrub attributes at all — verified
+ * against 2.1.1, where `<a href="/s?q=pierogi">` ships as
+ * `http://localhost/s?q=pierogi`. This pass closes that by CALLING slice A's
+ * `scrubAttribute`; it implements no rule of its own.
+ */
+export declare function scrubEventAttributes<T>(event: T, ctx: ScrubContext): T;

package/dist/replay/recorder.d.ts

@@ -0,0 +1,20 @@
+import { type RecorderHandle, type RecorderOptions } from './config';
+/**
+ * ONE RECORDER AT A TIME, AND THE SECOND ONE IS INERT. rrweb's `record` is a
+ * module singleton (see `active` above), so a second concurrent
+ * `startRecording()` silently takes the session over from the first, whose
+ * buffer then stops filling while its handle still reports healthy stats —
+ * the exact silent-degradation shape this slice exists to eliminate.
+ *
+ * REFUSED BY RETURNING AN INERT HANDLE, NOT BY THROWING. This is a call the
+ * recorder can be made on any stack, including a framework's, and the
+ * precedent is already set two ways in this file: a failed `record()` yields
+ * an inert handle, and `triggers.ts` contains the sink. `attachReplay`
+ * (index.ts) DOES throw, and deliberately: that is an explicit
+ * once-per-application wiring call on the app author's own stack, where the
+ * throw is the only signal a developer will see. Here the first recorder is
+ * already running and the honest answer is to leave it alone.
+ *
+ * `stop()` on the owning recorder releases the slot.
+ */
+export declare function startRecording(opts: RecorderOptions): RecorderHandle;