Skip to content

Stats sharing implementation handoff

Document type: Completed branch implementation and verification record, not an active roadmap.

Audience: Engineers reviewing, merging, deploying, or maintaining stats-sharing behavior.

Status date: 2026-09-12

Working branch: feat/stats-sharing-2

Scope of this document: Implementation complete on the branch; not yet merged to main or deployed. The branch contains both backend persistent storage/APIs and a frontend client with real settings/group exceptions consumed from the server. Frontend preview steps 3–6 were superseded by the backend implementation and are marked obsolete below. The final frontend hookup section documents the completed integration. Automated desktop/mobile browser integration is complete; target-environment deployment and manual assistive-technology verification remain pending.

This status is a dated branch record. Check the platform roadmap and deployed revision before inferring current merge or production state.

This document serves as the implementation record and is sufficient for understanding the completed work and acceptance criteria. Read AGENTS.md, the applicable files in .github/instructions/, and the neighboring tests before editing. Preserve unrelated work and do not edit generated output.

Product decisions that are settled

  1. Groups are a private comparison context, not a social network. Do not add public profiles, following, people search, feeds, comments, direct messages, or arbitrary sharing outside a group.
  2. Game selection remains a dropdown. Six or more games are expected, so game tabs do not scale.
  3. Today’s group status, the completed final score/time, and the current Daily streak remain group-visible. A positive streak includes the visible 🔥 treatment in standings. Zero is a neutral state on detail pages.
  4. Detailed lifetime scorecards are controlled at the game level, not stat by stat. Detailed sharing is enabled by default and can be opted out of per game.
  5. Letter Golf detailed sharing includes the longest-word highlight and its length when the word is known. There is no separate “share the length but hide the word” control in this version. A missing word in legacy data may still show the known length.
  6. A group-level exception applies to all detailed game scorecards for that group and has exactly three modes:
  7. Use my defaults
  8. Share all scorecards
  9. Current streak only
  10. Individual play history, complete submitted-word lists, puzzle answers, partial progress, and solutions are never part of detailed scorecard sharing.
  11. The player’s profile is never public. Shared details are only reachable through /groups/[groupId]/members/[userId], after group-membership authorization.
  12. Stats-sharing controls persist through the authenticated settings API. The server remains authoritative and returns the complete effective state after each sparse update.
  13. Member scorecards use only the authorized, privacy-filtered group projection. Fixtures and preview notices are no longer part of the implementation.

This decision set supersedes older roadmap wording that calls broader scorecard sharing “opt-in” or leaves opt-in versus opt-out unresolved.

Implementation summary by phase

Backend implementation (persistent storage + authorized APIs)

Commits implementing persistent player settings, authenticated member scorecard projection, and account lifecycle integration:

  • c6b336b — Persistent player settings model for stats-sharing preferences under PlayerEntity.Settings
  • 403096f — Settings PATCH/GET endpoints with sparse update, complete-state response, and optimistic concurrency
  • c4ec0a4 — Account lifecycle (merge, delete, export) preserves settings correctly
  • 95ad28e — Authorized GroupMemberSharedStatsService scorecard projection with per-game and per-group visibility enforcement
  • 9108a10 — GET /v1/groups/{groupId}/members/{userId}/scorecard endpoint with privacy filtering and allow-listed response contracts

Frontend implementation (settings client + rendered member details + settings page + navigation + Phase 5 discovery)

Commits implementing real settings fetch/mutation, server-backed member detail rendering, persistent /settings/stats-sharing route, and Phase 5 group Today discovery notice:

  • 5defce1 — Typed client for the authorized member scorecard endpoint
  • ec80bea — Member detail page renders server-projected scorecard with per-game and per-group visibility applied
  • 4072b43 — Shared member scorecard page wired to the server-loaded projection
  • 087b7dbc — Typed, runtime-validated stats-sharing settings GET/PATCH client
  • a683d9e7 — Personalized group-list fetches explicitly disable caching
  • 2ef0c19e — Persistent settings route and per-control optimistic PATCH form
  • 2363e2bf — Main Settings links to the stats-sharing route
  • 08778acc — Standalone hydration-safe Stats Sharing discovery notice with focused localStorage/accessibility tests
  • b8125af8 — Render notice above GamePicker on authorized group Today pages with focused server-page composition/boundary tests
  • f1ac1382 — Privacy disclosure/effective date and newest-first player update article with focused tests
  • 576e211 — Reusable, versioned contextual announcement component with the Stats Sharing notice as a feature-owned wrapper
  • e3e1b48 — Stateful Playwright API harness and complete Stats Sharing browser journey on desktop and mobile
  • 6be957f — Signed-cookie viewer identity resolution and deterministic group-navigation regression coverage

