@genex-ai/multiplayer 0.17.6 → 0.17.8

package/README.md

@@ -213,7 +213,9 @@ self-heal on the next publish, and lost `send()` events / inputs are counted in
 Render `reconnecting`/`reconnected` as an overlay and keep your loop running. `disconnect` is terminal
 (server restart, revoked session `4401`, or the link never recovered `4003`): read a fresh token and
 `connect()` again. A deliberate `leave()` never reconnects. The relay also broadcasts `server:restart` right before
-a deploy — flush saves when you see it.
+a deploy — flush saves when you see it. An authority session (`connectAuthority`) does more: a deploy or a dead server
+moves its seat to a fresh room by itself, on the same session object, saying `draining`, `rejoining` and `rejoined`
+(PROTOCOL.md §17.13), and its `disconnect` means it is over for good.
 
 **One seat per player:** the relay enforces a single session per identity per room — a
 second tab / device / reloaded page supersedes the previous session (old one gets
@@ -627,7 +629,7 @@ for (const e of JSON.parse(GenexMultiplayerBridge.drainAuthorityEventsJson(h)))
 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.
+Genex's authority servers serve these rooms in production (Asia, EU and US); `npx genex-authority-dev start` serves the same module locally.
 
 ```ts
 import { connectAuthority } from '@genex-ai/multiplayer/authority';
@@ -664,7 +666,9 @@ s.on('hit', (data) => flash(data));          // events your room module emits
   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
+  (a move of your place past 5 cm: 0.05 × the room's `lengthUnit`, else the preset's implied unit), `peakCorrection`
+  (the largest such move, room units; velocity and angles are never in it), `peakStateCorrection` (the largest
+  correction of any other mirrored field, each in its own unit: only zero or not says anything) 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
@@ -739,8 +743,8 @@ s.on('hit', (data) => flash(data));          // events your room module emits
   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 })`)
+  subscribed kinds); the wire and the reference tables are `wire.ts` and `physics.ts`. Genex's authority
+  servers run these rooms on the pinned core. `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,
@@ -780,8 +784,11 @@ s.on('hit', (data) => flash(data));          // events your room module emits
   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).
+- **Letting a held body go.** A module that holds a body with `cap` 0 and lifts it unannounced lifts it for inputs on their
+  way, so a held stick lurches by about speed × round trip. Announce the tick (a countdown does anyway) and give the session a
+  `seatRule` that sets `cap` on it (§17.11 *Seat rules*): every seat starts on one tick, and no correction, measured on UDP.
 - **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 setting*): `config.inputs: { preset?, repeat?, settleMs? }` (`settleMs`: §17.11 *A quiet seat*), `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
@@ -793,17 +800,24 @@ s.on('hit', (data) => flash(data));          // events your room module emits
   `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
+- **The fast channel** ([§17.12](./PROTOCOL.md#1712-the-fast-channel-fast1)), on by default: over UDP for Node
+  clients (bots, the netcode bench, tests) and over WebTransport in a browser, with nothing to pass.
+  `connectAuthority({ … })` asks for `fast@1`, `fast: false` turns it off,
+  and `openUdpFastSocket` from `@genex-ai/multiplayer/authority/fast-udp` is there to wrap. One line per join
+  names the transport and any fallback (`session.fast.line`; stderr, or `fastLog`). 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.
+  no longer holds them. Join, events and the rest of the state stay on the WebSocket. The seat moves only
+  once the path is proven, with the WebSocket carrying everything until then, so a network that blocks UDP
+  loses no input. 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, every input sent stepped once and every
+  motion field at the WebSocket's latest value, and comes back by itself when the path does (retrying from
+  1 s up to every minute, with jitter). A seat with nothing to send keeps its channel with an empty datagram
+  every 250 ms, and a NAT rebinding or a Wi-Fi to mobile move keeps it on UDP. `s.fast` says `live`,
+  `snapshots`, `fallbacks`, `returns` and `fallback`: why the seat is on the WebSocket now (`no-webtransport`,
+  `no-relay`, `not-offered`, `unreachable`, `handshake`, `stall`, `server`). 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
@@ -868,6 +882,13 @@ export default defineRoom({
 });
 ```
 
