@tesana/sdk 1.0.3 → 1.1.0

package/dist/tesana.iife.js

@@ -1,10 +1,10 @@
-/* Tesana play-time SDK v1.0.3 */
+/* 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.3";
+//
+// 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);
@@ -199,6 +247,60 @@ function onBootstrapUpgrade(fn) {
  */
 let adClient = null;
 
+/**
+ * The live localization capability, kept module-scoped for the same reason as
+ * the ad client: the host can change the language at any moment, and the game
+ * holds a reference to `tesana.l10n` that must not be replaced underneath it.
+ * The listener calls `applyLocale`, which re-points this object in place.
+ */
+let l10nClient = null;
+
+/**
+ * The languages the platform can translate into, in display order.
+ *
+ * Mirrors the service's own list, which is the authority; this copy exists so a
+ * language picker can be drawn before the service has answered — and so a page
+ * with no host at all, where nothing will ever answer, still has an honest
+ * list rather than an empty one.
+ */
+const L10N_TARGETS = ["en", "es", "fr", "de", "it", "pt-BR", "ru", "zh", "ja", "ko"];
+
+/**
+ * Fold whatever a host calls a language onto one of ours.
+ *
+ * `navigator.language` reports `en-US` and `pt-PT`; a site may store `pt` or
+ * `zh`; a player may be handed `de-AT`. None of those are in the list above and
+ * all of them mean a language we do translate into, so the base tag is what
+ * gets matched and the region is dropped — a game in `pt-BR` is more useful to
+ * a `pt-PT` player than one left in English. An unknown tag stays as it is and
+ * simply falls back to the source language at the call site.
+ */
+function normalizeLocale(tag) {
+  const value = String(tag || "").trim().replace(/_/g, "-");
+  if (!value) return "";
+  const exact = L10N_TARGETS.find((t) => t.toLowerCase() === value.toLowerCase());
+  if (exact) return exact;
+  const base = value.split("-")[0].toLowerCase();
+  return L10N_TARGETS.find((t) => t.split("-")[0].toLowerCase() === base) || value;
+}
+
+/** `{name}` in `text`, filled from `values`. The one interpolation rule the SDK and the service share. */
+function fillPlaceholders(text, values) {
+  const source = String(text == null ? "" : text);
+  if (!values || typeof values !== "object") return source;
+  return source.replace(/\{(\w+)\}/g, (whole, key) =>
+    Object.prototype.hasOwnProperty.call(values, key) ? String(values[key]) : whole,
+  );
+}
+
+/** Fold a locale message from the host into the live client, if it is listening. */
+function resyncLocale(data) {
+  if (!l10nClient) return;
+  const payload = data && typeof data.payload === "object" ? data.payload : data;
+  const next = payload && (payload.locale || payload.lang || payload.language);
+  if (next) l10nClient.applyLocale(next);
+}
+
 /** A policy message from the host, or `null` when none is in force. */
 function adPolicyFrom(data) {
   if (!data || typeof data !== "object") return null;
@@ -350,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;
     }
@@ -368,6 +472,19 @@ function startListening() {
       }
       return;
     }
