[rNLKJA]

Summary

This PR revives the COMP30024 (Semester 1, 2022) Cachex project as Cachex Arena. It is a static Next.js app that runs a line-by-line TypeScript port of our original A* search and minimax agent in the browser.

Live demo: https://cachex-ai.vercel.app

Structure

• The original submission was moved into coursework/ with git mv, so history is kept. Its contents are unchanged, and coursework/README.md explains how to run it with uv on Python 3.12.
• scripts/ holds uv (PEP 723) scripts that import the unchanged Python:
  • generate_parity_fixtures.py writes the Vitest parity fixtures.
  • benchmark_agent.py writes the agent-vs-random benchmark. It pins PYTHONHASHSEED=0, so its output is byte-for-byte reproducible.
• web/ is the deployable Next.js 16 app (React 19, Tailwind v4, shadcn/ui, next-themes, lucide). It is the Vercel root.
• .github/workflows/ci.yml runs pnpm install --frozen-lockfile, then lint, typecheck, test and build in web/.

App

• /: the landing page. It covers the rules, what the coursework asked, what we built, the evaluation weights, key results from the original code (the _4399 agent won 144 of 160 games, 90%, against the random agent) and an About section with credits.
• /play: play the minimax agent or the random baseline on boards from 3×3 to 10×10, as either colour. It has STEAL, capture animations, undo, a move log, a "why that move?" panel and keyboard play. The agent runs in a Web Worker.
• /spectate: AI vs AI with play, pause and step, a speed control, seeded replays and an evaluation trend chart.
• /astar: the A* Lab. You can edit boards, animate open and closed sets, compare Manhattan with Euclidean, import or export the original sample_input.json format, and check results against the recorded outputs. It also re-runs the notebook's heuristic study in a worker, using the notebook's insertion counter on every size from 2 to 99.

Parity

847 Vitest tests check the port against fixtures generated by the original Python:

• A* paths and node counts.
• CPython set-order tie-breaking.
• Referee board states and captures.
• Evaluation features, minimax and Player.action.
• Full self-play games.
• The recorded sample_output*.txt files, read straight from coursework/.

Review fixes in this branch

• Benchmark reproducibility.
• Keyboard focus is kept on the board after each move.
• AA-contrast text tokens.
• Candidate bars that ignore the 1e-5 tie-break bias.
• The heuristic study's metric and board sizes.
• Sample preset provenance.
• Mobile table, header and chart.
• The dark-mode edge glow.
• Spectator state.
• Slider labels and tool tooltips.
• Sticky board columns.
• 404 metadata.
• Repo hygiene.

Run locally

cd web
pnpm install
pnpm dev        # http://localhost:3000
pnpm lint && pnpm typecheck && pnpm test && pnpm build

Notes

• The university's specification PDFs are still under coursework/Project Part A/specification/. The website does not serve them; whether to remove them from the public repo is the owner's call.

🤖 Generated with Claude Code