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

package/src/core/offline/hub-kinds/daily-kind.ts

@@ -0,0 +1,68 @@
+/**
+ * The hub's daily kind, a composite op: complete a day with the token the
+ * game started it with; when that token has expired by the time the op
+ * replays (401), start the day again for a fresh token and complete with
+ * that. The completion is replayable, so a retry after a lost reply never
+ * records it twice. A completion sent at once (online) is reported by the
+ * daily system itself; one that replays later is reported here.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import { HubError } from '../../errors';
+import type { EndpointReply } from '../../rest/endpoint-types';
+import { isJsonObject, isRecord, optionalNumber, optionalString } from '../../storage/json-guards';
+import { checkedKind } from '../kind-adapters';
+import type { RegisteredKind } from '../outbox-kinds';
+import type { GameFieldsSource } from './game-fields';
+
+/** One daily completion. */
+export type DailyPayload = { readonly day: string; readonly token: string; readonly meta: { readonly [key: string]: Json } };
+
+/** The kind name. */
+export const DAILY_KIND = 'hub.daily';
+
+/** What a completion answers. */
+export type DailyCompletion = EndpointReply<'completeDailyChallenge'>;
+
+function readDaily(stored: Json): DailyPayload | undefined {
+  if (!isRecord(stored) || !isJsonObject(stored.meta)) {
+    return undefined;
+  }
+  const day = optionalString(stored.day);
+  const token = optionalString(stored.token);
+  return day === undefined || token === undefined ? undefined : { day, token, meta: stored.meta };
+}
+
+/** A completion reply read back, or `undefined` when it doesn't read as one. */
+export function readDailyCompletion(result: Json | undefined): DailyCompletion | undefined {
+  if (!isRecord(result) || result.ok !== true) {
+    return undefined;
+  }
+  const day = optionalString(result.day);
+  const count = optionalNumber(result.count);
+  const rank = result.rank === null ? null : optionalNumber(result.rank);
+  return day === undefined || count === undefined || rank === undefined ? undefined : { ok: true, day, count, rank };
+}
+
+/** The daily kind, by name; `onCompleted` hears each completion that lands from the queue. */
+export function dailyKinds(game: GameFieldsSource, onCompleted: (payload: DailyPayload, completion: DailyCompletion) => void): Record<string, RegisteredKind> {
+  return {
+    [DAILY_KIND]: checkedKind(readDaily, {
+      run: async ({ day, token, meta }, context) => {
+        let completion: DailyCompletion;
+        try {
+          completion = await context.call('completeDailyChallenge', { ...game(), day, token, meta });
+        } catch (failure) {
+          if (!(failure instanceof HubError) || failure.status !== 401) {
+            throw failure;
+          }
+          const started = await context.call('startDailyChallenge', { ...game(), day });
+          completion = await context.call('completeDailyChallenge', { ...game(), day, token: started.token, meta });
+        }
+        if (context.isReplay) {
+          onCompleted({ day, token, meta }, completion);
+        }
+        return completion;
+      },
+    }),
+  };
+}

package/src/core/offline/hub-kinds/economy-kinds.ts

