@diffenderfer-games/hub-contract 0.0.0-stage → 2.0.0-next.1

package/src/logic/race.ts

@@ -0,0 +1,169 @@
+/**
+ * Wording for race UIs (HUD, result card, history): stat values, result
+ * labels and the "how it ended" line, identical on every screen. Copy rule
+ * (multiplayer.md §10): no violent words; racers "finish", "are out", "give
+ * up" or "drop out".
+ */
+import type { RaceSummary } from '../api/catalog';
+import type { RaceOutcome, RaceParams, RacerResult, RacerState, RaceResult, RaceStats, RaceStatValue } from '../api/mp/races';
+import type { RaceStatFormat } from '../manifest/race';
+import { raceClock } from './time';
+
+/** One declared race stat (key, title, display format). */
+export type RaceStatSpec = RaceSummary['stats'][number];
+
+/** A stat value for display, per its declared format. Unknown or absent values show as `'–'`. */
+export function formatStat(value: RaceStatValue | undefined, format: RaceStatFormat): string {
+  if (value === undefined) {
+    return '–';
+  }
+  switch (format) {
+    case 'percent':
+      return typeof value === 'number' ? `${String(Math.round(Math.max(0, Math.min(1, value)) * 100))}%` : '–';
+    case 'time':
+      return typeof value === 'number' ? raceClock(value) : '–';
+    case 'bool':
+      return typeof value === 'boolean' ? (value ? '✓' : '✗') : '–';
+    case 'color':
+      return typeof value === 'string' ? '●' : '–';
+    case 'int':
+      if (typeof value === 'number') {
+        return String(Math.round(value));
+      }
+      return typeof value === 'boolean' ? (value ? '✓' : '✗') : '–';
+  }
+}
+
+/** The declared stats with their values (the HUD shows at most `max`). */
+export function shownStats(spec: RaceSummary | null, stats: RaceStats, max = 3): { spec: RaceStatSpec; value: RaceStatValue | undefined }[] {
+  return spec ? spec.stats.slice(0, max).map((s) => ({ spec: s, value: stats[s.key] })) : [];
+}
+
+/** "Board 4x4 · Level Hard" from the manifest's option titles; unknown values are skipped. */
+export function paramsText(spec: RaceSummary | null, params: RaceParams): string {
+  if (!spec) {
+    return '';
+  }
+  const parts: string[] = [];
+  for (const param of spec.params) {
+    const matchingOption = param.options.find((option) => option.value === params[param.key]);
+    if (matchingOption) {
+      parts.push(param.title === matchingOption.title ? matchingOption.title : `${param.title} ${matchingOption.title}`);
+    }
+  }
+  return parts.join(' · ');
+}
+
+/** A racer's live state as a short tag (`''` while racing and connected). */
+export function racerStateTag(state: RacerState, isConnected: boolean): string {
+  switch (state) {
+    case 'finished':
+      return '🏁 Finished';
+    case 'lost':
+      return 'Out';
+    case 'forfeit':
+      return 'Gave up';
+    case 'disconnected':
+      return 'Dropped out';
+    case 'racing':
+      return isConnected ? '' : 'Reconnecting…';
+  }
+}
+
+const RESULT_LABEL: Readonly<Record<RacerResult, string>> = {
+  won: '🏆 Won', beaten: "Didn't finish", lost: 'Out', forfeit: 'Gave up', disconnected: 'Dropped out', timeout: "Time's up",
+};
+
+/** A racer's line in the result card and history. */
+export function resultLabel(racerResult: RacerResult): string {
+  return RESULT_LABEL[racerResult];
+}
+
+/** The result card's title from my point of view (`me` is `null` when watching). */
+export function resultTitle(result: RaceResult, me: number | null): string {
+  const winner = result.players.find((player) => player.userId === result.winnerId);
+  if (!winner) {
+    return "Time's up!";
+  }
+  return winner.userId === me ? 'You won! 🏆' : `${winner.name} won`;
+}
+
+/** Names joined for a sentence: "Sam", "Sam and Ali", "Sam, Ali and Jo". */
+export function nameList(names: readonly string[]): string {
+  const last = names.at(-1);
+  if (names.length <= 1 || last === undefined) {
+    return names[0] ?? 'Everyone';
+  }
+  return `${names.slice(0, -1).join(', ')} and ${last}`;
+}
+
+/** How the race ended, in one friendly sentence, from my point of view. */
+export function outcomeLine(result: RaceResult, me: number | null): string {
+  const winner = result.players.find((player) => player.userId === result.winnerId);
+  if (!winner) {
+    return 'Nobody finished before the time ran out.';
+  }
+  const mine = result.players.find((player) => player.userId === me);
+  const others = result.players.filter((player) => player.userId !== result.winnerId);
+  const namesWithOutcome = (outcome: RaceOutcome): string[] => others.filter((player) => player.result === outcome).map((player) => player.name);
+  const didIWin = winner.userId === me;
+  if (result.outcome === 'finished') {
+    return `${didIWin ? 'You' : winner.name} finished first in ${raceClock(winner.ms)}.`;
+  }
+  if (mine && !didIWin) {
+    if (mine.result === 'forfeit') {
+      return 'You gave up.';
+    }
+    if (mine.result === 'lost') {
+      return "You're out — better luck next race!";
+    }
+    if (mine.result === 'disconnected') {
+      return 'Your connection dropped.';
+    }
+  }
+  const lost = namesWithOutcome('lost');
+  const gaveUp = namesWithOutcome('forfeit');
+  const dropped = namesWithOutcome('disconnected');
+  const bits: string[] = [];
+  if (gaveUp.length > 0) {
+    bits.push(`${nameList(gaveUp)} gave up`);
+  }
+  if (lost.length > 0) {
+    bits.push(`${nameList(lost)} ${lost.length === 1 ? 'is' : 'are'} out`);
+  }
+  if (dropped.length > 0) {
+    bits.push(`${nameList(dropped)} dropped out`);
+  }
+  const why = bits.length > 0 ? bits.join(', ') : 'Everyone else is out';
+  return `${why.charAt(0).toUpperCase()}${why.slice(1)} — ${didIWin ? 'you win' : `${winner.name} wins`}!`;
+}
+
+const HISTORY_VERB: Readonly<Record<RacerResult, string>> = {
+  won: 'Won', beaten: 'Lost', lost: 'Out', forfeit: 'Gave up', disconnected: 'Dropped out', timeout: "Time's up",
+};
+
+/** My race's headline verb in the history ("Won vs Sam", "Lost vs Sam"). */
+export function historyVerb(racerResult: RacerResult): string {
+  return HISTORY_VERB[racerResult];
+}
+
+/** True when a racer's time means something (they finished or dropped out themselves). */
+export function hasOwnTime(racerResult: RacerResult): boolean {
+  return racerResult !== 'beaten' && racerResult !== 'timeout';
+}
+
+/** The history badge for my result. */
+export function historyBadge(racerResult: RacerResult | undefined): string {
+  switch (racerResult) {
+    case 'won':
+      return '🏆';
+    case 'forfeit':
+      return '🏳️';
+    case 'disconnected':
+      return '📶';
+    case 'timeout':
+      return '⏱️';
+    default:
+      return '🏁';
+  }
+}

