@diffenderfer-games/hub 2.0.0-next.0 → 2.0.0-next.10

package/src/core/storage/json-guards.ts

@@ -1,74 +1,80 @@
-/**
- * Small type guards for values this client did not create: JSON read back
- * from `localStorage`, error bodies, objects from other bundles. The browser
- * client carries no zod (plan D16), so these replace schema parsing on the
- * few shapes it reads.
- */
-import type { Json } from '@diffenderfer-games/hub-contract';
-
-/** A plain object's fields, not yet checked. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: the fields of a value read from storage or another bundle
-export type UncheckedRecord = Readonly<Record<string, unknown>>;
-
-/** Whether `candidate` is a non-null, non-array object. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: checks a value read from storage or another bundle
-export function isRecord(candidate: unknown): candidate is UncheckedRecord {
-  return typeof candidate === 'object' && candidate !== null && !Array.isArray(candidate);
-}
-
-/** `candidate` when it is a string, else `undefined`. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: one field of an unchecked record
-export function optionalString(candidate: unknown): string | undefined {
-  return typeof candidate === 'string' ? candidate : undefined;
-}
-
-/** `candidate` when it is a finite number, else `undefined`. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: one field of an unchecked record
-export function optionalNumber(candidate: unknown): number | undefined {
-  return typeof candidate === 'number' && Number.isFinite(candidate) ? candidate : undefined;
-}
-
-/** Whether `candidate` is a string or `null`. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: one field of an unchecked record
-export function isNullableString(candidate: unknown): candidate is string | null {
-  return candidate === null || typeof candidate === 'string';
-}
-
-/** Whether `candidate` is a JSON value (what `JSON.parse` can return). */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: checks a value read from storage
-export function isJson(candidate: unknown): candidate is Json {
-  if (candidate === null || typeof candidate === 'string' || typeof candidate === 'boolean') {
-    return true;
-  }
-  if (typeof candidate === 'number') {
-    return Number.isFinite(candidate);
-  }
-  if (Array.isArray(candidate)) {
-    return candidate.every(isJson);
-  }
-  return isRecord(candidate) && Object.values(candidate).every(isJson);
-}
-
-/** Whether `candidate` is an object whose every value is a finite number. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: checks a value read from storage
-export function isNumberRecord(candidate: unknown): candidate is Readonly<Record<string, number>> {
-  return isRecord(candidate) && Object.values(candidate).every((entry) => optionalNumber(entry) !== undefined);
-}
-
-/** The strings in `candidate`, or an empty list when it is not an array. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: a list read from storage
-export function stringsIn(candidate: unknown): string[] {
-  return Array.isArray(candidate) ? candidate.filter((entry): entry is string => typeof entry === 'string') : [];
-}
-
-/** Parse JSON text without throwing: `undefined` when it is not JSON. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: text read from storage, checked by the caller's guard next
-export function parseJsonText(text: string): unknown {
-  try {
-    // eslint-disable-next-line no-restricted-syntax -- trust boundary: JSON.parse's result, checked by the caller's guard next
-    const parsed: unknown = JSON.parse(text);
-    return parsed;
-  } catch {
-    return undefined;
-  }
-}
+/**
+ * Small type guards for values this client did not create: JSON read back
+ * from `localStorage`, error bodies, objects from other bundles. The browser
+ * client carries no zod (plan D16), so these replace schema parsing on the
+ * few shapes it reads.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+
+/** A plain object's fields, not yet checked. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: the fields of a value read from storage or another bundle
+export type UncheckedRecord = Readonly<Record<string, unknown>>;
+
+/** Whether `candidate` is a non-null, non-array object. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: checks a value read from storage or another bundle
+export function isRecord(candidate: unknown): candidate is UncheckedRecord {
+  return typeof candidate === 'object' && candidate !== null && !Array.isArray(candidate);
+}
+
+/** `candidate` when it is a string, else `undefined`. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: one field of an unchecked record
+export function optionalString(candidate: unknown): string | undefined {
+  return typeof candidate === 'string' ? candidate : undefined;
+}
+
+/** `candidate` when it is a finite number, else `undefined`. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: one field of an unchecked record
+export function optionalNumber(candidate: unknown): number | undefined {
+  return typeof candidate === 'number' && Number.isFinite(candidate) ? candidate : undefined;
+}
+
+/** Whether `candidate` is a string or `null`. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: one field of an unchecked record
+export function isNullableString(candidate: unknown): candidate is string | null {
+  return candidate === null || typeof candidate === 'string';
+}
+
+/** Whether `candidate` is a JSON value (what `JSON.parse` can return). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: checks a value read from storage
+export function isJson(candidate: unknown): candidate is Json {
+  if (candidate === null || typeof candidate === 'string' || typeof candidate === 'boolean') {
+    return true;
+  }
+  if (typeof candidate === 'number') {
+    return Number.isFinite(candidate);
+  }
+  if (Array.isArray(candidate)) {
+    return candidate.every(isJson);
+  }
+  return isRecord(candidate) && Object.values(candidate).every(isJson);
+}
+
+/** Whether `candidate` is an object whose every value is a finite number. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: checks a value read from storage
+export function isNumberRecord(candidate: unknown): candidate is Readonly<Record<string, number>> {
+  return isRecord(candidate) && Object.values(candidate).every((entry) => optionalNumber(entry) !== undefined);
+}
+
+/** The strings in `candidate`, or an empty list when it is not an array. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a list read from storage
+export function stringsIn(candidate: unknown): string[] {
+  return Array.isArray(candidate) ? candidate.filter((entry): entry is string => typeof entry === 'string') : [];
+}
+
+/** Parse JSON text without throwing: `undefined` when it is not JSON. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: text read from storage, checked by the caller's guard next
+export function parseJsonText(text: string): unknown {
+  try {
+    // eslint-disable-next-line no-restricted-syntax -- trust boundary: JSON.parse's result, checked by the caller's guard next
+    const parsed: unknown = JSON.parse(text);
+    return parsed;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Whether `candidate` is a JSON object (not an array or `null`). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: checks a value read from storage
+export function isJsonObject(candidate: unknown): candidate is { readonly [key: string]: Json } {
+  return isRecord(candidate) && Object.values(candidate).every(isJson);
+}

package/src/core/storage/key-value.ts

@@ -1,66 +1,66 @@
-/**
- * The string store behind the offline cache and queues: `localStorage` when
- * the page has it, else an in-memory map (privacy mode, Node, tests). Every
- * key keeps the v1 client's name, so a page upgraded from a vendored copy
- * still reads the queue and cache that copy wrote.
- */
-
-/** A string key-value store with `localStorage`'s semantics. */
-export interface KeyValueStore {
-  /** The stored text, or `null`. */
-  read(key: string): string | null;
-  /** Store text; a full or blocked storage is ignored. */
-  write(key: string, text: string): void;
-  /** Forget a key. */
-  remove(key: string): void;
-  /** Every stored key. */
-  keys(): string[];
-}
-
-/** A store backed by a `Storage` (`localStorage`). */
-function storageBacked(storage: Storage): KeyValueStore {
-  return {
-    read: (key) => storage.getItem(key),
-    write: (key, text) => {
-      try {
-        storage.setItem(key, text);
-      } catch {
-        // A full or blocked storage loses the write, as in v1.
-      }
-    },
-    remove: (key) => {
-      storage.removeItem(key);
-    },
-    keys: () => Object.keys(storage),
-  };
-}
-
-/** A store held in memory for this page only. */
-export function createMemoryStore(): KeyValueStore {
-  const entries = new Map<string, string>();
-  return {
-    read: (key) => entries.get(key) ?? null,
-    write: (key, text) => {
-      entries.set(key, text);
-    },
-    remove: (key) => {
-      entries.delete(key);
-    },
-    keys: () => [...entries.keys()],
-  };
-}
-
-/** The page's `localStorage`, or `undefined` when it is missing or throws (privacy mode). */
-function pageStorage(): Storage | undefined {
-  try {
-    return typeof localStorage === 'undefined' ? undefined : localStorage;
-  } catch {
-    return undefined;
-  }
-}
-
-/** `localStorage` when available, else a fresh in-memory store. */
-export function createPageStore(): KeyValueStore {
-  const storage = pageStorage();
-  return storage === undefined ? createMemoryStore() : storageBacked(storage);
-}
+/**
+ * The string store behind the offline cache and queues: `localStorage` when
+ * the page has it, else an in-memory map (privacy mode, Node, tests). Every
+ * key keeps the v1 client's name, so a page upgraded from a vendored copy
+ * still reads the queue and cache that copy wrote.
+ */
+
+/** A string key-value store with `localStorage`'s semantics. */
+export interface KeyValueStore {
+  /** The stored text, or `null`. */
+  read(key: string): string | null;
+  /** Store text; a full or blocked storage is ignored. */
+  write(key: string, text: string): void;
+  /** Forget a key. */
+  remove(key: string): void;
+  /** Every stored key. */
+  keys(): string[];
+}
+
+/** A store backed by a `Storage` (`localStorage`). */
+function storageBacked(storage: Storage): KeyValueStore {
+  return {
+    read: (key) => storage.getItem(key),
+    write: (key, text) => {
+      try {
+        storage.setItem(key, text);
+      } catch {
+        // A full or blocked storage loses the write, as in v1.
+      }
+    },
+    remove: (key) => {
+      storage.removeItem(key);
+    },
+    keys: () => Object.keys(storage),
+  };
+}
+
+/** A store held in memory for this page only. */
+export function createMemoryStore(): KeyValueStore {
+  const entries = new Map<string, string>();
+  return {
+    read: (key) => entries.get(key) ?? null,
+    write: (key, text) => {
+      entries.set(key, text);
+    },
+    remove: (key) => {
+      entries.delete(key);
+    },
+    keys: () => [...entries.keys()],
+  };
+}
+
+/** The page's `localStorage`, or `undefined` when it is missing or throws (privacy mode). */
+function pageStorage(): Storage | undefined {
+  try {
+    return typeof localStorage === 'undefined' ? undefined : localStorage;
+  } catch {
+    return undefined;
+  }
+}
+
+/** `localStorage` when available, else a fresh in-memory store. */
+export function createPageStore(): KeyValueStore {
+  const storage = pageStorage();
+  return storage === undefined ? createMemoryStore() : storageBacked(storage);
+}