@@ -0,0 +1,86 @@
+/**
+ * The hub's economy and catalog kinds: inventory grants and house
+ * exchanges (each one replayable call, never folded: every grant counts),
+ * and starring a game (a game's last star or unstar wins).
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import { isRecord, optionalNumber, optionalString } from '../../storage/json-guards';
+import { checkedKind } from '../kind-adapters';
+import type { GoodsPayload } from '../local-inventory';
+import type { RegisteredKind } from '../outbox-kinds';
+import type { GameFieldsSource } from './game-fields';
+
+/** A house exchange: what the player gives up and gets. */
+export type ExchangePayload = { readonly take?: GoodsPayload; readonly give?: GoodsPayload };
+
+/** A star or unstar. */
+export type FavoritePayload = { readonly slug: string; readonly on: boolean };
+
+/** The kind names. */
+export const ECONOMY_KINDS = { grant: 'hub.grant', exchange: 'hub.exchange', favorite: 'hub.favorite' } as const;
+
+/** Goods read back, or `undefined` when malformed. */
+export function readGoods(stored: Json | undefined): GoodsPayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const coins = stored.coins === undefined ? undefined : optionalNumber(stored.coins);
+  if (stored.coins !== undefined && coins === undefined) {
+    return undefined;
+  }
+  const items: Record<string, number> = {};
+  if (stored.items !== undefined) {
+    if (!isRecord(stored.items)) {
+      return undefined;
+    }
+    for (const [key, qty] of Object.entries(stored.items)) {
+      const count = optionalNumber(qty);
+      if (count === undefined) {
+        return undefined;
+      }
+      items[key] = count;
+    }
+  }
+  return { ...(stored.items === undefined ? {} : { items }), ...(coins === undefined ? {} : { coins }) };
+}
+
+function readExchange(stored: Json): ExchangePayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const take = stored.take === undefined ? undefined : readGoods(stored.take);
+  const give = stored.give === undefined ? undefined : readGoods(stored.give);
+  if ((stored.take !== undefined && take === undefined) || (stored.give !== undefined && give === undefined)) {
+    return undefined;
+  }
+  return { ...(take === undefined ? {} : { take }), ...(give === undefined ? {} : { give }) };
+}
+
+function readFavorite(stored: Json): FavoritePayload | undefined {
+  if (!isRecord(stored) || typeof stored.on !== 'boolean') {
+    return undefined;
+  }
+  const slug = optionalString(stored.slug);
+  return slug === undefined ? undefined : { slug, on: stored.on };
+}
+
+/** The economy kinds, by name; `onFavorites` hears the starred list each star answers with. */
+export function economyKinds(game: GameFieldsSource, onFavorites: (games: string[]) => void): Record<string, RegisteredKind> {
+  return {
+    [ECONOMY_KINDS.grant]: checkedKind(readGoods, {
+      run: (goods, context) => context.call('grantInventoryItems', { ...game(), ...goods }),
+    }),
+    [ECONOMY_KINDS.exchange]: checkedKind(readExchange, {
+      run: (exchange, context) => context.call('exchangeInventoryItems', { ...game(), ...exchange }),
+    }),
+    [ECONOMY_KINDS.favorite]: checkedKind(readFavorite, {
+      mergeKey: (favorite) => favorite.slug,
+      replaces: true,
+      run: async (favorite, context) => {
+        const reply = await context.call('setGameFavorite', { slug: favorite.slug, on: favorite.on });
+        onFavorites(reply.games);
+        return reply;
+      },
+    }),
+  };
+}

package/src/core/offline/hub-kinds/game-fields.ts

@@ -0,0 +1,2 @@
+/** The `{ slug }` path field the hub kinds' calls need, read when they run (it throws when the slug is unknown). */
+export type GameFieldsSource = () => { readonly slug: string };

package/src/core/offline/hub-kinds/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Every kind the hub itself queues offline (`hub.*`), registered on a
+ * client's outbox. The docs' "Offline and replay" table lists them.
+ */
+import { writeLocalFavorites } from '../favorites';
+import type { Outbox } from '../outbox';
+import { dailyKinds, type DailyCompletion, type DailyPayload } from './daily-kind';
+import { economyKinds } from './economy-kinds';
+import type { GameFieldsSource } from './game-fields';
+import { progressKinds } from './progress-kinds';
+
+export { DAILY_KIND, type DailyPayload } from './daily-kind';
+export { ECONOMY_KINDS, type ExchangePayload, type FavoritePayload } from './economy-kinds';
+export { legacyOperation } from './legacy-ops';
+export { PROGRESS_KINDS, type ProfilePayload, type SavePayload, type ScorePayload, type StatPayload } from './progress-kinds';
+
+/** What the hub kinds report back to their client. */
+export interface HubKindHooks {
+  /** This game's `{ slug }`. */
+  readonly game: GameFieldsSource;
+  /** A daily completion landed (the menu's calendar listens for `hub:daily-complete`). */
+  readonly onDailyComplete: (payload: DailyPayload, completion: DailyCompletion) => void;
+}
+
+/** Register every hub kind on `outbox`. */
+export function registerHubKinds(outbox: Outbox, hooks: HubKindHooks): void {
+  const kinds = {
+    ...progressKinds(hooks.game),
+    ...dailyKinds(hooks.game, hooks.onDailyComplete),
+    ...economyKinds(hooks.game, writeLocalFavorites),
+  };
+  for (const [kind, definition] of Object.entries(kinds)) {
+    outbox.define(kind, definition);
+  }
+}

