Rebuild the Hawkins paid pilot on the session-based multiplayer API

[jodeleeuw]

Rebuilds reference-game-hawkins.html on the current jspsych-multiplayer API (#103 rejoin, #105 session IDs and shared randomness, #106 group formation). It replaces #1, #19, #24 and #25, which were written against the older API.

What changed

• Pairing. On JATOS, waitForGroup() is the waiting room. The batch's Max active members must be 2, and the adapter seals each pair, so a third arrival starts a new group instead of ending one that has formed. Locally, two tabs share one ?mp_session= link.
• Dyad ID and schedule. The dyad ID is jsPsych.multiplayer.sessionId. The 36-round schedule comes from jsPsych.multiplayer.shuffle, so both partners get the same order and each dyad gets its own.
• Dropouts. A partner leaving is detected by presence (ended_by: "participant_left"). For timed-out rounds, both partners attribute the idle rounds to the same role, and both exit.
• Reloads. A reloaded page (previousInstance) gets its own paid exit.
• Exits. One terminal screen routes every ending (Hawkins.exitFor). Completion codes: complete, partner_dropped, no_match, inactive, reloaded. All are still blank in CONFIG.
• Saving. On JATOS, the full data is submitted as result data, and the study ends with endStudyAndRedirect when the participant clicks submit. DataPipe is optional.
• Dependencies. Everything loads from vendor/, which npm run vendor fills at pinned versions: jspsych-multiplayer 0128c44 and jsPsych preview 5cb6b05. vendor/ stays gitignored.

Review findings fixed from the old PRs

• Prolific IDs are read from jatos.urlQueryParameters on JATOS.
• The final save waits for saves still in flight and always sends a chunk carrying the outcome, so it no longer reports "saved" too early.
• No retry sleep after the last attempt, and Retry-After is capped.
• The .jzip end record is correct; the archive passes unzip -t.
• Tangrams use the original's exact draw boxes (width and aspect ratio).
• The matcher's feedback highlight is green.

Testing

• npm test: 33 tests, all passing. They cover the pipeline, schedule, idle attribution, exit routing, the JATOS save target, and the jzip structure.
• A two-tab run in Chrome on the local adapter:
  • The tabs paired with the same schedule and got different roles.
  • The matcher couldn't click until the director had sent a message, and the round scored correct.
  • Tangram J rendered at 50.6% × 83.1% of its cell, the original's size.
  • Reloading the matcher tab showed the reload exit, and the director got the partner-left exit with the outcome recorded.

Not tested: a real JATOS server; the waiting-room timeout and the idle exit in a browser (both are covered by unit tests only).

Still open

• Completion codes and the DataPipe ID are unset.
• reference-game-cwg.html is still on the old API.
• READINESS.md predates the upstream changes.

🤖 Generated with Claude Code