feat: add plugin-multiplayer-match

[Mandyx22]

Summary

Adds a new package, @jspsych-multiplayer/plugin-multiplayer-match — partition a multiplayer group into matched sub-groups (pairs by default, or triads/larger) by deterministic consensus: every client independently computes the same partition from the shared group-session snapshot, with no coordinator and no extra round-trip.

It is the foundational primitive under pairwise / small-group paradigms — trust game, ultimatum, dyadic negotiation, partner coordination — and composes with the other primitives: pair up with match, assign a role within each pair via plugin-multiplayer-role (drive it off position), then play a round with plugin-multiplayer-choice.

Design

Mirrors plugin-multiplayer-role: a short barrier (push joinedAt/data → communicate wait → partition the resolved snapshot → publish store → save data), headless apart from a waiting message.

• Pure core (match-core.ts, own spec): buildMatches(snapshot, opts) orders participants (from a stable id sort) and chunks them into groups of group_size. Reuses byId/hashSeed/mulberry32 from role's core so the partition is byte-identical on every client.
• Strategies: ordered (by id), join_order (by joinedAt), random (seeded Fisher–Yates; seed defaults to a hash of the sorted ids + round, so pairings are unpredictable-by-id yet identical across clients, and re-pair each round).
• Leftover policy for non-divisible counts: error (default — fail loud), spectator (leave extras unmatched), smaller_group (one undersized group). Unknown strategy/leftover values throw rather than silently falling back.
• Fail-loud timeout (matched_self: false, timed_out: true); a config error (e.g. non-divisible with error) rejects the trial rather than being relabeled a timeout.
• Store for downstream trials: getMyPartners / getMyGroup / getMyPosition / getMatchMap, plus buildMatches — all static members.

Parameters / data

group_size (default 2), expected_players, strategy, seed, round, leftover, ready, push_data, save_group, timeout, on_timeout, message. Data: match_group, partners, members, position, match_map, matched_self, timed_out, group.

Testing

• New package: 29 tests (16 pure-core: pairing/triads/join_order/random-determinism/leftover-policies/enum-validation/edges; 13 plugin: barrier, partition, spectator, config-error-vs-timeout, timeout, join_order readiness, slot-key preservation, save_group, startTimeline smoke test).
• tsc + rollup build clean; repo-root npm run build exit 0; repo-wide npm test 301 passing / 13 suites; prettier clean.
• Changeset (minor) included.

🤖 Generated with Claude Code

[htsukamoto5]

Pushed a fix for compatibility with the latest jsPsych#3694: communicate() was removed from the multiplayer API (commit 78f6c84), and this plugin still called api.communicate(payload, isReady, timeout), so the trial would break against a current core build.

Changes (commit on this branch):

• Replaced the communicate() call with push().then(() => wait()).
• The rejection handler now name-checks the error: only a genuine MultiplayerTimeoutError routes to the graceful timeout path (timed_out: true + on_timeout); any other rejection (e.g. a backend/push failure) rethrows so the trial halts loudly instead of masquerading as a timeout. Matching on error.name (not instanceof) survives two loaded copies of jspsych.
• Dropped the now-removed communicate from the local MultiplayerApiLike mirror and the test mock, and set the mock's timeout rejection to name = "MultiplayerTimeoutError" so it mirrors the real API.
• Added a regression test that a non-timeout rejection (push failure) propagates rather than being masked as a timeout.

tsc clean, 30/30 tests pass, build clean, patch changeset added. Same approach we used for plugin-multiplayer-role in #45.

[jodeleeuw]

Pushed 12a344d: merged main (which now includes plugin-multiplayer-choice, resolving this PR's ordering dependency for match-room.html) and regenerated package-lock.json from a clean npm install — the previous lock diff had stripped resolved/integrity hashes from 808 entries and carried a stray extraneous entry for the then-unmerged choice package; the diff vs. main is now just the 17-line match workspace entry. Verified match-room.html against the updated choice plugin (it only uses unchanged surface: data_key/player_label/payoff/reveal/choices_by_player/my_payoff); full repo build + 405 tests pass, CI green.

[github-actions]

📦 New package — trusted-publishing bootstrap needed

This PR added one or more new packages. npm trusted publishing (OIDC) can't be configured for a package that doesn't exist yet, so a maintainer must do a one-time bootstrap per new package. After that, releases publish automatically via OIDC (publish.yml).

Before running the commands below: npm >=11.15.0 (npm install -g npm@latest) — required for npm trust; older versions fail the trust step with HTTP 400. Also 2FA enabled, logged in (npm login), with publish access to the @jspsych-multiplayer scope.

@jspsych-multiplayer/plugin-multiplayer-match

From a fresh checkout of main:

npm ci && npm run build
npm publish -w @jspsych-multiplayer/plugin-multiplayer-match --access public
npm trust github @jspsych-multiplayer/plugin-multiplayer-match --repo jspsych/jspsych-multiplayer --file publish.yml --allow-publish

Once bootstrapped, bump the version and merge to main — publish.yml publishes future versions tokenlessly via OIDC, with provenance.