` and the placeholder script tag.
- [ ] **Step 7: Commit**
```bash
git add Frontend/package.json Frontend/package-lock.json Frontend/vite.config.ts \
Frontend/tsconfig.json Frontend/tsconfig.node.json Frontend/tsconfig.app.json \
Frontend/index.html Frontend/src/
git -c user.email=meelstorm@gmail.com -c user.name=meelstorm commit -m "feat(frontend): scaffold Vite + React + TypeScript project"
```
---
## Task 2: `protocol.ts` — wire message TypeScript types
**Files:**
- Create: `Frontend/src/protocol.ts`
Mirror the backend's WireMessages exactly. This is the source of truth for what the frontend expects on the wire.
- [ ] **Step 1: Write `Frontend/src/protocol.ts`**
```ts
// Wire messages exchanged with the backend over WebSocket.
// Mirror of Backend/WireMessages.cs.
export interface CursorMessage {
type: 'cursor';
x: number;
y: number;
}
export interface InitFrame {
type: 'init';
world: [number, number];
}
export interface StateFrame {
type: 'state';
x: number;
y: number;
angle: number;
engine: number;
target: [number, number];
step: number;
}
export type ServerFrame = InitFrame | StateFrame;
export function isInit(frame: ServerFrame): frame is InitFrame {
return frame.type === 'init';
}
export function isState(frame: ServerFrame): frame is StateFrame {
return frame.type === 'state';
}
```
- [ ] **Step 2: Verify TypeScript compiles**
```bash
cd Frontend && npx tsc --noEmit && cd ..
```
Expected: no errors.
- [ ] **Step 3: Commit**
```bash
git add Frontend/src/protocol.ts
git -c user.email=meelstorm@gmail.com -c user.name=meelstorm commit -m "feat(frontend): wire message TypeScript types"
```
---
## Task 3: `useGameSocket` hook
**Files:**
- Create: `Frontend/src/hooks/useGameSocket.ts`
Opens the WebSocket on mount, parses inbound frames, exposes `{init, state, connected, send}` as React state.
- [ ] **Step 1: Write `Frontend/src/hooks/useGameSocket.ts`**
```ts
import { useEffect, useRef, useState } from 'react';
import type { InitFrame, ServerFrame, StateFrame, CursorMessage } from '../protocol';
import { isInit, isState } from '../protocol';
export interface GameSocketState {
connected: boolean;
init: InitFrame | null;
state: StateFrame | null;
sendCursor: (x: number, y: number) => void;
}
/**
* Opens a WebSocket to the given URL, tracks the latest init/state frames.
* Auto-reconnects with exponential backoff on close.
*/
export function useGameSocket(url: string): GameSocketState {
const [connected, setConnected] = useState(false);
const [init, setInit] = useState
(null);
const [state, setState] = useState(null);
const wsRef = useRef(null);
useEffect(() => {
let closed = false;
let backoffMs = 500;
let reconnectTimer: number | null = null;
const open = () => {
const ws = new WebSocket(url);
wsRef.current = ws;
ws.onopen = () => {
setConnected(true);
backoffMs = 500; // reset backoff on successful connect
};
ws.onclose = () => {
setConnected(false);
wsRef.current = null;
if (!closed) {
reconnectTimer = window.setTimeout(open, backoffMs);
backoffMs = Math.min(backoffMs * 2, 8000);
}
};
ws.onerror = () => { /* let onclose handle it */ };
ws.onmessage = (ev) => {
let frame: ServerFrame;
try {
frame = JSON.parse(ev.data) as ServerFrame;
} catch {
return;
}
if (isInit(frame)) setInit(frame);
else if (isState(frame)) setState(frame);
};
};
open();
return () => {
closed = true;
if (reconnectTimer !== null) window.clearTimeout(reconnectTimer);
wsRef.current?.close();
};
}, [url]);
const sendCursor = (x: number, y: number) => {
const ws = wsRef.current;
if (!ws || ws.readyState !== WebSocket.OPEN) return;
const msg: CursorMessage = { type: 'cursor', x, y };
ws.send(JSON.stringify(msg));
};
return { connected, init, state, sendCursor };
}
```
- [ ] **Step 2: Verify TypeScript compiles**
```bash
cd Frontend && npx tsc --noEmit && cd ..
```
Expected: no errors.
- [ ] **Step 3: Commit**
```bash
git add Frontend/src/hooks/useGameSocket.ts
git -c user.email=meelstorm@gmail.com -c user.name=meelstorm commit -m "feat(frontend): useGameSocket hook with auto-reconnect"
```
---
## Task 4: `useCursorSender` hook
**Files:**
- Create: `Frontend/src/hooks/useCursorSender.ts`
Attaches a `mousemove` listener to a target element (the canvas). Converts pixel coords → world coords in `[0,1] × [0,1]` using letterbox mapping. Throttles sends to ~50 Hz using a `requestAnimationFrame` timestamp gate.
- [ ] **Step 1: Write `Frontend/src/hooks/useCursorSender.ts`**
```ts
import { useEffect, useRef } from 'react';
/**
* Convert a viewport point to world coords in [0,1] × [0,1] using
* letterbox mapping (preserves world aspect ratio 1:1).
*/
export function viewportToWorld(
viewportPx: { x: number; y: number },
viewportSize: { w: number; h: number },
): { x: number; y: number } {
// World is 1×1. Fit inside viewport with black bars on the wider axis.
const scale = Math.min(viewportSize.w, viewportSize.h);
const offsetX = (viewportSize.w - scale) / 2;
const offsetY = (viewportSize.h - scale) / 2;
return {
x: Math.max(0, Math.min(1, (viewportPx.x - offsetX) / scale)),
y: Math.max(0, Math.min(1, (viewportPx.y - offsetY) / scale)),
};
}
const SEND_INTERVAL_MS = 20; // 50 Hz cap
export function useCursorSender(
targetRef: React.RefObject,
onSend: (x: number, y: number) => void,
) {
const lastCursorRef = useRef<{ x: number; y: number } | null>(null);
const lastSentAtRef = useRef(0);
const rafRef = useRef(null);
useEffect(() => {
const el = targetRef.current;
if (!el) return;
const handleMove = (ev: MouseEvent) => {
const rect = el.getBoundingClientRect();
const world = viewportToWorld(
{ x: ev.clientX - rect.left, y: ev.clientY - rect.top },
{ w: rect.width, h: rect.height },
);
lastCursorRef.current = world;
};
const tick = (now: number) => {
const c = lastCursorRef.current;
if (c && now - lastSentAtRef.current >= SEND_INTERVAL_MS) {
onSend(c.x, c.y);
lastSentAtRef.current = now;
}
rafRef.current = requestAnimationFrame(tick);
};
el.addEventListener('mousemove', handleMove);
rafRef.current = requestAnimationFrame(tick);
return () => {
el.removeEventListener('mousemove', handleMove);
if (rafRef.current !== null) cancelAnimationFrame(rafRef.current);
};
}, [targetRef, onSend]);
}
```
- [ ] **Step 2: Verify TypeScript compiles**
```bash
cd Frontend && npx tsc --noEmit && cd ..
```
Expected: no errors.
- [ ] **Step 3: Commit**
```bash
git add Frontend/src/hooks/useCursorSender.ts
git -c user.email=meelstorm@gmail.com -c user.name=meelstorm commit -m "feat(frontend): useCursorSender hook with letterbox mapping and 50 Hz throttle"
```
---
## Task 5: `render.ts` — pure canvas draw functions
**Files:**
- Create: `Frontend/src/render.ts`
Pure functions that draw the scene on a `CanvasRenderingContext2D`. Testable without a DOM (Vitest is not being set up in this plan — this is more about keeping the module isolated for correctness).
- [ ] **Step 1: Write `Frontend/src/render.ts`**
```ts
import type { StateFrame } from './protocol';
/** Ship as a filled triangle, drawn at (x,y) rotated by angle. Size in canvas px. */
export function drawShip(
ctx: CanvasRenderingContext2D,
worldX: number,
worldY: number,
angle: number,
engine: number,
scale: number,
offsetX: number,
offsetY: number,
) {
const px = offsetX + worldX * scale;
const py = offsetY + worldY * scale;
const size = scale * 0.04;
ctx.save();
ctx.translate(px, py);
ctx.rotate(angle);
// Body: triangle pointing up (angle=0 → up).
ctx.fillStyle = '#eee';
ctx.beginPath();
ctx.moveTo(0, -size);
ctx.lineTo(size * 0.7, size * 0.6);
ctx.lineTo(-size * 0.7, size * 0.6);
ctx.closePath();
ctx.fill();
// Flame if an engine is firing.
if (engine !== 0) {
ctx.fillStyle = '#ff9d3d';
ctx.beginPath();
if (engine === 2) {
// Main engine: flame under the ship.
const flame = size * 0.9 + Math.random() * size * 0.4;
ctx.moveTo(-size * 0.4, size * 0.6);
ctx.lineTo(size * 0.4, size * 0.6);
ctx.lineTo(0, size * 0.6 + flame);
} else if (engine === 1) {
// Left thruster: flame on right side of body.
ctx.moveTo(size * 0.7, -size * 0.2);
ctx.lineTo(size * 0.7, size * 0.2);
ctx.lineTo(size * 1.3, 0);
} else if (engine === 3) {
// Right thruster: flame on left side of body.
ctx.moveTo(-size * 0.7, -size * 0.2);
ctx.lineTo(-size * 0.7, size * 0.2);
ctx.lineTo(-size * 1.3, 0);
}
ctx.closePath();
ctx.fill();
}
ctx.restore();
}
/** Draw a crosshair at the target world position. */
export function drawTarget(
ctx: CanvasRenderingContext2D,
worldX: number,
worldY: number,
scale: number,
offsetX: number,
offsetY: number,
) {
const px = offsetX + worldX * scale;
const py = offsetY + worldY * scale;
const r = 8;
ctx.strokeStyle = '#5cf';
ctx.lineWidth = 1.5;
ctx.beginPath();
ctx.arc(px, py, r, 0, Math.PI * 2);
ctx.stroke();
ctx.beginPath();
ctx.moveTo(px - r * 1.5, py);
ctx.lineTo(px + r * 1.5, py);
ctx.moveTo(px, py - r * 1.5);
ctx.lineTo(px, py + r * 1.5);
ctx.stroke();
}
/** Layout: fit the 1×1 world into the canvas with black letterbox bars. */
export function layout(canvas: HTMLCanvasElement) {
const scale = Math.min(canvas.width, canvas.height);
const offsetX = (canvas.width - scale) / 2;
const offsetY = (canvas.height - scale) / 2;
return { scale, offsetX, offsetY };
}
/** Render one frame: clear + world background + target + ship. */
export function renderFrame(
canvas: HTMLCanvasElement,
state: StateFrame | null,
) {
const ctx = canvas.getContext('2d');
if (!ctx) return;
// Clear
ctx.fillStyle = '#000';
ctx.fillRect(0, 0, canvas.width, canvas.height);
const { scale, offsetX, offsetY } = layout(canvas);
// World background (subtle dark band so the play area is visible).
ctx.fillStyle = '#0a0a12';
ctx.fillRect(offsetX, offsetY, scale, scale);
if (!state) return;
drawTarget(ctx, state.target[0], state.target[1], scale, offsetX, offsetY);
drawShip(ctx, state.x, state.y, state.angle, state.engine, scale, offsetX, offsetY);
}
```
- [ ] **Step 2: Verify TypeScript compiles**
```bash
cd Frontend && npx tsc --noEmit && cd ..
```
Expected: no errors.
- [ ] **Step 3: Commit**
```bash
git add Frontend/src/render.ts
git -c user.email=meelstorm@gmail.com -c user.name=meelstorm commit -m "feat(frontend): pure canvas draw functions (ship + flame + target + layout)"
```
---
## Task 6: `useAnimationLoop`, `LanderCanvas`, `App` — wire it all up
**Files:**
- Create: `Frontend/src/hooks/useAnimationLoop.ts`
- Create: `Frontend/src/LanderCanvas.tsx`
- Modify: `Frontend/src/App.tsx`
- [ ] **Step 1: Write `Frontend/src/hooks/useAnimationLoop.ts`**
```ts
import { useEffect, useRef } from 'react';
/** Calls `callback` once per browser frame. Runs while mounted. */
export function useAnimationLoop(callback: (now: number) => void) {
const cbRef = useRef(callback);
cbRef.current = callback;
useEffect(() => {
let rafId = 0;
const loop = (now: number) => {
cbRef.current(now);
rafId = requestAnimationFrame(loop);
};
rafId = requestAnimationFrame(loop);
return () => cancelAnimationFrame(rafId);
}, []);
}
```
- [ ] **Step 2: Write `Frontend/src/LanderCanvas.tsx`**
```tsx
import { useEffect, useRef } from 'react';
import type { StateFrame } from './protocol';
import { renderFrame } from './render';
import { useAnimationLoop } from './hooks/useAnimationLoop';
import { useCursorSender } from './hooks/useCursorSender';
export interface LanderCanvasProps {
state: StateFrame | null;
onCursor: (x: number, y: number) => void;
}
/**
* Full-viewport canvas. Redraws every animation frame reading the latest
* `state` prop (no interpolation). Mouse movement is captured on the canvas
* and forwarded through `onCursor`.
*/
export function LanderCanvas({ state, onCursor }: LanderCanvasProps) {
const canvasRef = useRef(null);
const stateRef = useRef(state);
stateRef.current = state;
// Keep the canvas's backing store in sync with its CSS size + devicePixelRatio.
useEffect(() => {
const canvas = canvasRef.current;
if (!canvas) return;
const resize = () => {
const dpr = window.devicePixelRatio ?? 1;
const rect = canvas.getBoundingClientRect();
canvas.width = Math.floor(rect.width * dpr);
canvas.height = Math.floor(rect.height * dpr);
};
resize();
window.addEventListener('resize', resize);
return () => window.removeEventListener('resize', resize);
}, []);
useAnimationLoop(() => {
const canvas = canvasRef.current;
if (!canvas) return;
renderFrame(canvas, stateRef.current);
});
useCursorSender(canvasRef as React.RefObject, onCursor);
return (
);
}
```
- [ ] **Step 3: Overwrite `Frontend/src/App.tsx`**
```tsx
import { useGameSocket } from './hooks/useGameSocket';
import { LanderCanvas } from './LanderCanvas';
// Vite dev server proxies `/ws` → `ws://localhost:5100`. In prod the backend
// serves the built static files, so same-origin works there too.
function buildWsUrl(): string {
const proto = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
return `${proto}//${window.location.host}/ws/game`;
}
export function App() {
const { connected, state, sendCursor } = useGameSocket(buildWsUrl());
return (
<>
);
}
interface StatusBarProps { connected: boolean; step: number; }
function StatusBar({ connected, step }: StatusBarProps) {
return (
●{' '}
{connected ? 'connected' : 'disconnected'} · step {step}
);
}
```
- [ ] **Step 4: Verify TypeScript compiles and build passes**
```bash
cd Frontend && npx tsc --noEmit && npm run build && cd ..
```
Expected: no TypeScript errors, `dist/` produced.
- [ ] **Step 5: Commit**
```bash
git add Frontend/src/hooks/useAnimationLoop.ts Frontend/src/LanderCanvas.tsx Frontend/src/App.tsx
git -c user.email=meelstorm@gmail.com -c user.name=meelstorm commit -m "feat(frontend): LanderCanvas + App wiring cursor and state to WebSocket"
```
---
## Task 7: End-to-end manual verification
**Files:** (none — verification only)
This task launches everything at once (backend + frontend) and confirms the ship renders and moves.
- [ ] **Step 1: Kill any stale processes**
```bash
pkill -f "dotnet.*Backend" 2>/dev/null; sleep 1
pkill -f "vite" 2>/dev/null; sleep 1
```
- [ ] **Step 2: Publish CLI (idempotent)**
```bash
dotnet publish GameCli/GameCli.csproj -c Release -o publish/GameCli
```
- [ ] **Step 3: Start the backend in the background**
```bash
ASPNETCORE_URLS=http://localhost:5100 dotnet run --project Backend --no-launch-profile > /tmp/backend.log 2>&1 &
BACKEND_PID=$!
sleep 5
grep -q "Loaded PPO policy" /tmp/backend.log && echo "backend loaded ONNX" || (echo "backend startup failed"; cat /tmp/backend.log; exit 1)
curl -sf http://localhost:5100/ && echo
```
Expected: `backend loaded ONNX` and health returns `GameCli Backend`.
- [ ] **Step 4: Start the Vite dev server**
```bash
cd Frontend
npm run dev > /tmp/vite.log 2>&1 &
VITE_PID=$!
cd ..
sleep 5
curl -sf http://localhost:5173/ | grep -q "Cursor-Following Lander" && echo "vite serving index"
```
Expected: `vite serving index`.
- [ ] **Step 5: WebSocket handshake test through Vite's proxy**
Use a small Node script or curl to prove the WS proxies through. Node one-liner (assumes `ws` is available; if not, skip this step and rely on the browser check below).
Simpler: just use `curl` to hit the frontend and confirm no 500 errors. The real WS test is the browser check.
- [ ] **Step 6: Browser check (manual — the deliverable)**
Open `http://localhost:5173/` in a browser. You should see:
- Black background with a slightly-lighter square (the world).
- A blue crosshair follows your mouse.
- A small white triangular ship appears somewhere in the world, twitching / firing engines as the (smoke-trained) PPO policy tries to control it.
- Top-left corner shows `● connected · step N` with N ticking up.
If the ship never appears or the socket says `disconnected`, capture what's on screen and the browser DevTools Network → WS tab for the `ws/game` connection to diagnose.
- [ ] **Step 7: Teardown**
```bash
kill $VITE_PID $BACKEND_PID 2>/dev/null
wait $VITE_PID $BACKEND_PID 2>/dev/null
```
- [ ] **Step 8: No commit — verification only**
---
## Definition of done for Plan 4
- `npx tsc --noEmit` in `Frontend/` reports 0 errors.
- `npm run build` produces `Frontend/dist/`.
- With backend running on 5100 and Vite dev server on 5173, opening `http://localhost:5173/` shows a canvas with a ship that responds to the cursor.
- Every source file has one clear responsibility; no file exceeds ~150 lines.
## Notes on real training vs the smoke model
The ship's motion quality directly reflects how well-trained the PPO policy is. The current `models/ppo_lander.onnx` was trained for only 10k steps in Plan 2 — it's essentially random with a slight bias. To see actual cursor-following behavior:
```bash
source .venv/bin/activate
python Training/train.py --steps 2000000 --n-envs 8
python Training/export_onnx.py \
--checkpoint checkpoints/ppo_lander_final.zip \
--out models/ppo_lander.onnx
```
Then restart the backend so it re-loads the new ONNX. Training takes on the order of an hour on CPU.