@woosh/meep-engine 3.46.0 → 3.49.0

package/src/engine/network/README.md

@@ -7,14 +7,48 @@ server-authoritative rollback orchestrator, layered over a pluggable transport.
 
 | Layer | Pieces | Responsibility |
 | --- | --- | --- |
-| Transport | `transport/adapters/*` (`WebRTCDataChannel`, `WebTransport`, `WebSocket`, `NodeUDP`, `Simulated`, `Loopback`) | Move opaque byte buffers. UDP-style unless `reliable`/`ordered` say otherwise. |
-| Channel | `transport/Channel.js` | Seq + ack-bitfield header; surfaces `onPacketAcked` / `onPacketLost` / `onPayload`. No retransmit. |
-| Reliability / fragmentation | `transport/ReliableCommandPipeline.js`, `transport/fragments/*` | At-least-once commands; MTU fragmentation + NACK retransmit. |
+| Transport | `transport/adapters/*` (`WebRTCDataChannel`, `WebTransport`, `WebSocket`, `NodeUDP`, `Simulated`, `Loopback`) | Move opaque datagrams of at most `max_datagram_bytes`. UDP-style unless `reliable` says otherwise. |
+| Connection | `transport/connection/*` (`Connection`, `TxStream`, `RxStream`, `RangeSet`) | Numbered packets acknowledged by ranges, loss detection and probe timeout after QUIC; unreliable messages of up to a datagram with a delivery notice; reliable lanes for messages of any size up to `max_message_bytes`, paced. Everything for a peer leaves in as few datagrams as fit, once a tick. Design: [`MESSAGE_TRANSPORT.md`](./MESSAGE_TRANSPORT.md). |
 | Sim core | `sim/*` (`ActionLog`, `SimAction`, `SimActionExecutor`, `RewindEngine`, `Snapshotter`, registries) | Record/apply/rewind replicated state mutations. |
 | Replication | `replication/Replicator.js`, `replication/ScopeFilter.js` | Pack/unpack action records per peer, scope-filtered. |
 | Orchestrator | `orchestrator/NetworkPeer.js`, `orchestrator/ServerAuthoritative{Server,Client}.js` | Per-tick send/recv, rollback (server), predict-reconcile (client). |
 | Facade | `NetworkSession.js` | One config + lifecycle surface; wires everything below. |
 
+## What the session assumes, and what a tick costs
+
+The stack is built for fully networked worlds of millions of objects. A tick's cost is in what
+changed and what is owned — never in how many networked entities there are — and that holds only on
+these terms, which the game has to keep:
+
+- **Every replicated change goes through the host's action executor.** An action — `send`, a
+  client's input — carries its own change. A system that writes a replicated component directly
+  (physics moving its bodies, a controller) reports each write:
+  `dataset.sendEvent(entity, "net_mutate_component", { component_type })`. The host records the
+  component as it stands, at full precision — the wire's quantised image is never written back into
+  the host's state. **A write nobody reports stays on the host**: the session never looks for
+  changes by itself. (Until 2026-10-15 it compared every replicated component of every networked
+  entity at the end of each host step: 7–8 ms a tick for 20,000 entities with nothing changing.)
+- **Ownership is set when a `NetworkIdentity` attaches, or by the join** — never by writing
+  `owner_peer_id` or `network_id` afterwards. Each peer's owned entities are indexed when ownership
+  is set; what a tick does per owned entity (AUTH_STATE to its owner, the client's record of what it
+  predicted) walks that index.
+
+Measured (one-component trees, one client, 30 Hz, Node 22, ms per tick):
+
+| | ms |
+| --- | --- |
+| Host, 20,000 entities, nothing changing, client synced | 0.01–0.02 (was 14–15) |
+| Client, 20,000 entities, nothing changing | 0.02 (was 0.7) |
+| Host, 100 / 1,000 actions a tick, building them included | 0.4 / 3.8 |
+| Client, applying 100 / 1,000 actions a tick | 1.3 / 4.2 |
+
+What does scale with the world, by design:
+
+- **A join** sends every networked entity once per joining peer, paged and paced; host memory per
+  joiner is the lane's window and 12 bytes an entity (`MESSAGE_TRANSPORT.md` §3.7).
+- **Interpolation**: every networked entity gets an `Interpolated`, and the `InterpolationSystem`
+  records and blends each one every frame (below). Not measured at this scale.
+
 ## Smooth by default
 
 A game that wires a `NetworkSession` the obvious way renders smoothly at any display rate, with
