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

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

@@ -0,0 +1,221 @@
+/**
+ * `hub.saved`: the player's games in progress, of every kind (a daily
+ * challenge, a single-player run, an online game), for a game's own
+ * "Continue" list and for the hub's "Your games" lists.
+ *
+ * - `list()` is this game's, `listAll()` every game's (the home page, the
+ *   menu); both merge in what this device saved and the hub hasn't heard
+ *   of yet, and work offline from the device copies.
+ * - `opened` says which instance the page was opened for (synchronous).
+ * - `onOpen(handler)` lets a running game switch to an instance picked from
+ *   the hub menu without a reload; `open(id)` is that same path.
+ * - `on('change')` fires when this game's list changes (a save here or on
+ *   another device, a finish, a discard, a move in an online game).
+ */
+import type { SavedCounts } from '@diffenderfer-games/hub-contract';
+import { isBrowserPage } from '../page';
+import { readField } from '../../realtime/cross-bundle';
+import { mergeSavedLists, type DeviceCopies } from './saved-list';
+import { countSaved } from './saved-order';
+import { SAVED_CHANGE_EVENT, SAVED_OPEN_EVENT, savedGameUrl, savedOpenedOnPage, type SavedOpened } from './saved-open';
+import type { SavedEntry, SavedListOptions } from './saved-types';
+
+/** How long changes must be quiet before `on('change')` listeners hear the new list, ms. */
+export const SAVED_CHANGE_QUIET_MS = 300;
+
+/** What `hub.saved` needs from its client. */
+export interface SavedHost {
+  /** This game's slug; `null` on the home page. */
+  readonly slug: string | null;
+  /** The hub's list (one game, or all), or `undefined` when it can't be reached. */
+  fetchList(game: string | null): Promise<readonly SavedEntry[] | undefined>;
+  /** What this device holds for the signed-in player. */
+  deviceCopies(): DeviceCopies;
+  /** Discard a daily or run (works offline where it can). */
+  discard(entry: SavedEntry): Promise<void>;
+  /** Go to a URL (`location.assign`). */
+  navigate(url: string): void;
+}
+
+/** A change listener: this game's games in progress. */
+export type SavedChangeListener = (games: SavedEntry[]) => void;
+
+/** An `onOpen` handler: switch to this instance without a reload. */
+export type SavedOpenHandler = (instance: SavedEntry) => void | Promise<void>;
+
+/** The detail of {@link SAVED_OPEN_EVENT}. */
+export interface SavedOpenDetail {
+  readonly entry: SavedEntry;
+}
+
+/** Whether an entry is of one of `kinds` (all when absent). */
+function isOfKinds(entry: SavedEntry, options: SavedListOptions): boolean {
+  return options.kinds === undefined || options.kinds.includes(entry.kind);
+}
+
+/** `hub.saved`. */
+export class HubSaved {
+  private readonly host: SavedHost;
+  /** Each handler with the kinds it takes (every kind when `undefined`). */
+  private readonly openHandlers = new Map<SavedOpenHandler, SavedListOptions>();
+  private readonly changeListeners = new Set<SavedChangeListener>();
+  private isListeningForOpen = false;
+  private isListeningForChange = false;
+  private changeTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(host: SavedHost) {
+    this.host = host;
+  }
+
+  /**
+   * The instance this page was opened for (`?hub_open=<id>&hub_kind=<kind>`,
+   * taken out of the address bar), or `null`. Synchronous: read it before
+   * routing or drawing a title screen.
+   */
+  get opened(): SavedOpened | null {
+    return savedOpenedOnPage();
+  }
+
+  /** This game's games in progress: online games waiting on the player first, then the newest. Works offline. */
+  async list(options: SavedListOptions = {}): Promise<SavedEntry[]> {
+    const slug = this.host.slug;
+    if (slug === null) {
+      return [];
+    }
+    const hub = await this.host.fetchList(slug);
+    return mergeSavedLists(hub, this.host.deviceCopies(), slug).filter((entry) => isOfKinds(entry, options));
+  }
+
+  /** Every game's games in progress (the home page and the menu). Online, plus this device's copies. */
+  async listAll(): Promise<SavedEntry[]> {
+    return mergeSavedLists(await this.host.fetchList(null), this.host.deviceCopies(), null);
+  }
+
+  /** The badge counts across every game. */
+  async counts(): Promise<SavedCounts> {
+    return countSaved(await this.listAll());
+  }
+
+  /**
+   * Switch to an instance of THIS game when the player picks it from the
+   * hub menu, without a reload. Without a handler the page reloads with
+   * `?hub_open=<id>`. With `{ kinds }` the handler takes only those kinds;
+   * the others still reload the page (with `?hub_resume=1` or `?daily=` for
+   * a saved run or a daily). Returns a function that removes the handler.
+   */
+  onOpen(handler: SavedOpenHandler, options: SavedListOptions = {}): () => void {
+    this.openHandlers.set(handler, options);
+    this.listenForOpen();
+    return () => {
+      this.openHandlers.delete(handler);
+    };
+  }
+
+  /** Open an instance: in this game through `onOpen` (or a reload), in another game by going there. */
+  async open(id: string): Promise<void> {
+    const entry = (await this.listAll()).find((candidate) => candidate.id === id);
+    if (entry === undefined) {
+      return;
+    }
+    this.openEntry(entry);
+  }
+
+  /** Open an entry already in hand (the hub's lists). */
+  openEntry(entry: SavedEntry): void {
+    if (entry.game === this.host.slug && isBrowserPage()) {
+      const event = new CustomEvent<SavedOpenDetail>(SAVED_OPEN_EVENT, { detail: { entry }, cancelable: true });
+      if (!window.dispatchEvent(event)) {
+        return;
+      }
+    }
+    this.host.navigate(savedGameUrl(entry));
+  }
+
+  /**
+   * Discard a daily challenge or a saved run (the caller asks first; the
+   * hub's own lists ask for themselves). Online games are left with
+   * `hub.turns`, never discarded.
+   */
+  async discard(id: string): Promise<void> {
+    const entry = (await this.listAll()).find((candidate) => candidate.id === id);
+    if (entry === undefined || entry.kind === 'turns') {
+      return;
+    }
+    await this.host.discard(entry);
+    this.changed();
+  }
+
+  /** Hear when this game's list changes; returns a function that stops listening. */
+  on(_eventName: 'change', listener: SavedChangeListener): () => void {
+    this.changeListeners.add(listener);
+    this.listenForChange();
+    return () => {
+      this.changeListeners.delete(listener);
+    };
+  }
+
+  /** Something of this game's changed (a save here, an event from the hub): tell the listeners, once per quiet spell. */
+  changed(): void {
+    if (this.changeListeners.size === 0 || this.changeTimer !== null) {
+      return;
+    }
+    this.changeTimer = setTimeout(() => {
+      this.changeTimer = null;
+      void this.list().then((games) => {
+        for (const listener of this.changeListeners) {
+          listener(games);
+        }
+      }, () => undefined);
+    }, SAVED_CHANGE_QUIET_MS);
+  }
+
+  private listenForOpen(): void {
+    if (this.isListeningForOpen || !isBrowserPage()) {
+      return;
+    }
+    this.isListeningForOpen = true;
+    window.addEventListener(SAVED_OPEN_EVENT, (event) => {
+      const entry = event instanceof CustomEvent ? readEntry(event.detail) : null;
+      const handlers = entry === null ? [] : [...this.openHandlers].filter(([, options]) => isOfKinds(entry, options)).map(([handler]) => handler);
+      if (entry === null || entry.game !== this.host.slug || handlers.length === 0 || event.defaultPrevented) {
+        return;
+      }
+      event.preventDefault();
+      for (const handler of handlers) {
+        void Promise.resolve(handler(entry)).catch(() => undefined);
+      }
+    });
+  }
+
+  private listenForChange(): void {
+    if (this.isListeningForChange || !isBrowserPage()) {
+      return;
+    }
+    this.isListeningForChange = true;
+    window.addEventListener(SAVED_CHANGE_EVENT, (event) => {
+      const game = event instanceof CustomEvent ? readField(event.detail, 'game') : undefined;
+      if (game === this.host.slug) {
+        this.changed();
+      }
+    });
+  }
+}
+
+/** The entry in an open event's detail (it may come from another bundle), or `null`. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: an event detail another bundle may have made
+function readEntry(detail: unknown): SavedEntry | null {
+  const entry = readField(detail, 'entry');
+  const id = readField(entry, 'id');
+  const game = readField(entry, 'game');
+  const kind = readField(entry, 'kind');
+  if (typeof id !== 'string' || typeof game !== 'string' || (kind !== 'daily' && kind !== 'run' && kind !== 'turns')) {
+    return null;
+  }
+  return isSavedEntry(entry) ? entry : null;
+}
+
+/** Shape check for an entry made by another copy of this client. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: see readEntry
+function isSavedEntry(candidate: unknown): candidate is SavedEntry {
+  return typeof readField(candidate, 'path') === 'string' && typeof readField(candidate, 'progress') === 'object';
+}

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

@@ -0,0 +1,122 @@
+/**
+ * The device's copies of daily challenges in progress
+ * (`hub:<slug>:daily:<day>`), in the browser storage every game on the site
+ * shares, written the moment a game saves a daily (before the debounced
+ * send). So a daily resumes offline and right after a reload, the queued
+ * send stays small (it reads the newest state here), and the lists show a
+ * daily the hub hasn't heard of yet, or hide one finished or discarded
+ * offline. A copy belongs to the player who made it (`userId`); `id` is the
+ * hub's instance id, or `local:<slug>:<day>` for a day started offline.
+ */
+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 daily challenge as this device last saw it. */
+export interface LocalDaily {
+  readonly id: string;
+  readonly game: string;
+  readonly day: string;
+  readonly seed: number;
+  /** `active` in progress; `finished` (won) or `discarded`, kept until the hub has it. */
+  readonly status: 'active' | 'finished' | 'discarded';
+  readonly userId: number | null;
+  /** When it last changed here, epoch ms. */
+  readonly at: number;
+  readonly label: string;
+  readonly fraction: number | null;
+  readonly title: string | null;
+  readonly version: number;
+  readonly gameTitle: string;
+  /** The state the game last saved, `null` before its first save. */
+  readonly state: Json;
+  readonly isSynced: boolean;
+}
+
+const KEY_PATTERN = /^hub:(.+):daily:(\d{4}-\d{2}-\d{2})$/;
+const STATUSES: readonly LocalDaily['status'][] = ['active', 'finished', 'discarded'];
+
+function keyFor(game: string, day: string): string {
+  return `hub:${game}:daily:${day}`;
+}
+
+/** A stored copy read back, or `null` when missing or malformed. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a record read back from localStorage
+function readCopy(stored: unknown): LocalDaily | null {
+  if (!isRecord(stored)) {
+    return null;
+  }
+  const id = optionalString(stored.id);
+  const game = optionalString(stored.game);
+  const day = optionalString(stored.day);
+  const seed = optionalNumber(stored.seed);
+  const at = optionalNumber(stored.at);
+  const label = optionalString(stored.label);
+  const version = optionalNumber(stored.version);
+  const gameTitle = optionalString(stored.gameTitle);
+  const userId = stored.userId === null ? null : optionalNumber(stored.userId);
+  const fraction = stored.fraction === null ? null : optionalNumber(stored.fraction);
+  const status = STATUSES.find((candidate) => candidate === stored.status);
+  if (id === undefined || game === undefined || day === undefined || seed === undefined || at === undefined || label === undefined
+    || version === undefined || gameTitle === undefined || userId === undefined || fraction === undefined || status === undefined
+    || !isNullableString(stored.title) || !isJson(stored.state)) {
+    return null;
+  }
+  return { id, game, day, seed, status, userId, at, label, fraction, title: stored.title, version, gameTitle, state: stored.state, isSynced: stored.isSynced === true };
+}
+
+/** The device copies of daily challenges. */
+export class LocalDailyStore {
+  private readonly store: KeyValueStore;
+
+  constructor(store: KeyValueStore) {
+    this.store = store;
+  }
+
+  /** The copy of `game`'s `day`, or `null`. */
+  read(game: string, day: string): LocalDaily | null {
+    const text = this.store.read(keyFor(game, day));
+    return text === null ? null : readCopy(parseJsonText(text));
+  }
+
+  /** Store a copy; answers whether it stuck (a full storage refuses a large state). */
+  write(copy: LocalDaily): boolean {
+    const text = JSON.stringify(copy);
+    this.store.write(keyFor(copy.game, copy.day), text);
+    return this.store.read(keyFor(copy.game, copy.day)) === text;
+  }
+
+  /** Forget a copy. */
+  remove(game: string, day: string): void {
+    this.store.remove(keyFor(game, day));
+  }
+
+  /** The hub has the change made at `at` (and calls the instance `id`): mark it synced; a closed copy is forgotten. */
+  markSynced(game: string, day: string, at: number, id?: string): void {
+    const copy = this.read(game, day);
+    if (copy === null || copy.at !== at) {
+      if (copy !== null && id !== undefined && copy.id !== id) {
+        this.write({ ...copy, id });
+      }
+      return;
+    }
+    if (copy.status === 'active') {
+      this.write({ ...copy, id: id ?? copy.id, isSynced: true });
+    } else {
+      this.remove(game, day);
+    }
+  }
+
+  /** Every copy of `userId`'s, any game. */
+  all(userId: number | null): LocalDaily[] {
+    const copies: LocalDaily[] = [];
+    for (const key of this.store.keys()) {
+      const match = KEY_PATTERN.exec(key);
+      const copy = match?.[1] === undefined || match[2] === undefined ? null : this.read(match[1], match[2]);
+      if (copy !== null && copy.userId === userId) {
+        copies.push(copy);
+      }
+    }
+    return copies;
+  }
+}

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/storage/json-guards.ts

@@ -72,3 +72,9 @@ export function parseJsonText(text: string): unknown {
     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);
+}