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

package/src/core/resume/local-resume.ts

@@ -0,0 +1,130 @@
+/**
+ * The device's copy of each game's resume slot (`hub:<slug>:resume`), in the
+ * browser storage every game on the site shares. It is written the moment a
+ * game saves, before the debounced send, so:
+ * - `hub.resume.load()` works offline and right after a reload;
+ * - the queued send reads the newest state from here, so the outbox entry
+ *   stays small (it carries the state itself only when this copy couldn't
+ *   be stored);
+ * - the home page's Resume card can show a run the hub hasn't heard of yet
+ *   (saved offline, or the tab closed before the send), and hide one cleared
+ *   offline.
+ *
+ * A record belongs to the player who saved it (`userId`), so another account
+ * on the same device never sees it. `isSynced` turns true once the hub has it.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import { isJson, isNullableString, isRecord, optionalNumber, optionalString, parseJsonText } from '../storage/json-guards';
+import type { KeyValueStore } from '../storage/key-value';
+
+/** A run as this device saved it. */
+export interface LocalRun {
+  readonly status: 'saved';
+  readonly userId: number | null;
+  /** When the game saved it, epoch ms. */
+  readonly at: number;
+  readonly label: string;
+  readonly fraction: number | null;
+  readonly title: string | null;
+  readonly version: number;
+  /** The game's title, for the Resume card before the hub knows the run. */
+  readonly gameTitle: string;
+  readonly state: Json;
+  readonly isSynced: boolean;
+}
+
+/** A run this device cleared (kept until the hub has the clear). */
+export interface LocalClear {
+  readonly status: 'cleared';
+  readonly userId: number | null;
+  readonly at: number;
+  readonly isSynced: boolean;
+}
+
+/** A device copy of one game's slot. */
+export type LocalResume = LocalRun | LocalClear;
+
+const KEY_PATTERN = /^hub:(.+):resume$/;
+
+function keyFor(slug: string): string {
+  return `hub:${slug}:resume`;
+}
+
+/** A stored record read back, or `null` when missing or malformed. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a record read back from localStorage
+function readRecord(stored: unknown): LocalResume | null {
+  if (!isRecord(stored)) {
+    return null;
+  }
+  const at = optionalNumber(stored.at);
+  const userId = stored.userId === null ? null : optionalNumber(stored.userId);
+  const isSynced = stored.isSynced === true;
+  if (at === undefined || userId === undefined) {
+    return null;
+  }
+  if (stored.status === 'cleared') {
+    return { status: 'cleared', userId, at, isSynced };
+  }
+  const label = optionalString(stored.label);
+  const gameTitle = optionalString(stored.gameTitle);
+  const version = optionalNumber(stored.version);
+  const fraction = stored.fraction === null ? null : optionalNumber(stored.fraction);
+  if (stored.status !== 'saved' || label === undefined || gameTitle === undefined || version === undefined
+    || fraction === undefined || !isNullableString(stored.title) || !isJson(stored.state)) {
+    return null;
+  }
+  return { status: 'saved', userId, at, label, fraction, title: stored.title, version, gameTitle, state: stored.state, isSynced };
+}
+
+/** The device copies of every game's slot. */
+export class LocalResumeStore {
+  private readonly store: KeyValueStore;
+
+  constructor(store: KeyValueStore) {
+    this.store = store;
+  }
+
+  /** `slug`'s copy, or `null`. */
+  read(slug: string): LocalResume | null {
+    const text = this.store.read(keyFor(slug));
+    return text === null ? null : readRecord(parseJsonText(text));
+  }
+
+  /** Store `slug`'s copy; answers whether it stuck (a full storage refuses a large state). */
+  write(slug: string, record: LocalResume): boolean {
+    const text = JSON.stringify(record);
+    this.store.write(keyFor(slug), text);
+    return this.store.read(keyFor(slug)) === text;
+  }
+
+  /** Forget `slug`'s copy. */
+  remove(slug: string): void {
+    this.store.remove(keyFor(slug));
+  }
+
+  /** The hub now has `slug`'s save or clear made at `at`: mark it synced (a clear is simply forgotten). */
+  markSynced(slug: string, at: number): void {
+    const record = this.read(slug);
+    if (record === null || record.at !== at) {
+      return;
+    }
+    if (record.status === 'cleared') {
+      this.remove(slug);
+    } else {
+      this.write(slug, { ...record, isSynced: true });
+    }
+  }
+
+  /** Every game's copy, by slug. */
+  all(): Map<string, LocalResume> {
+    const records = new Map<string, LocalResume>();
+    for (const key of this.store.keys()) {
+      const slug = KEY_PATTERN.exec(key)?.[1];
+      const record = slug === undefined ? null : this.read(slug);
+      if (slug !== undefined && record !== null) {
+        records.set(slug, record);
+      }
+    }
+    return records;
+  }
+}

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

