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

package/src/errors/codes/social.ts

@@ -0,0 +1,31 @@
+/** Error codes from friends, messages, notifications, reports and suggestions. */
+export const SOCIAL_CODES = [
+  /** No such player, or one who blocked you or is suspended (they look the same). */
+  'no_player',
+  /** Not one of the preset avatars. */
+  'bad_avatar',
+  /** The chat-lock password was wrong. */
+  'bad_password',
+  /** An admin turned new friend requests off. */
+  'friend_requests_off',
+  /** You can't do that to yourself (friend, block; also invites, joins and room targets). */
+  'bad_target',
+  /** The other player is a guest and must create an account first. */
+  'guest_target',
+  /** You blocked them: unblock first. */
+  'blocked',
+  /** You or they have the most friends allowed. */
+  'friends_limit',
+  /** Too many outgoing friend requests waiting. */
+  'pending_limit',
+  /** The friend request is gone. */
+  'no_request',
+  /** You're not friends (messages, friend bells). */
+  'not_friends',
+  /** You've blocked the most players allowed. */
+  'blocks_limit',
+  /** The player isn't taking messages. */
+  'dms_closed',
+  /** Too many of your suggestions are waiting for review. */
+  'too_many_pending',
+] as const;

package/src/errors/index.ts

@@ -0,0 +1,88 @@
+/**
+ * The error model (plan §5.3). Every failed REST call and every failed socket
+ * ack carries an {@link ErrorBody}. `error` is always safe to show a player.
+ * Public codes are listed per area in `codes/`; admin-only codes live in the
+ * server-only internal contract.
+ *
+ * Each schema here also has a named `…Schema` interface. Endpoints reference
+ * these schemas hundreds of times; naming their types lets the published
+ * `.d.ts` refer to them instead of printing every code at every use.
+ */
+import { z } from 'zod';
+import { Millis } from '../common';
+import { CORE_CODES } from './codes/core';
+import { MULTIPLAYER_CODES } from './codes/multiplayer';
+import { PLAY_CODES } from './codes/play';
+import { SOCIAL_CODES } from './codes/social';
+
+const errorCode = z.enum([...CORE_CODES, ...PLAY_CODES, ...SOCIAL_CODES, ...MULTIPLAYER_CODES]);
+
+/** The type of the {@link ErrorCode} schema. */
+export interface ErrorCodeSchema extends Readonly<typeof errorCode> {}
+
+/** Every public error code. */
+export const ErrorCode: ErrorCodeSchema = errorCode;
+
+/** A public error code. */
+export type ErrorCode = z.infer<ErrorCodeSchema>;
+
+const rejectReason = z.enum([
+  'link', 'personal_info', 'contact', 'language', 'slur', 'sexual', 'grown_up', 'unkind',
+  'threat', 'drugs', 'spam', 'shouting', 'too_long', 'empty', 'chars', 'reserved',
+  'rate_limited', 'muted', 'check_unavailable', 'chat_off', 'not_friends', 'suspended',
+  'quick_only', 'dms_closed', 'other',
+]);
+
+/** The type of the {@link RejectReason} schema. */
+export interface RejectReasonSchema extends Readonly<typeof rejectReason> {}
+
+/**
+ * Why text was rejected or a chat action was refused. Coarse on purpose: a
+ * reason names a category, never the word or list that matched.
+ */
+export const RejectReason: RejectReasonSchema = rejectReason;
+
+/** A content-reject reason. */
+export type RejectReason = z.infer<RejectReasonSchema>;
+
+const errorBody = z.object({
+  /** A sentence that is always safe to show the player. */
+  error: z.string(),
+  /** What went wrong, for code to branch on. */
+  code: ErrorCode.optional(),
+  /** Content rejects and suspensions: the category. */
+  reason: RejectReason.optional(),
+  /** A kid-friendly suggestion, e.g. "try saying it another way". */
+  hint: z.string().optional(),
+  /** Rate limits: how long to wait, in ms (0 when not limited). */
+  retryAfterMs: z.number().int().nonnegative().optional(),
+  /** Suspensions and mutes: when they end (epoch ms). */
+  until: Millis.optional(),
+});
+
+/** The type of the {@link ErrorBody} schema. */
+export interface ErrorBodySchema extends Readonly<typeof errorBody> {}
+
+/** The body of every error response and failed socket ack. */
+export const ErrorBody: ErrorBodySchema = errorBody;
+
+/** An error body. */
+export type ErrorBody = z.infer<ErrorBodySchema>;
+
+const contentRejected = errorBody.extend({
+  code: z.literal('content_rejected'),
+  reason: RejectReason,
+  hint: z.string(),
+});
+
+/** The type of the {@link ContentRejected} schema. */
+export interface ContentRejectedSchema extends Readonly<typeof contentRejected> {}
+
+/**
+ * The 422 content-rejected body (multiplayer.md §4.6), shared by DMs, room
+ * chat, suggestions, names and trade notes.
+ */
+export const ContentRejected: ContentRejectedSchema = contentRejected;
+
+/** A content-rejected body. */
+export type ContentRejected = z.infer<ContentRejectedSchema>;

