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

package/src/avatar.ts

@@ -0,0 +1,62 @@
+/**
+ * `@diffenderfer-games/hub/avatar`: draw players' avatars in any game.
+ *
+ * ```ts
+ * import { ready, render, animator } from '@diffenderfer-games/hub/avatar';
+ *
+ * await ready();                                   // loads the art once
+ * el.innerHTML = render.svg(seat.look, { size: 48 });
+ * const anim = animator(seat.look, { seed: seat.userId });
+ * anim.express('happy');
+ * render.canvas(ctx, seat.look, { x, y, size: 64, pose: anim.pose(now) });
+ * ```
+ *
+ * The art loads lazily (`ready()`); before it does, renders draw the
+ * silhouette. Zero dependencies; the Pixi and three.js adapters take the
+ * library as an argument (`/avatar/pixi`, `/avatar/three`). Docs: "Avatars"
+ * in docs/hub.md.
+ *
+ * @packageDocumentation
+ */
+import { renderBitmap, renderDataUrl } from './avatar/outputs/bitmap';
+import { renderCanvas, renderCanvasAt } from './avatar/outputs/canvas';
+import { renderElement } from './avatar/outputs/element';
+import { renderSvg } from './avatar/outputs/svg';
+
+export {
+  ACCESSORY_SLOTS, CATALOG, CATALOG_REVISION, DEFAULT_GEN, LOOK_CODE_PREFIX, PALETTES,
+  canonicalLook, decodeLook, defaultLook, distinctLooks, encodeLook, isLookCode, isValidLook, lookProblem,
+  normaliseHex, partById, partName, partsOf, randomLook, resolveColour, sameLook, seededRng,
+  type AccessorySlot, type AvatarLook, type CatalogEntry, type DecodedLook, type LookAccessory, type LookColour,
+  type LookPart, type LookProblem, type PaletteName, type PartCategory, type Preset, type RandomLookOptions, type Rng,
+} from '@diffenderfer-games/hub-contract/avatar';
+export { ready, onArtReady } from './avatar/art-store';
+export { animator, Animator, type AnimatorOptions, type At, type Feeling } from './avatar/animator/animator';
+export { REACTIONS, type Reaction } from './avatar/animator/reactions';
+export { EXPRESSIONS, EXPRESSION_NAMES, expressionFromEmote, isExpression, mix, type BrowParams, type Expression, type FaceExtra, type FaceParams, type MouthParams } from './avatar/face';
+export { facingFrom, layout, lookToward } from './avatar/layout';
+export { avatarEmoji, describe } from './avatar/describe';
+export { defineAvatarElement } from './avatar/outputs/custom-element';
+export type { AvatarElement } from './avatar/outputs/element';
+export type { CanvasPlacement } from './avatar/outputs/canvas';
+export { overlays, type ActivityIcon, type Overlay, type ReactionGlyph } from './avatar/overlays';
+export { overlaySvg, paintOverlay } from './avatar/outputs/overlay-svg';
+export { catalog } from './avatar/catalog-view';
+export { composeAvatar, HEAD_Y, type Composed } from './avatar/render/compose';
+export { paintNodes, type Ctx2D } from './avatar/outputs/canvas-paint';
+export { sceneToSvg } from './avatar/outputs/svg-markup';
+export { toCode, toLook } from './avatar/look-like';
+export { contrast, deltaE, lightness } from './avatar/colour';
+export type { SceneNode } from './avatar/scene';
+export type { Anchor, BodyPose, Facing, Frame, LookDir, LookLike, Point, Pose, RenderOptions, StatusProp, View } from './avatar/render/types';
+export { AvatarAtlas, createAtlas, type AtlasFrame, type AtlasOptions } from './avatar/atlas';
+
+/** Every output: SVG markup, a live element, Canvas 2D, a bitmap or a data URL. */
+export const render = {
+  svg: renderSvg,
+  element: renderElement,
+  canvas: renderCanvas,
+  canvasAt: renderCanvasAt,
+  bitmap: renderBitmap,
+  dataUrl: renderDataUrl,
+};

package/src/core/avatar/avatar-cache.ts

