@genex-ai/multiplayer 0.17.0 → 0.17.6

package/README.md

@@ -581,7 +581,8 @@ not the page a friend should land on. Any parameter name works except the platfo
 (`embed`, `ref`, `s`, `from`, `remix`, `slug`, and everything starting `genex_`).
 
 `joinPrivate` rejects when the code does not lead to a lobby this player can reach: it has
-closed, or its host is on another region's relay than this player's nearest one. Catch it
+closed, or (only where the regional relays do not share presence) its host is on another
+region's relay than this player's nearest one. Catch it
 and show the menu. Keep the typed code as the second way in: a shell that does not pass the
 link's parameter on yet opens the game without it.
 
@@ -604,6 +605,269 @@ for (const e of JSON.parse(drainEventsJson(h))) { /* { type: 'playerJoined', id
 Pages with no bundler load `dist/bridge.global.js` (the SDK and embed-sdk bundled in), which sets
 `window.GenexMultiplayerBridge`. A JS game should use the SDK directly, not the bridge.
 
+*(0.17.3, contract version 2)* A server-authoritative game (below) drives its room through the
+bridge's authority calls instead — `openAuthority`, `setInput`, `predictProjectile` (your shot, drawn
+the frame you fire it; `''` without a seat or while it reconnects), `setWorld` (a `firstperson` or
+`vehicle` room's collision world, 0.17.4), `frame` (your predicted entity and every other one,
+interpolated, as one JSON string per render frame), `authorityJson`,
+`drainAuthorityEventsJson`, `closeAuthority`, `disposeAuthority` — from
+`@genex-ai/multiplayer/bridge/authority`, or on a page from `dist/bridge-authority.global.js`, which is
+`bridge.global.js` plus these calls (a relay game keeps loading the smaller script).
+
+```js
+const h = GenexMultiplayerBridge.openAuthority(JSON.stringify({ gameId: 'my-game', urls: [] }));
+// every render frame:
+GenexMultiplayerBridge.setInput(h, JSON.stringify({ moveX: 1, moveY: 0, yaw: aim, buttons: 0 }));
+const { me, entities } = JSON.parse(GenexMultiplayerBridge.frame(h));
+for (const e of JSON.parse(GenexMultiplayerBridge.drainAuthorityEventsJson(h))) { /* joined, message, … */ }
+```
+
+## Server-authoritative rooms — `@genex-ai/multiplayer/authority` *(0.17.2; firstperson, vehicle and projectiles 0.17.4)*
+
+Protocol 4 ([`PROTOCOL.md` §17](./PROTOCOL.md#17-authority-rooms-protocol-4)): the server runs the
+game's own room module at a fixed tick, clients send typed input and render what the server writes.
+Use it when cheating matters (competitive play); everything above is the relay and is unchanged by it.
+The authority servers are not live yet; only a local development server serves these rooms.
+
+```ts
+import { connectAuthority } from '@genex-ai/multiplayer/authority';
+import * as genexEmbed from '@genex-ai/embed-sdk';
+
+await genexEmbed.waitForPlayer();
+const s = await connectAuthority({
+  urls: genexEmbed.getAuthorityUrls(),       // the authority cluster, NOT getColyseusUrls()
+  regions: genexEmbed.getAuthorityRegions(), // its regions: the nearest is joined (PROTOCOL.md §17.1)
+  room: 'my-game',
+  auth: () => genexEmbed.getColyseusAuth(),
+});
+
+function loop(now: number) {
+  s.input.moveX = right - left;              // [-1, 1]
+  s.input.moveY = up - down;
+  s.input.yaw = aimAngle;                    // radians
+  s.input.buttons = firing ? 1 : 0;          // your bitmask, < 2^24
+  s.frame(now);                              // FIRST: sends due inputs, predicts, interpolates
+  const me = s.me();                         // your entity, predicted (no input delay)
+  for (const e of s.entities().values()) draw(e.id, e.x, e.y, e.yaw);   // others ~100 ms behind
+  requestAnimationFrame(loop);
+}
+requestAnimationFrame(loop);
+s.on('hit', (data) => flash(data));          // events your room module emits
+```
+
+- **Input, not state.** `s.input` is sent once per fixed step (the room's tick rate) while you call
+  `frame()`; nothing is sent while you do not. There is no heartbeat.
+- **Prediction.** When the room runs a movement preset (`topdown`, `firstperson` or `vehicle`), your own entity
+  moves the instant you press, with the same step the server runs, and is corrected smoothly when the
+  server disagrees.
+  Pass `predict: { step, fields }` for your own step, or `predict: false` to render the server's state.
+  When your entity respawns (its `epoch` changes) it snaps to the server's new pose and keeps the
+  inputs still in flight, which the server applies to the new life, so moving through a death costs no
+  correction. `s.telemetry` counts `inputsSent`, `inputsDropped`, `reconciles`, `visibleCorrections`
+  (> 0.05 units), `peakCorrection` and `reseeds` (respawns of your entity and reconnects, never counted
+  as corrections). `s.prediction` says whether your entity is predicted right now, and why not
+  (`off`, `no_entity`, `no_preset`, `world_mismatch`).
+- **`firstperson`** ([§17.7](./PROTOCOL.md#177-movement-presets)) is Source-engine movement through a
+  static world of boxes and ramps, z up: friction, ground and air acceleration (air-strafing), jump,
+  duck and crouch-jump, a free step up ledges, staying on the ground down slopes and stairs, sliding
+  along walls; a ramp too steep to stand on is a wall. Ask for `tickHz: 60`: air-strafing turns the
+  wish direction once per input, so at 30 Hz a perfect strafe gains less than half of what it does at
+  60 (sub-steps do not change that). Send `moveX`/`moveY` in WORLD axes (turn your
+  camera-relative keys by your view yaw yourself; the step has no trigonometry), `yaw`/`pitch` as the
+  aim, and jump / duck / walk on `buttons` (1, 2, 4 by default). Give the session the module's world —
+  `connectAuthority({ …, world })` or `s.setWorld(world)` before the first `frame()` — the same
+  `{ boxes: [[minX, minY, minZ, maxX, maxY, maxZ], …], ramps: [[…, axis, lo, hi], …] }` the module
+  exports: it is validated (`WorldError` when §17.7 refuses it) and hashed, and your entity is
+  predicted only while that hash is the room's `params.world`. Otherwise it renders from the server's
+  state, and `s.prediction.reason` is `world_mismatch`. Entities then also carry `pitch` (within the
+  preset's ±`pitchLimit`), `duck` (0 standing .. 1 ducked; derive the eye height from it), `mstate`
+  (`MoveState` bits: 1 onGround, 2 ducking, 4 jumpHeld) and `cap` (the speed multiplier the module
+  writes: a ceiling on the speed, never a weaker push, so a wound cannot freeze a player), predicted
+  for yours and interpolated for others. `firstpersonWorld(spec)` validates and
+  hashes a world, and `stepFirstperson` is the step itself.
+- **`vehicle`** ([§17.7](./PROTOCOL.md#177-movement-presets)) is an arcade car on Rocket League's
+  ground and air handling, kept level (no pitch or roll): throttle, braking and coasting, boost from a
+  fuel tank, grip that turns the velocity with the heading (`driftGrip` while drift is held, so the
+  tail slides), a turn rate that grows with speed up to `turnSpeed` and mirrors in reverse, a jump and
+  steering in the air. It drives the same hull through the same world as `firstperson` (walls clip
+  the velocity along them, nothing bounces), so it takes the same `world` / `setWorld` and predicts
+  only while the hashes match. Axes: x/y is the ground, z is up, and `yaw` is the heading,
+  counterclockwise seen from above (+yaw turns left; yaw 0 faces +x). The heading is the BODY's
+  state, not input: send `moveY` as the throttle (below 0 reverses) and `moveX` as the steer, where
+  **+1 turns right, toward −yaw** (your steer-right key is `moveX = +1`, as for any other right input),
+  and jump / boost / drift on `buttons` (1, 2, 4 by default); `yaw`, `pitch` and `moveZ` are unused.
+  Ask for `tickHz: 60`. Entities then also carry `spin` (the yaw rate, rad/s, positive toward +yaw:
+  for wheels and skid marks) and `fuel` (the tank, 0..1), predicted for yours and the server's latest
+  for others; your own heading draws along the short arc across ±π. The module writes `fuel` to
+  refuel (a boost pad, a respawn: `fuel: 1, spin: 0, mstate: 0` with an `epoch` bump) and `cap` to
+  scale both top speeds; the step only burns fuel. `stepVehicle` is the step itself. It turns the
+  heading with `psin` / `pcos`, §17.7's portable sine and cosine (exported here), which every engine
+  computes to the same bits; the platform's `Math.sin` / `Math.cos` differ in the last bit between
+  engines and would desynchronize prediction.
+- **Entities** carry `kind`, `owner`, `x y z yaw` (rendered), `vx vy vz`, `hp`, `flags`, `epoch`,
+  `data` (JSON text), the projectile fields `t0`, `g`, `src`, the firstperson fields `pitch`,
+  `duck`, `mstate`, `cap` and the vehicle fields `spin`, `fuel`. A changed `epoch` is a teleport: it snaps, never glides. Another player's snap
+  lands when its render time (100 ms behind) reaches the bump, the time lag compensation judges a shot
+  at; until then it is drawn where it was, and `epoch` reports the life drawn.
+- **Projectiles** ([§17.9](./PROTOCOL.md#179-projectiles)) are entities with a launch tick `t0 > 0`,
+  a gravity `g` and their shooter's seat `src` (`''` for a server one). Each is drawn from its
+  closed-form flight (`projectileAt`), never interpolated: another player's at the server's present,
+  not 100 ms behind. Fire your own with `s.predictProjectile({ kind, x, y, z, vx, vy, vz, g })` while
+  staging the input that fires: it is drawn that same frame under the id the room module's launch
+  gets (`<seat>.<seq>.<n>`), keeps that id when the server's projectile confirms it, and flies on
+  from where the prediction was; one the server re-launches as its own (a bounce) is drawn at the
+  server's present from then on. One no state ever shows (refused, or removed by a hit before a patch
+  carried it) is dropped as soon as the server acknowledges the input that fired it, one whose input
+  a drop lost at the reconnect's first state (the next shot reuses its id), and at the latest after
+  max(2·RTT, 600 ms). While the socket is down (`reconnecting` until `reconnected`) it predicts
+  nothing and answers `''`: no input goes out then. Every client in a room that launches projectiles must implement §17.9: an
+  older one draws each projectile frozen at its launch point.
+  A projectile is never `me()`. `s.telemetry` counts `projectilesPredicted`, `projectilesConfirmed`,
+  `projectilesRejected` and the latest `lastProjectileLeadMs`. The module side is
+  `ctx.projectiles.launch / at / sweep`.
+- **Physics rooms** ([§17.10](./PROTOCOL.md#1710-physics)): the server simulates rigid bodies and
+  this session draws them; nothing on the client steps physics. Every join sends the `physics@1`
+  capability, which a physics room requires (426 without it). A body entity (one with a descriptor in
+  the state's `bodies`) comes out of `entities()` with `body: true`, its drawn orientation in
+  `qx qy qz qw` (z up) and the server's `sleep` flag; its `x y z` are the server's present, not
+  100 ms behind: the latest state (the body at the patch's tick + 1) extrapolated on the room clock
+  by its velocities (at most 250 ms, back a tick at most before its tick, not at all while asleep), and a newer state eased in from where
+  the older one was drawn (the offset decaying as e^(−age / 100 ms)). An `epoch` bump, a correction
+  over one metre or a body's first state snaps. A body out of this client's view is still listed,
+  held at its last state, until its descriptor goes. `vx vy vz` on a body are its linear velocity in
+  room units/s. `s.telemetry` counts `bodyStates`, `bodySnaps` and `peakBodyCorrection`. The drawing
+  is `physics-draw.ts` (`bodyStateOf`, `extrapolateBody`, `receiveBodyState`, `drawBody`), held to
+  the netcode bench's `physics-draw.json` vectors. A body entity is never `me()`. The module side is
+  `config.physics` and `ctx.physics` (commands, queries answered next tick, events, `body(key)` for
+  subscribed kinds); the wire and the reference tables are `wire.ts` and `physics.ts`. No Genex server
+  runs physics until the pinned core ships. `s.setPhysics(hash)` (or `connectAuthority({ …, physics })`)
+  names a physics world your client runs a copy of; `s.physics.reason` is `physics_mismatch` while the
+  room's hash differs.
+- **Physics prediction** ([§17.11](./PROTOCOL.md#1711-physics-prediction)): give the session the core,
+  `connectAuthority({ …, world, physicsCore: async () => { const p = await import('@genex-ai/physics');
+  await p.init(); return p; } })`, and in a predicting room (the default for physics rooms) it steps the
+  bodies near you in a world of its own and draws them at your present (`predicted: true` on their
+  view); the core loads only once the room sends keyframes, and `wasmSimdSupported()` says when to pass
+  the non-SIMD module instead. `predictPhysics: false` turns it off; `s.physicsPrediction` reports
+  `status` (`on`, `off`, `loading`, `unavailable`, `mismatch`, `self_test`, `diverged`, `cpu`), how
+  keyframes were adopted, the slowest and latest replay and how many held a 60 Hz frame back
+  (`peakResimMs`, `lastResimMs`, `slowResims`), and how often the replay budget fell back to `cpu` and came back
+  (`fallbacks`, `recoveries`: `cpu` probes a replay every 500 ms and turns prediction on again after
+  four calm ones). The budget is the device's (4 ms desktop, 5 mobile); `physicsBudgetMs` overrides it
+  when it is a finite number over 0 (benches and CI on a slow host; a game leaves it unset). Remote players move by their velocity or, in a room asking
+  `remotePredict: 'inputDecay'`, by their last input repeated with decay (`'hold'`: held). Module commands are not
+  predicted, except the rules the module writes as pure functions and hands the client too:
+  `contacts(a, b)`, a seat contact rule (a car-to-car bump) run in your own entity's prediction
+  against the other seats, and `bodyRule({ tick, seats, body })`, a body rule (a scripted hit on a
+  ball) run before every step of the client world, and `kinematicRule(key, tick)`, where the module
+  poses its kinematic bodies (a door, a moving floor) at each tick, so the client world moves them as
+  the room does and draws them as predicted bodies (and by the rule on the server's timeline whenever
+  it does not predict them: no core, `cpu`); the module must run the same functions. Held to
+  the netcode bench's `physics-predict.json` (tolerance 0 on the client stateHash) and
+  `seat-contacts.json`. With `contacts`, `seatDrawing` chooses how other seats are drawn:
+  `predicted` (default, the Rocket League model) on your car's clock, every other seat stepped by the
+  room preset under its last input (`remotePredict: 'hold'` holds it) with the module's whole contact
+  pass (`contactPass`, else `contacts` on every pair) run on every seat and yours, each correction
+  eased in as a decaying offset that keeps the drawn velocity and never pulls a seat back against its
+  motion (`drawTick()`, `drawLead()` say where they were drawn); `separate` on
+  the render timeline but moved out of your drawn entity by the rule and taken round it, never across
+  it (draw-only); `timeline` on the render timeline only (a seat that missed yours on the server can
+  be drawn through it). `predicted` and `separate` keep every seat out of yours and out of each other
+  ([§17.11 *Drawing other seats*](./PROTOCOL.md#1711-physics-prediction)). A room whose module
+  declares `config.contacts` (the universal contact policy: a genre preset such as `shooter` or
+  `vehicle-arena`, a contact shape and per-pair rules by tag, §17.11 *Contact policy*) needs no
+  `contacts` or `contactPass`: given neither, the session runs the declared policy the state carries
+  as both, in your prediction, the seat prediction, the physics replay and the drawing guard. The
+  authority host runs the same pass on the server after each tick's preset steps and before the
+  module's `step`, so the module writes no contact code at all (and must not run a pass of its own).
+- **Input repeat** is a room setting ([§17.11 *Input pacing*](./PROTOCOL.md#1711-physics-prediction),
+  *The setting*): `config.inputs: { preset?, repeat? }`, `repeat` (`'on'` or `'off'`) as given, else
+  the genre preset's (`inputs.preset`, else `config.contacts.preset`), else on; `vehicle-arena` is off,
+  `shooter`, `platformer`, `party` and `physics-sandbox` on (`INPUT_PRESETS`). On, a starved seat's
+  held input is repeated and the session compares your prediction at
+  `reconcileThrough(held, ack, inRep, sent)` (`ack + inRep` once sent; past the inputs sent, a hitch,
+  it waits at the input it compared at last) and throttles after a starve; off, the room holds a starved seat
+  and the session reads the plain ack and never throttles. The session reads the room's setting from
+  the state's preset text (`presetInputRepeat`); a bad `config.inputs` is refused by its path.
+- **Reconnection** is automatic and in place, as for `connect()`; `reconnecting`, `reconnected` and
+  `disconnect` fire as there. An input that came due while the socket was down is dropped, never
+  replayed. `leave()` during an outage still leaves: it stops reconnecting, and a retry already under
+  way leaves the moment it lands.
+- **The fast channel** ([§17.12](./PROTOCOL.md#1712-the-fast-channel-fast1)), Node clients for now
+  (bots, the netcode bench, tests): `connectAuthority({ …, fast: openUdpFastSocket })` with
+  `openUdpFastSocket` from `@genex-ai/multiplayer/authority/fast-udp` asks for `fast@1`. In a room that
+  offers it your inputs go by UDP datagram, each one in several (a lost datagram costs nothing), and the
+  room's motion comes back as per-seat ack-delta snapshots written into the same state a patch writes,
+  so prediction, reconcile and interpolation run unchanged; a WebSocket held up by a lost TCP segment
+  no longer holds them. Join, events and the rest of the state stay on the WebSocket. With no snapshot
+  1 s after the first datagram or 2 s after the last, a binding it cannot use, or the server's
+  `__fast:off`, the seat goes on by WebSocket for the rest of the socket, every input sent stepped
+  once and every motion field at the WebSocket's latest value. `s.fast` says `live`, `snapshots` and `fallback` (its reason). The browser's WebTransport
+  opener comes later; a room without the channel plays exactly as before.
+- **Lag compensation.** Every input tells the server what you saw: other entities `renderDelayMs`
+  (default 100) in the past, whether or not your own entity is predicted.
+- **Every server message** also reaches `onEvent(type, data)` when you pass it, in order and with no
+  name withheld (`on(type)` skips the session's own event names) — for a facade forwarding them all.
+- **Refusals** reject `connectAuthority` with the server's error; branch on `err.code` (`JoinError`):
+  402 the game's owner is not entitled to authority rooms (final; not retried), 424 no room module is
+  published, 429 the owner's room quota refused a new room, 426 this package is too old for the
+  server (update and republish). 503 (no capacity) is retried after 1, 2 and 4 s (`capacityRetryMs`).
+
+A game's server code is one module typed by `@genex-ai/multiplayer/authority/module`, which has no
+dependencies so it can be bundled alone:
+
+```ts
+import { defineRoom } from '@genex-ai/multiplayer/authority/module';
+
+export default defineRoom({
+  contract: 1,
+  config: { tickHz: 30, preset: { name: 'topdown' } },
+  init: () => ({}),
+  onJoin: (ctx, player) => { ctx.entities.spawn({ kind: 'player', owner: player.id }); },
+  onLeave: (ctx, player) => { const e = ctx.entities.ownedBy(player.id); if (e) ctx.entities.remove(e.id); },
+  onInput: () => {},
+  step: () => {},
+});
+```
+
+A `firstperson` room exports its collision world beside its config; the server validates it at init
+and writes its hash into the resolved preset's `params.world`, and the game client passes the same
+world to `setWorld`:
+
+```ts
+import { defineRoom } from '@genex-ai/multiplayer/authority/module';
+import world from './world.json';            // { boxes: [[…6], …], ramps: [[…9], …] }, shared with the client
+
+export default defineRoom({
+  contract: 1,
+  config: { tickHz: 60, preset: { name: 'firstperson' } },
+  world,
+  init: () => ({}),
+  onJoin: (ctx, player) => { ctx.entities.spawn({ kind: 'player', owner: player.id, z: 0 }); },
+  onLeave: (ctx, player) => { const e = ctx.entities.ownedBy(player.id); if (e) ctx.entities.remove(e.id); },
+  onInput: () => {},
+  step: () => {},
+});
+```
+
+A `vehicle` room exports its world the same way, and refuels on a respawn:
+
+```ts
+import { defineRoom } from '@genex-ai/multiplayer/authority/module';
+import world from './arena.json';            // the floor, walls and ramps, shared with the client
+
+export default defineRoom({
+  contract: 1,
+  config: { tickHz: 60, preset: { name: 'vehicle' } },
+  world,
+  init: () => ({}),
+  onJoin: (ctx, player) => { ctx.entities.spawn({ kind: 'car', owner: player.id, z: 0, fuel: 1 }); },
+  onLeave: (ctx, player) => { const e = ctx.entities.ownedBy(player.id); if (e) ctx.entities.remove(e.id); },
+  onInput: () => {},
+  step: () => {},
+});
+```
+
 ## Rules of thumb
 
 - **`me` / `shared` are synced; everything else is local.** Movement input → mutate a local object → `me.set` it on the tick.

package/dist/authority/fast-udp.d.ts

@@ -0,0 +1,13 @@
+import { F as FastSocketOpener } from '../fast-client-CZ41v-oB.js';
+import '../module-DqtFb5wA.js';
+
+/** The host (an IPv6 host unbracketed) and port of a `udp://host:port` url, else null: the url is
+ *  server-supplied, so anything more than a host and a port in 1..65535 is refused. */
+declare function udpEndpoint(url: string): {
+    host: string;
+    port: number;
+} | null;
+/** A {@link FastSocketOpener} for `udp://` urls on node:dgram; null for any other url. */
+declare const openUdpFastSocket: FastSocketOpener;
+
+export { openUdpFastSocket, udpEndpoint };

