Merge pull request #2 from kevinkiklee/feat/playwright-e2e

feat: i18n, e2e tests, component refactoring, and cleanup

Author: kevinkiklee

.github/workflows/deploy.yml

@@ -26,3 +26,14 @@ jobs:
       - run: npm run lint
       - run: npm test
       - run: npm run build
+
+      # Integration tests (Playwright)
+      - run: npx playwright install --with-deps chromium firefox
+      - run: npx playwright test
+
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 7

.gitignore

@@ -24,6 +24,10 @@ build
 # Build artifacts
 *.tsbuildinfo
 
+# Playwright
+playwright-report/
+test-results/
+
 
 # Source examples (not published)
 examples/

CLAUDE.md

@@ -28,8 +28,8 @@ Every tool features a `LearnPanel` (right sidebar) defined in `content.ts` and `
 - **Interactive Challenges**: 3-5 multiple-choice questions with persistence to `localStorage`.
 - **Tooltips**: Use `InfoTooltip` on control labels for quick definitions.
 
-### 4. Layout Shell (`src/components/shared/ToolPageShell.tsx`)
-Standard three-column layout (Controls | Main Visualizer | LearnPanel). Provides consistent header actions (Share, Export, Info).
+### 4. Layout
+Each tool manages its own layout (Controls | Main Visualizer | LearnPanel). Consistent header actions (Share, Export, Info) via `ToolActions` component.
 
 ## Engineering Standards
 

GEMINI.md

@@ -1,104 +1,139 @@
 # PhotoTools
 
-Free photography calculators, simulators, and references. No sign-up required — your photos never leave your browser.
+Free photography calculators, simulators, and references. No sign-up, no uploads — everything runs in your browser.
 
 **[www.phototools.io](https://www.phototools.io)**
 
-## Tools
-
-### Live in Production
+---
 
-- **FOV Simulator** — Compare field of view across up to four lens and sensor combinations, overlaid on real-world scenes. Plan lens purchases and understand how focal length and sensor size affect what you capture.
-- **Color Scheme Generator** — Build harmonious color palettes using complementary, analogous, triadic, split-complementary, and tetradic relationships. Pick colors from uploaded photos or the color wheel to plan wardrobe, props, and set design.
-- **Star Trail Calculator** — Calculate maximum exposure for pinpoint stars using the 500 Rule or the more accurate NPF Rule. Plan star trail stacking sessions with frame count and total duration estimates. Animated canvas preview with sky gradient, star glow, and terrain.
-- **White Balance Visualizer** — See how color temperature (1000K–12000K) shifts the look of different scenes. Compare presets from Candle to Blue Sky, or upload your own photo to preview white balance changes via WebGL.
-- **Sensor Size Comparison** — Visually compare camera sensor sizes from medium format down to smartphone. Overlay, side-by-side, and pixel density modes with per-sensor resolution and popular camera model data.
-- **EXIF Viewer** — View EXIF metadata and histogram for any photo. Extracts camera, lens, exposure settings, GPS coordinates, and software info. Includes a privacy warning when location data is detected. 100% client-side — nothing is uploaded.
+## What is PhotoTools?
 
-### In Development
+PhotoTools is a collection of interactive tools that help photographers understand and visualize core concepts — field of view, depth of field, exposure, color theory, white balance, and more. Each tool includes an educational Learn panel with beginner and in-depth explanations, key factors, pro tips, and interactive quiz challenges.
 
-- **Exposure Triangle Simulator** — Interactively adjust aperture, shutter speed, and ISO to see real-time effects on exposure, depth of field blur, motion blur, and noise through a WebGL preview.
-- **Depth of Field Calculator** — Calculate near focus, far focus, hyperfocal distance, and total depth of field for any lens, aperture, and subject distance. Includes an interactive DoF diagram.
-- **Hyperfocal Distance Simulator** — Learn where to focus for maximum sharpness from foreground to infinity. Includes a depth of field diagram and a mini reference table for quick field use.
-- **Shutter Speed Visualizer** — Find the minimum safe shutter speed for sharp handheld shots based on focal length, crop factor, and image stabilization stops.
-- **Perspective Compression Simulator** — See how focal length affects background compression and apparent distance between subjects.
-- **ND Filter Calculator** — Calculate the resulting shutter speed after attaching any ND filter (1–10 stops).
+All image processing happens client-side. Photos you load into the EXIF Viewer, Histogram, Frame Studio, or any other tool never leave your device.
 
-### Reference
+## Tools
 
-- **Glossary** — 50+ photography terms with clear definitions, linked to relevant tools for hands-on learning.
+### Visualizers
 
-Each tool includes an educational **Learn panel** with beginner and deeper explanations, key factors, pro tips, and interactive challenges with try-again and reset functionality.
+| Tool | Description |
+|------|-------------|
+| **[FOV Simulator](https://www.phototools.io/fov-simulator)** | Compare field of view across up to four lens/sensor combinations overlaid on real-world scenes. Plan lens purchases and understand how focal length and sensor size affect framing. |
+| **[Color Scheme Generator](https://www.phototools.io/color-scheme-generator)** | Build harmonious color palettes using complementary, analogous, triadic, split-complementary, and tetradic relationships. Pick colors from uploaded photos or the color wheel. |
+| **[Star Trail Calculator](https://www.phototools.io/star-trail-calculator)** | Calculate maximum exposure for pinpoint stars (500 Rule and NPF Rule). Plan star trail stacking sessions with frame count and duration estimates. Animated sky preview. |
+| **[White Balance Visualizer](https://www.phototools.io/white-balance-visualizer)** | See how color temperature (1000K–12000K) shifts the look of scenes. Compare presets from Candle to Blue Sky, or upload your own photo for a live WebGL preview. |
+| **[Sensor Size Comparison](https://www.phototools.io/sensor-size-comparison)** | Visually compare sensor sizes from medium format to smartphone. Overlay, side-by-side, and pixel density modes with resolution data and popular camera models. |
 
-## Tech Stack
+### File Tools
 
-- Next.js 16 (App Router, Turbopack)
-- React 19 + TypeScript 6
-- Vitest + Testing Library (235 tests across 18 files)
-- CSS Modules + CSS custom properties (design tokens)
-- Canvas API + WebGL2 + GLSL shaders
-- Vercel (deployment)
+| Tool | Description |
+|------|-------------|
+| **[Frame Studio](https://www.phototools.io/frame-studio)** | Crop, frame, and compose photos with aspect ratio presets and composition grid overlays (rule of thirds, golden ratio, diagonal). |
+| **[EXIF Viewer](https://www.phototools.io/exif-viewer)** | View EXIF metadata and histogram for any photo. Extracts camera, lens, exposure, GPS, and software info. Privacy warning when location data is detected. 100% client-side. |
 
-## Development
+### Reference
 
-```bash
-npm install
-npm run dev
-```
+| Tool | Description |
+|------|-------------|
+| **[Glossary](https://www.phototools.io/learn/glossary)** | 50+ photography terms with clear definitions, linked to relevant tools for hands-on learning. |
 
-Dev server runs at `http://localhost:3000`. All tools are visible in development regardless of production status.
+### In Development
 