Previous frontend-preview work (steps 3–6 now superseded)

Earlier commits that implemented sample-data placeholders have been superseded by real server integration. The branch currently contains these commits from that phase:

  • 52688cf — Canonical scorecard presentation (scorecard-primitives.tsx, stats components)
  • f3bdb1f — Group navigation foundation (Today/Members routing, flame treatment for streaks)
  • 46244aa — Frontend polish and accessibility foundation

What steps 1 and 2 implemented (previous frontend-preview work, now superseded)

The following describes the sample-data / frontend-preview foundation that was later superseded by backend integration. Steps 3–6 below are no longer the current implementation path; refer to the "Implementation summary by phase" section above for what actually shipped.

Earlier preview commits:

  • 52688cf — Polish personal scorecard stats layout
  • f3bdb1f — Polish group stats navigation
  • 46244aa — Refine stats sharing frontend polish

Step 1: canonical scorecard presentation

  • frontend/minigames/src/app/components/scorecard-primitives.tsx now owns the shared streak card, metric grid, and quiet Daily status treatment.
  • letter-golf-stats.tsx uses those primitives. “Longest word” now treats the word as the primary value and the length as supporting detail; legacy length-only and empty states are safe.
  • reverse-cross-stats.tsx now starts with the same current/best streak card, uses natural-height metric cards, and replaces the green completion banner with quiet inline completion copy.
  • Reverse Cross retains responsive overall timing and board-size rendering for sizes 5 through 9.
  • Focused component and page tests were added or updated.

Step 2: discovery and navigation foundation

  • Positive streaks in Today standings include 🔥 while retaining readable streak text.
  • Today standings rows already navigate to the group-scoped member detail route and preserve ?game=.
  • Names in the Members roster now do the same and have a mobile-sized hit target; owner actions remain separate controls.
  • The Members navigation item remains current on nested member detail routes. Today remains an exact route match.

At the end of the historical step 2, the backend supplied only sharedStats.currentDailyStreakDays; the member detail page intentionally did not have another member's lifetime statistics.

Current frontend architecture to preserve

  • Group shell and headings: frontend/minigames/src/app/groups/[groupId]/layout.tsx
  • Today page: frontend/minigames/src/app/groups/[groupId]/page.tsx
  • Dropdown: frontend/minigames/src/app/groups/[groupId]/game-picker.tsx
  • Member detail: frontend/minigames/src/app/groups/[groupId]/members/[userId]/page.tsx
  • Group navigation helpers: frontend/minigames/src/app/groups/group-game.ts
  • Current group API types: frontend/minigames/src/lib/groups.ts
  • Settings shell: frontend/minigames/src/app/settings/page.tsx and settings-form.tsx
  • Existing notification component: frontend/minigames/src/app/components/toast.tsx
  • Canonical game scorecards: letter-golf-stats.tsx and reverse-cross-stats.tsx

Keep pages as Server Components unless browser state or event handlers are required. Keep switches, selects, pending state, and toast state in a small client component rather than converting an entire route to a Client Component.

Step 3 — Build the rich group-member detail presentation (completed)

Outcome (Completed)

/groups/[groupId]/members/[userId]?game=lettergolf and the equivalent Reverse Cross URL render the authorized shared-scorecard layout for the requested member within the group context. The backend scorecard endpoint returns only allow-listed fields for the requested game and enforces per-game and per-group visibility rules. Real server-backed data replaced the frontend preview approach.

Completion: The member detail page now fetches the actual scorecard from the dedicated API, renders per-game visibility decisions (shared, current streak only, or not shared), and displays only fields the server explicitly returned. No frontend preview remains.

The remaining Step 3 instructions below are retained as historical design context only. Do not reintroduce their sample-data or preview behavior.

Page order

Use the existing group shell; do not duplicate the site header or group heading inside the page.

  1. Back to standings, preserving the selected game.
  2. Member display name as the page’s h2; append (you) for the viewer.
  3. Supporting copy: Detailed scorecard preview for {group name} during the frontend-only phase. After backend hookup this becomes Overall stats shared with {group name}.
  4. The same game dropdown used on Today. It must operate on the current member-detail pathname and preserve the member and group IDs.
  5. Today card: Today · Global Daily plus Completed · Score 3, Completed · Time 1:30, Playing, or Not played, using the existing standings formatters.
  6. A visible preview notice immediately before sample statistics: Frontend preview — the detailed statistics below are sample values and are not supplied by the server yet.
  7. The selected game’s scorecard, using the existing canonical components and headingLevel="h3".
  8. A quiet scope note after the scorecard:
  9. Letter Golf: Individual puzzle history and complete submitted-word lists are not shared.
  10. Reverse Cross: Individual puzzle history and puzzle answers are not shared.

