feat(jspsych): record form-state changes for survey replay fidelity

claude · claude · commit 61e35b587729 · 2026-05-01T13:39:39.000Z
The MutationObserver only sees the DOM `value` *attribute*; the IDL
`value` property the browser writes when a participant types into a
field, toggles a checkbox or radio, or changes a select is invisible to
it. As a result, replays of survey trials reconstructed the form
controls but rendered them empty.

Add three new InputRecord variants — input.value, input.checked,
input.select — emitted from capture-phase `input`/`change` listeners on
document. input.value is RAF-coalesced (rapid typing produces one event
per frame with the latest value) and flushed at trial finish so the
final value is never lost. input.checked and input.select are
unthrottled and fire on commit. &lt;input type=file&gt; is intentionally
ignored.
diff --git a/docs/reference/session-recording-schema.md b/docs/reference/session-recording-schema.md
@@ -235,11 +235,32 @@ type InputRecord =
       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
diff --git a/packages/jspsych/src/modules/recording.ts b/packages/jspsych/src/modules/recording.ts
@@ -144,7 +144,15 @@ export type InputRecord =
       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";
@@ -219,6 +227,12 @@ export class SessionRecorder {
   // 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;
 
@@ -304,6 +318,8 @@ export class SessionRecorder {
     this.mouseRafScheduled = false;
     this.scrollRafScheduled = false;
     this.pendingScroll.clear();
+    this.inputRafScheduled = false;
+    this.pendingInput.clear();
 
     this.patchMathRandom();
     this.attachSessionListeners();
@@ -318,6 +334,7 @@ export class SessionRecorder {
     if (this.currentTrial !== null) {
       this.flushPendingMouse();
       this.flushPendingScroll();
+      this.flushPendingInput();
       this.currentTrial.t_end = this.t();
       this.currentTrial = null;
     }
@@ -363,6 +380,7 @@ export class SessionRecorder {
     if (!this.currentTrial) return;
     this.flushPendingMouse();
     this.flushPendingScroll();
+    this.flushPendingInput();
     this.detachTrialListeners();
     this.currentTrial.t_end = this.t();
     this.currentTrial.trial_data = serializeJson(trialData);
@@ -474,6 +492,12 @@ export class SessionRecorder {
     // 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() {
@@ -816,6 +840,61 @@ export class SessionRecorder {
     }
   };
 
+  // `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();
diff --git a/packages/jspsych/tests/core/record-session.test.ts b/packages/jspsych/tests/core/record-session.test.ts
@@ -329,6 +329,214 @@ describe("record_session option", () => {
     });
   });
 
+  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(