package/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * The diffenderfer.games hub wire contract: zod schemas and types for the
+ * public REST API, the `/_ws` socket envelope, ops and events, error bodies
+ * and the `game.*` manifest.
+ *
+ * @packageDocumentation
+ */
+export * from './common';
+export * from './entities';
+export * from './errors';
+export * from './middleware';
+export * from './api';
+export * from './realtime';
+export * from './manifest';
+export * from './limits';
+export * from './logic';

package/src/limits.ts

@@ -0,0 +1,100 @@
+/**
+ * Limits a UI has to know about: text lengths, name rules, seat counts and
+ * the rules for a game's `package.json` `game.*` block. Each number is
+ * defined once here; the schemas and the server import it.
+ *
+ * Rate thresholds, caps and timers are server-only and not part of this package.
+ */
+import { z } from 'zod';
+
+/** Account name and password rules (sign-up, claim, rename). */
+export const ACCOUNT_LIMITS = {
+  /** Shortest username, after trimming. */
+  usernameMin: 2,
+  /** Longest username, after trimming. */
+  usernameMax: 24,
+  /** Shortest password. */
+  passwordMin: 6,
+  /** How many built-in avatars there are (`a0` … `a23`). */
+  avatarCount: 24,
+} as const;
+
+/** The characters a username may use: letters, digits, `_`, `-` and spaces. */
+export const USERNAME_PATTERN = /^[A-Za-z0-9_\- ]+$/;
+
+/**
+ * The text limits every social UI renders from. The hub sends the live values
+ * in `GET /social/config` and the socket `hello` (`limits`); the server can
+ * change them (`HUB_LIMITS_JSON`), so a UI should prefer the sent values.
+ */
+export const UiLimits = z.object({
+  /** Longest direct message, in characters. */
+  dmMaxChars: z.number().int().positive(),
+  /** Longest room or party chat line, in characters. */
+  roomChatMaxChars: z.number().int().positive(),
+  /** Longest suggestion title, in characters. */
+  suggestionTitleMax: z.number().int().positive(),
+  /** Longest suggestion body, in characters. */
+  suggestionBodyMax: z.number().int().positive(),
+});
+
+/** The text limits every social UI renders from. */
+export type UiLimits = z.infer<typeof UiLimits>;
+
+/** Today's default {@link UiLimits}, used until the hub sends its own. */
+export const UI_LIMIT_DEFAULTS = {
+  dmMaxChars: 200,
+  roomChatMaxChars: 120,
+  suggestionTitleMax: 60,
+  suggestionBodyMax: 500,
+} as const satisfies UiLimits;
+
+/** Seats in hub rooms and parties. */
+export const SEAT_LIMITS = {
+  /** Most players in one hub room, and the top of any `players` range. */
+  maxSeats: 8,
+  /** Most members in one party. */
+  partyMax: 8,
+} as const;
+
+/** What a racer's live stats (`hub.race.status(stats)`) may hold. */
+export const RACE_STATS_LIMITS = {
+  /** Most stat keys in one update. */
+  maxKeys: 12,
+  /** Largest update, in bytes of JSON. */
+  maxBytes: 600,
+} as const;
+
+/** Limits on the `package.json` `game.*` block (see the manifest schemas). */
+export const MANIFEST_LIMITS = {
+  /** Most `game.changes` entries the hub reads. */
+  changesMax: 200,
+  /** Longest `game.changes` entry, in characters. */
+  changeTextMax: 280,
+  /** Longest leaderboard title, in characters. */
+  leaderboardTitleMax: 80,
+  /** Furthest the menu button may be pushed from its corner, in px. */
+  menuOffsetMax: 600,
+  /** Longest lobby URL suffix, in characters. */
+  lobbyMax: 200,
+  /** Most `game.multiplayer.modes`. */
+  modesMax: 16,
+  /** Longest mode title, in characters. */
+  modeTitleMax: 40,
+  /** Most `game.multiplayer.quickChat` phrases. */
+  quickChatMax: 24,
+  /** Longest quick-chat phrase, in characters. */
+  quickChatTextMax: 40,
+  /** Most `game.multiplayer.chatAllow` words. */
+  chatAllowMax: 20,
+  /** Most `game.race.params`. */
+  raceParamsMax: 6,
+  /** Most options in one race param. */
+  raceOptionsMax: 12,
+  /** Most `game.race.stats` (the live HUD shows the first 3). */
+  raceStatsMax: 8,
+  /** Longest race param, option or stat title, in characters. */
+  raceTitleMax: 24,
+  /** Largest `game.race.minMs`, in ms (10 minutes). */
+  raceMinMsMax: 600_000,
+} as const;

package/src/logic/daily.ts

