diff --git a/Client/context-files/global.md b/Client/context-files/global.md new file mode 100644 index 0000000..20c4b51 --- /dev/null +++ b/Client/context-files/global.md @@ -0,0 +1,28 @@ +# Global Client Rules and Shared Contracts + +## Global Persistent UI (All Scenes) +- `Settings` button is present in every scene. +- `Report Bug` button is present in every scene. +- Placement and interaction pattern must remain consistent across scenes. + +## Shared Transport Notes +- Persistent real-time session to relay/hub for presence + notifications. +- HTTPS API calls for auth/account/content operations. +- Auth model: short-lived access token + refresh token. +- Device/session id tracked by server. +- Every payload includes `requestId` and `serverTimeUtc`. +- List endpoints support paging (`page`, `pageSize`) and sorting. + +## Global Input Consistency Rules +- Multi-touch support is required for touch-capable devices. +- Core camera gestures and selection semantics are shared across all scenes. +- Scene-specific controls may add actions, but must not override baseline navigation behavior. +- Input remapping and accessibility options should apply globally, not per-scene. + +## Security and Validation Baseline +- Server authoritative for identity/session, ownership, deck legality, and entitlements. +- Client authoritative for rendering and non-authoritative UI state (filters/sorts). +- Every mutating request requires: + - valid access token + - account ownership check + - anti-replay safeguards (`requestId`, timestamp window) diff --git a/Client/context-files/scenes.md b/Client/context-files/scenes.md index f70a49b..2698f38 100644 --- a/Client/context-files/scenes.md +++ b/Client/context-files/scenes.md @@ -1,724 +1,31 @@ -# Scenes and Client/Server Data Plan (Draft 1) - -This file defines scene scope and network data flow for the first client/server planning pass. - ---- - -## 1) Scene/Page/UI Map (Client-First Draft) - -### 1.1 Boot + Session Scenes -1. `ClientLaunch` -2. `HubConnection` -3. `PatchAndVersionCheck` -4. `AuthGateway` - -### 1.2 Auth Scenes -5. `Login` -6. `Register` -7. `OAuthStart` -8. `OAuthCallback` - -### 1.3 Primary App Scenes -9. `MainMenu` -10. `Bazaar` -11. `Leaderboard` -12. `Settings` -13. `AccountManagement` -14. `CollectionHub` -15. `RankedPlay` -16. `CustomPlay` -17. `DeckEditor` -18. `CardViewer` -19. `Cosmetics` - -### 1.4 Global Persistent UI (All Scenes) - -- `Settings` button is present in every scene. -- `Report Bug` button is present in every scene. -- Placement and interaction pattern must remain consistent across scenes. - -### 1.5 Per-Scene UI Blocks (Draft) - -#### `ClientLaunch` -- Splash/logo -- Build/version text -- Background init indicator - -#### `HubConnection` -- Connection status indicator (connecting/retrying/failed) -- Retry button + diagnostics link (optional) - -#### `PatchAndVersionCheck` -- Version comparison summary -- Patch progress bar -- Release notes panel (optional) -- Continue button when ready - -#### `AuthGateway` -- Account/session check spinner -- Auth route chooser (Login/Register/OAuth) -- Service status banner - -#### `Login` -- Username/email field -- Password field -- Remember device toggle -- Submit + Forgot Password actions - -#### `Register` -- Email/username/password inputs -- Terms/privacy acceptance controls -- Submit action + validation messages - -#### `OAuthStart` -- Provider buttons -- OAuth status text - -#### `OAuthCallback` -- Verifying auth state message -- Success/failure redirect panel - -#### `MainMenu` (Primary Interactive Hub) -- Navigation nodes/buttons to: - - `Bazaar` - - `Leaderboard` - - `Settings` - - `AccountManagement` - - `CollectionHub` - - `RankedPlay` - - `CustomPlay` -- Profile summary widget -- Notifications widget -- Settings/logout actions -- Input support: - - mouse + touch (multi-touch required) - - use standard camera gestures for movement - - selection input: left click and middle mouse click on option nodes - - input behavior baseline is global and must remain consistent across all scenes -- Interactive background system: - - dark aura visual treatment - - rotatable 3D grid layer - - grid topology state can shift between square and hex - -#### `AccountManagement` -- Identity panel: - - username - - email - - profile image -- Password change action: - - `Change Password` button opens popup/modal - - fields: `new password`, `confirm password` - - actions: `Submit` and `Cancel` -- Linked accounts panel: - - `Link Account` action for available OAuth providers - - show currently linked OAuth providers/status -- Stats panel: - - Origin points - - Win - - Loss - - Forfeit - - Draw - - Cards owned - - Cards played -- Spending panel: - - `Total Spent` value censored by default - - toggle to uncensor and reveal: - - money spent - - origin points spent - - `Download Report` action for full spending profile/metrics export -- Spending controls panel: - - set monthly spending cap (money and/or origin points, per policy) - - cap is lock-enforced once set and can be changed only once per month - - clear warnings/explanations shown before setting or changing cap - - show next eligible cap-change date/time -- Legal links panel: - - Terms of Service (TOS) - - EULA - - other required legal documents - -#### `CollectionHub` -- Tab nav (DeckEditor/CardViewer/Cosmetics) -- Collection summary strip - -#### `DeckEditor` -- Deck list panel -- Card search/filter panel -- Deck composition panel -- Validation/errors panel -- Save/duplicate/delete actions - -#### `CardViewer` -- Search input -- Filter/sort controls -- Card grid/list -- Card detail drawer/modal - -#### `Cosmetics` -- Cosmetic category selector (back/trim/art/model) -- Preview pane -- Owned/locked state indicators -- Equip/apply controls - ---- - -## 2) Shared Transport Notes - -- Connection model: - - Persistent real-time session to relay/hub for presence + notifications. - - HTTPS API calls for auth/account/content operations. -- Auth model: - - Short-lived access token + refresh token. - - Device/session id tracked by server. -- Data model: - - Every payload includes `requestId` and `serverTimeUtc`. - - Every list endpoint supports paging (`page`, `pageSize`) and sorting. - ---- - -## 3) Scene Details - -## 3.1 `ClientLaunch` - -### Client - -- Boot local config, device fingerprint, cached token state. -- Initialize telemetry/session id. -- Transition to `HubConnection`. - -### Server - -- None yet (local-only scene). - -### Data Exchange - -Client -> Server: -- none - -Server -> Client: -- none - ---- - -## 3.2 `HubConnection` - -### Client - -- Open relay/hub socket. -- Send initial hello with client build + platform metadata. -- Wait for connection acceptance and service availability. - -### Server - -- Validate protocol version compatibility. -- Return environment capabilities and endpoint map. -- Return maintenance/degraded status if active. - -### Data Exchange - -Client -> Server (`HubHello`): -- `requestId` -- `clientVersion` -- `contentVersion` (installed asset/content hash) -- `platform` (`windows`, `linux`, etc.) -- `locale` -- `deviceId` -- `sessionId` - -Server -> Client (`HubWelcome`): -- `requestId` -- `connectionId` -- `minSupportedClientVersion` -- `latestClientVersion` -- `latestContentVersion` -- `serviceStatus` (`ok`, `degraded`, `maintenance`) -- `apiBaseUrl` -- `cdnBaseUrl` -- `authProvidersEnabled` (`google`, `steam`, `apple`, `microsoft`) -- `motd` (optional) - ---- - -## 3.3 `PatchAndVersionCheck` - -### Client - -- Compare installed version/content against server-required values. -- If update needed: show patch status UI, download/apply, then reconnect. -- If up-to-date: continue to `AuthGateway`. - -### Server - -- Provide update manifest and rollout policy. -- Enforce hard-block if client below minimum supported version. - -### Data Exchange - -Client -> Server (`VersionStatusRequest`): -- `requestId` -- `clientVersion` -- `contentVersion` -- `platform` - -Server -> Client (`VersionStatusResponse`): -- `requestId` -- `isClientSupported` -- `requiresClientUpdate` -- `requiresContentUpdate` -- `minimumAllowedVersion` -- `targetClientVersion` -- `targetContentVersion` -- `updateManifestUrl` -- `updateNotes` (optional) -- `blockReason` (if unsupported) - ---- - -## 3.4 `AuthGateway` - -### Client - -- Decide entry path: - - Existing session refresh. - - Username/password login. - - Register new account. - - OAuth provider login. -- Render enabled options based on server capabilities. - -### Server - -- Validate refresh tokens and return session state. -- Provide auth policy (password rules, age gates, region restrictions if needed). - -### Data Exchange - -Client -> Server (`SessionProbe`): -- `requestId` -- `refreshToken` (optional) -- `deviceId` - -Server -> Client (`SessionProbeResult`): -- `requestId` -- `isAuthenticated` -- `accountId` (if authenticated) -- `displayName` (if authenticated) -- `authMethodsAvailable` -- `passwordPolicy` - ---- - -## 3.5 `Login` / `Register` - -### Client - -- Login: - - Submit account identifier + password. -- Register: - - Submit account fields and required agreements. -- On success transition to `MainMenu`. - -### Server - -- Login: - - Validate credentials, enforce lockout and MFA if enabled. -- Register: - - Create account, validate uniqueness, persist agreements. -- Return auth tokens + account summary. - -### Data Exchange - -Client -> Server (`LoginRequest`): -- `requestId` -- `emailOrUsername` -- `password` -- `deviceId` - -Server -> Client (`LoginResponse`): -- `requestId` -- `success` -- `accessToken` -- `refreshToken` -- `expiresAtUtc` -- `accountSummary` -- `errorCode` (if failed) - -Client -> Server (`RegisterRequest`): -- `requestId` -- `email` -- `username` -- `password` -- `countryCode` -- `dob` (if required by policy) -- `acceptedPolicies` (policy ids + timestamps) - -Server -> Client (`RegisterResponse`): -- `requestId` -- `success` -- `accessToken` (optional; if auto-login enabled) -- `refreshToken` (optional) -- `accountSummary` (optional) -- `requiresEmailVerification` -- `errorCode` (if failed) - ---- - -## 3.6 `OAuthStart` / `OAuthCallback` - -### Client - -- Start OAuth flow with selected provider. -- Open provider auth URL. -- Receive callback code/state and exchange with backend. -- On success transition to `MainMenu`. - -### Server - -- Generate signed OAuth start URL and anti-forgery state. -- Exchange auth code with provider and bind/create game account. -- Return tokens and account summary. - -### Data Exchange - -Client -> Server (`OAuthStartRequest`): -- `requestId` -- `provider` (`google`, `steam`, `apple`, `microsoft`) -- `returnUri` -- `deviceId` - -Server -> Client (`OAuthStartResponse`): -- `requestId` -- `authorizationUrl` -- `state` -- `codeVerifier` (if PKCE client-managed) - -Client -> Server (`OAuthExchangeRequest`): -- `requestId` -- `provider` -- `authorizationCode` -- `state` -- `codeVerifier` (if PKCE) - -Server -> Client (`OAuthExchangeResponse`): -- `requestId` -- `success` -- `accessToken` -- `refreshToken` -- `expiresAtUtc` -- `accountSummary` -- `errorCode` (if failed) - ---- - -## 3.7 `MainMenu` - -### Client - -- Display entry points: - - Ranked Play - - Custom Play - - Collection - - Bazaar - - Account Management - - Settings - - Leaderboard - - Log Out - - Admin (only if authorized) -- Show account profile and key notifications. - -### Server - -- Return entitlement/role-based menu permissions. -- Return badge counts (rewards, inbox, moderation flags, etc.). -- Return feature flags for visible modules. - -### Data Exchange - -Client -> Server (`MainMenuBootstrapRequest`): -- `requestId` -- `accountId` -- `clientVersion` - -Server -> Client (`MainMenuBootstrapResponse`): -- `requestId` -- `profileSummary` -- `roles` (`player`, `admin`, etc.) -- `featureFlags` -- `menuPermissions` -- `notificationCounts` -- `rankedSummary` (current rank, season id) - ---- - -## 3.8 `AccountManagement` - -### Client - -- Display identity/profile details and account-linked providers. -- Support password update via modal workflow. -- Display account stats and spending summary with default-censored totals. -- Allow uncensor toggle for spending values. -- Provide export action for full spending profile report. -- Show legal document links (TOS, EULA, related policies). - -### Server - -- Return account profile, linked OAuth providers, and player/account stats. -- Process password change requests. -- Return spending summary fields and detailed spending report export. -- Enforce monthly spending cap locks and cap-change cooldown windows. -- Return legal document metadata and URLs. - -### Data Exchange - -Client -> Server (`AccountOverviewRequest`): -- `requestId` -- `accountId` - -Server -> Client (`AccountOverviewResponse`): -- `requestId` -- `username` -- `email` -- `profileImageUrl` -- `linkedProviders` -- `stats`: - - `originPoints` - - `wins` - - `losses` - - `forfeits` - - `draws` - - `cardsOwned` - - `cardsPlayed` -- `spendingSummary`: - - `moneySpent` - - `originPointsSpent` - - `censoredByDefault` (`true`) -- `spendingCap`: - - `capEnabled` - - `moneyCapAmount` (optional) - - `originPointsCapAmount` (optional) - - `effectiveFromUtc` - - `nextCapChangeAllowedAtUtc` - - `lockReason` (when change is blocked) -- `legalDocuments` (name + url) - -Client -> Server (`ChangePasswordRequest`): -- `requestId` -- `currentPassword` (if policy requires) -- `newPassword` -- `confirmPassword` - -Server -> Client (`ChangePasswordResponse`): -- `requestId` -- `success` -- `errorCode` (if failed) - -Client -> Server (`LinkOAuthRequest`): -- `requestId` -- `provider` - -Server -> Client (`LinkOAuthResponse`): -- `requestId` -- `success` -- `linkedProviders` -- `errorCode` (if failed) - -Client -> Server (`SpendingCapUpdateRequest`): -- `requestId` -- `moneyCapAmount` (optional) -- `originPointsCapAmount` (optional) -- `acceptWarning` (`true` required) - -Server -> Client (`SpendingCapUpdateResponse`): -- `requestId` -- `success` -- `spendingCap` -- `nextCapChangeAllowedAtUtc` -- `warningMessage` -- `errorCode` (if failed, including cooldown violation) - -Client -> Server (`SpendingReportRequest`): -- `requestId` -- `format` (`csv`, `json`, `pdf`) - -Server -> Client (`SpendingReportResponse`): -- `requestId` -- `success` -- `downloadUrl` -- `expiresAtUtc` -- `errorCode` (if failed) - ---- - -## 3.9 `Collection` (Hub Scene) - -### Client - -- Load owned cards, deck list, cosmetics. -- Provide tabs/sub-scenes: - - `DeckEditor` - - `CardViewer` - - `Cosmetics` - -### Server - -- Return collection inventory + ownership states. -- Return deck metadata and validation rules. -- Return unlocked/purchasable card backs, trims, and art/model variants. - -### Data Exchange - -Client -> Server (`CollectionBootstrapRequest`): -- `requestId` -- `accountId` -- `includeInventory` -- `includeDecks` -- `includeCosmetics` - -Server -> Client (`CollectionBootstrapResponse`): -- `requestId` -- `cardInventory` (card definition id + ownership/quantity + variants owned) -- `deckSummaries` -- `cosmeticInventory` -- `collectionStats` -- `rulesVersion` - ---- - -## 3.10 `DeckEditor` - -### Client - -- Build/edit decks with full filtering and sorting. -- Validate deck locally with server rule mirror. -- Save, duplicate, rename, delete deck. - -### Server - -- Validate deck against current legal format/rules. -- Persist deck revisions and return canonical saved state. - -### Data Exchange - -Client -> Server (`DeckValidateRequest`): -- `requestId` -- `deckDraft` -- `formatId` - -Server -> Client (`DeckValidateResponse`): -- `requestId` -- `isValid` -- `errors` -- `warnings` - -Client -> Server (`DeckSaveRequest`): -- `requestId` -- `deckId` (optional for new deck) -- `deckName` -- `deckCards` (card instance ids or definition ids + quantity model) -- `formatId` - -Server -> Client (`DeckSaveResponse`): -- `requestId` -- `success` -- `deckId` -- `deckRevision` -- `isValid` -- `errors` (if invalid/rejected) - ---- - -## 3.11 `CardViewer` - -### Client - -- Browse card library and owned-only views. -- Apply filters/sorts: - - Type, affinity, cost, rarity, owned/unowned, set, text search. -- View alternate art/model versions. - -### Server - -- Return searchable card metadata and ownership projection. -- Return art/model variant manifests. - -### Data Exchange - -Client -> Server (`CardSearchRequest`): -- `requestId` -- `query` -- `filters` -- `sort` -- `page` -- `pageSize` - -Server -> Client (`CardSearchResponse`): -- `requestId` -- `results` -- `totalCount` -- `facets` - ---- - -## 3.12 `Cosmetics` (Card Back / Trim / Variant Selection) - -### Client - -- Display available card back/trim options and card-specific art/model variants. -- Preview and equip selections. - -### Server - -- Verify ownership and compatibility for selected cosmetic. -- Persist equipped defaults and per-card overrides. - -### Data Exchange - -Client -> Server (`CosmeticEquipRequest`): -- `requestId` -- `scope` (`globalDeckDefault`, `cardDefinition`, `cardInstance`) -- `targetId` -- `cardBackId` (optional) -- `trimId` (optional) -- `artVariantId` (optional) -- `modelVariantId` (optional) - -Server -> Client (`CosmeticEquipResponse`): -- `requestId` -- `success` -- `equippedState` -- `errorCode` (if failed) - ---- - -## 3.13 Global Input Consistency Rules - -- Multi-touch support is required for touch-capable devices. -- Core camera gestures and selection semantics are shared across all scenes. -- Scene-specific controls may add actions, but must not override baseline navigation behavior. -- Input remapping and accessibility options should apply globally, not per-scene. - ---- - -## 4) Security and Validation Baseline - -- Server authoritative for: - - Account identity/session state - - Collection ownership - - Deck legality - - Cosmetic entitlement -- Client authoritative for: - - Local scene rendering - - Non-authoritative UI filtering/sorting state -- Every mutating request requires: - - valid access token - - account ownership check - - anti-replay safeguards (`requestId`, timestamp window) - ---- - -## 5) Next Draft Targets - -- Ranked Play scene breakdown and matchmaking payload contracts. -- Custom Play lobby + room state contracts. -- Bazaar transaction flow and inventory mutation rules. -- Settings scene-level data model and interactions. -- Admin scene contracts and role-gated operations. +# Scenes Index + +This file is the top-level map. Scene details now live in `context-files/scenes/*.scene.md`. + +## Boot + Session +1. `ClientLaunch` → `scenes/client-launch.scene.md` +2. `HubConnection` → `scenes/hub-connection.scene.md` +3. `PatchAndVersionCheck` → `scenes/patch-and-version-check.scene.md` +4. `AuthGateway` → `scenes/auth-gateway.scene.md` + +## Auth +5. `Login` → `scenes/login.scene.md` +6. `Register` → `scenes/register.scene.md` +7. `OAuthStart` → `scenes/oauth-start.scene.md` +8. `OAuthCallback` → `scenes/oauth-callback.scene.md` + +## Primary App +9. `MainMenu` → `scenes/main-menu.scene.md` +10. `Bazaar` → `scenes/bazaar.scene.md` +11. `Leaderboard` → `scenes/leaderboard.scene.md` +12. `Settings` → `scenes/settings.scene.md` +13. `AccountManagement` → `scenes/account-management.scene.md` +14. `CollectionHub` → `scenes/collection-hub.scene.md` +15. `RankedPlay` → `scenes/ranked-play.scene.md` +16. `CustomPlay` → `scenes/custom-play.scene.md` +17. `DeckEditor` → `scenes/deck-editor.scene.md` +18. `CardViewer` → `scenes/card-viewer.scene.md` +19. `Cosmetics` → `scenes/cosmetics.scene.md` + +## Global Rules +- Shared/global client rules are in `global.md`. diff --git a/Client/context-files/scenes/account-management.scene.md b/Client/context-files/scenes/account-management.scene.md new file mode 100644 index 0000000..5945b6d --- /dev/null +++ b/Client/context-files/scenes/account-management.scene.md @@ -0,0 +1,72 @@ +# AccountManagement Scene + +## UI +- Identity panel: username, email, profile image +- Password change modal: + - fields: `new password`, `confirm password` + - actions: `Submit`, `Cancel` +- Linked accounts panel: + - `Link Account` for OAuth providers + - linked provider status list +- Stats panel: + - Origin points, Win, Loss, Forfeit, Draw, Cards owned, Cards played +- Spending panel: + - `Total Spent` censored by default + - uncensor toggle + - money spent + origin points spent + - `Download Report` for full spending profile +- Spending controls panel: + - set monthly spending cap (money and/or origin points) + - cap lock-enforced once set + - cap can be changed once per month + - warnings required before set/change + - show next eligible cap-change date/time +- Legal links panel: + - TOS, EULA, other required legal docs + +## Client +- Display profile, linked providers, stats, spending, legal docs. +- Support password update workflow. +- Support spending cap update workflow with warning acknowledgment. + +## Server +- Return account profile, linked providers, stats, spending summary. +- Process password changes. +- Enforce spending cap locks and cooldown windows. +- Return spending report export URL. +- Return legal document metadata and URLs. + +## Data Exchange +### Client -> Server (`AccountOverviewRequest`) +- `requestId`, `accountId` + +### Server -> Client (`AccountOverviewResponse`) +- `requestId`, `username`, `email`, `profileImageUrl`, `linkedProviders` +- `stats`: `originPoints`, `wins`, `losses`, `forfeits`, `draws`, `cardsOwned`, `cardsPlayed` +- `spendingSummary`: `moneySpent`, `originPointsSpent`, `censoredByDefault` +- `spendingCap`: `capEnabled`, `moneyCapAmount`, `originPointsCapAmount`, `effectiveFromUtc`, `nextCapChangeAllowedAtUtc`, `lockReason` +- `legalDocuments` (name + url) + +### Client -> Server (`ChangePasswordRequest`) +- `requestId`, `currentPassword` (if policy requires), `newPassword`, `confirmPassword` + +### Server -> Client (`ChangePasswordResponse`) +- `requestId`, `success`, `errorCode` + +### Client -> Server (`LinkOAuthRequest`) +- `requestId`, `provider` + +### Server -> Client (`LinkOAuthResponse`) +- `requestId`, `success`, `linkedProviders`, `errorCode` + +### Client -> Server (`SpendingCapUpdateRequest`) +- `requestId`, `moneyCapAmount` (optional), `originPointsCapAmount` (optional), `acceptWarning` + +### Server -> Client (`SpendingCapUpdateResponse`) +- `requestId`, `success`, `spendingCap`, `nextCapChangeAllowedAtUtc`, `warningMessage`, `errorCode` + +### Client -> Server (`SpendingReportRequest`) +- `requestId`, `format` (`csv`, `json`, `pdf`) + +### Server -> Client (`SpendingReportResponse`) +- `requestId`, `success`, `downloadUrl`, `expiresAtUtc`, `errorCode` diff --git a/Client/context-files/scenes/auth-gateway.scene.md b/Client/context-files/scenes/auth-gateway.scene.md new file mode 100644 index 0000000..efdfc1d --- /dev/null +++ b/Client/context-files/scenes/auth-gateway.scene.md @@ -0,0 +1,22 @@ +# AuthGateway Scene + +## UI +- Account/session check spinner +- Auth route chooser (Login/Register/OAuth) +- Service status banner + +## Client +- Decide entry path: session refresh, login, register, OAuth. +- Render enabled options based on server capabilities. + +## Server +- Validate refresh tokens and return session state. +- Provide auth policy. + +## Data Exchange +### Client -> Server (`SessionProbe`) +- `requestId`, `refreshToken` (optional), `deviceId` + +### Server -> Client (`SessionProbeResult`) +- `requestId`, `isAuthenticated`, `accountId`, `displayName` +- `authMethodsAvailable`, `passwordPolicy` diff --git a/Client/context-files/scenes/bazaar.scene.md b/Client/context-files/scenes/bazaar.scene.md new file mode 100644 index 0000000..d68417e --- /dev/null +++ b/Client/context-files/scenes/bazaar.scene.md @@ -0,0 +1,9 @@ +# Bazaar Scene + +## Status +Draft placeholder. + +## Planned Scope +- Define scene UI blocks +- Define client interactions +- Define server contract and payloads diff --git a/Client/context-files/scenes/card-viewer.scene.md b/Client/context-files/scenes/card-viewer.scene.md new file mode 100644 index 0000000..b9e94f8 --- /dev/null +++ b/Client/context-files/scenes/card-viewer.scene.md @@ -0,0 +1,20 @@ +# CardViewer Scene + +## UI +- Search input +- Filter/sort controls +- Card grid/list +- Card detail drawer/modal + +## Client +- Browse card library and owned-only views. + +## Server +- Return searchable metadata, ownership projection, and variant manifests. + +## Data Exchange +### Client -> Server (`CardSearchRequest`) +- `requestId`, `query`, `filters`, `sort`, `page`, `pageSize` + +### Server -> Client (`CardSearchResponse`) +- `requestId`, `results`, `totalCount`, `facets` diff --git a/Client/context-files/scenes/client-launch.scene.md b/Client/context-files/scenes/client-launch.scene.md new file mode 100644 index 0000000..6e5fa5a --- /dev/null +++ b/Client/context-files/scenes/client-launch.scene.md @@ -0,0 +1,14 @@ +# ClientLaunch Scene + +## UI +- Splash/logo +- Build/version text +- Background init indicator + +## Client +- Boot local config, device fingerprint, cached token state. +- Initialize telemetry/session id. +- Transition to `HubConnection`. + +## Server +- None (local-only scene). diff --git a/Client/context-files/scenes/collection-hub.scene.md b/Client/context-files/scenes/collection-hub.scene.md new file mode 100644 index 0000000..7b26b80 --- /dev/null +++ b/Client/context-files/scenes/collection-hub.scene.md @@ -0,0 +1,18 @@ +# CollectionHub Scene + +## UI +- Tab nav (`DeckEditor`, `CardViewer`, `Cosmetics`) +- Collection summary strip + +## Client +- Load owned cards, deck list, cosmetics. + +## Server +- Return collection inventory, deck metadata, validation rules, cosmetic inventory. + +## Data Exchange +### Client -> Server (`CollectionBootstrapRequest`) +- `requestId`, `accountId`, `includeInventory`, `includeDecks`, `includeCosmetics` + +### Server -> Client (`CollectionBootstrapResponse`) +- `requestId`, `cardInventory`, `deckSummaries`, `cosmeticInventory`, `collectionStats`, `rulesVersion` diff --git a/Client/context-files/scenes/cosmetics.scene.md b/Client/context-files/scenes/cosmetics.scene.md new file mode 100644 index 0000000..7f04393 --- /dev/null +++ b/Client/context-files/scenes/cosmetics.scene.md @@ -0,0 +1,20 @@ +# Cosmetics Scene + +## UI +- Cosmetic category selector (back/trim/art/model) +- Preview pane +- Owned/locked state indicators +- Equip/apply controls + +## Client +- Display and preview cosmetic options; equip selections. + +## Server +- Verify ownership/compatibility and persist equipped defaults/overrides. + +## Data Exchange +### Client -> Server (`CosmeticEquipRequest`) +- `requestId`, `scope`, `targetId`, `cardBackId`, `trimId`, `artVariantId`, `modelVariantId` + +### Server -> Client (`CosmeticEquipResponse`) +- `requestId`, `success`, `equippedState`, `errorCode` diff --git a/Client/context-files/scenes/custom-play.scene.md b/Client/context-files/scenes/custom-play.scene.md new file mode 100644 index 0000000..dbbf36e --- /dev/null +++ b/Client/context-files/scenes/custom-play.scene.md @@ -0,0 +1,9 @@ +# Custom play Scene + +## Status +Draft placeholder. + +## Planned Scope +- Define scene UI blocks +- Define client interactions +- Define server contract and payloads diff --git a/Client/context-files/scenes/deck-editor.scene.md b/Client/context-files/scenes/deck-editor.scene.md new file mode 100644 index 0000000..f626699 --- /dev/null +++ b/Client/context-files/scenes/deck-editor.scene.md @@ -0,0 +1,27 @@ +# DeckEditor Scene + +## UI +- Deck list panel +- Card search/filter panel +- Deck composition panel +- Validation/errors panel +- Save/duplicate/delete actions + +## Client +- Build/edit decks, local mirror validation, save/duplicate/rename/delete. + +## Server +- Validate deck against current rules and persist deck revisions. + +## Data Exchange +### Client -> Server (`DeckValidateRequest`) +- `requestId`, `deckDraft`, `formatId` + +### Server -> Client (`DeckValidateResponse`) +- `requestId`, `isValid`, `errors`, `warnings` + +### Client -> Server (`DeckSaveRequest`) +- `requestId`, `deckId`, `deckName`, `deckCards`, `formatId` + +### Server -> Client (`DeckSaveResponse`) +- `requestId`, `success`, `deckId`, `deckRevision`, `isValid`, `errors` diff --git a/Client/context-files/scenes/hub-connection.scene.md b/Client/context-files/scenes/hub-connection.scene.md new file mode 100644 index 0000000..5cc7fa6 --- /dev/null +++ b/Client/context-files/scenes/hub-connection.scene.md @@ -0,0 +1,25 @@ +# HubConnection Scene + +## UI +- Connection status indicator (connecting/retrying/failed) +- Retry button + diagnostics link (optional) + +## Client +- Open relay/hub socket. +- Send initial hello with client build + platform metadata. +- Wait for connection acceptance and service availability. + +## Server +- Validate protocol version compatibility. +- Return environment capabilities and endpoint map. +- Return maintenance/degraded status if active. + +## Data Exchange +### Client -> Server (`HubHello`) +- `requestId`, `clientVersion`, `contentVersion`, `platform`, `locale`, `deviceId`, `sessionId` + +### Server -> Client (`HubWelcome`) +- `requestId`, `connectionId` +- `minSupportedClientVersion`, `latestClientVersion`, `latestContentVersion` +- `serviceStatus`, `apiBaseUrl`, `cdnBaseUrl` +- `authProvidersEnabled`, `motd` (optional) diff --git a/Client/context-files/scenes/leaderboard.scene.md b/Client/context-files/scenes/leaderboard.scene.md new file mode 100644 index 0000000..a780a88 --- /dev/null +++ b/Client/context-files/scenes/leaderboard.scene.md @@ -0,0 +1,9 @@ +# Leaderboard Scene + +## Status +Draft placeholder. + +## Planned Scope +- Define scene UI blocks +- Define client interactions +- Define server contract and payloads diff --git a/Client/context-files/scenes/login.scene.md b/Client/context-files/scenes/login.scene.md new file mode 100644 index 0000000..ab6e15b --- /dev/null +++ b/Client/context-files/scenes/login.scene.md @@ -0,0 +1,21 @@ +# Login Scene + +## UI +- Username/email field +- Password field +- Remember device toggle +- Submit + Forgot Password actions + +## Client +- Submit account identifier + password. +- On success transition to `MainMenu`. + +## Server +- Validate credentials, enforce lockout and MFA if enabled. + +## Data Exchange +### Client -> Server (`LoginRequest`) +- `requestId`, `emailOrUsername`, `password`, `deviceId` + +### Server -> Client (`LoginResponse`) +- `requestId`, `success`, `accessToken`, `refreshToken`, `expiresAtUtc`, `accountSummary`, `errorCode` diff --git a/Client/context-files/scenes/main-menu.scene.md b/Client/context-files/scenes/main-menu.scene.md new file mode 100644 index 0000000..f5c75c0 --- /dev/null +++ b/Client/context-files/scenes/main-menu.scene.md @@ -0,0 +1,30 @@ +# MainMenu Scene (Primary Interactive Hub) + +## UI +- Navigation nodes/buttons to: + - `Bazaar`, `Leaderboard`, `Settings`, `AccountManagement`, `CollectionHub`, `RankedPlay`, `CustomPlay` +- Profile summary widget +- Notifications widget +- Settings/logout actions +- Interactive background: + - dark aura visual treatment + - rotatable 3D grid layer + - grid topology can shift between square and hex + +## Input +- mouse + touch (multi-touch required) +- standard camera gestures for movement +- node selection via left click and middle mouse click + +## Client +- Display entry points and key account notifications. + +## Server +- Return role/entitlement menu permissions, badge counts, feature flags. + +## Data Exchange +### Client -> Server (`MainMenuBootstrapRequest`) +- `requestId`, `accountId`, `clientVersion` + +### Server -> Client (`MainMenuBootstrapResponse`) +- `requestId`, `profileSummary`, `roles`, `featureFlags`, `menuPermissions`, `notificationCounts`, `rankedSummary` diff --git a/Client/context-files/scenes/oauth-callback.scene.md b/Client/context-files/scenes/oauth-callback.scene.md new file mode 100644 index 0000000..4d07c13 --- /dev/null +++ b/Client/context-files/scenes/oauth-callback.scene.md @@ -0,0 +1,19 @@ +# OAuthCallback Scene + +## UI +- Verifying auth state message +- Success/failure redirect panel + +## Client +- Receive callback code/state and exchange with backend. +- On success transition to `MainMenu`. + +## Server +- Exchange auth code with provider and bind/create game account. + +## Data Exchange +### Client -> Server (`OAuthExchangeRequest`) +- `requestId`, `provider`, `authorizationCode`, `state`, `codeVerifier` + +### Server -> Client (`OAuthExchangeResponse`) +- `requestId`, `success`, `accessToken`, `refreshToken`, `expiresAtUtc`, `accountSummary`, `errorCode` diff --git a/Client/context-files/scenes/oauth-start.scene.md b/Client/context-files/scenes/oauth-start.scene.md new file mode 100644 index 0000000..7e0cdee --- /dev/null +++ b/Client/context-files/scenes/oauth-start.scene.md @@ -0,0 +1,19 @@ +# OAuthStart Scene + +## UI +- Provider buttons +- OAuth status text + +## Client +- Start OAuth flow with selected provider. +- Open provider auth URL. + +## Server +- Generate signed OAuth start URL and anti-forgery state. + +## Data Exchange +### Client -> Server (`OAuthStartRequest`) +- `requestId`, `provider`, `returnUri`, `deviceId` + +### Server -> Client (`OAuthStartResponse`) +- `requestId`, `authorizationUrl`, `state`, `codeVerifier` (if PKCE client-managed) diff --git a/Client/context-files/scenes/patch-and-version-check.scene.md b/Client/context-files/scenes/patch-and-version-check.scene.md new file mode 100644 index 0000000..abde34b --- /dev/null +++ b/Client/context-files/scenes/patch-and-version-check.scene.md @@ -0,0 +1,25 @@ +# PatchAndVersionCheck Scene + +## UI +- Version comparison summary +- Patch progress bar +- Release notes panel (optional) +- Continue button when ready + +## Client +- Compare installed version/content against server-required values. +- If update needed: show patch status UI, download/apply, reconnect. +- If up-to-date: continue to `AuthGateway`. + +## Server +- Provide update manifest and rollout policy. +- Enforce hard-block below minimum supported version. + +## Data Exchange +### Client -> Server (`VersionStatusRequest`) +- `requestId`, `clientVersion`, `contentVersion`, `platform` + +### Server -> Client (`VersionStatusResponse`) +- `requestId`, `isClientSupported`, `requiresClientUpdate`, `requiresContentUpdate` +- `minimumAllowedVersion`, `targetClientVersion`, `targetContentVersion` +- `updateManifestUrl`, `updateNotes` (optional), `blockReason` (if unsupported) diff --git a/Client/context-files/scenes/ranked-play.scene.md b/Client/context-files/scenes/ranked-play.scene.md new file mode 100644 index 0000000..57d105c --- /dev/null +++ b/Client/context-files/scenes/ranked-play.scene.md @@ -0,0 +1,9 @@ +# Ranked play Scene + +## Status +Draft placeholder. + +## Planned Scope +- Define scene UI blocks +- Define client interactions +- Define server contract and payloads diff --git a/Client/context-files/scenes/register.scene.md b/Client/context-files/scenes/register.scene.md new file mode 100644 index 0000000..db88f9e --- /dev/null +++ b/Client/context-files/scenes/register.scene.md @@ -0,0 +1,20 @@ +# Register Scene + +## UI +- Email/username/password inputs +- Terms/privacy acceptance controls +- Submit action + validation messages + +## Client +- Submit account fields and required agreements. +- On success transition to `MainMenu`. + +## Server +- Create account, validate uniqueness, persist agreements. + +## Data Exchange +### Client -> Server (`RegisterRequest`) +- `requestId`, `email`, `username`, `password`, `countryCode`, `dob`, `acceptedPolicies` + +### Server -> Client (`RegisterResponse`) +- `requestId`, `success`, `accessToken` (optional), `refreshToken` (optional), `accountSummary` (optional), `requiresEmailVerification`, `errorCode` diff --git a/Client/context-files/scenes/settings.scene.md b/Client/context-files/scenes/settings.scene.md new file mode 100644 index 0000000..ffa24a7 --- /dev/null +++ b/Client/context-files/scenes/settings.scene.md @@ -0,0 +1,9 @@ +# Settings Scene + +## Status +Draft placeholder. + +## Planned Scope +- Define scene UI blocks +- Define client interactions +- Define server contract and payloads