@@ -0,0 +1,65 @@
+/**
+ * The player's saved runs: the hub's list merged with this device's copies,
+ * so a run saved offline (or just before the tab closed) shows at once and a
+ * run cleared offline disappears at once. Pure.
+ */
+import type { ResumeSummary } from '@diffenderfer-games/hub-contract';
+import type { LocalResume, LocalRun } from './local-resume';
+import type { ResumeEntry } from './resume-types';
+
+function fromHub(summary: ResumeSummary): ResumeEntry {
+  return {
+    slug: summary.game,
+    gameTitle: summary.gameTitle,
+    path: summary.path,
+    hasImage: summary.hasImage,
+    progress: summary.progress,
+    title: summary.title,
+    savedAt: summary.updatedAt,
+    isLocalOnly: false,
+  };
+}
+
+function fromDevice(slug: string, run: LocalRun, known: ResumeSummary | undefined): ResumeEntry {
+  return {
+    slug,
+    gameTitle: known?.gameTitle ?? run.gameTitle,
+    path: known?.path ?? `/${slug}`,
+    hasImage: known?.hasImage ?? false,
+    progress: { label: run.label, fraction: run.fraction },
+    title: run.title,
+    savedAt: run.at,
+    isLocalOnly: !run.isSynced,
+  };
+}
+
+/** One game's entry, from the hub's summary (if any) and the device copy (if the player's). */
+function mergeOne(slug: string, hub: ResumeSummary | undefined, copy: LocalResume | undefined, isHubKnown: boolean): ResumeEntry | null {
+  if (copy === undefined) {
+    return hub === undefined ? null : fromHub(hub);
+  }
+  if (copy.status === 'cleared') {
+    return hub !== undefined && hub.updatedAt > copy.at ? fromHub(hub) : null;
+  }
+  if (hub !== undefined && hub.updatedAt >= copy.at) {
+    return fromHub(hub);
+  }
+  // The hub hasn't got this run: show it while it waits to be sent, or when the hub can't be asked.
+  // A synced copy the hub no longer lists was cleared or pruned elsewhere.
+  return !copy.isSynced || !isHubKnown || hub !== undefined ? fromDevice(slug, copy, hub) : null;
+}
+
+/**
+ * The runs to show, newest first. `hub` is the hub's list, or `undefined`
+ * when it couldn't be reached; `copies` are the device's, by slug; only
+ * those saved by `userId` count.
+ */
+export function mergeResumeLists(hub: readonly ResumeSummary[] | undefined, copies: ReadonlyMap<string, LocalResume>, userId: number | null): ResumeEntry[] {
+  const hubBySlug = new Map((hub ?? []).map((summary) => [summary.game, summary] as const));
+  const mine = new Map([...copies].filter(([, copy]) => copy.userId === userId));
+  const slugs = new Set([...hubBySlug.keys(), ...mine.keys()]);
+  return [...slugs]
+    .map((slug) => mergeOne(slug, hubBySlug.get(slug), mine.get(slug), hub !== undefined))
+    .filter((entry): entry is ResumeEntry => entry !== null)
+    .sort((a, b) => b.savedAt - a.savedAt);
+}

package/src/core/resume/resume-request.ts

