12 Monthly Surprises 🎁

A birthday present project featuring 12 monthly tiles that unlock progressively throughout the year. Each tile links to a puzzle game, and when solved, reveals a 4-digit code.

Features

• Progressive Unlocking: Tiles unlock one month at a time based on the current date
• Puzzle Integration: Each tile links to a Clues by Sam game
• Code Reveal: Once a puzzle is solved, the tile displays the 4-digit code
• Progress Tracking: Uses localStorage to remember which puzzles have been solved
• Responsive Design: Works on desktop, tablet, and mobile devices
• Visual States: Three distinct visual states (locked 🔒, unlocked 🎁, resolved ✅)

Screenshots

Desktop View

Unlocked Puzzle Modal

Resolved Tile

Mobile View

How to Use

1. Host the Website: Upload index.html, styles.css, and script.js to any web hosting service (GitHub Pages, Netlify, Vercel, etc.)
2. Share the Link: Give the website URL to your friend
3. Monthly Unlocks: Each month, a new tile will automatically unlock
4. Solve Puzzles: Click on unlocked tiles to access the puzzle game
5. Enter Codes: After solving a puzzle, enter the 4-digit code to mark it as complete

Setup and Customization

1. Set the Start Date

Open script.js and modify these variables at the top of the file:

const PROJECT_START_YEAR = 2025;  // Year when the project starts
const PROJECT_START_MONTH = 1;     // Month when the project starts (1 = January)

2. Configure Game Links and Codes

In script.js, update the gameConfig array with your actual Clues by Sam game URLs:

const gameConfig = [
    { month: 'January', gameUrl: 'https://cluesbysam.com/your-game-1', code: '1234' },
    { month: 'February', gameUrl: 'https://cluesbysam.com/your-game-2', code: '2345' },
    // ... etc
];

Important: The code field is for your reference only. The app doesn't validate codes - it accepts any 4-digit number. You can check the Clues by Sam archives to know when your friend solves each puzzle.

3. Customize Colors and Styling

Edit styles.css to change:

• Background gradient (look for background: linear-gradient(...))
• Tile colors for different states (.tile.locked, .tile.unlocked, .tile.resolved)
• Font sizes and spacing

Local Testing

To test locally:

# Navigate to the project directory
cd /path/to/project

# Start a simple HTTP server
python3 -m http.server 8080

# Open browser to http://localhost:8080

Debug Commands

Open the browser console and use these commands:

// Unlock all tiles for testing
debugUnlockAll();

// Reset all progress
debugReset();

Hosting Options

GitHub Pages (Free) - Automated Deployment

This project includes a GitHub Actions workflow that automatically deploys to GitHub Pages.

Setup Steps:

1. Push your code to a GitHub repository (if not already done)
2. Go to your repository Settings > Pages
3. Under "Build and deployment", select Source: "GitHub Actions"
4. The workflow will automatically deploy when you push to the main branch
5. Your site will be available at https://username.github.io/repository-name/

Manual trigger:

• You can also manually trigger the deployment from the "Actions" tab > "Deploy to GitHub Pages" > "Run workflow"

Netlify (Free)

1. Drag and drop your project folder to Netlify
2. Your site will be live instantly

Vercel (Free)

1. Connect your GitHub repository to Vercel
2. Deploy with one click

Browser Compatibility

• Chrome/Edge: ✅ Fully supported
• Firefox: ✅ Fully supported
• Safari: ✅ Fully supported
• Mobile browsers: ✅ Fully supported

Privacy

• All data is stored locally in the browser using localStorage
• No data is sent to any server
• Codes are stored client-side only

License

This is a personal project created as a birthday gift. Feel free to use and modify for your own personal projects!