@arcadible/sdk 1.5.0-next.1 → 1.5.0-next.3

package/dist/client.d.ts

@@ -1,4 +1,5 @@
 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";
@@ -31,6 +32,13 @@ export interface Arcadible {
      * `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,7 @@ 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";
@@ -37,9 +38,11 @@ export function createClient(options = {}) {
     });
     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;
     });
@@ -55,6 +58,9 @@ export function createClient(options = {}) {
         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, and none comes after `ready`.
+        if (context || settled)
+            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,5 +1,6 @@
 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";
@@ -16,6 +17,7 @@ export type ServeOptions = {
     lifecycle?: LifecycleHost;
     holds?: Holds;
     system?: System;
+    context?: ContextState;
 };
 export type Host = {
     close(): void;
@@ -23,8 +25,9 @@ export type Host = {
     leave(timeout?: number): Promise<void>;
     setSystem(state: Partial<SystemState>): void;
 };
-type HostOptions = Omit<ServeOptions, "holds" | "system"> & {
+type HostOptions = Omit<ServeOptions, "holds" | "system" | "context"> & {
     language?: string;
+    launchedAt?: string;
     frame: HTMLIFrameElement;
     origin: string;
     window?: Window;

package/dist/host.js

@@ -1,6 +1,8 @@
 // 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 { isTime } from "./context/rules.js";
 import { createHolds } from "./lifecycle/holds.js";
 import { shortLanguage } from "./system/rules.js";
 import { createSystem } from "./system/server.js";
@@ -17,6 +19,7 @@ export function serve(options) {
             // 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()),
@@ -43,7 +46,20 @@ export function createHost(options) {
     const answering = answerHellos({
         frame: options.frame,
         origin: options.origin,
-        server: serve({ ...options, holds, system }),
+        server: serve({
+            ...options,
+            holds,
+            system,
+            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(),
+                },
+            },
+        }),
         window: win,
         onHello: options.onHello,
     });

package/dist/index.d.ts

@@ -5,4 +5,5 @@ 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/lifecycle/holds.js

@@ -58,7 +58,10 @@ export function createHolds() {
                     },
                     [Names.Paused]: (data) => {
                         const value = isObject(data) ? data["n"] : undefined;
-                        if (typeof value !== "number" || value > n)
+                        // a pause the page sent: a whole number, from 1 up to the last.
+                        if (!Number.isInteger(value) || value < 1)
+                            return;
+                        if (value > n)
                             return;
                         settled = Math.max(settled, value);
                         if (settled < n)

package/dist/system/rules.d.ts

@@ -8,5 +8,7 @@ export type SystemState = {
 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 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;

package/dist/system/rules.js

@@ -23,8 +23,15 @@ export function stateOf(value) {
     return { language: value["language"] };
 }
 // [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")
+        return null;
+    const short = tag.split("-")[0]?.toLowerCase() ?? "";
+    return isLanguage(short) ? short : null;
+}
+// [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";
+    return languageOf(tag) ?? "en";
 }

package/dist/system/server.js

@@ -1,15 +1,15 @@
 // 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";
+import { languageOf, Names, shortLanguage } from "./rules.js";
 // [function]
 export function createSystem(initial) {
-    let state = { ...initial };
+    // only a short tag goes to the game: `en-US` as `en`.
+    let state = { ...initial, language: shortLanguage(initial.language) };
     let context = null;
     return {
         set(next) {
-            const language = next.language !== undefined && isLanguage(next.language)
-                ? next.language
-                : state.language;
+            // a tag that isn't a language changes nothing.
+            const language = languageOf(next.language) ?? state.language;
             if (language === state.language)
                 return;
             state = { ...state, language };

package/dist/version.d.ts

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

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

package/package.json

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