+    // The player changed the site's language. The host is the authority — it
+    // resolved which language the player wants, and it owns the setting — so
+    // this only carries it down. The game's own text re-renders when it draws
+    // again, which is why the skill tells games to redraw from `t()` rather
+    // than cache translated strings at startup.
+    if (data.type === "tesana-locale") {
+      try {
+        resyncLocale(data);
+      } catch {
+        /* a bad locale must never break the listener */
+      }
+      return;
+    }
     if (data.type === "tesana-ad-show") {
       try {
         const requestId = data.requestId || data.request_id;
@@ -399,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;
@@ -453,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]
  */
@@ -491,6 +967,16 @@ async function init(config = {}) {
   } catch (err) {
     client.goOffline(err);
   }
+  // Localization comes after identity, not before: the bundle is fetched with
+  // the player's token, so a game that just minted one would otherwise load it
+  // unauthenticated and stay in its source language all session. Awaited here
+  // so `await __TESANA_READY__` is genuinely enough — the first frame a game
+  // draws can already be translated.
+  try {
+    await client.l10n.reload();
+  } catch {
+    /* localization must never block the game's start */
+  }
   window.__TESANA_PLAYER__ = client.player.me();
   // A provisional "offline" answer can upgrade later. Re-point this client in
   // place — the game holds a reference to it — and re-run the identity step,
@@ -498,7 +984,7 @@ async function init(config = {}) {
   // player with a balance frozen at zero.
   const finishUpgrade = () => {
     client.configure(buildConfig(mergedConfig()));
-    client.ensureSession();
+    client.ensureSession().then(() => client.l10n.reload());
     window.__TESANA_PLAYER__ = client.player.me();
   };
   onBootstrapUpgrade(finishUpgrade);
@@ -561,6 +1047,18 @@ function buildConfig(merged) {
     adsEnabled: merged.adsEnabled,
     adFormats: merged.adFormats || merged.ad_formats || [],
     adMinIntervalMs: merged.adMinIntervalMs ?? merged.ad_min_interval_ms,
+    // The player's language, as the host resolved it. The host owns the
+    // setting (the site has a language picker and the game does not), so this
+    // is read from the bootstrap rather than sniffed here — a game that
+    // guessed from `navigator.language` would disagree with the site the
+    // player is reading. Absent means an older host: localization then falls
+    // back to the source language and the game renders exactly as it did.
+    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,
   };
 }
 
@@ -572,7 +1070,7 @@ function defaultEndpoint() {
 
 class TesanaClient {
   /**
-   * @param {{ endpoint: string, gameId: string, token: string, rail: string, deviceId: string, multiplayer?: boolean, saveEndpoint?: string, saveToken?: string, offline?: boolean, roomEndpoint?: string, roomToken?: string, player?: object|null, vanityAddress?: string, adsEnabled?: boolean }} opts
+   * @param {{ endpoint: string, gameId: string, token: string, rail: string, deviceId: string, multiplayer?: boolean, saveEndpoint?: string, saveToken?: string, offline?: boolean, roomEndpoint?: string, roomToken?: string, player?: object|null, vanityAddress?: string, adsEnabled?: boolean, locale?: string }} opts
    */
   constructor(opts) {
     this.endpoint = opts.endpoint;
@@ -615,12 +1113,18 @@ class TesanaClient {
       ws: null,
       handlers: [],
       roomId: null,
+      // The current room's share code, or null for a public room.
+      code: null,
       // Reconnect state. `wsUrl` is kept so a dropped socket can re-enter the
       // same room; `leaving` stops a deliberate leave from being retried.
       wsUrl: null,
       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
@@ -827,6 +1331,22 @@ class TesanaClient {
     // same object in place, rather than the game holding a stale policy.
     adClient = this.ads;
 
+    // Localization. A generated game draws its text onto a canvas, so the
+    // platform cannot translate the running game the way it translates the
+    // site's own pages — the game has to ask, and this is the surface it asks
+    // through. The same one rule as the shop: an unreachable service costs a
+    // translation and never the game. Every method here has a source-language
+    // answer, and `t()` is synchronous, so a menu never waits on a network to
+    // draw itself in the player's language.
+    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.
@@ -843,14 +1363,42 @@ class TesanaClient {
               .then((r) => r.rooms)
               .catch(() => [])
           : Promise.resolve([]),
+      // Open a room. It is public and always joinable unless you pass a `code`,
+      // which is the only way entry is restricted: the room is then unlisted and
+      // only someone with the code can reach it. The resolved code is on
+      // `room.code` in the result (the service generates one if you pass
+      // `code: true`), so show it to the room.
       create: (opts) =>
         this._mpEnabled
           ? this._mpEnter(this._mpRequest("POST", "/v1/mp/rooms", opts || {}))
           : this._mpRefuse(),
-      join: (roomId) =>
-        this._mpEnabled
-          ? this._mpEnter(this._mpRequest("POST", `/v1/mp/rooms/${enc(roomId)}/join`))
-          : this._mpRefuse(),
+      // Accept the room a game got from list() as well as from a session. Both
+      // read as "the room to join": `list()` rows are keyed `id`, a
+      // create/quickJoin/join result carries `roomId`. Taking an object here is
+      // what stops a lobby that calls `join(room)` from having to know which.
+      join: (room) => {
+        if (!this._mpEnabled) return this._mpRefuse();
+        const roomId =
+          room && typeof room === "object" ? room.id || room.roomId : room;
+        // The bug this guards: a game read `room.roomId` off a list() row,
+        // where it is undefined, and we asked the service for the room named
+        // "undefined" — a 404 indistinguishable from a deleted room. Fail
+        // here, by name, so the mistake is legible.
+        if (roomId == null || roomId === "") {
+          const err = new Error(
+            "join() needs a room id — pass a room from list() (its `id`) or a create/join result",
+          );
+          err.code = "mp_room_id_required";
+          return Promise.reject(err);
+        }
+        return this._mpEnter(
+          this._mpRequest("POST", `/v1/mp/rooms/${enc(roomId)}/join`),
+        );
+      },
+      // Join the fullest public room with a free seat, creating one if there is
+      // none. Pass `code` to enter a private room instead: the first player to
+      // use a code opens that room and the rest join it, and a full one refuses
+      // rather than opening a second room under the same code.
       quickJoin: (opts) =>
         this._mpEnabled
           ? this._mpEnter(this._mpRequest("POST", "/v1/mp/quick-join", opts || {}))
@@ -1027,17 +1575,83 @@ class TesanaClient {
    * @param {Promise<{ wsUrl: string, roomId?: string, room?: object, playerId?: string }>} session
    */
   async _mpEnter(session) {
-    const joined = await session;
-    await this._mpOpen(joined.wsUrl);
+    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)`
+    // instead of opening a second one and stranding the first.
+    try {
+      await this._mpOpen(joined.wsUrl);
+    } catch (err) {
+      const roomId = joined.roomId || joined.room?.id || null;
+      const wrapped = new Error(
+        roomId ? `${err?.message || "multiplayer unavailable"} (room ${roomId})` : err?.message || "multiplayer unavailable",
+      );
+      wrapped.code = err?.code || "mp_enter_failed";
+      wrapped.roomId = roomId;
+      throw wrapped;
+    }
     this._mp.roomId = joined.roomId || joined.room?.id || null;
+    this._mp.code = joined.room?.code || null;
     return {
       wsUrl: joined.wsUrl,
       roomId: this._mp.roomId,
+      code: this._mp.code,
       playerId: joined.playerId || this._player?.id,
       room: joined.room,
     };
   }
 
+  /**
+   * 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
    */
@@ -1096,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();
       };
     });
@@ -1134,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();
@@ -1142,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 {
@@ -1175,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 }));
   }
 
@@ -1209,9 +1889,11 @@ class TesanaClient {
     this._mp.leaving = true;
     this._mpClose();
     this._mp.roomId = null;
+    this._mp.code = null;
     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 {
@@ -1233,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),
@@ -1263,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);
@@ -1307,6 +2006,13 @@ class TesanaClient {
         minIntervalMs: config.adMinIntervalMs,
       });
     }
+    // A later bootstrap may carry the player's language — a provisionally
+    // "offline" answer has none, and the real one arrives a moment later. The
+    // capability is re-pointed in place, exactly as the ad policy is.
+    if (config.locale && this.l10n) {
+      const next = normalizeLocale(config.locale);
+      if (next && next !== this.l10n.locale()) this.l10n.applyLocale(next);
+    }
     this._mpEnabled = config.multiplayer !== false;
     this.multiplayer.enabled = this._mpEnabled;
     return this;
@@ -1540,6 +2246,300 @@ class TesanaClient {
     };
   }
 
+  // -------------------------------------------------------------------- l10n
+  //
+  // Localization, from the game's side. The service owns the dictionary and the
+  // translation; this owns one promise: a game that asks for its text in the
+  // player's language gets something renderable, always.
+  //
+  // Deliberately synchronous where the game needs it to be. `t()` reads a map
+  // that was filled before the first frame, so drawing a localized menu costs no
+  // await and no round trip; only text the game discovers at runtime — a
+  // procedurally generated item name, something the player typed — goes through
+  // the async path. A game that never awaits anything still localizes.
+  _makeL10n(opts) {
+    const state = {
+      locale: normalizeLocale(opts.locale || ""),
+      // The language the game's own strings are written in. Declared by the
+      // build; the service is told the same value, so the two agree rather
+      // than one guessing what the other meant.
+      source: "en",
+      // The platform's list, refined by the service's answer when it arrives.
+      languages: L10N_TARGETS.slice(),
+      // Source text -> translated text, filled before `ready` resolves.
+      bundle: {},
+      // The game's own key -> source text, for `t("ui.play")`.
+      index: {},
+      handlers: [],
+      // `requested`: what the game's source language resolved to (en, de, …)
+      // vs `target`: what is actually being served — the difference is a
+      // language the game did not declare, where the source is the answer.
+      target: "",
+      loaded: false,
+      // The bundle is asked for from three places on a normal boot — `ready`,
+      // `init`'s await, and the post-session reload — and all three want the
+      // same one. `inflight` is the shared request; `loadedFor` is the target
+      // that has already been answered, so a repeat is a no-op rather than a
+      // second round trip for an object we already hold.
+      inflight: null,
+      inflightTarget: "",
+      loadedFor: null,
+    };
+
+    const self = this;
+
+    /** Emit a locale change to every listener, without letting one break the rest. */
+    function emit() {
+      const event = { locale: state.locale, target: state.target, languages: state.languages.slice() };
+      for (const fn of [...state.handlers]) {
+        try {
+          fn(event);
+        } catch {
+          /* a game handler */
+        }
+      }
+    }
+
+    /**
+     * Resolve `key` against the bundle.
+     *
+     * Three shapes, because a game reaches for all three: a key it declared
+     * (`"ui.play"`), the source sentence itself (`"Play"`), and a key with a
+     * fallback for the source text that was never declared. Whatever is not
+     * found comes back as the fallback or the key, which is what makes an
+     * unreachable service a non-event.
+     */
+    function lookup(key, fallback) {
+      const name = String(key == null ? "" : key);
+      const source = state.index[name] || name;
+      const hit = state.bundle[source];
+      if (typeof hit === "string" && hit) return hit;
+      if (typeof fallback === "string" && fallback) return fallback;
+      return source;
+    }
+
+    /**
+     * Load the bundle, at most once per (language, reachability) combination.
+     *
+     * A boot calls this from several independent places — the `ready` promise,
+     * `init`'s await, and the post-session `reload` — and they all want the
+     * same bundle. Coalescing them is not an optimization for its own sake:
+     * every extra request is the player's bundle fetched twice, and a game
+     * that redraws on `onChange` should not be able to multiply it.
+     */
+    function load() {
+      const target = self._canReach() && state.locale && state.locale !== state.source ? state.locale : "";
+      if (state.inflight && state.inflightTarget === target) return state.inflight;
+      if (state.loadedFor === target && state.loaded) return Promise.resolve(state);
+      state.inflightTarget = target;
+      state.inflight = fetchBundle(target).finally(() => {
+        state.inflight = null;
+      });
+      return state.inflight;
+    }
+
+    async function fetchBundle(target) {
+      if (!self._canReach()) {
+        // No address, or no game id: nothing will ever answer, and asking
+        // anyway would throw a relative-URL fetch. The source language is the
+        // honest answer and the game renders exactly as it always did.
+        state.loaded = true;
+        state.loadedFor = target;
+        return state;
+      }
+      try {
+        if (!target) {
+          // Nothing to fetch — and no request at all, either. A source-language
+          // boot needs no bundle (nothing is translated) and no language list
+          // (the platform's known set is already in memory), so a game with no
+          // localization in force makes zero localization requests. That
+          // matters beyond tidiness: it is the same rule as the rest of the
+          // SDK, that a capability nobody asked for must not put bytes on the
+          // wire, and it is what a game running entirely offline relies on.
+          state.target = "";
+          state.loaded = true;
+          state.loadedFor = target;
+          return state;
+        }
+        const data = await self.request(
+          "GET",
+          `/v1/l10n/bundle?target=${enc(target)}`,
+        );
+        if (data && typeof data.translations === "object" && data.translations) {
+          state.bundle = data.translations;
+        }
+        if (data && typeof data.index === "object" && data.index) {
+          state.index = data.index;
+        }
+        if (typeof data?.source === "string" && data.source) state.source = data.source;
+        // `target` is the service's answer about what it actually served.
+        // It is `""` for a language this game has not declared, which is the
+        // signal that the source text IS the answer.
+        state.target = typeof data?.target === "string" && data.target ? data.target : "";
+        // The declared language set arrives with the bundle's own response
+        // rather than a second route. It is one fact about one game, and two
+        // requests to learn it is one more chance for a boot to be slower than
+        // the first frame.
+        if (Array.isArray(data?.languages) && data.languages.length) {
+          // The game's own declared set, in the order it chose — which is how
+          // a game that lists French first gets French first in its picker.
+          state.languages = data.languages.slice();
+        }
+      } catch (err) {
+        // An outage costs the translation, not the game. One deduped line is
+        // enough to make it findable without spamming the console on retry.
+        warnOnce(
+          "l10n-unreachable",
+          `Tesana localization: could not reach the translation service (${(err && err.message) || "request failed"}).`
+            + " The game keeps playing in its source language.",
+        );
+      }
+      state.loaded = true;
+      state.loadedFor = target;
+      return state;
+    }
+
+    return {
+      /**
+       * The player's language, synchronously, as the host resolved it.
+       *
+       * Follows the same tag vocabulary the site uses (`pt-BR`, `zh`), not
+       * AWS's, so a game can pass it straight to `Intl`/`toLocaleString`.
+       */
+      locale: () => state.locale,
+      /** The languages this game offers, the host's order preserved. */
+      languages: () => state.languages.slice(),
+      /** The language text is actually being served in, or `""` when it is the source. */
+      target: () => state.target,
+      /** The language the game's own strings are written in. */
+      source: () => state.source,
+      /** Whether the initial bundle has landed. `t()` works before it does. */
+      get loaded() {
+        return state.loaded;
+      },
+
+      /**
+       * The translated text for `key`, synchronously.
+       *
+       * Prefer this. It is filled before the first frame, so a game never has
+       * to await anything to draw a localized menu — and when the bundle is
+       * empty (a service outage, a language the game never declared) it returns
+       * the source text, which is a rendered game rather than a blank one.
+       *
+       * @param {string} key  a declared key, or the source sentence itself
+       * @param {object|string} [vars]  `{name}` values, or a fallback string
+       */
+      t: (key, vars) => {
+        // The second argument is both of the things a caller wants to pass:
+        // placeholder values, and a fallback for an undeclared key. A string is
+        // unambiguously a fallback; an object is unambiguously values.
+        const values = vars && typeof vars === "object" ? vars : null;
+        const fallback = typeof vars === "string" ? vars : "";
+        return fillPlaceholders(lookup(key, fallback), values);
+      },
+
+      /**
+       * Translate text the game discovered while running.
+       *
+       * The one path that costs a round trip, so it is the one to keep off the
+       * hot path: ask once, at the moment the text is created (a generated
+       * name, a line of dialogue just chosen), never per frame. Resolves the
+       * source text on any failure, so a `.then` never sees a rejection.
+       *
+       * @param {string} text
+       * @param {{ id?: string, values?: Record<string, unknown>, target?: string }} [opts]
+       */
+      translate: async (text, opts = {}) => {
+        const values = opts.values && typeof opts.values === "object" ? opts.values : null;
+        const target = opts.target || state.target || (state.locale !== state.source ? state.locale : "");
+        // A named string is routed through the id-keyed path, which is what
+        // lets the service remember it under the game's own name and serve it
+        // from cache next time without even a hash lookup.
+        if (opts.id && self._canReach() && target) {
+          try {
+            const data = await self.request("POST", "/v1/l10n/string", {
+              id: String(opts.id),
+              text: String(text == null ? "" : text),
+              values: values || undefined,
+              target,
+              source: state.source,
+            });
+            if (data && typeof data.value === "string" && data.value) return data.value;
+          } catch {
+            /* falls through to the source text below */
+          }
+        }
+        // The anonymous path requires a target to be worth a call. With no
+        // target this *is* the source language, and asking the server to hand
+        // back what it was given is the most expensive no-op available.
+        if (self._canReach() && target) {
+          try {
+            const data = await self.request("POST", "/v1/l10n/translate", {
+              strings: [String(text == null ? "" : text)],
+              target,
+              source: state.source,
+            });
+            const hit = data?.translations?.[String(text)];
+            if (typeof hit === "string" && hit) return fillPlaceholders(hit, values);
+          } catch {
+            /* ditto */
+          }
+        }
+        return fillPlaceholders(String(text == null ? "" : text), values);
+      },
+
+      /**
+       * Subscribe to a language change. Returns an unsubscribe function.
+       *
+       * A game should redraw its text (or call `t()` again) on this rather than
+       * caching translated strings at startup, because the player can change
+       * the site's language without reloading the frame.
+       *
+       * @param {(event: { locale: string, target: string, languages: string[] }) => void} fn
+       */
+      onChange: (fn) => {
+        if (typeof fn !== "function") return () => {};
+        state.handlers.push(fn);
+        return () => {
+          state.handlers = state.handlers.filter((handler) => handler !== fn);
+        };
+      },
+
+      /** Resolves after the initial bundle. A game may await it with `__TESANA_READY__`. */
+      ready: load(),
+
+      /**
+       * Reload the bundle, after an identity or language change.
+       *
+       * The constructor loads immediately from whatever the page already
+       * carries. A game that minted its own token — or a host whose real
+       * bootstrap replaced a provisional "offline" one — has no credential that
+       * first time, so the bundle would be empty and the game would stay in its
+       * source language for the whole session. `init` awaits this after the
+       * identity step, which is what makes the documented
+       * `await window.__TESANA_READY__` sufficient for a localized first frame.
+       */
+      reload: () => load(),
+
+      // ---- internal wiring (used by the bootstrap listener) ----
+      /** A new language from the host. Resolves the same promise the game already holds. */
+      applyLocale(next) {
+        const locale = normalizeLocale(next);
+        if (!locale || locale === state.locale) return state;
+        state.locale = locale;
+        // The old bundle is the *previous* language's, so it is cleared rather
+        // than left to serve: showing a menu in a language the player just
+        // switched away from is worse than showing the source text for the
+        // moment the refill takes. `t()` falls back to source in between.
+        state.bundle = {};
+        state.target = "";
+        emit();
+        load().catch(() => {});
+        return state;
+      },
+    };
+  }
+
   // ------------------------------------------------------------------ saves
   //
   // Writes go to the local cache first, always, so a failed upload is a save
@@ -1681,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.