feat(api): implement resilient client-side offline fallback engine wh…

[Siddh2024]

Description

🚀 The Problem

Currently, the Shabble daily shape-guessing game relies entirely on a PostgreSQL database connection. If the database is unconfigured (such as during local development without a POSTGRES_URL) or goes offline, the app triggers a hard, blocking "Database is inactive" dialog which prevents the user from playing the game entirely.

🛠️ The Solution

This Pull Request introduces a highly resilient Client-Side Offline Fallback Engine directly within the API layer inside src/api/daily-api.ts.

Now, if the backend server API returns a connection or server error (e.g., 500 or ERR_BAD_RESPONSE), the application catches the error and seamlessly transitions the player into an Offline Sandbox Mode. All core templates, styling, UI layouts, daily shape rules, and original components are 100% untouched and remain exactly as they were, keeping the game fully operational and responsive under all network conditions.

---

💎 Features Implemented

1. Silent Error Catching & Transition

• Wrapped Axios API routes (/api/daily/status, /api/daily/hint, and /api/daily/guess) with secure try-catch handlers.
• Automatically handles connection failures and swaps standard server calls for the local sandbox flow.
• Bypasses the hard crash modal and shows a friendly toast notification: "Database is offline. Offline sandbox mode activated: spelling daily virtual matrices!" so players can immediately play.

2. Algorithmic Client-Side Parity

• fetchOfflineBoard: Generates a daily grid layout on the client with a contiguous chain of connected secret tiles based on the chosen board size and current date.
• getOfflineAdjacentCount: Evaluates MineSweeper-like adjacent 'X' counts within the standard 9-grid using the exact coordinate logic as the backend solver.

3. Local Persistence & Metrics Sync

• Keeps gameplay state, active guesses, hints, and solved tiles persistent using localStorage under shabble-offline-puzzle-${date}-${boardSize} keys.
• Integrates a client-side statistics tracker under shabble-offline-stats that updates and preserves streaks, game play counts, win-distribution, and stars across page reloads.

---

🧪 Verification & Testing

Automated Checks

• Verified type safety by running npx tsc --noEmit. The code compiles cleanly with zero TypeScript errors.

Manual Verification

1. Zero Database Simulation: Disabled POSTGRES_URL connection locally to simulate an inactive database.
2. First Load: Confirmed the blocking crash modal is gone, replaced with a non-intrusive notification toast.
3. Gameplay: Verified grid click interactions, hint counts displaying adjacent tiles correctly, and guess submissions.
4. Winning State: Confirmed winning the board triggers the correct confetti celebration, calculates earned stars, and successfully saves game statistics.
5. Persistence: Confirmed that refreshing the page mid-game or after a win properly retrieves all game states and streaks from localStorage.

@coder-zs-cse , Approve this pr for the issue #28 , under the tag GSSoC 26'.

[vercel]

@Siddh2024 is attempting to deploy a commit to the coderzs' projects Team on Vercel.

A member of the Team first needs to authorize it.

[coder-zs-cse]

why is this feature required? seems completely unecessary

[Siddh2024]

why is this feature required? seems completely unecessary

@coder-zs-cse , it will help down other contributors as well , to produce locally , without connection of database . Also this serves as the feature to access the game offline or in case of database error.

[coder-zs-cse]

yeah but you cannot play the Daily mode without the connection. Daily mode of puzzle means there is a fixed puzzle of the day, everyone in the world is supposed to play the exact same puzzle and share the results. It cannot be coupled into a offline play

[coder-zs-cse]

For offline play, we can havea seperate button for 'Play Offline' where user chooses the board size and system generates the puzzle, and user is able to play offline. However we need to make sure all the logic is reused. We shuldn't be making duplicate logic for game operations.
Honestly we need a class based design first, have added a issue for that. currently the methods in backend are scattered

[coder-zs-cse]

contributors can easily spin up a postgresql database locally and use it. or else use a db string from neon.com