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

package/src/core/offline/local-inventory.ts

@@ -0,0 +1,64 @@
+/**
+ * The cached inventory, changed the way the hub would change it, so grants
+ * and house exchanges made offline show at once. The hub has the last word
+ * when they replay.
+ */
+import type { Inventory } from '@diffenderfer-games/hub-contract';
+import { isRecord, optionalNumber, optionalString } from '../storage/json-guards';
+
+/** Goods moved by a grant or an exchange: item key to quantity, and coins. */
+export type GoodsPayload = { readonly items?: { readonly [key: string]: number }; readonly coins?: number };
+
+/** An empty inventory. */
+export const EMPTY_INVENTORY: Inventory = { items: [], coins: 0 };
+
+/** A cached inventory, or `null` when there is none or it is malformed. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: an inventory read back from localStorage
+export function readInventory(stored: unknown): Inventory | null {
+  if (!isRecord(stored) || !Array.isArray(stored.items)) {
+    return null;
+  }
+  const coins = optionalNumber(stored.coins);
+  const items = stored.items.flatMap((item): Inventory['items'] => {
+    const key = isRecord(item) ? optionalString(item.key) : undefined;
+    const qty = isRecord(item) ? optionalNumber(item.qty) : undefined;
+    return key === undefined || qty === undefined ? [] : [{ key, qty }];
+  });
+  return coins === undefined ? null : { items, coins };
+}
+
+/** The holdings as a key-to-quantity map. */
+function quantities(inventory: Inventory): Map<string, number> {
+  return new Map(inventory.items.map((item) => [item.key, item.qty]));
+}
+
+/** The holdings from a map (positive counts only, sorted by key). */
+function fromQuantities(held: ReadonlyMap<string, number>, coins: number): Inventory {
+  const items = [...held].filter(([, qty]) => qty > 0).sort(([first], [second]) => first.localeCompare(second)).map(([key, qty]) => ({ key, qty }));
+  return { items, coins };
+}
+
+/** `inventory` with `goods` added. */
+export function withGoods(inventory: Inventory, goods: GoodsPayload): Inventory {
+  const held = quantities(inventory);
+  for (const [key, qty] of Object.entries(goods.items ?? {})) {
+    held.set(key, (held.get(key) ?? 0) + qty);
+  }
+  return fromQuantities(held, inventory.coins + (goods.coins ?? 0));
+}
+
+/** `inventory` with `goods` removed, or the hub's refusal message when it can't cover them. */
+export function withoutGoods(inventory: Inventory, goods: GoodsPayload): Inventory | string {
+  if ((goods.coins ?? 0) > inventory.coins) {
+    return "You don't have enough coins.";
+  }
+  const held = quantities(inventory);
+  for (const [key, qty] of Object.entries(goods.items ?? {})) {
+    const have = held.get(key) ?? 0;
+    if (qty > have) {
+      return `You don't have ${String(qty)}× "${key}".`;
+    }
+    held.set(key, have - qty);
+  }
+  return fromQuantities(held, inventory.coins - (goods.coins ?? 0));
+}

package/src/core/offline/local-store.ts

@@ -1,15 +1,19 @@
 /**
  * The offline cache: what the client serves when the hub can't be reached,
- * and where queued writes and buffered events wait. Keys are the v1 client's
- * (`hub:user`, `hub:<slug>:save:<slot>`, `hub:<slug>:queue`, ...), so a page
- * upgraded from a vendored copy keeps that copy's cache and queues.
+ * and where buffered analytics events wait (queued writes live in the
+ * outbox, `outbox.ts`). Keys are the v1 client's (`hub:user`,
+ * `hub:<slug>:save:<slot>`, `hub:<slug>:events`, ...), so a page upgraded
+ * from a vendored copy keeps that copy's cache, and its `hub:<slug>:queue`
+ * moves into the outbox.
  */
