# Quartiles — Daily Word Fragment Puzzle Game

A sleek, Apple News+ inspired webapp clone of the addictive word puzzle game **Quartiles**. Combine letter tiles into words, discover the 5 hidden 4-tile Quartiles, claim the massive 40-point completion bonus, and climb the ranks from Novice to Expert!

![Quartiles Web App](https://img.shields.io/badge/Game-Quartiles-amber?style=for-the-badge)
![Built with Vite](https://img.shields.io/badge/Built_With-Vite_%26_Vanilla_JS-646CFF?style=for-the-badge&logo=vite)
![Design System](https://img.shields.io/badge/Design-Apple_iOS_Aesthetic-10B981?style=for-the-badge)

---

## 🎮 How to Play

1. **The Board**: You are presented with a **4×5 grid of 20 letter tiles**. Each tile contains a 2 to 4 letter fragment (morpheme, syllable, or root).
2. **Build Words**: Tap 1, 2, 3, or 4 tiles in sequence to construct valid English words.
3. **Submit**: Tap the **✓ ENTER** button (or press `Enter` on your keyboard) to validate.
4. **Tile Reusability**: Tiles stay on the board and can be reused to form as many different words as possible!

### 🏆 Points System

| Tile Count | Type | Points |
| :---: | :---: | :---: |
| **1 Tile** | Single-fragment word | **1 pt** |
| **2 Tiles** | Compound word | **2 pts** |
| **3 Tiles** | Multi-part word | **4 pts** |
| **4 Tiles** | **"Quartile"** (Target word) | **8 pts** |

### ✨ The 40-Point Quartiles Bonus
Every puzzle contains **5 target 4-tile Quartiles**. Finding all 5 target Quartiles awards an instant **40-point completion bonus** with celebratory confetti!

### 📈 Ranks & Tiers
- **Novice**: 0 – 24 pts
- **Apprentice**: 25 – 49 pts
- **Builder**: 50 – 69 pts
- **Artisan**: 70 – 84 pts
- **Wordsmith**: 85 – 99 pts
- **Expert**: **100+ pts** *(The primary daily milestone!)*
- **Perfect**: 100% of all constructible words found on the board!

---

## 🌟 Key Features

- **Apple News+ Inspired Aesthetics**: Crisp typography, frosted glass (`backdrop-filter: blur`), curated color palettes, tactile tile presses, and smooth animations.
- **Dark Mode & Light Mode**: Seamless toggle matching iOS system styling.
- **Auto-Lock Solved Quartiles**: Toggle locking to automatically pin found 4-tile Quartiles in neat rows at the top of the grid with padlock badges, while allowing remaining tiles to shuffle freely.
- **Shuffle & Sort A-Z**: Reorder unlocked tiles to spot new combinations or sort them alphabetically.
- **Interactive Words Found Drawer**: Filter solved words by tile count (*All, Quartiles, 3-Tiles, 2-Tiles, 1-Tile*), view point values, and tile fragment breakdowns.
- **Progressive Hint System**: Contextual hints guiding you to unfound Quartiles and words without spoiling the puzzle.
- **Daily Puzzles & Archive**: A new generated puzzle every day (seeded by date, so everyone gets the same board), with the last three weeks available in the calendar.
- **Unlimited Random Mode**: Instant on-the-fly puzzle generator yielding infinite unique playable boards.
- **Custom Puzzle Creator & Sharing**: Create your own puzzle using 5 custom four-tile words and share with friends via URL hash.
- **Tactile Web Audio Feedback**: Realistic acoustic clicks, pops, harmonious chords, and celebratory fanfare built using the native Web Audio API (0 external sound files needed).
- **Canvas Confetti**: High-performance canvas particle system for Quartile and Expert victories.
- **Keyboard Shortcuts**:
  - `Enter`: Submit constructed word
  - `Backspace`: Remove last tile from tray
  - `Escape`: Clear active tray
  - `Spacebar`: Shuffle board tiles
- **Progress Persistence**: Automatically saves your game progress, score, and solved words in `localStorage`.

---

## 🚀 Getting Started

### Prerequisites
- Node.js (v18+)
- npm

### Installation & Local Run
```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Open your browser at http://localhost:5173
```

### Production Build
```bash
npm run build
npm run preview
```

---

## 📁 Project Structure

```
quartiles/
├── index.html                 # App shell with SEO and viewport configuration
├── package.json               # Scripts and dependencies (Vite)
├── src/
│   ├── main.js                # App bootstrap, event wiring, keyboard handlers
│   ├── styles/
│   │   ├── main.css           # Design tokens, variables, typography, reset
│   │   ├── board.css          # 4x5 grid layout, tactile tiles, active builder
│   │   └── components.css     # Score bar, action buttons, drawer, modals
│   ├── components/
│   │   ├── Header.js          # Brand title, date badge, utility controls
│   │   ├── ScoreRankBar.js    # Score, rank progression, 5-segment Quartiles tracker
│   │   ├── WordBuilder.js     # Construction tray with drag & drop reorder
│   │   ├── TileGrid.js        # 20-tile responsive board with locked rows
│   │   ├── ActionBar.js       # Shuffle, Sort A-Z, Lock Quartiles, Hint
│   │   ├── WordsDrawer.js     # Categorized found words bottom sheet
│   │   ├── Modals.js          # How to Play, Calendar, Builder, Stats, Settings
│   │   ├── Toast.js           # Spring floating notifications
│   │   └── UpdateBanner.js    # "New version available" reload prompt
│   ├── data/
│   │   ├── puzzles.js         # Target word pool (all puzzles are generated from it)
│   │   └── lexicon.js         # SCOWL recognized English vocabulary set
│   ├── version.json           # App version (bumped by the pre-commit hook)
│   └── engine/
│       ├── solver.js          # Tree-pruning word solver and rank calculator
│       ├── generator.js       # Daily (seeded), unlimited and custom puzzle generator
│       ├── daily.js           # Daily puzzle lookup and calendar list
│       ├── version.js         # Polls /version.json for new deploys
│       ├── audio.js           # Web Audio API acoustic synthesizer
│       └── confetti.js        # Canvas particle confetti engine
└── scripts/
    ├── build-all-data.mjs     # Builds the target word pool (src/data/puzzles.js)
    ├── build-client-lexicon.mjs
    └── bump-version.mjs       # Version bump (run by .githooks/pre-commit)
```