Presentation requirements

Letter Golf order:

  1. current/best Daily streak card;
  2. All-time Play metrics;
  3. Score Distribution.

Reverse Cross order:

  1. current/best Daily streak card;
  2. Play metrics;
  3. Overall timing;
  4. Timing by board size, supporting 5 × 5 through 9 × 9 without horizontal overflow on a phone.

Do not add game tabs. Reuse GamePicker, passing group.dailyGames, so future supported games can be added to one game registry. As part of this step, move the hard-coded game label list out of GamePicker into a small shared module such as frontend/minigames/src/app/groups/group-games.ts. That registry should own game type, user-facing label, and personal scorecard route. It must not include non-live games yet.

Component boundary

Add a reusable, presentation-only component, for example:

groups/[groupId]/members/[userId]/shared-member-scorecard.tsx

It should receive an explicit view model rather than fetch data. Keep the page responsible for membership-scoped loading and Today-state assembly.

Recommended preview model:

type SharedScorecardPreview =
  | {
      gameType: "lettergolf";
      stats: PlayerStatsResponse;
      streak: Pick<StreakResponse, "current" | "longest">;
    }
  | {
      gameType: "reversecross";
      stats: PlayerStatsResponse;
      streak: Pick<StreakResponse, "current" | "longest">;
    };

The canonical scorecard components currently accept a full StreakResponse because personal scorecards can describe whether today is complete. Shared scorecards must not invent lastPlayedDate. Refactor the prop boundary so a shared view can provide { current, longest } and suppress the personal Daily-status line. Preserve current personal-page behavior by default. A prop such as showDailyStatus?: boolean, defaulting to true, is acceptable; a small ScorecardStreakSummary type is preferable to fabricating a date.

Put sample data in one plainly temporary file such as shared-scorecard-preview-data.ts. Do not scatter fixture numbers through the page. Use plausible values for both live games and all Reverse Cross sizes so responsive layout can be reviewed. Include a deletion marker comment naming the future API hookup, but do not add an API call to an endpoint that does not exist.

States to render

  • Selected member exists and has a positive real current streak.
  • Selected member has a visible zero current streak.
  • Selected member has no current streak projection.
  • Today is Completed, Playing, or Not played.
  • Letter Golf preview.
  • Reverse Cross preview.
  • Missing member continues through notFound().
  • Group fetch failure and non-membership continue to use the existing group access boundary; do not create a public fallback.

Focused tests

Extend members/[userId]/page.test.tsx and add a component test only if useful. Cover both games, dropdown/back-link query preservation, Today copy, preview disclosure, hidden/missing current streak, and the fact that sample data is labelled. Do not duplicate all scorecard component tests.

Step 4 — Add the frontend-only Stats Sharing settings page (superseded)

This section records the discarded preview plan. The implemented persistent route is described in "Frontend integration of completed backend APIs" below. Do not implement the dummy behavior.

Route and entry point

Create:

/settings/stats-sharing

Suggested files:

frontend/minigames/src/app/settings/stats-sharing/page.tsx
frontend/minigames/src/app/settings/stats-sharing/stats-sharing-preview-form.tsx
frontend/minigames/src/app/settings/stats-sharing/page.test.tsx
frontend/minigames/src/app/settings/stats-sharing/stats-sharing-preview-form.test.tsx

The existing /settings layout already supplies non-indexable metadata. Use SiteHeader, the same narrow 600-pixel shell, and a BackLink to /settings. Add a distinct Stats sharing section to the main Settings form, preferably after Profile and before cookie Privacy, with concise copy and a Manage stats sharing link/button. Do not put a new top-level hamburger item beside Settings.

Exact page structure and copy

  • h1: Stats Sharing
  • Intro: Choose which detailed game scorecards members of your groups can see. Your profile is never public.
  • Persistent preview notice: Frontend preview — these controls show dummy defaults. Changes are not saved and do not affect what group members can see.
  • Always-visible explanation: Always visible in your groups: today’s Completed, Playing, or Not played state; your final score or time after completion; and your current Daily streak.
  • Section heading: Detailed game scorecards
  • One switch per live scorecard game:
  • Letter Golf — Shares averages, bests, streak record, score distribution, achievement counts, and longest-word highlights.
  • Reverse Cross — Shares completion, streak record, overall timing, and timing by board size.
  • Footer note: New games appear here when their scorecards become available. Detailed sharing is on by default.
  • Collapsible native details/summary: Group exceptions
  • One select per real group membership with Use my defaults, Share all scorecards, and Current streak only.