@@ -47,10 +81,9 @@ nothing else to set up. What that takes, and where it lives:
   `Interpolated.snap` for a teleport (`PhysicsSystem.setPose` sets it), or
   `InterpolationSystem.restore()` / `session.normalize_if_dirty()` before writing the truth. A write
   over a blend without either is a write to a drawn pose, and the next step puts the truth back.
-- **The host publishes what changed.** Replicated components the host's simulation wrote directly
-  (physics, controllers) are published at the end of each step, recorded without being written
-  back — the host keeps full precision — and nothing an action already carried is sent twice.
-  `publish_changes: false` to publish by hand.
+- **What travels is what goes through the executor** (see "What the session assumes" above):
+  actions, and direct writes reported with `net_mutate_component`, which the host records without
+  writing them back — the host keeps full precision.
 - **Clients reconcile by comparison** (`reconcile: 'correct'`, the default): the host's state for
   frame S is compared with what the client predicted for S, and a component that differs is
   carried into the present by its `Correction` (`network/correction`) — the session knows no
@@ -62,7 +95,13 @@ nothing else to set up. What that takes, and where it lives:
   the action-log rewind + replay, exact for simulations made only of deterministic actions.
 - **Late input is applied, not rolled back** (`late_input: 'apply'`, host default). Input
   buffering (`simulation_delay_ticks`) and time dilation keep input on time; the client's per-tick
-  `FRAME_MARKER` keeps the dilation honest when it sends no input.
+  `FRAME_MARKER` keeps the dilation honest when it sends no input. Input older than the host's
+  window (`frame_capacity`) is dropped and reported (`onPendingActionDropped`, `'window'`).
+- **A record is known by its frame and its place in it, never by its bytes.** The action stream
+  re-sends every unconfirmed frame each tick; the host tells the copies from new input by
+  `(sender, frame, ordinal)`, the ordinal being the record's index in the sender's frame, carried
+  on the wire. Two inputs alike in every byte — a held key, frame after frame, or two identical
+  actions in one frame — are two inputs, late and folded into one host frame or not.
 
 Things the session cannot fix for the game:
 
@@ -94,34 +133,71 @@ connection:
   is ever sent, on this connection or a later one that resumes it: that input was predicted on a
   world that is gone. The client's input starts at the frame the snapshot sets its counter to.
 
-The first answer is the answer. The host sends each `INITIAL_SYNC` more than once, against loss,
-and a host that has finished with a client's old session readmits its new connection as a fresh
-peer before it reads the `RESUME_HELLO` on it — so a `RESUME_REJECT` can arrive after the snapshot it
-announces. A client acts on neither once the connection has its answer: the copies would put what it
-owns back behind input it has already sent, and the reject would throw away the token the snapshot
-issued.
+The first answer is the answer. A host that has finished with a client's old session readmits its
+new connection as a fresh peer before it reads the `RESUME_HELLO` on it — so a `RESUME_REJECT` can
+arrive after the snapshot it announces. The snapshot's first page is the answer: a client acts on no
+later accept or reject on that connection, and the reconnect ladder stops there, so a join that takes
+a while is not torn down and restarted by the next attempt.
 
 The host keeps to the same rule from its side, because what a peer can make it do has to be bounded
 by what the host decided, not by how often the peer asks. It answers a connection's `RESUME_HELLO`
-once and ignores any later one on that connection, and it sends a connection its `INITIAL_SYNC` —
-the copies against loss included — once, when it takes the connection for a fresh peer: as it binds
-it, or after refusing the connection's claim to resume. Each is the whole world, serialized; no
-number of claims buys another. A connection here is a transport the host binds with `connect()`, so
+once and ignores any later one on that connection, and it gives a connection one join, when it takes
+the connection for a fresh peer: as it binds it, or after refusing the connection's claim to resume.
+A join is the whole world, once, and then what changed while it was going out, for at most eight
+rounds; no number of claims buys another. A peer that drops before its join finished is never
+resumed: it holds part of a world. A connection here is a transport the host binds with `connect()`, so
 a reconnect has to reach the host as a new one — the fresh transport a `transport_factory` returns,
 bound once the host has seen the old one end. One that lands on a connection the host still holds
 is a second claim on that connection, and is not sent the world again.
 