package/src/logic/time.ts

@@ -0,0 +1,81 @@
+/**
+ * Time and count wording shared by every hub UI (the social drawer, the menu,
+ * the home page, race cards). One copy, so "3h ago" reads the same everywhere
+ * (plan §8.4: the menu and the catalog page each had their own).
+ */
+
+const padTwoDigits = (count: number): string => String(count).padStart(2, '0');
+
+/**
+ * `m:ss` (or `h:mm:ss`) elapsed since `since`.
+ * @example elapsed(0, 252_000) // "4:12"
+ */
+export function elapsed(since: number, now: number): string {
+  const total = Math.max(0, Math.floor((now - since) / 1000));
+  const hours = Math.floor(total / 3600);
+  const minutes = Math.floor((total % 3600) / 60);
+  const paddedSeconds = padTwoDigits(total % 60);
+  return hours ? `${String(hours)}:${padTwoDigits(minutes)}:${paddedSeconds}` : `${String(minutes)}:${paddedSeconds}`;
+}
+
+/**
+ * "just now", "5m ago", "3h ago", "2d ago", then a short date (in the
+ * viewer's locale) after a week.
+ */
+export function relativeTime(then: number, now: number): string {
+  const seconds = Math.max(0, Math.floor((now - then) / 1000));
+  if (seconds < 60) {
+    return 'just now';
+  }
+  if (seconds < 3600) {
+    return `${String(Math.floor(seconds / 60))}m ago`;
+  }
+  if (seconds < 86400) {
+    return `${String(Math.floor(seconds / 3600))}h ago`;
+  }
+  if (seconds < 7 * 86400) {
+    return `${String(Math.floor(seconds / 86400))}d ago`;
+  }
+  return new Date(then).toLocaleDateString(undefined, { month: 'short', day: 'numeric' });
+}
+
+/**
+ * A seconds countdown for mutes and rate limits: "42s" or "3:05".
+ * @param ms - time left, in ms
+ */
+export function countdown(ms: number): string {
+  const seconds = Math.max(0, Math.ceil(ms / 1000));
+  return seconds < 60 ? `${String(seconds)}s` : `${String(Math.floor(seconds / 60))}:${padTwoDigits(seconds % 60)}`;
+}
+
+/** Badge text: `''` for 0, the number up to 9, then `'9+'`. */
+export function badgeText(count: number): string {
+  if (count <= 0) {
+    return '';
+  }
+  return count > 9 ? '9+' : String(count);
+}
+
+/**
+ * When a suspension or mute ends, for the "can't use online play" notice.
+ * `''` when there is no end (0, or a permanent suspension far in the future).
+ */
+export function untilText(until: number): string {
+  if (!until || until > 8e15) {
+    return '';
+  }
+  return new Date(until).toLocaleString(undefined, { month: 'short', day: 'numeric', hour: 'numeric', minute: '2-digit' });
+}
+
+/**
+ * A race clock: `83_400` → `"1:23.4"`; past an hour `"1:02:03"`.
+ * @param ms - elapsed race time, in ms
+ */
+export function raceClock(ms: number): string {
+  const tenths = Math.max(0, Math.floor(ms / 100));
+  const seconds = Math.floor(tenths / 10);
+  const hours = Math.floor(seconds / 3600);
+  const minutes = Math.floor((seconds % 3600) / 60);
+  const paddedSeconds = padTwoDigits(seconds % 60);
+  return hours ? `${String(hours)}:${padTwoDigits(minutes)}:${paddedSeconds}` : `${String(minutes)}:${paddedSeconds}.${String(tenths % 10)}`;
+}

