twinwire 0.0.0-stage → 1.0.0

package/dist/server/turn.js

@@ -0,0 +1,52 @@
+import { createHmac } from 'node:crypto';
+import { validIceServers } from '../core/rtc.js';
+/**
+ * Short-lived TURN credentials for coturn's `use-auth-secret` (the "TURN REST API" scheme): the username is
+ * `<expiry unix seconds>:<user>` and the password is base64(HMAC-SHA1(secret, username)). Never ship the secret.
+ */
+export function turnCredentials(o) {
+    if (!o.secret)
+        throw new Error('TURN secret required');
+    const ttl = o.ttlSeconds ?? 3600;
+    if (!Number.isInteger(ttl) || ttl < 60 || ttl > 7 * 86400)
+        throw new RangeError('Invalid TURN ttl');
+    const user = (o.user ?? 'player').replace(/[^\w.-]/g, '').slice(0, 64) || 'player';
+    const username = `${Math.floor((o.now ?? Date.now()) / 1000) + ttl}:${user}`;
+    const server = { urls: o.urls, username, credential: createHmac('sha1', o.secret).update(username).digest('base64') };
+    if (!validIceServers([server]))
+        throw new Error('Invalid TURN URL');
+    return server;
+}
+/**
+ * ICE servers from Cloudflare Realtime TURN (a managed relay with anycast TURN over UDP, TCP and TLS:443).
+ * Credentials are fetched with your key and cached until shortly before they expire.
+ */
+export function cloudflareTurn(o) {
+    const ttl = o.ttlSeconds ?? 86400, get = o.fetch ?? fetch;
+    let cached = null, until = 0, inflight = null;
+    return async () => {
+        if (cached && Date.now() < until)
+            return cached;
+        inflight ??= (async () => {
+            try {
+                const res = await get(`https://rtc.live.cloudflare.com/v1/turn/keys/${encodeURIComponent(o.keyId)}/credentials/generate-ice-servers`, {
+                    method: 'POST', headers: { Authorization: `Bearer ${o.apiToken}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ ttl }),
+                });
+                if (!res.ok)
+                    throw new Error(`Cloudflare TURN ${res.status}`);
+                const body = await res.json();
+                const list = Array.isArray(body.iceServers) ? body.iceServers : body.iceServers ? [body.iceServers] : [];
+                if (!validIceServers(list))
+                    throw new Error('Cloudflare TURN returned invalid ICE servers');
+                cached = list;
+                until = Date.now() + ttl * 900;
+                return list;
+            }
+            finally {
+                inflight = null;
+            }
+        })();
+        return inflight;
+    };
+}
+//# sourceMappingURL=turn.js.map

package/dist/server/turn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn.js","sourceRoot":"","sources":["../../src/server/turn.ts"],"names":[],"mappings":"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"}

package/docs/ADOPTING.md

@@ -0,0 +1,64 @@
+# Adopting Twinwire in an existing game
+
+Most games that come to Twinwire already have netcode of some kind: a WebSocket, maybe geckos.io or a hand-rolled
+WebRTC path, a reliability layer, rooms. Swap the transport first and keep the game's own model of the world; then
+move pieces onto Twinwire's helpers only where they're better than what you have.
+
+## A staged path
+
+1. **Keep your world, swap the wire.** Leave the simulation, the snapshot format and the rendering alone. Replace the
+   connection code with a `GameClient` on the page and `createGameServer` on the server, behind a flag if you can.
+2. **Sort your traffic into two kinds.**
+   - Things that must arrive, in order (hits, doors, purchases, chat, map changes): `sendEvent`. Remove any old
+     reliability layer on that path instead of running two acknowledgement schemes.
+   - Things where only the newest matters (positions, snapshots, inputs): `sendState` on a stable stream number.
+3. **Stamp what depends on time.** Events and states travel separately, so nothing orders one against the other.
+   Put the server tick (or a map/world generation number) in each event, and in each snapshot; a snapshot that belongs
+   to a change the client hasn't heard about yet waits for it, and one from before a change is dropped.
+4. **Rooms on the lobby.** Codes, quick play, seats and build matching come from `Lobby`/`LobbyClient`. Put the build
+   id in room `meta` (`match` for quick play, `canJoin` for codes), and keep your world in `room.data`. Seats survive
+   reconnects through the session itself; `onReconnect` is where your world re-sends whatever a fresh client needs.
+5. **Then the helpers, if they beat yours.** Deltas against acknowledged snapshots (`ack: true`, `SnapshotHistory`),
+   interpolation (`Timeline`, `AdaptivePlayback`), prediction (`Predictor`, `InputInbox`, `encodeInputs`).
+
+## Sizes
+
+A state can be up to 64 KiB (`maxStateBytes`, up to 256 KiB), but a per-tick packet that fits 1078 bytes fits one
+datagram on any path. Bigger states are fragmented by SCTP on the datagram path, and anything over `datagramStateBytes`
+(8 KiB) takes the WebSocket instead, where it can't be lost piecewise: fine for a whole snapshot after a map change, not
+for every tick. Events are JSON up to 64 KiB each.
+
+## By kind of game
+
+- **Action games (shooters, platformers, fighting):** keep your own movement, collision and hit rules on the server.
+  Send inputs redundantly (`encodeInputs` with the last few), apply them with `InputInbox`, and reconcile on the client.
+  A shot that matters is an event that names the input/tick it came from, so the server can check it against its own
+  history.
+- **Social and co-op worlds:** interest-filter what each player gets (`SpatialGrid` for "who is near"), send compact
+  records at a modest rate (10-20 Hz), and acknowledged records (`ReplicaSender`) for things that change rarely.
+- **Strategy:** commands are events, applied by the server; snapshots at the simulation's own rate.
+- **Turn-based:** WebSocket only (`rtc: false`): there's nothing for UDP to speed up.
+
+## A real port: Nocturne Keep
+
+[Nocturne Keep](https://nocturnekeep.com) is a pixel-art platformer whose rooms run the game's own code headless on
+the server (a Node `vm` per room, each in its own worker thread), with each phone simulating only its own player.
+Before Twinwire it used geckos.io for WebRTC, a separate WebSocket fallback, and a Quake-3-style reliable layer that
+repeated unacknowledged messages in every packet.
+
+- The page's connection code (about 120 lines) became a `GameClient` and a `LobbyClient`; the server's hello, codes,
+  quick play and seat tokens became `Lobby` callbacks.
+- The reliable layer went away on both sides. Its messages are events, each stamped `[serverFrame, message]`.
+- Its JSON snapshots, already deltas against the last snapshot the phone acknowledged, stayed exactly as they were:
+  they became stream 0 states, with the map-change number added so a snapshot that beats its map event waits for it.
+- A reload keeps the seat: the page saves `checkpoint()` in sessionStorage and resumes it when the player rejoins.
+- All of its multi-browser suites (co-op story, every map, every boss, maker rooms, races, the roguelike together) pass
+  over WebRTC, and its live check plays the public site in Chromium and WebKit.
+
+## Checks worth copying
+
+- Two browsers agree on the same world at the same tick (same enemies, same positions within a tolerance).
+- A lost stop or state change heals by itself (the next state repairs it).
+- Both directions survive UDP failing while the WebSocket stays up (`IMPAIR`, `RTC=0` in the browser test).
+- A phone that drops (tunnel, app switch) comes back to its seat; a reload with a checkpoint too.
+- Measure before and after with the same inputs: corrections, input-to-visible delay, missed snapshots, bytes.

package/docs/API.md

@@ -0,0 +1,181 @@
+# API and integration
+
+All modules are ESM with TypeScript declarations.
+
+| Import | For |
+|---|---|
+| `twinwire/client` | Browser: `GameClient`, `LobbyClient`, `BrowserRtcPeer` |
+| `twinwire/server` | Node: `createGameServer`, `GameServer`, `GameSession`, `Lobby`, `Room`, `createNativeRtcFactory`, `turnCredentials`, `cloudflareTurn` |
+| `twinwire/netcode` | Both: clock, interpolation, prediction, timing, snapshots, replication, codecs, spatial |
+| `twinwire` | Both: the wire protocol and `Endpoint` |
+| `twinwire/browser` | `dist/browser/twinwire.js` (also `.min.js`; ESM `.mjs` for `import`): client + lobby + netcode as `window.Twinwire` |
+
+Browser code never imports the server entry. Node needs `ws`; WebRTC on the server needs `node-datachannel@0.33.x`.
+
+## GameClient
+
+```ts
+const client = new GameClient({
+  url: 'wss://game.example.com/connect',
+  room: 'mygame',                 // a namespace the server sees; rooms with codes come from the lobby
+  auth: { name: 'WREN', build },  // any JSON, checked by the server's authenticate hook; also session.hello
+  rtc: {},                        // default. false = WebSocket only. { iceServers } overrides the server's list
+  endpoint: { bytesPerSecond: 32 * 1024 },
+});
+```
+
+| Member | Contract |
+|---|---|
+| `connect()` | Starts join/resume and pumping. |
+| `whenOnline()` | Promise: resolves when online (at once if already), rejects if the session is lost or closed first. |
+| `status`, `onStatus(s)` | `idle`, `connecting`, `online`, `paused`, `closed`, `lost`. |
+| `transport`, `onTransport(t)` | `rtc` (datagrams proven both ways), `ws`, `none`. |
+| `onSession({id,resumed})` | Identity is available. `resumed: false` means a brand-new session: reset game state. |
+| `onSessionLost({pendingEvents,reason})` | Expiry, kick, takeover by another tab, authentication or protocol rejection. Retrying stops; call `newSession()`. |
+| `sendEvent(json)` | Ordered, acknowledged, deduplicated; replayed after reconnects. Returns its seq; throws when the outbox is full (512 events / 1 MiB) or the event is over 64 KiB. |
+| `onEvent(data, seq)` | Each event exactly once, in order, whichever path brought it first. |
+| `sendState(stream, bytes, {ttlMs, priority, ack}?)` | Latest wins per stream (0 to 65535). Returns the seq, or 0 before the session is online and the clock synced. Up to `maxStateBytes` (64 KiB). |
+| `onState({stream,seq,time,data,via})` | Newer than anything seen on that stream this connection. `time` is the sender's server-clock estimate: never trust it for authority. |
+| `onStateAck(stream, seq)` | For states sent with `ack: true`: the newest the peer has seen. |
+| `iceServers` | What the server suggested in its welcome. |
+| `clock` | `synced`, `rttMs`, `uncertaintyMs`, `serverTime(performance.now())`. |
+| `pause()` / `resume()` | Close and reopen the connection, keeping the session. |
+| `reconnectNow()` | Skip the backoff (the network came back). |
+| `newSession()` | Drop the old session and its unsent actions; get a new identity. |
+| `close()` | Leave for good (the server ends the session at once). |
+| `checkpoint()` / `options.checkpoint` | Carry a session across page loads. Holds a bearer token: never put it in a URL. |
+| `bindPageLifecycle({hiddenPauseMs, wakeCheckMs})` | Pause on `pagehide` or after 20 s hidden; when the page is back, resume, or replace a socket that stays silent for 1.5 s; reconnect at once on `online`. |
+| `intercept(fn)`, `on('session' \| 'lost', fn)` | Extra listeners for helpers such as `LobbyClient`. |
+| `endpoint.stats` | Traffic, stale/expired/coalesced states, `eventsViaDatagram`, `datagramRttMs`, and more. |
+| `options.impair` | `{lagMs, jitterMs, loss, duplicate}` on this client's sends, and asked of the server (which honours it only with `allowImpairment`). `lagMs` is one way. |
+
+Callbacks should be short. Don't throw from `onEvent` after side effects: a throw means "not accepted" and the event
+comes again.
+
+## LobbyClient
+
+```ts
+const lobby = new LobbyClient(client);
+const room = await lobby.create({ mode: 'night', visibility: 'private', maxMembers: 4, meta: { build } });
+await lobby.join('KQXT');                       // case-insensitive
+await lobby.quickPlay({ mode: 'night', match: { build }, create: { maxMembers: 4 } });
+await lobby.setReady(true); await lobby.setName('WREN'); await lobby.setMeta({ skin: 2 });
+await lobby.kick(2); await lobby.leave();
+lobby.onRoom = room => {};   // RoomView | null on every change
+lobby.onLeft = reason => {}; // kicked, replaced, closed, expired, new session
+lobby.room; lobby.me; lobby.isHost; lobby.countdownMs();
+```
+
+`RoomView`: `{ code, mode, visibility, phase, maxMembers, meta, you, members: [{seat, name, ready, connected, host, meta}], countdownEndsAt }`.
+Requests reject with the server's message (`no room called ZZZZ`, `that room is full`, your `canJoin` text). Lobby
+traffic uses events with a `$lobby` key; `onEvent` never sees them.
+
+## Server
+
+```ts
+const server = await createGameServer({
+  host: '127.0.0.1', port: 8787, origins: ['https://game.example.com'],
+  rtc: await createNativeRtcFactory({ port: 8788, maxMessageSize: 64 * 1024 + 22 }),
+  iceServers: session => [turnCredentials({ secret: process.env.TURN_SECRET, urls: 'turn:turn.example.com:3478', user: session.id })],
+  trustProxy: true, resumeGraceMs: 90_000,
+  authenticate: ({ auth, room, resuming, ip }) => validBuild(auth) ? 'anon' : null,
+  endpoint: { bytesPerSecond: 48 * 1024 },
+});
+await server.listen();
+```
+
+| Option | Default | |
+|---|---|---|
+| `origins` | required | Exact page origins. `allowMissingOrigin` lets non-browser clients in. |
+| `rtc` | none | `createNativeRtcFactory({port, publicIp?, bindAddress?, iceServers?, maxMessageSize?})`. Without it: WebSocket only. |
+| `iceServers` | `[]` | Array or `(session) => array \| Promise`. Sent in each welcome. |
+| `trustProxy` | false | Read the client address from the last `X-Forwarded-For` hop when the peer is a local proxy. |
+| `resumeGraceMs` | 90 000 | How long a dropped session (and its lobby seat) waits. |
+| `maxSessions` / `maxConnections` / `maxPerIp` | 256 / 512 / 32 | |
+| `rateLimit` | 300 msg/s, 256 KiB/s | Per connection, both transports together. |
+| `allowImpairment` | false | Honour a client's `impair`. Development only. |
+| `endpoint` | | Endpoint options for every session (below). |
+
+| Member | |
+|---|---|
+| `sessions` | Map of id to `GameSession`: `id`, `room`, `subject`, `ip`, `hello` (latest `auth`), `connected`, `transport`, `data` (yours), `sendEvent`, `sendState`, `onEvent`, `onState`, `onStateAck`, `endpoint`. |
+| `on('session' \| 'disconnect' \| 'expire', fn)` | Listeners beside `onSession` / `onDisconnect` / `onExpire`. |
+| `endSession(session, reason)` | Kick: the client gets `onSessionLost(reason)`. |
+| `broadcast(room, json)` | To every session that said hello with that `room`. |
+| `metrics()` | Sessions, connections, rtc/ws counts, bytes, pending events, protocol errors. For `/health`. |
+| `addressOf(req)` | The address the limits use. |
+
+## Lobby
+
+```ts
+const lobby = new Lobby(server, {
+  maxMembers: 4, codeLength: 4, emptyCloseMs: 30_000,
+  joinablePhases: ['lobby', 'playing'],   // join by code mid-game (drop-in)
+  quickPlayPhases: ['lobby'],             // quick play only into rooms still waiting
+  ready: { countdownMs: 3000, minMembers: 1 },  // or false
+  evictDisconnected: true, allowHostKick: true, maxRoomsPerIpPerHour: 30,
+  clientMetaKeys: ['skin'],                 // meta keys members may set themselves (default: any)
+  canCreate: (session, req) => null,      // or an error message
+  canJoin: (room, session, req) => room.meta.build !== session.hello?.build ? 'A NEW VERSION IS OUT' : null,
+});
+```
+
+The lobby owns each session's `onEvent`/`onState`; use its callbacks: `onCreate(room, creator)`, `onJoin(room, member)`,
+`onLeave(room, member, reason)`, `onDisconnect`, `onReconnect`, `onStart(room)`, `onClose(room, reason)`,
+`onEvent(room, member, data, session)`, `onState(room, member, state, session)`. `room`/`member` are null for a
+session that isn't in a room.
+
+`Room`: `code`, `mode`, `visibility`, `phase`, `meta`, `data` (yours), `members` (by session id), `host`,
+`memberAt(seat)`, `connectedCount`, `broadcast(json, except?)`, `send(member, json)`, `setPhase(p)` (`'lobby'` clears
+ready), `setMeta(patch)`, `setVisibility(v)`, `start()`, `close(reason)`. `Member`: `session`, `seat` (stable),
+`name`, `ready`, `connected`, `meta`, `data` (yours). `lobby.createRoom(...)`, `roomOf(session)`, `memberOf(session)`.
+
+A member keeps its seat while disconnected, until its session expires (`resumeGraceMs`). Seats are the lowest free
+number. The host is the earliest-joined connected member.
+
+## Endpoint options
+
+`bytesPerSecond` (32 KiB) and `burstBytes`: scheduling budget for states and events (a message bigger than the burst
+goes once the bucket is full). `maxBufferedBytes` (64 KiB): socket backpressure. `maxStateBytes` (64 KiB, at most
+256 KiB). `datagramStateBytes` (8 KiB): bigger states use the WebSocket. `datagramEvents` (true). `stateAckIntervalMs`
+(50). `probeIntervalMs`/`probeTimeoutMs` (250/1500). `maxStreams` (1024). `events: {maxEvents, maxBytes,
+maxEventBytes}`. `impair`. Both ends should agree on `maxStateBytes`.
+
+## Netcode
+
+**Clock and timing.** `NetworkClock` (the client has one). `FixedStepper(hz, maxCatchUp)` runs a fixed simulation
+step and reports dropped time instead of spiralling. `PROFILES` has starting rates for social, action, strategy and
+turn-based games.
+
+**Snapshot interpolation.** One `Timeline` per entity, `AdaptivePlayback(intervalMs)` to choose a render time that
+covers the jitter you actually see: `observe(clock.serverTime(now), state.time)` on arrival, `advance(serverNow, dt)`
+per frame, then `timeline.sample(renderTime, lerp, extrapolate?, maxMs)`. Mark teleports as `discontinuity`.
+
+**Prediction.** `Predictor(initial, step, dt)`: `push(input)` predicts, `recent(n)` for redundant sends
+(`encodeInputs`), `reconcile({ack, tick, state})` replays what the server hasn't applied. The server feeds
+`InputInbox` and acks the last input it applied. `rewindTime` clamps lag-compensation requests.
+
+**Delta snapshots.**
+
+```ts
+const history = new SnapshotHistory<Entities>();   // one per player
+session.onStateAck = (stream, seq) => history.acknowledge(seq);
+const base = history.baseline;                       // null: send everything
+const seq = session.sendState(0, encode({ b: base?.seq ?? 0, d: diffEntities(base?.value ?? null, world) }), { ack: true });
+history.record(seq, world);
+// client: view = applyEntityDelta(states.get(msg.b) ?? null, msg.d); states.set(s.seq, view)
+```
+
+Reset both sides when the connection epoch changes (`onSession`). A null field and a missing field are the same.
+
+**Acknowledged records.** `ReplicaSender`/`ReplicaReceiver` resend whole small entity records until acknowledged,
+with generations for reused ids.
+
+**Codecs and interest.** `defineSchema({x: {type: 'i16', scale: 10}, ...})` for fixed binary layouts.
+`SpatialGrid` for "who is near whom"; your rules still decide who may see what.
+
+## Limits worth knowing
+
+No order holds between events and states: stamp events with the server tick or a map generation when a snapshot
+depends on them. Events are acknowledged when your callback returns, not when a database commits: give purchases
+an action id and make handlers idempotent.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,101 @@
+# Architecture and guarantees
+
+## Boundaries
+
+The unit is a **logical session**, not a socket. The server keeps a session's identity and event counters while its
+physical connections come and go. Every accepted WebSocket gets a new **epoch**; frames from an older epoch are
+ignored on either path. The WebSocket carries control, events and WebRTC signalling; state uses a WebRTC data
+channel when one is proven, else the WebSocket.
+
+```
+ game: input, simulation, rendering                   game: rooms, authoritative simulation
+              |                                                     |
+ GameClient (+ LobbyClient)  <---- one session ---->   GameServer (+ Lobby)
+   events: ordered, acked        WebSocket: control, events, signalling, fallback state
+   states: latest wins           WebRTC datagrams: state, probes, mirrored events, state acks
+```
+
+The application owns authority. The library can't decide whether a position, hit or purchase is legal.
+
+## Connection lifecycle
+
+1. WebSocket: version, origin, room name, authentication; create or resume one session. The welcome carries the
+   epoch, a resume token and the ICE servers for this session.
+2. Pings estimate the server clock. States aren't sent before the client has an estimate.
+3. The client offers an unordered, zero-retransmit data channel (signalled over the WebSocket). The server answers
+   from one UDP port shared by every connection.
+4. Each side probes the datagram path and needs its own replies back. "Open" isn't proof: one-way loss is caught.
+5. State uses datagrams while proof is recent (1.5 s); otherwise the WebSocket. RTC is retried with backoff.
+6. A lost WebSocket pauses the session; the client reconnects with its token (backoff from 200 ms, at once when the
+   browser reports `online` or the page comes back). The server rechecks authentication and the room/subject
+   binding. Unacknowledged events are replayed both ways.
+7. After `resumeGraceMs` the session expires. The client must call `newSession()`; old actions are not replayed into
+   a new player.
+
+A second tab resuming the same token takes the session over; the first reports session loss rather than fighting.
+
+## Wire protocol (version 3)
+
+Binary frames, little-endian, 22-byte header: magic `TW`, version, kind, epoch (u32), stream (u16), seq (u32),
+time (f64).
+
+| Kind | Path | Meaning |
+|---|---|---|
+| 1 state | either | Latest-wins application bytes. |
+| 6 state-acked | either | The same, and the receiver reports the newest seq it saw. |
+| 5 state acks | datagram if up | Pairs of (stream u16, seq u32), at most every 50 ms. |
+| 2/3 probe/reply | datagram | Liveness proof and RTT. |
+| 4 events | datagram | Copies of WebSocket-sent unacknowledged events (`[[seq, json], ...]`, under 1 KB) and, in the seq field, the sender's own receive ack. |
+
+Control messages are JSON text on the WebSocket: `hello`, `welcome`, `event`, `ack`, `ping`/`pong`, `signal`,
+`rtc-reset`, `leave`, `reset`.
+
+## Delivery contracts
+
+### Replaceable state
+
+`sendState` keeps only the newest unsent payload per stream, expires it after `ttlMs`, and sends by priority and age
+within the byte budget. Receivers drop anything not newer than what they have on that stream, whichever path it
+came by. A payload up to 1078 bytes fits one datagram; larger ones (up to `maxStateBytes`) are fragmented by SCTP on
+the datagram path, and anything over `datagramStateBytes` (8 KiB) goes on the WebSocket instead, where a large
+snapshot can't be lost piecewise.
+
+Sending is not delivering. Make each payload self-contained or a delta against a snapshot the receiver
+**acknowledged** (`ack: true`, `SnapshotHistory`). The WebSocket fallback can't drop queued bytes the way UDP does;
+coalescing and the buffer limit keep that backlog short.
+
+### Acknowledged events
+
+Ordered sequence numbers, a bounded outbox, duplicate suppression within a session, replay after reconnects. Every
+event goes on the WebSocket; while datagrams are proven, copies are also sent on them and retried at about 1.5×RTT
+(six tries). The receiver delivers each seq once, in order, from whichever copy arrives first, holding early ones in a
+bounded buffer, and acknowledges on both paths. The result: event latency close to UDP under loss, with TCP as the
+guarantee.
+
+An ACK means your callback returned. It isn't a database commit. For purchases and transfers, give the action an id,
+persist it with the result, and reply with success or failure.
+
+## Lobby
+
+Rooms are the lobby's, not the transport's: a session joins a room by request (create, code, quick play), keeps a
+stable seat across reconnects, and leaves when it asks, is kicked or replaced, or its session expires. Room changes go
+to members as `$lobby` events with a view tailored to each (their own seat). Ready-up counts down on the server clock
+and starts the room; any change cancels the countdown.
+
+## Performance controls
+
+Simulation, replication and rendering rates are separate (`FixedStepper`). Budgets: per-peer token bucket for
+states and events (control and probes are exempt so recovery isn't starved), socket buffer high-water, per-connection
+message and byte rate limits on both transports.
+
+## Security
+
+Production needs HTTPS/WSS, exact origins, input validation and, where accounts exist, `authenticate`. Origin isn't
+authentication. Resume tokens are bearer secrets. Behind a proxy use `trustProxy` so per-address limits see real
+addresses. TURN secrets stay on the server (`turnCredentials` mints short-lived ones). The native adapter keeps DTLS
+fingerprint verification on. `allowImpairment` is for development.
+
+## Not here (yet)
+
+WebTransport (Safari shipped it in 26.4; a transport adapter can replace the data channel later), multi-region
+routing, durable session storage across server restarts, rollback netcode, voice.

package/docs/OPERATIONS.md

@@ -0,0 +1,93 @@
+# VPS operation and the $5 target
+
+The package has no hosting fees. It does not impose a provider bill cap, buy servers, or guarantee that a $5 VPS can run every game. Simulation cost, concurrency, entity density, activity hours, transfer allowance, and public-IP costs determine that result. A New Jersey server can be a test baseline for nearby players; it cannot provide equally low latency to players worldwide.
+
+## Budget before deployment
+
+Use your actual provider terms. The calculator's defaults are illustrative, not a live Vultr quote:
+
+```sh
+npm run budget -- --base 5 --included-gb 1000 --overage 0.01 \
+  --bytes 12000 --players 5 --hours 100 --overhead 0.20
+```
+
+`--players` is average concurrency during the specified active hours, not registered users. `--bytes` is observed encoded downlink bytes/sec/player, not an estimated schema size alone. `--overhead` estimates additional network framing. The calculator does not include backups, VAT, managed TLS services, relays, logs, storage, or transfer used by other processes.
+
+Arithmetic example, not a plan recommendation: 50 players at 40,000 bytes/sec for 720 hours generate 5,184 GB of application payload. With a hypothetical $5 base, 1,000 GB allowance, and $0.01/GB overage, that is $46.84 even before protocol overhead. A transport library cannot make continuous traffic free.
+
+To approach the target, send compact state only to relevant viewers, reduce idle updates, batch small entity records, bound rates, and leave static assets on the existing CDN. The default endpoint budget is a starting cap, not an established visual-quality optimum. Event/control overhead and transport accounting still need measurement.
+
+## Deployment templates
+
+`deploy/Dockerfile`, `deploy/Caddyfile`, and `deploy/twinwire-demo.service` are templates, not tested deployments. They run the arena as a lab; replace the command with your actual room entry point after integration. Nothing here provisions infrastructure.
+
+Suggested layout: client/static assets through the existing host; a conventional Node process on the VPS; local Caddy terminates HTTPS/WSS on 443 and proxies `/connect`; WebRTC connects directly to a public UDP socket. The UDP endpoint must be reachable independently of the HTTP proxy. Do not assume a standard HTTP CDN forwards this UDP port.
+
+A browser on HTTPS requires a secure WebSocket endpoint. Configure exact allowed origins. Keep admin/health endpoints restricted as appropriate. The sample `/health` intentionally contains no tokens or player data, but does expose process counts and memory.
+
+The native server uses one UDP port for its connections. Use a distinct UDP port for each project/process on the same host. Muxing within a process does not let unrelated processes safely share the same port. The optional `publicIp` setting only rewrites IPv4 host candidates; it does not set up NAT or port forwarding. Test IPv6-only client paths and NAT64 explicitly before claiming them supported.
+
+Example environment for a staging lab:
+
+```sh
+HOST=127.0.0.1
+PORT=8787
+ALLOWED_ORIGINS=https://game.example.com
+RTC=1
+RTC_PORT=8788
+# Set only when candidate rewriting is required by your network layout:
+# RTC_PUBLIC_IP=203.0.113.7
+```
+
+Serve it behind TLS, allow the configured UDP port through the relevant firewall, and test from outside the VPS. Do not expose plain WS from an HTTPS page. Do not advertise example addresses as working endpoints.
+
+## Resource and security operations
+
+Run the process as a dedicated unprivileged user. Restrict writable paths; back up durable game data separately. Process restart loses the transport's in-memory sessions/outboxes, so the app must implement full resync and action idempotency across restarts. Database-backed transport resumption is not implemented.
+
+Per-IP connection limits use the actual TCP peer address. Behind Caddy, all peers may be attributed to the proxy. Set an appropriate cap and rate limit at the proxy; never blindly trust client-supplied `X-Forwarded-For` headers.
+
+Monitor process RSS/CPU, event-loop p99, simulation tick p99, queued bytes, state expiry/coalescing, pending events, session resume failures, datagram success/fallback/retry, total NIC transfer, and provider-billed egress. Server transport counters do not include full network overhead or all handshake traffic.
+
+Keep UDP optional, but do not hide a missing native dependency. `RTC=1` fails startup if native support is unavailable. A connection that uses WS fallback is a valid compatibility result, not proof that the UDP deployment works.
+
+## Measurement plan
+
+Use a staging VPS with the intended memory/CPU allocation. Run 50 clients from a different machine with your actual game simulation and visible-entity density. Record busy and idle behavior separately. Do not infer capacity from the localhost lab's server+clients combined CPU.
+
+Use OS-level network impairment on machines you control to test both protocols with real transport behavior. The deterministic test harness injects application-level drops/reordering and does not model actual TCP congestion control. Never label that as cellular measurement.
+
+Use two physical devices for remote input-to-pixel latency, or a calibrated camera/capture method. Report measurement error, render buffering, and clock assumptions. A snapshot's interpolation error at a delayed timestamp is not its error relative to the other player's present position.
+
+## STUN and TURN
+
+Players reach your server's UDP port directly: the server has a public address, so the browser's connectivity checks
+arrive from wherever the player is and no relay is needed for ordinary home, office or cellular NAT. Some networks
+block UDP outright (some corporate and school Wi-Fi, some hotel captive portals); those players stay on the
+WebSocket, which works everywhere HTTPS does. TURN helps one more group: networks that block UDP to arbitrary ports
+but allow it (or TURN over TLS on 443) to a relay.
+
+Give clients ICE servers from the server so you can rotate them without a new build:
+
+```js
+import { turnCredentials, cloudflareTurn } from 'twinwire/server';
+// your own coturn (use-auth-secret, static-auth-secret=...): credentials expire after ttlSeconds
+iceServers: session => [
+  { urls: 'stun:turn.mygame.com:3478' },
+  turnCredentials({ secret: process.env.TURN_SECRET, user: session.id.slice(0, 8),
+    urls: ['turn:turn.mygame.com:3478?transport=udp', 'turns:turn.mygame.com:443?transport=tcp'] }),
+],
+// or Cloudflare's managed relay (anycast, UDP/TCP/TLS 443), cached until shortly before expiry
+iceServers: cloudflareTurn({ keyId: process.env.CF_TURN_KEY_ID, apiToken: process.env.CF_TURN_TOKEN }),
+```
+
+Relayed traffic counts against the relay's bandwidth (your VPS's for coturn, Cloudflare's pricing otherwise). Add
+TURN once you've measured players stuck on the WebSocket path (`server.metrics().ws`) who would benefit.
+
+On a VPS behind 1:1 NAT (some clouds give the instance a private address), set `publicIp` on the native factory so
+its host candidates carry the public address, or add a STUN server to the factory's own `iceServers`.
+
+## Health endpoint
+
+`server.metrics()` returns sessions, connections, how many are on rtc vs ws, bytes each way, pending events and
+protocol errors: serve it from your `http` handler on `/health`.

package/docs/RELEASE-CHECKLIST.md

@@ -0,0 +1,25 @@
+# Release checklist
+
+For maintainers, before tagging `vX.Y.Z` (the tag publishes to npm: `.github/workflows/release.yml`).
+
+- [ ] `npm ci && npm run check` (build, all tests, 0 skipped).
+- [ ] `npm run test:native`: datagrams selected, fallback and recovery in the same session.
+- [ ] `npm run test:browser`, `IMPAIR=1 npm run test:browser`, `RTC=0 npm run test:browser`: Chromium, Firefox, WebKit.
+- [ ] `npm run test:example` and `RTC=1 npm run test:example`.
+- [ ] `npm audit` clean; `npm pack --dry-run` lists only `dist`, docs, README, LICENSE, CHANGELOG.
+- [ ] Wire change? `VERSION` bumped in `src/core/protocol.ts`, and the change called out in CHANGELOG.md.
+- [ ] `validation/STATUS.md` updated with what actually ran; `CHANGELOG.md` has the version's entry.
+- [ ] `version` in package.json matches the tag.
+
+# Before you ship a game on it
+
+Things a library's tests can't establish for your game:
+
+- Safari on the oldest iOS you support and the newest, on a real phone: Wi-Fi and cellular, the hand-off between them,
+  screen lock, backgrounding, reload and page restore.
+- Your server corrects invalid movement and judges hits by its own rules; nothing private leaks through snapshots,
+  interest filtering, broadcasts or reconnects.
+- Actions that must happen exactly once (purchases, transfers) carry an action id and are stored with their result.
+- Your simulation, serialization and traffic stay inside their frame budget at the player counts you expect, on the
+  machine you'll run (`tools/bench.mjs` for the transport; your own world for the rest).
+- Your monthly transfer fits your host's allowance (`npm run budget`).

package/package.json

@@ -1,6 +1,102 @@
 {
   "name": "twinwire",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Multiplayer networking for browser games: one resumable session on two wires (WebSocket + WebRTC datagrams), reliable events at UDP latency, delta snapshots, a lobby with codes, quick play and ready-up, and netcode helpers. Works in every browser, iPhone Safari included.",
+  "keywords": [
+    "multiplayer",
+    "netcode",
+    "game",
+    "gamedev",
+    "webrtc",
+    "websocket",
+    "datachannel",
+    "udp",
+    "lobby",
+    "matchmaking",
+    "snapshot-interpolation",
+    "client-side-prediction",
+    "turn",
+    "stun",
+    "browser",
+    "safari"
+  ],
+  "homepage": "https://github.com/studiokimeiga/twinwire#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/studiokimeiga/twinwire.git"
+  },
+  "bugs": {
+    "url": "https://github.com/studiokimeiga/twinwire/issues"
+  },
+  "author": "Studio Kimeiga",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    },
+    "./netcode": {
+      "types": "./dist/netcode/index.d.ts",
+      "import": "./dist/netcode/index.js"
+    },
+    "./browser": {
+      "import": "./dist/browser/twinwire.mjs",
+      "default": "./dist/browser/twinwire.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "docs"
+  ],
+  "scripts": {
+    "build": "npm run clean && tsc -p tsconfig.json && node tools/bundle.mjs",
+    "check": "npm run build && npm test",
+    "test": "node --test --test-concurrency=1 test/*.test.mjs",
+    "test:browser": "node tools/browser-e2e.mjs",
+    "test:native": "node tools/native-rtc-test.mjs",
+    "bench": "node tools/bench.mjs",
+    "budget": "node tools/budget.mjs",
+    "demo": "node examples/arena/server.mjs",
+    "prepack": "npm run build",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run check && npm run test:native",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "example": "node examples/party/server.mjs",
+    "test:example": "node tools/party-e2e.mjs"
+  },
+  "dependencies": {
+    "ws": "^8.18.3"
+  },
+  "peerDependencies": {
+    "node-datachannel": ">=0.33.4 <0.34.0"
+  },
+  "peerDependenciesMeta": {
+    "node-datachannel": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "esbuild": "^0.28.2",
+    "node-datachannel": "^0.33.4",
+    "playwright": "^1.63.0",
+    "typescript": "~5.8.3"
+  }
+}