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

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

@@ -11,8 +11,9 @@
  * - `load()` / `get()` read it back; `requested` says the page was opened to
  *   resume, so the game restores without asking.
  *
- * Saves are ignored while the page is in a race, a daily challenge or an
- * online room: those runs are never resumed.
+ * Saves are ignored while the page is in a race or an online room: those
+ * runs are never resumed. During a daily challenge they go to the day's own
+ * saved game (`hub.daily.save`), so the day can be picked up again.
  */
 import type { ResumeSlot, ResumeSummary } from '@diffenderfer-games/hub-contract';
 import { HubError } from '../errors';
@@ -35,6 +36,7 @@ const BLOCKED_HINTS: Readonly<Record<ResumeBlocker, string>> = {
   daily: 'a daily challenge is active. When the player leaves a daily without finishing it, call hub.daily.cancel().',
   race: 'a race is on: races are never resumed.',
   room: 'the page is in a hub room: online games are never resumed.',
+  turns: 'an online game is open: the hub keeps its state, so nothing is saved on the page.',
 };
 
 /** Longest label or title kept (the contract's `RESUME_TEXT_MAX`). */
@@ -51,6 +53,8 @@ export interface ResumeHost {
   gameTitle(): string;
   /** Why saving is off right now, or `null`. */
   blocker(): ResumeBlocker | null;
+  /** The page's daily challenge while one is being played (saves go to the day instead of the run), else `null`. */
+  daily?(): DailyRoute | null;
   /** Perform a resume op: at once when online with nothing waiting, else queued. */
   send(payload: ResumePayload): Promise<void>;
   /** This game's run on the hub, or `undefined` when the hub can't be reached. */
@@ -59,8 +63,18 @@ export interface ResumeHost {
   fetchList(): Promise<ResumeSummary[] | undefined>;
   /** Clear another game's run on the hub (the home page's discard); throws offline. */
   clearOther(slug: string): Promise<void>;
+  /** The run changed here (saved or cleared): `hub.saved` listeners hear it. */
+  onChange?(): void;
 }
 
+/** Where a save goes during a daily challenge (`hub.daily`). */
+export interface DailyRoute {
+  save(input: ResumeSaveInput<GamePayload>): boolean;
+}
+
+/** The label a daily goes back to when the game clears its run mid-daily (the day restarts from its seed). */
+const DAILY_RESTART_LABEL = 'Started';
+
 /** A label or title trimmed and clipped, or `null` when blank. */
 function shortText(text: string | null | undefined): string | null {
   const trimmed = (text ?? '').trim();
@@ -111,8 +125,9 @@ export class HubResume {
   /**
    * Save the run (the latest save wins). Stored on the device at once; sent
    * after {@link RESUME_DEBOUNCE_MS} of quiet, or when the page is hidden.
-   * Returns `false` (and saves nothing) in a race, a daily challenge or an
-   * online room. Throws a `HubError` 413 over 512 KB, 400 without a label.
+   * Returns `false` (and saves nothing) in a race or an online room; during
+   * a daily challenge the save goes to the day (`hub.daily.save`). Throws a
+   * `HubError` 413 over 512 KB, 400 without a label.
    */
   save<TState extends GamePayload>(run: ResumeSaveInput<TState>): boolean {
     const blocker = this.host.blocker();
@@ -120,6 +135,11 @@ export class HubResume {
       this.warnBlocked(blocker);
       return false;
     }
+    const daily = this.host.daily?.() ?? null;
+    if (daily !== null) {
+      // During a daily challenge the run IS the day: it is saved to the day's saved game, not the game's run.
+      return daily.save(run);
+    }
     const slug = this.requireSlug();
     const label = shortText(run.progress.label);
     if (label === null) {
@@ -135,6 +155,7 @@ export class HubResume {
       version: Math.max(0, Math.floor(run.version ?? 0)), gameTitle: this.host.gameTitle(), state, isSynced: false,
     };
     const isStored = this.host.local.write(slug, copy);
+    this.host.onChange?.();
     this.schedule({
       action: 'save', savedAt: copy.at, label, fraction, title: copy.title, version: copy.version,
       ...(isStored ? {} : { state }),
@@ -158,6 +179,17 @@ export class HubResume {
   /** Clear the run: call it when the run ends (won, lost or quit). Works offline. */
   async clear(): Promise<void> {
     const slug = this.requireSlug();
+    const daily = this.host.daily?.() ?? null;
+    if (daily !== null) {
+      // The day's run ended without a win: the day stays in progress, starting over from its seed.
+      daily.save({ state: null, progress: { label: DAILY_RESTART_LABEL } });
+      return;
+    }
+    await this.clearRun(slug);
+  }
+
+  /** Delete the game's saved run (never the day being played). */
+  private async clearRun(slug: string): Promise<void> {
     if (this.timer !== null) {
       clearTimeout(this.timer);
       this.timer = null;
@@ -165,6 +197,7 @@ export class HubResume {
     this.waiting = null;
     const at = Date.now();
     this.host.local.write(slug, { status: 'cleared', userId: this.host.currentUserId(), at, isSynced: false });
+    this.host.onChange?.();
     await this.host.send({ action: 'clear', before: at });
   }
 
@@ -186,7 +219,8 @@ export class HubResume {
       return run;
     }
     if (run.version < options.version) {
-      await this.clear();
+      // A stale saved run is dropped; a daily being played is left alone.
+      await this.clearRun(slug);
     }
     return null;
   }

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

@@ -60,5 +60,5 @@ export interface ResumeEntry {
   readonly isLocalOnly: boolean;
 }
 
-/** Why a save was ignored: the page is in a race, a daily challenge or an online room. */
-export type ResumeBlocker = 'race' | 'daily' | 'room';
+/** 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;
+}

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;
+  }
+}