towerdef/docs/NEXT.md
Claude a5bd09d505 Phone UI and touch precision overhaul, proxy fixes, Orbital Uplink, four new maps
Phone panels (reviewed + QA'd, matrix of 22 layouts with real taps/bounding boxes):
- selected-tower action bar over the board (Upgrade/Sell/Target/close), info panel
  updated in place so taps are never lost, scrollable palette for 7+ towers,
  overlays with pinned footers (Help "Got it", Play solo, Join always visible),
  tappable room chip to invite, reduced-motion/contrast/forced-colors fixes,
  paused state, partner cursor labels, bigger level pips and owner flags
- touch input rewritten around "pointerdown commits nothing": pinch never builds,
  10px tap slop, palm-proof pinch, long-press pings with any tool armed, nudge
  arrows for precise placement, hotkey repeat guard, proportional wheel zoom
- new e2e: select/sell, info-panel stability, UI states, touch precision;
  camera unit tests

Proxy/server (reproduced against real nginx 1.26 with NPM v2.16 config):
- Origin check works when the proxy drops a non-default port, TRUSTED_PROXIES for
  proxies on global IPv6/CGNAT addresses, service worker no longer serves nginx's
  502 page, DEPLOY.md corrected (NPM default read timeout is 90 s, Advanced-tab
  limits, path-prefix, cookie size, per-IP cap behaviour)

Content:
- Orbital Uplink: 4-level endgame tower (450 + 500/800/1200 credits): piercing
  armour-ignoring beam, blast and lingering slow, ground+air, range 11-14;
  glyph, beam effect, sound, help text, unit tests
- Maps: The Canyon, Archipelago, Fortress, Pinwheel (7 maps total)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tb8pW2KAN4oFkh1aK1BfD8
2026-10-10 18:03:24 +00:00

92 lines
7.9 KiB
Markdown

# Where to pick up (written 2026-10-09)
Netwall is playable and pushed: solo (desktop + phone), two-player co-op through the Node server, music, PWA, deploy docs.
Development was paused on purpose before the fix stage. This file is the entry point for the next session.
## State of the repo
| Area | State |
|---|---|
| `public/js/sim.js` | Shared rules. 20 unit tests. **Balance not tuned yet** (see `docs/BALANCE.md`). |
| `server/` | Done and reviewed by an independent adversarial pass (5 real issues found and fixed: pid leak/slot hijack, room-flood lockout, spoofable X-Forwarded-For, startup crash in restricted sandboxes, clock-step in rate limiter). 59 tests. |
| `public/` client | Works, but a second review pass found many issues. **None fixed yet.** See `docs/review-2026-10-09/findings.md`. |
| `e2e/` | `npm run e2e`: smoke, touch, end flow, co-op (two browsers incl. reconnect), 14-size layout matrix. All passed at the last run. |
| `tools/bot.js` | Headless balance bot (dev tool). Complete; its results are summarised in `docs/BALANCE.md`. |
| Deploy | `docs/DEPLOY.md`, `deploy/netwall.service`, README setup guide. Never run against a real nginx Proxy Manager or on a phone yet (an NPM-style review found doc inaccuracies, listed in the findings). |
`npm test` = 91 passing. `npm run e2e` = 9 scenarios (22-layout matrix, touch precision, selection/sell, info-panel stability, UI states, co-op). Verified from a fresh `git clone` earlier (2026-10-09).
## Fixed since this was written
* 2026-10-10: selecting a placed Firewall no longer throws (walls can be sold again; e2e scenario `06-select-sell`).
## Roadmap (decided with the user, 2026-10-10)
The user playtested ("fun, mostly usable") and chose: maze stays strong (no wall price rule), an Easy/Normal/Hard picker,
and these features after the fixes: more maps, new towers and enemies, server leaderboard, room list / quick match.
Later requests: an **endgame tower** (Orbital Uplink, in the sim already), **attack-vs-defend multiplayer** (`docs/VERSUS.md`),
and a check that the layout holds on **tablets and foldables**.
| Wave | Content | State |
|---|---|---|
| 1 | Phone panels/layout + touch precision (one owner of main.js/style.css), proxy/server doc fixes, QA | **done 2026-10-10** (QA passed) |
| 2 | Co-op robustness (stalled-render tower loss, half-open sockets, idempotent upgrade/wave), audio + keyboard + a11y | drafted |
| 3 | Content: new towers/enemies (healer, shielded, Sandbox, Load Balancer). Done already: Orbital Uplink (sim, glyph, beam, sound, help), 4 new maps (Canyon, Archipelago, Fortress, Pinwheel) | in progress |
| 4 | Attack-vs-defend versus mode, bots for both sides | design in `docs/VERSUS.md` |
| 5 | Difficulty picker + ONE time-boxed balance pass (IDS dominance, weak Mortar/Arc, credit pile-up; maze stays strong) | after 3 and 4 |
| 6 | Server leaderboard (needs `StateDirectory=netwall` + `DATA_DIR`; solo scores are client-reported) and an opt-in public room list | after 5 |
| any | Tablet/foldable viewports in the e2e matrix (near-square 690x830, 840x700, half-folded 841x400, cover 344x800) | todo |
## Suggested order of work
1. **The wall bug above**, then the other confirmed high/medium client bugs:
* `code-2`: the info panel is rebuilt with `innerHTML` on every `view.rev` change, so an Upgrade/Sell/Target tap that
lands during a rebuild is lost (worse in co-op, where the partner's actions bump `rev`). Update in place or rebuild
only when this tower's signature changes.
* `coop-1` / `code-1`: `RemoteController` keeps only the last 10 snapshots; a render stall of ~0.5 to 1 s drops snapshots
that carry `tw` (tower list) before they are displayed, so the partner's new towers are lost until a resync. Never
discard an entry whose `tw` has not been applied (or apply `tw` to the mirror on arrival and only delay the drawn list).
* `touch-1`, `touch-2`: with a wall armed, the first finger of a pinch builds a wall immediately; with a turret armed
it moves the pending placement. Defer the first placement to pointerup/first real move and cancel on a second pointer.
* Phone layout: after tapping a tower the Upgrade/Sell/Target buttons are below the fold (`visual-2`, `touch-3`); on small
phones the first-run Help has no visible "Got it" (`visual-3`) and the co-op room code and Invite button are not
visible while waiting for a partner (`visual-4`, `touch-8`). Likely fix: show the selected-tower panel as a bottom
sheet over the palette, put room code/invite in the top bar or a toast, make overlays scroll with a sticky button row.
* `coop-2`: after a half-open connection (Wi-Fi/cell switch) the UI looks alive but frozen for 47 to 65 s; show the
reconnect overlay as soon as the watchdog fires and open a new socket without waiting for the old one to close.
2. **Co-op correctness**: simultaneous Upgrade / Next Wave from both players are applied twice (`coop-5`: make upgrade
idempotent, e.g. send the expected level; ignore a wave command within ~1 s of another), host-leaves-while-end-screen
(`coop-3`, `code-11`), failed join from the menu kills the live game (`coop-4`), controller races (`code-3`, `code-4`).
3. **Smaller UX/a11y**: reduced-motion hides every toast (`touch-5`, `visual-6`), Space held launches ~20 waves
(`code-6`: ignore `e.repeat`), co-op music/stinger after Play again (`code-5`, `code-7`, `code-12`), touch target sizes,
safe-area double padding, contrast, colour-only enemy legend, pause not obvious.
4. **Proxy docs/behaviour** (`proxy-*` in the findings): 403 when the public URL has a non-default port (Origin vs Host
port handling), DEPLOY.md claims NPM can send `X-Forwarded-Host` from the Advanced tab (it cannot), NPM's default read
timeout is 90 s not 60 s, service worker serves nginx's 502 page instead of the cached app, path-prefix instructions for NPM.
5. **Balance** (`docs/BALANCE.md`): the baseline shows the game is currently too easy and IDS Sniper dominates.
6. Real-world checks that were never possible in the sandbox: a real phone (iOS Safari audio unlock, safe areas, wake
lock), real nginx Proxy Manager with Let's Encrypt, a Proxmox LXC with the systemd unit.
Findings marked UNVERIFIED were reported with a reproduction but not yet independently re-checked (the verification
stage was stopped); re-run the repro from `docs/review-2026-10-09/repro-scripts.tgz` before fixing.
## Decisions waiting for the user
* **Maze exploit.** A long serpentine of cheap walls (5 credits) makes routes about 5 to 6 times longer than the direct path.
Options: escalating wall price, a wall cap, or faster/tougher waves. See `docs/BALANCE.md`.
* **Room codes** are 4 characters (about 1M); a stranger could guess an open room. Options: 6 characters, an optional
room password, per-IP rate limit on failed joins.
* **Music size.** battle/boss/menu are 3 to 8 MB each and downloaded whole on first use; fine on Wi-Fi, heavy on mobile
data. Could re-encode to mono ~48 kbps.
## Dev environment (what the session used, none of it is in the repo)
* The sandbox had no Node and no root. The user's machine can install anything: `apt install nodejs npm`, `npm install`,
`npx playwright-core install chromium-headless-shell` (plus `npx playwright-core install-deps` as root) and `npm run e2e` is all that is needed.
* The review pipeline (5 reviewers, a verifier per finding, one fixer, a final QA) was a Workflow script; a copy is in
`docs/review-2026-10-09/phase2-workflow.js` and can be re-run (re-point its scratch paths) to verify the UNVERIFIED
findings and to run the fix stage.
* Conventions: `public/js/sim.js` must stay pure and DOM-free (it runs in the browser for solo and in Node for co-op); `ws` is the only
runtime dependency; the client uses only relative URLs (works under a proxy path prefix); `test/` may only hold real test files
(plain `node --test` runs everything there).
* Git: commit and push at milestones is pre-authorised for this project.