kotsukotsu/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

A typing tutor app for a child (Leo), built with React 19 + TypeScript + Bun fullstack server. Uses Bun as the package manager, runtime, bundler, and server.

Commands

• bun run dev — start dev server with HMR (bun --hot server.ts)
• bun run build — typecheck (tsc -b)
• bun run lint — ESLint

Architecture

Server — server.ts is the entry point using Bun.serve() with HTML imports. It serves the React app and API routes. The HTML file (index.html) is the client entrypoint — Bun's built-in bundler processes all referenced scripts/styles automatically.

Auth — Passkey (WebAuthn) authentication via @simplewebauthn/server + @simplewebauthn/browser. Server-side auth logic in server/auth.ts. Sessions stored in SQLite via HTTP-only cookies.

Database — SQLite via bun:sql (server/db.ts). Tables: users, credentials (passkey public keys), sessions. DB file: leo-typing.db (gitignored).

Frontend Auth Gate — src/components/AuthGate.tsx wraps the app. Shows login/register screen if not authenticated, otherwise renders the main app. Uses render-prop pattern to pass user and onLogout to App.

Modes — The app has four tabs, each a top-level component rendered by App.tsx:

• LessonMode — structured lessons with progressive key introduction; lessons unlock sequentially (90%+ accuracy required)
• FreeMode — free typing practice using random quotes
• GameMode — game selector with two games:
  • Falling Words — DOM-based falling words with combo system
  • Missile Strike — Canvas 2D missile flight game with interceptor dodging
• StatsView — charts (recharts) showing WPM/accuracy trends and per-key heatmaps

Core hook: useTypingEngine — shared typing logic used by LessonMode and FreeMode. Tracks cursor position, errors, WPM (updated every 500ms), per-key hit/miss stats, and fires onComplete when text is finished. GameMode has its own input handling since its mechanics differ.

State: useStats — persists UserProgress (completed lessons, session history, game high score) to localStorage under key leo-typing-progress.

Sound: sounds.ts — all audio is synthesized via Web Audio API oscillators (no audio files). Exports: playKeyClick, playWordComplete, playCombo, playMiss, playGameOver, playLaunch, playDodge, playMissileHit, playExplosion.

Data files — src/data/lessons.ts (lesson definitions with word lists), src/data/quotes.ts (free mode texts), src/data/keyboard.ts (key-to-finger mapping for the visual keyboard).

Styling — CSS Modules (src/styles/*.module.css) plus a global stylesheet.

TypeScript config — tsconfig.app.json covers src/ (client code, DOM types), tsconfig.server.json covers server.ts + server/ (Bun types).