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

package/src/daily/daily-system.ts

@@ -1,161 +1,276 @@
-/**
- * Daily challenges, client side. A daily-enabled game calls
- * `hub.daily.define({ play })` once at load; `play` receives a
- * {@link DailyChallenge} and starts exactly that challenge. When the player
- * finishes, the game calls `hub.daily.complete({ score, … })`.
- *
- * The system is a page-wide singleton shared by the game's client and the
- * injected menu, so the menu can start a day on the instance the game
- * registered `play` on. Deep links (`/<slug>/?daily=YYYY-MM-DD`) auto-start.
- */
-import { readField } from '../realtime/cross-bundle';
-import type { DailyAll, DailyChallenge, DailyCompleteResponse, DailyCompletionMeta, DailyDefinition, DailyHost, DailyStatus } from './types';
-
-const DAY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
-
-/** The window event the injected menu fires to start a day on the game's instance. */
-export const DAILY_START_EVENT = 'hub:daily-start';
-
-/** A day key, or `null` when `candidate` isn't one. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: a URL parameter or a window global set by the host page
-function asDayKey(candidate: unknown): string | null {
-  return typeof candidate === 'string' && DAY_PATTERN.test(candidate) ? candidate : null;
-}
-
-/** The day the page was deep-linked to, if any. */
-function readDeepLinkDay(): string | null {
-  // Prefer the value the host's injected snippet captured at parse time: it
-  // survives games that rewrite their own URL on boot.
-  const captured = typeof window === 'undefined' ? null : asDayKey(readField(window, '__hubDailyDeep'));
-  if (captured !== null || typeof location === 'undefined') {
-    return captured;
-  }
-  return asDayKey(new URL(location.href).searchParams.get('daily'));
-}
-
-/** The message of a thrown value. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: anything a REST call can throw
-function messageOf(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-/** Daily challenges (`hub.daily`). */
-export class DailySystem {
-  /**
-   * The challenge in progress (set when a day starts, cleared on complete).
-   * A game's win handler checks it: `if (hub.daily.active) hub.daily.complete(…)`.
-   */
-  active: DailyChallenge | null = null;
-  private readonly host: DailyHost;
-  private play: DailyDefinition['play'] | null = null;
-  private pendingDay: string | null = null;
-  private isRelaying = false;
-
-  constructor(host: DailyHost) {
-    this.host = host;
-    if (typeof window !== 'undefined') {
-      // The injected menu (another module instance) asks us to start a day.
-      window.addEventListener(DAILY_START_EVENT, (event) => {
-        if (this.isRelaying) {
-          return;
-        }
-        const day = event instanceof CustomEvent ? readField(event.detail, 'day') : undefined;
-        if (typeof day === 'string') {
-          void this.startAndPlay(day);
-        }
-      });
-    }
-  }
-
-  /** Whether a game registered a daily-challenge handler on this page. */
-  get isDefined(): boolean {
-    return this.play !== null;
-  }
-
-  /**
-   * Register the game's challenge runner. Call once at load. If the page was
-   * deep-linked with `?daily=DATE` (or a start was requested before this),
-   * that day starts now.
-   */
-  define(definition: DailyDefinition): void {
-    this.play = definition.play;
-    const day = readDeepLinkDay() ?? this.pendingDay;
-    this.pendingDay = null;
-    if (day !== null) {
-      void this.startAndPlay(day);
-    }
-  }
-
-  /**
-   * Fetch the signed token for `day`, make it active and call the game's
-   * `play`. Before `define`, the day is kept and played then, so the menu's
-   * own instance never fetches a token; it is also relayed to any other
-   * daily system on the page (a client copy that couldn't share this one).
-   */
-  async startAndPlay(day: string): Promise<void> {
-    const play = this.play;
-    if (play === null) {
-      this.pendingDay = day;
-      this.relayStart(day);
-      return;
-    }
-    try {
-      const started = await this.host.start(day);
-      const challenge: DailyChallenge = { day: started.day, seed: started.seed, token: started.token, alreadyCompleted: started.alreadyCompleted };
-      this.active = challenge;
-      this.host.emit('hub:daily-started', { day: started.day, seed: started.seed, alreadyCompleted: started.alreadyCompleted });
-      play({ ...challenge });
-    } catch (error) {
-      this.host.emit('hub:daily-error', { day, error: messageOf(error) });
-    }
-  }
-
-  /**
-   * Record completion of the active challenge with optional metadata.
-   * Resolves with the new completion count and rank, or `null` when no
-   * challenge is active or the hub refused.
-   */
-  async complete(meta: DailyCompletionMeta = {}): Promise<DailyCompleteResponse | null> {
-    const challenge = this.active;
-    if (challenge === null) {
-      return null;
-    }
-    try {
-      const completed = await this.host.complete(challenge.day, challenge.token, meta);
-      this.active = null;
-      this.host.emit('hub:daily-complete', { day: challenge.day, count: completed.count, rank: completed.rank, meta });
-      return completed;
-    } catch (error) {
-      this.host.emit('hub:daily-error', { day: challenge.day, error: messageOf(error) });
-      return null;
-    }
-  }
-
-  /** Ask the page's other daily systems to start `day` (this one ignores its own event). */
-  private relayStart(day: string): void {
-    if (typeof window === 'undefined') {
-      return;
-    }
-    this.isRelaying = true;
-    try {
-      window.dispatchEvent(new CustomEvent(DAILY_START_EVENT, { detail: { day } }));
-    } finally {
-      this.isRelaying = false;
-    }
-  }
-
-  /** Abandon the active challenge without recording it (e.g. the player quit). */
-  cancel(): void {
-    this.active = null;
-  }
-
-  /** This game's window and the player's completions. */
-  status(): Promise<DailyStatus> {
-    return this.host.status();
-  }
-
-  /** Every daily-enabled game and the global standings (for the home hub). */
-  all(): Promise<DailyAll> {
-    return this.host.all();
-  }
-}
+/**
+ * Daily challenges, client side. A daily-enabled game calls
+ * `hub.daily.define({ play })` once at load; `play` receives a
+ * {@link DailyChallenge} and starts exactly that challenge. When the player
+ * finishes, the game calls `hub.daily.complete({ score, … })`.
+ *
+ * The system is a page-wide singleton shared by the game's client and the
+ * injected menu, so the menu can start a day on the instance the game
+ * registered `play` on. Deep links (`/<slug>/?daily=YYYY-MM-DD`) auto-start.
+ */
+import { readField } from '../realtime/cross-bundle';
+import type { SavedEntry } from '../core/saved/saved-types';
+import type { DailyAll, DailyChallenge, DailyCompleteResponse, DailyCompletionMeta, DailyDefinition, DailyHost, DailySaveInput, DailyStartResponse, DailyStatus } from './types';
+
+const DAY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+
+/** The window event the injected menu fires to start a day on the game's instance. */
+export const DAILY_START_EVENT = 'hub:daily-start';
+
+/** A day key, or `null` when `candidate` isn't one. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a URL parameter or a window global set by the host page
+function asDayKey(candidate: unknown): string | null {
+  return typeof candidate === 'string' && DAY_PATTERN.test(candidate) ? candidate : null;
+}
+
+/** The day the page was deep-linked to, if any. */
+function readDeepLinkDay(): string | null {
+  // Prefer the value the host's injected snippet captured at parse time: it
+  // survives games that rewrite their own URL on boot.
+  const captured = typeof window === 'undefined' ? null : asDayKey(readField(window, '__hubDailyDeep'));
+  if (captured !== null || typeof location === 'undefined') {
+    return captured;
+  }
+  return asDayKey(new URL(location.href).searchParams.get('daily'));
+}
+
+/** The message of a thrown value. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: anything a REST call can throw
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** The challenge a start or resume answered. */
+function challengeOf(started: DailyStartResponse): DailyChallenge {
+  return {
+    day: started.day, seed: started.seed, token: started.token, alreadyCompleted: started.alreadyCompleted,
+    instanceId: started.instanceId, saved: started.saved, savedVersion: started.savedVersion, resumed: started.resumed,
+  };
+}
+
+/** Daily challenges (`hub.daily`). */
+export class DailySystem {
+  /**
+   * The challenge in progress: set when a day starts; cleared the moment the
+   * game calls `complete` (whatever the hub answers, and before it answers)
+   * or `cancel` (or `discard`). A game's win handler checks it:
+   * `if (hub.daily.active) hub.daily.complete(…)`. While it is set the page
+   * is in a daily run, so `hub.resume.save` saves to the day instead of the
+   * game's run: a game whose player leaves a daily unfinished must call
+   * `cancel()`.
+   */
+  active: DailyChallenge | null = null;
+  private readonly host: DailyHost;
+  private play: DailyDefinition['play'] | null = null;
+  private pendingDay: string | null = null;
+  private pendingInstance: string | null = null;
+  /** A start on its way to the hub, so a resume of the same day waits for it instead of starting it twice. */
+  private inFlight: Promise<void> | null = null;
+  private isRelaying = false;
+
+  constructor(host: DailyHost) {
+    this.host = host;
+    if (typeof window !== 'undefined') {
+      // The injected menu (another module instance) asks us to start a day.
+      window.addEventListener(DAILY_START_EVENT, (event) => {
+        if (this.isRelaying) {
+          return;
+        }
+        const day = event instanceof CustomEvent ? readField(event.detail, 'day') : undefined;
+        if (typeof day === 'string') {
+          void this.startAndPlay(day);
+        }
+      });
+    }
+  }
+
+  /** Whether a game registered a daily-challenge handler on this page. */
+  get isDefined(): boolean {
+    return this.play !== null;
+  }
+
+  /**
+   * Register the game's challenge runner. Call once at load. If the page was
+   * deep-linked with `?daily=DATE` (or a start was requested before this),
+   * that day starts now.
+   */
+  define(definition: DailyDefinition): void {
+    this.play = definition.play;
+    const day = readDeepLinkDay() ?? this.pendingDay;
+    const instanceId = this.pendingInstance;
+    this.pendingDay = null;
+    this.pendingInstance = null;
+    if (day !== null) {
+      void this.startAndPlay(day);
+    } else if (instanceId !== null) {
+      void this.resume(instanceId);
+    }
+  }
+
+  /**
+   * Fetch the signed token for `day`, make it active and call the game's
+   * `play`. Before `define`, the day is kept and played then, so the menu's
+   * own instance never fetches a token; it is also relayed to any other
+   * daily system on the page (a client copy that couldn't share this one).
+   */
+  async startAndPlay(day: string): Promise<void> {
+    const play = this.play;
+    if (play === null) {
+      this.pendingDay = day;
+      this.relayStart(day);
+      return;
+    }
+    const starting = (async (): Promise<void> => {
+      try {
+        this.begin(play, challengeOf(await this.host.start(day)));
+      } catch (error) {
+        this.host.emit('hub:daily-error', { day, error: messageOf(error) });
+      }
+    })();
+    this.inFlight = starting;
+    await starting;
+    if (this.inFlight === starting) {
+      this.inFlight = null;
+    }
+  }
+
+  /**
+   * Pick up a day in progress by its saved game's id (from `hub.saved`):
+   * a fresh token, then the game's `play` with `challenge.saved`. Finishing
+   * it any time later gives that day's credit. A no-op while that day is
+   * already being played.
+   */
+  async resume(instanceId: string): Promise<void> {
+    // A start may be on its way for the same day (the `?daily=` link of the same open): let it land first.
+    await this.inFlight;
+    if (this.active?.instanceId === instanceId) {
+      return;
+    }
+    const play = this.play;
+    if (play === null) {
+      this.pendingInstance = instanceId;
+      return;
+    }
+    try {
+      this.begin(play, challengeOf(await this.host.resume(instanceId)));
+    } catch (error) {
+      this.host.emit('hub:daily-error', { day: '', error: messageOf(error) });
+    }
+  }
+
+  /** Make `challenge` the active day and hand it to the game. */
+  private begin(play: DailyDefinition['play'], challenge: DailyChallenge): void {
+    this.active = challenge;
+    this.host.emit('hub:daily-started', { day: challenge.day, seed: challenge.seed, alreadyCompleted: challenge.alreadyCompleted === true, resumed: challenge.resumed === true });
+    if (challenge.resumed === true) {
+      this.host.emit('hub:daily-resumed', { day: challenge.day, seed: challenge.seed, alreadyCompleted: false, resumed: true });
+    }
+    play({ ...challenge });
+  }
+
+  /**
+   * Save the active day's state, so it can be picked up later (a reload,
+   * another device, next week) and still give that day's credit. Kept on
+   * the device at once and sent after a short quiet spell (works offline).
+   * `hub.resume.save` during a daily lands here too. Returns `false` with
+   * no daily active, or for a replay of a completed day (nothing to save).
+   */
+  save(input: DailySaveInput): boolean {
+    const challenge = this.active;
+    if (challenge === null || challenge.instanceId === null) {
+      return false;
+    }
+    return this.host.save(challenge, input);
+  }
+
+  /** This game's days in progress (the calendar marks them, the game can list them). */
+  inProgress(): Promise<SavedEntry[]> {
+    return this.host.inProgress();
+  }
+
+  /**
+   * Give up the active day: its progress is discarded and nothing is
+   * recorded. The day can be started again fresh while it is in the 30-day
+   * window. (The hub's lists ask the player first; a game asks for itself.)
+   */
+  async discard(): Promise<void> {
+    const challenge = this.active;
+    if (challenge === null) {
+      return;
+    }
+    this.active = null;
+    if (challenge.instanceId !== null) {
+      await this.host.discard(challenge);
+    }
+    this.host.emit('hub:daily-discarded', { day: challenge.day, discarded: true });
+  }
+
+  /**
+   * Record completion of the active challenge with optional metadata.
+   * Resolves with the new completion count and rank, or `null` when no
+   * challenge is active, the hub refused, or the hub can't be reached: then
+   * the completion is queued (`hub:daily-queued`) and replays when it is
+   * back (`hub:daily-complete` follows). The daily run ends at the call,
+   * so `active` is `null` at once, even if the hub then refuses it.
+   */
+  async complete(meta: DailyCompletionMeta = {}): Promise<DailyCompleteResponse | null> {
+    const challenge = this.active;
+    if (challenge === null) {
+      return null;
+    }
+    this.active = null;
+    try {
+      const completed = await this.host.complete(challenge.day, challenge.token, meta);
+      if (completed === null) {
+        // Queued offline: `hub:daily-complete` follows when it replays.
+        this.host.emit('hub:daily-queued', { day: challenge.day, queued: true, meta });
+        return null;
+      }
+      this.host.emit('hub:daily-complete', { day: challenge.day, count: completed.count, rank: completed.rank, meta });
+      return completed;
+    } catch (error) {
+      this.host.emit('hub:daily-error', { day: challenge.day, error: messageOf(error) });
+      return null;
+    }
+  }
+
+  /** Ask the page's other daily systems to start `day` (this one ignores its own event). */
+  private relayStart(day: string): void {
+    if (typeof window === 'undefined') {
+      return;
+    }
+    this.isRelaying = true;
+    try {
+      window.dispatchEvent(new CustomEvent(DAILY_START_EVENT, { detail: { day } }));
+    } finally {
+      this.isRelaying = false;
+    }
+  }
+
+  /**
+   * Pause the active day: the player left it unfinished (quit, picked
+   * another level, started a normal game). Nothing is recorded, and the day
+   * stays in progress in "Your games" and the calendar, to finish later
+   * (its last save is sent now). Until then the page counts as in a daily,
+   * so `hub.resume.save` saves to the day: call `cancel()` on every path
+   * that leaves a daily without `complete`. To give a day up, `discard()`.
+   */
+  cancel(): void {
+    const challenge = this.active;
+    this.active = null;
+    if (challenge !== null) {
+      void this.host.flush().catch(() => undefined);
+      this.host.emit('hub:daily-paused', { day: challenge.day, paused: true });
+    }
+  }
+
+  /** This game's window and the player's completions. */
+  status(): Promise<DailyStatus> {
+    return this.host.status();
+  }
+
+  /** Every daily-enabled game and the global standings (for the home hub). */
+  all(): Promise<DailyAll> {
+    return this.host.all();
+  }
+}

