feat(jspsych): add record_session option for high-fidelity replay capture

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, 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 a snapshot of the trial parameters and rendered DOM at the start of every trial, all DOM mutations within `#jspsych-content`, mouse, touch, keyboard, and clipboard events, video and audio playback events, viewport changes, and every `Math.random()` output. The returned object contains the schema version (`schema_version: 1`); the on-disk format is the contract between recorder and any replayer.
+
+### 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

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, extractStimulusSource } 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,6 +155,8 @@ export class JsPsych {
 
     this.experimentStartTime = new Date();
 
+    this.sessionRecorder?.start(this.getDisplayElement());
+
     await this.timeline.run();
     await Promise.resolve(this.options.on_finish(this.data.get()));
 
@@ -155,6 +165,7 @@ export class JsPsych {
     }
 
     this.data.removeInteractionListeners();
+    this.sessionRecorder?.stop("finished");
   }
 
   async simulate(
@@ -196,12 +207,23 @@ 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();
+  }
+
   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 +416,12 @@ export class JsPsych {
 
   private timelineDependencies: TimelineNodeDependencies = {
     onTrialStart: (trial: Trial) => {
+      this.sessionRecorder?.onTrialStart({
+        trial_index: trial.index ?? -1,
+        plugin: trial.pluginClass?.["info"]?.name ?? "unknown",
+        trial_params: trial.trialObject,
+        stimulus_source: extractStimulusSource(trial.trialObject),
+      });
       this.options.on_trial_start(trial.trialObject);
 
       // apply the focus to the element containing the experiment.
@@ -402,6 +430,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 +444,7 @@ export class JsPsych {
 
     onTrialFinished: (trial: Trial) => {
       const result = trial.getResult();
+      this.sessionRecorder?.onTrialFinish(result);
       this.options.on_trial_finish(result);
 
       if (result) {