package/dist/authority/fast-udp.js

@@ -0,0 +1,52 @@
+// src/authority/fast-udp.ts
+import { createSocket } from "dgram";
+var UDP_SCHEME = "udp:";
+var PORT_MAX = 65535;
+var CONNECT_QUEUE_MAX = 32;
+var BARE_PATHS = ["", "/"];
+var onlyHostAndPort = (u) => u.username === "" && u.password === "" && BARE_PATHS.includes(u.pathname) && u.search === "" && u.hash === "";
+function udpEndpoint(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return null;
+  }
+  const port = Number(parsed.port);
+  const portOk = Number.isInteger(port) && port >= 1 && port <= PORT_MAX;
+  if (parsed.protocol !== UDP_SCHEME || !portOk || parsed.hostname === "" || !onlyHostAndPort(parsed)) return null;
+  return { host: parsed.hostname.replace(/^\[(.*)\]$/, "$1"), port };
+}
+var openUdpFastSocket = (url, receive) => {
+  const to = udpEndpoint(url);
+  if (to === null) return null;
+  const socket = createSocket(to.host.includes(":") ? "udp6" : "udp4");
+  let connected = false;
+  let closed = false;
+  let waiting = [];
+  socket.on("message", (msg) => receive(new Uint8Array(msg.buffer, msg.byteOffset, msg.byteLength)));
+  socket.on("error", () => {
+  });
+  socket.connect(to.port, to.host, () => {
+    connected = true;
+    if (!closed) for (const bytes of waiting) socket.send(bytes);
+    waiting = [];
+  });
+  const fast = {
+    send(bytes) {
+      if (closed) return;
+      if (connected) socket.send(bytes);
+      else waiting = [...waiting, bytes].slice(-CONNECT_QUEUE_MAX);
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      socket.close();
+    }
+  };
+  return fast;
+};
+export {
+  openUdpFastSocket,
+  udpEndpoint
+};

