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!

---

🎮 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

# Install dependencies
npm install

# Start development server
npm run dev

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

Production Build

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)