@diffenderfer-games/hub 2.0.0-next.5 → 2.0.0-next.7

package/src/core/saved/saved-list.ts

@@ -0,0 +1,129 @@
+/**
+ * A player's games in progress: the hub's list merged with this device's
+ * copies of runs (`hub.resume`) and daily challenges (`hub.daily.save`), so
+ * one saved offline (or just before the tab closed) shows at once, and one
+ * cleared or discarded offline disappears at once. Pure.
+ */
+import { compareSaved } from './saved-order';
+import type { LocalResume, LocalRun } from '../resume/local-resume';
+import type { LocalDaily } from './local-saved';
+import type { SavedEntry } from './saved-types';
+
+/** The id a run saved only on this device goes by until the hub has it. */
+export function localRunId(slug: string): string {
+  return `local:${slug}:run`;
+}
+
+/** The id a daily started only on this device goes by until the hub has it. */
+export function localDailyId(slug: string, day: string): string {
+  return `local:${slug}:${day}`;
+}
+
+/** A device run as an entry, with the game's catalog fields from the hub's entry when it has one. */
+function runEntry(slug: string, run: LocalRun, known: SavedEntry | undefined): SavedEntry {
+  return {
+    id: known?.id ?? localRunId(slug),
+    game: slug,
+    gameTitle: known?.gameTitle ?? run.gameTitle,
+    path: known?.path ?? `/${slug}`,
+    hasImage: known?.hasImage ?? false,
+    kind: 'run',
+    status: 'active',
+    title: run.title,
+    progress: { label: run.label, fraction: run.fraction },
+    version: run.version,
+    createdAt: known?.createdAt ?? run.at,
+    updatedAt: run.at,
+    finishedAt: null,
+    isLocalOnly: !run.isSynced,
+  };
+}
+
+/** One game's run: the hub's, the device's newer copy, or none (cleared on the device). */
+function mergeRun(slug: string, hub: SavedEntry | undefined, copy: LocalResume | undefined, isHubKnown: boolean): SavedEntry | null {
+  if (copy === undefined) {
+    return hub ?? null;
+  }
+  if (copy.status === 'cleared') {
+    return hub !== undefined && hub.updatedAt > copy.at ? hub : null;
+  }
+  if (hub !== undefined && hub.updatedAt >= copy.at) {
+    return hub;
+  }
+  // The hub hasn't got this run: show it while it waits to be sent, or when the hub can't be asked.
+  return !copy.isSynced || !isHubKnown || hub !== undefined ? runEntry(slug, copy, hub) : null;
+}
+
+/** A device daily as an entry. */
+function dailyEntry(daily: LocalDaily, known: SavedEntry | undefined): SavedEntry {
+  return {
+    id: daily.id,
+    game: daily.game,
+    gameTitle: known?.gameTitle ?? daily.gameTitle,
+    path: known?.path ?? `/${daily.game}`,
+    hasImage: known?.hasImage ?? false,
+    kind: 'daily',
+    status: 'active',
+    title: daily.title,
+    progress: { label: daily.label, fraction: daily.fraction },
+    version: daily.version,
+    createdAt: known?.createdAt ?? daily.at,
+    updatedAt: daily.at,
+    finishedAt: null,
+    daily: { day: daily.day, seed: daily.seed },
+    isLocalOnly: !daily.isSynced,
+  };
+}
+
+/** What the device holds, for one player. */
+export interface DeviceCopies {
+  /** Run copies by slug (`hub.resume`). */
+  readonly runs: ReadonlyMap<string, LocalResume>;
+  /** Daily copies (`hub.daily`), any game. */
+  readonly dailies: readonly LocalDaily[];
+}
+
+/** One daily: the hub's entry, the device's newer copy, or none (discarded or finished on the device). */
+function mergeDaily(hub: SavedEntry | undefined, copy: LocalDaily | undefined, isHubKnown: boolean): SavedEntry | null {
+  if (copy === undefined) {
+    return hub ?? null;
+  }
+  if (copy.status !== 'active') {
+    return hub !== undefined && hub.updatedAt > copy.at ? hub : null;
+  }
+  if (hub !== undefined && hub.updatedAt >= copy.at) {
+    return hub;
+  }
+  return !copy.isSynced || !isHubKnown || hub !== undefined ? dailyEntry(copy, hub) : null;
+}
+
+/** The key that pairs a hub daily with a device copy: its game and day. */
+const dailyKey = (game: string, day: string): string => `${game}#${day}`;
+
+/**
+ * The entries to show, in the shared list order. `hub` is the hub's list,
+ * or `undefined` when it couldn't be reached; `copies` are the device's
+ * (already only the player's); `game` limits the device copies to one game.
+ */
+export function mergeSavedLists(hub: readonly SavedEntry[] | undefined, copies: DeviceCopies, game: string | null): SavedEntry[] {
+  const isHubKnown = hub !== undefined;
+  const fromHub = hub ?? [];
+  const runs = new Map(fromHub.filter((entry) => entry.kind === 'run').map((entry) => [entry.game, entry] as const));
+  const dailies = new Map(fromHub.flatMap((entry) => (entry.kind === 'daily' && entry.daily !== undefined ? [[dailyKey(entry.game, entry.daily.day), entry] as const] : [])));
+  const runCopies = new Map([...copies.runs].filter(([slug]) => game === null || slug === game));
+  const dailyCopies = new Map(copies.dailies.filter((copy) => game === null || copy.game === game).map((copy) => [dailyKey(copy.game, copy.day), copy] as const));
+  const merged: SavedEntry[] = fromHub.filter((entry) => entry.kind === 'turns');
+  for (const slug of new Set([...runs.keys(), ...runCopies.keys()])) {
+    const entry = mergeRun(slug, runs.get(slug), runCopies.get(slug), isHubKnown);
+    if (entry !== null) {
+      merged.push(entry);
+    }
+  }
+  for (const key of new Set([...dailies.keys(), ...dailyCopies.keys()])) {
+    const entry = mergeDaily(dailies.get(key), dailyCopies.get(key), isHubKnown);
+    if (entry !== null) {
+      merged.push(entry);
+    }
+  }
+  return merged.sort(compareSaved);
+}