Fetch the real group list with the existing fetchMyGroups server helper so group names are not hard-coded. The settings values remain dummy. If the player has no groups, show neutral text explaining that group exceptions appear after joining a group; do not render fake groups.

Dummy behavior

Initial state on every load:

{
  games: { lettergolf: true, reversecross: true },
  groupOverrides: {}
}

The form is interactive in memory only. A reload resets it. Do not call updatePlayerSettings, add new methods to lib/players.ts, write cookies/local storage, or imply persistence.

Use a native checkbox for each boolean and style it as a switch, or use an already installed accessible primitive. Do not add a UI dependency solely for a switch. Each control needs a visible label and a programmatic name. Each group select should use the group name in its accessible label.

On every preview control change, show the existing Toast at viewport-bottom with exactly:

Preview only — no settings were saved.

Do not use Settings saved, a green success treatment, or a fake loading state.

Focused tests

Cover default-on state, local toggle/select behavior, reset-on-remount, preview toast text, group names from props, the no-groups state, and the absence of any settings API call. Use role/name queries so the tests enforce accessible controls.

Step 5 — Discovery prompts and navigation

Group Today notice (completed)

The group Today notice has been implemented on this branch with the following exact contract:

  • title: New: shared game scorecards
  • body: Members of your groups can see the detailed scorecards you choose to share.
  • action: Review stats sharing, linking to /settings/stats-sharing
  • dismissal: Persisted in local storage using versioned key feature-announcement:stats-sharing-scorecards:v1:dismissed (presentation state only, not a sharing preference)
  • icon dismiss accessible name: Dismiss shared game scorecards notice
  • control height: 44px
  • placement: Appears only above GamePicker on authorized group Today pages
  • exclusions: Not rendered on gameplay screens, victory overlays, group rows, global header
  • resilience: Storage read/write failures remain usable (notice re-appears on next session if storage fails)

Completed in three focused commits (see implementation summary above): standalone notice hydration safety and localStorage/accessibility tests (08778acc); notice rendering above GamePicker on authorized Today pages with server-page composition/boundary tests (b8125af8); and integration with privacy/update messaging and player article archive (f1ac1382).

Reusing contextual announcements

frontend/minigames/src/app/components/dismissible-announcement.tsx owns the shared presentation, hydration-safe dismissal, storage-failure behavior, and versioned key format. Feature-specific wrappers provide an announcementId, numeric version, copy, accessible dismiss label, and optional action. Render each wrapper on the page nearest to the announced feature; no global registry or layout integration is required. Incrementing version gives the announcement a new storage key and shows the revised message again.

Discovery messaging completion (Phase 5)

The following discovery and privacy disclosure implementation is now complete:

  • Privacy disclosure: Updated /privacy page accurately describes player-owned per-game default settings and per-group override persistence, server-enforced authorization, private-group membership as authorization boundary, current Daily streak and Today standings as group-visible, and exclusions of public profile/history/submitted words/answers/partial progress.
  • Player update article: Added to /updates archive (newest-first ordering) with effective dates and current privacy/sharing state reflected accurately.
  • Settings page: Persistent, fully functional, persists real settings via PATCH. On success, toast shows Stats sharing updated. On failure, it shows Could not update stats sharing. Try again.

Implemented navigation contract

  • Standings row → /groups/{groupId}/members/{userId}?game={selectedGame}
  • Members row → the same detail URL
  • Detail dropdown change → same group/member pathname with a different game
  • Detail Back to standings → /groups/{groupId}?game={selectedGame}
  • Main Settings → /settings/stats-sharing
  • Stats Sharing Back to settings → /settings

All game query construction should use the existing helpers rather than hand-built variants. Do not add a public member/profile link.

Notice and messaging tests (completed)

Focused validation completed for Phase 5 discovery and messaging:

  • Announcement and notice tests (2 files, 7 tests): Generated/versioned keys, version-bump redisplay, initial visibility, exact copy and settings link, optional actions, dismissal persistence, localStorage read/write failures, and accessible semantics.
  • Page composition tests (1 file, 4 tests): Successful placement above GamePicker, preserved group-fetch arguments, missing-cookie behavior, and fetch-failure behavior.
  • Privacy + update tests (2 files, 15 tests): Privacy disclosure and link accuracy, update article metadata and ordering, sharing-control descriptions, server enforcement, and data exclusions.
  • Coverage: TypeScript type-check, focused ESLint, and git diff --check passed for each affected chunk.
  • Phase 5 checkpoint: 780 frontend tests passed across 84 files with no failures or skips. ESLint, TypeScript, the production Next.js build, and git diff --check passed.

