Skip to content

Game & App Overview ​

Pedro is a modern, real-time multiplayer card game app designed for seamless social play, strategic decision-making, and AI-assisted gameplay.


What Makes Pedro Special? ​

1. Seamless Multiplayer, Clubs & Unified Lobby ​

  • Instant Synchronization: Play in real-time with friends or opponents across devices.
  • Pedro Clubs & "Challo Gallery" Founders Club: Players can create or join private social clubs (such as the ♠️ Challo Gallery Founders Club, invite code CHALLO) via 6-character club invite codes, shareable links (?club=CHALLO), or direct in-app club invitations. Club Owners and Admins can invite players directly in-app via the Invite Players modal in Club Details (manage-club-member with action 'invite'), sending an FCM push notification and surfacing Club Invitations directly on the recipient's Home Feed (where they can Accept or Decline with one tap). Each club features its own member roster, pending invitations list (with one-tap invitation revoking for admins), Owner/Admin management controls (editing club name/description, rotating invite codes, promoting/demoting admins, inviting/uninviting players, and removing members), and a dedicated private leaderboard.
  • Unified Multi-Club Home Feed & Invitations: The Home screen features a horizontal My Clubs strip ([ ♠️ Challo Gallery (👥 12) ] [ + Club ], whose Club Details sheet includes a direct Club Games shortcut) and merges Open Tables (top 3), Live Now (top 2), and Recent Games (up to 5 personal and non-archived club matches, de-duplicated against the upper sections) across a player's clubs (up to 10 clubs) alongside global Open Tables—sorting Club tables first (♠️ Challo Gallery • 👀) and surfacing winner callouts (🏆 You Won! / 🏆 Won by <Name>) and role-adaptive actions (Jump In, Watch Live, Join Table, View, Full). All pending club and game invitations are rendered without preview caps directly on the Home Feed for instant one-tap response.
  • Floating Bottom Navigation & Unified "All Games" Hub: A Material 3 Expressive floating stadium pill at the bottom of the screen provides direct access to Home, All Games, Rankings, and Profile while letting feed content scroll seamlessly beneath it. On the Home tab, an adaptive + / + New Game floating action button sits inline alongside the navigation pill (compact circular + on phones, expanded + New Game stadium button on wider tablet and web viewports). The All Games screen consolidates accessible matches into a unified chronological feed ordered strictly by most recent activity (lastActivityAt = updatedAt ?? createdAt, newest first)—combining the player's own games, pending invitations, open/live global tables, and matches from their clubs (up to 10 clubs, even when they were not seated), while excluding unrelated public games from Completed and Archived history.
  • Scope Chips, Status Filter Pills & Role-Adaptive Actions: Players in clubs can slice the All Games feed by scope (All, ♠️ <Club>, 👤 My Games) and combine it with horizontal status pills:
    • All: Displays all active and completed non-archived games matching the selected scope across Live, Waiting, and Finished.
    • 🟢 Live: Filters to active matches (playing or starting), displaying "Jump In" for seated players and "Watch Live" (with secondary button styling) for spectators.
    • 🪑 Waiting: Filters to tables waiting for players (waiting), showing "Lobby" for seated players, "Join Table" for open seats, and disabled "Full (8/8)" when all seats are taken.
    • 🏁 Completed: Filters to finished personal and club matches (finished), highlighting winner attribution (🏆 You Won! / 🏆 Won by <Name>) and one-tap "View" access to completed round summaries and standings.
    • 📦 Archived: Reveals archived personal and club games (archived), opening read-only match recaps with final standings and completed round scores.
  • 3-Way Table Visibility (♠️ Club / 🌐 Open / 🔒 Private) & 6-Character Room Codes: When creating a game, hosts choose between:
    • ♠️ Club Table (visibility: 'club'): Smart default for club members (with a one-tap club chip picker if the host belongs to multiple clubs). Listed in that club's lobby feed, enables spectator hand peeking (👀), and rolls up exclusively to that club's leaderboard. If a waiting club table needs more players, the host can tap Open Empty Seats to Public to convert the room into a public Open Table before starting.
    • 🌐 Open Table (visibility: 'public'): Listed in the global Open Tables lobby feed so any player can claim a seat (Join Table), disables spectator hand peeking, and rolls up to the 🌐 Global Open Play leaderboard.
    • 🔒 Private Table (visibility: 'private'): Hidden from public and club feeds; joinable via direct invitation, 6-character Room Code (Join with Code), or share link (?code=XXXXXX). Enables spectator hand peeking (👀) and runs as an unranked casual table.
  • Searchable Player Invites & Persistent Lobby Modal: Hosts in game lobbies and Club Owners/Admins in club details can search players by screen name (screenNameLower prefix indexing) or pick from suggested co-players and club members inside persistent invitation modals (InviteDialog and ClubInviteDialog), inviting or uninviting players in a single session with real-time status streaming and dynamic capacity indicators.
  • Trinidadian AI Bot Seat Fill (🤖 Add AI Bot): Hosts in waiting lobbies can add or remove server-side Trinidadian AI bot personas (🤖 Uncle Sonny, 🤖 Tantava Merle, 🤖 Breezy Rumshop, and 🤖 Captain Kyle) via manage-game-bot so a 2- or 3-player group can start a full 4+ player match immediately without waiting on human seats. Bots bid, select trump, discard down to 6 cards, and play legal tricks automatically on the server with authentic strategy (protecting the 5 of trumps, hunting vulnerable 5s/9s/Jacks, and leading highest safe trumps).
  • Universal Turn Timer (10s Grace + 45s Countdown), Auto-Play & Leaderboard Isolation: To prevent tables from stalling while respecting deep thinking time, all game visibilities (Open, Club, and Private) feature a universal 55-second turn deadline (10s quiet thinking grace followed by a 45s visual countdown). Players can extend their countdown by +45s (up to 3 times per turn) or tablemates can tap Call & +45s. If a turn reaches 0s without extension (or if a player taps Step Away (Auto-Play)), the seat switches to Passive Auto-Play (auto-passing bids unless forced to open at 1 point, and playing legal cards in 350ms) with a top Resume Seat banner for instant manual restoration. Any round featuring an AI bot or an Auto-Play seat is strictly Leaderboard-Exempt from Global and Club leaderboards.
  • Randomized Table Seating: When the host starts the game, all non-host players are randomly shuffled around the table (with the host anchored at the first seat as the opening round's dealer) so seating order does not depend on invitation acceptance speed.
  • Game Management, Leaving Waiting Tables, Archiving & Deletion: Non-host players who join a waiting game can vacate their seat before the match starts by tapping Leave Table (leave-game) from the lobby waiting room or from the Recent Games overflow menu on the Home feed. To keep Live Now, Open Tables, and Recent Games feeds clean when a match is abandoned mid-game or left idle in a waiting room, games can be archived automatically or manually:
    • Automatic 24-Hour Inactivity Archiving (sweep-abandoned-games): An hourly Google Cloud Scheduler job (sweep-abandoned-games-hourly, authenticated via OIDC) sweeps games stuck in 'waiting', 'starting', or 'playing' status with no gameplay activity (updatedAt ?? createdAt) for 24+ hours, transitioning them to status: 'archived' (isArchived: true, isOpen: false) and cleaning up transient hands, server, and viewers subcollections while preserving completed round archives (games/{gameId}/rounds/*) and leaderboard stats.
    • Manual Archiving (archive-game): Game hosts, Club Owners/Admins (for club-scoped games), and Global App Admins can manually archive any waiting or live game from the Home feed (Open Tables, Live Now, or Recent Games), the All Games screen, the waiting lobby (GameRoomScreen), or the active game board (GameBoardScreen).
    • Archived Filter & Read-Only Summary: Archived games are hidden by default across all active feeds and can be inspected anytime using the 📦 Archived status filter pill on the All Games screen, opening a read-only Archived Match summary with final standings and completed round recaps.
    • Permanent Deletion (delete-game): Game creators also retain the option to permanently delete games they created (with confirmation), removing the game document, reversing any leaderboard round rollups, and deleting associated chat messages and reactions.

2. Interactive AI Companions ​

  • Global AI Narrator (Trinidad & Tobago Voice): An in-game announcer observes high-impact milestones—such as notable winning bidding contracts ($\ge 12$), dramatic all-in (20) or large jump bids ($\ge 5$ or $\ge 17$), trump suit replacement announcements, major non-final trick heists (hanging an opponent's Jack or capturing the 9-point Pedro card), contract sets or makes at round completion, and match championships. Routine 1-point mid-trick plays (such as safe Aces or 2s) and standard minimum bids are filtered to keep table talk focused and impactful. Commentary is generated dynamically via Genkit (gemini-3.5-flash-lite) in Cloud Functions using rich, culturally authentic Trinidad & Tobago scenario pools (15–25+ local cultural angles per event type). Each event randomly samples two distinct Trini scenarios to inspire the prompt, ensuring fresh, non-repetitive picong and table banter (with expressions like "Lardits!", "Jah!", "Daylight robbery on de table!", and "Pressure in de savannah!").
  • Personal AI Coach & Smart Room Naming (gemini-3.5-flash-lite):
    • Bid Assistant: Provides on-demand bidding advice during the Wadger phase when tapping the subtle Help (?) icon button next to Your Hand, analyzing your hand and suggesting competitive bid ranges with strategy tips without shifting table layout.
    • Tactical Insights: Recommends optimal moves and highlights key remaining cards on demand during gameplay when tapping the subtle Help (?) icon button next to Your Hand to elevate your skills without shifting table layout.
    • Creative Room Names: Automatically generates vibrant, playful room titles powered by gemini-3.5-flash-lite using dynamic prompt entropy (rotating through 15+ themed Caribbean and Pedro card vibes, 6+ naming patterns, and authentic Pedro/Trini lore terms with rolling session de-duplication to prevent repetitive defaults). When offline, a combinatorial fallback pool of 32+ adjectives and 32+ card nouns provides over 1,000 unique name combinations. Hosts can freely edit suggested names or tap the interactive 🎲 Re-Roll button directly within the Create Game dialog to shuffle instant alternatives.
    • App Check & Replay Protection Security: Client-side AI calls via Firebase AI Logic are strictly protected by Firebase App Check enforced with Fraud Defense (reCAPTCHA Enterprise) and Replay Protection across iOS, Android, and Web (enforcementMode: ENFORCED). Client inference requests use single-use limited App Check tokens (FirebaseAI.googleAI(useLimitedUseAppCheckTokens: true)), preventing unauthorized API quota exploitation and token replay attacks while unlocking high-cost generative models (gemini-3.1-flash-lite-image). On iOS, the Google Cloud reCAPTCHA Enterprise key enforces bundle ID integrity (com.ool.pedro) and risk assessment scoring (minimum valid score threshold of 0.1), with native runtime symbols preserved via -ObjC. All services stream runtime diagnostic errors directly to Firebase Crashlytics.

3. In-Game Social Interactions & Live Reactions ​

  • Transient Chat Notifications & Multi-Directional Dismissal: When comments are posted by the AI Narrator or fellow players, a floating toast notification appears over the board for 5 seconds before fading into the collapsed Game Chat bar. Players can dismiss the toast early by swiping in any direction—up, down, left, or right (DismissDirection.all)—or by tapping the close (X) button.
  • Adaptive Game Chat Drawer & Safe Keyboard Handling: When opened, the Game Chat expands with a screen-proportionate, responsive height that leaves ample room for the live card table. When typing on mobile devices, the layout adaptively preserves full visibility of the text field and send controls directly above the soft keyboard without pixel overflow. Hitting "Done" on the keyboard dismisses the keyboard safely without prematurely sending draft messages; message transmission is strictly controlled via the UI send button.
  • Quick Table Callout Reactions & De-Bursted Personal Usage Ordering: Located directly beneath the player's card hand (and in the spectator dock), a focused strip of 8 in-game callout pills enables one-tap expressive table banter. Callouts can be rapidly triggered as many times as the player taps without throttling or visual debouncing, sending celebratory showers of floating callout badges in real time without cluttering the persistent chat log. To prevent spammed reactions from artificially distorting usage rankings, rapid multi-taps within a 10-second burst window coalesce into a single usage event for popularity scoring. The 8 in-game reactions dynamically order based on each player's personal de-bursted usage (locking for the duration of an active match to preserve muscle memory and refreshing upon entering the next game).
  • Club-Level Dynamic Reactions & Shared Pool: Clubs can express their own inside jokes, local memes, and timely banter via a shared pool of up to 40 manageable reactions alongside 6 permanent Roots reactions (😱 OMG!, 😱 Lardits!, 🥵 Pressure!, 🤦 Madness!, ⏱️ Play Fast!, 😤 Steups!). Any club member can create new custom reactions ([Emoji + up to 15 characters text]) or delete non-Roots reactions from the club pool. A built-in "✨ Suggest Emoji" assistant powered client-side by Firebase AI Logic (gemini-3.5-flash-lite) automatically recommends the most fitting emoji for any entered callout text (while supporting custom manual emoji selection).
  • Customizable 8-Slot Personal Loadouts via Unified Drag-and-Drop: Players manage their active 8 in-game reaction loadout via a clean two-section modal (ClubReactionsSheet). The first section provides streamlined reaction creation with optional instant equip, while the second section features a single unified drag-and-drop list (ReorderableListView). An intuitive In-Game Bar Cutoff Divider separates the top 8 equipped reactions (▲ IN YOUR GAME BAR (8 MAX)) from the rest of the club pool (▼ OFF GAME BAR). Dragging a reaction from below the divider equips it and automatically displaces the 8th reaction; dragging an equipped reaction below the divider removes it and promotes the next available off-bar reaction. The 6 permanent reactions carry a 🔒 Roots badge and cannot be deleted, while custom reactions include a one-tap delete button. When a club member deletes a reaction from the shared pool while a match is underway, active games retain the reaction so players can continue tapping it until the match concludes, only backfilling from the remaining pool upon entering the next match.
  • Real-Time Reaction Freshness & Anti-Storm Recovery: Floating callout reactions are strictly real-time ephemeral visual effects. When joining a table as a spectator or returning to the app after a delay (e.g. backgrounding the app or waking a sleeping device), the overlay automatically suppresses stale reactions and away-period backlogs, ensuring players and viewers are never overwhelmed by a replay storm of historical emojis. Live reactions sent by table participants display immediately without delay.
  • Client Progress Indicators & Atomic Server Transactions: All state-mutating actions across the client—including table creation, joining seats, adding/removing AI bots, starting matches, submitting bids, choosing trump suits, playing cards, requesting AI hints, calling slow players, and sending chat messages—display immediate indeterminate progress indicators (CircularProgressIndicator, LinearProgressIndicator, and 'SUBMITTING...' / 'Thinking...' status cues) with in-flight interaction guards. On the backend, Cloud Functions orchestrate game state transitions within Firestore transactions to enforce idempotency and strict 52-card deck uniqueness, eliminating race conditions and duplicate card dealing under rapid user interactions or concurrent device retries.

4. Smart Notifications & "Call Player" (Nudge) ​

  • Granular Per-Game Turn Alerts: Turn push notifications alert players when it is their turn to bid, choose trump, or play a card. When a player is actively viewing a game, redundant turn push notifications and bottom snack bars for that specific match are suppressed client-side in pure Dart (NotificationService), allowing the in-game green board highlight to speak for itself. Notifications for any other concurrent matches continue to arrive cleanly as top OS banners displayed via flutter_local_notifications.
  • Game Lifecycle Updates: Immediate alerts when receiving a game invite, when a lobby match begins, or when a final winner is crowned.
  • AI Narrator "Call Player" Nudge: If a player is taking too long to play, waiting players can tap the "Call Player" button on the board. This prompts the AI Narrator to poke the slow player with witty Trinidadian banter drawn from 25+ authentic local everyday distractions (e.g., turning pelau before it burns, pulling clothes off the line before rain falls, peeping through curtains at neighbour business, or waiting on a Bus Route maxi), broadcasting live to room chat and delivering a high-priority push notification directly to their device. A 30-second cooldown protects players from spam, and redundant confirmation snack bars are eliminated.
  • Cross-Platform Push Architecture (Android & iOS): Notifications are delivered via Firebase Cloud Messaging (FCM). On iOS devices, the app utilizes native Apple Push Notification service (APNs) integration configured with aps-environment entitlements, remote-notification background modes, foreground presentation delegation via UNUserNotificationCenter, and asynchronous APNs device token synchronization with private user subcollections (/users/{userId}/private/fcm).

5. User Profiles, Privacy & App Store Compliance ​

  • Flexible & Secure Sign-In: Sign in easily and jump straight into the action with support for Email/Password and native one-tap Google Sign-In across Web, Android, and iOS release environments (configured with native iOS URL schemes, GID client descriptors, and seamless presentation lifecycle).
  • Initial Google Account Avatar: When signing in with Google, the photo from the user's Google account is automatically used as their initial avatar. Players can also re-sync or revert to their Google profile photo at any time from their profile settings.
  • AI Avatar Generator (gemini-3.1-flash-image): Players can generate stylized, vibrant cartoon avatars directly within the app using Firebase AI Logic:
    • Cartoon Animals: Create cartoon portraits of favorite animals (e.g. a majestic lion, clever fox, sly wolf, or wise owl).
    • Cartoon Persons: Generate stylized cartoon headshots based on custom descriptions, specifically designed with darker skin tones (deep melanin and rich brown complexions, e.g. army woman, astronaut, detective, or gamer).
    • In-App Interactive Preview: Allows players to preview generated artwork in a circular frame, refine prompts, and confirm before setting as their active avatar.
  • Custom Image Upload: Players can continue to upload their own images from their device photo gallery.
  • Firebase Cloud Storage & FirebaseUI Storage: All generated and uploaded avatars are saved to Firebase Cloud Storage under timestamped, user-scoped paths (avatars/{userId}_{timestamp}.jpg). Avatars are efficiently rendered and cached across the app using FirebaseUI Storage (StorageImage), with authenticated-only read access and user-isolated write validation in storage.rules.
  • Private FCM Token Isolation (/users/{userId}/private/fcm): Device push notification tokens (fcmTokens) are isolated in a private owner-only subcollection (/users/{userId}/private/fcm) so public player profile reads (/users/{userId}) only expose screenName, screenNameLower, displayName, and avatarUrl.
  • In-App Account Deletion (delete-account): In compliance with Apple App Store Guideline 5.1.1(v) and Google Play Data Safety requirements, players can permanently delete their account from the Delete Account control in their Profile screen (DELETE confirmation dialog). The server removes their profile, private FCM tokens, blocked user entries, club memberships, custom storage avatars, and Firebase Auth account while anonymizing historical round records as "Deleted Player".
  • UGC Moderation — Report & Block Player (report-player, block-player): Players can report or block abusive users directly from any chat message (ChatOverlay) or from the Player Round Details Modal (🚩 Report or Block Player). Reporting creates an audit entry in /moderation_reports/{reportId}, and blocking immediately hides that user's chat messages and reactions locally via /users/{userId}/blocked_users/{blockedUid}.
  • Minimum Client Version Gate (/app_config/client): The app watches /app_config/client.minBuildNumber and displays an "Update Required" banner whenever a client's build number falls behind a breaking server-side game protocol or security update.
  • Administrative Backfill Tool: An administrative CLI utility (scripts/backfill_google_avatars.sh / functions/bin/backfill_google_avatars.dart) allows operators to scan existing accounts and backfill missing avatar URLs for players who previously authenticated via Google Sign-In.
  • Offline-Resilient Profile Initialization & Cache Fallback: Profile loading during app startup (AuthGate) leverages a multi-tiered resilience strategy. Remote Firestore queries feature non-blocking timeouts with immediate fallback to local Firestore cache (Source.cache) and persisted Firebase Authentication credentials, ensuring users are never blocked or stuck on timeout error screens during cold starts or transient cellular connectivity drops.
  • Version Identification, Release Notes & Diagnostics Reporting: Players and beta testers can quickly identify and copy their exact app version and build number (vX.Y.Z (Build N)) from the footer of the Sign-In screen, the bottom of the User Profile screen, or via the About Pedro info dialog in game lobbies and the Home screen. The About Pedro dialog also features a "What's New" release notes section that is automatically updated on master whenever a release build is tagged (./scripts/worktree.sh release v1.X.Y), summarizing the user-facing features and gameplay updates since the previous tagged release (or noting bug fixes and stability improvements when a release contains no user-facing changes). On the version footer, a single tap copies the version string, while a long press copies a full diagnostic bundle (Version, Build, Platform, Firebase UID, Active Game ID, and live Firebase App Check token status) for frictionless bug reporting.

6. Adaptive & Accessible Design ​

  • Clean, intuitive interface with smooth animations, clear card visuals, and adaptive layouts tailored for phones, tablets, and web browsers.
  • Subtle Error Feedback & Slow-Network Resilience (SubtleErrorSnackBar):
    • Calm, Floating Error Presentation: Replaces unconstrained full-screen red error banners and raw stack traces with a discreet, floating pill (SnackBarBehavior.floating, rounded corners, dark slate surface, max 2 lines) positioned cleanly so it never obstructs card interactions or table visibility.
    • Actionable Error Categorization: Automatically classifies exceptions without exposing Pigeon or Cloud Functions plugin tags ([firebase_functions/...]):
      • Network / Connection Hiccups: Displays a calm offline notice ("Connection hiccup — your action didn't go through. Check your signal and try again.") with an immediate inline Retry action.
      • Table State Syncing: On high-latency 3G connections where local hand snapshots lag behind table state, stale plays show a reassuring sync prompt ("Table state is syncing on a slow connection — wait a moment and try again.").
      • Rule & Input Validation: Clean single-line messages (e.g. "Bid must be higher.", "Must follow suit.") without stack traces.
    • Optimistic Play Protection & Slow-Network Stream Synchronization:
      • In GameRepository.watchGameSession, cards recorded as played in the round (playedCards, currentLift, lastLift) are automatically filtered out of the local hand during trick play, ensuring played cards never linger as phantom tappable cards if secret hand snapshots lag behind over cellular networks.
      • Secret hand documents (games/{gameId}/hands/{uid}) are proactively re-fetched upon round and phase transitions (such as moving from discarding to trick play).
      • Client-side submission safety timers are extended to 15 seconds, and card submission guards stay locked until the card is confirmed removed from the player's hand.
      • Server-side trick resolution (isCardAlreadyPlayedByPlayerInRound) ensures duplicate or retried card play requests remain fully idempotent even when the acting player won the previous trick.
    • Non-Fatal Crashlytics Diagnostic Reporting: While users only see clean, actionable guidance, complete stack traces and diagnostic context are automatically captured in mobile release builds via non-fatal Firebase Crashlytics records (FirebaseCrashlytics.instance.recordError(..., fatal: false)).
  • Veranda Felt Table Stadium & Lower-Arc Club Crest Watermark: The active playing table is styled as a stadium-curved emerald felt surface with subtle radial depth and corner flourishes. Across the lower trick-clearing corridor, a delicate watermark displays club branding (─── ♠ CHALLO GALLERY ───) above the full room name (Shuffling Under the Mango Tree), grounding the table's identity without interfering with active trick cards or spectator sightlines. The top AppBar removes redundant brand logos, dedicating maximum breathing room to back navigation, quick share, and the contract status widget.
  • Translucent Baize Trick Mat & Circular Trump Medallion: The central trick play zone is delineated by a frosted translucent baize mat, while the AppBar contract tracker anchors the trump suit in a crisp circular white medallion with subtle depth and tooltip guidance, serving as the single source of truth for trump suit and contract progress.
  • 3-Row Stacked Atelier Game Cards & Full Room Name Visibility: Across the Home feed (Open Tables, Live Now, and Recent Games) and the All Games catalog, entries use an expanded 3-row stacked card architecture ([Status / Club Badge / Target Score] $\to$ [Full-Width Room Name] $\to$ [Participant Avatars / Seats + CTA]). This provides full ~330px horizontal headroom for authentic Trinidadian AI room names without clipping, alongside clear club tags ([♠ Challo Gallery • 👀]). In waiting lobbies (GameRoomScreen), the navigation bar displays a clean 'Table Lobby' heading while the body room access banner prominently showcases the full game title and club identity.
  • Adaptive Turn & Action Indicators & Atelier Emerald Turn Frame: To ensure players never miss their turn to act when their gaze is focused on the center trick mat or table cards, the local player's interaction area dynamically frames itself with an inset 3.0px Atelier Emerald border (#00694B), a soft ambient emerald glow (#00694B at 35% alpha, blurRadius: 12, spreadRadius: 1), and a high-contrast stadium pill badge (● YOUR TURN or ● YOUR TURN TO LEAD). This styling mirrors the 3.0px #00694B emerald turn ring and name pill border on active opponent seats for table-wide visual consistency. During lift review cooldown, the frame smoothly shifts to a warm amber review border (#FFCA53) and REVIEWING LIFT... pill badge, before settling back to a calm neutral hairline (1.0px #DBE3DE) while waiting.
  • Adaptive Multi-Row Trick Grid (5 to 8 Players): To preserve complete visual clarity and situational awareness during multiplayer games with 5 to 8 players, trick cards in the live lift area and the Previous Trick modal adaptively organize into a 2-row layout bounded by a safe central corridor. Cards automatically scale responsively, with side player badges adjusting their alignments and footprints in 7–8 player sessions so no cards or player attribution labels are ever blocked.
  • Compact Player Cards & Color-Coded Point Pips: Player cards maintain a compact, bounded height budget across all table configurations. During the Wadger (bidding) phase, each player's card displays their current bid (Bid: X) or Passed status while the clear center board highlights the current Leading Bid and bidder; once bidding concludes, individual bids disappear (leaving only the winning bidder's contract badge). During trick play, bulky multi-line text chips are replaced by a neat horizontal row of distinct, color-coded circular pips (High: Sky Blue, Low: Deep Indigo, Jack: Orange, Hang Jack: Red, 5: Green, 9: Purple, Game: Amber). Tapping any player card opens a rich Player Round Details Modal displaying full point breakdowns, explanations, discards, and shortcuts to captured lifts and the Game Point Race.
  • Modal-able Trick Board (Active Trick Modal): To ensure maximum visibility even on compact mobile devices, the central trick table features a zoom indicator (zoom_in). Tapping anywhere on the active trick area opens an enlarged Active Trick Modal that presents all played cards, called lead suit, and the current winning play in full detail.
  • Responsive Card Interactions, Directional Play Entry & Lift Sweep Animations: Instant visual feedback (upward card lift, dimming, and border emphasis) upon card selection in hand, paired with proactive tap debouncing and server-side idempotency to eliminate accidental double-submissions. As each player plays a card, the card flies into the center trick grid along a directional vector from that player's seat (or local hand tray) with a natural wrist-flick settle. When a trick completes, the winning card pulses with a golden highlight during a brief review window before the center trick cards gather into a fanned packet and sweep along a curved arc directly into the winning player's seat, leaving a clean "Lift Won by <Winner>" status pill until the next trick is led.
  • Tactile Table Sound Effects & Haptic Feedback (SoundService): Brings the card table to life without audio fatigue using short, warm acoustic foley and marimba cues bundled in assets/sounds/:
    • Core Table Foley: Crisp cardstock flick-on-felt for card plays (card_play.wav with $\pm 5%$ random pitch variation), soft felt brush when sweeping completed tricks (lift_sweep.wav), wooden poker-chip clicks that rise subtly in pitch with higher bids (bid_tap.wav), double wooden table knocks when passing (pass_knock.wav), and a warm resonant chord when locking in the trump suit (trump_lock.wav).
    • Turn Alerts & Pedro Highlights: A gentle ascending two-note marimba tap (your_turn.wav) when action rotates to the local player, distinct celebratory chimes whenever the Jack of trump (jack_captured.wav), Pedro (5 of trump) (pedro_captured.wav), or 9 of trump (nine_captured.wav) is won in a lift, round-end flourishes for making (bid_made.wav) or getting set on (bid_set.wav) a contract, and a championship fanfare (game_won.wav) when a match concludes.
    • Social Cues & Anti-Spam Cooldowns: Soft bubble pops (reaction_pop.wav) on floating callout reactions and muted acoustic plucks (chat_toast.wav) on incoming chat toasts, throttled by per-cue cooldown windows so rapid bot turns or emoji bursts never stack or clip.
    • Ambient Audio Citizenship & Independent Profile Toggles: Configured with AVAudioSessionCategory.ambient (mixWithOthers) on iOS and AndroidAudioFocus.none on Android so Pedro never pauses background music or podcasts and respects the hardware silent switch. Players can independently toggle Sound Effects and Haptic Feedback anytime from their Profile screen (persisted locally via SharedPreferences).
  • Themed Playing Card Decks & Vector French Suits (♠, ♥, ♦, ♣): When creating a game, one of four custom Card Deck Themes is randomly pre-selected by default (with live mini-card previews so the host can switch themes anytime before creating the table):
    • Classic Casino (classic): Warm ivory card faces, traditional crimson (♥ ♦) and jet-black (♠ ♣) vector suits, subtle inner frame, and classic crimson/navy filigree lattice card backs.
    • Caribbean Parlour (caribbean): Sunlit island parchment faces, hibiscus coral and deep ocean navy suits, tropical compass/sunburst medallions honoring Pedro's roots, and an ornate nautical compass & palm-frond card back.
    • Royal Velvet & Gold (royal): Regal cream faces with metallic gold double-filigree frames, ruby and obsidian suits, royal court crests, and a deep burgundy velvet & gold foil card back.
    • Four-Color Pro (four_color): High-contrast tournament deck featuring four distinct suit colors (♠ Black, ♥ Red, ♦ Blue, ♣ Green) for instant suit recognition during fast trick play.
    • Cards render with traditional top-left and inverted bottom-right corner indices featuring enlarged suit pips, high-visibility centerpiece suit icons (78%–88% opacity), classic solid French vector suit silhouettes (plush round-lobed Hearts with crisp top V-clefts, tall concave-faceted Diamonds, sleek cordate Spades with flared pedestals, and deeply notched three-leaf Club trefoils), and unobstructed bottom-left golden PEDRO badges paired with 8-point starburst medallions on both signature 5 and 9 cards, while automatically adapting to a clean high-contrast layout at compact modal scales (34×52).
  • Seasonal Themes & Trinidad Cultural Table Decorations (SeasonalThemeService): Celebrates both international holidays and Trinidad & Tobago's signature cultural calendar with authentic festive atmosphere while strictly adhering to non-intrusive gameplay and accessibility principles:
    • Remote Config Control (seasonal_theme & seasonal_theme_config): Allows instant, live remote activation across iOS, Android, and Web without publishing new app builds. Supports explicit holiday activations (halloween, diwali, christmas, carnival, trini_pride, eid, new_years, easter, july_august) with optional JSON parameter overrides for custom greetings, banners, and scheduled auto-expiry (endDate, e.g. "2026-11-09" in Trinidad AST time UTC-4, or an ISO-8601 timestamp) that automatically reverts to classic emerald felt once the holiday concludes.
    • User Opt-Out Switch (ProfileScreen): A persistent toggle (Seasonal Themes, stored in SharedPreferences) directly in player settings alongside Sound Effects and Haptic Feedback, allowing any player to opt out and preserve the classic emerald parlour felt year-round.
    • Screen-by-Screen Theme Zones & Ambient Animations: Seasonal themes extend beyond the lobby into live game tables across 6 distinct in-game visual zones:
      • Zone G1 / W1 (AppBar Header): A compact seasonal badge (SeasonalAppBarBadge(compact: true)) beside the table title and a 2px gradient accent line (SeasonalAppBarBottomBar) along the bottom edge of the AppBar.
      • Zone G2 (Table Perimeter & Corners): Soft radial corner vignette washes and an inset rounded perimeter frame that subtly grounds the playing surface.
      • Zone G3 & G4 (Table Surface Art & Slow Ambient Motion): High-contrast multi-layered vector marks rendered in the table corners with slow, hypnotic ambient animations (8-second continuous repeating cycle) driven by phase:
        • Halloween (halloween): Flickering candlelight inside carved jack-o'-lanterns, dangling spider swaying on silk webs, glowing Soucouyant fireball trail, and folklore silhouettes.
        • Divali — Festival of Lights (diwali): Terracotta clay deyas with warm pulsing flame halos, slowly spinning geometric Rangoli mandalas, and marigold garlands.
        • Trini Christmas & Parang (christmas): Decorated evergreen tree with glowing star topper, gently draped fairy lights, and red sorrel sprigs.
        • Trinidad Carnival (carnival): Swaying tropical Mas feather plumes, tenor steelpan icon, and floating golden bokeh confetti.
        • Sweet T&T (trini_pride): Waving Red, White & Black ribbon bunting, blooming red Chaconia flower clusters, and a fluttering hummingbird.
        • Eid-ul-Fitr (eid): Golden crescent moon, swaying hanging Fanoos lanterns with ambient glow halos, and geometric star filigree.
        • New Year & Old Year's Night (new_years): Midnight Port of Spain harbour fireworks bursts, clinking champagne toast flutes, and sparkling starlight rosettes.
        • Trini Easter & Kite Season (easter): Traditional hexagonal Caribbean Madbull kites bobbing on Savannah winds, cross-spars, fluttering bow tails, and pastel breeze ribbons.
        • July/August Vacation Lime (july_august): Swaying Maracas Bay coconut palm fronds, water coconut with straw, sunbeams, and turquoise ocean ripples.
      • Zone G5 (Center Trick & Wadger Mat): The center trick/bidding card area is framed with SeasonalCenterMatDecoration, featuring 4 micro-corner flourishes (22×22px), themed border tint, subtle background wash, and the seasonal emoji prefix on phase headers.
      • Zone G6 (Player & Spectator Hand Docks): When awaiting opponent turns, the bottom player tray displays a themed accent border and subtle wash that smoothly transitions via AnimatedContainer (240ms) into the prominent 3.0px Atelier Emerald active-turn frame (#00694B) with ambient outer glow and high-contrast ● YOUR TURN stadium pill badge whenever it is the local player's turn to act, while leaving table-level social callouts (ReactionBar) cleanly positioned below the gameplay frame.
    • Accessibility & Motion Safety: All ambient animations continuously monitor MediaQuery.disableAnimationsOf(context) and automatically freeze at a graceful midpoint (0.50 phase) when Reduce Motion is enabled. All visual art elements are restricted to perimeter areas to guarantee 100% unobstructed readability of cards, suit indicators, bids, and player avatars.
    • Curated Cultural Motifs & Dual-Layer Visuals: Combines bundled 16:9 hero background banners (app/assets/themes/*.png) with crisp CustomPainter vector motifs:
      • Halloween (halloween): Fuses classic spider webs and carved pumpkins with iconic Trinidadian folklore characters: Soucouyant fireball orb with ember trail, Douen (Dwen) wide woven straw hat and backward footprints, La Diablesse wide-brimmed hat & lace fan silhouette, and subtle glowing Lagahoo eyes with faint chain links.
      • Divali — Festival of Lights (diwali): Glowing terracotta clay deyas (dias) with warm layered flame halos, intricate geometric rangoli corner mandalas, and marigold garlands.
      • Trini Christmas & Parang (christmas): Decorated evergreen Christmas tree with gold star topper, draped fairy string lights along the top border, and crimson sorrel & poinsettia sprigs.
      • Trinidad Carnival (carnival): Tropical Mas feather plumes, tenor steelpan drum icon, and golden bokeh confetti.
      • Sweet T&T (trini_pride): Diagonal Red, White & Black ribbon bunting, blooming red Chaconia flower corner clusters, and an emerald hummingbird.
      • Eid-ul-Fitr (eid): Golden crescent moon, hanging fanoos lanterns, and 8-point geometric star filigree.
      • New Year & Old Year's Night (new_years): Midnight Port of Spain harbour fireworks bursts, celebratory clinking champagne toast flutes, festive curly streamers, and sparkling starlight rosettes.
      • Trini Easter & Kite Season (easter): Traditional hexagonal Caribbean tissue-paper Madbull kites soaring across Savannah skies, cross-spars, fluttering bow tails, and pastel breeze ribbons.
      • July/August Vacation Lime (july_august): Sun-drenched Caribbean coconut palm fronds, refreshing green water coconut with a straw, warm radiating sunbeams, and turquoise Maracas Bay ocean wave ripples.

7. Signature Branding & Visual Identity ​

  • Iconic Mobile & Web Presence: Features a custom luxury emblem centered on a polished gold capital 'P' adorned with a playing card spade on a deep emerald green felt background, evoking the timeless atmosphere of classic card tables across iOS, Android, and Web platforms.

8. Live Spectating, Hand Peeking (👀), Spectator Scaling & Chat Controls ​

  • Always-On Live Spectating: Spectating is always enabled. Public matches (visibility == 'public') appear in the global Live Now feed (bounded to active tables) where anyone can tap "Watch Live". Private matches (visibility == 'private') are hidden from the public feed; invited players or anyone with the 6-character Room Code or Share Link (?code=XXXXXX) can watch live once the match starts.
  • Spectator Hand Peeking (👀) for Private & Club Tables: Mirroring traditional in-person lime play where spectators stand behind a player's chair, hand peeking is automatically ON for Private and Club games and automatically OFF for Public Open games. In Private/Club games, non-seated spectators can select any seated player from the 👀 Peek Hand bar in the spectator dock to immediately view their cards read-only (via games/{gameId}/hands/{uid} security rules) while asynchronously syncing peek state via set-viewer-peek. Whenever a spectator peeks at a player's hand, a 👀 N badge appears on that player's avatar card around the board, and the Live Spectators sheet (👁️ N) displays 👀 Peeking at {PlayerName}'s hand beneath the spectator's name.
  • Decoupled Spectator Lease Subcollection (games/{gameId}/viewers/{uid}): To eliminate Firestore write amplification when dozens of spectators watch a single match, 30-second viewer heartbeats (heartbeat-viewer) write exclusively to individual games/{gameId}/viewers/{uid} subcollection documents rather than mutating the parent games/{gameId} document on every pulse.
  • Host Spectator Chat Controls (set-spectator-chat-mode): Game hosts can configure spectator chat privileges directly from the game board overflow menu:
    • All Chat & Reactions (all): Default for Club and Private tables—spectators can send text chat messages and float emoji reactions.
    • Reactions Only (reactions_only): Default for Public Open tables—spectators can float table callout reactions (🃏 Card!, ⚖️ Judgement!, 🤦 Madness!, 🧪 Gramoxone!) without posting text messages to the room chat.
    • Muted (muted): Spectators can watch silently with both text chat and reactions disabled.
  • Dedicated Spectator Layout: Spectators enter the table with an unconstrained perimeter layout showing all 4–8 players arranged around the table. Directly above the persistent Game Chat drawer, the bottom hand bar is swapped with a specialized Spectator Mode dock showing live turn indicators, optional hand peeking, and a full-width real-time emoji reaction strip.
  • Live Spectator Presence & Active Viewers List: A live viewer badge (👁️ N) appears in the app bar. Tapping the badge opens a bottom sheet listing all active spectators and whose hand they are peeking at in real time.
  • Swipe-Away / Force-Close Resilience: Dual-layer presence tracking pairs Flutter's AppLifecycleListener (instant unregister when the app is backgrounded, hidden, or detached—ignoring transient iOS inactive states such as taking screenshots or pulling down Notification Center) with a 30-second heartbeat lease (60-second TTL in Firestore) to self-heal ghost viewer counts even if a device is abruptly powered off or killed.
  • Deep Linking & Visual Social Sharing ("VIP Tickets" & "Brag / Roast Cards"): Players and spectators can tap Share across game lobbies, active tables, completed game summaries, round recaps, and leaderboards to open the interactive Share Preview Sheet (SharePreviewSheet):
    • High-DPI Visual Poster Cards (1140px PNG): Captures a rich, branded RepaintBoundary poster card (PedroShareCardFrame at 3.0x pixel ratio) styled in Emerald Casino Felt, Crimson Shame, Royal Rivalry Purple, or Gold VIP Ticket palettes, and shares both the PNG image and deep link natively via share_plus (XFile.fromData + ShareParams) to WhatsApp, iMessage, Instagram, and Web Share sheets.
    • Editable 🇹🇹 Trini Picong Captions: Pre-populates an editable caption field with contextual Trinidadian Pedro banter ("Contract buss!", "Neck in the noose!", "Clean sweep!") that players can customize before sharing, with a one-tap Reset to restore the default picong and a Copy Text option.
    • Five Shareable Surfaces & Interactive Variant Selectors:
      1. Match Summary & Winner Podium (MatchSummaryShareCard): Switch between the 🏆 Winner Spotlight card and the 📊 Full Final Scoreboard card from the completed GameSummaryView or GameBoardScreen.
      2. Single-Round Recap (RoundRecapShareCard): Share any live or archived RoundSummaryDialog showing the contract badge (MADE vs. BUSS), trump suit, point breakdown (High, Low, J, HJ, 5, 9, Game), and key round highlights.
      3. Hall of Shame & Hall of Fame (LeaderboardAccoladeShareCard): From the LeaderboardView header banner, switch between the 🥇 Category Top-3 Podium, a 🎯 Single-Player Roast / Spotlight (picking any ranked player in that category to roast or celebrate individually), or the 📋 All-Categories Digest.
      4. Rivalry "Tale of the Tape" & Player Dossier (RivalryTapeShareCard): Share head-to-head card heist comparisons (Jacks Hung, 9s Stolen, 5s Stolen, Match Wins, Total Heist Points) or a single player's career dossier directly from the Rivalries header or the _showHeadToHeadSheet modal.
      5. VIP Table & Club Invitations (InviteTicketShareCard): Share perforated gold-foil VIP passes for Waiting Game Lobbies (showing open seats and room code), Live Spectator Passes (showing current round and score leader), and Club Invitations (showing club name, member count, and invite code).
    • Native Universal Links (iOS) and Android App Links (assetlinks.json / apple-app-site-association) route players directly to their seat and non-players directly into live spectating.
  • Chronological "All Games" Activity Feed: The Home feed and dedicated All Games screen list matches chronologically by their most recent gameplay activity (updatedAt ?? createdAt), organized into Live Matches, Open Tables, and My Games tabs with relative timestamps (e.g., "Just now", "5m ago").
  • Completed Game Summary View: Opening any completed match (status == 'finished') from Recent Games on the Home feed, All Games, a room code, or a shared deep link presents a dedicated Game Summary screen rather than the pre-game lobby or an empty card table. The summary showcases the Match Champion banner (winner, final score vs. target score, table visibility/club badge, and total rounds played), a ranked Final Standings scoreboard with aggregated lifts won and contracts made, a Round-by-Round Recap loading archived rounds (games/{gameId}/rounds/round_{N}) with one-tap access to each round's full breakdown, and the persistent Game Chat log with AI Narrator commentary.

9. Club-Scoped & Global Leaderboards, Hall of Shame & Head-to-Head Rivalries ​

  • Strictly Isolated Club vs. Global Leaderboards: Using the ScopeSelectorBar at the top of the Rankings tab (or the synced scope switcher on the Home Bento Stats card), players can switch between each of their clubs (♠️ Challo Gallery, etc.) and 🌐 Global Open Play:
    • Club Games (visibility == 'club'): Roll up exclusively to clubs/{clubId}/leaderboards/{periodId} so a club's Hall of Fame, Hall of Shame, and Nemesis & Prey rivalries remain 100% pure to games played inside that club.
    • Public Open Games (visibility == 'public'): Roll up exclusively to the global leaderboards/{periodId} board.
    • Private Games (visibility == 'private'): Archive round history to games/{gameId}/rounds/round_{N} without affecting club or global leaderboards.
    • AI Bot Exclusion (bot_*): Synthetic AI bot seats (bot_sonny, bot_merle, bot_breezy, bot_kyle) are automatically excluded from leaderboard player stats and head-to-head rivalry records while human participants at the same table continue to earn full round stats.
  • Persistent Round Archiving (games/{gameId}/rounds/round_{N}): Every completed round is permanently archived as an immutable document capturing full trick histories (completedLifts), per-player round stat deltas (playerSummaries), directed card heists (heists), visibility/club scope, and winner/victim scalar identifiers.
  • Weekly & All-Time Rankings: Players can switch effortlessly between This Week, Last Week, and All-Time timeframes in the Rankings tab, as well as view live personal win-rate and points counters in the Home feed Bento grid.
  • 🏆 Hall of Fame (Triumphs): Tracks 9 positive accolades across spotlight cards, a Top-3 podium, and full rankings:
    • The Jack Hanger (hangJacks), Higher than High (highTrumps), Lower than Low (lowTrumps), Table Boss (gamesWon), Pedro Catcher (fivesWon), Nine Hunter (ninesWon), Contract Boss (bidsMade), Point Hoarder (gamePointsWon), and One-Round Wonder (singleRoundWins — winning a match with a 15+ point target score in a single round, with ties broken by the highest points won in those single-round victories).
  • 💀 Hall of Shame (Unfortunate Distinctions): Celebrates table picong by tracking 4 unfortunate distinctions and the exact count of times each player suffered them:
    • Neck in the Noose (jacksHung — most Jacks hung by opponents), Nine Donor (ninesLost — most 9s of trumps lost), Pedro Donor (fivesLost — most 5s of trumps lost), and Biggest Buss (bidsSet — most contracts set).
  • ⚔️ Head-to-Head Rivalries ("Nemesis & Prey"):
    • Tracks directed player-vs-player card heists (Jacks hung, 9s stolen, 5s stolen, cumulative heist points) and match victories.
    • Highlights each player's personal 😈 Your Nemesis and 🎯 Favorite Prey, plus a ranked 🔥 Hottest Table Feuds list.
    • Tapping any player or feud opens the ⚔️ Tale of the Tape modal comparing You vs. Opponent side-by-side.
  • Atomic Rollups, Game Deletion Reversal & CLI Tools:
    • Round archives and target club/global leaderboard increments commit in a single atomic Firestore WriteBatch inside finalizeRound().
    • Deleting a game (deleteGame) automatically reverses its persisted rounds from the matching club or global leaderboard in the same batch (cleanly ignoring legacy games created before round archiving).
    • Administrative CLI scripts (cd functions && dart run bin/seed_founders_club.dart [--dry-run] and dart run bin/rebuild_leaderboards.dart [--dry-run]) provision the Challo Gallery Founders Club (inviteCode: 'CHALLO', backfilling existing historical rollups) and deterministically reconcile leaderboard rollups.

10. Backend Architecture, Anti-Cheat Isolation & Cloud Functions Endpoints ​

  • Anti-Cheat Subcollection Hand & Deck Isolation: To prevent network-inspector cheating in ranked Public Open games, card hands and the undealt deck are stripped from the public games/{gameId} document (which exposes only handCount: N and hand: []):
    • Undealt Deck (games/{gameId}/server/deck): Locked down to server-only access (allow read, write: if false; in firestore.rules), storing the undealt talon strictly for Cloud Functions during post-trump re-dealing.
    • Player Hands (games/{gameId}/hands/{uid}): Protected by firestore.rules so each seated player can only read their own hands/{uid} document (request.auth.uid == playerUid), while non-seated spectators (!(request.auth.uid in game.playerIds)) can read player hands only when watching 'private' or 'club' tables.
  • Server-Side Authoritative Game, Bot, Club & Moderation Logic: All game, club, and moderation state transitions (game creation, joining and leaving waiting tables via join-game and leave-game, game deletion via delete-game, opening a waiting club table to the public via open-game-to-public, AI bot management via manage-game-bot, turn timeout enforcement via resolve-turn-timeout, club creation/joining/leaving/administration via create-club, join-club, leave-club, update-club, manage-club-member (supporting member removal, admin promotion/demotion, in-app club invitations, uninviting, and invite declining), and delete-club, account deletion via delete-account, UGC reporting/blocking via report-player and block-player, player invitations, bidding, trump selection, card play, scoring, player nudges, and spectator presence) are orchestrated server-side in Cloud Functions to guarantee state integrity.
  • Spectator Presence, Hand Peek & Chat Control Endpoints: Dedicated callable endpoints (join-game-as-viewer, set-viewer-peek, heartbeat-viewer, leave-game-viewer, set-spectator-chat-mode) track live spectators in games/{gameId}/viewers/{uid}, hand peeking (👀), and spectator chat permissions securely.
  • Dart Cloud Functions & Cloud Run Deployment: Cloud functions are authored in Dart using firebase_functions and deployed directly as Google Cloud Run services (https://<function-name>-260654198138.us-central1.run.app).
  • Dynamic Callable Routing: The Flutter client seamlessly routes callable invocations through PedroFunctionsExtension.callable:
    • In local development and automated testing, functions automatically target the local Firebase Functions Emulator suite (localhost:5001 or 10.0.2.2:5001).
    • In production release builds across Android, iOS, and Web, functions target deterministic Cloud Run endpoints (https://<function-name>-260654198138.us-central1.run.app).
  • End-to-End Authentication & Transport Security: Cloud Run services allow public HTTP transport invocation (allUsers with roles/run.invoker, verified with retry loops in deploy_functions.sh) so client callable requests reach the Dart container, where request credentials are cryptographically authenticated against Firebase Authentication (request.auth). Client repositories proactively verify authentication state (_auth.currentUser) and force fresh ID token resolution before dispatching sensitive lifecycle operations like game deletion.

11. Mobile Beta Distribution & Store Release Pipeline ​

  • Apple TestFlight (upload_to_testflight / pilot): iOS builds compile directly to App Store distribution IPAs signed with Pedro AppStore Profile (ExportOptions.plist), declaring non-exempt encryption compliance (ITSAppUsesNonExemptEncryption: false). Builds upload to App Store Connect and are automatically submitted and distributed to external testers via the "player-players" Public Link group (distribute_external: true, with internal testing configurable via ios_external: false / --internal). Symbolicated dSYMs are continuously uploaded to Firebase Crashlytics.
  • Google Play Testing Tracks (upload_to_play_store / supply): Android builds compile to signed Android App Bundles (.aab) verified against key.properties. Fastlane auto-increments versionCode against existing Google Play releases and publishes to the Open testing (beta) track by default (with internal and alpha tracks remaining configurable via android_track / --track) with release notes attached.
  • Play App Signing & Deep Link Verification: Google Play App Signing key SHA-256 fingerprints are integrated into assetlinks.json and Firebase Console so Android App Links (https://pedro-f65a6.web.app/join/...) and Google Sign-In authenticate seamlessly on Play Store builds.
  • Multi-Channel & Tester Migration Support: CI/CD pipelines in .github/workflows/distribute_beta.yml support --channel store, --channel firebase, or --channel both to run store testing in parallel with Firebase App Distribution. The scripts/distribute/export_firebase_testers.sh utility exports Firebase testers directly into ready-to-import CSV formats for Google Play Console and App Store Connect TestFlight.