package/src/core/ticket.ts

@@ -1,43 +1,43 @@
-/**
- * The own-server ticket request (`hub.mp.ticket()`): a 60-second identity
- * ticket for this game's own server, fetched straight from the hub. It must
- * not depend on the social runtime: on the first visit after a deploy the
- * service worker can still serve an older menu that never loads it. When the
- * page has no session yet, a guest one is created and the request retried
- * once.
- */
-import { HubError, OfflineError } from './errors';
-import { detectApiBase, detectSlug } from './page';
-import { createRestClient, type RestClient } from './rest/rest-client';
-
-/** A REST client for the page's API base that uses the global fetch at call time. */
-function pageRestClient(): RestClient {
-  return createRestClient({ apiBase: detectApiBase(), fetch: (input, init) => globalThis.fetch(input, init) });
-}
-
-/** One ticket request; a transport failure is an {@link OfflineError}. */
-async function requestTicket(rest: RestClient, slug: string): Promise<string> {
-  try {
-    return (await rest.call('getGameServerTicket', { slug })).ticket;
-  } catch (failure) {
-    throw failure instanceof HubError && failure.isOffline ? new OfflineError() : failure;
-  }
-}
-
-/** A ticket for this page's game; signs in a guest first when the page has no session. */
-export async function fetchGameServerTicket(): Promise<string> {
-  const slug = detectSlug();
-  if (slug === null) {
-    throw new HubError('Hub: could not determine the game slug.');
-  }
-  const rest = pageRestClient();
-  try {
-    return await requestTicket(rest, slug);
-  } catch (failure) {
-    if (!(failure instanceof HubError) || failure.status !== 401) {
-      throw failure;
-    }
-    await rest.call('ensureGuestSession');
-    return requestTicket(rest, slug);
-  }
-}
+/**
+ * The own-server ticket request (`hub.mp.ticket()`): a 60-second identity
+ * ticket for this game's own server, fetched straight from the hub. It must
+ * not depend on the social runtime: on the first visit after a deploy the
+ * service worker can still serve an older menu that never loads it. When the
+ * page has no session yet, a guest one is created and the request retried
+ * once.
+ */
+import { HubError, OfflineError } from './errors';
+import { detectApiBase, detectSlug } from './page';
+import { createRestClient, type RestClient } from './rest/rest-client';
+
+/** A REST client for the page's API base that uses the global fetch at call time. */
+function pageRestClient(): RestClient {
+  return createRestClient({ apiBase: detectApiBase(), fetch: (input, init) => globalThis.fetch(input, init) });
+}
+
+/** One ticket request; a transport failure is an {@link OfflineError}. */
+async function requestTicket(rest: RestClient, slug: string): Promise<string> {
+  try {
+    return (await rest.call('getGameServerTicket', { slug })).ticket;
+  } catch (failure) {
+    throw failure instanceof HubError && failure.isOffline ? new OfflineError() : failure;
+  }
+}
+
+/** A ticket for this page's game; signs in a guest first when the page has no session. */
+export async function fetchGameServerTicket(): Promise<string> {
+  const slug = detectSlug();
+  if (slug === null) {
+    throw new HubError('Hub: could not determine the game slug.');
+  }
+  const rest = pageRestClient();
+  try {
+    return await requestTicket(rest, slug);
+  } catch (failure) {
+    if (!(failure instanceof HubError) || failure.status !== 401) {
+      throw failure;
+    }
+    await rest.call('ensureGuestSession');
+    return requestTicket(rest, slug);
+  }
+}

