@tesana/sdk 1.0.2 → 1.0.4

package/dist/tesana.esm.js

@@ -37,7 +37,7 @@
 // 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.2";
+const VERSION = "1.0.4";
 
 const LOCAL_CACHE = "tesana.play.v1";
 
@@ -197,6 +197,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;
@@ -366,6 +420,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;
@@ -415,6 +482,21 @@ function deviceId() {
   return id;
 }
 
+/**
+ * The store-native purchase surface a desktop prelude publishes, or null.
+ *
+ * A desktop, Steam or App Store build has no page above it and no Stripe — the
+ * store's own purchase must run instead, and only the native side can open it.
+ * `tesana-desktop.js` publishes `TesanaDesktop.storePurchase` on exactly those
+ * builds and nothing else, so its presence is the whole signal. Reaching for it
+ * on a plain web page finds `undefined` and changes nothing.
+ */
+function storeBilling() {
+  const desktop = typeof window !== "undefined" ? window.TesanaDesktop : null;
+  if (!desktop || typeof desktop.storePurchase !== "function") return null;
+  return desktop;
+}
+
 /** How long the host has to answer a sign-in before we give up. */
 const SIGN_IN_TIMEOUT_MS = 120000;
 
@@ -474,6 +556,16 @@ export 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,
@@ -481,7 +573,7 @@ export 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);
@@ -544,6 +636,15 @@ 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) || "",
+    ),
   };
 }
 