@@ -0,0 +1,95 @@
+/**
+ * The device's avatar cache (avatars.md §5.6), so faces render offline:
+ * your own look (`hub:avatar:me`, read synchronously at startup) and an LRU
+ * of other players' codes (`hub:avatar:cache`, 200 entries).
+ */
+import { isLookCode } from '@diffenderfer-games/hub-contract/avatar';
+import { isRecord, optionalNumber, optionalString, parseJsonText } from '../storage/json-guards';
+import type { KeyValueStore } from '../storage/key-value';
+
+/** Your own look as cached. */
+export interface CachedMine {
+  readonly userId: number;
+  readonly code: string;
+  readonly isDefault: boolean;
+  readonly updatedAt: number;
+}
+
+const MINE_KEY = 'hub:avatar:me';
+const OTHERS_KEY = 'hub:avatar:cache';
+const OTHERS_MAX = 200;
+
+/** The device cache over a key-value store. */
+export class AvatarCache {
+  private readonly store: KeyValueStore;
+  private others: Map<number, string> | null = null;
+
+  constructor(store: KeyValueStore) {
+    this.store = store;
+  }
+
+  /** Your cached look, or `null` (never cached, or another player's on this device). */
+  readMine(userId: number | null): CachedMine | null {
+    const parsed = parseJsonText(this.store.read(MINE_KEY) ?? '');
+    if (!isRecord(parsed)) {
+      return null;
+    }
+    const id = optionalNumber(parsed.userId);
+    const code = optionalString(parsed.code);
+    if (id === undefined || code === undefined || !isLookCode(code) || (userId !== null && id !== userId)) {
+      return null;
+    }
+    return { userId: id, code, isDefault: parsed.isDefault === true, updatedAt: optionalNumber(parsed.updatedAt) ?? 0 };
+  }
+
+  /** Remember your look. */
+  writeMine(mine: CachedMine): void {
+    this.store.write(MINE_KEY, JSON.stringify(mine));
+    this.remember(mine.userId, mine.code);
+  }
+
+  /** A player's cached code, or `undefined`. */
+  codeOf(userId: number): string | undefined {
+    return this.loadOthers().get(userId);
+  }
+
+  /** Remember a player's code (most recent last; the oldest drop past 200). */
+  remember(userId: number, code: string): void {
+    if (code === '') {
+      return;
+    }
+    const others = this.loadOthers();
+    if (others.get(userId) === code) {
+      return;
+    }
+    others.delete(userId);
+    others.set(userId, code);
+    while (others.size > OTHERS_MAX) {
+      const oldest = others.keys().next().value;
+      if (oldest === undefined) {
+        break;
+      }
+      others.delete(oldest);
+    }
+    this.store.write(OTHERS_KEY, JSON.stringify([...others]));
+  }
+
+  private loadOthers(): Map<number, string> {
+    if (this.others !== null) {
+      return this.others;
+    }
+    const others = new Map<number, string>();
+    const parsed = parseJsonText(this.store.read(OTHERS_KEY) ?? '[]');
+    if (Array.isArray(parsed)) {
+      for (const entry of parsed) {
+        const id = Array.isArray(entry) ? optionalNumber(entry[0]) : undefined;
+        const code = Array.isArray(entry) ? optionalString(entry[1]) : undefined;
+        if (id !== undefined && code !== undefined && isLookCode(code)) {
+          others.set(id, code);
+        }
+      }
+    }
+    this.others = others;
+    return others;
+  }
+}

package/src/core/avatar/avatar-ref.ts

@@ -0,0 +1,34 @@
+/** Building {@link AvatarRef}s from codes, payloads and seeds. */
+import { decodeLook, defaultLook, encodeLook } from '@diffenderfer-games/hub-contract/avatar';
+import type { AvatarRef } from './avatar-types';
+
+/** A ref for a code (`''` = hidden). */
+export function refOf(code: string, isDefault = false): AvatarRef {
+  if (code === '') {
+    return { code: '', look: null, isDefault: false, hidden: true };
+  }
+  return { code, look: decodeLook(code)?.look ?? null, isDefault, hidden: false };
+}
+
+/** A seeded default look as a ref (bots, previews, local pass-and-play seats). */
+export function botRef(seed: string | number): AvatarRef {
+  const look = defaultLook(seed);
+  return { code: encodeLook(look), look, isDefault: true, hidden: false };
+}
+
+/** Anything that carries a player's look: a seat, a `PlayerLite`, a racer, a ticket user. */
+export interface CarriesLook {
+  readonly look?: string;
+  readonly userId?: number;
+  readonly id?: number;
+  readonly uid?: number;
+}
+
+/** The ref a payload carries; an old hub's payload (no `look`) falls back to the id's default. */
+export function refFrom(carrier: CarriesLook): AvatarRef {
+  if (carrier.look !== undefined) {
+    return refOf(carrier.look);
+  }
+  const id = carrier.userId ?? carrier.id ?? carrier.uid;
+  return id === undefined ? refOf('') : botRef(id);
+}

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

