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

7.9 KiB

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.