@arcadible/sdk 1.5.0-next.3 → 1.5.0

package/README.md

@@ -7,20 +7,26 @@
 <h1 align="center">Arcadible SDK</h1>
 
 <p align="center">
-  Arcadible's loading screen for your game, and saves that carry over from one version to the next.
+  How your game works with Arcadible.
 </p>
 
 <p align="center">
   <a href="https://developer.arcadible.com/references/arcadible-sdk">Docs</a> ·
   <a href="https://developer.arcadible.com/build/initialization">Initialization</a> ·
   <a href="https://developer.arcadible.com/build/saves">Saves</a> ·
+  <a href="https://developer.arcadible.com/build/pausing">Pausing</a> ·
   <a href="https://arcadible.com">Arcadible</a> ·
   <a href="https://studio.arcadible.com">Studio</a>
 </p>
 
 <br>
 
-The Arcadible SDK is optional: a game runs on [Arcadible](https://arcadible.com) without it. With it, a game gets two things from the play page around it: its [initialization](https://developer.arcadible.com/build/initialization), bracketed, so Arcadible's loading screen shows the game's splash and progress until its first frame is drawn, and [saves](https://developer.arcadible.com/build/saves), kept by the play page, so the player's progress carries over from one version to the next.
+The Arcadible SDK is optional: a game runs on [Arcadible](https://arcadible.com) without it. With it, a game gets these from the play page around it:
+
+- **[Initialization](https://developer.arcadible.com/build/initialization),** bracketed, so Arcadible's loading screen shows the game's splash and progress until its first frame is drawn.
+- **[Saves](https://developer.arcadible.com/build/saves),** kept by the play page, so the player's progress carries over from one version to the next.
+- **[Pausing](https://developer.arcadible.com/build/pausing):** Arcadible tells the game when to stop, go quiet, and save, and when to carry on.
+- **[`system` and `context`](https://developer.arcadible.com/references/arcadible-sdk#system):** the store's language, and when this run launched.
 
 ## Install
 
@@ -58,11 +64,28 @@ Saves are for what your game remembers between sessions, such as progress, setti
 
 Off Arcadible, such as on your dev server, the package still works, with the same rules and limits: there's no loading screen, so `initComplete()` resolves at once, saves are kept in the game's own browser storage, `arcadible.saves.where` is `"build"`, and `arcadible.build` is `null`.
 
+## Pause and resume
+
+```js
+arcadible.on("pause", async () => {
+  loop.stop();
+  audio.mute();
+  await arcadible.saves.write("progress", JSON.stringify(progress));
+});
+arcadible.on("resume", () => {
+  loop.start();
+  audio.unmute();
+});
+```
+
+Arcadible pauses your game when the page is hidden, when it covers your game, and before it closes or reloads it, when it waits a moment for your save. Stop, go quiet, and save, drawing nothing over your game; on `resume`, carry on, or show a "Ready?" first in an action game.
+
 ## Learn more
 
 - [Initialization](https://developer.arcadible.com/build/initialization): where each call goes, progress, and what comes after.
 - [Saves](https://developer.arcadible.com/build/saves): using saves well, across versions, channels, and tabs, and where they're kept.
-- [Arcadible SDK](https://developer.arcadible.com/references/arcadible-sdk): including it, every call, the saves' included, and every code.
+- [Pausing](https://developer.arcadible.com/build/pausing): what a pause asks of your game, and resuming.
+- [Arcadible SDK](https://developer.arcadible.com/references/arcadible-sdk): including it, every call, the saves' included, `system` and `context`, and every code.
 - [Limits](https://developer.arcadible.com/references/limits#saves): how many saves, and how large.
 
 ## License

package/dist/host.d.ts

@@ -1,4 +1,4 @@
-import type { Hello } from "./bus/protocol.js";
+import { type Hello } from "./bus/protocol.js";
 import { type Server } from "./bus/server.js";
 import { type ContextState } from "./context/rules.js";
 import { type Holds } from "./lifecycle/holds.js";

package/dist/host.js

@@ -1,10 +1,12 @@
 // The page's side of the bus. The play page uses `createHost`;
 // a game standing alone runs `serve` in its own page.
+// [import]
+import { log } from "./bus/protocol.js";
 import { answerHellos, createServer } from "./bus/server.js";
 import { contextServer } from "./context/server.js";
 import { isTime } from "./context/rules.js";
 import { createHolds } from "./lifecycle/holds.js";
-import { shortLanguage } from "./system/rules.js";
+import { browserLanguage } from "./system/rules.js";
 import { createSystem } from "./system/server.js";
 import { lifecycleServer } from "./lifecycle/server.js";
 import { savesServer } from "./saves/server.js";
@@ -32,6 +34,18 @@ export function serve(options) {
     });
 }
 // [function]
+// The launch's time: the page's, by Arcadible's clock, or the device's when
+// none is given (as under `arc serve`). One that isn't an ISO time in UTC is
+// a bug in the page, said in the console, and the device's time is used, so
+// the game still gets one.
+function launchedAt(given) {
+    if (isTime(given))
+        return given;
+    if (given !== undefined) {
+        log("error", `launchedAt isn't an ISO time in UTC: ${JSON.stringify(given)}; the device's time is used.`);
+    }
+    return new Date().toISOString();
+}
 // The play page's host: it answers its iframe's hello with a welcome and a
 // private channel. Call it before inserting the iframe, so no hello is
 // missed. It holds the game while the page is hidden; `hold` holds it for
@@ -41,7 +55,7 @@ export function createHost(options) {
     const win = options.window ?? window;
     const holds = createHolds();
     const system = createSystem({
-        language: options.language ?? shortLanguage(win.navigator?.language),
+        language: options.language ?? browserLanguage(win.navigator?.language),
     });
     const answering = answerHellos({
         frame: options.frame,
@@ -53,11 +67,7 @@ export function createHost(options) {
             context: {
                 // Arcadible's time when given, else the device's: never a time the
                 // game would refuse.
-                launch: {
-                    at: isTime(options.launchedAt)
-                        ? options.launchedAt
-                        : new Date().toISOString(),
-                },
+                launch: { at: launchedAt(options.launchedAt) },
             },
         }),
         window: win,

package/dist/system/client.d.ts

@@ -1,7 +1,12 @@
 import type { Bus } from "../bus/client.js";
 /** Arcadible's state for the player, which changes while the game runs. */
 export interface System {
-    /** The store's language, a short tag: "en", "ja". */
+    /**
+     * The language Arcadible's store shows this player: a well-formed BCP 47
+     * tag in its canonical form ("en", "ja", later perhaps "zh-Hant" or
+     * "pt-BR"), ready for `Intl`. Match it against your game's languages by
+     * dropping parts from the end ("zh-Hant-TW", "zh-Hant", "zh").
+     */
     readonly language: string;
     /**
      * Called when something changes, with the new state (this same object)

package/dist/system/rules.d.ts

@@ -4,11 +4,19 @@ export declare const Names: {
 export type SystemState = {
     language: string;
 };
-/** A language the page may send: a short, lowercase tag. */
+/**
+ * A language tag (BCP 47, as the web, iOS, and Android use) in its canonical
+ * form, `zh-hant-tw` as `zh-Hant-TW`, or null if it isn't a well-formed one
+ * (`en_US`, `English`, empty). Only its shape is checked, never whether
+ * Arcadible uses it, so a language added later is never refused.
+ */
+export declare function languageOf(tag: unknown): string | null;
+/** Whether a value is a language tag in its canonical form. */
 export declare function isLanguage(value: unknown): value is string;
-/** The state as the game keeps it: only fields it knows, each checked. */
+/**
+ * The state as the game keeps it: only fields it knows, each checked, the
+ * language in its canonical form.
+ */
 export declare function stateOf(value: unknown): SystemState | null;
-/** A language tag as a short one: `en-US` as `en`, or null if it isn't one. */
-export declare function languageOf(tag: unknown): string | null;
-/** A browser's language as a short tag: `en-US` as `en`, or `en`. */
-export declare function shortLanguage(tag: string | undefined): string;
+/** A browser's language (`navigator.language`) as the page sends it, or `en`. */
+export declare function browserLanguage(tag: string | undefined): string;

package/dist/system/rules.js

@@ -8,30 +8,54 @@ export const Names = {
     // every change.
     State: "system.state",
 };
-// a language as the store names it: a short tag, `en` or `ja`.
-const LANGUAGE = /^[a-z]{2,3}$/u;
+// The longest language tag kept: room for a language, script, region, and a
+// variant or two (`zh-Hant-TW`, `sl-rozaj-biske`), not a paragraph.
+const MAX_LANGUAGE = 35;
+// A tag's shape, where the browser can't say (no `Intl.getCanonicalLocales`).
+const SHAPE = /^[A-Za-z]{2,3}(-[A-Za-z0-9]{1,8})*$/u;
+// The language itself, first: an ISO 639 code, two or three letters. BCP 47
+// also allows five to eight (`english` is well-formed), which nothing uses.
+const PRIMARY = /^[A-Za-z]{2,3}(-|$)/u;
 // [function]
-/** A language the page may send: a short, lowercase tag. */
-export function isLanguage(value) {
-    return typeof value === "string" && LANGUAGE.test(value);
+/**
+ * A language tag (BCP 47, as the web, iOS, and Android use) in its canonical
+ * form, `zh-hant-tw` as `zh-Hant-TW`, or null if it isn't a well-formed one
+ * (`en_US`, `English`, empty). Only its shape is checked, never whether
+ * Arcadible uses it, so a language added later is never refused.
+ */
+export function languageOf(tag) {
+    if (typeof tag !== "string" || tag.length === 0)
+        return null;
+    if (tag.length > MAX_LANGUAGE || !PRIMARY.test(tag))
+        return null;
+    if (typeof Intl === "undefined" || !Intl.getCanonicalLocales) {
+        return SHAPE.test(tag) ? tag : null;
+    }
+    try {
+        return Intl.getCanonicalLocales(tag)[0] ?? null;
+    }
+    catch {
+        return null;
+    }
 }
 // [function]
-/** The state as the game keeps it: only fields it knows, each checked. */
-export function stateOf(value) {
-    if (!isObject(value) || !isLanguage(value["language"]))
-        return null;
-    return { language: value["language"] };
+/** Whether a value is a language tag in its canonical form. */
+export function isLanguage(value) {
+    return typeof value === "string" && languageOf(value) === value;
 }
 // [function]
-/** A language tag as a short one: `en-US` as `en`, or null if it isn't one. */
-export function languageOf(tag) {
-    if (typeof tag !== "string")
+/**
+ * The state as the game keeps it: only fields it knows, each checked, the
+ * language in its canonical form.
+ */
+export function stateOf(value) {
+    if (!isObject(value))
         return null;
-    const short = tag.split("-")[0]?.toLowerCase() ?? "";
-    return isLanguage(short) ? short : null;
+    const language = languageOf(value["language"]);
+    return language ? { language } : null;
 }
 // [function]
-/** A browser's language as a short tag: `en-US` as `en`, or `en`. */
-export function shortLanguage(tag) {
+/** A browser's language (`navigator.language`) as the page sends it, or `en`. */
+export function browserLanguage(tag) {
     return languageOf(tag) ?? "en";
 }

package/dist/system/server.js

@@ -1,10 +1,10 @@
 // The page's side of `system`: Arcadible's state for the player, sent as
 // the game connects and again whenever it changes. Nothing waits on it.
-import { languageOf, Names, shortLanguage } from "./rules.js";
+import { browserLanguage, languageOf, Names, } from "./rules.js";
 // [function]
 export function createSystem(initial) {
-    // only a short tag goes to the game: `en-US` as `en`.
-    let state = { ...initial, language: shortLanguage(initial.language) };
+    // only a well-formed tag goes to the game, in its canonical form.
+    let state = { ...initial, language: browserLanguage(initial.language) };
     let context = null;
     return {
         set(next) {

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.5.0-next.3";
+export declare const VERSION = "1.5.0";

package/dist/version.js

@@ -1,3 +1,3 @@
 // The client's version, sent in its hello and shown as `arcadible.version`,
 // for bug reports. It matches package.json (test/unit/protocol.test.ts).
-export const VERSION = "1.5.0-next.3";
+export const VERSION = "1.5.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "author": "Offst, Inc.",
-  "description": "The Arcadible SDK: Arcadible's loading screen for a game's initialization, and saves that carry over between its versions.",
+  "description": "The Arcadible SDK: how your game works with Arcadible.",
   "devDependencies": {
     "@playwright/test": "1.63.0",
     "@types/node": "^25.0.3",
@@ -43,5 +43,5 @@
   ],
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "1.5.0-next.3"
+  "version": "1.5.0"
 }