@crowdedkingdoms/crowdyjs 18.19.0 → 18.20.0-dev.1

package/README.md

@@ -12,19 +12,23 @@ gameplay, minted per app through `client.portal`.
 
 Start here:
 
-- [SDK guide](https://docs.crowdedkingdoms.com/crowdyjs/readme) — the canonical
+- [SDK guide](https://docs.dev.crowdedkingdoms.com/crowdyjs/readme) — the canonical
   walkthrough of everything in this README.
-- [Build a game](https://docs.crowdedkingdoms.com/build-a-game/intro) — a
+- [Build a game](https://docs.dev.crowdedkingdoms.com/build-a-game/intro) — a
   hands-on tutorial from sign-in to a playable voxel game.
-- [Platform overview](https://docs.crowdedkingdoms.com/overview/client-workflow)
+- [Platform overview](https://docs.dev.crowdedkingdoms.com/overview/client-workflow)
   — how a client session flows through the platform.
 
 ## Install
 
 ```bash
-npm install @crowdedkingdoms/crowdyjs
+npm install @crowdedkingdoms/crowdyjs@dev
 ```
 
+This README is the `dev` branch's: it documents the release on the `dev` dist-tag
+(`npm view @crowdedkingdoms/crowdyjs dist-tags`), and its links go to the dev docs site. A
+plain `npm install` resolves `latest`, the production release, which has no `client.exec`.
+
 **Server compatibility.** A release selects fields the Game API it was built against has,
 so it needs that Game API or newer; promote the Game API before the SDK on each tier.
 
@@ -196,8 +200,8 @@ Notes:
 - Use `client.auth.setToken(token)` to seed a token externally (e.g. when
   restoring auth from a non-default storage).
 
-Deeper reading: [Portals & app-scoped tokens](https://docs.crowdedkingdoms.com/management-api/portals-and-app-tokens)
-and [Sign in](https://docs.crowdedkingdoms.com/management-api/authentication).
+Deeper reading: [Portals & app-scoped tokens](https://docs.dev.crowdedkingdoms.com/management-api/portals-and-app-tokens)
+and [Sign in](https://docs.dev.crowdedkingdoms.com/management-api/authentication).
 
 ### Org-managed players
 
@@ -394,7 +398,7 @@ query AppForRouting($appId: BigInt!) {
 `CrowdyClient` with `httpUrl: gameApiUrl` (and the matching `wsUrl`) holding
 that app's app-scoped token, then drive gameplay through that client. Apps
 with no `gameApiUrl` keep working against the default `httpUrl` you
-configured. See [Loading an app's Game API](https://docs.crowdedkingdoms.com/crowdyjs/shared-environment-routing).
+configured. See [Loading an app's Game API](https://docs.dev.crowdedkingdoms.com/crowdyjs/shared-environment-routing).
 
 ## Realtime notifications
 
@@ -552,7 +556,14 @@ The plain `sendActorUpdate`, `sendVoxelUpdate`, `sendAudioPacket`,
 `sendTextPacket`, and `sendClientEvent` methods return the GraphQL mutation
 result immediately. The `AndWait` variants allocate a `sequenceNumber` when
 one is missing and wait for either a matching notification or
-`GenericErrorResponse`. `sendChannelMessage` broadcasts an opaque payload on a
+`GenericErrorResponse`, timing the wait from when the send was accepted. The
+first awaited send of each session (the first connect, a reconnect, or a move to
+another instance) is retried once with a fresh `sequenceNumber` if it is refused
+`UNAUTHORIZED` or, for the actor and voxel updates the server echoes, if it times
+out (`UDP_SEQUENCE_TIMEOUT`), which is how a realtime server older than v0.42.0
+answers a session's first message. A send whose `sequenceNumber` you chose is
+not retried, and an audio, text or event send's timeout (its normal success) is
+never retried. `sendChannelMessage` broadcasts an opaque payload on a
 channel. `sendRangedChannelMessage` publishes on a channel too, but only members
 with a live actor within `maxDistance` chunks (straight-line distance between
 chunk coordinates) of `chunk` receive it; they get the same `channelMessage`
@@ -820,7 +831,7 @@ reach your bundle. Reads are synchronous snapshots and writes happen on
 WebSocket events (not `requestAnimationFrame`), so render loops read freely
 and a backgrounded tab keeps ingesting updates; pass `workerTicker()` to also
 keep timer-driven sends at full rate while hidden. See the
-[World Stores guide](https://docs.crowdedkingdoms.com/crowdyjs/stores).
+[World Stores guide](https://docs.dev.crowdedkingdoms.com/crowdyjs/stores).
 
 ## Game Kit
 
@@ -898,7 +909,7 @@ The protocol is held to ck-exec's golden record of the starters
 (`test/unit/fixtures/kit-protocol.json`): every module call and topic in it is replayed in
 `test/unit/game-kit.test.mjs`. The blueprints, `kit.deploy`, the engines and the model-backed
 helpers went with the game model in 18.0.0; the hub modules replace them. See the
-[Game Kit docs](https://docs.crowdedkingdoms.com/game-kit/intro) and
+[Game Kit docs](https://docs.dev.crowdedkingdoms.com/game-kit/intro) and
 [MIGRATION.md](MIGRATION.md).
 
 ## ck-exec
@@ -962,7 +973,7 @@ Integers above 2^53 decode as `number` and lose precision unless you pass
 `{ decode: { useBigInt64: true } }`. A call's whole numbers outside 32 bits (a timestamp in
 milliseconds, a player id) go out as 64-bit integers (18.11.0; before, as floats, which a
 hub's integer fields refuse). The wire format is in the
-[ck-exec docs](https://docs.crowdedkingdoms.com/exec/intro).
+[ck-exec docs](https://docs.dev.crowdedkingdoms.com/exec/intro).
 
 ### A mod's CLIENT half
 
@@ -1033,7 +1044,7 @@ counts what was dropped); `invoke` sends at most 256 KiB each way and is refused
 module is not running. `NOT_FOUND` holds a CLIENT half back 15 s and `RATE_LIMITED` 60 s. The
 grid's owner is asked about their own CLIENT halves like anyone; answer yes in `confirm` when
 `prompt.authorId` is the player. See
-[CLIENT halves](https://docs.crowdedkingdoms.com/exec/client-halves).
+[CLIENT halves](https://docs.dev.crowdedkingdoms.com/exec/client-halves).
 
 ## Hosting a game on Crowdy Games
 
@@ -1152,8 +1163,8 @@ CLIENT project needs ck-api `v2.25.1` or later. A CLIENT crate still on the lega
 `mountCrowdyStudio` and the controller take `mods: client.exec`. Crowdy Studio runs nothing
 on legacy player compute since 18.0.0.
 
-See [CLIENT halves](https://docs.crowdedkingdoms.com/exec/client-halves), [mods](https://docs.crowdedkingdoms.com/exec/mods)
-and [Embed Crowdy Studio in your game](https://docs.crowdedkingdoms.com/crowdyjs/crowdy-studio-embed).
+See [CLIENT halves](https://docs.dev.crowdedkingdoms.com/exec/client-halves), [mods](https://docs.dev.crowdedkingdoms.com/exec/mods)
+and [Embed Crowdy Studio in your game](https://docs.dev.crowdedkingdoms.com/crowdyjs/crowdy-studio-embed).
 
 ### The Studio agent (DeepSeek Harness in the browser)
 
@@ -1344,7 +1355,7 @@ no other repositories and no network access required:
   `src/generated/graphql-schema.ts`, the generated schema types.
 
 Schema refresh is explicit, from the published
-[SDL](https://docs.crowdedkingdoms.com/schema/game-api.graphql):
+[SDL](https://docs.dev.crowdedkingdoms.com/schema/game-api.graphql):
 
 ```bash
 npm run schema:sync:prod

package/dist/default-origin.d.ts

@@ -1,6 +1,6 @@
 /**
  * GENERATED — do not edit. The operator tooling's
- * `sync-client-origins.mjs --write --tier prod` writes this file, and
+ * `sync-client-origins.mjs --write --tier dev` writes this file, and
  * `check-sdk-default-origin.mjs` refuses it when it names the wrong tier or a
  * host that declaration does not carry. Regenerate; never hand-edit.
  *
@@ -10,14 +10,14 @@
  * than no default at all. Every fallback this SDK ever removed named a host that
  * was already dead. A generated file plus a gate is what makes this one different.
  *
- * Source: the operator's per-tier public CK API origin declaration, tier 'prod'
+ * Source: the operator's per-tier public CK API origin declaration, tier 'dev'
  */
 /** The tier this build of the SDK is published for. */
-export declare const CROWDY_DEFAULT_TIER = "prod";
+export declare const CROWDY_DEFAULT_TIER = "dev";
 /** The public CK API origin for that tier. */
-export declare const CROWDY_DEFAULT_HTTP_ORIGIN = "https://ck.prod.crowdedkingdoms.com";
+export declare const CROWDY_DEFAULT_HTTP_ORIGIN = "https://ck.dev.crowdedkingdoms.com";
 /** The same host over WebSocket. A scheme is composed; a hostname is looked up. */
-export declare const CROWDY_DEFAULT_WS_ORIGIN = "wss://ck.prod.crowdedkingdoms.com";
+export declare const CROWDY_DEFAULT_WS_ORIGIN = "wss://ck.dev.crowdedkingdoms.com";
 /** The bare hostname, for callers that need to compare rather than dial. */
-export declare const CROWDY_DEFAULT_HOST = "ck.prod.crowdedkingdoms.com";
+export declare const CROWDY_DEFAULT_HOST = "ck.dev.crowdedkingdoms.com";
 //# sourceMappingURL=default-origin.d.ts.map

package/dist/default-origin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"default-origin.d.ts","sourceRoot":"","sources":["../src/default-origin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,uDAAuD;AACvD,eAAO,MAAM,mBAAmB,SAAS,CAAC;AAE1C,8CAA8C;AAC9C,eAAO,MAAM,0BAA0B,wCAAwC,CAAC;AAEhF,mFAAmF;AACnF,eAAO,MAAM,wBAAwB,sCAAsC,CAAC;AAE5E,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB,gCAAgC,CAAC"}
+{"version":3,"file":"default-origin.d.ts","sourceRoot":"","sources":["../src/default-origin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,uDAAuD;AACvD,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAEzC,8CAA8C;AAC9C,eAAO,MAAM,0BAA0B,uCAAuC,CAAC;AAE/E,mFAAmF;AACnF,eAAO,MAAM,wBAAwB,qCAAqC,CAAC;AAE3E,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB,+BAA+B,CAAC"}

package/dist/default-origin.js

@@ -1,6 +1,6 @@
 /**
  * GENERATED — do not edit. The operator tooling's
- * `sync-client-origins.mjs --write --tier prod` writes this file, and
+ * `sync-client-origins.mjs --write --tier dev` writes this file, and
  * `check-sdk-default-origin.mjs` refuses it when it names the wrong tier or a
  * host that declaration does not carry. Regenerate; never hand-edit.
  *
@@ -10,13 +10,13 @@
  * than no default at all. Every fallback this SDK ever removed named a host that
  * was already dead. A generated file plus a gate is what makes this one different.
  *
- * Source: the operator's per-tier public CK API origin declaration, tier 'prod'
+ * Source: the operator's per-tier public CK API origin declaration, tier 'dev'
  */
 /** The tier this build of the SDK is published for. */
-export const CROWDY_DEFAULT_TIER = 'prod';
+export const CROWDY_DEFAULT_TIER = 'dev';
 /** The public CK API origin for that tier. */
-export const CROWDY_DEFAULT_HTTP_ORIGIN = 'https://ck.prod.crowdedkingdoms.com';
+export const CROWDY_DEFAULT_HTTP_ORIGIN = 'https://ck.dev.crowdedkingdoms.com';
 /** The same host over WebSocket. A scheme is composed; a hostname is looked up. */
-export const CROWDY_DEFAULT_WS_ORIGIN = 'wss://ck.prod.crowdedkingdoms.com';
+export const CROWDY_DEFAULT_WS_ORIGIN = 'wss://ck.dev.crowdedkingdoms.com';
 /** The bare hostname, for callers that need to compare rather than dial. */
-export const CROWDY_DEFAULT_HOST = 'ck.prod.crowdedkingdoms.com';
+export const CROWDY_DEFAULT_HOST = 'ck.dev.crowdedkingdoms.com';

package/dist/domains/udp.d.ts

@@ -33,10 +33,13 @@ import { type VideoCodec } from '../media/video-frames.js';
  *
  * Spatial caveats: a `sequenceNumber` is a uint8 (0-255) used for
  * **correlation only** — not an idempotency key, and the server does not dedupe
- * replays. The **first** spatial message to a brand-new chunk may be dropped
- * server-side while grid permissions load, so clients should re-send (the
- * two-client tests register twice for this reason). To receive any
- * `...AndWait` echo or notification you must have an active {@link subscribe}.
+ * replays. The game server holds a session's first messages, and the first
+ * message into a newly entered region, until the permissions they need have
+ * loaded (realtime server v0.42.0 and later); an older server dropped or
+ * refused them. Against one, the SDK retries the first awaited send of each
+ * session once (see {@link sendActorUpdateAndWait}), but a plain `send*` may
+ * still be lost. To receive any `...AndWait` echo or notification you must have
+ * an active {@link subscribe}.
  */
 export declare class UdpAPI {
     private gql;
@@ -50,6 +53,8 @@ export declare class UdpAPI {
     private waitForGameplayTokenRefresh?;
     private readonly sequences;
     private readonly inFlightActorUpdates;
+    /** The session epoch of the last awaited send that was answered. */
+    private confirmedEpoch;
     constructor(gql: GraphQLClient, subs: SubscriptionManager, metrics?: RealtimeMetrics | undefined, 
     /**
      * When set, every UDP send waits for this promise (a gameplay-token
@@ -159,8 +164,22 @@ export declare class UdpAPI {
      * @param input - {@link ActorUpdateRequestInput} (see {@link sendActorUpdate}
      *   for field units/encoding). Omit `sequenceNumber` to let the SDK allocate
      *   one.
-     * @param options - `timeoutMs`: how long to wait for the echo, in
-     *   milliseconds; defaults to the client's realtime `waitTimeoutMs` (5000).
+     * Every `send*AndWait` behaves as follows:
+     * - `timeoutMs` counts from when the send was accepted, not from the call, so
+     *   a slow send leg (the first send opening the proxy session, the binary
+     *   relay finishing its handshake) does not shorten the wait for the echo.
+     * - The first awaited send of a new session (the first connect, a reconnect,
+     *   a move to another instance) is retried once with a fresh sequence number
+     *   if it is refused `UNAUTHORIZED` or, for the actor and voxel updates the
+     *   server echoes, if its echo times out (`UDP_SEQUENCE_TIMEOUT`), which is
+     *   how a game server older than v0.42.0 answers a session's first messages;
+     *   the resolved notification then carries the retry's sequence number. A
+     *   send whose `sequenceNumber` you chose is not retried, and neither is the
+     *   timeout of an audio, text or event send, which is how those succeed.
+     *
+     * @param options - `timeoutMs`: how long to wait for the echo once the send
+     *   is accepted, in milliseconds; defaults to the client's realtime
+     *   `waitTimeoutMs` (5000).
      * @returns The correlated {@link SpatialNotification} (your own
      *   `ActorUpdateNotification` self-echo).
      * @throws {CrowdyGraphQLError} if the underlying send is rejected.
@@ -168,7 +187,8 @@ export declare class UdpAPI {
      *   request timeout.
      * @throws {CrowdyRealtimeError} if no echo arrives within `timeoutMs`
      *   (`code === 'UDP_SEQUENCE_TIMEOUT'`, retryable), or the server returns a
-     *   matching `GenericErrorResponse` (its `code` is the server's `errorCode`).
+     *   matching `GenericErrorResponse` (its `code` is the server's `errorCode`),
+     *   after the one retry described above when it applies.
      * @example
      * ```ts
      * const unsubscribe = client.udp.subscribe({}, appId); // echoes need an open WS
@@ -588,6 +608,26 @@ export declare class UdpAPI {
      * ```
      */
     subscribe(handlers: UdpNotificationHandlers, appId: string): () => void;
+    /**
+     * What every `send*AndWait` does.
+     *
+     * The wait is registered before the send, so an echo that beats the send's
+     * own response is not missed, and its clock starts once the send has been
+     * accepted, so a lazy proxy-session open or the relay's handshake on the send
+     * leg is not taken from the echo's window.
+     *
+     * The first awaited send of a new session (the first connect, a reconnect, or
+     * a move to another instance) is retried once, with a fresh sequence number,
+     * when it is refused `UNAUTHORIZED` or, for a send the server echoes, when
+     * its echo times out: a game server from before the one that holds a
+     * session's first messages refuses or drops them while the session's
+     * permissions load. A send the server does not echo (audio, text, a client
+     * event) succeeds by timing out, so its timeout is never retried. Only when
+     * the SDK chose the sequence number, because the retry needs one of its own
+     * and a caller who chose theirs is correlating by it.
+     */
+    private sendAndWait;
+    private sendOnceAndWait;
     private withSequence;
 }
 //# sourceMappingURL=udp.d.ts.map

package/dist/domains/udp.d.ts.map

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

package/dist/domains/udp.js

@@ -33,10 +33,13 @@ import { encodeBase64 } from '../utils.js';
  *
  * Spatial caveats: a `sequenceNumber` is a uint8 (0-255) used for
  * **correlation only** — not an idempotency key, and the server does not dedupe
- * replays. The **first** spatial message to a brand-new chunk may be dropped
- * server-side while grid permissions load, so clients should re-send (the
- * two-client tests register twice for this reason). To receive any
- * `...AndWait` echo or notification you must have an active {@link subscribe}.
+ * replays. The game server holds a session's first messages, and the first
+ * message into a newly entered region, until the permissions they need have
+ * loaded (realtime server v0.42.0 and later); an older server dropped or
+ * refused them. Against one, the SDK retries the first awaited send of each
+ * session once (see {@link sendActorUpdateAndWait}), but a plain `send*` may
+ * still be lost. To receive any `...AndWait` echo or notification you must have
+ * an active {@link subscribe}.
  */
 export class UdpAPI {
     constructor(gql, subs, metrics, 
@@ -52,6 +55,8 @@ export class UdpAPI {
         this.waitForGameplayTokenRefresh = waitForGameplayTokenRefresh;
         this.sequences = new SequenceAllocator();
         this.inFlightActorUpdates = new Set();
+        /** The session epoch of the last awaited send that was answered. */
+        this.confirmedEpoch = -1;
     }
     /**
      * Resolves when every in-flight {@link sendActorUpdate} has settled.
@@ -261,8 +266,22 @@ export class UdpAPI {
      * @param input - {@link ActorUpdateRequestInput} (see {@link sendActorUpdate}
      *   for field units/encoding). Omit `sequenceNumber` to let the SDK allocate
      *   one.
-     * @param options - `timeoutMs`: how long to wait for the echo, in
-     *   milliseconds; defaults to the client's realtime `waitTimeoutMs` (5000).
+     * Every `send*AndWait` behaves as follows:
+     * - `timeoutMs` counts from when the send was accepted, not from the call, so
+     *   a slow send leg (the first send opening the proxy session, the binary
+     *   relay finishing its handshake) does not shorten the wait for the echo.
+     * - The first awaited send of a new session (the first connect, a reconnect,
+     *   a move to another instance) is retried once with a fresh sequence number
+     *   if it is refused `UNAUTHORIZED` or, for the actor and voxel updates the
+     *   server echoes, if its echo times out (`UDP_SEQUENCE_TIMEOUT`), which is
+     *   how a game server older than v0.42.0 answers a session's first messages;
+     *   the resolved notification then carries the retry's sequence number. A
+     *   send whose `sequenceNumber` you chose is not retried, and neither is the
+     *   timeout of an audio, text or event send, which is how those succeed.
+     *
+     * @param options - `timeoutMs`: how long to wait for the echo once the send
+     *   is accepted, in milliseconds; defaults to the client's realtime
+     *   `waitTimeoutMs` (5000).
      * @returns The correlated {@link SpatialNotification} (your own
      *   `ActorUpdateNotification` self-echo).
      * @throws {CrowdyGraphQLError} if the underlying send is rejected.
@@ -270,7 +289,8 @@ export class UdpAPI {
      *   request timeout.
      * @throws {CrowdyRealtimeError} if no echo arrives within `timeoutMs`
      *   (`code === 'UDP_SEQUENCE_TIMEOUT'`, retryable), or the server returns a
-     *   matching `GenericErrorResponse` (its `code` is the server's `errorCode`).
+     *   matching `GenericErrorResponse` (its `code` is the server's `errorCode`),
+     *   after the one retry described above when it applies.
      * @example
      * ```ts
      * const unsubscribe = client.udp.subscribe({}, appId); // echoes need an open WS
@@ -285,13 +305,7 @@ export class UdpAPI {
      * ```
      */
     async sendActorUpdateAndWait(input, options = {}) {
-        const request = this.withSequence(input);
-        const wait = this.subs.waitForSequence(request.sequenceNumber, options.timeoutMs);
-        await this.sendActorUpdate(request);
-        // Nothing can be echoed that has not left: the bundled relay path holds a
-        // send for up to bundleWindowMs, so put it on the wire before waiting.
-        this.subs.flushSends();
-        return wait;
+        return this.sendAndWait(input, options.timeoutMs, true, (request) => this.sendActorUpdate(request));
     }
     /**
      * Send a single voxel (block) update for spatial replication to nearby
@@ -358,13 +372,7 @@ export class UdpAPI {
      *   (its `code` is the server's `errorCode`).
      */
     async sendVoxelUpdateAndWait(input, options = {}) {
-        const request = this.withSequence(input);
-        const wait = this.subs.waitForSequence(request.sequenceNumber, options.timeoutMs);
-        await this.sendVoxelUpdate(request);
-        // Nothing can be echoed that has not left: the bundled relay path holds a
-        // send for up to bundleWindowMs, so put it on the wire before waiting.
-        this.subs.flushSends();
-        return wait;
+        return this.sendAndWait(input, options.timeoutMs, true, (request) => this.sendVoxelUpdate(request));
     }
     /**
      * Send a spatial voice/audio packet, fanned out to nearby actors as a
@@ -423,13 +431,7 @@ export class UdpAPI {
      *   `errorCode`, e.g. `UNAUTHORIZED` for a missing voice permission).
      */
     async sendAudioPacketAndWait(input, options = {}) {
-        const request = this.withSequence(input);
-        const wait = this.subs.waitForSequence(request.sequenceNumber, options.timeoutMs);
-        await this.sendAudioPacket(request);
-        // Nothing can be echoed that has not left: the bundled relay path holds a
-        // send for up to bundleWindowMs, so put it on the wire before waiting.
-        this.subs.flushSends();
-        return wait;
+        return this.sendAndWait(input, options.timeoutMs, false, (request) => this.sendAudioPacket(request));
     }
     /**
      * Send ONE webcam video fragment, fanned out to nearby actors as a
@@ -540,13 +542,7 @@ export class UdpAPI {
      *   `errorCode`).
      */
     async sendTextPacketAndWait(input, options = {}) {
-        const request = this.withSequence(input);
-        const wait = this.subs.waitForSequence(request.sequenceNumber, options.timeoutMs);
-        await this.sendTextPacket(request);
-        // Nothing can be echoed that has not left: the bundled relay path holds a
-        // send for up to bundleWindowMs, so put it on the wire before waiting.
-        this.subs.flushSends();
-        return wait;
+        return this.sendAndWait(input, options.timeoutMs, false, (request) => this.sendTextPacket(request));
     }
     /**
      * Send a custom, app-defined client event for spatial replication to nearby
@@ -603,13 +599,7 @@ export class UdpAPI {
      *   `errorCode`).
      */
     async sendClientEventAndWait(input, options = {}) {
-        const request = this.withSequence(input);
-        const wait = this.subs.waitForSequence(request.sequenceNumber, options.timeoutMs);
-        await this.sendClientEvent(request);
-        // Nothing can be echoed that has not left: the bundled relay path holds a
-        // send for up to bundleWindowMs, so put it on the wire before waiting.
-        this.subs.flushSends();
-        return wait;
+        return this.sendAndWait(input, options.timeoutMs, false, (request) => this.sendClientEvent(request));
     }
     /**
      * Send a direct actor-to-actor message, delivered only to the actor whose
@@ -824,6 +814,59 @@ export class UdpAPI {
     subscribe(handlers, appId) {
         return this.subs.subscribe(handlers, appId);
     }
+    /**
+     * What every `send*AndWait` does.
+     *
+     * The wait is registered before the send, so an echo that beats the send's
+     * own response is not missed, and its clock starts once the send has been
+     * accepted, so a lazy proxy-session open or the relay's handshake on the send
+     * leg is not taken from the echo's window.
+     *
+     * The first awaited send of a new session (the first connect, a reconnect, or
+     * a move to another instance) is retried once, with a fresh sequence number,
+     * when it is refused `UNAUTHORIZED` or, for a send the server echoes, when
+     * its echo times out: a game server from before the one that holds a
+     * session's first messages refuses or drops them while the session's
+     * permissions load. A send the server does not echo (audio, text, a client
+     * event) succeeds by timing out, so its timeout is never retried. Only when
+     * the SDK chose the sequence number, because the retry needs one of its own
+     * and a caller who chose theirs is correlating by it.
+     */
+    async sendAndWait(input, timeoutMs, echoed, send) {
+        const epoch = this.subs.sessionEpoch();
+        const retryable = epoch !== this.confirmedEpoch && input.sequenceNumber == null;
+        try {
+            const echo = await this.sendOnceAndWait(this.withSequence(input), timeoutMs, send).catch((error) => {
+                if (!retryable || !isFirstSendFailure(error, echoed))
+                    throw error;
+                return this.sendOnceAndWait(this.withSequence({ ...input, sequenceNumber: undefined }), timeoutMs, send);
+            });
+            this.confirmedEpoch = epoch;
+            return echo;
+        }
+        catch (error) {
+            // A send the server does not echo succeeds by timing out, and that
+            // answers for the session as well as an echo would.
+            if (!echoed && isTimeout(error))
+                this.confirmedEpoch = epoch;
+            throw error;
+        }
+    }
+    async sendOnceAndWait(request, timeoutMs, send) {
+        const wait = this.subs.expectSequence(request.sequenceNumber, timeoutMs);
+        try {
+            await send(request);
+        }
+        catch (error) {
+            wait.cancel();
+            throw error;
+        }
+        // Nothing can be echoed that has not left: the bundled relay path holds a
+        // send for up to bundleWindowMs, so put it on the wire before waiting.
+        this.subs.flushSends();
+        wait.start();
+        return wait.promise;
+    }
     withSequence(input) {
         return {
             ...input,
@@ -831,3 +874,11 @@ export class UdpAPI {
         };
     }
 }
+/** How a session's first message failed on a game server that did not hold it. */
+function isFirstSendFailure(error, echoed) {
+    return (error instanceof CrowdyRealtimeError &&
+        (error.code === 'UNAUTHORIZED' || (echoed && isTimeout(error))));
+}
+function isTimeout(error) {
+    return error instanceof CrowdyRealtimeError && error.code === 'UDP_SEQUENCE_TIMEOUT';
+}

package/dist/generated/graphql-schema.d.ts

@@ -8951,7 +8951,7 @@ export declare enum UdpErrorCode {
     PasswordTooShort = "PASSWORD_TOO_SHORT",
     /** The app-scoped gameplay token has expired. Refresh it (same app, via refreshAppToken) before it lapses, or re-portal through the Overworld for a fresh token, then re-authorize the realtime session. */
     TokenExpired = "TOKEN_EXPIRED",
-    /** The caller lacks the runtime/grid permission required for this action. Grid permissions can load asynchronously, so the first message to a newly entered region may transiently return this — retry shortly. */
+    /** The caller lacks the runtime/grid permission required for this action. A message sent right after connecting or entering a new region waits for that permission to load rather than being refused, so this means the permission is missing or could not be confirmed in time; after a move or a new session, one retry is enough to tell the two apart. */
     Unauthorized = "UNAUTHORIZED",
     /** Unspecified server error (1). Retry; if it persists, report it. */
     UnknownError = "UNKNOWN_ERROR",