package/dist/authority/fast-webtransport.d.ts

@@ -0,0 +1,45 @@
+import { a as FastBindMessage, F as FastSocketOpener } from '../fast-client-CZ41v-oB.js';
+import '../module-DqtFb5wA.js';
+
+/** Hex digits of one certificate hash (SHA-256). */
+declare const FAST_WT_HASH_HEX_DIGITS = 64;
+/** Hashes one binding may carry (the relay sends its current and next certificate's). */
+declare const FAST_WT_HASHES_MAX = 4;
+/** A `wt` binding this client can open: its url and the certificate hashes as bytes. */
+interface FastWebTransportTarget {
+    url: string;
+    hashes: Uint8Array[];
+}
+/** The WebTransport `wt` of a binding this client can use, else null: an `https://` url with a host and
+ *  no credentials, query or fragment, and 1..{@link FAST_WT_HASHES_MAX} hashes of
+ *  {@link FAST_WT_HASH_HEX_DIGITS} lowercase hex digits. The binding is server-supplied, so anything
+ *  else is refused. */
+declare function fastWebTransportOf(bind: Pick<FastBindMessage, 'wt'>): FastWebTransportTarget | null;
+/** The part of the browser's `WebTransport` the opener uses. */
+interface WebTransportLike {
+    readonly ready: Promise<unknown>;
+    readonly closed: Promise<unknown>;
+    /** `pending`, `reliable-only` or `supports-unreliable` where the browser exposes it. */
+    readonly reliability?: string;
+    readonly datagrams: {
+        readonly readable: ReadableStream<Uint8Array>;
+        readonly writable: WritableStream<Uint8Array>;
+        readonly maxDatagramSize?: number;
+    };
+    close(info?: {
+        closeCode?: number;
+        reason?: string;
+    }): void;
+}
+/** `new WebTransport(url, options)`. */
+type WebTransportConstructor = new (url: string, options: Record<string, unknown>) => WebTransportLike;
+/** The options a fast@1 session opens with. */
+declare function webTransportOptions(target: FastWebTransportTarget): Record<string, unknown>;
+/** A {@link FastSocketOpener} on `WebTransport` (the browser's, or a stand-in in tests): null when the
+ *  binding has no usable `wt` or there is no WebTransport. */
+declare function webTransportFastOpener(WebTransport: WebTransportConstructor | undefined): FastSocketOpener;
+/** The browser's opener: the global `WebTransport` (null where there is none, so the seat stays on the
+ *  WebSocket). */
+declare const openWebTransportFastSocket: FastSocketOpener;
+
+export { FAST_WT_HASHES_MAX, FAST_WT_HASH_HEX_DIGITS, type FastWebTransportTarget, type WebTransportConstructor, type WebTransportLike, fastWebTransportOf, openWebTransportFastSocket, webTransportFastOpener, webTransportOptions };

