@diffenderfer-games/hub 2.0.0-next.0 → 2.0.0-next.2

package/src/core/offline/queue.ts

@@ -1,171 +1,126 @@
-/**
- * The offline mutation queue. Writes apply to the local cache at once and
- * queue a durable op; when the hub is reachable again the queue replays in
- * order. Ops collapse as they are queued (a save's last write wins, `incr`s
- * add up, `max`es keep the largest, a board keeps its best, profile patches
- * merge), so the backlog stays small.
- *
- * The op shapes are the v1 client's, unchanged: a page upgraded from a
- * vendored copy replays the queue that copy left in `localStorage`.
- */
-import type { Json } from '@diffenderfer-games/hub-contract';
-import type { SortDir } from '@diffenderfer-games/hub-contract';
-import { isJson, isNullableString, isRecord, optionalNumber, optionalString, type UncheckedRecord } from '../storage/json-guards';
-
-/** A score submission's options as queued (the metadata already JSON). */
-export interface QueuedScoreOptions {
-  /** The board's title; only used when the board key is first created. */
-  readonly title?: string;
-  /** The sort direction; only used on board creation. Default `desc`. */
-  readonly sort?: SortDir;
-  /** Any JSON stored with the entry (a character, a run seed). */
-  readonly meta?: Json;
-}
-
-/** A profile change: either part may be left out. */
-export interface ProfilePatch {
-  /** Shown to other players; `null` clears it. */
-  displayName?: string | null;
-  /** The game's own profile data. */
-  data?: Json;
-}
-
-/** A queued op's id and when it was queued. */
-interface QueueStamp {
-  /** Unique within this page: `<epoch ms>-<sequence>`. */
-  readonly id: string;
-  /** When it was queued (epoch ms). */
-  readonly ts: number;
-}
-
-/** A queued write, before it is stamped. */
-export type QueueOpInput =
-  | { readonly kind: 'putSave'; readonly slot: string; readonly data: Json; readonly label: string | null }
-  | { readonly kind: 'deleteSave'; readonly slot: string }
-  | { readonly kind: 'setStat'; readonly key: string; readonly value: number }
-  | { readonly kind: 'maxStat'; readonly key: string; readonly value: number }
-  | { readonly kind: 'incrStat'; readonly key: string; readonly amount: number }
-  | { readonly kind: 'submitScore'; readonly key: string; readonly score: number; readonly opts: QueuedScoreOptions }
-  | { readonly kind: 'setProfile'; readonly patch: ProfilePatch };
-
-/** A queued write, as stored under `hub:<slug>:queue`. */
-export type QueueOp = QueueOpInput & QueueStamp;
-
-/** The score options in a stored op, or `undefined` when they are malformed. */
-function readScoreOptions(stored: UncheckedRecord): QueuedScoreOptions | 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 }) };
-}
-
-/** The profile patch in a stored op, or `undefined` when it is malformed. */
-function readProfilePatch(stored: UncheckedRecord): ProfilePatch | undefined {
-  if ((stored.displayName !== undefined && !isNullableString(stored.displayName)) || (stored.data !== undefined && !isJson(stored.data))) {
-    return undefined;
-  }
-  const patch: ProfilePatch = {};
-  if (stored.displayName !== undefined) {
-    patch.displayName = stored.displayName;
-  }
-  if (stored.data !== undefined) {
-    patch.data = stored.data;
-  }
-  return patch;
-}
-
-/** One stored op's write, or `undefined` when it is not a known, well-formed op. */
-function readOpInput(stored: UncheckedRecord): QueueOpInput | undefined {
-  const slot = optionalString(stored.slot);
-  const key = optionalString(stored.key);
-  const statValue = optionalNumber(stored.value);
-  switch (stored.kind) {
-    case 'putSave':
-      return slot !== undefined && isJson(stored.data) && isNullableString(stored.label) ? { kind: 'putSave', slot, data: stored.data, label: stored.label } : undefined;
-    case 'deleteSave':
-      return slot === undefined ? undefined : { kind: 'deleteSave', slot };
-    case 'setStat':
-    case 'maxStat':
-      return key !== undefined && statValue !== undefined ? { kind: stored.kind, key, value: statValue } : undefined;
-    case 'incrStat': {
-      const amount = optionalNumber(stored.amount);
-      return key !== undefined && amount !== undefined ? { kind: 'incrStat', key, amount } : undefined;
-    }
-    case 'submitScore': {
-      const score = optionalNumber(stored.score);
-      const opts = isRecord(stored.opts) ? readScoreOptions(stored.opts) : undefined;
-      return key !== undefined && score !== undefined && opts !== undefined ? { kind: 'submitScore', key, score, opts } : undefined;
-    }
-    case 'setProfile': {
-      const patch = isRecord(stored.patch) ? readProfilePatch(stored.patch) : undefined;
-      return patch === undefined ? undefined : { kind: 'setProfile', patch };
-    }
-    default:
-      return undefined;
-  }
-}
-
-/** The well-formed ops of a stored queue, in order; anything malformed is dropped. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: a queue read back from localStorage (possibly written by a v1 client)
-export function readQueue(stored: unknown): QueueOp[] {
-  if (!Array.isArray(stored)) {
-    return [];
-  }
-  return stored.flatMap((entry): QueueOp[] => {
-    if (!isRecord(entry)) {
-      return [];
-    }
-    const input = readOpInput(entry);
-    const id = optionalString(entry.id);
-    const ts = optionalNumber(entry.ts);
-    return input === undefined || id === undefined || ts === undefined ? [] : [{ ...input, id, ts }];
-  });
-}
-
-/** The better of two scores on a board sorted `sort` (`desc` by default). */
-export function betterScore(first: number, second: number, sort: SortDir | undefined): number {
-  return sort === 'asc' ? Math.min(first, second) : Math.max(first, second);
-}
-
-/** The op that `queued` becomes when `incoming` collapses into it, or `undefined` when they don't collapse. */
-function collapsedOp(queued: QueueOp, incoming: QueueOp): QueueOp | undefined {
-  if (queued.kind === 'incrStat' && incoming.kind === 'incrStat' && queued.key === incoming.key) {
-    return { ...queued, amount: queued.amount + incoming.amount };
-  }
-  if (queued.kind === 'maxStat' && incoming.kind === 'maxStat' && queued.key === incoming.key) {
-    return { ...queued, value: Math.max(queued.value, incoming.value) };
-  }
-  if (queued.kind === 'setStat' && incoming.kind === 'setStat' && queued.key === incoming.key) {
-    return { ...queued, value: incoming.value };
-  }
-  if (queued.kind === 'submitScore' && incoming.kind === 'submitScore' && queued.key === incoming.key) {
-    return { ...queued, score: betterScore(queued.score, incoming.score, incoming.opts.sort), opts: incoming.opts };
-  }
-  if (queued.kind === 'setProfile' && incoming.kind === 'setProfile') {
-    return { ...queued, patch: { ...queued.patch, ...incoming.patch } };
-  }
-  return undefined;
-}
-
-/** Whether an op writes save slot `slot`. */
-function writesSlot(op: QueueOp, slot: string): boolean {
-  return (op.kind === 'putSave' || op.kind === 'deleteSave') && op.slot === slot;
-}
-
-/**
- * The queue with `incoming` added: a save or delete replaces any queued
- * write to the same slot (and goes last); a compatible op merges into the
- * first queued one in place; anything else is appended.
- */
-export function enqueueOp(queue: readonly QueueOp[], incoming: QueueOp): QueueOp[] {
-  if (incoming.kind === 'putSave' || incoming.kind === 'deleteSave') {
-    return [...queue.filter((op) => !writesSlot(op, incoming.slot)), incoming];
-  }
-  const mergeAt = queue.findIndex((op) => collapsedOp(op, incoming) !== undefined);
-  if (mergeAt < 0) {
-    return [...queue, incoming];
-  }
-  return queue.map((op, i) => (i === mergeAt ? (collapsedOp(op, incoming) ?? op) : op));
-}
+/**
+ * The v1 client's offline queue (`hub:<slug>:queue`): its op shapes and the
+ * reader for what a vendored v1 copy left in `localStorage`. This client
+ * queues into the outbox instead (`outbox.ts`) and moves any v1 ops there on
+ * start (`hub-kinds/legacy-ops.ts`), so nothing a v1 copy queued is lost.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import type { SortDir } from '@diffenderfer-games/hub-contract';
+import { isJson, isNullableString, isRecord, optionalNumber, optionalString, type UncheckedRecord } from '../storage/json-guards';
+
+/** A score submission's options as queued (the metadata already JSON). */
+export interface QueuedScoreOptions {
+  /** The board's title; only used when the board key is first created. */
+  readonly title?: string;
+  /** The sort direction; only used on board creation. Default `desc`. */
+  readonly sort?: SortDir;
+  /** Any JSON stored with the entry (a character, a run seed). */
+  readonly meta?: Json;
+}
+
+/** A profile change: either part may be left out. */
+export interface ProfilePatch {
+  /** Shown to other players; `null` clears it. */
+  displayName?: string | null;
+  /** The game's own profile data. */
+  data?: Json;
+}
+
+/** A queued op's id and when it was queued. */
+interface QueueStamp {
+  /** Unique within this page: `<epoch ms>-<sequence>`. */
+  readonly id: string;
+  /** When it was queued (epoch ms). */
+  readonly ts: number;
+}
+
+/** A queued write, before it is stamped. */
+export type QueueOpInput =
+  | { readonly kind: 'putSave'; readonly slot: string; readonly data: Json; readonly label: string | null }
+  | { readonly kind: 'deleteSave'; readonly slot: string }
+  | { readonly kind: 'setStat'; readonly key: string; readonly value: number }
+  | { readonly kind: 'maxStat'; readonly key: string; readonly value: number }
+  | { readonly kind: 'incrStat'; readonly key: string; readonly amount: number }
+  | { readonly kind: 'submitScore'; readonly key: string; readonly score: number; readonly opts: QueuedScoreOptions }
+  | { readonly kind: 'setProfile'; readonly patch: ProfilePatch };
+
+/** A queued write, as stored under `hub:<slug>:queue`. */
+export type QueueOp = QueueOpInput & QueueStamp;
+
+/** The score options in a stored op, or `undefined` when they are malformed. */
+function readScoreOptions(stored: UncheckedRecord): QueuedScoreOptions | 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 }) };
+}
+
+/** The profile patch in a stored op, or `undefined` when it is malformed. */
+function readProfilePatch(stored: UncheckedRecord): ProfilePatch | undefined {
+  if ((stored.displayName !== undefined && !isNullableString(stored.displayName)) || (stored.data !== undefined && !isJson(stored.data))) {
+    return undefined;
+  }
+  const patch: ProfilePatch = {};
+  if (stored.displayName !== undefined) {
+    patch.displayName = stored.displayName;
+  }
+  if (stored.data !== undefined) {
+    patch.data = stored.data;
+  }
+  return patch;
+}
+
+/** One stored op's write, or `undefined` when it is not a known, well-formed op. */
+function readOpInput(stored: UncheckedRecord): QueueOpInput | undefined {
+  const slot = optionalString(stored.slot);
+  const key = optionalString(stored.key);
+  const statValue = optionalNumber(stored.value);
+  switch (stored.kind) {
+    case 'putSave':
+      return slot !== undefined && isJson(stored.data) && isNullableString(stored.label) ? { kind: 'putSave', slot, data: stored.data, label: stored.label } : undefined;
+    case 'deleteSave':
+      return slot === undefined ? undefined : { kind: 'deleteSave', slot };
+    case 'setStat':
+    case 'maxStat':
+      return key !== undefined && statValue !== undefined ? { kind: stored.kind, key, value: statValue } : undefined;
+    case 'incrStat': {
+      const amount = optionalNumber(stored.amount);
+      return key !== undefined && amount !== undefined ? { kind: 'incrStat', key, amount } : undefined;
+    }
+    case 'submitScore': {
+      const score = optionalNumber(stored.score);
+      const opts = isRecord(stored.opts) ? readScoreOptions(stored.opts) : undefined;
+      return key !== undefined && score !== undefined && opts !== undefined ? { kind: 'submitScore', key, score, opts } : undefined;
+    }
+    case 'setProfile': {
+      const patch = isRecord(stored.patch) ? readProfilePatch(stored.patch) : undefined;
+      return patch === undefined ? undefined : { kind: 'setProfile', patch };
+    }
+    default:
+      return undefined;
+  }
+}
+
+/** The well-formed ops of a stored queue, in order; anything malformed is dropped. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a queue read back from localStorage (possibly written by a v1 client)
+export function readQueue(stored: unknown): QueueOp[] {
+  if (!Array.isArray(stored)) {
+    return [];
+  }
+  return stored.flatMap((entry): QueueOp[] => {
+    if (!isRecord(entry)) {
+      return [];
+    }
+    const input = readOpInput(entry);
+    const id = optionalString(entry.id);
+    const ts = optionalNumber(entry.ts);
+    return input === undefined || id === undefined || ts === undefined ? [] : [{ ...input, id, ts }];
+  });
+}
+
+/** The better of two scores on a board sorted `sort` (`desc` by default). */
+export function betterScore(first: number, second: number, sort: SortDir | undefined): number {
+  return sort === 'asc' ? Math.min(first, second) : Math.max(first, second);
+}

