@tesana/sdk 1.3.3 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -60,6 +60,30 @@ succeeding.
60
60
  | `tesana.feedback` | Player reports to the creator — `open` (host form) / `submit`; crashes are filed automatically |
61
61
  | `tesana.config` | Values the creator tunes without a rebuild — `get(key, default)` / `getAll` / `ready` |
62
62
  | `tesana.share` | Invite links — `share({ roomCode, levelId, text })` / `share.params()` |
63
+ | `tesana.build` | This build's id (its hash), from the host or the page's `<meta name="tesana-build">`; `""` when neither says |
64
+ | `tesana.release` | The release number when this build is the release players have, else `null` |
65
+ | `tesana.locale` | The player's language as a BCP 47 tag, e.g. `"ko-KR"` (since 1.4.0; see Languages) |
66
+ | `tesana.l10n` | The platform's translation of declared strings — `t` / `locale` (the site's language) / `languages` / `onChange` |
67
+
68
+ ### Languages (since 1.4.0)
69
+
70
+ A game that ships its own translations picks one at start from
71
+ `tesana.locale`: the site's language when the player picked it, English
72
+ included (the host says so with `localeChosen: true` on the bootstrap and on
73
+ each `tesana-locale` change; a host that does not say counts only a
74
+ non-English language as picked), otherwise the browser's first language, as a
75
+ canonical BCP 47 tag (`ko-KR`, `fr`, `zh-Hant-TW`). The
76
+ site sends `en` to every visitor who has not picked a language, so
77
+ `tesana.l10n.locale()` (the site's language, which the platform translates
78
+ into) says `en` for most Korean or French players; `tesana.locale` does not.
79
+ Match its base tag against the languages the game ships and fall back to
80
+ English. A change while playing fires `tesana.l10n.onChange`.
81
+
82
+ ```js
83
+ const shipped = ["en", "ko", "fr", "ja"];
84
+ const base = tesana.locale.toLowerCase().split("-")[0];
85
+ const lang = shipped.includes(base) ? base : "en";
86
+ ```
63
87
 
64
88
  Leaderboards and achievements are client-reported, so they are a ranking to show
65
89
  off rather than a prize table; nothing here mints coins or grants entitlements.
@@ -60,7 +60,7 @@
60
60
  // 1.3.3 (TES-314, DEC-126): an offline build that was never given an endpoint
61
61
  // (a desktop export with no play session) makes no play-service calls: its
62
62
  // base would only be the page's own origin, the wrapper's loopback server.
63
- const VERSION = "1.3.3";
63
+ const VERSION = "1.4.0";
64
64
 
65
65
  const LOCAL_CACHE = "tesana.play.v1";
66
66
 
@@ -305,6 +305,44 @@ function normalizeLocale(tag) {
305
305
  return L10N_TARGETS.find((t) => t.split("-")[0].toLowerCase() === base) || value;
306
306
  }
307
307
 
308
+ /** A language tag in its canonical BCP 47 form (`ko-KR`, `zh-Hant-TW`), or "" when it is not one. */
309
+ function canonicalTag(tag) {
310
+ const value = String(tag || "").trim().replace(/_/g, "-");
311
+ if (!value) return "";
312
+ try {
313
+ return Intl.getCanonicalLocales(value)[0] || "";
314
+ } catch {
315
+ return "";
316
+ }
317
+ }
318
+
319
+ /**
320
+ * The player's language, for a game choosing which of its own translations
321
+ * to show (`tesana.locale`, TES-4382).
322
+ *
323
+ * The host's word wins when the player chose it, English included: the host
324
+ * says so with `localeChosen: true`, on the bootstrap and on each
325
+ * `tesana-locale` change. An unset or default site language is not: tesana.com
326
+ * sends `en` to every visitor who has not picked one, Korean and French
327
+ * browsers included, so then the browser's own first language answers
328
+ * (TES-4391). A host that does not say (`chosen` undefined, older hosts) can
329
+ * only have sent a non-English language because the player picked it, so
330
+ * that counts as chosen and English does not. `l10n.locale()` stays the
331
+ * site's language, which is what the platform translates into.
332
+ *
333
+ * @param {string} host the host's own tag, "" when it sent none
334
+ * @param {boolean|undefined} chosen whether the player picked it; undefined when the host did not say
335
+ */
336
+ function playerLocale(host, chosen) {
337
+ const site = canonicalTag(host);
338
+ const picked = typeof chosen === "boolean" ? chosen : site.split("-")[0].toLowerCase() !== "en";
339
+ if (site && picked) return site;
340
+ const nav = typeof navigator !== "undefined" && navigator
341
+ ? (Array.isArray(navigator.languages) && navigator.languages[0]) || navigator.language
342
+ : "";
343
+ return canonicalTag(nav) || site || "en";
344
+ }
345
+
308
346
  /** `{name}` in `text`, filled from `values`. The one interpolation rule the SDK and the service share. */