Step 6 — Integration polish, accessibility, tests, and documentation

Responsive and accessible implementation

The implementation is designed for the current narrow mobile and 600-pixel desktop content widths. Playwright on Desktop Chrome and Pixel 7 verifies keyboard operation for the primary journey, 44px notice controls, both game renderings, and no document-level horizontal overflow. Component tests cover semantic headings, native controls, focus behavior, and toast/announcement live regions.

The following checks still require manual review before rollout:

  • Screen-reader output, focus order, and status announcements across the full journey.
  • Light, dark, and forced-colors presentation, including visible focus and non-color privacy cues.
  • Reflow at 200% zoom, long-word wrapping, and the Reverse Cross 5×5 through 9×9 size view.
  • The complete journey in the non-production target environment.

Test coverage

Tests cover Phase 4 through Phase 6:

  • Both canonical scorecard components (Letter Golf and Reverse Cross).
  • Member detail page for both games, all visibility states (shared/currentStreakOnly/hidden), Today projections, and current streak rendering.
  • GamePicker on group Today and within member detail; query parameter preservation.
  • Standings and Members navigation with flame treatment for positive streaks.
  • Stats Sharing settings page: fetch, per-control PATCH mutations, success/failure toasts, per-control submit prevention, group-override selects.
  • Settings entry point and backlink navigation.
  • Phase 5 discovery: Group Today notice placement above GamePicker, dismissal and localStorage persistence, settings link, and storage-failure resilience.
  • Phase 5 privacy/messaging: Privacy disclosure accuracy, update article contents, effective dates, per-game/per-group sharing documentation.
  • Phase 6 browser integration: Notice placement and dismissal persistence, keyboard navigation, per-game settings persistence through reload, group-override precedence, viewer/target privacy ownership, both game scorecards, no horizontal overflow, and client-error monitoring on Desktop Chrome and Pixel 7.
  • Authorization boundaries: non-members cannot access group or member-scorecard endpoints (backend contracts tested separately).

Focused validation on 2026-09-12 completed: announcement and notice implementation 2 files/7 tests, page composition 1 file/4 tests, privacy + update messaging 2 files/15 tests, and the Stats Sharing Playwright journey in both configured projects. Final local validation passed 784 frontend tests across 84 files, ESLint, TypeScript, the production Next.js build, git diff --check, and the full Playwright matrix with 51 passed and 1 skipped. Manual screen-reader, focus/status-announcement, light/dark/forced-colors, 200% zoom, long-word, and Reverse Cross 5×5–9×9 reflow checks, plus non-production deployment verification, remain separate rollout checks. Phase 6 automated integration is complete on the branch; the branch is not merged or deployed.

Run from the repository root:

npm run lint --prefix .\frontend\minigames
npx --prefix .\frontend\minigames tsc --noEmit
npm run test --prefix .\frontend\minigames
npm run build --prefix .\frontend\minigames

No separate formatter script exists in frontend/minigames/package.json. git diff --check confirms whitespace compliance.

Documentation updates (2026-09-12)

  • doc/group-member-social-ui-plan.md: Updated to mark Stats Sharing complete and link to this handoff.
  • doc/roadmap.md: Updated to include Phase 5 discovery messaging and notice implementation (notice above GamePicker, privacy disclosure, update articles).
  • doc/engagement-platform-plan.md: Updated to reference backend implementation on this branch.
  • This document: Recorded Phase 6 browser integration, final local validation, and the deploy-without-a-feature-flag decision.
  • Privacy and release copy: Updated /privacy page with accurate disclosure of player-controlled settings, server authorization, and data exclusions. Added /updates article with effective date and current messaging. Feature is not marketed as live until after merge and production deployment.

Frontend acceptance checklist (Phases 4–6 complete locally)