@@ -0,0 +1,54 @@
+/**
+ * Daily-challenge day keys and seeds: UTC `YYYY-MM-DD` keys, the playable
+ * window, and the deterministic per-(game, day) seed both the hub and the
+ * game compute. Pure; the signed tokens stay server-only.
+ */
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const DAY_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+/** The UTC day key (`YYYY-MM-DD`) of a timestamp. */
+export function dayKey(ts: number): string {
+  return new Date(ts).toISOString().slice(0, 10);
+}
+
+/**
+ * The playable window, newest first: today and the `count - 1` days before it.
+ * @param count - how many days (the back-fill window, 30 by default on the hub)
+ */
+export function windowDays(now: number, count: number): string[] {
+  return Array.from({ length: count }, (_, i) => dayKey(now - i * DAY_MS));
+}
+
+/**
+ * Is `day` playable? A player's local "today" can be UTC±1, so one day into
+ * the future is accepted, plus `backfillDays` into the past. Compared in
+ * whole UTC days, so it is locale-independent.
+ */
+export function inWindow(day: string, now: number, backfillDays: number): boolean {
+  if (!DAY_RE.test(day)) {
+    return false;
+  }
+  const dayStart = Date.parse(`${day}T00:00:00Z`);
+  const today = Date.parse(`${dayKey(now)}T00:00:00Z`);
+  if (Number.isNaN(dayStart) || Number.isNaN(today)) {
+    return false;
+  }
+  const diff = Math.round((dayStart - today) / DAY_MS);
+  return diff <= 1 && diff >= -backfillDays;
+}
+
+/**
+ * The deterministic uint32 seed for a (game, day): FNV-1a over `game#day`.
+ * The game derives its level or difficulty from it, so everyone plays the
+ * same challenge.
+ */
+export function seedForDay(game: string, day: string): number {
+  let hash = 2166136261 >>> 0;
+  const seedInput = `${game}#${day}`;
+  for (let i = 0; i < seedInput.length; i++) {
+    hash ^= seedInput.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}

package/src/logic/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Pure, browser-safe helpers every hub UI shares: time and count wording,
+ * presence status lines, race wording, and daily day keys and seeds.
+ */
+export * from './daily';
+export * from './presence';
+export * from './race';
+export * from './time';

package/src/logic/presence.ts

@@ -0,0 +1,62 @@
+/**
+ * How a friend's presence reads in every list: the status dot, label, game,
+ * detail and elapsed time (plan §5.2 of multiplayer.md: "consistent everywhere").
+ */
+import type { Presence } from '../api/social/presence';
+import { elapsed, relativeTime } from './time';
+
+/** The pieces of a status line, so renderers can bold the game title. */
+export interface StatusParts {
+  /** A coloured dot emoji. */
+  readonly dot: string;
+  /** 'Playing', 'In lobby', 'Away', 'Online', 'Last seen 3h ago'… */
+  readonly label: string;
+  /** The game title (rendered bold), or `''`. */
+  readonly game: string;
+  /** The game-provided detail, or `''`. */
+  readonly detail: string;
+  /** Elapsed time while playing (`'4:12'`), or `''`. */
+  readonly elapsed: string;
+  readonly online: boolean;
+  /** Their presence offers Join. */
+  readonly joinable: boolean;
+  /** Their presence offers Watch. */
+  readonly watchable: boolean;
+}
+
+/** Status line pieces for a friend; `p` is `null` when they are offline. */
+export function statusParts(presence: Presence | null, now: number, lastSeenAt = 0): StatusParts {
+  const base = { game: '', detail: '', elapsed: '', online: true, joinable: false, watchable: false };
+  if (!presence) {
+    return { ...base, online: false, dot: '⚪', label: lastSeenAt ? `Last seen ${relativeTime(lastSeenAt, now)}` : 'Offline' };
+  }
+  const game = presence.gameTitle ?? '';
+  const detail = presence.detail ?? '';
+  const hasRoom = presence.room !== undefined && presence.room !== '';
+  const flags = { joinable: presence.joinable === true && hasRoom, watchable: presence.watchable === true && hasRoom };
+  switch (presence.kind) {
+    case 'playing':
+      return { ...base, ...flags, dot: '🟢', label: 'Playing', game, detail, elapsed: elapsed(presence.since, now) };
+    case 'watching':
+      return { ...base, ...flags, dot: '🟢', label: 'Watching', game, detail };
+    case 'lobby':
+      return { ...base, ...flags, dot: '🟠', label: 'In lobby', game, detail };
+    case 'away':
+      return { ...base, dot: '🟡', label: 'Away', game };
+    case 'menu':
+      return { ...base, dot: '🟢', label: 'Online', game };
+  }
+}
+
+/** The status line as one string, e.g. "🟢 Playing 8 Ball Pool · Table vs Sam · 4:12". */
+export function statusText(parts: StatusParts): string {
+  const head = parts.label === 'Playing' || parts.label === 'Watching'
+    ? [parts.game ? `${parts.label} ${parts.game}` : parts.label]
+    : [parts.label, parts.game];
+  return `${parts.dot} ${[...head, parts.detail, parts.elapsed].filter(Boolean).join(' · ')}`;
+}
+
+/** The drawer header: "👥 3 friends online · 41 playing now". */
+export function headerLine(friendsOnline: number, online: number): string {
+  return `👥 ${String(friendsOnline)} friend${friendsOnline === 1 ? '' : 's'} online · ${String(online)} playing now`;
+}

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