@tesana/sdk 1.0.4 → 1.1.0

package/dist/tesana.iife.js

@@ -1,10 +1,10 @@
-/* Tesana play-time SDK v1.0.4 */
+/* Tesana play-time SDK v1.1.0 */
 (function (root) {
 /**
  * Tesana play-time SDK. Vanilla JS, no npm in games.
  * Host injects window.__TESANA__ or postMessage { type: "tesana-bootstrap", ... }.
  * v1 is player identity, per-game saves, optional open-lobby multiplayer,
- * cloud saves, and the in-game coin economy.
+ * cloud saves, the in-game coin economy, and gameplay analytics.
  *
  * THIS FILE IS THE ONE COPY. It is the source of truth for `window.Tesana`:
  * the engine injects the built artifact into every game and the CDN serves it
@@ -39,7 +39,11 @@
 // 1.0.0 ships six services together: saves, shop, leaderboards, achievements,
 // a vanity address (`tesana.vanity`) and in-game ads (`tesana.ads`). These are
 // the first release, so there is no earlier number to stay compatible with.
-const VERSION = "1.0.4";
+//
+// 1.1.0 adds gameplay analytics, `tesana.track` and `tesana.gameplay.*`. The
+// engine's analytics skill already taught them, so a game following it threw a
+// TypeError on its first death; this is the release that makes those calls real.
+const VERSION = "1.1.0";
 
 const LOCAL_CACHE = "tesana.play.v1";
 
@@ -55,6 +59,21 @@ const LOCAL_CACHE = "tesana.play.v1";
 const MP_RECONNECT_BASE_MS = 1000;
 const MP_RECONNECT_MAX_MS = 30000;
 const MP_RECONNECT_MAX_ATTEMPTS = 8;
+//: How long to wait for the host to answer a bootstrap request before giving
+//: up on that attempt. The answer is a token mint; a host that is slow must not
+//: hold a request open indefinitely.
+const MP_HOST_ASK_TIMEOUT_MS = 5000;
+//: How long `create`/`quickJoin` will wait for a room that is being placed.
+//:
+//: Room creation on GameLift is asynchronous, so the service answers 202 with
+//: no `wsUrl` and a `retryAfterMs` instead of holding the request open. The
+//: client polls until the room is ready or this budget runs out. It is longer
+//: than the service's own placement poll (90s) only in the sense that it gives
+//: up first: a client should decide for itself how long it will wait, and a
+//: game can watch `onStatus` rather than being blocked.
+const MP_PLACING_TIMEOUT_MS = 45000;
+//: Default gap between placement polls, used when the service does not say.
+const MP_PLACING_RETRY_MS = 1500;
 
 /**
  * A polite, dns-safe label: lowercase letters, digits and internal hyphens,
@@ -128,6 +147,18 @@ const bootstrapWaiters = [];
 // can re-point them in place. A game holds a reference to its client, so it
 // must not be rebuilt — only upgraded.
 const upgradeHandlers = [];
+// Whether a bootstrap the client asked for is in flight. It is what makes a
+// late answer an update rather than an unsolicited message that re-points a
+// live session.
+let bootstrapRequestPending = false;
+// The in-flight ask, so a burst of refused calls mints once rather than once
+// per caller. The host does its own rate-limiting; this only removes the
+// duplicate round-trips a simultaneous burst would otherwise make.
+let bootstrapAskPromise = null;
+//: Bumped every time a host answer replaces the live bootstrap. A caller that
+//: asked for a fresh token can tell whether it actually arrived by watching
+//: this, without having to hold a listener of its own.
+let bootstrapGeneration = 0;
 
 /**
  * Diagnostics that should say their piece once per session, not once per call.
@@ -152,17 +183,34 @@ function isGuestBootstrap(data) {
 }
 
 /** Fold a host's answer into the live config, upgrading a provisional one. */
-function applyBootstrap(data) {
+function applyBootstrap(data, opts = {}) {
   const next = data && typeof data === "object" ? data : {};
+  // Whether the client asked for this answer. A bootstrap it asked for is a
+  // refresh — its token aged out and the host minted another — and may update a
+  // live session. One it did not ask for may not, or anything able to post into
+  // the frame could re-point a running game's credential and identity.
+  const asked = opts.force || bootstrapRequestPending;
+  bootstrapRequestPending = false;
   if (bootstrap) {
     // A real host has already answered — unless that answer was a guest and
     // this one is the account they just signed in to.
-    if (!bootstrap.offline && !(isGuestBootstrap(bootstrap) && !next.offline && !isGuestBootstrap(next))) return;
+    if (!bootstrap.offline && !(isGuestBootstrap(bootstrap) && !next.offline && !isGuestBootstrap(next))) {
+      if (asked) {
+        // A forced update may refresh credentials (token, save token, room
+        // token) but never the player's identity: the player is who the
+        // signing-in page said they are, and a stale or mismatched answer must
+        // not silently become them.
+        if (bootstrap.player && next.player !== undefined) delete next.player;
+      } else {
+        return;
+      }
+    }
     // Still offline, unless it now carries a room token: a signed-out
     // visitor's multiplayer arrives after the site has already said "offline".
-    if (next.offline && !(next.roomToken && !bootstrap.roomToken)) return;
+    if (next.offline && !(next.roomToken && !bootstrap.roomToken) && !asked) return;
   }
   bootstrap = next;
+  bootstrapGeneration += 1;
   window.__TESANA__ = { ...(window.__TESANA__ || {}), ...next };
   const waiting = bootstrapWaiters.splice(0);
   for (const resolve of waiting) resolve(bootstrap);
@@ -404,6 +452,8 @@ function startListening() {
     // The site posts `{ type, payload }`; a baked or spliced bootstrap is the
     // payload itself. Accept both, so one SDK reads either host.
     if (data.type === "tesana-bootstrap") {
+      // `applyBootstrap` decides whether this answer may update a live session:
+      // one the client asked for may, one it did not may not.
       applyBootstrap(data.payload && typeof data.payload === "object" ? data.payload : data);
       return;
     }
@@ -466,16 +516,73 @@ function waitBootstrap(timeoutMs = 1500) {
   if (bootstrap) return Promise.resolve(bootstrap);
 
   startListening();
-  // Ask, rather than wait to be told. The frame can finish loading before the
-  // site has minted the session, and a request is what makes the site post the
-  // second time — without it a signed-in player's real bootstrap never arrives.
-  post({ type: "tesana-bootstrap-request" });
   return new Promise((resolve) => {
+    // The waiter is registered before the ask goes out. A host that answers
+    // from the same tick — a test double, or a same-document frame — would
+    // otherwise be answered into an empty list and the game would fall to
+    // "offline" a second and a half later for no reason.
     bootstrapWaiters.push(resolve);
     setTimeout(() => applyBootstrap({ offline: true }), timeoutMs);
+    // Ask, rather than wait to be told. The frame can finish loading before the
+    // site has minted the session, and a request is what makes the site post the
+    // second time — without it a signed-in player's real bootstrap never arrives.
+    askHostForBootstrap();
   });
 }
 
+/** Ask the host to post a bootstrap. Shared by boot and refresh, so the flag
+ * that makes an answer an update is set in exactly one place. The message name
+ * is what tells the host whether to re-mint or merely re-post. */
+function askHostForBootstrap(type = "tesana-bootstrap-request") {
+  bootstrapRequestPending = true;
+  post({ type });
+}
+
+/**
+ * Ask the host for a fresh bootstrap after a credential was refused.
+ *
+ * This is the SDK half of token expiry. A player token lives two hours and
+ * used to be re-minted only on a page load, so after two hours a blip was
+ * permanent until the player reloaded. Asking the host re-mints through it, and
+ * the answer flows back through the same upgrade path identity and ads already
+ * use, so a live game is re-pointed in place.
+ *
+ * Resolves with the new bootstrap, or `null` when there is no host or the host
+ * did not answer in time. Concurrent callers share one ask: a game that has
+ * been open for hours hits a burst of refusals at once, and one mint is what
+ * all of them needed. The host rate-limits the mints themselves.
+ *
+ * @returns {Promise<object|null>}
+ */
+function requestHostBootstrap() {
+  if (typeof window === "undefined") return Promise.resolve(null);
+  if (bootstrapAskPromise) return bootstrapAskPromise;
+  startListening();
+  const askedAt = bootstrapGeneration;
+  // A refresh, named as one. The host re-mints on this and merely re-posts on a
+  // boot request, so the two are never confused.
+  askHostForBootstrap("tesana-bootstrap-refresh");
+  bootstrapAskPromise = new Promise((resolve) => {
+    let done = false;
+    const finish = (value) => {
+      if (done) return;
+      done = true;
+      clearInterval(poll);
+      clearTimeout(expiry);
+      bootstrapAskPromise = null;
+      resolve(value);
+    };
+    // The bootstrap is delivered by the module-level listener, so watch the
+    // generation rather than registering a second listener — the token the host
+    // mints is scoped to this frame and is not ours to consume only here.
+    const poll = setInterval(() => {
+      if (bootstrapGeneration !== askedAt) finish(bootstrap);
+    }, 25);
+    const expiry = setTimeout(() => finish(null), MP_HOST_ASK_TIMEOUT_MS);
+  });
+  return bootstrapAskPromise;
+}
+
 function deviceId() {
   const cache = readCache();
   if (cache.deviceId) return cache.deviceId;
@@ -520,6 +627,308 @@ function post(message) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Gameplay analytics: `tesana.track` and `tesana.gameplay`
+// ---------------------------------------------------------------------------
+//
+// A game reports what happened in it (a level started, the player died, a run
+// ended with a score) so its creator can see where players get stuck and where
+// they quit. The pipe already exists end to end: the runtime shell injected
+// into every web build exposes `window.__TESANA_EVENT__`, the Tesana page above
+// the game buffers `tesana-gameplay-event` messages and files them against the
+// play session with a token only it holds, and the ingest endpoint stores them.
+// These functions are the game's end of that pipe.
+//
+// Three rules shape everything below:
+//
+//   - **Never throw.** The engine tells the AI to call these inline, at the
+//     moment a player dies, with no guard. A TypeError here would turn a death
+//     into a crash, so every entry point is wrapped and answers `false` when it
+//     drops something.
+//   - **Match the ingest endpoint's caps.** The server keeps at most 20 payload
+//     keys, 40-character keys, 64-character strings and 2,000 characters in all,
+//     and throws away the whole payload when it is over. Trimming here means a
+//     slightly-too-big event loses a key rather than all of its context.
+//   - **Discrete moments, not frames.** A game that reports on every frame
+//     would fill the table and answer nothing, so events are rate limited per
+//     second and capped per page load.
+//
+// They are synchronous and need no `init()`: they never touch the play service,
+// only the page, so a game can report a level start on its first frame.
+
+//: The message the host's play tracking listens for. Mirrored by the web host
+//: (`PLAY_MESSAGES.gameplayEvent`) and the runtime shell.
+const GAMEPLAY_MESSAGE = "tesana-gameplay-event";
+
+//: The event types the ingest endpoint understands, minus the two the shell
+//: owns (`session_end`, `error`). `track()` with one of these names files the
+//: event under that type; any other name is a `custom` event.
+const GAMEPLAY_EVENT_TYPES = new Set(["level_start", "level_complete", "death", "checkpoint", "score"]);
+const GAMEPLAY_TYPE_ALIASES = { levelStart: "level_start", levelComplete: "level_complete" };
+
+//: The ingest endpoint's own limits (`games/api/play_events.py`).
+const GAMEPLAY_NAME_MAX = 64;
+const GAMEPLAY_STRING_MAX = 64;
+const GAMEPLAY_KEY_MAX = 40;
+const GAMEPLAY_PROPS_MAX_KEYS = 20;
+const GAMEPLAY_PROPS_MAX_CHARS = 2000;
+
+//: At most this many events in any one second. Ten a second is exactly what
+//: one host flush can carry (100 events every 10 seconds), and far above what a
+//: game reporting real moments ever needs.
+const GAMEPLAY_RATE_PER_SECOND = 10;
+//: At most this many events per page load. An honest session sends tens; a
+//: game stuck reporting at the rate limit for an hour would send 36,000.
+const GAMEPLAY_SESSION_MAX = 1000;
+
+//: Props promoted to the event's own columns rather than kept as context.
+const GAMEPLAY_LEVEL_ID_KEYS = ["levelId", "level_id", "level"];
+const GAMEPLAY_LEVEL_INDEX_KEYS = ["levelIndex", "level_index"];
+const GAMEPLAY_NUMBER_KEYS = ["x", "y", "z", "value"];
+const GAMEPLAY_PROMOTED = new Set([
+  ...GAMEPLAY_LEVEL_ID_KEYS,
+  ...GAMEPLAY_LEVEL_INDEX_KEYS,
+  ...GAMEPLAY_NUMBER_KEYS,
+  "name",
+]);
+
+let gameplaySecond = -1;
+let gameplayInSecond = 0;
+let gameplaySent = 0;
+
+/** A finite number, or `undefined`. Numeric strings count; NaN never does. */
+function gameplayNumber(value) {
+  if (typeof value === "number") return Number.isFinite(value) ? value : undefined;
+  if (typeof value === "string" && value.trim() !== "") {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+  return undefined;
+}
+
+/** A trimmed, capped string id from a string or a number, or `undefined`. */
+function gameplayId(value, limit) {
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) return undefined;
+    return String(value).slice(0, limit);
+  }
+  if (typeof value !== "string") return undefined;
+  const text = value.trim().slice(0, limit);
+  return text || undefined;
+}
+
+/** The first of `keys` that `props` holds a value for. */
+function gameplayFirst(props, keys) {
+  for (const key of keys) {
+    if (props[key] !== undefined && props[key] !== null) return props[key];
+  }
+  return undefined;
+}
+
+/**
+ * Roughly how long the server's `repr()` of this payload will be.
+ *
+ * The endpoint measures Python's `repr`, not JSON: it writes `1.0` for `1` and
+ * puts a space after each colon and comma. Four characters per key is a safe
+ * margin over both differences, so a payload that passes here passes there.
+ */
+function gameplayPayloadSize(payload, keys) {
+  return JSON.stringify(payload).length + 4 * keys;
+}
+
+/**
+ * Keep the scalar context a game passed, within the endpoint's caps.
+ *
+ * @param {object} props
+ * @param {boolean} keepName keep a `name` prop as context (a custom event, whose
+ *   own name is the event's name) rather than treating it as the name column
+ */
+function gameplayPayload(props, keepName) {
+  const payload = {};
+  let kept = 0;
+  for (const rawKey of Object.keys(props)) {
+    if (kept >= GAMEPLAY_PROPS_MAX_KEYS) break;
+    if (GAMEPLAY_PROMOTED.has(rawKey) && !(keepName && rawKey === "name")) continue;
+    const key = String(rawKey).trim().slice(0, GAMEPLAY_KEY_MAX);
+    if (!key || Object.prototype.hasOwnProperty.call(payload, key)) continue;
+    let value;
+    try {
+      value = props[rawKey];
+    } catch {
+      continue;
+    }
+    if (typeof value === "string") {
+      value = value.slice(0, GAMEPLAY_STRING_MAX);
+    } else if (typeof value === "number") {
+      if (!Number.isFinite(value)) continue;
+    } else if (typeof value !== "boolean" && value !== null) {
+      // Objects, arrays, functions, undefined, symbols and bigints are not
+      // stored: the analytics layer queries flat keys, and a nested shape it
+      // did not expect is a foot-gun rather than a feature.
+      continue;
+    }
+    payload[key] = value;
+    if (gameplayPayloadSize(payload, kept + 1) > GAMEPLAY_PROPS_MAX_CHARS) {
+      delete payload[key];
+      continue;
+    }
+    kept += 1;
+  }
+  return kept ? payload : null;
+}
+
+/**
+ * Build the event the host files, in the shape `POST /play/events` accepts.
+ *
+ * @param {string} type one of the ingest endpoint's event types
+ * @param {string|undefined} name the event's own name (a custom event, a death's cause)
+ * @param {object} props what the game passed
+ */
+function gameplayEvent(type, name, props) {
+  const event = { type };
+  const named = name !== undefined ? name : gameplayId(props.name, GAMEPLAY_NAME_MAX);
+  if (named) event.name = named;
+  const levelId = gameplayId(gameplayFirst(props, GAMEPLAY_LEVEL_ID_KEYS), GAMEPLAY_STRING_MAX);
+  if (levelId) event.level_id = levelId;
+  const levelIndex = gameplayNumber(gameplayFirst(props, GAMEPLAY_LEVEL_INDEX_KEYS));
+  if (levelIndex !== undefined) event.level_index = Math.max(0, Math.floor(levelIndex));
+  for (const key of GAMEPLAY_NUMBER_KEYS) {
+    const number = gameplayNumber(props[key]);
+    if (number !== undefined) event[key] = number;
+  }
+  // A custom event's own name is already its name, so a `name` prop is kept as
+  // context like any other key instead of overwriting it.
+  const payload = gameplayPayload(props, type === "custom");
+  if (payload) event.payload = payload;
+  event.ts = Date.now();
+  return event;
+}
+
+/** Whether one more event fits this second and this page load. */
+function gameplayAllowed() {
+  if (gameplaySent >= GAMEPLAY_SESSION_MAX) {
+    warnOnce(
+      "gameplay-session-max",
+      `tesana.track: ${GAMEPLAY_SESSION_MAX} events this session; further events are dropped. Report discrete moments (a level, a death, a run's end), never every frame.`,
+    );
+    return false;
+  }
+  const second = Math.floor(Date.now() / 1000);
+  if (second !== gameplaySecond) {
+    gameplaySecond = second;
+    gameplayInSecond = 0;
+  }
+  if (gameplayInSecond >= GAMEPLAY_RATE_PER_SECOND) {
+    warnOnce(
+      "gameplay-rate",
+      `tesana.track: more than ${GAMEPLAY_RATE_PER_SECOND} events in one second; the extra ones are dropped. Report discrete moments, never every frame.`,
+    );
+    return false;
+  }
+  gameplayInSecond += 1;
+  gameplaySent += 1;
+  return true;
+}
+
+/**
+ * Hand an event to whoever files it. `true` when it was handed on.
+ *
+ * The shell's `__TESANA_EVENT__` comes first: it posts the same message, and
+ * going through it lets the shell name the last level in its `session_end`.
+ * Without the shell, the message goes straight to the Tesana page above. With
+ * neither there is nobody to tell, and the event is dropped.
+ */
+function gameplayDeliver(event) {
+  if (typeof window === "undefined") return false;
+  const bridge = window.__TESANA_EVENT__;
+  if (typeof bridge === "function") {
+    bridge(event);
+    return true;
+  }
+  if (!hasHost()) return false;
+  post({ type: GAMEPLAY_MESSAGE, event });
+  return true;
+}
+
+/** The game's props as a plain object, whatever it actually passed. */
+function gameplayProps(props) {
+  return props && typeof props === "object" && !Array.isArray(props) ? props : {};
+}
+
+/**
+ * Report something that happened in the game.
+ *
+ * `name` is the game's own name for it (`"powerup_picked"`). A name that is one
+ * of the platform's types (`"death"`, `"level_start"`, `"level_complete"`,
+ * `"checkpoint"`, `"score"`) is filed as that type. `props` is a small object of
+ * scalars; `levelId`, `levelIndex`, `x`, `y`, `z` and `value` become columns and
+ * anything else rides along as context.
+ *
+ * Synchronous, never throws, and never returns a promise: `true` when the event
+ * was handed on, `false` when it was dropped (a bad name, too many events, or
+ * nothing above the game to hand it to).
+ *
+ * @param {string} name
+ * @param {Record<string, string|number|boolean|null>} [props]
+ * @returns {boolean}
+ */
+function track(name, props) {
+  try {
+    const label = gameplayId(name, GAMEPLAY_NAME_MAX);
+    if (!label) {
+      warnOnce("gameplay-name", "tesana.track: the first argument must be a non-empty event name.");
+      return false;
+    }
+    if (!gameplayAllowed()) return false;
+    const builtIn = GAMEPLAY_TYPE_ALIASES[label] || label;
+    const event = GAMEPLAY_EVENT_TYPES.has(builtIn)
+      ? gameplayEvent(builtIn, undefined, gameplayProps(props))
+      : gameplayEvent("custom", label, gameplayProps(props));
+    return gameplayDeliver(event);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * One gameplay helper. `props` may also be a bare level id (`levelStart(3)`), or
+ * for `score` a bare value (`score(1200)`).
+ *
+ * @param {string} type
+ * @param {"levelId"|"value"} shorthand
+ */
+function gameplayHelper(type, shorthand) {
+  return function report(props) {
+    try {
+      if (!gameplayAllowed()) return false;
+      const given = typeof props === "string" || typeof props === "number"
+        ? { [shorthand]: props }
+        : gameplayProps(props);
+      return gameplayDeliver(gameplayEvent(type, undefined, given));
+    } catch {
+      return false;
+    }
+  };
+}
+
+/**
+ * The progression events every game with levels, waves, runs or deaths should
+ * send. `levelId` is the join key: give it the same stable value in each call
+ * for one level, so a funnel can line them up.
+ */
+const gameplay = Object.freeze({
+  /** A level, stage, wave or area begins: `{ levelId, levelIndex? }`. */
+  levelStart: gameplayHelper("level_start", "levelId"),
+  /** A level is cleared: `{ levelId }`. */
+  levelComplete: gameplayHelper("level_complete", "levelId"),
+  /** The player died: `{ levelId, x?, y?, z?, name? }` (`name` is the cause). */
+  death: gameplayHelper("death", "levelId"),
+  /** A checkpoint is reached: `{ levelId, name? }`. */
+  checkpoint: gameplayHelper("checkpoint", "levelId"),
+  /** A run ended: `{ value, levelId? }`. */
+  score: gameplayHelper("score", "value"),
+});
+
 /**
  * @param {TesanaConfig} [config]
  */
@@ -647,6 +1056,9 @@ function buildConfig(merged) {
     locale: normalizeLocale(
       merged.locale || merged.language || merged.lang || (typeof navigator !== "undefined" && navigator.language) || "",
     ),
+    // How a dropped room socket is retried. A game can shrink the waits (a
+    // test, or a game with unusual tolerance); the defaults are the fleet's.
+    multiplayerReconnect: merged.multiplayerReconnect || undefined,
   };
 }
 
@@ -709,6 +1121,10 @@ class TesanaClient {
       leaving: false,
       reconnectTimer: null,
       reconnectAttempts: 0,
+      // The code of the last close we saw. 4401 means the grant was refused —
+      // expired, most likely — and a fresh one has to be minted before the next
+      // reconnect can succeed. Cleared once a reconnect has used it.
+      lastCloseCode: null,
       reconnectExhausted: false,
       statusHandlers: [],
       // Overridable so a test (or a game with unusual tolerance) can shorten
@@ -925,6 +1341,12 @@ class TesanaClient {
     this.l10n = this._makeL10n(opts);
     l10nClient = this.l10n;
 
+    // Gameplay analytics. The same functions as `Tesana.track` and
+    // `Tesana.gameplay` on the global, so a game can call them before its
+    // `await __TESANA_READY__` resolves; none of them depends on this client.
+    this.track = track;
+    this.gameplay = gameplay;
+
     this.multiplayer = {
       // Read this before drawing a lobby: when it is false the game is not
       // allowed rooms yet and the calls below refuse.
@@ -1153,7 +1575,7 @@ class TesanaClient {
    * @param {Promise<{ wsUrl: string, roomId?: string, room?: object, playerId?: string }>} session
    */
   async _mpEnter(session) {
-    const joined = await session;
+    const joined = await this._mpAwaitPlacement(await session);
     // A room that was opened and then could not be entered is reported as what
     // it is: the room exists. The SDK cannot seat the player — that is the
     // host's job — but it can name the room so a game retries `join(roomId)`
@@ -1180,6 +1602,56 @@ class TesanaClient {
     };
   }
 
+  /**
+   * Wait out a room that is still being placed, then hand back its session.
+   *
+   * Room creation on GameLift outlives a single HTTP request — a cold fleet can
+   * take minutes — so the service answers 202 with the room's identity, the
+   * caller's seat, and `retryAfterMs`, and no `wsUrl`. Treating that as a failed
+   * create is what used to leave a ghost: the room existed, its creator was
+   * seated, and the client believed nothing had happened. So the client polls
+   * the same room it was handed (`join` re-issues the seat, it does not take a
+   * second) until the address exists or the wait budget runs out.
+   *
+   * The budget is the client's own. A game that would rather show a spinner and
+   * decide for itself calls `join(roomId)` after `create` rejects with
+   * `mp_room_placing`, and this consumes the same code path.
+   *
+   * @param {{ wsUrl?: string, roomId?: string, state?: string, retryAfterMs?: number, room?: object }} session
+   */
+  async _mpAwaitPlacement(session) {
+    if (!session || session.wsUrl || session.state !== "placing") return session;
+    const roomId = session.roomId || session.room?.id;
+    if (!roomId) return session;
+    this._mpEmitStatus({ status: "placing", roomId });
+    // Instance-overridable so a game (or a test) can decide how long it will
+    // wait for placement without reaching into module scope.
+    const budget = Number(this._mpPlacingTimeoutMs) || MP_PLACING_TIMEOUT_MS;
+    const deadline = Date.now() + budget;
+    let current = session;
+    while (!current?.wsUrl && Date.now() < deadline) {
+      const gap = Math.max(250, Number(current.retryAfterMs) || MP_PLACING_RETRY_MS);
+      await new Promise((resolve) => setTimeout(resolve, Math.min(gap, Math.max(0, deadline - Date.now()))));
+      if (Date.now() >= deadline) break;
+      try {
+        current = await this._mpRequest("POST", `/v1/mp/rooms/${enc(roomId)}/join`, {});
+      } catch (err) {
+        // A 404 here is a room that ended between polls, which is a real
+        // failure; anything else is worth another try until the budget is gone.
+        if (err?.status === 404) throw err;
+      }
+    }
+    if (!current?.wsUrl) {
+      // The room is still real, so the code names it and says so — a game can
+      // choose to keep waiting with `join(roomId)` rather than start over.
+      const err = new Error("Room is still starting");
+      err.code = "mp_room_placing";
+      err.roomId = roomId;
+      throw err;
+    }
+    return current;
+  }
+
   /**
    * @param {string} wsUrl
    */
@@ -1238,13 +1710,22 @@ class TesanaClient {
         if (this._mp.ws === ws) this._mp.ws = null;
         if (!opened) {
           clearTimeout(timer);
-          reject(new Error(event.reason || "multiplayer closed"));
+          const err = new Error(event.reason || "multiplayer closed");
+          // The code is carried, not just the reason: 4401 is an expired or
+          // rejected grant, which a re-mint can fix, while 4403 is the game
+          // being denied rooms, which it cannot. Recovery keys off this.
+          err.code = event.code || 1006;
+          // Recorded for the same reason: a reconnect whose fresh grant is
+          // *also* refused must mint again rather than retry a dead URL.
+          if (this._mp.wsUrl) this._mp.lastCloseCode = event.code || null;
+          reject(err);
           return;
         }
         // The socket dropped after we were in the room. That is a scale-in,
         // a deploy, or a network blip — none of which the player caused, and
         // all of which used to leave them silently alone in a match. Retry
         // unless they actually meant to leave.
+        this._mp.lastCloseCode = event.code || null;
         this._mpScheduleReconnect();
       };
     });
@@ -1276,7 +1757,7 @@ class TesanaClient {
     mp.reconnectTimer = setTimeout(() => {
       mp.reconnectTimer = null;
       if (mp.leaving) return;
-      this._mpOpen(mp.wsUrl).catch(() => {
+      this._mpReconnectAttempt().catch(() => {
         // Still not up — schedule the next attempt, which is where the
         // attempt count grows and the backoff widens.
         this._mpScheduleReconnect();
@@ -1284,6 +1765,56 @@ class TesanaClient {
     }, delay);
   }
 
+  /**
+   * One reconnect: get a current grant if the last one was refused, then try the
+   * room again.
+   *
+   * The grant the client holds is embedded in `wsUrl` and was minted when it
+   * first joined. A game open longer than the token's life therefore cannot
+   * re-enter on a reconnect, and the backoff above only retries the same dead
+   * URL — the player sits in "reconnecting" until they reload. Re-requesting the
+   * room session mints a fresh URL, and `mpJoin` is idempotent, so asking as an
+   * already-seated player re-issues the same seat rather than a second one.
+   *
+   * The fresh grant itself comes from the ordinary 401 path in `_send`: the join
+   * goes out with the token the client already has, comes back refused, and is
+   * retried once with one minted token. That is deliberate — it keeps the mint in
+   * the one place that knows how to do it, so a stale socket and a stale HTTP
+   * call recover identically and only ever ask the host once between them.
+   */
+  async _mpReconnectAttempt() {
+    const mp = this._mp;
+    let wsUrl = mp.wsUrl;
+    // 4401 — the grant was refused, so the URL itself is dead and a fresh one is
+    // required. 4409 — the room is being re-placed and has no address yet, so
+    // the URL the client holds is not usable either. Both are fixed by asking
+    // for the room again; 4403 (the game is denied rooms) and 4404 (the room is
+    // gone) are not, and fall through to the URL we have so the attempt is still
+    // counted and the backoff still applies.
+    if ((mp.lastCloseCode === 4401 || mp.lastCloseCode === 4409) && mp.roomId) {
+      try {
+        // `_mpAwaitPlacement` is harmless when the room is already up (it
+        // returns the session untouched) and necessary when a reconnect lands
+        // during a re-placement — a 4409 close, or a room swept and reopened,
+        // answers with no `wsUrl`, and retrying the old URL would never work.
+        const session = await this._mpAwaitPlacement(
+          await this._mpRequest("POST", `/v1/mp/rooms/${enc(mp.roomId)}/join`),
+        );
+        if (session && session.wsUrl) {
+          wsUrl = session.wsUrl;
+          mp.wsUrl = wsUrl;
+          mp.code = session.room?.code ?? mp.code;
+        }
+      } catch {
+        // The room is gone, or the fresh grant was refused too. Fall through to
+        // the URL we have: the room may have been replaced under the same id,
+        // and if it has not, the next attempt retries this same path.
+      }
+    }
+    mp.lastCloseCode = null;
+    return this._mpOpen(wsUrl);
+  }
+
   _mpEmitStatus(status) {
     for (const fn of this._mp.statusHandlers) {
       try {
@@ -1317,7 +1848,14 @@ class TesanaClient {
    */
   _mpSend(data) {
     const ws = this._mp.ws;
-    if (!ws || ws.readyState !== 1) throw new Error("Not in a room");
+    if (!ws || ws.readyState !== 1) {
+      // Not a room failure — a socket that is between attempts. Tagged so a
+      // game can tell it from a real refusal, and so a caller that has an
+      // outbox can wait for the reconnect rather than drop the message.
+      const err = new Error("Not in a room");
+      err.code = "mp_not_connected";
+      throw err;
+    }
     ws.send(JSON.stringify(data && typeof data === "object" ? data : { value: data }));
   }
 
@@ -1355,6 +1893,7 @@ class TesanaClient {
     this._mp.wsUrl = null;
     this._mp.reconnectAttempts = 0;
     this._mp.reconnectExhausted = false;
+    this._mp.lastCloseCode = null;
     try {
       if (!roomId) return { ok: true, room: null };
       try {
@@ -1376,24 +1915,13 @@ class TesanaClient {
     return this._send(this._baseFor(), this._authFor(), method, path, body);
   }
 
-  /** Whether multiplayer rides a rooms-only token while everything else is offline. */
-  _roomsOnly() {
-    return Boolean(this.offline && this.roomEndpoint && this.roomToken);
-  }
-
-  _mpRequest(method, path, body) {
-    return this._roomsOnly()
-      ? this._send(this.roomEndpoint, this.roomToken, method, path, body)
-      : this.request(method, path, body);
-  }
-
-  async _send(base, authToken, method, path, body) {
+  /** One transport attempt, with no retry and no body parsing. */
+  async _fetchSend(base, authToken, method, path, body) {
     const headers = { "content-type": "application/json" };
     if (authToken) headers.authorization = `Bearer ${authToken}`;
     if (this.deviceId) headers["x-tesana-device"] = this.deviceId;
-    let res;
     try {
-      res = await fetch(`${base}${path}`, {
+      return await fetch(`${base}${path}`, {
         method,
         headers,
         body: body == null || method === "GET" ? undefined : JSON.stringify(body),
@@ -1406,6 +1934,34 @@ class TesanaClient {
       // still has, reported as missing.
       throw err;
     }
+  }
+
+  /** Whether multiplayer rides a rooms-only token while everything else is offline. */
+  _roomsOnly() {
+    return Boolean(this.offline && this.roomEndpoint && this.roomToken);
+  }
+
+  _mpRequest(method, path, body) {
+    return this._roomsOnly()
+      ? this._send(this.roomEndpoint, this.roomToken, method, path, body)
+      : this.request(method, path, body);
+  }
+
+  async _send(base, authToken, method, path, body) {
+    let res = await this._fetchSend(base, authToken, method, path, body);
+    // A refused credential is usually age, not refusal: the player token lives
+    // two hours. Ask the host to re-mint and retry once with the new one. The
+    // retry is guarded on the token actually changing, so a genuinely
+    // unauthorized player fails exactly as they did before rather than looping.
+    if (res.status === 401) {
+      // The ask may land on a host we cannot reach, so `asked` is null and the
+      // retry is skipped — the 401 below is thrown exactly as it always was.
+      const asked = await requestHostBootstrap();
+      const next = base === this.roomEndpoint ? this.roomToken : this._authFor();
+      if (asked && next && next !== authToken) {
+        res = await this._fetchSend(base, next, method, path, body);
+      }
+    }
     const data = await res.json().catch(() => ({}));
     if (!res.ok) {
       const error = new Error(data.message || res.statusText);
@@ -2125,7 +2681,7 @@ function enc(value) {
 }
 
 
-  var api = { init: init, TesanaClient: TesanaClient, version: VERSION };
+  var api = { init: init, TesanaClient: TesanaClient, version: VERSION, track: track, gameplay: gameplay };
   root.Tesana = api;
   // A game's first line may be `await window.__TESANA_READY__`, the promise
   // form the engine's skills teach, so start booting the moment this loads.