Phase 4 features (completed)

  • The game selector is a dropdown everywhere and works on nested member pages.
  • Both live games render real shared-detail scorecards from the server with privacy enforcement.
  • Real Today state and real current streak are rendered from the server projection.
  • The Stats Sharing page fetches real settings and group list, initializes form state, and persists PATCH mutations.
  • Per-game default-on and per-group inheritance/override behavior match the backend contracts.
  • Settings changes are persisted to the server via PATCH.
  • Success and failure toasts show accurate copy.
  • Main Settings links to the Stats Sharing page.
  • No public profile, history, word-list, answer, or partial-progress surface was added.
  • Member detail rendering respects per-game visibility decisions and handles currentStreakOnly correctly.
  • Focused tests, full frontend tests, lint, TypeScript, build, and git diff --check pass for the final branch state.
  • Authorization boundaries verified: non-members cannot access group or member scorecard views/endpoints.

Phase 5 discovery and messaging (completed)

  • Notice appears above GamePicker on authorized group Today pages with exact title/body/action/dismiss contract.
  • Notice persists dismissal in versioned localStorage key; storage failures remain usable.
  • Notice has 44px accessible dismiss control; never appears on gameplay/overlays/group rows/header.
  • /privacy page accurately discloses player-controlled per-game defaults, per-group overrides, server authorization, and data exclusions.
  • /updates archive includes effective-dated article with current messaging; ordering is newest-first.
  • Notice links correctly to /settings/stats-sharing.
  • Focused validation: notice 7 tests, page composition 4 tests, privacy/messaging 15 tests (26 total); TypeScript/ESLint/git diff --check passing.

Phase 6 integration and closeout (completed locally)

  • Phase 6 Playwright journey passes on Desktop Chrome and Pixel 7, including keyboard use and responsive overflow checks.
  • Full validation: 784 tests across 84 files, ESLint, TypeScript, production build, full Playwright matrix (51 passed, 1 skipped), and git diff --check pass.
  • Manual screen-reader, focus/status-announcement, light/dark/forced-colors, 200%-zoom, long-word, and Reverse Cross 5×5–9×9 reflow verification pending.
  • Non-production deployment verification pending.

Backend implementation (COMPLETED)

This section documents the backend work that has been completed on the feat/stats-sharing-2 branch. All backend subsystems are implemented, tested, and ready for integration deployment.

Backend data model

Persist stats-sharing preferences under PlayerEntity.Settings, not on every group member record. This keeps the player authoritative for their own privacy choices and avoids dual-writing the same preference into every group.

Recommended additive storage shape:

{
  "settings": {
    "statsSharing": {
      "detailedScorecardsByGame": {
        "lettergolf": false
      },
      "groupOverrides": {
        "group-id": "currentStreakOnly"
      }
    }
  }
}

Semantics:

  • A missing game key means true, matching the approved default-on/opt-out policy and allowing new live scorecard games to appear without migrating every player document.
  • A missing group key means inherit.
  • Persist only exceptions when practical: false game defaults and non-inherit group overrides.
  • Allowed group modes are shareAll and currentStreakOnly; inherit in an update removes the stored override.
  • Cap overrides at Consts.MaxGroupsPerUser and reject unsupported game names or invalid modes.
  • Ignore stale overrides for groups the player no longer belongs to. Prefer removing the matching override during leave/removal cleanup so it cannot unexpectedly return after rejoining.
  • Account export must include these preferences, and account deletion already removes them with the player document.
  • Account merge must be privacy-conservative: false game defaults win over true, and currentStreakOnly wins over a less restrictive group mode for the same group. Add explicit merge tests.

Add storage, response, request, mapping, validation, updater, export, deletion/merge, and compatibility tests. Old documents with no statsSharing property must deserialize safely and behave as default-on.

Settings API

Prefer a dedicated contract rather than crowding the existing simple settings form:

GET   /v1/players/me/stats-sharing
PATCH /v1/players/me/stats-sharing

Recommended response:

{
  "detailedScorecardsByGame": {
    "lettergolf": true,
    "reversecross": true
  },
  "groupOverrides": {
    "group-id": "currentStreakOnly"
  }
}

Recommended partial request:

{
  "detailedScorecardsByGame": {
    "lettergolf": false
  },
  "groupOverrides": {
    "group-id": "inherit"
  }
}

Patch only supplied entries and leave unknown/future game entries untouched. Return the complete effective settings after the update. Reuse the current PlayerSettingsUpdater optimistic-concurrency pattern or extract a narrowly shared ETag retry helper; do not duplicate unbounded retry logic.

Expected errors:

  • 400 for unsupported game types, invalid modes, excessive overrides, malformed IDs, or a group override outside the caller’s current memberships;
  • 409 after bounded optimistic-concurrency retries are exhausted;
  • normal authenticated-cookie identity behavior consistent with other /players/me endpoints.

Dedicated member scorecard API