package/src/manifest/changes.ts

@@ -0,0 +1,55 @@
+/**
+ * `game.changes`: player-facing "What's new" notes (docs/hub.md "What's new").
+ */
+import { z } from 'zod';
+import { Key } from '../common';
+import { MANIFEST_LIMITS } from '../limits';
+import { trimmedText } from './fields';
+
+/** The text of one note: plain words for a player, at most 280 characters. */
+export const ChangeText = trimmedText(MANIFEST_LIMITS.changeTextMax);
+
+/**
+ * One note: a string (identified by its text, so rewording re-announces it)
+ * or `{ id, text }` (identified by `id`, so it can be reworded).
+ */
+export const ChangeEntry = z.union([
+  ChangeText,
+  z.strictObject({
+    /** A stable id: letters, digits and `_ . : -`, 1 to 64 characters. */
+    id: Key,
+    /** The note. */
+    text: ChangeText,
+  }),
+]);
+
+/** One "What's new" note. */
+export type ChangeEntry = z.output<typeof ChangeEntry>;
+
+/**
+ * The form a string note is identified by: lowercase, whitespace collapsed,
+ * trailing punctuation dropped. Two notes with the same form are duplicates.
+ */
+export function normalizeChangeText(text: string): string {
+  return text.toLowerCase().replace(/\s+/g, ' ').trim().replace(/[\s.!?…]+$/u, '');
+}
+
+/** The identity the hub stores a note under. */
+function noteIdentity(note: ChangeEntry): string {
+  return typeof note === 'string' ? `h:${normalizeChangeText(note)}` : `id:${note.id}`;
+}
+
+/** `game.changes`: at most 200 notes, no duplicates. Newest last. */
+export const GameChanges = z
+  .array(ChangeEntry)
+  .max(MANIFEST_LIMITS.changesMax)
+  .superRefine((notes, ctx) => {
+    const seen = new Set<string>();
+    notes.forEach((note, i) => {
+      const id = noteIdentity(note);
+      if (seen.has(id)) {
+        ctx.addIssue({ code: 'custom', message: 'duplicate note (same id, or the same text ignoring case and trailing punctuation)', path: [i] });
+      }
+      seen.add(id);
+    });
+  });

