Richer session mix + instant next round

[javaisbetterthanpython]

Summary

Upstream: pickleball-shuffler#4

Players keep partnering and opposing the same people over a 7–9 round session (typical 2-hour event) instead of getting a rich mix. This issue improves session-wide variety and makes New round feel instant via background pre-generation.

Problem

• Typical sessions: ~7–9 rounds; scale target 8 players / 2 courts up to 28 players / 6 courts (must scale beyond).
• Users want no repeat partners or opponents more than once in a session when mathematically possible.
• Partner and opponent variety are equally important.

Rules

Session-wide no-repeat (when possible)

• No player partners the same person more than once per session.
• No player opposes the same person more than once per session.
• Fixed pairs exempt from the partner repeat rule (they always partner).
• Fixed-pair players still follow the no repeat opponents rule with everyone else, as much as possible given fixed-pair count.
• Never block round generation — always produce a valid round.

Graceful degradation (when impossible)

• Treat partner and opponent repeats equally — pick whichever hurts the session least.
• Scoring: heavily penalize 3rd+ repeats, then minimize total repeat pairings.
• Show a small note on the round when repeats are unavoidable (e.g. odd headcount, fixed pairs, late joiners).

Background pre-generation

• Pre-compute round N+1 as soon as round N is displayed.
• New round / Re-jumble should feel instant (<1s perceived) by using pre-computed results.
• Invalidation:
  • Reuse pre-gen only on player rename (no roster change).
  • All other changes discard pre-gen and restart immediately in background — including while a dialog is still open (e.g. add player before closing Players modal).
• Changes that force restart: add/remove player, court count change, fixed pair change, volunteer sit-outs, mark inactive, enable groups, etc.

Acceptance criteria

• Algorithm enforces no-repeat partner/opponent when mathematically possible for 8–28 player sessions
• Fixed-pair partner exemption and opponent rules implemented
• Degradation scoring: penalize 3rd+ repeats, then minimize total repeats
• Round always generates (never hangs or blocks)
• Background pre-gen starts when current round is shown
• New round uses pre-computed result when valid
• Invalidation: rename reuses; all other edits discard and restart pre-gen immediately
• Unavoidable-repeat note shown on affected rounds
• Automated tests for no-repeat property across seeds (8–28 players, varied courts)
• yarn test:ci and yarn build pass

Files likely touched

• src/matching/heuristics.ts
• src/matching/worker.ts
• src/useShuffler.tsx
• pages/rounds.tsx
• test/heuristics.spec.tsx

Dependencies

none

Upstream reference

• Improve generation look-ahead panathea/pickleball-shuffler#4

[javaisbetterthanpython]

Manual testing surfaced a hang when starting later rounds: background pre-gen and user-initiated generation were posting to the Web Worker concurrently, so message listeners could miss responses and generating stayed true.

Fix pushed to PR #40 (14cc0e2): serialize worker requests on main thread + queue jobs inside the worker; instant path no longer flashes "Jumbling…" when pre-gen cache hits.

Remaining before close:

• Re-verify in browser after the fix
• One flaky/failing degradation test (degradation avoids third-plus session pairings when possible) was already failing on the branch — needs a look
• Full test:ci + merge

Pausing here to finish #31 first; will pick this back up after.