Modernize app and add Tailwind v4 game mode

README.md

@@ -1,39 +1,49 @@
-# [https://www.css2wind.com/](https://www.css2wind.com/)
+# css2wind
 
-## Accessing locally
+[css2wind.com](https://www.css2wind.com/) is a small Next.js minigame for practicing CSS-to-Tailwind translations.
 
-You need to have these installed:
+## Setup
 
-- [git](https://git-scm.com/downloads)
-- [node.js](https://nodejs.org/en/download/)
+Requirements:
 
-If you don't have one, it is recommended that you also download an IDE:
+- Bun 1.3 or newer
 
-- [vs code](https://code.visualstudio.com/download)
+Install dependencies and start the local app:
 
-Then, you can:
+```bash
+bun install
+bun run dev
+```
 
-- [clone this repo](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) if you just want to look around
-- [fork this repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo) if you want to contribue code and open pull requests
+Open [http://localhost:3000](http://localhost:3000).
 
-Now, access the directory to which you just cloned the repository:
+## Scripts
 
-`cd css2wind`
+- `bun run dev`: start the Next.js development server.
+- `bun run typecheck`: run TypeScript without emitting files.
+- `bun run lint`: run ESLint.
+- `bun run test`: run Vitest unit tests.
+- `bun run build`: create a production build.
 
-Finally, you should install dependencies:
+## Game Modes
 
-`npm install`
+The homepage defaults to the original Tailwind v3 game. Tailwind v4 is available through the compact `v3` / `v4` selector in the game UI.
 
-And build the website:
+Progress is stored per mode in localStorage:
 
-`npm run dev`
+- `css2wind:game:tailwind-v3`
+- `css2wind:game:tailwind-v4`
 
-Now, this url should be running css2wind locally!
+The `/api/v1` endpoint remains compatible with the previous shape and returns the v3 dictionary.
 
-[http://localhost:3000/](http://localhost:3000/)
+## Verification
 
----
+Before merging, run:
 
-## Contributions
-
-Issues and pull requests are appreciated!
+```bash
+bun install
+bun run typecheck
+bun run lint
+bun run test
+bun run build
+```

docs/adr/0001-single-worker-modernization.md

@@ -0,0 +1,19 @@
+# 0001 Single Worker Modernization
+
+## Status
+
+Accepted
+
+## Decision
+
+Modernize the existing app in one branch while preserving the default Tailwind v3 minigame behavior.
+
+Implementation was delegated to a single `gpt-5.5` worker using low reasoning effort. The parent process retained responsibility for review, verification oversight, git operations, and PR preparation.
+
+## Context
+
+The app was on older Next, React, and Tailwind dependencies, and the game state was concentrated in one large client component.
+
+## Consequences
+
+The migration can update dependencies, tests, and internal game structure together. Behavior changes must remain explicit, with Tailwind v4 exposed only through an opt-in selector.

docs/adr/0002-game-mode-registry.md

@@ -0,0 +1,23 @@
+# 0002 Game Mode Registry
+
+## Status
+
+Accepted
+
+## Decision
+
+Represent game modes with `GameMode = "tailwind-v3" | "tailwind-v4"` and load dictionaries from a typed registry.
+
+Store progress under `css2wind:game:<mode>` and persist answer history as `{ css, answers }`.
+
+## Context
+
+The game and API previously imported a single dictionary from the API folder. Adding Tailwind v4 requires mode-specific data without making client code reverse-lookup globals.
+
+A single `sessionProgress` key mixed progress across modes and answer history only stored answer arrays, forcing the answer modal to reverse-lookup the dictionary.
+
+## Consequences
+
+The v3 dictionary remains the default and backs `/api/v1`. The v4 dictionary starts as parity data, with answer differences added only when verified.
+
+Switching modes keeps progress isolated. The answer modal can render from saved history and no longer imports a global dictionary.

docs/adr/0003-tailwind-v4-migration.md

@@ -0,0 +1,17 @@
+# 0003 Tailwind v4 Migration
+
+## Status
+
+Accepted
+
+## Decision
+
+Use `@tailwindcss/postcss`, `@import "tailwindcss"`, and CSS `@theme` tokens for app-specific spacing, breakpoints, colors, and animations.
+
+## Context
+
+Tailwind v4 moves configuration toward CSS-first setup. The app used `tailwindcss-3d` for a small input flip effect.
+
+## Consequences
+
+The PostCSS config is simpler, the old plugin is removed, and the few required 3D utilities are defined locally in CSS.

docs/adr/0004-framework-upgrade.md

@@ -0,0 +1,19 @@
+# 0004 Framework Upgrade
+
+## Status
+
+Accepted
+
+## Decision
+
+Upgrade the app to Next 16.2.9, React 19.2.7, React DOM 19.2.7, Tailwind CSS 4.3.1, `@tailwindcss/postcss` 4.3.1, PostCSS 8.5.15, Prettier 3.8.4, and `prettier-plugin-tailwindcss` 0.8.0.
+
+Use Bun as the package manager and command runner. Keep linting, typechecking, unit tests, and production build as explicit Bun-run scripts.
+
+## Context
+
+The app was previously on an old Next 13 canary, React 18, Tailwind 3, and `next lint`. Next 16 and Tailwind 4 require config updates, including modern ESLint flat config and the Tailwind v4 PostCSS plugin.
+
+## Consequences
+
+The app uses stable framework versions and a Bun lockfile. The homepage avoids self-fetching its own API and imports dictionary data in process.

docs/adr/0005-verification-baseline.md

@@ -0,0 +1,17 @@
+# 0005 Verification Baseline
+
+## Status
+
+Accepted
+
+## Decision
+
+Use TypeScript, ESLint, Vitest, and `next build` as the baseline verification suite.
+
+## Context
+
+The app needs coverage for mode selection, evaluation, persistence, and result text. End-to-end browser tests are intentionally removed from this project state.
+
+## Consequences
+
+Local verification runs through Bun: install dependencies, typecheck, lint, run unit tests, and produce a production build.

eslint.config.mjs

@@ -0,0 +1,12 @@
+import nextVitals from "eslint-config-next/core-web-vitals";
+
+const eslintConfig = [
+  ...nextVitals,
+  {
+    rules: {
+      "react-hooks/set-state-in-effect": "off",
+    },
+  },
+];
+
+export default eslintConfig;