@@ -0,0 +1,52 @@
+/**
+ * Whether this page was opened from the home page's Resume card
+ * (`/<slug>/?hub_resume=1`). The first client copy on the page to look takes
+ * the parameter out of the address bar (so a reload or a shared link doesn't
+ * resume again) and records the answer on `window`, so every other copy on
+ * the page (a game's bundled client and the host's `/_hub/hub.js`) answers
+ * the same, however late it asks.
+ */
+import { isBrowserPage } from '../page';
+
+/** The query parameter (the contract's `RESUME_REQUEST_PARAM`; the browser client carries no contract code). */
+export const RESUME_REQUEST_PARAM = 'hub_resume';
+
+/** Where the answer is kept for the page. */
+const PAGE_FLAG = '__HUB_RESUME_REQUESTED__';
+
+/** Take `hub_resume` out of the address bar, keeping the rest of the URL and the history state. */
+function stripParam(url: URL): void {
+  url.searchParams.delete(RESUME_REQUEST_PARAM);
+  try {
+    history.replaceState(history.state, '', `${url.pathname}${url.search}${url.hash}`);
+  } catch {
+    // A sandboxed page that refuses replaceState keeps the parameter; the answer is still recorded.
+  }
+}
+
+/** Whether the address has `hub_resume`; it is taken out when it does. */
+function takeParam(): boolean {
+  try {
+    const url = new URL(location.href);
+    if (!url.searchParams.has(RESUME_REQUEST_PARAM)) {
+      return false;
+    }
+    stripParam(url);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** `true` when the page was opened to resume (synchronous, so a game can decide before it routes or draws). */
+export function isResumeRequested(): boolean {
+  if (!isBrowserPage()) {
+    return false;
+  }
+  if (Reflect.has(window, PAGE_FLAG)) {
+    return Reflect.get(window, PAGE_FLAG) === true;
+  }
+  const isRequested = takeParam();
+  Reflect.set(window, PAGE_FLAG, isRequested);
+  return isRequested;
+}

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

@@ -0,0 +1,64 @@
+/**
+ * `hub.resume`'s public types: what a game saves, what it loads back, and
+ * the player's list of saved runs the home page shows.
+ */
+import type { GamePayload } from '../game-data';
+
+/** How far along a run is. */
+export interface ResumeProgress {
+  /** A short line the game writes, such as "Level 12" or "Round 3 of 5" (up to 60 characters). */
+  readonly label: string;
+  /** 0 to 1, drawn as a progress bar; leave it out when the game can't say. */
+  readonly fraction?: number | null;
+}
+
+/** A run to save. `TState` is the game's own JSON-safe state type. */
+export interface ResumeSaveInput<TState extends GamePayload> {
+  /** Everything the game needs to pick the run up again (up to 512 KB as JSON). */
+  readonly state: TState;
+  readonly progress: ResumeProgress;
+  /** An optional name for the run ("Klondike, draw 3"), shown under the game's name. */
+  readonly title?: string | null;
+  /** The game's state version (default 0). Bump it when `state` changes shape; see `load({ version })`. */
+  readonly version?: number;
+}
+
+/** A saved run, read back. */
+export interface ResumeRun<TState> {
+  readonly state: TState;
+  readonly progress: { readonly label: string; readonly fraction: number | null };
+  readonly title: string | null;
+  readonly version: number;
+  /** When the game saved it, epoch ms. */
+  readonly savedAt: number;
+}
+
+/** Options for reading the run back. */
+export interface ResumeLoadOptions {
+  /**
+   * The state version this code reads. A run saved with an older version is
+   * dropped (cleared) and reads as `null`; a newer one (from a newer copy of
+   * the game in another tab) reads as `null` but is kept.
+   */
+  readonly version?: number;
+}
+
+/** One saved run in the player's list (the home page's Resume card). */
+export interface ResumeEntry {
+  /** The game's slug. */
+  readonly slug: string;
+  readonly gameTitle: string;
+  /** The game's URL path, like `/solitaire`. */
+  readonly path: string;
+  /** The game has a tile image (`/_tiles/<slug>`). */
+  readonly hasImage: boolean;
+  readonly progress: { readonly label: string; readonly fraction: number | null };
+  readonly title: string | null;
+  /** When it was saved, epoch ms. */
+  readonly savedAt: number;
+  /** Saved on this device and not yet sent to the hub (offline, or the tab closed first). */
+  readonly isLocalOnly: boolean;
+}
+
+/** Why a save was ignored: the page is in a race or an online room. (`'daily'` is no longer returned: a save during a daily goes to the day.) */
+export type ResumeBlocker = 'race' | 'daily' | 'room' | 'turns';

package/src/core/saved/daily-saves.ts

@@ -0,0 +1,196 @@
+/**
+ * A game's daily challenges in progress on this device: what `hub.daily`
+ * saves and discards, kept in the device copy at once (`LocalDailyStore`)
+ * and sent through the `hub.saved` outbox kind after a short quiet spell
+ * (at once when the page hides), so a day survives a reload, offline play
+ * and a tab closed mid-move. A day started while the hub can't be reached
+ * gets a device-only id; its first send starts it on the hub.
+ */
+import type { DailyChallenge, DailySaveInput, DailyStartResponse } from '../../daily/types';
+import { HubError } from '../errors';
+import { toStoredJson } from '../game-data';
+import type { SavedPayload } from '../offline/hub-kinds';
+import { isBrowserPage } from '../page';
+import { dailySeed } from './daily-seed';
+import type { LocalDaily, LocalDailyStore } from './local-saved';
+import { localDailyId } from './saved-list';
+
+/** How long saves must be quiet before the latest is sent, ms (the same as `hub.resume`). */
+export const DAILY_SAVE_DEBOUNCE_MS = 3000;
+
+/** Largest state, bytes of JSON (the contract's `SAVED_MAX_STATE_BYTES`). */
+const MAX_STATE_BYTES = 512 * 1024;
+
+/** Longest label or title kept. */
+const TEXT_MAX = 60;
+
+/** The label of a day started and not saved yet. */
+const STARTED_LABEL = 'Started';
+
+/** What the daily saves need from their client. */
+export interface DailySavesHost {
+  readonly slug: string;
+  readonly local: LocalDailyStore;
+  currentUserId(): number | null;
+  gameTitle(): string;
+  /** Queue (or send at once) a `hub.saved` op. */
+  send(payload: SavedPayload): Promise<void>;
+}
+
+/** A label or title trimmed and clipped, or `null` when blank. */
+function shortText(text: string | null | undefined): string | null {
+  const trimmed = (text ?? '').trim();
+  return trimmed === '' ? null : trimmed.slice(0, TEXT_MAX);
+}
+
+/** A game's daily saves. */
+export class DailySaves {
+  private readonly host: DailySavesHost;
+  private readonly timers = new Map<string, ReturnType<typeof setTimeout>>();
+  private readonly waiting = new Map<string, SavedPayload>();
+  private isListening = false;
+
+  constructor(host: DailySavesHost) {
+    this.host = host;
+  }
+
+  /**
+   * The answer a device-only start gives while the hub can't be reached:
+   * the day's copy here (its saved state) or a fresh one. No token: the
+   * completion fetches one when the hub is back.
+   */
+  startLocally(day: string): DailyStartResponse {
+    const userId = this.host.currentUserId();
+    const existing = this.host.local.read(this.host.slug, day);
+    const copy: LocalDaily = existing !== null && existing.status === 'active' && existing.userId === userId ? existing : {
+      id: localDailyId(this.host.slug, day), game: this.host.slug, day, seed: dailySeed(this.host.slug, day), status: 'active', userId, at: Date.now(),
+      label: STARTED_LABEL, fraction: null, title: null, version: 0, gameTitle: this.host.gameTitle(), state: null, isSynced: false,
+    };
+    if (copy !== existing) {
+      this.host.local.write(copy);
+    }
+    return {
+      token: '', day, seed: copy.seed, expiresAt: 0, alreadyCompleted: false, completedAt: null, meta: null,
+      instanceId: copy.id, saved: copy.state, savedVersion: copy.version, resumed: existing !== null,
+    };
+  }
+
+  /** The hub started (or resumed) a day: keep a copy that knows its id, unless the device has a newer save. */
+  remember(started: DailyStartResponse): DailyStartResponse {
+    if (started.instanceId === null) {
+      return started;
+    }
+    const existing = this.host.local.read(this.host.slug, started.day);
+    if (existing !== null && existing.status === 'active' && existing.userId === this.host.currentUserId() && !existing.isSynced) {
+      // This device saved after its last send: play on from that.
+      this.host.local.write({ ...existing, id: started.instanceId });
+      return { ...started, saved: existing.state, savedVersion: existing.version };
+    }
+    return started;
+  }
+
+  /** Save the active day's state: on the device now, to the hub soon. */
+  save(challenge: DailyChallenge, input: DailySaveInput): boolean {
+    const label = shortText(input.progress.label);
+    if (label === null) {
+      throw new HubError('hub.daily.save: progress.label is required.', 400);
+    }
+    const state = toStoredJson(input.state);
+    if (new TextEncoder().encode(JSON.stringify(state)).length > MAX_STATE_BYTES) {
+      throw new HubError(`hub.daily.save: state exceeds ${String(MAX_STATE_BYTES)} bytes.`, 413);
+    }
+    if (challenge.instanceId === null) {
+      return false;
+    }
+    const fraction = typeof input.progress.fraction === 'number' && Number.isFinite(input.progress.fraction) ? Math.min(1, Math.max(0, input.progress.fraction)) : null;
+    const copy: LocalDaily = {
+      id: challenge.instanceId, game: this.host.slug, day: challenge.day, seed: challenge.seed, status: 'active', userId: this.host.currentUserId(),
+      at: Date.now(), label, fraction, title: shortText(input.title), version: Math.max(0, Math.floor(input.version ?? 0)),
+      gameTitle: this.host.gameTitle(), state, isSynced: false,
+    };
+    if (!this.host.local.write(copy)) {
+      return false;
+    }
+    this.schedule({ action: 'save', game: copy.game, day: copy.day, at: copy.at });
+    return true;
+  }
+
+  /** Give the day up: the copy says so at once, the hub hears it now (or when back online). */
+  async discard(challenge: DailyChallenge): Promise<void> {
+    this.dropWaiting(challenge.day);
+    const at = Date.now();
+    const base = this.host.local.read(this.host.slug, challenge.day) ?? this.blankCopy(challenge);
+    this.host.local.write({ ...base, id: challenge.instanceId ?? base.id, status: 'discarded', at, isSynced: false });
+    await this.host.send({ action: 'discard', game: this.host.slug, day: challenge.day, at });
+  }
+
+  /** The day was won: no save is waiting for it any more, and the lists hide it until the hub confirms. */
+  finished(day: string): void {
+    this.dropWaiting(day);
+    const existing = this.host.local.read(this.host.slug, day);
+    if (existing !== null) {
+      this.host.local.write({ ...existing, status: 'finished', at: Date.now(), isSynced: false });
+    }
+  }
+
+  /** The hub recorded the day: forget the copy. */
+  completed(day: string): void {
+    this.host.local.remove(this.host.slug, day);
+  }
+
+  /** Send every waiting save now. */
+  async flush(): Promise<void> {
+    const payloads = [...this.waiting.values()];
+    for (const timer of this.timers.values()) {
+      clearTimeout(timer);
+    }
+    this.timers.clear();
+    this.waiting.clear();
+    await Promise.all(payloads.map((payload) => this.host.send(payload)));
+  }
+
+  private blankCopy(challenge: DailyChallenge): LocalDaily {
+    return {
+      id: challenge.instanceId ?? localDailyId(this.host.slug, challenge.day), game: this.host.slug, day: challenge.day, seed: challenge.seed,
+      status: 'active', userId: this.host.currentUserId(), at: Date.now(), label: STARTED_LABEL, fraction: null, title: null, version: 0,
+      gameTitle: this.host.gameTitle(), state: null, isSynced: false,
+    };
+  }
+
+  private dropWaiting(day: string): void {
+    const timer = this.timers.get(day);
+    if (timer !== undefined) {
+      clearTimeout(timer);
+    }
+    this.timers.delete(day);
+    this.waiting.delete(day);
+  }
+
+  private schedule(payload: SavedPayload): void {
+    this.dropWaiting(payload.day);
+    this.waiting.set(payload.day, payload);
+    this.timers.set(payload.day, setTimeout(() => {
+      this.timers.delete(payload.day);
+      this.waiting.delete(payload.day);
+      void this.host.send(payload).catch(() => undefined);
+    }, DAILY_SAVE_DEBOUNCE_MS));
+    this.listenToPage();
+  }
+
+  /** Send waiting saves as soon as the page is hidden or closed. */
+  private listenToPage(): void {
+    if (this.isListening || !isBrowserPage()) {
+      return;
+    }
+    this.isListening = true;
+    const flushNow = (): void => { void this.flush().catch(() => undefined); };
+    window.addEventListener('pagehide', flushNow);
+    if (typeof document !== 'undefined') {
+      document.addEventListener('visibilitychange', () => {
+        if (document.visibilityState === 'hidden') {
+          flushNow();
+        }
+      });
+    }
+  }
+}

package/src/core/saved/daily-seed.ts

@@ -0,0 +1,16 @@
+/**
+ * The deterministic seed of a (game, day), the same FNV-1a as the
+ * contract's `seedForDay` (the browser client carries no contract code; a
+ * test keeps the two in step). Used for a day started offline.
+ */
+
+/** The uint32 seed for `game` on `day`. */
+export function dailySeed(game: string, day: string): number {
+  let hash = 2166136261 >>> 0;
+  const seedInput = `${game}#${day}`;
+  for (let i = 0; i < seedInput.length; i++) {
+    hash ^= seedInput.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}