-## Tool Visibility
+These tools are functional in the dev environment but not yet published to production:
 
-Each tool in `src/lib/data/tools.ts` has separate `dev` and `prod` status fields with three states:
+- **Exposure Triangle Simulator** — Adjust aperture, shutter speed, and ISO to see real-time effects on exposure, depth of field blur, motion blur, and noise (WebGL).
+- **Depth of Field Calculator** — Calculate near/far focus, hyperfocal distance, and total DoF with an interactive diagram.
+- **Hyperfocal Distance Simulator** — Learn where to focus for maximum foreground-to-infinity sharpness.
+- **Shutter Speed Visualizer** — Find the minimum safe shutter speed for handheld shooting based on focal length, crop factor, and stabilization.
+- **Perspective Compression Simulator** — See how focal length affects background compression and apparent subject distance.
+- **ND Filter Calculator** — Calculate resulting shutter speed after attaching any ND filter (1–10 stops).
 
-- **`live`** — fully accessible, appears in nav, homepage, and footer
-- **`draft`** — appears in nav/homepage as "Coming Soon" (disabled); still reachable by direct URL with a draft banner
-- **`disabled`** — hidden from all menus, not shown anywhere in production
+## Tech Stack
 
-Helper functions: `getLiveTools()` (live only), `getVisibleTools()` (live + draft), `getAllTools()` (everything).
+| Layer | Technology |
+|-------|-----------|
+| Framework | Next.js 16 (App Router, Turbopack) |
+| UI | React 19, TypeScript 6, CSS Modules |
+| Rendering | Canvas API, WebGL2 + GLSL shaders |
+| i18n | next-intl |
+| Unit tests | Vitest + Testing Library (353 tests) |
+| E2E tests | Playwright (Chromium + Firefox) |
+| Deployment | Vercel (auto-deploy from `main`) |
+| Analytics | Vercel Speed Insights, Google Analytics |
+| Ads/Consent | Google AdSense, CookieYes |
 