package/src/core/saved/saved-open.ts

@@ -0,0 +1,104 @@
+/**
+ * Opening one saved game in its game page: the address the hub's lists use
+ * (`/<slug>/?hub_open=<id>&hub_kind=<kind>`, plus `hub_resume=1` for a run
+ * and `daily=<day>` for a daily, so games that only know `hub.resume` or
+ * `hub.daily` restore it too), and reading it back on arrival. The first
+ * client copy on the page takes the parameters out of the address bar (a
+ * reload or a shared link doesn't open it again) and records the answer on
+ * `window`, so every copy (a game's bundled client, the host's
+ * `/_hub/hub.js`) answers the same.
+ *
+ * Picking a game of THIS page from the hub menu fires
+ * {@link SAVED_OPEN_EVENT} on `window`: a client with an `onOpen` handler
+ * cancels it and switches in place; otherwise the menu loads the address.
+ */
+import type { SavedGame, SavedKind } from '@diffenderfer-games/hub-contract';
+import { readField } from '../../realtime/cross-bundle';
+import { isBrowserPage } from '../page';
+import { RESUME_REQUEST_PARAM } from '../resume/resume-request';
+
+/** The instance id parameter (the contract's `SAVED_OPEN_PARAM`). */
+export const SAVED_OPEN_PARAM = 'hub_open';
+
+/** The instance kind parameter (the contract's `SAVED_KIND_PARAM`). */
+export const SAVED_KIND_PARAM = 'hub_kind';
+
+/** The window event the hub menu fires to open an instance of this page's game (cancelable). */
+export const SAVED_OPEN_EVENT = 'hub:saved-open';
+
+/** The window event the social runtime fires for each `ev:saved` (detail: the `SavedGame`). */
+export const SAVED_CHANGE_EVENT = 'hub:saved';
+
+/** Where the answer is kept for the page. */
+const PAGE_FLAG = '__HUB_SAVED_OPENED__';
+
+/** The instance a page was opened for. */
+export interface SavedOpened {
+  readonly id: string;
+  readonly kind: SavedKind;
+}
+
+const KINDS: readonly SavedKind[] = ['daily', 'run', 'turns'];
+
+/** `text` as a kind, or `null`. */
+function asKind(text: string | null): SavedKind | null {
+  return KINDS.find((kind) => kind === text) ?? null;
+}
+
+/** The address that opens `game` in its page. */
+export function savedGameUrl(game: Pick<SavedGame, 'id' | 'kind' | 'path' | 'daily'>): string {
+  const params = new URLSearchParams();
+  if (game.kind === 'run') {
+    params.set(RESUME_REQUEST_PARAM, '1');
+  }
+  if (game.kind === 'daily' && game.daily !== undefined) {
+    params.set('daily', game.daily.day);
+  }
+  params.set(SAVED_OPEN_PARAM, game.id);
+  params.set(SAVED_KIND_PARAM, game.kind);
+  return `${game.path.replace(/\/+$/, '')}/?${params.toString()}`;
+}
+
+/** Read and strip `hub_open` / `hub_kind`; `null` when absent or malformed. */
+function takeParams(): SavedOpened | null {
+  try {
+    const url = new URL(location.href);
+    const id = url.searchParams.get(SAVED_OPEN_PARAM);
+    const kind = asKind(url.searchParams.get(SAVED_KIND_PARAM));
+    if (!url.searchParams.has(SAVED_OPEN_PARAM) && !url.searchParams.has(SAVED_KIND_PARAM)) {
+      return null;
+    }
+    url.searchParams.delete(SAVED_OPEN_PARAM);
+    url.searchParams.delete(SAVED_KIND_PARAM);
+    try {
+      history.replaceState(history.state, '', `${url.pathname}${url.search}${url.hash}`);
+    } catch {
+      // A sandboxed page that refuses replaceState keeps them; the answer is still recorded.
+    }
+    return id === null || id === '' || kind === null ? null : { id, kind };
+  } catch {
+    return null;
+  }
+}
+
+/** A recorded answer read back. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a window global another bundle may have set
+function readRecorded(value: unknown): SavedOpened | null {
+  const id = readField(value, 'id');
+  const kind = readField(value, 'kind');
+  const savedKind = asKind(typeof kind === 'string' ? kind : null);
+  return typeof id === 'string' && savedKind !== null ? { id, kind: savedKind } : null;
+}
+
+/** The instance this page was opened for, or `null` (synchronous, so a game can route before it draws). */
+export function savedOpenedOnPage(): SavedOpened | null {
+  if (!isBrowserPage()) {
+    return null;
+  }
+  if (Reflect.has(window, PAGE_FLAG)) {
+    return readRecorded(Reflect.get(window, PAGE_FLAG));
+  }
+  const opened = takeParams();
+  Reflect.set(window, PAGE_FLAG, opened);
+  return opened;
+}