-A chunk of a fragmented message that goes missing — of an `INITIAL_SYNC`, typically — is re-sent when
-the receiver asks with a `NACK_FRAGMENT`, and that repair is bounded the same way. A NACK re-sends
-each chunk of the message at most once however many times it names it, and nothing for an index the
-message does not have; the host answers three NACKs per message. So repair adds at most three copies
-of any message the host chose to send.
+### Joining a world of any size
+
+A join is pages of whole entities on the connection's paced BULK lane, each built when it is sent;
+what is lost is re-sent by the lane. The host holds the joining peer's action stream and AUTH_STATE
+meanwhile. A round that goes out within one tick is built at one frame D and is the last: the FINAL
+page follows it, and the action stream is released from D + 1. The first round — the whole world —
+gets one tick's budget (256 KiB); a larger world goes out over as many ticks as the lane's window
+takes, and when it has all arrived, every entity changed since its page — by an action the host's
+executor ran — or created since, is the next round, which may fill the lane. The client holds the
+action stream and AUTH_STATE from `connect()` until its world is whole, applies each page as it
+lands, and on FINAL seeks its frame counter to the host's newest frame, forgets what it predicted on
+the partial world, applies what it held, releases its own input and fires `onSynced`. Host memory
+per joining peer is the lane's window and 12 bytes per entity; client memory is a page and what it
+holds, at most `max_queued_bytes`.
+
+### A client that stalls
+
+A client in a background tab takes no steps (`Ticker` suspends, and discards the gap when the tab
+returns), and neither does one under a debugger or with the lid shut; the host runs on, and what it
+sent is waiting in the client's held transport. Two things happen on the first steps back, keyed on
+what the session sees and never on the page's visibility:
+
+- **More than the host's input window behind** (`frame_capacity`, 32 frames), the client re-takes the
+  host's time — the host names its frame in every TIME_DILATION packet — exactly as a snapshot sets
+  it: the counter moves to the host's frame plus the lead, what was predicted on the old numbering is
+  dropped, and input starts again from there. `stall_count` counts these. Inside the window the time
+  dilation closes the gap on its own, at 5% of a frame per frame, with the input applied late
+  meanwhile. Measured before the rule: 20 × the stall to recover, and every input trimmed until the
+  gap was inside the window.
+- **Silent past `connection_timeout_ms`**, the client has been reaped into the host's grace window and
+  its transport closed, so the close is waiting behind the held packets: the reconnect ladder runs on
+  the first step back, and the host, whose log no longer reaches the client's last ack, sends its
+  world again. A transport with no close of its own (`NodeUDP`) leaves the client to find out through
+  its own silence budget, which runs on frame time and so starts again when the client does.
+
+### A connection that breaks
+
+A connection does not authenticate datagrams; its transport delivers only the peer's (DTLS, TLS, and
+`NodeUDP` by source address). When a connection stops being whole — a peer past its limits, or an
+acknowledgement of a packet never sent, the mark of a datagram that was not the peer's — the session
+handles it as a dropped transport and closes the transport: the host puts the peer in its grace
+window and the client resumes on a new connection. See [`MESSAGE_TRANSPORT.md`](./MESSAGE_TRANSPORT.md) §3.9.
 
 ## Wired automatically by `NetworkSession`
 
