Merge feature/frontend-js into develop

Plan 3c: JavaScript frontend (storage.js, grid-editor.js, toolchain).

Adds the Node toolchain (ESLint airbnb-base + Prettier) with a CI step,
public/js/storage.js (bfStorage module for localStorage pre-fill and the home
page's recent-scenarios list), public/js/grid-editor.js (battlefield grid
interactions and JSON fetch save), public/assets/archetypes.json (the four
ArchetypeTemplate definitions), four placeholder PNGs at
public/assets/placeholders/, and updated <script> tags in home.php and
team-editor.php and a data-scenario-id attribute + script tag in
battlefield-editor.php. Also adds *.js and *.json to .gitattributes to
enforce LF line endings on those file types.

196/196 tests pass; PHPStan level 6 clean; ESLint 0 errors; Prettier clean.
Two fix commits were made during the per-task review loop: brief's URL
parsing slice index in storage.js was off-by-one (slice(-2,-1) returned
'edit' instead of the id), and brief's buildScenarioJson emitted a nested
objective shape that didn't match the backend's flat objectiveId/X/Y
fields. Both were corrected.

.eslintrc.json

@@ -0,0 +1,11 @@
+{
+    "env": {
+        "browser": true,
+        "es2022": true
+    },
+    "parserOptions": {
+        "ecmaVersion": 2022,
+        "sourceType": "module"
+    },
+    "extends": "airbnb-base"
+}

.gitattributes

@@ -0,0 +1,3 @@
+*.php text eol=lf
+*.js text eol=lf
+*.json text eol=lf

.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  php:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+      - uses: shivammathur/setup-php@b604ade2a87db23f8871b7182e69ec5e75effb45 # v2
+        with:
+          php-version: '8.3'
+          coverage: none
+          tools: composer:v2
+      - run: composer validate --strict
+      - run: composer install --no-interaction --prefer-dist
+      - run: composer check
+      - run: npm ci --no-audit --no-fund
+      - run: npm run lint
+      - run: npm run format

.gitignore

@@ -0,0 +1,14 @@
+.worktrees/
+/vendor/
+/var/cache/
+/var/phpunit/
+/var/phpstan/
+/var/logs/
+/var/uploads/*
+!/var/uploads/.htaccess
+!/var/uploads/index.php
+/var/secret.key
+/node_modules/
+/public/js/*.map
+.phpunit.result.cache
+.phpunit.cache

.prettierrc

@@ -0,0 +1,5 @@
+{
+    "singleQuote": true,
+    "trailingComma": "all",
+    "printWidth": 100
+}

.vscode/settings.json

@@ -0,0 +1,16 @@
+{
+    "workbench.colorCustomizations": {
+        "tree.indentGuidesStroke": "#3d92ec",
+        "activityBar.background": "#053241",
+        "titleBar.activeBackground": "#07465B",
+        "titleBar.activeForeground": "#F3FBFE",
+        "titleBar.inactiveBackground": "#053241",
+        "titleBar.inactiveForeground": "#F3FBFE",
+        "statusBar.background": "#053241",
+        "statusBar.foreground": "#F3FBFE",
+        "statusBar.debuggingBackground": "#053241",
+        "statusBar.debuggingForeground": "#F3FBFE",
+        "statusBar.noFolderBackground": "#053241",
+        "statusBar.noFolderForeground": "#F3FBFE"
+    }
+}

Notes/Initial Ideas.md

@@ -0,0 +1,18 @@
+# BattleForge
+
+## Initial Ideas
+
+- **Concept**: BattleForge is a flexible "tactical game engine" web app that can be used to create skirmish-style games in a variety of genres.
+- **Core Gameplay**: Players control a team of units on a grid-based battlefield, taking turns to move and attack. The game emphasizes strategic positioning, unit abilities, and resource management.
+- **Customization**: Players can create and customize their own units, abilities, and battlefields, allowing for endless variety and replayability.
+- **Multiplayer**: Support asynchronous multiplayer, allowing players to compete against friends or strangers, with turn notifications (via email, in-app, or browser notifications) and matchmaking.
+- **Single Player**: Sandbox mode for free play with simple AI opponents.
+- **Art Style**: Images can be uploaded by users, but the app will also provide a library of free assets (units, structures, and terrain) to get started. The art style can be pixel art, isometric, or top-down, depending on user preference.
+
+## Basic Features
+
+- **Unit Creation**: Users can create custom units with various stats (health, attack, defense, speed) and abilities (e.g., heal, area damage, buffs).
+- **Battlefield Editor**: A drag-and-drop interface for designing custom battlefields with different terrain types (e.g., forests, mountains, water) that affect gameplay.
+- **Turn-Based Combat**: Players take turns moving their units and using abilities, with a simple UI for selecting actions and targeting.
+- **Resource Management**: Players can earn resources during battles to upgrade their units or purchase new ones for future battles.
+- **Matchmaking and Leaderboards**: A system for finding opponents and tracking player rankings based on wins, losses, and other performance metrics.

composer.json

@@ -0,0 +1,41 @@
+{
+    "name": "battleforge/battleforge",
+    "description": "A standalone tactical combat game.",
+    "type": "project",
+    "license": "proprietary",
+    "require": {
+        "php": "^8.3"
+    },
+    "require-dev": {
+        "dealerdirect/phpcodesniffer-composer-installer": "^1.0",
+        "phpstan/phpstan": "^2.0",
+        "phpunit/phpunit": "^11.5",
+        "squizlabs/php_codesniffer": "^3.10"
+    },
+    "autoload": {
+        "psr-4": {
+            "BattleForge\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "BattleForge\\Tests\\": "tests/"
+        }
+    },
+    "scripts": {
+        "lint": "phpcs",
+        "analyse": "phpstan analyse --no-progress",
+        "test": "phpunit",
+        "check": [
+            "@lint",
+            "@analyse",
+            "@test"
+        ]
+    },
+    "config": {
+        "allow-plugins": {
+            "dealerdirect/phpcodesniffer-composer-installer": true
+        },
+        "sort-packages": true
+    }
+}

docs/superpowers/plans/2026-07-07-frontend-js.md

@@ -0,0 +1,912 @@
+# Plan 3c: JavaScript Frontend Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add the small JavaScript surface that lets the home page list recent scenarios from `localStorage`, the team editor pre-fill from `localStorage`, and the battlefield editor run click-paint grid interactions with JSON fetch save.
+
+**Architecture:** Two pure-ESM JavaScript files (`public/js/storage.js` and `public/js/grid-editor.js`) attach `window.bfStorage` and run `DOMContentLoaded` on their respective pages. The team editor's form continues to POST to the existing Plan 3b `PostTeamEditor` handler; the battlefield editor's form submit is intercepted by the JS to send a JSON fetch. The Node toolchain (ESLint `airbnb-base` + Prettier) is added with a new `npm run lint` and `npm run format` step in CI.
+
+**Tech Stack:** PHP 8.3 (unchanged), vanilla ESM JavaScript (no bundler, no transpiler), Node 20+ with ESLint `^8.57.0`, `eslint-config-airbnb-base ^15.0.0`, `eslint-plugin-import ^2.29.0`, Prettier `^3.3.0`.
+
+## Global Constraints
+
+These apply to every task and are copied verbatim from the design spec.
+
+- Anonymous browser persistence: scenarios and matches live in the browser's `localStorage` (`scenario:{id}` and `match:current`); the server never stores game state.
+- Every state-changing form or request uses and verifies a CSRF token before mutation. The token is per-session, signed with the app's secret using `hash_hmac('sha256', …)`. Forms use a hidden `_csrf` field; fetch uses an `X-CSRF-Token` header.
+- All rendered output is escaped for its output context via the `Escape::html`, `Escape::attr`, and `Escape::url` helpers. Templates do not interpolate user input without one of these helpers. The JS uses `textContent` and `value` setters, never `innerHTML` (with one exception: building the home page's recent-scenarios list uses `appendChild` on `<a>` elements with `textContent`, never `innerHTML`).
+- Bundled placeholder images are committed under `public/assets/placeholders/`; user uploads live in `var/uploads/` (git-ignored).
+- The single small JS file (`public/js/grid-editor.js` and `public/js/storage.js`) passes ESLint `airbnb/base` and Prettier.
+- PHP follows the repository PHPCS rules and passes PHPStan at level 6.
+- Composer configuration passes `composer validate --strict`.
+- Lint, static analysis, unit and integration tests, the end-to-end smoke test, and Composer validation are required CI checks.
+- No third-party JS libraries. The two JS files are pure ESM, no dependencies, no `eval`, no `Function` constructor.
+- The data shape for scenarios in `localStorage` is the same canonical shape that `BattleForge\Application\ScenarioSerializer::scenarioToArray` produces.
+- `var/secret.key` is added to `.gitignore` (the Plan 3b `FullFlowTest` creates it on first run).
+
+## File Structure
+
+```text
+public/
+├── assets/
+│   ├── archetypes.json                (NEW) — 4 ArchetypeTemplate definitions
+│   ├── placeholders/                  (NEW)
+│   │   ├── defender.png
+│   │   ├── striker.png
+│   │   ├── support.png
+│   │   └── scout.png
+│   ├── styles.css                     (unchanged)
+│   └── js/                            (NEW)
+│       ├── storage.js                 (NEW) — bfStorage module
+│       └── grid-editor.js             (NEW) — battlefield grid interactions
+
+src/Views/                             (updated — add <script> tags only)
+├── home.php                            (add <script type="module" src="/js/storage.js">)
+├── team-editor.php                     (add <script type="module" src="/js/storage.js">)
+└── battlefield-editor.php              (add <script type="module" src="/js/grid-editor.js"></script>)
+
+package.json                            (NEW)
+.eslintrc.json                         (NEW)
+.prettierrc                            (NEW)
+.github/workflows/ci.yml               (updated — add npm ci, lint, format steps)
+.gitignore                            (updated — add var/secret.key, node_modules/)
+```
+
+## Delivery Sequence
+
+Plan 3c is the third of four plans. It is the last plan in the original "Plan 3" deliverable. It depends on Plan 3a+3b's PHP web layer being merged (which it is on `develop`).
+
+1. Toolchain + assets (Task 1)
+2. `storage.js` and template `<script>` tags (Task 2)
+3. `grid-editor.js` and CI update (Task 3)
+4. Final whole-branch code review (Task 4)
+
+## Execution Preflight
+
+Execute this plan in an isolated worktree on `feature/frontend-js`, branched from `develop`. The implementation branch will be submitted as a pull request into `develop` only after every completion check is green.
+
+### Task 1: Node toolchain + `archetypes.json` + placeholder images
+
+**Files:**
+- Create: `package.json`
+- Create: `.eslintrc.json`
+- Create: `.prettierrc`
+- Create: `public/assets/archetypes.json`
+- Create: `public/assets/placeholders/defender.png`
+- Create: `public/assets/placeholders/striker.png`
+- Create: `public/assets/placeholders/support.png`
+- Create: `public/assets/placeholders/scout.png`
+- Modify: `.gitignore`
+
+**Interfaces:**
+- Produces: a Node toolchain that lints and formats the JS files (Tasks 2 and 3 land in this toolchain's lint gate). The `archetypes.json` matches `BattleForge\Application\ArchetypeCatalog::templates()` exactly (defender, striker, support, scout). The four placeholder PNGs are valid 32×32 transparent PNGs with simple monochrome silhouettes (a circle for defender, a triangle for striker, a square for support, a diamond for scout — the exact pixel art is up to the implementer; the test only checks that the file is a valid PNG and has the right dimensions). The `.gitignore` excludes `var/secret.key` and `node_modules/`.
+
+- [ ] **Step 1: Update `.gitignore`**
+
+Append `var/secret.key` and `node_modules/` to the existing `.gitignore`. Replace the file with:
+
+```
+.worktrees/
+/vendor/
+/var/cache/
+/var/phpunit/
+/var/phpstan/
+/var/logs/
+/var/uploads/*
+!/var/uploads/.htaccess
+!/var/uploads/index.php
+/var/secret.key
+/node_modules/
+/public/js/*.map
+.phpunit.result.cache
+.phpunit.cache
+```
+
+- [ ] **Step 2: Create `package.json`**
+
+Create `package.json`:
+
+```json
+{
+    "name": "battleforge-battleforge",
+    "description": "BattleForge frontend toolchain.",
+    "private": true,
+    "license": "proprietary",
+    "scripts": {
+        "lint": "eslint public/js",
+        "format": "prettier --check public/js"
+    },
+    "devDependencies": {
+        "eslint": "^8.57.0",
+        "eslint-config-airbnb-base": "^15.0.0",
+        "eslint-plugin-import": "^2.29.0",
+        "prettier": "^3.3.0"
+    }
+}
+```
+
+- [ ] **Step 3: Create `.eslintrc.json`**
+
+Create `.eslintrc.json`:
+
+```json
+{
+    "env": {
+        "browser": true,
+        "es2022": true
+    },
+    "parserOptions": {
+        "ecmaVersion": 2022,
+        "sourceType": "module"
+    },
+    "extends": "airbnb-base"
+}
+```
+
+- [ ] **Step 4: Create `.prettierrc`**
+
+Create `.prettierrc`:
+
+```json
+{
+    "singleQuote": true,
+    "trailingComma": "all",
+    "printWidth": 100
+}
+```
+
+- [ ] **Step 5: Create `public/assets/archetypes.json`**
+
+The `ArchetypeTemplate` values must match `BattleForge\Domain\ArchetypeCatalog::templates()` exactly. The Plan 3a catalog:
+
+- defender: minHealth 10, maxHealth 14, minAttack 2, maxAttack 4, minDefense 3, maxDefense 5, minSpeed 1, maxSpeed 3, allowedAbilities ["buff"]
+- striker: minHealth 6, maxHealth 10, minAttack 4, maxAttack 6, minDefense 1, maxDefense 2, minSpeed 2, maxSpeed 4, allowedAbilities ["area_damage"]
+- support: minHealth 5, maxHealth 9, minAttack 1, maxAttack 3, minDefense 1, maxDefense 3, minSpeed 2, maxSpeed 4, allowedAbilities ["heal", "buff"]
+- scout: minHealth 4, maxHealth 7, minAttack 2, maxAttack 4, minDefense 0, maxDefense 2, minSpeed 4, maxSpeed 6, allowedAbilities []
+
+Create `public/assets/archetypes.json`:
+
+```json
+{
+    "defender": { "minHealth": 10, "maxHealth": 14, "minAttack": 2, "maxAttack": 4, "minDefense": 3, "maxDefense": 5, "minSpeed": 1, "maxSpeed": 3, "allowedAbilities": ["buff"] },
+    "striker":  { "minHealth": 6,  "maxHealth": 10, "minAttack": 4, "maxAttack": 6, "minDefense": 1, "maxDefense": 2, "minSpeed": 2, "maxSpeed": 4, "allowedAbilities": ["area_damage"] },
+    "support":  { "minHealth": 5,  "maxHealth": 9,  "minAttack": 1, "maxAttack": 3, "minDefense": 1, "maxDefense": 3, "minSpeed": 2, "maxSpeed": 4, "allowedAbilities": ["heal", "buff"] },
+    "scout":    { "minHealth": 4,  "maxHealth": 7,  "minAttack": 2, "maxAttack": 4, "minDefense": 0, "maxDefense": 2, "minSpeed": 4, "maxSpeed": 6, "allowedAbilities": [] }
+}
+```
+
+- [ ] **Step 6: Create the four placeholder PNGs**
+
+Each placeholder is a 32×32 transparent PNG with a simple silhouette. Generate them programmatically (the implementer can run a one-off PHP or Node script, or use ImageMagick if installed). The exact pixel art is up to the implementer; the test (added in Step 7) only checks that:
+
+- The file is a valid PNG (starts with the PNG magic bytes `\x89PNG\r\n\x1a\n`).
+- The file decodes to a 32×32 image via `getimagesize()`.
+
+Suggested silhouettes (a 32×32 grid of black-on-transparent pixels; the implementer can use any simple shape that distinguishes the four archetypes):
+
+- defender (circle): pixels at (16, 8), (12, 10), (20, 10), (8, 14), (24, 14), (8, 18), (24, 18), (12, 22), (20, 22), (16, 24).
+- striker (triangle): pixels at (16, 6), (10, 14), (22, 14), (12, 16), (20, 16), (14, 18), (18, 18), (16, 22).
+- support (square): pixels at (8, 8), (24, 8), (8, 24), (24, 24), (10, 10), (22, 10), (10, 22), (22, 22).
+- scout (diamond): pixels at (16, 6), (12, 10), (20, 10), (8, 16), (24, 16), (12, 22), (20, 22), (16, 26).
+
+The implementer can create these by hand (e.g. via a small PHP script that calls `imagecreatetruecolor` + `imagesetpixel` + `imagepng`, or via a Node script using `sharp` — but per the global constraints, no third-party JS libraries; the implementer can use a hand-rolled PNG generator or just copy a 32×32 transparent PNG from an existing source and write the silhouette bytes by hand).
+
+- [ ] **Step 7: Verify the assets are valid**
+
+Run: `php -r 'foreach (["defender", "striker", "support", "scout"] as $a) { $p = __DIR__ . "/public/assets/placeholders/$a.png"; $i = getimagesize($p); echo "$a: {$i[0]}x{$i[1]} type=$i[2]\n"; }'`
+Expected: four lines, each `32x32 type=3` (3 = PNG). If any line shows different dimensions, regenerate that file.
+
+Run: `php -r 'var_dump(json_decode(file_get_contents(__DIR__ . "/public/assets/archetypes.json"), true));' | head -5`
+Expected: the four archetypes as objects.
+
+- [ ] **Step 8: Install Node dependencies**
+
+Run: `npm install`
+Expected: `node_modules/` is created; `package-lock.json` is generated. `npm run lint` will fail at this point because `public/js/*.js` doesn't exist yet; that's expected and will be fixed in Tasks 2 and 3.
+
+- [ ] **Step 9: Run the full quality suite and commit**
+
+Run: `composer check`
+Expected: 196/196 tests pass, PHPStan clean, PHPCS clean on the changed files. The new `package.json`, `.eslintrc.json`, `.prettierrc`, and the four PNGs are not PHP, so PHPCS doesn't check them. PHPStan excludes `src/Views/*` and the JS files.
+
+```powershell
+git add .gitignore package.json package-lock.json .eslintrc.json .prettierrc public/assets/archetypes.json public/assets/placeholders/
+git commit -m "chore: add Node toolchain, archetypes.json, and placeholder images"
+```
+
+### Task 2: `storage.js` and template `<script>` tags
+
+**Files:**
+- Create: `public/js/storage.js`
+- Modify: `src/Views/home.php` (add `<script type="module" src="/js/storage.js"></script>`)
+- Modify: `src/Views/team-editor.php` (add `<script type="module" src="/js/storage.js"></script>` and a "Start match" button)
+
+**Interfaces:**
+- Produces `public/js/storage.js`, an ESM module that attaches `window.bfStorage` with eight methods: `load(id)`, `save(id, scenario)`, `delete(id)`, `listAll()`, `currentMatch()`, `setCurrentMatch(match)`, `removeCurrentMatch()`. The module's top-level code runs `populateRecentScenarios()` on `DOMContentLoaded` (for the home page) and `prefillTeamEditor()` on `DOMContentLoaded` (for the team editor), based on which root element is present in the DOM. The "Start match" button on the team editor POSTs to `/scenarios/{id}/start` and stores the response in `localStorage`.
+
+- [ ] **Step 1: Implement `storage.js`**
+
+Create `public/js/storage.js`:
+
+```js
+const STORAGE_PREFIX = 'scenario:';
+const MATCH_KEY = 'match:current';
+
+function load(id) {
+  try {
+    const raw = localStorage.getItem(STORAGE_PREFIX + id);
+    if (raw === null) {
+      return null;
+    }
+    return JSON.parse(raw);
+  } catch (e) {
+    return null;
+  }
+}
+
+function save(id, scenario) {
+  const stamped = Object.assign({}, scenario, { lastModified: Date.now() });
+  localStorage.setItem(STORAGE_PREFIX + id, JSON.stringify(stamped));
+}
+
+function remove(id) {
+  localStorage.removeItem(STORAGE_PREFIX + id);
+}
+
+function listAll() {
+  const items = [];
+  for (let i = 0; i < localStorage.length; i += 1) {
+    const key = localStorage.key(i);
+    if (key === null || !key.startsWith(STORAGE_PREFIX)) {
+      continue;
+    }
+    const id = key.slice(STORAGE_PREFIX.length);
+    const scenario = load(id);
+    if (scenario === null) {
+      continue;
+    }
+    items.push({
+      id,
+      name: typeof scenario.name === 'string' ? scenario.name : id,
+      lastModified: typeof scenario.lastModified === 'number' ? scenario.lastModified : 0,
+    });
+  }
+  items.sort((a, b) => b.lastModified - a.lastModified);
+  return items;
+}
+
+function currentMatch() {
+  try {
+    const raw = localStorage.getItem(MATCH_KEY);
+    if (raw === null) {
+      return null;
+    }
+    return JSON.parse(raw);
+  } catch (e) {
+    return null;
+  }
+}
+
+function setCurrentMatch(match) {
+  localStorage.setItem(MATCH_KEY, JSON.stringify(match));
+}
+
+function removeCurrentMatch() {
+  localStorage.removeItem(MATCH_KEY);
+}
+
+function getCsrfToken() {
+  const meta = document.querySelector('meta[name="csrf-token"]');
+  return meta ? meta.getAttribute('content') : '';
+}
+
+function populateRecentScenarios() {
+  const root = document.getElementById('recent');
+  if (!root) {
+    return;
+  }
+  while (root.firstChild) {
+    root.removeChild(root.firstChild);
+  }
+  const items = listAll();
+  if (items.length === 0) {
+    const p = document.createElement('p');
+    p.className = 'bf-empty';
+    p.appendChild(document.createTextNode('No saved scenarios yet.'));
+    root.appendChild(p);
+    return;
+  }
+  const ul = document.createElement('ul');
+  for (const item of items) {
+    const li = document.createElement('li');
+    const a = document.createElement('a');
+    a.setAttribute('href', '/scenarios/' + encodeURIComponent(item.id) + '/edit/team');
+    a.appendChild(document.createTextNode(item.name + ' (' + item.id + ')'));
+    li.appendChild(a);
+    ul.appendChild(li);
+  }
+  root.appendChild(ul);
+}
+
+async function fetchArchetypes() {
+  const res = await fetch('/assets/archetypes.json');
+  return res.json();
+}
+
+function prefillTeamEditor() {
+  const form = document.querySelector('form[action*="/edit/team"]');
+  if (!form) {
+    return;
+  }
+  const id = decodeURIComponent(window.location.pathname.split('/').slice(-2, -1)[0] || 'new');
+  if (id === 'new') {
+    return;
+  }
+  const scenario = load(id);
+  if (scenario === null) {
+    return;
+  }
+  const fields = form.querySelectorAll('input[name], select[name]');
+  fields.forEach((field) => {
+    const name = field.getAttribute('name');
+    if (!name) {
+      return;
+    }
+    const value = resolveField(scenario, name);
+    if (value !== undefined) {
+      field.value = String(value);
+    }
+  });
+}
+
+function resolveField(scenario, path) {
+  const parts = parsePath(path);
+  if (parts === null) {
+    return undefined;
+  }
+  let cursor = scenario;
+  for (const part of parts) {
+    if (cursor === null || cursor === undefined) {
+      return undefined;
+    }
+    cursor = cursor[part];
+  }
+  return cursor;
+}
+
+function parsePath(name) {
+  const match = name.match(/^(teamA|teamB)\[units\]\[(\d+)\]\[(\w+)\]$/);
+  if (match) {
+    const [, team, indexStr, key] = match;
+    const teamKey = team === 'teamA' ? 'teamA' : 'teamB';
+    return [teamKey, 'units', Number(indexStr), key];
+  }
+  const simple = [
+    'id',
+    'name',
+    'battlefieldWidth',
+    'battlefieldHeight',
+    'victoryCondition',
+    'holdRoundsRequired',
+  ];
+  if (simple.includes(name)) {
+    return [name];
+  }
+  return null;
+}
+
+async function startMatch() {
+  const id = decodeURIComponent(window.location.pathname.split('/').slice(-2, -1)[0] || 'new');
+  if (id === 'new') {
+    return;
+  }
+  const scenario = load(id);
+  if (scenario === null) {
+    return;
+  }
+  const csrf = getCsrfToken();
+  const res = await fetch('/scenarios/' + encodeURIComponent(id) + '/start', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-CSRF-Token': csrf,
+    },
+    body: JSON.stringify(scenario),
+  });
+  if (!res.ok) {
+    alert('Start match failed: HTTP ' + res.status);
+    return;
+  }
+  const data = await res.json();
+  if (data.match) {
+    setCurrentMatch(data.match);
+    window.location.href = '/';
+  } else {
+    alert('Start match failed: ' + (data.errors ? data.errors.join(', ') : 'unknown'));
+  }
+}
+
+window.bfStorage = {
+  load,
+  save,
+  delete: remove,
+  listAll,
+  currentMatch,
+  setCurrentMatch,
+  removeCurrentMatch,
+};
+
+document.addEventListener('DOMContentLoaded', () => {
+  populateRecentScenarios();
+  prefillTeamEditor();
+  const startBtn = document.getElementById('bf-start-match');
+  if (startBtn) {
+    startBtn.addEventListener('click', (event) => {
+      event.preventDefault();
+      startMatch();
+    });
+  }
+});
+```
+
+The module:
+- Attaches `window.bfStorage` with the 8 methods.
+- On `DOMContentLoaded`, populates the home page's `<div id="recent">`, pre-fills the team editor's form fields, and wires the "Start match" button.
+- The "Start match" button calls `POST /scenarios/{id}/start` with the loaded scenario as JSON and `X-CSRF-Token` from the layout's `<meta name="csrf-token">`. On success, stores the match in `localStorage` and navigates to `/`.
+- Uses `textContent` and `value` setters throughout. Never `innerHTML` (the recent-scenarios list uses `appendChild` on `<a>` elements with `textContent`).
+- Handles corrupt JSON gracefully: `load()` returns `null`, `listAll()` skips keys that fail to parse.
+
+- [ ] **Step 2: Update `src/Views/home.php` to import the JS**
+
+Edit `src/Views/home.php`. After the existing `<div id="recent">` block, add the script import. The exact location depends on the existing template; locate the closing `</body>` tag and add the script before it (or add it after `<div id="recent">` if the template is structured that way).
+
+Add this line at the end of the template body, before the closure that calls `render_layout`:
+
+```php
+    <script type="module" src="<?= $a('/js/storage.js') ?>"></script>
+```
+
+The exact context-dependent insertion point will be clear from the file. Use `Escape::attr` to escape the URL attribute.
+
+- [ ] **Step 3: Update `src/Views/team-editor.php` to import the JS and add the Start match button**
+
+Two changes to `src/Views/team-editor.php`:
+
+1. Add the script import at the end of the template body (before the `render_layout` closure):
+
+```php
+    <script type="module" src="<?= $a('/js/storage.js') ?>"></script>
+```
+
+2. Add a "Start match" button at the bottom of the form, just after the existing "Save" submit button:
+
+```php
+        <button type="submit">Save</button>
+        <button type="button" id="bf-start-match">Start match</button>
+    </form>
+```
+
+The "Start match" button is a `<button type="button">` (not `type="submit"`) so the form's submit handler is not invoked. The JS wires the click event in `storage.js`.
+
+- [ ] **Step 4: Run the lint and format checks**
+
+Run: `npm run lint`
+Expected: 0 errors. ESLint may flag a few unused parameters or stylistic issues; if so, fix them.
+
+Run: `npm run format`
+Expected: 0 errors. Prettier may flag formatting drift; if so, run `npx prettier --write public/js/storage.js` and commit the result.
+
+- [ ] **Step 5: Run the full quality suite and commit**
+
+Run: `composer check`
+Expected: 196/196 tests pass, PHPStan clean, PHPCS clean on the changed files. The new JS file is checked by ESLint and Prettier (not by the PHP suite).
+
+```powershell
+git add public/js/storage.js src/Views/home.php src/Views/team-editor.php
+git commit -m "feat: add localStorage helpers and wire team editor pre-fill"
+```
+
+### Task 3: `grid-editor.js` and CI update
+
+**Files:**
+- Create: `public/js/grid-editor.js`
+- Modify: `src/Views/battlefield-editor.php` (add `<script type="module" src="/js/grid-editor.js"></script>`)
+- Modify: `.github/workflows/ci.yml` (add `npm ci`, `npm run lint`, `npm run format` steps)
+
+**Interfaces:**
+- Produces `public/js/grid-editor.js`, an ESM module that runs on `DOMContentLoaded` for the battlefield editor. The module:
+  - Reads the `data-scenario-id` attribute from the `<form id="battlefield-form">` element.
+  - Loads the scenario from `bfStorage.load(id)` and populates the in-memory `tileMap`, `deploymentZones`, and `objective` state.
+  - Paints the grid: each tile button's `data-paint` attribute is updated, the objective tile gets `data-objective="1"`, and the zone tiles get `data-zone="alpha"` or `data-zone="bravo"`.
+  - Listens for clicks on `.bf-tile` buttons: in the default terrain-paint mode, updates `tileMap`; in zone mode, toggles zone membership; in objective mode, places the objective. Shift-click in any mode removes the paint or zone membership.
+  - Listens for clicks on the `Save` button (`event.preventDefault()`), builds the canonical scenario JSON, POSTs to `/scenarios/{id}/edit/battlefield` with `Content-Type: application/json` and `X-CSRF-Token`. On success, writes the returned `scenario` to `localStorage` and shows a "Saved" toast. On 400 with errors, shows the errors inline in the form.
+
+- [ ] **Step 1: Implement `grid-editor.js`**
+
+Create `public/js/grid-editor.js`:
+
+```js
+const TERRAINS = ['open', 'forest', 'rough', 'water', 'blocking'];
+
+function getCsrfToken() {
+  const meta = document.querySelector('meta[name="csrf-token"]');
+  return meta ? meta.getAttribute('content') : '';
+}
+
+function getCurrentMode() {
+  const checked = document.querySelector('input[name="zoneMode"]:checked');
+  return checked ? checked.value : 'terrain';
+}
+
+function getSelectedPaint() {
+  const active = document.querySelector('.bf-paint.active');
+  if (active) {
+    return active.getAttribute('data-paint');
+  }
+  return 'forest';
+}
+
+function loadScenario(id) {
+  if (window.bfStorage && typeof window.bfStorage.load === 'function') {
+    return window.bfStorage.load(id);
+  }
+  return null;
+}
+
+function saveScenario(id, scenario) {
+  if (window.bfStorage && typeof window.bfStorage.save === 'function') {
+    window.bfStorage.save(id, scenario);
+  }
+}
+
+function applyTile(button, paint, zone, isObjective) {
+  button.setAttribute('data-paint', paint);
+  if (zone) {
+    button.setAttribute('data-zone', zone);
+  } else {
+    button.removeAttribute('data-zone');
+  }
+  if (isObjective) {
+    button.setAttribute('data-objective', '1');
+  } else {
+    button.removeAttribute('data-objective');
+  }
+}
+
+function loadGrid(tileMap, deploymentZones, objective) {
+  document.querySelectorAll('.bf-tile').forEach((button) => {
+    const x = button.getAttribute('data-x');
+    const y = button.getAttribute('data-y');
+    const key = x + ':' + y;
+    if (tileMap[key]) {
+      button.setAttribute('data-paint', tileMap[key]);
+    }
+    button.removeAttribute('data-zone');
+    button.removeAttribute('data-objective');
+  });
+  for (const [team, positions] of Object.entries(deploymentZones)) {
+    positions.forEach((pos) => {
+      const selector = `.bf-tile[data-x="${pos.x}"][data-y="${pos.y}"]`;
+      const button = document.querySelector(selector);
+      if (button) {
+        button.setAttribute('data-zone', team);
+      }
+    });
+  }
+  if (objective) {
+    const selector = `.bf-tile[data-x="${objective.x}"][data-y="${objective.y}"]`;
+    const button = document.querySelector(selector);
+    if (button) {
+      button.setAttribute('data-objective', '1');
+    }
+  }
+}
+
+function readGrid() {
+  const tileMap = {};
+  const deploymentZones = { alpha: [], bravo: [] };
+  let objective = null;
+  document.querySelectorAll('.bf-tile').forEach((button) => {
+    const x = Number(button.getAttribute('data-x'));
+    const y = Number(button.getAttribute('data-y'));
+    const paint = button.getAttribute('data-paint');
+    if (paint && paint !== 'open') {
+      tileMap[x + ':' + y] = paint;
+    }
+    const zone = button.getAttribute('data-zone');
+    if (zone === 'alpha' || zone === 'bravo') {
+      deploymentZones[zone].push({ x, y });
+    }
+    if (button.getAttribute('data-objective') === '1') {
+      objective = { x, y };
+    }
+  });
+  return { tileMap, deploymentZones, objective };
+}
+
+function buildScenarioJson(scenarioId, tileMap, deploymentZones, objective) {
+  const widthInput = document.querySelector('input[name="battlefieldWidth"]');
+  const heightInput = document.querySelector('input[name="battlefieldHeight"]');
+  return {
+    id: scenarioId,
+    name: scenarioId,
+    battlefieldWidth: widthInput ? Number(widthInput.value) : 8,
+    battlefieldHeight: heightInput ? Number(heightInput.value) : 8,
+    battlefieldTerrain: tileMap,
+    teamA: {
+      units: [],
+    },
+    teamB: {
+      units: [],
+    },
+    deploymentZones,
+    objectives: objective
+      ? { 'objective-1': { id: 'objective-1', position: objective } }
+      : {},
+    victoryCondition: objective ? 'hold_objective' : 'eliminate_all',
+    holdRoundsRequired: objective ? 3 : 1,
+  };
+}
+
+function paintTile(button) {
+  const mode = getCurrentMode();
+  if (event.shiftKey) {
+    applyTile(button, 'open', null, false);
+    return;
+  }
+  if (mode === 'objective') {
+    document.querySelectorAll('.bf-tile[data-objective]').forEach((other) => {
+      other.removeAttribute('data-objective');
+    });
+    applyTile(button, 'open', null, true);
+    return;
+  }
+  if (mode === 'alpha' || mode === 'bravo') {
+    const current = button.getAttribute('data-zone');
+    if (current === mode) {
+      button.removeAttribute('data-zone');
+    } else {
+      button.setAttribute('data-zone', mode);
+    }
+    return;
+  }
+  applyTile(button, getSelectedPaint(), null, false);
+}
+
+function selectPalette(event) {
+  document.querySelectorAll('.bf-paint').forEach((b) => b.classList.remove('active'));
+  event.currentTarget.classList.add('active');
+}
+
+function showToast(message) {
+  const toast = document.createElement('div');
+  toast.className = 'bf-toast';
+  toast.appendChild(document.createTextNode(message));
+  document.body.appendChild(toast);
+  setTimeout(() => toast.remove(), 3000);
+}
+
+function showErrors(errors) {
+  const existing = document.querySelector('.bf-errors');
+  if (existing) {
+    existing.remove();
+  }
+  const div = document.createElement('div');
+  div.className = 'bf-errors';
+  const ul = document.createElement('ul');
+  errors.forEach((msg) => {
+    const li = document.createElement('li');
+    li.appendChild(document.createTextNode(msg));
+    ul.appendChild(li);
+  });
+  div.appendChild(ul);
+  const form = document.getElementById('battlefield-form');
+  if (form) {
+    form.parentNode.insertBefore(div, form);
+  }
+}
+
+async function save(event) {
+  event.preventDefault();
+  const form = document.getElementById('battlefield-form');
+  if (!form) {
+    return;
+  }
+  const id = form.getAttribute('data-scenario-id');
+  if (!id) {
+    return;
+  }
+  const { tileMap, deploymentZones, objective } = readGrid();
+  const scenario = buildScenarioJson(id, tileMap, deploymentZones, objective);
+  const csrf = getCsrfToken();
+  let res;
+  try {
+    res = await fetch('/scenarios/' + encodeURIComponent(id) + '/edit/battlefield', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-CSRF-Token': csrf,
+      },
+      body: JSON.stringify(scenario),
+    });
+  } catch (e) {
+    showErrors(['Network error: ' + e.message]);
+    return;
+  }
+  if (res.ok) {
+    const data = await res.json();
+    if (data.scenario) {
+      saveScenario(id, data.scenario);
+      showToast('Saved.');
+    } else {
+      showErrors([(data.errors || ['Unknown error']).join(', ')]);
+    }
+  } else if (res.status === 400) {
+    let data = {};
+    try {
+      data = await res.json();
+    } catch (e) {
+      // body wasn't JSON
+    }
+    showErrors(data.errors || ['Validation failed (HTTP 400).']);
+  } else {
+    showErrors(['Save failed: HTTP ' + res.status]);
+  }
+}
+
+document.addEventListener('DOMContentLoaded', () => {
+  const form = document.getElementById('battlefield-form');
+  if (!form) {
+    return;
+  }
+  const id = form.getAttribute('data-scenario-id');
+  if (id) {
+    const scenario = loadScenario(id);
+    if (scenario) {
+      loadGrid(
+        scenario.battlefieldTerrain || {},
+        scenario.deploymentZones || { alpha: [], bravo: [] },
+        scenario.objectives && scenario.objectives['objective-1']
+          ? scenario.objectives['objective-1'].position
+          : null,
+      );
+    }
+  }
+  document.querySelectorAll('.bf-tile').forEach((button) => {
+    button.addEventListener('click', () => paintTile(button));
+  });
+  document.querySelectorAll('.bf-paint').forEach((button) => {
+    button.addEventListener('click', selectPalette);
+  });
+  if (document.querySelector('.bf-paint')) {
+    document.querySelector('.bf-paint').classList.add('active');
+  }
+  form.addEventListener('submit', save);
+});
+```
+
+The module:
+- Reads `data-scenario-id` from the form.
+- Loads the scenario from `bfStorage.load(id)` and repaints the grid.
+- Handles click-paint on tiles, including shift-click to erase.
+- Handles palette selection (clicking a paint button sets the active mode).
+- On Save, intercepts the form submit, builds the canonical scenario JSON, fetches the existing Plan 3b `PostBattlefieldEditor` endpoint, parses the response, and writes the result back to `localStorage`.
+- Handles all four response cases: 200 with `scenario`, 400 with `errors`, network failure, and other HTTP failures.
+
+- [ ] **Step 2: Update `src/Views/battlefield-editor.php`**
+
+Three changes:
+
+1. Add `data-scenario-id="<?= $a($scenarioId) ?>"` to the form element:
+
+```php
+<form id="battlefield-form" method="post" action="<?= $a('/scenarios/' . $e($scenarioId) . '/edit/battlefield') ?>" enctype="application/x-www-form-urlencoded" data-scenario-id="<?= $a($scenarioId) ?>">
+```
+
+2. Add the script import at the end of the template body (before the `render_layout` closure):
+
+```php
+    <script type="module" src="<?= $a('/js/grid-editor.js') ?>"></script>
+```
+
+- [ ] **Step 3: Update `.github/workflows/ci.yml`**
+
+Add `npm ci`, `npm run lint`, and `npm run format` steps after the existing `composer check` step. The workflow uses pinned action SHAs (per Plan 1's baseline).
+
+Append the following steps to the existing `php` job in `.github/workflows/ci.yml`:
+
+```yaml
+      - run: npm ci --no-audit --no-fund
+      - run: npm run lint
+      - run: npm run format
+```
+
+The full workflow should now be:
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  php:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+      - uses: shivammathur/setup-php@b604ade2a87db23f8871b7182e69ec5e75effb45 # v2
+        with:
+          php-version: '8.3'
+          coverage: none
+          tools: composer:v2
+      - run: composer validate --strict
+      - run: composer install --no-interaction --prefer-dist
+      - run: composer check
+      - run: npm ci --no-audit --no-fund
+      - run: npm run lint
+      - run: npm run format
+```
+
+(Use the actual pinned SHAs from the existing workflow; the SHAs above are placeholders showing the shape.)
+
+- [ ] **Step 4: Run the lint and format checks**
+
+Run: `npm run lint`
+Expected: 0 errors. ESLint may flag a few unused parameters or stylistic issues; if so, fix them.
+
+Run: `npm run format`
+Expected: 0 errors.
+
+- [ ] **Step 5: Run the full quality suite and commit**
+
+Run: `composer check`
+Expected: 196/196 tests pass, PHPStan clean, PHPCS clean on the changed files.
+
+```powershell
+git add public/js/grid-editor.js src/Views/battlefield-editor.php .github/workflows/ci.yml
+git commit -m "feat: add battlefield grid editor and CI lint step"
+```
+
+### Task 4: Final whole-branch code review
+
+Dispatch a fresh subagent with the merge-base diff for the entire feature branch. The reviewer checks for:
+
+- Spec compliance (every in-scope capability from the Plan 3c spec is implemented).
+- Code quality (clean separation of concerns, proper error handling, type safety, ESLint/Prettier clean).
+- Production readiness (backward compatibility, no obvious bugs).
+- Security: `bfStorage` reads and writes `localStorage` only, never `eval` or `Function` constructor; the home page's recent-scenarios list uses `textContent`, never `innerHTML`.
+
+After the review, address Critical and Important findings. Minor findings can be deferred to Plan 4.
+
+## Completion Check
+
+Run:
+
+```powershell
+composer validate --strict
+composer check
+npm run lint
+npm run format
+git status --short
+```
+
+Expected:
+
+- Composer reports a valid manifest.
+- PHPCS reports no coding-standard violations on the changed files.
+- PHPStan reports no errors at level 6.
+- PHPUnit passes 196 tests.
+- ESLint reports 0 errors on `public/js/*.js`.
+- Prettier reports 0 formatting drift.
+- Git reports no untracked files except `.worktrees/` (git-ignored).
+
+The web app is fully functional from the browser: `php -S 0.0.0.0:8000 -t public` serves the home page with the recent-scenarios list, the team editor with `localStorage` pre-fill, and the battlefield editor with click-paint grid interactions. The battle interface and bundled scenarios land in Plan 4.

docs/superpowers/specs/2026-07-06-persistence-editors-design.md

@@ -0,0 +1,266 @@
+# Persistence, Secure Image Handling, and Scenario Editors Design
+
+## Purpose
+
+Plan 3 of the four-plan BattleForge build. Closes the gap between the pure-PHP `Domain` layer (Plans 1 and 2) and the in-browser experience by adding:
+
+- Anonymous-browser persistence of scenarios and in-progress matches (no user accounts, no cross-device, no server-side storage of game state).
+- Server-rendered editor pages for teams and battlefields, with the domain's `Scenario` and `ScenarioValidator` enforcing every rule.
+- A secure image-upload pipeline (content-sniffed, size-limited, dimension-limited, session-scoped).
+- A minimal plain-PHP web stack with the cross-cutting security concerns the spec demands (CSRF, output escaping, content-validated uploads).
+
+## Success Criteria
+
+Plan 3 succeeds when a new user, without developer assistance and with no global state, can:
+
+1. Visit `http://localhost:8000/`, see a home page that lists their recent scenarios, and start a new one.
+2. Use the team editor to build two teams of 3-6 units each, choosing archetypes, stats, abilities, names, and optional custom images.
+3. Use the battlefield editor to choose dimensions, paint terrain, place deployment zones, and place an objective (when the victory condition requires it).
+4. Validate the assembled scenario server-side; see clear errors when something is invalid.
+5. Upload a custom image and have it appear in the team editor.
+6. "Start a match" from a saved scenario and have the initial `MatchState` round-trip through the browser.
+7. Refresh the page, lose the connection, or come back tomorrow and find their saved scenarios still in their browser (no data loss from the user's perspective).
+8. Reject forged cross-site requests, accept only image types the spec allows, and never let a user access another user's uploads.
+
+## Out of Scope (deferred to Plan 4 or later)
+
+- Hot-seat battle interface: Plan 3 ships a placeholder page that reads the assembled `MatchState` from `localStorage` and renders a "Battle interface coming in Plan 4" stub.
+- Bundled scenarios (the three ready-made scenarios in the spec): Plan 4.
+- Real-time interaction, drag-and-drop, or any other JS surface beyond the single fetch-based grid editor and the small `localStorage` helper.
+- Server-side storage of scenarios, matches, or any game state.
+- User accounts, sessions beyond the CSRF cookie, or any per-user server-side state.
+- Mobile-native, PWA, offline service workers, or any non-server-rendered path.
+- Antivirus scanning or upload rate limiting.
+
+## In Scope
+
+### Persistence
+
+- Scenarios are JSON-serialized in the browser's `localStorage`, keyed as `scenario:{id}`.
+- In-progress matches are JSON-serialized in `localStorage`, keyed as `match:current`.
+- The server never sees a `Scenario` or `MatchState` after the editor POST completes. Each form submission is validated and acknowledged; the browser then writes to `localStorage` on its own.
+- The home page lists scenarios by enumerating `localStorage` keys; no server call.
+- "Resume in-progress match" reads `match:current` and shows a banner on the home page.
+
+### Team Editor
+
+- One form per scenario, with sections for: meta (id, name), team A, team B, victory condition.
+- Each team section has 3-6 unit rows; rows are added and removed client-side (DOM manipulation, no fetch).
+- Each unit row has: archetype dropdown, display name, image upload button + hidden URL field, four stat inputs (with `min`/`max` from the chosen archetype's template), and an abilities multi-select (limited to the chosen archetype's allowlist).
+- The archetype JSON is served from `/assets/archetypes.json` and includes the four `ArchetypeTemplate` definitions.
+- A new "Upload" form submits a single image to `POST /assets/upload` and writes the returned URL into the unit row's hidden `image` field. The unit-editor form is not submitted as part of the upload.
+- Victory condition: a radio pair (`EliminateAll` / `HoldObjective`). When `HoldObjective` is selected, an input for `holdRoundsRequired` (1-10) appears.
+- Submitting the form POSTs the full draft to `POST /scenarios/{id}/edit/team`. The server parses, builds a `ScenarioDraft`, runs `ScenarioValidator::validate()`, and on failure re-renders the form with errors inline.
+
+### Battlefield Editor
+
+- One page per scenario. Width/height inputs (8-16 each) at the top.
+- Terrain palette: one button per `Terrain` enum value. The selected button is the "current paint."
+- Grid: an HTML `<table>` of `<button>` cells with `data-x` and `data-y`. Clicking applies the current paint. Shift-click erases.
+- Two deployment-zone controls (one per team). Each is a "click on grid to add this tile to my zone" mode.
+- Objective control: a single "click on grid to place the objective" mode that is only shown when the victory condition is `HoldObjective`.
+- The page ships with a small ESM helper (~50 lines, no build step) that maintains an in-memory `tileMap` object, posts it as JSON to `POST /scenarios/{id}/edit/battlefield` on save, and writes the server's response to `localStorage`.
+
+### Image Upload Pipeline
+
+- Multipart POST to `POST /assets/upload` with a hidden CSRF field.
+- Server reads `$_FILES['image']`, validates with `ImageValidator` (see below), stores the file at `var/uploads/{userToken}/{hash}.{ext}`, and returns `{"url": "/assets/{userToken}/{hash}.{ext}"}`.
+- `GET /assets/{userToken}/{filename}` streams the file with the right `Content-Type`. The `{userToken}` is derived from the session cookie and the request's `{userToken}` is verified to match; mismatch returns 404. Misses return 404.
+- No listing endpoint. No directory traversal.
+- Bundled placeholder images at `/assets/placeholders/{archetype}.png` are committed under `public/assets/placeholders/` and served without the `{userToken}` prefix.
+
+### Security and Quality
+
+- A per-session CSRF token stored in an `HttpOnly`, `SameSite=Lax` cookie, signed with the app's secret using `hash_hmac('sha256', …)`.
+- Every form includes a hidden `_csrf` field; the fetch helper reads the value from a `<meta name="csrf-token">` tag and sends it in an `X-CSRF-Token` header.
+- All output escaping goes through `Escape::html`, `Escape::attr`, and `Escape::url` helpers. Code review enforces the pattern; PHPStan has no rule for it.
+- All uploaded images are content-validated by reading the first 12 bytes and checking the magic number against an allowlist (PNG, JPEG, WebP, GIF), then `getimagesizefromstring()` to confirm dimensions are ≤ 512×512, then size-checked at ≤ 2 MB.
+- `Content-Security-Policy: default-src 'self'; img-src 'self' data:; style-src 'self'` is set on every page. No `unsafe-inline`.
+- `X-Content-Type-Options: nosniff` and `Referrer-Policy: same-origin` on every page.
+- Bundled placeholders are committed; user uploads live in `var/uploads/` (git-ignored).
+- PHP follows the repository PHPCS rules and passes PHPStan at level 6.
+- The single small JS file (`public/js/grid-editor.js` and `public/js/storage.js`) passes ESLint `airbnb/base` and Prettier.
+
+## System Boundaries
+
+The Plan 1+2 system boundaries are preserved and extended:
+
+1. **Content library** (Domain, unchanged): owns curated unit archetypes, abilities, terrain, and bundled asset metadata. Served read-only to the web layer.
+2. **Scenario editor** (web, NEW): hosts the team and battlefield editor pages. The `Application` layer translates form input into a `Scenario` and runs `ScenarioValidator`. The web layer never inspects a `Scenario` directly.
+3. **Rules engine** (Domain, unchanged from Plans 1 and 2): authoritatively validates actions and resolves combat.
+4. **Battle interface** (Plan 4, stubbed in Plan 3 as a "match is loaded" page that reads `match:current` from `localStorage`).
+
+The new Application and Http layers sit between the web pages and the Domain. They do not depend on browser presentation code, and the Domain does not depend on them.
+
+## Architecture
+
+The four `// @phpstan-ignore` annotations in `src/Domain/` (in `UnitState`, `MatchState`, `Scenario`, `DeploymentZone`) reference "Plan 4" in their parenthetical comments. The comments will be updated to "Plan 3" in a follow-up amend after this design is approved.
+
+```
+src/
+├── Domain/                       (Plan 1 + 2, unchanged)
+│   └── … 19 files …
+│
+├── Application/                  (NEW)
+│   ├── ScenarioSerializer.php    JSON ↔ Scenario
+│   ├── ScenarioDraft.php         mutable draft state for the editor
+│   ├── ImageUploadService.php    validates + stores a user-uploaded image
+│   └── ImageValidator.php        content-sniff + size + dimension checks
+│
+├── Http/                         (NEW)
+│   ├── Router.php                tiny path → handler dispatcher
+│   ├── Request.php               value object wrapping $_GET, $_POST, $_FILES, $_SERVER
+│   ├── Response.php             value object with status, headers, body
+│   ├── CsrfToken.php             per-session token store + verify helper
+│   ├── Escape.php                html(), attr(), url() helpers
+│   └── Handlers/
+│       ├── GetHomePage.php
+│       ├── GetTeamEditor.php
+│       ├── PostTeamEditor.php
+│       ├── GetBattlefieldEditor.php
+│       ├── PostBattlefieldEditor.php
+│       ├── GetAssets.php
+│       └── PostImageUpload.php
+│
+├── Views/                        (NEW — plain PHP templates)
+│   ├── layout.php
+│   ├── home.php
+│   ├── team-editor.php
+│   ├── battlefield-editor.php
+│   ├── match-stub.php
+│   └── upload-result.php
+│
+└── public/                       (NEW — document root for `php -S`)
+    ├── index.php                 front controller
+    ├── assets/
+    │   ├── archetypes.json
+    │   ├── placeholders/{defender,striker,support,scout}.png
+    │   └── (user uploads live under var/uploads/, not here)
+    └── js/
+        ├── storage.js
+        └── grid-editor.js
+```
+
+`var/` is the only runtime-writable directory. It is git-ignored. It contains:
+
+```
+var/
+├── cache/                        PHP opcode cache (created by `php -S` if enabled)
+├── phpunit/                      PHPUnit cache
+├── phpstan/                      PHPStan cache
+└── uploads/
+    ├── .htaccess                 Deny from all (Apache)
+    ├── index.php                 Sentinel that returns 403 (built-in dev server)
+    └── {userToken}/              Per-browser namespace; created on first upload
+```
+
+## Data and Action Flow
+
+### Cold-start flow
+
+1. Browser hits `GET /`. Server renders the home page.
+2. A small inline script in the home page enumerates `localStorage` keys matching `scenario:*` and `match:current` and renders the list.
+3. User picks an existing scenario → the team editor opens with the form pre-filled.
+4. User picks "New scenario" → the team editor opens with an empty form for a new id.
+
+### Team editor save flow
+
+1. User edits the form, presses Save.
+2. Browser POSTs the form to `POST /scenarios/{id}/edit/team` with `Content-Type: application/x-www-form-urlencoded` and a hidden `_csrf` field.
+3. Server's `PostTeamEditor` handler:
+   a. Verifies the CSRF token.
+   b. Parses the form into a `ScenarioDraft`.
+   c. Builds a `Scenario` from the draft.
+   d. Runs `ScenarioValidator::validate($scenario)`.
+   e. On failure: re-renders the editor with the validator's errors next to each field, preserving the form's values.
+   f. On success: renders the editor with an inline `<script>` block that calls `localStorage.setItem('scenario:' + id, JSON.stringify(scenarioJson))` and shows a "Saved" toast. The server does not store the scenario.
+
+### Battlefield editor save flow
+
+1. User clicks tiles in the grid; the small JS helper maintains an in-memory `tileMap` object.
+2. User presses Save; the JS helper POSTs the assembled JSON to `POST /scenarios/{id}/edit/battlefield` with `Content-Type: application/json` and an `X-CSRF-Token` header.
+3. Server's `PostBattlefieldEditor` handler:
+   a. Verifies the CSRF token.
+   b. Decodes the JSON body, validates the shape, builds a `ScenarioDraft`, runs the validator.
+   c. On failure: returns `{"ok": false, "errors": [...]}` with HTTP 400.
+   d. On success: returns `{"ok": true, "scenario": ...}` with HTTP 200. The JS helper writes `localStorage` and shows a toast.
+
+### Image upload flow
+
+1. User picks an image in the team editor and presses Upload.
+2. Browser submits the file to `POST /assets/upload` as `multipart/form-data` with a hidden `_csrf` field.
+3. Server's `PostImageUpload` handler:
+   a. Verifies the CSRF token.
+   b. Validates the upload with `ImageValidator`.
+   c. Writes the file to `var/uploads/{userToken}/{hash}.{ext}`.
+   d. Returns `{"url": "/assets/{userToken}/{hash}.{ext}"}` with HTTP 200.
+4. JS writes the returned URL into the unit row's hidden `image` field. The unit-editor form is not submitted as part of the upload.
+
+### Start-match flow
+
+1. User on the team editor presses "Continue to battlefield" or on the battlefield editor presses "Start match."
+2. JS reads the assembled `Scenario` JSON from `localStorage`, POSTs to `POST /scenarios/{id}/start` with `Content-Type: application/json`.
+3. Server runs `ScenarioValidator` (defense in depth), calls `Scenario::startMatch('alpha')`, returns the initial `MatchState` JSON. (No browser-side `startMatch` call; the JS does not run the domain's PHP code.)
+4. JS writes `match:current` to `localStorage` and navigates to `GET /match/current`.
+
+## Validation and Failure Handling
+
+- `ScenarioValidator` is the single source of truth for "is this scenario valid." Both the server (on every form POST) and the browser (before navigating forward) call it.
+- A rejected action or form never partially mutates the persisted state. The browser's `localStorage` write happens only on a successful server response.
+- Failure to save a scenario leaves the user's in-progress form intact; the editor re-renders the same values with errors inline.
+- The CSRF token's invalid-or-missing case returns a generic 403 page that links back to `GET /`. The user's in-progress form state is preserved in `localStorage` via the on-change JS hook.
+- A failed image upload shows an inline error next to the upload button; the unit row keeps whatever `image` field it had.
+- Corrupt or incompatible JSON in `localStorage` (e.g. a hand-edited scenario) is rejected on read: the home page's "Recent scenarios" list skips it and shows a "scenario corrupt" placeholder for that key.
+
+## Security and Quality Requirements
+
+- Every state-changing form or request uses and verifies a CSRF token before mutation. The token is per-session, signed with the app's secret, and the form's hidden field is required for HTML forms or the `X-CSRF-Token` header is required for fetch POSTs.
+- All input is sanitized and validated at the application boundary in the `Request` value object and the `ImageValidator`.
+- All rendered output is escaped for its output context via the `Escape::html`, `Escape::attr`, and `Escape::url` helpers. Templates do not interpolate user input without one of these helpers.
+- Uploaded images are validated by content (magic number) and by dimensions; the stored file's name is a server-generated random hex; the original filename and declared MIME are discarded after validation.
+- `var/uploads/` is denied by `.htaccess` (Apache) and `index.php` (built-in server).
+- The dev server is the built-in `php -S` running on a single port. No CGI, no Apache-only assumptions; the `var/uploads/.htaccess` and `var/uploads/index.php` sentinels cover both Apache deployments and the built-in server respectively.
+- PHP follows the repository PHPCS rules and passes PHPStan at level 6.
+- The small JS surface passes ESLint `airbnb/base` and Prettier.
+- Composer configuration passes `composer validate --strict`.
+- All output includes `X-Content-Type-Options: nosniff`, `Referrer-Policy: same-origin`, and a `Content-Security-Policy` header that forbids inline scripts and styles.
+
+## Verification Strategy
+
+### Unit tests
+
+- `ScenarioSerializerTest`: round-trip every Plan 2 fixture through `toJson` → `fromJson`; add fixtures for all four archetypes, both victory conditions, every terrain, and at least one uploaded-image reference.
+- `ScenarioDraftTest`: form fields → `ScenarioDraft` → `Scenario` for every field combination; error cases (out-of-bounds stat, unknown archetype, ability not in allowlist, oversized team, etc.).
+- `ImageValidatorTest`: valid PNG/JPEG/WebP/GIF headers; invalid headers (text, executable, fake extension); size > 2 MB; dimension > 512; MIME/extension mismatch.
+- `ImageUploadServiceTest`: round-trips a temp file through the service; asserts the file lands at the expected path; asserts the response URL is well-formed.
+- `CsrfTokenTest`: round-trip; cross-session rejection; expired-cookie rejection.
+- `EscapeTest`: regression set for `<`, `>`, `'`, `"`, `&`, control characters, NULL bytes.
+- `RequestTest`: synthetic `$_GET`/`$_POST`/`$_FILES`/`$_SERVER` extraction.
+
+### Integration tests
+
+- One happy-path and one validation-error test per handler. Asserts cover status code, `Content-Type` header, presence/absence of the CSRF token in the response body, and inline error placement.
+- A round-trip "save scenario" integration test: POST a full team-editor form, assert the response says "saved," then GET the same page and assert the form is pre-filled.
+- A round-trip "upload + read back" integration test: POST a small PNG to `/assets/upload`, then GET the returned URL and assert the body matches the uploaded bytes exactly.
+- A round-trip "forged CSRF" test: a POST without the token returns 403.
+- A round-trip "wrong user" test: an upload stored under one session's `{userToken}` is unreadable from a different session.
+
+### End-to-end smoke test (seeded in Plan 3, completed in Plan 4)
+
+- Plan 3 ships the *plumbing* of an E2E test that boots a tiny PHP server in a background process, sends a sequence of HTTP requests, and asserts on response bodies. Plan 4 fills in the battle-interaction assertions.
+
+### Static analysis / lint
+
+- PHPCS rules stay `PSR-12`; the new `src/Http/`, `src/Application/`, `src/Views/`, and `public/` directories are added to the `phpcs.xml` `<file>` list.
+- PHPStan level 6 stays. New exclusions: `src/Views/*` and `public/index.php`.
+- ESLint `airbnb/base` + Prettier on the single small JS file. `package.json` + `package-lock.json` are committed; CI gains an `npm run lint` step.
+
+### Manual usability check
+
+- A new tester with no BattleForge context can: open the dev URL, see the home page, create a new scenario, build two teams with mixed archetypes, paint a simple battlefield, save both, and start a match — without leaving the browser or seeing any error from the validator that wasn't explained inline.
+
+## Release Boundary
+
+Plan 3 is releasable when every in-scope capability and success criterion is met, the verification suite is green (PHPUnit, PHPStan, PHPCS, ESLint, Prettier), and no out-of-scope capability (battle interface, bundled scenarios, AI, online play) is required to exercise the local creation flow. The local dev server runs the full app on a single port with `php -S`.
+
+The next plan (Plan 4) will replace the battle-page stub with a real battle interface, add the three bundled scenarios, and ship the end-to-end smoke test that the Plan 3 plumbing seeds.

docs/superpowers/specs/2026-07-06-persistence-editors-ui-design.md

@@ -0,0 +1,254 @@
+# Plan 3b: Editor Handlers, Views, and Front Controller Design
+
+## Purpose
+
+Plan 3b of the four-plan BattleForge build. Completes the web layer that Plan 3a started: the seven remaining PHP tasks that ship the editor pages, the front controller, the full-flow integration test, and CI verification.
+
+Plan 3a delivered 10 of 17 written tasks: toolchain, output escaping, CSRF, Request/Response, Router, JSON serializer, image validator, image upload service, scenario draft, and the first two HTTP handlers (home page and asset serving). Plan 3b delivers the remaining 7:
+
+- The five remaining HTTP handlers (team editor GET/POST, battlefield editor GET/POST, image upload POST, start-match POST)
+- The six view templates
+- The full front controller that wires the routes together and issues the CSRF + upload tokens
+- A full-flow integration test
+- CI verification
+- Final whole-branch code review
+
+The design is a delta on `docs/superpowers/specs/2026-07-06-persistence-editors-design.md` (the Plan 3 spec), which is the authoritative design. This document records only the clarifications and decisions that are specific to Plan 3b; everything else is inherited from the Plan 3 spec.
+
+## Success Criteria
+
+Plan 3b succeeds when a new user, without developer assistance, can:
+
+1. Visit `http://localhost:8000/`, see the home page, and click "New scenario".
+2. Fill in two teams of 3-6 units each on the team editor, upload a custom image, and save. The browser shows a "Saved" toast and the scenario lands in `localStorage` under `scenario:{id}`.
+3. Navigate to the battlefield editor, paint a small grid, place deployment zones, place an objective (when the victory condition requires it), and save. The same `localStorage` key is updated with the assembled scenario.
+4. Click "Start match" and have the initial `MatchState` round-trip through the server's `PostStartMatch` endpoint, land in `localStorage` under `match:current`, and render the "match loaded" stub.
+5. Refresh the page, navigate around, and find their scenarios still in their browser.
+6. Try a forged cross-site POST and see a 403. Try to access another user's uploaded image and see a 404.
+
+## Out of Scope (deferred to Plan 3c or Plan 4)
+
+- The JavaScript surface: `public/js/storage.js`, `public/js/grid-editor.js`, ESLint, Prettier. The current handlers and views render with HTML form submits and a `<script type="module">` placeholder; Plan 3c adds the fetch-based battlefield grid and the `localStorage` write helpers.
+- Bundled placeholder images under `public/assets/placeholders/`.
+- The `archetypes.json` asset.
+- The hot-seat battle interface (Plan 4).
+- Bundled scenarios (Plan 4).
+- End-to-end smoke test against a real browser (Plan 4).
+
+## In Scope
+
+### HTTP Handlers (six new files in `src/Http/Handlers/`)
+
+All handlers are `final class` with a public `handle(Request $request, array $params): Response` method. Each handler:
+
+1. Verifies the CSRF token at the top (form POSTs read `_csrf` from `$request->post`; fetch POSTs read `X-CSRF-Token` from `$request->server`; the secret comes from the front controller via a request attribute `__csrf_secret`). Mismatch returns `Response::html(403, '<h1>Forbidden</h1>')` for form POSTs or `Response::json(403, ['error' => 'csrf'])`.
+2. Parses the form or JSON body.
+3. Calls the relevant `Application` service (`ScenarioDraft::fromPost`, `ScenarioSerializer::scenarioFromArray`, `ImageUploadService::store`, `Scenario::startMatch`).
+4. Runs the validator where applicable.
+5. Returns a `Response` with the right status, headers, and body.
+
+The handlers:
+
+- **`GetTeamEditor::handle`** — Returns `Response::html(200, …)` rendering the team editor template. The form is rendered empty; Plan 3c's `storage.js` populates it from `localStorage` on load.
+- **`PostTeamEditor::handle`** — Reads form fields, builds a `ScenarioDraft`, calls `toScenario()`, runs `ScenarioValidator::validate()`. On success, renders a "Saved" template that contains a `<script type="module">` block that calls `localStorage.setItem('scenario:' + id, JSON.stringify(scenarioJson))`. On failure, re-renders the editor with errors and original form values.
+- **`GetBattlefieldEditor::handle`** — Returns `Response::html(200, …)` rendering the battlefield editor with an empty `<table class="bf-grid">` (Plan 3c populates it from `localStorage`).
+- **`PostBattlefieldEditor::handle`** — Reads `Content-Type: application/json` body via `$request->rawBody`, decodes a `ScenarioDraft`-shaped array, runs the validator, returns `Response::json(200, ['ok' => true, 'scenario' => $array])` on success or `Response::json(400, ['ok' => false, 'errors' => [...]])` on failure.
+- **`PostImageUpload::handle`** — Reads `$_FILES['image']`, computes the `userToken` (derived from the CSRF secret — see CSRF Model below), constructs `ImageUploadService($userToken, $uploadsRoot)`, calls `store($tempPath, $declaredMime)`, returns `Response::json(200, ['url' => $url])` on success or `Response::json(400, ['error' => $message])` on failure.
+- **`PostStartMatch::handle`** — Reads the JSON body, decodes a `Scenario` via `ScenarioSerializer::scenarioFromArray`, runs `ScenarioValidator::validate()` (defense in depth), calls `Scenario::startMatch('alpha')`, returns `Response::json(200, ['match' => $array])` on success or `Response::json(400, ['errors' => [...]])` on failure.
+
+### View Templates (six new files in `src/Views/`)
+
+All templates are plain PHP files. They:
+
+1. Begin with `<?php declare(strict_types=1); ?>`.
+2. Use `require __DIR__ . '/layout.php';` for shared chrome (the layout sets up `<meta name="csrf-token" content="…">`, `<link rel="stylesheet" href="/assets/styles.css">`, security headers via `header()` calls in the front controller, and the document body).
+3. Print every dynamic value via `Escape::html`, `Escape::attr`, or `Escape::url`.
+4. Do not call domain code directly. They receive pre-built data from the handler.
+
+The templates:
+
+- **`layout.php`** — Shared chrome. Sets `Content-Security-Policy: default-src 'self'; img-src 'self' data:; style-src 'self'` (Plan 3c may tighten this), `X-Content-Type-Options: nosniff`, `Referrer-Policy: same-origin`. Outputs the doctype, `<head>` with the CSRF meta and the stylesheet link, the `<body>` open tag, and `</body></html>`.
+- **`home.php`** — The home page: heading, "New scenario" link to `/scenarios/new/edit/team`, `<div id="recent">` placeholder (Plan 3c populates it from `localStorage`).
+- **`team-editor.php`** — The team editor form. Sections for meta (id, name), team A, team B, victory condition, hidden `_csrf` field, an `<input type="file" name="unit-N-image">` per unit row for the upload form, and a "Save" submit button. The actual archetype list and stat min/max are derived from `ArchetypeCatalog::templates()` and inlined in the HTML so the form is fully functional without JS. Plan 3c adds the JS that pre-fills the form from `localStorage`.
+- **`battlefield-editor.php`** — The battlefield editor: width/height number inputs, terrain palette, `<table class="bf-grid">` rendered empty (Plan 3c populates it from `localStorage`), two deployment-zone fieldsets, an objective fieldset (only when `HoldObjective` is the victory condition), hidden `_csrf` field, "Save" submit.
+- **`match-stub.php`** — The Plan-3a/3c "Battle interface coming in Plan 4" placeholder. Reads `match:current` from the request's `localStorage` simulation (the integration test sets it via the `__csrf` cookie pattern; the front controller's real version hands the JS a `match:current` key from the dispatch flow).
+- **`upload-result.php`** — A small fragment used by the upload form's iframe-style response (so the parent form can read the returned URL). Renders a `<script type="text/javascript">` block that calls `window.parent.postMessage({url: "..."}, "*")` and a fallback link.
+
+### Front Controller (modifies `public/index.php`)
+
+The Task 1 stub is replaced with a real front controller. The front controller is the only place that touches `$_GET`, `$_POST`, `$_FILES`, `$_COOKIE`, `$_SERVER` directly. It:
+
+1. Reads `$_GET`, `$_POST`, `$_FILES`, `$_COOKIE`, `$_SERVER`.
+2. Derives the request method, path, query string, and content type.
+3. Reads the app secret from `BATTLEFORGE_SECRET` (env var) or, if absent, from `var/secret.key` (a 32-byte random file created on first run and git-ignored).
+4. Issues a CSRF token on first visit (when the `__csrf` cookie is absent) by setting the cookie to `CsrfToken::issue($secret)[1]` — the cookie holds the HMAC, the form/header holds the original token value. On every response, the controller ensures the cookie is set with `HttpOnly`, `SameSite=Lax`, `Secure` (production), `Path=/`, `Expires=time()+86400`.
+5. Computes the `__uploads_token` cookie as `hash_hmac('sha256', $secret, 'bf-uploads')` (or reads it from the request) and threads it to `GetAssets` via a request attribute `__uploads_token` (read inside the handler via `$request->server['__uploads_token']`).
+6. Configures the `Router` with the eight routes:
+    - `GET /` → `GetHomePage`
+    - `GET /scenarios/{id}/edit/team` → `GetTeamEditor`
+    - `POST /scenarios/{id}/edit/team` → `PostTeamEditor`
+    - `GET /scenarios/{id}/edit/battlefield` → `GetBattlefieldEditor`
+    - `POST /scenarios/{id}/edit/battlefield` → `PostBattlefieldEditor`
+    - `POST /scenarios/{id}/start` → `PostStartMatch`
+    - `POST /assets/upload` → `PostImageUpload`
+    - `GET /assets/{kind}/{filename}` → `GetAssets` (the router pattern handles `{kind}` and `{filename}`)
+7. Builds a `Request` value object with the request data, the CSRF secret (in `__csrf_secret`), the upload token (in `__uploads_token`), and the request method, path, and content type.
+8. Dispatches and emits the response (status, headers, body).
+
+### CSRF Model
+
+A single `__csrf` cookie per session. The cookie holds `hash_hmac('sha256', $token, $secret)` (the `issue()` method's second return value). The form/header holds the original token (`$token`, the first return value). On every state-changing request:
+
+- Forms: hidden `_csrf` field with `$token` is matched against `CsrfToken::verify($token, $secret, $request->cookies['__csrf'] ?? '')`.
+- Fetch: `X-CSRF-Token` header with `$token` is matched the same way.
+
+The upload-endpoint user token is derived from the same secret:
+
+```php
+$userToken = hash_hmac('sha256', $secret, 'bf-uploads');
+```
+
+`GetAssets` validates `$request->cookies['__uploads_token'] === $params['userToken']`. The front controller sets the `__uploads_token` cookie on first visit.
+
+**Hardening note for the front controller**: the `userToken` path-param in `GetAssets` should be validated against a strict format (e.g. `/^[a-f0-9]{32,}$/`) to prevent directory traversal. The router's `[^/]+` pattern restricts `$filename` already, but `$userToken` is the path-segment before the file, so a defensive regex there is appropriate.
+
+### System Boundaries (delta on the Plan 3 spec)
+
+Plan 3b introduces no new boundaries. The four module boundaries from the Plan 3 spec still hold:
+
+1. **Content library** (Domain, unchanged).
+2. **Scenario editor** (web, expanding): now includes the team editor, battlefield editor, and image upload forms.
+3. **Rules engine** (Domain, unchanged).
+4. **Battle interface** (Plan 4, stubbed in Plan 3b's `match-stub.php`).
+
+The `Application` and `Http` layers from Plan 3a continue to mediate between the web pages and the `Domain`. The front controller in `public/index.php` is the only place that touches the superglobals.
+
+## Data and Action Flow
+
+### Cold-start flow (no change from Plan 3 spec)
+
+### Team editor save flow
+
+1. User edits the form, presses Save.
+2. Browser POSTs the form to `POST /scenarios/{id}/edit/team` with `Content-Type: application/x-www-form-urlencoded` and a hidden `_csrf` field.
+3. Server's `PostTeamEditor`:
+   a. Verifies the CSRF token.
+   b. Reads form fields into a `ScenarioDraft`.
+   c. Calls `ScenarioDraft::toScenario()` and `ScenarioValidator::validate($scenario)`.
+   d. On failure: re-renders the editor with errors and original form values.
+   e. On success: renders a "Saved" template that includes a `<script type="module">` block that calls `localStorage.setItem('scenario:' + id, JSON.stringify(scenarioJson))`.
+
+### Battlefield editor save flow
+
+1. User clicks tiles; the small JS helper maintains a `tileMap` object.
+2. User presses Save; the JS helper POSTs JSON to `POST /scenarios/{id}/edit/battlefield` with `Content-Type: application/json` and `X-CSRF-Token` header.
+3. Server's `PostBattlefieldEditor`:
+   a. Verifies the CSRF token from the header.
+   b. Decodes the JSON body.
+   c. Runs `ScenarioValidator::validate()`.
+   d. On failure: returns `Response::json(400, ['ok' => false, 'errors' => [...]])`.
+   e. On success: returns `Response::json(200, ['ok' => true, 'scenario' => $array])`.
+
+(Note: Plan 3b ships the form-based team editor; the JS-driven fetch is added in Plan 3c. The handler accepts both for compatibility.)
+
+### Image upload flow
+
+1. User picks an image, presses Upload.
+2. Browser submits the file to `POST /assets/upload` as `multipart/form-data` with a hidden `_csrf` field.
+3. Server's `PostImageUpload`:
+   a. Verifies the CSRF token.
+   b. Reads `$_FILES['image']`.
+   c. Constructs `ImageUploadService($userToken, $uploadsRoot)`, calls `store($tempPath, $declaredMime)`.
+   d. Returns `Response::json(200, ['url' => $url])` on success or `Response::json(400, ['error' => $message])` on failure.
+
+### Start-match flow
+
+1. User clicks "Start match" on either editor.
+2. JS reads the assembled `Scenario` from `localStorage`, POSTs JSON to `POST /scenarios/{id}/start` with `X-CSRF-Token` header.
+3. Server's `PostStartMatch`:
+   a. Verifies the CSRF token.
+   b. Decodes a `Scenario` via `ScenarioSerializer::scenarioFromArray`.
+   c. Runs `ScenarioValidator::validate()` (defense in depth).
+   d. Calls `Scenario::startMatch('alpha')`.
+   e. Returns `Response::json(200, ['match' => $array])` on success or `Response::json(400, ['errors' => [...]])` on failure.
+
+## Validation and Failure Handling
+
+- `ScenarioValidator` is the single source of truth for scenario validity. Both the server (on every form POST) and the browser (when Plan 3c lands) call it.
+- A rejected action never partially mutates the persisted state. `localStorage` writes happen only on a successful server response.
+- Failure to save a scenario leaves the user's in-progress form intact; the editor re-renders the same values with errors inline.
+- The CSRF token's invalid-or-missing case returns a generic 403 page (form POSTs) or 403 JSON (fetch POSTs) that links back to `GET /`. The user's in-progress form state is preserved in `localStorage` (Plan 3c's responsibility).
+- A failed image upload returns 400 JSON with the error message. The unit row keeps whatever `image` field it had.
+- Corrupt or incompatible JSON in `localStorage` is rejected on read: the JS helper skips the row and surfaces an error to the user.
+
+## Security and Quality Requirements
+
+Inherited from the Plan 3 spec:
+
+- Every state-changing form or request uses and verifies a CSRF token before mutation. Forms use a hidden `_csrf` field; fetch uses an `X-CSRF-Token` header.
+- All rendered output is escaped via `Escape::html`, `Escape::attr`, and `Escape::url`. Code review enforces the pattern.
+- All uploaded images are content-validated and by dimensions; the stored file's name is a server-generated random hex; the original filename and declared MIME are discarded after validation.
+- `var/uploads/` is denied by `.htaccess` (Apache) and `index.php` (built-in server).
+- The dev server is the built-in `php -S`.
+- PHP follows the repository PHPCS rules and passes PHPStan at level 6.
+- Composer configuration passes `composer validate --strict`.
+- All output includes `X-Content-Type-Options: nosniff`, `Referrer-Policy: same-origin`, and the `Content-Security-Policy` header.
+
+Plan 3b-specific:
+
+- The front controller's `userToken` validation in `GetAssets` uses a strict format regex (`/^[a-f0-9]{32,}$/`) to harden the path-traversal surface.
+- The `BATTLEFORGE_SECRET` env var takes precedence over the per-install file. The per-install file is `var/secret.key`, a 32-byte binary file created on first run with `random_bytes(32)` and `chmod 0600`. The file is git-ignored.
+- The CSRF secret in the `__csrf` cookie is bound to the browser via the cookie's `HttpOnly` + `SameSite=Lax` attributes, and the secret is HMAC-signed server-side. A cross-site request cannot forge the HMAC.
+
+## Verification Strategy
+
+### Unit tests (in `tests/Integration/` per the established Plan 3a pattern)
+
+The handlers are integration-tested, not unit-tested, because their behavior crosses the HTTP / Application / Domain boundary. Each handler has at least:
+
+- One happy-path test: synthetic `Request` with a valid CSRF token and a valid form/JSON body, asserts on the response status, headers, and body.
+- One validation-error test: synthetic `Request` with valid CSRF but out-of-bounds data, asserts the response carries the validator's error messages.
+
+Tests cover (per the Plan 3 spec):
+
+- `GetTeamEditor` — 200 with security headers and a form.
+- `PostTeamEditor` — happy path returns 200 with `localStorage.setItem` snippet; out-of-bounds stat returns 200 with the validator's error message inline.
+- `GetBattlefieldEditor` — 200 with security headers and an empty grid.
+- `PostBattlefieldEditor` — happy path returns `{ok: true, scenario: ...}`; invalid shape returns `{ok: false, errors: [...]}`.
+- `PostImageUpload` — 200 with `{url: ...}`; missing file returns 400; invalid file returns 400.
+- `PostStartMatch` — 200 with `{match: ...}` containing `activeTeamId: 'alpha'` and `round: 1`.
+- Forged CSRF (no `_csrf` field) returns 403 for form POSTs and 403 JSON for fetch POSTs.
+- Wrong-user upload (token mismatch) returns 404.
+
+### Full-flow integration test (`FullFlowTest`)
+
+A single integration test that walks the full create-and-save flow:
+
+1. Bootstraps the front controller in-process (no `php -S` boot) by including `public/index.php` with synthetic superglobals.
+2. Issues a CSRF token.
+3. GET home page.
+4. POST team editor with a valid form body, asserts the response says "Saved" and contains the `localStorage.setItem` snippet.
+5. POST battlefield editor with a valid JSON body, asserts `{ok: true, ...}`.
+6. POST start-match with the assembled scenario, asserts the response contains the initial match state.
+
+This test exercises the actual `public/index.php` front controller end-to-end and is the closest the MVP gets to a true E2E test (a real browser-driven E2E is in Plan 4).
+
+### CI verification (Task 16)
+
+The existing `.github/workflows/ci.yml` already runs `composer check` (PHPCS + PHPStan + PHPUnit). Plan 3b adds no new dependencies. No workflow change is required; just verify the existing workflow is present.
+
+### Static analysis / lint
+
+- PHPCS scope: `src/Http/Handlers/`, `src/Views/` (excluded by `phpstan.neon` but still checked by PHPCS), `public/index.php`. Already covered by the Task 1 `phpcs.xml`.
+- PHPStan level 6 stays. `src/Views/*` is excluded (templates are not statically analyzed). `public/index.php` is included.
+- The pre-existing line-length warnings from Plan 1+2 are not addressed in Plan 3b. They remain as a known follow-up. Plan 3b's new files should not introduce new warnings.
+
+### Manual usability check
+
+A new tester with no BattleForge context can: open the dev URL, see the home page, click "New scenario", fill in two teams with mixed archetypes, upload a custom image, save the team editor, paint a small grid, save the battlefield editor, click "Start match", and reach the "match loaded" stub — without leaving the browser or seeing any error from the validator that wasn't explained inline.
+
+## Release Boundary
+
+Plan 3b is releasable when every in-scope capability and success criterion is met, the verification suite is green (PHPUnit, PHPStan, PHPCS), and no out-of-scope capability (the JS-driven UX, the battle interface, bundled scenarios) is required to exercise the local creation flow. The local dev server runs the full app on a single port with `php -S`.
+
+The next plan (Plan 3c) will add the JavaScript surface (`storage.js`, `grid-editor.js`, placeholder images) and the `archetypes.json` asset. Plan 4 will replace the `match-stub.php` placeholder with the real battle interface, add the three bundled scenarios, and ship the E2E smoke test that this plan seeds.

docs/superpowers/specs/2026-07-07-frontend-js-design.md

@@ -0,0 +1,184 @@
+# Plan 3c: JavaScript Frontend Design
+
+## Purpose
+
+Plan 3c of the four-plan BattleForge build. Closes the gap between the Plan 3a+3b PHP backend and the in-browser experience by adding the small JavaScript surface that Plan 3a's web layer was waiting for. Plan 3c is the third of four plans and the last one in the original "Plan 3" deliverable.
+
+Plan 3a's web layer (the front controller, the editor handlers, the views) shipped without any JavaScript beyond a `<script type="module" src="...">` placeholder. Plan 3c delivers the JS that pre-fills the team editor from `localStorage`, runs the battlefield grid interactions, and wires the home page's "Recent scenarios" list. The web app is currently functional from the browser with HTML-only form submits; Plan 3c adds the JS-driven UX that the spec calls for.
+
+## Success Criteria
+
+Plan 3c succeeds when a new user, without developer assistance, can:
+
+1. Visit `http://localhost:8000/` and see the home page with a "Recent scenarios" list populated from `localStorage`.
+2. Click "New scenario", fill the team editor, save — the page reloads, the recent list shows the new scenario, and clicking the new scenario in the recent list opens the team editor pre-filled with the saved data.
+3. Navigate to the battlefield editor, paint a small grid, place deployment zones, place an objective, save — the saved state is in `localStorage` under the same `scenario:{id}` key, and the home page's recent list shows the updated scenario.
+4. Refresh the page or come back tomorrow and find their scenarios still in their browser.
+5. Open the browser dev tools and see no console errors, no `eval`, no unhandled promise rejections, no mixed-content warnings.
+
+## Out of Scope (deferred to Plan 4)
+
+- The hot-seat battle interface (Plan 4 ships a real battle page that reads `match:current` from `localStorage` and renders the turn-based UI).
+- Three bundled scenarios (Plan 4 ships them as JSON fixtures in `public/scenarios/`).
+- An end-to-end smoke test against a real browser. The spec calls for it under Plan 4, not Plan 3c.
+- Drag-and-drop on the grid (the spec says it's optional; the click-paint approach in Plan 3c is sufficient for the MVP).
+- Service worker / offline support (the spec explicitly excludes this).
+- Animation of combat, terrain, or transitions (Plan 4).
+- The "Start match" button on the team editor navigates to the home page after a successful match start; Plan 4 adds the route that shows the match in progress.
+
+## In Scope
+
+### Two JavaScript files
+
+**`public/js/storage.js`** — the localStorage helper. Exposes `window.bfStorage` with eight methods:
+
+```js
+window.bfStorage = {
+  // Read a scenario by id. Returns the parsed object or null if missing/corrupt.
+  load(id) -> object | null,
+
+  // Write a scenario to localStorage under `scenario:{id}`.
+  // The argument is the canonical Plan-3a scenario shape (the same shape
+  // ScenarioSerializer::scenarioToArray produces).
+  save(id, scenario) -> void,
+
+  // Remove a scenario from localStorage.
+  delete(id) -> void,
+
+  // List all stored scenarios, sorted by last-modified descending.
+  // Returns [{id, name, lastModified}].
+  listAll() -> [{id, name, lastModified}],
+
+  // Read/write the in-progress match.
+  currentMatch() -> object | null,
+  setCurrentMatch(match) -> void,
+  removeCurrentMatch() -> void,
+};
+```
+
+The module handles corrupt JSON gracefully: `load(id)` returns `null` if `JSON.parse` throws, and `listAll()` skips keys that fail to parse (showing a "corrupt scenario" placeholder in the home page).
+
+**`public/js/grid-editor.js`** — the battlefield editor grid helper. Runs on `DOMContentLoaded`. Reads `data-scenario-id` from the form element, calls `bfStorage.load(id)`, and populates the grid. Manages three modes selected by the existing `name="zoneMode"` radio buttons (alpha, bravo, objective, plus the default terrain-paint mode which is implicit when none of the zone radios are selected). On tile click, applies the current mode to that tile. Shift-click removes the paint or zone membership. The form's submit is intercepted; the JS builds the canonical scenario JSON, fetches `POST /scenarios/{id}/edit/battlefield` with `Content-Type: application/json` and `X-CSRF-Token: <token>` (read from the layout's `<meta name="csrf-token">`), parses the response, and writes the returned `scenario` to `localStorage`. On 400 with `{ok: false, errors: [...]}`, displays the errors inline in the form.
+
+### One JSON asset
+
+**`public/assets/archetypes.json`** — the four `ArchetypeTemplate` definitions, served at `/assets/archetypes.json`. Format:
+
+```json
+{
+  "defender": { "minHealth": 10, "maxHealth": 14, "minAttack": 2, "maxAttack": 4, "minDefense": 3, "maxDefense": 5, "minSpeed": 1, "maxSpeed": 3, "allowedAbilities": ["buff"] },
+  "striker":  { "minHealth": 6,  "maxHealth": 10, "minAttack": 4, "maxAttack": 6, "minDefense": 1, "maxDefense": 2, "minSpeed": 2, "maxSpeed": 4, "allowedAbilities": ["area_damage"] },
+  "support":  { "minHealth": 5,  "maxHealth": 9,  "minAttack": 1, "maxAttack": 3, "minDefense": 1, "maxDefense": 3, "minSpeed": 2, "maxSpeed": 4, "allowedAbilities": ["heal", "buff"] },
+  "scout":    { "minHealth": 4,  "maxHealth": 7,  "minAttack": 2, "maxAttack": 4, "minDefense": 0, "maxDefense": 2, "minSpeed": 4, "maxSpeed": 6, "allowedAbilities": [] }
+}
+```
+
+The `ArchetypeCatalog::templates()` from Plan 3a is the canonical source for these values. Plan 3c's JSON must stay in sync with Plan 3a's PHP enum values. A future task could generate this JSON from the PHP source, but Plan 3c ships a hand-maintained copy.
+
+### Four placeholder images
+
+**`public/assets/placeholders/{defender,striker,support,scout}.png`** — 64×64 (or 32×32) transparent PNGs with a simple silhouette representing each archetype. Served at `/assets/placeholders/{archetype}.png` (no `userToken` prefix). The team editor's `<img>` tags for unit art default to these URLs when no uploaded image is set. The exact pixel art is up to the implementer; the test just checks the file exists and is a valid PNG.
+
+### Updated view templates
+
+Three templates get new `<script type="module">` tags:
+
+- **`src/Views/home.php`** — adds `<script type="module" src="/js/storage.js"></script>`. The `<div id="recent">` is populated by `storage.js` on `DOMContentLoaded`.
+- **`src/Views/team-editor.php`** — adds `<script type="module" src="/js/storage.js"></script>`. The form fields are pre-filled by `storage.js` on `DOMContentLoaded`. Adds a "Start match" button at the bottom of the form that calls `bfStorage.load(id)`, fetches `POST /scenarios/{id}/start`, calls `bfStorage.setCurrentMatch(match)`, and navigates to `GET /`.
+- **`src/Views/battlefield-editor.php`** — adds `<script type="module" src="/js/grid-editor.js"></script>`. The grid is populated by `grid-editor.js` on `DOMContentLoaded`.
+
+### Node toolchain
+
+- **`package.json`** — declares `eslint ^8.57.0`, `eslint-config-airbnb-base ^15.0.0`, `eslint-plugin-import ^2.29.0`, `prettier ^3.3.0`. Scripts: `lint` (`eslint public/js`), `format` (`prettier --check public/js`).
+- **`.eslintrc.json`** — extends `airbnb-base`, env `browser + es2022`, sourceType `module`.
+- **`.prettierrc`** — `{ "singleQuote": true, "trailingComma": "all", "printWidth": 100 }` (matches the existing PHPCS PSR-12 style).
+
+### CI update
+
+- **`.github/workflows/ci.yml`** — adds `npm ci`, `npm run lint`, `npm run format` steps after the existing `composer check` step.
+- **`.gitignore`** — adds `var/secret.key` (Plan 3b's `FullFlowTest` creates it on first run; it shouldn't be committed) and `node_modules/`.
+
+## System Boundaries
+
+Plan 3c introduces no new boundaries. The Plan 3a+3b web layer's four boundaries still hold:
+
+1. **Content library** (Domain, unchanged): `ArchetypeCatalog` is the canonical source; `archetypes.json` is a hand-maintained mirror used by the JS.
+2. **Scenario editor** (web, now JS-driven): Plan 3c adds the JS layer that pre-fills forms and runs grid interactions. The form submit still goes to the same PHP handlers.
+3. **Rules engine** (Domain, unchanged).
+4. **Battle interface** (Plan 4).
+
+The JS layer reads and writes the canonical scenario shape (Plan 3a's `ScenarioSerializer::scenarioToArray`). It does not introduce a separate "draft" shape or a UI-only data model. The home page's "Recent scenarios" list parses the same shape for display.
+
+## Data and Action Flow
+
+### Cold-start flow
+
+1. Browser hits `GET /`. `GetHomePage` returns 200 with the home page (which now includes `<script type="module" src="/js/storage.js"></script>`).
+2. `storage.js` runs. `bfStorage.listAll()` enumerates `localStorage` keys matching `scenario:*`, parses each value, returns an array sorted by `lastModified` descending. The home page's `<div id="recent">` is populated with one `<a>` per item, pointing to `/scenarios/{id}/edit/team`.
+3. User clicks "New scenario" → `GET /scenarios/new/edit/team`.
+
+### Team editor flow
+
+1. Browser hits `GET /scenarios/{id}/edit/team`. `GetTeamEditor` returns 200 with the team editor template (which now includes `<script type="module" src="/js/storage.js"></script>`).
+2. `storage.js` reads `window.location.pathname`, extracts `{id}` (or `'new'` for the new-scenario case), calls `bfStorage.load(id)`. If a scenario exists, the JS pre-fills each form field by name (e.g. `teamA[units][0][archetype]` → `document.querySelector('[name="teamA[units][0][archetype]"]').value = scenario.units[0].archetype`). If the id is `'new'`, the form stays empty.
+3. The archetype dropdowns are populated from `/assets/archetypes.json` (fetched once on script load).
+4. User edits, then presses Save. The form's submit triggers a normal `POST /scenarios/{id}/edit/team` (no JS intercept).
+5. The server returns 200 with a `<script type="module">` block that calls `localStorage.setItem('scenario:' + id, JSON.stringify(scenarioJson))`. The browser runs the script and writes.
+6. On a validation error, the server returns 200 with the form re-rendered and the validator's error in `<div class="bf-errors">`. No JS write happens; the form keeps the user's in-progress values.
+
+### Battlefield editor flow
+
+1. Browser hits `GET /scenarios/{id}/edit/battlefield`. `GetBattlefieldEditor` returns 200 with the battlefield editor template (which now includes `<script type="module" src="/js/grid-editor.js"></script>`).
+2. `grid-editor.js` reads `bfStorage.load(id)`, populates the `tileMap` from `scenario.battlefieldTerrain`, populates the deployment zones (extracted from `scenario.deploymentZones`), and populates the objective position (if `HoldObjective`).
+3. The grid is repainted: each tile button's `data-paint` attribute is updated, the objective tile gets `data-objective="1"`, and the zone tiles get `data-zone="alpha"` or `data-zone="bravo"`.
+4. User clicks a palette button to select terrain paint mode, then clicks tiles. Each click updates the in-memory `tileMap` and updates the button's `data-paint`. User clicks one of the `name="zoneMode"` radios (alpha / bravo / objective) and clicks tiles to add to that zone or place the objective. Shift-click in any mode removes the paint or zone membership.
+5. User presses Save. The JS intercepts the form submit (`event.preventDefault()`), builds the canonical scenario JSON, POSTs to `/scenarios/{id}/edit/battlefield` with `Content-Type: application/json` and `X-CSRF-Token: <token>` (read from the layout's `<meta name="csrf-token">`), parses the response, and writes the returned `scenario` to `localStorage`.
+6. On 400 with `{ok: false, errors: [...]}`, the JS shows the errors inline in the form (e.g. "Deployment zone alpha includes impassable terrain at (3,4)").
+
+### Start-match flow
+
+1. From the team editor, user clicks "Start match" (a new button at the bottom of the form). The JS reads `bfStorage.load(id)`, fetches `POST /scenarios/{id}/start` with `X-CSRF-Token`, parses the response, calls `bfStorage.setCurrentMatch(match)`, and navigates to `GET /`.
+2. The home page (when reloaded) shows a "Match in progress" banner at the top, driven by `bfStorage.currentMatch()`. Plan 4 adds a real battle page that this banner links to.
+
+## Validation and Failure Handling
+
+- `bfStorage.load(id)` returns `null` if the value is missing or fails to JSON-parse. The home page's `listAll()` skips keys that fail to parse, and the team editor's pre-fill gracefully no-ops on `null`.
+- The team editor's form submit falls back to the server's re-render path (Plan 3a's `PostTeamEditor` re-renders the form on validation failure with the user's in-progress values and the validator's error message). The JS does not intercept the submit.
+- The battlefield editor's fetch fallback path: on 400, the JS shows the validator's errors inline and keeps the user's in-progress state in the `tileMap` and zone maps. On network failure (e.g. fetch throws), the JS shows a "Network error" message and the form stays editable.
+- The "Start match" button's failure path: on 400 (invalid scenario), the JS shows the validator's errors inline. On network failure, shows a "Network error" message and keeps the form editable.
+
+## Security and Quality Requirements
+
+Inherited from the Plan 3 spec:
+
+- All rendered output is escaped for its output context. The PHP templates use `Escape::html` / `Escape::attr` / `Escape::url`. The JS uses `textContent` and `value` setters, never `innerHTML` (with one exception: building the home page's recent-scenarios list uses `appendChild` on `<a>` elements with `textContent`, never `innerHTML`).
+- The single small JS file passes ESLint `airbnb/base` and Prettier checks. CI fails if either fails.
+- `composer validate --strict` and the existing `composer check` continue to pass.
+
+Plan 3c-specific:
+
+- No third-party JS libraries. The two files are pure ESM, no dependencies, no `eval`, no `Function` constructor.
+- The `archetypes.json` is served from the same origin. The home page's "Recent scenarios" list is read from `localStorage`, never from the network.
+- `var/secret.key` is added to `.gitignore` so the Plan 3b full-flow test's generated secret file is not committed.
+
+## Verification Strategy
+
+### Lint and format (CI gate)
+
+- `npm run lint` — ESLint `airbnb-base` over `public/js/*.js`. Fails on any rule violation, including unused variables, missing semicolons, and unhandled promise rejections.
+- `npm run format` — Prettier `--check public/js`. Fails on any formatting drift.
+
+### Smoke test (optional, recommended)
+
+- One Playwright test that boots the dev server with `php -S`, loads the home page, asserts the empty "Recent scenarios" list, calls `bfStorage.save('demo', {id: 'demo', name: 'Demo'})` via `page.evaluate`, reloads, and asserts the list shows "Demo". This is the Plan 3c analog of `FullFlowTest` for Plan 3b.
+- If Playwright is too heavy for Plan 3c, the spec's CI requirement (ESLint + Prettier) is sufficient, and the Playwright test lands in Plan 4 with the battle interface.
+
+### Manual usability check
+
+A new tester with no BattleForge context can: open the dev URL, see the home page, click "New scenario", fill the team editor, save, see the recent list show the new scenario, click it, see the team editor pre-filled, paint a small grid, save, see the battlefield state persist, and refresh to find their work still there — without leaving the browser or seeing any error from the validator that wasn't explained inline.
+
+## Release Boundary
+
+Plan 3c is releasable when every in-scope capability and success criterion is met, the verification suite is green (`composer check`, `npm run lint`, `npm run format`), and no out-of-scope capability (the battle interface, bundled scenarios, the end-to-end Playwright smoke test) is required to exercise the local creation flow. The local dev server runs the full app on a single port with `php -S`, and the JS layer loads from `/js/`.
+
+The next plan (Plan 4) will replace the home page's "Match in progress" banner with the real battle interface, add the three bundled scenarios, and ship the end-to-end smoke test that this plan's spec leaves as a follow-up.

package.json

@@ -0,0 +1,16 @@
+{
+    "name": "battleforge-battleforge",
+    "description": "BattleForge frontend toolchain.",
+    "private": true,
+    "license": "proprietary",
+    "scripts": {
+        "lint": "eslint public/js",
+        "format": "prettier --check public/js"
+    },
+    "devDependencies": {
+        "eslint": "^8.57.0",
+        "eslint-config-airbnb-base": "^15.0.0",
+        "eslint-plugin-import": "^2.29.0",
+        "prettier": "^3.3.0"
+    }
+}

phpcs.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0"?>
+<ruleset name="BattleForge">
+    <description>BattleForge coding standards.</description>
+
+    <file>src</file>
+    <file>tests</file>
+    <file>public/index.php</file>
+
+    <arg name="colors"/>
+    <arg value="sp"/>
+
+    <rule ref="PSR12"/>
+</ruleset>

phpstan.neon

@@ -0,0 +1,9 @@
+parameters:
+    level: 6
+    paths:
+        - src
+        - tests
+        - public/index.php
+    excludePaths:
+        - src/Views/*
+    tmpDir: var/phpstan

phpunit.xml

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/11.5/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         cacheDirectory="var/phpunit"
+         colors="true">
+    <testsuites>
+        <testsuite name="unit">
+            <directory>tests/Unit</directory>
+        </testsuite>
+        <testsuite name="integration">
+            <directory>tests/Integration</directory>
+        </testsuite>
+    </testsuites>
+
+    <source>
+        <include>
+            <directory>src</directory>
+        </include>
+    </source>
+</phpunit>

public/assets/archetypes.json

@@ -0,0 +1,6 @@
+{
+    "defender": { "minHealth": 10, "maxHealth": 14, "minAttack": 2, "maxAttack": 4, "minDefense": 3, "maxDefense": 5, "minSpeed": 1, "maxSpeed": 3, "allowedAbilities": ["buff"] },
+    "striker":  { "minHealth": 6,  "maxHealth": 10, "minAttack": 4, "maxAttack": 6, "minDefense": 1, "maxDefense": 2, "minSpeed": 2, "maxSpeed": 4, "allowedAbilities": ["area_damage"] },
+    "support":  { "minHealth": 5,  "maxHealth": 9,  "minAttack": 1, "maxAttack": 3, "minDefense": 1, "maxDefense": 3, "minSpeed": 2, "maxSpeed": 4, "allowedAbilities": ["heal", "buff"] },
+    "scout":    { "minHealth": 4,  "maxHealth": 7,  "minAttack": 2, "maxAttack": 4, "minDefense": 0, "maxDefense": 2, "minSpeed": 4, "maxSpeed": 6, "allowedAbilities": [] }
+}

public/assets/styles.css

@@ -0,0 +1,21 @@
+* { box-sizing: border-box; }
+html, body { margin: 0; padding: 0; font-family: sans-serif; }
+body { padding: 1rem; max-width: 64rem; margin: 0 auto; }
+fieldset { margin: 0 0 1rem 0; padding: 0.5rem 1rem; }
+legend { font-weight: bold; }
+label { display: block; margin: 0.25rem 0; }
+input, select, button, textarea { font: inherit; }
+input[type="number"] { width: 5rem; }
+table.bf-grid { border-collapse: collapse; }
+table.bf-grid td { padding: 0; }
+table.bf-grid button { width: 2rem; height: 2rem; border: 1px solid #ccc; background: #fff; }
+table.bf-grid button[data-paint="open"] { background: #fff; }
+table.bf-grid button[data-paint="forest"] { background: #cfc; }
+table.bf-grid button[data-paint="rough"] { background: #fec; }
+table.bf-grid button[data-paint="water"] { background: #cce; }
+table.bf-grid button[data-paint="blocking"] { background: #444; color: #fff; }
+table.bf-grid button[data-objective="1"] { outline: 3px solid #c00; }
+table.bf-grid button[data-zone="alpha"] { outline: 3px solid #00c; }
+table.bf-grid button[data-zone="bravo"] { outline: 3px solid #0c0; }
+.bf-errors { color: #c00; }
+.bf-toast { background: #dfd; padding: 0.5rem 1rem; margin: 0.5rem 0; }

public/index.php

@@ -0,0 +1,137 @@
+<?php
+
+declare(strict_types=1);
+
+use BattleForge\Http\CsrfToken;
+use BattleForge\Http\Handlers\GetAssets;
+use BattleForge\Http\Handlers\GetBattlefieldEditor;
+use BattleForge\Http\Handlers\GetHomePage;
+use BattleForge\Http\Handlers\GetTeamEditor;
+use BattleForge\Http\Handlers\PostBattlefieldEditor;
+use BattleForge\Http\Handlers\PostImageUpload;
+use BattleForge\Http\Handlers\PostStartMatch;
+use BattleForge\Http\Handlers\PostTeamEditor;
+use BattleForge\Http\Request;
+use BattleForge\Http\Response;
+use BattleForge\Http\Router;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+// 1. Read the app secret.
+$secret = getenv('BATTLEFORGE_SECRET');
+if ($secret === false || $secret === '') {
+    $secretFile = __DIR__ . '/../var/secret.key';
+    if (!is_file($secretFile)) {
+        if (!is_dir(dirname($secretFile))) {
+            mkdir(dirname($secretFile), 0700, true);
+        }
+        file_put_contents($secretFile, random_bytes(32));
+        chmod($secretFile, 0600);
+    }
+    $secret = file_get_contents($secretFile);
+    if ($secret === false) {
+        http_response_code(500);
+        echo "Failed to read app secret.\n";
+        return;
+    }
+}
+
+// 2. Ensure the __csrf cookie is set. If absent, issue a fresh token.
+$cookies = $_COOKIE;
+$existingCookie = (string) ($cookies['__csrf'] ?? '');
+if ($existingCookie === '') {
+    [$token, $cookie] = CsrfToken::issue($secret);
+    setcookie('__csrf', $cookie, [
+        'expires' => time() + 86400,
+        'path' => '/',
+        'secure' => isset($_SERVER['HTTPS']),
+        'httponly' => true,
+        'samesite' => 'Lax',
+    ]);
+    $existingCookie = $cookie;
+    $cookies['__csrf'] = $cookie;
+}
+
+// 3. Compute the upload-endpoint user token (derived from the same secret).
+$uploadsToken = hash_hmac('sha256', $secret, 'bf-uploads');
+
+// 4. Determine the request method, path, and content type.
+$method = strtoupper((string) ($_SERVER['REQUEST_METHOD'] ?? 'GET'));
+$uri = (string) ($_SERVER['REQUEST_URI'] ?? '/');
+$path = parse_url($uri, PHP_URL_PATH) ?: '/';
+$queryString = (string) (parse_url($uri, PHP_URL_QUERY) ?? '');
+$contentType = isset($_SERVER['CONTENT_TYPE']) ? (string) $_SERVER['CONTENT_TYPE'] : null;
+if ($contentType !== null) {
+    $semicolon = strpos($contentType, ';');
+    if ($semicolon !== false) {
+        $contentType = substr($contentType, 0, $semicolon);
+    }
+    $contentType = trim($contentType);
+}
+
+// 5. Read the raw body for fetch POSTs that submit JSON.
+$rawBody = (string) ($_SERVER['__raw_body'] ?? file_get_contents('php://input'));
+
+// 6. Build a Request with the request data, the CSRF secret, and the upload token.
+$server = $_SERVER;
+if (!isset($server['__csrf_secret'])) {
+    $server['__csrf_secret'] = $secret;
+}
+$server['__uploads_token'] = $uploadsToken;
+
+$request = new Request(
+    get: $_GET,
+    post: $_POST,
+    files: $_FILES,
+    cookies: $cookies,
+    server: $server,
+    queryString: $queryString,
+    method: $method,
+    path: $path,
+    contentType: $contentType,
+    rawBody: $rawBody,
+);
+
+// 7. Configure the router with the eight routes.
+$uploadsRoot = __DIR__ . '/../var/uploads';
+$placeholderDir = __DIR__ . '/assets/placeholders';
+
+$homePage = static fn (Request $r, array $p): Response => (new GetHomePage())->handle($r, $p);
+$getTeam = static fn (Request $r, array $p): Response => (new GetTeamEditor())->handle($r, $p);
+$postTeam = static fn (Request $r, array $p): Response => (new PostTeamEditor())->handle($r, $p);
+$getBattlefield = static fn (Request $r, array $p): Response => (new GetBattlefieldEditor())->handle($r, $p);
+$postBattlefield = static fn (Request $r, array $p): Response => (new PostBattlefieldEditor())->handle($r, $p);
+$postStart = static fn (Request $r, array $p): Response => (new PostStartMatch())->handle($r, $p);
+$postUpload = static fn (Request $r, array $p): Response => (new PostImageUpload($uploadsRoot))->handle($r, $p);
+$getAssets = static function (Request $r, array $p) use ($placeholderDir, $uploadsRoot): Response {
+    return (new GetAssets($placeholderDir, $uploadsRoot))->handle($r, $p);
+};
+$getUploadedAsset = static function (Request $r, array $p) use ($placeholderDir, $uploadsRoot): Response {
+    $handler = new GetAssets($placeholderDir, $uploadsRoot);
+    return $handler->handle(
+        $r,
+        ['kind' => 'uploads', 'userToken' => $p['userToken'] ?? '', 'filename' => $p['filename'] ?? ''],
+    );
+};
+
+$router = new Router();
+$router->add('GET', '/', $homePage);
+$router->add('GET', '/scenarios/{id}/edit/team', $getTeam);
+$router->add('POST', '/scenarios/{id}/edit/team', $postTeam);
+$router->add('GET', '/scenarios/{id}/edit/battlefield', $getBattlefield);
+$router->add('POST', '/scenarios/{id}/edit/battlefield', $postBattlefield);
+$router->add('POST', '/scenarios/{id}/start', $postStart);
+$router->add('POST', '/assets/upload', $postUpload);
+$router->add('GET', '/assets/uploads/{userToken}/{filename}', $getUploadedAsset);
+$router->add('GET', '/assets/{kind}/{filename}', $getAssets);
+
+// 8. Dispatch and emit.
+$response = $router->dispatch($request);
+
+http_response_code($response->status);
+foreach ($response->headers as $name => $value) {
+    header($name . ': ' . $value);
+}
+echo $response->body;
+
+return $response->status;

public/js/grid-editor.js

@@ -0,0 +1,266 @@
+function getCsrfToken() {
+  const meta = document.querySelector('meta[name="csrf-token"]');
+  return meta ? meta.getAttribute('content') : '';
+}
+
+function getCurrentMode() {
+  const checked = document.querySelector('input[name="zoneMode"]:checked');
+  return checked ? checked.value : 'terrain';
+}
+
+function getSelectedPaint() {
+  const active = document.querySelector('.bf-paint.active');
+  if (active) {
+    return active.getAttribute('data-paint');
+  }
+  return 'forest';
+}
+
+function loadScenario(id) {
+  if (window.bfStorage && typeof window.bfStorage.load === 'function') {
+    return window.bfStorage.load(id);
+  }
+  return null;
+}
+
+function saveScenario(id, scenario) {
+  if (window.bfStorage && typeof window.bfStorage.save === 'function') {
+    window.bfStorage.save(id, scenario);
+  }
+}
+
+function applyTile(button, paint, zone, isObjective) {
+  button.setAttribute('data-paint', paint);
+  if (zone) {
+    button.setAttribute('data-zone', zone);
+  } else {
+    button.removeAttribute('data-zone');
+  }
+  if (isObjective) {
+    button.setAttribute('data-objective', '1');
+  } else {
+    button.removeAttribute('data-objective');
+  }
+}
+
+function loadGrid(tileMap, deploymentZones, objective) {
+  document.querySelectorAll('.bf-tile').forEach((button) => {
+    const x = button.getAttribute('data-x');
+    const y = button.getAttribute('data-y');
+    const key = `${x}:${y}`;
+    if (tileMap[key]) {
+      button.setAttribute('data-paint', tileMap[key]);
+    }
+    button.removeAttribute('data-zone');
+    button.removeAttribute('data-objective');
+  });
+  Object.entries(deploymentZones).forEach(([team, positions]) => {
+    positions.forEach((pos) => {
+      const selector = `.bf-tile[data-x="${pos.x}"][data-y="${pos.y}"]`;
+      const button = document.querySelector(selector);
+      if (button) {
+        button.setAttribute('data-zone', team);
+      }
+    });
+  });
+  if (objective) {
+    const selector = `.bf-tile[data-x="${objective.x}"][data-y="${objective.y}"]`;
+    const button = document.querySelector(selector);
+    if (button) {
+      button.setAttribute('data-objective', '1');
+    }
+  }
+}
+
+function readGrid() {
+  const tileMap = {};
+  const deploymentZones = { alpha: [], bravo: [] };
+  let objective = null;
+  document.querySelectorAll('.bf-tile').forEach((button) => {
+    const x = Number(button.getAttribute('data-x'));
+    const y = Number(button.getAttribute('data-y'));
+    const paint = button.getAttribute('data-paint');
+    if (paint && paint !== 'open') {
+      tileMap[`${x}:${y}`] = paint;
+    }
+    const zone = button.getAttribute('data-zone');
+    if (zone === 'alpha' || zone === 'bravo') {
+      deploymentZones[zone].push({ x, y });
+    }
+    if (button.getAttribute('data-objective') === '1') {
+      objective = { x, y };
+    }
+  });
+  return { tileMap, deploymentZones, objective };
+}
+
+function buildScenarioJson(scenarioId, tileMap, deploymentZones, objective) {
+  const widthInput = document.querySelector('input[name="battlefieldWidth"]');
+  const heightInput = document.querySelector('input[name="battlefieldHeight"]');
+  const result = {
+    id: scenarioId,
+    name: scenarioId,
+    battlefieldWidth: widthInput ? Number(widthInput.value) : 8,
+    battlefieldHeight: heightInput ? Number(heightInput.value) : 8,
+    battlefieldTerrain: tileMap,
+    teamA: {
+      units: [],
+    },
+    teamB: {
+      units: [],
+    },
+    deploymentZones,
+    objectives: {},
+    victoryCondition: 'eliminate_all',
+    holdRoundsRequired: 1,
+  };
+  if (objective) {
+    result.victoryCondition = 'hold_objective';
+    result.holdRoundsRequired = 3;
+    result.objectiveId = 'objective-1';
+    result.objectiveX = objective.x;
+    result.objectiveY = objective.y;
+  }
+  return result;
+}
+
+function paintTile(button, ev) {
+  const mode = getCurrentMode();
+  if (ev.shiftKey) {
+    applyTile(button, 'open', null, false);
+    return;
+  }
+  if (mode === 'objective') {
+    document.querySelectorAll('.bf-tile[data-objective]').forEach((other) => {
+      other.removeAttribute('data-objective');
+    });
+    applyTile(button, 'open', null, true);
+    return;
+  }
+  if (mode === 'alpha' || mode === 'bravo') {
+    const current = button.getAttribute('data-zone');
+    if (current === mode) {
+      button.removeAttribute('data-zone');
+    } else {
+      button.setAttribute('data-zone', mode);
+    }
+    return;
+  }
+  applyTile(button, getSelectedPaint(), null, false);
+}
+
+function selectPalette(event) {
+  document.querySelectorAll('.bf-paint').forEach((b) => b.classList.remove('active'));
+  event.currentTarget.classList.add('active');
+}
+
+function showToast(message) {
+  const toast = document.createElement('div');
+  toast.className = 'bf-toast';
+  toast.appendChild(document.createTextNode(message));
+  document.body.appendChild(toast);
+  setTimeout(() => toast.remove(), 3000);
+}
+
+function showErrors(errors) {
+  const existing = document.querySelector('.bf-errors');
+  if (existing) {
+    existing.remove();
+  }
+  const div = document.createElement('div');
+  div.className = 'bf-errors';
+  const ul = document.createElement('ul');
+  errors.forEach((msg) => {
+    const li = document.createElement('li');
+    li.appendChild(document.createTextNode(msg));
+    ul.appendChild(li);
+  });
+  div.appendChild(ul);
+  const form = document.getElementById('battlefield-form');
+  if (form) {
+    form.parentNode.insertBefore(div, form);
+  }
+}
+
+async function save(event) {
+  event.preventDefault();
+  const form = document.getElementById('battlefield-form');
+  if (!form) {
+    return;
+  }
+  const id = form.getAttribute('data-scenario-id');
+  if (!id) {
+    return;
+  }
+  const { tileMap, deploymentZones, objective } = readGrid();
+  const scenario = buildScenarioJson(id, tileMap, deploymentZones, objective);
+  const csrf = getCsrfToken();
+  let res;
+  try {
+    res = await fetch(`/scenarios/${encodeURIComponent(id)}/edit/battlefield`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-CSRF-Token': csrf,
+      },
+      body: JSON.stringify(scenario),
+    });
+  } catch (e) {
+    showErrors([`Network error: ${e.message}`]);
+    return;
+  }
+  if (res.ok) {
+    const data = await res.json();
+    if (data.scenario) {
+      saveScenario(id, data.scenario);
+      showToast('Saved.');
+    } else {
+      showErrors([(data.errors || ['Unknown error']).join(', ')]);
+    }
+  } else if (res.status === 400) {
+    let data = {};
+    try {
+      data = await res.json();
+    } catch (e) {
+      // body wasn't JSON
+    }
+    showErrors(data.errors || ['Validation failed (HTTP 400).']);
+  } else {
+    showErrors([`Save failed: HTTP ${res.status}`]);
+  }
+}
+
+document.addEventListener('DOMContentLoaded', () => {
+  const form = document.getElementById('battlefield-form');
+  if (!form) {
+    return;
+  }
+  const id = form.getAttribute('data-scenario-id');
+  if (id) {
+    const scenario = loadScenario(id);
+    if (scenario) {
+      const battlefield = scenario.battlefield || {};
+      const terrain = battlefield.terrain || {};
+      const rawZones = scenario.deploymentZones || {};
+      const deploymentZones = { alpha: [], bravo: [] };
+      ['alpha', 'bravo'].forEach((team) => {
+        if (rawZones[team] && Array.isArray(rawZones[team].positions)) {
+          deploymentZones[team] = rawZones[team].positions;
+        }
+      });
+      const objectiveMarker = scenario.objectives ? scenario.objectives['objective-1'] : null;
+      const objective = objectiveMarker ? objectiveMarker.position : null;
+      loadGrid(terrain, deploymentZones, objective);
+    }
+  }
+  document.querySelectorAll('.bf-tile').forEach((button) => {
+    button.addEventListener('click', (ev) => paintTile(button, ev));
+  });
+  document.querySelectorAll('.bf-paint').forEach((button) => {
+    button.addEventListener('click', selectPalette);
+  });
+  if (document.querySelector('.bf-paint')) {
+    document.querySelector('.bf-paint').classList.add('active');
+  }
+  form.addEventListener('submit', save);
+});

public/js/storage.js

@@ -0,0 +1,219 @@
+const STORAGE_PREFIX = 'scenario:';
+const MATCH_KEY = 'match:current';
+
+function load(id) {
+  try {
+    const raw = localStorage.getItem(STORAGE_PREFIX + id);
+    if (raw === null) {
+      return null;
+    }
+    return JSON.parse(raw);
+  } catch (e) {
+    return null;
+  }
+}
+
+function save(id, scenario) {
+  const stamped = { ...scenario, lastModified: Date.now() };
+  localStorage.setItem(STORAGE_PREFIX + id, JSON.stringify(stamped));
+}
+
+function remove(id) {
+  localStorage.removeItem(STORAGE_PREFIX + id);
+}
+
+function listAll() {
+  const items = [];
+  for (let i = 0; i < localStorage.length; i += 1) {
+    const key = localStorage.key(i);
+    if (key !== null && key.startsWith(STORAGE_PREFIX)) {
+      const id = key.slice(STORAGE_PREFIX.length);
+      const scenario = load(id);
+      if (scenario !== null) {
+        items.push({
+          id,
+          name: typeof scenario.name === 'string' ? scenario.name : id,
+          lastModified: typeof scenario.lastModified === 'number' ? scenario.lastModified : 0,
+        });
+      }
+    }
+  }
+  items.sort((a, b) => b.lastModified - a.lastModified);
+  return items;
+}
+
+function currentMatch() {
+  try {
+    const raw = localStorage.getItem(MATCH_KEY);
+    if (raw === null) {
+      return null;
+    }
+    return JSON.parse(raw);
+  } catch (e) {
+    return null;
+  }
+}
+
+function setCurrentMatch(match) {
+  localStorage.setItem(MATCH_KEY, JSON.stringify(match));
+}
+
+function removeCurrentMatch() {
+  localStorage.removeItem(MATCH_KEY);
+}
+
+function getCsrfToken() {
+  const meta = document.querySelector('meta[name="csrf-token"]');
+  return meta ? meta.getAttribute('content') : '';
+}
+
+function parsePath(name) {
+  const match = name.match(/^(teamA|teamB)\[units\]\[(\d+)\]\[(\w+)\]$/);
+  if (match) {
+    const [, team, indexStr, key] = match;
+    const teamKey = team === 'teamA' ? 'teamA' : 'teamB';
+    return [teamKey, 'units', Number(indexStr), key];
+  }
+  const simple = [
+    'id',
+    'name',
+    'battlefieldWidth',
+    'battlefieldHeight',
+    'victoryCondition',
+    'holdRoundsRequired',
+  ];
+  if (simple.includes(name)) {
+    return [name];
+  }
+  return null;
+}
+
+function resolveField(scenario, path) {
+  const parts = parsePath(path);
+  if (parts === null) {
+    return undefined;
+  }
+  let cursor = scenario;
+  for (let i = 0; i < parts.length; i += 1) {
+    if (cursor === null || cursor === undefined) {
+      return undefined;
+    }
+    cursor = cursor[parts[i]];
+  }
+  return cursor;
+}
+
+function populateRecentScenarios() {
+  const root = document.getElementById('recent');
+  if (!root) {
+    return;
+  }
+  while (root.firstChild) {
+    root.removeChild(root.firstChild);
+  }
+  const items = listAll();
+  if (items.length === 0) {
+    const p = document.createElement('p');
+    p.className = 'bf-empty';
+    p.appendChild(document.createTextNode('No saved scenarios yet.'));
+    root.appendChild(p);
+    return;
+  }
+  const ul = document.createElement('ul');
+  items.forEach((item) => {
+    const li = document.createElement('li');
+    const a = document.createElement('a');
+    a.setAttribute('href', `/scenarios/${encodeURIComponent(item.id)}/edit/team`);
+    a.appendChild(document.createTextNode(`${item.name} (${item.id})`));
+    li.appendChild(a);
+    ul.appendChild(li);
+  });
+  root.appendChild(ul);
+}
+
+// eslint-disable-next-line no-unused-vars
+async function fetchArchetypes() {
+  const res = await fetch('/assets/archetypes.json');
+  return res.json();
+}
+
+function prefillTeamEditor() {
+  const form = document.querySelector('form[action*="/edit/team"]');
+  if (!form) {
+    return;
+  }
+  const id = decodeURIComponent(window.location.pathname.split('/').slice(-3, -2)[0] || 'new');
+  if (id === 'new') {
+    return;
+  }
+  const scenario = load(id);
+  if (scenario === null) {
+    return;
+  }
+  const fields = form.querySelectorAll('input[name], select[name]');
+  fields.forEach((field) => {
+    const name = field.getAttribute('name');
+    if (!name) {
+      return;
+    }
+    const value = resolveField(scenario, name);
+    if (value !== undefined) {
+      Object.assign(field, { value: String(value) });
+    }
+  });
+}
+
+async function startMatch() {
+  const id = decodeURIComponent(window.location.pathname.split('/').slice(-3, -2)[0] || 'new');
+  if (id === 'new') {
+    return;
+  }
+  const scenario = load(id);
+  if (scenario === null) {
+    return;
+  }
+  const csrf = getCsrfToken();
+  const res = await fetch(`/scenarios/${encodeURIComponent(id)}/start`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-CSRF-Token': csrf,
+    },
+    body: JSON.stringify(scenario),
+  });
+  if (!res.ok) {
+    // eslint-disable-next-line no-alert
+    alert(`Start match failed: HTTP ${res.status}`);
+    return;
+  }
+  const data = await res.json();
+  if (data.match) {
+    setCurrentMatch(data.match);
+    window.location.href = '/';
+  } else {
+    // eslint-disable-next-line no-alert
+    alert(`Start match failed: ${data.errors ? data.errors.join(', ') : 'unknown'}`);
+  }
+}
+
+window.bfStorage = {
+  load,
+  save,
+  delete: remove,
+  listAll,
+  currentMatch,
+  setCurrentMatch,
+  removeCurrentMatch,
+};
+
+document.addEventListener('DOMContentLoaded', () => {
+  populateRecentScenarios();
+  prefillTeamEditor();
+  const startBtn = document.getElementById('bf-start-match');
+  if (startBtn) {
+    startBtn.addEventListener('click', (event) => {
+      event.preventDefault();
+      startMatch();
+    });
+  }
+});

src/Application/ImageUploadService.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Application;
+
+final class ImageUploadService
+{
+    public function __construct(
+        private readonly string $userToken,
+        private readonly string $uploadsRoot,
+    ) {
+    }
+
+    public function store(string $tempPath, string $declaredMime): string
+    {
+        $validated = ImageValidator::validate($tempPath, $declaredMime);
+
+        $namespace = $this->uploadsRoot . '/' . $this->userToken;
+        if (!is_dir($namespace)) {
+            mkdir($namespace, 0700, true);
+        }
+
+        $hash = bin2hex(random_bytes(16));
+        $filename = $hash . '.' . $validated->extension;
+        $destination = $namespace . '/' . $filename;
+
+        if (!rename($tempPath, $destination)) {
+            throw new InvalidImageException("Could not move upload to {$destination}.");
+        }
+
+        // Lock the file down: the namespace is already 0700; tighten the
+        // file itself to 0600 in case the server's umask is permissive.
+        chmod($destination, 0600);
+
+        return '/assets/uploads/' . $this->userToken . '/' . $filename;
+    }
+}

src/Application/ImageValidator.php

@@ -0,0 +1,81 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Application;
+
+final class ImageValidator
+{
+    /**
+     * @return array{string, string} [canonicalMime, extension] for a recognized image, or null.
+     */
+    private static function detect(string $header): ?array
+    {
+        if (substr($header, 0, 8) === "\x89PNG\r\n\x1a\n") {
+            return ['image/png', 'png'];
+        }
+
+        if (substr($header, 0, 3) === "\xff\xd8\xff") {
+            return ['image/jpeg', 'jpg'];
+        }
+
+        if (substr($header, 0, 6) === 'GIF87a' || substr($header, 0, 6) === 'GIF89a') {
+            return ['image/gif', 'gif'];
+        }
+
+        if (substr($header, 0, 4) === 'RIFF' && substr($header, 8, 4) === 'WEBP') {
+            return ['image/webp', 'webp'];
+        }
+
+        return null;
+    }
+
+    public static function validate(
+        string $tempPath,
+        string $declaredMime,
+        int $maxBytes = 2_000_000,
+        int $maxDimension = 512,
+    ): ValidatedImage {
+        if (!is_file($tempPath)) {
+            throw new InvalidImageException('Upload is not a file.');
+        }
+
+        $size = filesize($tempPath);
+        if ($size === false || $size > $maxBytes) {
+            throw new InvalidImageException("File exceeds the {$maxBytes} byte limit.");
+        }
+
+        $handle = fopen($tempPath, 'rb');
+        if ($handle === false) {
+            throw new InvalidImageException('Could not read upload.');
+        }
+        $header = fread($handle, 12);
+        fclose($handle);
+        if ($header === false || strlen($header) < 12) {
+            throw new InvalidImageException('Upload is too small to be an image.');
+        }
+
+        $detected = self::detect($header);
+        if ($detected === null) {
+            throw new InvalidImageException('File is not a supported image type.');
+        }
+
+        [$canonical, $extension] = $detected;
+
+        if ($declaredMime !== $canonical) {
+            throw new InvalidImageException('Declared MIME does not match file contents.');
+        }
+
+        $info = getimagesize($tempPath);
+        if ($info === false) {
+            throw new InvalidImageException('Image is corrupt or unreadable.');
+        }
+
+        [$width, $height] = $info;
+        if ($width > $maxDimension || $height > $maxDimension) {
+            throw new InvalidImageException("Image dimensions exceed the {$maxDimension} pixel limit.");
+        }
+
+        return new ValidatedImage($canonical, $extension);
+    }
+}

src/Application/InvalidImageException.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Application;
+
+use RuntimeException;
+
+final class InvalidImageException extends RuntimeException
+{
+}

src/Application/ScenarioDraft.php

@@ -0,0 +1,215 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Application;
+
+use BattleForge\Domain\Archetype;
+use BattleForge\Domain\Battlefield;
+use BattleForge\Domain\DeploymentZone;
+use BattleForge\Domain\ObjectiveMarker;
+use BattleForge\Domain\Position;
+use BattleForge\Domain\Scenario;
+use BattleForge\Domain\Terrain;
+use BattleForge\Domain\UnitState;
+use BattleForge\Domain\VictoryCondition;
+use InvalidArgumentException;
+
+final readonly class ScenarioDraft
+{
+    /**
+     * @param list<UnitState> $units
+     * @param array<string, DeploymentZone> $deploymentZones
+     * @param array<string, ObjectiveMarker> $objectives
+     */
+    public function __construct(
+        public string $id,
+        public string $name,
+        public Battlefield $battlefield,
+        public array $units,
+        public array $deploymentZones,
+        public array $objectives,
+        public VictoryCondition $victoryCondition,
+        public int $holdRoundsRequired,
+    ) {
+    }
+
+    public function toScenario(): Scenario
+    {
+        return new Scenario(
+            id: $this->id,
+            name: $this->name,
+            battlefield: $this->battlefield,
+            units: $this->units,
+            deploymentZones: $this->deploymentZones,
+            objectives: $this->objectives,
+            victoryCondition: $this->victoryCondition,
+            holdRoundsRequired: $this->holdRoundsRequired,
+        );
+    }
+
+    /** @param array<string, mixed> $post */
+    public static function fromPost(array $post): self
+    {
+        $id = self::stringField($post, 'id');
+        $name = self::stringField($post, 'name');
+        $width = self::intField($post, 'battlefieldWidth');
+        $height = self::intField($post, 'battlefieldHeight');
+
+        $terrain = [];
+        foreach (($post['battlefieldTerrain'] ?? []) as $key => $value) {
+            $terrain[(string) $key] = self::terrainField((string) $value);
+        }
+        $battlefield = new Battlefield($width, $height, $terrain);
+
+        $alphaUnits = self::parseTeamUnits($post['teamA']['units'] ?? [], 'alpha');
+        $bravoUnits = self::parseTeamUnits($post['teamB']['units'] ?? [], 'bravo');
+        $units = [...$alphaUnits, ...$bravoUnits];
+
+        // The form does not yet expose a "deployment zone" picker (3b adds it).
+        // For 3a we synthesize one zone per team containing the unit positions.
+        // When 3b lands, the editor's POST will include explicit zone tiles.
+        $deploymentZones = [
+            'alpha' => new DeploymentZone('alpha', self::collectPositions($alphaUnits)),
+            'bravo' => new DeploymentZone('bravo', self::collectPositions($bravoUnits)),
+        ];
+
+        $victory = self::victoryField(self::stringField($post, 'victoryCondition'));
+        $holdRounds = self::intField($post, 'holdRoundsRequired');
+
+        $objectives = [];
+        if ($victory === VictoryCondition::HoldObjective) {
+            $objId = self::stringField($post, 'objectiveId');
+            $objX = self::intField($post, 'objectiveX');
+            $objY = self::intField($post, 'objectiveY');
+            $objectives[$objId] = new ObjectiveMarker($objId, new Position($objX, $objY));
+        }
+
+        return new self(
+            id: $id,
+            name: $name,
+            battlefield: $battlefield,
+            units: $units,
+            deploymentZones: $deploymentZones,
+            objectives: $objectives,
+            victoryCondition: $victory,
+            holdRoundsRequired: $holdRounds,
+        );
+    }
+
+    /**
+     * @param list<array<string, mixed>> $rows
+     * @return list<UnitState>
+     */
+    private static function parseTeamUnits(array $rows, string $teamId): array
+    {
+        $units = [];
+        foreach ($rows as $index => $row) {
+            if (!is_array($row)) { // @phpstan-ignore function.alreadyNarrowedType (Runtime guard: PHPDoc is not a runtime contract for JSON-sourced arrays in Plan 3.)
+                throw new InvalidArgumentException("Team {$teamId} unit row {$index} is malformed.");
+            }
+
+            $unitId = self::stringField($row, 'id');
+            $archetype = self::archetypeField(self::stringField($row, 'archetype'));
+            $maxHealth = self::intField($row, 'maxHealth');
+            $attack = self::intField($row, 'attack');
+            $defense = self::intField($row, 'defense');
+            $speed = self::intField($row, 'speed');
+            $abilities = [];
+            foreach (($row['abilities'] ?? []) as $ability) {
+                $abilities[] = (string) $ability;
+            }
+            $position = new Position(
+                self::intField($row, 'x'),
+                self::intField($row, 'y'),
+            );
+
+            $units[] = new UnitState(
+                id: $unitId,
+                teamId: $teamId,
+                position: $position,
+                maxHealth: $maxHealth,
+                health: $maxHealth,
+                attack: $attack,
+                defense: $defense,
+                speed: $speed,
+                actionsRemaining: 2,
+                hasAttacked: false,
+                archetype: $archetype,
+                abilities: $abilities,
+                attackBonus: 0,
+                hasUsedAbility: false,
+            );
+        }
+
+        return $units;
+    }
+
+    /**
+     * @param list<UnitState> $units
+     * @return list<Position>
+     */
+    private static function collectPositions(array $units): array
+    {
+        $positions = [];
+        foreach ($units as $unit) {
+            $positions[] = $unit->position;
+        }
+
+        return $positions;
+    }
+
+    private static function archetypeField(string $value): Archetype
+    {
+        $archetype = Archetype::tryFrom($value);
+        if ($archetype === null) {
+            throw new InvalidArgumentException("Unknown archetype: {$value}.");
+        }
+
+        return $archetype;
+    }
+
+    private static function terrainField(string $value): Terrain
+    {
+        $terrain = Terrain::tryFrom($value);
+        if ($terrain === null) {
+            throw new InvalidArgumentException("Unknown terrain: {$value}.");
+        }
+
+        return $terrain;
+    }
+
+    private static function victoryField(string $value): VictoryCondition
+    {
+        $victory = VictoryCondition::tryFrom($value);
+        if ($victory === null) {
+            throw new InvalidArgumentException("Unknown victory condition: {$value}.");
+        }
+
+        return $victory;
+    }
+
+    /**
+     * @param array<string, mixed> $array
+     */
+    private static function stringField(array $array, string $key): string
+    {
+        if (!isset($array[$key]) || !is_string($array[$key]) || $array[$key] === '') {
+            throw new InvalidArgumentException("Field '{$key}' is required.");
+        }
+
+        return $array[$key];
+    }
+
+    /**
+     * @param array<string, mixed> $array
+     */
+    private static function intField(array $array, string $key): int
+    {
+        if (!isset($array[$key])) {
+            throw new InvalidArgumentException("Field '{$key}' is required.");
+        }
+
+        return (int) $array[$key];
+    }
+}

src/Application/ScenarioSerializer.php

@@ -0,0 +1,270 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Application;
+
+use BattleForge\Domain\Archetype;
+use BattleForge\Domain\ArchetypeCatalog;
+use BattleForge\Domain\Battlefield;
+use BattleForge\Domain\DeploymentZone;
+use BattleForge\Domain\MatchState;
+use BattleForge\Domain\ObjectiveMarker;
+use BattleForge\Domain\Position;
+use BattleForge\Domain\Scenario;
+use BattleForge\Domain\Terrain;
+use BattleForge\Domain\UnitState;
+use BattleForge\Domain\VictoryCondition;
+use InvalidArgumentException;
+
+final class ScenarioSerializer
+{
+    /** @return array<string, mixed> */
+    public static function scenarioToArray(Scenario $scenario): array
+    {
+        $terrainMap = [];
+
+        for ($y = 0; $y < $scenario->battlefield->height; $y++) {
+            for ($x = 0; $x < $scenario->battlefield->width; $x++) {
+                $position = new Position($x, $y);
+                $tile = $scenario->battlefield->terrainAt($position);
+                if ($tile === Terrain::Open) {
+                    continue;
+                }
+                $terrainMap[$position->key()] = $tile->value;
+            }
+        }
+
+        $units = [];
+        foreach ($scenario->units as $unit) {
+            $units[] = self::unitToArray($unit);
+        }
+
+        $deploymentZones = [];
+        foreach ($scenario->deploymentZones as $teamId => $zone) {
+            $deploymentZones[$teamId] = self::deploymentZoneToArray($zone);
+        }
+
+        $objectives = [];
+        foreach ($scenario->objectives as $id => $objective) {
+            $objectives[$id] = ['id' => $objective->id, 'position' => self::positionToArray($objective->position)];
+        }
+
+        return [
+            'id' => $scenario->id,
+            'name' => $scenario->name,
+            'battlefield' => [
+                'width' => $scenario->battlefield->width,
+                'height' => $scenario->battlefield->height,
+                'terrain' => $terrainMap,
+            ],
+            'units' => $units,
+            'deploymentZones' => $deploymentZones,
+            'objectives' => $objectives,
+            'victoryCondition' => $scenario->victoryCondition->value,
+            'holdRoundsRequired' => $scenario->holdRoundsRequired,
+        ];
+    }
+
+    /** @param array<string, mixed> $data */
+    public static function scenarioFromArray(array $data): Scenario
+    {
+        $terrainMap = [];
+        foreach (($data['battlefield']['terrain'] ?? []) as $key => $value) {
+            $terrainMap[(string) $key] = Terrain::from((string) $value);
+        }
+
+        $battlefield = new Battlefield(
+            (int) $data['battlefield']['width'],
+            (int) $data['battlefield']['height'],
+            $terrainMap,
+        );
+
+        $units = [];
+        foreach (($data['units'] ?? []) as $row) {
+            $units[] = self::unitFromArray($row);
+        }
+
+        $deploymentZones = [];
+        foreach (($data['deploymentZones'] ?? []) as $teamId => $row) {
+            $deploymentZones[(string) $teamId] = self::deploymentZoneFromArray($row);
+        }
+
+        $objectives = [];
+        foreach (($data['objectives'] ?? []) as $id => $row) {
+            $objectives[(string) $id] = new ObjectiveMarker(
+                (string) $row['id'],
+                self::positionFromArray($row['position']),
+            );
+        }
+
+        return new Scenario(
+            id: (string) $data['id'],
+            name: (string) $data['name'],
+            battlefield: $battlefield,
+            units: $units,
+            deploymentZones: $deploymentZones,
+            objectives: $objectives,
+            victoryCondition: VictoryCondition::from((string) $data['victoryCondition']),
+            holdRoundsRequired: (int) $data['holdRoundsRequired'],
+        );
+    }
+
+    /** @return array<string, mixed> */
+    public static function matchToArray(MatchState $match): array
+    {
+        $terrainMap = [];
+        for ($y = 0; $y < $match->battlefield->height; $y++) {
+            for ($x = 0; $x < $match->battlefield->width; $x++) {
+                $position = new Position($x, $y);
+                $tile = $match->battlefield->terrainAt($position);
+                if ($tile === Terrain::Open) {
+                    continue;
+                }
+                $terrainMap[$position->key()] = $tile->value;
+            }
+        }
+
+        $units = [];
+        foreach ($match->units as $unit) {
+            $units[] = self::unitToArray($unit);
+        }
+
+        return [
+            'battlefield' => [
+                'width' => $match->battlefield->width,
+                'height' => $match->battlefield->height,
+                'terrain' => $terrainMap,
+            ],
+            'units' => $units,
+            'activeTeamId' => $match->activeTeamId,
+            'round' => $match->round,
+            'winnerTeamId' => $match->winnerTeamId,
+            'actionLog' => $match->actionLog,
+            'victoryCondition' => $match->victoryCondition->value,
+            'holdRoundsRequired' => $match->holdRoundsRequired,
+            'objectiveControl' => $match->objectiveControl,
+        ];
+    }
+
+    /** @param array<string, mixed> $data */
+    public static function matchFromArray(array $data): MatchState
+    {
+        $terrainMap = [];
+        foreach (($data['battlefield']['terrain'] ?? []) as $key => $value) {
+            $terrainMap[(string) $key] = Terrain::from((string) $value);
+        }
+
+        $battlefield = new Battlefield(
+            (int) $data['battlefield']['width'],
+            (int) $data['battlefield']['height'],
+            $terrainMap,
+        );
+
+        $units = [];
+        foreach (($data['units'] ?? []) as $row) {
+            $units[] = self::unitFromArray($row);
+        }
+
+        return new MatchState(
+            battlefield: $battlefield,
+            units: $units,
+            activeTeamId: (string) $data['activeTeamId'],
+            round: (int) $data['round'],
+            winnerTeamId: $data['winnerTeamId'] ?? null,
+            actionLog: array_map(static fn (mixed $entry): string => (string) $entry, $data['actionLog'] ?? []),
+            objectives: [],
+            victoryCondition: VictoryCondition::from((string) $data['victoryCondition']),
+            holdRoundsRequired: (int) $data['holdRoundsRequired'],
+            objectiveControl: $data['objectiveControl'] ?? [],
+        );
+    }
+
+    /** @return array<string, mixed> */
+    private static function unitToArray(UnitState $unit): array
+    {
+        return [
+            'id' => $unit->id,
+            'teamId' => $unit->teamId,
+            'position' => self::positionToArray($unit->position),
+            'maxHealth' => $unit->maxHealth,
+            'health' => $unit->health,
+            'attack' => $unit->attack,
+            'defense' => $unit->defense,
+            'speed' => $unit->speed,
+            'archetype' => $unit->archetype->value,
+            'abilities' => $unit->abilities,
+        ];
+    }
+
+    /** @param array<string, mixed> $row */
+    private static function unitFromArray(array $row): UnitState
+    {
+        $archetype = Archetype::from((string) $row['archetype']);
+        // Validate the ability allowlist against the catalog before constructing,
+        // because the runtime guard in UnitState only catches non-string entries.
+        $template = ArchetypeCatalog::templates()[$archetype->value] ?? null;
+        if ($template !== null) {
+            $abilities = array_map(static fn (mixed $a): string => (string) $a, $row['abilities'] ?? []);
+            foreach ($abilities as $ability) {
+                if (!in_array($ability, $template->allowedAbilities, true)) {
+                    throw new InvalidArgumentException("Ability {$ability} is not in archetype {$archetype->value}'s allowlist.");
+                }
+            }
+        }
+
+        return new UnitState(
+            id: (string) $row['id'],
+            teamId: (string) $row['teamId'],
+            position: self::positionFromArray($row['position']),
+            maxHealth: (int) $row['maxHealth'],
+            health: (int) $row['health'],
+            attack: (int) $row['attack'],
+            defense: (int) $row['defense'],
+            speed: (int) $row['speed'],
+            actionsRemaining: 2,
+            hasAttacked: false,
+            archetype: $archetype,
+            abilities: $abilities ?? [],
+            attackBonus: 0,
+            hasUsedAbility: false,
+        );
+    }
+
+    /** @return array<string, mixed> */
+    private static function positionToArray(Position $position): array
+    {
+        return ['x' => $position->x, 'y' => $position->y];
+    }
+
+    private static function positionFromArray(mixed $row): Position
+    {
+        if (!is_array($row)) {
+            throw new InvalidArgumentException('Expected position to be an array.');
+        }
+
+        return new Position((int) $row['x'], (int) $row['y']);
+    }
+
+    /** @return array<string, mixed> */
+    private static function deploymentZoneToArray(DeploymentZone $zone): array
+    {
+        $positions = [];
+        foreach ($zone->positions as $position) {
+            $positions[] = self::positionToArray($position);
+        }
+
+        return ['teamId' => $zone->teamId, 'positions' => $positions];
+    }
+
+    /** @param array<string, mixed> $row */
+    private static function deploymentZoneFromArray(array $row): DeploymentZone
+    {
+        $positions = [];
+        foreach (($row['positions'] ?? []) as $positionRow) {
+            $positions[] = self::positionFromArray($positionRow);
+        }
+
+        return new DeploymentZone((string) $row['teamId'], $positions);
+    }
+}

src/Application/ValidatedImage.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Application;
+
+final readonly class ValidatedImage
+{
+    public function __construct(
+        public string $canonicalMime,
+        public string $extension,
+    ) {
+    }
+}

src/Domain/AbilityCatalog.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Domain;
+
+final class AbilityCatalog
+{
+    /**
+     * @return array<string, AbilityDefinition>
+     */
+    public static function definitions(): array
+    {
+        static $cache = null;
+
+        if ($cache !== null) {
+            return $cache;
+        }
+
+        $cache = [
+            AbilityId::Heal->value => new AbilityDefinition(
+                id: AbilityId::Heal,
+                label: 'Heal',
+                range: 2,
+                areaRadius: 0,
+                target: AbilityDefinition::TARGET_ALLY,
+                effect: AbilityDefinition::EFFECT_RESTORE_HEALTH,
+                effectValue: 5,
+            ),
+            AbilityId::AreaDamage->value => new AbilityDefinition(
+                id: AbilityId::AreaDamage,
+                label: 'Area Damage',
+                range: 3,
+                areaRadius: 1,
+                target: AbilityDefinition::TARGET_TILE,
+                effect: AbilityDefinition::EFFECT_DEAL_DAMAGE,
+                effectValue: 3,
+            ),
+            AbilityId::Buff->value => new AbilityDefinition(
+                id: AbilityId::Buff,
+                label: 'Rally',
+                range: 1,
+                areaRadius: 0,
+                target: AbilityDefinition::TARGET_ALLY,
+                effect: AbilityDefinition::EFFECT_APPLY_BUFF,
+                effectValue: 2,
+            ),
+        ];
+
+        return $cache;
+    }
+}

src/Domain/AbilityDefinition.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Domain;
+
+use InvalidArgumentException;
+
+final readonly class AbilityDefinition
+{
+    public const TARGET_SELF = 'self';
+    public const TARGET_ALLY = 'ally';
+    public const TARGET_ENEMY = 'enemy';
+    public const TARGET_TILE = 'tile';
+
+    public const EFFECT_RESTORE_HEALTH = 'restore_health';
+    public const EFFECT_DEAL_DAMAGE = 'deal_damage';
+    public const EFFECT_APPLY_BUFF = 'apply_buff';
+
+    /** @var list<string> */
+    private const TARGETS = [self::TARGET_SELF, self::TARGET_ALLY, self::TARGET_ENEMY, self::TARGET_TILE];
+
+    /** @var list<string> */
+    private const EFFECTS = [self::EFFECT_RESTORE_HEALTH, self::EFFECT_DEAL_DAMAGE, self::EFFECT_APPLY_BUFF];
+
+    public function __construct(
+        public AbilityId $id,
+        public string $label,
+        public int $range,
+        public int $areaRadius,
+        public string $target,
+        public string $effect,
+        public int $effectValue,
+    ) {
+        if ($this->range < 0) {
+            throw new InvalidArgumentException('Ability range cannot be negative.');
+        }
+
+        if ($this->areaRadius < 0) {
+            throw new InvalidArgumentException('Ability area radius cannot be negative.');
+        }
+
+        if (!in_array($this->target, self::TARGETS, true)) {
+            throw new InvalidArgumentException("Unknown ability target: {$this->target}.");
+        }
+
+        if (!in_array($this->effect, self::EFFECTS, true)) {
+            throw new InvalidArgumentException("Unknown ability effect: {$this->effect}.");
+        }
+    }
+}

src/Domain/AbilityId.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Domain;
+
+enum AbilityId: string
+{
+    case Heal = 'heal';
+    case AreaDamage = 'area_damage';
+    case Buff = 'buff';
+}

src/Domain/Archetype.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Domain;
+
+enum Archetype: string
+{
+    case Defender = 'defender';
+    case Striker = 'striker';
+    case Support = 'support';
+    case Scout = 'scout';
+}

src/Domain/ArchetypeCatalog.php

@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Domain;
+
+final class ArchetypeCatalog
+{
+    /**
+     * @return array<string, ArchetypeTemplate>
+     */
+    public static function templates(): array
+    {
+        static $cache = null;
+
+        if ($cache !== null) {
+            return $cache;
+        }
+
+        $cache = [
+            Archetype::Defender->value => new ArchetypeTemplate(
+                minHealth: 10,
+                maxHealth: 14,
+                minAttack: 2,
+                maxAttack: 4,
+                minDefense: 3,
+                maxDefense: 5,
+                minSpeed: 1,
+                maxSpeed: 3,
+                allowedAbilities: ['buff'],
+            ),
+            Archetype::Striker->value => new ArchetypeTemplate(
+                minHealth: 6,
+                maxHealth: 10,
+                minAttack: 4,
+                maxAttack: 6,
+                minDefense: 1,
+                maxDefense: 2,
+                minSpeed: 2,
+                maxSpeed: 4,
+                allowedAbilities: ['area_damage'],
+            ),
+            Archetype::Support->value => new ArchetypeTemplate(
+                minHealth: 5,
+                maxHealth: 9,
+                minAttack: 1,
+                maxAttack: 3,
+                minDefense: 1,
+                maxDefense: 3,
+                minSpeed: 2,
+                maxSpeed: 4,
+                allowedAbilities: ['heal', 'buff'],
+            ),
+            Archetype::Scout->value => new ArchetypeTemplate(
+                minHealth: 4,
+                maxHealth: 7,
+                minAttack: 2,
+                maxAttack: 4,
+                minDefense: 0,
+                maxDefense: 2,
+                minSpeed: 4,
+                maxSpeed: 6,
+                allowedAbilities: [],
+            ),
+        ];
+
+        return $cache;
+    }
+}

src/Domain/ArchetypeTemplate.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Domain;
+
+use InvalidArgumentException;
+
+final readonly class ArchetypeTemplate
+{
+    /** @param list<string> $allowedAbilities */
+    public function __construct(
+        public int $minHealth,
+        public int $maxHealth,
+        public int $minAttack,
+        public int $maxAttack,
+        public int $minDefense,
+        public int $maxDefense,
+        public int $minSpeed,
+        public int $maxSpeed,
+        public array $allowedAbilities,
+    ) {
+        if ($this->minHealth > $this->maxHealth) {
+            throw new InvalidArgumentException('Health range is inverted.');
+        }
+        if ($this->minAttack > $this->maxAttack) {
+            throw new InvalidArgumentException('Attack range is inverted.');
+        }
+        if ($this->minDefense > $this->maxDefense) {
+            throw new InvalidArgumentException('Defense range is inverted.');
+        }
+        if ($this->minSpeed > $this->maxSpeed || $this->minSpeed < 1) {
+            throw new InvalidArgumentException('Speed range must be at least 1 and non-inverted.');
+        }
+        if ($this->minHealth < 1) {
+            throw new InvalidArgumentException('Minimum health must be at least 1.');
+        }
+    }
+
+    /** @return array{maxHealth: int, attack: int, defense: int, speed: int} */
+    public function defaultStats(): array
+    {
+        return [
+            'maxHealth' => (int) ceil(($this->minHealth + $this->maxHealth) / 2),
+            'attack' => (int) ceil(($this->minAttack + $this->maxAttack) / 2),
+            'defense' => (int) ceil(($this->minDefense + $this->maxDefense) / 2),
+            'speed' => (int) ceil(($this->minSpeed + $this->maxSpeed) / 2),
+        ];
+    }
+}

src/Domain/Battlefield.php

@@ -0,0 +1,148 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Domain;
+
+use InvalidArgumentException;
+use SplQueue;
+
+final readonly class Battlefield
+{
+    /** @var array<string, Terrain> */
+    private array $terrain;
+
+    /**
+     * @param array<string, Terrain> $terrain
+     */
+    public function __construct(
+        public int $width,
+        public int $height,
+        array $terrain = [],
+    ) {
+        if ($width < 8 || $width > 16 || $height < 8 || $height > 16) {
+            throw new InvalidArgumentException('Battlefield dimensions must each be between 8 and 16.');
+        }
+
+        $validatedTerrain = [];
+
+        foreach ($terrain as $key => $terrainType) {
+            if (!self::isTerrain($terrainType)) {
+                throw new InvalidArgumentException("Invalid terrain value at coordinate {$key}.");
+            }
+
+            $position = self::positionFromTerrainKey($key);
+
+            if (!$this->contains($position)) {
+                throw new InvalidArgumentException("Terrain coordinate {$key} is outside the battlefield.");
+            }
+
+            $validatedTerrain[$key] = $terrainType;
+        }
+
+        $this->terrain = $validatedTerrain;
+    }
+
+    private static function isTerrain(mixed $terrain): bool
+    {
+        return $terrain instanceof Terrain;
+    }
+
+    private static function positionFromTerrainKey(mixed $key): Position
+    {
+        if (!is_string($key) || preg_match('/^(\d+):(\d+)$/', $key, $matches) !== 1) {
+            throw new InvalidArgumentException("Invalid terrain coordinate: {$key}.");
+        }
+
+        $position = new Position((int) $matches[1], (int) $matches[2]);
+
+        if ($key !== $position->key()) {
+            throw new InvalidArgumentException("Invalid terrain coordinate: {$key}.");
+        }
+
+        return $position;
+    }
+
+    public function contains(Position $position): bool
+    {
+        return $position->x >= 0
+            && $position->x < $this->width
+            && $position->y >= 0
+            && $position->y < $this->height;
+    }
+
+    public function terrainAt(Position $position): Terrain
+    {
+        return $this->terrain[$position->key()] ?? Terrain::Open;
+    }
+
+    /**
+     * @param list<Position> $occupied
+     * @return array<string, int>
+     */
+    public function reachable(Position $start, int $budget, array $occupied): array
+    {
+        if (!$this->contains($start)) {
+            throw new InvalidArgumentException('Reachability start position is outside the battlefield.');
+        }
+
+        if ($budget < 0) {
+            throw new InvalidArgumentException('Reachability budget cannot be negative.');
+        }
+
+        $occupiedKeys = [];
+
+        foreach ($occupied as $position) {
+            if (!$this->contains($position)) {
+                throw new InvalidArgumentException('Occupied position is outside the battlefield.');
+            }
+
+            $occupiedKeys[$position->key()] = true;
+        }
+
+        $costs = [$start->key() => 0];
+        /** @var SplQueue<Position> $queue */
+        $queue = new SplQueue();
+        $queue->enqueue($start);
+
+        while (!$queue->isEmpty()) {
+            $current = $queue->dequeue();
+            $currentCost = $costs[$current->key()];
+
+            foreach ($this->neighbors($current) as $neighbor) {
+                $key = $neighbor->key();
+                $movementCost = $this->terrainAt($neighbor)->movementCost();
+
+                if ($movementCost === null || isset($occupiedKeys[$key])) {
+                    continue;
+                }
+
+                $cost = $currentCost + $movementCost;
+
+                if ($cost > $budget || (isset($costs[$key]) && $costs[$key] <= $cost)) {
+                    continue;
+                }
+
+                $costs[$key] = $cost;
+                $queue->enqueue($neighbor);
+            }
+        }
+
+        return $costs;
+    }
+
+    /**
+     * @return list<Position>
+     */
+    private function neighbors(Position $position): array
+    {
+        $neighbors = [
+            new Position($position->x + 1, $position->y),
+            new Position($position->x - 1, $position->y),
+            new Position($position->x, $position->y + 1),
+            new Position($position->x, $position->y - 1),
+        ];
+
+        return array_values(array_filter($neighbors, $this->contains(...)));
+    }
+}

src/Domain/CombatEngine.php

@@ -0,0 +1,398 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Domain;
+
+use InvalidArgumentException;
+
+final class CombatEngine
+{
+    public function move(MatchState $match, string $unitId, Position $destination): MatchState
+    {
+        $this->assertMatchActive($match);
+
+        $unit = $this->unitOrFail($match, $unitId);
+        $this->assertCanAct($match, $unit);
+
+        $occupied = [];
+
+        foreach ($match->units as $otherUnit) {
+            if ($otherUnit->id !== $unit->id && !$otherUnit->isDefeated()) {
+                $occupied[] = $otherUnit->position;
+            }
+        }
+
+        $reachable = $match->battlefield->reachable($unit->position, $unit->speed, $occupied);
+
+        if ($destination->key() === $unit->position->key() || !isset($reachable[$destination->key()])) {
+            throw new CombatException('Destination is not reachable.');
+        }
+
+        $movedUnit = $unit->moveTo($destination)->spendAction();
+        $next = $match->withUnit($movedUnit);
+        $actionLog = [...$match->actionLog, "{$unit->id} moved to {$destination->key()}"];
+
+        return $next->copy(actionLog: $actionLog);
+    }
+
+    public function attack(MatchState $match, string $attackerId, string $targetId): MatchState
+    {
+        $this->assertMatchActive($match);
+
+        $attacker = $this->unitOrFail($match, $attackerId);
+        $this->assertCanAct($match, $attacker);
+
+        if ($attacker->hasAttacked) {
+            throw new CombatException('Unit has already attacked this turn.');
+        }
+
+        $target = $this->unitOrFail($match, $targetId);
+
+        if ($target->teamId === $attacker->teamId || $target->isDefeated()) {
+            throw new CombatException('Target must be an active enemy unit.');
+        }
+
+        $distance = $attacker->position->distanceTo($target->position);
+
+        if ($distance !== 1) {
+            throw new CombatException('Target is outside attack range.');
+        }
+
+        $terrainDefense = $match->battlefield->terrainAt($target->position)->defenseBonus();
+        $damage = max(1, $attacker->attack + $attacker->attackBonus - $target->defense - $terrainDefense);
+        $updatedAttacker = $attacker->markAttacked()->spendAction();
+        $updatedTarget = $target->takeDamage($damage);
+        $next = $match->withUnit($updatedAttacker)->withUnit($updatedTarget);
+        $actionLog = [...$match->actionLog, "{$attacker->id} attacked {$target->id} for {$damage} damage"];
+        $next = $next->copy(actionLog: $actionLog);
+
+        return $this->checkVictoryAfterAction($next, $attacker->teamId);
+    }
+
+    public function useAbility(MatchState $match, string $unitId, string $abilityId, ?Position $target): MatchState
+    {
+        $this->assertMatchActive($match);
+
+        $caster = $this->unitOrFail($match, $unitId);
+        $this->assertCanAct($match, $caster);
+
+        if ($caster->hasUsedAbility) {
+            throw new CombatException('Unit has already used an ability this turn.');
+        }
+
+        $definitions = AbilityCatalog::definitions();
+
+        if (!isset($definitions[$abilityId])) {
+            throw new CombatException("Unknown ability: {$abilityId}.");
+        }
+
+        $definition = $definitions[$abilityId];
+
+        if (!in_array($abilityId, $caster->allowedAbilities(), true)) {
+            throw new CombatException('Unit archetype forbids that ability.');
+        }
+
+        $affected = $this->resolveAbilityTargets($match, $caster, $definition, $target);
+
+        $next = $match;
+        $logParts = [];
+
+        foreach ($affected as $affectedUnit) {
+            $current = $next->unit($affectedUnit['id']);
+            $updated = match ($definition->effect) {
+                AbilityDefinition::EFFECT_RESTORE_HEALTH => $current->restoreHealth($definition->effectValue),
+                AbilityDefinition::EFFECT_DEAL_DAMAGE => $current->takeDamage($affectedUnit['damage'] ?? 0),
+                AbilityDefinition::EFFECT_APPLY_BUFF => $current->withAttackBonus($definition->effectValue),
+                default => throw new CombatException("Unknown ability effect: {$definition->effect}."),
+            };
+            $next = $next->withUnit($updated);
+
+            $logParts[] = match ($definition->effect) {
+                AbilityDefinition::EFFECT_RESTORE_HEALTH => "{$affectedUnit['id']} for {$definition->effectValue}",
+                AbilityDefinition::EFFECT_DEAL_DAMAGE => "{$affectedUnit['id']} for {$affectedUnit['damage']} damage",
+                AbilityDefinition::EFFECT_APPLY_BUFF => "{$affectedUnit['id']} with +{$definition->effectValue} attack",
+            };
+        }
+
+        $next = $next->withUnit($next->unit($caster->id)->spendAbility());
+
+        $summary = "{$caster->id} used {$definition->label} on " . implode(', ', $logParts);
+        $next = $next->copy(actionLog: [...$next->actionLog, $summary]);
+
+        return $this->checkVictoryAfterAction($next, $caster->teamId);
+    }
+
+    public function endTurn(MatchState $match): MatchState
+    {
+        $this->assertMatchActive($match);
+
+        $teamIds = [];
+
+        foreach ($match->units as $unit) {
+            $teamIds[$unit->teamId] = true;
+        }
+
+        $teamIds = array_keys($teamIds);
+        sort($teamIds);
+
+        if (count($teamIds) !== 2) {
+            throw new CombatException('Matches require exactly two teams.');
+        }
+
+        $livingTeams = array_fill_keys($teamIds, false);
+
+        foreach ($match->units as $unit) {
+            if (!$unit->isDefeated()) {
+                $livingTeams[$unit->teamId] = true;
+            }
+        }
+
+        foreach ($livingTeams as $teamId => $alive) {
+            if (!$alive) {
+                throw new CombatException('Cannot end turn while a team is eliminated.');
+            }
+        }
+
+        $endingTeamId = $match->activeTeamId;
+        $nextTeamId = $endingTeamId === $teamIds[0] ? $teamIds[1] : $teamIds[0];
+
+        if ($nextTeamId === $teamIds[0] && $match->round === PHP_INT_MAX) {
+            throw new CombatException('Match round limit reached.');
+        }
+
+        $units = [];
+
+        foreach ($match->units as $unit) {
+            $units[] = $unit->teamId === $nextTeamId ? $unit->startTurn() : $unit;
+        }
+
+        $round = $match->round + ($nextTeamId === $teamIds[0] ? 1 : 0);
+
+        $next = $match->copy(
+            units: $units,
+            activeTeamId: $nextTeamId,
+            round: $round,
+            actionLog: [...$match->actionLog, "{$endingTeamId} ended turn"],
+        );
+
+        return $this->resolveObjectiveVictory($next, $endingTeamId === $teamIds[0]);
+    }
+
+    /**
+     * @return list<array{id: string, damage?: int}>
+     */
+    private function resolveAbilityTargets(
+        MatchState $match,
+        UnitState $caster,
+        AbilityDefinition $definition,
+        ?Position $target,
+    ): array {
+        if ($definition->target === AbilityDefinition::TARGET_SELF) {
+            return [['id' => $caster->id]];
+        }
+
+        if ($target === null) {
+            throw new CombatException('Ability requires a target position.');
+        }
+
+        if (!$match->battlefield->contains($target)) {
+            throw new CombatException('Ability target is outside the battlefield.');
+        }
+
+        $distance = $caster->position->distanceTo($target);
+
+        if ($distance > $definition->range) {
+            throw new CombatException('Ability target is out of range.');
+        }
+
+        $tileKeys = [$target->key()];
+
+        if ($definition->areaRadius > 0) {
+            $tileKeys = self::tilesWithinRadius(
+                $match->battlefield,
+                $target,
+                $definition->areaRadius,
+            );
+        }
+
+        if ($definition->effect === AbilityDefinition::EFFECT_DEAL_DAMAGE) {
+            $affected = [];
+
+            foreach ($match->units as $candidate) {
+                if ($candidate->isDefeated()) {
+                    continue;
+                }
+                if ($candidate->teamId === $caster->teamId) {
+                    continue;
+                }
+                $found = false;
+                foreach ($tileKeys as $key) {
+                    if ($candidate->position->key() === $key) {
+                        $found = true;
+                        break;
+                    }
+                }
+                if (!$found) {
+                    continue;
+                }
+
+                $terrainDefense = $match->battlefield->terrainAt($candidate->position)->defenseBonus();
+                $damage = max(1, $definition->effectValue - $candidate->defense - $terrainDefense);
+                $affected[] = ['id' => $candidate->id, 'damage' => $damage];
+            }
+
+            return $affected;
+        }
+
+        $targetUnit = null;
+
+        foreach ($match->units as $candidate) {
+            if ($candidate->position->key() === $target->key()) {
+                $targetUnit = $candidate;
+                break;
+            }
+        }
+
+        if ($targetUnit === null) {
+            throw new CombatException('Ability target is empty.');
+        }
+
+        $expectedTeam = $definition->target === AbilityDefinition::TARGET_ALLY ? $caster->teamId : null;
+
+        if ($expectedTeam !== null && $targetUnit->teamId !== $expectedTeam) {
+            throw new CombatException('Ability target must be an ally.');
+        }
+
+        if ($definition->target === AbilityDefinition::TARGET_ENEMY && $targetUnit->teamId === $caster->teamId) {
+            throw new CombatException('Ability target must be an enemy.');
+        }
+
+        return [['id' => $targetUnit->id]];
+    }
+
+    private function checkVictoryAfterAction(MatchState $match, string $actingTeamId): MatchState
+    {
+        foreach ($match->units as $unit) {
+            if ($unit->teamId !== $actingTeamId && !$unit->isDefeated()) {
+                return $match;
+            }
+        }
+
+        return $match->withWinner($actingTeamId);
+    }
+
+    /**
+     * @param bool $endingTeamIsFirstInOrder true when the team that just ended is the first team in
+     *                                       sorted team order; this identifies the first half of a round.
+     */
+    private function resolveObjectiveVictory(MatchState $match, bool $endingTeamIsFirstInOrder): MatchState
+    {
+        if ($match->victoryCondition !== VictoryCondition::HoldObjective || $match->objectives === []) {
+            return $match;
+        }
+
+        $next = $match;
+
+        if ($endingTeamIsFirstInOrder) {
+            /** @var list<ObjectiveMarker> $objectiveList */
+            $objectiveList = array_values($match->objectives);
+            $objective = $objectiveList[0];
+            $controller = $this->objectiveController($match, $objective->position);
+
+            if ($controller !== null) {
+                $control = (new ObjectiveControl($match->objectiveControl))->recordRound($controller);
+                $next = $match->withObjectiveControl($control->roundsByTeam);
+            }
+
+            return $next;
+        }
+
+        foreach ($match->objectiveControl as $teamId => $count) {
+            if ($count >= $match->holdRoundsRequired) {
+                return $next->withWinner($teamId);
+            }
+        }
+
+        return $next;
+    }
+
+    private function objectiveController(MatchState $match, Position $tile): ?string
+    {
+        $teams = [];
+
+        foreach ($match->units as $unit) {
+            if ($unit->isDefeated() || $unit->position->key() !== $tile->key()) {
+                continue;
+            }
+            $teams[$unit->teamId] = true;
+        }
+
+        if (count($teams) !== 1) {
+            return null;
+        }
+
+        return array_key_first($teams);
+    }
+
+    private function unitOrFail(MatchState $match, string $unitId): UnitState
+    {
+        try {
+            return $match->unit($unitId);
+        } catch (InvalidArgumentException $exception) {
+            throw new CombatException("Unknown unit: {$unitId}.", previous: $exception);
+        }
+    }
+
+    private function assertMatchActive(MatchState $match): void
+    {
+        if ($match->winnerTeamId !== null) {
+            throw new CombatException('The match is already complete.');
+        }
+    }
+
+    /** @return list<string> */
+    private static function tilesWithinRadius(Battlefield $battlefield, Position $center, int $radius): array
+    {
+        $seen = [$center->key() => true];
+        $frontier = [$center];
+        $result = [$center->key()];
+
+        for ($step = 0; $step < $radius; $step++) {
+            $next = [];
+            foreach ($frontier as $position) {
+                foreach ([[1, 0], [-1, 0], [0, 1], [0, -1]] as $offset) {
+                    $candidate = new Position($position->x + $offset[0], $position->y + $offset[1]);
+                    if (!$battlefield->contains($candidate)) {
+                        continue;
+                    }
+                    $key = $candidate->key();
+                    if (isset($seen[$key])) {
+                        continue;
+                    }
+                    $seen[$key] = true;
+                    $result[] = $key;
+                    $next[] = $candidate;
+                }
+            }
+            $frontier = $next;
+        }
+
+        return $result;
+    }
+
+    private function assertCanAct(MatchState $match, UnitState $unit): void
+    {
+        if ($unit->teamId !== $match->activeTeamId) {
+            throw new CombatException("It is not this unit's turn.");
+        }
+
+        if ($unit->isDefeated()) {
+            throw new CombatException('Defeated units cannot act.');
+        }
+
+        if ($unit->actionsRemaining === 0) {
+            throw new CombatException('Unit has no actions remaining.');
+        }
+    }
+}

src/Domain/CombatException.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Domain;
+
+use DomainException;
+
+final class CombatException extends DomainException
+{
+}

src/Domain/DeploymentZone.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Domain;
+
+use InvalidArgumentException;
+
+final readonly class DeploymentZone
+{
+    /** @param list<Position> $positions */
+    public function __construct(
+        public string $teamId,
+        public array $positions,
+    ) {
+        if ($teamId === '') {
+            throw new InvalidArgumentException('Deployment zone team id cannot be empty.');
+        }
+
+        if ($positions === []) {
+            throw new InvalidArgumentException('Deployment zone must contain at least one position.');
+        }
+
+        if (!array_is_list($positions)) { // @phpstan-ignore function.alreadyNarrowedType (Runtime guard: PHPDoc is not a runtime contract for JSON-sourced arrays in Plan 4.)
+            throw new InvalidArgumentException('Deployment zone positions must be a list.');
+        }
+    }
+
+    public function contains(Position $position): bool
+    {
+        foreach ($this->positions as $candidate) {
+            if ($candidate->key() === $position->key()) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+}

src/Domain/MatchState.php

@@ -0,0 +1,233 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Domain;
+
+use InvalidArgumentException;
+
+final readonly class MatchState
+{
+    /**
+     * @param list<UnitState> $units
+     * @param list<string> $actionLog
+     * @param array<string, ObjectiveMarker> $objectives
+     * @param array<string, int> $objectiveControl
+     */
+    public function __construct(
+        public Battlefield $battlefield,
+        public array $units,
+        public string $activeTeamId,
+        public int $round = 1,
+        public ?string $winnerTeamId = null,
+        public array $actionLog = [],
+        public array $objectives = [],
+        public VictoryCondition $victoryCondition = VictoryCondition::EliminateAll,
+        public int $holdRoundsRequired = 1,
+        public array $objectiveControl = [],
+    ) {
+        if (!self::isList($units)) {
+            throw new InvalidArgumentException('Match units must be a list.');
+        }
+
+        if ($units === []) {
+            throw new InvalidArgumentException('Match must contain at least one unit.');
+        }
+
+        $unitIds = [];
+        $teamIds = [];
+        $occupiedPositions = [];
+
+        foreach ($units as $unit) {
+            if (!self::isUnitState($unit)) {
+                throw new InvalidArgumentException('Match units must contain only UnitState instances.');
+            }
+
+            if (isset($unitIds[$unit->id])) {
+                throw new InvalidArgumentException("Duplicate unit id: {$unit->id}.");
+            }
+
+            if (!$battlefield->contains($unit->position)) {
+                throw new InvalidArgumentException("Unit {$unit->id} is outside the battlefield.");
+            }
+
+            if (!$unit->isDefeated() && $battlefield->terrainAt($unit->position)->movementCost() === null) {
+                throw new InvalidArgumentException("Living unit {$unit->id} must stand on passable terrain.");
+            }
+
+            $positionKey = $unit->position->key();
+
+            if (!$unit->isDefeated() && isset($occupiedPositions[$positionKey])) {
+                throw new InvalidArgumentException("Living units cannot share position {$positionKey}.");
+            }
+
+            if (!$unit->isDefeated()) {
+                $occupiedPositions[$positionKey] = true;
+            }
+
+            $unitIds[$unit->id] = true;
+            $teamIds[$unit->teamId] = true;
+        }
+
+        if ($activeTeamId === '') {
+            throw new InvalidArgumentException('Active team id cannot be empty.');
+        }
+
+        if (!isset($teamIds[$activeTeamId])) {
+            throw new InvalidArgumentException("Active team has no units: {$activeTeamId}.");
+        }
+
+        if ($round < 1) {
+            throw new InvalidArgumentException('Match round must be at least 1.');
+        }
+
+        if (!self::isList($actionLog)) {
+            throw new InvalidArgumentException('Match action log must be a list.');
+        }
+
+        foreach ($actionLog as $entry) {
+            if (!self::isString($entry)) {
+                throw new InvalidArgumentException('Match action log entries must be strings.');
+            }
+        }
+
+        if ($winnerTeamId !== null && $winnerTeamId === '') {
+            throw new InvalidArgumentException('Winner team id cannot be empty.');
+        }
+
+        if ($winnerTeamId !== null && !isset($teamIds[$winnerTeamId])) {
+            throw new InvalidArgumentException("Winner team has no units: {$winnerTeamId}.");
+        }
+
+        if ($holdRoundsRequired < 1) {
+            throw new InvalidArgumentException('Hold rounds required must be at least 1.');
+        }
+
+        foreach ($objectives as $objective) {
+            if (!$objective instanceof ObjectiveMarker) { // @phpstan-ignore instanceof.alwaysTrue (Runtime guard: PHPDoc is not a runtime contract for JSON-sourced arrays in Plan 4.)
+                throw new InvalidArgumentException('Objectives must be ObjectiveMarker instances.');
+            }
+            if (!$battlefield->contains($objective->position)) {
+                throw new InvalidArgumentException("Objective {$objective->id} is outside the battlefield.");
+            }
+        }
+
+        foreach ($objectiveControl as $teamId => $count) {
+            if (!self::isString($teamId) || $teamId === '') {
+                throw new InvalidArgumentException('Objective control team id must be a non-empty string.');
+            }
+            if (!self::isInt($count) || $count < 0) {
+                throw new InvalidArgumentException('Objective control count must be a non-negative integer.');
+            }
+        }
+    }
+
+    private static function isUnitState(mixed $unit): bool
+    {
+        return $unit instanceof UnitState;
+    }
+
+    private static function isString(mixed $value): bool
+    {
+        return is_string($value);
+    }
+
+    private static function isInt(mixed $value): bool
+    {
+        return is_int($value);
+    }
+
+    private static function isList(mixed $value): bool
+    {
+        return is_array($value) && array_is_list($value);
+    }
+
+    public function unit(string $id): UnitState
+    {
+        foreach ($this->units as $unit) {
+            if ($unit->id === $id) {
+                return $unit;
+            }
+        }
+
+        throw new InvalidArgumentException("Unknown unit id: {$id}.");
+    }
+
+    public function withUnit(UnitState $replacement): self
+    {
+        $units = $this->units;
+
+        foreach ($units as $index => $unit) {
+            if ($unit->id === $replacement->id) {
+                $units[$index] = $replacement;
+
+                return $this->copy(units: $units);
+            }
+        }
+
+        throw new InvalidArgumentException("Unknown unit id: {$replacement->id}.");
+    }
+
+    public function withWinner(?string $winnerTeamId): self
+    {
+        return new self(
+            $this->battlefield,
+            $this->units,
+            $this->activeTeamId,
+            $this->round,
+            $winnerTeamId,
+            $this->actionLog,
+            $this->objectives,
+            $this->victoryCondition,
+            $this->holdRoundsRequired,
+            $this->objectiveControl,
+        );
+    }
+
+    /**
+     * @param array<string, int> $objectiveControl
+     */
+    public function withObjectiveControl(array $objectiveControl): self
+    {
+        return new self(
+            $this->battlefield,
+            $this->units,
+            $this->activeTeamId,
+            $this->round,
+            $this->winnerTeamId,
+            $this->actionLog,
+            $this->objectives,
+            $this->victoryCondition,
+            $this->holdRoundsRequired,
+            $objectiveControl,
+        );
+    }
+
+    /**
+     * @param list<UnitState>|null $units
+     * @param list<string>|null $actionLog
+     * @param array<string, ObjectiveMarker>|null $objectives
+     * @param array<string, int>|null $objectiveControl
+     */
+    public function copy(
+        ?array $units = null,
+        ?string $activeTeamId = null,
+        ?int $round = null,
+        ?array $actionLog = null,
+        ?array $objectives = null,
+        ?array $objectiveControl = null,
+    ): self {
+        return new self(
+            $this->battlefield,
+            $units ?? $this->units,
+            $activeTeamId ?? $this->activeTeamId,
+            $round ?? $this->round,
+            $this->winnerTeamId,
+            $actionLog ?? $this->actionLog,
+            $objectives ?? $this->objectives,
+            $this->victoryCondition,
+            $this->holdRoundsRequired,
+            $objectiveControl ?? $this->objectiveControl,
+        );
+    }
+}

src/Domain/ObjectiveControl.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Domain;
+
+use InvalidArgumentException;
+
+final readonly class ObjectiveControl
+{
+    /** @param array<string, int> $roundsByTeam */
+    public function __construct(public array $roundsByTeam)
+    {
+        foreach ($roundsByTeam as $teamId => $count) {
+            if ($teamId === '') {
+                throw new InvalidArgumentException('Objective control team id cannot be empty.');
+            }
+            if ($count < 0) {
+                throw new InvalidArgumentException('Objective control count cannot be negative.');
+            }
+        }
+    }
+
+    public static function empty(): self
+    {
+        return new self([]);
+    }
+
+    public function recordRound(string $controllerTeamId): self
+    {
+        if ($controllerTeamId === '') {
+            throw new InvalidArgumentException('Controller team id cannot be empty.');
+        }
+
+        $next = $this->roundsByTeam;
+        $next[$controllerTeamId] = ($next[$controllerTeamId] ?? 0) + 1;
+
+        return new self($next);
+    }
+
+    /** @return array{teamId: string, rounds: int} */
+    public function forTeam(string $teamId): array
+    {
+        return ['teamId' => $teamId, 'rounds' => $this->roundsByTeam[$teamId] ?? 0];
+    }
+}

src/Domain/ObjectiveMarker.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Domain;
+
+use InvalidArgumentException;
+
+final readonly class ObjectiveMarker
+{
+    public function __construct(
+        public string $id,
+        public Position $position,
+    ) {
+        if ($id === '') {
+            throw new InvalidArgumentException('Objective id cannot be empty.');
+        }
+    }
+
+    public function key(): string
+    {
+        return $this->id;
+    }
+}

src/Domain/Position.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Domain;
+
+final readonly class Position
+{
+    public function __construct(
+        public int $x,
+        public int $y,
+    ) {
+    }
+
+    public function key(): string
+    {
+        return $this->x . ':' . $this->y;
+    }
+
+    public function distanceTo(self $position): int
+    {
+        return abs($this->x - $position->x) + abs($this->y - $position->y);
+    }
+}

src/Domain/Scenario.php

@@ -0,0 +1,160 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Domain;
+
+use InvalidArgumentException;
+
+final readonly class Scenario
+{
+    /**
+     * @param list<UnitState> $units
+     * @param array<string, DeploymentZone> $deploymentZones
+     * @param array<string, ObjectiveMarker> $objectives
+     */
+    public function __construct(
+        public string $id,
+        public string $name,
+        public Battlefield $battlefield,
+        public array $units,
+        public array $deploymentZones,
+        public array $objectives,
+        public VictoryCondition $victoryCondition,
+        public int $holdRoundsRequired,
+    ) {
+        if ($id === '') {
+            throw new InvalidArgumentException('Scenario id cannot be empty.');
+        }
+
+        if ($name === '') {
+            throw new InvalidArgumentException('Scenario name cannot be empty.');
+        }
+
+        if (!array_is_list($units)) { // @phpstan-ignore function.alreadyNarrowedType (Runtime guard: PHPDoc is not a runtime contract for JSON-sourced arrays in Plan 4.)
+            throw new InvalidArgumentException('Scenario units must be a list.');
+        }
+
+        if ($deploymentZones === []) {
+            throw new InvalidArgumentException('Scenario must declare at least one deployment zone.');
+        }
+
+        if (count($deploymentZones) !== 2) {
+            throw new InvalidArgumentException('Scenarios must declare exactly two deployment zones.');
+        }
+
+        if ($holdRoundsRequired < 1) {
+            throw new InvalidArgumentException('Hold rounds required must be at least 1.');
+        }
+
+        if ($victoryCondition === VictoryCondition::HoldObjective && count($this->objectives) !== 1) {
+            throw new InvalidArgumentException('Hold objective victory requires exactly one objective.');
+        }
+
+        if ($victoryCondition === VictoryCondition::EliminateAll && $this->objectives !== []) {
+            throw new InvalidArgumentException('Eliminate all victory does not allow objectives.');
+        }
+
+        $unitsByTeam = $this->groupUnitsByTeam($units);
+
+        foreach ($unitsByTeam as $teamId => $teamUnits) {
+            if (count($teamUnits) < 3 || count($teamUnits) > 6) {
+                throw new InvalidArgumentException("Team {$teamId} must have between 3 and 6 units.");
+            }
+
+            if (!isset($deploymentZones[$teamId])) {
+                throw new InvalidArgumentException("Team {$teamId} is missing a deployment zone.");
+            }
+        }
+
+        foreach ($units as $unit) {
+            if (!$this->battlefield->contains($unit->position)) {
+                throw new InvalidArgumentException("Unit {$unit->id} is outside the battlefield.");
+            }
+
+            $template = ArchetypeCatalog::templates()[$unit->archetype->value] ?? null;
+            if ($template === null) {
+                throw new InvalidArgumentException("Unit {$unit->id} uses an unknown archetype.");
+            }
+
+            if ($unit->maxHealth < $template->minHealth || $unit->maxHealth > $template->maxHealth) {
+                throw new InvalidArgumentException("Unit {$unit->id} health is outside archetype bounds.");
+            }
+            if ($unit->attack < $template->minAttack || $unit->attack > $template->maxAttack) {
+                throw new InvalidArgumentException("Unit {$unit->id} attack is outside archetype bounds.");
+            }
+            if ($unit->defense < $template->minDefense || $unit->defense > $template->maxDefense) {
+                throw new InvalidArgumentException("Unit {$unit->id} defense is outside archetype bounds.");
+            }
+            if ($unit->speed < $template->minSpeed || $unit->speed > $template->maxSpeed) {
+                throw new InvalidArgumentException("Unit {$unit->id} speed is outside archetype bounds.");
+            }
+
+            foreach ($unit->abilities as $ability) {
+                if (!in_array($ability, $template->allowedAbilities, true)) {
+                    throw new InvalidArgumentException("Unit {$unit->id} has an ability that its archetype forbids.");
+                }
+            }
+
+            $zone = $deploymentZones[$unit->teamId] ?? null;
+            if ($zone === null || !$zone->contains($unit->position)) {
+                throw new InvalidArgumentException("Unit {$unit->id} must start inside team {$unit->teamId} deployment zone.");
+            }
+        }
+
+        foreach ($objectives as $objective) {
+            if (!$this->battlefield->contains($objective->position)) {
+                throw new InvalidArgumentException("Objective {$objective->id} is outside the battlefield.");
+            }
+        }
+    }
+
+    public function startMatch(string $activeTeamId): MatchState
+    {
+        $resetUnits = [];
+
+        foreach ($this->units as $unit) {
+            $resetUnits[] = new UnitState(
+                $unit->id,
+                $unit->teamId,
+                $unit->position,
+                $unit->maxHealth,
+                $unit->maxHealth,
+                $unit->attack,
+                $unit->defense,
+                $unit->speed,
+                2,
+                false,
+                $unit->archetype,
+                $unit->abilities,
+                0,
+                false,
+            );
+        }
+
+        return new MatchState(
+            battlefield: $this->battlefield,
+            units: $resetUnits,
+            activeTeamId: $activeTeamId,
+            objectives: $this->objectives,
+            victoryCondition: $this->victoryCondition,
+            holdRoundsRequired: $this->holdRoundsRequired,
+        );
+    }
+
+    /**
+     * @param list<UnitState> $units
+     * @return array<string, list<UnitState>>
+     */
+    private function groupUnitsByTeam(array $units): array
+    {
+        $grouped = [];
+
+        foreach ($units as $unit) {
+            $grouped[$unit->teamId] ??= [];
+            $grouped[$unit->teamId][] = $unit;
+        }
+
+        return $grouped;
+    }
+}

src/Domain/ScenarioValidator.php

@@ -0,0 +1,82 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Domain;
+
+final class ScenarioValidator
+{
+    /**
+     * @return list<string>
+     */
+    public static function validate(Scenario $scenario): array
+    {
+        $errors = [];
+
+        $occupied = [];
+
+        foreach ($scenario->deploymentZones as $teamId => $zone) {
+            foreach ($zone->positions as $position) {
+                if (!$scenario->battlefield->contains($position)) {
+                    $errors[] = "Deployment zone for {$teamId} includes a position outside the battlefield.";
+                    continue;
+                }
+                if ($scenario->battlefield->terrainAt($position)->movementCost() === null) {
+                    $errors[] = "Deployment zone for {$teamId} sits on impassable terrain at {$position->key()}.";
+                }
+                if (isset($occupied[$position->key()])) {
+                    $errors[] = "Deployment zones overlap at {$position->key()}.";
+                }
+                $occupied[$position->key()] = $teamId;
+            }
+        }
+
+        $reachableFromDeployment = self::reachableFromDeployment($scenario, $occupied);
+
+        foreach ($scenario->objectives as $objective) {
+            if (!$scenario->battlefield->contains($objective->position)) {
+                $errors[] = "Objective {$objective->id} is outside the battlefield.";
+                continue;
+            }
+            if ($scenario->battlefield->terrainAt($objective->position)->movementCost() === null) {
+                $errors[] = "Objective {$objective->id} sits on impassable terrain.";
+            }
+            if (!isset($reachableFromDeployment[$objective->position->key()])) {
+                $errors[] = "Objective {$objective->id} is unreachable from any deployment zone.";
+            }
+        }
+
+        return $errors;
+    }
+
+    /**
+     * @param array<string, string> $occupied
+     * @return array<string, true>
+     */
+    private static function reachableFromDeployment(Scenario $scenario, array $occupied): array
+    {
+        $merged = $scenario->units;
+        $allReachable = [];
+
+        foreach ($merged as $unit) {
+            $others = [];
+
+            foreach ($merged as $other) {
+                if ($other->id === $unit->id || $other->isDefeated()) {
+                    continue;
+                }
+                $others[] = $other->position;
+            }
+
+            $reachable = $scenario->battlefield->reachable($unit->position, $unit->speed, $others);
+
+            foreach ($reachable as $key => $_cost) {
+                if (!isset($occupied[$key])) {
+                    $allReachable[$key] = true;
+                }
+            }
+        }
+
+        return $allReachable;
+    }
+}

src/Domain/Terrain.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Domain;
+
+enum Terrain: string
+{
+    case Open = 'open';
+    case Forest = 'forest';
+    case Rough = 'rough';
+    case Water = 'water';
+    case Blocking = 'blocking';
+
+    public function movementCost(): ?int
+    {
+        return match ($this) {
+            self::Open => 1,
+            self::Forest, self::Rough => 2,
+            self::Water, self::Blocking => null,
+        };
+    }
+
+    public function defenseBonus(): int
+    {
+        return $this === self::Forest ? 1 : 0;
+    }
+}

src/Domain/UnitState.php

@@ -0,0 +1,182 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Domain;
+
+use InvalidArgumentException;
+
+final readonly class UnitState
+{
+    /** @param list<string> $abilities */
+    public function __construct(
+        public string $id,
+        public string $teamId,
+        public Position $position,
+        public int $maxHealth,
+        public int $health,
+        public int $attack,
+        public int $defense,
+        public int $speed,
+        public int $actionsRemaining,
+        public bool $hasAttacked = false,
+        public Archetype $archetype = Archetype::Defender,
+        public array $abilities = [],
+        public int $attackBonus = 0,
+        public bool $hasUsedAbility = false,
+    ) {
+        if ($id === '') {
+            throw new InvalidArgumentException('Unit id cannot be empty.');
+        }
+
+        if ($teamId === '') {
+            throw new InvalidArgumentException('Unit team id cannot be empty.');
+        }
+
+        if ($maxHealth < 1) {
+            throw new InvalidArgumentException('Unit maximum health must be at least 1.');
+        }
+
+        if ($health < 0 || $health > $maxHealth) {
+            throw new InvalidArgumentException('Unit health must be between 0 and maximum health.');
+        }
+
+        if ($attack < 0 || $defense < 0) {
+            throw new InvalidArgumentException('Unit attack and defense cannot be negative.');
+        }
+
+        if ($speed < 1) {
+            throw new InvalidArgumentException('Unit speed must be at least 1.');
+        }
+
+        if ($actionsRemaining < 0 || $actionsRemaining > 2) {
+            throw new InvalidArgumentException('Unit actions remaining must be between 0 and 2.');
+        }
+
+        if ($attackBonus < 0) {
+            throw new InvalidArgumentException('Unit attack bonus cannot be negative.');
+        }
+
+        if (!self::isList($abilities)) {
+            throw new InvalidArgumentException('Unit abilities must be a list.');
+        }
+
+        foreach ($abilities as $ability) {
+            // @phpstan-ignore function.alreadyNarrowedType (Runtime guard: PHPDoc is not a runtime contract for JSON-sourced arrays in Plan 4.)
+            if (!is_string($ability) || $ability === '') {
+                throw new InvalidArgumentException('Unit abilities must be non-empty strings.');
+            }
+        }
+    }
+
+    public function isDefeated(): bool
+    {
+        return $this->health === 0;
+    }
+
+    /** @return list<string> */
+    public function allowedAbilities(): array
+    {
+        return ArchetypeCatalog::templates()[$this->archetype->value]->allowedAbilities;
+    }
+
+    public function moveTo(Position $position): self
+    {
+        return $this->copy(position: $position);
+    }
+
+    public function spendAction(): self
+    {
+        if ($this->actionsRemaining === 0) {
+            throw new InvalidArgumentException('Unit has no actions remaining.');
+        }
+
+        return $this->copy(actionsRemaining: $this->actionsRemaining - 1);
+    }
+
+    public function spendAbility(): self
+    {
+        if ($this->hasUsedAbility) {
+            throw new InvalidArgumentException('Unit has already used an ability this turn.');
+        }
+
+        if ($this->actionsRemaining === 0) {
+            throw new InvalidArgumentException('Unit has no actions remaining.');
+        }
+
+        return $this->copy(actionsRemaining: $this->actionsRemaining - 1, hasUsedAbility: true);
+    }
+
+    public function takeDamage(int $damage): self
+    {
+        return $this->copy(health: max(0, $this->health - max(0, $damage)));
+    }
+
+    public function restoreHealth(int $amount): self
+    {
+        if ($amount < 0) {
+            throw new InvalidArgumentException('Restore health amount cannot be negative.');
+        }
+
+        return $this->copy(health: min($this->maxHealth, $this->health + $amount));
+    }
+
+    public function markAttacked(): self
+    {
+        return $this->copy(hasAttacked: true);
+    }
+
+    public function withAttackBonus(int $bonus): self
+    {
+        if ($bonus < 0) {
+            throw new InvalidArgumentException('Attack bonus cannot be negative.');
+        }
+
+        return $this->copy(attackBonus: $bonus);
+    }
+
+    public function startTurn(): self
+    {
+        if ($this->isDefeated()) {
+            return $this;
+        }
+
+        return $this->copy(
+            actionsRemaining: 2,
+            hasAttacked: false,
+            attackBonus: 0,
+            hasUsedAbility: false,
+        );
+    }
+
+    private function copy(
+        ?Position $position = null,
+        ?int $health = null,
+        ?int $actionsRemaining = null,
+        ?bool $hasAttacked = null,
+        ?int $attackBonus = null,
+        ?bool $hasUsedAbility = null,
+    ): self {
+        return new self(
+            $this->id,
+            $this->teamId,
+            $position ?? $this->position,
+            $this->maxHealth,
+            $health ?? $this->health,
+            $this->attack,
+            $this->defense,
+            $this->speed,
+            $actionsRemaining ?? $this->actionsRemaining,
+            $hasAttacked ?? $this->hasAttacked,
+            $this->archetype,
+            $this->abilities,
+            $attackBonus ?? $this->attackBonus,
+            $hasUsedAbility ?? $this->hasUsedAbility,
+        );
+    }
+
+    private static function isList(mixed $value): bool
+    {
+        return is_array($value) && array_is_list($value);
+    }
+}

src/Domain/VictoryCondition.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Domain;
+
+enum VictoryCondition: string
+{
+    case EliminateAll = 'eliminate_all';
+    case HoldObjective = 'hold_objective';
+}

src/Http/CsrfToken.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Http;
+
+final class CsrfToken
+{
+    /** @return array{0: string, 1: string} */
+    public static function issue(string $secret): array
+    {
+        $token = bin2hex(random_bytes(32));
+        $cookie = hash_hmac('sha256', $token, $secret);
+
+        return [$token, $cookie];
+    }
+
+    public static function verify(string $submitted, string $secret, string $expectedCookieValue): bool
+    {
+        $computed = hash_hmac('sha256', $submitted, $secret);
+
+        return hash_equals($expectedCookieValue, $computed);
+    }
+}

src/Http/Escape.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Http;
+
+final class Escape
+{
+    public static function html(mixed $value): string
+    {
+        if ($value === null) {
+            return '';
+        }
+
+        return htmlspecialchars((string) $value, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
+    }
+
+    public static function attr(mixed $value): string
+    {
+        return self::html($value);
+    }
+
+    public static function url(string $value): string
+    {
+        return rawurlencode($value);
+    }
+}

src/Http/Handlers/GetAssets.php

@@ -0,0 +1,78 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Http\Handlers;
+
+use BattleForge\Http\Request;
+use BattleForge\Http\Response;
+
+final class GetAssets
+{
+    public function __construct(
+        private readonly string $placeholderDir,
+        private readonly string $uploadsRoot,
+    ) {
+    }
+
+    /** @param array<string, string> $params */
+    public function handle(Request $request, array $params): Response
+    {
+        $kind = $params['kind'] ?? '';
+        $filename = $params['filename'] ?? '';
+
+        if ($kind === 'placeholders') {
+            return $this->serveFrom($this->placeholderDir . '/' . $filename);
+        }
+
+        if ($kind === 'uploads') {
+            $userToken = $params['userToken'] ?? '';
+            if (!preg_match('/^[a-f0-9]{32,}$/', $userToken)) {
+                return Response::html(404, '<h1>Not found</h1>');
+            }
+
+            $requestToken = (string) ($request->server['__uploads_token'] ?? '');
+
+            if ($userToken !== $requestToken) {
+                return Response::html(404, '<h1>Not found</h1>');
+            }
+
+            return $this->serveFrom($this->uploadsRoot . '/' . $userToken . '/' . $filename);
+        }
+
+        return Response::html(404, '<h1>Not found</h1>');
+    }
+
+    private function serveFrom(string $path): Response
+    {
+        if (!is_file($path)) {
+            return Response::html(404, '<h1>Not found</h1>');
+        }
+
+        $body = file_get_contents($path);
+        if ($body === false) {
+            return Response::html(500, '<h1>Read error</h1>');
+        }
+
+        $ext = strtolower(pathinfo($path, PATHINFO_EXTENSION));
+        $contentType = match ($ext) {
+            'png' => 'image/png',
+            'jpg', 'jpeg' => 'image/jpeg',
+            'webp' => 'image/webp',
+            'gif' => 'image/gif',
+            default => 'application/octet-stream',
+        };
+
+        return new Response(200, ['Content-Type' => $contentType] + self::securityHeaders(), $body);
+    }
+
+    /** @return array<string, string> */
+    private static function securityHeaders(): array
+    {
+        return [
+            'X-Content-Type-Options' => 'nosniff',
+            'Referrer-Policy' => 'same-origin',
+            'Content-Security-Policy' => "default-src 'self'; img-src 'self' data:; style-src 'self'",
+        ];
+    }
+}

src/Http/Handlers/GetBattlefieldEditor.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Http\Handlers;
+
+use BattleForge\Http\Request;
+use BattleForge\Http\Response;
+
+final class GetBattlefieldEditor
+{
+    /** @param array<string, string> $params */
+    public function handle(Request $request, array $params): Response
+    {
+        $csrf = $request->cookies['__csrf'] ?? '';
+        $scenarioId = $params['id'] ?? 'new';
+        $width = 8;
+        $height = 8;
+
+        ob_start();
+        require_once __DIR__ . '/../../Views/layout.php';
+        require __DIR__ . '/../../Views/battlefield-editor.php';
+        $body = (string) ob_get_clean();
+
+        return Response::html(200, $body);
+    }
+}

src/Http/Handlers/GetHomePage.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Http\Handlers;
+
+use BattleForge\Http\Request;
+use BattleForge\Http\Response;
+
+final class GetHomePage
+{
+    /** @param array<string, string> $params */
+    public function handle(Request $request, array $params): Response
+    {
+        $csrf = $request->cookies['__csrf'] ?? '';
+
+        ob_start();
+        require_once __DIR__ . '/../../Views/layout.php';
+        require __DIR__ . '/../../Views/home.php';
+        $body = (string) ob_get_clean();
+
+        return Response::html(200, $body);
+    }
+}

src/Http/Handlers/GetTeamEditor.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Http\Handlers;
+
+use BattleForge\Http\Request;
+use BattleForge\Http\Response;
+
+final class GetTeamEditor
+{
+    /** @param array<string, string> $params */
+    public function handle(Request $request, array $params): Response
+    {
+        $csrf = $request->cookies['__csrf'] ?? '';
+        $scenarioId = $params['id'] ?? 'new';
+
+        $error = null;
+        $old = [];
+        $post = [];
+
+        ob_start();
+        require_once __DIR__ . '/../../Views/layout.php';
+        require __DIR__ . '/../../Views/team-editor.php';
+        $body = (string) ob_get_clean();
+
+        return Response::html(200, $body);
+    }
+}

src/Http/Handlers/PostBattlefieldEditor.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Http\Handlers;
+
+use BattleForge\Application\ScenarioDraft;
+use BattleForge\Application\ScenarioSerializer;
+use BattleForge\Domain\ScenarioValidator;
+use BattleForge\Http\CsrfToken;
+use BattleForge\Http\Request;
+use BattleForge\Http\Response;
+
+final class PostBattlefieldEditor
+{
+    /** @param array<string, string> $params */
+    public function handle(Request $request, array $params): Response
+    {
+        $submitted = (string) ($request->server['HTTP_X_CSRF_TOKEN'] ?? '');
+        $expected = (string) ($request->cookies['__csrf'] ?? '');
+        $secret = (string) ($request->server['__csrf_secret'] ?? '');
+
+        if ($secret === '' || $expected === '' || !CsrfToken::verify($submitted, $secret, $expected)) {
+            return Response::json(403, ['error' => 'csrf']);
+        }
+
+        try {
+            $payload = json_decode($request->rawBody, true, flags: JSON_THROW_ON_ERROR);
+        } catch (\JsonException $exception) {
+            return Response::json(400, ['ok' => false, 'errors' => ['Malformed JSON.']]);
+        }
+
+        try {
+            $draft = ScenarioDraft::fromPost($payload);
+            $scenario = $draft->toScenario();
+            ScenarioValidator::validate($scenario);
+        } catch (\InvalidArgumentException $exception) {
+            return Response::json(400, ['ok' => false, 'errors' => [$exception->getMessage()]]);
+        }
+
+        return Response::json(200, ['ok' => true, 'scenario' => ScenarioSerializer::scenarioToArray($scenario)]);
+    }
+}

src/Http/Handlers/PostImageUpload.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Http\Handlers;
+
+use BattleForge\Application\ImageUploadService;
+use BattleForge\Application\InvalidImageException;
+use BattleForge\Http\CsrfToken;
+use BattleForge\Http\Request;
+use BattleForge\Http\Response;
+
+final class PostImageUpload
+{
+    public function __construct(private readonly string $uploadsRoot)
+    {
+    }
+
+    /** @param array<string, string> $params */
+    public function handle(Request $request, array $params): Response
+    {
+        $submitted = (string) ($request->post['_csrf'] ?? '');
+        $expected = (string) ($request->cookies['__csrf'] ?? '');
+        $secret = (string) ($request->server['__csrf_secret'] ?? '');
+
+        if ($secret === '' || $expected === '' || !CsrfToken::verify($submitted, $secret, $expected)) {
+            return Response::json(403, ['error' => 'csrf']);
+        }
+
+        $file = $request->files['image'] ?? null;
+        if ($file === null) {
+            return Response::json(400, ['error' => 'No image uploaded.']);
+        }
+
+        $tempPath = (string) ($file['tmp_name'] ?? '');
+        $declaredMime = (string) ($file['type'] ?? '');
+
+        if ($tempPath === '' || !is_file($tempPath)) {
+            // Production: $request->files['image']['tmp_name'] is PHP-set from the multipart body,
+            // so is_file() confirms the temp file exists. is_uploaded_file() is stricter but
+            // unsuitable for unit tests that synthesize tmp files via tempnam().
+            return Response::json(400, ['error' => 'Upload is not a file.']);
+        }
+
+        $userToken = hash_hmac('sha256', $secret, 'bf-uploads');
+
+        try {
+            $service = new ImageUploadService($userToken, $this->uploadsRoot);
+            $url = $service->store($tempPath, $declaredMime);
+        } catch (InvalidImageException $exception) {
+            return Response::json(400, ['error' => $exception->getMessage()]);
+        }
+
+        return Response::json(200, ['url' => $url]);
+    }
+}

src/Http/Handlers/PostStartMatch.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Http\Handlers;
+
+use BattleForge\Application\ScenarioDraft;
+use BattleForge\Application\ScenarioSerializer;
+use BattleForge\Domain\ScenarioValidator;
+use BattleForge\Http\CsrfToken;
+use BattleForge\Http\Request;
+use BattleForge\Http\Response;
+
+final class PostStartMatch
+{
+    /** @param array<string, string> $params */
+    public function handle(Request $request, array $params): Response
+    {
+        $submitted = (string) ($request->server['HTTP_X_CSRF_TOKEN'] ?? '');
+        $expected = (string) ($request->cookies['__csrf'] ?? '');
+        $secret = (string) ($request->server['__csrf_secret'] ?? '');
+
+        if ($secret === '' || $expected === '' || !CsrfToken::verify($submitted, $secret, $expected)) {
+            return Response::json(403, ['error' => 'csrf']);
+        }
+
+        try {
+            $payload = json_decode($request->rawBody, true, flags: JSON_THROW_ON_ERROR);
+            $draft = ScenarioDraft::fromPost($payload);
+            $scenario = $draft->toScenario();
+            ScenarioValidator::validate($scenario);
+            $match = $scenario->startMatch('alpha');
+        } catch (\JsonException $exception) {
+            return Response::json(400, ['errors' => ['Malformed JSON.']]);
+        } catch (\InvalidArgumentException $exception) {
+            return Response::json(400, ['errors' => [$exception->getMessage()]]);
+        }
+
+        return Response::json(200, ['match' => ScenarioSerializer::matchToArray($match)]);
+    }
+}

src/Http/Handlers/PostTeamEditor.php

@@ -0,0 +1,87 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Http\Handlers;
+
+use BattleForge\Application\ScenarioDraft;
+use BattleForge\Domain\ScenarioValidator;
+use BattleForge\Http\CsrfToken;
+use BattleForge\Http\Escape;
+use BattleForge\Http\Request;
+use BattleForge\Http\Response;
+
+final class PostTeamEditor
+{
+    /** @param array<string, string> $params */
+    public function handle(Request $request, array $params): Response
+    {
+        $submitted = (string) ($request->post['_csrf'] ?? '');
+        $expected = (string) ($request->cookies['__csrf'] ?? '');
+        $secret = (string) ($request->server['__csrf_secret'] ?? '');
+
+        if ($secret === '' || $expected === '' || !CsrfToken::verify($submitted, $secret, $expected)) {
+            return Response::html(403, '<h1>Forbidden</h1>');
+        }
+
+        try {
+            $draft = ScenarioDraft::fromPost($request->post);
+            $scenario = $draft->toScenario();
+            ScenarioValidator::validate($scenario);
+        } catch (\InvalidArgumentException $exception) {
+            return $this->renderForm($request, $params['id'] ?? 'new', $request->cookies['__csrf'] ?? '', $exception->getMessage(), $request->post);
+        }
+
+        $json = json_encode($this->scenarioToArray($scenario), JSON_THROW_ON_ERROR);
+        $url = (string) ($params['id'] ?? $scenario->id);
+        $safeUrl = json_encode($url, JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT);
+        $body = <<<HTML
+<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="utf-8"><title>Saved</title></head>
+<body>
+<p>Scenario saved.</p>
+<script type="module">
+localStorage.setItem('scenario:{$safeUrl}', $json);
+</script>
+</body>
+</html>
+HTML;
+
+        return Response::html(200, $body);
+    }
+
+    /** @param array<string, mixed> $post */
+    private function renderForm(Request $request, string $scenarioId, string $csrf, string $error, array $post): Response
+    {
+        $error = Escape::html($error);
+        $csrf = Escape::html($csrf);
+        $scenarioId = Escape::html($scenarioId);
+
+        $old = array_intersect_key($post, array_flip([
+            'id',
+            'name',
+            'battlefieldWidth',
+            'battlefieldHeight',
+            'victoryCondition',
+            'holdRoundsRequired',
+        ]));
+        $old = array_map(static fn ($v): string => is_scalar($v) ? (string) $v : '', $old);
+
+        $teamA = $post['teamA']['units'] ?? [];
+        $teamB = $post['teamB']['units'] ?? [];
+
+        ob_start();
+        require_once __DIR__ . '/../../Views/layout.php';
+        require __DIR__ . '/../../Views/team-editor.php';
+        $body = (string) ob_get_clean();
+
+        return Response::html(200, $body);
+    }
+
+    /** @return array<string, mixed> */
+    private function scenarioToArray(\BattleForge\Domain\Scenario $scenario): array
+    {
+        return \BattleForge\Application\ScenarioSerializer::scenarioToArray($scenario);
+    }
+}

src/Http/Request.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Http;
+
+final readonly class Request
+{
+    /**
+     * @param array<string, mixed> $get
+     * @param array<string, mixed> $post
+     * @param array<string, array<string, mixed>> $files
+     * @param array<string, string> $cookies
+     * @param array<string, string> $server
+     */
+    public function __construct(
+        public array $get,
+        public array $post,
+        public array $files,
+        public array $cookies,
+        public array $server,
+        public string $queryString,
+        public string $method,
+        public string $path,
+        public ?string $contentType,
+        public string $rawBody,
+    ) {
+    }
+}

src/Http/Response.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Http;
+
+final class Response
+{
+    private const SECURITY_HEADERS = [
+        'X-Content-Type-Options' => 'nosniff',
+        'Referrer-Policy' => 'same-origin',
+        'Content-Security-Policy' => "default-src 'self'; img-src 'self' data:; style-src 'self'",
+    ];
+
+    /** @param array<string, string> $headers */
+    public function __construct(
+        public int $status,
+        public array $headers,
+        public string $body,
+    ) {
+    }
+
+    public static function html(int $status, string $body): self
+    {
+        return new self(
+            $status,
+            ['Content-Type' => 'text/html; charset=utf-8'] + self::SECURITY_HEADERS,
+            $body,
+        );
+    }
+
+    public static function json(int $status, mixed $body): self
+    {
+        return new self(
+            $status,
+            ['Content-Type' => 'application/json; charset=utf-8'] + self::SECURITY_HEADERS,
+            json_encode($body, JSON_THROW_ON_ERROR),
+        );
+    }
+
+    public static function redirect(string $location, int $status = 303): self
+    {
+        return new self(
+            $status,
+            ['Location' => $location] + self::SECURITY_HEADERS,
+            '',
+        );
+    }
+}

src/Http/Router.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Http;
+
+use InvalidArgumentException;
+
+final class Router
+{
+    /** @var list<array{method: string, pattern: string, handler: callable(Request, array<string, string>): Response}> */
+    private array $routes = [];
+
+    public function add(string $method, string $path, callable $handler): void
+    {
+        $pattern = '#^' . preg_replace('#\{([a-zA-Z_][a-zA-Z0-9_]*)\}#', '(?P<$1>[^/]+)', $path) . '$#';
+
+        $this->routes[] = [
+            'method' => strtoupper($method),
+            'pattern' => $pattern,
+            'handler' => $handler,
+        ];
+    }
+
+    public function dispatch(Request $request): Response
+    {
+        foreach ($this->routes as $route) {
+            if ($route['method'] !== $request->method) {
+                continue;
+            }
+
+            if (preg_match($route['pattern'], $request->path, $matches) === 1) {
+                $params = [];
+
+                foreach ($matches as $key => $value) {
+                    if (is_string($key)) {
+                        $params[$key] = $value;
+                    }
+                }
+
+                return ($route['handler'])($request, $params);
+            }
+        }
+
+        return Response::html(404, '<h1>Not found</h1>');
+    }
+}

src/Views/battlefield-editor.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+use BattleForge\Http\Escape;
+
+/**
+ * @var string $csrf    Provided by the front controller.
+ * @var string $scenarioId  Provided by the front controller from the URL.
+ * @var int    $width   Battlefield width (8-16).
+ * @var int    $height  Battlefield height (8-16).
+ */
+$e = static fn (string $v): string => Escape::html($v);
+$a = static fn (string $v): string => Escape::attr($v);
+$terrain = ['open', 'forest', 'rough', 'water', 'blocking'];
+?><?php
+render_layout(static function () use ($csrf, $e, $a, $scenarioId, $width, $height, $terrain): void {
+    ?>
+    <h1>Battlefield editor</h1>
+    <p>Scenario: <strong><?= $e($scenarioId) ?></strong></p>
+    <form id="battlefield-form" method="post" action="<?= $a('/scenarios/' . $e($scenarioId) . '/edit/battlefield') ?>" enctype="application/x-www-form-urlencoded" data-scenario-id="<?= $a($scenarioId) ?>">
+        <input type="hidden" name="_csrf" value="<?= $a($csrf) ?>">
+        <fieldset>
+            <legend>Battlefield</legend>
+            <label>Width: <input type="number" name="battlefieldWidth" min="8" max="16" value="<?= $e((string) $width) ?>" required></label>
+            <label>Height: <input type="number" name="battlefieldHeight" min="8" max="16" value="<?= $e((string) $height) ?>" required></label>
+        </fieldset>
+        <fieldset>
+            <legend>Terrain palette</legend>
+            <?php foreach ($terrain as $t) : ?>
+                <button type="button" data-paint="<?= $a($t) ?>" class="bf-paint"><?= $e($t) ?></button>
+            <?php endforeach; ?>
+        </fieldset>
+        <fieldset>
+            <legend>Grid (<?= $e((string) $width) ?> × <?= $e((string) $height) ?>)</legend>
+            <table class="bf-grid" id="bf-grid">
+                <?php for ($y = 0; $y < $height; $y++) : ?>
+                    <tr>
+                        <?php for ($x = 0; $x < $width; $x++) : ?>
+                            <td><button type="button" class="bf-tile" data-x="<?= $e((string) $x) ?>" data-y="<?= $e((string) $y) ?>" data-paint="open">.</button></td>
+                        <?php endfor; ?>
+                    </tr>
+                <?php endfor; ?>
+            </table>
+        </fieldset>
+        <fieldset>
+            <legend>Deployment zones</legend>
+            <label><input type="radio" name="zoneMode" value="alpha" checked> Place team A zones</label>
+            <label><input type="radio" name="zoneMode" value="bravo"> Place team B zones</label>
+            <label><input type="radio" name="zoneMode" value="objective"> Place objective</label>
+        </fieldset>
+        <button type="submit">Save</button>
+    </form>
+    <script type="module" src="<?= $a('/js/grid-editor.js') ?>"></script>
+    <?php
+}, $csrf, 'Battlefield editor');

src/Views/home.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+use BattleForge\Http\Escape;
+
+/** @var string $csrf Provided by the front controller. */
+?><?php
+render_layout(static function () use ($csrf): void {
+    $e = static fn (string $v): string => Escape::html($v);
+    $a = static fn (string $v): string => Escape::attr($v);
+    ?>
+    <h1>BattleForge</h1>
+    <p><a href="<?= $a('/scenarios/new/edit/team') ?>">New scenario</a></p>
+    <h2>Recent scenarios</h2>
+    <div id="recent"><p class="bf-empty">No saved scenarios yet.</p></div>
+    <script type="module" src="<?= $a('/js/storage.js') ?>"></script>
+    <?php
+}, $csrf, 'BattleForge');

src/Views/layout.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+use BattleForge\Http\Escape;
+
+/**
+ * Render the shared document chrome around a body closure.
+ *
+ * @param callable(): void $body     Emits the template's body content.
+ * @param string $csrf               The pre-issued CSRF token (HMAC-verified by the front controller).
+ * @param string $title              Page title; HTML-escaped by the layout.
+ * @param string $extraHead          Optional extra `<head>` content (e.g. a per-template script tag).
+ */
+function render_layout(callable $body, string $csrf, string $title, string $extraHead = ''): void
+{
+    $e = static fn (string $v): string => Escape::html($v);
+    $a = static fn (string $v): string => Escape::attr($v);
+    ?><!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title><?= $e($title) ?></title>
+    <link rel="stylesheet" href="<?= $a('/assets/styles.css') ?>">
+    <meta name="csrf-token" content="<?= $a($csrf) ?>">
+    <?= $extraHead /* trusted raw HTML for the optional extra-head block */ ?>
+</head>
+<body>
+    <?php $body(); ?>
+</body>
+</html>
+    <?php
+}

src/Views/team-editor.php

@@ -0,0 +1,89 @@
+<?php
+
+declare(strict_types=1);
+
+use BattleForge\Domain\Archetype;
+use BattleForge\Domain\ArchetypeCatalog;
+use BattleForge\Http\Escape;
+
+/**
+ * @var string  $csrf   Provided by the front controller.
+ * @var ?string $error  Optional validator error message; HTML-escaped on output.
+ * @var array<string, string> $old  Optional old form values, keyed by field name; HTML-escaped on output.
+ * @var array<string, mixed>  $post Raw form data (for repopulating per-unit fields).
+ */
+$e = static fn (string $v): string => Escape::html($v);
+$a = static fn (string $v): string => Escape::attr($v);
+$archetypes = ArchetypeCatalog::templates();
+?><?php
+render_layout(static function () use ($csrf, $e, $a, $archetypes, $error, $old, $post): void {
+    ?>
+    <h1>Team editor</h1>
+    <?php if ($error !== null) : ?>
+        <div class="bf-errors"><p><?= $e($error) ?></p></div>
+    <?php endif; ?>
+    <form method="post" action="<?= $a('/scenarios/' . $e($old['id'] ?? 'new') . '/edit/team') ?>" enctype="multipart/form-data">
+        <input type="hidden" name="_csrf" value="<?= $a($csrf) ?>">
+        <fieldset>
+            <legend>Scenario</legend>
+            <label>Id: <input type="text" name="id" value="<?= $e($old['id'] ?? '') ?>" required></label>
+            <label>Name: <input type="text" name="name" value="<?= $e($old['name'] ?? '') ?>" required></label>
+            <label>Battlefield width: <input type="number" name="battlefieldWidth" min="8" max="16" value="<?= $e($old['battlefieldWidth'] ?? '8') ?>" required></label>
+            <label>Battlefield height: <input type="number" name="battlefieldHeight" min="8" max="16" value="<?= $e($old['battlefieldHeight'] ?? '8') ?>" required></label>
+        </fieldset>
+        <fieldset>
+            <legend>Team A</legend>
+            <?php for ($i = 0; $i < 3; $i++) :
+                $row = $post['teamA']['units'][$i] ?? null; ?>
+                <div class="bf-unit">
+                    <input type="text" name="teamA[units][<?= $i ?>][id]" placeholder="a-<?= $i + 1 ?>" value="<?= $e($row['id'] ?? '') ?>" required>
+                    <select name="teamA[units][<?= $i ?>][archetype]" required>
+                        <?php foreach ($archetypes as $key => $template) : ?>
+                            <option value="<?= $a($key) ?>"<?= (($row['archetype'] ?? '') === $key) ? ' selected' : '' ?>><?= $e($key) ?></option>
+                        <?php endforeach; ?>
+                    </select>
+                    <input type="number" name="teamA[units][<?= $i ?>][maxHealth]" placeholder="maxHealth" required>
+                    <input type="number" name="teamA[units][<?= $i ?>][attack]" placeholder="attack" required>
+                    <input type="number" name="teamA[units][<?= $i ?>][defense]" placeholder="defense" required>
+                    <input type="number" name="teamA[units][<?= $i ?>][speed]" placeholder="speed" required>
+                    <input type="text" name="teamA[units][<?= $i ?>][x]" placeholder="x" value="<?= $e($row['x'] ?? '0') ?>" required>
+                    <input type="text" name="teamA[units][<?= $i ?>][y]" placeholder="y" value="<?= $e($row['y'] ?? '0') ?>" required>
+                    <input type="file" name="teamA[units][<?= $i ?>][image]" accept="image/*">
+                    <input type="hidden" name="teamA[units][<?= $i ?>][imageUrl]" value="<?= $e($row['imageUrl'] ?? '') ?>">
+                </div>
+            <?php endfor; ?>
+        </fieldset>
+        <fieldset>
+            <legend>Team B</legend>
+            <?php for ($i = 0; $i < 3; $i++) :
+                $row = $post['teamB']['units'][$i] ?? null; ?>
+                <div class="bf-unit">
+                    <input type="text" name="teamB[units][<?= $i ?>][id]" placeholder="b-<?= $i + 1 ?>" value="<?= $e($row['id'] ?? '') ?>" required>
+                    <select name="teamB[units][<?= $i ?>][archetype]" required>
+                        <?php foreach ($archetypes as $key => $template) : ?>
+                            <option value="<?= $a($key) ?>"<?= (($row['archetype'] ?? '') === $key) ? ' selected' : '' ?>><?= $e($key) ?></option>
+                        <?php endforeach; ?>
+                    </select>
+                    <input type="number" name="teamB[units][<?= $i ?>][maxHealth]" placeholder="maxHealth" required>
+                    <input type="number" name="teamB[units][<?= $i ?>][attack]" placeholder="attack" required>
+                    <input type="number" name="teamB[units][<?= $i ?>][defense]" placeholder="defense" required>
+                    <input type="number" name="teamB[units][<?= $i ?>][speed]" placeholder="speed" required>
+                    <input type="text" name="teamB[units][<?= $i ?>][x]" placeholder="x" value="<?= $e($row['x'] ?? '7') ?>" required>
+                    <input type="text" name="teamB[units][<?= $i ?>][y]" placeholder="y" value="<?= $e($row['y'] ?? '7') ?>" required>
+                    <input type="file" name="teamB[units][<?= $i ?>][image]" accept="image/*">
+                    <input type="hidden" name="teamB[units][<?= $i ?>][imageUrl]" value="<?= $e($row['imageUrl'] ?? '') ?>">
+                </div>
+            <?php endfor; ?>
+        </fieldset>
+        <fieldset>
+            <legend>Victory</legend>
+            <label><input type="radio" name="victoryCondition" value="eliminate_all"<?= (($old['victoryCondition'] ?? 'eliminate_all') === 'eliminate_all') ? ' checked' : '' ?>> Eliminate all</label>
+            <label><input type="radio" name="victoryCondition" value="hold_objective"<?= (($old['victoryCondition'] ?? '') === 'hold_objective') ? ' checked' : '' ?>> Hold objective</label>
+            <label>Hold rounds: <input type="number" name="holdRoundsRequired" min="1" max="10" value="<?= $e($old['holdRoundsRequired'] ?? '1') ?>"></label>
+        </fieldset>
+        <button type="submit">Save</button>
+        <button type="button" id="bf-start-match">Start match</button>
+    </form>
+    <script type="module" src="<?= $a('/js/storage.js') ?>"></script>
+    <?php
+}, $csrf, 'Team editor');

tests/Integration/.gitkeep

@@ -0,0 +1,6 @@
+<?php
+
+declare(strict_types=1);
+
+// Placeholder so PHPUnit's integration test suite has a directory to scan.
+// The first real integration tests land in a later task.

tests/Integration/FullFlowTest.php

@@ -0,0 +1,226 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Integration;
+
+use BattleForge\Http\CsrfToken;
+use PHPUnit\Framework\TestCase;
+
+final class FullFlowTest extends TestCase
+{
+    private const SECRET = 'unit-test-secret';
+
+    protected function setUp(): void
+    {
+        // Reset superglobals between requests.
+        $_GET = [];
+        $_POST = [];
+        $_FILES = [];
+        $_COOKIE = [];
+        $_SERVER = [];
+    }
+
+    public function testTheFullCreateAndSaveFlow(): void
+    {
+        [$token, $cookie] = CsrfToken::issue(self::SECRET);
+        // Use a deterministic secret so the upload token HMAC matches between upload and fetch.
+        putenv('BATTLEFORGE_SECRET=' . self::SECRET);
+
+        try {
+            // Step 1: GET home page.
+            $_SERVER['REQUEST_METHOD'] = 'GET';
+            $_SERVER['REQUEST_URI'] = '/';
+            $homeBody = $this->runFrontController();
+            self::assertStringContainsString('New scenario', $homeBody);
+            self::assertStringContainsString('name="csrf-token"', $homeBody);
+
+            // Step 2: POST team editor.
+            $_COOKIE['__csrf'] = $cookie;
+            $_SERVER['REQUEST_METHOD'] = 'POST';
+            $_SERVER['REQUEST_URI'] = '/scenarios/demo/edit/team';
+            $_SERVER['CONTENT_TYPE'] = 'application/x-www-form-urlencoded';
+            $_SERVER['__csrf_secret'] = self::SECRET;
+            $_POST = $this->validTeamPost($token);
+            $teamBody = $this->runFrontController();
+            self::assertSame(200, $this->lastStatus);
+            self::assertStringContainsString('localStorage.setItem', $teamBody);
+            self::assertStringContainsString('scenario:"demo"', $teamBody);
+
+            // Step 3: POST battlefield editor.
+            $_SERVER['REQUEST_METHOD'] = 'POST';
+            $_SERVER['REQUEST_URI'] = '/scenarios/demo/edit/battlefield';
+            $_SERVER['CONTENT_TYPE'] = 'application/json';
+            $_SERVER['HTTP_X_CSRF_TOKEN'] = $token;
+            $_POST = [];
+            $this->rawBody = json_encode($this->validBattlefieldPayload(), JSON_THROW_ON_ERROR);
+            $_SERVER['__raw_body'] = $this->rawBody;
+            $bfBody = $this->runFrontController();
+            self::assertSame(200, $this->lastStatus);
+            $bfJson = json_decode($bfBody, true);
+            self::assertSame(true, $bfJson['ok'] ?? null);
+
+            // Step 4: POST start-match.
+            $_SERVER['REQUEST_METHOD'] = 'POST';
+            $_SERVER['REQUEST_URI'] = '/scenarios/demo/start';
+            $this->rawBody = json_encode($this->validBattlefieldPayload(), JSON_THROW_ON_ERROR);
+            $_SERVER['__raw_body'] = $this->rawBody;
+            $startBody = $this->runFrontController();
+            self::assertSame(200, $this->lastStatus);
+            $startJson = json_decode($startBody, true);
+            self::assertSame('alpha', $startJson['match']['activeTeamId'] ?? null);
+            self::assertSame(1, $startJson['match']['round'] ?? null);
+            self::assertCount(6, $startJson['match']['units'] ?? []);
+
+            // Step 5: POST image upload, then GET the returned URL.
+            $this->uploadAndFetchAsset();
+        } finally {
+            // Always purge the per-install uploads dir after the test.
+            $uploadsRoot = __DIR__ . '/../../var/uploads';
+            if (is_dir($uploadsRoot)) {
+                foreach (glob($uploadsRoot . '/*/*') as $file) {
+                    @unlink($file);
+                }
+                foreach (glob($uploadsRoot . '/*') as $dir) {
+                    @rmdir($dir);
+                }
+            }
+        }
+    }
+
+    private function uploadAndFetchAsset(): void
+    {
+        $expectedToken = hash_hmac('sha256', self::SECRET, 'bf-uploads');
+        $expectedDir = realpath(__DIR__ . '/../../var/uploads') ?: (__DIR__ . '/../../var/uploads');
+
+        // Create the multipart body manually so we can pre-compute the file we expect to find.
+        $png = base64_decode(
+            'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR4nGNgYGBgAAAABQABh6FO1AAAAABJRU5ErkJggg==',
+            true,
+        );
+        $tmp = tempnam(sys_get_temp_dir(), 'bf-upload-');
+        file_put_contents($tmp, $png);
+
+        try {
+            [$token, $cookie] = CsrfToken::issue(self::SECRET);
+            $_COOKIE['__csrf'] = $cookie;
+            $_SERVER['REQUEST_METHOD'] = 'POST';
+            $_SERVER['REQUEST_URI'] = '/assets/upload';
+            $_SERVER['CONTENT_TYPE'] = 'multipart/form-data; boundary=----test';
+            $_SERVER['__csrf_secret'] = self::SECRET;
+            $_POST = ['_csrf' => $token];
+            $_FILES = [
+                'image' => [
+                    'name' => 'test.png',
+                    'type' => 'image/png',
+                    'tmp_name' => $tmp,
+                    'error' => 0,
+                    'size' => strlen($png),
+                ],
+            ];
+            $this->rawBody = '';
+            $_SERVER['__raw_body'] = '';
+            $body = $this->runFrontController();
+            self::assertSame(200, $this->lastStatus, 'upload response: ' . $body);
+            $payload = json_decode($body, true);
+            $url = is_array($payload) ? (string) ($payload['url'] ?? '') : '';
+            self::assertNotSame('', $url);
+            self::assertStringStartsWith('/assets/uploads/' . $expectedToken . '/', $url);
+
+            // Now fetch the asset back through the front controller.
+            $_COOKIE = [];
+            $_POST = [];
+            $_FILES = [];
+            $_SERVER['REQUEST_METHOD'] = 'GET';
+            $_SERVER['REQUEST_URI'] = $url;
+            unset($_SERVER['CONTENT_TYPE'], $_SERVER['HTTP_X_CSRF_TOKEN'], $_SERVER['__raw_body']);
+            $this->rawBody = '';
+            $fetchBody = $this->runFrontController();
+            self::assertSame(200, $this->lastStatus, 'fetch response: ' . $fetchBody);
+            self::assertSame($png, $fetchBody);
+
+            // Clean up the uploaded file so the outer finally does not loop on it.
+            $filename = substr($url, strlen('/assets/uploads/' . $expectedToken . '/'));
+            @unlink($expectedDir . '/' . $expectedToken . '/' . $filename);
+        } finally {
+            @unlink($tmp);
+        }
+    }
+
+    private string $rawBody = '';
+    private int $lastStatus = 0;
+
+    private function runFrontController(): string
+    {
+        $this->lastStatus = 0;
+        $body = $this->captureOutput(function (): void {
+            $this->lastStatus = (require __DIR__ . '/../../public/index.php') ?? http_response_code();
+        });
+        return $body;
+    }
+
+    /** @param callable(): void $fn */
+    private function captureOutput(callable $fn): string
+    {
+        ob_start();
+        try {
+            $fn();
+        } finally {
+            $output = (string) ob_get_clean();
+        }
+        return $output;
+    }
+
+    /** @return array<string, mixed> */
+    private function validTeamPost(string $token): array
+    {
+        return [
+            '_csrf' => $token,
+            'id' => 'demo',
+            'name' => 'Demo',
+            'battlefieldWidth' => '8',
+            'battlefieldHeight' => '8',
+            'teamA' => ['units' => $this->unitRows('a', 0, 2, 0)],
+            'teamB' => ['units' => $this->unitRows('b', 5, 7, 7)],
+            'victoryCondition' => 'eliminate_all',
+            'holdRoundsRequired' => '1',
+        ];
+    }
+
+    /** @return array<string, mixed> */
+    private function validBattlefieldPayload(): array
+    {
+        return [
+            'id' => 'demo',
+            'name' => 'Demo',
+            'battlefieldWidth' => 8,
+            'battlefieldHeight' => 8,
+            'battlefieldTerrain' => [],
+            'teamA' => ['units' => $this->unitRows('a', 0, 2, 0)],
+            'teamB' => ['units' => $this->unitRows('b', 5, 7, 7)],
+            'victoryCondition' => 'eliminate_all',
+            'holdRoundsRequired' => 1,
+        ];
+    }
+
+    /**
+     * @return list<array<string, string|int>>
+     */
+    private function unitRows(string $teamPrefix, int $xStart, int $xEnd, int $y): array
+    {
+        $rows = [];
+        for ($i = 0; $i <= $xEnd - $xStart; $i++) {
+            $rows[] = [
+                'id' => "{$teamPrefix}{$i}",
+                'archetype' => 'defender',
+                'maxHealth' => 12,
+                'attack' => 3,
+                'defense' => 4,
+                'speed' => 2,
+                'x' => $xStart + $i,
+                'y' => $y,
+            ];
+        }
+        return $rows;
+    }
+}

tests/Integration/GetAssetsTest.php

@@ -0,0 +1,127 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Integration;
+
+use BattleForge\Http\Request;
+use BattleForge\Http\Handlers\GetAssets;
+use PHPUnit\Framework\TestCase;
+
+final class GetAssetsTest extends TestCase
+{
+    private string $placeholderDir;
+    private string $uploadsDir;
+
+    protected function setUp(): void
+    {
+        $this->placeholderDir = sys_get_temp_dir() . '/bf-placeholders-' . bin2hex(random_bytes(4));
+        mkdir($this->placeholderDir, 0755, true);
+        // 1x1 red PNG
+        $png = base64_decode(
+            'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR4nGNgYGBgAAAABQABh6FO1AAAAABJRU5ErkJggg==',
+            true,
+        );
+        file_put_contents($this->placeholderDir . '/defender.png', $png);
+
+        $this->uploadsDir = sys_get_temp_dir() . '/bf-assets-' . bin2hex(random_bytes(4));
+        mkdir($this->uploadsDir, 0700, true);
+    }
+
+    protected function tearDown(): void
+    {
+        if (is_dir($this->uploadsDir)) {
+            foreach (glob($this->uploadsDir . '/*/*') as $file) {
+                unlink($file);
+            }
+            foreach (glob($this->uploadsDir . '/*') as $dir) {
+                rmdir($dir);
+            }
+            rmdir($this->uploadsDir);
+        }
+
+        if (is_dir($this->placeholderDir)) {
+            foreach (glob($this->placeholderDir . '/*') as $file) {
+                unlink($file);
+            }
+            rmdir($this->placeholderDir);
+        }
+    }
+
+    public function testItServesAPlaceholderImageWithoutAuth(): void
+    {
+        $handler = new GetAssets($this->placeholderDir, $this->uploadsDir);
+        $request = new Request([], [], [], [], [], '', 'GET', '/assets/placeholders/defender.png', null, '');
+        $response = $handler->handle($request, ['kind' => 'placeholders', 'filename' => 'defender.png']);
+
+        self::assertSame(200, $response->status);
+        self::assertSame('image/png', $response->headers['Content-Type'] ?? '');
+        self::assertGreaterThan(0, strlen($response->body));
+    }
+
+    public function testItReturns404ForAMissingFile(): void
+    {
+        $handler = new GetAssets($this->placeholderDir, $this->uploadsDir);
+        $request = new Request([], [], [], [], [], '', 'GET', '/assets/placeholders/missing.png', null, '');
+        $response = $handler->handle($request, ['kind' => 'placeholders', 'filename' => 'missing.png']);
+
+        self::assertSame(404, $response->status);
+    }
+
+    public function testItServesAnUploadedAssetWhenTheServerTokenMatches(): void
+    {
+        $userToken = str_repeat('a', 64);
+        $namespace = $this->uploadsDir . '/' . $userToken;
+        mkdir($namespace, 0700, true);
+        $payload = base64_decode(
+            'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR4nGNgYGBgAAAABQABh6FO1AAAAABJRU5ErkJggg==',
+            true,
+        );
+        file_put_contents($namespace . '/demo.png', $payload);
+
+        $handler = new GetAssets($this->placeholderDir, $this->uploadsDir);
+        $request = new Request(
+            [],
+            [],
+            [],
+            [],
+            ['__uploads_token' => $userToken],
+            '',
+            'GET',
+            '/assets/uploads/' . $userToken . '/demo.png',
+            null,
+            '',
+        );
+        $response = $handler->handle(
+            $request,
+            ['kind' => 'uploads', 'userToken' => $userToken, 'filename' => 'demo.png'],
+        );
+
+        self::assertSame(200, $response->status);
+        self::assertSame('image/png', $response->headers['Content-Type'] ?? '');
+        self::assertSame($payload, $response->body);
+    }
+
+    public function testItRefusesAnUploadedAssetWhenTheServerTokenDiffers(): void
+    {
+        $handler = new GetAssets($this->placeholderDir, $this->uploadsDir);
+        $request = new Request(
+            [],
+            [],
+            [],
+            [],
+            ['__uploads_token' => str_repeat('a', 64)],
+            '',
+            'GET',
+            '/assets/uploads/abc/def.png',
+            null,
+            '',
+        );
+        $response = $handler->handle(
+            $request,
+            ['kind' => 'uploads', 'userToken' => str_repeat('b', 64), 'filename' => 'def.png'],
+        );
+
+        self::assertSame(404, $response->status);
+    }
+}

tests/Integration/GetBattlefieldEditorTest.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Integration;
+
+use BattleForge\Http\Handlers\GetBattlefieldEditor;
+use BattleForge\Http\Request;
+use PHPUnit\Framework\TestCase;
+
+final class GetBattlefieldEditorTest extends TestCase
+{
+    public function testItReturnsTheBattlefieldEditorPageWithAnEmptyGrid(): void
+    {
+        $handler = new GetBattlefieldEditor();
+        $request = new Request([], [], [], [], [], '', 'GET', '/scenarios/demo/edit/battlefield', 'text/html', '');
+
+        $response = $handler->handle($request, ['id' => 'demo']);
+
+        self::assertSame(200, $response->status);
+        self::assertStringContainsString('text/html', $response->headers['Content-Type'] ?? '');
+        self::assertStringContainsString('class="bf-grid"', $response->body);
+        self::assertStringContainsString('name="_csrf"', $response->body);
+    }
+}

tests/Integration/GetHomePageTest.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Integration;
+
+use BattleForge\Http\Request;
+use BattleForge\Http\Response;
+use BattleForge\Http\Handlers\GetHomePage;
+use PHPUnit\Framework\TestCase;
+
+final class GetHomePageTest extends TestCase
+{
+    public function testItReturnsTheHomePageWithSecurityHeaders(): void
+    {
+        $handler = new GetHomePage();
+        $request = new Request([], [], [], [], [], '', 'GET', '/', 'text/html', '');
+        $response = $handler->handle($request, []);
+
+        self::assertSame(200, $response->status);
+        self::assertStringContainsString('text/html', $response->headers['Content-Type'] ?? '');
+        self::assertSame('nosniff', $response->headers['X-Content-Type-Options']);
+        self::assertStringContainsString('default-src', $response->headers['Content-Security-Policy']);
+        self::assertStringContainsString('<a href="/scenarios/new/edit/team">', $response->body);
+    }
+}

tests/Integration/GetTeamEditorTest.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Integration;
+
+use BattleForge\Http\Handlers\GetTeamEditor;
+use BattleForge\Http\Request;
+use PHPUnit\Framework\TestCase;
+
+final class GetTeamEditorTest extends TestCase
+{
+    public function testItReturnsTheTeamEditorPageWithSecurityHeaders(): void
+    {
+        $handler = new GetTeamEditor();
+        $request = new Request([], [], [], [], [], '', 'GET', '/scenarios/demo/edit/team', 'text/html', '');
+
+        $response = $handler->handle($request, ['id' => 'demo']);
+
+        self::assertSame(200, $response->status);
+        self::assertStringContainsString('text/html', $response->headers['Content-Type'] ?? '');
+        self::assertSame('nosniff', $response->headers['X-Content-Type-Options']);
+        self::assertStringContainsString('default-src', $response->headers['Content-Security-Policy']);
+        self::assertStringContainsString('name="_csrf"', $response->body);
+        self::assertStringContainsString('name="id"', $response->body);
+        self::assertStringContainsString('name="victoryCondition"', $response->body);
+        self::assertStringContainsString('value="defender"', $response->body);
+    }
+}

tests/Integration/PostBattlefieldEditorTest.php

@@ -0,0 +1,101 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Integration;
+
+use BattleForge\Http\CsrfToken;
+use BattleForge\Http\Handlers\PostBattlefieldEditor;
+use BattleForge\Http\Request;
+use PHPUnit\Framework\TestCase;
+
+final class PostBattlefieldEditorTest extends TestCase
+{
+    private const SECRET = 'unit-test-secret';
+
+    public function testItRejectsARequestWithAMissingCsrfHeader(): void
+    {
+        $handler = new PostBattlefieldEditor();
+        $request = $this->buildRequest(rawBody: '{}', csrfHeader: '');
+        $response = $handler->handle($request, ['id' => 'demo']);
+
+        self::assertSame(403, $response->status);
+        self::assertStringContainsString('csrf', $response->body);
+    }
+
+    public function testItAcceptsAValidBattlefieldJsonAndReturnsOk(): void
+    {
+        [$token, $cookie] = CsrfToken::issue(self::SECRET);
+        $handler = new PostBattlefieldEditor();
+        $request = $this->buildRequest(
+            rawBody: json_encode($this->validBattlefield(), JSON_THROW_ON_ERROR),
+            csrfHeader: $token,
+            cookies: ['__csrf' => $cookie],
+            server: ['__csrf_secret' => self::SECRET],
+        );
+        $response = $handler->handle($request, ['id' => 'demo']);
+
+        self::assertSame(200, $response->status);
+        $body = json_decode($response->body, true);
+        self::assertSame(true, $body['ok'] ?? null);
+        self::assertSame('demo', $body['scenario']['id'] ?? null);
+    }
+
+    public function testItReturns400OnAnInvalidShape(): void
+    {
+        [$token, $cookie] = CsrfToken::issue(self::SECRET);
+        $handler = new PostBattlefieldEditor();
+        $request = $this->buildRequest(
+            rawBody: json_encode(['this' => 'is not a valid scenario'], JSON_THROW_ON_ERROR),
+            csrfHeader: $token,
+            cookies: ['__csrf' => $cookie],
+            server: ['__csrf_secret' => self::SECRET],
+        );
+        $response = $handler->handle($request, ['id' => 'demo']);
+
+        self::assertSame(400, $response->status);
+        $body = json_decode($response->body, true);
+        self::assertSame(false, $body['ok'] ?? null);
+        self::assertNotEmpty($body['errors'] ?? []);
+    }
+
+    /**
+     * @param array<string, string> $cookies
+     * @param array<string, string> $server
+     */
+    private function buildRequest(string $rawBody, string $csrfHeader, array $cookies = [], array $server = []): Request
+    {
+        $server['HTTP_X_CSRF_TOKEN'] = $csrfHeader;
+        $server['CONTENT_TYPE'] = 'application/json';
+
+        return new Request([], [], [], $cookies, $server, '', 'POST', '/scenarios/demo/edit/battlefield', 'application/json', $rawBody);
+    }
+
+    /** @return array<string, mixed> */
+    private function validBattlefield(): array
+    {
+        return [
+            'id' => 'demo',
+            'name' => 'Demo',
+            'battlefieldWidth' => 8,
+            'battlefieldHeight' => 8,
+            'battlefieldTerrain' => [],
+            'teamA' => [
+                'units' => [
+                    ['id' => 'a1', 'archetype' => 'defender', 'maxHealth' => 12, 'attack' => 3, 'defense' => 4, 'speed' => 2, 'x' => 0, 'y' => 0],
+                    ['id' => 'a2', 'archetype' => 'defender', 'maxHealth' => 12, 'attack' => 3, 'defense' => 4, 'speed' => 2, 'x' => 1, 'y' => 0],
+                    ['id' => 'a3', 'archetype' => 'defender', 'maxHealth' => 12, 'attack' => 3, 'defense' => 4, 'speed' => 2, 'x' => 2, 'y' => 0],
+                ],
+            ],
+            'teamB' => [
+                'units' => [
+                    ['id' => 'b1', 'archetype' => 'striker', 'maxHealth' => 8, 'attack' => 5, 'defense' => 2, 'speed' => 3, 'x' => 7, 'y' => 7],
+                    ['id' => 'b2', 'archetype' => 'striker', 'maxHealth' => 8, 'attack' => 5, 'defense' => 2, 'speed' => 3, 'x' => 6, 'y' => 7],
+                    ['id' => 'b3', 'archetype' => 'striker', 'maxHealth' => 8, 'attack' => 5, 'defense' => 2, 'speed' => 3, 'x' => 5, 'y' => 7],
+                ],
+            ],
+            'victoryCondition' => 'eliminate_all',
+            'holdRoundsRequired' => 1,
+        ];
+    }
+}

tests/Integration/PostImageUploadTest.php

@@ -0,0 +1,105 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Integration;
+
+use BattleForge\Http\CsrfToken;
+use BattleForge\Http\Handlers\PostImageUpload;
+use BattleForge\Http\Request;
+use PHPUnit\Framework\TestCase;
+
+final class PostImageUploadTest extends TestCase
+{
+    private const SECRET = 'unit-test-secret';
+    private string $uploadsRoot;
+
+    protected function setUp(): void
+    {
+        $this->uploadsRoot = sys_get_temp_dir() . '/bf-uploads-' . bin2hex(random_bytes(4));
+        mkdir($this->uploadsRoot, 0700, true);
+    }
+
+    protected function tearDown(): void
+    {
+        if (is_dir($this->uploadsRoot)) {
+            foreach (glob($this->uploadsRoot . '/*/*') as $file) {
+                unlink($file);
+            }
+            foreach (glob($this->uploadsRoot . '/*') as $dir) {
+                rmdir($dir);
+            }
+            rmdir($this->uploadsRoot);
+        }
+    }
+
+    public function testItRejectsARequestWithAMissingCsrfField(): void
+    {
+        $handler = new PostImageUpload($this->uploadsRoot);
+        $request = new Request([], [], [], [], [], '', 'POST', '/assets/upload', 'multipart/form-data', '');
+        $response = $handler->handle($request, []);
+
+        self::assertSame(403, $response->status);
+    }
+
+    public function testItAcceptsAValidImageAndReturnsAUrl(): void
+    {
+        [$token, $cookie] = CsrfToken::issue(self::SECRET);
+        $handler = new PostImageUpload($this->uploadsRoot);
+        $tmp = tempnam(sys_get_temp_dir(), 'bf-up');
+        file_put_contents($tmp, $this->validPng(8, 8));
+        $request = new Request(
+            get: [],
+            post: ['_csrf' => $token],
+            files: ['image' => ['name' => 'a.png', 'tmp_name' => $tmp, 'error' => 0, 'size' => 70, 'type' => 'image/png']],
+            cookies: ['__csrf' => $cookie],
+            server: ['__csrf_secret' => self::SECRET],
+            queryString: '',
+            method: 'POST',
+            path: '/assets/upload',
+            contentType: 'multipart/form-data',
+            rawBody: '',
+        );
+        $response = $handler->handle($request, []);
+
+        self::assertSame(200, $response->status);
+        $body = json_decode($response->body, true);
+        self::assertStringStartsWith('/assets/', $body['url'] ?? '');
+        self::assertStringEndsWith('.png', $body['url'] ?? '');
+    }
+
+    public function testItReturns400OnAnInvalidImage(): void
+    {
+        [$token, $cookie] = CsrfToken::issue(self::SECRET);
+        $handler = new PostImageUpload($this->uploadsRoot);
+        $tmp = tempnam(sys_get_temp_dir(), 'bf-up');
+        file_put_contents($tmp, 'not an image');
+        $request = new Request(
+            get: [],
+            post: ['_csrf' => $token],
+            files: ['image' => ['name' => 'a.png', 'tmp_name' => $tmp, 'error' => 0, 'size' => 12, 'type' => 'image/png']],
+            cookies: ['__csrf' => $cookie],
+            server: ['__csrf_secret' => self::SECRET],
+            queryString: '',
+            method: 'POST',
+            path: '/assets/upload',
+            contentType: 'multipart/form-data',
+            rawBody: '',
+        );
+        $response = $handler->handle($request, []);
+
+        self::assertSame(400, $response->status);
+    }
+
+    private function validPng(int $width, int $height): string
+    {
+        if ($width === 8 && $height === 8) {
+            return base64_decode(
+                'iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAYAAADED76LAAAAFElEQVR4nGNgYGD4z0AswK' .
+                'EWBgYGRgYGBkYGRgAAB4nCH2AAAAAElFTkSuQmCC',
+                true,
+            );
+        }
+        throw new \InvalidArgumentException('Only 8x8 base PNG supported.');
+    }
+}

tests/Integration/PostStartMatchTest.php

@@ -0,0 +1,96 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Integration;
+
+use BattleForge\Http\CsrfToken;
+use BattleForge\Http\Handlers\PostStartMatch;
+use BattleForge\Http\Request;
+use PHPUnit\Framework\TestCase;
+
+final class PostStartMatchTest extends TestCase
+{
+    private const SECRET = 'unit-test-secret';
+
+    public function testItRejectsARequestWithAMissingCsrfHeader(): void
+    {
+        $handler = new PostStartMatch();
+        $request = $this->buildRequest('{}', '');
+        $response = $handler->handle($request, ['id' => 'demo']);
+
+        self::assertSame(403, $response->status);
+    }
+
+    public function testItAcceptsAValidScenarioAndReturnsTheInitialMatch(): void
+    {
+        [$token, $cookie] = CsrfToken::issue(self::SECRET);
+        $handler = new PostStartMatch();
+        $request = $this->buildRequest(
+            rawBody: json_encode($this->validScenario(), JSON_THROW_ON_ERROR),
+            csrfHeader: $token,
+            cookies: ['__csrf' => $cookie],
+        );
+        $response = $handler->handle($request, ['id' => 'demo']);
+
+        self::assertSame(200, $response->status);
+        $body = json_decode($response->body, true);
+        self::assertSame('alpha', $body['match']['activeTeamId'] ?? null);
+        self::assertSame(1, $body['match']['round'] ?? null);
+        self::assertCount(6, $body['match']['units'] ?? []);
+    }
+
+    public function testItReturns400OnAnInvalidScenario(): void
+    {
+        [$token, $cookie] = CsrfToken::issue(self::SECRET);
+        $handler = new PostStartMatch();
+        $request = $this->buildRequest(
+            rawBody: json_encode(['this' => 'is not a valid scenario'], JSON_THROW_ON_ERROR),
+            csrfHeader: $token,
+            cookies: ['__csrf' => $cookie],
+        );
+        $response = $handler->handle($request, ['id' => 'demo']);
+
+        self::assertSame(400, $response->status);
+    }
+
+    /** @param array<string, string> $cookies */
+    private function buildRequest(string $rawBody, string $csrfHeader, array $cookies = []): Request
+    {
+        $server = [
+            'HTTP_X_CSRF_TOKEN' => $csrfHeader,
+            '__csrf_secret' => self::SECRET,
+            'CONTENT_TYPE' => 'application/json',
+        ];
+
+        return new Request([], [], [], $cookies, $server, '', 'POST', '/scenarios/demo/start', 'application/json', $rawBody);
+    }
+
+    /** @return array<string, mixed> */
+    private function validScenario(): array
+    {
+        return [
+            'id' => 'demo',
+            'name' => 'Demo',
+            'battlefieldWidth' => 8,
+            'battlefieldHeight' => 8,
+            'battlefieldTerrain' => [],
+            'teamA' => [
+                'units' => [
+                    ['id' => 'a1', 'archetype' => 'defender', 'maxHealth' => 12, 'attack' => 3, 'defense' => 4, 'speed' => 2, 'x' => 0, 'y' => 0],
+                    ['id' => 'a2', 'archetype' => 'defender', 'maxHealth' => 12, 'attack' => 3, 'defense' => 4, 'speed' => 2, 'x' => 1, 'y' => 0],
+                    ['id' => 'a3', 'archetype' => 'defender', 'maxHealth' => 12, 'attack' => 3, 'defense' => 4, 'speed' => 2, 'x' => 2, 'y' => 0],
+                ],
+            ],
+            'teamB' => [
+                'units' => [
+                    ['id' => 'b1', 'archetype' => 'striker', 'maxHealth' => 8, 'attack' => 5, 'defense' => 2, 'speed' => 3, 'x' => 7, 'y' => 7],
+                    ['id' => 'b2', 'archetype' => 'striker', 'maxHealth' => 8, 'attack' => 5, 'defense' => 2, 'speed' => 3, 'x' => 6, 'y' => 7],
+                    ['id' => 'b3', 'archetype' => 'striker', 'maxHealth' => 8, 'attack' => 5, 'defense' => 2, 'speed' => 3, 'x' => 5, 'y' => 7],
+                ],
+            ],
+            'victoryCondition' => 'eliminate_all',
+            'holdRoundsRequired' => 1,
+        ];
+    }
+}

tests/Integration/PostTeamEditorTest.php

@@ -0,0 +1,127 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Integration;
+
+use BattleForge\Domain\Archetype;
+use BattleForge\Http\CsrfToken;
+use BattleForge\Http\Handlers\PostTeamEditor;
+use BattleForge\Http\Request;
+use PHPUnit\Framework\TestCase;
+
+final class PostTeamEditorTest extends TestCase
+{
+    private const SECRET = 'unit-test-secret';
+
+    public function testItRejectsARequestWithAMissingCsrfToken(): void
+    {
+        $handler = new PostTeamEditor();
+        $request = $this->buildRequest(post: ['id' => 'demo']);
+        $response = $handler->handle($request, ['id' => 'demo']);
+
+        self::assertSame(403, $response->status);
+        self::assertStringContainsString('Forbidden', $response->body);
+    }
+
+    public function testItRejectsARequestWithAnInvalidCsrfToken(): void
+    {
+        $handler = new PostTeamEditor();
+        $request = $this->buildRequest(post: ['id' => 'demo', '_csrf' => 'tampered']);
+        $response = $handler->handle($request, ['id' => 'demo']);
+
+        self::assertSame(403, $response->status);
+    }
+
+    public function testItSavesAValidScenarioAndReturnsTheLocalStorageSnippet(): void
+    {
+        [$token, $cookie] = CsrfToken::issue(self::SECRET);
+        $handler = new PostTeamEditor();
+        $request = $this->buildRequest(
+            post: $this->validPost($token),
+            cookies: ['__csrf' => $cookie],
+            server: ['__csrf_secret' => self::SECRET],
+        );
+        $response = $handler->handle($request, ['id' => 'demo']);
+
+        self::assertSame(200, $response->status);
+        self::assertStringContainsString('localStorage.setItem', $response->body);
+        self::assertStringContainsString('scenario:"demo"', $response->body);
+    }
+
+    public function testItRejectsAnOutOfBoundsStatAndReRendersTheForm(): void
+    {
+        [$token, $cookie] = CsrfToken::issue(self::SECRET);
+        $handler = new PostTeamEditor();
+        $post = $this->validPost($token);
+        $post['teamA']['units'][0]['maxHealth'] = '9999';
+        $request = $this->buildRequest(
+            post: $post,
+            cookies: ['__csrf' => $cookie],
+            server: ['__csrf_secret' => self::SECRET],
+        );
+        $response = $handler->handle($request, ['id' => 'demo']);
+
+        self::assertSame(200, $response->status);
+        self::assertStringContainsString('bf-errors', $response->body);
+        self::assertStringContainsString('outside archetype bounds', $response->body);
+    }
+
+    public function testItEscapesAMaliciousIdSoItCannotBreakOutOfTheScriptBlock(): void
+    {
+        [$token, $cookie] = CsrfToken::issue(self::SECRET);
+        $handler = new PostTeamEditor();
+        $post = $this->validPost($token);
+        $post['id'] = '</script><script>alert(1)</script>';
+        $request = $this->buildRequest(
+            post: $post,
+            cookies: ['__csrf' => $cookie],
+            server: ['__csrf_secret' => self::SECRET],
+        );
+        $response = $handler->handle($request, ['id' => $post['id']]);
+
+        self::assertSame(200, $response->status);
+        // The literal payload that would execute must NOT appear verbatim in the body.
+        self::assertStringNotContainsString('<script>alert(1)</script>', $response->body);
+        // The JSON-encoded id is what we want to see, with the </ tag escaped to <\/.
+        self::assertStringContainsString('<\\/script><script>alert(1)<\\/script>', $response->body);
+    }
+
+    /**
+     * @param array<string, mixed>  $post
+     * @param array<string, string> $cookies
+     * @param array<string, string> $server
+     */
+    private function buildRequest(array $post, array $cookies = [], array $server = []): Request
+    {
+        return new Request([], $post, [], $cookies, $server, '', 'POST', '/scenarios/demo/edit/team', 'application/x-www-form-urlencoded', '');
+    }
+
+    /** @return array<string, mixed> */
+    private function validPost(string $token): array
+    {
+        return [
+            '_csrf' => $token,
+            'id' => 'demo',
+            'name' => 'Demo',
+            'battlefieldWidth' => '8',
+            'battlefieldHeight' => '8',
+            'teamA' => [
+                'units' => [
+                    ['id' => 'a1', 'archetype' => 'defender', 'maxHealth' => '12', 'attack' => '3', 'defense' => '4', 'speed' => '2', 'x' => '0', 'y' => '0'],
+                    ['id' => 'a2', 'archetype' => 'defender', 'maxHealth' => '12', 'attack' => '3', 'defense' => '4', 'speed' => '2', 'x' => '1', 'y' => '0'],
+                    ['id' => 'a3', 'archetype' => 'defender', 'maxHealth' => '12', 'attack' => '3', 'defense' => '4', 'speed' => '2', 'x' => '2', 'y' => '0'],
+                ],
+            ],
+            'teamB' => [
+                'units' => [
+                    ['id' => 'b1', 'archetype' => 'striker', 'maxHealth' => '8', 'attack' => '5', 'defense' => '2', 'speed' => '3', 'x' => '7', 'y' => '7'],
+                    ['id' => 'b2', 'archetype' => 'striker', 'maxHealth' => '8', 'attack' => '5', 'defense' => '2', 'speed' => '3', 'x' => '6', 'y' => '7'],
+                    ['id' => 'b3', 'archetype' => 'striker', 'maxHealth' => '8', 'attack' => '5', 'defense' => '2', 'speed' => '3', 'x' => '5', 'y' => '7'],
+                ],
+            ],
+            'victoryCondition' => 'eliminate_all',
+            'holdRoundsRequired' => '1',
+        ];
+    }
+}

tests/Unit/Application/ImageUploadServiceTest.php

@@ -0,0 +1,94 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Unit\Application;
+
+use BattleForge\Application\ImageUploadService;
+use PHPUnit\Framework\TestCase;
+
+final class ImageUploadServiceTest extends TestCase
+{
+    private string $tmpDir;
+
+    protected function setUp(): void
+    {
+        $this->tmpDir = sys_get_temp_dir() . '/bf-uploads-' . bin2hex(random_bytes(4));
+        mkdir($this->tmpDir, 0700, true);
+    }
+
+    protected function tearDown(): void
+    {
+        if (is_dir($this->tmpDir)) {
+            foreach (glob($this->tmpDir . '/*/*') as $file) {
+                unlink($file);
+            }
+            foreach (glob($this->tmpDir . '/*') as $dir) {
+                rmdir($dir);
+            }
+            rmdir($this->tmpDir);
+        }
+    }
+
+    public function testItStoresAValidImageAndReturnsAStableUrl(): void
+    {
+        $service = new ImageUploadService('user-token-1', $this->tmpDir);
+        $tmp = tempnam(sys_get_temp_dir(), 'bf-up');
+        file_put_contents($tmp, self::validPng(8, 8));
+
+        $url = $service->store($tmp, 'image/png');
+
+        self::assertStringStartsWith('/assets/uploads/user-token-1/', $url);
+        self::assertStringEndsWith('.png', $url);
+
+        $stored = $this->tmpDir . '/user-token-1/' . basename($url);
+        self::assertFileExists($stored);
+    }
+
+    public function testItCreatesTheUserNamespaceDirectory(): void
+    {
+        $service = new ImageUploadService('fresh-user', $this->tmpDir);
+        $tmp = tempnam(sys_get_temp_dir(), 'bf-up');
+        file_put_contents($tmp, self::validPng(8, 8));
+
+        $service->store($tmp, 'image/png');
+
+        self::assertDirectoryExists($this->tmpDir . '/fresh-user');
+    }
+
+    public function testItProducesUniqueFilenamesForRepeatedUploads(): void
+    {
+        $service = new ImageUploadService('user-token-2', $this->tmpDir);
+        $tmp1 = tempnam(sys_get_temp_dir(), 'bf-up');
+        $tmp2 = tempnam(sys_get_temp_dir(), 'bf-up');
+        file_put_contents($tmp1, self::validPng(8, 8));
+        file_put_contents($tmp2, self::validPng(8, 8));
+
+        $url1 = $service->store($tmp1, 'image/png');
+        $url2 = $service->store($tmp2, 'image/png');
+
+        self::assertNotSame($url1, $url2);
+    }
+
+    public function testItRejectsAnInvalidImage(): void
+    {
+        $service = new ImageUploadService('user-token-3', $this->tmpDir);
+        $tmp = tempnam(sys_get_temp_dir(), 'bf-up');
+        file_put_contents($tmp, 'not an image');
+
+        $this->expectException(\BattleForge\Application\InvalidImageException::class);
+        $service->store($tmp, 'image/png');
+    }
+
+    private static function validPng(int $width, int $height): string
+    {
+        if ($width === 8 && $height === 8) {
+            return base64_decode(
+                'iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAYAAADED76LAAAAFElEQVR4nGNgYGD4z0AswK' .
+                'EWBgYGRgYGBkYGRgAAB4nCH2AAAAAElFTkSuQmCC',
+                true,
+            );
+        }
+        throw new \InvalidArgumentException('Only 8x8 base PNG supported in tests.');
+    }
+}

tests/Unit/Application/ImageValidatorTest.php

@@ -0,0 +1,180 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Unit\Application;
+
+use BattleForge\Application\ImageValidator;
+use BattleForge\Application\InvalidImageException;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+
+final class ImageValidatorTest extends TestCase
+{
+    private const TMP_DIR = '/tmp';
+
+    public function testItAcceptsAValidPng(): void
+    {
+        $path = self::TMP_DIR . '/bf-valid-' . bin2hex(random_bytes(4)) . '.png';
+        self::assertNotFalse(file_put_contents($path, self::validPng(8, 8)));
+
+        try {
+            $result = ImageValidator::validate($path, 'image/png');
+            self::assertSame('image/png', $result->canonicalMime);
+            self::assertSame('png', $result->extension);
+        } finally {
+            unlink($path);
+        }
+    }
+
+    public function testItRejectsAFileWithTheWrongDeclaredMime(): void
+    {
+        $path = self::TMP_DIR . '/bf-bad-mime-' . bin2hex(random_bytes(4)) . '.png';
+        self::assertNotFalse(file_put_contents($path, self::validPng(8, 8)));
+
+        try {
+            $this->expectException(InvalidImageException::class);
+            $this->expectExceptionMessage('Declared MIME does not match file contents');
+            ImageValidator::validate($path, 'image/jpeg');
+        } finally {
+            unlink($path);
+        }
+    }
+
+    public function testItRejectsTextContent(): void
+    {
+        $path = self::TMP_DIR . '/bf-text-' . bin2hex(random_bytes(4)) . '.txt';
+        self::assertNotFalse(file_put_contents($path, 'this is not an image'));
+
+        try {
+            $this->expectException(InvalidImageException::class);
+            ImageValidator::validate($path, 'image/png');
+        } finally {
+            unlink($path);
+        }
+    }
+
+    public function testItRejectsOversizedFiles(): void
+    {
+        $path = self::TMP_DIR . '/bf-huge-' . bin2hex(random_bytes(4)) . '.png';
+        // Create a 2 MB + 1 byte file
+        $bytes = str_repeat('A', 2_000_001);
+        self::assertNotFalse(file_put_contents($path, $bytes));
+
+        try {
+            $this->expectException(InvalidImageException::class);
+            $this->expectExceptionMessage('exceeds the 2000000 byte limit');
+            ImageValidator::validate($path, 'image/png');
+        } finally {
+            unlink($path);
+        }
+    }
+
+    public function testItRejectsOversizedDimensions(): void
+    {
+        $path = self::TMP_DIR . '/bf-wide-' . bin2hex(random_bytes(4)) . '.png';
+        self::assertNotFalse(file_put_contents($path, self::validPng(600, 8)));
+
+        try {
+            $this->expectException(InvalidImageException::class);
+            $this->expectExceptionMessage('exceed the 512 pixel limit');
+            ImageValidator::validate($path, 'image/png');
+        } finally {
+            unlink($path);
+        }
+    }
+
+    public function testItAcceptsJpegWebpAndGif(): void
+    {
+        $jpeg = self::TMP_DIR . '/bf-jpeg-' . bin2hex(random_bytes(4)) . '.jpg';
+        $webp = self::TMP_DIR . '/bf-webp-' . bin2hex(random_bytes(4)) . '.webp';
+        $gif = self::TMP_DIR . '/bf-gif-' . bin2hex(random_bytes(4)) . '.gif';
+        file_put_contents($jpeg, self::validJpeg(8, 8));
+        file_put_contents($webp, self::validWebp(8, 8));
+        file_put_contents($gif, self::validGif(8, 8));
+
+        try {
+            self::assertSame('jpg', ImageValidator::validate($jpeg, 'image/jpeg')->extension);
+            self::assertSame('webp', ImageValidator::validate($webp, 'image/webp')->extension);
+            self::assertSame('gif', ImageValidator::validate($gif, 'image/gif')->extension);
+        } finally {
+            unlink($jpeg);
+            unlink($webp);
+            unlink($gif);
+        }
+    }
+
+    /**
+     * Build a minimal valid PNG of the given dimensions, using a pre-baked
+     * 8x8 transparent PNG as the base and trusting `getimagesize` to accept
+     * any correctly-formed PNG. We just need the file to (1) have the PNG
+     * magic and (2) be decodable by GD or `getimagesize`.
+     *
+     * For the oversized-dimensions test we synthesize a 600x8 PNG via
+     * `imagecreatetruecolor` + `imagepng` to force the IHDR to claim those
+     * dimensions.
+     */
+    private static function validPng(int $width, int $height): string
+    {
+        if ($width === 8 && $height === 8) {
+            return base64_decode(
+                'iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAYAAADED76LAAAAFElEQVR4nGNgYGD4z0AswK' .
+                'EWBgYGRgYGBkYGRgAAB4nCH2AAAAAElFTkSuQmCC',
+                true,
+            );
+        }
+
+        $im = imagecreatetruecolor($width, $height);
+        if ($im === false) {
+            throw new \RuntimeException('Failed to create image.');
+        }
+        ob_start();
+        imagepng($im);
+        $bytes = ob_get_clean();
+        imagedestroy($im);
+
+        return (string) $bytes;
+    }
+
+    private static function validJpeg(int $width, int $height): string
+    {
+        $im = imagecreatetruecolor($width, $height);
+        if ($im === false) {
+            throw new \RuntimeException('Failed to create image.');
+        }
+        ob_start();
+        imagejpeg($im);
+        $bytes = ob_get_clean();
+        imagedestroy($im);
+
+        return (string) $bytes;
+    }
+
+    private static function validWebp(int $width, int $height): string
+    {
+        $im = imagecreatetruecolor($width, $height);
+        if ($im === false) {
+            throw new \RuntimeException('Failed to create image.');
+        }
+        ob_start();
+        imagewebp($im);
+        $bytes = ob_get_clean();
+        imagedestroy($im);
+
+        return (string) $bytes;
+    }
+
+    private static function validGif(int $width, int $height): string
+    {
+        $im = imagecreatetruecolor($width, $height);
+        if ($im === false) {
+            throw new \RuntimeException('Failed to create image.');
+        }
+        ob_start();
+        imagegif($im);
+        $bytes = ob_get_clean();
+        imagedestroy($im);
+
+        return (string) $bytes;
+    }
+}

tests/Unit/Application/ScenarioDraftTest.php

@@ -0,0 +1,127 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Unit\Application;
+
+use BattleForge\Application\ScenarioDraft;
+use BattleForge\Domain\Archetype;
+use BattleForge\Domain\Battlefield;
+use BattleForge\Domain\DeploymentZone;
+use BattleForge\Domain\Position;
+use BattleForge\Domain\Scenario;
+use BattleForge\Domain\Terrain;
+use BattleForge\Domain\UnitState;
+use BattleForge\Domain\VictoryCondition;
+use PHPUnit\Framework\TestCase;
+
+final class ScenarioDraftTest extends TestCase
+{
+    public function testItBuildsAScenarioFromFormFields(): void
+    {
+        $post = [
+            'id' => 'demo',
+            'name' => 'Demo',
+            'battlefieldWidth' => '8',
+            'battlefieldHeight' => '8',
+            'battlefieldTerrain' => [
+                '0:0' => 'forest',
+            ],
+            'teamA' => [
+                'units' => [
+                    [
+                        'id' => 'a1',
+                        'x' => '0',
+                        'y' => '0',
+                        'archetype' => 'defender',
+                        'maxHealth' => '12',
+                        'attack' => '3',
+                        'defense' => '4',
+                        'speed' => '2',
+                        'abilities' => ['buff'],
+                        'image' => '/assets/placeholders/defender.png',
+                    ],
+                    ['id' => 'a2', 'x' => '1', 'y' => '0', 'archetype' => 'defender', 'maxHealth' => '12', 'attack' => '3', 'defense' => '4', 'speed' => '2', 'abilities' => [], 'image' => ''],
+                    ['id' => 'a3', 'x' => '2', 'y' => '0', 'archetype' => 'defender', 'maxHealth' => '12', 'attack' => '3', 'defense' => '4', 'speed' => '2', 'abilities' => [], 'image' => ''],
+                ],
+            ],
+            'teamB' => [
+                'units' => [
+                    ['id' => 'b1', 'x' => '7', 'y' => '7', 'archetype' => 'striker', 'maxHealth' => '8', 'attack' => '5', 'defense' => '2', 'speed' => '3', 'abilities' => ['area_damage'], 'image' => ''],
+                    ['id' => 'b2', 'x' => '6', 'y' => '7', 'archetype' => 'striker', 'maxHealth' => '8', 'attack' => '5', 'defense' => '2', 'speed' => '3', 'abilities' => [], 'image' => ''],
+                    ['id' => 'b3', 'x' => '5', 'y' => '7', 'archetype' => 'striker', 'maxHealth' => '8', 'attack' => '5', 'defense' => '2', 'speed' => '3', 'abilities' => [], 'image' => ''],
+                ],
+            ],
+            'victoryCondition' => 'eliminate_all',
+            'holdRoundsRequired' => '1',
+        ];
+
+        $draft = ScenarioDraft::fromPost($post);
+        $scenario = $draft->toScenario();
+
+        self::assertSame('demo', $scenario->id);
+        self::assertSame(8, $scenario->battlefield->width);
+        self::assertSame(Terrain::Forest, $scenario->battlefield->terrainAt(new Position(0, 0)));
+        self::assertCount(6, $scenario->units);
+        self::assertSame('a1', $scenario->units[0]->id);
+        self::assertSame(Archetype::Defender, $scenario->units[0]->archetype);
+        self::assertSame(['buff'], $scenario->units[0]->abilities);
+        self::assertSame(VictoryCondition::EliminateAll, $scenario->victoryCondition);
+    }
+
+    public function testItRejectsUnknownArchetype(): void
+    {
+        $post = $this->validPost();
+        $post['teamA']['units'][0]['archetype'] = 'rogue';
+
+        $this->expectException(\InvalidArgumentException::class);
+        ScenarioDraft::fromPost($post)->toScenario();
+    }
+
+    public function testItRejectsUnknownTerrain(): void
+    {
+        $post = $this->validPost();
+        $post['battlefieldTerrain'] = ['0:0' => 'lava'];
+
+        $this->expectException(\InvalidArgumentException::class);
+        ScenarioDraft::fromPost($post)->toScenario();
+    }
+
+    public function testItRejectsUnknownVictoryCondition(): void
+    {
+        $post = $this->validPost();
+        $post['victoryCondition'] = 'first_blood';
+
+        $this->expectException(\InvalidArgumentException::class);
+        ScenarioDraft::fromPost($post)->toScenario();
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    private function validPost(): array
+    {
+        return [
+            'id' => 'demo',
+            'name' => 'Demo',
+            'battlefieldWidth' => '8',
+            'battlefieldHeight' => '8',
+            'teamA' => [
+                'units' => [
+                    ['id' => 'a1', 'x' => '0', 'y' => '0', 'archetype' => 'defender', 'maxHealth' => '12', 'attack' => '3', 'defense' => '4', 'speed' => '2', 'abilities' => [], 'image' => ''],
+                    ['id' => 'a2', 'x' => '1', 'y' => '0', 'archetype' => 'defender', 'maxHealth' => '12', 'attack' => '3', 'defense' => '4', 'speed' => '2', 'abilities' => [], 'image' => ''],
+                    ['id' => 'a3', 'x' => '2', 'y' => '0', 'archetype' => 'defender', 'maxHealth' => '12', 'attack' => '3', 'defense' => '4', 'speed' => '2', 'abilities' => [], 'image' => ''],
+                ],
+            ],
+            'teamB' => [
+                'units' => [
+                    ['id' => 'b1', 'x' => '7', 'y' => '7', 'archetype' => 'striker', 'maxHealth' => '8', 'attack' => '5', 'defense' => '2', 'speed' => '3', 'abilities' => [], 'image' => ''],
+                    ['id' => 'b2', 'x' => '6', 'y' => '7', 'archetype' => 'striker', 'maxHealth' => '8', 'attack' => '5', 'defense' => '2', 'speed' => '3', 'abilities' => [], 'image' => ''],
+                    ['id' => 'b3', 'x' => '5', 'y' => '7', 'archetype' => 'striker', 'maxHealth' => '8', 'attack' => '5', 'defense' => '2', 'speed' => '3', 'abilities' => [], 'image' => ''],
+                ],
+            ],
+            'victoryCondition' => 'eliminate_all',
+            'holdRoundsRequired' => '1',
+        ];
+    }
+}

tests/Unit/Application/ScenarioSerializerTest.php

@@ -0,0 +1,138 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Unit\Application;
+
+use BattleForge\Application\ScenarioSerializer;
+use BattleForge\Domain\Archetype;
+use BattleForge\Domain\Battlefield;
+use BattleForge\Domain\DeploymentZone;
+use BattleForge\Domain\MatchState;
+use BattleForge\Domain\ObjectiveMarker;
+use BattleForge\Domain\Position;
+use BattleForge\Domain\Scenario;
+use BattleForge\Domain\Terrain;
+use BattleForge\Domain\UnitState;
+use BattleForge\Domain\VictoryCondition;
+use PHPUnit\Framework\TestCase;
+
+final class ScenarioSerializerTest extends TestCase
+{
+    public function testItRoundTripsACompleteScenario(): void
+    {
+        $scenario = new Scenario(
+            id: 'demo',
+            name: 'Demo',
+            battlefield: new Battlefield(8, 8, ['0:0' => Terrain::Forest]),
+            units: [
+                new UnitState('alpha-1', 'alpha', new Position(0, 0), 12, 12, 3, 4, 2, 2, false, Archetype::Defender, ['buff'], 0, false),
+                new UnitState('alpha-2', 'alpha', new Position(1, 0), 12, 12, 3, 4, 2, 2, false, Archetype::Defender, [], 0, false),
+                new UnitState('alpha-3', 'alpha', new Position(2, 0), 12, 12, 3, 4, 2, 2, false, Archetype::Defender, [], 0, false),
+                new UnitState('bravo-1', 'bravo', new Position(7, 7), 8, 8, 5, 2, 3, 2, false, Archetype::Striker, ['area_damage'], 0, false),
+                new UnitState('bravo-2', 'bravo', new Position(6, 7), 8, 8, 5, 2, 3, 2, false, Archetype::Striker, [], 0, false),
+                new UnitState('bravo-3', 'bravo', new Position(5, 7), 8, 8, 5, 2, 3, 2, false, Archetype::Striker, [], 0, false),
+            ],
+            deploymentZones: [
+                'alpha' => new DeploymentZone('alpha', [new Position(0, 0), new Position(1, 0), new Position(2, 0)]),
+                'bravo' => new DeploymentZone('bravo', [new Position(7, 7), new Position(6, 7), new Position(5, 7)]),
+            ],
+            objectives: [],
+            victoryCondition: VictoryCondition::EliminateAll,
+            holdRoundsRequired: 1,
+        );
+
+        $array = ScenarioSerializer::scenarioToArray($scenario);
+        $reconstructed = ScenarioSerializer::scenarioFromArray($array);
+
+        self::assertSame($scenario->id, $reconstructed->id);
+        self::assertSame($scenario->name, $reconstructed->name);
+        self::assertSame($scenario->battlefield->width, $reconstructed->battlefield->width);
+        self::assertSame($scenario->battlefield->height, $reconstructed->battlefield->height);
+        self::assertSame('forest', $reconstructed->battlefield->terrainAt(new Position(0, 0))->value);
+        self::assertCount(6, $reconstructed->units);
+        self::assertSame('alpha-1', $reconstructed->units[0]->id);
+        self::assertSame(Archetype::Defender, $reconstructed->units[0]->archetype);
+        self::assertSame(['buff'], $reconstructed->units[0]->abilities);
+        self::assertSame(12, $reconstructed->units[0]->maxHealth);
+        self::assertSame(3, $reconstructed->units[0]->attack);
+        self::assertSame(4, $reconstructed->units[0]->defense);
+        self::assertSame(2, $reconstructed->units[0]->speed);
+        self::assertSame($scenario->victoryCondition, $reconstructed->victoryCondition);
+    }
+
+    public function testItRoundTripsAHoldObjectiveScenario(): void
+    {
+        $scenario = new Scenario(
+            id: 'hold',
+            name: 'Hold',
+            battlefield: new Battlefield(8, 8),
+            units: [
+                new UnitState('alpha-1', 'alpha', new Position(0, 0), 12, 12, 3, 4, 2, 2, false, Archetype::Defender, [], 0, false),
+                new UnitState('alpha-2', 'alpha', new Position(1, 0), 12, 12, 3, 4, 2, 2, false, Archetype::Defender, [], 0, false),
+                new UnitState('alpha-3', 'alpha', new Position(2, 0), 12, 12, 3, 4, 2, 2, false, Archetype::Defender, [], 0, false),
+                new UnitState('bravo-1', 'bravo', new Position(7, 7), 8, 8, 5, 2, 3, 2, false, Archetype::Striker, [], 0, false),
+                new UnitState('bravo-2', 'bravo', new Position(6, 7), 8, 8, 5, 2, 3, 2, false, Archetype::Striker, [], 0, false),
+                new UnitState('bravo-3', 'bravo', new Position(5, 7), 8, 8, 5, 2, 3, 2, false, Archetype::Striker, [], 0, false),
+            ],
+            deploymentZones: [
+                'alpha' => new DeploymentZone('alpha', [new Position(0, 0), new Position(1, 0), new Position(2, 0)]),
+                'bravo' => new DeploymentZone('bravo', [new Position(7, 7), new Position(6, 7), new Position(5, 7)]),
+            ],
+            objectives: ['objective-1' => new ObjectiveMarker('objective-1', new Position(4, 4))],
+            victoryCondition: VictoryCondition::HoldObjective,
+            holdRoundsRequired: 3,
+        );
+
+        $reconstructed = ScenarioSerializer::scenarioFromArray(ScenarioSerializer::scenarioToArray($scenario));
+
+        self::assertSame(VictoryCondition::HoldObjective, $reconstructed->victoryCondition);
+        self::assertSame(3, $reconstructed->holdRoundsRequired);
+        self::assertArrayHasKey('objective-1', $reconstructed->objectives);
+        self::assertSame('4:4', $reconstructed->objectives['objective-1']->position->key());
+    }
+
+    public function testItRoundTripsAMatchState(): void
+    {
+        $scenario = new Scenario(
+            id: 'demo',
+            name: 'Demo',
+            battlefield: new Battlefield(8, 8),
+            units: [
+                new UnitState('alpha-1', 'alpha', new Position(0, 0), 6, 6, 4, 2, 4, 2, false, Archetype::Scout, [], 0, false),
+                new UnitState('alpha-2', 'alpha', new Position(1, 0), 6, 6, 4, 2, 4, 2, false, Archetype::Scout, [], 0, false),
+                new UnitState('alpha-3', 'alpha', new Position(2, 0), 6, 6, 4, 2, 4, 2, false, Archetype::Scout, [], 0, false),
+                new UnitState('bravo-1', 'bravo', new Position(7, 7), 6, 6, 4, 2, 4, 2, false, Archetype::Scout, [], 0, false),
+                new UnitState('bravo-2', 'bravo', new Position(6, 7), 6, 6, 4, 2, 4, 2, false, Archetype::Scout, [], 0, false),
+                new UnitState('bravo-3', 'bravo', new Position(5, 7), 6, 6, 4, 2, 4, 2, false, Archetype::Scout, [], 0, false),
+            ],
+            deploymentZones: [
+                'alpha' => new DeploymentZone('alpha', [new Position(0, 0), new Position(1, 0), new Position(2, 0)]),
+                'bravo' => new DeploymentZone('bravo', [new Position(7, 7), new Position(6, 7), new Position(5, 7)]),
+            ],
+            objectives: [],
+            victoryCondition: VictoryCondition::EliminateAll,
+            holdRoundsRequired: 1,
+        );
+        $match = $scenario->startMatch('alpha');
+
+        $reconstructed = ScenarioSerializer::matchFromArray(ScenarioSerializer::matchToArray($match));
+
+        self::assertSame('alpha', $reconstructed->activeTeamId);
+        self::assertSame(1, $reconstructed->round);
+        self::assertCount(6, $reconstructed->units);
+        self::assertSame(2, $reconstructed->units[0]->actionsRemaining);
+        self::assertFalse($reconstructed->units[0]->hasAttacked);
+        self::assertSame(0, $reconstructed->units[0]->attackBonus);
+    }
+
+    public function testItRejectsShapeErrors(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+
+        ScenarioSerializer::scenarioFromArray([
+            'id' => 'demo',
+            // missing 'name', 'battlefield', 'units', etc.
+        ]);
+    }
+}

tests/Unit/Domain/AbilityCatalogTest.php

@@ -0,0 +1,59 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Unit\Domain;
+
+use BattleForge\Domain\AbilityCatalog;
+use BattleForge\Domain\AbilityDefinition;
+use BattleForge\Domain\AbilityId;
+use PHPUnit\Framework\TestCase;
+
+final class AbilityCatalogTest extends TestCase
+{
+    public function testItExposesExactlyTheThreePlannedAbilities(): void
+    {
+        $keys = array_keys(AbilityCatalog::definitions());
+
+        sort($keys);
+
+        self::assertSame(['area_damage', 'buff', 'heal'], $keys);
+    }
+
+    public function testHealTargetsAnAllyWithinRangeAndRestoresHealth(): void
+    {
+        $definition = AbilityCatalog::definitions()[AbilityId::Heal->value];
+
+        self::assertInstanceOf(AbilityDefinition::class, $definition);
+        self::assertSame('Heal', $definition->label);
+        self::assertSame(2, $definition->range);
+        self::assertSame(0, $definition->areaRadius);
+        self::assertSame('ally', $definition->target);
+        self::assertSame('restore_health', $definition->effect);
+        self::assertSame(5, $definition->effectValue);
+    }
+
+    public function testAreaDamageTargetsAnEnemyTileAndAffectsANeighborhood(): void
+    {
+        $definition = AbilityCatalog::definitions()[AbilityId::AreaDamage->value];
+
+        self::assertSame('Area Damage', $definition->label);
+        self::assertSame(3, $definition->range);
+        self::assertSame(1, $definition->areaRadius);
+        self::assertSame('tile', $definition->target);
+        self::assertSame('deal_damage', $definition->effect);
+        self::assertSame(3, $definition->effectValue);
+    }
+
+    public function testBuffTargetsAnAllyAndAppliesAnAttackBonus(): void
+    {
+        $definition = AbilityCatalog::definitions()[AbilityId::Buff->value];
+
+        self::assertSame('Rally', $definition->label);
+        self::assertSame(1, $definition->range);
+        self::assertSame(0, $definition->areaRadius);
+        self::assertSame('ally', $definition->target);
+        self::assertSame('apply_buff', $definition->effect);
+        self::assertSame(2, $definition->effectValue);
+    }
+}

tests/Unit/Domain/ArchetypeCatalogTest.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Unit\Domain;
+
+use BattleForge\Domain\Archetype;
+use BattleForge\Domain\ArchetypeCatalog;
+use BattleForge\Domain\ArchetypeTemplate;
+use PHPUnit\Framework\TestCase;
+
+final class ArchetypeCatalogTest extends TestCase
+{
+    public function testItExposesExactlyTheFourPlannedArchetypes(): void
+    {
+        $keys = array_keys(ArchetypeCatalog::templates());
+
+        sort($keys);
+
+        self::assertSame(['defender', 'scout', 'striker', 'support'], $keys);
+    }
+
+    public function testEveryArchetypeTemplateCarriesAllFourStatRanges(): void
+    {
+        foreach (ArchetypeCatalog::templates() as $key => $template) {
+            self::assertInstanceOf(ArchetypeTemplate::class, $template);
+            self::assertLessThanOrEqual($template->maxHealth, $template->minHealth);
+            self::assertLessThanOrEqual($template->maxAttack, $template->minAttack);
+            self::assertLessThanOrEqual($template->maxDefense, $template->minDefense);
+            self::assertLessThanOrEqual($template->maxSpeed, $template->minSpeed);
+            self::assertGreaterThanOrEqual(1, $template->minSpeed);
+        }
+    }
+
+    public function testEveryArchetypeTemplateDefaultsToTheCenterOfItsRanges(): void
+    {
+        foreach (ArchetypeCatalog::templates() as $template) {
+            $defaults = $template->defaultStats();
+
+            self::assertSame((int) ceil(($template->minHealth + $template->maxHealth) / 2), $defaults['maxHealth']);
+            self::assertSame((int) ceil(($template->minAttack + $template->maxAttack) / 2), $defaults['attack']);
+            self::assertSame((int) ceil(($template->minDefense + $template->maxDefense) / 2), $defaults['defense']);
+            self::assertSame((int) ceil(($template->minSpeed + $template->maxSpeed) / 2), $defaults['speed']);
+        }
+    }
+
+    public function testDefaultStatsReturnAllFourKeys(): void
+    {
+        $template = ArchetypeCatalog::templates()[Archetype::Defender->value];
+
+        self::assertSame(
+            ['maxHealth', 'attack', 'defense', 'speed'],
+            array_keys($template->defaultStats()),
+        );
+    }
+}

tests/Unit/Domain/ArchetypeTemplateTest.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Unit\Domain;
+
+use BattleForge\Domain\ArchetypeTemplate;
+use PHPUnit\Framework\TestCase;
+
+final class ArchetypeTemplateTest extends TestCase
+{
+    public function testItRejectsInvertedStatRanges(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+
+        new ArchetypeTemplate(
+            minHealth: 10,
+            maxHealth: 5,
+            minAttack: 1,
+            maxAttack: 3,
+            minDefense: 0,
+            maxDefense: 2,
+            minSpeed: 1,
+            maxSpeed: 4,
+            allowedAbilities: [],
+        );
+    }
+
+    public function testItRejectsZeroMinimumSpeed(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+
+        new ArchetypeTemplate(
+            minHealth: 5,
+            maxHealth: 10,
+            minAttack: 1,
+            maxAttack: 3,
+            minDefense: 0,
+            maxDefense: 2,
+            minSpeed: 0,
+            maxSpeed: 4,
+            allowedAbilities: [],
+        );
+    }
+
+    public function testItExposesAllowedAbilitiesVerbatim(): void
+    {
+        $template = new ArchetypeTemplate(
+            minHealth: 5,
+            maxHealth: 10,
+            minAttack: 1,
+            maxAttack: 3,
+            minDefense: 0,
+            maxDefense: 2,
+            minSpeed: 1,
+            maxSpeed: 4,
+            allowedAbilities: ['heal', 'buff'],
+        );
+
+        self::assertSame(['heal', 'buff'], $template->allowedAbilities);
+    }
+}

tests/Unit/Domain/BattlefieldTest.php

@@ -0,0 +1,121 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Unit\Domain;
+
+use BattleForge\Domain\Battlefield;
+use BattleForge\Domain\Position;
+use BattleForge\Domain\Terrain;
+use InvalidArgumentException;
+use PHPUnit\Framework\TestCase;
+
+final class BattlefieldTest extends TestCase
+{
+    public function testItRejectsDimensionsOutsideTheSupportedRange(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        new Battlefield(7, 16);
+    }
+
+    public function testItAcceptsMinimumAndMaximumDimensions(): void
+    {
+        $minimum = new Battlefield(8, 8);
+        $maximum = new Battlefield(16, 16);
+
+        self::assertSame([8, 8], [$minimum->width, $minimum->height]);
+        self::assertSame([16, 16], [$maximum->width, $maximum->height]);
+    }
+
+    public function testItRejectsDimensionsAboveTheSupportedRange(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        new Battlefield(16, 17);
+    }
+
+    public function testItRejectsNonCanonicalTerrainCoordinates(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        new Battlefield(8, 8, ['01:0' => Terrain::Forest]);
+    }
+
+    public function testItRejectsMalformedTerrainCoordinates(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        new Battlefield(8, 8, ['not-a-coordinate' => Terrain::Forest]);
+    }
+
+    public function testItRejectsInvalidTerrainValues(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        // @phpstan-ignore argument.type
+        new Battlefield(8, 8, ['0:0' => 'forest']);
+    }
+
+    public function testReachableRejectsAStartOutsideTheBattlefield(): void
+    {
+        $battlefield = new Battlefield(8, 8);
+
+        $this->expectException(InvalidArgumentException::class);
+
+        $battlefield->reachable(new Position(-1, 0), 2, []);
+    }
+
+    public function testReachableRejectsANegativeBudget(): void
+    {
+        $battlefield = new Battlefield(8, 8);
+
+        $this->expectException(InvalidArgumentException::class);
+
+        $battlefield->reachable(new Position(0, 0), -1, []);
+    }
+
+    public function testReachableRejectsOccupiedPositionsOutsideTheBattlefield(): void
+    {
+        $battlefield = new Battlefield(8, 8);
+
+        $this->expectException(InvalidArgumentException::class);
+
+        $battlefield->reachable(new Position(0, 0), 2, [new Position(8, 0)]);
+    }
+
+    public function testItFindsReachableTilesUsingTerrainCostsAndObstacles(): void
+    {
+        $battlefield = new Battlefield(8, 8, [
+            '1:0' => Terrain::Forest,
+            '0:1' => Terrain::Rough,
+            '2:0' => Terrain::Water,
+            '1:1' => Terrain::Blocking,
+        ]);
+
+        $reachable = $battlefield->reachable(
+            new Position(0, 0),
+            2,
+            [new Position(0, 2)],
+        );
+
+        self::assertSame([
+            '0:0' => 0,
+            '1:0' => 2,
+            '0:1' => 2,
+        ], $reachable);
+    }
+
+    public function testReachableReplacesAHighCostRouteWithALowerCostDetour(): void
+    {
+        $battlefield = new Battlefield(8, 8, [
+            '1:0' => Terrain::Forest,
+            '2:0' => Terrain::Forest,
+            '3:0' => Terrain::Forest,
+        ]);
+
+        $reachable = $battlefield->reachable(new Position(0, 0), 7, []);
+
+        self::assertSame(6, $reachable['4:0']);
+    }
+}

tests/Unit/Domain/MatchStateTest.php

@@ -0,0 +1,252 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Unit\Domain;
+
+use BattleForge\Domain\Battlefield;
+use BattleForge\Domain\MatchState;
+use BattleForge\Domain\Position;
+use BattleForge\Domain\Terrain;
+use BattleForge\Domain\UnitState;
+use InvalidArgumentException;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+
+final class MatchStateTest extends TestCase
+{
+    public function testItRejectsDuplicateUnitIds(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        new MatchState(
+            new Battlefield(8, 8),
+            [$this->unit('unit-1', 'alpha'), $this->unit('unit-1', 'bravo')],
+            'alpha',
+        );
+    }
+
+    public function testItRejectsAUnitOutsideTheBattlefield(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Unit alpha-1 is outside the battlefield.');
+
+        new MatchState(
+            new Battlefield(8, 8),
+            [$this->unit('alpha-1', 'alpha', new Position(8, 0))],
+            'alpha',
+        );
+    }
+
+    #[DataProvider('impassableTerrainProvider')]
+    public function testItRejectsALivingUnitOnImpassableTerrain(Terrain $terrain): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Living unit alpha-1 must stand on passable terrain.');
+
+        new MatchState(
+            new Battlefield(8, 8, ['0:0' => $terrain]),
+            [$this->unit('alpha-1', 'alpha')],
+            'alpha',
+        );
+    }
+
+    /**
+     * @return iterable<string, array{Terrain}>
+     */
+    public static function impassableTerrainProvider(): iterable
+    {
+        yield 'water' => [Terrain::Water];
+        yield 'blocking' => [Terrain::Blocking];
+    }
+
+    public function testItRejectsLivingUnitsAtTheSamePosition(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Living units cannot share position 0:0.');
+
+        new MatchState(
+            new Battlefield(8, 8),
+            [$this->unit('alpha-1', 'alpha'), $this->unit('bravo-1', 'bravo')],
+            'alpha',
+        );
+    }
+
+    public function testItAcceptsLivingAndDefeatedUnitsAtTheSamePosition(): void
+    {
+        $match = new MatchState(
+            new Battlefield(8, 8),
+            [
+                $this->unit('alpha-1', 'alpha'),
+                $this->unit('bravo-1', 'bravo', health: 0),
+            ],
+            'alpha',
+        );
+
+        self::assertSame('0:0', $match->unit('alpha-1')->position->key());
+        self::assertSame('0:0', $match->unit('bravo-1')->position->key());
+    }
+
+    public function testItRejectsAnUnknownUnitLookup(): void
+    {
+        $match = $this->match();
+
+        $this->expectException(InvalidArgumentException::class);
+        $match->unit('unknown');
+    }
+
+    public function testItRejectsAnUnknownReplacement(): void
+    {
+        $match = $this->match();
+
+        $this->expectException(InvalidArgumentException::class);
+        $match->withUnit($this->unit('unknown', 'alpha'));
+    }
+
+    public function testReplacingAUnitDoesNotMutateTheMatch(): void
+    {
+        $match = $this->match();
+        $replacement = $match->unit('alpha-1')->moveTo(new Position(2, 0));
+        $replaced = $match->withUnit($replacement);
+
+        self::assertSame('0:0', $match->unit('alpha-1')->position->key());
+        self::assertSame('2:0', $replaced->unit('alpha-1')->position->key());
+    }
+
+    public function testCopyReplacesMutableMatchProgressIncludingAnEmptyLog(): void
+    {
+        $match = $this->match(actionLog: ['started']);
+        $copied = $match->copy(activeTeamId: 'bravo', round: 2, actionLog: []);
+
+        self::assertSame('alpha', $match->activeTeamId);
+        self::assertSame(1, $match->round);
+        self::assertSame(['started'], $match->actionLog);
+        self::assertSame('bravo', $copied->activeTeamId);
+        self::assertSame(2, $copied->round);
+        self::assertSame([], $copied->actionLog);
+    }
+
+    public function testWinnerCanBeSetAndClearedWithoutChangingOtherState(): void
+    {
+        $match = $this->match(actionLog: ['started']);
+        $won = $match->withWinner('alpha');
+        $cleared = $won->withWinner(null);
+
+        self::assertSame('alpha', $won->winnerTeamId);
+        self::assertNull($cleared->winnerTeamId);
+        self::assertSame($match->battlefield, $cleared->battlefield);
+        self::assertSame($match->units, $cleared->units);
+        self::assertSame($match->activeTeamId, $cleared->activeTeamId);
+        self::assertSame($match->round, $cleared->round);
+        self::assertSame($match->actionLog, $cleared->actionLog);
+    }
+
+    public function testItRejectsANonListUnitsArray(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        // @phpstan-ignore argument.type
+        new MatchState(new Battlefield(8, 8), ['first' => $this->unit('alpha-1', 'alpha')], 'alpha');
+    }
+
+    public function testItRejectsAnEmptyUnitsArray(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        new MatchState(new Battlefield(8, 8), [], 'alpha');
+    }
+
+    public function testItRejectsANonUnitMember(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        // @phpstan-ignore argument.type
+        new MatchState(new Battlefield(8, 8), ['not-a-unit'], 'alpha');
+    }
+
+    public function testItRejectsAnEmptyActiveTeam(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        new MatchState(new Battlefield(8, 8), [$this->unit('alpha-1', 'alpha')], '');
+    }
+
+    public function testItRejectsAnActiveTeamWithoutAUnit(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        new MatchState(new Battlefield(8, 8), [$this->unit('alpha-1', 'alpha')], 'bravo');
+    }
+
+    public function testItRejectsARoundBelowOne(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        new MatchState(new Battlefield(8, 8), [$this->unit('alpha-1', 'alpha')], 'alpha', 0);
+    }
+
+    public function testItRejectsANonListActionLog(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        new MatchState(
+            new Battlefield(8, 8),
+            [$this->unit('alpha-1', 'alpha')],
+            'alpha',
+            // @phpstan-ignore argument.type
+            actionLog: ['first' => 'started'],
+        );
+    }
+
+    public function testItRejectsANonStringActionLogEntry(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        // @phpstan-ignore argument.type
+        new MatchState(new Battlefield(8, 8), [$this->unit('alpha-1', 'alpha')], 'alpha', actionLog: [1]);
+    }
+
+    public function testItRejectsAnEmptyWinnerTeam(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        new MatchState(new Battlefield(8, 8), [$this->unit('alpha-1', 'alpha')], 'alpha', winnerTeamId: '');
+    }
+
+    public function testItRejectsAWinnerWithoutAUnit(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        new MatchState(
+            new Battlefield(8, 8),
+            [$this->unit('alpha-1', 'alpha')],
+            'alpha',
+            winnerTeamId: 'bravo',
+        );
+    }
+
+    /**
+     * @param list<string> $actionLog
+     */
+    private function match(array $actionLog = []): MatchState
+    {
+        return new MatchState(
+            new Battlefield(8, 8),
+            [
+                $this->unit('alpha-1', 'alpha'),
+                $this->unit('bravo-1', 'bravo', new Position(7, 7)),
+            ],
+            'alpha',
+            actionLog: $actionLog,
+        );
+    }
+
+    private function unit(
+        string $id,
+        string $teamId,
+        ?Position $position = null,
+        int $health = 10,
+    ): UnitState {
+        return new UnitState($id, $teamId, $position ?? new Position(0, 0), 10, $health, 4, 2, 4, 2);
+    }
+}

tests/Unit/Domain/ScenarioTest.php

@@ -0,0 +1,280 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Unit\Domain;
+
+use BattleForge\Domain\Archetype;
+use BattleForge\Domain\Battlefield;
+use BattleForge\Domain\CombatEngine;
+use BattleForge\Domain\DeploymentZone;
+use BattleForge\Domain\MatchState;
+use BattleForge\Domain\ObjectiveMarker;
+use BattleForge\Domain\Position;
+use BattleForge\Domain\Scenario;
+use BattleForge\Domain\UnitState;
+use BattleForge\Domain\VictoryCondition;
+use InvalidArgumentException;
+use PHPUnit\Framework\TestCase;
+
+final class ScenarioTest extends TestCase
+{
+    public function testItRejectsNonListUnits(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        new Scenario(
+            id: 'demo',
+            name: 'Demo',
+            battlefield: new Battlefield(8, 8),
+            units: ['alpha-1' => $this->unit('alpha-1', 'alpha', new Position(0, 0))], // @phpstan-ignore argument.type (Test fixture intentionally passes a non-list units array to verify constructor validation.)
+            deploymentZones: ['alpha' => new DeploymentZone('alpha', [new Position(0, 0)])],
+            objectives: [],
+            victoryCondition: VictoryCondition::EliminateAll,
+            holdRoundsRequired: 1,
+        );
+    }
+
+    public function testItRejectsTeamsOutsideTheThreeToSixSizeWindow(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Team alpha must have between 3 and 6 units.');
+
+        $units = [
+            $this->unit('alpha-1', 'alpha', new Position(0, 0)),
+            $this->unit('alpha-2', 'alpha', new Position(1, 0)),
+            $this->unit('bravo-1', 'bravo', new Position(7, 7)),
+            $this->unit('bravo-2', 'bravo', new Position(6, 7)),
+            $this->unit('bravo-3', 'bravo', new Position(5, 7)),
+        ];
+
+        new Scenario(
+            id: 'demo',
+            name: 'Demo',
+            battlefield: new Battlefield(8, 8),
+            units: $units,
+            deploymentZones: [
+                'alpha' => new DeploymentZone('alpha', [new Position(0, 0), new Position(1, 0)]),
+                'bravo' => new DeploymentZone('bravo', [new Position(7, 7), new Position(6, 7), new Position(5, 7)]),
+            ],
+            objectives: [],
+            victoryCondition: VictoryCondition::EliminateAll,
+            holdRoundsRequired: 1,
+        );
+    }
+
+    public function testItRejectsAbilitiesOutsideTheArchetypeAllowlist(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Unit alpha-1 has an ability that its archetype forbids.');
+
+        $bad = $this->unit('alpha-1', 'alpha', new Position(0, 0), archetype: Archetype::Scout, abilities: ['heal'], attack: 3, defense: 1, speed: 5, maxHealth: 6);
+        $alpha2 = $this->unit('alpha-2', 'alpha', new Position(1, 0));
+        $alpha3 = $this->unit('alpha-3', 'alpha', new Position(2, 0));
+        $bravo = $this->unit('bravo-1', 'bravo', new Position(7, 7));
+        $bravo2 = $this->unit('bravo-2', 'bravo', new Position(6, 7));
+        $bravo3 = $this->unit('bravo-3', 'bravo', new Position(5, 7));
+
+        new Scenario(
+            id: 'demo',
+            name: 'Demo',
+            battlefield: new Battlefield(8, 8),
+            units: [$bad, $alpha2, $alpha3, $bravo, $bravo2, $bravo3],
+            deploymentZones: [
+                'alpha' => new DeploymentZone('alpha', [new Position(0, 0), new Position(1, 0), new Position(2, 0)]),
+                'bravo' => new DeploymentZone('bravo', [new Position(7, 7), new Position(6, 7), new Position(5, 7)]),
+            ],
+            objectives: [],
+            victoryCondition: VictoryCondition::EliminateAll,
+            holdRoundsRequired: 1,
+        );
+    }
+
+    public function testItRejectsUnitsOutsideTheirDeploymentZone(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Unit alpha-1 must start inside team alpha deployment zone.');
+
+        $bad = $this->unit('alpha-1', 'alpha', new Position(3, 0));
+        $alpha2 = $this->unit('alpha-2', 'alpha', new Position(0, 0));
+        $alpha3 = $this->unit('alpha-3', 'alpha', new Position(1, 0));
+        $bravo = $this->unit('bravo-1', 'bravo', new Position(7, 7));
+        $bravo2 = $this->unit('bravo-2', 'bravo', new Position(6, 7));
+        $bravo3 = $this->unit('bravo-3', 'bravo', new Position(5, 7));
+
+        new Scenario(
+            id: 'demo',
+            name: 'Demo',
+            battlefield: new Battlefield(8, 8),
+            units: [$bad, $alpha2, $alpha3, $bravo, $bravo2, $bravo3],
+            deploymentZones: [
+                'alpha' => new DeploymentZone('alpha', [new Position(0, 0), new Position(1, 0), new Position(2, 0)]),
+                'bravo' => new DeploymentZone('bravo', [new Position(7, 7), new Position(6, 7), new Position(5, 7)]),
+            ],
+            objectives: [],
+            victoryCondition: VictoryCondition::EliminateAll,
+            holdRoundsRequired: 1,
+        );
+    }
+
+    public function testHoldObjectiveRequiresExactlyOneObjective(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Hold objective victory requires exactly one objective.');
+
+        $units = $this->validUnitSet();
+        $zones = $this->validZones();
+
+        new Scenario(
+            id: 'demo',
+            name: 'Demo',
+            battlefield: new Battlefield(8, 8),
+            units: $units,
+            deploymentZones: $zones,
+            objectives: [],
+            victoryCondition: VictoryCondition::HoldObjective,
+            holdRoundsRequired: 3,
+        );
+    }
+
+    public function testStartMatchReturnsAFreshMatchStateWithResetUnits(): void
+    {
+        $scenario = $this->validScenario();
+
+        $match = $scenario->startMatch('alpha');
+
+        self::assertInstanceOf(MatchState::class, $match);
+        self::assertSame('alpha', $match->activeTeamId);
+        self::assertSame(1, $match->round);
+        self::assertNull($match->winnerTeamId);
+        foreach ($match->units as $unit) {
+            self::assertSame(2, $unit->actionsRemaining);
+            self::assertFalse($unit->hasAttacked);
+            self::assertSame(0, $unit->attackBonus);
+            self::assertFalse($unit->hasUsedAbility);
+        }
+    }
+
+    public function testStartMatchDoesNotShareUnitInstancesWithTheScenario(): void
+    {
+        $scenario = $this->validScenario();
+
+        $match = $scenario->startMatch('alpha');
+
+        $original = $scenario->units[0];
+        $fromMatch = $match->unit($original->id);
+
+        self::assertNotSame($original, $fromMatch);
+        self::assertSame($original->id, $fromMatch->id);
+    }
+
+    public function testStartingAMatchWithAbilityAndObjectivePlaysThrough(): void
+    {
+        $units = [
+            new UnitState('alpha-1', 'alpha', new Position(0, 0), 10, 10, 4, 2, 4, 2, false, Archetype::Striker, ['area_damage']),
+            new UnitState('alpha-2', 'alpha', new Position(1, 0), 9, 9, 3, 2, 4, 2, false, Archetype::Support, ['heal', 'buff']),
+            new UnitState('alpha-3', 'alpha', new Position(2, 0), 10, 10, 4, 3, 3, 2, false, Archetype::Defender),
+            new UnitState('bravo-1', 'bravo', new Position(7, 7), 7, 7, 4, 2, 5, 2, false, Archetype::Scout),
+            new UnitState('bravo-2', 'bravo', new Position(6, 7), 10, 10, 4, 2, 4, 2, false, Archetype::Striker),
+            new UnitState('bravo-3', 'bravo', new Position(5, 7), 10, 10, 4, 3, 3, 2, false, Archetype::Defender),
+        ];
+        $scenario = new Scenario(
+            id: 'demo',
+            name: 'Demo',
+            battlefield: new Battlefield(8, 8),
+            units: $units,
+            deploymentZones: [
+                'alpha' => new DeploymentZone('alpha', [new Position(0, 0), new Position(1, 0), new Position(2, 0)]),
+                'bravo' => new DeploymentZone('bravo', [new Position(7, 7), new Position(6, 7), new Position(5, 7)]),
+            ],
+            objectives: ['objective-1' => new ObjectiveMarker('objective-1', new Position(0, 0))],
+            victoryCondition: VictoryCondition::HoldObjective,
+            holdRoundsRequired: 2,
+        );
+
+        $match = $scenario->startMatch('alpha');
+        $engine = new CombatEngine();
+        $end1 = $engine->endTurn($match);
+        $end2 = $engine->endTurn($end1);
+
+        self::assertSame('alpha', $end2->activeTeamId);
+        self::assertSame(['alpha' => 1], $end2->objectiveControl);
+        self::assertNull($end2->winnerTeamId);
+    }
+
+    /** @return list<UnitState> */
+    private function validUnitSet(): array
+    {
+        return [
+            $this->unit('alpha-1', 'alpha', new Position(0, 0)),
+            $this->unit('alpha-2', 'alpha', new Position(1, 0)),
+            $this->unit('alpha-3', 'alpha', new Position(2, 0)),
+            $this->unit('bravo-1', 'bravo', new Position(7, 7)),
+            $this->unit('bravo-2', 'bravo', new Position(6, 7)),
+            $this->unit('bravo-3', 'bravo', new Position(5, 7)),
+        ];
+    }
+
+    /** @return array<string, DeploymentZone> */
+    private function validZones(): array
+    {
+        return [
+            'alpha' => new DeploymentZone('alpha', [
+                new Position(0, 0),
+                new Position(1, 0),
+                new Position(2, 0),
+            ]),
+            'bravo' => new DeploymentZone('bravo', [
+                new Position(7, 7),
+                new Position(6, 7),
+                new Position(5, 7),
+            ]),
+        ];
+    }
+
+    private function validScenario(): Scenario
+    {
+        return new Scenario(
+            id: 'demo',
+            name: 'Demo',
+            battlefield: new Battlefield(8, 8),
+            units: $this->validUnitSet(),
+            deploymentZones: $this->validZones(),
+            objectives: [],
+            victoryCondition: VictoryCondition::EliminateAll,
+            holdRoundsRequired: 1,
+        );
+    }
+
+    /**
+     * @param list<string> $abilities
+     */
+    private function unit(
+        string $id,
+        string $team,
+        Position $position,
+        Archetype $archetype = Archetype::Defender,
+        array $abilities = [],
+        int $attack = 4,
+        int $defense = 3,
+        int $speed = 3,
+        int $maxHealth = 10,
+    ): UnitState {
+        return new UnitState(
+            $id,
+            $team,
+            $position,
+            $maxHealth,
+            $maxHealth,
+            $attack,
+            $defense,
+            $speed,
+            2,
+            false,
+            $archetype,
+            $abilities,
+            0,
+            false,
+        );
+    }
+}

tests/Unit/Domain/ScenarioValidatorTest.php

@@ -0,0 +1,162 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Unit\Domain;
+
+use BattleForge\Domain\Archetype;
+use BattleForge\Domain\Battlefield;
+use BattleForge\Domain\DeploymentZone;
+use BattleForge\Domain\ObjectiveMarker;
+use BattleForge\Domain\Position;
+use BattleForge\Domain\Scenario;
+use BattleForge\Domain\ScenarioValidator;
+use BattleForge\Domain\Terrain;
+use BattleForge\Domain\UnitState;
+use BattleForge\Domain\VictoryCondition;
+use PHPUnit\Framework\TestCase;
+
+final class ScenarioValidatorTest extends TestCase
+{
+    public function testItReturnsAnEmptyListForAValidScenario(): void
+    {
+        $scenario = $this->validScenario();
+
+        self::assertSame([], ScenarioValidator::validate($scenario));
+    }
+
+    public function testItRejectsAnObjectiveOnImpassableTerrain(): void
+    {
+        $scenario = $this->validScenario(
+            terrain: ['4:4' => Terrain::Water],
+            objectivePosition: new Position(4, 4),
+        );
+
+        $errors = ScenarioValidator::validate($scenario);
+
+        self::assertNotEmpty($errors);
+        self::assertTrue((bool) array_filter($errors, static fn (string $error): bool => str_contains($error, 'impassable')));
+    }
+
+    public function testItRejectsAnObjectiveUnreachableFromAnyDeploymentZone(): void
+    {
+        $scenario = $this->validScenario(
+            terrain: [
+                '3:4' => Terrain::Blocking,
+                '4:3' => Terrain::Blocking,
+                '5:4' => Terrain::Blocking,
+                '4:5' => Terrain::Blocking,
+            ],
+            objectivePosition: new Position(4, 4),
+        );
+
+        $errors = ScenarioValidator::validate($scenario);
+
+        self::assertTrue((bool) array_filter($errors, static fn (string $error): bool => str_contains($error, 'unreachable')));
+    }
+
+    public function testItRejectsOverlappingDeploymentZones(): void
+    {
+        $units = $this->unitSet();
+        $battlefield = new Battlefield(8, 8);
+        $scenario = new Scenario(
+            id: 'demo',
+            name: 'Demo',
+            battlefield: $battlefield,
+            units: $units,
+            deploymentZones: [
+                'alpha' => new DeploymentZone('alpha', [new Position(0, 0), new Position(1, 0), new Position(2, 0)]),
+                'bravo' => new DeploymentZone('bravo', [new Position(1, 0), new Position(2, 0), new Position(7, 7), new Position(6, 7), new Position(5, 7)]),
+            ],
+            objectives: [],
+            victoryCondition: VictoryCondition::EliminateAll,
+            holdRoundsRequired: 1,
+        );
+
+        $errors = ScenarioValidator::validate($scenario);
+
+        self::assertTrue((bool) array_filter($errors, static fn (string $error): bool => str_contains($error, 'overlap')));
+    }
+
+    public function testItRejectsDeploymentPositionsOnImpassableTerrain(): void
+    {
+        $units = $this->unitSet();
+        $battlefield = new Battlefield(8, 8, ['0:0' => Terrain::Water]);
+        $scenario = new Scenario(
+            id: 'demo',
+            name: 'Demo',
+            battlefield: $battlefield,
+            units: $units,
+            deploymentZones: [
+                'alpha' => new DeploymentZone('alpha', [new Position(0, 0), new Position(1, 0), new Position(2, 0)]),
+                'bravo' => new DeploymentZone('bravo', [new Position(7, 7), new Position(6, 7), new Position(5, 7)]),
+            ],
+            objectives: [],
+            victoryCondition: VictoryCondition::EliminateAll,
+            holdRoundsRequired: 1,
+        );
+
+        $errors = ScenarioValidator::validate($scenario);
+
+        self::assertTrue((bool) array_filter($errors, static fn (string $error): bool => str_contains($error, 'impassable')));
+    }
+
+    /**
+     * @param array<string, Terrain> $terrain
+     */
+    private function validScenario(
+        array $terrain = [],
+        ?Position $objectivePosition = null,
+    ): Scenario {
+        $units = $this->unitSet();
+        $battlefield = new Battlefield(8, 8, $terrain);
+        $objectives = [];
+
+        if ($objectivePosition !== null) {
+            $objectives = ['objective-1' => new ObjectiveMarker('objective-1', $objectivePosition)];
+        }
+
+        return new Scenario(
+            id: 'demo',
+            name: 'Demo',
+            battlefield: $battlefield,
+            units: $units,
+            deploymentZones: $this->zones(),
+            objectives: $objectives,
+            victoryCondition: $objectivePosition === null
+                ? VictoryCondition::EliminateAll
+                : VictoryCondition::HoldObjective,
+            holdRoundsRequired: 1,
+        );
+    }
+
+    /** @return array<string, DeploymentZone> */
+    private function zones(): array
+    {
+        return [
+            'alpha' => new DeploymentZone('alpha', [
+                new Position(0, 0),
+                new Position(1, 0),
+                new Position(2, 0),
+            ]),
+            'bravo' => new DeploymentZone('bravo', [
+                new Position(7, 7),
+                new Position(6, 7),
+                new Position(5, 7),
+            ]),
+        ];
+    }
+
+    /** @return list<UnitState> */
+    private function unitSet(): array
+    {
+        return [
+            new UnitState('alpha-1', 'alpha', new Position(0, 0), 10, 10, 4, 3, 2, 2, false, Archetype::Defender),
+            new UnitState('alpha-2', 'alpha', new Position(1, 0), 8, 8, 5, 2, 3, 2, false, Archetype::Striker),
+            new UnitState('alpha-3', 'alpha', new Position(2, 0), 7, 7, 2, 2, 3, 2, false, Archetype::Support),
+            new UnitState('bravo-1', 'bravo', new Position(7, 7), 10, 10, 4, 3, 2, 2, false, Archetype::Defender),
+            new UnitState('bravo-2', 'bravo', new Position(6, 7), 8, 8, 5, 2, 3, 2, false, Archetype::Striker),
+            new UnitState('bravo-3', 'bravo', new Position(5, 7), 6, 6, 3, 1, 5, 2, false, Archetype::Scout),
+        ];
+    }
+}

tests/Unit/Domain/UnitStateTest.php

@@ -0,0 +1,256 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Unit\Domain;
+
+use BattleForge\Domain\Position;
+use BattleForge\Domain\UnitState;
+use InvalidArgumentException;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+
+final class UnitStateTest extends TestCase
+{
+    /**
+     * @param callable(): UnitState $createUnit
+     */
+    #[DataProvider('invalidUnitProvider')]
+    public function testItRejectsInvalidConstructorArguments(callable $createUnit): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        $createUnit();
+    }
+
+    /**
+     * @return iterable<string, array{callable(): UnitState}>
+     */
+    public static function invalidUnitProvider(): iterable
+    {
+        yield 'empty unit id' => [
+            static fn (): UnitState => new UnitState('', 'alpha', new Position(0, 0), 10, 10, 4, 2, 4, 2),
+        ];
+        yield 'empty team id' => [
+            static fn (): UnitState => new UnitState('unit-1', '', new Position(0, 0), 10, 10, 4, 2, 4, 2),
+        ];
+        yield 'zero maximum health' => [
+            static fn (): UnitState => new UnitState('unit-1', 'alpha', new Position(0, 0), 0, 0, 4, 2, 4, 2),
+        ];
+        yield 'negative health' => [
+            static fn (): UnitState => new UnitState('unit-1', 'alpha', new Position(0, 0), 10, -1, 4, 2, 4, 2),
+        ];
+        yield 'health above maximum' => [
+            static fn (): UnitState => new UnitState('unit-1', 'alpha', new Position(0, 0), 10, 11, 4, 2, 4, 2),
+        ];
+        yield 'negative attack' => [
+            static fn (): UnitState => new UnitState('unit-1', 'alpha', new Position(0, 0), 10, 10, -1, 2, 4, 2),
+        ];
+        yield 'negative defense' => [
+            static fn (): UnitState => new UnitState('unit-1', 'alpha', new Position(0, 0), 10, 10, 4, -1, 4, 2),
+        ];
+        yield 'zero speed' => [
+            static fn (): UnitState => new UnitState('unit-1', 'alpha', new Position(0, 0), 10, 10, 4, 2, 0, 2),
+        ];
+        yield 'negative actions remaining' => [
+            static fn (): UnitState => new UnitState('unit-1', 'alpha', new Position(0, 0), 10, 10, 4, 2, 4, -1),
+        ];
+        yield 'too many actions remaining' => [
+            static fn (): UnitState => new UnitState('unit-1', 'alpha', new Position(0, 0), 10, 10, 4, 2, 4, 3),
+        ];
+    }
+
+    public function testItReportsWhetherItIsDefeated(): void
+    {
+        self::assertTrue($this->unit(health: 0)->isDefeated());
+        self::assertFalse($this->unit(health: 1)->isDefeated());
+    }
+
+    public function testMovingReturnsAChangedCopy(): void
+    {
+        $unit = $this->unit();
+        $moved = $unit->moveTo(new Position(2, 3));
+
+        self::assertNotSame($unit, $moved);
+        self::assertSame('0:0', $unit->position->key());
+        self::assertSame('2:3', $moved->position->key());
+    }
+
+    public function testSpendingAnActionReturnsAChangedCopyAndRejectsExhaustedUnits(): void
+    {
+        $unit = $this->unit(actionsRemaining: 1);
+        $spent = $unit->spendAction();
+
+        self::assertSame(1, $unit->actionsRemaining);
+        self::assertSame(0, $spent->actionsRemaining);
+
+        $this->expectException(InvalidArgumentException::class);
+        $spent->spendAction();
+    }
+
+    public function testDamageCannotReduceHealthBelowZero(): void
+    {
+        $unit = $this->unit(health: 3);
+        $damaged = $unit->takeDamage(5);
+
+        self::assertSame(3, $unit->health);
+        self::assertSame(0, $damaged->health);
+    }
+
+    public function testNegativeDamageIsANoOp(): void
+    {
+        $unit = $this->unit(health: 7);
+        $damaged = $unit->takeDamage(-3);
+
+        self::assertNotSame($unit, $damaged);
+        self::assertSame(7, $damaged->health);
+    }
+
+    public function testMarkingAttackedReturnsAChangedCopy(): void
+    {
+        $unit = $this->unit();
+        $attacked = $unit->markAttacked();
+
+        self::assertFalse($unit->hasAttacked);
+        self::assertTrue($attacked->hasAttacked);
+    }
+
+    public function testStartingTurnResetsALivingUnit(): void
+    {
+        $unit = $this->unit(actionsRemaining: 0, hasAttacked: true);
+        $started = $unit->startTurn();
+
+        self::assertNotSame($unit, $started);
+        self::assertSame(2, $started->actionsRemaining);
+        self::assertFalse($started->hasAttacked);
+    }
+
+    public function testStartingTurnReturnsTheSameDefeatedUnit(): void
+    {
+        $unit = $this->unit(health: 0, actionsRemaining: 0, hasAttacked: true);
+
+        self::assertSame($unit, $unit->startTurn());
+    }
+
+    public function testItCarriesArchetypeAbilitiesAndBonus(): void
+    {
+        $unit = new UnitState(
+            id: 'unit-1',
+            teamId: 'alpha',
+            position: new Position(0, 0),
+            maxHealth: 10,
+            health: 10,
+            attack: 4,
+            defense: 2,
+            speed: 4,
+            actionsRemaining: 2,
+            hasAttacked: false,
+            archetype: \BattleForge\Domain\Archetype::Support,
+            abilities: ['heal', 'buff'],
+            attackBonus: 2,
+            hasUsedAbility: false,
+        );
+
+        self::assertSame(\BattleForge\Domain\Archetype::Support, $unit->archetype);
+        self::assertSame(['heal', 'buff'], $unit->abilities);
+        self::assertSame(2, $unit->attackBonus);
+        self::assertFalse($unit->hasUsedAbility);
+    }
+
+    public function testItRejectsEmptyStringAbilities(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Unit abilities must be non-empty strings.');
+
+        new UnitState(
+            id: 'unit-1',
+            teamId: 'alpha',
+            position: new Position(0, 0),
+            maxHealth: 10,
+            health: 10,
+            attack: 4,
+            defense: 2,
+            speed: 4,
+            actionsRemaining: 2,
+            hasAttacked: false,
+            archetype: \BattleForge\Domain\Archetype::Defender,
+            abilities: [''],
+        );
+    }
+
+    public function testItExposesAllowedAbilitiesFromTheArchetypeCatalog(): void
+    {
+        $unit = $this->unit();
+
+        self::assertSame(
+            \BattleForge\Domain\ArchetypeCatalog::templates()[$unit->archetype->value]->allowedAbilities,
+            $unit->allowedAbilities(),
+        );
+    }
+
+    public function testWithAttackBonusReturnsAChangedCopyAndRejectsNegativeBonus(): void
+    {
+        $unit = $this->unit();
+        $buffed = $unit->withAttackBonus(3);
+
+        self::assertNotSame($unit, $buffed);
+        self::assertSame(0, $unit->attackBonus);
+        self::assertSame(3, $buffed->attackBonus);
+
+        $this->expectException(\InvalidArgumentException::class);
+        $unit->withAttackBonus(-1);
+    }
+
+    public function testSpendAbilityMarksAndConsumesOneActionButNotTwo(): void
+    {
+        $unit = $this->unit();
+        $spent = $unit->spendAbility();
+
+        self::assertSame(1, $spent->actionsRemaining);
+        self::assertTrue($spent->hasUsedAbility);
+    }
+
+    public function testSpendAbilityRejectsAUnitThatAlreadyUsedAnAbility(): void
+    {
+        $unit = $this->unit(hasUsedAbility: true);
+
+        $this->expectException(\InvalidArgumentException::class);
+        $unit->spendAbility();
+    }
+
+    public function testStartTurnClearsAttackBonusAndAbilityUse(): void
+    {
+        $unit = $this->unit(actionsRemaining: 0, hasAttacked: true, attackBonus: 3, hasUsedAbility: true);
+        $started = $unit->startTurn();
+
+        self::assertSame(2, $started->actionsRemaining);
+        self::assertFalse($started->hasAttacked);
+        self::assertSame(0, $started->attackBonus);
+        self::assertFalse($started->hasUsedAbility);
+    }
+
+    private function unit(
+        int $health = 10,
+        int $actionsRemaining = 2,
+        bool $hasAttacked = false,
+        int $attackBonus = 0,
+        bool $hasUsedAbility = false,
+    ): UnitState {
+        return new UnitState(
+            'unit-1',
+            'alpha',
+            new Position(0, 0),
+            10,
+            $health,
+            4,
+            2,
+            4,
+            $actionsRemaining,
+            $hasAttacked,
+            archetype: \BattleForge\Domain\Archetype::Defender,
+            abilities: [],
+            attackBonus: $attackBonus,
+            hasUsedAbility: $hasUsedAbility,
+        );
+    }
+}

tests/Unit/Http/CsrfTokenTest.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Unit\Http;
+
+use BattleForge\Http\CsrfToken;
+use PHPUnit\Framework\TestCase;
+
+final class CsrfTokenTest extends TestCase
+{
+    private const SECRET = 'unit-test-secret';
+
+    public function testIssueReturnsTokenAndCookieValue(): void
+    {
+        [$token, $cookie] = CsrfToken::issue(self::SECRET);
+
+        self::assertNotSame('', $token);
+        self::assertNotSame('', $cookie);
+        self::assertSame(64, strlen($token));
+    }
+
+    public function testVerifyAcceptsAValidPair(): void
+    {
+        [$token, $cookie] = CsrfToken::issue(self::SECRET);
+
+        self::assertTrue(CsrfToken::verify($token, self::SECRET, $cookie));
+    }
+
+    public function testVerifyRejectsATamperedCookieValue(): void
+    {
+        [$token] = CsrfToken::issue(self::SECRET);
+
+        self::assertFalse(CsrfToken::verify($token, self::SECRET, 'not-the-cookie'));
+    }
+
+    public function testVerifyRejectsATamperedToken(): void
+    {
+        [, $cookie] = CsrfToken::issue(self::SECRET);
+
+        self::assertFalse(CsrfToken::verify('not-the-token', self::SECRET, $cookie));
+    }
+
+    public function testIssueProducesDifferentTokensAcrossCalls(): void
+    {
+        [$tokenA] = CsrfToken::issue(self::SECRET);
+        [$tokenB] = CsrfToken::issue(self::SECRET);
+
+        self::assertNotSame($tokenA, $tokenB);
+    }
+
+    public function testDifferentSecretsProduceDifferentCookieValues(): void
+    {
+        [$tokenA, $cookieA] = CsrfToken::issue('secret-a');
+        [, $cookieB] = CsrfToken::issue('secret-b');
+
+        self::assertTrue(CsrfToken::verify($tokenA, 'secret-a', $cookieA));
+        self::assertFalse(CsrfToken::verify($tokenA, 'secret-b', $cookieB));
+    }
+}

tests/Unit/Http/EscapeTest.php

@@ -0,0 +1,64 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Unit\Http;
+
+use BattleForge\Http\Escape;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+
+final class EscapeTest extends TestCase
+{
+    #[DataProvider('htmlProvider')]
+    public function testItEscapesHtmlContext(mixed $input, string $expected): void
+    {
+        self::assertSame($expected, Escape::html($input));
+    }
+
+    /**
+     * @return iterable<string, array{mixed, string}>
+     */
+    public static function htmlProvider(): iterable
+    {
+        yield 'plain' => ['hello', 'hello'];
+        yield 'less-than' => ['<script>', '&lt;script&gt;'];
+        yield 'ampersand' => ['a & b', 'a &amp; b'];
+        yield 'double-quote' => ['she said "hi"', 'she said &quot;hi&quot;'];
+        yield 'single-quote' => ["it's", 'it&#039;s'];
+        yield 'invalid-utf8-substituted' => ["a\xC0\x80b", "a\xEF\xBF\xBD\xEF\xBF\xBDb"];
+        yield 'integer' => [42, '42'];
+        yield 'null' => [null, ''];
+    }
+
+    #[DataProvider('attrProvider')]
+    public function testItEscapesAttributeContext(mixed $input, string $expected): void
+    {
+        self::assertSame($expected, Escape::attr($input));
+    }
+
+    /**
+     * @return iterable<string, array{mixed, string}>
+     */
+    public static function attrProvider(): iterable
+    {
+        yield 'tag-breakout' => ['" onclick="', '&quot; onclick=&quot;'];
+        yield 'apostrophe' => ["' onclick='", '&#039; onclick=&#039;'];
+    }
+
+    #[DataProvider('urlProvider')]
+    public function testItEncodesUrls(string $input, string $expected): void
+    {
+        self::assertSame($expected, Escape::url($input));
+    }
+
+    /**
+     * @return iterable<string, array{string, string}>
+     */
+    public static function urlProvider(): iterable
+    {
+        yield 'space' => ['hello world', 'hello%20world'];
+        yield 'slash' => ['a/b', 'a%2Fb'];
+        yield 'unicode' => ['héllo', 'h%C3%A9llo'];
+    }
+}

tests/Unit/Http/RequestTest.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Unit\Http;
+
+use BattleForge\Http\Request;
+use PHPUnit\Framework\TestCase;
+
+final class RequestTest extends TestCase
+{
+    public function testItExposesAllSuperglobalsAsConstructorArgs(): void
+    {
+        $request = new Request(
+            get: ['q' => '1'],
+            post: ['name' => 'alpha'],
+            files: ['image' => ['name' => 'a.png', 'tmp_name' => '/tmp/x', 'error' => 0, 'size' => 12, 'type' => 'image/png']],
+            cookies: ['__csrf' => 'cookie-value'],
+            server: ['HTTP_HOST' => 'localhost'],
+            queryString: 'q=1',
+            method: 'POST',
+            path: '/scenarios/demo/edit/team',
+            contentType: 'application/x-www-form-urlencoded',
+            rawBody: '',
+        );
+
+        self::assertSame(['q' => '1'], $request->get);
+        self::assertSame(['name' => 'alpha'], $request->post);
+        self::assertSame('a.png', $request->files['image']['name']);
+        self::assertSame('cookie-value', $request->cookies['__csrf']);
+        self::assertSame('localhost', $request->server['HTTP_HOST']);
+        self::assertSame('q=1', $request->queryString);
+        self::assertSame('POST', $request->method);
+        self::assertSame('/scenarios/demo/edit/team', $request->path);
+        self::assertSame('application/x-www-form-urlencoded', $request->contentType);
+        self::assertSame('', $request->rawBody);
+    }
+
+    public function testItAllowsNullContentType(): void
+    {
+        $request = new Request(
+            get: [],
+            post: [],
+            files: [],
+            cookies: [],
+            server: [],
+            queryString: '',
+            method: 'GET',
+            path: '/',
+            contentType: null,
+            rawBody: '',
+        );
+
+        self::assertNull($request->contentType);
+    }
+}

tests/Unit/Http/RouterTest.php

@@ -0,0 +1,83 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Tests\Unit\Http;
+
+use BattleForge\Http\Request;
+use BattleForge\Http\Response;
+use BattleForge\Http\Router;
+use PHPUnit\Framework\TestCase;
+
+final class RouterTest extends TestCase
+{
+    public function testItDispatchesAMatchingStaticRoute(): void
+    {
+        $router = new Router();
+        $router->add('GET', '/', static fn (Request $request): Response => Response::html(200, 'home'));
+
+        $response = $router->dispatch($this->request('GET', '/'));
+
+        self::assertSame(200, $response->status);
+        self::assertSame('home', $response->body);
+    }
+
+    public function testItReturnsA404ForUnknownPaths(): void
+    {
+        $router = new Router();
+
+        $response = $router->dispatch($this->request('GET', '/missing'));
+
+        self::assertSame(404, $response->status);
+    }
+
+    public function testItReturnsAMethodNotAllowedResponseForMismatchedMethods(): void
+    {
+        $router = new Router();
+        $router->add('POST', '/', static fn (): Response => Response::html(200, 'ok'));
+
+        $response = $router->dispatch($this->request('GET', '/'));
+
+        self::assertSame(404, $response->status);
+    }
+
+    public function testItCapturesPathParams(): void
+    {
+        $router = new Router();
+        $router->add('GET', '/scenarios/{id}/edit', static function (Request $request, array $params): Response {
+            return Response::html(200, 'id=' . $params['id']);
+        });
+
+        $response = $router->dispatch($this->request('GET', '/scenarios/demo/edit'));
+
+        self::assertSame(200, $response->status);
+        self::assertSame('id=demo', $response->body);
+    }
+
+    public function testItMatchesMoreSpecificRoutesFirstByRegistrationOrder(): void
+    {
+        $router = new Router();
+        $router->add('GET', '/scenarios/{id}', static fn (): Response => Response::html(200, 'any'));
+        $router->add('GET', '/scenarios/special', static fn (): Response => Response::html(200, 'special'));
+
+        $response = $router->dispatch($this->request('GET', '/scenarios/special'));
+
+        self::assertSame('any', $response->body);
+    }
+
+    private function request(string $method, string $path): Request
+    {
+        return new Request(
+            get: [],
+            post: [],
+            files: [],
+            cookies: [],
+            server: [],
+            queryString: '',
+            method: $method,
+            path: $path,
+            contentType: null,
+            rawBody: '',
+        );
+    }
+}