chore(e2e): RANGO_E2E_PORT_OFFSET — per-checkout port isolation for shared Playwright webServers - #711

Problem

Two clones of this repo running e2e at the same time collide on the fixed fixture ports (rangojs-router 5188/5189 + host 5296/5297, cloudflare-basic 5198/5199). Under reuseExistingServer: !CI, the second run silently reuses the FIRST checkout's server — its tests execute against the other checkout's code with no error — and each run's stale-server cleanup kills the other's servers mid-flight (ERR_CONNECTION_REFUSED waves). This burned about an hour of phantom-failure chasing during #705 verification, when a parallel agent session in a sibling clone was running the same suites.

Change

One knob: RANGO_E2E_PORT_OFFSET (default 0 — zero behavior change). It shifts every fixture port uniformly in:

• packages/rangojs-router/playwright.config.ts (dev/preview + host dev/preview)
• packages/rangojs-router/e2e/host-routing.test.ts (builds absolute URLs from the same constants — reads the same env so it cannot drift from the config)
• tests/cloudflare-basic/playwright.config.ts (dev/preview)

Uniform shifting preserves the deliberate cross-suite spacing (host 5296/5297 was chosen to avoid cloudflare-basic 5198/5199 — that invariant holds at any offset). All other suites (multi-router, vite-rsc-demo, no-typescript, stress-demo, …) already use dynamic per-test ports (findPort()) and need nothing.

Documented in AGENTS.md → Environment gotchas, so agent sessions learn to set it when a sibling clone may be testing.

Usage

# in clone B, while clone A is running e2e:
export RANGO_E2E_PORT_OFFSET=100
pnpm exec playwright test …   # all fixture servers bind 5288/5289/5396/5397/5298/5299

Test plan

• Offset 400: router webServers boot on 5588/5589/5696/5697, cloudflare-basic on 5599/5598 (spawn commands verified in output); content-negotiation --project=dev 23/23 and cloudflare-basic cache-signal --project=dev green against the shifted ports.
• Default (no env): prior runs on these exact configs (39/39, 50/50 in fix(router): RSC flight wire format becomes explicit opt-in — generic clients get the HTML document #705) bound the unchanged ports.
• typecheck (16/16), test:unit:all (0 failures), lint, format.

Notes

• CI is unaffected (single checkout per runner; env unset → offset 0).
• Deliberate non-goal: auto-deriving an offset from the checkout path — implicit port drift is harder to debug than one explicit env var; the AGENTS.md note makes the knob discoverable exactly when the failure mode appears.