package/src/core/offline/replay-lease.ts

@@ -0,0 +1,87 @@
+/**
+ * One replayer at a time per game, across tabs and across the client copies
+ * on one page: a Web Lock where the browser has them, else a lease in
+ * `localStorage` that its holder renews while it works and that lapses if
+ * the tab dies. A replayer that can't get it simply doesn't run; the holder
+ * replays for everyone.
+ */
+import { isRecord, optionalNumber, optionalString, parseJsonText } from '../storage/json-guards';
+import type { KeyValueStore } from '../storage/key-value';
+
+/** Runs work while holding the lease. */
+export interface ReplayLease {
+  /** Run `work` holding the lease; `false` (without running it) when another replayer holds it. */
+  hold(work: () => Promise<void>): Promise<boolean>;
+}
+
+/** How long a `localStorage` lease lasts without renewal. */
+export const STORAGE_LEASE_MS = 15_000;
+
+/** How often the holder renews it. */
+const RENEW_EVERY_MS = 5_000;
+
+/** A lease on the Web Locks API. */
+function webLockLease(locks: LockManager, name: string): ReplayLease {
+  return {
+    hold: (work) => locks.request(name, { ifAvailable: true }, async (lock) => {
+      if (lock === null) {
+        return false;
+      }
+      await work();
+      return true;
+    }),
+  };
+}
+
+/** The lease's holder and expiry, or `undefined` when there is none. */
+function readLease(text: string | null): { readonly owner: string; readonly until: number } | undefined {
+  const stored = text === null ? undefined : parseJsonText(text);
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const owner = optionalString(stored.owner);
+  const until = optionalNumber(stored.until);
+  return owner === undefined || until === undefined ? undefined : { owner, until };
+}
+
+/** A lease kept in `store` under `key`, for pages without Web Locks. */
+export function storageLease(store: KeyValueStore, key: string, now: () => number = Date.now): ReplayLease {
+  const owner = `${String(now())}-${Math.random().toString(36).slice(2)}`;
+  const claim = (): boolean => {
+    const current = readLease(store.read(key));
+    if (current !== undefined && current.owner !== owner && current.until > now()) {
+      return false;
+    }
+    store.write(key, JSON.stringify({ owner, until: now() + STORAGE_LEASE_MS }));
+    return readLease(store.read(key))?.owner === owner;
+  };
+  return {
+    async hold(work) {
+      if (!claim()) {
+        return false;
+      }
+      const renewal = setInterval(claim, RENEW_EVERY_MS);
+      try {
+        await work();
+      } finally {
+        clearInterval(renewal);
+        if (readLease(store.read(key))?.owner === owner) {
+          store.remove(key);
+        }
+      }
+      return true;
+    },
+  };
+}
+
+/** The page's Web Locks, when it has them. */
+function pageLocks(): LockManager | undefined {
+  return typeof navigator !== 'undefined' && 'locks' in navigator ? navigator.locks : undefined;
+}
+
+/** The lease for game `slug`'s outbox: a Web Lock when available, else one in `store`. */
+export function createReplayLease(slug: string, store: KeyValueStore): ReplayLease {
+  const name = `hub:${slug}:outbox-lease`;
+  const locks = pageLocks();
+  return locks === undefined ? storageLease(store, name) : webLockLease(locks, name);
+}

