@outcrawl/sdk 0.1.0

package/dist/types/_deps/replay/events.d.ts

@@ -0,0 +1,1004 @@
+/**
+ * Outcrawl session replay - event model and wire constants.
+ *
+ * The format follows OpenReplay's shape, not rrweb's: **one full snapshot per
+ * frame, then pure deltas**. rrweb re-snapshots on a timer, and at roughly
+ * 500 KB per snapshot every five minutes those keyframes dominate stored bytes
+ * for a session that is otherwise a few kilobytes of mutations. Here a second
+ * snapshot is only ever emitted when the capture layer genuinely has no delta to
+ * describe what happened - a main-frame navigation, or a deliberate sparse
+ * checkpoint on a long session so scrubbing does not replay from zero
+ * (`index-seek.ts`).
+ *
+ * Three invariants run through every event.
+ *
+ * **Monotonic `t`.** Milliseconds since session start, integral, never
+ * decreasing. The encoder throws on a regression rather than writing bytes that
+ * would make the seek index lie.
+ *
+ * **Frame-qualified node ids.** Blink backend node ids are allocated per
+ * renderer process, so a site-isolated iframe hands out the same numbers as its
+ * parent. A bare `node: number` therefore aliases two different elements the
+ * moment a cross-origin iframe appears - which on real targets is immediately.
+ * Every reference to an existing node is a `NodeRef` of `{ frame, node }`.
+ *
+ * Inside a serialised DOM tree the ids stay bare, because a tree belongs to
+ * exactly one frame: `Snapshot.frame` for a snapshot, `parent.frame` for an
+ * inserted subtree. An `<iframe>` element carries `frame` pointing at the child
+ * frame whose own `Snapshot` holds its document; the element's `children` remain
+ * parent-frame nodes.
+ *
+ * **Tab-slabbed frame ordinals.** A recording is one BROWSER CONTEXT over a
+ * time range, not one page, and its tabs share one stream and one clock. Two
+ * renderers told to number their frames the same way would both call their main
+ * frame 0, and a player would fold one tab's mutations into another's tree. So
+ * tab k's ordinals come out of slab `k * FRAME_ORDINAL_SLAB` and `tabOf`
+ * inverts it - which makes tab identity a property of a field every event
+ * already carries rather than a field added to all fifteen of them.
+ */
+/**
+ * Bump on ANY incompatible change, including edits to `STATIC_STRINGS` in
+ * `dictionary.ts` - the dictionary is as much part of the wire contract as the
+ * field order is.
+ *
+ * APPENDING AN EVENT TYPE IS NOT ONE, and `SubresourceCapture: 11` was added
+ * without a bump on purpose. `readFileHeader` rejects any version it does not
+ * equal exactly, so bumping is itself the breaking change here: it would
+ * orphan every session already in storage, which is a strictly worse outcome
+ * than the one it protects against. A new type at the END of the enum leaves
+ * every existing stream byte-identical and decoding identically, and the only
+ * incompatible direction - an old decoder meeting a new stream - does not
+ * exist as a deployment, because the encoder, the decoder and the player ship
+ * as one artifact.
+ *
+ * Editing `STATIC_STRINGS` is still a bump, and is why nothing was added to it
+ * for assets: dictionary indices shift, and every stored stream reinterprets
+ * its string table.
+ *
+ * ## TAB IDENTITY DID NOT BUMP IT EITHER, and this is the case worth reading
+ *
+ * Making a recording the whole browser context rather than one page is a
+ * change in KIND, not another event type, so it was decided against the corpus
+ * rather than by precedent. Three things had to hold and all three do.
+ *
+ * Identity rides a field that already exists. Tab k's frames live in slab
+ * `k * FRAME_ORDINAL_SLAB`, so the per-event frame varint - written once per
+ * event since version 1 and elided for ordinal 0 by `TYPE_FRAME_ZERO` -
+ * already says which tab an event belongs to. Nothing was added to any of the
+ * fifteen events to carry it. A per-event `tab` field was the obvious version
+ * and was refused: a byte on every event of a 12,000-event session to restate
+ * a number the stream already holds.
+ *
+ * An absent tab means tab 0 WITHOUT A READER APPLYING A DEFAULT. Every session
+ * recorded before the capture layer could attach a second tab has every
+ * ordinal below one slab, so `tabOf` answers 0 for all of them by arithmetic.
+ * A reader therefore never asks for a field a stored session cannot have,
+ * which is the requirement a version-gated field would have failed.
+ *
+ * `Console` and `Network` gained a `frame` - the one place identity was NOT
+ * free, because the encoder wrote a hard 0 for both. It is written into the
+ * varint slot those types already elided, so the byte layout of every stored
+ * session is unchanged and they decode to tab 0.
+ */
+export declare const FORMAT_VERSION = 1;
+/** `OCRP`. Session stream magic. */
+export declare const FILE_MAGIC: Uint8Array<ArrayBuffer>;
+/** `SG`. Segment frame magic, so a truncated stream can be resynchronised. */
+export declare const SEGMENT_MAGIC: Uint8Array<ArrayBuffer>;
+/** magic(4) + version(1) + flags(1). Fixed width so segment 0 is at a known offset. */
+export declare const FILE_HEADER_BYTES = 6;
+/** magic(2) + payloadLength(u32le). Fixed width so an index scan can hop frames. */
+export declare const SEGMENT_HEADER_BYTES = 6;
+/** Segment flag bits. */
+export declare const SegmentFlags: {
+    /**
+     * The segment opens with a main-frame `Snapshot`, so playback may start here
+     * without decoding anything earlier. The capture layer is responsible for
+     * emitting snapshots for every other live frame within the same segment.
+     */
+    readonly Checkpoint: 1;
+};
+/**
+ * Every event's type byte carries this bit when the event's frame is 0, letting
+ * the frame varint be omitted entirely. The main frame is the overwhelming
+ * majority of events, and this is the cheapest byte in the format to remove.
+ *
+ * Safe because `EventType` needs four bits and will not grow to 128 members.
+ */
+export declare const TYPE_FRAME_ZERO = 128;
+/**
+ * Width of one tab's frame-ordinal space, and therefore how a tab is
+ * identified on the wire.
+ *
+ * ONE RECORDING IS ONE BROWSER CONTEXT, not one page. Every tab of a session
+ * records into this stream under one session id, and every renderer numbers
+ * its own frames from whatever the capture command was told. Told the same
+ * thing twice, two tabs both claim main-frame ordinal 0 and both allocate
+ * subframes from 1 - so a player applies tab B's mutations to tab A's tree and
+ * reconstructs a page that never existed. That is a replay which is not merely
+ * incomplete but confidently WRONG, and durable recordings get believed.
+ *
+ * So tab k is armed in its own slab: its main frame is `k * FRAME_ORDINAL_SLAB`
+ * and its renderer mints same-process subframes from one above that. TAB
+ * IDENTITY IS THEREFORE ALREADY IN EVERY EVENT, at no cost: the frame ordinal
+ * is written once per event and `TYPE_FRAME_ZERO` elides it entirely for tab
+ * 0's main frame. A per-event `tab` field would restate a number the `frame`
+ * varint already carries.
+ *
+ * THIS IS WHY AN ABSENT TAB MEANS TAB 0 WITHOUT A DEFAULT BEING APPLIED. Every
+ * session recorded before the capture layer could attach a second tab has
+ * every ordinal below one slab, so {@link tabOf} answers 0 for all of them by
+ * arithmetic rather than by a reader's convention - and a reader never has to
+ * ask for a field a stored session cannot have.
+ *
+ * 65536 and not 1024: `frame` is varint-encoded per event, so a 2^16 slab
+ * costs three varint bytes instead of one on every event of tab 1 and up,
+ * which is a few KB on a real session and compresses to almost nothing because
+ * it is the same three bytes every time. A 1024-wide slab would save that and
+ * put a page with 1023 same-process iframes into the next tab's id space,
+ * which is silent DOM corruption rather than a size regression.
+ *
+ * Defined here rather than in the capture layer because it is a WIRE fact: a
+ * decoder that did not know it could not tell a viewer which tab an event
+ * belongs to, and two copies of it are two chances to disagree.
+ */
+export declare const FRAME_ORDINAL_SLAB = 65536;
+/**
+ * Which tab a frame ordinal belongs to. The only way to ask.
+ *
+ * `>>> 16` rather than a division by {@link FRAME_ORDINAL_SLAB}: the slab is
+ * 2^16 and every ordinal is a non-negative integer well below 2^31, so the
+ * shift is exact and cheaper. It exists as a function so that the shift is
+ * written once - one open-coded `>>> 16` against a slab that later changes
+ * width is a whole tab of events silently attributed to its neighbour.
+ */
+export declare function tabOf(frame: number): number;
+/** A tab's main-frame ordinal: its identity, as every `TabEvent` carries it. */
+export declare function frameBaseOf(tab: number): number;
+/**
+ * String encoding: one varint header, low bit says which kind.
+ *
+ * - `header & 1` set - inline. `header >> 1` is the UTF-8 byte length, and those
+ *   bytes follow. The string is then appended to the segment's dynamic table.
+ * - `header & 1` clear - reference. `header >> 1` indexes the static dictionary
+ *   below `STATIC_COUNT`, and the segment's dynamic table above it.
+ *
+ * The dynamic table is never transmitted: both sides append every inline string
+ * they see, in the same order, so the table builds itself. That makes a
+ * one-shot string cost exactly what inlining it would have cost - no table entry
+ * plus index to pay for it - which in turn means every string in the format can
+ * be run through the table, text nodes and input values included, with no
+ * downside when they turn out to be unique.
+ */
+export declare const STRING_INLINE = 1;
+/**
+ * `MouseMove` batch modes. Pointer bursts are the highest-volume event class in
+ * a session and their per-sample deltas need five or six bits, so the packed
+ * mode declares one bit width for the batch and packs samples at that width.
+ * `MOUSE_WIDE` is the fallback for a batch too wide to pack, which keeps the
+ * packing unconditional rather than a bet on well-behaved input.
+ */
+export declare const MOUSE_WIDE = 0;
+export declare const MOUSE_PACKED = 1;
+/**
+ * Widest bit field the packed mode will use.
+ *
+ * Two widths share one byte as nibbles, so 15 is the ceiling. That covers a
+ * jump of +-16,383 pixels or milliseconds between consecutive samples, which no
+ * real pointer stream reaches - and anything that does falls back to
+ * `MOUSE_WIDE` rather than failing.
+ */
+export declare const MAX_PACKED_BITS = 15;
+/**
+ * Presence bits for optional fields.
+ *
+ * Every event or node with optional fields writes one flags byte before its
+ * fixed fields. A byte shared by up to eight optionals beats a per-field
+ * presence marker, and putting the bits here rather than privately in
+ * `encoder.ts` and `decoder.ts` makes encoder/decoder drift - the failure mode
+ * that produces plausible-looking garbage instead of an error - impossible.
+ *
+ * Tri-state booleans need two bits: one that the field was present at all, one
+ * for its value, so `masked: false` survives the round trip distinctly from an
+ * absent `masked`.
+ */
+export declare const SnapshotFlags: {
+    readonly Parent: 1;
+    readonly Adopted: 2;
+};
+export declare const ElementFlags: {
+    readonly Namespace: 1;
+    readonly Shadow: 2;
+    readonly Frame: 4;
+};
+export declare const ShadowFlags: {
+    readonly Adopted: 1;
+};
+export declare const InsertFlags: {
+    readonly Previous: 1;
+};
+export declare const AttrFlags: {
+    readonly Value: 1;
+};
+export declare const StyleFlags: {
+    readonly SourceUrl: 1;
+    readonly Owner: 2;
+    readonly DisabledSet: 4;
+    readonly DisabledValue: 8;
+};
+export declare const InputFlags: {
+    readonly Value: 1;
+    readonly CheckedSet: 2;
+    readonly CheckedValue: 4;
+    readonly MaskedSet: 8;
+    readonly MaskedValue: 16;
+};
+export declare const AssetFlags: {
+    readonly ContentType: 1;
+    readonly Dropped: 2;
+};
+/**
+ * Presence bits for {@link RegionFilmEvent}, deliberately the same two as
+ * {@link AssetFlags} and deliberately a separate constant.
+ *
+ * The same two optionals happen to be optional on both events for the same
+ * reason - a body can be refused and a container can be unknown - but a film
+ * segment and a subresource are different events whose optional sets will
+ * diverge, and sharing one constant is how the bit that was added for one
+ * silently changes the meaning of the other's byte.
+ */
+export declare const FilmFlags: {
+    readonly ContentType: 1;
+    readonly Dropped: 2;
+};
+/**
+ * Presence bits for {@link ConsoleEvent}.
+ *
+ * `MainFrame` is a VALUE bit rather than a presence bit, and it is here rather
+ * than in a byte of its own because the flags byte is already being spent. The
+ * field is not optional: every console line either came from the frame the
+ * session is attached to or from one below it, and "unknown" is not a state the
+ * browser can be in about a message it just routed.
+ */
+export declare const ConsoleFlags: {
+    readonly Url: 1;
+    readonly Line: 2;
+    readonly MainFrame: 4;
+};
+/** Presence bits for {@link NetworkEvent}. */
+export declare const NetworkFlags: {
+    readonly Method: 1;
+    readonly Status: 2;
+    readonly MimeType: 4;
+    readonly EncodedBytes: 8;
+    readonly DurationMs: 16;
+};
+/**
+ * Presence bits for {@link TabEvent}.
+ *
+ * In PDL order - `url` then `title` - because that is the order
+ * `Outcrawl.sessionTarget` declares them in and the order the codec writes
+ * them, so the three read top to bottom together.
+ *
+ * All three are genuinely optional and absence is a CLAIM: "this phase is not
+ * about the url" is a different statement from an empty url, and the
+ * difference is a `Close` wiping the label off a strip chip. A reader applies
+ * what is present and keeps what it had.
+ */
+export declare const TabFlags: {
+    readonly Url: 1;
+    readonly Title: 2;
+    readonly Opener: 4;
+};
+/**
+ * Console severity, as the browser can actually distinguish it.
+ *
+ * FOUR VALUES, AND THERE IS NO `info`. `ThreadDebuggerCommonImpl::
+ * V8MessageLevelToMessageLevel` maps v8's `kMessageLog` and `kMessageInfo` onto
+ * one `mojom::ConsoleMessageLevel`, so `console.info` is not distinguishable
+ * from `console.log` on any in-process route -- the collapse is in Blink,
+ * upstream of every tap. A fifth member here would be a distinction the data
+ * does not carry, which is the same reason `Outcrawl.sessionConsole` does not
+ * declare one either.
+ *
+ * Numeric rather than the protocol's strings because the set is closed by
+ * Blink's own enum and a byte beats interning four literals.
+ */
+export declare const ConsoleLevel: {
+    readonly Log: 0;
+    readonly Warn: 1;
+    readonly Error: 2;
+    readonly Debug: 3;
+};
+export type ConsoleLevel = (typeof ConsoleLevel)[keyof typeof ConsoleLevel];
+/**
+ * Which end of one resource load this row is.
+ *
+ * TWO ROWS PER COMPLETED LOAD, both emitted when the load ENDS, because
+ * `WebContentsImpl::ResourceLoadComplete` is the funnel and it fires once. The
+ * pair is what makes a request visible as open-and-unanswered when the playhead
+ * sits between them.
+ *
+ * `Failed` is a NET error, not an HTTP one: a 404 is a `Response` with `status`
+ * 404, exactly as the CDP path reported it.
+ */
+export declare const NetworkPhase: {
+    readonly Request: 0;
+    readonly Response: 1;
+    readonly Failed: 2;
+};
+export type NetworkPhase = (typeof NetworkPhase)[keyof typeof NetworkPhase];
+export declare const EventType: {
+    readonly Snapshot: 0;
+    readonly NodeInserted: 1;
+    readonly NodeRemoved: 2;
+    readonly AttrChanged: 3;
+    readonly TextChanged: 4;
+    readonly StyleSheetAdded: 5;
+    readonly Navigation: 6;
+    readonly Input: 7;
+    readonly Scroll: 8;
+    readonly MouseMove: 9;
+    readonly Viewport: 10;
+    readonly SubresourceCapture: 11;
+    readonly RegionFilm: 12;
+    readonly Console: 13;
+    readonly Network: 14;
+    readonly Tab: 15;
+};
+export type EventType = (typeof EventType)[keyof typeof EventType];
+/** Indexed by `EventType`, for error messages and debugging. */
+export declare const EVENT_NAMES: readonly string[];
+/**
+ * Why an asset's bytes are NOT in the bundle.
+ *
+ * Present on a {@link SubresourceCaptureEvent} whose body was refused. The
+ * entry is still emitted, and that is the whole point: a replay that says what
+ * it dropped beats one that lies. A player renders a labelled placeholder and
+ * strips the dead reference, so the viewer's browser never reaches for an
+ * origin it cannot get to.
+ *
+ * An asset with NO entry at all is a third case and means no claim either way
+ * - every session recorded before this event existed has none, and a player
+ * must leave those references untouched rather than make them worse.
+ */
+export declare const DropReason: {
+    /** Bigger than the per-asset ceiling on its own. */
+    readonly TooLarge: 1;
+    /** The session's byte budget was already spent. */
+    readonly BudgetExhausted: 2;
+    /** The load failed, or its bytes could not be read back. */
+    readonly FetchFailed: 3;
+};
+export type DropReason = (typeof DropReason)[keyof typeof DropReason];
+/** DOM `nodeType` values, reused so the wire matches the platform. */
+export declare const NodeKind: {
+    readonly Element: 1;
+    readonly Text: 3;
+    readonly Comment: 8;
+    readonly Document: 9;
+    readonly Doctype: 10;
+};
+export type NodeKind = (typeof NodeKind)[keyof typeof NodeKind];
+export declare const NavKind: {
+    /** A new document committed; a `Snapshot` for the frame follows. */
+    readonly Commit: 0;
+    /** History API or fragment change; the DOM survives, no snapshot follows. */
+    readonly SameDocument: 1;
+    readonly BackForward: 2;
+    readonly Reload: 3;
+};
+export type NavKind = (typeof NavKind)[keyof typeof NavKind];
+/**
+ * Which step in a tab's life a {@link TabEvent} reports.
+ *
+ * FOUR KINDS, and each one exists because the fact is NOT derivable from the
+ * event stream itself.
+ *
+ * `Open` is not derivable because a tab's first `Snapshot` arrives one CDP
+ * round trip after the tab existed, and a tab that opens and is closed before
+ * it commits a document produces no snapshot at all.
+ *
+ * `Close` is not derivable at all: a stream that stops carrying a slab's
+ * events is indistinguishable from a tab sitting idle in the background, and
+ * on a real session most background tabs are idle.
+ *
+ * `Focus` is not derivable because nothing about a document says whether the
+ * browser was SHOWING it, and "what the browser showed" is the focused tab.
+ *
+ * `Info` is not derivable because a title is not in the DOM stream's frame at
+ * all - `<title>`'s text node is, but the title Blink resolved from it is a
+ * browser-side fact - and because a url a player can label a chip with must
+ * survive a `Close` that carries none.
+ */
+export declare const TabKind: {
+    /** This tab now exists. Emitted before its first `Snapshot`. */
+    readonly Open: 0;
+    /** This tab is gone. Nothing later belongs to it. */
+    readonly Close: 1;
+    /** This tab became the one the browser was showing. */
+    readonly Focus: 2;
+    /** Its url, its title, or both changed. */
+    readonly Info: 3;
+};
+export type TabKind = (typeof TabKind)[keyof typeof TabKind];
+/**
+ * A reference to a node that already exists in the reconstructed DOM.
+ *
+ * `frame` is a capture-assigned frame ordinal (0 is the main frame), stable for
+ * the life of the frame. `node` is the Blink backend node id, unique only within
+ * that frame.
+ */
+export interface NodeRef {
+    frame: number;
+    node: number;
+}
+/** An attribute, kept as an ordered pair so attribute order survives the round trip. */
+export interface Attr {
+    name: string;
+    value: string;
+}
+export interface ElementNode {
+    kind: typeof NodeKind.Element;
+    node: number;
+    /** `nodeName`: upper case for HTML elements, authored case for SVG and MathML. */
+    tag: string;
+    attrs: Attr[];
+    children: DomNode[];
+    /** Set only outside the XHTML namespace. */
+    namespace?: string;
+    /** Attached shadow root, open or closed - we read it from C++, so closed is visible. */
+    shadow?: ShadowRootNode;
+    /** For `<iframe>`/`<frame>`/`<object>`: the child frame whose `Snapshot` holds its document. */
+    frame?: number;
+}
+export interface TextNode {
+    kind: typeof NodeKind.Text;
+    node: number;
+    text: string;
+}
+export interface CommentNode {
+    kind: typeof NodeKind.Comment;
+    node: number;
+    text: string;
+}
+export interface DocumentNode {
+    kind: typeof NodeKind.Document;
+    node: number;
+    children: DomNode[];
+}
+export interface DoctypeNode {
+    kind: typeof NodeKind.Doctype;
+    node: number;
+    name: string;
+    publicId: string;
+    systemId: string;
+}
+export type DomNode = ElementNode | TextNode | CommentNode | DocumentNode | DoctypeNode;
+/**
+ * A shadow root. Not a member of `DomNode` because it cannot appear as a child;
+ * it hangs off its host element's `shadow`.
+ */
+export interface ShadowRootNode {
+    node: number;
+    mode: 'open' | 'closed';
+    children: DomNode[];
+    /**
+     * `adoptedStyleSheets`, as stylesheet ids from `StyleSheetAdded`. Ids rather
+     * than text because adopted sheets are genuinely shared objects - the same
+     * sheet adopted into 200 shadow roots is one `StyleSheetAdded` and 200
+     * references.
+     */
+    adopted?: number[];
+}
+export interface ViewportSize {
+    width: number;
+    height: number;
+    /** `devicePixelRatio`. Fractional, so it goes on the wire as `f64`. */
+    dpr: number;
+}
+/** A batched pointer sample. `dt` is milliseconds after the carrying event's `t`. */
+export interface MousePosition {
+    x: number;
+    y: number;
+    dt: number;
+}
+interface EventBase {
+    /** Milliseconds since session start. Integral and non-decreasing across the session. */
+    t: number;
+}
+/** The full DOM of one frame. First event of the session, and of every checkpoint. */
+export interface SnapshotEvent extends EventBase {
+    type: typeof EventType.Snapshot;
+    frame: number;
+    url: string;
+    root: DomNode;
+    viewport: ViewportSize;
+    /** Parent frame ordinal. Absent exactly for the main frame. */
+    parent?: number;
+    /** Document-level `adoptedStyleSheets`, as `StyleSheetAdded` ids. */
+    adopted?: number[];
+}
+export interface NodeInsertedEvent extends EventBase {
+    type: typeof EventType.NodeInserted;
+    parent: NodeRef;
+    /** Insert after this sibling. Absent means the subtree became the first child. */
+    previous?: NodeRef;
+    /** The inserted subtree, in `parent.frame`. */
+    node: DomNode;
+}
+export interface NodeRemovedEvent extends EventBase {
+    type: typeof EventType.NodeRemoved;
+    parent: NodeRef;
+    target: NodeRef;
+}
+export interface AttrChangedEvent extends EventBase {
+    type: typeof EventType.AttrChanged;
+    target: NodeRef;
+    name: string;
+    /** Absent means the attribute was removed. */
+    value?: string;
+}
+export interface TextChangedEvent extends EventBase {
+    type: typeof EventType.TextChanged;
+    target: NodeRef;
+    text: string;
+}
+/**
+ * A stylesheet became active: `<style>`, `<link>`, or a constructed sheet pushed
+ * into `adoptedStyleSheets`. The last of these is invisible to rrweb, which is
+ * one of the reasons its replays of component-heavy sites render unstyled.
+ */
+export interface StyleSheetAddedEvent extends EventBase {
+    type: typeof EventType.StyleSheetAdded;
+    frame: number;
+    /** Stylesheet id, referenced by `adopted` lists. Unique within the frame. */
+    sheet: number;
+    text: string;
+    sourceUrl?: string;
+    /** Owner `<style>` or `<link>`. Absent for constructed sheets, which have none. */
+    owner?: NodeRef;
+    disabled?: boolean;
+}
+export interface NavigationEvent extends EventBase {
+    type: typeof EventType.Navigation;
+    frame: number;
+    url: string;
+    kind: NavKind;
+}
+/**
+ * A form control's value changed.
+ *
+ * `masked` records that the capture layer redacted the value, so a player can
+ * render "hidden" rather than silently showing an empty field.
+ */
+export interface InputEvent extends EventBase {
+    type: typeof EventType.Input;
+    target: NodeRef;
+    value?: string;
+    checked?: boolean;
+    masked?: boolean;
+}
+/** `target` is the scrolling element, or the frame's document node for the viewport. */
+export interface ScrollEvent extends EventBase {
+    type: typeof EventType.Scroll;
+    target: NodeRef;
+    x: number;
+    y: number;
+}
+/**
+ * Pointer movement, batched. One event per burst rather than one per sample: at
+ * 60 Hz an unbatched stream is the single largest contributor to a session's
+ * byte count, and the samples compress far better as deltas within one array.
+ */
+export interface MouseMoveEvent extends EventBase {
+    type: typeof EventType.MouseMove;
+    frame: number;
+    positions: MousePosition[];
+}
+export interface ViewportEvent extends EventBase {
+    type: typeof EventType.Viewport;
+    frame: number;
+    viewport: ViewportSize;
+}
+/**
+ * One subresource the renderer actually loaded, and the content hash its bytes
+ * are stored under.
+ *
+ * Identity only. The bytes are NOT here and must not be: a 2 MB image inside a
+ * segment sized for DOM deltas breaks both the 64 KB segment ceiling and the
+ * one-coalesced-ranged-GET-per-chunk seek path. Bodies live in their own
+ * objects, addressed by {@link hash}; this event is what tells a player which
+ * hash a URL resolved to at a given time.
+ *
+ * WHY THE BROWSER EMITS THIS AND A CLIENT CANNOT SYNTHESISE IT
+ *
+ * Only the renderer knows what it fetched. Walking the DOM and CSS for
+ * references over-captures fonts by 9x on a measured real page - both
+ * `@font-face` blocks on books.toscrape.com list eot, woff, ttf and svg, and
+ * Chromium takes the woff and never asks for the rest, so a parser bills
+ * 613,107 B where the browser spent 66,996 B. It also under-captures, because
+ * `srcset`, `image-set()` and lazy loading are resolved against a viewport and
+ * a device pixel ratio that only the renderer has. This is the same boundary
+ * the fork already draws for pointer timing, in the other direction: whoever
+ * knows the answer owns it.
+ *
+ * `url` is normalised by `assetKey`, which is also what a player calls on a
+ * CSS `url()` token, so the two sides cannot disagree about the key.
+ */
+export interface SubresourceCaptureEvent extends EventBase {
+    type: typeof EventType.SubresourceCapture;
+    frame: number;
+    /** Absolute, fragment-stripped, `assetKey`-normalised request URL. */
+    url: string;
+    /**
+     * Lowercase hex, 32 chars: SHA-256 truncated to 128 bits.
+     *
+     * A string rather than 16 raw bytes for two reasons that both cost bytes to
+     * ignore. It is usable as a `Map` key by value, which is how a player folds
+     * a URL table and caches one decoded body per hash. And it goes through the
+     * segment's string table, so an asset restated at every checkpoint - which a
+     * checkpoint owes, exactly as it owes stylesheets - costs its 32 characters
+     * once and a table reference every time after.
+     *
+     * Truncated to 128 bits because this addresses one session's assets, where
+     * the birthday bound at a million assets is around 1e-27.
+     */
+    hash: string;
+    /** Bytes of the body as loaded. Present even when `dropped` is set. */
+    byteLength: number;
+    /** From the response. Absent when the load failed before headers. */
+    contentType?: string;
+    /** Set when the bytes are NOT in the bundle. See {@link DropReason}. */
+    dropped?: DropReason;
+}
+/**
+ * One encoded run of film over one region the DOM stream structurally cannot
+ * carry: an accelerated canvas, a WebGL context, a `<video>`.
+ *
+ * ## Why this is in the DOM stream at all
+ *
+ * Because a replay is one timeline. Those elements record a
+ * `ForeignLayerDisplayItem` wrapping a `cc::Layer` whose pixels live in GPU
+ * textures, so painting produces drawing commands for everything around them
+ * and nothing for them - which is why the fork reports their rects in
+ * `uncaptured` rather than pretending, and why `Outcrawl.startRegionFilm`
+ * exists to film exactly those rects. A film delivered beside the recording
+ * would be a second artifact with a second clock, and the two would drift the
+ * moment anybody seeked. Here the run is an event: it has the session's `t`,
+ * it lands in a segment, the seek index covers it, a checkpoint restates it,
+ * and the same retention sweep removes it.
+ *
+ * Identity only, exactly like {@link SubresourceCaptureEvent}: the H.264 bytes
+ * live in the session's asset store under {@link hash} and are fetched through
+ * the reader's `asset()` once per body. Frames as stills would have been the
+ * simpler wire and it was measured to be the wrong one - individual WebP at
+ * quality 40 costs 17.65 MB/min against 4.43 MB/min for H.264 at crf 34 and
+ * 5 fps on a full-viewport animating 3D scene, because consecutive frames of
+ * one region are nearly identical and a bag of stills throws away the only
+ * compression that matters.
+ */
+export interface RegionFilmEvent extends EventBase {
+    type: typeof EventType.RegionFilm;
+    frame: number;
+    /**
+     * `"canvas"` or `"video"`: the renderer's own label, the same string from
+     * the same predicate that fills `Outcrawl.UncapturedRegion.kind`.
+     *
+     * A string rather than a union so a browser that learns a third kind parses
+     * here instead of failing.
+     */
+    kind: string;
+    /** Where the run belongs on the page, in the frame's own coordinates. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /**
+     * The readback's OWN pixel dimensions, which are NOT {@link width} and
+     * {@link height} whenever a canvas backing store is not 1:1 with its layout
+     * box - a device pixel ratio above one, or `width`/`height` attributes that
+     * disagree with the CSS box.
+     *
+     * Carried so a player scales the film onto the rect. Assuming the two pairs
+     * are equal presents a crop of a region as the whole region, which is the
+     * same class of lie as drawing white where a canvas was.
+     */
+    imageWidth: number;
+    imageHeight: number;
+    /** Content hash of the encoded run. Same shape and store as an asset's. */
+    hash: string;
+    /** Bytes of the encoded run. Present even when `dropped` is set. */
+    byteLength: number;
+    /**
+     * Session time of the run's FIRST FRAME, which is not `t` and cannot be.
+     *
+     * A run is encoded once it is complete, so its event necessarily enters the
+     * stream after its last frame — and `t` is non-decreasing across the
+     * session, so the event cannot be stamped back at the moment the filming
+     * started. `t` is therefore where the run BECOMES KNOWN and `startedAt` is
+     * what it covers, and a player composites the run while
+     * `startedAt <= playhead < startedAt + durationMs`, seeking the video to
+     * `playhead - startedAt`.
+     *
+     * The consequence is worth stating rather than discovering: playing forward
+     * across a canvas that has just appeared, the region is blank until its
+     * first run lands, which is why the recorder bounds a run's length instead
+     * of letting one canvas film for a whole session. After a SEEK there is no
+     * lag at all, because the checkpoint restates every run it already knows.
+     *
+     * On the wire this is `t - startedAt`, a small varint on first emission and
+     * a growing one at each restatement, rather than a second absolute
+     * millisecond count.
+     */
+    startedAt: number;
+    /**
+     * How long the run covers, from {@link startedAt}. Measured across the
+     * browser's own frame timestamps rather than from a nominal frame rate:
+     * encoding at the requested fps turned a 12.22 s segment into 6.6 s of
+     * video, and a 1:1 seek then ran out of film and held the last frame while
+     * everything else kept moving.
+     */
+    durationMs: number;
+    /** Frames in the run. With `durationMs`, the rate actually achieved. */
+    frames: number;
+    /** Container of the encoded run. `video/mp4` for everything shipped today. */
+    contentType?: string;
+    /** Set when the bytes are NOT in the bundle. See {@link DropReason}. */
+    dropped?: DropReason;
+}
+/**
+ * One console line the page produced, from `Outcrawl.sessionConsole`.
+ *
+ * ## THIS IS A LOG, NOT STATE, AND THAT IS THE WHOLE DESIGN
+ *
+ * Every other event in this format folds into `ReconstructState`: it says what
+ * the page IS at `t`. A console line says what HAPPENED at `t` and is never
+ * unsaid. So `applyEvent` folds nothing for it, a `Snapshot` does not clear it
+ * the way it clears its frame's tables, and a checkpoint does not restate it.
+ *
+ * Stated at length because the frame model is the one a reader will assume, and
+ * assuming it here produces the opposite of a fix. Restating a cumulative
+ * console at every checkpoint is unbounded: the asset table a checkpoint owes
+ * back is forty entries and a session's console is however many lines the page
+ * chose to print. The alternative -- a bounded ring buffer in state -- would
+ * make a seek and a play-through agree only by throwing away the lines a
+ * customer opened the replay to read.
+ *
+ * The consumer is therefore a WHOLE-SESSION pass rather than the fold:
+ * `buildTimeline` in `@outcrawl/player` reads every event once and turns an
+ * `Error` line into a prominent scrub-bar mark, and an export carries these
+ * verbatim in its segments for anything decoding the stream directly.
+ *
+ * ## Why it is in this stream at all
+ *
+ * The same argument {@link RegionFilmEvent} makes: a replay is one timeline. A
+ * console log delivered beside the recording is a second artifact with a second
+ * clock, and the two drift the moment anybody seeks. Here the line has the
+ * session's `t`, it lands in a segment, the seek index covers it and the same
+ * retention sweep removes it.
+ *
+ * ## What this route does not carry, so nobody looks for it
+ *
+ * `console.log`'s object arguments. V8 flattens them with
+ * `V8ValueStringBuilder` before the only embedder-visible callback fires, and
+ * that flattener renders a plain object through `ObjectProtoToString` -- so
+ * `console.log('x', {a:1})` arrives as `x [object Object]`. The CDP route is no
+ * better: `V8RuntimeAgentImpl::enable` replays pre-enable messages with
+ * `generatePreview=false`. Shared and service workers are also absent, having
+ * no parent frame to proxy through, and so are `kNetwork`-source messages,
+ * which `FrameConsole::ReportMessageToClient` drops before the browser sees
+ * them.
+ */
+export interface ConsoleEvent extends EventBase {
+    type: typeof EventType.Console;
+    level: ConsoleLevel;
+    text: string;
+    /**
+     * WHICH TAB said it: the emitting tab's main-frame ordinal, per
+     * {@link FRAME_ORDINAL_SLAB}. `tabOf(frame)` is the tab.
+     *
+     * A TAB ATTRIBUTION AND NOT A FRAME ONE, which is why {@link frameId} is
+     * still here beside it. The frame that produced the line may be an
+     * out-of-process iframe several levels down, and the browser reports it by
+     * token rather than by any ordinal this stream assigned - so this field
+     * answers "whose console pane does this belong in", not "which document".
+     *
+     * Zero means tab 0, and it means it for every session ever recorded: the
+     * encoder elides this varint entirely for ordinal 0 through
+     * `TYPE_FRAME_ZERO`, so a stored stream that predates multi-tab capture
+     * decodes to 0 here without a byte changing and without a reader applying a
+     * default. Before this field existed the encoder wrote a hard 0 for every
+     * console line, which on a multi-tab session stacked five tabs' diagnostics
+     * onto tab 0 - complete-looking and wrong, which is worse than a gap.
+     */
+    frame: number;
+    /**
+     * `Page.frameId` of the frame that produced it: the `devtools_frame_token`,
+     * NOT this stream's frame ordinal.
+     *
+     * The two are different namespaces and cannot be reconciled here. An ordinal
+     * is assigned by whichever renderer's capture emitted a DOM event; this token
+     * is the browser's per-frame identity, and the browser is the only process
+     * that sees every frame. Carried as the browser's own string so it joins
+     * against `getFrameOrdinal` and against a client's own frame lifecycle, and
+     * so it is never mistaken for something the fold could index.
+     */
+    frameId: string;
+    /** False for any subframe, including an out-of-process one. */
+    mainFrame: boolean;
+    /**
+     * The script URL Blink attributed the message to. Absent when it had none,
+     * which is what a platform-raised message with no script in scope looks like.
+     */
+    url?: string;
+    /**
+     * One-based, as Blink counts. Absent when unknown and NEVER defaulted to 1: a
+     * wrong line is worse than no line for anybody counting lines in a source
+     * file.
+     */
+    line?: number;
+}
+/**
+ * One end of one resource load, from `Outcrawl.sessionNetwork`.
+ *
+ * A log and not state, for the reasons {@link ConsoleEvent} sets out at length;
+ * the fold ignores it and `buildTimeline` marks a {@link NetworkPhase.Failed}
+ * row on the scrub bar.
+ *
+ * ## `at` IS THE MEASUREMENT AND `t` IS ONLY WHEN WE LEARNED IT
+ *
+ * `ResourceLoadComplete` fires when a load ENDS, so both of a load's rows are
+ * produced at that instant however long the load took. Stamping the `Request`
+ * row at that instant would put every request on the timeline at the moment it
+ * finished, which is wrong about the one thing a network pane exists to show --
+ * and it cannot simply be stamped earlier, because `t` is non-decreasing across
+ * the session and the stream has already moved on.
+ *
+ * So this carries both, exactly as {@link RegionFilmEvent} carries `startedAt`
+ * beside `t` and for the same reason. `t` is where the row became known;
+ * `at` is the instant it describes -- `load_timing_info.request_start` for a
+ * `Request`, browser arrival for a `Response` or a `Failed`. A viewer places
+ * the row at `at`. `at <= t` always, and the wire spends the difference rather
+ * than a second absolute millisecond count.
+ *
+ * A load with no net-level timing at all -- a DNS or connect failure -- has
+ * `at` equal to arrival, because there is nothing else to date it to.
+ *
+ * ## What is missing from this route, stated rather than discovered
+ *
+ * Cancelled loads: a request still in flight when the page navigates away is
+ * reported through `NotifyResourceLoadCanceled`, which the renderer handles
+ * renderer-side only, so nothing reaches the browser and no row is emitted.
+ * Per-hop redirect detail: one load produces one `Request` and one closing row,
+ * with the started-with URL on the first and the ended-on URL on the second, so
+ * a redirect shows as the URL changing across the pair -- `blink.mojom
+ * .RedirectInfo` carries no full URL to report the hops with. And response
+ * bodies, on any route, deliberately: `ResourceLoadInfo` does not carry one and
+ * the body pipe never reaches the browser process.
+ */
+export interface NetworkEvent extends EventBase {
+    type: typeof EventType.Network;
+    phase: NetworkPhase;
+    /**
+     * `<childProcessId>.<requestId>`, the shape `IdentifiersFactory::RequestId`
+     * gives a CDP `Network.requestId`, so a row here is joinable against a
+     * protocol log. A memory-cache hit arrives with no request id of any kind and
+     * is reported as `memcache.<n>`, which cannot collide.
+     */
+    requestId: string;
+    /**
+     * The URL of THIS row: what the load was started with on `Request`, what it
+     * ended on when closing. See the redirect note above.
+     */
+    url: string;
+    /**
+     * WHICH TAB loaded it: the emitting tab's main-frame ordinal. See
+     * {@link ConsoleEvent.frame}, which this is exactly - including that 0 is
+     * tab 0 for every stored session at no wire cost.
+     */
+    frame: number;
+    /** `devtools_frame_token`, not a frame ordinal. See {@link ConsoleEvent.frameId}. */
+    frameId: string;
+    /** Session milliseconds of the instant this row describes. Integral, `<= t`. */
+    at: number;
+    /**
+     * The request method, post-redirect: the notifier overwrites it on each hop
+     * and no field could hold both. Absent only on a memory-cache hit.
+     */
+    method?: string;
+    /**
+     * HTTP status. Absent on `Failed`, matching the CDP fold, and absent when
+     * there were no headers at all. Every optional here is ABSENT rather than
+     * zero when the route did not carry it: a status of 0, a byte count of 0 and
+     * a duration of 0 all read as measurements and none of them would be one.
+     */
+    status?: number;
+    mimeType?: string;
+    /** On the wire after TLS and proxying: CDP's `encodedDataLength`. Integral. */
+    encodedBytes?: number;
+    /** Request start to browser arrival, on the closing row. Integral. */
+    durationMs?: number;
+}
+/**
+ * One step in one tab's life: it opened, it closed, it became the tab the
+ * browser was showing, or its url and title changed.
+ *
+ * ## Why the context needs events at all
+ *
+ * A recording is one BROWSER CONTEXT over a time range, not one page, and it is
+ * played back on ONE CLOCK: scrubbing to `t` shows which tabs existed at `t`,
+ * which was focused, and what each contained. A tab that opened at 12.4s does
+ * not exist before 12.4s and a tab closed at 30.1s is gone after it, whether
+ * the viewer is playing or seeking across the instant.
+ *
+ * Every DOM event already says which tab it belongs to for free -
+ * {@link FRAME_ORDINAL_SLAB} - so this event carries only what the slab cannot
+ * express. See {@link TabKind} for why each of the four is one of those.
+ *
+ * ## A LOG AT THE CONTEXT LEVEL, folded like state
+ *
+ * Unlike {@link ConsoleEvent} these DO fold: the open tab set and the focused
+ * tab are what the context IS at `t`. And unlike a frame's tables they are not
+ * cleared by a `Snapshot`, because a snapshot is one document committing and a
+ * tab surviving a navigation is the ordinary case.
+ *
+ * A checkpoint therefore RESTATES them, exactly as it restates a frame's asset
+ * table: one `Open` per tab still open, carrying its current url and title,
+ * plus one `Focus`. Without that a seek onto a checkpoint lands in a context
+ * with no tabs in it. A restated `Open` for a tab already open is a no-op and
+ * never a reset - the same last-write-wins rule the asset table has.
+ *
+ * ## No favicon, and that is a limit rather than a deferral
+ *
+ * `DevToolsAgentHost` exposes `GetTitle` and `GetURL` and nothing else a chip
+ * could draw; a favicon lives in `content::FaviconStatus` on the `WebContents`
+ * side and no `Outcrawl` command or event carries it. A player labels a tab
+ * with its title and the origin of its url. An empty icon slot would be a
+ * surface asserting something it does not know.
+ */
+export interface TabEvent extends EventBase {
+    type: typeof EventType.Tab;
+    /**
+     * THE TAB'S IDENTITY: its main-frame ordinal, `tabOf(frame)` tabs in.
+     *
+     * The same field every other event carries, which is the point - a tab is
+     * identified one way in this format and the wire pays for it once. Never
+     * reused: the capture layer's tab index only ever increases, so a tab
+     * closing and another opening cannot collapse two documents into one id.
+     */
+    frame: number;
+    kind: TabKind;
+    /**
+     * The url the browser shows on the tab. Absent means THIS STEP IS NOT ABOUT
+     * THE URL, which is not the same as an empty url: a `Close` carries none and
+     * must not wipe the label off a chip.
+     */
+    url?: string;
+    /**
+     * The title Blink parsed, not the placeholder Chromium held before the parse.
+     * Absent on the same terms as {@link url}.
+     */
+    title?: string;
+    /**
+     * Main-frame ordinal of the tab that SPAWNED this one - a `window.open` or a
+     * `target=_blank` link. Absent when nothing spawned it: the session's own
+     * first tab, or one the runtime opened on its own behalf.
+     *
+     * Only ever present on {@link TabKind.Open}, and it is LOAD-BEARING TWICE.
+     * A strip draws it, to show that a checkout tab came out of a cart tab. And
+     * a player's fold follows it for SUCCESSION: when the focused tab closes and
+     * the recording states no new focus, the view moves to the tab that spawned
+     * the dead one rather than to the nearest survivor.
+     *
+     * That second use is why this field must not be pruned as decorative. Both
+     * answers look plausible on any single recording - the opener and the nearest
+     * survivor are frequently the same tab - so dropping it changes which page a
+     * viewer is looking at after a close, silently and only sometimes.
+     * `worker/scripts/probe-replay-two-tabs.ts` asserts the value on its
+     * page-spawned tab so a regression fails a run instead of changing a replay.
+     */
+    opener?: number;
+}
+export type ReplayEvent = SnapshotEvent | NodeInsertedEvent | NodeRemovedEvent | AttrChangedEvent | TextChangedEvent | StyleSheetAddedEvent | NavigationEvent | InputEvent | ScrollEvent | MouseMoveEvent | ViewportEvent | SubresourceCaptureEvent | RegionFilmEvent | ConsoleEvent | NetworkEvent | TabEvent;
+export {};