package/src/core/turns/hub-turns.ts

@@ -0,0 +1,161 @@
+/**
+ * `hub.turns`: online, turn-based games the hub runs from the game's own
+ * rules module (`game.turns`), played over minutes or days. Make one
+ * (inviting friends, with a link, or with open seats anyone may take),
+ * join one, open one the player sits in, and list them. Players see "an
+ * online game", never "a turn game".
+ *
+ * ```ts
+ * const opened = hub.saved.opened;
+ * const game = opened?.kind === 'turns' ? await hub.turns.open(opened.id)
+ *   : hub.turns.link !== null ? await hub.turns.join(hub.turns.link)
+ *   : null;
+ * game?.on('move', ({ view, events }) => animate(events, view));
+ * ```
+ */
+import type { CreateTurnGame, OpenTurnGame, TurnDeadline } from '@diffenderfer-games/hub-contract';
+import { toStoredJson, type GamePayload } from '../game-data';
+import { isBrowserPage } from '../page';
+import type { SavedEntry } from '../saved/saved-types';
+import { TurnGame, type TurnGameHost, type TurnGameOptions } from './turn-game';
+import { readYourTurnBuzz, saveYourTurnBuzz } from './your-turn-buzz';
+
+/** The query parameter an invite link carries (`/<slug>/?hub_turn_link=<key>`); the client strips it. */
+export const TURN_LINK_PARAM = 'hub_turn_link';
+
+/** Where the answer is kept for the page. */
+const PAGE_FLAG = '__HUB_TURN_LINK__';
+
+/** How to make a game. */
+export interface TurnCreateOptions {
+  readonly mode?: string;
+  /** The game's own setup choices (at most 2 KB of JSON). */
+  readonly options?: GamePayload;
+  /** Friends to invite (their seats are held). */
+  readonly invite?: readonly number[];
+  /** Make a link others can take a seat with (`game.link`). */
+  readonly link?: boolean;
+  /** List the open seats in Play online for anyone to take. */
+  readonly public?: boolean;
+  /** Seats in all (within `game.turns.players`). */
+  readonly seats?: number;
+  /** Let the computer fill seats nobody took (default true, when the game has bots). */
+  readonly bots?: boolean;
+  /** How long a turn may wait before the others may let the computer play it (default none). */
+  readonly deadline?: TurnDeadline;
+  /** Start by itself once every seat is taken (the creator needn't come back). */
+  readonly autoStart?: boolean;
+}
+
+/** What `hub.turns` needs from its client. */
+export interface TurnsHost extends TurnGameHost {
+  readonly slug: string | null;
+  create(body: CreateTurnGame): ReturnType<TurnGameHost['get']>;
+  join(id: string): ReturnType<TurnGameHost['get']>;
+  joinByLink(key: string): ReturnType<TurnGameHost['get']>;
+  listOpen(game: string | null): Promise<OpenTurnGame[]>;
+  list(): Promise<SavedEntry[]>;
+}
+
+/** Read and strip `hub_turn_link`, once per page. */
+function linkOnPage(): string | null {
+  if (!isBrowserPage()) {
+    return null;
+  }
+  if (Reflect.has(window, PAGE_FLAG)) {
+    // eslint-disable-next-line no-restricted-syntax -- trust boundary: a window field another bundle may have set
+    const recorded: unknown = Reflect.get(window, PAGE_FLAG);
+    return typeof recorded === 'string' ? recorded : null;
+  }
+  let key: string | null = null;
+  try {
+    const url = new URL(location.href);
+    key = url.searchParams.get(TURN_LINK_PARAM);
+    if (key !== null) {
+      url.searchParams.delete(TURN_LINK_PARAM);
+      history.replaceState(history.state, '', `${url.pathname}${url.search}${url.hash}`);
+    }
+  } catch {
+    // A sandboxed page keeps the parameter; the answer is still recorded.
+  }
+  Reflect.set(window, PAGE_FLAG, key);
+  return key;
+}
+
+/** Whether `idOrKey` is a game id (`sg_…`) rather than a link key. */
+function isGameId(idOrKey: string): boolean {
+  return idOrKey.startsWith('sg_');
+}
+
+/** `hub.turns`. */
+export class HubTurns {
+  private readonly host: TurnsHost;
+  private isBuzzOn = true;
+  private readonly gameOptions: TurnGameOptions = { isBuzzOn: () => this.isBuzzOn };
+
+  constructor(host: TurnsHost) {
+    this.host = host;
+  }
+
+  /**
+   * This page's "your turn" buzz (a short vibration when the player becomes
+   * due in an open game, see `TurnGame.setYourTurnBuzz`): pass `false` if
+   * your game gives its own signal. On by default.
+   */
+  setYourTurnBuzz(isOn: boolean): void {
+    this.isBuzzOn = isOn;
+  }
+
+  /** The player's own "Buzz when it's my turn" switch on this device (the menu's Settings show it too). */
+  get playerYourTurnBuzz(): boolean {
+    return readYourTurnBuzz();
+  }
+
+  set playerYourTurnBuzz(isOn: boolean) {
+    saveYourTurnBuzz(isOn);
+  }
+
+  /** The invite link key this page was opened with (`?hub_turn_link=`), taken out of the address bar; `null` when none. Synchronous. */
+  get link(): string | null {
+    return linkOnPage();
+  }
+
+  /** Make a game in this page's game (its lobby): the player takes the first seat. */
+  async create<View = GamePayload, Move extends GamePayload = GamePayload, Event = GamePayload>(options: TurnCreateOptions = {}): Promise<TurnGame<View, Move, Event>> {
+    const slug = this.host.slug ?? '';
+    const body: CreateTurnGame = {
+      game: slug,
+      ...(options.mode === undefined ? {} : { mode: options.mode }),
+      ...(options.options === undefined ? {} : { options: toStoredJson(options.options) }),
+      ...(options.invite === undefined ? {} : { invite: [...options.invite] }),
+      ...(options.link === undefined ? {} : { link: options.link }),
+      ...(options.public === undefined ? {} : { public: options.public }),
+      ...(options.seats === undefined ? {} : { seats: options.seats }),
+      ...(options.bots === undefined ? {} : { bots: options.bots }),
+      ...(options.deadline === undefined ? {} : { deadline: options.deadline }),
+      ...(options.autoStart === undefined ? {} : { autoStart: options.autoStart }),
+    };
+    return new TurnGame<View, Move, Event>(this.host, await this.host.create(body), this.gameOptions);
+  }
+
+  /** Take a seat: by the game's id (an invite, an open seat) or by an invite link's key. */
+  async join<View = GamePayload, Move extends GamePayload = GamePayload, Event = GamePayload>(idOrLinkKey: string): Promise<TurnGame<View, Move, Event>> {
+    const joined = isGameId(idOrLinkKey) ? await this.host.join(idOrLinkKey) : await this.host.joinByLink(idOrLinkKey);
+    return new TurnGame<View, Move, Event>(this.host, joined, this.gameOptions);
+  }
+
+  /** Open a game the player sits in (from `hub.saved.opened`, the Continue list, an invite). */
+  async open<View = GamePayload, Move extends GamePayload = GamePayload, Event = GamePayload>(id: string): Promise<TurnGame<View, Move, Event>> {
+    return new TurnGame<View, Move, Event>(this.host, await this.host.get(id), this.gameOptions);
+  }
+
+  /** This game's online games the player sits in (the same rows as `hub.saved.list({ kinds: ['turns'] })`). */
+  list(): Promise<SavedEntry[]> {
+    return this.host.list();
+  }
+
+  /** Open-seat games of this game anyone may join (none across a block). */
+  openLobbies(): Promise<OpenTurnGame[]> {
+    return this.host.listOpen(this.host.slug);
+  }
+}