package/src/core/offline/replay-policy.ts

@@ -0,0 +1,52 @@
+/**
+ * What a failed replay does next, and how long it waits:
+ *
+ * - `offline`: the hub (or the network) can't be reached. The op stays at
+ *   the head of the queue and replay waits for the connection.
+ * - `retry`: the hub answered with a passing problem (408, 429, 5xx) or a
+ *   game handler's fetch failed. The op stays at the head and is retried with
+ *   backoff, up to {@link MAX_RETRIES} times, then dropped.
+ * - `drop`: the hub refused it (any other status) or the handler threw
+ *   something else. The op is dropped and reported, and the queue moves on.
+ */
+import { HubError } from '../errors';
+
+/** What to do after a failed replay. */
+export type FailureVerdict = 'offline' | 'retry' | 'drop';
+
+/** The most tries for an op that keeps getting a passing failure. */
+export const MAX_RETRIES = 8;
+
+/** The first retry's delay. */
+const BASE_DELAY_MS = 1000;
+
+/** The longest delay between tries. */
+const MAX_DELAY_MS = 60_000;
+
+/** Statuses that mean "try again later". */
+const PASSING_STATUSES: ReadonlySet<number> = new Set([408, 425, 429]);
+
+/** The verdict for a failure. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: whatever a replay handler threw
+export function verdictFor(failure: unknown): FailureVerdict {
+  if (failure instanceof HubError) {
+    if (failure.status === undefined) {
+      return 'offline';
+    }
+    return failure.status >= 500 || PASSING_STATUSES.has(failure.status) ? 'retry' : 'drop';
+  }
+  // A game handler's own fetch rejects with a TypeError when the network is down.
+  return failure instanceof TypeError ? 'retry' : 'drop';
+}
+
+/** The delay before try `attempts + 1`: doubling from 1 s, capped at 60 s, with jitter so tabs and players spread out. */
+export function backoffMs(attempts: number, random: () => number = Math.random): number {
+  const ceiling = Math.min(MAX_DELAY_MS, BASE_DELAY_MS * 2 ** Math.max(0, attempts - 1));
+  return Math.round(ceiling / 2 + (ceiling / 2) * random());
+}
+
+/** A failure's message, for reports. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: whatever a replay handler threw
+export function failureMessage(failure: unknown): string {
+  return failure instanceof Error ? failure.message : String(failure);
+}

package/src/core/page.ts

@@ -1,74 +1,74 @@
-/**
- * What the page tells the client: the host's injected `window.__HUB__`
- * (contract `HubInject`), the game's slug, and the API base. A page the host
- * did not inject (`game.hub: false`, local development) has no `__HUB__`.
- */
-import type { HubInject } from '@diffenderfer-games/hub-contract';
-import { isRecord, optionalString } from './storage/json-guards';
-
-declare global {
-  interface Window {
-    /** The host's injected config (contract `HubInject`); read through {@link injectedConfig}. */
-    // eslint-disable-next-line no-restricted-syntax -- trust boundary: written by the host's inline script, read field by field
-    __HUB__?: unknown;
-  }
-}
-
-/** The fields of `window.__HUB__` the core client reads. */
-export type InjectedConfig = Partial<Pick<HubInject, 'slug'>> & { readonly apiBase?: string };
-
-/** Whether this code runs in a browser page. */
-export function isBrowserPage(): boolean {
-  return typeof window !== 'undefined';
-}
-
-/** Whether the host injected this page (`window.__HUB__` exists), so the menu and social runtime can arrive. */
-export function isHubInjectedPage(): boolean {
-  return isBrowserPage() && isRecord(window.__HUB__);
-}
-
-/** The injected config's slug and API base, read defensively (empty outside a hub page). */
-export function injectedConfig(): InjectedConfig {
-  if (!isBrowserPage() || !isRecord(window.__HUB__)) {
-    return {};
-  }
-  const slug = optionalString(window.__HUB__.slug);
-  const apiBase = optionalString(window.__HUB__.apiBase);
-  return { ...(slug === undefined ? {} : { slug }), ...(apiBase === undefined ? {} : { apiBase }) };
-}
-
-/** The game's slug: the injected one, else the first URL path segment, else `null`. */
-export function detectSlug(): string | null {
-  const injectedSlug = injectedConfig().slug;
-  if (injectedSlug !== undefined && injectedSlug !== '') {
-    return injectedSlug;
-  }
-  if (typeof location === 'undefined') {
-    return null;
-  }
-  return location.pathname.split('/').find((segment) => segment !== '') ?? null;
-}
-
-/** An API base made absolute against the page origin (`http://localhost` outside a browser), without a trailing slash. */
-export function absoluteApiBase(apiBase: string): string {
-  const origin = typeof location === 'undefined' ? 'http://localhost' : location.origin;
-  return new URL(apiBase, origin).toString().replace(/\/$/, '');
-}
-
-/** The page's API base: the injected one, else `/_api`, made absolute. */
-export function detectApiBase(): string {
-  return absoluteApiBase(injectedConfig().apiBase ?? '/_api');
-}
-
-/** Dispatch a `CustomEvent` on `window` (no-op outside a browser; listener errors never reach the caller). */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: event details are whatever the event documents; listeners read them
-export function emitWindowEvent(eventName: string, detail?: unknown): void {
-  if (!isBrowserPage()) {
-    return;
-  }
-  try {
-    window.dispatchEvent(new CustomEvent(eventName, { detail }));
-  } catch {
-    // A page without CustomEvent (very old browsers) misses the event.
-  }
-}
+/**
+ * What the page tells the client: the host's injected `window.__HUB__`
+ * (contract `HubInject`), the game's slug, and the API base. A page the host
+ * did not inject (`game.hub: false`, local development) has no `__HUB__`.
+ */
+import type { HubInject } from '@diffenderfer-games/hub-contract';
+import { isRecord, optionalString } from './storage/json-guards';
+
+declare global {
+  interface Window {
+    /** The host's injected config (contract `HubInject`); read through {@link injectedConfig}. */
+    // eslint-disable-next-line no-restricted-syntax -- trust boundary: written by the host's inline script, read field by field
+    __HUB__?: unknown;
+  }
+}
+
+/** The fields of `window.__HUB__` the core client reads. */
+export type InjectedConfig = Partial<Pick<HubInject, 'slug'>> & { readonly apiBase?: string };
+
+/** Whether this code runs in a browser page. */
+export function isBrowserPage(): boolean {
+  return typeof window !== 'undefined';
+}
+
+/** Whether the host injected this page (`window.__HUB__` exists), so the menu and social runtime can arrive. */
+export function isHubInjectedPage(): boolean {
+  return isBrowserPage() && isRecord(window.__HUB__);
+}
+
+/** The injected config's slug and API base, read defensively (empty outside a hub page). */
+export function injectedConfig(): InjectedConfig {
+  if (!isBrowserPage() || !isRecord(window.__HUB__)) {
+    return {};
+  }
+  const slug = optionalString(window.__HUB__.slug);
+  const apiBase = optionalString(window.__HUB__.apiBase);
+  return { ...(slug === undefined ? {} : { slug }), ...(apiBase === undefined ? {} : { apiBase }) };
+}
+
+/** The game's slug: the injected one, else the first URL path segment, else `null`. */
+export function detectSlug(): string | null {
+  const injectedSlug = injectedConfig().slug;
+  if (injectedSlug !== undefined && injectedSlug !== '') {
+    return injectedSlug;
+  }
+  if (typeof location === 'undefined') {
+    return null;
+  }
+  return location.pathname.split('/').find((segment) => segment !== '') ?? null;
+}
+
+/** An API base made absolute against the page origin (`http://localhost` outside a browser), without a trailing slash. */
+export function absoluteApiBase(apiBase: string): string {
+  const origin = typeof location === 'undefined' ? 'http://localhost' : location.origin;
+  return new URL(apiBase, origin).toString().replace(/\/$/, '');
+}
+
+/** The page's API base: the injected one, else `/_api`, made absolute. */
+export function detectApiBase(): string {
+  return absoluteApiBase(injectedConfig().apiBase ?? '/_api');
+}
+
+/** Dispatch a `CustomEvent` on `window` (no-op outside a browser; listener errors never reach the caller). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: event details are whatever the event documents; listeners read them
+export function emitWindowEvent(eventName: string, detail?: unknown): void {
+  if (!isBrowserPage()) {
+    return;
+  }
+  try {
+    window.dispatchEvent(new CustomEvent(eventName, { detail }));
+  } catch {
+    // A page without CustomEvent (very old browsers) misses the event.
+  }
+}

package/src/core/rest/endpoint-types.ts

@@ -1,22 +1,22 @@
-/**
- * Per-endpoint request and reply types, derived from the contract's spec
- * **type** only (`import type`, erased at build): the browser bundle carries
- * the route table, never the schemas (plan D16).
- */
-import type { CallReturn, ClientData } from '@ayepi/core/client';
-import type { PublicEndpoints } from '@diffenderfer-games/hub-contract';
-
-/** The name of a public REST endpoint (`getCurrentUser`, `writeSave`, ...). */
-export type EndpointName = keyof PublicEndpoints;
-
-/** One endpoint's request fields: path params, query and body merged into one object. */
-export type EndpointFields<K extends EndpointName> = ClientData<PublicEndpoints[K]>;
-
-/**
- * An endpoint that declares several success statuses comes back from ayepi's
- * client as `{ status, data }`; this client always hands back the body.
- */
-type ReplyBody<Reply> = Reply extends { readonly status: number; readonly data: infer Body } ? Body : Reply;
-
-/** One endpoint's success reply body. */
-export type EndpointReply<K extends EndpointName> = ReplyBody<Awaited<CallReturn<PublicEndpoints[K]>>>;
+/**
+ * Per-endpoint request and reply types, derived from the contract's spec
+ * **type** only (`import type`, erased at build): the browser bundle carries
+ * the route table, never the schemas (plan D16).
+ */
+import type { CallReturn, ClientData } from '@ayepi/core/client';
+import type { PublicEndpoints } from '@diffenderfer-games/hub-contract';
+
+/** The name of a public REST endpoint (`getCurrentUser`, `writeSave`, ...). */
+export type EndpointName = keyof PublicEndpoints;
+
+/** One endpoint's request fields: path params, query and body merged into one object. */
+export type EndpointFields<K extends EndpointName> = ClientData<PublicEndpoints[K]>;
+
+/**
+ * An endpoint that declares several success statuses comes back from ayepi's
+ * client as `{ status, data }`; this client always hands back the body.
+ */
+type ReplyBody<Reply> = Reply extends { readonly status: number; readonly data: infer Body } ? Body : Reply;
+
+/** One endpoint's success reply body. */
+export type EndpointReply<K extends EndpointName> = ReplyBody<Awaited<CallReturn<PublicEndpoints[K]>>>;