# 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.