package/src/manifest/controls.ts

@@ -0,0 +1,42 @@
+/**
+ * `game.controls`: the gamepad-to-keyboard map zero-config games use, so a
+ * controller or arcade stick works in a game that never calls
+ * `hub.input.define()` (docs/hub.md "Mapping controls per game").
+ */
+import { z } from 'zod';
+import { SEAT_LIMITS } from '../limits';
+
+/** A `KeyboardEvent.code`, such as `ArrowUp`, `Space`, `KeyZ` or `ShiftLeft`. */
+export const KeyCode = z.string().regex(/^[A-Za-z0-9]{1,32}$/, 'must be a KeyboardEvent.code such as ArrowUp, Space or KeyZ');
+
+/** A standard-gamepad button index, `"0"` to `"19"`. */
+export const ButtonIndex = z.string().regex(/^(?:1?[0-9])$/, 'must be a gamepad button index 0-19');
+
+/** One player's map. Unset directions and buttons keep the defaults. */
+export const ControlMap = z.strictObject({
+  /** Key pressed for stick/d-pad up. Default `ArrowUp`. */
+  up: KeyCode.optional(),
+  /** Key pressed for stick/d-pad down. Default `ArrowDown`. */
+  down: KeyCode.optional(),
+  /** Key pressed for stick/d-pad left. Default `ArrowLeft`. */
+  left: KeyCode.optional(),
+  /** Key pressed for stick/d-pad right. Default `ArrowRight`. */
+  right: KeyCode.optional(),
+  /**
+   * Button index → key. Defaults: `0` Space, `1` Enter, `2` KeyZ, `3` KeyX,
+   * `8` Escape, `9` Enter.
+   */
+  buttons: z.record(ButtonIndex, KeyCode).optional(),
+});
+
+/** A gamepad-to-keyboard map. */
+export type ControlMap = z.infer<typeof ControlMap>;
+
+/** `game.controls`: one map for every pad, or one per player in `players`. */
+export const GameControls = ControlMap.extend({
+  /** Per-player maps, by gamepad order; pads past the end use the first. Overrides the shared map. */
+  players: z.array(ControlMap).min(1).max(SEAT_LIMITS.maxSeats).optional(),
+});
+
+/** `game.controls`. */
+export type GameControls = z.infer<typeof GameControls>;

package/src/manifest/fields.ts

