diff --git a/docs/reference/jspsych.md b/docs/reference/jspsych.md
index 97aa093098..b7a25dc6fa 100644
--- a/docs/reference/jspsych.md
+++ b/docs/reference/jspsych.md
@@ -34,6 +34,7 @@ The settings object can contain several parameters. None of the parameters are r
 | override_safe_mode         | boolean  | Running a jsPsych experiment directly in a web browser (e.g., by double clicking on a local HTML file) will load the page using the `file://` protocol. Some features of jsPsych don't work with this protocol. By default, when jsPsych detects that it's running on a page loaded via the `file://` protocol, it runs in _safe mode_, which automatically disables features that don't work in this context. Specifically, the use of Web Audio is disabled (audio will be played using HTML5 audio instead, even if `use_webaudio` is `true`) and video preloading is disabled. The `override_safe_mode` parameter defaults to `false`, but you can set it to `true` to force these features to operate under the `file://` protocol. In order for this to work, you will need to disable web security (CORS) features in your browser - this is safe to do if you know what you are doing. Note that this parameter has no effect when you are running the experiment on a web server, because the page will be loaded via the `http://` or `https://` protocol. |
 | case_sensitive_responses   | boolean  | If `true`, then jsPsych will make a distinction between uppercase and lowercase keys when evaluating keyboard responses, e.g. "A" (uppercase) will not be recognized as a valid response if the trial only accepts "a" (lowercase). If false, then jsPsych will not make a distinction between uppercase and lowercase keyboard responses, e.g. both "a" and "A" responses will be valid when the trial's key choice parameter is "a". Setting this parameter to false is useful if you want key responses to be treated the same way when CapsLock is turned on or the Shift key is held down. The default value is `false`. |
 extensions | array | Array containing information about one or more jsPsych extensions that are used during the experiment. Each extension should be specified as an object with `type` (required), which is the name of the extension, and `params` (optional), which is an object containing any parameter-value pairs to be passed to the extension's `initialize` function. Default value is an empty array. |
+| record_session             | boolean  | If `true`, jsPsych captures a high-fidelity recording of the session — DOM mutations within the display element, mouse/touch/keyboard/clipboard input, scroll position (window and per-element), video and audio playback events, viewport changes (including pinch zoom), and every `Math.random()` output — sufficient to reconstruct a replay of what the participant saw and did. The recording is retrieved at the end of the experiment via `jsPsych.getSessionRecording()` and can be `JSON.stringify`'d and saved alongside the trial data. While enabled, `Math.random` is wrapped to log every call into the recording; this is reverted when the experiment ends. The default value is `false`. **Note:** text typed into form inputs (e.g. survey responses) is captured verbatim. Inform participants accordingly. |
 
 ### Return value
 
