@arcadible/sdk 1.5.0-next.0 → 1.5.0-next.2

package/dist/client.d.ts

@@ -1,4 +1,6 @@
 import { type Build } from "./bus/protocol.js";
+import { type Context } from "./context/client.js";
+import { type System } from "./system/client.js";
 import type { Backend } from "./saves/backend/types.js";
 import { type Saves } from "./saves/client.js";
 export type Ready = {
@@ -23,6 +25,20 @@ export interface Arcadible {
     readonly build: Build | null | undefined;
     /** Saves that carry over between the game's versions. */
     readonly saves: Saves;
+    /**
+     * Arcadible's state for the player, which changes while the game runs and
+     * asks nothing of it: `language`, with `on("change")`. Set by the time
+     * `ready` settles; `null` where no page says, such as standing alone, and
+     * `undefined` before.
+     */
+    readonly system: System | null | undefined;
+    /**
+     * How this run started, fixed for the run: `launch.at`, Arcadible's time
+     * at launch, so a daily puzzle doesn't trust the device's clock. Set by
+     * the time `ready` settles; `null` where no page says, such as standing
+     * alone, and `undefined` before.
+     */
+    readonly context: Context | null | undefined;
     /**
      * Starts the game's initialization: call it as your code starts, before
      * anything it awaits, and Arcadible shows the game's loading screen until

package/dist/client.js

@@ -6,6 +6,8 @@ import { openBus } from "./bus/client.js";
 import { buildOf, REQUEST_TIMEOUT } from "./bus/protocol.js";
 import { createLifecycle } from "./lifecycle/client.js";
 import { createPause } from "./lifecycle/pause.js";
+import { createContextClient } from "./context/client.js";
+import { createSystemClient } from "./system/client.js";
 import { indexedDBBackend } from "./saves/backend/indexeddb.js";
 import { createSaves } from "./saves/client.js";
 import { serve } from "./host.js";
@@ -35,8 +37,12 @@ export function createClient(options = {}) {
         timeout: options.requestTimeout ?? REQUEST_TIMEOUT,
     });
     let settled = null;
+    const system = createSystemClient(bus);
+    const context = createContextClient(bus);
     // ready once welcomed, and each module's first messages have arrived.
     const ready = Promise.all([bus.welcomed, opened]).then(([welcome]) => {
+        system.settle();
+        context.settle();
         settled = { build: buildOf(welcome.build) };
         return settled;
     });
@@ -49,6 +55,12 @@ export function createClient(options = {}) {
             return settled ? settled.build : undefined;
         },
         saves,
+        get system() {
+            return system.value;
+        },
+        get context() {
+            return context.value;
+        },
         initStart() {
             lifecycle.start();
             return ready;

package/dist/context/client.d.ts

@@ -0,0 +1,12 @@
+import type { Bus } from "../bus/client.js";
+/** How this run started, fixed for the run. */
+export interface Context {
+    readonly launch: {
+        /** This launch, by Arcadible's clock, as an ISO string. */
+        readonly at: string;
+    };
+}
+export declare function createContextClient(bus: Bus): {
+    settle(): void;
+    readonly value: Context | null | undefined;
+};

package/dist/context/client.js

@@ -0,0 +1,31 @@
+// The game's side of `context`: `arcadible.context`, how this run started,
+// fixed for the run. `undefined` before `ready`, and `null` where no page
+// says (standing alone, or an older page).
+import { isObject, log } from "../bus/protocol.js";
+import { contextOf, Names } from "./rules.js";
+// [function]
+export function createContextClient(bus) {
+    let context = null;
+    let settled = false;
+    bus.on(Names.State, isObject, (data) => {
+        // fixed for the run: the first one stands.
+        if (context)
+            return;
+        const next = contextOf(data);
+        if (!next) {
+            log("warn", "ignored a malformed context from the play page.");
+            return;
+        }
+        context = Object.freeze({ launch: Object.freeze({ ...next.launch }) });
+    });
+    return {
+        settle() {
+            settled = true;
+        },
+        get value() {
+            if (!settled)
+                return undefined;
+            return context;
+        },
+    };
+}

package/dist/context/rules.d.ts

@@ -0,0 +1,12 @@
+export declare const Names: {
+    readonly State: "context.state";
+};
+export type ContextState = {
+    launch: {
+        at: string;
+    };
+};
+/** A time the page may send: an ISO string in UTC that reads as a date. */
+export declare function isTime(value: unknown): value is string;
+/** The context as the game keeps it: only fields it knows, each checked. */
+export declare function contextOf(value: unknown): ContextState | null;

package/dist/context/rules.js

@@ -0,0 +1,29 @@
+// `context` on the bus, shared by both ends: how this run started, fixed
+// for the run.
+// [import]
+import { isObject } from "../bus/protocol.js";
+// [declare]
+export const Names = {
+    // the context, `{ launch: { at } }`: an event, sent once, as the module
+    // opens.
+    State: "context.state",
+};
+// a time as JavaScript's toISOString() writes it, in UTC.
+const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/u;
+// [function]
+/** A time the page may send: an ISO string in UTC that reads as a date. */
+export function isTime(value) {
+    return (typeof value === "string" &&
+        ISO.test(value) &&
+        !Number.isNaN(Date.parse(value)));
+}
+// [function]
+/** The context as the game keeps it: only fields it knows, each checked. */
+export function contextOf(value) {
+    if (!isObject(value))
+        return null;
+    const launch = value["launch"];
+    if (!isObject(launch) || !isTime(launch["at"]))
+        return null;
+    return { launch: { at: launch["at"] } };
+}

package/dist/context/server.d.ts

@@ -0,0 +1,3 @@
+import type { Module } from "../bus/server.js";
+import { type ContextState } from "./rules.js";
+export declare function contextServer(context: ContextState): () => Module;

package/dist/context/server.js

@@ -0,0 +1,13 @@
+// The page's side of `context`: how this run started, sent once as the game
+// connects. It never changes during the run.
+import { Names } from "./rules.js";
+// [function]
+export function contextServer(context) {
+    return () => ({
+        handlers: {},
+        // first on each channel, so the game has it by `ready`.
+        async open(send) {
+            send(Names.State, context);
+        },
+    });
+}

package/dist/host.d.ts

@@ -1,6 +1,9 @@
 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";
+import { type SystemState } from "./system/rules.js";
+import { type System } from "./system/server.js";
 import { type LifecycleHost } from "./lifecycle/server.js";
 import type { Backend } from "./saves/backend/types.js";
 import type { Where } from "./saves/rules.js";
@@ -13,13 +16,18 @@ export type ServeOptions = {
     now?: () => Date;
     lifecycle?: LifecycleHost;
     holds?: Holds;
+    system?: System;
+    context?: ContextState;
 };
 export type Host = {
     close(): void;
     hold(): () => void;
     leave(timeout?: number): Promise<void>;
+    setSystem(state: Partial<SystemState>): void;
 };
-type HostOptions = Omit<ServeOptions, "holds"> & {
+type HostOptions = Omit<ServeOptions, "holds" | "system" | "context"> & {
+    language?: string;
+    launchedAt?: string;
     frame: HTMLIFrameElement;
     origin: string;
     window?: Window;
@@ -29,5 +37,6 @@ export declare function serve(options: ServeOptions): Server;
 export declare function createHost(options: HostOptions): Host;
 export type { Server } from "./bus/server.js";
 export { createHolds, type Holds } from "./lifecycle/holds.js";
+export { createSystem, type System } from "./system/server.js";
 export { indexedDBBackend } from "./saves/backend/indexeddb.js";
 export { memoryBackend } from "./saves/backend/memory.js";

package/dist/host.js

@@ -1,7 +1,10 @@
 // The page's side of the bus. The play page uses `createHost`;
 // a game standing alone runs `serve` in its own page.
 import { answerHellos, createServer } from "./bus/server.js";
+import { contextServer } from "./context/server.js";
 import { createHolds } from "./lifecycle/holds.js";
+import { shortLanguage } from "./system/rules.js";
+import { createSystem } from "./system/server.js";
 import { lifecycleServer } from "./lifecycle/server.js";
 import { savesServer } from "./saves/server.js";
 // [function]
@@ -11,8 +14,11 @@ export function serve(options) {
     return createServer({
         build: version === null ? null : { version, channel },
         modules: [
-            // first, so the game knows whether it's held by `ready`.
+            // first, so the game knows whether it's held, and the system's
+            // state, by `ready`.
             ...(options.holds ? [options.holds.module] : []),
+            ...(options.system ? [options.system.module] : []),
+            ...(options.context ? [contextServer(options.context)] : []),
             savesServer({
                 backend,
                 now: options.now ?? (() => new Date()),
@@ -33,10 +39,20 @@ export function serve(options) {
 export function createHost(options) {
     const win = options.window ?? window;
     const holds = createHolds();
+    const system = createSystem({
+        language: options.language ?? shortLanguage(win.navigator?.language),
+    });
     const answering = answerHellos({
         frame: options.frame,
         origin: options.origin,
-        server: serve({ ...options, holds }),
+        server: serve({
+            ...options,
+            holds,
+            system,
+            context: {
+                launch: { at: options.launchedAt ?? new Date().toISOString() },
+            },
+        }),
         window: win,
         onHello: options.onHello,
     });
@@ -60,8 +76,10 @@ export function createHost(options) {
         },
         hold: () => holds.hold(),
         leave: (timeout) => holds.leave(timeout),
+        setSystem: (state) => system.set(state),
     };
 }
 export { createHolds } from "./lifecycle/holds.js";
+export { createSystem } from "./system/server.js";
 export { indexedDBBackend } from "./saves/backend/indexeddb.js";
 export { memoryBackend } from "./saves/backend/memory.js";

package/dist/index.d.ts

@@ -4,4 +4,6 @@ export { ArcadibleError, Codes } from "./bus/protocol.js";
 export type { Build, Code } from "./bus/protocol.js";
 export type { Arcadible, Ready } from "./client.js";
 export type { Saves } from "./saves/client.js";
+export type { System } from "./system/client.js";
+export type { Context } from "./context/client.js";
 export type { SaveInfo } from "./saves/rules.js";

package/dist/system/client.d.ts

@@ -0,0 +1,15 @@
+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". */
+    readonly language: string;
+    /**
+     * Called when something changes, with the new state (this same object)
+     * and the names of what changed. Returns a function that unsubscribes.
+     */
+    on(name: "change", listener: (system: System, changed: readonly string[]) => void): () => void;
+}
+export declare function createSystemClient(bus: Bus): {
+    settle(): void;
+    readonly value: System | null | undefined;
+};

package/dist/system/client.js

@@ -0,0 +1,62 @@
+// The game's side of `system`: `arcadible.system`, Arcadible's state for the
+// player, read at any time, with one `change` event naming what changed.
+// `undefined` before `ready`, and `null` where no page says (standing
+// alone, or an older page).
+import { ArcadibleError, Codes, isObject, log } from "../bus/protocol.js";
+import { Names, stateOf } from "./rules.js";
+// [function]
+export function createSystemClient(bus) {
+    let state = null;
+    let settled = false;
+    const listeners = new Set();
+    const system = {
+        get language() {
+            return state.language;
+        },
+        on(name, listener) {
+            if (name !== "change") {
+                throw new ArcadibleError(Codes.Invalid, `arcadible.system.on takes "change", not ${JSON.stringify(name)}.`);
+            }
+            if (typeof listener !== "function") {
+                throw new ArcadibleError(Codes.Invalid, 'arcadible.system.on("change") takes a function.');
+            }
+            const fn = listener;
+            listeners.add(fn);
+            return () => {
+                listeners.delete(fn);
+            };
+        },
+    };
+    bus.on(Names.State, isObject, (data) => {
+        const next = stateOf(data);
+        if (!next) {
+            log("warn", "ignored a malformed system state from the play page.");
+            return;
+        }
+        const before = state;
+        state = next;
+        if (!before || !settled)
+            return;
+        const changed = Object.keys(next).filter((key) => next[key] !== before[key]);
+        if (changed.length === 0)
+            return;
+        for (const listener of [...listeners]) {
+            try {
+                listener(system, changed);
+            }
+            catch (err) {
+                log("error", "a system change listener failed.", err);
+            }
+        }
+    });
+    return {
+        settle() {
+            settled = true;
+        },
+        get value() {
+            if (!settled)
+                return undefined;
+            return state ? system : null;
+        },
+    };
+}

package/dist/system/rules.d.ts

@@ -0,0 +1,12 @@
+export declare const Names: {
+    readonly State: "system.state";
+};
+export type SystemState = {
+    language: string;
+};
+/** A language the page may send: a short, lowercase tag. */
+export declare function isLanguage(value: unknown): value is string;
+/** The state as the game keeps it: only fields it knows, each checked. */
+export declare function stateOf(value: unknown): SystemState | null;
+/** A browser's language as a short tag: `en-US` as `en`, or `en`. */
+export declare function shortLanguage(tag: string | undefined): string;

package/dist/system/rules.js

@@ -0,0 +1,30 @@
+// `system` on the bus, shared by both ends: Arcadible's state for the
+// player, which changes while the game runs and asks nothing of it.
+// [import]
+import { isObject } from "../bus/protocol.js";
+// [declare]
+export const Names = {
+    // the state, `{ language }`: an event, sent as the module opens and on
+    // 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;
+// [function]
+/** A language the page may send: a short, lowercase tag. */
+export function isLanguage(value) {
+    return typeof value === "string" && LANGUAGE.test(value);
+}
+// [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"] };
+}
+// [function]
+/** A browser's language as a short tag: `en-US` as `en`, or `en`. */
+export function shortLanguage(tag) {
+    const short = (tag ?? "").split("-")[0]?.toLowerCase() ?? "";
+    return isLanguage(short) ? short : "en";
+}

package/dist/system/server.d.ts

@@ -0,0 +1,7 @@
+import type { Module, ModuleContext } from "../bus/server.js";
+import { type SystemState } from "./rules.js";
+export type System = {
+    set(state: Partial<SystemState>): void;
+    module(context: ModuleContext): Module;
+};
+export declare function createSystem(initial: SystemState): System;

package/dist/system/server.js

@@ -0,0 +1,30 @@
+// 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 { isLanguage, Names } from "./rules.js";
+// [function]
+export function createSystem(initial) {
+    let state = { ...initial };
+    let context = null;
+    return {
+        set(next) {
+            const language = next.language !== undefined && isLanguage(next.language)
+                ? next.language
+                : state.language;
+            if (language === state.language)
+                return;
+            state = { ...state, language };
+            context?.broadcast(Names.State, state);
+        },
+        module(ctx) {
+            context = ctx;
+            return {
+                handlers: {},
+                // the state now, first on each channel, so the game has it by
+                // `ready`.
+                async open(send) {
+                    send(Names.State, state);
+                },
+            };
+        },
+    };
+}

package/dist/version.d.ts

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

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.0";
+export const VERSION = "1.5.0-next.2";

package/package.json

@@ -43,5 +43,5 @@
   ],
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "1.5.0-next.0"
+  "version": "1.5.0-next.2"
 }