@@ -0,0 +1,89 @@
+/**
+ * Field rules shared by several parts of the `game.*` manifest. Each rule is
+ * defined once here.
+ */
+import { z } from 'zod';
+import { MANIFEST_LIMITS, SEAT_LIMITS } from '../limits';
+
+/**
+ * A non-empty string with no leading or trailing whitespace. Used for fields
+ * the hub reads verbatim (commands, paths, titles), where stray spaces are a
+ * mistake rather than something the hub would trim away.
+ */
+export const Trimmed = z.string().regex(/^\S(?:[\s\S]*\S)?$/, 'must be non-empty, with no leading or trailing spaces');
+
+/** A label the hub trims and shows to players, at most `max` characters. */
+export function trimmedText(max: number) {
+  return z.string().trim().min(1).max(max);
+}
+
+/**
+ * A URL suffix relative to `/<slug>/` that invites and Join open, such as
+ * `?lobby=1` or `play/online`. Not absolute, no `..`, no `//`.
+ */
+export const LobbySuffix = z
+  .string()
+  .trim()
+  .regex(new RegExp(`^[A-Za-z0-9_./?=&#%-]{0,${MANIFEST_LIMITS.lobbyMax}}$`), 'may only use letters, digits and _ . / ? = & # % -')
+  .refine((s) => !s.startsWith('/') && !s.includes('..') && !s.includes('//'), 'must be a relative URL suffix (no leading /, no .., no //)');
+
+/**
+ * A `[min, max]` player range: whole numbers, `lowest <= min <= max <= 8`.
+ *
+ * @param lowest - the smallest `min` allowed (1 for multiplayer, 2 for races)
+ */
+export function playerRange(lowest: number) {
+  const seatCount = z.number().int().min(lowest).max(SEAT_LIMITS.maxSeats);
+  return z.tuple([seatCount, seatCount]).refine(([min, max]) => min <= max, `must be [min, max] with ${lowest} <= min <= max <= ${SEAT_LIMITS.maxSeats}`);
+}
+
+/**
+ * An optional block that may also be written as `false` ("off"). `false`
+ * parses to `undefined`, the same as leaving the field out.
+ *
+ * (A `z.union` with `z.literal(false)` would work too, but it hides the
+ * block's own field errors behind a bare "Invalid input".)
+ */
+export function orFalse<T extends z.ZodType>(block: T) {
+  return z.preprocess((v: false | z.input<T>) => (v === false ? undefined : v), block.optional()).optional();
+}
+
+/** True when no two items share a `key`. */
+export function hasUniqueKeys(items: readonly { readonly key: string }[]): boolean {
+  return new Set(items.map((i) => i.key)).size === items.length;
+}
+
+/** The placeholders a `build` or `start` command may use. */
+export const COMMAND_PLACEHOLDERS = ['PORT', 'GAME_PATH', 'GAME_SLUG'] as const;
+
+const PLACEHOLDER = /\{\{(\w+)\}\}/g;
+const KNOWN_PLACEHOLDERS: ReadonlySet<string> = new Set(COMMAND_PLACEHOLDERS);
+
+/**
+ * A shell command the host runs in the app folder. It may use the
+ * placeholders `{{PORT}}`, `{{GAME_PATH}}` and `{{GAME_SLUG}}`; any other
+ * `{{NAME}}` fails the build.
+ */
+export const Command = Trimmed.refine(
+  (cmd) => [...cmd.matchAll(PLACEHOLDER)].every((m) => KNOWN_PLACEHOLDERS.has(m[1] ?? '')),
+  `may only use the placeholders ${COMMAND_PLACEHOLDERS.map((p) => `{{${p}}}`).join(', ')}`,
+);
+
+/** True when a relative path names something strictly inside its folder. */
+function staysInside(path: string): boolean {
+  let depth = 0;
+  for (const part of path.split(/[\\/]/)) {
+    if (part === '..') {
+      depth -= 1;
+      if (depth < 0) {
+        return false;
+      }
+    } else if (part !== '' && part !== '.') {
+      depth += 1;
+    }
+  }
+  return depth > 0;
+}
+
+/** A file path relative to the app folder that stays inside it, e.g. `cover.png`. */
+export const AppFilePath = Trimmed.refine(staysInside, 'must be a file inside the app folder');

package/src/manifest/game.ts