@@ -0,0 +1,43 @@
+/** The shapes `hub.avatar` works with (avatars.md §6). */
+import type { AvatarLook } from '@diffenderfer-games/hub-contract/avatar';
+
+/**
+ * A player's avatar as games hold it: the code (pass it to any renderer),
+ * the decoded look, whether it is their generated default, and whether the
+ * player is hidden from you (draw the silhouette).
+ */
+export interface AvatarRef {
+  readonly code: string;
+  /** `null` when hidden or the code is malformed (renderers draw the silhouette). */
+  readonly look: AvatarLook | null;
+  /** They never designed one: this is their generated default. */
+  readonly isDefault: boolean;
+  /** Hidden where the username is hidden (§2.8). */
+  readonly hidden: boolean;
+}
+
+/** A player's avatar changed (`hub.avatar.on('change')`). */
+export interface AvatarChange {
+  readonly userId: number;
+  readonly ref: AvatarRef;
+}
+
+/** Options for the designer. */
+export interface OpenDesignerOptions {
+  /** Why it opened (`'game'`, `'world'`, …), for metrics only. */
+  readonly reason?: string;
+}
+
+/** What the designer reports when it closes. */
+export interface DesignerResult {
+  /** The player saved a new look. */
+  readonly saved: boolean;
+}
+
+/** What the social runtime adds for avatars (feature version 5). */
+export interface RuntimeAvatarApi {
+  /** Open "Make your avatar" over the page; resolves when it closes. */
+  openDesigner(options?: OpenDesignerOptions): Promise<DesignerResult>;
+  /** Live `ev:avatar` changes (yours, friends', your room's). */
+  on(event: 'change', listener: (change: { readonly userId: number; readonly code: string }) => void): () => void;
+}

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

