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¶
- 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.
- Game selection remains a dropdown. Six or more games are expected, so game tabs do not scale.
- 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. - 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.
- 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.
- A group-level exception applies to all detailed game scorecards for that group and has exactly three modes:
Use my defaultsShare all scorecardsCurrent streak only- Individual play history, complete submitted-word lists, puzzle answers, partial progress, and solutions are never part of detailed scorecard sharing.
- The player’s profile is never public. Shared details are only reachable through
/groups/[groupId]/members/[userId], after group-membership authorization. - Stats-sharing controls persist through the authenticated settings API. The server remains authoritative and returns the complete effective state after each sparse update.
- 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.Settings403096f— Settings PATCH/GET endpoints with sparse update, complete-state response, and optimistic concurrencyc4ec0a4— Account lifecycle (merge, delete, export) preserves settings correctly95ad28e— Authorized GroupMemberSharedStatsService scorecard projection with per-game and per-group visibility enforcement9108a10— 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 endpointec80bea— Member detail page renders server-projected scorecard with per-game and per-group visibility applied4072b43— Shared member scorecard page wired to the server-loaded projection087b7dbc— Typed, runtime-validated stats-sharing settings GET/PATCH clienta683d9e7— Personalized group-list fetches explicitly disable caching2ef0c19e— Persistent settings route and per-control optimistic PATCH form2363e2bf— Main Settings links to the stats-sharing route08778acc— Standalone hydration-safe Stats Sharing discovery notice with focused localStorage/accessibility testsb8125af8— Render notice above GamePicker on authorized group Today pages with focused server-page composition/boundary testsf1ac1382— Privacy disclosure/effective date and newest-first player update article with focused tests576e211— Reusable, versioned contextual announcement component with the Stats Sharing notice as a feature-owned wrappere3e1b48— Stateful Playwright API harness and complete Stats Sharing browser journey on desktop and mobile6be957f— 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 layoutf3bdb1f—Polish group stats navigation46244aa—Refine stats sharing frontend polish
Step 1: canonical scorecard presentation¶
frontend/minigames/src/app/components/scorecard-primitives.tsxnow owns the shared streak card, metric grid, and quiet Daily status treatment.letter-golf-stats.tsxuses 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.tsxnow 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.tsxandsettings-form.tsx - Existing notification component:
frontend/minigames/src/app/components/toast.tsx - Canonical game scorecards:
letter-golf-stats.tsxandreverse-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.
Back to standings, preserving the selected game.- Member display name as the page’s
h2; append(you)for the viewer. - Supporting copy:
Detailed scorecard preview for {group name}during the frontend-only phase. After backend hookup this becomesOverall stats shared with {group name}. - The same game dropdown used on Today. It must operate on the current member-detail pathname and preserve the member and group IDs.
- Today card:
Today · Global DailyplusCompleted · Score 3,Completed · Time 1:30,Playing, orNot played, using the existing standings formatters. - 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. - The selected game’s scorecard, using the existing canonical components and
headingLevel="h3". - A quiet scope note after the scorecard:
- Letter Golf:
Individual puzzle history and complete submitted-word lists are not shared. - Reverse Cross:
Individual puzzle history and puzzle answers are not shared.
Presentation requirements¶
Letter Golf order:
- current/best Daily streak card;
- All-time Play metrics;
- Score Distribution.
Reverse Cross order:
- current/best Daily streak card;
- Play metrics;
- Overall timing;
- 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:
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:
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, andCurrent 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:
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:
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
/privacypage 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
/updatesarchive (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 showsCould 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 --checkpassed 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 --checkpassed.
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
/privacypage with accurate disclosure of player-controlled settings, server authorization, and data exclusions. Added/updatesarticle 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 --checkpass 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.
-
/privacypage accurately discloses player-controlled per-game defaults, per-group overrides, server authorization, and data exclusions. -
/updatesarchive 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 --checkpassing.
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 --checkpass. - 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
shareAllandcurrentStreakOnly;inheritin an update removes the stored override. - Cap overrides at
Consts.MaxGroupsPerUserand 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
currentStreakOnlywins 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:
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:
400for unsupported game types, invalid modes, excessive overrides, malformed IDs, or a group override outside the caller’s current memberships;409after bounded optimistic-concurrency retries are exhausted;- normal authenticated-cookie identity behavior consistent with other
/players/meendpoints.
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:
Authorization order:
- Resolve the caller from the signed HTTP-only cookie.
- Read the group and verify the caller is a member.
- Verify the target is still a member of that group.
- 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
GroupMemberSharedStatsServiceas the policy boundary or rename it to reflect both standings summaries and detailed projections. - The standings request may retain one bounded
GetManyAsyncfor 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;
shareAllandcurrentStreakOnlygroup 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 scorecardstitle andMembers of your groups can see the detailed scorecards you choose to share.body. /privacypage updated with accurate disclosure of player-controlled settings, server authorization, and data exclusions./updatesarticle 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:
- Deploy the additive storage/contracts and backend endpoints to a non-production environment.
- Verify authorization, opt-outs, group overrides, old-document defaults, payload size, and both game projections directly against that backend.
- Deploy the frontend, including settings management, detailed member scorecards, accurate privacy/release copy, and the
Newnotice, to the same environment. - 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.
- 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.
- 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 scorecardsoverrides per-game defaults for one group. -
Current streak onlyhides 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.