+### A level as a world: `@genex-ai/multiplayer/world-fit`
+
+A world for `firstperson` or `vehicle` from a real level, at build time: `readGltfLevel(path)` reads a glb or glTF and
+`sceneFromThree(scene)` (`@genex-ai/multiplayer/world-fit/three`, no Node in it) reads a three.js scene, both into the same scene
+file ([WORLD-SCENE.md](WORLD-SCENE.md)) for `genex world fit`. Node names or `extras.genex` say what collides, on which channel and
+where a spawn is; a file is hostile input and a refusal names what to change: [WORLD-GLTF.md](WORLD-GLTF.md).
+
 ## Rules of thumb
 
 - **`me` / `shared` are synced; everything else is local.** Movement input → mutate a local object → `me.set` it on the tick.

package/WORLD-GLTF.md

@@ -0,0 +1,109 @@
+# A level from a glb, a glTF or a three.js scene
+
+Two doors to the same [scene file](WORLD-SCENE.md), so a level from any engine with a glTF exporter reaches `genex world fit`:
+
+```sh
+genex world gltf level.glb level.scene.json    # no flags: a level says what it needs in its own extras
+```
+
+```ts
+import { sceneFromThree } from "@genex-ai/multiplayer/world-fit/three";
+const { json, notes } = sceneFromThree(gltf, { scale: 39.37 });   // a THREE.Scene, an Object3D or what GLTFLoader gave you
+```
+
+One level gives one scene by either door: `packages/netcode-bench/test/authority/world-gltf-three.test.ts` holds a level
+through `GLTFLoader` and `sceneFromThree` to the reader's scene, value for value. Same file, same bytes and hash on Mac, Linux
+and Windows (`world-gltf.yml`). Library: `readGltfLevel(path)` and `runWorldGltf(args)` in `@genex-ai/multiplayer/world-fit`. `genex world gltf` exits 0, 1 on a call
+that is not one and 3 on a refused level, as `genex world fit` does.
+
+## Space and units
+A glTF is metres, y up, right-handed. A three.js scene is y up too. Everything comes out in the room's axes, z up, handedness
+kept: drawing space `(X, Y, Z)` is the room's `(X, −Z, Y)`, the same turn as drawing a room's body at `(x, z, −y)`. Coordinates land
+on a grid of 1/256 of a unit, then float32, so no path to a number shows.
+
+- **The reader** scales metres by `unitsPerMeter`, 39.37 (Source units) unless the glTF scene's `extras.genex.unitsPerMeter` says
+  otherwise. A game in metres sets it to 1.
+- **The helper** scales by its `scale` option, default 1: a game that draws the server's numbers as they are. A model loaded in
+  metres and not scaled in the scene is `{ scale: 39.37 }`; a model with `model.scale.setScalar(39.37)` is already there.
+- **Hull**: `extras.genex.hull` on the scene (`radius`, `height`, `crouchHeight`, `step`, `jump`, `leap`, room units). Left out, the
+  fit sizes the Source defaults from `unitsPerMeter`. Make it your room's own parameters if they differ.
+
+## Marks
+A mesh collides, on both channels, unless it is marked. Any exporter can say all of these in a node's name; Blender, three.js and
+anything that writes custom properties can say them in `extras.genex` (`userData.genex` in three.js), and those win. A parent passes
+its mark to what hangs under it; a child's own mark wins.
+
+| Name starts with | `extras.genex` | Meaning |
+|---|---|---|
+| | | Collides: stops a hull and a bullet |
+| `nocol_` | `{ "collide": "none" }` | Only drawn: art beside a collision proxy, a sky dome, a banner, a character |
+| `clip_` | `{ "collide": "move" }` | Clip wall: stops a hull, a bullet passes |
+| `shot_` | `{ "collide": "shot" }` | Stops a bullet, a hull passes |
+| `box_` | `{ "shape": "box" }` | Its bounds as one box |
+| `hull_` | `{ "shape": "hull" }` | The convex hull of its points, up to 4,096 |
+| | `{ "shape": "mesh" }` | Triangles, no box looked for |
+| `movable_` | `{ "movable": true }` | Moves or disappears at run time: named in the fit's report, never in the world |
+| `prop_` | `{ "prop": true }` | May be cut when a budget runs out |
+| `spawn_` | `{ "spawn": true }` | Where a player starts: the node's origin, on or just over the floor. Its own mesh does not collide. `spawn_Red_1` is the spawn `Red_1` |
+| | `{ "tags": ["red"] }` | Carried to the actor or spawn for the game |
+
+Prefixes stack in any case: `CLIP_box_Fence.001`. A misspelled mark is refused rather than ignored.
+Hidden objects still collide: that is what a collision proxy usually is. Mark what is only for show.
+
+What else it works out, so an exporter never has to:
+- **A closed cube is an exact box**, on the world's axes or turned, even inside a merged mesh, and under negative scale. A cube
+  sheared by a non-uniform parent is the exact hull of its corners. A cube flattened by a scale of zero is the plane left.
+- **A node an animation moves is movable**, with what hangs under it. In three.js, pass the loaded `gltf`, not `gltf.scene`, so it can see the animations.
+- **An instanced mesh is every instance** (`EXT_mesh_gpu_instancing`, `THREE.InstancedMesh`). **An LOD is its nearest level.**
+- **Quantized positions** (`KHR_mesh_quantization`) read as the numbers they mean. **Strips and fans** are triangles; points and lines are no surface.
+
+## Refusals
+A file is hostile input. Every refusal is a `LevelRefusal` with a `code` and a message naming the node or field and what to do; the
+scene is not written and an existing one stays. The reader's table is `packages/multiplayer/test/world-gltf-hostile.test.ts`.
+
+| Code | What it says |
+|---|---|
+| `not_gltf`, `bad_container`, `bad_version` | Not a glb or glTF 2; chunks that do not add up |
+| `bad_reference`, `bad_accessor`, `bad_index`, `bad_value`, `not_finite` | An index naming nothing; an accessor that does not fit or is sparse; an index past its vertices; a bad transform; NaN or infinity |
+| `node_cycle` | A cycle, or a node with two parents |
+| `too_large` | Past a limit below |
+| `compressed` | Draco (`KHR_draco_mesh_compression`) or meshopt (`EXT_meshopt_compression`, `KHR_meshopt_compression`) on something that collides. Not decoded here: re-export without it, or load it in three.js and use `sceneFromThree`, whose loader decodes it. Compressed art marked `nocol_` is no problem |
+| `unknown_extension` | A required extension this cannot honour, by name |
+| `uri_refused` | A buffer URI that leaves the input's folder or is not a plain file: a parent segment, an absolute path, a scheme, a host, a backslash, an encoded trick, a link leading outside (by realpath), a FIFO. Nothing outside the folder is read and nothing touches the network. Image URIs are never read at all |
+| `skinned`, `morphed` | A skinned or morph-posed mesh that collides: a world is static. Mark it `nocol_` beside a static proxy, or `movable_` |
+| `unsupported` | A `THREE.BatchedMesh` that collides |
+| `degenerate` | A mesh with no triangle of any area left. A few among real ones are dropped and counted in `notes` |
+| `non_manifold` | More than 64 triangles on one edge, which no surface has. Ordinary non-manifold edges are kept and counted in `notes`: the scene format reads a surface, open or closed |
+| `no_spawn`, `no_surface`, `bad_mark` | What it says |
+
+Limits, each checked before anything is decoded for it: 1 GiB a file or buffer and for all buffers together, 8,000,000 triangles with
+instances counted, 24,000,000 vertices an accessor, 1,000,000 nodes, depth 1,024. Past them, give what no one walks on a `nocol_` mark
+or a collision proxy.
+
+## The whole path
+```sh
+genex world gltf level.glb level.scene.json          # or write sceneFromThree's json to that file
+genex world fit level.scene.json world.json          # the §17.7 world, and what it cost and changed
+```
+Then the world is one file both sides import: `defineRoom({ …, world })` in the module, `connectAuthority({ …, world })` on the
+client. Draw the glb as it is, in the same units: the world is made from it, not drawn. A spawn from the scene is where `onJoin` puts a seat.
+
+`packages/netcode-bench/demo/level-walk/` is this path on a real page: `courtyard.glb` (`conformance/authority/world-scene/`,
+written by its `courtyard.reference.mjs`), fitted, in a local `genex-authority-dev` room, two three.js seats and a Rust seat walking it.
+`packages/netcode-bench/test/authority/world-gltf-route.test.ts` walks the same routes with no browser.
+
+### three.js in a game
+Run the helper wherever the level already exists. A Node build script needs no browser: `new GLTFLoader().parse(arrayBuffer, "", …)`
+for a glb with embedded buffers, or a `Scene` built in code. In a page, hand a creator the file:
+```ts
+const url = URL.createObjectURL(new Blob([sceneFromThree(gltf, { scale: 39.37 }).json], { type: "application/json" }));
+```
+Do this once, at build time, and import what the fit wrote: never fit or re-export in a player's page, or one float's difference
+turns prediction off (`world_mismatch`).
+
+### Rust, or any engine with a glTF exporter
+1. Export the level as a glb in metres, with the marks above. Blender: *Include > Custom Properties* writes `extras`; names are always kept.
+2. `genex world gltf level.glb level.scene.json`, then `genex world fit level.scene.json world.json`.
+3. Rust: `FirstpersonWorld::from_json_str(include_str!("../assets/world.json"))` and `session.set_world(world)`; the module exports the
+   same file. Draw with `engine = (g.x, g.z, −g.y)`. `sdks/rust/genex-multiplayer/examples/level_walk.rs` does this against a room:
+   hash equal to the room's, predicted, no correction. A game in metres sets `unitsPerMeter` to 1 and every distance in its params.

