docs: clarify wait_for_key_release tracks only the most recent key press

With persist: true, a listener holds one pending release at a time; a
later valid press supersedes an unreleased earlier one. Document this
intended behavior in the API reference and a code comment, and add a
test that locks it in.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: jodeleeuw

docs/reference/jspsych-pluginAPI.md

@@ -165,7 +165,7 @@ audio_context_start_time | numeric | The scheduled time of the sound file in the
 allow_held_key | boolean | If `true`, then responses will be registered from keys that are being held down. If `false`, then a held key can only register a response the first time that `getKeyboardResponse` is called for that key. For example, if a participant holds down the `A` key before the experiment starts, then the first time `getKeyboardResponse` is called, the `A` will register as a key press. However, any future calls to `getKeyboardResponse` will not register the `A` until the participant releases the key and presses it again.
 persist | boolean | If false, then the keyboard listener will only trigger the first time a valid key is pressed. If true, then it will trigger every time a valid key is pressed until it is explicitly cancelled by `jsPsych.pluginAPI.cancelKeyboardResponse` or `jsPsych.pluginAPI.cancelAllKeyboardResponses`.
 minimum_valid_rt | number | The minimum valid response time for key presses. Any key press response time that is less than this value will be treated as invalid and ignored.
-wait_for_key_release | boolean | If `true`, the `callback_function` is not triggered when the key is pressed down. Instead, it is triggered when the response key is released (on `keyup`), and the object passed to it gains a third property, `rt_key_duration`, in addition to `key` and `rt`. `rt` still reflects the time of the key press, while `rt_key_duration` is the time in milliseconds that the key was held down, measured from the initial key press to the key release (or `null` if no press timestamp was recorded). If the keyboard listener is cancelled by `jsPsych.pluginAPI.cancelKeyboardResponse` or `jsPsych.pluginAPI.cancelAllKeyboardResponses` before the key is released, the deferred callback will not fire. `rt_key_duration` is always measured with `performance.now()`, regardless of `rt_method`. Defaults to `false`, in which case the callback fires at the key press with only `key` and `rt`.
+wait_for_key_release | boolean | If `true`, the `callback_function` is not triggered when the key is pressed down. Instead, it is triggered when the response key is released (on `keyup`), and the object passed to it gains a third property, `rt_key_duration`, in addition to `key` and `rt`. `rt` still reflects the time of the key press, while `rt_key_duration` is the time in milliseconds that the key was held down, measured from the initial key press to the key release (or `null` if no press timestamp was recorded). If the keyboard listener is cancelled by `jsPsych.pluginAPI.cancelKeyboardResponse` or `jsPsych.pluginAPI.cancelAllKeyboardResponses` before the key is released, the deferred callback will not fire. `rt_key_duration` is always measured with `performance.now()`, regardless of `rt_method`. When combined with `persist: true`, a listener tracks only one pending key release at a time: the release being awaited is always that of the most recent valid key press. If a second valid key is pressed before the first is released, the first press is superseded and its release will not fire the callback (only the most recent press's release is reported). Defaults to `false`, in which case the callback fires at the key press with only `key` and `rt`.
 
 #### Return value
 

packages/jspsych/src/modules/plugin-api/KeyboardListenerAPI.ts

@@ -158,6 +158,12 @@ export class KeyboardListenerAPI {
           // defer the callback until this key is released, keyed by the listener handle so that
           // the pending release is cancelled together with the listener (see cancelKeyboardResponse
           // and cancelAllKeyboardResponses).
+          //
+          // Because the pending release is keyed by listener, each listener tracks only one pending
+          // release at a time. With persist: true, if a second valid key is pressed before the first
+          // is released, this overwrites the earlier pending release: only the most recent press's
+          // release fires the callback. This is intentional — a deferred response reflects the most
+          // recent key press, matching how the non-deferred path only reports the latest press.
           this.pendingReleases.set(listener, { key, rt, callback_function });
         } else {
           callback_function({ key: e.key, rt });

packages/jspsych/tests/pluginAPI/pluginapi.test.ts

@@ -349,6 +349,31 @@ describe("#getKeyboardResponse wait_for_key_release", () => {
       expect.objectContaining({ key: "a", rt_key_duration: 250 })
     );
   });
+
+  test("persist: true: a second press before the first is released supersedes the first; only the latest press's release fires", async () => {
+    new KeyboardListenerAPI(getRootElement).getKeyboardResponse({
+      callback_function: callback,
+      wait_for_key_release: true,
+      persist: true,
+    });
+
+    // press "a", then press "b" before releasing "a"
+    await keyDown("a");
+    jest.advanceTimersByTime(100);
+    await keyDown("b");
+    jest.advanceTimersByTime(100);
+
+    // releasing "a" does not fire: it was superseded by the "b" press
+    await keyUp("a");
+    expect(callback).toHaveBeenCalledTimes(0);
+
+    // releasing "b" fires with the duration measured from the "b" press
+    await keyUp("b");
+    expect(callback).toHaveBeenCalledTimes(1);
+    expect(callback).toHaveBeenLastCalledWith(
+      expect.objectContaining({ key: "b", rt_key_duration: 100 })
+    );
+  });
 });
 
 describe("#cancelKeyboardResponse", () => {