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

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

package/src/core/hub-progress.ts

@@ -9,6 +9,7 @@ import { HubConnection } from './connection';
 import { HubError, SAVE_UNKNOWN_CODE } from './errors';
 import { toGameData, toStoredJson, type GamePayload } from './game-data';
 import { PROGRESS_KINDS, type ProfilePayload, type ScorePayload } from './offline/hub-kinds';
+import { pageAccount, toPageUser } from './page-account';
 import { isRecord } from './storage/json-guards';
 import type { LeaderboardResult, MeResponse, Profile, Save, SaveMeta, SubmitScoreOptions, SubmitScoreResult, User } from './types';
 
@@ -46,9 +47,30 @@ function typedSave<TData>(save: Save | null): Save<TData> | null {
 
 /** Accounts, profile, saves, stats and leaderboards. */
 export class HubProgress extends HubConnection {
+  /** Who the page is signed in as, as the hub's events and this client's sign-ins tell it. */
+  protected readonly account = pageAccount();
+
+  /**
+   * Your user id, or `null` when nobody is signed in (also before an offline
+   * first visit has an account). Synchronous, and it follows the account as
+   * the hub changes it (a new guest's account made by the menu, sign-in,
+   * sign-out) with no `hub.me()` needed. Compare it with a seat's `userId`
+   * to find yours.
+   */
+  userId(): number | null {
+    const heard = this.account.user;
+    const id = heard === undefined ? this.store.getUser()?.id ?? null : heard?.id ?? null;
+    // 0 is an offline local guest: no account on the hub yet.
+    return id === 0 ? null : id;
+  }
+
   /** The current user (or `null`) and the games they have a profile in. */
   me(): Promise<MeResponse> {
-    return this.withFallback(() => this.rest.call('getCurrentUser'), () => {
+    return this.withFallback(async () => {
+      const reply = await this.rest.call('getCurrentUser');
+      this.account.note(reply.user === null ? null : toPageUser(reply.user));
+      return reply;
+    }, () => {
       const profile = this.store.getProfile();
       return { user: this.store.getUser(), profiles: profile === null ? [] : [{ game: profile.game, displayName: profile.displayName }] };
     });
@@ -65,9 +87,7 @@ export class HubProgress extends HubConnection {
       if (known !== null) {
         return { user: known };
       }
-      const guest: User = { id: 0, username: 'Guest-local', guest: true };
-      this.store.setUser(guest);
-      return { user: guest };
+      return this.signInLocally({ id: 0, username: 'Guest-local', guest: true });
     });
   }
 
@@ -94,25 +114,36 @@ export class HubProgress extends HubConnection {
   logout(): Promise<{ ok: true }> {
     return this.withFallback(async () => {
       const reply = await this.rest.call('logOut');
-      this.store.clearUser();
+      this.signedOut();
       return reply;
     }, () => {
-      this.store.clearUser();
+      this.signedOut();
       return { ok: true } as const;
     });
   }
 
   private signInLocally(user: User): AuthResponse {
-    this.store.setUser(user);
+    this.remember(user);
     return { user };
   }
 
   /** Remember who the hub signed in, so the cache's notes about the hub's copies are read for the right player. */
   private signedIn(reply: AuthResponse): AuthResponse {
-    this.store.setUser(reply.user);
+    this.remember(reply.user);
     return reply;
   }
 
+  /** The cache and the page (`hub.userId()`, `hub.avatar`) learn who is signed in. */
+  private remember(user: User): void {
+    this.store.setUser(user);
+    this.account.note(toPageUser(user));
+  }
+
+  private signedOut(): void {
+    this.store.clearUser();
+    this.account.note(null);
+  }
+
   /** This game's profile for the current user, or `profile: null`. `TData` is the game's own data type. */
   getProfile<TData = Json>(): Promise<{ profile: Profile<TData> | null }> {
     return this.withFallback(