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

package/src/manifest/fields.ts

@@ -1,89 +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');
+/**
+ * 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

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

@@ -1,12 +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';
+/**
+ * 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

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

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