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

package/src/daily/daily-system.ts

@@ -9,7 +9,8 @@
  * registered `play` on. Deep links (`/<slug>/?daily=YYYY-MM-DD`) auto-start.
  */
 import { readField } from '../realtime/cross-bundle';
-import type { DailyAll, DailyChallenge, DailyCompleteResponse, DailyCompletionMeta, DailyDefinition, DailyHost, DailyStatus } from './types';
+import type { SavedEntry } from '../core/saved/saved-types';
+import type { DailyAll, DailyChallenge, DailyCompleteResponse, DailyCompletionMeta, DailyDefinition, DailyHost, DailySaveInput, DailyStartResponse, DailyStatus } from './types';
 
 const DAY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
 
@@ -39,20 +40,32 @@ function messageOf(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+/** The challenge a start or resume answered. */
+function challengeOf(started: DailyStartResponse): DailyChallenge {
+  return {
+    day: started.day, seed: started.seed, token: started.token, alreadyCompleted: started.alreadyCompleted,
+    instanceId: started.instanceId, saved: started.saved, savedVersion: started.savedVersion, resumed: started.resumed,
+  };
+}
+
 /** Daily challenges (`hub.daily`). */
 export class DailySystem {
   /**
    * The challenge in progress: set when a day starts; cleared the moment the
    * game calls `complete` (whatever the hub answers, and before it answers)
-   * or `cancel`. A game's win handler checks it:
+   * or `cancel` (or `discard`). A game's win handler checks it:
    * `if (hub.daily.active) hub.daily.complete(…)`. While it is set the page
-   * is in a daily run, so `hub.resume.save` saves nothing: a game whose
-   * player leaves a daily unfinished must call `cancel()`.
+   * is in a daily run, so `hub.resume.save` saves to the day instead of the
+   * game's run: a game whose player leaves a daily unfinished must call
+   * `cancel()`.
    */
   active: DailyChallenge | null = null;
   private readonly host: DailyHost;
   private play: DailyDefinition['play'] | null = null;
   private pendingDay: string | null = null;
+  private pendingInstance: string | null = null;
+  /** A start on its way to the hub, so a resume of the same day waits for it instead of starting it twice. */
+  private inFlight: Promise<void> | null = null;
   private isRelaying = false;
 
   constructor(host: DailyHost) {
@@ -84,9 +97,13 @@ export class DailySystem {
   define(definition: DailyDefinition): void {
     this.play = definition.play;
     const day = readDeepLinkDay() ?? this.pendingDay;
+    const instanceId = this.pendingInstance;
     this.pendingDay = null;
+    this.pendingInstance = null;
     if (day !== null) {
       void this.startAndPlay(day);
+    } else if (instanceId !== null) {
+      void this.resume(instanceId);
     }
   }
 
@@ -103,17 +120,91 @@ export class DailySystem {
       this.relayStart(day);
       return;
     }
+    const starting = (async (): Promise<void> => {
+      try {
+        this.begin(play, challengeOf(await this.host.start(day)));
+      } catch (error) {
+        this.host.emit('hub:daily-error', { day, error: messageOf(error) });
+      }
+    })();
+    this.inFlight = starting;
+    await starting;
+    if (this.inFlight === starting) {
+      this.inFlight = null;
+    }
+  }
+
+  /**
+   * Pick up a day in progress by its saved game's id (from `hub.saved`):
+   * a fresh token, then the game's `play` with `challenge.saved`. Finishing
+   * it any time later gives that day's credit. A no-op while that day is
+   * already being played.
+   */
+  async resume(instanceId: string): Promise<void> {
+    // A start may be on its way for the same day (the `?daily=` link of the same open): let it land first.
+    await this.inFlight;
+    if (this.active?.instanceId === instanceId) {
+      return;
+    }
+    const play = this.play;
+    if (play === null) {
+      this.pendingInstance = instanceId;
+      return;
+    }
     try {
-      const started = await this.host.start(day);
-      const challenge: DailyChallenge = { day: started.day, seed: started.seed, token: started.token, alreadyCompleted: started.alreadyCompleted };
-      this.active = challenge;
-      this.host.emit('hub:daily-started', { day: started.day, seed: started.seed, alreadyCompleted: started.alreadyCompleted });
-      play({ ...challenge });
+      this.begin(play, challengeOf(await this.host.resume(instanceId)));
     } catch (error) {
-      this.host.emit('hub:daily-error', { day, error: messageOf(error) });
+      this.host.emit('hub:daily-error', { day: '', error: messageOf(error) });
     }
   }
 
+  /** Make `challenge` the active day and hand it to the game. */
+  private begin(play: DailyDefinition['play'], challenge: DailyChallenge): void {
+    this.active = challenge;
+    this.host.emit('hub:daily-started', { day: challenge.day, seed: challenge.seed, alreadyCompleted: challenge.alreadyCompleted === true, resumed: challenge.resumed === true });
+    if (challenge.resumed === true) {
+      this.host.emit('hub:daily-resumed', { day: challenge.day, seed: challenge.seed, alreadyCompleted: false, resumed: true });
+    }
+    play({ ...challenge });
+  }
+
+  /**
+   * Save the active day's state, so it can be picked up later (a reload,
+   * another device, next week) and still give that day's credit. Kept on
+   * the device at once and sent after a short quiet spell (works offline).
+   * `hub.resume.save` during a daily lands here too. Returns `false` with
+   * no daily active, or for a replay of a completed day (nothing to save).
+   */
+  save(input: DailySaveInput): boolean {
+    const challenge = this.active;
+    if (challenge === null || challenge.instanceId === null) {
+      return false;
+    }
+    return this.host.save(challenge, input);
+  }
+
+  /** This game's days in progress (the calendar marks them, the game can list them). */
+  inProgress(): Promise<SavedEntry[]> {
+    return this.host.inProgress();
+  }
+
+  /**
+   * Give up the active day: its progress is discarded and nothing is
+   * recorded. The day can be started again fresh while it is in the 30-day
+   * window. (The hub's lists ask the player first; a game asks for itself.)
+   */
+  async discard(): Promise<void> {
+    const challenge = this.active;
+    if (challenge === null) {
+      return;
+    }
+    this.active = null;
+    if (challenge.instanceId !== null) {
+      await this.host.discard(challenge);
+    }
+    this.host.emit('hub:daily-discarded', { day: challenge.day, discarded: true });
+  }
+
   /**
    * Record completion of the active challenge with optional metadata.
    * Resolves with the new completion count and rank, or `null` when no
@@ -157,12 +248,20 @@ export class DailySystem {
   }
 
   /**
-   * Abandon the active challenge without recording it: the player quit, or
-   * left the daily for normal play (another level, a new game). Until then
-   * the page counts as in a daily run and `hub.resume.save` saves nothing.
+   * Pause the active day: the player left it unfinished (quit, picked
+   * another level, started a normal game). Nothing is recorded, and the day
+   * stays in progress in "Your games" and the calendar, to finish later
+   * (its last save is sent now). Until then the page counts as in a daily,
+   * so `hub.resume.save` saves to the day: call `cancel()` on every path
+   * that leaves a daily without `complete`. To give a day up, `discard()`.
    */
   cancel(): void {
+    const challenge = this.active;
     this.active = null;
+    if (challenge !== null) {
+      void this.host.flush().catch(() => undefined);
+      this.host.emit('hub:daily-paused', { day: challenge.day, paused: true });
+    }
   }
 
   /** This game's window and the player's completions. */

package/src/daily/page-daily.ts

@@ -8,8 +8,8 @@ import { hasMethods } from '../realtime/cross-bundle';
 import { DailySystem } from './daily-system';
 import type { DailyHost } from './types';
 
-/** The cross-bundle shape number of the `daily` singleton. Bump only on an incompatible change. */
-export const DAILY_SINGLETON_API = 1;
+/** The cross-bundle shape number of the `daily` singleton (2 added save, resume, discard and inProgress). Bump only on an incompatible change. */
+export const DAILY_SINGLETON_API = 2;
 
 /** Whether `candidate` is some bundle's daily system (v1 copies included). */
 // eslint-disable-next-line no-restricted-syntax -- trust boundary: the instance may come from another bundle

package/src/daily/types.ts

@@ -3,12 +3,14 @@
  * answers (typed from the contract's daily endpoints).
  */
 import type { dailyEndpoints, Json } from '@diffenderfer-games/hub-contract';
+import type { GamePayload } from '../core/game-data';
+import type { SavedEntry } from '../core/saved/saved-types';
 import type { SchemaOutput } from '../realtime/wire-types';
 
 /** The response type of a daily endpoint. */
 type DailyResponse<Name extends keyof typeof dailyEndpoints> = SchemaOutput<(typeof dailyEndpoints)[Name]['cfg']['response']>;
 
-/** This game's daily window and the player's completions (`GET /games/:slug/daily`). */
+/** This game's daily window, the player's completions and days in progress (`GET /games/:slug/daily`). */
 export type DailyStatus = DailyResponse<'getGameDailyChallenges'>;
 
 /** Every daily game and the global standings (`GET /daily`). */
@@ -17,7 +19,7 @@ export type DailyAll = DailyResponse<'listDailyChallengesForAllGames'>;
 /** One game's row in {@link DailyAll}. */
 export type DailyGameStatus = DailyAll['games'][number];
 
-/** The answer to starting a day: its seed and the signed token to present on completion. */
+/** The answer to starting (or resuming) a day: its seed, the signed token to present on completion, and its saved game. */
 export type DailyStartResponse = DailyResponse<'startDailyChallenge'>;
 
 /** The answer to completing a day: the player's new completion count and rank. */
@@ -25,26 +27,49 @@ export type DailyCompleteResponse = DailyResponse<'completeDailyChallenge'>;
 
 /** The challenge a game's `play` receives: set up and start exactly this day (derive the level from `seed`). */
 export interface DailyChallenge {
-  /** The day, `YYYY-MM-DD`. */
+  /** The day, `YYYY-MM-DD` (a UTC day key). */
   day: string;
   /** Deterministic per game and day. */
   seed: number;
-  /** The signed token `complete` presents. */
+  /** The signed token `complete` presents (empty for a day started offline: it is fetched when the hub is back). */
   token: string;
-  /** The player already completed this day (a replay). */
+  /** The player already completed this day (a replay for fun: nothing is saved or recorded). */
   alreadyCompleted?: boolean;
+  /** The day's saved game; `null` for a replay of a completed day. */
+  instanceId: string | null;
+  /**
+   * The state last saved for this day (`hub.daily.save`, or `hub.resume.save`
+   * during the daily), or `null` when the day starts fresh. A game that
+   * saves restores from it: `if (challenge.saved) startFrom(challenge.saved)`.
+   */
+  saved: GamePayload | null;
+  /** The game's state version of `saved` (0 when none). */
+  savedVersion: number;
+  /** The day was already in progress and was picked up again. */
+  resumed?: boolean;
 }
 
 /** What `hub.daily.define` takes. */
 export interface DailyDefinition {
-  /** Start this challenge now. */
+  /** Start this challenge now (restore `challenge.saved` when it has one). */
   play: (challenge: DailyChallenge) => void;
 }
 
 /** Metadata a game records with a completion (`{ score, difficulty, timeMs, … }`). */
 export type DailyCompletionMeta = Record<string, Json>;
 
-/** What the daily system needs from the hub client: the REST calls and its window events. */
+/** A daily state save (the same shape as `hub.resume.save`). */
+export interface DailySaveInput {
+  /** Everything needed to rebuild the day's run (up to 512 KB as JSON). */
+  readonly state: GamePayload;
+  /** A short line ("34 cards left") and an optional 0 to 1 fraction. */
+  readonly progress: { readonly label: string; readonly fraction?: number | null };
+  readonly title?: string | null;
+  /** The game's state version (default 0). */
+  readonly version?: number;
+}
+
+/** What the daily system needs from the hub client: the REST calls, the device copy and its window events. */
 export interface DailyHost {
   /** This page's game slug. */
   readonly slug: string | null;
@@ -52,17 +77,29 @@ export interface DailyHost {
   status(): Promise<DailyStatus>;
   /** `GET /daily`. */
   all(): Promise<DailyAll>;
-  /** `POST /games/:slug/daily/:day/start`. */
+  /** Start (or pick up) a day: `POST /games/:slug/daily/:day/start`, or a device-only start while offline. */
   start(day: string): Promise<DailyStartResponse>;
+  /** Pick a day in progress up again by its saved game's id. */
+  resume(instanceId: string): Promise<DailyStartResponse>;
   /** `POST /games/:slug/daily/:day/complete`; `null` when it was queued offline, to replay when the hub is back. */
   complete(day: string, token: string, meta: DailyCompletionMeta): Promise<DailyCompleteResponse | null>;
+  /** Keep the day's state on the device at once and send it soon (works offline); `false` when it can't be stored. */
+  save(challenge: DailyChallenge, input: DailySaveInput): boolean;
+  /** Send a waiting save now. */
+  flush(): Promise<void>;
+  /** Give the day up: discard its saved game (works offline). */
+  discard(challenge: DailyChallenge): Promise<void>;
+  /** This game's days in progress (the saved games of kind daily). */
+  inProgress(): Promise<SavedEntry[]>;
   /** Fire a `hub:*` window event (the menu listens). */
   emit(name: string, detail: DailyEventDetail): void;
 }
 
 /** The detail of the `hub:daily-*` window events. */
 export type DailyEventDetail =
-  | { day: string; seed: number; alreadyCompleted: boolean }
+  | { day: string; seed: number; alreadyCompleted: boolean; resumed?: boolean }
   | { day: string; count: number; rank: number | null; meta: DailyCompletionMeta }
   | { day: string; queued: true; meta: DailyCompletionMeta }
+  | { day: string; paused: true }
+  | { day: string; discarded: true }
   | { day: string; error: string };

package/src/doctor/hub-version-fetch.ts

@@ -1,43 +1,43 @@
-/**
- * Reading the hub's `GET /_api/version` for `hub-doctor`, with a timeout so a
- * hung or unreachable hub fails a game's CI quickly instead of stalling it.
- */
-import { HubVersion } from '@diffenderfer-games/hub-contract';
-
-/** How long the doctor waits for the hub by default, ms. */
-export const DEFAULT_HUB_TIMEOUT_MS = 10_000;
-
-/** The hub could not be asked: down, slow, or answering with an error. */
-export interface HubUnreachable {
-  /** The URL that was asked. */
-  readonly unreachableUrl: string;
-  /** Why, for the message (`timed out after 10000 ms`, `HTTP 502`, a network error). */
-  readonly reason: string;
-}
-
-/** Whether a version lookup failed. */
-export function isHubUnreachable(lookup: HubVersion | null | HubUnreachable): lookup is HubUnreachable {
-  return lookup !== null && 'unreachableUrl' in lookup;
-}
-
-/**
- * The hub's version: `null` for a hub from before versioning (404), a
- * {@link HubUnreachable} when it can't be read within `timeoutMs`.
- */
-export async function fetchHubVersion(hubUrl: string, timeoutMs: number = DEFAULT_HUB_TIMEOUT_MS): Promise<HubVersion | null | HubUnreachable> {
-  const url = new URL('/_api/version', hubUrl).toString();
-  try {
-    const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
-    if (response.status === 404) {
-      return null;
-    }
-    if (!response.ok) {
-      return { unreachableUrl: url, reason: `HTTP ${String(response.status)}` };
-    }
-    return HubVersion.parse(await response.json());
-  } catch (failure) {
-    const isTimeout = failure instanceof Error && (failure.name === 'TimeoutError' || failure.name === 'AbortError');
-    const reason = isTimeout ? `timed out after ${String(timeoutMs)} ms` : failure instanceof Error ? failure.message : String(failure);
-    return { unreachableUrl: url, reason };
-  }
-}
+/**
+ * Reading the hub's `GET /_api/version` for `hub-doctor`, with a timeout so a
+ * hung or unreachable hub fails a game's CI quickly instead of stalling it.
+ */
+import { HubVersion } from '@diffenderfer-games/hub-contract';
+
+/** How long the doctor waits for the hub by default, ms. */
+export const DEFAULT_HUB_TIMEOUT_MS = 10_000;
+
+/** The hub could not be asked: down, slow, or answering with an error. */
+export interface HubUnreachable {
+  /** The URL that was asked. */
+  readonly unreachableUrl: string;
+  /** Why, for the message (`timed out after 10000 ms`, `HTTP 502`, a network error). */
+  readonly reason: string;
+}
+
+/** Whether a version lookup failed. */
+export function isHubUnreachable(lookup: HubVersion | null | HubUnreachable): lookup is HubUnreachable {
+  return lookup !== null && 'unreachableUrl' in lookup;
+}
+
+/**
+ * The hub's version: `null` for a hub from before versioning (404), a
+ * {@link HubUnreachable} when it can't be read within `timeoutMs`.
+ */
+export async function fetchHubVersion(hubUrl: string, timeoutMs: number = DEFAULT_HUB_TIMEOUT_MS): Promise<HubVersion | null | HubUnreachable> {
+  const url = new URL('/_api/version', hubUrl).toString();
+  try {
+    const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+    if (response.status === 404) {
+      return null;
+    }
+    if (!response.ok) {
+      return { unreachableUrl: url, reason: `HTTP ${String(response.status)}` };
+    }
+    return HubVersion.parse(await response.json());
+  } catch (failure) {
+    const isTimeout = failure instanceof Error && (failure.name === 'TimeoutError' || failure.name === 'AbortError');
+    const reason = isTimeout ? `timed out after ${String(timeoutMs)} ms` : failure instanceof Error ? failure.message : String(failure);
+    return { unreachableUrl: url, reason };
+  }
+}

package/src/index.ts

@@ -17,7 +17,7 @@
  * queue their own operations with `hub.offline` (docs: "Offline and replay").
  *
  * The page-wide namespaces hang off `hub` as lazy getters (`hub.input`,
- * `hub.daily`, `hub.resume`, `hub.social`, `hub.mp`, `hub.rooms`, `hub.race`), and each has
+ * `hub.daily`, `hub.resume`, `hub.saved`, `hub.social`, `hub.mp`, `hub.rooms`, `hub.race`), and each has
  * its own entry (`@diffenderfer-games/hub/input`, ...) for games that want
  * only that part.
  *
@@ -28,6 +28,7 @@ export {
   ContentRejectedError,
   HubError,
   OfflineError,
+  SAVE_UNKNOWN_CODE,
   UNSUPPORTED_BY_HUB,
   type HubErrorCode,
   type HubErrorDetails,
@@ -37,7 +38,16 @@ export type { AuthResponse, ProfileUpdate, StatResult } from './core/hub-progres
 export type { GrantBundle, TradeBundle, TradeId, TradeListOptions, TradeNoteOptions } from './core/hub-economy';
 export type { HubMenuControl } from './core/menu-control';
 export { HubResume, RESUME_DEBOUNCE_MS, RESUME_MAX_STATE_BYTES } from './core/resume/hub-resume';
+export { HubAvatar, type AvatarHost, type AvatarModule } from './core/avatar/hub-avatar';
+export type { AvatarChange, AvatarRef, DesignerResult, OpenDesignerOptions, RuntimeAvatarApi } from './core/avatar/avatar-types';
+export type { CarriesLook } from './core/avatar/avatar-ref';
 export type { ResumeBlocker, ResumeEntry, ResumeLoadOptions, ResumeProgress, ResumeRun, ResumeSaveInput } from './core/resume/resume-types';
+export { HubSaved, SAVED_CHANGE_QUIET_MS, type SavedChangeListener, type SavedOpenDetail, type SavedOpenHandler } from './core/saved/hub-saved';
+export { SAVED_CHANGE_EVENT, SAVED_KIND_PARAM, SAVED_OPEN_EVENT, SAVED_OPEN_PARAM, savedGameUrl } from './core/saved/saved-open';
+export type * from './core/saved/saved-types';
+export { HubTurns, TURN_LINK_PARAM, type TurnCreateOptions } from './core/turns/hub-turns';
+export { TURN_CHAT_EVENT, TURN_EVENT, TURN_POLL_MS, TURN_RESYNC_EVENT, TurnGame, type TurnGameEvents, type TurnMoveEvent, type TurnOutcome } from './core/turns/turn-game';
+export type { OpenTurnGame, TurnChatLine, TurnDeadline, TurnGameView } from '@diffenderfer-games/hub-contract';
 export type { QueueOp, QueueOpInput, QueuedScoreOptions, ProfilePatch } from './core/offline/queue';
 export { OfflineApi } from './core/offline/offline-api';
 export { OUTBOX_FULL_CODE, type OfflineEventDetails, type OfflineEventName, type OfflineListener, type OfflineOp } from './core/offline/outbox';

package/src/input/input-system.ts

@@ -18,7 +18,7 @@ import type { ModalityTracker } from './modality';
 import { parseLegacyControls } from './legacy-controls';
 import type { LegacyControls } from './legacy-controls';
 import { Navigator } from './navigator';
-import type { NavigatorContext } from './navigator';
+import type { AutoNavigateTarget, NavigatorContext } from './navigator';
 import { feedDeviceState, OnScreenControls } from './on-screen-controls';
 import type { PageInputControl } from './page-control';
 import { describeBinding, PlayerRemaps } from './player-remaps';
@@ -286,6 +286,15 @@ export class InputSystem implements ControlsPanelHost, PageInputControl {
     this.navigator.setAutoNavigate(Navigator.queryFor(selector), options?.back ?? null);
   }
 
+  /**
+   * The game's current `autoNavigate` target (its query and back action), or
+   * `null`. Hub UI that takes the gamepad for a while (a dialog) reads it,
+   * and gives it back with `autoNavigate(target.query, { back })` when done.
+   */
+  autoNavigateTarget(): AutoNavigateTarget | null {
+    return this.navigator.autoNavigateTarget();
+  }
+
   /** Stop navigating the game's own menu. */
   clearAutoNavigate(): void {
     this.navigator.clearAutoNavigate(this.controls.existingOverlay);

package/src/input/navigator.ts

@@ -40,6 +40,12 @@ function visibleMatches(selector: string): HTMLElement[] {
   return [...document.querySelectorAll<HTMLElement>(selector)].filter((element) => element.getClientRects().length > 0);
 }
 
+/** What `autoNavigate` was last given: the targets' query and the back action. */
+export interface AutoNavigateTarget {
+  readonly query: () => NavTarget[];
+  readonly back: (() => void) | null;
+}
+
 /** A navigable group with its highlight state. */
 interface GroupNavigation {
   readonly definition: NavigableDef;
@@ -81,6 +87,11 @@ export class Navigator {
     this.autoNavigateState = null;
   }
 
+  /** The current auto-navigate target and back action, or `null` when none is set. */
+  autoNavigateTarget(): AutoNavigateTarget | null {
+    return this.autoNavigateQuery === null ? null : { query: this.autoNavigateQuery, back: this.autoNavigateBack };
+  }
+
   /** Make a CSS selector's visible matches the auto-navigate targets. */
   static queryFor(selector: string | (() => NavTarget[])): () => NavTarget[] {
     return typeof selector === 'string' ? () => visibleMatches(selector) : selector;

package/src/input.ts

@@ -15,6 +15,7 @@ export type { InputModality } from './input/modality';
 export { isPageInputControl } from './input/page-control';
 export type { PageInputControl } from './input/page-control';
 export type * from './input/types';
+export type { AutoNavigateTarget } from './input/navigator';
 export { Overlay } from './overlay/overlay';
 export { layoutControls } from './overlay/layout';
 export type { LayoutOptions } from './overlay/layout';

package/src/overlay/overlay.ts

@@ -123,9 +123,15 @@ export class Overlay implements NavHighlighter {
     }
   }
 
-  /** Game insets (px) auto-placed controls keep clear of, e.g. a top HUD bar. Merged with earlier calls. */
+  /**
+   * Game insets (px) auto-placed controls keep clear of, e.g. a top HUD bar.
+   * Merged with earlier calls. Also published on the page as
+   * `--hub-inset-top` (and right, bottom, left), so the hub's toasts sit
+   * below a top HUD too.
+   */
   setInsets(insets: Partial<Insets>): void {
     this.gameInsets = { ...this.gameInsets, ...insets };
+    publishInsets(this.gameInsets);
     this.layout();
   }
 
@@ -208,3 +214,21 @@ export class Overlay implements NavHighlighter {
     return { top: pixels(style.paddingTop), right: pixels(style.paddingRight), bottom: pixels(style.paddingBottom), left: pixels(style.paddingLeft) };
   }
 }
+
+/** Every inset side. */
+const INSET_SIDES: readonly (keyof Insets)[] = ['top', 'right', 'bottom', 'left'];
+
+/** The page-wide CSS variables other hub UI (the runtime's toasts) keeps clear of. */
+function publishInsets(insets: Partial<Insets>): void {
+  if (typeof document === 'undefined') {
+    return;
+  }
+  for (const side of INSET_SIDES) {
+    const px = insets[side];
+    if (px === undefined) {
+      document.documentElement.style.removeProperty(`--hub-inset-${side}`);
+    } else {
+      document.documentElement.style.setProperty(`--hub-inset-${side}`, `${String(Math.max(0, Math.round(px)))}px`);
+    }
+  }
+}

package/src/realtime/runtime-api.ts

@@ -3,6 +3,7 @@
  * the page, and that `hub.presence`, `hub.social`, `hub.mp`, `hub.rooms`,
  * `hub.notify` and `hub.race` forward to.
  */
+import type { RuntimeAvatarApi } from '../core/avatar/avatar-types';
 import type { HubMpApi, InviteLinkMethods } from './multiplayer-types';
 import type { HubRaceApi } from './race-types';
 import type { HubRoomsApi, RoomReclaimMethods } from './room-types';
@@ -11,10 +12,10 @@ import type { HubNotifyApi, HubPresenceApi, HubSocialApi, PlayOnlineMethods } fr
 /**
  * The realtime feature version the runtime reports in {@link RealtimeApi.version}.
  * 2 added races; 3 added invite links and taking back a held seat; 4 added
- * "Play online" (tournaments). A client feature-detects newer additions with
- * it (or by the optional method).
+ * "Play online" (tournaments); 5 added avatars (the designer and `ev:avatar`).
+ * A client feature-detects newer additions with it (or by the optional method).
  */
-export const REALTIME_FEATURE_VERSION = 4;
+export const REALTIME_FEATURE_VERSION = 5;
 
 /** `hub.social` as a runtime installs it: version 4's `openPlayOnline` is missing on older runtimes. */
 export type RuntimeSocialApi = Omit<HubSocialApi, keyof PlayOnlineMethods> & Partial<PlayOnlineMethods>;
@@ -35,6 +36,14 @@ export const REALTIME_SINGLETON_API = 1;
 /** The window event the runtime fires once it has installed itself. */
 export const REALTIME_READY_EVENT = 'hub:rt-ready';
 
+/**
+ * The window event the runtime fires each time its socket says hello (it
+ * connected, or connected again after a drop), with `{ user: { id, look } }`
+ * from the hello snapshot. `hub.avatar` and `hub.userId()` follow it; changes
+ * sent while the socket was down are fetched again.
+ */
+export const SESSION_EVENT = 'hub:session';
+
 /** The window event the menu fires when the runtime failed to load (its reason is on `window.__HUB_RT_ERROR__`). */
 export const REALTIME_FAILED_EVENT = 'hub:rt-failed';
 
@@ -57,4 +66,6 @@ export interface RealtimeApi {
   notify: HubNotifyApi;
   /** Races (feature version 2 and later). */
   race?: HubRaceApi;
+  /** Avatars: the designer and live changes (feature version 5 and later). */
+  avatar?: RuntimeAvatarApi;
 }

package/src/social.ts

@@ -14,5 +14,6 @@ export {
   REALTIME_FEATURE_VERSION,
   REALTIME_READY_EVENT,
   REALTIME_SINGLETON_API,
+  SESSION_EVENT,
 } from './realtime/runtime-api';
 export type * from './realtime/types';