Do not add every member’s full scorecard to GET /v1/groups/{groupId}. That response supports standings for up to 50 members and should remain bounded. Keep its existing batch projection limited to current streaks.

Add a point-read detail endpoint:

GET /v1/groups/{groupId}/members/{memberUserId}/scorecard?game=lettergolf

Authorization order:

  1. Resolve the caller from the signed HTTP-only cookie.
  2. Read the group and verify the caller is a member.
  3. Verify the target is still a member of that group.
  4. Only then read the target player and project allowed fields.

Never accept a caller-supplied user ID as authorization. Never fall back to a public player endpoint. Apply the target player’s game default and the selected group override on the server; frontend hiding is not a privacy boundary.

Recommended response envelope:

interface GroupMemberScorecardResponse {
  groupId: string;
  groupName: string;
  puzzleLanguage: string;
  member: { userId: string; displayName: string };
  gameType: "lettergolf" | "reversecross";
  today: {
    status: "NotPlayed" | "Playing" | "Completed";
    result: GroupStandingsResultResponse | null;
  };
  currentDailyStreakDays: number;
  detailVisibility: "shared" | "currentStreakOnly";
  scorecard: LetterGolfSharedScorecard | ReverseCrossSharedScorecard | null;
}

Use a discriminated, allow-listed scorecard contract. Do not serialize PlayerEntity, the generic stats dictionaries, or PlayerResponse directly; a future private counter must not become shared merely because it was added to a dictionary.

Letter Golf projection:

interface LetterGolfSharedScorecard {
  gameType: "lettergolf";
  streak: { current: number; longest: number };
  gamesPlayed: number;
  averageScore: number | null;
  bestScore: number | null;
  longestWord: { length: number; word: string | null } | null;
  holeInOnes: number;
  strictHoleInOnes: number;
  scoreHistogram: Record<"1" | "2" | "3" | "4+", number>;
}

When detailed Letter Golf sharing is enabled, return the longest word when known. A null word with a known length is a legacy/missing-data state, not a per-stat privacy setting.

Reverse Cross projection:

interface ReverseCrossSharedScorecard {
  gameType: "reversecross";
  streak: { current: number; longest: number };
  gamesStarted: number;
  gamesCompleted: number;
  completionRate: number;
  bestDurationMilliseconds: number | null;
  typicalDurationMilliseconds: number | null;
  timingByBoardSize: Array<{
    size: 5 | 6 | 7 | 8 | 9;
    gamesCompleted: number;
    bestDurationMilliseconds: number | null;
    typicalDurationMilliseconds: number | null;
  }>;
}

Compute averages, rates, “typical” eligibility, active current streak, and allowed fields on the server or in a server-owned projection service. Keep durations within JavaScript’s safe-integer range. Return an empty/shared scorecard state distinctly from currentStreakOnly: a player can permit sharing but have no completed games yet.

Backend service and performance boundary

  • Keep GroupMemberSharedStatsService as the policy boundary or rename it to reflect both standings summaries and detailed projections.
  • The standings request may retain one bounded GetManyAsync for current streaks across at most 50 members.
  • The member scorecard endpoint should perform one group point read, the existing selected-event lookup/backfill as needed, and one target-player point read. No N+1 member reads.
  • Group override evaluation must be centralized and unit tested; do not duplicate visibility logic in endpoint mapping.
  • Do not log word highlights, scorecard payloads, cookie values, or user IDs at high-cardinality telemetry dimensions.
  • Keep cancellation and existing bounded retry behavior end to end.

Backend tests and contract work

At minimum cover:

  • default-on behavior for an old player document;
  • per-game opt-out;
  • shareAll and currentStreakOnly group overrides taking precedence;
  • no cross-game leakage;
  • longest word included only in an allowed Letter Golf detail projection;
  • no history, word list, answers, generic private counters, or dates in the response;
  • caller not in group;
  • target not in group;
  • target missing;
  • supported/unsupported game validation;
  • zero/no-stats versus hidden detail states;
  • ETag retry and exhausted conflict for settings;
  • conservative account-merge behavior;
  • export includes the preference;
  • group standings payload remains bounded and does not gain detailed scorecards.

Regenerate or update the OpenAPI contract through the repository’s established workflow and update frontend contract tests. Do not hand-edit generated output.

Frontend integration of completed backend APIs (completed)

1. Add typed API clients (completed)

In frontend/minigames/src/lib/players.ts, add the stats-sharing settings response/request types plus fetchStatsSharingSettings and updateStatsSharingSettings.