-## Testing
+## Getting Started
 
 ```bash
-npm test            # single run (235 tests)
-npm run test:watch  # watch mode
+git clone https://github.com/kevinkiklee/phototools.io.git
+cd phototools.io
+npm install
+npm run dev
 ```
 
-## Build & Lint
+The dev server starts at `http://localhost:3000`. In development, all tools are visible regardless of production status — draft tools show a banner.
 
-```bash
-npm run build
-npm run lint
-```
+## Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Start dev server (Turbopack) |
+| `npm run build` | Production build |
+| `npm run start` | Serve production build locally |
+| `npm run lint` | Run ESLint |
+| `npm test` | Run Vitest unit tests |
+| `npm run test:watch` | Run tests in watch mode |
+| `npm run test:e2e` | Run Playwright e2e tests (requires build) |
 
 ## Project Structure
 
 ```
 src/
-  app/                    Routes (homepage, tools, learn/glossary)
-    [slug]/               Each tool at top-level URL (e.g. /fov-simulator)
-      page.tsx            Route entry point
-      _components/        Tool-specific UI components (co-located)
+  app/                        App Router routes
+    [slug]/                   Each tool at a top-level URL (e.g. /fov-simulator)
+      page.tsx                Route entry point
+      _components/            Tool-specific UI (co-located, private folder)
+    api/contact/              Contact form API route (Resend)
+    learn/glossary/           Photography glossary page
   components/
-    layout/               Nav (mega-menu), Footer, ThemeProvider, ThemeToggle
-    shared/               Reusable components (ToolPageShell, LearnPanel, ControlPanel, ToolIcon, etc.)
+    layout/                   Nav (mega-menu), Footer, ThemeProvider, ThemeToggle
+    shared/                   Reusable UI — LearnPanel, ControlPanel, ToolActions,
+                              FileDropZone, ShareModal, AdUnit, MobileAdBanner, etc.
   lib/
-    math/                 Pure calculation modules with co-located tests
-    data/                 Tool registry, education content, sensors, glossary, etc.
-    data/education/       Per-tool educational content, challenge definitions, types
-    utils/                Query sync, export helpers
-    types.ts              Shared TypeScript types
-public/                   Images, icons, manifest, sitemap, robots.txt
+    math/                     Pure calculation modules with co-located tests
+                              (fov, dof, exposure, color, histogram, compression,
+                              startrail, diffraction, frame, grid)
+    data/                     Tool registry, education content, sensors, focal lengths,
+                              scenes, glossary, camera settings, ND filters, white balance
+    data/education/           Per-tool education skeletons and challenge definitions
+    i18n/                     Message loader and translation JSON files (next-intl)
+    utils/                    URL query sync, canvas export helpers
+    types.ts                  Shared TypeScript types
+    ads.ts                    Ad configuration and feature flags
+  e2e/                        Playwright e2e test specs
+public/                       Static assets (scene images, sample photos)
 ```
 