@@ -0,0 +1,132 @@
+/**
+ * The `game` block of an app's `package.json`: how the host builds, serves
+ * and shows the game (HANDOFF.md "The game block").
+ *
+ * This is the **strict** authoring schema `hub-doctor` runs in a game: a
+ * mistake fails the parse. The host stays lenient at boot (a bad field falls
+ * back to its default with a warning), so one typo never takes a game down.
+ */
+import { z } from 'zod';
+import { MANIFEST_LIMITS } from '../limits';
+import { GameChanges } from './changes';
+import { GameControls } from './controls';
+import { AppFilePath, Command, Trimmed, orFalse } from './fields';
+import { GameLeaderboardDecls } from './leaderboards';
+import { GameMultiplayer, StaticGameMultiplayer } from './multiplayer';
+import { GameRace } from './race';
+
+/** The corner the injected hub menu button sits in. Default `top-left`. */
+export const MenuPosition = z.enum(['top-left', 'top-right', 'bottom-left', 'bottom-right']);
+
+/** A menu button corner. */
+export type MenuPosition = z.infer<typeof MenuPosition>;
+
+/** Pixels to push the menu button away from its corner, 0 to 600. */
+const OffsetPx = z.number().int().min(0).max(MANIFEST_LIMITS.menuOffsetMax);
+
+/** The menu offset as the host sends it: both axes, in px. */
+export const MenuOffsetXY = z.strictObject({
+  /** Inward from the left or right edge, px. */
+  x: OffsetPx,
+  /** Down from a top corner or up from a bottom one, px. */
+  y: OffsetPx,
+});
+
+/**
+ * `game.menuOffset`: how far to push the menu button away from its corner so
+ * it clears the game's own bars. A number moves it vertically only.
+ */
+export const MenuOffset = z.union([OffsetPx, MenuOffsetXY.partial()]);
+
+/** Fields both app types share. */
+const commonFields = {
+  /** Shown on the catalog card and in the menu. */
+  title: Trimmed,
+  /** Catalog, search and link-preview text. Falls back to `package.json` `description`. */
+  description: Trimmed.optional(),
+  /**
+   * Credit shown on the tile, e.g. `"Mason & Phil"` (split into authors for the
+   * catalog filter). Falls back to `package.json` `author`.
+   */
+  author: z.string().trim().min(1).optional(),
+  /** Runs at boot when the source changed. May use `{{PORT}}`, `{{GAME_PATH}}`, `{{GAME_SLUG}}`. */
+  build: Command.optional(),
+  /** Tile and preview image, relative to the project root (not `serveDir`); must stay inside it. */
+  image: AppFilePath.optional(),
+  /** `true` leaves the app out of the catalog entirely. */
+  hidden: z.boolean().optional(),
+  /** `false` opts out of the injected hub menu and SDK. */
+  hub: z.boolean().optional(),
+  /** `false` opts out of the PWA install tags and service worker. */
+  pwa: z.boolean().optional(),
+  /** The corner the hub menu button sits in. Default `top-left`. */
+  menuPosition: MenuPosition.optional(),
+  /** Push the menu button away from its corner, px: a number (vertical) or `{ x, y }`. */
+  menuOffset: MenuOffset.optional(),
+  /** `true` opts into the shared daily challenges (`hub.daily.define(...)`). */
+  dailyChallenges: z.boolean().optional(),
+  /** Boards to create up front, so they show before the first score. */
+  leaderboards: GameLeaderboardDecls.optional(),
+  /** The gamepad-to-keyboard map for games that never call `hub.input.define()`. */
+  controls: GameControls.optional(),
+  /** Turns a single-player game into a race target; `true` for all defaults, `false` for off. */
+  race: GameRace,
+  /** Player-facing "What's new" notes, one per change, newest last. Keep it updated. */
+  changes: GameChanges.optional(),
+};
+
+/** A static app: the build emits a folder the host serves. */
+export const StaticGame = z.strictObject({
+  /** `static`: no running process. */
+  type: z.literal('static'),
+  /** The folder served at `/<slug>/`; must exist after `build`. */
+  serveDir: Trimmed,
+  /** Makes the game an online invite/join target (`hub-rooms` only); `false` for off. */
+  multiplayer: orFalse(StaticGameMultiplayer),
+  ...commonFields,
+});
+
+/** A process app: the host runs a long-lived server and proxies to it. */
+export const ProcessGame = z.strictObject({
+  /** `process`: the host starts `start` and proxies `/<slug>/` to it. */
+  type: z.literal('process'),
+  /** The long-lived server command; must listen on the assigned port (`{{PORT}}` or `PORT`). */
+  start: Command,
+  /** The path the host polls until it answers below 500. Default `/`. */
+  healthPath: Trimmed.startsWith('/').optional(),
+  /** Makes the game an online invite/join target; `false` for off. */
+  multiplayer: orFalse(GameMultiplayer),
+  ...commonFields,
+});
+
+/** The `game` block of a game's `package.json`. */
+export const GameManifest = z.discriminatedUnion('type', [StaticGame, ProcessGame]);
+
+/** A parsed `game` block (defaults applied). */
+export type GameManifest = z.output<typeof GameManifest>;
+
+/** The `game` block as a game writes it. */
+export type GameManifestInput = z.input<typeof GameManifest>;
+
+/** A game's `package.json`: the `game` block plus the npm fields the host falls back to. */
+export const GamePackageJson = z.looseObject({
+  /** The npm name; the title fallback. */
+  name: z.string().optional(),
+  /** The description fallback. */
+  description: z.string().optional(),
+  /** The author fallback: npm's string or `{ name }` form. */
+  author: z.union([z.string(), z.looseObject({ name: z.string().optional() })]).optional(),
+  /** How the host treats the app. */
+  game: GameManifest,
+});
+
+/**
+ * The host repo's own `game` block: only its "What's new" notes (shown as
+ * "diffenderfer.games"). It is not an app, so it has no `type`.
+ */
+export const HostManifest = z.strictObject({
+  /** The host's display name. */
+  title: Trimmed.optional(),
+  /** The host's own notes (menu, friends, home page). */
+  changes: GameChanges.optional(),
+});