package/src/core/offline/hub-kinds/legacy-ops.ts

@@ -0,0 +1,37 @@
+/**
+ * The v1 client's queued writes (`hub:<slug>:queue`) as outbox operations,
+ * so a page upgraded from a vendored copy still replays what that copy queued.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import type { QueueOp } from '../queue';
+import { PROGRESS_KINDS, readProfile, readScoreOptions } from './progress-kinds';
+
+/** One outbox operation, before it is stamped. */
+export interface KindedPayload {
+  readonly kind: string;
+  readonly payload: Json;
+}
+
+/** The outbox operation for a v1 queued write, or `undefined` when it no longer reads as one. */
+export function legacyOperation(op: QueueOp): KindedPayload | undefined {
+  switch (op.kind) {
+    case 'putSave':
+      return { kind: PROGRESS_KINDS.save, payload: { slot: op.slot, data: op.data, label: op.label } };
+    case 'deleteSave':
+      return { kind: PROGRESS_KINDS.save, payload: { slot: op.slot, deleted: true } };
+    case 'setStat':
+      return { kind: PROGRESS_KINDS.stat, payload: { key: op.key, mode: 'set', value: op.value } };
+    case 'maxStat':
+      return { kind: PROGRESS_KINDS.stat, payload: { key: op.key, mode: 'max', value: op.value } };
+    case 'incrStat':
+      return { kind: PROGRESS_KINDS.stat, payload: { key: op.key, mode: 'incr', value: op.amount } };
+    case 'submitScore': {
+      const opts = readScoreOptions({ ...op.opts });
+      return opts === undefined ? undefined : { kind: PROGRESS_KINDS.score, payload: { key: op.key, score: op.score, opts } };
+    }
+    case 'setProfile': {
+      const patch = readProfile({ ...op.patch });
+      return patch === undefined ? undefined : { kind: PROGRESS_KINDS.profile, payload: patch };
+    }
+  }
+}

package/src/core/offline/hub-kinds/progress-kinds.ts