@@ -555,7 +656,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;
@@ -598,6 +699,8 @@ 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,
@@ -810,6 +913,16 @@ 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;
+
     this.multiplayer = {
       // Read this before drawing a lobby: when it is false the game is not
       // allowed rooms yet and the calls below refuse.
@@ -826,14 +939,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 || {}))
@@ -901,6 +1042,12 @@ class TesanaClient {
    * @param {{ clientRequestId?: string }} [opts]
    */
   async _topUp(packId, opts = {}) {
+    // A desktop/Steam build buys through its store, not through a Tesana page.
+    // `hasHost()` is false there (no parent frame) and Stripe is the wrong rail,
+    // so store billing is checked first — its presence is what distinguishes a
+    // storefront build from a page opened straight from the play CDN.
+    const desktop = storeBilling();
+    if (desktop) return this._topUpViaStore(desktop, packId);
     if (hasHost()) {
       // The host owns checkout: it opens Stripe in a window of its own and
       // tells us how it went. We only ask. The message names are the host's,
@@ -933,6 +1080,67 @@ class TesanaClient {
     return result;
   }
 
+  /**
+   * Buy a coin pack through the store this build ships on.
+   *
+   * Two halves, in this order for a reason: the store takes the money, and only
+   * then does the play service turn the store's own transaction id into coins.
+   * The id is the store's, not ours — it is the one thing a client cannot
+   * invent twice, so it is what makes the credit idempotent when the purchase
+   * is replayed after a crash. Reporting before a successful purchase would
+   * credit coins for a purchase that never happened.
+   *
+   * The result is shaped like the web top-up: a purchase returns the new
+   * balance, and a decline is `{ ok: false, code: "cancelled" }` rather than an
+   * exception, because a player closing the store sheet is a normal answer.
+   *
+   * @param {any} desktop  `window.TesanaDesktop` with `storePurchase`
+   * @param {string} packId
+   */
+  async _topUpViaStore(desktop, packId) {
+    // Sign in *before* the store sheet, never after.
+    //
+    // Coins are account-scoped, so a player with no account has nothing to hold
+    // them: `redeem` refuses an unlinked player, and a guest is exactly that.
+    // On the web rail the refusal arrives harmlessly first, because the host
+    // runs checkout server-side and no money has moved yet. Here the store
+    // charges on this side of the wire, so a refusal discovered at redemption
+    // is a player who was billed and got nothing — the one outcome worth
+    // blocking a sale over. A launcher that cannot sign anyone in therefore
+    // refuses the sale rather than taking payment it cannot honour.
+    const canBuy = () => !this.offline && !this._isGuestSession();
+    if (!canBuy()) {
+      if (typeof desktop.signIn !== "function") {
+        return { ok: false, purchased: false, code: "login_required" };
+      }
+      const answer = await this._signInViaNative(canBuy);
+      if (!answer || answer.signedIn !== true) {
+        return { ok: false, purchased: false, code: "login_required" };
+      }
+    }
+    const purchase = await desktop.storePurchase({ packId });
+    if (!purchase || purchase.ok !== true) {
+      return {
+        ok: false,
+        purchased: false,
+        code: (purchase && purchase.code) || "cancelled",
+      };
+    }
+    // A store that charged but reported no id cannot be credited — there would
+    // be no way to tell a replay from a new purchase. Surface it as a failure
+    // rather than granting an untraceable lot.
+    if (!purchase.transactionId) {
+      const err = new Error("The store did not return a transaction id.");
+      err.code = "no_transaction_id";
+      throw err;
+    }
+    return this.request("POST", "/v1/economy/redeem", {
+      rail: this.rail,
+      packId,
+      transactionId: purchase.transactionId,
+    });
+  }
+
   _mpRefuse() {
     const err = new Error("Multiplayer is not available for this game yet");
     err.code = "multiplayer_disabled";
@@ -944,11 +1152,27 @@ class TesanaClient {
    */
   async _mpEnter(session) {
     const joined = await session;
-    await this._mpOpen(joined.wsUrl);
+    // 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,
     };
@@ -1125,6 +1349,7 @@ 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;
@@ -1223,6 +1448,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;
@@ -1456,6 +1688,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
@@ -1508,6 +2034,13 @@ class TesanaClient {
   _signIn() {
     const signedIn = () => !this.offline && !this._isGuestSession();
     if (signedIn()) return Promise.resolve({ signedIn: true });
+    // A desktop/Steam build has no host to draw an account UI. Its launcher is
+    // the sign-in surface, and only it can vouch for the player to the host
+    // with the internal secret that account linking requires — so this asks the
+    // native side to run sign-in and then waits for the bootstrap that carries
+    // the linked token, exactly as the web path waits for the host's answer.
+    const desktop = storeBilling();
+    if (desktop && typeof desktop.signIn === "function") return this._signInViaNative(signedIn);
     post({ type: "tesana-sign-in-request", gameId: this.gameId });
     return new Promise((resolve) => {
       let expiry = null;
@@ -1541,7 +2074,46 @@ class TesanaClient {
 
   /** A guest the site vouches for: saves in the cloud, but has no account to spend from. */
   _isGuestSession() {
-    return Boolean(this._player && this._player.isGuest);
+    if (!this._player) return false;
+    // Two signals, because the answer arrives from two places. A host posts
+    // `isGuest: true` in its bootstrap — the web's word for it — while an
+    // identity this client resolves itself (`/v1/player/me`) reports `isLinked`
+    // and no `isGuest` at all. Reading only the first would let a native
+    // session, whose whole point is an account-free identity, pass as a
+    // signed-in player; the store path gates a sale on exactly this, so that
+    // mistake is a card charged for coins we then refuse to grant.
+    return this._player.isGuest === true || this._player.isLinked === false;
+  }
+
+  /**
+   * Ask the native launcher to sign the player in, then wait for the token.
+   *
+   * The launcher is the only party that can reach the host route with the
+   * internal secret that account linking needs, so this hands it the request
+   * and then watches `signedIn()` — which flips the moment the linked bootstrap
+   * replaces the guest one. Polling rather than listening is deliberate: the
+   * bootstrap arrives through the SDK's own upgrade path (`onBootstrapUpgrade`
+   * re-points the client and re-runs identity), and there is no second channel
+   * to subscribe to here.
+   */
+  _signInViaNative(signedIn) {
+    return window.TesanaDesktop.signIn({ gameId: this.gameId }).then((answer) => {
+      if (!answer || answer.ok !== true || answer.signedIn !== true) return { signedIn: false };
+      return new Promise((resolve) => {
+        const waitForToken = (attempt) => {
+          if (signedIn()) return resolve({ signedIn: true });
+          // Report what is actually true when the wait runs out. The web path
+          // predates this and answers optimistically; its launcher-started
+          // sign-in gets a fresh page instead, so it never observes the lie.
+          // Here the caller is a store purchase deciding whether money may
+          // move, and "probably signed in" is not a state a charge may proceed
+          // on — a token that never arrived means no account to hold the coins.
+          if ((attempt || 0) >= 60) return resolve({ signedIn: signedIn() });
+          setTimeout(() => waitForToken((attempt || 0) + 1), 50);
+        };
+        waitForToken(0);
+      });
+    });
   }
 
 }