coorl-lost-cities/web/README.md

COOLRL Lost Cities Web

Browser-only Lost Cities client. The rules engine, observation builder, and PPO inference all run on the device; there is no application server.

The verified final JAX PPO policy is committed at public/models/jax-ppo.onnx (3.1 MB). Vite copies it to the static build, and the app resolves the asset relative to the deployed site so it works on GitHub Pages, GitLab Pages, or a normal web root. Its size and SHA-256 are recorded in public/models/jax-ppo.json.

Pushes to main build and publish the client through the repository's GitHub Pages and GitLab Pages workflows. Each workflow supplies the correct base URL for its host.

Setup

Install and run the checked-in final policy:

cd web
npm ci
npm run dev

Build the same static bundle used by a host:

npm run build
npm run preview

To replace the shipped policy, export a verified Orbax checkpoint from the repository root. The exporter writes both the ONNX file and its public metadata manifest:

uv run --with onnx scripts/export_jax_ppo_onnx.py \
  --checkpoint /path/to/checkpoint \
  --output web/public/models/jax-ppo.onnx

The policy tries WebGPU first and falls back to ONNX Runtime WebAssembly. If the model asset is absent, the UI remains playable using a simple local heuristic and reports that fallback in the header.

Checks

cd web
npm test
npm run build

The TypeScript engine follows src/lost_cities_jax/engine.py and its 96-action atomic action space. Cross-runtime fixtures can be regenerated with:

uv run python scripts/generate_web_parity_fixture.py