@@ -0,0 +1,148 @@
+/**
+ * The hub's progress kinds: saves, stats, scores and the game profile. Each
+ * is one replayable call, and each folds new writes into waiting ones so the
+ * backlog stays small: a save slot's last write wins, `incr`s add up, `max`es
+ * keep the largest, `set`s keep the last, a board keeps its best, and profile
+ * patches merge.
+ */
+import type { Json, SortDir } from '@diffenderfer-games/hub-contract';
+import { isJson, isNullableString, isRecord, optionalNumber, optionalString } from '../../storage/json-guards';
+import { checkedKind } from '../kind-adapters';
+import type { RegisteredKind } from '../outbox-kinds';
+import { betterScore } from '../queue';
+import type { GameFieldsSource } from './game-fields';
+
+/** A save slot write: new contents, or a delete. */
+export type SavePayload =
+  | { readonly slot: string; readonly data: Json; readonly label: string | null }
+  | { readonly slot: string; readonly deleted: true };
+
+/** How a stat update combines with the stored value. */
+export type StatMode = 'set' | 'incr' | 'max';
+
+/** One stat update. */
+export type StatPayload = { readonly key: string; readonly mode: StatMode; readonly value: number };
+
+/** A score's board options, as queued. */
+export type ScoreOptionsPayload = { readonly title?: string; readonly sort?: SortDir; readonly meta?: Json };
+
+/** One score submission. */
+export type ScorePayload = { readonly key: string; readonly score: number; readonly opts: ScoreOptionsPayload };
+
+/** A profile change; either part may be left out. */
+export type ProfilePayload = { readonly displayName?: string | null; readonly data?: Json };
+
+/** The kind names. */
+export const PROGRESS_KINDS = { save: 'hub.save', stat: 'hub.stat', score: 'hub.score', profile: 'hub.profile' } as const;
+
+function readSave(stored: Json): SavePayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const slot = optionalString(stored.slot);
+  if (slot === undefined) {
+    return undefined;
+  }
+  if (stored.deleted === true) {
+    return { slot, deleted: true };
+  }
+  return isJson(stored.data) && isNullableString(stored.label) ? { slot, data: stored.data, label: stored.label } : undefined;
+}
+
+function readStat(stored: Json): StatPayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const key = optionalString(stored.key);
+  const value = optionalNumber(stored.value);
+  const mode = stored.mode === 'set' || stored.mode === 'incr' || stored.mode === 'max' ? stored.mode : undefined;
+  return key === undefined || value === undefined || mode === undefined ? undefined : { key, mode, value };
+}
+
+/** Score options read back, or `undefined` when malformed. */
+export function readScoreOptions(stored: Json): ScoreOptionsPayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const title = optionalString(stored.title);
+  const sort = stored.sort === 'asc' || stored.sort === 'desc' ? stored.sort : undefined;
+  if (stored.meta !== undefined && !isJson(stored.meta)) {
+    return undefined;
+  }
+  return { ...(title === undefined ? {} : { title }), ...(sort === undefined ? {} : { sort }), ...(stored.meta === undefined ? {} : { meta: stored.meta }) };
+}
+
+function readScore(stored: Json): ScorePayload | undefined {
+  if (!isRecord(stored) || !isJson(stored.opts)) {
+    return undefined;
+  }
+  const key = optionalString(stored.key);
+  const score = optionalNumber(stored.score);
+  const opts = readScoreOptions(stored.opts);
+  return key === undefined || score === undefined || opts === undefined ? undefined : { key, score, opts };
+}
+
+/** A profile patch read back, or `undefined` when malformed. */
+export function readProfile(stored: Json): ProfilePayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const { displayName, data: profileData } = stored;
+  if ((displayName !== undefined && !isNullableString(displayName)) || (profileData !== undefined && !isJson(profileData))) {
+    return undefined;
+  }
+  return { ...(displayName === undefined ? {} : { displayName }), ...(profileData === undefined ? {} : { data: profileData }) };
+}
+
+/** Two waiting stat updates of one key folded together, or `undefined` when their modes differ. */
+export function mergeStats(waiting: StatPayload, incoming: StatPayload): StatPayload | undefined {
+  if (waiting.mode !== incoming.mode) {
+    return undefined;
+  }
+  switch (incoming.mode) {
+    case 'incr':
+      return { ...waiting, value: waiting.value + incoming.value };
+    case 'max':
+      return { ...waiting, value: Math.max(waiting.value, incoming.value) };
+    case 'set':
+      return incoming;
+  }
+}
+
+/** The progress kinds, by name. */
+export function progressKinds(game: GameFieldsSource): Record<string, RegisteredKind> {
+  return {
+    [PROGRESS_KINDS.save]: checkedKind(readSave, {
+      mergeKey: (save) => save.slot,
+      replaces: true,
+      run: async (save, context) => {
+        if ('deleted' in save) {
+          await context.call('deleteSave', { ...game(), slot: save.slot });
+        } else {
+          await context.call('writeSave', { ...game(), slot: save.slot, data: save.data, label: save.label });
+        }
+      },
+    }),
+    [PROGRESS_KINDS.stat]: checkedKind(readStat, {
+      mergeKey: (stat) => stat.key,
+      merge: mergeStats,
+      run: async (stat, context) => {
+        await context.call('updateGameStat', { ...game(), key: stat.key, value: stat.value, mode: stat.mode });
+      },
+    }),
+    [PROGRESS_KINDS.score]: checkedKind(readScore, {
+      mergeKey: (submission) => submission.key,
+      merge: (waiting, incoming) => ({ ...waiting, score: betterScore(waiting.score, incoming.score, incoming.opts.sort), opts: incoming.opts }),
+      run: async (submission, context) => {
+        await context.call('submitScore', { ...game(), key: submission.key, score: submission.score, ...submission.opts });
+      },
+    }),
+    [PROGRESS_KINDS.profile]: checkedKind(readProfile, {
+      mergeKey: () => 'profile',
+      merge: (waiting, incoming) => ({ ...waiting, ...incoming }),
+      run: async (patch, context) => {
+        await context.call('setGameProfile', { ...game(), ...patch });
+      },
+    }),
+  };
+}

