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