package/WORLD-SCENE.md

@@ -0,0 +1,135 @@
+# The world scene format
+
+What an engine's exporter writes and `genex world fit` reads: a level as collision surfaces, in world space, with no
+engine in it. Reader and checks: `src/world-fit/scene.ts` (`parseWorldScene`); a small example every exporter can
+compare with: `../netcode-bench/conformance/authority/world-scene/sample.json`. A glb, a glTF or a three.js scene becomes this
+file with no exporter to write: [WORLD-GLTF.md](WORLD-GLTF.md).
+
+Exporters: Unity (`sdks/unity/README.md`, *From a level to a world*).
+
+```json
+{
+  "format": "genex-world-scene",
+  "version": 1,
+  "unitsPerMeter": 39.37,
+  "source": { "engine": "unity", "level": "Yard" },
+  "hull": { "radius": 16, "height": 72, "crouchHeight": 54, "step": 18, "jump": 57, "leap": 189 },
+  "actors": [
+    { "name": "Ground", "surfaces": [
+        { "kind": "box", "center": [0, 0, -16], "half": [2000, 2000, 16] } ] },
+    { "name": "Fence_3", "tags": ["fence"], "surfaces": [
+        { "kind": "box", "center": [100, 40, 44], "axes": [[0.8, 0.6, 0], [-0.6, 0.8, 0], [0, 0, 1]], "half": [32, 2, 44],
+          "channels": ["move"] } ] },
+    { "name": "Rock_1", "tags": ["prop"], "surfaces": [
+        { "kind": "mesh", "vertices": [0, 0, 0, 90, 0, 0, 0, 90, 0, 0, 0, 60], "indices": [0, 1, 2, 0, 1, 3, 1, 2, 3, 2, 0, 3] } ] }
+  ],
+  "spawns": [ { "at": [0, 0, 8], "name": "Red_1", "tags": ["red"] } ]
+}
+```
+
+## Space
+- World space, the room's units, the same axes the game hands the step: **z up**, x and y as §17.7 moves them. An engine
+  with y up converts here, the way it converts everything else it sends the room.
+- `unitsPerMeter` says what a unit is. It sizes the report's areas and, when `hull` is left out, scales the Source
+  defaults. It rescales nothing else.
+- `hull` is the room's own hull: `radius`, `height` (stand), `crouchHeight`, `step`, `jump` (how high a standing jump
+  lifts the feet, `jumpImpulse² / (2·gravity)`) and `leap` (how far a run jump carries, `maxSpeed · 2·jumpImpulse / gravity`).
+  Every tolerance the fit uses comes from these; a scene has no tuning values to set.
+
+## Actors and surfaces
+An actor is what a creator knows by name: a refusal says `Wreck_12`. Write the engine's own name, a path when names repeat.
+Each surface is one of:
+
+| `kind` | Fields | Meaning |
+|---|---|---|
+| `box` | `center`, `half`, `axes?` | An oriented box. `axes` are three orthonormal rows; left out means the world's. A box on the axes stays exact in the fit |
+| `hull` | `points` | The convex hull of up to 4,096 points |
+| `sphere` | `center`, `radius` | |
+| `capsule` | `a`, `b`, `radius` | Any direction |
+| `mesh` | `vertices`, `indices` | Triangles: x y z per vertex, three indices per triangle, wound either way, open or closed |
+| `heightfield` | `origin`, `cell`, `cols`, `rows`, `heights` | `heights[row·cols + col]` at `origin + (col·cell[0], row·cell[1])`, solid below. `null` (NaN in binary) is a hole |
+
+Big arrays may be `{ "f32le": "<base64>" }` (`vertices`, `heights`) and `{ "u32le": "<base64>" }` (`indices`).
+
+Write everything that collides: the fit decides what a hull can reach and drops the rest, so an exporter never prunes.
+
+## Channels
+`channels` on a surface says which traces it answers, and left out means both. `move` stops a hull. `shot` stops a bullet.
+
+| Engine says | Write |
+|---|---|
+| Blocks pawns and traces | leave it out |
+| Clip wall: blocks pawns, not traces | `["move"]` |
+| Shot-only mesh: bullets stop, characters pass | `["shot"]` |
+| Neither | leave the surface out |
+
+`genex world fit` reads `move`, `genex world shots` reads `shot`, from the same file.
+
+## Where a level ends
+`bound` is optional: `{ "min": [x, y], "max": [x, y], "ceiling": z }`, `ceiling` optional. Write it when the level is meant to stop
+somewhere its geometry alone doesn't stop a hull. The fit adds solid of its own, `move` only, named `Bound` in the report and counted
+in the budget: walls outside those edges, tall enough that nothing in the level lifts a hull over, and a lid whose underside is
+at `ceiling`, so a hull's head stays under it. A spawn outside the bound or over the ceiling is refused at its path. Leave it out and
+the level's reach is whatever its geometry gives; the fit doesn't guess where a creator meant it to end.
+
+## Tags
+Free strings on an actor or a surface, carried for the game. The fit reads two:
+- `movable`: moves or disappears at run time. Never in a static world; the report names it.
+- `prop`: may be cut when a budget runs out, as one box a surface, before anything else that costs reach. An exporter tags
+  only what its engine or creator already calls a prop: an actor no wider than eight hull radii counts as one with no tag.
+
+## The shot world
+`genex world shots <scene.json> <shots.json> [--max-boxes <n>] [--max-bytes <n>] [--report <file>] [--json]` writes what a module
+exports as `shotWorld`, `{ boxes, ramps, tolerance }`, or exits 3 and writes none. `fitShotWorld` is the same thing in code. It keeps
+what a muzzle can see from where a hull can be: a surface no hull reaches and a line reaches stays, one no line reaches goes, and that
+is sound on the lattice. A straight line moves one way on each axis, so it stays in the flood of its own octant, which from a yard open
+to the sky does not come back down outside the wall. A source box on the axes stays one box. Anything else gets boxes cut round the
+surface they hold, so a stop is off by less than a cell. The cell is the finest of a ladder (a quarter of the hull's radius, doubling) the
+budget holds. Boxes only: no ramps yet. The report reads rays from where a hull stands, against the source's own triangles: `accuracy`
+(hit or miss, along the ray, and `surface`, how far the fit's stops are from a real surface: along a ray a near miss of an edge
+reads as the whole way to the next wall) and `claims`, what a tolerance is worth by the rule of `ctx.world.claim`: honest claims refused or
+capped, and how far past a real surface the most a claim may say reaches. The world's `tolerance` is `surface` at the 99th percentile.
+It names what moves at run time and what no muzzle sees. It is not fed to any client.
+
+## What `genex world fit` reads and says
+`genex world fit <scene.json> <world.json> [--max-boxes <n>] [--max-ramps <n>] [--report <file>] [--json]` writes the §17.7
+world, or exits 3 and writes none. `@genex-ai/multiplayer/world-fit`'s `fitScene` is the same thing in code. The report gives
+reach lost and extra against the source, how far floors really are from the source's (`floor`: the highest surface under a
+hull's whole footprint, with no cell rounding, at the lattice's points, with the worst ones named), how far walls may recede, how far the reach runs past the level (`reachExtent`, below), the costliest
+actors and, on a refusal, what each would lose as one box. What it models: a square hull walking, stepping, dropping, jumping, crouch jumping and leaping off
+edges. What it does not: a slope a room can't stand on reads as walkable if its steps are, up to a steep one. Steeper, a column a cell
+wide with a face rising a crouching hull's height or more beside it and falling two cells or more on its other side is no floor:
+closed up the face's height and counted in `leanLedges`, so a tall leaning wall is its outer envelope, as wide at its top as at its
+widest, and a true lip under a cell wide goes the same way. Held to leans up to 12 degrees off the vertical; past that a hull can still
+stand on some of a face, because its lips can be a step apart. The floor figures skip the part of that top past the real wall. A door a hull clears by under a
+cell is found on a finer lattice of its own, down to a thirty-second of a cell: open between exact boxes, shut and named in
+`narrowDoorsShut` between walls the fit can't keep exact. The rule for the other way: a gap too narrow for the
+hull in the source never opens, at any rung, and stays shut by `gapMarginUnits`, an eighth of a cell on the radius.
+
+Floors win over budget. Where a coarser rung leaves feet past a radius from the source's floor, repair rounds spend boxes there; if
+feet stay past a radius at worst or half a radius at the 99th percentile, the fit refuses with `floor_over`, writes no world, and
+names who costs the most, as `over_budget` does. `open_slits` is the same for a gap left open: a report with either is never `ok`.
+
+What the floor numbers say, in the scene's units, all against the same reading of the highest surface under a hull's footprint:
+
+| Field | What it is | What can pass it |
+|---|---|---|
+| `floor.p99Units`, `floor.maxUnits` | Source against fit at the lattice's points. These are what the fit holds itself to: half a radius and a radius, or `floor_over` | A real hull rests between lattice points, so a seat's feet can read more than `maxUnits` at an edge, resting on a ledge by a hair |
+| `floor.upperBoundUnits` | The same with the footprint half a cell wider and narrower, which holds every position between the points | Nothing: a seat's feet stay under it. It is a ledge's height wherever a footprint can overlap a ledge by a hair more in one world than the other, so it says little of how a level looks |
+| `floor.edgeFreeUnits` | How far apart the two ranges of height are: nothing if a shift of half a cell can make them read alike | |
+
+So compare a seat's worst feet with `upperBoundUnits`, and its 99th percentile with `p99Units`. A seat over `maxUnits` at an edge rest
+is not a broken fit; a seat over `upperBoundUnits` is.
+
+`reachExtent` says how far the source's reach runs past what the level holds, and is measured whether or not anything is wrong:
+`coreMin` and `coreMax` are the plan of the spawns and every actor but flat ground as wide as the level; `outsideCoreM2` and
+`outsideCorePct` the reach further than a run jump past that, `farthestFromCoreM` how far it gets; `walkedM2` what a hull gets to from
+a spawn with no jump, `beyondWalkPct` the share of the reach only a jump gets to, and `outsideWalkedPct` the share further than a run
+jump past the plan of what walking gets to. `flagged` is true at 25% of either `outsideCorePct` or `outsideWalkedPct`, with no `bound`.
+It never refuses: whether the reach is what the creator meant is theirs to say, with a `bound`.
+
+Spawns are where the hull's reach starts: `at`, with optional `name` and `tags`. A level with no spawn cannot be fitted.
+
+## Compatibility
+`version` is checked and a new meaning is a new version. A reader refuses a bad value with its path (`WorldSceneError`,
+`$.actors[3].surfaces[0].half[1] is below zero`).

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

