Codex Web Education

A game-like coding arena that turns real UI failures into verified debugging missions.

Comment

Inspiration

Frontend debugging is often taught as a checklist or a code quiz, but real bugs are felt in the browser. We wanted a small learning toy where cause and effect is immediate: touch one safe setting, watch the UI and source change, verify real behavior, and damage a boss only when the behavior truly passes.

What it does

Codex Web Education is a bilingual Korean and English debugging arena with five focused missions:

  1. Keyboard Trap repairs dialog identity, focus containment, Escape dismissal, and focus restoration.
  2. Flex Tangle repairs computed Flexbox display, direction, alignment, justification, and gap.
  3. Motion Phantom repairs animation timing, travel distance, and reduced-motion behavior.
  4. Stream Gremlin repairs a safe deterministic simulation of SSE framing, event parsing, and bounded reconnects.
  5. State Doppelganger repairs immutable updates, a single source of truth, and complete reset behavior.

The broken fixture is the visual center. Allowlisted controls sit beside it, and every valid change immediately updates the rendered interface and a React-like source representation. Check & attack runs actual DOM, keyboard, computed-style, timing, and interaction checks. Only newly passing evaluator results deal damage or award XP.

After a verified failure, an optional visual coach appears beside the related failure. It begins with one observation and one progressive hint, highlights only unresolved controls, and keeps provider and technical evidence behind disclosure. Attempt history preserves fixture-only snapshots and meaningful code diffs.

How we built it

We used Next.js 16, React 19, strict TypeScript, CSS, Vitest, and Playwright. Reducer-driven battle state is separated from typed RepairProvider, DialogObjectiveEvaluator, and CoachProvider interfaces. Mission presets use only curated allowlisted values. The source preview is explanatory text and is never executed.

The default coach is deterministic and requires no account, key, model, or network service. An optional server-local Ollama vision provider validates structured input and safely falls back to the deterministic coach. The SSE mission is a deterministic browser simulation rather than arbitrary networking or generated code.

Challenges we ran into

The hardest part was making reward truth impossible to fake: clicks, timers, and setting changes cannot award progress. We also had to preserve keyboard focus, live announcements, reduced-motion behavior, mobile ordering, replay-safe XP, and five isolated repair vocabularies while keeping the loop easy to understand.

Accomplishments that we are proud of

  • Five direct-manipulation missions with different cute bosses and defeated states.
  • Visible defect signals attached to the broken UI instead of a distant text-only report.
  • AI-style coaching that is hidden until a real failed verification and keeps glow on unresolved controls.
  • Verified damage, deterministic presets, snapshot evidence, code diffs, bilingual copy, keyboard flow, and mobile layout.
  • A clean suite of 29 unit tests and 15 end-to-end tests across Chromium, including security, storage fallback, replay, reduced motion, and browser-console checks.

What we learned

Debugging instruction works best when failure is visible beside the control and verification measures browser outcomes rather than button clicks. Separating repair input, evaluation, coaching, and rewards made each boundary easier to test and safer to explain.

What is next

We would add authored missions for responsive grids, form validation, async race conditions, and render performance, plus safe mission-authoring tools and privacy-preserving learner progress analytics.

Built With

Share this project:

Updates