Track jsPsych#3694's updated multiplayer contract

[jodeleeuw]

Follows the contract changes made on jsPsych#3694 after a review of the core MultiplayerAPI. The core side is commits 02e113c3, 96515f67, 5e3f18ca and cfe4c340 on that PR.

What changed in core

• A pending wait() rejects with a MultiplayerCancelledError when the experiment ends or is aborted, instead of hanging. jsPsych also cancels multiplayer subscriptions in abortExperiment() and after on_finish.
• push(), update() and wait() reject rather than throwing when the API is not connected.
• get(), getAll(), subscriber arguments and the wait() result are JSON copies, so session data must be JSON-serializable.
• update() merges onto this client's last write and coalesces writes issued faster than the backend confirms them.
• wait() treats null, negative and non-finite timeouts as no timeout; participantId is null until connect() resolves.

Fixes

• scoreboard: a cancelled wait took the backend-error path, so after abortExperiment() the plugin logged an error and drew a final board over the cleared display, leaving a Continue button that called finishTrial after the run had ended. After disconnect(), getAll() on that path threw inside a void-started async function, stranding the participant on the waiting message.
• countdown and draw: both drove repeating timers with a raw setInterval, which survives abortExperiment(). Countdown could call finishTrial after the run ended; draw kept writing to the session indefinitely. Both now tick through jsPsych's timer registry.
• chat and reference-game: each send rebuilt this client's whole message list from the adapter's cache, so two quick sends against a lagging cache could drop a message. Each now keeps its own messages in a local array.
• adapter-multiplayer-firebase: connect() marked itself connected before arming disconnect cleanup, so a failure there left a connected-looking adapter with a leaked listener, an owned app that disconnect() never released, and a retry that silently did nothing.
• jatos adapter example: called jsPsych.pluginAPI.connect, a TypeError.

Cleanup

• resolveMultiplayerApi() reads only jsPsych.multiplayer; the pluginAPI fallback is gone, since any build exposing the API there predates this contract.
• Hand-rolled read-merge-write against a client's own slot is now update() (choice, countdown, match, role, scoreboard, reference-game, and the live-scoreboard example).
• Each plugin's local API mirror carries the new types and docs, plus an isMultiplayerCancelledError helper where the plugin waits.
• Docs site, READMEs and examples updated; every example and the tutorial re-pinned to a preview build carrying the current contract.

Testing

npm test — 576 tests in 26 suites pass. Mocks modelled the old contract (live snapshots, no cancellation, null timeouts firing at once) and could not catch any of the bugs above, so they now follow the real one. Each plugin that waits has a cancelled-wait test, and the timer, message-race and Firebase fixes have regression tests that were each checked to fail against the old code.

Notes for review

• Chat's failed-send behaviour changed. A failed send is now resent by the next one, so a message that failed still reaches the group. Previously it was rendered locally and then lost, leaving that participant's view permanently out of step.
• Not done, say if you want it: both chat and reference-game build the saved transcript in end() from getAll(), so with a lagging cache a message the participant saw can be missing from the trial data.
• ready still replaces its whole slot with push() rather than merging, since that is documented behaviour.
• Requires a core build with the current contract; it will not work against older #3694 previews.

🤖 Generated with Claude Code