@@ -1,5 +1,6 @@
-import { F as FastSocketOpener } from '../fast-client-CZ41v-oB.js';
-import '../module-DqtFb5wA.js';
+import { F as FastSocketOpener } from '../fast-client--A88q0kk.js';
+import '../module-CSpXrzFc.js';
+import '../shot-world-D22tqOUT.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. */
@@ -7,6 +8,7 @@ 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;
 

package/dist/authority/fast-udp.js

@@ -1,51 +1,13 @@
+import {
+  udpEndpoint,
+  udpFastOpener
+} from "../chunk-YWQ3ALYY.js";
+
 // 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;
-};
+import { lookup } from "dns";
+import { isIP } from "net";
+var openUdpFastSocket = udpFastOpener({ createSocket, lookup, isIP });
 export {
   openUdpFastSocket,
   udpEndpoint

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

@@ -1,5 +1,6 @@
-import { a as FastBindMessage, F as FastSocketOpener } from '../fast-client-CZ41v-oB.js';
-import '../module-DqtFb5wA.js';
+import { F as FastSocketOpener, a as FastFallbackReason, b as FastBindMessage } from '../fast-client--A88q0kk.js';
+import '../module-CSpXrzFc.js';
+import '../shot-world-D22tqOUT.js';
 
 /** Hex digits of one certificate hash (SHA-256). */
 declare const FAST_WT_HASH_HEX_DIGITS = 64;
@@ -23,7 +24,9 @@ interface WebTransportLike {
     readonly reliability?: string;
     readonly datagrams: {
         readonly readable: ReadableStream<Uint8Array>;
-        readonly writable: WritableStream<Uint8Array>;
+        /** Chromium's way to send; Safari 26 has only `createWritable()`. */
+        readonly writable?: WritableStream<Uint8Array>;
+        createWritable?(): WritableStream<Uint8Array>;
         readonly maxDatagramSize?: number;
     };
     close(info?: {
@@ -38,8 +41,27 @@ declare function webTransportOptions(target: FastWebTransportTarget): Record<str
 /** 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 part of a global scope {@link chooseFastSocket} reads. */
+interface FastSocketScope {
+    WebTransport?: unknown;
+    /** A page has one; */
+    document?: unknown;
+    /** a worker has this. Neither: not a browser (Node). */
+    importScripts?: unknown;
+}
 /** The browser's opener: the global `WebTransport` (null where there is none, so the seat stays on the
  *  WebSocket). */
 declare const openWebTransportFastSocket: FastSocketOpener;
+/** How a seat opens its fast channel, and why it never asks when it does not. */
+interface FastSocketChoice {
+    open: FastSocketOpener | undefined;
+    /** The reason `s.fast` reads from the start. */
+    fallback: FastFallbackReason | null;
+}
+/** The socket for `connectAuthority`'s `fast`: the game's own opener, none when the game said `false`;
+ *  with no word from the game, WebTransport wherever `scope` has it. A browser without it never asks
+ *  (a seat that asks and then cannot open the binding loses the WebSocket inputs it sent before the
+ *  binding, PROTOCOL.md §17.12 *Fallback*), and says so. Node, with neither, is a plain WebSocket seat. */
+declare function chooseFastSocket(given: FastSocketOpener | false | undefined, scope?: FastSocketScope): FastSocketChoice;
 
-export { FAST_WT_HASHES_MAX, FAST_WT_HASH_HEX_DIGITS, type FastWebTransportTarget, type WebTransportConstructor, type WebTransportLike, fastWebTransportOf, openWebTransportFastSocket, webTransportFastOpener, webTransportOptions };
+export { FAST_WT_HASHES_MAX, FAST_WT_HASH_HEX_DIGITS, type FastSocketChoice, type FastSocketScope, type FastWebTransportTarget, type WebTransportConstructor, type WebTransportLike, chooseFastSocket, fastWebTransportOf, openWebTransportFastSocket, webTransportFastOpener, webTransportOptions };

package/dist/authority/fast-webtransport.js

@@ -1,122 +1,19 @@
 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);
+  FAST_WT_HASHES_MAX,
+  FAST_WT_HASH_HEX_DIGITS,
+  chooseFastSocket,
+  fastWebTransportOf,
+  openWebTransportFastSocket,
+  webTransportFastOpener,
+  webTransportOptions
+} from "../chunk-NFMGIKFZ.js";
+import "../chunk-OD6NRSX2.js";
+import "../chunk-2NGXXQDS.js";
+import "../chunk-CSQEEANB.js";
 export {
   FAST_WT_HASHES_MAX,
   FAST_WT_HASH_HEX_DIGITS,
+  chooseFastSocket,
   fastWebTransportOf,
   openWebTransportFastSocket,
   webTransportFastOpener,