package/src/manifest/index.ts

@@ -0,0 +1,12 @@
+/**
+ * The `package.json` `game.*` manifest and the injected `window.__HUB__`
+ * config.
+ */
+export * from './changes';
+export * from './controls';
+export { AppFilePath, COMMAND_PLACEHOLDERS, Command, LobbySuffix } from './fields';
+export * from './game';
+export * from './inject';
+export * from './leaderboards';
+export * from './multiplayer';
+export * from './race';

package/src/manifest/inject.ts

@@ -0,0 +1,31 @@
+/**
+ * `window.__HUB__`: the small config object the host writes into every page
+ * it injects (game pages, and the catalog page). The SDK and the menu read it
+ * to find the game's slug, the API base and the menu placement.
+ *
+ * The same inline script may also set `window.__hubDailyDeep` (a
+ * `?daily=YYYY-MM-DD` deep link captured before game code runs) and
+ * `window.__hubInstall` (the PWA install prompt); those are not part of this
+ * object.
+ */
+import { z } from 'zod';
+import { Slug } from '../common';
+import { GameControls } from './controls';
+import { MenuOffsetXY, MenuPosition } from './game';
+
+/** The injected `window.__HUB__` config. */
+export const HubInject = z.strictObject({
+  /** The game's slug. Missing on the catalog page. */
+  slug: Slug.optional(),
+  /** Where the REST API lives. Always `/_api` today. */
+  apiBase: z.literal('/_api'),
+  /** The menu button's corner (from `game.menuPosition`). Missing on the catalog page. */
+  menu: MenuPosition.optional(),
+  /** The menu button's offset from its corner (from `game.menuOffset`); only sent when not 0,0. */
+  menuOffset: MenuOffsetXY.optional(),
+  /** The game's `game.controls`, as written; only sent when set. */
+  controls: GameControls.optional(),
+});
+
+/** The injected `window.__HUB__` config. */
+export type HubInject = z.infer<typeof HubInject>;

package/src/manifest/leaderboards.ts

@@ -0,0 +1,29 @@
+/**
+ * `game.leaderboards`: boards declared up front, so they show on the catalog
+ * before the first score.
+ */
+import { z } from 'zod';
+import { SortDir } from '../api/leaderboards';
+import { Key } from '../common';
+import { MANIFEST_LIMITS } from '../limits';
+import { Trimmed, hasUniqueKeys } from './fields';
+
+/** One declared leaderboard. */
+export const LeaderboardDecl = z.strictObject({
+  /** The board key `hub.submitScore(key, score)` uses: letters, digits and `_ . : -`, 1 to 64. */
+  key: Key,
+  /** What players see, at most 80 characters. Defaults to the key. */
+  title: Trimmed.max(MANIFEST_LIMITS.leaderboardTitleMax).optional(),
+  /** Which scores rank first. Default `desc`. */
+  sort: SortDir.default('desc'),
+  /** List players whose best is 0. Default `false`. */
+  showZeros: z.boolean().optional(),
+  /**
+   * `server`: only the game's own server may submit (trusted multiplayer
+   * results); the client endpoint refuses. Default `client`.
+   */
+  source: z.enum(['client', 'server']).default('client'),
+});
+
+/** `game.leaderboards`: unique keys. */
+export const GameLeaderboardDecls = z.array(LeaderboardDecl).refine(hasUniqueKeys, 'leaderboard keys must be unique');