-import type { Board, Json, SortDir, Stats } from '@diffenderfer-games/hub-contract';
+import type { Board, Inventory, Json, SortDir, Stats } from '@diffenderfer-games/hub-contract';
 import { isJson, isNullableString, isNumberRecord, isRecord, optionalNumber, optionalString, parseJsonText } from '../storage/json-guards';
 import { createPageStore, type KeyValueStore } from '../storage/key-value';
 import type { Profile, Save, SaveMeta, SnapshotResponse, User } from '../types';
+import { cloudSaveOf, readCloudSaveIndex, withCloudSave, type CloudSaveIndex } from './cloud-saves';
 import { appendEvent, readEvents, type BufferedEvent } from './events';
-import { betterScore, enqueueOp, readQueue, type QueueOp, type QueueOpInput, type QueuedScoreOptions } from './queue';
+import { EMPTY_INVENTORY, readInventory } from './local-inventory';
+import { betterScore, readQueue, type QueueOp, type QueuedScoreOptions } from './queue';
 
 /** The key of the locally known user, shared by every game (like the real session). */
 export const USER_KEY = 'hub:user';
@@ -83,7 +87,6 @@ function readLocalBoard(stored: unknown): LocalBoard | null {
 export class LocalStore {
   private readonly prefix: string;
   private readonly store: KeyValueStore;
-  private sequence = 0;
 
   /** The cache for game `slug` in `store` (default: `localStorage`, or memory without it). */
   constructor(slug: string, store: KeyValueStore = createPageStore()) {
@@ -157,6 +160,37 @@ export class LocalStore {
     this.store.remove(`${this.prefix}save:${slot}`);
   }
 
+  /**
+   * The hub's `updatedAt` for `slot` as the current user last saw it (`null`:
+   * the slot was empty), or `undefined` when this device doesn't know.
+   */
+  cloudSave(slot: string): number | null | undefined {
+    const user = this.getUser();
+    return user === null ? undefined : cloudSaveOf(this.readCloudSaves(this.prefix), user.id, slot);
+  }
+
+  /** Note the hub's copy of `slot` (just read or written) for the current user: its `updatedAt`, or `null` when empty. */
+  rememberCloudSave(slot: string, updatedAt: number | null): void {
+    const user = this.getUser();
+    if (user !== null) {
+      this.writeStored(`${this.prefix}cloud-saves`, withCloudSave(this.readCloudSaves(this.prefix), user.id, slot, updatedAt));
+    }
+  }
+
+  /** Cache a slot as read from the hub (forgetting it when the hub has none), and note the hub's copy. */
+  cacheCloudSave(slot: string, save: Save | null): void {
+    if (save === null) {
+      this.deleteSave(slot);
+    } else {
+      this.writeStored(`${this.prefix}save:${slot}`, save);
+    }
+    this.rememberCloudSave(slot, save?.updatedAt ?? null);
+  }
+
+  private readCloudSaves(gamePrefix: string): CloudSaveIndex | null {
+    return readCloudSaveIndex(this.readStored(`${gamePrefix}cloud-saves`));
+  }
+
   /** This game's cached stats. */
   getStats(): Stats {
     const stored = this.readStored(`${this.prefix}stats`);
@@ -197,26 +231,22 @@ export class LocalStore {
     return { board, best };
   }
 
-  /** The queued writes, oldest first. */
-  getQueue(): QueueOp[] {
-    return readQueue(this.readStored(`${this.prefix}queue`));
+  /** The v1 client's queued writes, removed from storage (the caller moves them into the outbox). */
+  takeLegacyQueue(): QueueOp[] {
+    const queue = readQueue(this.readStored(`${this.prefix}queue`));
+    this.store.remove(`${this.prefix}queue`);
+    return queue;
   }
 
-  /** Replace the queue. */
-  setQueue(queue: readonly QueueOp[]): void {
-    this.writeStored(`${this.prefix}queue`, queue);
+  /** This game's cached inventory (empty when none is cached). */
+  getInventory(): Inventory {
+    return readInventory(this.readStored(`${this.prefix}inventory`)) ?? EMPTY_INVENTORY;
   }
 
-  /** How many writes are queued. */
-  queueLength(): number {
-    return this.getQueue().length;
-  }
-
-  /** Queue a write, collapsing it with a compatible queued one. */
-  enqueue(input: QueueOpInput): void {
-    this.sequence += 1;
-    const now = Date.now();
-    this.setQueue(enqueueOp(this.getQueue(), { ...input, id: `${String(now)}-${String(this.sequence)}`, ts: now }));
+  /** Store this game's inventory and return it. */
+  setInventory(inventory: Inventory): Inventory {
+    this.writeStored(`${this.prefix}inventory`, inventory);
+    return inventory;
   }
 
   /** The buffered analytics events, oldest first. */
@@ -234,11 +264,20 @@ export class LocalStore {
     this.setEvents(appendEvent(this.getEvents(), { type, ts: Date.now() }));
   }
 
-  /** Fan a `/me/snapshot` reply out across every game's cache keys. */
+  /**
+   * Fan a `/me/snapshot` reply out across every game's cache keys. It lists
+   * every save slot of every game the player has played, so each game's
+   * slots on the hub become known (and this game's are all empty when it
+   * isn't listed).
+   */
   hydrate(snapshot: SnapshotResponse): void {
     if (snapshot.user !== null) {
       this.writeStored(USER_KEY, snapshot.user);
     }
+    const userId = snapshot.user?.id;
+    if (userId !== undefined && !Object.keys(snapshot.games).some((slug) => `hub:${slug}:` === this.prefix)) {
+      this.writeStored(`${this.prefix}cloud-saves`, { userId, complete: true, saves: {} } satisfies CloudSaveIndex);
+    }
     for (const [slug, game] of Object.entries(snapshot.games)) {
       const gamePrefix = `hub:${slug}:`;
       if (game.profile !== null) {
@@ -247,6 +286,10 @@ export class LocalStore {
       for (const save of game.saves) {
         this.writeStored(`${gamePrefix}save:${save.slot}`, save);
       }
+      if (userId !== undefined) {
+        const saves = Object.fromEntries(game.saves.map((save) => [save.slot, save.updatedAt]));
+        this.writeStored(`${gamePrefix}cloud-saves`, { userId, complete: true, saves } satisfies CloudSaveIndex);
+      }
       this.writeStored(`${gamePrefix}stats`, game.stats);
       this.writeStored(`${gamePrefix}inventory`, game.inventory);
     }

package/src/core/offline/offline-api.ts

@@ -0,0 +1,65 @@
+/**
+ * `hub.offline`: the outbox, opened to games. A game defines its own kinds
+ * (a handler per kind, which may make several dependent calls) and enqueues
+ * operations of them; the hub queues them in order, replays them when it is
+ * reachable, and reports what happened.
+ */
+import { toStoredJson, type GamePayload } from '../game-data';
+import { HubError } from '../errors';
+import { gameKind } from './kind-adapters';
+import type { OfflineEventName, OfflineListener, OfflineOp, Outbox } from './outbox';
+import { HUB_KIND_PREFIX, type OfflineHandler, type OfflineKindDefinition } from './outbox-kinds';
+
+/** What `hub.offline` drives. */
+export interface OfflineHost {
+  /** The game's outbox. */
+  readonly outbox: Outbox;
+  /** Replay now when the hub is reachable (and nothing else is replaying). */
+  requestSync(): void;
+}
+
+/** The game-facing outbox API. */
+export class OfflineApi {
+  private readonly host: OfflineHost;
+
+  /** The API over `host`. */
+  constructor(host: OfflineHost) {
+    this.host = host;
+  }
+
+  /**
+   * Define what an operation of `kind` does when it replays. Define every
+   * kind at load, before or after enqueueing: waiting ops of an undefined
+   * kind hold the queue until it is defined. `hub.*` kinds are the hub's own.
+   */
+  define<Payload extends GamePayload>(kind: string, definition: OfflineHandler<Payload> | OfflineKindDefinition<Payload>): void {
+    if (kind.startsWith(HUB_KIND_PREFIX) || kind === '') {
+      throw new HubError(`Offline kinds starting with "${HUB_KIND_PREFIX}" are the hub's own; name yours after your game.`);
+    }
+    this.host.outbox.define(kind, gameKind(definition));
+    this.host.requestSync();
+  }
+
+  /**
+   * Queue an operation of `kind` and replay it as soon as the hub is
+   * reachable (at once when online). Resolves the queued op; its outcome
+   * arrives as a `replayed` or `failed` event. Throws a `HubError` (code
+   * `offline_queue_full`) when the outbox is full.
+   */
+  enqueue(kind: string, payload: GamePayload): OfflineOp {
+    const op = this.host.outbox.stamp(kind, toStoredJson(payload));
+    this.host.outbox.add(op);
+    this.host.requestSync();
+    return op;
+  }
+
+  /** The waiting operations (the hub's and the game's), oldest first. */
+  pending(): OfflineOp[] {
+    return this.host.outbox.pending();
+  }
+
+  /** Listen for `queued`, `replayed` or `failed`; returns the unsubscribe function. */
+  on<Name extends OfflineEventName>(name: Name, listener: OfflineListener<Name>): () => void {
+    return this.host.outbox.on(name, listener);
+  }
+}

package/src/core/offline/outbox-entry.ts

@@ -0,0 +1,59 @@
+/**
+ * One operation in the offline outbox: a `kind` (whose registered handler
+ * performs it), its JSON payload, and its replay bookkeeping. Each entry is
+ * stored under its own key, so two tabs adding and removing entries never
+ * overwrite each other's lists.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import { isJson, isRecord, optionalNumber, optionalString } from '../storage/json-guards';
+
+/** A queued operation. */
+export interface OutboxEntry {
+  /** Unique and sortable by queue time: replay runs in `id` order. Also the base of its operation keys. */
+  readonly id: string;
+  /** Which handler performs it (`hub.save`, `hub.stat`, or a game's own kind). */
+  readonly kind: string;
+  /** The handler's input. */
+  readonly payload: Json;
+  /** When it was queued (epoch ms). */
+  readonly createdAt: number;
+  /** How many times replay has started it. A started entry never absorbs a later one. */
+  readonly attempts: number;
+  /** Not before this time (epoch ms); 0 means as soon as possible. */
+  readonly retryAt: number;
+  /** The last failure's message, when it has failed before. */
+  readonly lastError?: string;
+}
+
+/** How wide the time part of an id is (enough for epoch ms until the year 5138). */
+const TIME_DIGITS = 14;
+
+/** How wide the sequence part of an id is. */
+const SEQUENCE_DIGITS = 6;
+
+/**
+ * A new entry id: the queue time, a per-page sequence and a random tag, so
+ * ids sort by time and two tabs queueing in the same millisecond never clash.
+ */
+export function newEntryId(now: number, sequence: number): string {
+  const tag = Math.floor(Math.random() * 36 ** 6).toString(36).padStart(6, '0');
+  return `${String(now).padStart(TIME_DIGITS, '0')}-${String(sequence % 10 ** SEQUENCE_DIGITS).padStart(SEQUENCE_DIGITS, '0')}-${tag}`;
+}
+
+/** A stored entry, or `undefined` when it is malformed. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: an entry read back from localStorage
+export function readEntry(stored: unknown): OutboxEntry | undefined {
+  if (!isRecord(stored) || !isJson(stored.payload)) {
+    return undefined;
+  }
+  const id = optionalString(stored.id);
+  const kind = optionalString(stored.kind);
+  const createdAt = optionalNumber(stored.createdAt);
+  const attempts = optionalNumber(stored.attempts);
+  const retryAt = optionalNumber(stored.retryAt);
+  const lastError = optionalString(stored.lastError);
+  if (id === undefined || kind === undefined || createdAt === undefined || attempts === undefined || retryAt === undefined) {
+    return undefined;
+  }
+  return { id, kind, payload: stored.payload, createdAt, attempts, retryAt, ...(lastError === undefined ? {} : { lastError }) };
+}

package/src/core/offline/outbox-kinds.ts

@@ -0,0 +1,78 @@
+/**
+ * Outbox kinds: what each sort of queued operation does when it replays,
+ * and how a new one folds into those already waiting. The hub registers its
+ * own (`hub.*`); a game adds its own with `hub.offline.define`.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import type { EndpointName, EndpointReply } from '../rest/endpoint-types';
+import type { CallArguments } from '../rest/rest-client';
+
+/** What a kind's handler gets besides its payload. */
+export interface ReplayContext {
+  /** The operation's id (stable across retries). */
+  readonly opId: string;
+  /** Which try this is, from 1. */
+  readonly attempt: number;
+  /** `false` when the op runs at once (online, nothing waiting); `true` when it runs from the queue. */
+  readonly isReplay: boolean;
+  /**
+   * Call a hub endpoint. Calls to endpoints marked for offline replay carry
+   * an operation key made from the op id and the call's position in the
+   * handler, so a retried op whose earlier calls already landed gets their
+   * remembered replies instead of running them twice. Make the same calls in
+   * the same order on every try.
+   */
+  call<K extends EndpointName>(name: K, ...fieldsArgument: CallArguments<K>): Promise<EndpointReply<K>>;
+  /** A key for `step` of this op that is the same on every try: send it to a game server to deduplicate there. */
+  key(step: string): string;
+}
+
+/** Performs one operation of a kind. Throw to fail it (see the docs for which failures retry). */
+export type OfflineHandler<Payload> = (payload: Payload, context: ReplayContext) => Promise<Json | undefined> | Json | undefined;
+
+/** A kind, with optional rules for folding new operations into waiting ones. */
+export interface OfflineKindDefinition<Payload> {
+  /** Perform one operation. */
+  readonly run: OfflineHandler<Payload>;
+  /**
+   * Operations with the same merge key may fold together. Without one, every
+   * operation replays on its own.
+   */
+  readonly mergeKey?: (payload: Payload) => string;
+  /**
+   * Fold `incoming` into the newest waiting operation with the same merge key
+   * (in its place in the queue); `undefined` to queue it separately.
+   */
+  readonly merge?: (waiting: Payload, incoming: Payload) => Payload | undefined;
+  /** `true`: a new operation replaces every waiting one with the same merge key and goes last (a save slot's last write wins). */
+  readonly replaces?: boolean;
+}
+
+/** A kind as the outbox runs it: payloads are the stored JSON. */
+export interface RegisteredKind {
+  /** Perform one operation (malformed payloads are refused before this). */
+  readonly run: (payload: Json, context: ReplayContext) => Promise<Json | undefined> | Json | undefined;
+  /** Whether a stored payload is well formed for this kind. */
+  readonly accepts: (payload: Json) => boolean;
+  readonly mergeKey?: (payload: Json) => string;
+  readonly merge?: (waiting: Json, incoming: Json) => Json | undefined;
+  readonly replaces: boolean;
+}
+
+/** The prefix reserved for the hub's own kinds. */
+export const HUB_KIND_PREFIX = 'hub.';
+
+/** The registered kinds of one client. */
+export class KindRegistry {
+  private readonly kinds = new Map<string, RegisteredKind>();
+
+  /** Register (or replace) a kind. */
+  register(kind: string, definition: RegisteredKind): void {
+    this.kinds.set(kind, definition);
+  }
+
+  /** A registered kind, or `undefined`. */
+  get(kind: string): RegisteredKind | undefined {
+    return this.kinds.get(kind);
+  }
+}

package/src/core/offline/outbox-merge.ts

@@ -0,0 +1,39 @@
+/**
+ * How a new operation joins the outbox (pure, so it is easy to test): queued
+ * on its own, folded into the newest waiting one with the same merge key, or
+ * replacing every waiting one with that key. An entry replay has started is
+ * never changed or replaced: its request may already have reached the hub
+ * under its operation key, so a changed payload would be lost.
+ */
+import type { OutboxEntry } from './outbox-entry';
+import type { RegisteredKind } from './outbox-kinds';
+
+/** The store changes one enqueue makes. */
+export interface EnqueuePlan {
+  /** Entries to write (the new one, or a waiting one with a merged payload). */
+  readonly put: OutboxEntry;
+  /** Entries to remove (waiting ones the new one replaces). */
+  readonly remove: readonly string[];
+  /** `true` when `put` is a waiting entry that absorbed the new one. */
+  readonly isMerged: boolean;
+}
+
+/** How `incoming` (of kind `kind`) joins `entries` (oldest first). */
+export function planEnqueue(entries: readonly OutboxEntry[], incoming: OutboxEntry, kind: RegisteredKind): EnqueuePlan {
+  const separately: EnqueuePlan = { put: incoming, remove: [], isMerged: false };
+  const { mergeKey } = kind;
+  if (mergeKey === undefined) {
+    return separately;
+  }
+  const key = mergeKey(incoming.payload);
+  const sameKey = entries.filter((entry) => entry.kind === incoming.kind && kind.accepts(entry.payload) && mergeKey(entry.payload) === key);
+  if (kind.replaces) {
+    return { put: incoming, remove: sameKey.filter((entry) => entry.attempts === 0).map((entry) => entry.id), isMerged: false };
+  }
+  const newest = sameKey.at(-1);
+  if (kind.merge === undefined || newest === undefined || newest.attempts > 0) {
+    return separately;
+  }
+  const merged = kind.merge(newest.payload, incoming.payload);
+  return merged === undefined ? separately : { put: { ...newest, payload: merged }, remove: [], isMerged: true };
+}

package/src/core/offline/outbox-replayer.ts

@@ -0,0 +1,141 @@
+/**
+ * Replays the outbox in order, holding the game's replay lease so only one
+ * tab (or client copy) sends at a time. Each entry is marked started before
+ * its handler runs, then removed on success or on a permanent failure; a
+ * passing failure leaves it at the head with a backoff, so nothing behind it
+ * jumps the queue. An entry whose kind isn't defined here stops this
+ * replayer (and lets go of the lease) so a client that knows the kind, such
+ * as the game's own copy on the page, can carry on.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import type { OutboxEntry } from './outbox-entry';
+import type { KindRegistry, ReplayContext } from './outbox-kinds';
+import type { OutboxStore } from './outbox-store';
+import type { ReplayLease } from './replay-lease';
+import { backoffMs, failureMessage, MAX_RETRIES, verdictFor } from './replay-policy';
+
+/** An op dropped during replay, with why. */
+export interface ReplayFailure {
+  /** The dropped op. */
+  readonly entry: OutboxEntry;
+  /** Why it was dropped (the hub's message, or the handler's). */
+  readonly error: string;
+}
+
+/** Why a replay stopped before the outbox was empty. */
+export type ReplayStop = 'connection' | 'backoff' | 'unknown-kind' | 'lease';
+
+/** What one replay did. */
+export interface ReplayReport {
+  /** The ops that landed, in order. */
+  readonly replayed: OutboxEntry[];
+  /** The ops dropped. */
+  readonly failed: ReplayFailure[];
+  /** Why it stopped early, or `undefined` when the outbox is empty. */
+  readonly stoppedBy?: ReplayStop;
+}
+
+/** What the replayer works with. */
+export interface ReplayerParts {
+  readonly store: OutboxStore;
+  readonly kinds: KindRegistry;
+  readonly lease: ReplayLease;
+  /** The context an entry's handler gets on try `attempt`. */
+  readonly contextFor: (entry: OutboxEntry, attempt: number) => ReplayContext;
+  /** An op landed (`result` is what its handler returned). */
+  readonly onReplayed: (entry: OutboxEntry, result: Json | undefined) => void;
+  /** An op was dropped. */
+  readonly onFailed: (failure: ReplayFailure) => void;
+  /** The hub couldn't be reached. */
+  readonly onUnreachable: () => void;
+  /** Ask for another replay in `delayMs`. */
+  readonly scheduleRetry: (delayMs: number) => void;
+  readonly now: () => number;
+}
+
+/** A report for a replay that didn't get the lease. */
+const LEASE_HELD: ReplayReport = { replayed: [], failed: [], stoppedBy: 'lease' };
+
+/** Replays one game's outbox. */
+export class OutboxReplayer {
+  private readonly parts: ReplayerParts;
+
+  /** A replayer over `parts`. */
+  constructor(parts: ReplayerParts) {
+    this.parts = parts;
+  }
+
+  /** Replay everything due, in order. `isEager` skips the backoff of ops waiting for the connection (it just came back). */
+  async replay(isEager = false): Promise<ReplayReport> {
+    let report: ReplayReport = LEASE_HELD;
+    const isHeld = await this.parts.lease.hold(async () => {
+      report = await this.drain(isEager);
+    });
+    return isHeld ? report : LEASE_HELD;
+  }
+
+  private async drain(isEager: boolean): Promise<ReplayReport> {
+    const { store, kinds, now } = this.parts;
+    const replayed: OutboxEntry[] = [];
+    const failed: ReplayFailure[] = [];
+    for (let head = store.list()[0]; head !== undefined; head = store.list()[0]) {
+      if (head.retryAt > now() && !(isEager && head.lastError === undefined)) {
+        this.parts.scheduleRetry(head.retryAt - now());
+        return { replayed, failed, stoppedBy: 'backoff' };
+      }
+      const kind = kinds.get(head.kind);
+      if (kind === undefined) {
+        return { replayed, failed, stoppedBy: 'unknown-kind' };
+      }
+      if (!kind.accepts(head.payload)) {
+        store.remove(head.id);
+        this.drop(failed, head, 'Malformed offline operation payload.');
+        continue;
+      }
+      const started: OutboxEntry = { ...head, attempts: head.attempts + 1 };
+      store.put(started);
+      try {
+        const result = await kind.run(head.payload, this.parts.contextFor(head, started.attempts));
+        store.remove(head.id);
+        replayed.push(started);
+        this.parts.onReplayed(started, result ?? undefined);
+      } catch (failure) {
+        const stop = this.settleFailure(started, failure, failed);
+        if (stop !== undefined) {
+          return { replayed, failed, stoppedBy: stop };
+        }
+      }
+    }
+    return { replayed, failed };
+  }
+
+  /** Record a failed try; answers why replay stops, or `undefined` to carry on with the next op. */
+  // eslint-disable-next-line no-restricted-syntax -- trust boundary: whatever a replay handler threw
+  private settleFailure(started: OutboxEntry, failure: unknown, failed: ReplayFailure[]): ReplayStop | undefined {
+    const { store, now } = this.parts;
+    const verdict = verdictFor(failure);
+    const message = failureMessage(failure);
+    if (verdict === 'drop' || (verdict === 'retry' && started.attempts >= MAX_RETRIES)) {
+      store.remove(started.id);
+      this.drop(failed, started, message);
+      return undefined;
+    }
+    const delay = backoffMs(started.attempts);
+    // Waiting for the connection is not an error of the op's own: an eager replay (back online) retries it at once.
+    const { id, kind, payload, createdAt, attempts } = started;
+    const retrying: OutboxEntry = { id, kind, payload, createdAt, attempts, retryAt: now() + delay };
+    const waiting: OutboxEntry = verdict === 'offline' ? retrying : { ...retrying, lastError: message };
+    store.put(waiting);
+    if (verdict === 'offline') {
+      this.parts.onUnreachable();
+    }
+    this.parts.scheduleRetry(delay);
+    return verdict === 'offline' ? 'connection' : 'backoff';
+  }
+
+  private drop(failed: ReplayFailure[], entry: OutboxEntry, error: string): void {
+    const failure = { entry, error };
+    failed.push(failure);
+    this.parts.onFailed(failure);
+  }
+}

package/src/core/offline/outbox-store.ts

@@ -0,0 +1,85 @@
+/**
+ * Where the outbox lives: one `localStorage` key per entry,
+ * `hub:<slug>:outbox:<id>`, read back in id (queue) order. A tab adding an
+ * entry and another removing one touch different keys, so neither loses the
+ * other's change. The outbox is capped by entry count and stored size.
+ */
+import { parseJsonText } from '../storage/json-guards';
+import type { KeyValueStore } from '../storage/key-value';
+import { readEntry, type OutboxEntry } from './outbox-entry';
+
+/** The most entries one game's outbox holds. */
+export const OUTBOX_MAX_ENTRIES = 500;
+
+/** The most stored characters one game's outbox holds (about 2 MB of `localStorage`). */
+export const OUTBOX_MAX_CHARS = 1_000_000;
+
+/** One game's outbox. */
+export class OutboxStore {
+  /** The key prefix of this game's entries. */
+  readonly prefix: string;
+  private readonly store: KeyValueStore;
+
+  /** The outbox for game `slug` in `store`. */
+  constructor(slug: string, store: KeyValueStore) {
+    this.prefix = `hub:${slug}:outbox:`;
+    this.store = store;
+  }
+
+  /** Every well-formed entry, oldest first. Malformed ones are removed. */
+  list(): OutboxEntry[] {
+    const entries: OutboxEntry[] = [];
+    for (const key of this.entryKeys()) {
+      const text = this.store.read(key);
+      const entry = text === null ? undefined : readEntry(parseJsonText(text));
+      if (entry === undefined) {
+        this.store.remove(key);
+      } else {
+        entries.push(entry);
+      }
+    }
+    return entries;
+  }
+
+  /** How many entries are queued. */
+  count(): number {
+    return this.entryKeys().length;
+  }
+
+  /** One entry, or `undefined` once it is gone (replayed, or removed by another tab). */
+  get(id: string): OutboxEntry | undefined {
+    const text = this.store.read(this.prefix + id);
+    return text === null ? undefined : readEntry(parseJsonText(text));
+  }
+
+  /** Whether `extra` more stored characters in one more entry still fit under the caps. */
+  fits(extraChars: number): boolean {
+    const keys = this.entryKeys();
+    if (keys.length >= OUTBOX_MAX_ENTRIES) {
+      return false;
+    }
+    const used = keys.reduce((total, key) => total + (this.store.read(key)?.length ?? 0), 0);
+    return used + extraChars <= OUTBOX_MAX_CHARS;
+  }
+
+  /** Store an entry (new or updated); `false` when the storage refused it (full or blocked). */
+  put(entry: OutboxEntry): boolean {
+    const text = JSON.stringify(entry);
+    this.store.write(this.prefix + entry.id, text);
+    return this.store.read(this.prefix + entry.id) === text;
+  }
+
+  /** Forget an entry. */
+  remove(id: string): void {
+    this.store.remove(this.prefix + id);
+  }
+
+  /** Whether a storage key belongs to this outbox (for cross-tab `storage` events). */
+  owns(key: string | null): boolean {
+    return key === null || key.startsWith(this.prefix);
+  }
+
+  private entryKeys(): string[] {
+    return this.store.keys().filter((key) => key.startsWith(this.prefix)).sort();
+  }
+}