package/src/core/saved/saved-order.ts

@@ -0,0 +1,49 @@
+/**
+ * The order and badge counts of saved games, the same rules as the
+ * contract's `compareSaved` and `countSaved` (the hub's `GET /saved` and
+ * every list agree; the browser client carries no contract code, so this
+ * copy is kept in step by a test). Pure.
+ */
+import type { SavedCounts } from '@diffenderfer-games/hub-contract';
+import type { SavedEntry } from './saved-types';
+
+/** The fields the order and counts read. */
+type Listed = Pick<SavedEntry, 'id' | 'kind' | 'updatedAt' | 'turns'>;
+
+/** The player must move in this online game now. */
+export function isYourTurn(entry: Pick<SavedEntry, 'turns'>): boolean {
+  return entry.turns?.isMyTurn === true && entry.turns.phase === 'playing';
+}
+
+/** Online games waiting on the player first (oldest turn first), then the newest. */
+export function compareSaved(a: Listed, b: Listed): number {
+  const isATurn = isYourTurn(a);
+  const isBTurn = isYourTurn(b);
+  if (isATurn !== isBTurn) {
+    return isATurn ? -1 : 1;
+  }
+  if (isATurn && a.turns !== undefined && b.turns !== undefined && a.turns.turnStartedAt !== b.turns.turnStartedAt) {
+    return a.turns.turnStartedAt - b.turns.turnStartedAt;
+  }
+  if (a.updatedAt !== b.updatedAt) {
+    return b.updatedAt - a.updatedAt;
+  }
+  return a.id < b.id ? 1 : -1;
+}
+
+/** The badge counts of a list of games in progress. */
+export function countSaved(entries: readonly Listed[]): SavedCounts {
+  const counts = { yourTurn: 0, dailies: 0, runs: 0, waiting: 0, total: entries.length };
+  for (const entry of entries) {
+    if (entry.kind === 'daily') {
+      counts.dailies += 1;
+    } else if (entry.kind === 'run') {
+      counts.runs += 1;
+    } else if (isYourTurn(entry)) {
+      counts.yourTurn += 1;
+    } else {
+      counts.waiting += 1;
+    }
+  }
+  return counts;
+}

package/src/core/saved/saved-types.ts

@@ -0,0 +1,24 @@
+/**
+ * `hub.saved`'s public types: one game in progress as the lists show it,
+ * the badge counts, and what `opened` says about the page.
+ */
+import type { SavedCounts, SavedDaily, SavedGame, SavedKind, SavedProgress, SavedStatus, TurnSummary } from '@diffenderfer-games/hub-contract';
+
+export type { SavedCounts, SavedDaily, SavedKind, SavedProgress, SavedStatus, TurnSummary };
+export type { SavedOpened } from './saved-open';
+
+/**
+ * One game in progress: a daily challenge, a single-player run or an online
+ * game. Its `id` is the hub's, or `local:…` for one saved only on this
+ * device so far.
+ */
+export interface SavedEntry extends Omit<SavedGame, 'id'> {
+  readonly id: string;
+  /** Saved on this device and not yet sent to the hub (offline, or the tab closed first). */
+  readonly isLocalOnly?: boolean;
+}
+
+/** Which kinds to list. */
+export interface SavedListOptions {
+  readonly kinds?: readonly SavedKind[];
+}

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

@@ -0,0 +1,140 @@
+/**
+ * `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 } from './turn-game';
+
+/** 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;
+
+  constructor(host: TurnsHost) {
+    this.host = host;
+  }
+
+  /** 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));
+  }
+
+  /** 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);
+  }
+
+  /** 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 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);
+  }
+}