package/src/daily/page-daily.ts

@@ -1,36 +1,36 @@
-/**
- * The page's one daily-challenge system (plan §4.4): the first bundle to
- * create it wins, so the menu starts days on the instance the game defined.
- */
-import { HUB_CLIENT_VERSION } from '../core/version/client-version.gen';
-import { claimSingleton } from '../globals';
-import { hasMethods } from '../realtime/cross-bundle';
-import { DailySystem } from './daily-system';
-import type { DailyHost } from './types';
-
-/** The cross-bundle shape number of the `daily` singleton. Bump only on an incompatible change. */
-export const DAILY_SINGLETON_API = 1;
-
-/** Whether `candidate` is some bundle's daily system (v1 copies included). */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: the instance may come from another bundle
-export function isDailySystem(candidate: unknown): candidate is DailySystem {
-  return hasMethods(candidate, ['define', 'startAndPlay', 'complete', 'cancel', 'status', 'all']);
-}
-
-let claimedDaily: DailySystem | null = null;
-
-/**
- * The page-wide daily system, created with `host` if no bundle has made one
- * yet. On a shape mismatch the registered one is kept and this bundle gets a
- * private instance. The answer is kept for this bundle.
- */
-export function getDaily(host: DailyHost): DailySystem {
-  claimedDaily ??= claimSingleton({
-    name: 'daily',
-    version: HUB_CLIENT_VERSION,
-    api: DAILY_SINGLETON_API,
-    create: () => new DailySystem(host),
-    isInstance: isDailySystem,
-  });
-  return claimedDaily;
-}
+/**
+ * The page's one daily-challenge system (plan §4.4): the first bundle to
+ * create it wins, so the menu starts days on the instance the game defined.
+ */
+import { HUB_CLIENT_VERSION } from '../core/version/client-version.gen';
+import { claimSingleton } from '../globals';
+import { hasMethods } from '../realtime/cross-bundle';
+import { DailySystem } from './daily-system';
+import type { DailyHost } from './types';
+
+/** The cross-bundle shape number of the `daily` singleton (2 added save, resume, discard and inProgress). Bump only on an incompatible change. */
+export const DAILY_SINGLETON_API = 2;
+
+/** Whether `candidate` is some bundle's daily system (v1 copies included). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: the instance may come from another bundle
+export function isDailySystem(candidate: unknown): candidate is DailySystem {
+  return hasMethods(candidate, ['define', 'startAndPlay', 'complete', 'cancel', 'status', 'all']);
+}
+
+let claimedDaily: DailySystem | null = null;
+
+/**
+ * The page-wide daily system, created with `host` if no bundle has made one
+ * yet. On a shape mismatch the registered one is kept and this bundle gets a
+ * private instance. The answer is kept for this bundle.
+ */
+export function getDaily(host: DailyHost): DailySystem {
+  claimedDaily ??= claimSingleton({
+    name: 'daily',
+    version: HUB_CLIENT_VERSION,
+    api: DAILY_SINGLETON_API,
+    create: () => new DailySystem(host),
+    isInstance: isDailySystem,
+  });
+  return claimedDaily;
+}