package/src/core/offline/kind-adapters.ts

@@ -0,0 +1,48 @@
+/**
+ * Turning a typed kind definition into the JSON-in, JSON-out form the outbox
+ * runs: the hub's kinds check their stored payloads with a reader; a game's
+ * kinds vouch for their own payload type, as with saves.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import { toGameData, toStoredJson, type GamePayload } from '../game-data';
+import type { OfflineHandler, OfflineKindDefinition, RegisteredKind } from './outbox-kinds';
+
+/** Reads a stored payload back, or `undefined` when it is malformed. */
+export type PayloadReader<Payload> = (stored: Json) => Payload | undefined;
+
+/** A kind whose payloads are checked by `read` (the hub's own kinds). */
+export function checkedKind<Payload extends Json>(read: PayloadReader<Payload>, definition: OfflineKindDefinition<Payload>): RegisteredKind {
+  const readOrThrow = (stored: Json): Payload => {
+    const payload = read(stored);
+    if (payload === undefined) {
+      throw new Error('Malformed offline operation payload.');
+    }
+    return payload;
+  };
+  const { mergeKey, merge } = definition;
+  return {
+    run: (stored, context) => definition.run(readOrThrow(stored), context),
+    accepts: (stored) => read(stored) !== undefined,
+    ...(mergeKey === undefined ? {} : { mergeKey: (stored: Json) => mergeKey(readOrThrow(stored)) }),
+    ...(merge === undefined ? {} : { merge: (waiting: Json, incoming: Json) => merge(readOrThrow(waiting), readOrThrow(incoming)) }),
+    replaces: definition.replaces === true,
+  };
+}
+
+/** A game's kind: a bare handler or a full definition, its payload typed by the game. */
+export function gameKind<Payload extends GamePayload>(definition: OfflineHandler<Payload> | OfflineKindDefinition<Payload>): RegisteredKind {
+  const full: OfflineKindDefinition<Payload> = typeof definition === 'function' ? { run: definition } : definition;
+  const { mergeKey, merge } = full;
+  return {
+    run: (stored, context) => full.run(toGameData<Payload>(stored), context),
+    accepts: () => true,
+    ...(mergeKey === undefined ? {} : { mergeKey: (stored: Json) => mergeKey(toGameData<Payload>(stored)) }),
+    ...(merge === undefined ? {} : {
+      merge: (waiting: Json, incoming: Json) => {
+        const merged = merge(toGameData<Payload>(waiting), toGameData<Payload>(incoming));
+        return merged === undefined ? undefined : toStoredJson(merged);
+      },
+    }),
+    replaces: full.replaces === true,
+  };
+}

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,18 @@
 /**
  * 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 { 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 +86,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()) {
@@ -197,26 +199,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. */

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