@@ -0,0 +1,308 @@
+/**
+ * `hub.avatar` (avatars.md §6): players' looks without the renderer. Codes
+ * arrive in payloads (seats, `PlayerLite`, racers), so `from()` needs no
+ * request; `of()` and `many()` batch and cache the rest; your own look is
+ * cached on the device so it works offline. `load()` brings in the renderer
+ * (`@diffenderfer-games/hub/avatar`) and its art when a game wants to draw.
+ *
+ * It follows the page's account (the menu's account events, the runtime's
+ * socket hello, this client's sign-ins): when your account appears or
+ * changes, or the hello says your look is not the one cached, your look is
+ * fetched again and `change` fires. Each hello also re-checks the players
+ * this page asked about, so a change sent while the socket was down is not
+ * missed.
+ */
+import type { MyAvatar } from '@diffenderfer-games/hub-contract';
+import { encodeLook, type AvatarLook } from '@diffenderfer-games/hub-contract/avatar';
+import type * as AvatarEntry from '../../avatar';
+import { pageBridge } from '../../realtime/bridge';
+import { createRuntimeOpener } from '../../realtime/runtime-opener';
+import type { AccountListener, PageUser } from '../page-account';
+import { AvatarCache } from './avatar-cache';
+import { botRef, refFrom, refOf, type CarriesLook } from './avatar-ref';
+import type { AvatarChange, AvatarRef, DesignerResult, OpenDesignerOptions } from './avatar-types';
+import { createPageStore } from '../storage/key-value';
+
+/** What `hub.avatar` needs from its client. */
+export interface AvatarHost {
+  /** The signed-in user's id, or `null` (`hub.userId()`). */
+  readonly currentUserId: () => number | null;
+  /** Hear every report of who is signed in (the page's account). */
+  readonly onAccount: (listener: AccountListener) => () => void;
+  /** `GET /avatar/me`; rejects when offline. */
+  readonly fetchMine: () => Promise<MyAvatar>;
+  /** `POST /avatar/batch`. */
+  readonly fetchCodes: (ids: readonly number[]) => Promise<Record<string, string>>;
+  /** Queue a save of your look (sent now when online, replayed later when not). */
+  readonly queueSave: (code: string, savedAt: number) => Promise<void>;
+}
+
+/** The renderer module `load()` resolves with. */
+export type AvatarModule = typeof AvatarEntry;
+
+type ChangeListener = (change: AvatarChange) => void;
+
+const BATCH_MAX = 100;
+const openWithRuntime = createRuntimeOpener(pageBridge);
+
+/** The look `mine()` gives before the account exists (a new guest's is being made). */
+const NO_ACCOUNT_YET = botRef('you');
+
+/** `hub.avatar`. */
+export class HubAvatar {
+  private readonly host: AvatarHost;
+  private readonly cache = new AvatarCache(createPageStore());
+  private readonly listeners = new Set<ChangeListener>();
+  private pending = new Map<number, ((code: string) => void)[]>();
+  private flushQueued = false;
+  private detachRuntime: (() => void) | null = null;
+  /** The account the last report named. */
+  private lastUserId: number | null;
+  /** The code of your look the page was last given (`mine`, `mineSync`, `change`). */
+  private mineShown: string | null = null;
+  /** Players this page asked about or was handed (re-checked on each socket hello). */
+  private readonly seen = new Set<number>();
+
+  constructor(host: AvatarHost) {
+    this.host = host;
+    this.lastUserId = host.currentUserId();
+    host.onAccount((user, source) => {
+      this.onAccount(user, source === 'session');
+    });
+  }
+
+  /**
+   * Your look (your default if you never designed one). Works offline from
+   * the device cache. Before your account exists (a new guest's is made just
+   * after the game starts) it resolves at once with a default look, and
+   * `change` brings yours when the account is there.
+   */
+  async mine(): Promise<AvatarRef> {
+    const userId = this.host.currentUserId();
+    if (userId === null) {
+      return this.showMine(NO_ACCOUNT_YET);
+    }
+    try {
+      const mine = await this.host.fetchMine();
+      return this.noteMine(userId, mine);
+    } catch (failure) {
+      const cached = this.mineSync();
+      if (cached !== null) {
+        return cached;
+      }
+      throw failure;
+    }
+  }
+
+  /** Your cached look, or your default; `null` only while nobody is signed in. */
+  mineSync(): AvatarRef | null {
+    const userId = this.host.currentUserId();
+    if (userId === null) {
+      return null;
+    }
+    const cached = this.cache.readMine(userId);
+    return this.showMine(cached === null ? botRef(userId) : refOf(cached.code, cached.isDefault));
+  }
+
+  /** Any player's look: from the cache, else batched with other requests in the same tick. */
+  of(userId: number): Promise<AvatarRef> {
+    this.seen.add(userId);
+    const cached = this.cache.codeOf(userId);
+    if (cached !== undefined) {
+      return Promise.resolve(refOf(cached));
+    }
+    return new Promise((resolve) => {
+      const waiting = this.pending.get(userId) ?? [];
+      waiting.push((code) => {
+        resolve(code === '' ? botRef(userId) : refOf(code));
+      });
+      this.pending.set(userId, waiting);
+      this.scheduleFlush();
+    });
+  }
+
+  /** Many players' looks at once. */
+  async many(userIds: readonly number[]): Promise<Map<number, AvatarRef>> {
+    const refs = await Promise.all(userIds.map(async (id) => [id, await this.of(id)] as const));
+    return new Map(refs);
+  }
+
+  /** The look a payload already carries (a `RoomSeat`, `PlayerLite`, racer or ticket user). No request. */
+  from(carrier: CarriesLook): AvatarRef {
+    const ref = refFrom(carrier);
+    const id = carrier.userId ?? carrier.id ?? carrier.uid;
+    if (id !== undefined && carrier.look !== undefined) {
+      this.seen.add(id);
+      this.cache.remember(id, carrier.look);
+    }
+    return ref;
+  }
+
+  /** A seeded default for bots, previews and local pass-and-play seats: `bot('local:2')`. */
+  bot(seed: string | number): AvatarRef {
+    return botRef(seed);
+  }
+
+  /** Save your look (designer code paths; queued offline, latest wins). */
+  async save(look: AvatarLook): Promise<AvatarRef> {
+    const code = encodeLook(look);
+    const savedAt = Date.now();
+    const userId = this.host.currentUserId();
+    if (userId !== null) {
+      this.noteMine(userId, { code, isDefault: false, updatedAt: savedAt });
+    }
+    await this.host.queueSave(code, savedAt);
+    return refOf(code);
+  }
+
+  /**
+   * Hear about look changes (yours, friends', your room's, and yours when
+   * your account appears). Returns the unsubscribe function. Wait for this
+   * rather than polling `mine()`.
+   */
+  on(_event: 'change', listener: ChangeListener): () => void {
+    this.listeners.add(listener);
+    this.attachRuntime();
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /** Open "Make your avatar" over the game; resolves when it closes. */
+  openDesigner(options: OpenDesignerOptions = {}): Promise<DesignerResult> {
+    return new Promise((resolve) => {
+      openWithRuntime((realtime) => {
+        if (realtime.avatar === undefined) {
+          resolve({ saved: false });
+          return;
+        }
+        void realtime.avatar.openDesigner(options).then(resolve, () => {
+          resolve({ saved: false });
+        });
+      });
+    });
+  }
+
+  /** Loads the renderer and its art; resolves when rendering is synchronous. */
+  async load(): Promise<AvatarModule> {
+    const avatar = await import('../../avatar');
+    await avatar.ready();
+    return avatar;
+  }
+
+  /** Remember the ref the page was given for your look. */
+  private showMine(ref: AvatarRef): AvatarRef {
+    this.mineShown = ref.code;
+    return ref;
+  }
+
+  /** Cache your look; `change` fires when it differs from the one the page last had. */
+  private noteMine(userId: number, mine: Pick<MyAvatar, 'code' | 'isDefault' | 'updatedAt'>): AvatarRef {
+    const before = this.mineShown ?? this.cache.readMine(userId)?.code ?? null;
+    this.cache.writeMine({ userId, code: mine.code, isDefault: mine.isDefault, updatedAt: mine.updatedAt });
+    const ref = this.showMine(refOf(mine.code, mine.isDefault));
+    if (mine.code !== before) {
+      this.emit({ userId, ref });
+    }
+    return ref;
+  }
+
+  /** Someone said who is signed in: fetch your look when the account is new or its look isn't the cached one. */
+  private onAccount(user: PageUser | null, isHello: boolean): void {
+    const userId = user === null || user.id === 0 ? null : user.id;
+    const isNewAccount = userId !== this.lastUserId;
+    this.lastUserId = userId;
+    if (user === null || userId === null) {
+      return;
+    }
+    if (isNewAccount || (user.look !== null && user.look !== this.cache.readMine(userId)?.code)) {
+      void this.refreshMine(userId);
+    }
+    if (isHello) {
+      void this.recheckSeen();
+    }
+  }
+
+  private async refreshMine(userId: number): Promise<void> {
+    const mine = await this.host.fetchMine().catch(() => null);
+    if (mine !== null && this.host.currentUserId() === userId) {
+      this.noteMine(userId, mine);
+    }
+  }
+
+  /** The socket (re)connected: a change sent while it was down never arrived, so ask again. */
+  private async recheckSeen(): Promise<void> {
+    if (this.listeners.size === 0 || this.seen.size === 0) {
+      return;
+    }
+    const codes = await this.fetchCodes([...this.seen]);
+    for (const [userId, code] of codes) {
+      if (code !== '' && code !== this.cache.codeOf(userId)) {
+        this.cache.remember(userId, code);
+        this.emit({ userId, ref: refOf(code) });
+      }
+    }
+  }
+
+  private emit(change: AvatarChange): void {
+    for (const listener of this.listeners) {
+      listener(change);
+    }
+  }
+
+  private attachRuntime(): void {
+    if (this.detachRuntime !== null) {
+      return;
+    }
+    this.detachRuntime = pageBridge.subscribe((realtime) => realtime.avatar?.on('change', ({ userId, code }) => {
+      if (userId === this.host.currentUserId()) {
+        this.noteMine(userId, { code, isDefault: false, updatedAt: Date.now() });
+        return;
+      }
+      this.cache.remember(userId, code);
+      this.emit({ userId, ref: refOf(code) });
+    }) ?? (() => undefined));
+  }
+
+  private scheduleFlush(): void {
+    if (this.flushQueued) {
+      return;
+    }
+    this.flushQueued = true;
+    queueMicrotask(() => {
+      this.flushQueued = false;
+      void this.flush();
+    });
+  }
+
+  private async flush(): Promise<void> {
+    const batch = this.pending;
+    this.pending = new Map();
+    const codes = await this.fetchCodes([...batch.keys()]);
+    for (const [id, waiting] of batch) {
+      const code = codes.get(id) ?? '';
+      if (code !== '') {
+        this.cache.remember(id, code);
+      }
+      for (const resolve of waiting) {
+        resolve(code);
+      }
+    }
+  }
+
+  /** Players' codes, in batches; offline or failing, the missing ones are left out (they get their default). */
+  private async fetchCodes(ids: readonly number[]): Promise<Map<number, string>> {
+    const codes = new Map<number, string>();
+    for (let i = 0; i < ids.length; i += BATCH_MAX) {
+      const slice = ids.slice(i, i + BATCH_MAX);
+      const answered = await this.host.fetchCodes(slice).catch((): Record<string, string> => ({}));
+      for (const id of slice) {
+        const code = answered[String(id)];
+        if (code !== undefined) {
+          codes.set(id, code);
+        }
+      }
+    }
+    return codes;
+  }
+}

package/src/core/connection.ts

@@ -12,6 +12,7 @@ import { LocalStore } from './offline/local-store';
 import { OfflineApi } from './offline/offline-api';
 import { Outbox, type OfflineOp } from './offline/outbox';
 import { LocalResumeStore } from './resume/local-resume';
+import { LocalDailyStore } from './saved/local-saved';
 import { absoluteApiBase, detectApiBase, detectSlug, emitWindowEvent, isBrowserPage } from './page';
 import { createRestClient, type RestClient } from './rest/rest-client';
 import { createPageStore } from './storage/key-value';
@@ -65,6 +66,8 @@ export class HubConnection {
   protected readonly outbox: Outbox;
   /** The device copies of every game's resume slot (`hub.resume`). */
   protected readonly resumeStore: LocalResumeStore;
+  /** The device copies of daily challenges in progress (every game's). */
+  protected readonly dailyStore: LocalDailyStore;
   private readonly offlineMode: NonNullable<HubOptions['offline']>;
   private isReachable = true;
   private runningSync: Promise<SyncResult> | null = null;
@@ -90,6 +93,7 @@ export class HubConnection {
     const pageStore = createPageStore();
     this.store = new LocalStore(this.slug ?? 'app', pageStore);
     this.resumeStore = new LocalResumeStore(pageStore);
+    this.dailyStore = new LocalDailyStore(pageStore);
     this.outbox = new Outbox({
       slug: this.slug ?? 'app',
       store: pageStore,
@@ -108,9 +112,13 @@ export class HubConnection {
     registerHubKinds(this.outbox, {
       game: () => this.gameFields(),
       onDailyComplete: (payload, completion) => {
+        if (this.slug !== null) {
+          this.dailyStore.remove(this.slug, payload.day);
+        }
         emitWindowEvent('hub:daily-complete', { day: payload.day, count: completion.count, rank: completion.rank, meta: payload.meta });
       },
       resume: this.resumeStore,
+      dailies: this.dailyStore,
       cloudSaves: this.store,
     });
     this.importLegacyQueue();

package/src/core/errors.ts

@@ -41,6 +41,8 @@ export interface HubErrorDetails {
   readonly retryAfterMs?: number | undefined;
   /** When a suspension or mute ends (epoch ms). */
   readonly until?: number | undefined;
+  /** An online game's rules refused a move (`illegal`): the rules' own short code. */
+  readonly rule?: string | undefined;
 }
 
 /**
@@ -62,6 +64,8 @@ export class HubError extends Error {
   readonly retryAfterMs: number | undefined;
   /** When a suspension or mute ends (epoch ms). */
   readonly until: number | undefined;
+  /** An online game's rules refused a move (`code` is `illegal`): the rules' own short code, such as `cell_taken`. */
+  readonly rule: string | undefined;
 
   /** An error with a player-safe `message`, the HTTP `status` (if any) and the body's extras. */
   constructor(message: string, status?: number, details: HubErrorDetails = {}) {
@@ -73,6 +77,7 @@ export class HubError extends Error {
     this.hint = details.hint;
     this.retryAfterMs = details.retryAfterMs;
     this.until = details.until;
+    this.rule = details.rule;
   }
 
   /** `true` when the failure was a network or transport error, not an HTTP status. */
@@ -122,12 +127,13 @@ export function readErrorFields(body: unknown): ErrorBodyFields {
     hint: optionalString(body.hint),
     retryAfterMs: optionalNumber(body.retryAfterMs),
     until: optionalNumber(body.until),
+    rule: optionalString(body.rule),
   };
 }
 
 /** The right error class for a failure: a 422 or `content_rejected` is a {@link ContentRejectedError}. */
 export function errorFor(message: string, status: number | undefined, details: HubErrorDetails): HubError {
-  return status === 422 || details.code === 'content_rejected'
+  return (status === 422 && details.code !== 'illegal') || details.code === 'content_rejected'
     ? new ContentRejectedError(message, status, details)
     : new HubError(message, status, details);
 }