In frontend/minigames/src/lib/groups.ts, add the discriminated member-scorecard types and fetchGroupMemberScorecard(groupId, memberUserId, game, cookieHeader?).

Keep game-type narrowing exhaustive. Reject or render a safe unsupported state for an unknown future discriminator rather than treating it as Letter Golf.

2. Replace member preview fixtures (completed)

  • Delete shared-scorecard-preview-data.ts.
  • Fetch the dedicated member scorecard from the Server Component.
  • Remove the sample-data preview notice.
  • Change the context line to Overall stats shared with {group name}.
  • Map the allow-listed API response into the canonical scorecard presentation models.
  • For detailVisibility: "currentStreakOnly", show Today and current streak plus neutral text such as {name} shares only their current Daily streak for {game}.
  • For allowed sharing with no scorecard yet, show {name} does not have a {game} scorecard yet.
  • Treat a fetch failure as recoverable page copy, not as “the player hid their stats.”

Do not use the viewer’s own /players/me response to fill another member’s page, and do not bypass the group projection when the viewed member happens to be the caller. The page should show exactly what that group is authorized to see.

3. Replace dummy settings (completed)

  • Fetch settings and the caller’s real groups on the server.
  • Initialize the client form from the response.
  • On a switch/select change, disable that control while its PATCH is pending.
  • Send only the changed game or group entry.
  • On success, replace local state with the server response and toast Stats sharing updated.
  • On failure, restore the prior value and toast Could not update stats sharing. Try again.
  • Prevent rapid double-submission per control. The server remains authoritative if two browser tabs race.
  • Remove the frontend-preview notice and preview-only toast copy.

Step 5 (Phase 5) — Activate accurate discovery copy and messaging (completed)

Endpoint visibility enforcement and settings persistence are confirmed; discovery messaging has been activated with approved contract:

  • Group notice now displays exact approved New: shared game scorecards title and Members of your groups can see the detailed scorecards you choose to share. body.
  • /privacy page updated with accurate disclosure of player-controlled settings, server authorization, and data exclusions.
  • /updates article archive includes effective-dated entry documenting current sharing/privacy state.
  • Feature remains not-merged/not-deployed; marketing activation deferred to post-merge production rollout.

5. Rollout order

Stats Sharing does not have a feature-specific runtime flag, and this rollout does not add one. Use the additive API boundary and independently deployable backend/frontend artifacts instead:

  1. Deploy the additive storage/contracts and backend endpoints to a non-production environment.
  2. Verify authorization, opt-outs, group overrides, old-document defaults, payload size, and both game projections directly against that backend.
  3. Deploy the frontend, including settings management, detailed member scorecards, accurate privacy/release copy, and the New notice, to the same environment.
  4. Run the browser journey and manual screen-reader, focus/status-announcement, light/dark/forced-colors, 200%-zoom, long-word, and Reverse Cross 5×5–9×9 reflow checks against the deployed environment.
  5. Promote the already-validated artifacts through the normal reviewed release process. If frontend verification fails, roll back the frontend; the unused additive backend contract can remain deployed safely.
  6. Monitor authorization failures, latency, Cosmos request charge, settings conflicts, and frontend fetch errors. Do not include private stat values in telemetry.

The backend must be authoritative before the production UI says scorecards are shared. Frontend switches, hidden DOM, route guards, and preview fixtures are never privacy enforcement.

Final end-to-end acceptance checklist

  • A group member can open another member from Today or Members and retain the selected game.
  • Letter Golf and Reverse Cross render only their explicitly allow-listed shared fields.
  • Per-game default-off hides that game’s detailed scorecard in every inheriting group.
  • Share all scorecards overrides per-game defaults for one group.
  • Current streak only hides all detailed scorecards for one group.
  • Current Daily streak and Today standings remain available under the settled group rules.
  • Longest-word text is shared when Letter Golf details are shared and the legacy data contains it.
  • History, submitted-word lists, answers, partial progress, and arbitrary future counters never leak.
  • Settings survive reload and account/session transitions after backend hookup.
  • Non-members cannot retrieve the group or member scorecard projection.
  • Older clients continue to consume the additive group response safely.
  • Backend tests, frontend tests, lint, TypeScript, and the production frontend build pass.
  • Desktop/mobile Playwright integration covers settings persistence, override precedence, privacy ownership, notice behavior, both games, keyboard navigation, and responsive overflow.
  • Manual screen-reader, focus/status-announcement, light/dark/forced-colors, 200%-zoom, long-word, and Reverse Cross 5×5–9×9 reflow verification is complete.
  • Non-production deployment and target-environment smoke verification are complete.