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

package/src/logic/presence.ts

@@ -1,62 +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`;
-}
+/**
+ * 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/time.ts

@@ -1,81 +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)}`;
-}
+/**
+ * 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

@@ -1,55 +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);
-    });
-  });
+/**
+ * `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

@@ -1,42 +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>;
+/**
+ * `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>;