@net-mesh/browser 0.43.0 → 0.44.0

package/dist/netcode/wire.d.ts

@@ -40,22 +40,43 @@ export interface WireInput<I> {
     readonly data: I;
 }
 export type Frame<E, I> = 
-/** Player → host: join (repeated until the first snapshot). */
+/**
+ * Player → host: join (repeated until the first snapshot). `f` is the
+ * player's entity-codec fingerprint, if it has one: the host sends binary
+ * snapshots only when it matches its own (`codec.ts`).
+ */
 {
     readonly n: string;
     readonly k: 'h';
+    readonly f?: string;
 }
-/** Player → host: the newest inputs, the unacknowledged ones repeated. */
+/**
+ * Player → host: the newest inputs, the unacknowledged ones repeated.
+ * `ep`: the assignment epoch the player sent them under (sharded
+ * matches); a host at another epoch drops them.
+ */
  | {
     readonly n: string;
     readonly k: 'i';
     readonly i: readonly WireInput<I>[];
+    readonly ep?: number;
 }
-/** Player → host: clock ping. */
+/** Player → host: clock ping, repeating the codec fingerprint (a lost join must not pin a player to JSON). */
  | {
     readonly n: string;
     readonly k: 'p';
     readonly t0: number;
+    readonly f?: string;
+}
+/**
+ * Player → host: binary-snapshot indexes it has no name for; the host
+ * names them again (only indexes it showed that player, and an index at
+ * most once per 100 ms).
+ */
+ | {
+    readonly n: string;
+    readonly k: 'u';
+    readonly u: readonly number[];
 }
 /**
  * Player → host: the interest keys it wants, version `v` (repeated until a
@@ -93,10 +114,23 @@ export type Frame<E, I> =
     readonly of?: number;
     /** The interest version this snapshot was filtered by, if any. */
     readonly iv?: number;
+    /** The assignment epoch the host sent it under (sharded matches). */
+    readonly ep?: number;
 };
 /** Interest keys a player may name, and the longest key, in UTF-16 units. */
 export declare const MAX_NETCODE_INTEREST_KEYS = 256;
 export declare const MAX_NETCODE_INTEREST_KEY_LENGTH = 64;
+/** Indexes one `u` frame may ask to have named. */
+export declare const MAX_NAME_REQUESTS = 256;
+/**
+ * A binary-snapshot name not used for this long, ms, is forgotten: by the
+ * host for an id no player has been shown (it gets a fresh index if it
+ * comes back, named again), and by the host for one player once that
+ * player has not been shown it. A player keeps a name three times as long
+ * from the last frame that carried the index, so it never forgets one the
+ * host still counts as known to it; forgetting early would only cost a `u`.
+ */
+export declare const NAME_FORGET_MS = 10000;
 /** Chunks a snapshot may be split into, at most. */
 export declare const MAX_SNAPSHOT_CHUNKS = 256;
 /**

package/dist/netcode/wire.js

@@ -11,6 +11,17 @@
 /** Interest keys a player may name, and the longest key, in UTF-16 units. */
 export const MAX_NETCODE_INTEREST_KEYS = 256;
 export const MAX_NETCODE_INTEREST_KEY_LENGTH = 64;
