@hopple/sdk 0.1.0-rc.3 → 1.0.0-next.1

package/manifest.d.ts

@@ -0,0 +1,1011 @@
+//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/manifest/src/manifest.d.ts
+/**
+ * The API a game is written against: `M.m`, a major and the least minor it
+ * needs, or `next`, the pre-releases of the next stable release.
+ *
+ * @group Manifest
+ * @category Important
+ * @pattern ^(?:(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)|next)$
+ * @errorMessage must be the API the game is written against, like "1.0", or "next"
+ */
+type ApiVersion = string;
+/**
+ * How the game wants to be held. The host decides what to do about it.
+ *
+ * @group Layout
+ */
+type Orientation = 'portrait' | 'landscape' | 'any';
+/**
+ * Whether the host may put its own furniture over the game's frame.
+ *
+ * The one layout question that has to be answered before the bundle runs, which
+ * is why it is declared here rather than asked at runtime: the host sizes the
+ * frame before there is a game to ask. A game that says nothing gets `reserve`,
+ * so a rail never lands on the buttons of something written before rails
+ * existed.
+ *
+ * @group Layout
+ */
+type InsetMode =
+/** The frame is the whole surface; read `sdk.layout` and keep out of the way. */
+'draw-under' |
+/** The host shrinks the frame clear of its own furniture. Nothing to avoid. */
+'reserve';
+/**
+ * What a game declares about layout. Absent means every default.
+ *
+ * @group Layout
+ * @category Useful
+ */
+type LayoutDeclaration = {
+  insets: InsetMode;
+};
+/**
+ * What a prop may hold, as one word. The three the wire carries, and no more.
+ *
+ * @group Analytics
+ */
+type AnalyticsType = 'string' | 'number' | 'boolean';
+/**
+ * One event's props. Every one optional: see `AnalyticsDeclaration`.
+ *
+ * Prop names follow the grammar event names do, which `@hopple/protocol`
+ * enforces on the wire too; a test keeps the two in step.
+ *
+ * @group Analytics
+ * @maxProperties 8
+ * @propertyNames { pattern: '^[a-z0-9]+(?:[._-][a-z0-9]+)*$', maxLength: 24, errorMessage: 'must be a prop name of lowercase letters, digits, dots, hyphens and underscores' }
+ */
+type AnalyticsShape = Record<string, AnalyticsType>;
+/**
+ * The custom events a game sends, and what each one carries.
+ *
+ * **The first key here whose reader is not the host.** `layout.insets` is
+ * declared because a frame has to be sized before there is a game to ask;
+ * nothing about analytics has to be answered before the bundle runs. What earns
+ * this its place is cardinality: names and columns invented at runtime make a
+ * pipe nobody can build a table for, and the party that has to build that table
+ * — the publish CLI, the server, a creator dashboard — is exactly the party that
+ * already reads the manifest and never talks to a game.
+ *
+ * **Every prop is optional and nothing is required**, which is what keeps the
+ * declaration cheap enough to be worth asking for: forgetting one costs a column
+ * rather than the event. The additive rule carries over unchanged — add events,
+ * add props, never retype one — and that is the whole of what a per-event table
+ * needs to survive the game's next version.
+ *
+ * @group Analytics
+ * @category Useful
+ */
+type AnalyticsDeclaration = {
+  /**
+   * Every event the game may send, by name.
+   *
+   * Names starting `hopple.` are the host's own records and not a game's to
+   * use. The grammar is the wire's too: `@hopple/protocol` enforces the same
+   * one, and a test keeps the two in step. At most 64 events: the wire never
+   * sees a declaration, so nothing enforces this at runtime and nothing has to.
+   *
+   * @maxProperties 64
+   * @propertyNames { pattern: '^[a-z0-9]+(?:[._-][a-z0-9]+)*$', maxLength: 48, not: { pattern: '^hopple\\.' }, errorMessage: 'must be lowercase letters, digits, dots, hyphens and underscores, and must not start with "hopple.", which the host uses' }
+   */
+  events: Record<string, AnalyticsShape>;
+};
+/**
+ * What a game expects to keep, in bytes.
+ *
+ * **The manifest's own test is whether the host must know before the bundle
+ * runs**, and here it must: a host that prefetches a save from a server has to
+ * know which games have one before there is a game to ask, and a publish
+ * pipeline that provisions storage has to know before a player exists.
+ *
+ * The budget the game expects, not a grant. A host answers with its own cap at
+ * the handshake, and a game with no key here may still call the API — it just
+ * gets nothing prefetched, which is the honest reading of not having said so.
+ *
+ * @group Save
+ * @category Useful
+ */
+type SaveDeclaration = {
+  /**
+   * At most 1 MiB. Not the same question as what a host will take — that is
+   * the host's and is settled at the handshake. This is only what is worth
+   * writing down: a declaration in the megabytes is a game that has
+   * misunderstood what this is for, and finding that out at publish time is
+   * cheaper than at a player's.
+   *
+   * @asType integer
+   * @exclusiveMinimum 0
+   * @maximum 1048576
+   */
+  bytes: number;
+};
+/**
+ * One thing a game makes noise with, as the player is offered it.
+ *
+ * The title is the whole of it, and required: this exists to be a label on a
+ * fader in a host's own panel, and a fader labelled `sfx2` is a control nobody
+ * can use. What a channel *is* — a bus, a set of samples, one oscillator — is
+ * the game's business and is never described here.
+ *
+ * @group Audio
+ */
+type AudioChannel = {
+  /**
+   * What to call it in front of a player.
+   *
+   * @category Important
+   * @pattern \S
+   * @maxLength 40
+   * @errorMessage must not be blank
+   */
+  title: string;
+};
+/**
+ * What this game makes noise with, so a host can offer a fader for each.
+ *
+ * **A map from the first version, even for a game with one channel.** The
+ * channel id travels in `audio.set`, which is frozen game-side code, and a
+ * single-channel key would have to *change meaning* to grow a second one — the
+ * one move the additive rule forbids.
+ *
+ * **The manifest's test is whether the host must know before the bundle runs**,
+ * and here it must twice over. The panel is drawn where the game's title is,
+ * which a host draws for games in a feed that nobody has opened; and the
+ * opening volumes ride in the handshake, so the host has to know which channels
+ * it is stating a volume for before there is a game to ask.
+ *
+ * **The key is required, and `null` is how a silent game says so.** Leaving it
+ * out would read the same as forgetting it, and a game that makes noise but
+ * never said so is one whose player cannot turn it down. An object with no
+ * channels is a game with sound and no tracks worth a fader of their own: it
+ * gets a master fader and a mute button and no more. What is never optional is
+ * obeying what the host then says: see `AudioState`.
+ *
+ * @group Audio
+ * @category Useful
+ */
+type AudioDeclaration = {
+  /**
+   * The channels, by id. Optional, and may be empty: either way there is only
+   * the master. At most 8: a panel of faders nobody can read is not a feature.
+   *
+   * `master` is refused rather than quietly shadowed. A master fader exists
+   * whether or not a game has said anything, and an author who wrote it meant
+   * something by it; a fader that turned out to be the host's own would be a
+   * control that ignored half of what they wired it to. The id grammar is the
+   * wire's too, and a test keeps the two in step.
+   *
+   * @maxProperties 8
+   * @propertyNames { pattern: '^[a-z0-9]+(?:[._-][a-z0-9]+)*$', maxLength: 48, not: { const: 'master' }, errorMessage: 'must be lowercase letters, digits, dots, hyphens and underscores, and must not be "master", which every host adds itself' }
+   */
+  channels?: Record<string, AudioChannel>;
+};
+/**
+ * Which way a board sorts — the one thing about a score that cannot be guessed.
+ *
+ * `desc` is the ordinary leaderboard, where more is better. `asc` is a time, a
+ * stroke count, a number of moves. Nothing downstream can infer this from the
+ * values it holds, and a client that guessed would render a time board upside
+ * down, so it is required rather than defaulted.
+ *
+ * @group Score
+ */
+type ScoreDirection = 'asc' | 'desc';
+/**
+ * How to draw the number.
+ *
+ * A client renders a board for a game it has never run, so it cannot ask the
+ * game what `224310` means. `integer` is a count, `decimal` a measurement,
+ * `duration-ms` a time to be written as minutes and seconds. Absent is
+ * `integer`, which is what most boards are.
+ *
+ * @group Score
+ */
+type ScoreFormat = 'integer' | 'decimal' | 'duration-ms';
+/** @group Score */
+type ScoreBoard = {
+  /**
+   * What to call it in front of a player.
+   *
+   * @category Important
+   * @pattern \S
+   * @maxLength 40
+   * @errorMessage must not be blank
+   */
+  title: string;
+  direction: ScoreDirection;
+  /** See `ScoreFormat`. Absent means `integer`. */
+  format?: ScoreFormat;
+};
+/**
+ * The boards this game keeps a score on.
+ *
+ * **A map from the first version, even for a game that wants one board.** The
+ * board id travels in `score.submit`, which is frozen game-side code, and a
+ * single-board key would have to *change meaning* to grow a second one — the
+ * one thing the additive rule forbids. A map costs a game with one board the
+ * few characters of naming it, and costs a game with four nothing at all.
+ *
+ * **Read by the host and by the server**, which is what earns it a key rather
+ * than a runtime call: a client draws a game's board in a sheet over a feed
+ * without ever having run that game, and the server has to know how a board
+ * sorts before it can answer a query about one.
+ *
+ * @group Score
+ * @category Useful
+ */
+type ScoreDeclaration = {
+  /**
+   * The boards, by id. At least one: a `score` key with no boards is a game
+   * that meant to declare one and did not, and reading it as "no boards" would
+   * hand it a scoreboard tab with nothing behind it. The id grammar is the
+   * wire's too, and a test keeps the two in step.
+   *
+   * @minProperties 1
+   * @maxProperties 16
+   * @propertyNames { pattern: '^[a-z0-9]+(?:[._-][a-z0-9]+)*$', maxLength: 48, errorMessage: 'must be lowercase letters, digits, dots, hyphens and underscores' }
+   */
+  boards: Record<string, ScoreBoard>;
+};
+/**
+ * One named step on the way to a measured achievement's target.
+ *
+ * **A tier is a label, never a second achievement.** The achievement is
+ * unlocked at its `target` and nowhere else; a tier is what a panel calls the
+ * player between here and there — *Silver, 50 of 100*. Modelling each tier as
+ * its own id would be three rows in every board that draws them and three
+ * unlocks a game has to remember to send, where this is one number reported
+ * once and read three ways.
+ *
+ * @group Achievements
+ */
+type AchievementTier = {
+  /**
+   * The reported value this tier is reached at, on the near side of the target.
+   *
+   * @minimum -9007199254740991
+   * @maximum 9007199254740991
+   */
+  at: number;
+  /**
+   * What to call the player who has reached it.
+   *
+   * @category Important
+   * @pattern \S
+   * @maxLength 40
+   * @errorMessage must not be blank
+   */
+  title: string;
+  /**
+   * A glyph for this tier, where it wants its own.
+   *
+   * @pattern \S
+   * @maxLength 8
+   * @errorMessage must not be blank
+   */
+  icon?: string;
+};
+/**
+ * What makes an achievement measured rather than flagged.
+ *
+ * **`direction` is the one thing that cannot be guessed**, exactly as it cannot
+ * be guessed for a board. `desc` — the default, and what most achievements are
+ * — counts up to the target: *break 100 blocks*. `asc` counts down to it:
+ * *finish under two minutes*, where the value kept is the player's best time
+ * and a smaller one beats a larger. A panel that assumed bigger-is-better would
+ * draw a stopwatch achievement as though every slow run were progress.
+ *
+ * **`format` is how to draw the number**, for the reason a board needs one:
+ * whoever renders this has never run the game and cannot ask it what `112400`
+ * means.
+ *
+ * Both are `ScoreDirection` and `ScoreFormat` rather than types of their own.
+ * "Which way is better" and "how is this number written" are the same two
+ * questions wherever they are asked, and a second spelling of each is two
+ * vocabularies to keep in step and one bug when they drift.
+ *
+ * @group Achievements
+ */
+type AchievementProgress = {
+  /**
+   * The value that unlocks it. Reaching it is the whole of being unlocked.
+   *
+   * Bounded by `Number.MAX_SAFE_INTEGER`, for the reason `SCORE_VALUE_MAX` is:
+   * past there a whole number stops round-tripping through JSON and through a
+   * 64-bit column, and progress toward a target nobody can reproduce is
+   * progress nobody can draw.
+   *
+   * @minimum -9007199254740991
+   * @maximum 9007199254740991
+   */
+  target: number;
+  /** Which way is better. Absent is `desc`: more is better. */
+  direction?: ScoreDirection;
+  /** How to draw the value. Absent is `integer`. */
+  format?: ScoreFormat;
+  /**
+   * Named milestones on the way, ordered toward the target.
+   *
+   * @maxItems 8
+   */
+  tiers?: AchievementTier[];
+};
+/**
+ * One thing a player can be shown to have done.
+ *
+ * **Two kinds, told apart by one key.** Without `progress` this is a flag: it
+ * happens once, and saying so twice is the same fact twice. With `progress` it
+ * is measured — a count, a distance, a best time — reported as the game goes
+ * and unlocked when the value reaches the target.
+ *
+ * **`secret` withholds the words, never the row.** A secret achievement is
+ * listed while it is locked, so a player can see there is one left, with its
+ * title and detail held back until it is theirs. Hiding the row itself would
+ * make the list's length change under the player, which reads as a bug rather
+ * than as a surprise. It is a courtesy of the panel and not a secret kept from
+ * the machine: the manifest ships beside the bundle and is public, so anybody
+ * who wants the words already has them.
+ *
+ * @group Achievements
+ */
+type Achievement = {
+  /**
+   * What to call it in front of a player.
+   *
+   * @category Important
+   * @pattern \S
+   * @maxLength 40
+   * @errorMessage must not be blank
+   */
+  title: string;
+  /**
+   * One line under the title, saying what it takes.
+   *
+   * @pattern \S
+   * @maxLength 120
+   * @errorMessage must not be blank
+   */
+  detail?: string;
+  /**
+   * A short glyph to draw beside it — an emoji, usually. Eight characters is
+   * enough for an emoji with a modifier on it.
+   *
+   * @pattern \S
+   * @maxLength 8
+   * @errorMessage must not be blank
+   */
+  icon?: string;
+  /** Whether the words are withheld until it is unlocked. See above. */
+  secret?: boolean;
+  /** Present makes this measured rather than flagged. See `AchievementProgress`. */
+  progress?: AchievementProgress;
+};
+/**
+ * The achievements this game keeps for a player.
+ *
+ * **A map, for the reason `score.boards` is one**: the id travels in
+ * `achievement.unlock`, which is frozen game-side code, so the shape has to
+ * hold a second entry without anything changing meaning.
+ *
+ * **Read by the host, by the client and by the server, and by none of them from
+ * the game.** The site draws this panel for a game sitting in the feed that has
+ * never been run; the server refuses an id no publisher declared. That is what
+ * earns a manifest key rather than a runtime call — the same test `score`
+ * passed.
+ *
+ * @group Achievements
+ * @category Useful
+ */
+type AchievementDeclaration = {
+  /**
+   * The achievements, by id. At least one: an `achievements` key with nothing
+   * in it is a game that meant to declare one and did not. The id grammar is
+   * the wire's too, and a test keeps the two in step.
+   *
+   * @minProperties 1
+   * @maxProperties 128
+   * @propertyNames { pattern: '^[a-z0-9]+(?:[._-][a-z0-9]+)*$', maxLength: 48, errorMessage: 'must be lowercase letters, digits, dots, hyphens and underscores' }
+   */
+  list: Record<string, Achievement>;
+};
+/**
+ * A device a game can be played with, as one word.
+ *
+ * Hardware rather than API surface: `mouse` and `touch` are separate words even
+ * though a game reads both through one pointer, because what a *client* does
+ * with this is decide whether to put a game in front of somebody who has no way
+ * to play it.
+ *
+ * @group Input
+ */
+type InputDevice = 'keyboard' | 'mouse' | 'touch' | 'gamepad';
+/**
+ * One set of devices that together are enough to play.
+ *
+ * @group Input
+ * @minItems 1
+ * @maxItems 8
+ */
+type InputDeviceSet = InputDevice[];
+/**
+ * A name for something that can *press* an action.
+ *
+ * `key.<code>` names a physical key by `KeyboardEvent.code` — **the code and
+ * never the character**. `KeyA` is the key where A sits on a US keyboard and
+ * stays that key on AZERTY, where it types Q, so a game that binds movement to
+ * codes has WASD under the same four fingers everywhere. `Escape` is the host's:
+ * it leaves fullscreen and pointer lock, which are invisible from inside the
+ * frame, and a game that bound it would lose that fight quietly on every press.
+ *
+ * `pad.south` is the south of either cluster: the face button on one pad and the
+ * d-pad's down on another, which is what makes one binding cover both. Compass
+ * words for both clusters, with no `pad.dpad.down` alias beside
+ * `pad.left.south` — a vocabulary that can never shrink should not start out
+ * doubled. A thumbstick is not one of these; see `InputStick`.
+ *
+ * @group Input
+ * @pattern ^(?:key\.(?!Escape$)(?=.{1,48}$)[A-Za-z][A-Za-z0-9]*|pointer\.(?:primary|secondary)|mouse\.(?:left|middle|right)|touch\.tap|controls\.(?=.{1,48}$)[a-z0-9]+(?:[_-][a-z0-9]+)*|pad\.(?:north|south|east|west|start|select)|pad\.(?:left|right)\.(?:north|south|east|west|bumper|trigger))$
+ * @errorMessage is not a binding this SDK knows (a thumbstick is read rather than bound, and Escape is the host's key)
+ */
+type InputBinding = string;
+/**
+ * A name for a thumbstick — something a game reads, never binds.
+ *
+ * @group Input
+ * @pattern ^(?:controls\.(?=.{1,48}$)[a-z0-9]+(?:[_-][a-z0-9]+)*|pad\.stick|pad\.(?:left|right)\.stick)$
+ * @errorMessage must name a thumbstick, such as pad.left.stick
+ */
+type InputStick = string;
+/**
+ * What presses an action: at least one binding, and at most 8.
+ *
+ * @group Input
+ * @minItems 1
+ * @maxItems 8
+ */
+type InputBindings = InputBinding[];
+/**
+ * One thing a player does, named by the game and bound to whatever produces it.
+ *
+ * **An action is a button and never an axis.** A key, a face button on a pad, a
+ * pointer button and an on-screen button all press the same action, because
+ * from the game's side they are the same event. A thumbstick is not one of
+ * those and is read through its own API — folding the two together would put a
+ * range on every binding that mostly does not have one, and would leave a game
+ * unable to say whether it meant the press or the lean.
+ *
+ * **An object rather than a bare list of bindings**, from the first version,
+ * because two strings are wanted the moment anybody draws this: a `title` for
+ * the remapping screen, which shows actions to a player and cannot show
+ * `move.left`, and a `label` for the face of an on-screen button. Growing a
+ * list into an object later would change what an action's value *is*, which is
+ * the one move the additive rule forbids. Only the object is accepted, even for
+ * an action that needs neither string: one way to write an action is one way to
+ * read it.
+ *
+ * @group Input
+ */
+type InputAction = {
+  /** What presses it. See `InputBinding` for the vocabulary. */
+  bind: InputBindings;
+  /**
+   * What to call it in front of a player, in a remapping screen.
+   *
+   * @pattern \S
+   * @maxLength 40
+   * @errorMessage must not be blank
+   */
+  title?: string;
+  /**
+   * What to draw on an on-screen button: a glyph, or a letter.
+   *
+   * @pattern \S
+   * @maxLength 8
+   * @errorMessage must not be blank
+   */
+  label?: string;
+};
+/**
+ * What presses a player's action on a pad or on the screen: a pad button, or
+ * an on-screen control. Keys and mouse buttons are a keyboard set's, in
+ * `PlayerInputDeclaration.keyboard`.
+ *
+ * @group Input
+ * @pattern ^(?:controls\.(?=.{1,48}$)[a-z0-9]+(?:[_-][a-z0-9]+)*|pad\.(?:north|south|east|west|start|select)|pad\.(?:left|right)\.(?:north|south|east|west|bumper|trigger))$
+ * @errorMessage must be a pad button or an on-screen control: a player's keys and mouse buttons go in input.player.keyboard
+ */
+type PlayerBinding = string;
+/**
+ * What presses a player's action on their part of the keyboard: a key, or a
+ * mouse button.
+ *
+ * @group Input
+ * @pattern ^(?:key\.(?!Escape$)(?=.{1,48}$)[A-Za-z][A-Za-z0-9]*|mouse\.(?:left|middle|right))$
+ * @errorMessage must be a key or a mouse button (and Escape is the host's key)
+ */
+type KeyboardBinding = string;
+/**
+ * One thing each player does: the same action for every local player, pressed
+ * by their own pad, their own part of the keyboard, or the on-screen controls.
+ *
+ * @group Input
+ */
+type PlayerInputAction = {
+  /**
+   * What presses it on a pad, the same for every pad, and on the screen.
+   * Leave it out for an action pressed only on the keyboard.
+   *
+   * @minItems 1
+   * @maxItems 8
+   */
+  bind?: PlayerBinding[];
+  /**
+   * What to call it in front of a player, in a remapping screen.
+   *
+   * @pattern \S
+   * @maxLength 40
+   * @errorMessage must not be blank
+   */
+  title?: string;
+  /**
+   * What to draw on an on-screen button: a glyph, or a letter.
+   *
+   * @pattern \S
+   * @maxLength 8
+   * @errorMessage must not be blank
+   */
+  label?: string;
+  /**
+   * Whether pressing it on a pad or a part of the keyboard nobody plays with
+   * makes a new player, while the game is taking players. Left out on every
+   * action, any of them does.
+   */
+  join?: boolean;
+};
+/**
+ * One part of the keyboard one player plays with: the keys and mouse buttons
+ * that press each of the player actions there.
+ *
+ * @group Input
+ */
+type KeyboardSet = {
+  /**
+   * What the players call it: *Left keys*, *Arrows*.
+   *
+   * @pattern \S
+   * @maxLength 40
+   * @errorMessage must not be blank
+   */
+  title?: string;
+  /**
+   * The keys and mouse buttons of each player action, by its id.
+   *
+   * @maxProperties 64
+   * @propertyNames { pattern: '^[a-z0-9]+(?:[._-][a-z0-9]+)*$', maxLength: 48, errorMessage: 'must be a player action id' }
+   */
+  bind: Record<string, KeyboardBinding[]>;
+};
+/**
+ * What each local player does, and how they share the keyboard.
+ *
+ * **One set of actions for every player.** Each local player has their own
+ * copy, pressed by the pad they hold, the part of the keyboard they play with,
+ * or the on-screen controls. A pad's buttons are the same for every pad, so any
+ * number of pads just works; the keyboard is split into sets, one player each,
+ * so the number of sets is how many can share it.
+ *
+ * @group Input
+ */
+type PlayerInputDeclaration = {
+  /**
+   * The actions each player has, by id: never an id `actions` declares too.
+   *
+   * @maxProperties 32
+   * @propertyNames { pattern: '^[a-z0-9]+(?:[._-][a-z0-9]+)*$', maxLength: 48, errorMessage: 'must be lowercase letters, digits, dots, hyphens and underscores' }
+   */
+  actions: Record<string, PlayerInputAction>;
+  /**
+   * The parts of the keyboard players play with, one player each, in the
+   * order they are offered. A player alone hears every one of them. Left out,
+   * the keyboard presses no player's action.
+   *
+   * @minItems 1
+   * @maxItems 4
+   */
+  keyboard?: KeyboardSet[];
+};
+/**
+ * How a group of on-screen buttons is arranged.
+ *
+ * Arrangement only, with the count doing the rest, so three across and five
+ * down need no words of their own. **A shape nobody recognises is drawn as a
+ * `column`** — the same escape `Obstruction.reserved` is. Whoever renders these
+ * may be older than the game that declared them, and a control that fails to
+ * appear is a game that cannot be played at all. It is still refused at
+ * publish, where saying so is cheap.
+ *
+ * @group Input
+ */
+type ControlShape = 'row' | 'column' | 'diamond' | 'cluster';
+/**
+ * One on-screen control: a group of buttons, or a thumbstick.
+ *
+ * **A button slot names an action; a stick slot names a stick.** The asymmetry
+ * is the hardware's. On-screen buttons have no fixed count or position — three
+ * across, five down, four in a diamond — so there is no standard control to
+ * unify them with, and the action is the only stable name they have. Thumbsticks
+ * come in twos and everybody agrees which is which, so a virtual one says which
+ * it stands for and a game reads the physical stick and this one through one id.
+ *
+ * There is no d-pad here. A d-pad is four buttons wherever it exists — four
+ * entries on the wire from a real pad, four keys on a keyboard — so a layout
+ * that wants one declares four buttons and binds them like anything else.
+ *
+ * @group Input
+ * @if { properties: { type: { const: 'buttons' } }, required: ['type'] }
+ * @then { required: ['buttons'], properties: { as: { type: 'object', additionalProperties: { $ref: '#/definitions/InputBinding' } }, axis: { not: {}, errorMessage: 'is only for a thumbstick' } } }
+ * @else { properties: { as: { $ref: '#/definitions/InputStick' } } }
+ */
+type ControlSlot = {
+  type: 'buttons' | 'thumbstick';
+  /**
+   * `buttons` only: the actions this control presses, in drawing order.
+   *
+   * @minItems 1
+   * @maxItems 8
+   */
+  buttons?: string[];
+  /** `buttons` only. See `ControlShape`. Absent is `column`. */
+  shape?: ControlShape;
+  /**
+   * What this control stands in for on a standard pad.
+   *
+   * On a thumbstick it is the stick id a game reads — `pad.left.stick` — so one
+   * `onStick` sees the physical stick and this one alike. Left out, the stick is
+   * only itself, which a game reads as `controls.<id>`. On a group of buttons it
+   * is a map from action to standard button, optional and rarely wanted: a game
+   * whose bindings already name `pad.south` needs nothing here, and this is for
+   * one that also wants the low-level path to see the press.
+   */
+  as?: InputStick | Record<string, InputBinding>;
+  /** `thumbstick` only. See `ControlAxis`. Absent, the stick moves both ways. */
+  axis?: ControlAxis;
+};
+/**
+ * The one direction an on-screen thumbstick moves in: `x` across, `y` up and
+ * down.
+ *
+ * For a game that steers along one line — a runner sliding left and right, a
+ * paddle — where a stick that also leans up and down is a thumb wandering off
+ * the line it means. The drawn stick becomes a track along that axis and always
+ * reports the other one as 0. **Only the drawn stick:** a real pad's stick still
+ * reports both, so a game reads the axis it wants from either.
+ *
+ * Whoever draws the controls may be older than the game, and draw a stick that
+ * moves both ways. The SDK zeroes the other axis whatever the renderer reports,
+ * so the game hears one axis either way.
+ *
+ * @group Input
+ */
+type ControlAxis = 'x' | 'y';
+/**
+ * The controls in one zone of a layout, by id.
+ *
+ * @group Input
+ * @maxProperties 8
+ * @propertyNames { pattern: '^[a-z0-9]+(?:[._-][a-z0-9]+)*$', maxLength: 48, errorMessage: 'must be a control id of lowercase letters, digits, dots, hyphens and underscores' }
+ */
+type ControlZoneSlots = Record<string, ControlSlot>;
+/**
+ * One named arrangement of on-screen controls.
+ *
+ * A game may declare several and switch between them — a menu wants different
+ * controls from play, and a driving section different ones again — which is why
+ * they are named rather than there being one. A zone nobody knows is a layout
+ * from a newer minor, which a host reads leniently, so whoever draws it simply
+ * has nowhere to put it.
+ *
+ * @group Input
+ */
+type ControlLayout = {
+  left?: ControlZoneSlots;
+  right?: ControlZoneSlots;
+  full?: ControlZoneSlots;
+};
+/**
+ * What a game says about how it is played.
+ *
+ * **It passes the manifest's test twice.** The host must know before the bundle
+ * runs — whether on-screen controls apply at all, and what a remapping screen
+ * offers, are settled before there is a game to ask — and it is read by parties
+ * that never run the game: a feed deciding whether to show a keyboard-only game
+ * to somebody holding a phone, and a remapping screen opened from outside a run.
+ *
+ * Action, control and layout ids follow the grammar the wire does, and a test
+ * keeps the two in step.
+ *
+ * @group Input
+ * @category Useful
+ */
+type InputDeclaration = {
+  /**
+   * The sets of hardware this game can be played with: any one set, every
+   * member of which must be present.
+   *
+   * A flat list of alternatives rather than a tree of `any` and `all`. Every
+   * real answer is a handful of alternatives, and this one renders straight into
+   * *needs a keyboard and a mouse* without anybody having written a solver.
+   *
+   * **The publisher's claim, taken at its word**, exactly as `orientation` is:
+   * nothing here checks it against the bindings. It cannot be checked. A game is
+   * free to read the platform directly — raw key events, an accelerometer, a
+   * microphone — and that is a stated allowance rather than an oversight, so
+   * what a game *binds* never implies what it can be played with.
+   *
+   * @minItems 1
+   * @maxItems 8
+   */
+  supported?: InputDeviceSet[];
+  /**
+   * The actions, by id.
+   *
+   * @maxProperties 64
+   * @propertyNames { pattern: '^[a-z0-9]+(?:[._-][a-z0-9]+)*$', maxLength: 48, errorMessage: 'must be lowercase letters, digits, dots, hyphens and underscores' }
+   */
+  actions?: Record<string, InputAction>;
+  /**
+   * Named arrangements of on-screen controls. See `ControlLayout`.
+   *
+   * @maxProperties 8
+   * @propertyNames { pattern: '^[a-z0-9]+(?:[._-][a-z0-9]+)*$', maxLength: 48, errorMessage: 'must be a layout name of lowercase letters, digits, dots, hyphens and underscores' }
+   */
+  controls?: Record<string, ControlLayout>;
+  /**
+   * What each local player does, beside `actions`, which are everybody's. See
+   * `PlayerInputDeclaration`.
+   */
+  player?: PlayerInputDeclaration;
+};
+/**
+ * How many people play a game on one device.
+ *
+ * Read by hosts before the game runs: a listing says *1–4 on one device*, and
+ * the input panel offers a row for each player.
+ *
+ * @group Input
+ * @category Useful
+ */
+type PlayersDeclaration = {
+  /**
+   * The most players on one device, each with their own copy of
+   * `input.player`'s actions. 1 when left out.
+   *
+   * @minimum 1
+   * @maximum 8
+   * @asType integer
+   */
+  local?: number;
+};
+/**
+ * A preview's revision: a whole number from 1, the `R` of its package's
+ * `0.R.p`. A breaking change to the preview is a new revision.
+ *
+ * @group Manifest
+ * @category Useful
+ * @minimum 1
+ * @asType integer
+ */
+type PreviewRevision = number;
+/**
+ * The previews a game is written against, each at the revision it needs.
+ *
+ * A preview is a part of the SDK that is not stable yet: its own `0.x`
+ * package, versioned apart from `api`, and served only to the games that
+ * declare it, at the revision they declare. A change to a preview reaches the
+ * games written against it and nobody else.
+ *
+ * @group Manifest
+ * @category Useful
+ */
+type PreviewsDeclaration = {
+  /**
+   * That this game plays over the network, in matches, at this revision of
+   * `@hopple/sdk-preview-network`: `sdk.match`.
+   *
+   * The permission a reviewer grants, and what lets a host offer *Play with
+   * friends* before the game has loaded. Nothing else about networking is
+   * declared: the way a match is played, and its size, are chosen by the game
+   * when it makes one. Absent, a game is never told about a match, and never
+   * reaches one.
+   */
+  network?: PreviewRevision;
+};
+/**
+ * Publishing refuses a key the manifest's API does not know; a host reading a
+ * published one ignores it (see `validateManifest`).
+ *
+ * @group Manifest
+ * @category Important
+ */
+type GameManifest = {
+  /**
+   * The API the game is written against. The major picks what the game is
+   * served; the minor is the least it needs. The CLI fills it from the
+   * installed `@hopple/sdk` when the config leaves it out.
+   *
+   * @category Important
+   */
+  api: ApiVersion;
+  /**
+   * Stable across versions, and unique among its publisher's games: it is the
+   * second half of the address the game is published at, `owner/id`, and the
+   * name every new version is filed under. Lowercase, url-safe, and no two
+   * hyphens in a row, because it ends up in urls and storage keys.
+   *
+   * @category Important
+   * @pattern ^[a-z0-9]+(?:-[a-z0-9]+)*$
+   * @maxLength 64
+   * @errorMessage must be lowercase letters, digits and hyphens
+   */
+  id: string;
+  /**
+   * The handle of the account the game is published under: the first half of
+   * `owner/id`. Absent, it is whoever publishes it. Present, only that account
+   * and the game's collaborators may publish it.
+   *
+   * @category Useful
+   * @pattern ^[a-z0-9]+(?:-[a-z0-9]+)*$
+   * @maxLength 64
+   * @errorMessage must be a handle: lowercase letters, digits and hyphens
+   */
+  owner?: string;
+  /**
+   * The game's own version, `MAJOR.MINOR.PATCH`. Ours to read, never to parse for meaning.
+   *
+   * @category Important
+   * @pattern ^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$
+   * @errorMessage must look like 1.0.0
+   */
+  version: string;
+  /**
+   * @category Important
+   * @pattern \S
+   * @maxLength 60
+   * @errorMessage must not be blank
+   */
+  title: string;
+  /**
+   * A sentence or two about the game, shown beside its title.
+   *
+   * @category Useful
+   * @pattern \S
+   * @maxLength 500
+   * @errorMessage must not be blank
+   */
+  description?: string;
+  /**
+   * A picture of the game, shown wherever a link to it is pasted — a chat, a
+   * post, a message.
+   *
+   * The path of a PNG, JPEG or WebP file, relative to the config the manifest
+   * is in, and at most `COVER_MAX_BYTES`. `hopple publish` uploads it beside
+   * the game. 1200 × 630 is the shape every platform shows whole; without one,
+   * a link shows Hopple's own card.
+   *
+   * @category Useful
+   * @pattern ^(?!/)(?!.*\.\.)[A-Za-z0-9._/-]+\.(?:png|jpe?g|webp)$
+   * @maxLength 200
+   * @errorMessage must be the path of a .png, .jpg or .webp file beside the config, like "cover.png"
+   */
+  cover?: string;
+  /** @category Important */
+  orientation: Orientation;
+  /**
+   * How the game wants the host's furniture handled. See `InsetMode`.
+   *
+   * @category Useful
+   */
+  layout?: LayoutDeclaration;
+  /**
+   * The custom events this game sends. See `AnalyticsDeclaration`.
+   *
+   * @category Useful
+   */
+  analytics?: AnalyticsDeclaration;
+  /**
+   * That this game keeps state, and roughly how much. See `SaveDeclaration`.
+   *
+   * @category Useful
+   */
+  save?: SaveDeclaration;
+  /**
+   * The boards this game keeps a score on. See `ScoreDeclaration`.
+   *
+   * @category Useful
+   */
+  score?: ScoreDeclaration;
+  /**
+   * What a player can be shown to have done. See `AchievementDeclaration`.
+   *
+   * @category Useful
+   */
+  achievements?: AchievementDeclaration;
+  /**
+   * How this game is played, and what it draws to be played with. See `InputDeclaration`.
+   *
+   * @category Useful
+   */
+  input?: InputDeclaration;
+  /**
+   * How many play on one device. See `PlayersDeclaration`.
+   *
+   * @category Useful
+   */
+  players?: PlayersDeclaration;
+  /**
+   * What this game makes noise with, one channel at a time, or `null` for a
+   * game that makes none. See `AudioDeclaration`.
+   *
+   * @category Important
+   */
+  audio: AudioDeclaration | null;
+  /**
+   * The previews this game is written against, each at its revision. See
+   * `PreviewsDeclaration`.
+   *
+   * @category Useful
+   */
+  previews?: PreviewsDeclaration;
+};
+/**
+ * @group Manifest
+ * @category Useful
+ */
+type ManifestProblem = {
+  /** The key at fault, or `''` when the document itself is the problem. */
+  field: string;
+  message: string;
+};
+/**
+ * @group Manifest
+ * @category Useful
+ */
+type ManifestCheck = {
+  ok: true;
+  manifest: GameManifest;
+} | {
+  ok: false;
+  problems: ManifestProblem[];
+};
+/**
+ * Check a parsed manifest, without throwing and without changing it.
+ *
+ * Every problem is reported, not just the first: someone fixing a manifest
+ * wants the list, and a validator that reveals one error per run is a validator
+ * people stop running. A key the manifest does not know is refused, since a
+ * misspelt one would otherwise mean nothing in silence; `lenient` ignores it
+ * instead, for reading a manifest that was published, possibly against a newer
+ * minor than this one. A key we *do* know, spelled wrongly, is refused either
+ * way: `"draw_under"` would otherwise mean `reserve` in silence, and silence
+ * here looks exactly like a bug in the host.
+ *
+ * @group Manifest
+ * @category Important
+ */
+declare function validateManifest(value: unknown, options?: {
+  lenient?: boolean;
+}): ManifestCheck;
+/**
+ * One line per problem, worded the same wherever a manifest is rejected.
+ *
+ * Field names are set in backticks, because plenty of them are ordinary words
+ * — "entry is required" reads as a sentence about some entry, and
+ * "`entry` is required" names a key.
+ *
+ * @group Manifest
+ * @category Useful
+ */
+declare function describeProblems(problems: readonly ManifestProblem[]): string;
+//#endregion
+export { type ManifestCheck, type ManifestProblem, describeProblems, validateManifest };