309
347
  function fillPlaceholders(text, values) {
310
348
  const source = String(text == null ? "" : text);
@@ -319,7 +357,11 @@ function resyncLocale(data) {
319
357
  if (!l10nClient) return;
320
358
  const payload = data && typeof data.payload === "object" ? data.payload : data;
321
359
  const next = payload && (payload.locale || payload.lang || payload.language);
322
- if (next) l10nClient.applyLocale(next);
360
+ // The host says whether the player chose it (TES-4397): it re-posts the
361
+ // language on its own boot-time syncs too, which are not choices. A host
362
+ // that does not say leaves it to the language itself (see `playerLocale`).
363
+ const chosen = payload && typeof payload.localeChosen === "boolean" ? payload.localeChosen : "unknown";
364
+ if (next) l10nClient.applyLocale(next, { host: next, chosen });
323
365
  }
324
366
 
325
367
  /** A policy message from the host, or `null` when none is in force. */
@@ -1231,6 +1273,43 @@ function eventsHidden() {
1231
1273
  return typeof document !== "undefined" && Boolean(document) && document.visibilityState === "hidden";
1232
1274
  }
1233
1275
 
1276
+ /**
1277
+ * The build this page is, as the build stamped it: every published build
1278
+ * carries `<meta name="tesana-build" content="<hash>">` (the hash it is served
1279
+ * under), and so does the Studio's live preview. "" when there is none: a page
1280
+ * opened outside Tesana, or a game never built.
1281
+ */
1282
+ function pageBuildStamp() {
1283
+ try {
1284
+ if (typeof document === "undefined" || typeof document.querySelector !== "function") return "";
1285
+ const meta = document.querySelector('meta[name="tesana-build"]');
1286
+ const value = String((meta && meta.getAttribute && meta.getAttribute("content")) || "").trim();
1287
+ return /^[0-9a-f]{8,64}$/i.test(value) ? value.toLowerCase() : "";
1288
+ } catch {
1289
+ return "";
1290
+ }
1291
+ }
1292
+
1293
+ /**
1294
+ * Which build this is (`tesana.build`, bug reports, events): what the host or
1295
+ * the game named, else the page's own stamp (TES-196). The host names it on
1296
+ * tesana.com; a page with no host, or a host that names none, still has the
1297
+ * stamp.
1298
+ */
1299
+ function buildOf(merged) {
1300
+ return String(merged.build || merged.buildId || merged.buildVersion || pageBuildStamp() || "").slice(0, 64);
1301
+ }
1302
+
1303
+ /**
1304
+ * The release number of the running build (`tesana.release`), or null. The
1305
+ * host sends it only when the build is the release players have: a test build
1306
+ * in the Studio is no release yet.
1307
+ */
1308
+ function releaseOf(merged) {
1309
+ const number = Number(merged.release);
1310
+ return Number.isInteger(number) && number > 0 ? number : null;
1311
+ }
1312
+
1234
1313
  /**
1235
1314
  * Point the emitter at this page's bootstrap. Called by `init()` and again on
1236
1315
  * every bootstrap upgrade: a provisional answer may not name the game or carry
@@ -1247,7 +1326,7 @@ function eventsConfigure(merged) {
1247
1326
  }
1248
1327
  const game = eventsGame(merged);
1249
1328
  if (!game || page !== "yes") return;
1250
- const build = String(merged.build || merged.buildId || merged.buildVersion || "").slice(0, 64);
1329
+ const build = buildOf(merged);
1251
1330
  const session = EVENTS_OWN_COLLECTORS.has(url) ? eventsSessionToken(merged) : "";
1252
1331
  // Rebuilt on every bootstrap the session accepts: a refreshed token
1253
1332
  // replaces the old one. What was queued goes first, under the token it was
@@ -2060,12 +2139,18 @@ function buildConfig(merged) {
2060
2139
  locale: normalizeLocale(
2061
2140
  merged.locale || merged.language || merged.lang || (typeof navigator !== "undefined" && navigator.language) || "",
2062
2141
  ),
2142
+ // The host's own word, unfolded, for `tesana.locale`: "" when it sent none.
2143
+ hostLocale: String(merged.locale || merged.language || merged.lang || ""),
2144
+ // Whether the player picked that language (TES-4391); undefined when the host does not say.
2145
+ localeChosen: typeof merged.localeChosen === "boolean" ? merged.localeChosen : undefined,
2063
2146
  // How a dropped room socket is retried. A game can shrink the waits (a
2064
2147
  // test, or a game with unusual tolerance); the defaults are the fleet's.
2065
2148
  multiplayerReconnect: merged.multiplayerReconnect || undefined,
2066
- // Which build of the game this is, for a bug report. The host stamps it;
2067
- // absent means an older host and reports simply say nothing.
2068
- build: String(merged.build || merged.buildId || merged.buildVersion || "").slice(0, 64),
2149
+ // Which build of the game this is (`tesana.build`, bug reports): the
2150
+ // host's word, else the page's own stamp; "" when neither says.
2151
+ build: buildOf(merged),
2152
+ // The release players have, when this build is it (`tesana.release`).
2153
+ release: releaseOf(merged),
2069
2154
  // What an invite link carried, when the host opened the game from one.
2070
2155
  launch: merged.launch && typeof merged.launch === "object" ? merged.launch : null,
2071
2156
  };
@@ -2367,7 +2452,10 @@ class TesanaClient {
2367
2452
  this.track = track;
2368
2453
  this.gameplay = gameplay;
2369
2454
 
2455
+ /** Which build this is: its hash, or "" (TES-196). */
2370
2456
  this.build = opts.build || "";
2457
+ /** The release number of this build when it is the release players have, else null. */
2458
+ this.release = opts.release ?? null;
2371
2459
  this._launch = opts.launch || null;
2372
2460
 
2373
2461
  // Bug reports and crashes, to the creator. The host draws the form — like
@@ -3116,13 +3204,15 @@ class TesanaClient {
3116
3204
  // A later bootstrap may carry the player's language — a provisionally
3117
3205
  // "offline" answer has none, and the real one arrives a moment later. The
3118
3206
  // capability is re-pointed in place, exactly as the ad policy is.
3119
- if (config.locale && this.l10n) {
3120
- const next = normalizeLocale(config.locale);
3121
- if (next && next !== this.l10n.locale()) this.l10n.applyLocale(next);
3207
+ // The host's own word and whether the player chose it ride along, so
3208
+ // `tesana.locale` moves too, and onChange fires once for either change.
3209
+ if (this.l10n && (config.locale || config.hostLocale || typeof config.localeChosen === "boolean")) {
3210
+ this.l10n.applyLocale(config.locale, { host: config.hostLocale || undefined, chosen: config.localeChosen });
3122
3211
  }
3123
3212
  this._mpEnabled = config.multiplayer !== false;
3124
3213
  this.multiplayer.enabled = this._mpEnabled;
3125
3214
  if (config.build) this.build = config.build;
3215
+ if (config.release != null) this.release = config.release;
3126
3216
  if (config.launch) this._launch = config.launch;
3127
3217
  return this;
3128
3218
  }
@@ -3373,6 +3463,17 @@ class TesanaClient {
3373
3463
  // await and no round trip; only text the game discovers at runtime — a
3374
3464
  // procedurally generated item name, something the player typed — goes through
3375
3465
  // the async path. A game that never awaits anything still localizes.
3466
+
3467
+ /**
3468
+ * The player's language as a canonical BCP 47 tag (`ko-KR`, `fr`, `pt-BR`),
3469
+ * for a game choosing which of its own translations to show. The site's
3470
+ * language when the player picked one, else the browser's (TES-4382).
3471
+ * `l10n.locale()` stays the site's language.
3472
+ */
3473
+ get locale() {
3474
+ return this.l10n ? this.l10n.playerLocale() : playerLocale("", false);
3475
+ }
3476
+
3376
3477
  _makeL10n(opts) {
3377
3478
  const state = {
3378
3479
  locale: normalizeLocale(opts.locale || ""),
@@ -3400,6 +3501,10 @@ class TesanaClient {
3400
3501
  inflight: null,
3401
3502
  inflightTarget: "",
3402
3503
  loadedFor: null,
3504
+ // `tesana.locale`'s inputs: the host's own word ("" when it sent none)
3505
+ // and whether the player chose it while playing (TES-4382).
3506
+ hostLocale: opts.hostLocale || "",
3507
+ chosen: typeof opts.localeChosen === "boolean" ? opts.localeChosen : undefined,
3403
3508
  };
3404
3509
 
3405
3510
  const self = this;
@@ -3638,10 +3743,29 @@ class TesanaClient {
3638
3743
  reload: () => load(),
3639
3744
 
3640
3745
  // ---- internal wiring (used by the bootstrap listener) ----
3641
- /** A new language from the host. Resolves the same promise the game already holds. */
3642
- applyLocale(next) {
3746
+ /** `tesana.locale`: the player's language as a BCP 47 tag (see `playerLocale`). */
3747
+ playerLocale: () => playerLocale(state.hostLocale, state.chosen),
3748
+
3749
+ /**
3750
+ * A new language from the host. Resolves the same promise the game already holds.
3751
+ *
3752
+ * `host` is the host's own tag and `chosen` whether the player picked
3753
+ * it, as the host says: true or false, "unknown" when this host does
3754
+ * not say, or left out to keep what is known.
3755
+ */
3756
+ applyLocale(next, { host, chosen } = {}) {
3757
+ const before = playerLocale(state.hostLocale, state.chosen);
3758
+ if (host) state.hostLocale = String(host);
3759
+ if (typeof chosen === "boolean") state.chosen = chosen;
3760
+ else if (chosen === "unknown") state.chosen = undefined;
3643
3761
  const locale = normalizeLocale(next);
3644
- if (!locale || locale === state.locale) return state;
3762
+ if (!locale || locale === state.locale) {
3763
+ // The site's language stayed, but the player's may not have (they
3764
+ // picked English on a site that was already sending its default):
3765
+ // a game that follows `tesana.locale` still has to redraw.
3766
+ if (playerLocale(state.hostLocale, state.chosen) !== before) emit();
3767
+ return state;
3768
+ }
3645
3769
  state.locale = locale;
3646
3770
  // The old bundle is the *previous* language's, so it is cleared rather
3647
3771
  // than left to serve: showing a menu in a language the player just
@@ -1,4 +1,4 @@
1
- /* Tesana play-time SDK v1.3.3 */
1
+ /* Tesana play-time SDK v1.4.0 */
2
2
  (function (root) {
3
3
  /**
4
4
  * Tesana play-time SDK. Vanilla JS, no npm in games.
@@ -62,7 +62,7 @@
62
62
  // 1.3.3 (TES-314, DEC-126): an offline build that was never given an endpoint
63
63
  // (a desktop export with no play session) makes no play-service calls: its
64
64
  // base would only be the page's own origin, the wrapper's loopback server.
65
- const VERSION = "1.3.3";
65
+ const VERSION = "1.4.0";
66
66
 
67
67
  const LOCAL_CACHE = "tesana.play.v1";
68
68
 
@@ -307,6 +307,44 @@ function normalizeLocale(tag) {
307
307
  return L10N_TARGETS.find((t) => t.split("-")[0].toLowerCase() === base) || value;
308
308
  }
309
309
 
310
+ /** A language tag in its canonical BCP 47 form (`ko-KR`, `zh-Hant-TW`), or "" when it is not one. */
311
+ function canonicalTag(tag) {
312
+ const value = String(tag || "").trim().replace(/_/g, "-");
313
+ if (!value) return "";
314
+ try {
315
+ return Intl.getCanonicalLocales(value)[0] || "";
316
+ } catch {
317
+ return "";
318
+ }
319
+ }
320
+
321
+ /**
322
+ * The player's language, for a game choosing which of its own translations
323
+ * to show (`tesana.locale`, TES-4382).
324
+ *
325
+ * The host's word wins when the player chose it, English included: the host
326
+ * says so with `localeChosen: true`, on the bootstrap and on each
327
+ * `tesana-locale` change. An unset or default site language is not: tesana.com
328
+ * sends `en` to every visitor who has not picked one, Korean and French
329
+ * browsers included, so then the browser's own first language answers
330
+ * (TES-4391). A host that does not say (`chosen` undefined, older hosts) can
331
+ * only have sent a non-English language because the player picked it, so
332
+ * that counts as chosen and English does not. `l10n.locale()` stays the
333
+ * site's language, which is what the platform translates into.
334
+ *
335
+ * @param {string} host the host's own tag, "" when it sent none
336
+ * @param {boolean|undefined} chosen whether the player picked it; undefined when the host did not say
337
+ */
338
+ function playerLocale(host, chosen) {
339
+ const site = canonicalTag(host);
340
+ const picked = typeof chosen === "boolean" ? chosen : site.split("-")[0].toLowerCase() !== "en";
341
+ if (site && picked) return site;
342
+ const nav = typeof navigator !== "undefined" && navigator
343
+ ? (Array.isArray(navigator.languages) && navigator.languages[0]) || navigator.language
344
+ : "";
345
+ return canonicalTag(nav) || site || "en";
346
+ }
347
+
310
348
  /** `{name}` in `text`, filled from `values`. The one interpolation rule the SDK and the service share. */
311
349
  function fillPlaceholders(text, values) {
312
350
  const source = String(text == null ? "" : text);
@@ -321,7 +359,11 @@ function resyncLocale(data) {
321
359
  if (!l10nClient) return;
322
360
  const payload = data && typeof data.payload === "object" ? data.payload : data;
323
361
  const next = payload && (payload.locale || payload.lang || payload.language);
324
- if (next) l10nClient.applyLocale(next);
362
+ // The host says whether the player chose it (TES-4397): it re-posts the
363
+ // language on its own boot-time syncs too, which are not choices. A host
364
+ // that does not say leaves it to the language itself (see `playerLocale`).
365
+ const chosen = payload && typeof payload.localeChosen === "boolean" ? payload.localeChosen : "unknown";
366
+ if (next) l10nClient.applyLocale(next, { host: next, chosen });
325
367
  }
326
368
 
327
369
  /** A policy message from the host, or `null` when none is in force. */
@@ -1233,6 +1275,43 @@ function eventsHidden() {
1233
1275
  return typeof document !== "undefined" && Boolean(document) && document.visibilityState === "hidden";
1234
1276
  }
1235
1277
 
1278
+ /**
1279
+ * The build this page is, as the build stamped it: every published build
1280
+ * carries `<meta name="tesana-build" content="<hash>">` (the hash it is served
1281
+ * under), and so does the Studio's live preview. "" when there is none: a page
1282
+ * opened outside Tesana, or a game never built.
1283
+ */
1284
+ function pageBuildStamp() {
1285
+ try {
1286
+ if (typeof document === "undefined" || typeof document.querySelector !== "function") return "";
1287
+ const meta = document.querySelector('meta[name="tesana-build"]');
1288
+ const value = String((meta && meta.getAttribute && meta.getAttribute("content")) || "").trim();
1289
+ return /^[0-9a-f]{8,64}$/i.test(value) ? value.toLowerCase() : "";
1290
+ } catch {
1291
+ return "";
1292
+ }
1293
+ }
1294
+
1295
+ /**
1296
+ * Which build this is (`tesana.build`, bug reports, events): what the host or
1297
+ * the game named, else the page's own stamp (TES-196). The host names it on
1298
+ * tesana.com; a page with no host, or a host that names none, still has the
1299
+ * stamp.
1300
+ */
1301
+ function buildOf(merged) {
1302
+ return String(merged.build || merged.buildId || merged.buildVersion || pageBuildStamp() || "").slice(0, 64);
1303
+ }
1304
+
1305
+ /**
1306
+ * The release number of the running build (`tesana.release`), or null. The
1307
+ * host sends it only when the build is the release players have: a test build
1308
+ * in the Studio is no release yet.
1309
+ */
1310
+ function releaseOf(merged) {
1311
+ const number = Number(merged.release);
1312
+ return Number.isInteger(number) && number > 0 ? number : null;
1313
+ }
1314
+
1236
1315
  /**
1237
1316
  * Point the emitter at this page's bootstrap. Called by `init()` and again on
1238
1317
  * every bootstrap upgrade: a provisional answer may not name the game or carry
@@ -1249,7 +1328,7 @@ function eventsConfigure(merged) {
1249
1328
  }
1250
1329
  const game = eventsGame(merged);
1251
1330
  if (!game || page !== "yes") return;
1252
- const build = String(merged.build || merged.buildId || merged.buildVersion || "").slice(0, 64);
1331
+ const build = buildOf(merged);
1253
1332
  const session = EVENTS_OWN_COLLECTORS.has(url) ? eventsSessionToken(merged) : "";
1254
1333
  // Rebuilt on every bootstrap the session accepts: a refreshed token
1255
1334
  // replaces the old one. What was queued goes first, under the token it was
@@ -2062,12 +2141,18 @@ function buildConfig(merged) {
2062
2141
  locale: normalizeLocale(
2063
2142
  merged.locale || merged.language || merged.lang || (typeof navigator !== "undefined" && navigator.language) || "",
2064
2143
  ),
2144
+ // The host's own word, unfolded, for `tesana.locale`: "" when it sent none.
2145
+ hostLocale: String(merged.locale || merged.language || merged.lang || ""),
2146
+ // Whether the player picked that language (TES-4391); undefined when the host does not say.
2147
+ localeChosen: typeof merged.localeChosen === "boolean" ? merged.localeChosen : undefined,
2065
2148
  // How a dropped room socket is retried. A game can shrink the waits (a
2066
2149
  // test, or a game with unusual tolerance); the defaults are the fleet's.
2067
2150
  multiplayerReconnect: merged.multiplayerReconnect || undefined,
2068
- // Which build of the game this is, for a bug report. The host stamps it;
2069
- // absent means an older host and reports simply say nothing.
2070
- build: String(merged.build || merged.buildId || merged.buildVersion || "").slice(0, 64),
2151
+ // Which build of the game this is (`tesana.build`, bug reports): the
2152
+ // host's word, else the page's own stamp; "" when neither says.
2153
+ build: buildOf(merged),
2154
+ // The release players have, when this build is it (`tesana.release`).
2155
+ release: releaseOf(merged),
2071
2156
  // What an invite link carried, when the host opened the game from one.
2072
2157
  launch: merged.launch && typeof merged.launch === "object" ? merged.launch : null,
2073
2158
  };
@@ -2369,7 +2454,10 @@ class TesanaClient {
2369
2454
  this.track = track;
2370
2455
  this.gameplay = gameplay;
2371
2456
 
2457
+ /** Which build this is: its hash, or "" (TES-196). */
2372
2458
  this.build = opts.build || "";
2459
+ /** The release number of this build when it is the release players have, else null. */
2460
+ this.release = opts.release ?? null;
2373
2461
  this._launch = opts.launch || null;
2374
2462
 
2375
2463
  // Bug reports and crashes, to the creator. The host draws the form — like
@@ -3118,13 +3206,15 @@ class TesanaClient {
3118
3206
  // A later bootstrap may carry the player's language — a provisionally
3119
3207
  // "offline" answer has none, and the real one arrives a moment later. The
3120
3208
  // capability is re-pointed in place, exactly as the ad policy is.
3121
- if (config.locale && this.l10n) {
3122
- const next = normalizeLocale(config.locale);
3123
- if (next && next !== this.l10n.locale()) this.l10n.applyLocale(next);
3209
+ // The host's own word and whether the player chose it ride along, so
3210
+ // `tesana.locale` moves too, and onChange fires once for either change.
3211
+ if (this.l10n && (config.locale || config.hostLocale || typeof config.localeChosen === "boolean")) {
3212
+ this.l10n.applyLocale(config.locale, { host: config.hostLocale || undefined, chosen: config.localeChosen });
3124
3213
  }
3125
3214
  this._mpEnabled = config.multiplayer !== false;
3126
3215
  this.multiplayer.enabled = this._mpEnabled;
3127
3216
  if (config.build) this.build = config.build;
3217
+ if (config.release != null) this.release = config.release;
3128
3218
  if (config.launch) this._launch = config.launch;
3129
3219
  return this;
3130
3220
  }
@@ -3375,6 +3465,17 @@ class TesanaClient {
3375
3465
  // await and no round trip; only text the game discovers at runtime — a
3376
3466
  // procedurally generated item name, something the player typed — goes through
3377
3467
  // the async path. A game that never awaits anything still localizes.
3468
+
3469
+ /**
3470
+ * The player's language as a canonical BCP 47 tag (`ko-KR`, `fr`, `pt-BR`),
3471
+ * for a game choosing which of its own translations to show. The site's
3472
+ * language when the player picked one, else the browser's (TES-4382).
3473
+ * `l10n.locale()` stays the site's language.
3474
+ */
3475
+ get locale() {
3476
+ return this.l10n ? this.l10n.playerLocale() : playerLocale("", false);
3477
+ }
3478
+
3378
3479
  _makeL10n(opts) {
3379
3480
  const state = {
3380
3481
  locale: normalizeLocale(opts.locale || ""),
@@ -3402,6 +3503,10 @@ class TesanaClient {
3402
3503
  inflight: null,
3403
3504
  inflightTarget: "",
3404
3505
  loadedFor: null,
3506
+ // `tesana.locale`'s inputs: the host's own word ("" when it sent none)
3507
+ // and whether the player chose it while playing (TES-4382).
3508
+ hostLocale: opts.hostLocale || "",
3509
+ chosen: typeof opts.localeChosen === "boolean" ? opts.localeChosen : undefined,
3405
3510
  };
3406
3511
 
3407
3512
  const self = this;
@@ -3640,10 +3745,29 @@ class TesanaClient {
3640
3745
  reload: () => load(),
3641
3746
 
3642
3747
  // ---- internal wiring (used by the bootstrap listener) ----
3643
- /** A new language from the host. Resolves the same promise the game already holds. */
3644
- applyLocale(next) {
3748
+ /** `tesana.locale`: the player's language as a BCP 47 tag (see `playerLocale`). */
3749
+ playerLocale: () => playerLocale(state.hostLocale, state.chosen),
3750
+
3751
+ /**
3752
+ * A new language from the host. Resolves the same promise the game already holds.
3753
+ *
3754
+ * `host` is the host's own tag and `chosen` whether the player picked
3755
+ * it, as the host says: true or false, "unknown" when this host does
3756
+ * not say, or left out to keep what is known.
3757
+ */
3758
+ applyLocale(next, { host, chosen } = {}) {
3759
+ const before = playerLocale(state.hostLocale, state.chosen);
3760
+ if (host) state.hostLocale = String(host);
3761
+ if (typeof chosen === "boolean") state.chosen = chosen;
3762
+ else if (chosen === "unknown") state.chosen = undefined;
3645
3763
  const locale = normalizeLocale(next);
3646
- if (!locale || locale === state.locale) return state;
3764
+ if (!locale || locale === state.locale) {
3765
+ // The site's language stayed, but the player's may not have (they
3766
+ // picked English on a site that was already sending its default):
3767
+ // a game that follows `tesana.locale` still has to redraw.
3768
+ if (playerLocale(state.hostLocale, state.chosen) !== before) emit();
3769
+ return state;
3770
+ }
3647
3771
  state.locale = locale;
3648
3772
  // The old bundle is the *previous* language's, so it is cleared rather
3649
3773
  // than left to serve: showing a menu in a language the player just
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tesana/sdk",
3
- "version": "1.3.3",
3
+ "version": "1.4.0",
4
4
  "description": "Tesana play-time SDK — players, cloud saves, leaderboards, achievements and the in-game coin shop for a web game.",
5
5
  "type": "module",
6
6
  "license": "UNLICENSED",
package/src/tesana.js CHANGED
@@ -60,7 +60,7 @@
60
60
  // 1.3.3 (TES-314, DEC-126): an offline build that was never given an endpoint
61
61
  // (a desktop export with no play session) makes no play-service calls: its
62
62
  // base would only be the page's own origin, the wrapper's loopback server.
63
- const VERSION = "1.3.3";
63
+ const VERSION = "1.4.0";
64
64
 
65
65
  const LOCAL_CACHE = "tesana.play.v1";
66
66
 
@@ -305,6 +305,44 @@ function normalizeLocale(tag) {
305
305
  return L10N_TARGETS.find((t) => t.split("-")[0].toLowerCase() === base) || value;
306
306
  }
307
307
 
308
+ /** A language tag in its canonical BCP 47 form (`ko-KR`, `zh-Hant-TW`), or "" when it is not one. */
309
+ function canonicalTag(tag) {
310
+ const value = String(tag || "").trim().replace(/_/g, "-");
311
+ if (!value) return "";
312
+ try {
313
+ return Intl.getCanonicalLocales(value)[0] || "";
314
+ } catch {
315
+ return "";
316
+ }
317
+ }
318
+
319
+ /**
320
+ * The player's language, for a game choosing which of its own translations
321
+ * to show (`tesana.locale`, TES-4382).
322
+ *
323
+ * The host's word wins when the player chose it, English included: the host
324
+ * says so with `localeChosen: true`, on the bootstrap and on each
325
+ * `tesana-locale` change. An unset or default site language is not: tesana.com
326
+ * sends `en` to every visitor who has not picked one, Korean and French
327
+ * browsers included, so then the browser's own first language answers
328
+ * (TES-4391). A host that does not say (`chosen` undefined, older hosts) can
329
+ * only have sent a non-English language because the player picked it, so
330
+ * that counts as chosen and English does not. `l10n.locale()` stays the
331
+ * site's language, which is what the platform translates into.
332
+ *
333
+ * @param {string} host the host's own tag, "" when it sent none
334
+ * @param {boolean|undefined} chosen whether the player picked it; undefined when the host did not say
335
+ */
336
+ function playerLocale(host, chosen) {
337
+ const site = canonicalTag(host);
338
+ const picked = typeof chosen === "boolean" ? chosen : site.split("-")[0].toLowerCase() !== "en";
339
+ if (site && picked) return site;
340
+ const nav = typeof navigator !== "undefined" && navigator
341
+ ? (Array.isArray(navigator.languages) && navigator.languages[0]) || navigator.language
342
+ : "";
343
+ return canonicalTag(nav) || site || "en";
344
+ }
345
+
308
346
  /** `{name}` in `text`, filled from `values`. The one interpolation rule the SDK and the service share. */
309
347
  function fillPlaceholders(text, values) {
310
348
  const source = String(text == null ? "" : text);
@@ -319,7 +357,11 @@ function resyncLocale(data) {
319
357
  if (!l10nClient) return;
320
358
  const payload = data && typeof data.payload === "object" ? data.payload : data;
321
359
  const next = payload && (payload.locale || payload.lang || payload.language);
322
- if (next) l10nClient.applyLocale(next);
360
+ // The host says whether the player chose it (TES-4397): it re-posts the
361
+ // language on its own boot-time syncs too, which are not choices. A host
362
+ // that does not say leaves it to the language itself (see `playerLocale`).
363
+ const chosen = payload && typeof payload.localeChosen === "boolean" ? payload.localeChosen : "unknown";
364
+ if (next) l10nClient.applyLocale(next, { host: next, chosen });
323
365
  }
324
366
 
325
367
  /** A policy message from the host, or `null` when none is in force. */
@@ -1231,6 +1273,43 @@ function eventsHidden() {
1231
1273
  return typeof document !== "undefined" && Boolean(document) && document.visibilityState === "hidden";
1232
1274
  }
1233
1275
 
1276
+ /**
1277
+ * The build this page is, as the build stamped it: every published build
1278
+ * carries `<meta name="tesana-build" content="<hash>">` (the hash it is served
1279
+ * under), and so does the Studio's live preview. "" when there is none: a page
1280
+ * opened outside Tesana, or a game never built.
1281
+ */
1282
+ function pageBuildStamp() {
1283
+ try {
1284
+ if (typeof document === "undefined" || typeof document.querySelector !== "function") return "";
1285
+ const meta = document.querySelector('meta[name="tesana-build"]');
1286
+ const value = String((meta && meta.getAttribute && meta.getAttribute("content")) || "").trim();
1287
+ return /^[0-9a-f]{8,64}$/i.test(value) ? value.toLowerCase() : "";
1288
+ } catch {
1289
+ return "";
1290
+ }
1291
+ }
1292
+
1293
+ /**
1294
+ * Which build this is (`tesana.build`, bug reports, events): what the host or
1295
+ * the game named, else the page's own stamp (TES-196). The host names it on
1296
+ * tesana.com; a page with no host, or a host that names none, still has the
1297
+ * stamp.
1298
+ */
1299
+ function buildOf(merged) {
1300
+ return String(merged.build || merged.buildId || merged.buildVersion || pageBuildStamp() || "").slice(0, 64);
1301
+ }
1302
+
1303
+ /**
1304
+ * The release number of the running build (`tesana.release`), or null. The
1305
+ * host sends it only when the build is the release players have: a test build
1306
+ * in the Studio is no release yet.
1307
+ */
1308
+ function releaseOf(merged) {
1309
+ const number = Number(merged.release);
1310
+ return Number.isInteger(number) && number > 0 ? number : null;
1311
+ }
1312
+
1234
1313
  /**
1235
1314
  * Point the emitter at this page's bootstrap. Called by `init()` and again on
1236
1315
  * every bootstrap upgrade: a provisional answer may not name the game or carry
@@ -1247,7 +1326,7 @@ function eventsConfigure(merged) {
1247
1326
  }
1248
1327
  const game = eventsGame(merged);
1249
1328
  if (!game || page !== "yes") return;
1250
- const build = String(merged.build || merged.buildId || merged.buildVersion || "").slice(0, 64);
1329
+ const build = buildOf(merged);
1251
1330
  const session = EVENTS_OWN_COLLECTORS.has(url) ? eventsSessionToken(merged) : "";
1252
1331
  // Rebuilt on every bootstrap the session accepts: a refreshed token
1253
1332
  // replaces the old one. What was queued goes first, under the token it was
@@ -2060,12 +2139,18 @@ function buildConfig(merged) {
2060
2139
  locale: normalizeLocale(
2061
2140
  merged.locale || merged.language || merged.lang || (typeof navigator !== "undefined" && navigator.language) || "",
2062
2141
  ),
2142
+ // The host's own word, unfolded, for `tesana.locale`: "" when it sent none.
2143
+ hostLocale: String(merged.locale || merged.language || merged.lang || ""),
2144
+ // Whether the player picked that language (TES-4391); undefined when the host does not say.
2145
+ localeChosen: typeof merged.localeChosen === "boolean" ? merged.localeChosen : undefined,
2063
2146
  // How a dropped room socket is retried. A game can shrink the waits (a
2064
2147
  // test, or a game with unusual tolerance); the defaults are the fleet's.
2065
2148
  multiplayerReconnect: merged.multiplayerReconnect || undefined,
2066
- // Which build of the game this is, for a bug report. The host stamps it;
2067
- // absent means an older host and reports simply say nothing.
2068
- build: String(merged.build || merged.buildId || merged.buildVersion || "").slice(0, 64),
2149
+ // Which build of the game this is (`tesana.build`, bug reports): the
2150
+ // host's word, else the page's own stamp; "" when neither says.
2151
+ build: buildOf(merged),
2152
+ // The release players have, when this build is it (`tesana.release`).
2153
+ release: releaseOf(merged),
2069
2154
  // What an invite link carried, when the host opened the game from one.
2070
2155
  launch: merged.launch && typeof merged.launch === "object" ? merged.launch : null,
2071
2156
  };
@@ -2367,7 +2452,10 @@ class TesanaClient {
2367
2452
  this.track = track;
2368
2453
  this.gameplay = gameplay;
2369
2454
 
2455
+ /** Which build this is: its hash, or "" (TES-196). */
2370
2456
  this.build = opts.build || "";
2457
+ /** The release number of this build when it is the release players have, else null. */
2458
+ this.release = opts.release ?? null;
2371
2459
  this._launch = opts.launch || null;
2372
2460
 
2373
2461
  // Bug reports and crashes, to the creator. The host draws the form — like
@@ -3116,13 +3204,15 @@ class TesanaClient {
3116
3204
  // A later bootstrap may carry the player's language — a provisionally
3117
3205
  // "offline" answer has none, and the real one arrives a moment later. The
3118
3206
  // capability is re-pointed in place, exactly as the ad policy is.
3119
- if (config.locale && this.l10n) {
3120
- const next = normalizeLocale(config.locale);
3121
- if (next && next !== this.l10n.locale()) this.l10n.applyLocale(next);
3207
+ // The host's own word and whether the player chose it ride along, so
3208
+ // `tesana.locale` moves too, and onChange fires once for either change.
3209
+ if (this.l10n && (config.locale || config.hostLocale || typeof config.localeChosen === "boolean")) {
3210
+ this.l10n.applyLocale(config.locale, { host: config.hostLocale || undefined, chosen: config.localeChosen });
3122
3211
  }
3123
3212
  this._mpEnabled = config.multiplayer !== false;
3124
3213
  this.multiplayer.enabled = this._mpEnabled;
3125
3214
  if (config.build) this.build = config.build;
3215
+ if (config.release != null) this.release = config.release;
3126
3216
  if (config.launch) this._launch = config.launch;
3127
3217
  return this;
3128
3218
  }
@@ -3373,6 +3463,17 @@ class TesanaClient {
3373
3463
  // await and no round trip; only text the game discovers at runtime — a
3374
3464
  // procedurally generated item name, something the player typed — goes through
3375
3465
  // the async path. A game that never awaits anything still localizes.
3466
+
3467
+ /**
3468
+ * The player's language as a canonical BCP 47 tag (`ko-KR`, `fr`, `pt-BR`),
3469
+ * for a game choosing which of its own translations to show. The site's
3470
+ * language when the player picked one, else the browser's (TES-4382).
3471
+ * `l10n.locale()` stays the site's language.
3472
+ */
3473
+ get locale() {
3474
+ return this.l10n ? this.l10n.playerLocale() : playerLocale("", false);
3475
+ }
3476
+
3376
3477
  _makeL10n(opts) {
3377
3478
  const state = {
3378
3479
  locale: normalizeLocale(opts.locale || ""),
@@ -3400,6 +3501,10 @@ class TesanaClient {
3400
3501
  inflight: null,
3401
3502
  inflightTarget: "",
3402
3503
  loadedFor: null,
3504
+ // `tesana.locale`'s inputs: the host's own word ("" when it sent none)
3505
+ // and whether the player chose it while playing (TES-4382).
3506
+ hostLocale: opts.hostLocale || "",
3507
+ chosen: typeof opts.localeChosen === "boolean" ? opts.localeChosen : undefined,
3403
3508
  };
3404
3509
 
3405
3510
  const self = this;
@@ -3638,10 +3743,29 @@ class TesanaClient {
3638
3743
  reload: () => load(),
3639
3744
 
3640
3745
  // ---- internal wiring (used by the bootstrap listener) ----
3641
- /** A new language from the host. Resolves the same promise the game already holds. */
3642
- applyLocale(next) {
3746
+ /** `tesana.locale`: the player's language as a BCP 47 tag (see `playerLocale`). */
3747
+ playerLocale: () => playerLocale(state.hostLocale, state.chosen),
3748
+
3749
+ /**
3750
+ * A new language from the host. Resolves the same promise the game already holds.
3751
+ *
3752
+ * `host` is the host's own tag and `chosen` whether the player picked
3753
+ * it, as the host says: true or false, "unknown" when this host does
3754
+ * not say, or left out to keep what is known.
3755
+ */
3756
+ applyLocale(next, { host, chosen } = {}) {
3757
+ const before = playerLocale(state.hostLocale, state.chosen);
3758
+ if (host) state.hostLocale = String(host);
3759
+ if (typeof chosen === "boolean") state.chosen = chosen;
3760
+ else if (chosen === "unknown") state.chosen = undefined;
3643
3761
  const locale = normalizeLocale(next);
3644
- if (!locale || locale === state.locale) return state;
3762
+ if (!locale || locale === state.locale) {
3763
+ // The site's language stayed, but the player's may not have (they
3764
+ // picked English on a site that was already sending its default):
3765
+ // a game that follows `tesana.locale` still has to redraw.
3766
+ if (playerLocale(state.hostLocale, state.chosen) !== before) emit();
3767
+ return state;
3768
+ }
3645
3769
  state.locale = locale;
3646
3770
  // The old bundle is the *previous* language's, so it is cleared rather
3647
3771
  // than left to serve: showing a menu in a language the player just