+/** Indexes one `u` frame may ask to have named. */
+export const MAX_NAME_REQUESTS = 256;
+/**
+ * A binary-snapshot name not used for this long, ms, is forgotten: by the
+ * host for an id no player has been shown (it gets a fresh index if it
+ * comes back, named again), and by the host for one player once that
+ * player has not been shown it. A player keeps a name three times as long
+ * from the last frame that carried the index, so it never forgets one the
+ * host still counts as known to it; forgetting early would only cost a `u`.
+ */
+export const NAME_FORGET_MS = 10_000;
 /** Chunks a snapshot may be split into, at most. */
 export const MAX_SNAPSHOT_CHUNKS = 256;
 /**
@@ -25,6 +36,10 @@ export function chunkOf(id, of) {
     }
     return (hash >>> 0) % of;
 }
+/** An `ep` field: absent, or a non-negative safe integer. */
+function epochField(ep) {
+    return ep === undefined || (Number.isSafeInteger(ep) && ep >= 0);
+}
 const encoder = new TextEncoder();
 const decoder = new TextDecoder('utf-8', { fatal: true });
 export function encodeFrame(frame) {
@@ -47,11 +62,22 @@ export function decodeFrame(payload, label) {
     const frame = value;
     if (frame.n !== label || typeof frame.k !== 'string')
         return null;
+    const fingerprint = frame.f;
+    if (fingerprint !== undefined && (typeof fingerprint !== 'string' || fingerprint.length > 64))
+        return null;
     switch (frame.k) {
         case 'h':
             return frame;
+        case 'u': {
+            const u = frame.u;
+            return Array.isArray(u) && u.length <= MAX_NAME_REQUESTS && u.every(index => Number.isSafeInteger(index) && index >= 0)
+                ? frame
+                : null;
+        }
         case 'i':
-            return Array.isArray(frame.i) ? frame : null;
+            return Array.isArray(frame.i) && epochField(frame.ep)
+                ? frame
+                : null;
         case 'p':
             return typeof frame.t0 === 'number' ? frame : null;
         case 'w': {
@@ -73,6 +99,7 @@ export function decodeFrame(payload, label) {
         case 's': {
             const s = frame;
             if ((s.iv !== undefined && !Number.isSafeInteger(s.iv)) ||
+                !epochField(s.ep) ||
                 typeof s.tick !== 'number' ||
                 typeof s.t !== 'number' ||
                 typeof s.ack !== 'number' ||

package/dist/node.d.ts

@@ -883,6 +883,11 @@ export interface RetryReport {
     readonly online: string;
     /** Triggers filed by the ICE `disconnected` → `failed` watcher. */
     readonly iceFailed: string;
+    /**
+     * Triggers filed because the far end closed a DataChannel a session
+     * rode. One channel's loss counts once, here or under `iceFailed`.
+     */
+    readonly channelClosed: string;
     /** Every trigger seen, whatever the owner decided. */
     readonly triggers: string;
     /** Re-attempts STARTED. One per network change, per peer. */

package/dist/node.js

@@ -1075,6 +1075,7 @@ export function parseRetryReport(json) {
         armed: raw.armed === true,
         online: String(raw.online ?? '0'),
         iceFailed: String(raw.iceFailed ?? '0'),
+        channelClosed: String(raw.channelClosed ?? '0'),
         triggers: String(raw.triggers ?? '0'),
         started: String(raw.started ?? '0'),
         coalesced: String(raw.coalesced ?? '0'),

package/dist/world/link.d.ts

@@ -109,7 +109,16 @@ export interface RegionHandoffsOptions<E> {
     };
     /** Outcomes: `moved`, `refused`, `unresolved` (source), `admitted` (target). */
     onEvent?(event: HandoffEvent): void;
+    /** Entity handoffs: re-offer, give up, and how long a decision is remembered. */
     readonly timing?: HandoffTiming;
+    /**
+     * Forwarded actions ({@link RegionHandoffs.forward}), when they need other
+     * timing than entity handoffs: a hit is worthless after half a second,
+     * while a moving entity must not be given up that soon (it would be live
+     * nowhere) nor forgotten while its offer may still be re-sent (it could
+     * be admitted twice). Default: `timing`.
+     */
+    readonly actionTiming?: HandoffTiming;
     /** How often to re-offer and prune, ms. Default 100. */
     readonly tickMs?: number;
     readonly now?: () => number;

package/dist/world/link.js

@@ -264,9 +264,10 @@ export function regionHandoffs(options) {
             options.link.send({ to, body: frame });
         }
     };
-    const retryMs = options.timing?.retryMs ?? 250;
-    const giveUpMs = options.timing?.giveUpMs ?? 60_000;
-    const retentionMs = options.timing?.handledRetentionMs ?? 600_000;
+    const actionTiming = options.actionTiming ?? options.timing;
+    const retryMs = actionTiming?.retryMs ?? 250;
+    const giveUpMs = actionTiming?.giveUpMs ?? 60_000;
+    const retentionMs = actionTiming?.handledRetentionMs ?? 600_000;
     const stop = options.link.onMessage(body => {
         if (closed)
             return;

package/dist/world/regions.d.ts

@@ -44,8 +44,15 @@ export declare function regionsAround(x: number, z: number, options: {
 }): string[];
 /** The directory tag a region host announces. */
 export declare function regionTag(world: string, region: string): string;
-/** How often region hosts re-announce: an announcement is a lease. */
-export declare const REGION_ANNOUNCE_MS = 2000;
+/**
+ * How often region hosts re-announce: an announcement is a lease, held
+ * for the leaf's 300 s TTL. 30 s, not 2 s, for the reason
+ * `LOBBY_ANNOUNCE_MS` gives: re-announcements flood through the anchor to
+ * every peer, and at 2 s they saturated a host's anchor link at 64 nodes.
+ * A failed announcement is retried sooner, as a lobby's is
+ * (`ANNOUNCE_RETRY_MS`, doubling up to `ANNOUNCE_RETRY_MAX_MS`).
+ */
+export declare const REGION_ANNOUNCE_MS = 30000;
 /**
  * Announce that this node hosts `regions` of `world`, and keep announcing
  * (an announcement is a lease). `announce` replaces a node's tags, so pass

package/dist/world/regions.js

@@ -27,6 +27,7 @@
  * directory (`handoffLink({ peerOf: directory.peerOf })`) needs the list:
  * otherwise a node that announces a region could also send offers as it.
  */
+import { ANNOUNCE_RETRY_MAX_MS, ANNOUNCE_RETRY_MS } from '../lobby.js';
 import { nodeHexOf } from '../store/host.js';
 import { joinStore } from '../store/join.js';
 /** Region `r:<rx>:<rz>` for a position, with regions `size` units square. */
@@ -51,8 +52,15 @@ export function regionsAround(x, z, options) {
 export function regionTag(world, region) {
     return `net-world:${world}:region:${region}`;
 }
-/** How often region hosts re-announce: an announcement is a lease. */
-export const REGION_ANNOUNCE_MS = 2_000;
+/**
+ * How often region hosts re-announce: an announcement is a lease, held
+ * for the leaf's 300 s TTL. 30 s, not 2 s, for the reason
+ * `LOBBY_ANNOUNCE_MS` gives: re-announcements flood through the anchor to
+ * every peer, and at 2 s they saturated a host's anchor link at 64 nodes.
+ * A failed announcement is retried sooner, as a lobby's is
+ * (`ANNOUNCE_RETRY_MS`, doubling up to `ANNOUNCE_RETRY_MAX_MS`).
+ */
+export const REGION_ANNOUNCE_MS = 30_000;
 /**
  * Announce that this node hosts `regions` of `world`, and keep announcing
  * (an announcement is a lease). `announce` replaces a node's tags, so pass
@@ -61,9 +69,29 @@ export const REGION_ANNOUNCE_MS = 2_000;
 export function announceRegions(node, world, regions, options = {}) {
     const tags = [...(options.tags ?? []), ...regions.map(region => regionTag(world, region))];
     let stopped = false;
+    // A failed announcement is retried on a short backoff of its own: a
+    // region nobody can find for a whole lease refresh is a hole in the map.
+    let retry = null;
+    let retryMs = ANNOUNCE_RETRY_MS;
     const once = () => {
-        if (!stopped)
-            void node.announce(tags).catch(() => undefined);
+        if (stopped)
+            return;
+        if (retry !== null) {
+            clearTimeout(retry);
+            retry = null;
+        }
+        void node.announce(tags).then(() => {
+            retryMs = ANNOUNCE_RETRY_MS;
+        }, () => {
+            if (stopped || retry !== null)
+                return;
+            retry = setTimeout(() => {
+                retry = null;
+                once();
+            }, retryMs);
+            retry.unref?.();
+            retryMs = Math.min(retryMs * 2, ANNOUNCE_RETRY_MAX_MS);
+        });
     };
     once();
     const timer = setInterval(once, options.everyMs ?? REGION_ANNOUNCE_MS);
@@ -71,6 +99,8 @@ export function announceRegions(node, world, regions, options = {}) {
     return () => {
         stopped = true;
         clearInterval(timer);
+        if (retry !== null)
+            clearTimeout(retry);
     };
 }
 /** A region directory over the mesh's signed announcements. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@net-mesh/browser",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "description": "Browser-native Net mesh leaf \u2014 idiomatic TypeScript over the net-mesh-leaf wasm node",
   "type": "module",
   "main": "dist/index.js",
@@ -59,7 +59,8 @@
     "check:package": "node scripts/check-package.mjs",
     "test": "tsc -p tsconfig.test.json && vitest run",
     "test:watch": "vitest",
-    "bench:world": "node scripts/bench-world.mjs"
+    "bench:world": "node scripts/bench-world.mjs",
+    "bench:netcode": "node scripts/bench-netcode.mjs"
   },
   "devDependencies": {
     "esbuild": "^0.28.0",