package/dist/authority/fast-webtransport.js

@@ -0,0 +1,124 @@
+import {
+  fromHex
+} from "../chunk-5JGRFT2N.js";
+import "../chunk-K3SF5VDS.js";
+import "../chunk-ZSWF4VCN.js";
+
+// src/authority/fast-webtransport.ts
+var FAST_WT_HASH_HEX_DIGITS = 64;
+var FAST_WT_HASHES_MAX = 4;
+var WT_SCHEME = "https:";
+var CONNECT_QUEUE_MAX = 32;
+var HASH_PATTERN = /^[0-9a-f]+$/;
+var RELIABLE_ONLY = "reliable-only";
+function fastWebTransportOf(bind) {
+  const wt = bind.wt;
+  if (typeof wt !== "object" || wt === null) return null;
+  const { url, hashes } = wt;
+  if (typeof url !== "string" || !Array.isArray(hashes)) return null;
+  if (hashes.length === 0 || hashes.length > FAST_WT_HASHES_MAX) return null;
+  const hashOk = (h) => typeof h === "string" && h.length === FAST_WT_HASH_HEX_DIGITS && HASH_PATTERN.test(h);
+  if (!hashes.every(hashOk)) return null;
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return null;
+  }
+  const bare = parsed.username === "" && parsed.password === "" && parsed.search === "" && parsed.hash === "";
+  if (parsed.protocol !== WT_SCHEME || parsed.hostname === "" || !bare) return null;
+  return { url, hashes: hashes.map((h) => fromHex(h)) };
+}
+function webTransportOptions(target) {
+  return {
+    serverCertificateHashes: target.hashes.map((value) => ({ algorithm: "sha-256", value })),
+    requireUnreliable: true,
+    allowPooling: false,
+    congestionControl: "low-latency"
+  };
+}
+var carriesFast = (t) => t.reliability !== RELIABLE_ONLY;
+var SocketState = { Connecting: "connecting", Open: "open", Failed: "failed", Closed: "closed" };
+function webTransportFastOpener(WebTransport) {
+  return (_url, receive, bind) => {
+    const target = bind === void 0 ? null : fastWebTransportOf(bind);
+    if (target === null || WebTransport === void 0) return null;
+    let t;
+    try {
+      t = new WebTransport(target.url, webTransportOptions(target));
+    } catch {
+      return null;
+    }
+    let state = SocketState.Connecting;
+    let waiting = [];
+    let writer = null;
+    const fail = () => {
+      if (state === SocketState.Closed || state === SocketState.Failed) return;
+      state = SocketState.Failed;
+      writer = null;
+      waiting = [];
+      try {
+        t.close();
+      } catch {
+      }
+    };
+    const write = (w, bytes) => void w.write(bytes).catch(() => {
+    });
+    const readAll = async (reader) => {
+      for (; ; ) {
+        const r = await reader.read();
+        if (r.done) return;
+        if (state === SocketState.Open) receive(r.value);
+      }
+    };
+    t.ready.then(
+      () => {
+        if (state !== SocketState.Connecting) return;
+        if (!carriesFast(t)) return fail();
+        state = SocketState.Open;
+        const w = t.datagrams.writable.getWriter();
+        writer = w;
+        for (const bytes of waiting) write(w, bytes);
+        waiting = [];
+        readAll(t.datagrams.readable.getReader()).then(fail, fail);
+      },
+      () => fail()
+    );
+    t.closed.then(fail, fail);
+    const socket = {
+      send(bytes) {
+        if (state === SocketState.Open && writer !== null) write(writer, bytes);
+        else if (state === SocketState.Connecting) waiting = [...waiting, bytes].slice(-CONNECT_QUEUE_MAX);
+      },
+      close() {
+        if (state === SocketState.Closed) return;
+        const was = state;
+        state = SocketState.Closed;
+        writer = null;
+        waiting = [];
+        if (was === SocketState.Failed) return;
+        try {
+          t.close();
+        } catch {
+        }
+      },
+      failed: () => state === SocketState.Failed,
+      // The browser's outgoing limit, known once the session is open: the browser sends only uplinks,
+      // so the seat's largest uplink must fit (Chromium reports 1024; a 120 Hz seat's is 889).
+      maxDatagramBytes() {
+        const size = state === SocketState.Open ? t.datagrams.maxDatagramSize : void 0;
+        return typeof size === "number" ? size : void 0;
+      }
+    };
+    return socket;
+  };
+}
+var openWebTransportFastSocket = (url, receive, bind) => webTransportFastOpener(globalThis.WebTransport)(url, receive, bind);
+export {
+  FAST_WT_HASHES_MAX,
+  FAST_WT_HASH_HEX_DIGITS,
+  fastWebTransportOf,
+  openWebTransportFastSocket,
+  webTransportFastOpener,
+  webTransportOptions
+};