+## Architecture Highlights
+
+- **Tool registry** — All tools defined in `src/lib/data/tools.ts` with separate `dev`/`prod` status fields (`live`, `draft`, `disabled`). Helper functions: `getLiveTools()`, `getVisibleTools()`, `getAllTools()`.
+- **Education system** — Each tool has a LearnPanel sidebar with structured content: beginner/deeper explanations, key factors, pro tips, and progressive quiz challenges persisted to localStorage.
+- **Pure math layer** — All calculation logic lives in `src/lib/math/` as pure functions with thorough unit tests, decoupled from UI.
+- **Privacy-first** — All image processing is client-side. No photos are uploaded to any server. EXIF Viewer warns users when GPS data is detected.
+- **No desktop scroll** — On desktop, the application fits within the viewport (100vh). Individual panels scroll internally. Mobile pages scroll naturally.
+- **URL state sync** — Tool parameters are synced to URL query strings for shareability and SEO.
+- **Consent-first ads** — CookieYes consent banner loads before AdSense. Ads are blocked until the user grants consent.
+
 ## Deployment
 
-Push to `main` triggers:
-1. GitHub Actions CI (audit, lint, test, build)
-2. Vercel auto-deploy to production
+Pushing to `main` triggers:
+
+1. **GitHub Actions CI** — `npm ci` → `npm audit` → `npm run lint` → `npm test` → `npm run build` → Playwright e2e
+2. **Vercel auto-deploy** — production deployment to [www.phototools.io](https://www.phototools.io)
+
+## Contributing
 
-Live at [www.phototools.io](https://www.phototools.io).
+See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for the guide on adding new tools, and [docs/SETUP.md](docs/SETUP.md) for detailed setup instructions.
 
 ## License
 

README.md

@@ -10,7 +10,7 @@ import { SENSORS } from '@/lib/data/sensors'
 import { FOCAL_LENGTHS } from '@/lib/data/focalLengths'
 import { TOOLS, getToolBySlug, getLiveTools } from '@/lib/data/tools'
 import { GLOSSARY } from '@/lib/data/glossary'
-import { getAllEducation } from '@/lib/data/education'
+import { getAllSkeletons } from '@/lib/data/education'
 
 describe('FOV calculations with real sensor data', () => {
   it('all sensors produce valid FOV at all focal lengths', () => {
@@ -201,15 +201,15 @@ describe('Education and tool registry alignment', () => {
   it('every education entry has a matching tool or known sub-feature', () => {
     const toolSlugs = new Set(TOOLS.map((t) => t.slug))
     const knownSubFeatures = new Set(['histogram'])
-    for (const edu of getAllEducation()) {
+    for (const edu of getAllSkeletons()) {
       expect(toolSlugs.has(edu.slug) || knownSubFeatures.has(edu.slug)).toBe(true)
     }
   })
 
   it('every live tool has education content', () => {
     const liveTools = getLiveTools()
     for (const tool of liveTools) {
-      const edu = getAllEducation().find((e) => e.slug === tool.slug)
+      const edu = getAllSkeletons().find((e) => e.slug === tool.slug)
       expect(edu).toBeDefined()
     }
   })

__tests__/integration.test.ts

@@ -28,7 +28,7 @@ Dev server runs at `http://localhost:3000`.
 app/                    Routes (homepage, tool pages, learn/glossary)
 components/
   layout/               Nav (mega-menu), Footer, ThemeProvider, ThemeToggle
-  shared/               ToolPageShell, LearnPanel, InfoTooltip, ShareModal, ToolActions, FileDropZone, DraftBanner, Toast
+  shared/               LearnPanel, InfoTooltip, ShareModal, ToolActions, FileDropZone, DraftBanner
   tools/                One directory per tool + shared/
 lib/
   math/                 Pure calculation modules with co-located tests
@@ -43,13 +43,13 @@ public/                 Static assets (images, icons, manifest)
 
 1. **Math module** (if the tool needs calculations): create `lib/math/yourtool.ts` with pure functions and `lib/math/yourtool.test.ts` with tests.
 2. **Component**: create `components/tools/your-tool/YourTool.tsx` (add `'use client'` at the top if it uses state, effects, or event handlers) and `YourTool.module.css` for styles.
-3. **Route**: create `app/tools/your-tool/page.tsx`. Import and render the component inside `ToolPageShell`.
+3. **Route**: create `app/your-tool/page.tsx` with a co-located `_components/` directory for tool-specific UI.
 4. **Registry**: add an entry to the `TOOLS` array in `lib/data/tools.ts`:
    ```ts
    { slug: 'your-tool', name: 'Your Tool', description: '...', status: 'draft', category: 'calculator' }
    ```
    Set `status: 'live'` when the tool is ready for production. In development, all tools are visible regardless of status.
-5. **Education content**: add a `ToolEducation` entry in `lib/data/education/` with beginner/deeper explanations, tips, tooltips, and challenges. The `LearnPanel` renders automatically via `ToolPageShell`.
+5. **Education content**: add a `ToolEducation` entry in `lib/data/education/` with beginner/deeper explanations, tips, tooltips, and challenges. Include `LearnPanel` in the tool's layout.
 6. **Verify**: run `npm test && npm run build`.
 
 ## Adding a Glossary Term

docs/CONTRIBUTING.md

@@ -48,7 +48,7 @@ phototools.io/
 │       └── glossary/page.tsx       # Photography glossary
 ├── components/
 │   ├── layout/                     # Nav (mega-menu), Footer, ThemeProvider, ThemeToggle
-│   ├── shared/                     # ToolPageShell, LearnPanel, InfoTooltip, ShareModal, ToolActions, FileDropZone, DraftBanner, Toast
+│   ├── shared/                     # LearnPanel, InfoTooltip, ShareModal, ToolActions, FileDropZone, DraftBanner
 │   └── tools/                      # One directory per tool + shared/
 │       ├── fov-simulator/
 │       ├── dof-calculator/
@@ -93,7 +93,7 @@ Calculation logic lives in `lib/math/` as pure functions with no React dependenc
 ### Components
 
 - `components/layout/` — site-wide layout (Nav, Footer, theme)
-- `components/shared/` — reusable across tools (ToolPageShell wraps every tool page)
+- `components/shared/` — reusable across tools (LearnPanel, ControlPanel, ToolActions, etc.)
 - `components/tools/` — tool-specific UI, one directory per tool
 
 ### Styling
@@ -104,7 +104,7 @@ CSS Modules for component scoping. Design tokens (colors, spacing, typography) d
 
 1. **Math module** (if needed): create `lib/math/yourtool.ts` with pure calculation functions and `lib/math/yourtool.test.ts` with tests.
 2. **Component**: create `components/tools/your-tool/YourTool.tsx` (with `'use client'` if interactive) and `YourTool.module.css`.
-3. **Route**: create `app/tools/your-tool/page.tsx` that wraps the component in `ToolPageShell`.
+3. **Route**: create `app/your-tool/page.tsx` with a co-located `_components/` directory for tool-specific UI.
 4. **Registry**: add the tool to the `TOOLS` array in `lib/data/tools.ts` with `status: 'draft'`. Change to `'live'` when ready.
 5. **Test**: run `npm test` to verify. Run `npm run build` to confirm the build passes.
 

docs/SETUP.md

@@ -1,4 +1,7 @@
 import type { NextConfig } from 'next'
+import createNextIntlPlugin from 'next-intl/plugin'
+
+const withNextIntl = createNextIntlPlugin('./src/lib/i18n/request.ts')
 
 const nextConfig: NextConfig = {
   experimental: {
@@ -68,4 +71,4 @@ const nextConfig: NextConfig = {
   },
 }
 
-export default nextConfig
+export default withNextIntl(nextConfig)