-`NetworkPeer` (and through it `Channel`, `Replicator`, `ActionLog`,
-`SimActionExecutor`, the registries, `ReplicationSlotTable`, `Baseline`,
-the fragment layer, and `ReliableCommandPipeline`), the two orchestrators
+`NetworkPeer` (and through it a `Connection` per peer, `Replicator`, `ActionLog`,
+`SimActionExecutor`, the registries, `ReplicationSlotTable`, `Baseline`, and the
+host's `HostJoin`s), the two orchestrators
 (and through them `RewindEngine` and `InputRing`), plus `TimeDilation`,
 `AdaptiveRenderDelay`, `RenderPlayout`, `InterpolationLog`, `NetworkSystem`,
 `NetworkIdentity`, `Snapshotter`, `SmoothingState` (through the
@@ -149,7 +225,7 @@ If you wire one of these into the facade, move its row up to the section above.
 
 ## Deferred / known gaps
 
-- **Congestion control / send pacing** — there is none on the meep-owned send
-  path. Masked on the browser transports (DTLS/SCTP, TLS/TCP do it underneath);
+- **Congestion control** — the send rate is a fixed token bucket
+  (`send_rate_bytes_per_second`); nothing adapts it to the link. Masked on the browser transports (DTLS/SCTP, TLS/TCP do it underneath);
   only matters for raw `NodeUDP` / `Simulated` on constrained links. Design and
   rationale for the deferral are in [`CONGESTION_CONTROL.md`](./CONGESTION_CONTROL.md).

package/src/engine/network/SMOOTHNESS_DESIGN.md

@@ -92,7 +92,15 @@ avoided is corrected again by the next AUTH_STATE).
 The action-log rewind + replay path stays, as an opt-in (`reconcile: 'replay'`), for games whose
 predicted state is entirely produced by deterministic `SimAction`s and that want exactness.
 
-**The host publishes what changed.** At the end of every host step, each replicated component of
+**Superseded 2026-10-15: the host no longer looks for changes.** What follows describes the
+end-of-step comparison as built. It cost every host tick a pass over every networked entity — 7–8 ms
+for 20,000 entities with nothing changing — and the stack is for worlds of millions. It is gone: what
+travels is what goes through the executor, actions and direct writes reported with
+`net_mutate_component`, which the host records (`executor.record`, no write-back, D9's second half
+kept fixed). A direct write nobody reports stays on the host — D9's first half is the contract now,
+stated in the README's "What the session assumes".
+
+**The host publishes what changed** (as built, superseded above). At the end of every host step, each replicated component of
 each networked entity is encoded with its replication adapter and compared with what was last
 published; changed ones go out as `ReplaceComponentAction` records. They are recorded without
 applying (the host's live state is not overwritten with its quantised wire image — D9) and
@@ -171,9 +179,9 @@ path stays for `ServerAuthoritativeServer` users and for `reconcile: 'replay'` s
   no component type, and no physics. `POSE_CORRECTION` (Transform64, through physics for a body,
   hidden by `InterpolationSystem.correct`), `VELOCITY_CORRECTION` and `HOST_VALUE_CORRECTION` are
   given. `reconcile: 'correct' | 'replay'`, default `'correct'`.
-- Host: publishes changed replicated state at the end of each step, against a baseline of what the
-  peers hold that every executed action also updates; `late_input: 'apply' | 'rollback'`, default
-  `'apply'`.
+- Host: ~~publishes changed replicated state at the end of each step~~ (removed 2026-10-15: what
+  travels is what goes through the executor; a reported direct write is recorded, not executed);
+  `late_input: 'apply' | 'rollback'`, default `'apply'`.
 
 ### Orchestrators
 - `ServerAuthoritativeServer`: `begin_tick(frame)` / `end_tick()` split, so the EM's systems run
@@ -204,7 +212,7 @@ path stays for `ServerAuthoritativeServer` users and for `reconcile: 'replay'` s
   the next step. This was the rule for interpolated physics bodies already; it now holds for every
   `Interpolated` entity. **Behaviour change** for code that relied on the old absence of any restore
   for non-physics entities.
-- Peer ids are `[0, 252]`; 253 is `SENDER_RECORDED`.
+- Peer ids are `[0, 251]`; 252 is `SENDER_CORRECTED`, 253 is `SENDER_RECORDED`.
 - `PhysicsSystem.interpolationLog` is deprecated (ignored, warns once).
 - Wire format: a new `FRAME_MARKER` packet; nothing else.
 - `scene-editor`'s `RemotePresence` (the only in-repo `registerSource` user) needed one change: a

package/src/engine/network/diagnostics/BandwidthMeter.d.ts

@@ -1,6 +1,6 @@
 /**
  * Aggregates `getStats()` snapshots from one or more named sources (typically
- * a `Transport`, `Channel`, or `NetworkPeer.channel_for(peer)`) and reports
+ * a `Transport`, or `NetworkPeer.connection_for(peer)`) and reports
  * recent throughput rates.
  *
  * Per-source stats are queried via the source's `getStats()` method. A "sample"

package/src/engine/network/diagnostics/BandwidthMeter.js

@@ -2,7 +2,7 @@ import { assert } from "../../../core/assert.js";
 
 /**
  * Aggregates `getStats()` snapshots from one or more named sources (typically
- * a `Transport`, `Channel`, or `NetworkPeer.channel_for(peer)`) and reports
+ * a `Transport`, or `NetworkPeer.connection_for(peer)`) and reports
  * recent throughput rates.
  *
  * Per-source stats are queried via the source's `getStats()` method. A "sample"

package/src/engine/network/orchestrator/HostJoin.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Bytes of entity records a page is filled to. A page is a BULK message, so this is also how much
+ * the receiver holds of a join at a time. An entity larger than this is a page by itself.
+ */
+export const JOIN_PAGE_BYTES: number;
+/**
+ * Bytes of pages the first round — the whole world — may queue in one tick to finish there. A
+ * round that finishes in one tick is the join's last: every entity it carries is at the same
+ * frame, and every entity it leaves out is unchanged since its state went out, so the receiver
+ * holds the whole world at that frame. A world larger than this goes out over several ticks, paced
+ * by the lane's window, and a catch-up round follows.
+ *
+ * A catch-up round always tries to finish in its tick, with what the BULK lane may still hold as
+ * its budget: what changed while a world went out is a fraction of it, and a round that may only
+ * page would never shrink for a world that changes faster than a tick's budget.
+ */
+export const JOIN_FINAL_ROUND_BYTES: number;
+/**
+ * Catch-up rounds a join may take before it is given up. A catch-up round finishes in its tick
+ * unless what changed outgrows what the BULK lane may hold, so a join that needs more than one or
+ * two is a world changing faster than a peer can be sent it.
+ */
+export const JOIN_MAX_ROUNDS: 8;
+/**
+ * What a join has to say after {@link HostJoinadvance }.
+ */
+export type JoinProgress = number;
+/**
+ * What a join has to say after {@link HostJoin#advance}.
+ * @readonly
+ * @enum {number}
+ */
+export const JoinProgress: Readonly<{
+    /** Pages are going out, or the host is waiting to hear they arrived. */
+    Sending: 0;
+    /**
+     * The FINAL page has arrived: the peer holds the whole world. (Its action stream was released
+     * when FINAL was queued.)
+     */
+    Done: 1;
+    /** The world changed faster than it could be sent, round after round: drop the peer. */
+    DidNotConverge: 2;
+}>;
+/**
+ * The host's side of one peer joining: the world, sent as pages built when they go out, then what
+ * changed meanwhile, until the peer holds every entity's state at one frame. See
+ * `network/MESSAGE_TRANSPORT.md`, "Joining a world of any size".
+ *
+ * 1. The peer's action stream is held from the start (the caller holds it).
+ * 2. A round starts with a list of entities. If its pages fit {@link JOIN_FINAL_ROUND_BYTES}, they
+ *    all go in the tick the round starts, at that frame D; the FINAL page follows them, and the
+ *    peer's action stream is released from D + 1. The join is over. (The stream's datagrams can
+ *    overtake the last pages; the peer holds the stream until FINAL — `NetworkPeer.hold_inbound`.)
+ * 3. Otherwise the round's pages go out over as many ticks as it takes, each built at the frame it
+ *    is sent, while the BULK lane has less than {@link window_bytes} unacknowledged. Each entity's
+ *    network id is noted with the frame its state was sent at. Host memory: the window, and 8
+ *    bytes per entity.
+ * 4. When every page of such a round has arrived, every networked entity is checked: one changed
+ *    since its state was sent (`NetworkPeer.last_changed_frame`), or created since, is the next
+ *    round's list. An empty list ends the join with the FINAL page alone.
+ *
+ * The first round is the world. For a world that fits one tick's budget, the join is one tick.
+ *
+ * Built per join; allocates its id list and send-frame table once and grows them, nothing per tick.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class HostJoin {
+    /**
+     * @param {{
+     *   peer: import("./NetworkPeer.js").NetworkPeer,
+     *   peer_id: number,
+     *   session_token: Uint8Array,
+     *   world: import("../../ecs/EntityComponentDataset.js").EntityComponentDataset,
+     *   for_each_entity: function(function(number): void): void,
+     *   page_buffer: BinaryBuffer,
+     *   window_bytes: number,
+     * }} options
+     *   `for_each_entity(cb)` visits every networked entity id. `page_buffer` is scratch the caller
+     *   may share between joins. `window_bytes` is how far ahead of the peer's acknowledgements
+     *   pages are built.
+     */
+    constructor({ peer, peer_id, session_token, world, for_each_entity, page_buffer, window_bytes }: {
+        peer: import("./NetworkPeer.js").NetworkPeer;
+        peer_id: number;
+        session_token: Uint8Array;
+        world: import("../../ecs/EntityComponentDataset.js").EntityComponentDataset;
+        for_each_entity: (arg0: (arg0: number) => void) => void;
+        page_buffer: BinaryBuffer;
+        window_bytes: number;
+    });
+    peer: import("./NetworkPeer.js").NetworkPeer;
+    peer_id: number;
+    session_token: Uint8Array;
+    world: import("../../ecs/EntityComponentDataset.js").EntityComponentDataset;
+    for_each_entity: (arg0: (arg0: number) => void) => void;
+    page_buffer: BinaryBuffer;
+    window_bytes: number;
+    /** Catch-up rounds taken so far. */
+    get round(): number;
+    /**
+     * One tick of the join, at `frame` — the frame just simulated and published.
+     * @param {number} frame
+     * @returns {JoinProgress}
+     */
+    advance(frame: number): JoinProgress;
+    #private;
+}
+import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
+//# sourceMappingURL=HostJoin.d.ts.map

package/src/engine/network/orchestrator/HostJoin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HostJoin.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/orchestrator/HostJoin.js"],"names":[],"mappings":"AAKA;;;GAGG;AACH,qCAAyC;AAEzC;;;;;;;;;;GAUG;AACH,4CAAiD;AAEjD;;;;GAIG;AACH,gCAAiC;;;;2BAKvB,MAAM;AAHhB;;;;GAIG;AACH;IACI,wEAAwE;;IAExE;;;OAGG;;IAEH,wFAAwF;;GAEzF;AAOH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH;IAcI;;;;;;;;;;;;;OAaG;IACH,iGAbW;QACV,IAAQ,EAAE,OAAO,kBAAkB,EAAE,WAAW,CAAC;QACjD,OAAW,EAAE,MAAM,CAAC;QACpB,aAAiB,EAAE,UAAU,CAAC;QAC9B,KAAS,EAAE,OAAO,qCAAqC,EAAE,sBAAsB,CAAC;QAChF,eAAmB,gBAAoB,MAAM,KAAG,IAAI,KAAG,IAAI,CAAC;QAC5D,WAAe,EAAE,YAAY,CAAC;QAC9B,YAAgB,EAAE,MAAM,CAAC;KACtB,EAgBH;IAVG,6CAAgB;IAChB,gBAAsB;IACtB,0BAAkC;IAClC,4EAAkB;IAClB,+BAboC,MAAM,KAAG,IAAI,KAAG,IAAI,CAalB;IACtC,0BAA8B;IAC9B,qBAAgC;IAMpC,oCAAoC;IACpC,oBAEC;IAED;;;;OAIG;IACH,eAHW,MAAM,GACJ,YAAY,CA6DxB;;CAkFJ;6BA9Q4B,sCAAsC"}

package/src/engine/network/orchestrator/HostJoin.js

@@ -0,0 +1,271 @@
+import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
+import { snapshotter_write_entity } from "../sim/Snapshotter.js";
+import { Lane } from "../transport/connection/Connection.js";
+import { InitialSyncPage } from "./NetworkPeer.js";
+
+/**
+ * Bytes of entity records a page is filled to. A page is a BULK message, so this is also how much
+ * the receiver holds of a join at a time. An entity larger than this is a page by itself.
+ */
+export const JOIN_PAGE_BYTES = 16 * 1024;
+
+/**
+ * Bytes of pages the first round — the whole world — may queue in one tick to finish there. A
+ * round that finishes in one tick is the join's last: every entity it carries is at the same
+ * frame, and every entity it leaves out is unchanged since its state went out, so the receiver
+ * holds the whole world at that frame. A world larger than this goes out over several ticks, paced
+ * by the lane's window, and a catch-up round follows.
+ *
+ * A catch-up round always tries to finish in its tick, with what the BULK lane may still hold as
+ * its budget: what changed while a world went out is a fraction of it, and a round that may only
+ * page would never shrink for a world that changes faster than a tick's budget.
+ */
+export const JOIN_FINAL_ROUND_BYTES = 256 * 1024;
+
+/**
+ * Catch-up rounds a join may take before it is given up. A catch-up round finishes in its tick
+ * unless what changed outgrows what the BULK lane may hold, so a join that needs more than one or
+ * two is a world changing faster than a peer can be sent it.
+ */
+export const JOIN_MAX_ROUNDS = 8;
+
+/**
+ * What a join has to say after {@link HostJoin#advance}.
+ * @readonly
+ * @enum {number}
+ */
+export const JoinProgress = Object.freeze({
+    /** Pages are going out, or the host is waiting to hear they arrived. */
+    Sending: 0,
+    /**
+     * The FINAL page has arrived: the peer holds the whole world. (Its action stream was released
+     * when FINAL was queued.)
+     */
+    Done: 1,
+    /** The world changed faster than it could be sent, round after round: drop the peer. */
+    DidNotConverge: 2,
+});
+
+const PHASE_PAGING = 0;
+const PHASE_AWAITING = 1;
+/** FINAL is queued and the stream released; the join is over once FINAL has arrived */
+const PHASE_FINAL_SENT = 2;
+
+/**
+ * The host's side of one peer joining: the world, sent as pages built when they go out, then what
+ * changed meanwhile, until the peer holds every entity's state at one frame. See
+ * `network/MESSAGE_TRANSPORT.md`, "Joining a world of any size".
+ *
+ * 1. The peer's action stream is held from the start (the caller holds it).
+ * 2. A round starts with a list of entities. If its pages fit {@link JOIN_FINAL_ROUND_BYTES}, they
+ *    all go in the tick the round starts, at that frame D; the FINAL page follows them, and the
+ *    peer's action stream is released from D + 1. The join is over. (The stream's datagrams can
+ *    overtake the last pages; the peer holds the stream until FINAL — `NetworkPeer.hold_inbound`.)
+ * 3. Otherwise the round's pages go out over as many ticks as it takes, each built at the frame it
+ *    is sent, while the BULK lane has less than {@link window_bytes} unacknowledged. Each entity's
+ *    network id is noted with the frame its state was sent at. Host memory: the window, and 8
+ *    bytes per entity.
+ * 4. When every page of such a round has arrived, every networked entity is checked: one changed
+ *    since its state was sent (`NetworkPeer.last_changed_frame`), or created since, is the next
+ *    round's list. An empty list ends the join with the FINAL page alone.
+ *
+ * The first round is the world. For a world that fits one tick's budget, the join is one tick.
+ *
+ * Built per join; allocates its id list and send-frame table once and grows them, nothing per tick.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class HostJoin {
+    /** entity ids still to send this round */
+    #entities;
+    #count = 0;
+    #cursor = 0;
+    /** network id → frame its state was last sent at, -1 for never */
+    #sent_frame = new Float64Array(256).fill(-1);
+    #round = 0;
+    #phase = PHASE_PAGING;
+    #mark = -1;
+    #first_sent = false;
+    /** the first round's list is the world as it is when the join first advances */
+    #started = false;
+
+    /**
+     * @param {{
+     *   peer: import("./NetworkPeer.js").NetworkPeer,
+     *   peer_id: number,
+     *   session_token: Uint8Array,
+     *   world: import("../../ecs/EntityComponentDataset.js").EntityComponentDataset,
+     *   for_each_entity: function(function(number): void): void,
+     *   page_buffer: BinaryBuffer,
+     *   window_bytes: number,
+     * }} options
+     *   `for_each_entity(cb)` visits every networked entity id. `page_buffer` is scratch the caller
+     *   may share between joins. `window_bytes` is how far ahead of the peer's acknowledgements
+     *   pages are built.
+     */
+    constructor({ peer, peer_id, session_token, world, for_each_entity, page_buffer, window_bytes }) {
+        this.peer = peer;
+        this.peer_id = peer_id;
+        this.session_token = session_token;
+        this.world = world;
+        this.for_each_entity = for_each_entity;
+        this.page_buffer = page_buffer;
+        this.window_bytes = window_bytes;
+
+        this.#entities = new Int32Array(64);
+        this.#count = 0;
+    }
+
+    /** Catch-up rounds taken so far. */
+    get round() {
+        return this.#round;
+    }
+
+    /**
+     * One tick of the join, at `frame` — the frame just simulated and published.
+     * @param {number} frame
+     * @returns {JoinProgress}
+     */
+    advance(frame) {
+        const connection = this.peer.connection_for(this.peer_id);
+        if (connection === undefined) return JoinProgress.Sending;
+
+        if (!this.#started) {
+            // the world at the first frame the join runs on, not at connect: what is built between
+            // the two is part of it
+            this.#started = true;
+            this.for_each_entity(this.#push_entity);
+        }
+
+        if (this.#phase === PHASE_FINAL_SENT) {
+            // Over only once FINAL has arrived: until then the peer holds part of a world, and a
+            // peer that drops now must not be resumed into it.
+            return connection.is_delivered(Lane.BULK, this.#mark) ? JoinProgress.Done : JoinProgress.Sending;
+        }
+
+        for (; ;) {
+            if (this.#phase === PHASE_PAGING) {
+                if (this.#cursor === 0) {
+                    // A round starting now: if it all goes in this tick, it is the last. The world
+                    // is held to one tick's budget; a catch-up round may fill the lane, leaving
+                    // room for one more page of the largest a message may be.
+                    const lane_room = connection.max_queued_bytes - connection.unacked_bytes(Lane.BULK)
+                        - connection.max_message_bytes;
+                    const budget = this.#round === 0 ? Math.min(JOIN_FINAL_ROUND_BYTES, lane_room) : lane_room;
+                    let queued = 0;
+                    while (this.#cursor < this.#count && queued < budget) {
+                        queued += this.#send_page(frame, 0);
+                    }
+                    if (this.#cursor >= this.#count) {
+                        this.#send_page(frame, InitialSyncPage.FINAL);
+                        this.peer.release_outbound(this.peer_id, frame + 1);
+                        this.#phase = PHASE_FINAL_SENT;
+                        return JoinProgress.Sending;
+                    }
+                }
+                while (this.#cursor < this.#count && connection.unacked_bytes(Lane.BULK) < this.window_bytes) {
+                    this.#send_page(frame, 0);
+                }
+                if (this.#cursor < this.#count) return JoinProgress.Sending;
+                this.#phase = PHASE_AWAITING;
+            }
+
+            // every page of the round has been queued: has it all arrived?
+            if (!connection.is_delivered(Lane.BULK, this.#mark)) return JoinProgress.Sending;
+
+            this.#collect_changed();
+            if (this.#count === 0) {
+                this.#send_page(frame, InitialSyncPage.FINAL);
+                this.peer.release_outbound(this.peer_id, frame + 1);
+                this.#phase = PHASE_FINAL_SENT;
+                return JoinProgress.Sending;
+            }
+            this.#round++;
+            if (this.#round > JOIN_MAX_ROUNDS) return JoinProgress.DidNotConverge;
+            this.#cursor = 0;
+            this.#phase = PHASE_PAGING;
+        }
+    }
+
+    /**
+     * Fill and queue the next page from the cursor, or an empty one when `flags` asks for FINAL.
+     * @param {number} frame
+     * @param {number} flags
+     * @returns {number} bytes of entity records queued
+     */
+    #send_page(frame, flags) {
+        const buffer = this.page_buffer;
+        const slot_table = this.peer.slot_table;
+        buffer.position = 0;
+        buffer.writeUint32(0); // entity count, written at the end
+
+        let written = 0;
+        if ((flags & InitialSyncPage.FINAL) === 0) {
+            while (this.#cursor < this.#count) {
+                const entity_id = this.#entities[this.#cursor];
+                const network_id = slot_table.network_for(entity_id);
+                if (network_id < 0) {
+                    // gone since the round began
+                    this.#cursor++;
+                    continue;
+                }
+                if (written > 0 && buffer.position >= JOIN_PAGE_BYTES) break;
+                snapshotter_write_entity(buffer, this.world, slot_table, this.peer.component_registry, entity_id);
+                this.#set_sent(network_id, frame);
+                written++;
+                this.#cursor++;
+            }
+        }
+
+        const end = buffer.position;
+        buffer.position = 0;
+        buffer.writeUint32(written);
+        buffer.position = end;
+
+        if (!this.#first_sent) {
+            flags |= InitialSyncPage.FIRST;
+            this.#first_sent = true;
+        }
+        this.#mark = this.peer.send_sync_page(this.peer_id, this.session_token, frame, flags, buffer.raw_bytes, end);
+        return end;
+    }
+
+    /**
+     * The next round's list: networked entities changed since their state was sent, or never sent.
+     */
+    #collect_changed() {
+        this.#count = 0;
+        this.for_each_entity(this.#push_if_changed);
+    }
+
+    /** @type {function(number): void} */
+    #push_entity = (entity_id) => {
+        if (this.#count === this.#entities.length) {
+            const next = new Int32Array(this.#entities.length * 2);
+            next.set(this.#entities);
+            this.#entities = next;
+        }
+        this.#entities[this.#count++] = entity_id;
+    };
+
+    /** @type {function(number): void} */
+    #push_if_changed = (entity_id) => {
+        const network_id = this.peer.slot_table.network_for(entity_id);
+        if (network_id < 0) return;
+        const sent = network_id < this.#sent_frame.length ? this.#sent_frame[network_id] : -1;
+        if (sent >= 0 && this.peer.last_changed_frame(network_id) <= sent) return;
+        this.#push_entity(entity_id);
+    };
+
+    #set_sent(network_id, frame) {
+        if (network_id >= this.#sent_frame.length) {
+            let size = this.#sent_frame.length * 2;
+            while (size <= network_id) size *= 2;
+            const next = new Float64Array(size).fill(-1);
+            next.set(this.#sent_frame);
+            this.#sent_frame = next;
+        }
+        this.#sent_frame[network_id] = frame;
+    }
+}