@@ -460,6 +461,39 @@ alert('You have completed approximately '+progress.percent_complete+'% of the ex
 ```
 
 
+---
+
+## jsPsych.getSessionRecording
+
+```javascript
+jsPsych.getSessionRecording()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+Returns a `SessionRecording` object when the experiment was initialized with `record_session: true`, or `undefined` otherwise. The object is JSON-serializable.
+
+### Description
+
+Returns the high-fidelity session recording produced by the `record_session` option. The recording includes the rendered DOM at the start of every trial, all DOM mutations within `#jspsych-content`, mouse, touch, keyboard, and clipboard events, scroll position (window and per-element), video and audio playback events, viewport changes, and every `Math.random()` output. The returned object is versioned (`schema_version: 1`); see [Session Recording Schema](./session-recording-schema.md) for the full format reference.
+
+### Example
+
+```javascript
+var jsPsych = initJsPsych({
+  record_session: true,
+  on_finish: function() {
+    var recording = jsPsych.getSessionRecording();
+    var blob = new Blob([JSON.stringify(recording)], { type: "application/json" });
+    // ...persist or upload `blob` alongside the trial data
+  }
+});
+```
+
 ---
 
 ## jsPsych.getStartTime
diff --git a/docs/reference/session-recording-schema.md b/docs/reference/session-recording-schema.md
new file mode 100644
index 0000000000..2f3a8b93af
--- /dev/null
+++ b/docs/reference/session-recording-schema.md
@@ -0,0 +1,410 @@
+# Session Recording Schema
+
+When `initJsPsych` is called with `record_session: true`, jsPsych captures a session recording sufficient to reconstruct a visual replay of the participant's experience. This page documents the JSON-serializable shape returned by `jsPsych.getSessionRecording()`.
+
+The schema is versioned. Schemas with the same major version are read-compatible; consumers should branch on `schema_version` and reject anything they don't understand.
+
+**Current version: `1`.**
+
+## Replayer model
+
+A replayer treats this recording as observational. It does not re-execute trial code. The replay is reconstructed from three things:
+
+1. The DOM snapshot captured at each trial's `on_load` (`trial.initial_dom`).
+2. The chronological mutation and input event log scoped to that trial (`trial.events`).
+3. The session-level stylesheet snapshot (`stylesheets`) so the reconstructed DOM is styled identically to the original.
+4. Session-level metadata for context (viewport, scroll, RNG outputs, focus/blur, fullscreen).
+
+Each trial is a self-contained replay unit because jsPsych wipes the display element between trials.
+
+## Top-level shape
+
+```ts
+interface SessionRecording {
+  schema_version: 1;
+  jspsych_version: string;
+  recording_started_at: string;       // ISO 8601 wall-clock anchor
+  recording_started_at_perf: number;  // performance.now() at start
+  user_agent: string;
+  viewport: ViewportState;
+  rng: { seed: string | null; math_random_patched: boolean };
+  display_element_id: string;
+  stylesheets: StylesheetSnapshot[];
+  stylesheet_events: StylesheetEvent[];
+  trials: TrialRecording[];
+  viewport_changes: ViewportChange[];
+  rng_calls: RngCall[];
+  ended_at_perf: number | null;
+  end_reason: "finished" | "aborted" | "unload" | null;
+}
+```
+
+| Field | Description |
+| ----- | ----------- |
+| `schema_version` | Always `1` for recordings produced by this codebase. |
+| `jspsych_version` | The jsPsych package version that produced the recording. |
+| `recording_started_at` | ISO 8601 timestamp of when `start()` was called. |
+| `recording_started_at_perf` | The `performance.now()` value at recording start. All event `t` values are relative to this. |
+| `user_agent` | `navigator.userAgent` at recording start. |
+| `viewport` | The initial viewport state. See [`ViewportState`](#viewportstate). |
+| `rng.seed` | The seed installed via `jsPsych.randomization.setSeed` for the session, or `null` if `Math.random` was already non-native at recording start. |
+| `rng.math_random_patched` | `true` while recording is active; `Math.random` is wrapped to log every call into `rng_calls`. |
+| `display_element_id` | The `id` attribute of the display element (`#jspsych-content` by default). |
+| `stylesheets` | Snapshot of every stylesheet attached to the document at session start. See [Stylesheets](#stylesheets). |
+| `stylesheet_events` | Chronological log of `<head>` stylesheet changes that occurred after `start()`. See [Stylesheet events](#stylesheet-events). |
+| `trials` | Per-trial recordings, in chronological order. See [`TrialRecording`](#trialrecording). |
+| `viewport_changes` | Session-level log of viewport changes (window resize, page zoom, pinch zoom, pinch pan). |
+| `rng_calls` | Chronological log of every `Math.random` output. Includes calls outside trial boundaries (parameter eval, ITI, `on_finish`). |
+| `ended_at_perf` | The `performance.now()` at `stop()`. |
+| `end_reason` | How the session ended. `"aborted"` when `abortExperiment()` was called. |
+
+All `t` fields elsewhere in the document are floats in milliseconds, relative to `recording_started_at_perf` (i.e. `performance.now() - recording_started_at_perf`).
+
+## TrialRecording
+
+```ts
+interface TrialRecording {
+  trial_index: number;
+  t_start: number;
+  t_dom_ready: number | null;
+  t_end: number | null;
+  plugin: string;
+  initial_dom: DomNode | null;
+  events: RecordedEvent[];
+  trial_data: JsonValue;
+}
+```
+
+| Field | Description |
+| ----- | ----------- |
+| `trial_index` | The jsPsych trial index. Matches `trial_data.trial_index` and the row in `data.csv`. |
+| `t_start` | When the trial entered `onTrialStart` (before parameter evaluation completes). |
+| `t_dom_ready` | When the plugin's initial render completed (`on_load` fired). `initial_dom` was sampled at this moment. `null` if a recording was stopped before this point. |
+| `t_end` | When the trial ended. `null` if the recording was stopped before the trial finished. |
+| `plugin` | The plugin name (e.g. `"html-keyboard-response"`). For labeling and filtering only; replay does not depend on it. |
+| `initial_dom` | A "spine" DOM tree at `t_dom_ready` that walks from the display container down to the display element and includes the trial subtree. See [DOM representation](#dom-representation) and [Display spine](#display-spine). |
+| `events` | Chronological log of mutations and input events from `t_dom_ready` to `t_end`. Empty arrays are valid. |
+| `trial_data` | The data row written to `jsPsych.data` for this trial (the same object exported via `data.csv` / `data.json`). Includes `rt`, `response`, `trial_type`, `trial_index`, etc. |
+
+### Replay procedure for a single trial
+
+1. Clear the host element you render into.
+2. Instantiate `initial_dom` into the host. The recording's `initial_dom` is itself rooted at the experiment's display container (carrying the `jspsych-display-element` class), so you do not need to add wrapper classes yourself.
+3. Apply each entry in `events` at its `t`, in order.
+
+### Display spine
+
+`initial_dom` is not just the trial content — it is the chain of layout-bearing ancestors that wrap the trial content, with non-essential siblings stripped out. The shape is fixed for any jsPsych experiment:
+
+```
+display container (e.g. <body class="jspsych-display-element"> or the user's host)
+└── <div class="jspsych-content-wrapper">
+    └── <div id="jspsych-content" class="jspsych-content">
+        └── (trial-rendered content)
+```
+
+The recorder captures each ancestor's tag and attributes, but only the descendant on the path to the display element appears as a child. So when `display_element` defaults to `<body>`, the captured `<body>` node carries body's classes/style but has only the wrapper as a child — sibling content elsewhere in `<body>` is intentionally omitted.
+
+Why this matters: the CSS that vertically centers experiment content lives on `.jspsych-content-wrapper` (`margin: auto; flex: 1 1 100%`) and `.jspsych-display-element` (`display: flex; flex-direction: column`). Without the wrappers, `.jspsych-content`'s `margin: auto` has no flex parent to center against and the layout collapses to top-aligned, unstyled content.
+
+DOM mutations during the trial reference ids assigned during the spine serialization. The `MutationObserver` is scoped to the display element (`#jspsych-content`), so only mutations within that subtree are tracked at runtime — the wrappers are static and don't produce mutation events.
+
+## DOM representation
+
+```ts
+type DomNode = ElementNode | TextNode | CommentNode;
+
+interface ElementNode {
+  id: number;
+  kind: "element";
+  tag: string;                       // lowercased tag name
+  attrs: Record<string, string>;
+  children: DomNode[];
+  canvas_size?: { w: number; h: number };
+  media_src?: string;
+}
+
+interface TextNode    { id: number; kind: "text";    text: string; }
+interface CommentNode { id: number; kind: "comment"; text: string; }
+```
+
+Every node in `initial_dom` is assigned a monotonically-increasing integer `id`. Mutation events reference these ids. New nodes added later (via `dom.add`) carry their own id and may have child nodes that recursively carry ids of their own.
+
+**Per-trial scope.** Node ids are reset at every `t_dom_ready`. Ids in `trials[i]` have no relationship to ids in `trials[j]`.
+
+**Element-specific extras.**
+
+- `canvas_size`: present on `<canvas>` elements; carries `width`/`height` attributes at snapshot time. The pixel contents at any later moment are recorded as separate [`canvas.snapshot`](#canvas-snapshots) events keyed by node id.
+- `media_src`: present on `<video>` and `<audio>` elements; carries `currentSrc` if available, falling back to the `src` attribute.
+
+**What is not captured.**
+
+- Audio/video media data. Only playback events (`media.play`, `media.pause`, etc.) and the source URL are recorded.
+- Shadow DOM. jsPsych does not use it in core; recordings will not capture mutations inside shadow roots.
+- CSSOM rule-level edits (`sheet.insertRule`, `deleteRule`, etc.) made on a captured stylesheet after `start()` without touching the owning element's children. These bypass `MutationObserver` and so are not reflected in [`stylesheet_events`](#stylesheet-events). Edits via `<style>.textContent = …` or `appendChild`/`removeChild` on the inner text node are tracked.
+- Stylesheets attached to the document outside of `<head>` (e.g. a `<style>` placed in `<body>` outside the display element) after `start()`. The initial snapshot picks them up; subsequent changes are not tracked.
+
+## Stylesheets
+
+```ts
+type StylesheetSnapshot =
+  | { id: number; kind: "inline"; css: string;        media: string | null }
+  | { id: number; kind: "link";   href: string; css: string | null; media: string | null };
+```
+
+`stylesheets` is the snapshot of every entry in `document.styleSheets` at session start. It exists so a replayer can re-apply the same CSS to the reconstructed DOM — `initial_dom` carries class hooks like `.jspsych-display-element`, and without the matching rules the replay would render unstyled.
+
+| Field | Description |
+| ----- | ----------- |
+| `id` | Session-unique integer that subsequent [`stylesheet_events`](#stylesheet-events) reference when this sheet is later removed or its rule text changes. |
+| `kind` | `"inline"` for `<style>` tags; `"link"` for `<link rel="stylesheet">`. |
+| `css` | Resolved rule text (joined `cssRules.cssText`). `null` for `<link>` sheets when `cssRules` access throws (cross-origin sheets without CORS headers). |
+| `href` | The link's resolved URL. Replayers can refetch the source from this URL when `css` is `null`. |
+| `media` | The sheet's `media` attribute, or `null` if unset. |
+
+**Replay guidance.** For each entry, inject a `<style>` element with the captured `css` text into the replayer's document head. When `css` is `null` for a `link` entry, fetch the stylesheet from `href` (or substitute a known-good copy of the same asset) and inject the result. Apply the `media` attribute on the injected element so media-conditional rules behave correctly. Track the injected element by `id` so [`stylesheet_events`](#stylesheet-events) can be applied later.
+
+**Limitations.**
+
+- Captured at `start()`. Later mutations to `<head>` stylesheets are tracked separately in [`stylesheet_events`](#stylesheet-events); changes elsewhere (e.g. a `<style>` placed in `<body>` outside the display element) are not.
+- `@import` rules within a captured stylesheet are recorded as text. The imported sheet itself is not inlined; if the replayer's environment cannot resolve the import URL, those rules will not apply.
+- Pseudo-classes (`:hover`, `:focus`) and media queries are recorded as part of the rule text but only take effect during replay if the replayer reproduces the corresponding state or viewport.
+
+## Stylesheet events
+
+```ts
+type StylesheetEvent =
+  | { type: "stylesheet.add";    t: number; sheet: StylesheetSnapshot }
+  | { type: "stylesheet.remove"; t: number; id: number }
+  | { type: "stylesheet.update"; t: number; id: number; css: string };
+```
+
+A chronological log of `<head>` stylesheet changes after `start()`. Plugins commonly inject `<style>` blocks into `<head>` mid-session (e.g. when a survey widget mounts); without this log a replayer would only have the start-of-session snapshot and would render those trials unstyled.
+
+| Type | Field | Meaning |
+| ---- | ----- | ------- |
+| `stylesheet.add` | `sheet` | Full snapshot of the newly attached element, including a fresh `id`. |
+| `stylesheet.remove` | `id` | Id of an entry from `stylesheets` or a prior `stylesheet.add`. The replayer should remove the corresponding injected element. |
+| `stylesheet.update` | `id` | Id of a tracked `<style>` element. |
+|                    | `css` | New resolved rule text. The replayer should overwrite the injected element's text content. |
+
+**Scope.** The observer is rooted at `document.head`. Stylesheet changes inside the trial display element are already represented by the per-trial DOM mutation stream (`dom.add` / `dom.remove` / `dom.text`); they do not appear here. Changes to stylesheets elsewhere in `<body>` (outside the display element) after `start()` are not tracked.
+
+**Update coalescing.** Multiple child mutations to a single `<style>` element delivered in the same observer batch produce one `stylesheet.update` event carrying the final rule text. Updates and adds across separate batches are recorded individually.
+
+**Replay procedure.** Apply each entry in order:
+1. `stylesheet.add` — inject a `<style>` (or `<link>`) matching `sheet.kind`, mirroring the start-of-session snapshot logic.
+2. `stylesheet.remove` — find the previously-injected element by `id` and detach it.
+3. `stylesheet.update` — overwrite the previously-injected element's text content with the new `css`.
+
+## Event types
+
+`events` and `viewport_changes` are arrays of one of the following discriminated unions.
+
+```ts
+type RecordedEvent =
+  | DomMutation
+  | InputRecord
+  | ClipboardRecord
+  | MediaRecord
+  | FocusRecord
+  | ScrollRecord
+  | CanvasSnapshot;
+```
+
+### DOM mutations
+
+```ts
+type DomMutation =
+  | { type: "dom.add";    t: number; parent: number; before: number | null; node: DomNode }
+  | { type: "dom.remove"; t: number; node: number }
+  | { type: "dom.attr";   t: number; node: number; name: string; value: string | null }
+  | { type: "dom.text";   t: number; node: number; text: string };
+```
+
+| Type | Field | Meaning |
+| ---- | ----- | ------- |
+| `dom.add` | `parent` | Id of the parent element. |
+|          | `before` | Id of the next sibling, or `null` to append at end. |
+|          | `node` | Full subtree of the added node, with ids assigned. |
+| `dom.remove` | `node` | Id of the removed node. The node's children are also released. |
+| `dom.attr` | `node` | Id of the element. |
+|           | `name` | Attribute name. |
+|           | `value` | New value, or `null` if the attribute was removed. |
+| `dom.text` | `node` | Id of the text/comment node. |
+|           | `text` | New text content. |
+
+### Input events
+
+```ts
+type InputRecord =
+  | { type: "mouse.move"; t: number; x: number; y: number }
+  | {
+      type: "mouse.down" | "mouse.up" | "mouse.click";
+      t: number; x: number; y: number; button: number; target: number | null;
+    }
+  | {
+      type: "touch.start" | "touch.move" | "touch.end";
+      t: number; touches: { id: number; x: number; y: number }[];
+    }
+  | {
+      type: "key.down" | "key.up";
+      t: number; key: string; code: string;
+      mods: { ctrl: boolean; shift: boolean; alt: boolean; meta: boolean };
+      repeat: boolean; target: number | null;
+    }
+  | { type: "input.value";   t: number; node: number; value: string }
+  | { type: "input.checked"; t: number; node: number; checked: boolean }
+  | { type: "input.select";  t: number; node: number; values: string[] };
+```
+
+`mouse.move` is throttled to one record per animation frame, carrying the latest position. `target` is the id of the element under the event target if it is a tracked node within the trial's DOM, otherwise `null`.
+
+#### Form-state events
+
+The `MutationObserver` only sees the DOM `value` *attribute*; the IDL `value` property the browser writes when a participant types or toggles a control is invisible to it. The three form-state records carry the post-change state directly so a replayer can reconstitute survey responses without replaying keystrokes through a live form.
+
+| Type | Fires on | Carries |
+| ---- | -------- | ------- |
+| `input.value` | `<input>` (text-like types) and `<textarea>` | `value`: the element's current `.value` |
+| `input.checked` | `<input type="checkbox">` and `<input type="radio">` | `checked`: the element's current `.checked` |
+| `input.select` | `<select>` (single and `multiple`) | `values`: the `value` of each currently-selected `<option>`, in DOM order |
+
+`node` references the element's tracked id from the trial DOM (assigned in `initial_dom` or by a `dom.add` event).
+
+`input.value` is throttled to one record per animation frame per element: rapid typing produces one event with the latest value rather than one per keystroke. Pending values are flushed at trial end so the final state is never lost. `input.checked` and `input.select` fire on `change` (i.e. user commits) and are not throttled.
+
+Selecting a different `<input type="radio">` in a group emits a single `input.checked` event for the newly-checked button (`checked: true`); the implicitly-deselected button does not fire a `change` event and therefore produces no record. Replayers should set the chosen radio's `.checked = true` and rely on the browser to clear the rest of the group.
+
+Not captured: `<input type="file">` (uploaded file contents can't be replayed), `contenteditable` regions (their value lives in `textContent` and is reflected by the per-trial DOM mutation stream), and programmatic value writes that don't dispatch an `input` or `change` event.
+
+### Clipboard events
+
+```ts
+interface ClipboardRecord {
+  type: "clipboard.copy" | "clipboard.cut" | "clipboard.paste";
+  t: number;
+  text: string | null;
+  html: string | null;
+  target: number | null;
+}
+```
+
+`text` and `html` carry the `text/plain` and `text/html` representations from the `ClipboardEvent.clipboardData` payload. Either may be `null` if the corresponding type isn't present or access is denied.
+
+### Media events
+
+```ts
+type MediaRecord = {
+  type: "media.play" | "media.pause" | "media.ended" | "media.seeked" | "media.time";
+  t: number;
+  node: number;          // id of the <video>/<audio> element
+  current_time: number;  // element.currentTime, in seconds
+};
+```
+
+`media.time` records throttled `timeupdate` events at roughly 4 Hz and is intended for replay scrubbing rather than exact synchronization.
+
+### Canvas snapshots
+
+```ts
+interface CanvasSnapshot {
+  type: "canvas.snapshot";
+  t: number;
+  node: number;     // id of the <canvas> element
+  data_url: string; // PNG data URL: "data:image/png;base64,…"
+}
+```
+
+The `MutationObserver` cannot see drawing operations inside `<canvas>` (the pixels are not in the DOM tree). Without these events, replay reconstructs the element but renders it blank, so anything the participant drew (e.g. plugin-sketchpad strokes) would be invisible.
+
+**Capture timing.** Snapshots are taken at three moments:
+
+1. After a gesture release (`mouseup` or `touchend`) anywhere within the display element. The actual `toDataURL` call is deferred to the next animation frame so the page has finished painting the post-gesture state.
+2. When a tracked canvas is removed from the DOM mid-trial (jsPsych core clears the display element via `innerHTML = ""` between trials, which would otherwise lose the final pixel state).
+3. When a recording is stopped while a trial is in flight (`stop("aborted")` etc.).
+
+**Throttling and dedupe.** Per-canvas, gesture-driven snapshots are throttled to one every 250 ms; removal- and stop-driven snapshots bypass the throttle so the final state always lands. Identical consecutive data URLs are skipped, so a canvas whose pixels did not change does not produce noise.
+
+**Tainted canvases.** If a canvas drew cross-origin images without CORS headers, `toDataURL` throws `SecurityError`. The recorder catches this, skips the offending canvas, and continues — the recording is never broken by an unreadable canvas.
+
+**Replay procedure.** Track each `<canvas>` you instantiate from `initial_dom` by node id. When a `canvas.snapshot` event arrives, decode `data_url` (e.g. into an `Image` whose `src` is the data URL) and `drawImage` it onto the canvas at `(0, 0)`. This overwrites whatever was there and brings the canvas to the recorded state.
+
+### Focus events
+
+```ts
+interface FocusRecord {
+  type: "focus" | "blur" | "fullscreen.enter" | "fullscreen.exit";
+  t: number;
+}
+```
+
+Window-level focus state. `focus`/`blur` track participant attention (e.g. switching tabs); `fullscreen.enter`/`fullscreen.exit` track whether the browser is in fullscreen mode.
+
+### Scroll events
+
+```ts
+type ScrollRecord =
+  | { type: "scroll.window";  t: number; x: number; y: number }
+  | { type: "scroll.element"; t: number; node: number; x: number; y: number };
+```
+
+`scroll.window` carries `window.scrollX`/`scrollY`. `scroll.element` carries the element's `scrollLeft`/`scrollTop`, keyed by tracked node id. Both are throttled to one record per animation frame per target.
+
+## Viewport state
+
+```ts
+interface ViewportState {
+  w: number;             // window.innerWidth
+  h: number;             // window.innerHeight
+  dpr: number;           // window.devicePixelRatio
+  scale: number;         // visualViewport.scale (pinch zoom; 1.0 = none)
+  offset_x: number;      // visualViewport.offsetLeft (pinch pan)
+  offset_y: number;      // visualViewport.offsetTop
+}
+
+interface ViewportChange extends ViewportState { t: number }
+```
+
+The top-level `viewport` carries the initial state. `viewport_changes` is an append-only log of changes (debounced at ~100ms trailing edge) covering window resize, page zoom (`Ctrl+/Ctrl-`), pinch zoom, and pinch pan.
+
+To find the active viewport at any time `t`, take the last entry in `viewport_changes` with `entry.t <= t`, or fall back to the top-level `viewport` if there is none.
+
+## RNG calls
+
+```ts
+interface RngCall {
+  t: number;
+  fn: string;            // currently always "Math.random"
+  args: JsonValue;       // currently always []
+  result: JsonValue;     // the number that was returned
+}
+```
+
+While recording, `Math.random` is wrapped so every call is logged into the session-level `rng_calls` array, in the order it was consumed. This includes calls made:
+
+- During trial parameter evaluation (before `t_start`).
+- During trial execution (between `t_start` and `t_end`).
+- During the post-trial gap.
+- During the experimenter's session-level `on_finish` callback.
+
+For deterministic re-execution, a replayer can patch `Math.random` to return `rng_calls[cursor++].result` and let trial code re-consume the tape in order.
+
+## End reasons
+
+| Value | Meaning |
+| ----- | ------- |
+| `"finished"` | The experiment ran to completion. |
+| `"aborted"` | `jsPsych.abortExperiment()` was called. |
+| `"unload"` | Reserved for future use; not currently emitted by core. |
+| `null` | The recording is still active or was retrieved before `stop()` ran. |
+
+## Privacy considerations
+
+- **Text input is captured verbatim.** Any text typed into form fields, including in survey plugins, appears in the DOM mutation log. Inform participants accordingly when enabling `record_session`.
+- **Clipboard payloads are recorded.** Content the participant copies, cuts, or pastes within the experiment is preserved.
+- **Math.random is wrapped while recording is active.** The wrapper is removed when the experiment ends. User code that calls `Math.random` will have its outputs in `rng_calls`.
+
+## Backward compatibility
+
+`schema_version: 1` is the contract for v1 recorders. Additive fields (new event types, new optional fields on existing types) may be introduced in future minor revisions without bumping the major version. Replayers should ignore unrecognized event `type` values rather than failing.
diff --git a/mkdocs.yml b/mkdocs.yml
index edb129a827..81e636d943 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -73,6 +73,7 @@ nav:
   - 'jsPsych.turk': 'reference/jspsych-turk.md'
   - 'jsPsych.utils': 'reference/jspsych-utils.md'
   - 'jsPsych.pluginAPI': 'reference/jspsych-pluginAPI.md'
+  - 'Session Recording Schema': 'reference/session-recording-schema.md'
 - Plugins:
   - 'List of Plugins': 'plugins/list-of-plugins.md'
   - 'animation': 'plugins/animation.md'
diff --git a/packages/jspsych/jest.config.cjs b/packages/jspsych/jest.config.cjs
index 6ac19d5cf3..ec3aeebb24 100644
--- a/packages/jspsych/jest.config.cjs
+++ b/packages/jspsych/jest.config.cjs
@@ -1 +1,9 @@
-module.exports = require("@jspsych/config/jest").makePackageConfig(__dirname);
+const baseConfig = require("@jspsych/config/jest").makePackageConfig(__dirname);
+
+module.exports = {
+  ...baseConfig,
+  // Polyfill Web Streams / Fetch / TextEncoder onto the jsdom global so
+  // code that uses `CompressionStream`, `Response`, etc. (e.g. the
+  // session recording's compressed-output path) is testable here.
+  setupFiles: [...(baseConfig.setupFiles ?? []), require.resolve("./tests/jsdom-polyfills.cjs")],
+};
diff --git a/packages/jspsych/src/JsPsych.ts b/packages/jspsych/src/JsPsych.ts
index 1a7d519174..9139bf11c5 100644
--- a/packages/jspsych/src/JsPsych.ts
+++ b/packages/jspsych/src/JsPsych.ts
@@ -9,6 +9,7 @@ import { JsPsychExtension } from "./modules/extensions";
 import { PluginAPI, createJointPluginAPIObject } from "./modules/plugin-api";
 import { JsPsychPlugin } from "./modules/plugins";
 import * as randomization from "./modules/randomization";
+import { SessionRecorder, SessionRecording } from "./modules/recording";
 import * as turk from "./modules/turk";
 import * as utils from "./modules/utils";
 import { ProgressBar } from "./ProgressBar";
@@ -66,6 +67,8 @@ export class JsPsych {
 
   private extensionManager: ExtensionManager;
 
+  private sessionRecorder?: SessionRecorder;
+
   constructor(options?) {
     // override default options if user specifies an option
     options = {
@@ -86,10 +89,15 @@ export class JsPsych {
       override_safe_mode: false,
       case_sensitive_responses: false,
       extensions: [],
+      record_session: false,
       ...options,
     };
     this.options = options;
 
+    if (options.record_session) {
+      this.sessionRecorder = new SessionRecorder({ jspsychVersion: version });
+    }
+
     autoBind(this); // so we can pass JsPsych methods as callbacks and `this` remains the JsPsych instance
 
     // detect whether page is running in browser as a local file, and if so, disable web audio and
@@ -147,14 +155,22 @@ export class JsPsych {
 
     this.experimentStartTime = new Date();
 
-    await this.timeline.run();
-    await Promise.resolve(this.options.on_finish(this.data.get()));
+    this.sessionRecorder?.start(this.getDisplayElement(), this.getDisplayContainerElement());
 
-    if (this.endMessage) {
-      this.getDisplayElement().innerHTML = this.endMessage;
-    }
+    // The recorder patches `Math.random` and attaches global listeners; we
+    // must always tear it down (and remove interaction listeners), even if
+    // the timeline run or the user-provided `on_finish` callback throws.
+    try {
+      await this.timeline.run();
+      await Promise.resolve(this.options.on_finish(this.data.get()));
 
-    this.data.removeInteractionListeners();
+      if (this.endMessage) {
+        this.getDisplayElement().innerHTML = this.endMessage;
+      }
+    } finally {
+      this.data.removeInteractionListeners();
+      this.sessionRecorder?.stop("finished");
+    }
   }
 
   async simulate(
@@ -196,12 +212,86 @@ export class JsPsych {
     return this.displayContainerElement;
   }
 
+  /**
+   * Returns the high-fidelity session recording produced when `initJsPsych` is
+   * called with `record_session: true`. Returns `undefined` when recording is
+   * not enabled. The recording is suitable for serialization (e.g. via
+   * `JSON.stringify`) and persistence alongside the trial data.
+   */
+  getSessionRecording(): SessionRecording | undefined {
+    return this.sessionRecorder?.getRecording();
+  }
+
+  /**
+   * Returns the session recording as a gzip-compressed `Blob` with MIME type
+   * `application/gzip`. Returns `undefined` when recording is not enabled.
+   * Typical recordings compress 8-15x — useful when persisting alongside
+   * trial data or uploading to a backend. Uses the browser's built-in
+   * `CompressionStream`, so no extra dependency is bundled.
+   *
+   * @example Upload to a backend:
+   * ```ts
+   * const blob = await jsPsych.getSessionRecordingCompressed();
+   * if (blob) {
+   *   await fetch("/upload", { method: "POST", body: blob });
+   * }
+   * ```
+   *
+   * @example Offer the participant a download:
+   * ```ts
+   * const blob = await jsPsych.getSessionRecordingCompressed();
+   * if (blob) {
+   *   const a = document.createElement("a");
+   *   a.href = URL.createObjectURL(blob);
+   *   a.download = "session.json.gz";
+   *   a.click();
+   *   URL.revokeObjectURL(a.href);
+   * }
+   * ```
+   *
+   * @example Stash in jsPsych's data record (base64-encoded):
+   * ```ts
+   * const blob = await jsPsych.getSessionRecordingCompressed();
+   * if (blob) {
+   *   const buf = new Uint8Array(await blob.arrayBuffer());
+   *   let binary = "";
+   *   for (const byte of buf) binary += String.fromCharCode(byte);
+   *   jsPsych.data.addProperties({ session_recording_b64: btoa(binary) });
+   * }
+   * ```
+   */
+  async getSessionRecordingCompressed(): Promise<Blob | undefined> {
+    const recording = this.getSessionRecording();
+    if (!recording) return undefined;
+    // Drive the compression stream directly via its writer/reader so the
+    // implementation depends only on `TextEncoder`, `CompressionStream`,
+    // and `Blob` — all available in evergreen browsers (Chrome 80,
+    // Firefox 113, Safari 16.4) and in Node 18+.
+    const json = JSON.stringify(recording);
+    const cs = new CompressionStream("gzip");
+    const writer = cs.writable.getWriter();
+    // Don't await the writer; the reader loop below pulls chunks out as
+    // the writer pushes them in. Awaiting first would deadlock on
+    // backpressure for large recordings.
+    writer.write(new TextEncoder().encode(json));
+    writer.close();
+    const reader = cs.readable.getReader();
+    const chunks: Uint8Array[] = [];
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+    }
+    return new Blob(chunks, { type: "application/gzip" });
+  }
+
   abortExperiment(endMessage?: string, data = {}) {
     this.endMessage = endMessage;
     this.timeline.abort();
     this.pluginAPI.cancelAllKeyboardResponses();
     this.pluginAPI.clearAllTimeouts();
     this.finishTrial(data);
+    this.sessionRecorder?.stop("aborted");
   }
 
   abortCurrentTimeline() {
@@ -394,6 +484,10 @@ export class JsPsych {
 
   private timelineDependencies: TimelineNodeDependencies = {
     onTrialStart: (trial: Trial) => {
+      this.sessionRecorder?.onTrialStart({
+        trial_index: trial.index ?? -1,
+        plugin: trial.pluginClass?.["info"]?.name ?? "unknown",
+      });
       this.options.on_trial_start(trial.trialObject);
 
       // apply the focus to the element containing the experiment.
@@ -402,6 +496,10 @@ export class JsPsych {
       this.getDisplayElement().scrollTop = 0;
     },
 
+    onTrialLoad: (_trial: Trial) => {
+      this.sessionRecorder?.onTrialLoad();
+    },
+
     onTrialResultAvailable: (trial: Trial) => {
       const result = trial.getResult();
       if (result) {
@@ -412,6 +510,7 @@ export class JsPsych {
 
     onTrialFinished: (trial: Trial) => {
       const result = trial.getResult();
+      this.sessionRecorder?.onTrialFinish(result);
       this.options.on_trial_finish(result);
 
       if (result) {
diff --git a/packages/jspsych/src/modules/recording.ts b/packages/jspsych/src/modules/recording.ts
new file mode 100644
index 0000000000..727c544cd6
--- /dev/null
+++ b/packages/jspsych/src/modules/recording.ts
@@ -0,0 +1,1705 @@
+import * as randomization from "./randomization";
+
+// ---------------------------------------------------------------------------
+// Schema types (schema_version: 1)
+// ---------------------------------------------------------------------------
+
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+export interface SessionRecording {
+  schema_version: 1;
+  jspsych_version: string;
+  recording_started_at: string;
+  recording_started_at_perf: number;
+  user_agent: string;
+  viewport: ViewportState;
+  rng: { seed: string | null; math_random_patched: boolean };
+  display_element_id: string;
+  stylesheets: StylesheetSnapshot[];
+  // Chronological log of `<head>` stylesheet mutations after `start()`.
+  // Initial state is in `stylesheets`; this records subsequent additions,
+  // removals, and `<style>` text edits so the replayer can apply them
+  // alongside the per-trial DOM event stream.
+  stylesheet_events: StylesheetEvent[];
+  trials: TrialRecording[];
+  viewport_changes: ViewportChange[];
+  // Chronological log of every Math.random output consumed during the
+  // session. Captured at session scope (rather than per-trial) so calls
+  // outside trial boundaries — pre-trial parameter evaluation, post-trial
+  // gaps, the experimenter's `on_finish` — are never dropped. A replayer
+  // consumes this list in order.
+  rng_calls: RngCall[];
+  ended_at_perf: number | null;
+  end_reason: "finished" | "aborted" | "unload" | null;
+}
+
+// A snapshot of one stylesheet attached to the document. `inline` covers
+// `<style>` tags; `link` covers `<link rel="stylesheet">`. `css` is the
+// resolved rule text where readable; cross-origin sheets throw SecurityError
+// on `cssRules` access, so for those we record `href` only and leave `css`
+// null so a replayer can fetch the source out-of-band. `id` is unique within
+// the session and shared with `stylesheet_events` so add/remove/update
+// events can reference snapshots created at start.
+export type StylesheetSnapshot =
+  | { id: number; kind: "inline"; css: string; media: string | null }
+  | { id: number; kind: "link"; href: string; css: string | null; media: string | null };
+
+// Session-scope log entries for `<head>` stylesheet changes after start.
+// `stylesheet.add` carries a full snapshot (with a newly-assigned `id`);
+// `stylesheet.remove` and `stylesheet.update` reference an existing `id`
+// from `stylesheets` or a prior `add` event.
+export type StylesheetEvent =
+  | { type: "stylesheet.add"; t: number; sheet: StylesheetSnapshot }
+  | { type: "stylesheet.remove"; t: number; id: number }
+  | { type: "stylesheet.update"; t: number; id: number; css: string };
+
+export interface ViewportState {
+  w: number;
+  h: number;
+  dpr: number;
+  scale: number;
+  offset_x: number;
+  offset_y: number;
+}
+
+export interface ViewportChange extends ViewportState {
+  t: number;
+}
+
+export interface TrialRecording {
+  trial_index: number;
+  t_start: number;
+  t_dom_ready: number | null;
+  t_end: number | null;
+  plugin: string;
+  initial_dom: DomNode | null;
+  events: RecordedEvent[];
+  trial_data: JsonValue;
+}
+
+export type DomNode = ElementNode | TextNode | CommentNode;
+
+export interface ElementNode {
+  id: number;
+  kind: "element";
+  tag: string;
+  attrs: Record<string, string>;
+  children: DomNode[];
+  canvas_size?: { w: number; h: number };
+  media_src?: string;
+}
+
+export interface TextNode {
+  id: number;
+  kind: "text";
+  text: string;
+}
+
+export interface CommentNode {
+  id: number;
+  kind: "comment";
+  text: string;
+}
+
+export type RecordedEvent =
+  | DomMutation
+  | InputRecord
+  | ClipboardRecord
+  | MediaRecord
+  | FocusRecord
+  | ScrollRecord
+  | CanvasSnapshot;
+
+export type DomMutation =
+  | { type: "dom.add"; t: number; parent: number; before: number | null; node: DomNode }
+  | { type: "dom.remove"; t: number; node: number }
+  | { type: "dom.attr"; t: number; node: number; name: string; value: string | null }
+  | { type: "dom.text"; t: number; node: number; text: string };
+
+export type InputRecord =
+  | { type: "mouse.move"; t: number; x: number; y: number }
+  | {
+      type: "mouse.down" | "mouse.up" | "mouse.click";
+      t: number;
+      x: number;
+      y: number;
+      button: number;
+      target: number | null;
+    }
+  | {
+      type: "touch.start" | "touch.move" | "touch.end";
+      t: number;
+      touches: { id: number; x: number; y: number }[];
+    }
+  | {
+      type: "key.down" | "key.up";
+      t: number;
+      key: string;
+      code: string;
+      mods: { ctrl: boolean; shift: boolean; alt: boolean; meta: boolean };
+      repeat: boolean;
+      target: number | null;
+    }
+  // Form-state changes. The MutationObserver only sees the `value` *attribute*,
+  // not the IDL property the browser writes when a participant types or
+  // toggles a control. These records carry the post-change value/checked/
+  // selection so a replayer can reconstitute survey responses without
+  // having to replay keystrokes through a live form.
+  | { type: "input.value"; t: number; node: number; value: string }
+  | { type: "input.checked"; t: number; node: number; checked: boolean }
+  | { type: "input.select"; t: number; node: number; values: string[] };
+
+export interface ClipboardRecord {
+  type: "clipboard.copy" | "clipboard.cut" | "clipboard.paste";
+  t: number;
+  text: string | null;
+  html: string | null;
+  target: number | null;
+}
+
+export type MediaRecord = {
+  type: "media.play" | "media.pause" | "media.ended" | "media.seeked" | "media.time";
+  t: number;
+  node: number;
+  current_time: number;
+};
+
+export interface FocusRecord {
+  type: "focus" | "blur" | "fullscreen.enter" | "fullscreen.exit";
+  t: number;
+}
+
+export type ScrollRecord =
+  | { type: "scroll.window"; t: number; x: number; y: number }
+  | { type: "scroll.element"; t: number; node: number; x: number; y: number };
+
+// Captures `<canvas>` pixel state as a PNG data URL. The MutationObserver
+// can't see drawing operations inside `<canvas>`; without these events a
+// replayer reconstructs the element but renders it blank, so anything the
+// participant drew (e.g. plugin-sketchpad strokes) would be invisible.
+// Emitted at trial load (initial baseline), gesture boundaries
+// (mouseup/touchend/pointerup) and trial end, with per-canvas throttling.
+//
+// `region` distinguishes a full-canvas baseline from an incremental patch:
+//   - omitted: `data_url` is the entire canvas, to be drawn at (0, 0)
+//     after clearing. The first snapshot per canvas is always full so
+//     subsequent partials have a baseline to layer on.
+//   - present: `data_url` is a cropped rectangle of the canvas's current
+//     state. The replayer composites it at (region.x, region.y) without
+//     touching the rest of the canvas.
+// The recorder emits a partial when the changed bounding box covers less
+// than ~80% of the canvas; otherwise it emits a full snapshot since the
+// per-pixel cost of compositing approaches a full re-render.
+export interface CanvasSnapshot {
+  type: "canvas.snapshot";
+  t: number;
+  node: number;
+  data_url: string;
+  region?: { x: number; y: number; w: number; h: number };
+}
+
+export interface RngCall {
+  t: number;
+  fn: string;
+  args: JsonValue;
+  result: JsonValue;
+}
+
+// ---------------------------------------------------------------------------
+// SessionRecorder
+// ---------------------------------------------------------------------------
+
+const SCHEMA_VERSION = 1;
+const VIEWPORT_DEBOUNCE_MS = 100;
+const MEDIA_TIME_THROTTLE_MS = 250;
+// Per-canvas minimum gap between gesture-driven snapshots. Bounds the
+// `toDataURL` cost for users who rapidly click/release; trial-end
+// captures bypass this so the final state always lands.
+const CANVAS_SNAPSHOT_MIN_INTERVAL_MS = 250;
+// When the changed bounding box covers more than this fraction of the
+// canvas, fall back to a full snapshot. Cropping a near-full region
+// pays the `getImageData` + `drawImage` + `toDataURL` cost of a full
+// snapshot anyway, so the partial-snapshot bookkeeping is wasted.
+const CANVAS_FULL_SNAPSHOT_AREA_FRACTION = 0.8;
+// Per-canvas minimum gap between draw-triggered animation snapshots.
+// Distinct from `CANVAS_SNAPSHOT_MIN_INTERVAL_MS`, which throttles the
+// gesture-driven path. ~15 Hz is enough fidelity for replaying typical
+// canvas animations without producing 60 PNGs/sec for a continuously-
+// repainting stimulus.
+const CANVAS_ANIMATION_MIN_INTERVAL_MS = 66;
+// Pixel-mutating methods on `CanvasRenderingContext2D`. Wrapping these
+// lets the recorder notice when a canvas was redrawn between gestures
+// (the original heuristic only snapshotted at mouseup/touchend), so
+// canvases driven by animation loops or non-gesture timers can still
+// be reconstructed in the replay. Path-state methods (beginPath,
+// moveTo, lineTo, …) are intentionally omitted: they don't change
+// pixels until `fill` or `stroke` is called.
+const CANVAS_DRAW_METHODS = [
+  "clearRect",
+  "fillRect",
+  "strokeRect",
+  "fill",
+  "stroke",
+  "fillText",
+  "strokeText",
+  "drawImage",
+  "putImageData",
+] as const;
+
+export interface SessionRecorderOptions {
+  jspsychVersion: string;
+}
+
+export class SessionRecorder {
+  private readonly jspsychVersion: string;
+  private recording: SessionRecording;
+  private displayElement: HTMLElement | null = null;
+  // Outermost layout root for the experiment. The spine in `initial_dom`
+  // walks from `displayElement` up to and including this element so the
+  // jsPsych layout containers (and the host's classes/attrs) are
+  // captured. When unset we fall back to serializing only `displayElement`.
+  private displayContainer: HTMLElement | null = null;
+  private running = false;
+
+  private startPerf = 0;
+  private currentTrial: TrialRecording | null = null;
+
+  private nodeIds = new WeakMap<Node, number>();
+  private nextNodeId = 1;
+
+  private mutationObserver: MutationObserver | null = null;
+
+  // Session-scope: tracks stylesheet `<style>`/`<link>` elements in
+  // `<head>` so add/remove/update events can be emitted by stable id.
+  private headObserver: MutationObserver | null = null;
+  private styleNodeIds = new WeakMap<Node, number>();
+  private nextStylesheetId = 1;
+
+  private mouseRafScheduled = false;
+  private lastMouseX = 0;
+  private lastMouseY = 0;
+  private mouseDirty = false;
+
+  private scrollRafScheduled = false;
+  // Pending scroll state to flush at next animation frame. Key "window"
+  // refers to the document scroll; numeric keys are tracked node IDs.
+  private pendingScroll: Map<number | "window", { x: number; y: number }> = new Map();
+
+  private inputRafScheduled = false;
+  // Latest value-per-input collected within the current animation frame.
+  // Coalesced so a fast typist produces one record per RAF rather than
+  // one per keystroke (matching how mouse.move is throttled).
+  private pendingInput: Map<number, string> = new Map();
+
+  private viewportTimer: ReturnType<typeof setTimeout> | null = null;
+  private lastViewport: ViewportState | null = null;
+
+  private mediaListeners = new WeakMap<HTMLMediaElement, (ev: Event) => void>();
+  private mediaTimeLast = new WeakMap<HTMLMediaElement, number>();
+  // Strong ref to currently tracked media elements so we can iterate and
+  // remove their listeners when the trial ends. Cleared on detach.
+  private mediaTrackedElements = new Set<HTMLMediaElement>();
+
+  // Strong ref to canvas elements within the current trial's display
+  // subtree. Used to drive deferred snapshotting after gestures and at
+  // trial end. Per-canvas throttle/dedupe state is held alongside.
+  private canvasTrackedElements = new Set<HTMLCanvasElement>();
+  private canvasLastSnapshot = new WeakMap<HTMLCanvasElement, string>();
+  private canvasLastSnapshotTime = new WeakMap<HTMLCanvasElement, number>();
+  private canvasSnapshotScheduled = false;
+  // Last full-canvas pixel buffer per tracked canvas, used to compute
+  // the bounding box of changed pixels so subsequent snapshots can ship
+  // only the dirty rectangle. Cleared on canvas removal and on trial
+  // teardown. Absent for canvases that don't expose a 2d context (e.g.
+  // WebGL) — those always emit full snapshots.
+  private canvasShadowData = new WeakMap<HTMLCanvasElement, ImageData>();
+  private canvasInitialSnapshotScheduled = false;
+  // Set to true by the patched 2d-context draw methods whenever a
+  // tracked canvas is mutated. The frame tick reads-and-clears it to
+  // decide which canvases need a fresh diff.
+  private canvasDirty = new WeakMap<HTMLCanvasElement, boolean>();
+  // Last time the draw-detection path emitted (or attempted to emit) a
+  // snapshot for each canvas. Drives `CANVAS_ANIMATION_MIN_INTERVAL_MS`
+  // throttling without conflicting with the gesture-path throttle in
+  // `canvasLastSnapshotTime`.
+  private canvasAnimationLastTime = new WeakMap<HTMLCanvasElement, number>();
+  private canvasFrameLoopScheduled = false;
+  // Patched draw methods on `CanvasRenderingContext2D.prototype`. We
+  // restore them on `stop()` so opting in to recording does not leave
+  // wrappers in place after the experiment ends, even if the recorder
+  // auto-stopped due to abort or unload.
+  private canvasContextPatched = false;
+  private originalCanvasMethods = new Map<string, Function>();
+
+  // Reference to whatever `Math.random` was immediately before the recorder
+  // started. Restored verbatim on stop so opting into recording does not
+  // permanently alter `Math.random`, even if we auto-seeded.
+  private originalMathRandom: () => number = Math.random;
+  private mathRandomPatched = false;
+
+  private boundHandlers: Array<{
+    target: EventTarget;
+    type: string;
+    handler: EventListenerOrEventListenerObject;
+    options?: AddEventListenerOptions | boolean;
+    // True for handlers attached during a trial; cleared together at
+    // trial end. Session-scoped handlers (e.g. window resize) leave it
+    // unset and are torn down in `detachSessionListeners`.
+    trial?: boolean;
+  }> = [];
+
+  constructor(options: SessionRecorderOptions) {
+    this.jspsychVersion = options.jspsychVersion;
+    this.recording = this.createBlankRecording();
+  }
+
+  private createBlankRecording(): SessionRecording {
+    return {
+      schema_version: SCHEMA_VERSION,
+      jspsych_version: this.jspsychVersion,
+      recording_started_at: "",
+      recording_started_at_perf: 0,
+      user_agent: typeof navigator !== "undefined" ? navigator.userAgent : "",
+      viewport: { w: 0, h: 0, dpr: 1, scale: 1, offset_x: 0, offset_y: 0 },
+      rng: { seed: null, math_random_patched: false },
+      display_element_id: "",
+      stylesheets: [],
+      stylesheet_events: [],
+      trials: [],
+      viewport_changes: [],
+      rng_calls: [],
+      ended_at_perf: null,
+      end_reason: null,
+    };
+  }
+
+  // -------- lifecycle --------
+
+  start(displayElement: HTMLElement, displayContainer?: HTMLElement) {
+    // Idempotent: starting an already-running recorder is a no-op.
+    if (this.running) return;
+
+    // If the recorder previously ran and stopped, replace the recording
+    // object with a blank one so this `start()` begins a fresh session.
+    // The previous recording remains accessible to any caller who captured
+    // it via `getRecording()` before restarting.
+    if (this.recording.end_reason !== null) {
+      this.recording = this.createBlankRecording();
+    }
+
+    this.running = true;
+    this.displayElement = displayElement;
+    this.displayContainer = displayContainer ?? null;
+    this.startPerf = performance.now();
+    this.recording.recording_started_at = new Date().toISOString();
+    this.recording.recording_started_at_perf = this.startPerf;
+    this.recording.display_element_id = displayElement.id || "";
+    this.recording.viewport = readViewport();
+    this.lastViewport = { ...this.recording.viewport };
+
+    // Reset per-session ephemeral state so a reused recorder doesn't carry
+    // stale node ids, throttle flags, or pending event buffers.
+    this.currentTrial = null;
+    this.resetNodeIds();
+    this.styleNodeIds = new WeakMap();
+    this.nextStylesheetId = 1;
+    this.recording.stylesheets = this.captureStylesheets();
+    this.mouseDirty = false;
+    this.mouseRafScheduled = false;
+    this.scrollRafScheduled = false;
+    this.pendingScroll.clear();
+    this.inputRafScheduled = false;
+    this.pendingInput.clear();
+    this.canvasFrameLoopScheduled = false;
+    this.canvasInitialSnapshotScheduled = false;
+
+    this.patchMathRandom();
+    this.patchCanvasContext();
+    this.attachSessionListeners();
+  }
+
+  stop(reason: "finished" | "aborted" | "unload" = "finished") {
+    // Idempotent: stopping an already-stopped recorder is a no-op.
+    if (!this.running) return;
+
+    // Flush any throttled events from an in-flight trial so events near
+    // an abort boundary aren't silently dropped.
+    if (this.currentTrial !== null) {
+      this.flushPendingMouse();
+      this.flushPendingScroll();
+      this.flushPendingInput();
+      this.captureCanvasSnapshots(true);
+      this.currentTrial.t_end = this.t();
+      this.currentTrial = null;
+    }
+
+    this.detachTrialListeners();
+    this.detachSessionListeners();
+    this.unpatchMathRandom();
+    this.unpatchCanvasContext();
+    this.recording.ended_at_perf = this.t();
+    this.recording.end_reason = reason;
+    this.running = false;
+  }
+
+  getRecording(): SessionRecording {
+    return this.recording;
+  }
+
+  // -------- per-trial hooks --------
+
+  onTrialStart(info: { trial_index: number; plugin: string }) {
+    this.currentTrial = {
+      trial_index: info.trial_index,
+      t_start: this.t(),
+      t_dom_ready: null,
+      t_end: null,
+      plugin: info.plugin,
+      initial_dom: null,
+      events: [],
+      trial_data: null,
+    };
+    this.recording.trials.push(this.currentTrial);
+  }
+
+  onTrialLoad() {
+    if (!this.currentTrial || !this.displayElement) return;
+    this.currentTrial.t_dom_ready = this.t();
+    this.resetNodeIds();
+    this.currentTrial.initial_dom = this.serializeDisplaySpine(this.displayElement);
+    this.attachTrialListeners();
+    this.scanForMediaElements(this.displayElement);
+    // `scanForCanvasElements` registers each canvas via
+    // `trackCanvasElement`, which schedules the initial baseline
+    // snapshot for the next animation frame so synchronously-drawn
+    // stimuli (canvas-button-response, canvas-keyboard-response, ...)
+    // are captured before any interaction.
+    this.scanForCanvasElements(this.displayElement);
+  }
+
+  onTrialFinish(trialData: unknown) {
+    if (!this.currentTrial) return;
+    this.flushPendingMouse();
+    this.flushPendingScroll();
+    this.flushPendingInput();
+    this.captureCanvasSnapshots(true);
+    this.detachTrialListeners();
+    this.currentTrial.t_end = this.t();
+    this.currentTrial.trial_data = serializeJson(trialData);
+    this.currentTrial = null;
+  }
+
+  // -------- session listeners (viewport, focus) --------
+
+  private attachSessionListeners() {
+    this.bind(window, "resize", this.scheduleViewportRead);
+    if (window.visualViewport) {
+      this.bind(window.visualViewport, "resize", this.scheduleViewportRead);
+      this.bind(window.visualViewport, "scroll", this.scheduleViewportRead);
+    }
+    this.bind(window, "focus", () => this.pushFocus("focus"));
+    this.bind(window, "blur", () => this.pushFocus("blur"));
+    this.bind(document, "fullscreenchange", () => {
+      this.pushFocus(document.fullscreenElement ? "fullscreen.enter" : "fullscreen.exit");
+    });
+
+    // Watch <head> for stylesheet add/remove and <style> text edits.
+    // Plugins commonly inject `<style>` blocks into `<head>` mid-session;
+    // without this observer those rules would be missing from replay.
+    if (document.head) {
+      this.headObserver = new MutationObserver((records) => this.handleHeadMutations(records));
+      this.headObserver.observe(document.head, {
+        childList: true,
+        subtree: true,
+        characterData: true,
+      });
+    }
+  }
+
+  private detachSessionListeners() {
+    if (this.viewportTimer) {
+      clearTimeout(this.viewportTimer);
+      this.viewportTimer = null;
+    }
+    if (this.headObserver) {
+      // Drain any records the observer has queued but not yet delivered
+      // so changes near `stop()` aren't dropped.
+      const pending = this.headObserver.takeRecords();
+      if (pending.length > 0) this.handleHeadMutations(pending);
+      this.headObserver.disconnect();
+      this.headObserver = null;
+    }
+    for (const b of this.boundHandlers) {
+      b.target.removeEventListener(b.type, b.handler, b.options);
+    }
+    this.boundHandlers = [];
+  }
+
+  private scheduleViewportRead = () => {
+    if (this.viewportTimer) clearTimeout(this.viewportTimer);
+    this.viewportTimer = setTimeout(() => {
+      this.viewportTimer = null;
+      const v = readViewport();
+      const last = this.lastViewport;
+      if (
+        !last ||
+        last.w !== v.w ||
+        last.h !== v.h ||
+        last.dpr !== v.dpr ||
+        last.scale !== v.scale ||
+        last.offset_x !== v.offset_x ||
+        last.offset_y !== v.offset_y
+      ) {
+        this.lastViewport = v;
+        this.recording.viewport_changes.push({ t: this.t(), ...v });
+      }
+    }, VIEWPORT_DEBOUNCE_MS);
+  };
+
+  private pushFocus(type: FocusRecord["type"]) {
+    this.pushEvent({ type, t: this.t() });
+  }
+
+  // -------- per-trial listeners (DOM, input, media) --------
+
+  private attachTrialListeners() {
+    if (!this.displayElement) return;
+    const el = this.displayElement;
+
+    this.mutationObserver = new MutationObserver((records) => this.handleMutations(records));
+    this.mutationObserver.observe(el, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      characterData: true,
+    });
+
+    // Mouse and touch listeners are scoped to `window`/`document` in the
+    // capture phase rather than to `displayElement`. The display element
+    // is `#jspsych-content`, which is typically narrower than the
+    // viewport (centered, optionally constrained by `experiment_width`).
+    // Element-scoped listeners only fire while the cursor is over the
+    // element or its descendants, so a participant moving toward the
+    // browser chrome to resize/move the window — or drawing into a
+    // canvas corner that extends past `#jspsych-content` — would
+    // produce no `mouse.move` / `touch.move` events for the entire
+    // excursion. The replay would then show the cursor stuck at its
+    // last known position until it returned. Coordinates are already
+    // viewport-relative (`clientX`/`clientY`) so widening the scope
+    // doesn't change the recorded values; it only adds the events that
+    // were silently dropped before. `targetId` may now resolve to
+    // `null` when the target is outside the recorded display spine,
+    // which the schema already permits.
+    this.bind(window, "mousemove", this.handleMouseMove, true);
+    this.bind(window, "mousedown", this.handleMouseButton("mouse.down"), true);
+    this.bind(window, "mouseup", this.handleMouseButton("mouse.up"), true);
+    this.bind(window, "click", this.handleMouseButton("mouse.click"), true);
+    this.bind(document, "touchstart", this.handleTouch("touch.start"), {
+      passive: true,
+      capture: true,
+    });
+    this.bind(document, "touchmove", this.handleTouch("touch.move"), {
+      passive: true,
+      capture: true,
+    });
+    this.bind(document, "touchend", this.handleTouch("touch.end"), {
+      passive: true,
+      capture: true,
+    });
+    // Keyboard and clipboard events are listened at document scope in the
+    // capture phase: they may be dispatched on any element (including
+    // descendants of the body), and capture-phase listening ensures we see
+    // them before any user-attached handler can call stopPropagation.
+    this.bind(document, "keydown", this.handleKey("key.down"), true);
+    this.bind(document, "keyup", this.handleKey("key.up"), true);
+    this.bind(document, "copy", this.handleClipboard("clipboard.copy"), true);
+    this.bind(document, "cut", this.handleClipboard("clipboard.cut"), true);
+    this.bind(document, "paste", this.handleClipboard("clipboard.paste"), true);
+    // Scroll events do not bubble, so capture-phase listening at document
+    // scope catches scroll on any descendant element. Window scrolling is
+    // handled by the same listener via a Document target check.
+    this.bind(document, "scroll", this.handleScroll, true);
+    // Form-state events. `input` covers text fields, textareas, and
+    // sliders (fires on every value change). `change` covers checkboxes,
+    // radios, and selects (fires on commit). Capture phase at document
+    // scope so nothing in user code can stopPropagation past us.
+    this.bind(document, "input", this.handleInputEvent, true);
+    this.bind(document, "change", this.handleChangeEvent, true);
+  }
+
+  private detachTrialListeners() {
+    if (this.mutationObserver) {
+      this.mutationObserver.disconnect();
+      this.mutationObserver = null;
+    }
+    this.detachMediaListeners();
+    // WeakMap entries for the released canvases will be GC'd once the
+    // tracked-set strong refs drop here; explicit deletion happens in
+    // `releaseSubtree` for canvases removed mid-trial.
+    this.canvasTrackedElements.clear();
+    this.canvasSnapshotScheduled = false;
+    this.canvasInitialSnapshotScheduled = false;
+    // Tear down only the trial-scoped handlers; session-scoped handlers
+    // (resize, focus, blur, fullscreenchange) stay attached until stop().
+    const remaining: typeof this.boundHandlers = [];
+    for (const b of this.boundHandlers) {
+      if (b.trial) {
+        b.target.removeEventListener(b.type, b.handler, b.options);
+      } else {
+        remaining.push(b);
+      }
+    }
+    this.boundHandlers = remaining;
+  }
+
+  // -------- mutation handling --------
+
+  private handleMutations(records: MutationRecord[]) {
+    const t = this.t();
+    for (const r of records) {
+      try {
+        if (r.type === "childList") {
+          for (const removed of Array.from(r.removedNodes)) {
+            const id = this.nodeIds.get(removed);
+            if (id !== undefined) {
+              this.pushEvent({ type: "dom.remove", t, node: id });
+              this.releaseSubtree(removed);
+            }
+          }
+          const parentId = this.nodeIds.get(r.target);
+          if (parentId === undefined) continue;
+          for (const added of Array.from(r.addedNodes)) {
+            if (this.nodeIds.has(added)) continue;
+            const node = this.serializeNode(added);
+            if (!node) continue;
+            const before = this.findTrackedSibling(added.nextSibling);
+            this.pushEvent({ type: "dom.add", t, parent: parentId, before, node });
+            if (added instanceof HTMLMediaElement) this.attachMediaListeners(added);
+            else if (added instanceof Element) this.scanForMediaElements(added);
+            if (added instanceof HTMLCanvasElement) this.trackCanvasElement(added);
+            else if (added instanceof Element) this.scanForCanvasElements(added);
+          }
+        } else if (r.type === "attributes") {
+          const id = this.nodeIds.get(r.target);
+          if (id === undefined) continue;
+          const name = r.attributeName!;
+          const target = r.target as Element;
+          const value = target.getAttribute(name);
+          this.pushEvent({ type: "dom.attr", t, node: id, name, value });
+        } else if (r.type === "characterData") {
+          const id = this.nodeIds.get(r.target);
+          if (id === undefined) continue;
+          this.pushEvent({
+            type: "dom.text",
+            t,
+            node: id,
+            text: (r.target as CharacterData).data,
+          });
+        }
+      } catch {
+        // A capture failure must never break the experiment.
+      }
+    }
+  }
+
+  private findTrackedSibling(start: Node | null): number | null {
+    let cur = start;
+    while (cur) {
+      const id = this.nodeIds.get(cur);
+      if (id !== undefined) return id;
+      cur = cur.nextSibling;
+    }
+    return null;
+  }
+
+  private releaseSubtree(node: Node) {
+    if (node instanceof HTMLCanvasElement && this.canvasTrackedElements.has(node)) {
+      // jsPsych core clears the display element via `innerHTML = ""`
+      // immediately after each trial, before `onTrialFinish` fires. Take
+      // a final snapshot here so the canvas's last pixel state is in the
+      // recording instead of being silently dropped on removal.
+      this.snapshotCanvas(node, this.t(), true);
+      this.canvasTrackedElements.delete(node);
+      this.canvasShadowData.delete(node);
+    }
+    if (this.nodeIds.has(node)) {
+      this.nodeIds.delete(node);
+    }
+    if (node.hasChildNodes()) {
+      for (const child of Array.from(node.childNodes)) {
+        this.releaseSubtree(child);
+      }
+    }
+  }
+
+  // Serializes `displayElement` plus the chain of ancestors leading up
+  // to (and including) `displayContainer`. The returned tree is a
+  // "spine": each ancestor is captured with its tag and attributes, but
+  // only the descendant on the path to `displayElement` appears as a
+  // child — sibling content (e.g. unrelated body elements when
+  // `display_element` is `<body>`) is intentionally omitted.
+  //
+  // Without this, `initial_dom` would only contain `<div class=
+  // "jspsych-content">` and the trial subtree below it. The CSS that
+  // vertically centers experiment content lives on the wrappers
+  // (`jspsych-content-wrapper`, `jspsych-display-element`); replayers
+  // need those nodes to exist for `margin: auto` and the flex column
+  // to do their work.
+  //
+  // If no `displayContainer` was provided to `start()`, we fall back to
+  // serializing only `displayElement` so existing callers don't change
+  // behavior.
+  private serializeDisplaySpine(displayElement: HTMLElement): DomNode | null {
+    let root = this.serializeNode(displayElement);
+    if (!root) return null;
+    if (!this.displayContainer || this.displayContainer === displayElement) return root;
+    let cur: Element | null = displayElement.parentElement;
+    while (cur) {
+      root = this.wrapInElement(cur, root);
+      if (cur === this.displayContainer) break;
+      cur = cur.parentElement;
+    }
+    return root;
+  }
+
+  private wrapInElement(el: Element, child: DomNode): ElementNode {
+    const attrs: Record<string, string> = {};
+    for (const a of Array.from(el.attributes)) attrs[a.name] = a.value;
+    return {
+      id: this.assignId(el),
+      kind: "element",
+      tag: el.tagName.toLowerCase(),
+      attrs,
+      children: [child],
+    };
+  }
+
+  private serializeNode(node: Node): DomNode | null {
+    if (node.nodeType === Node.ELEMENT_NODE) {
+      const el = node as Element;
+      const id = this.assignId(el);
+      const attrs: Record<string, string> = {};
+      for (const a of Array.from(el.attributes)) attrs[a.name] = a.value;
+      const out: ElementNode = {
+        id,
+        kind: "element",
+        tag: el.tagName.toLowerCase(),
+        attrs,
+        children: [],
+      };
+      if (el instanceof HTMLCanvasElement) {
+        out.canvas_size = { w: el.width, h: el.height };
+      }
+      if (el instanceof HTMLMediaElement) {
+        out.media_src = el.currentSrc || el.src || "";
+      }
+      for (const child of Array.from(el.childNodes)) {
+        const sc = this.serializeNode(child);
+        if (sc) out.children.push(sc);
+      }
+      return out;
+    }
+    if (node.nodeType === Node.TEXT_NODE) {
+      return { id: this.assignId(node), kind: "text", text: (node as Text).data };
+    }
+    if (node.nodeType === Node.COMMENT_NODE) {
+      return { id: this.assignId(node), kind: "comment", text: (node as Comment).data };
+    }
+    return null;
+  }
+
+  // -------- stylesheet snapshot --------
+
+  // Captured at session start so a replayer can apply the same CSS to the
+  // recorded DOM. Without this, `initial_dom` reconstructs structure but
+  // not appearance — class hooks like `.jspsych-display-element` have no
+  // rules to attach to.
+  //
+  // We walk the DOM directly (rather than just `document.styleSheets`) so
+  // that <link rel="stylesheet"> tags whose sheet has not yet loaded — or
+  // failed to load — are still captured by href. For each element we then
+  // try to read the resolved rule text via the associated CSSStyleSheet:
+  //   - <style> tags: read `cssRules` (always readable for same-document
+  //     inline sheets); fall back to the element's `textContent` if rule
+  //     access throws.
+  //   - <link rel="stylesheet">: read `cssRules` if the sheet is loaded
+  //     and same-origin (or CORS-permissive). Otherwise record `href`
+  //     with `css: null` so a replayer can refetch out-of-band.
+  // Each captured element is registered in `styleNodeIds` so the head
+  // observer can emit remove/update events referencing the same id.
+  private captureStylesheets(): StylesheetSnapshot[] {
+    if (typeof document === "undefined") return [];
+    const out: StylesheetSnapshot[] = [];
+
+    const elements = document.querySelectorAll<HTMLElement>('style, link[rel~="stylesheet"]');
+    for (const el of Array.from(elements)) {
+      const snap = this.snapshotStylesheetElement(el);
+      if (snap) out.push(snap);
+    }
+
+    // Also include any sheets that weren't reached via the DOM walk —
+    // notably sheets pulled in via @import, which exist in
+    // `document.styleSheets` but have no `ownerNode` element.
+    for (const sheet of Array.from(document.styleSheets)) {
+      try {
+        const owner = sheet.ownerNode as Node | null;
+        if (owner && this.styleNodeIds.has(owner)) continue;
+        const css = readSheetText(sheet);
+        const media = sheet.media && sheet.media.mediaText ? sheet.media.mediaText : null;
+        if (sheet.href) {
+          out.push({ id: this.nextStylesheetId++, kind: "link", href: sheet.href, css, media });
+        } else if (css !== null) {
+          out.push({ id: this.nextStylesheetId++, kind: "inline", css, media });
+        }
+      } catch {
+        // Capture must never break the experiment.
+      }
+    }
+
+    return out;
+  }
+
+  // Builds a snapshot for a single `<style>` or `<link rel=stylesheet>`
+  // element and registers it in `styleNodeIds`. Returns null if the
+  // element is not a stylesheet kind we track. Used both by the initial
+  // capture and by the head observer for added nodes.
+  private snapshotStylesheetElement(el: HTMLElement): StylesheetSnapshot | null {
+    try {
+      const sheet = (el as unknown as { sheet?: CSSStyleSheet | null }).sheet ?? null;
+      const media = readMedia(el, sheet);
+      if (el instanceof HTMLLinkElement) {
+        if (!/(^|\s)stylesheet(\s|$)/i.test(el.rel)) return null;
+        const href = el.href || el.getAttribute("href") || "";
+        const id = this.nextStylesheetId++;
+        this.styleNodeIds.set(el, id);
+        return { id, kind: "link", href, css: sheet ? readSheetText(sheet) : null, media };
+      }
+      if (el instanceof HTMLStyleElement) {
+        const css = (sheet ? readSheetText(sheet) : null) ?? el.textContent ?? "";
+        const id = this.nextStylesheetId++;
+        this.styleNodeIds.set(el, id);
+        return { id, kind: "inline", css, media };
+      }
+    } catch {
+      // Capture must never break the experiment.
+    }
+    return null;
+  }
+
+  // Reads the current resolved CSS text for a tracked `<style>` element,
+  // preferring `sheet.cssRules` (which reflects rule-level edits made via
+  // CSSOM) and falling back to the element's `textContent`.
+  private readStyleCss(el: HTMLStyleElement): string {
+    try {
+      const sheet = el.sheet ?? null;
+      if (sheet) {
+        const text = readSheetText(sheet);
+        if (text !== null) return text;
+      }
+    } catch {
+      // fall through to textContent
+    }
+    return el.textContent ?? "";
+  }
+
+  private handleHeadMutations(records: MutationRecord[]) {
+    const t = this.t();
+    // Coalesce per-element updates so a single `textContent =` (which
+    // produces multiple child mutations) emits one event, not many.
+    const updated = new Set<HTMLStyleElement>();
+
+    for (const r of records) {
+      try {
+        if (r.type === "childList") {
+          // Mutations under a tracked <style> mean its rule text changed
+          // (e.g. `style.textContent = ...` replaces the inner text node).
+          if (r.target instanceof HTMLStyleElement && this.styleNodeIds.has(r.target)) {
+            updated.add(r.target);
+            continue;
+          }
+          // Otherwise, the mutation is at <head> level: stylesheets are
+          // being added or removed from the document.
+          for (const removed of Array.from(r.removedNodes)) {
+            const id = this.styleNodeIds.get(removed);
+            if (id === undefined) continue;
+            this.styleNodeIds.delete(removed);
+            this.recording.stylesheet_events.push({ type: "stylesheet.remove", t, id });
+          }
+          for (const added of Array.from(r.addedNodes)) {
+            if (!(added instanceof HTMLStyleElement) && !(added instanceof HTMLLinkElement)) {
+              continue;
+            }
+            if (this.styleNodeIds.has(added)) continue;
+            const snap = this.snapshotStylesheetElement(added as HTMLElement);
+            if (snap)
+              this.recording.stylesheet_events.push({ type: "stylesheet.add", t, sheet: snap });
+          }
+        } else if (r.type === "characterData") {
+          // Direct edit to the text node inside a <style> (e.g. via
+          // `style.firstChild.data = ...`). Walk up to the <style>.
+          let target: Node | null = r.target;
+          while (target && !(target instanceof HTMLStyleElement)) {
+            target = target.parentNode;
+          }
+          if (target && this.styleNodeIds.has(target)) {
+            updated.add(target as HTMLStyleElement);
+          }
+        }
+      } catch {
+        // Capture must never break the experiment.
+      }
+    }
+
+    for (const el of updated) {
+      const id = this.styleNodeIds.get(el);
+      if (id === undefined) continue;
+      this.recording.stylesheet_events.push({
+        type: "stylesheet.update",
+        t,
+        id,
+        css: this.readStyleCss(el),
+      });
+    }
+  }
+
+  private assignId(node: Node): number {
+    let id = this.nodeIds.get(node);
+    if (id === undefined) {
+      id = this.nextNodeId++;
+      this.nodeIds.set(node, id);
+    }
+    return id;
+  }
+
+  private resetNodeIds() {
+    this.nodeIds = new WeakMap();
+    this.nextNodeId = 1;
+  }
+
+  // -------- input handlers --------
+
+  private handleMouseMove = (ev: Event) => {
+    const e = ev as MouseEvent;
+    this.lastMouseX = e.clientX;
+    this.lastMouseY = e.clientY;
+    this.mouseDirty = true;
+    if (!this.mouseRafScheduled) {
+      this.mouseRafScheduled = true;
+      requestAnimationFrame(() => {
+        this.mouseRafScheduled = false;
+        this.flushPendingMouse();
+      });
+    }
+  };
+
+  private flushPendingMouse() {
+    if (!this.mouseDirty) return;
+    this.mouseDirty = false;
+    this.pushEvent({
+      type: "mouse.move",
+      t: this.t(),
+      x: this.lastMouseX,
+      y: this.lastMouseY,
+    });
+  }
+
+  private handleScroll = (ev: Event) => {
+    const target = ev.target;
+    if (target === document || target === document.documentElement || target === document.body) {
+      this.pendingScroll.set("window", {
+        x: window.scrollX,
+        y: window.scrollY,
+      });
+    } else if (target instanceof Element) {
+      const id = this.nodeIds.get(target);
+      if (id === undefined) return;
+      this.pendingScroll.set(id, { x: target.scrollLeft, y: target.scrollTop });
+    } else {
+      return;
+    }
+    if (!this.scrollRafScheduled) {
+      this.scrollRafScheduled = true;
+      requestAnimationFrame(() => {
+        this.scrollRafScheduled = false;
+        this.flushPendingScroll();
+      });
+    }
+  };
+
+  // `input` events come from text-like form fields, textareas, and sliders.
+  // Checkboxes/radios/selects also fire `input`, but they're routed through
+  // `handleChangeEvent` instead so we don't double-record. The MutationObserver
+  // can't see these changes — typing updates the IDL `value` property, not
+  // the DOM `value` attribute.
+  private handleInputEvent = (ev: Event) => {
+    const target = ev.target;
+    if (!(target instanceof Element)) return;
+    if (target instanceof HTMLInputElement) {
+      // Skip control kinds whose state lives elsewhere (handled by `change`).
+      const t = target.type;
+      if (t === "checkbox" || t === "radio" || t === "file") return;
+    } else if (!(target instanceof HTMLTextAreaElement)) {
+      return;
+    }
+    const id = this.nodeIds.get(target);
+    if (id === undefined) return;
+    this.pendingInput.set(id, target.value);
+    if (!this.inputRafScheduled) {
+      this.inputRafScheduled = true;
+      requestAnimationFrame(() => {
+        this.inputRafScheduled = false;
+        this.flushPendingInput();
+      });
+    }
+  };
+
+  private flushPendingInput() {
+    if (this.pendingInput.size === 0) return;
+    const t = this.t();
+    for (const [node, value] of this.pendingInput) {
+      this.pushEvent({ type: "input.value", t, node, value });
+    }
+    this.pendingInput.clear();
+  }
+
+  private handleChangeEvent = (ev: Event) => {
+    const target = ev.target;
+    if (!(target instanceof Element)) return;
+    const id = this.nodeIds.get(target);
+    if (id === undefined) return;
+    if (target instanceof HTMLInputElement) {
+      const ttype = target.type;
+      if (ttype === "checkbox" || ttype === "radio") {
+        this.pushEvent({ type: "input.checked", t: this.t(), node: id, checked: target.checked });
+      }
+      // Text-like inputs are already covered by `handleInputEvent`; their
+      // additional `change` event on blur would just duplicate the last
+      // value we already recorded.
+    } else if (target instanceof HTMLSelectElement) {
+      const values = Array.from(target.selectedOptions).map((o) => o.value);
+      this.pushEvent({ type: "input.select", t: this.t(), node: id, values });
+    }
+  };
+
+  private flushPendingScroll() {
+    if (this.pendingScroll.size === 0) return;
+    const t = this.t();
+    for (const [key, pos] of this.pendingScroll) {
+      if (key === "window") {
+        this.pushEvent({ type: "scroll.window", t, x: pos.x, y: pos.y });
+      } else {
+        this.pushEvent({ type: "scroll.element", t, node: key, x: pos.x, y: pos.y });
+      }
+    }
+    this.pendingScroll.clear();
+  }
+
+  private handleMouseButton(type: "mouse.down" | "mouse.up" | "mouse.click") {
+    return (ev: Event) => {
+      const e = ev as MouseEvent;
+      this.pushEvent({
+        type,
+        t: this.t(),
+        x: e.clientX,
+        y: e.clientY,
+        button: e.button,
+        target: this.targetId(e.target),
+      });
+      // Gesture release is the moment a stroke completes; snapshot any
+      // tracked canvases so the drawing it produced reaches the replay.
+      if (type === "mouse.up") this.scheduleCanvasSnapshot();
+    };
+  }
+
+  private handleTouch(type: "touch.start" | "touch.move" | "touch.end") {
+    return (ev: Event) => {
+      const e = ev as TouchEvent;
+      const touches = Array.from(e.changedTouches).map((tt) => ({
+        id: tt.identifier,
+        x: tt.clientX,
+        y: tt.clientY,
+      }));
+      this.pushEvent({ type, t: this.t(), touches });
+      if (type === "touch.end") this.scheduleCanvasSnapshot();
+    };
+  }
+
+  private handleKey(type: "key.down" | "key.up") {
+    return (ev: Event) => {
+      const e = ev as KeyboardEvent;
+      this.pushEvent({
+        type,
+        t: this.t(),
+        key: e.key,
+        code: e.code,
+        mods: { ctrl: e.ctrlKey, shift: e.shiftKey, alt: e.altKey, meta: e.metaKey },
+        repeat: e.repeat,
+        target: this.targetId(e.target),
+      });
+    };
+  }
+
+  private handleClipboard(type: ClipboardRecord["type"]) {
+    return (ev: Event) => {
+      const e = ev as ClipboardEvent;
+      let text: string | null = null;
+      let html: string | null = null;
+      try {
+        text = e.clipboardData?.getData("text/plain") ?? null;
+        html = e.clipboardData?.getData("text/html") ?? null;
+        if (html === "") html = null;
+      } catch {
+        // clipboard data may be inaccessible in some contexts
+      }
+      this.pushEvent({ type, t: this.t(), text, html, target: this.targetId(e.target) });
+    };
+  }
+
+  private targetId(target: EventTarget | null): number | null {
+    if (!target || !(target instanceof Node)) return null;
+    return this.nodeIds.get(target) ?? null;
+  }
+
+  // -------- media handling --------
+
+  private scanForMediaElements(root: Element) {
+    if (root instanceof HTMLMediaElement) this.attachMediaListeners(root);
+    const els = root.querySelectorAll("video, audio");
+    for (const el of Array.from(els)) {
+      this.attachMediaListeners(el as HTMLMediaElement);
+    }
+  }
+
+  private attachMediaListeners(media: HTMLMediaElement) {
+    if (this.mediaListeners.has(media)) return;
+    const id = this.assignId(media);
+    const handler = (ev: Event) => {
+      let type: MediaRecord["type"];
+      switch (ev.type) {
+        case "play":
+          type = "media.play";
+          break;
+        case "pause":
+          type = "media.pause";
+          break;
+        case "ended":
+          type = "media.ended";
+          break;
+        case "seeked":
+          type = "media.seeked";
+          break;
+        case "timeupdate": {
+          const now = performance.now();
+          const last = this.mediaTimeLast.get(media) ?? 0;
+          if (now - last < MEDIA_TIME_THROTTLE_MS) return;
+          this.mediaTimeLast.set(media, now);
+          type = "media.time";
+          break;
+        }
+        default:
+          return;
+      }
+      this.pushEvent({ type, t: this.t(), node: id, current_time: media.currentTime });
+    };
+    media.addEventListener("play", handler);
+    media.addEventListener("pause", handler);
+    media.addEventListener("ended", handler);
+    media.addEventListener("seeked", handler);
+    media.addEventListener("timeupdate", handler);
+    this.mediaTrackedElements.add(media);
+    this.mediaListeners.set(media, handler);
+  }
+
+  private detachMediaListeners() {
+    for (const media of this.mediaTrackedElements) {
+      const handler = this.mediaListeners.get(media);
+      if (!handler) continue;
+      media.removeEventListener("play", handler);
+      media.removeEventListener("pause", handler);
+      media.removeEventListener("ended", handler);
+      media.removeEventListener("seeked", handler);
+      media.removeEventListener("timeupdate", handler);
+      this.mediaListeners.delete(media);
+    }
+    this.mediaTrackedElements.clear();
+  }
+
+  // -------- canvas snapshotting --------
+
+  // Walks `root` for `<canvas>` elements and registers each one for
+  // snapshotting. Called on trial load and when subtrees are added
+  // mid-trial via `dom.add`.
+  private scanForCanvasElements(root: Element) {
+    if (root instanceof HTMLCanvasElement) {
+      this.trackCanvasElement(root);
+      return;
+    }
+    const els = root.querySelectorAll("canvas");
+    for (const el of Array.from(els)) {
+      this.trackCanvasElement(el as HTMLCanvasElement);
+    }
+  }
+
+  private trackCanvasElement(canvas: HTMLCanvasElement) {
+    this.canvasTrackedElements.add(canvas);
+    // Schedule an initial baseline snapshot. For canvases discovered at
+    // `onTrialLoad` this catches the post-render state of plugins that
+    // draw their stimulus synchronously. For canvases added mid-trial
+    // via the MutationObserver path this gives the same coverage. The
+    // diff path skips re-snapshotting canvases that are already
+    // baselined, so calling this for every added canvas is cheap.
+    this.scheduleInitialCanvasSnapshot();
+  }
+
+  // Wraps the pixel-mutating methods on `CanvasRenderingContext2D`
+  // so the recorder is notified whenever a tracked canvas is drawn to.
+  // The wrapper sets a per-canvas dirty flag and schedules a frame
+  // tick; the original method is then called with the original `this`
+  // and arguments so the wrap is invisible to plugin code. Idempotent
+  // and per-instance: the originals captured here are restored on
+  // `stop()`, even across nested recorder lifetimes.
+  private patchCanvasContext() {
+    if (this.canvasContextPatched) return;
+    if (typeof CanvasRenderingContext2D === "undefined") return;
+    const proto = CanvasRenderingContext2D.prototype as unknown as Record<string, Function>;
+    const recorder = this;
+    for (const method of CANVAS_DRAW_METHODS) {
+      const original = proto[method];
+      if (typeof original !== "function") continue;
+      this.originalCanvasMethods.set(method, original);
+      proto[method] = function (this: CanvasRenderingContext2D, ...args: unknown[]) {
+        try {
+          const canvas = this.canvas as HTMLCanvasElement | undefined;
+          if (canvas && recorder.canvasTrackedElements.has(canvas)) {
+            recorder.canvasDirty.set(canvas, true);
+            recorder.scheduleCanvasFrameTick();
+          }
+        } catch {
+          // Tracking must never break the experiment's own drawing.
+        }
+        return (original as Function).apply(this, args);
+      };
+    }
+    this.canvasContextPatched = true;
+  }
+
+  private unpatchCanvasContext() {
+    if (!this.canvasContextPatched) return;
+    if (typeof CanvasRenderingContext2D === "undefined") return;
+    const proto = CanvasRenderingContext2D.prototype as unknown as Record<string, Function>;
+    for (const [method, original] of this.originalCanvasMethods) {
+      proto[method] = original;
+    }
+    this.originalCanvasMethods.clear();
+    this.canvasContextPatched = false;
+  }
+
+  // Coalesces draw notifications into a single per-frame tick. Multiple
+  // draw calls between two animation frames (e.g. a stroke composed of
+  // many `lineTo`+`stroke` pairs) collapse to one snapshot attempt. The
+  // tick does not re-schedule itself; further draws will reschedule it,
+  // and quiescent canvases produce no work.
+  private scheduleCanvasFrameTick() {
+    if (this.canvasFrameLoopScheduled) return;
+    if (!this.running) return;
+    this.canvasFrameLoopScheduled = true;
+    requestAnimationFrame(this.runCanvasFrameTick);
+  }
+
+  private runCanvasFrameTick = () => {
+    this.canvasFrameLoopScheduled = false;
+    if (!this.running) return;
+    const t = this.t();
+    for (const canvas of this.canvasTrackedElements) {
+      if (!this.canvasDirty.get(canvas)) continue;
+      const last = this.canvasAnimationLastTime.get(canvas) ?? -Infinity;
+      // Skip without clearing the dirty flag: the next draw call will
+      // re-schedule a tick, by which time the throttle window has
+      // likely elapsed. If draws stop while throttled, the trial-end
+      // `releaseSubtree` snapshot will catch the final pixels.
+      if (t - last < CANVAS_ANIMATION_MIN_INTERVAL_MS) continue;
+      this.canvasAnimationLastTime.set(canvas, t);
+      this.canvasDirty.set(canvas, false);
+      // `force = true` bypasses the gesture-path 250 ms throttle. The
+      // animation throttle above already bounds frequency from this
+      // path; the diff inside `snapshotCanvas` then dedupes byte-
+      // identical states.
+      this.snapshotCanvas(canvas, t, true);
+    }
+  };
+
+  // Defers an unconditional snapshot to the next animation frame so we
+  // wait for any synchronous drawing during plugin setup (or during
+  // user `on_load`) to commit. Distinct from `scheduleCanvasSnapshot`,
+  // which respects the per-canvas throttle: initial baselines must not
+  // be throttled out by an immediately preceding gesture.
+  private scheduleInitialCanvasSnapshot() {
+    if (this.canvasInitialSnapshotScheduled) return;
+    if (this.canvasTrackedElements.size === 0) return;
+    this.canvasInitialSnapshotScheduled = true;
+    requestAnimationFrame(() => {
+      this.canvasInitialSnapshotScheduled = false;
+      this.captureCanvasSnapshots(true);
+    });
+  }
+
+  // Defers actual snapshotting to the next animation frame so we wait
+  // until the page has had a chance to paint the post-gesture state
+  // (otherwise `toDataURL` could return the canvas as it was *before*
+  // the up event's listeners ran). Coalesced via a single scheduled flag
+  // so a flurry of mouseups doesn't queue redundant work.
+  private scheduleCanvasSnapshot() {
+    if (this.canvasSnapshotScheduled) return;
+    if (this.canvasTrackedElements.size === 0) return;
+    this.canvasSnapshotScheduled = true;
+    requestAnimationFrame(() => {
+      this.canvasSnapshotScheduled = false;
+      this.captureCanvasSnapshots(false);
+    });
+  }
+
+  // Throttles to at most one snapshot per canvas per
+  // `CANVAS_SNAPSHOT_MIN_INTERVAL_MS`, and dedupes by data URL so a
+  // canvas whose pixels did not actually change does not produce noise.
+  // `force` bypasses the throttle for trial-end captures so the final
+  // state of every canvas is always recorded.
+  private captureCanvasSnapshots(force: boolean) {
+    if (this.canvasTrackedElements.size === 0) return;
+    const now = this.t();
+    for (const canvas of this.canvasTrackedElements) {
+      this.snapshotCanvas(canvas, now, force);
+    }
+  }
+
+  // Pushes a `canvas.snapshot` event for one canvas, applying the
+  // per-canvas throttle (unless `force`). Diffs the canvas's current
+  // pixels against the last shadow buffer to find the changed bounding
+  // box; emits a partial snapshot when the dirty area is small and a
+  // full snapshot otherwise. The first snapshot per canvas is always
+  // full so subsequent partials have a baseline.
+  //
+  // Also called from `releaseSubtree` to capture the final pixel state
+  // at the moment a canvas is removed from the trial DOM — jsPsych core
+  // clears the display element via `innerHTML = ""` before
+  // `onTrialFinish` runs, so a trial-end-only flush would miss it.
+  private snapshotCanvas(canvas: HTMLCanvasElement, t: number, force: boolean) {
+    const id = this.nodeIds.get(canvas);
+    if (id === undefined) return;
+    if (!force) {
+      const last = this.canvasLastSnapshotTime.get(canvas) ?? -Infinity;
+      if (t - last < CANVAS_SNAPSHOT_MIN_INTERVAL_MS) return;
+    }
+    const w = canvas.width;
+    const h = canvas.height;
+    if (w === 0 || h === 0) return;
+    try {
+      const ctx = getReadable2dContext(canvas);
+      const shadow = this.canvasShadowData.get(canvas);
+      const shadowValid = !!shadow && shadow.width === w && shadow.height === h;
+
+      // Without a readable 2d context (WebGL canvases, or 2d contexts
+      // created with `willReadFrequently: false` that subsequently fail)
+      // we can't diff. Emit a full snapshot via toDataURL and skip
+      // shadow tracking for this canvas.
+      if (!ctx) {
+        this.emitFullCanvasSnapshot(canvas, id, t);
+        return;
+      }
+
+      // First snapshot for this canvas — no baseline to diff against.
+      // Capture the current pixels into the shadow buffer and emit a
+      // full snapshot so the replayer has a starting point.
+      if (!shadowValid) {
+        const current = ctx.getImageData(0, 0, w, h);
+        this.canvasShadowData.set(canvas, current);
+        this.emitFullCanvasSnapshot(canvas, id, t);
+        return;
+      }
+
+      const current = ctx.getImageData(0, 0, w, h);
+      const bbox = computeDiffBbox(shadow!.data, current.data, w, h);
+      // Pixels are byte-identical to the last snapshot — emit nothing.
+      if (!bbox) return;
+
+      const fullThreshold = w * h * CANVAS_FULL_SNAPSHOT_AREA_FRACTION;
+      if (bbox.w * bbox.h >= fullThreshold) {
+        this.canvasShadowData.set(canvas, current);
+        this.emitFullCanvasSnapshot(canvas, id, t);
+        return;
+      }
+
+      const dataUrl = cropCanvasToDataURL(canvas, bbox);
+      this.canvasShadowData.set(canvas, current);
+      this.canvasLastSnapshotTime.set(canvas, t);
+      this.pushEvent({
+        type: "canvas.snapshot",
+        t,
+        node: id,
+        data_url: dataUrl,
+        region: bbox,
+      });
+    } catch {
+      // toDataURL/getImageData throw SecurityError on tainted canvases
+      // (canvases that drew cross-origin images without CORS headers).
+      // Skip and never break the experiment.
+    }
+  }
+
+  // Emits a full-canvas snapshot, applying the same data-URL dedupe the
+  // pre-diff implementation used. Useful for first captures, near-full
+  // dirty regions, and canvases without a readable 2d context.
+  private emitFullCanvasSnapshot(canvas: HTMLCanvasElement, id: number, t: number) {
+    const dataUrl = canvas.toDataURL();
+    if (this.canvasLastSnapshot.get(canvas) === dataUrl) return;
+    this.canvasLastSnapshot.set(canvas, dataUrl);
+    this.canvasLastSnapshotTime.set(canvas, t);
+    this.pushEvent({ type: "canvas.snapshot", t, node: id, data_url: dataUrl });
+  }
+
+  // -------- RNG --------
+
+  private isNativeMathRandom(fn: typeof Math.random) {
+    // Native built-ins stringify with the [native code] sentinel; any
+    // user-installed PRNG (e.g. via jsPsych.randomization.setSeed) will
+    // serialize as JS source instead.
+    return /\{\s*\[native code\]\s*\}/.test(Function.prototype.toString.call(fn));
+  }
+
+  private patchMathRandom() {
+    if (this.mathRandomPatched) return;
+    // Capture the *true* pre-recording Math.random before any potential
+    // auto-seeding so `stop()` can restore exactly what was there.
+    this.originalMathRandom = Math.random;
+
+    // Only auto-seed when Math.random is the native function; if the user
+    // already installed a seeded PRNG, leave it alone.
+    if (this.recording.rng.seed === null && this.isNativeMathRandom(this.originalMathRandom)) {
+      this.recording.rng.seed = randomization.setSeed();
+    }
+
+    const upstream = Math.random.bind(Math);
+    Math.random = () => {
+      const v = upstream();
+      // Captured at session scope: includes calls during pre-trial
+      // parameter evaluation, post-trial gaps, and the experimenter's
+      // `on_finish` — none of which are bracketed by a current trial.
+      this.recording.rng_calls.push({ t: this.t(), fn: "Math.random", args: [], result: v });
+      return v;
+    };
+    this.mathRandomPatched = true;
+    this.recording.rng.math_random_patched = true;
+  }
+
+  private unpatchMathRandom() {
+    if (!this.mathRandomPatched) return;
+    Math.random = this.originalMathRandom;
+    this.mathRandomPatched = false;
+  }
+
+  // -------- helpers --------
+
+  private bind(
+    target: EventTarget,
+    type: string,
+    handler: EventListenerOrEventListenerObject,
+    options?: AddEventListenerOptions | boolean
+  ) {
+    target.addEventListener(type, handler, options);
+    // Trial-scoped binds happen while `mutationObserver` is set (i.e. inside
+    // `attachTrialListeners`); session-scoped binds happen when it is not.
+    const trial = this.mutationObserver !== null;
+    this.boundHandlers.push({ target, type, handler, options, trial });
+  }
+
+  private pushEvent(ev: RecordedEvent) {
+    if (this.currentTrial) this.currentTrial.events.push(ev);
+  }
+
+  private t(): number {
+    return performance.now() - this.startPerf;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+// Reads the `media` attribute, preferring the parsed value on the
+// CSSStyleSheet (which normalizes whitespace/casing) and falling back to
+// the raw attribute on the owning element.
+function readMedia(el: HTMLElement, sheet: CSSStyleSheet | null): string | null {
+  const fromSheet = sheet?.media?.mediaText;
+  if (fromSheet) return fromSheet;
+  const attr = el.getAttribute("media");
+  return attr && attr.length > 0 ? attr : null;
+}
+
+// Reads the resolved CSS rule text from a stylesheet. Returns null when
+// `cssRules` is unreadable (cross-origin sheets without CORS access throw
+// SecurityError) so callers can record only the href in that case.
+function readSheetText(sheet: CSSStyleSheet): string | null {
+  try {
+    const rules = sheet.cssRules;
+    if (!rules) return null;
+    const parts: string[] = [];
+    for (let i = 0; i < rules.length; i++) {
+      parts.push(rules[i].cssText);
+    }
+    return parts.join("\n");
+  } catch {
+    return null;
+  }
+}
+
+// Returns the canvas's 2d rendering context if one exists and is
+// readable (i.e. `getImageData` is callable). WebGL canvases return
+// null here so the caller falls back to full-canvas `toDataURL`
+// snapshots.
+function getReadable2dContext(canvas: HTMLCanvasElement): CanvasRenderingContext2D | null {
+  try {
+    const ctx = canvas.getContext("2d");
+    return ctx ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// Finds the bounding box of pixels that differ between two same-size
+// ImageData buffers. Uses an edge-shrink walk: scan top-down for the
+// first dirty row, bottom-up for the last, then within that row band
+// scan inward from each side for the first dirty column. For typical
+// incremental drawing (a stroke, a localized clear) this terminates
+// after only a few thousand pixel comparisons even on a multi-megapixel
+// canvas. Returns null when the buffers are byte-identical.
+//
+// Exported for unit testing; a replayer doesn't need it.
+export function computeDiffBbox(
+  prev: Uint8ClampedArray,
+  curr: Uint8ClampedArray,
+  w: number,
+  h: number
+): { x: number; y: number; w: number; h: number } | null {
+  let top = -1;
+  for (let y = 0; y < h; y++) {
+    const rowStart = y * w * 4;
+    const rowEnd = rowStart + w * 4;
+    for (let i = rowStart; i < rowEnd; i++) {
+      if (prev[i] !== curr[i]) {
+        top = y;
+        break;
+      }
+    }
+    if (top !== -1) break;
+  }
+  if (top === -1) return null;
+
+  let bottom = top;
+  for (let y = h - 1; y > top; y--) {
+    const rowStart = y * w * 4;
+    const rowEnd = rowStart + w * 4;
+    let dirty = false;
+    for (let i = rowStart; i < rowEnd; i++) {
+      if (prev[i] !== curr[i]) {
+        dirty = true;
+        break;
+      }
+    }
+    if (dirty) {
+      bottom = y;
+      break;
+    }
+  }
+
+  let left = w - 1;
+  let right = 0;
+  for (let y = top; y <= bottom; y++) {
+    const rowStart = y * w * 4;
+    // Scan inward from the left up to the current `left` candidate.
+    for (let x = 0; x < left; x++) {
+      const i = rowStart + x * 4;
+      if (
+        prev[i] !== curr[i] ||
+        prev[i + 1] !== curr[i + 1] ||
+        prev[i + 2] !== curr[i + 2] ||
+        prev[i + 3] !== curr[i + 3]
+      ) {
+        left = x;
+        break;
+      }
+    }
+    // Scan inward from the right past the current `right` candidate.
+    for (let x = w - 1; x > right; x--) {
+      const i = rowStart + x * 4;
+      if (
+        prev[i] !== curr[i] ||
+        prev[i + 1] !== curr[i + 1] ||
+        prev[i + 2] !== curr[i + 2] ||
+        prev[i + 3] !== curr[i + 3]
+      ) {
+        right = x;
+        break;
+      }
+    }
+    if (left === 0 && right === w - 1) break;
+  }
+
+  return { x: left, y: top, w: right - left + 1, h: bottom - top + 1 };
+}
+
+// Copies a rectangular region out of a source canvas into a temporary
+// canvas and returns its data URL. The temporary canvas is sized to
+// the region so the resulting PNG carries only the dirty pixels.
+function cropCanvasToDataURL(
+  source: HTMLCanvasElement,
+  region: { x: number; y: number; w: number; h: number }
+): string {
+  const tmp = document.createElement("canvas");
+  tmp.width = region.w;
+  tmp.height = region.h;
+  const tctx = tmp.getContext("2d");
+  if (!tctx) return source.toDataURL();
+  tctx.drawImage(source, region.x, region.y, region.w, region.h, 0, 0, region.w, region.h);
+  return tmp.toDataURL();
+}
+
+function readViewport(): ViewportState {
+  const vv = window.visualViewport;
+  return {
+    w: window.innerWidth,
+    h: window.innerHeight,
+    dpr: window.devicePixelRatio || 1,
+    scale: vv?.scale ?? 1,
+    offset_x: vv?.offsetLeft ?? 0,
+    offset_y: vv?.offsetTop ?? 0,
+  };
+}
+
+/**
+ * JSON-safe serialization for `trial_data` (the per-trial data row). Drops
+ * functions and DOM nodes — the recording's visual fidelity comes from DOM
+ * mutations, not from re-executing trial parameters.
+ */
+export function serializeJson(value: unknown, seen = new WeakSet<object>()): JsonValue {
+  if (value === null || value === undefined) return null;
+  const t = typeof value;
+  if (t === "boolean" || t === "string") return value as JsonValue;
+  if (t === "number") return Number.isFinite(value as number) ? (value as number) : null;
+  if (t === "function") return null;
+  if (t !== "object") return null;
+  if (seen.has(value as object)) return null;
+  seen.add(value as object);
+  if (Array.isArray(value)) return value.map((v) => serializeJson(v, seen));
+  if (value instanceof Date) return value.toISOString();
+  if (value instanceof Element || value instanceof Node) return null;
+  const out: Record<string, JsonValue> = {};
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    out[k] = serializeJson(v, seen);
+  }
+  return out;
+}
diff --git a/packages/jspsych/src/timeline/Trial.ts b/packages/jspsych/src/timeline/Trial.ts
index 508d8f054f..25c327712e 100644
--- a/packages/jspsych/src/timeline/Trial.ts
+++ b/packages/jspsych/src/timeline/Trial.ts
@@ -256,6 +256,7 @@ export class Trial extends TimelineNode {
   }
 
   private onLoad = () => {
+    this.dependencies.onTrialLoad(this);
     this.runParameterCallback("on_load");
     this.dependencies.runOnLoadExtensionCallbacks(this.getParameterValue("extensions"));
   };
diff --git a/packages/jspsych/src/timeline/index.ts b/packages/jspsych/src/timeline/index.ts
index f929e00ccd..2f9589f425 100644
--- a/packages/jspsych/src/timeline/index.ts
+++ b/packages/jspsych/src/timeline/index.ts
@@ -160,6 +160,12 @@ export interface TimelineNodeDependencies {
    */
   onTrialStart: (trial: Trial) => void;
 
+  /**
+   * Called after a trial's plugin has rendered its initial DOM (immediately
+   * before per-trial `on_load` and extension `on_load` callbacks fire).
+   */
+  onTrialLoad: (trial: Trial) => void;
+
   /**
    * Called when a trial's result data is available, before invoking `onTrialFinished()`.
    */
diff --git a/packages/jspsych/tests/core/record-session.test.ts b/packages/jspsych/tests/core/record-session.test.ts
new file mode 100644
index 0000000000..b3f274110e
--- /dev/null
+++ b/packages/jspsych/tests/core/record-session.test.ts
@@ -0,0 +1,1321 @@
+import htmlKeyboardResponse from "@jspsych/plugin-html-keyboard-response";
+import { pressKey, startTimeline } from "@jspsych/test-utils";
+
+import { initJsPsych } from "../../src";
+import { computeDiffBbox } from "../../src/modules/recording";
+
+function findById(node: any, id: string): any {
+  if (node?.attrs?.id === id) return node;
+  for (const c of node?.children ?? []) {
+    const found = findById(c, id);
+    if (found) return found;
+  }
+  return null;
+}
+
+describe("record_session option", () => {
+  beforeEach(() => {
+    document.body.innerHTML = "";
+    // initJsPsych adds the `jspsych-display-element` class to whatever
+    // element it's given, defaulting to <body>. classList changes are
+    // not undone by clearing innerHTML, so without this reset the body
+    // accumulates layout classes from previous tests and the spine in
+    // `initial_dom` extends past where it should.
+    document.body.className = "";
+    document.body.removeAttribute("style");
+    document.body.removeAttribute("tabindex");
+  });
+
+  test("returns undefined when not enabled", async () => {
+    const jsPsych = initJsPsych();
+    await startTimeline([{ type: htmlKeyboardResponse, stimulus: "hi" }], jsPsych);
+    await pressKey("a");
+    expect(jsPsych.getSessionRecording()).toBeUndefined();
+  });
+
+  test("produces a recording when enabled", async () => {
+    const jsPsych = initJsPsych({ record_session: true });
+    await startTimeline([{ type: htmlKeyboardResponse, stimulus: "<p>Press A</p>" }], jsPsych);
+    await pressKey("a");
+
+    const rec = jsPsych.getSessionRecording();
+    expect(rec).toBeDefined();
+    expect(rec!.schema_version).toBe(1);
+    expect(rec!.trials).toHaveLength(1);
+
+    const trial = rec!.trials[0];
+    expect(trial.plugin).toBe("html-keyboard-response");
+    expect(trial.t_start).toBeGreaterThanOrEqual(0);
+    expect(trial.t_dom_ready).not.toBeNull();
+    expect(trial.t_end).not.toBeNull();
+    expect(trial.initial_dom).not.toBeNull();
+  });
+
+  test("getSessionRecordingCompressed returns undefined when recording is not enabled", async () => {
+    const jsPsych = initJsPsych();
+    await startTimeline([{ type: htmlKeyboardResponse, stimulus: "x" }], jsPsych);
+    await pressKey("a");
+    expect(await jsPsych.getSessionRecordingCompressed()).toBeUndefined();
+  });
+
+  test("getSessionRecordingCompressed produces a gzip Blob that round-trips to the original recording", async () => {
+    const jsPsych = initJsPsych({ record_session: true });
+    await startTimeline([{ type: htmlKeyboardResponse, stimulus: "<p>x</p>" }], jsPsych);
+    await pressKey("a");
+
+    const original = jsPsych.getSessionRecording()!;
+    const blob = await jsPsych.getSessionRecordingCompressed();
+    expect(blob).toBeInstanceOf(Blob);
+    expect(blob!.type).toBe("application/gzip");
+    // Sanity check: compressed payload is meaningfully smaller than the
+    // raw JSON for any non-trivial recording.
+    const rawSize = JSON.stringify(original).length;
+    expect(blob!.size).toBeLessThan(rawSize);
+
+    // Decompress with the symmetric DecompressionStream and verify the
+    // bytes parse back to the same recording object. Driving the
+    // decompressor manually (not via `Response`) keeps this test
+    // portable across environments where `Response` is unavailable.
+    const ds = new DecompressionStream("gzip");
+    const writer = ds.writable.getWriter();
+    writer.write(new Uint8Array(await blob!.arrayBuffer()));
+    writer.close();
+    const reader = ds.readable.getReader();
+    const decompressedChunks: Uint8Array[] = [];
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      decompressedChunks.push(value);
+    }
+    const decoded = new TextDecoder().decode(
+      decompressedChunks.reduce((acc, chunk) => {
+        const out = new Uint8Array(acc.length + chunk.length);
+        out.set(acc);
+        out.set(chunk, acc.length);
+        return out;
+      }, new Uint8Array(0))
+    );
+    expect(JSON.parse(decoded)).toEqual(original);
+  });
+
+  describe("display spine in initial_dom", () => {
+    test("initial_dom is rooted at the outermost jspsych-* ancestor, not at the content div", async () => {
+      // Without the spine, replayers only get <div class="jspsych-content">
+      // and the centering CSS (which targets the wrapper and outer container)
+      // can't take effect.
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline([{ type: htmlKeyboardResponse, stimulus: "<p>x</p>" }], jsPsych);
+      await pressKey("a");
+
+      const root = jsPsych.getSessionRecording()!.trials[0].initial_dom!;
+      expect(root.kind).toBe("element");
+      // jsPsych adds the jspsych-display-element class to the user's
+      // display container (here, the body since none was provided).
+      const rootClasses = ((root as any).attrs.class ?? "").split(/\s+/);
+      expect(rootClasses).toContain("jspsych-display-element");
+    });
+
+    test("the spine includes the jspsych-content-wrapper between container and content", async () => {
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline([{ type: htmlKeyboardResponse, stimulus: "<p>x</p>" }], jsPsych);
+      await pressKey("a");
+
+      const root = jsPsych.getSessionRecording()!.trials[0].initial_dom! as any;
+      // root → content-wrapper → jspsych-content
+      expect(root.children).toHaveLength(1);
+      const wrapper = root.children[0];
+      expect((wrapper.attrs.class ?? "").split(/\s+/)).toContain("jspsych-content-wrapper");
+      expect(wrapper.children).toHaveLength(1);
+      const content = wrapper.children[0];
+      expect((content.attrs.class ?? "").split(/\s+/)).toContain("jspsych-content");
+      expect(content.attrs.id).toBe("jspsych-content");
+    });
+
+    test("trial content from the plugin lives inside the jspsych-content node, not the spine wrappers", async () => {
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline(
+        [{ type: htmlKeyboardResponse, stimulus: '<p id="trial-p">hello</p>' }],
+        jsPsych
+      );
+      await pressKey("a");
+
+      const root = jsPsych.getSessionRecording()!.trials[0].initial_dom! as any;
+      // Walk down the spine to the jspsych-content node, then search its
+      // subtree for the trial paragraph. Plugins typically wrap their
+      // stimulus in a plugin-specific div, so the <p> is a descendant
+      // of jspsych-content rather than a direct child.
+      const wrapper = root.children[0];
+      const content = wrapper.children[0];
+      expect((content.attrs.class ?? "").split(/\s+/)).toContain("jspsych-content");
+      const trialP = findById(content, "trial-p");
+      expect(trialP).toBeDefined();
+      // Sibling content under outer wrappers must not appear in initial_dom
+      // even when display_element defaults to <body>; the spine excludes
+      // body siblings by design.
+      const containerSiblings = root.children.filter((c: any) => c !== wrapper);
+      expect(containerSiblings).toHaveLength(0);
+    });
+
+    test("the spine stops at the displayContainer (not the body when display_element is custom)", async () => {
+      // When the user provides a custom display_element, the recorder
+      // should walk up through the jsPsych-managed wrappers but stop at
+      // their host. Capturing further would risk including unrelated
+      // page chrome (siblings of the host inside <body>).
+      const host = document.createElement("div");
+      host.id = "experiment-host";
+      document.body.appendChild(host);
+
+      const jsPsych = initJsPsych({ record_session: true, display_element: host });
+      // `pressKey` dispatches on `document.body`, but with a custom
+      // display_element the keyboard listener is rooted at `host` (which
+      // sits inside body, not above it), so the keypress never reaches
+      // the listener. Use `trial_duration` to auto-advance instead so the
+      // run resolves and the recorder's stop() fires before the next test.
+      const tl = await startTimeline(
+        [{ type: htmlKeyboardResponse, stimulus: "<p>x</p>", trial_duration: 1 }],
+        jsPsych
+      );
+      await tl.finished;
+
+      const root = jsPsych.getSessionRecording()!.trials[0].initial_dom! as any;
+      // The spine's outermost element is the user's host (which jsPsych
+      // tagged with jspsych-display-element); the parent <body> is excluded
+      // because it isn't the displayContainer.
+      expect(root.attrs.id).toBe("experiment-host");
+    });
+  });
+
+  test("captures Math.random calls in the session-level rng_calls log", async () => {
+    const jsPsych = initJsPsych({ record_session: true });
+    await startTimeline(
+      [
+        {
+          type: htmlKeyboardResponse,
+          stimulus: "<p>x</p>",
+          on_load: () => {
+            Math.random();
+            Math.random();
+          },
+        },
+      ],
+      jsPsych
+    );
+    await pressKey("a");
+
+    const rec = jsPsych.getSessionRecording()!;
+    expect(rec.rng.math_random_patched).toBe(true);
+    expect(rec.rng_calls.length).toBeGreaterThanOrEqual(2);
+    for (const call of rec.rng_calls) {
+      expect(call.fn).toBe("Math.random");
+      expect(typeof call.result).toBe("number");
+      expect(typeof call.t).toBe("number");
+    }
+  });
+
+  test("captures Math.random calls made during pre-trial parameter evaluation", async () => {
+    // Parameter functions (e.g. a function-valued `stimulus`) are evaluated
+    // before `onTrialStart` fires, so any RNG calls there happen with no
+    // active trial. The session-level rng_calls log captures them anyway.
+    const jsPsych = initJsPsych({ record_session: true });
+    await startTimeline(
+      [
+        {
+          type: htmlKeyboardResponse,
+          stimulus: () => {
+            Math.random();
+            Math.random();
+            Math.random();
+            return "<p>x</p>";
+          },
+        },
+      ],
+      jsPsych
+    );
+    await pressKey("a");
+
+    const rec = jsPsych.getSessionRecording()!;
+    expect(rec.rng_calls.length).toBeGreaterThanOrEqual(3);
+
+    // Calls during parameter evaluation precede the trial's t_start, so we
+    // expect at least one call with t < trials[0].t_start.
+    const trialStart = rec.trials[0].t_start;
+    const preTrialCalls = rec.rng_calls.filter((c) => c.t < trialStart);
+    expect(preTrialCalls.length).toBeGreaterThanOrEqual(3);
+  });
+
+  test("restores Math.random to the original after the experiment finishes", async () => {
+    // Capture the true original BEFORE the recorder has any chance to seed
+    // or wrap it. After stop(), Math.random must be exactly this reference.
+    const original = Math.random;
+    let patchedRandom: () => number;
+
+    const jsPsych = initJsPsych({ record_session: true });
+    await startTimeline(
+      [
+        {
+          type: htmlKeyboardResponse,
+          stimulus: "x",
+          on_load: () => {
+            patchedRandom = Math.random;
+          },
+        },
+      ],
+      jsPsych
+    );
+    await pressKey("a");
+
+    expect(patchedRandom!).toBeDefined();
+    // The patched wrapper observed during the trial is a distinct function.
+    expect(patchedRandom!).not.toBe(original);
+    // After the experiment completes, the original is fully restored.
+    expect(Math.random).toBe(original);
+  });
+
+  test("captures the keypress event during the trial", async () => {
+    const jsPsych = initJsPsych({ record_session: true });
+    await startTimeline([{ type: htmlKeyboardResponse, stimulus: "x" }], jsPsych);
+    await pressKey("a");
+
+    const rec = jsPsych.getSessionRecording()!;
+    const keyEvents = rec.trials[0].events.filter(
+      (e) => e.type === "key.down" || e.type === "key.up"
+    );
+    expect(keyEvents.length).toBeGreaterThan(0);
+  });
+
+  test("records seed and viewport metadata", async () => {
+    const jsPsych = initJsPsych({ record_session: true });
+    await startTimeline([{ type: htmlKeyboardResponse, stimulus: "x" }], jsPsych);
+    await pressKey("a");
+
+    const rec = jsPsych.getSessionRecording()!;
+    expect(rec.rng.seed).not.toBeNull();
+    expect(rec.viewport).toEqual(
+      expect.objectContaining({
+        w: expect.any(Number),
+        h: expect.any(Number),
+        dpr: expect.any(Number),
+      })
+    );
+    expect(rec.user_agent).toEqual(expect.any(String));
+    expect(rec.recording_started_at).toEqual(expect.any(String));
+    expect(rec.end_reason).toBe("finished");
+  });
+
+  describe("stylesheet capture", () => {
+    afterEach(() => {
+      // Each test installs sheets directly on document.head; clean up so
+      // they don't leak across cases or pollute later tests in the file.
+      for (const el of Array.from(document.head.querySelectorAll("style,link"))) {
+        el.remove();
+      }
+    });
+
+    test("captures inline <style> rule text at session start", async () => {
+      const style = document.createElement("style");
+      style.textContent = ".jspsych-display-element { color: rebeccapurple; }";
+      document.head.appendChild(style);
+
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline([{ type: htmlKeyboardResponse, stimulus: "x" }], jsPsych);
+      await pressKey("a");
+
+      const rec = jsPsych.getSessionRecording()!;
+      const inline = rec.stylesheets.filter((s) => s.kind === "inline");
+      expect(inline.length).toBeGreaterThan(0);
+      expect(inline.some((s) => s.css.includes("rebeccapurple"))).toBe(true);
+    });
+
+    test("captures <link rel=stylesheet> href even when CSS is unreadable", async () => {
+      const link = document.createElement("link");
+      link.rel = "stylesheet";
+      link.href = "https://example.test/jspsych.css";
+      document.head.appendChild(link);
+
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline([{ type: htmlKeyboardResponse, stimulus: "x" }], jsPsych);
+      await pressKey("a");
+
+      const rec = jsPsych.getSessionRecording()!;
+      const linkSnaps = rec.stylesheets.filter((s) => s.kind === "link");
+      expect(linkSnaps.some((s) => s.href === "https://example.test/jspsych.css")).toBe(true);
+    });
+
+    test("initial stylesheets array is fixed at start; later additions go to stylesheet_events", async () => {
+      const style = document.createElement("style");
+      style.textContent = ".pre-existing { color: red; }";
+      document.head.appendChild(style);
+
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline(
+        [
+          {
+            type: htmlKeyboardResponse,
+            stimulus: "x",
+            on_load: () => {
+              const late = document.createElement("style");
+              late.textContent = ".added-during-trial { color: blue; }";
+              document.head.appendChild(late);
+            },
+          },
+        ],
+        jsPsych
+      );
+      await pressKey("a");
+
+      const rec = jsPsych.getSessionRecording()!;
+      const initialCss = rec.stylesheets.map((s) => s.css ?? "").join("\n");
+      expect(initialCss).toContain("pre-existing");
+      expect(initialCss).not.toContain("added-during-trial");
+
+      const adds = rec.stylesheet_events.filter((e) => e.type === "stylesheet.add");
+      expect(adds.some((e) => (e.sheet.css ?? "").includes("added-during-trial"))).toBe(true);
+    });
+
+    test("emits stylesheet.add when a <style> is appended to <head> mid-session", async () => {
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline(
+        [
+          {
+            type: htmlKeyboardResponse,
+            stimulus: "x",
+            on_load: () => {
+              const s = document.createElement("style");
+              s.textContent = ".mid-session { color: green; }";
+              document.head.appendChild(s);
+            },
+          },
+        ],
+        jsPsych
+      );
+      await pressKey("a");
+
+      const rec = jsPsych.getSessionRecording()!;
+      const adds = rec.stylesheet_events.filter((e) => e.type === "stylesheet.add");
+      expect(adds.length).toBeGreaterThan(0);
+      const match = adds.find(
+        (e) => e.sheet.kind === "inline" && e.sheet.css.includes("mid-session")
+      );
+      expect(match).toBeDefined();
+      expect(typeof match!.sheet.id).toBe("number");
+      expect(match!.t).toEqual(expect.any(Number));
+    });
+
+    test("emits stylesheet.remove referencing the original snapshot id", async () => {
+      const style = document.createElement("style");
+      style.textContent = ".doomed { color: red; }";
+      document.head.appendChild(style);
+
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline(
+        [
+          {
+            type: htmlKeyboardResponse,
+            stimulus: "x",
+            on_load: () => {
+              style.remove();
+            },
+          },
+        ],
+        jsPsych
+      );
+      await pressKey("a");
+
+      const rec = jsPsych.getSessionRecording()!;
+      const initial = rec.stylesheets.find((s) => (s.css ?? "").includes("doomed"));
+      expect(initial).toBeDefined();
+      const removes = rec.stylesheet_events.filter((e) => e.type === "stylesheet.remove");
+      expect(removes.some((e) => e.id === initial!.id)).toBe(true);
+    });
+
+    test("emits stylesheet.update when a tracked <style>'s text changes", async () => {
+      const style = document.createElement("style");
+      style.textContent = ".v1 { color: red; }";
+      document.head.appendChild(style);
+
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline(
+        [
+          {
+            type: htmlKeyboardResponse,
+            stimulus: "x",
+            on_load: () => {
+              style.textContent = ".v2 { color: blue; }";
+            },
+          },
+        ],
+        jsPsych
+      );
+      await pressKey("a");
+
+      const rec = jsPsych.getSessionRecording()!;
+      const initial = rec.stylesheets.find((s) => (s.css ?? "").includes("v1"));
+      expect(initial).toBeDefined();
+      const updates = rec.stylesheet_events.filter((e) => e.type === "stylesheet.update");
+      expect(updates.length).toBeGreaterThan(0);
+      const last = updates[updates.length - 1];
+      expect(last.id).toBe(initial!.id);
+      expect(last.css).toContain("v2");
+    });
+
+    test("ignores non-stylesheet head mutations (e.g. <meta>, <title>)", async () => {
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline(
+        [
+          {
+            type: htmlKeyboardResponse,
+            stimulus: "x",
+            on_load: () => {
+              const meta = document.createElement("meta");
+              meta.name = "irrelevant";
+              document.head.appendChild(meta);
+            },
+          },
+        ],
+        jsPsych
+      );
+      await pressKey("a");
+
+      const rec = jsPsych.getSessionRecording()!;
+      expect(rec.stylesheet_events).toHaveLength(0);
+    });
+  });
+
+  describe("canvas snapshot capture", () => {
+    test("captures a final canvas.snapshot at trial end for canvases in the initial DOM", async () => {
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline(
+        [
+          {
+            type: htmlKeyboardResponse,
+            stimulus: '<canvas id="c" width="50" height="50"></canvas>',
+            on_load: () => {
+              const c = document.getElementById("c") as HTMLCanvasElement;
+              const ctx = c.getContext("2d")!;
+              ctx.fillRect(10, 10, 20, 20);
+            },
+          },
+        ],
+        jsPsych
+      );
+      await pressKey("a");
+
+      const rec = jsPsych.getSessionRecording()!;
+      const snaps = rec.trials[0].events.filter((e) => e.type === "canvas.snapshot");
+      expect(snaps.length).toBeGreaterThan(0);
+      const last = snaps[snaps.length - 1];
+      expect(typeof last.node).toBe("number");
+      expect(last.data_url).toEqual(expect.stringMatching(/^data:image\/png/));
+    });
+
+    test("emits no canvas.snapshot events when the trial has no canvas", async () => {
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline(
+        [{ type: htmlKeyboardResponse, stimulus: "<p>no canvas here</p>" }],
+        jsPsych
+      );
+      await pressKey("a");
+
+      const rec = jsPsych.getSessionRecording()!;
+      const snaps = rec.trials[0].events.filter((e) => e.type === "canvas.snapshot");
+      expect(snaps).toHaveLength(0);
+    });
+
+    test("tracks canvases added mid-trial via dom.add", async () => {
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline(
+        [
+          {
+            type: htmlKeyboardResponse,
+            stimulus: '<div id="host"></div>',
+            on_load: () => {
+              const c = document.createElement("canvas");
+              c.id = "late";
+              c.width = 32;
+              c.height = 32;
+              document.getElementById("host")!.appendChild(c);
+            },
+          },
+        ],
+        jsPsych
+      );
+      await pressKey("a");
+
+      const rec = jsPsych.getSessionRecording()!;
+      const snaps = rec.trials[0].events.filter((e) => e.type === "canvas.snapshot");
+      expect(snaps.length).toBeGreaterThan(0);
+    });
+
+    test("captures the canvas's final pixel state when it is removed mid-trial", async () => {
+      // jsPsych core clears the display element via `innerHTML = ""` after
+      // every trial, before `onTrialFinish` fires. The recorder must take
+      // its final snapshot at the moment of removal — a trial-end-only
+      // flush would race with the cleanup and miss the canvas entirely.
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline(
+        [
+          {
+            type: htmlKeyboardResponse,
+            stimulus: '<canvas id="c" width="20" height="20"></canvas>',
+            on_load: () => {
+              const c = document.getElementById("c") as HTMLCanvasElement;
+              c.getContext("2d")!.fillRect(0, 0, 10, 10);
+              c.remove();
+            },
+          },
+        ],
+        jsPsych
+      );
+      await pressKey("a");
+
+      const rec = jsPsych.getSessionRecording()!;
+      const snaps = rec.trials[0].events.filter((e) => e.type === "canvas.snapshot");
+      expect(snaps).toHaveLength(1);
+      expect(snaps[0].data_url).toEqual(expect.stringMatching(/^data:image\/png/));
+    });
+
+    test("a tainted canvas (toDataURL throws) does not break the recording", async () => {
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline(
+        [
+          {
+            type: htmlKeyboardResponse,
+            stimulus: '<canvas id="c" width="10" height="10"></canvas>',
+            on_load: () => {
+              const c = document.getElementById("c") as HTMLCanvasElement;
+              c.toDataURL = () => {
+                throw new DOMException("tainted", "SecurityError");
+              };
+            },
+          },
+        ],
+        jsPsych
+      );
+      await pressKey("a");
+
+      const rec = jsPsych.getSessionRecording()!;
+      // Recording still ends cleanly and the trial completes.
+      expect(rec.end_reason).toBe("finished");
+      const snaps = rec.trials[0].events.filter((e) => e.type === "canvas.snapshot");
+      expect(snaps).toHaveLength(0);
+    });
+
+    test("patches CanvasRenderingContext2D draw methods during recording and restores them on stop", async () => {
+      const proto = (CanvasRenderingContext2D as any).prototype;
+      const originalFillRect = proto.fillRect;
+      let fillRectDuringTrial: any = null;
+
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline(
+        [
+          {
+            type: htmlKeyboardResponse,
+            stimulus: "x",
+            on_load: () => {
+              fillRectDuringTrial = proto.fillRect;
+            },
+          },
+        ],
+        jsPsych
+      );
+      await pressKey("a");
+
+      // Mid-trial: the prototype method is wrapped (not the captured original).
+      expect(fillRectDuringTrial).not.toBe(originalFillRect);
+      // After `stop()`: the wrapper is removed and the original is back in
+      // place so opting in to recording does not leave global state dirty.
+      expect(proto.fillRect).toBe(originalFillRect);
+    });
+
+    test("emits a follow-up partial snapshot when the canvas is drawn to after the baseline", async () => {
+      // jest-canvas-mock's `getImageData` returns blank pixels regardless
+      // of what was drawn, so we override it on the canvas's context with
+      // a deterministic stub: the first read returns blank (becomes the
+      // baseline shadow), every subsequent read returns a single red
+      // pixel at (3, 4). The diff path should then emit a partial
+      // snapshot whose `region` matches that pixel.
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline(
+        [
+          {
+            type: htmlKeyboardResponse,
+            stimulus: '<canvas id="c" width="20" height="20"></canvas>',
+            on_load: () => {
+              const c = document.getElementById("c") as HTMLCanvasElement;
+              const ctx = c.getContext("2d")!;
+              let calls = 0;
+              ctx.getImageData = () => {
+                calls++;
+                const buf = new Uint8ClampedArray(20 * 20 * 4);
+                if (calls > 1) {
+                  const i = (4 * 20 + 3) * 4;
+                  buf[i] = 255;
+                  buf[i + 3] = 255;
+                }
+                return new ImageData(buf, 20, 20);
+              };
+              // Trigger the patched draw method so the dirty flag is set
+              // and a frame tick is scheduled.
+              ctx.fillRect(0, 0, 1, 1);
+            },
+          },
+        ],
+        jsPsych
+      );
+      // Wait long enough for both the initial-baseline RAF and the
+      // animation-throttle window (~66 ms) so the draw-driven tick can
+      // fire and run a diff.
+      await new Promise((r) => setTimeout(r, 200));
+      await pressKey("a");
+
+      const rec = jsPsych.getSessionRecording()!;
+      const snaps = rec.trials[0].events.filter((e) => e.type === "canvas.snapshot") as Array<{
+        type: "canvas.snapshot";
+        t: number;
+        node: number;
+        data_url: string;
+        region?: { x: number; y: number; w: number; h: number };
+      }>;
+      // At least the full baseline + one diff-detected partial.
+      expect(snaps.length).toBeGreaterThanOrEqual(2);
+      const partial = snaps.find((s) => s.region !== undefined);
+      expect(partial).toBeDefined();
+      expect(partial!.region).toEqual({ x: 3, y: 4, w: 1, h: 1 });
+    });
+
+    test("captures an initial baseline snapshot via RAF shortly after trial load", async () => {
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline(
+        [
+          {
+            type: htmlKeyboardResponse,
+            stimulus: '<canvas id="c" width="40" height="40"></canvas>',
+            on_load: () => {
+              const c = document.getElementById("c") as HTMLCanvasElement;
+              c.getContext("2d")!.fillRect(0, 0, 10, 10);
+            },
+          },
+        ],
+        jsPsych
+      );
+      // Let the recorder's initial-baseline animation frame fire before the
+      // trial ends. Without it, the only snapshot would come from the
+      // trial-end `releaseSubtree` path (close to `t_end`).
+      await new Promise((r) => setTimeout(r, 50));
+      await pressKey("a");
+
+      const rec = jsPsych.getSessionRecording()!;
+      const snaps = rec.trials[0].events.filter((e) => e.type === "canvas.snapshot") as Array<{
+        type: "canvas.snapshot";
+        t: number;
+        node: number;
+        data_url: string;
+        region?: { x: number; y: number; w: number; h: number };
+      }>;
+      expect(snaps.length).toBeGreaterThanOrEqual(1);
+      // The first snapshot is a full baseline (no `region`) and lands much
+      // closer to `t_dom_ready` than to `t_end`. If the initial RAF didn't
+      // fire, this would instead land near `t_end` (release-on-removal).
+      expect(snaps[0].region).toBeUndefined();
+      const t_dom = rec.trials[0].t_dom_ready!;
+      const t_end = rec.trials[0].t_end!;
+      expect(snaps[0].t - t_dom).toBeLessThan((t_end - t_dom) / 2);
+    });
+  });
+
+  describe("computeDiffBbox", () => {
+    function makePixels(w: number, h: number, fill = 0): Uint8ClampedArray {
+      const buf = new Uint8ClampedArray(w * h * 4);
+      if (fill !== 0) buf.fill(fill);
+      return buf;
+    }
+
+    function setPixel(buf: Uint8ClampedArray, w: number, x: number, y: number, rgba: number[]) {
+      const i = (y * w + x) * 4;
+      buf[i] = rgba[0];
+      buf[i + 1] = rgba[1];
+      buf[i + 2] = rgba[2];
+      buf[i + 3] = rgba[3];
+    }
+
+    test("returns null when buffers are byte-identical", () => {
+      const w = 16;
+      const h = 16;
+      const a = makePixels(w, h);
+      const b = makePixels(w, h);
+      expect(computeDiffBbox(a, b, w, h)).toBeNull();
+    });
+
+    test("returns a 1x1 bbox at the changed pixel for a single-pixel diff", () => {
+      const w = 16;
+      const h = 16;
+      const a = makePixels(w, h);
+      const b = makePixels(w, h);
+      setPixel(b, w, 5, 7, [255, 0, 0, 255]);
+      expect(computeDiffBbox(a, b, w, h)).toEqual({ x: 5, y: 7, w: 1, h: 1 });
+    });
+
+    test("returns the tight bbox spanning two distant changed pixels", () => {
+      const w = 32;
+      const h = 32;
+      const a = makePixels(w, h);
+      const b = makePixels(w, h);
+      setPixel(b, w, 3, 4, [255, 0, 0, 255]);
+      setPixel(b, w, 20, 25, [0, 255, 0, 255]);
+      expect(computeDiffBbox(a, b, w, h)).toEqual({ x: 3, y: 4, w: 18, h: 22 });
+    });
+
+    test("returns the full canvas bbox when every pixel changed", () => {
+      const w = 8;
+      const h = 8;
+      const a = makePixels(w, h, 0);
+      const b = makePixels(w, h, 255);
+      expect(computeDiffBbox(a, b, w, h)).toEqual({ x: 0, y: 0, w, h });
+    });
+
+    test("detects an alpha-only change (channel 3) as a diff", () => {
+      const w = 4;
+      const h = 4;
+      const a = makePixels(w, h, 0);
+      const b = makePixels(w, h, 0);
+      // Only the alpha byte at (1, 1) differs.
+      b[(1 * w + 1) * 4 + 3] = 128;
+      expect(computeDiffBbox(a, b, w, h)).toEqual({ x: 1, y: 1, w: 1, h: 1 });
+    });
+  });
+
+  describe("form-state capture", () => {
+    test("captures input.value events for typed text", async () => {
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline(
+        [
+          {
+            type: htmlKeyboardResponse,
+            stimulus: '<input id="q" type="text">',
+            on_load: () => {
+              const input = document.getElementById("q") as HTMLInputElement;
+              input.value = "hello";
+              input.dispatchEvent(new Event("input", { bubbles: true }));
+            },
+          },
+        ],
+        jsPsych
+      );
+      await pressKey("a");
+
+      const rec = jsPsych.getSessionRecording()!;
+      const inputs = rec.trials[0].events.filter((e) => e.type === "input.value");
+      expect(inputs.length).toBeGreaterThan(0);
+      const last = inputs[inputs.length - 1];
+      expect(last.value).toBe("hello");
+      expect(typeof last.node).toBe("number");
+    });
+
+    test("captures input.value events for textarea content", async () => {
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline(
+        [
+          {
+            type: htmlKeyboardResponse,
+            stimulus: '<textarea id="ta"></textarea>',
+            on_load: () => {
+              const ta = document.getElementById("ta") as HTMLTextAreaElement;
+              ta.value = "line one\nline two";
+              ta.dispatchEvent(new Event("input", { bubbles: true }));
+            },
+          },
+        ],
+        jsPsych
+      );
+      await pressKey("a");
+
+      const rec = jsPsych.getSessionRecording()!;
+      const inputs = rec.trials[0].events.filter((e) => e.type === "input.value");
+      expect(inputs[inputs.length - 1].value).toBe("line one\nline two");
+    });
+
+    test("coalesces multiple input events on the same field within a frame", async () => {
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline(
+        [
+          {
+            type: htmlKeyboardResponse,
+            stimulus: '<input id="q" type="text">',
+            on_load: () => {
+              const input = document.getElementById("q") as HTMLInputElement;
+              for (const v of ["h", "he", "hel", "hell", "hello"]) {
+                input.value = v;
+                input.dispatchEvent(new Event("input", { bubbles: true }));
+              }
+            },
+          },
+        ],
+        jsPsych
+      );
+      await pressKey("a");
+
+      const rec = jsPsych.getSessionRecording()!;
+      const inputs = rec.trials[0].events.filter((e) => e.type === "input.value");
+      // Five rapid events without an intervening RAF flush coalesce into one.
+      expect(inputs).toHaveLength(1);
+      expect(inputs[0].value).toBe("hello");
+    });
+
+    test("captures input.checked events for checkboxes", async () => {
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline(
+        [
+          {
+            type: htmlKeyboardResponse,
+            stimulus: '<input id="cb" type="checkbox">',
+            on_load: () => {
+              const cb = document.getElementById("cb") as HTMLInputElement;
+              cb.checked = true;
+              cb.dispatchEvent(new Event("change", { bubbles: true }));
+            },
+          },
+        ],
+        jsPsych
+      );
+      await pressKey("a");
+
+      const rec = jsPsych.getSessionRecording()!;
+      const checks = rec.trials[0].events.filter((e) => e.type === "input.checked");
+      expect(checks).toHaveLength(1);
+      expect(checks[0].checked).toBe(true);
+    });
+
+    test("captures input.checked events for radio buttons", async () => {
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline(
+        [
+          {
+            type: htmlKeyboardResponse,
+            stimulus:
+              '<input id="r1" type="radio" name="g" value="a">' +
+              '<input id="r2" type="radio" name="g" value="b">',
+            on_load: () => {
+              const r2 = document.getElementById("r2") as HTMLInputElement;
+              r2.checked = true;
+              r2.dispatchEvent(new Event("change", { bubbles: true }));
+            },
+          },
+        ],
+        jsPsych
+      );
+      await pressKey("a");
+
+      const rec = jsPsych.getSessionRecording()!;
+      const checks = rec.trials[0].events.filter((e) => e.type === "input.checked");
+      expect(checks).toHaveLength(1);
+      expect(checks[0].checked).toBe(true);
+    });
+
+    test("captures input.select events for single-select <select>", async () => {
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline(
+        [
+          {
+            type: htmlKeyboardResponse,
+            stimulus:
+              '<select id="s">' +
+              '<option value="a">A</option>' +
+              '<option value="b">B</option>' +
+              "</select>",
+            on_load: () => {
+              const s = document.getElementById("s") as HTMLSelectElement;
+              s.value = "b";
+              s.dispatchEvent(new Event("change", { bubbles: true }));
+            },
+          },
+        ],
+        jsPsych
+      );
+      await pressKey("a");
+
+      const rec = jsPsych.getSessionRecording()!;
+      const selects = rec.trials[0].events.filter((e) => e.type === "input.select");
+      expect(selects).toHaveLength(1);
+      expect(selects[0].values).toEqual(["b"]);
+    });
+
+    test("captures input.select events for multi-select <select multiple>", async () => {
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline(
+        [
+          {
+            type: htmlKeyboardResponse,
+            stimulus:
+              '<select id="s" multiple>' +
+              '<option value="a">A</option>' +
+              '<option value="b">B</option>' +
+              '<option value="c">C</option>' +
+              "</select>",
+            on_load: () => {
+              const s = document.getElementById("s") as HTMLSelectElement;
+              (s.options[0] as HTMLOptionElement).selected = true;
+              (s.options[2] as HTMLOptionElement).selected = true;
+              s.dispatchEvent(new Event("change", { bubbles: true }));
+            },
+          },
+        ],
+        jsPsych
+      );
+      await pressKey("a");
+
+      const rec = jsPsych.getSessionRecording()!;
+      const selects = rec.trials[0].events.filter((e) => e.type === "input.select");
+      expect(selects).toHaveLength(1);
+      expect(selects[0].values).toEqual(["a", "c"]);
+    });
+
+    test("ignores input events from <input type=file>", async () => {
+      const jsPsych = initJsPsych({ record_session: true });
+      await startTimeline(
+        [
+          {
+            type: htmlKeyboardResponse,
+            stimulus: '<input id="f" type="file">',
+            on_load: () => {
+              const f = document.getElementById("f") as HTMLInputElement;
+              f.dispatchEvent(new Event("input", { bubbles: true }));
+            },
+          },
+        ],
+        jsPsych
+      );
+      await pressKey("a");
+
+      const rec = jsPsych.getSessionRecording()!;
+      const inputs = rec.trials[0].events.filter((e) => e.type === "input.value");
+      expect(inputs).toHaveLength(0);
+    });
+  });
+
+  test("captures window scroll events", async () => {
+    const jsPsych = initJsPsych({ record_session: true });
+    await startTimeline(
+      [
+        {
+          type: htmlKeyboardResponse,
+          stimulus: "x",
+          on_load: () => {
+            // simulate a scroll event on the document
+            document.dispatchEvent(new Event("scroll"));
+          },
+        },
+      ],
+      jsPsych
+    );
+    await pressKey("a");
+
+    const rec = jsPsych.getSessionRecording()!;
+    const scrollEvents = rec.trials[0].events.filter((e) => e.type === "scroll.window");
+    expect(scrollEvents.length).toBeGreaterThan(0);
+    expect(scrollEvents[0]).toEqual(
+      expect.objectContaining({
+        type: "scroll.window",
+        x: expect.any(Number),
+        y: expect.any(Number),
+        t: expect.any(Number),
+      })
+    );
+  });
+
+  test("captures element scroll events keyed by node id", async () => {
+    const jsPsych = initJsPsych({ record_session: true });
+    await startTimeline(
+      [
+        {
+          type: htmlKeyboardResponse,
+          stimulus:
+            '<div id="scroll-region" style="overflow:auto;height:50px;"><p>line</p><p>line</p></div>',
+          on_load: () => {
+            const region = document.getElementById("scroll-region")!;
+            // jsdom doesn't physically scroll, but dispatching the event with
+            // the element as target exercises the code path.
+            region.dispatchEvent(new Event("scroll"));
+          },
+        },
+      ],
+      jsPsych
+    );
+    await pressKey("a");
+
+    const rec = jsPsych.getSessionRecording()!;
+    const scrollEvents = rec.trials[0].events.filter((e) => e.type === "scroll.element");
+    expect(scrollEvents.length).toBeGreaterThan(0);
+    expect(scrollEvents[0]).toEqual(
+      expect.objectContaining({
+        type: "scroll.element",
+        node: expect.any(Number),
+        x: expect.any(Number),
+        y: expect.any(Number),
+      })
+    );
+  });
+
+  test("a fresh start() after stop() begins a new recording without leaking state", async () => {
+    const original = Math.random;
+    const jsPsych = initJsPsych({ record_session: true });
+
+    await startTimeline([{ type: htmlKeyboardResponse, stimulus: "first" }], jsPsych);
+    await pressKey("a");
+
+    // Snapshot the first run before re-starting; the recorder will replace
+    // its internal recording object on the next start().
+    const firstRecording = jsPsych.getSessionRecording()!;
+    expect(firstRecording.end_reason).toBe("finished");
+    expect(firstRecording.trials).toHaveLength(1);
+    expect(firstRecording.trials[0].plugin).toBe("html-keyboard-response");
+
+    // Math.random must be fully restored between sessions.
+    expect(Math.random).toBe(original);
+
+    // Reach the recorder via the JsPsych instance and restart it manually
+    // to exercise the reuse contract directly (without spinning up a second
+    // JsPsych instance, which would obscure the test).
+    const recorder = (jsPsych as any).sessionRecorder as {
+      start: (el: HTMLElement) => void;
+      stop: (reason?: "finished" | "aborted" | "unload") => void;
+      onTrialStart: (info: { trial_index: number; plugin: string }) => void;
+      onTrialFinish: (data: unknown) => void;
+      getRecording: () => any;
+    };
+
+    recorder.start(jsPsych.getDisplayElement());
+    recorder.onTrialStart({ trial_index: 0, plugin: "synthetic" });
+    recorder.onTrialFinish({ rt: 100 });
+    recorder.stop("finished");
+
+    const secondRecording = recorder.getRecording();
+
+    // The second recording is a brand-new object with only the new trial.
+    expect(secondRecording).not.toBe(firstRecording);
+    expect(secondRecording.trials).toHaveLength(1);
+    expect(secondRecording.trials[0].plugin).toBe("synthetic");
+    expect(secondRecording.end_reason).toBe("finished");
+
+    // The first recording is unchanged.
+    expect(firstRecording.trials).toHaveLength(1);
+    expect(firstRecording.trials[0].plugin).toBe("html-keyboard-response");
+
+    // Math.random is again restored after the second stop, with no
+    // double-wrapping (i.e. the function reference equals the true original).
+    expect(Math.random).toBe(original);
+  });
+
+  test("stop() flushes pending throttled events from an in-flight trial", async () => {
+    const jsPsych = initJsPsych({ record_session: true });
+
+    await startTimeline([{ type: htmlKeyboardResponse, stimulus: "x" }], jsPsych);
+
+    // Simulate user activity, then stop the recorder mid-trial without
+    // letting the rAF callback fire. The pending mouse-move position must
+    // still appear in the trial's events.
+    const display = jsPsych.getDisplayElement();
+    display.dispatchEvent(
+      new MouseEvent("mousemove", { clientX: 123, clientY: 456, bubbles: true })
+    );
+
+    const recorder = (jsPsych as any).sessionRecorder as {
+      stop: (reason?: "finished" | "aborted" | "unload") => void;
+    };
+    recorder.stop("aborted");
+
+    const rec = jsPsych.getSessionRecording()!;
+    expect(rec.end_reason).toBe("aborted");
+    const moves = rec.trials[0].events.filter((e) => e.type === "mouse.move");
+    expect(moves.length).toBeGreaterThan(0);
+    expect(moves[moves.length - 1]).toEqual(expect.objectContaining({ x: 123, y: 456 }));
+
+    // Tidy up: finish the still-pending pressKey-driven trial promise so
+    // the experiment can settle without tripping later assertions.
+    await pressKey("a");
+  });
+
+  test("captures mouse activity outside the #jspsych-content element", async () => {
+    // Regression test: mouse listeners used to be scoped to the display
+    // element (`#jspsych-content`), which is typically narrower than the
+    // viewport. Movements toward the browser chrome (to resize/move the
+    // window) or into a canvas corner that extends past the content
+    // div fired no events at all, so the replay would freeze the
+    // cursor at its last known position. Listeners are now window-
+    // scoped so events anywhere in the viewport are captured.
+    const jsPsych = initJsPsych({ record_session: true });
+    await startTimeline([{ type: htmlKeyboardResponse, stimulus: "x" }], jsPsych);
+
+    // Dispatch on `document.body`, which is outside `#jspsych-content`
+    // (the body wraps the display container, which wraps the content
+    // div). The old element-scoped listener would not see this event.
+    document.body.dispatchEvent(
+      new MouseEvent("mousemove", { clientX: 5, clientY: 7, bubbles: true })
+    );
+    // Allow the rAF-throttled flush to fire.
+    await new Promise((r) => requestAnimationFrame(r));
+
+    // And dispatch a click on the body, again outside the content div.
+    document.body.dispatchEvent(
+      new MouseEvent("click", { clientX: 11, clientY: 13, button: 0, bubbles: true })
+    );
+
+    await pressKey("a");
+
+    const rec = jsPsych.getSessionRecording()!;
+    const moves = rec.trials[0].events.filter((e) => e.type === "mouse.move") as Array<{
+      x: number;
+      y: number;
+    }>;
+    const clicks = rec.trials[0].events.filter((e) => e.type === "mouse.click") as Array<{
+      x: number;
+      y: number;
+      target: number | null;
+    }>;
+    expect(moves).toContainEqual(expect.objectContaining({ x: 5, y: 7 }));
+    expect(clicks).toContainEqual(expect.objectContaining({ x: 11, y: 13 }));
+  });
+
+  test("captures multiple trials, each with its own initial_dom and events", async () => {
+    const jsPsych = initJsPsych({ record_session: true });
+    await startTimeline(
+      [
+        { type: htmlKeyboardResponse, stimulus: "<p>first</p>" },
+        { type: htmlKeyboardResponse, stimulus: "<p>second</p>" },
+        { type: htmlKeyboardResponse, stimulus: "<p>third</p>" },
+      ],
+      jsPsych
+    );
+    await pressKey("a");
+    await pressKey("a");
+    await pressKey("a");
+
+    const rec = jsPsych.getSessionRecording()!;
+    expect(rec.trials).toHaveLength(3);
+    expect(rec.trials.map((t) => t.trial_index)).toEqual([0, 1, 2]);
+
+    // Each trial has its own DOM baseline and a non-null t_dom_ready / t_end.
+    for (const trial of rec.trials) {
+      expect(trial.initial_dom).not.toBeNull();
+      expect(trial.t_dom_ready).not.toBeNull();
+      expect(trial.t_end).not.toBeNull();
+    }
+
+    // Trials are chronologically ordered (each starts after the previous ended).
+    expect(rec.trials[1].t_start).toBeGreaterThanOrEqual(rec.trials[0].t_end!);
+    expect(rec.trials[2].t_start).toBeGreaterThanOrEqual(rec.trials[1].t_end!);
+
+    // The DOM baselines should reflect the distinct stimuli.
+    const html = (dom: any) => JSON.stringify(dom);
+    expect(html(rec.trials[0].initial_dom)).toContain("first");
+    expect(html(rec.trials[1].initial_dom)).toContain("second");
+    expect(html(rec.trials[2].initial_dom)).toContain("third");
+  });
+
+  test("captures viewport_changes when the window resizes", async () => {
+    const jsPsych = initJsPsych({ record_session: true });
+    await startTimeline(
+      [
+        {
+          type: htmlKeyboardResponse,
+          stimulus: "x",
+          on_load: () => {
+            // Mutate jsdom's reported viewport size, then dispatch resize.
+            Object.defineProperty(window, "innerWidth", {
+              configurable: true,
+              value: 9999,
+            });
+            Object.defineProperty(window, "innerHeight", {
+              configurable: true,
+              value: 8888,
+            });
+            window.dispatchEvent(new Event("resize"));
+          },
+        },
+      ],
+      jsPsych
+    );
+    // The recorder debounces viewport reads with a 100 ms trailing timer; let
+    // it fire before the trial ends.
+    await new Promise((r) => setTimeout(r, 150));
+    await pressKey("a");
+
+    const rec = jsPsych.getSessionRecording()!;
+    expect(rec.viewport_changes.length).toBeGreaterThan(0);
+    const last = rec.viewport_changes[rec.viewport_changes.length - 1];
+    expect(last.w).toBe(9999);
+    expect(last.h).toBe(8888);
+  });
+
+  test("captures window focus/blur events", async () => {
+    const jsPsych = initJsPsych({ record_session: true });
+    await startTimeline(
+      [
+        {
+          type: htmlKeyboardResponse,
+          stimulus: "x",
+          on_load: () => {
+            window.dispatchEvent(new Event("blur"));
+            window.dispatchEvent(new Event("focus"));
+          },
+        },
+      ],
+      jsPsych
+    );
+    await pressKey("a");
+
+    const rec = jsPsych.getSessionRecording()!;
+    const focusEvents = rec.trials[0].events.filter((e) => e.type === "focus" || e.type === "blur");
+    // Both blur and focus should be present.
+    expect(focusEvents.map((e) => e.type)).toEqual(expect.arrayContaining(["blur", "focus"]));
+  });
+
+  test("captures media play and pause events for video elements", async () => {
+    const jsPsych = initJsPsych({ record_session: true });
+    await startTimeline(
+      [
+        {
+          type: htmlKeyboardResponse,
+          stimulus: '<video id="vid" src="about:blank"></video>',
+          on_load: () => {
+            const video = document.getElementById("vid") as HTMLVideoElement;
+            video.dispatchEvent(new Event("play"));
+            video.dispatchEvent(new Event("pause"));
+          },
+        },
+      ],
+      jsPsych
+    );
+    await pressKey("a");
+
+    const rec = jsPsych.getSessionRecording()!;
+    const mediaEvents = rec.trials[0].events.filter((e) =>
+      ["media.play", "media.pause", "media.ended", "media.seeked", "media.time"].includes(e.type)
+    );
+    expect(mediaEvents.map((e) => e.type)).toEqual(
+      expect.arrayContaining(["media.play", "media.pause"])
+    );
+  });
+
+  test("abortExperiment marks the recording end_reason as 'aborted'", async () => {
+    const jsPsych = initJsPsych({ record_session: true });
+    await startTimeline(
+      [
+        {
+          type: htmlKeyboardResponse,
+          stimulus: "first",
+          on_finish: () => {
+            jsPsych.abortExperiment("done");
+          },
+        },
+        { type: htmlKeyboardResponse, stimulus: "second" },
+      ],
+      jsPsych
+    );
+    await pressKey("a");
+
+    const rec = jsPsych.getSessionRecording()!;
+    expect(rec.end_reason).toBe("aborted");
+    // Only the first trial should have started; the second never did.
+    expect(rec.trials).toHaveLength(1);
+  });
+});
diff --git a/packages/jspsych/tests/jsdom-polyfills.cjs b/packages/jspsych/tests/jsdom-polyfills.cjs
new file mode 100644
index 0000000000..f21f38ff1d
--- /dev/null
+++ b/packages/jspsych/tests/jsdom-polyfills.cjs
@@ -0,0 +1,31 @@
+// jsdom does not expose the Web Streams APIs or the
+// TextEncoder/TextDecoder pair, even though Node 18+ provides both.
+// Without this shim, code that uses `new CompressionStream()` etc.
+// cannot run under `testEnvironment: "jsdom"`, which would force the
+// recorder's compressed-recording path into browser-only territory and
+// leave it untested. We import the Node implementations and assign
+// them onto `globalThis` so test code sees the same surface a real
+// browser would.
+const { TextEncoder, TextDecoder } = require("util");
+const {
+  CompressionStream,
+  DecompressionStream,
+  ReadableStream,
+  WritableStream,
+  TransformStream,
+} = require("stream/web");
+const { Blob } = require("buffer");
+
+Object.assign(globalThis, {
+  TextEncoder,
+  TextDecoder,
+  CompressionStream,
+  DecompressionStream,
+  ReadableStream,
+  WritableStream,
+  TransformStream,
+  // jsdom's Blob is missing `.arrayBuffer()`, `.text()`, and `.stream()`
+  // (they were added in much newer Web spec revisions). Node's
+  // `node:buffer.Blob` implements the full Web API, so use it instead.
+  Blob,
+});
diff --git a/packages/jspsych/tests/test-utils.ts b/packages/jspsych/tests/test-utils.ts
index 3b0cbcbcad..84a46e7b5e 100644
--- a/packages/jspsych/tests/test-utils.ts
+++ b/packages/jspsych/tests/test-utils.ts
@@ -14,6 +14,7 @@ export class TimelineNodeDependenciesMock implements TimelineNodeDependencies {
   private displayElement = document.createElement("div");
 
   onTrialStart = jest.fn();
+  onTrialLoad = jest.fn();
   onTrialResultAvailable = jest.fn();
   onTrialFinished = jest.fn();