@hopple/sdk 1.0.0-next.1 → 1.0.0-next.4

package/README.md

@@ -673,8 +673,44 @@ sdk.input.controls.showing;        // whether controls are actually visible
 - Hiding them only stops drawing them; keys and gamepads keep working.
 - While shown, they appear in `sdk.layout.obstructions` as reserved
   rectangles, so code that avoids the host's buttons avoids them too.
-- They are drawn in a shadow root inside your frame, so your CSS can't affect
-  them and they don't appear in your DOM.
+- They are drawn in a shadow root inside your frame, so they don't appear in
+  your DOM and your CSS only reaches them where it is meant to: through
+  `hopple-controls::part(…)` and the `--hopple-pad-*` properties (see
+  [Styling them](#styling-the-on-screen-controls)).
+
+### Styling the on-screen controls
+
+```css
+hopple-controls {
+  --hopple-pad-tint: #2b1d0ecc;            /* a button's fill */
+  --hopple-pad-edge: #f5c542;              /* rims, the knob */
+  --hopple-pad-ink: #fff8e1;               /* labels and icons */
+  --hopple-pad-radius: 14px;
+  --hopple-pad-font: 700 16px/1 'My Font', sans-serif, hopple-keys;
+}
+hopple-controls::part(face pressed) { translate: 0 2px; }
+hopple-controls::part(face action-jump) { background: url(ui/jump.png) center / 70% no-repeat; }
+```
+
+```ts
+sdk.input.icon('jump', 'M12 3 4 13h5v8h6v-8h5z');   // a filled path in a 24×24 box, or null
+```
+
+- Parts: `face`, `label` and `icon` on a button; `group` behind a group of
+  buttons; `well`, `knob`, `groove` and `arrow` on a stick. Each also carries
+  `action-<id>` and `control-<id>`, and the states `pressed`, `held`,
+  `floating` and `resting`.
+- `<hopple-controls>` has `layout`, `sticks` and `look` attributes, and a
+  stick has `--hopple-stick-x` and `--hopple-stick-y` (−1 to 1) for a game to
+  read.
+- Sizes (`--hopple-pad-size`, `-stick`, `-track`, `-gap`, `-inset`) are held
+  between a size a thumb can press and one that leaves the game room. How big
+  one control is next to the others is its `scale` in the manifest. What a
+  part draws never changes where a touch lands.
+- A player can turn a game's look off, for every game or for one, and gets the
+  plain controls back: test that they still read well over the game.
+- Under `hopple dev`, a rule that names a part or a property the controls don't
+  have is reported to `onError`.
 
 ### Several players on one device
 

package/config.schema.json

@@ -63,6 +63,11 @@
           "maxLength": 64,
           "errorMessage": "must be a handle: lowercase letters, digits and hyphens"
         },
+        "publishable": {
+          "type": "boolean",
+          "description": "`false` for a game that is never to be uploaded: an example, a test, a game kept to one machine. `hopple dev` and `hopple check` still run it; `hopple upload` and `hopple publish` refuse it, and so does a server it is sent to another way. Absent, it may be published.",
+          "markdownDescription": "`false` for a game that is never to be uploaded: an example, a test, a\ngame kept to one machine. `hopple dev` and `hopple check` still run it;\n`hopple upload` and `hopple publish` refuse it, and so does a server it\nis sent to another way. Absent, it may be published."
+        },
         "version": {
           "type": "string",
           "description": "The game's own version, `MAJOR.MINOR.PATCH`. Ours to read, never to parse for meaning.",
@@ -84,6 +89,16 @@
           "maxLength": 500,
           "errorMessage": "must not be blank"
         },
+        "genres": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/GameGenre"
+          },
+          "description": "What kind of game it is, the main one first. Read by whoever files it in a catalogue, which never runs it. At most `GENRE_MAX`, not counting `local-multiplayer` and `online-multiplayer`: a game that is every kind tells a player nothing. The publisher's claim, taken at its word, except for those two. See `GameGenre`.",
+          "markdownDescription": "What kind of game it is, the main one first. Read by whoever files it in a\ncatalogue, which never runs it. At most `GENRE_MAX`, not counting\n`local-multiplayer` and `online-multiplayer`: a game that is every kind\ntells a player nothing. The publisher's claim, taken at its word, except\nfor those two. See `GameGenre`.",
+          "minItems": 1,
+          "maxItems": 5
+        },
         "cover": {
           "type": "string",
           "description": "A picture of the game, shown wherever a link to it is pasted — a chat, a post, a message.\n\nThe 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.",
@@ -165,6 +180,34 @@
       "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\""
     },
+    "GameGenre": {
+      "type": "string",
+      "enum": [
+        "racing",
+        "shooter",
+        "platformer",
+        "puzzle",
+        "arcade",
+        "physics",
+        "roguelike",
+        "strategy",
+        "building",
+        "idle",
+        "sports",
+        "horror",
+        "stealth",
+        "fighting",
+        "casual",
+        "simulation",
+        "adventure",
+        "rhythm",
+        "rpg",
+        "local-multiplayer",
+        "online-multiplayer"
+      ],
+      "description": "What kind of game this is, as one word from a list every game shares.\n\nA closed list, because a client files games under these and has to name each one in front of a player: left to free text, one kind of game becomes three spellings of it with a game each. The list only grows, since a published manifest has to stay valid. Whoever reads one may be older than the game, and ignores a word it does not know.\n\n`local-multiplayer` and `online-multiplayer` say how a game is played rather than what it is, and only count where the manifest bears them out: see `declaredGenres`.",
+      "markdownDescription": "What kind of game this is, as one word from a list every game shares.\n\nA closed list, because a client files games under these and has to name each\none in front of a player: left to free text, one kind of game becomes three\nspellings of it with a game each. The list only grows, since a published\nmanifest has to stay valid. Whoever reads one may be older than the game, and\nignores a word it does not know.\n\n`local-multiplayer` and `online-multiplayer` say how a game is played rather\nthan what it is, and only count where the manifest bears them out: see\n`declaredGenres`."
+    },
     "Orientation": {
       "type": "string",
       "enum": [
@@ -678,6 +721,13 @@
           "$ref": "#/definitions/ControlAxis",
           "description": "`thumbstick` only. See `ControlAxis`. Absent, the stick moves both ways.",
           "markdownDescription": "`thumbstick` only. See `ControlAxis`. Absent, the stick moves both ways."
+        },
+        "scale": {
+          "type": "number",
+          "description": "How big this control is next to the layout's others: `1.25` for a jump button a thumb lands on without looking, `0.8` for one pressed now and then. Absent, 1.\n\nA size in the layout rather than in the game's stylesheet, because whether the layout fits on a small screen is worked out from it before the controls are drawn. A game's stylesheet changes how they look, never how much of the screen they answer in.",
+          "markdownDescription": "How big this control is next to the layout's others: `1.25` for a jump\nbutton a thumb lands on without looking, `0.8` for one pressed now and then.\nAbsent, 1.\n\nA size in the layout rather than in the game's stylesheet, because whether\nthe layout fits on a small screen is worked out from it before the\ncontrols are drawn. A game's stylesheet changes how they look, never how\nmuch of the screen they answer in.",
+          "minimum": 0.75,
+          "maximum": 1.5
         }
       },
       "required": [

package/index.d.ts

@@ -1,4 +1,4 @@
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/protocol/src/analytics.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/protocol/src/analytics.d.ts
 /**
  * What a game says happened.
  *
@@ -29,7 +29,7 @@ type AnalyticsValue = string | number | boolean;
 /** @group Analytics */
 type AnalyticsProps = Record<string, AnalyticsValue>;
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/protocol/src/errors.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/protocol/src/errors.d.ts
 /**
  * How a call fails.
  *
@@ -115,7 +115,7 @@ declare class BridgeError extends Error {
   constructor(error: ProtocolError);
 }
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/protocol/src/input.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/protocol/src/input.d.ts
 /**
  * What the host says about how this game is being played.
  *
@@ -175,7 +175,7 @@ type InputBinding = {
   label?: string;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/protocol/src/pause.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/protocol/src/pause.d.ts
 /**
  * Whether the game is holding still, which the host may ask for and only the
  * game can answer.
@@ -233,7 +233,7 @@ type PauseState =
  */
 'unpausable';
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/protocol/src/save.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/protocol/src/save.d.ts
 /**
  * The one thing a game may keep.
  *
@@ -284,7 +284,7 @@ type SaveStored = {
   bytes: number;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/protocol/src/score.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/protocol/src/score.d.ts
 /**
  * What the host says came of it.
  *
@@ -322,7 +322,7 @@ type ScoreStanding = {
   of?: number;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/protocol/src/share.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/protocol/src/share.d.ts
 /**
  * A link to this game, offered to the player by the host.
  *
@@ -421,7 +421,7 @@ type ShareMeta = {
   [key: string]: ShareMetaValue;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/protocol/src/methods.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/protocol/src/methods.d.ts
 /**
  * How far a game has got with its own preparation.
  *
@@ -601,7 +601,7 @@ type DeviceInfo = {
   tier: DeviceTier;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/protocol/src/listeners.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/protocol/src/listeners.d.ts
 /**
  * The one way anything here is listened to: `on(listener)` hands back the
  * function that stops it.
@@ -630,7 +630,7 @@ type DeviceInfo = {
  */
 type Unsubscribe = () => void;
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/manifest/src/manifest.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/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.
@@ -1309,6 +1309,20 @@ type ControlSlot = {
   as?: InputStick | Record<string, InputBinding$1>;
   /** `thumbstick` only. See `ControlAxis`. Absent, the stick moves both ways. */
   axis?: ControlAxis;
+  /**
+   * How big this control is next to the layout's others: `1.25` for a jump
+   * button a thumb lands on without looking, `0.8` for one pressed now and then.
+   * Absent, 1.
+   *
+   * A size in the layout rather than in the game's stylesheet, because whether
+   * the layout fits on a small screen is worked out from it before the
+   * controls are drawn. A game's stylesheet changes how they look, never how
+   * much of the screen they answer in.
+   *
+   * @minimum 0.75
+   * @maximum 1.5
+   */
+  scale?: number;
 };
 /**
  * The one direction an on-screen thumbstick moves in: `x` across, `y` up and
@@ -1459,6 +1473,23 @@ type PreviewsDeclaration = {
    */
   network?: PreviewRevision;
 };
+/**
+ * What kind of game this is, as one word from a list every game shares.
+ *
+ * A closed list, because a client files games under these and has to name each
+ * one in front of a player: left to free text, one kind of game becomes three
+ * spellings of it with a game each. The list only grows, since a published
+ * manifest has to stay valid. Whoever reads one may be older than the game, and
+ * ignores a word it does not know.
+ *
+ * `local-multiplayer` and `online-multiplayer` say how a game is played rather
+ * than what it is, and only count where the manifest bears them out: see
+ * `declaredGenres`.
+ *
+ * @group Manifest
+ * @category Useful
+ */
+type GameGenre = 'racing' | 'shooter' | 'platformer' | 'puzzle' | 'arcade' | 'physics' | 'roguelike' | 'strategy' | 'building' | 'idle' | 'sports' | 'horror' | 'stealth' | 'fighting' | 'casual' | 'simulation' | 'adventure' | 'rhythm' | 'rpg' | 'local-multiplayer' | 'online-multiplayer';
 /**
  * Publishing refuses a key the manifest's API does not know; a host reading a
  * published one ignores it (see `validateManifest`).
@@ -1498,6 +1529,15 @@ type GameManifest = {
    * @errorMessage must be a handle: lowercase letters, digits and hyphens
    */
   owner?: string;
+  /**
+   * `false` for a game that is never to be uploaded: an example, a test, a
+   * game kept to one machine. `hopple dev` and `hopple check` still run it;
+   * `hopple upload` and `hopple publish` refuse it, and so does a server it
+   * is sent to another way. Absent, it may be published.
+   *
+   * @category Useful
+   */
+  publishable?: boolean;
   /**
    * The game's own version, `MAJOR.MINOR.PATCH`. Ours to read, never to parse for meaning.
    *
@@ -1522,6 +1562,18 @@ type GameManifest = {
    * @errorMessage must not be blank
    */
   description?: string;
+  /**
+   * What kind of game it is, the main one first. Read by whoever files it in a
+   * catalogue, which never runs it. At most `GENRE_MAX`, not counting
+   * `local-multiplayer` and `online-multiplayer`: a game that is every kind
+   * tells a player nothing. The publisher's claim, taken at its word, except
+   * for those two. See `GameGenre`.
+   *
+   * @category Useful
+   * @minItems 1
+   * @maxItems 5
+   */
+  genres?: GameGenre[];
   /**
    * A picture of the game, shown wherever a link to it is pasted — a chat, a
    * post, a message.
@@ -1654,7 +1706,7 @@ type ProjectManifest = Omit<GameManifest, 'api'> & {
   api?: ApiVersion;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/game/src/achievements.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/achievements.d.ts
 /**
  * Where this player stands on one achievement.
  *
@@ -1752,7 +1804,7 @@ type Achievements<Id extends string = string, Measured extends string = Id> = {
   progress(id: Measured, value: number): void;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/game/src/analytics.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/analytics.d.ts
 /**
  * @group Analytics
  * @category Important
@@ -1769,7 +1821,7 @@ type Analytics<Events extends object = Record<string, AnalyticsProps>> = {
   track<Event extends keyof Events & string>(name: Event, props?: Events[Event]): void;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/game/src/audio.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/audio.d.ts
 /**
  * Something about the game's sound changed: the host's order, the player's
  * mute, a fader. Read what you need — `volume(channel)`, `allowed` — and apply
@@ -1860,7 +1912,7 @@ type Audio<Channel extends string = string> = {
   media(element: HTMLMediaElement, channel?: Channel): Unsubscribe;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/game/src/info.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/info.d.ts
 /**
  * What the host said, frozen.
  *
@@ -1878,7 +1930,7 @@ type Info = Readonly<{
   device: Readonly<DeviceInfo>;
 }>;
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/game/src/layout.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/layout.d.ts
 /**
  * How much of each edge belongs to the host. CSS pixels.
  *
@@ -1988,7 +2040,7 @@ type InsetPolicy = {
  */
 declare function insetsFrom(obstructions: readonly Obstruction[], frame: Size, policy?: InsetPolicy): Insets;
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/game/src/names.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/names.d.ts
 /**
  * The keys of a declared map, or `string` where the map is not a literal one —
  * which is what a manifest typed as the wide `GameManifest` gives — and
@@ -2108,7 +2160,7 @@ type EventProps<M> = M extends {
  */
 type StickName = 'pad.left.stick' | 'pad.right.stick' | 'pad.stick' | `controls.${string}`;
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/game/src/input/state.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/input/state.d.ts
 /**
  * Where the pointer is, in the frame's own coordinates.
  *
@@ -2169,7 +2221,7 @@ type InputSnapshot<Action extends string = string> = {
   pointer: PointerState | null;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/game/src/input/players.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/input/players.d.ts
 /**
  * What one player holds: a pad, one part of the keyboard, or the on-screen
  * controls.
@@ -2191,7 +2243,7 @@ type Controller =
   kind: 'touch';
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/game/src/input/index.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/input/index.d.ts
 /**
  * A binding a game can name on its own, for a prompt about a button that is
  * not one of its actions: `pad.start`, `key.Space`.
@@ -2301,6 +2353,22 @@ type Input<Action extends string = string, Layout extends string = string, Playe
   describe(name: Action | ButtonName): string;
   /** The font family `glyph` draws in: name it, last, wherever a glyph is printed. */
   readonly font: string;
+  /**
+   * Draw an icon on an action's on-screen button instead of its label, or
+   * `null` to go back to the label.
+   *
+   *     hopple.input.icon('jump', 'M12 3 4 13h5v8h6v-8h5z');
+   *
+   * One SVG path, filled in the buttons' ink, in a 24 by 24 box: what icon
+   * sets draw filled icons in. The label stays the button's name for a screen
+   * reader. `glyph(action)` on a touch screen draws the same icon, so a prompt
+   * matches the button. A path that cannot be read, or that leaves the box, is
+   * reported to `onError` and the label is drawn instead.
+   *
+   * How the controls look otherwise is the game's stylesheet's: see the
+   * skill's input guide.
+   */
+  icon(action: Action, path: string | null): void;
   /**
    * Stop reading input and let go of everything held.
    *
@@ -2412,7 +2480,7 @@ type Controls<Layout extends string = string> = {
   readonly available: boolean;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/game/src/lifecycle.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/lifecycle.d.ts
 /** @group Lifecycle */
 type LifecycleListener = (phase: Phase, previous: Phase) => void | Promise<void>;
 /**
@@ -2431,7 +2499,7 @@ type Lifecycle = {
   on(listener: LifecycleListener): Unsubscribe;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/game/src/loop.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/loop.d.ts
 /**
  * The host has let the game run its loop, or stopped it. Return a promise to
  * make the host wait.
@@ -2485,7 +2553,7 @@ type Loop = {
   tick(frame: FrameCallback): Unsubscribe;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/game/src/panel.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/panel.d.ts
 /**
  * The pages of the host's panel a game has a name for, as the keys of this
  * interface.
@@ -2623,7 +2691,7 @@ type Panel = {
   open(page: PageId): void;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/game/src/pause.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/pause.d.ts
 /**
  * The host has asked for a pause, or for the game to carry on.
  *
@@ -2684,7 +2752,7 @@ type Pause = {
   on(listener: PauseListener): Unsubscribe;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/game/src/resources.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/resources.d.ts
 /**
  * The host has let the game hold its resources again, or asked for them back.
  * Return a promise to make the host wait until they have gone, or come back.
@@ -2714,7 +2782,7 @@ type Resources = {
   on(listener: ResourcesListener): Unsubscribe;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/game/src/save.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/save.d.ts
 /**
  * What a game gets back from a read: its own schema number, and its state.
  *
@@ -2851,7 +2919,7 @@ type Save = {
   readonly maxBytes: number;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/game/src/score.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/score.d.ts
 /**
  * Where this player stands on every board, as far as anybody has said.
  *
@@ -2928,7 +2996,7 @@ type Score<Board extends string = string> = {
   }): Promise<ScoreResult>;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/game/src/share.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/share.d.ts
 /**
  * @group Share
  * @category Important
@@ -3000,7 +3068,7 @@ type Share = {
   }): void;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/game/src/init.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/init.d.ts
 /**
  * What `init` hands back: every namespace a game has, on one object.
  *

package/index.js

@@ -1,4 +1,4 @@
-/*! @hopple/sdk 1.0.0-next.1 | Copyright (c) 2026 The Hopple authors | MIT License */
+/*! @hopple/sdk 1.0.0-next.4 | Copyright (c) 2026 The Hopple authors | MIT License */
 // The SDK runs from the runtime the page loads as its first script, which
 // defines the global `Hopple`; this forwards each export to it.
 const runtime = globalThis.Hopple;

package/manifest.d.ts

@@ -1,4 +1,4 @@
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/manifest/src/manifest.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/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.
@@ -671,6 +671,20 @@ type ControlSlot = {
   as?: InputStick | Record<string, InputBinding>;
   /** `thumbstick` only. See `ControlAxis`. Absent, the stick moves both ways. */
   axis?: ControlAxis;
+  /**
+   * How big this control is next to the layout's others: `1.25` for a jump
+   * button a thumb lands on without looking, `0.8` for one pressed now and then.
+   * Absent, 1.
+   *
+   * A size in the layout rather than in the game's stylesheet, because whether
+   * the layout fits on a small screen is worked out from it before the
+   * controls are drawn. A game's stylesheet changes how they look, never how
+   * much of the screen they answer in.
+   *
+   * @minimum 0.75
+   * @maximum 1.5
+   */
+  scale?: number;
 };
 /**
  * The one direction an on-screen thumbstick moves in: `x` across, `y` up and
@@ -821,6 +835,23 @@ type PreviewsDeclaration = {
    */
   network?: PreviewRevision;
 };
+/**
+ * What kind of game this is, as one word from a list every game shares.
+ *
+ * A closed list, because a client files games under these and has to name each
+ * one in front of a player: left to free text, one kind of game becomes three
+ * spellings of it with a game each. The list only grows, since a published
+ * manifest has to stay valid. Whoever reads one may be older than the game, and
+ * ignores a word it does not know.
+ *
+ * `local-multiplayer` and `online-multiplayer` say how a game is played rather
+ * than what it is, and only count where the manifest bears them out: see
+ * `declaredGenres`.
+ *
+ * @group Manifest
+ * @category Useful
+ */
+type GameGenre = 'racing' | 'shooter' | 'platformer' | 'puzzle' | 'arcade' | 'physics' | 'roguelike' | 'strategy' | 'building' | 'idle' | 'sports' | 'horror' | 'stealth' | 'fighting' | 'casual' | 'simulation' | 'adventure' | 'rhythm' | 'rpg' | 'local-multiplayer' | 'online-multiplayer';
 /**
  * Publishing refuses a key the manifest's API does not know; a host reading a
  * published one ignores it (see `validateManifest`).
@@ -860,6 +891,15 @@ type GameManifest = {
    * @errorMessage must be a handle: lowercase letters, digits and hyphens
    */
   owner?: string;
+  /**
+   * `false` for a game that is never to be uploaded: an example, a test, a
+   * game kept to one machine. `hopple dev` and `hopple check` still run it;
+   * `hopple upload` and `hopple publish` refuse it, and so does a server it
+   * is sent to another way. Absent, it may be published.
+   *
+   * @category Useful
+   */
+  publishable?: boolean;
   /**
    * The game's own version, `MAJOR.MINOR.PATCH`. Ours to read, never to parse for meaning.
    *
@@ -884,6 +924,18 @@ type GameManifest = {
    * @errorMessage must not be blank
    */
   description?: string;
+  /**
+   * What kind of game it is, the main one first. Read by whoever files it in a
+   * catalogue, which never runs it. At most `GENRE_MAX`, not counting
+   * `local-multiplayer` and `online-multiplayer`: a game that is every kind
+   * tells a player nothing. The publisher's claim, taken at its word, except
+   * for those two. See `GameGenre`.
+   *
+   * @category Useful
+   * @minItems 1
+   * @maxItems 5
+   */
+  genres?: GameGenre[];
   /**
    * A picture of the game, shown wherever a link to it is pasted — a chat, a
    * post, a message.

package/manifest.js

@@ -1,4 +1,4 @@
-/*! @hopple/sdk 1.0.0-next.1 | Copyright (c) 2026 The Hopple authors | MIT License */
+/*! @hopple/sdk 1.0.0-next.4 | Copyright (c) 2026 The Hopple authors | MIT License */
 //#region ../manifest/src/manifest.schema.ts
 const GameManifest = {
 	"type": "object",
@@ -16,6 +16,7 @@ const GameManifest = {
 			"maxLength": 64,
 			"errorMessage": "must be a handle: lowercase letters, digits and hyphens"
 		},
+		"publishable": { "type": "boolean" },
 		"version": {
 			"type": "string",
 			"pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$",
@@ -33,6 +34,12 @@ const GameManifest = {
 			"maxLength": 500,
 			"errorMessage": "must not be blank"
 		},
+		"genres": {
+			"type": "array",
+			"items": { "$ref": "#/definitions/GameGenre" },
+			"minItems": 1,
+			"maxItems": 5
+		},
 		"cover": {
 			"type": "string",
 			"pattern": "^(?!/)(?!.*\\.\\.)[A-Za-z0-9._/-]+\\.(?:png|jpe?g|webp)$",
@@ -65,6 +72,32 @@ const ApiVersion = {
 	"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\""
 };
+const GameGenre = {
+	"type": "string",
+	"enum": [
+		"racing",
+		"shooter",
+		"platformer",
+		"puzzle",
+		"arcade",
+		"physics",
+		"roguelike",
+		"strategy",
+		"building",
+		"idle",
+		"sports",
+		"horror",
+		"stealth",
+		"fighting",
+		"casual",
+		"simulation",
+		"adventure",
+		"rhythm",
+		"rpg",
+		"local-multiplayer",
+		"online-multiplayer"
+	]
+};
 const Orientation = {
 	"type": "string",
 	"enum": [
@@ -372,7 +405,12 @@ const ControlSlot = {
 			"type": "object",
 			"additionalProperties": { "$ref": "#/definitions/InputBinding" }
 		}] },
-		"axis": { "$ref": "#/definitions/ControlAxis" }
+		"axis": { "$ref": "#/definitions/ControlAxis" },
+		"scale": {
+			"type": "number",
+			"minimum": .75,
+			"maximum": 1.5
+		}
 	},
 	"required": ["type"],
 	"additionalProperties": false,
@@ -412,6 +450,7 @@ const InputStick = {
 const definitions = {
 	GameManifest,
 	ApiVersion,
+	GameGenre,
 	Orientation,
 	LayoutDeclaration,
 	InsetMode,
@@ -573,6 +612,7 @@ const definitions = {
 };
 AchievementProgress.properties.target.maximum;
 GameManifest.required;
+GameGenre.enum;
 /**
 * The zones a layout places controls in, in the order they are drawn.
 *
@@ -750,6 +790,9 @@ function walkObject(node, value, path, fail, lenient) {
 	}
 }
 function checkReferences(manifest, fail) {
+	const genres = manifest.genres ?? [];
+	for (const genre of new Set(genres.filter((one, index) => genres.indexOf(one) !== index))) fail("genres", `names "${genre}" twice`);
+	if (genres.filter((genre) => !MULTIPLAYER_GENRES.includes(genre)).length > 3) fail("genres", `must hold at most 3 genres, beside local-multiplayer and online-multiplayer`);
 	const players = manifest.input?.player;
 	const own = new Set(Object.keys(players?.actions ?? {}));
 	const actions = /* @__PURE__ */ new Set([...Object.keys(manifest.input?.actions ?? {}), ...own]);
@@ -787,6 +830,8 @@ function checkReferences(manifest, fail) {
 		}
 	}
 }
+/** The genres that say how a game is played together rather than what it is. */
+const MULTIPLAYER_GENRES = ["local-multiplayer", "online-multiplayer"];
 /**
 * Whether `a` beats `b` on a board sorted this way. Ties are not improvements.
 *

package/manifest.md

@@ -35,6 +35,7 @@ leave `api` and `previews` out: the CLI fills `api` from the installed
 | `version` | `MAJOR.MINOR.PATCH`, optional `-prerelease` | The game's own version. Shown to the game as `sdk.info.game.version`. |
 | `title` | at most 60 characters | What players see. |
 | `description` | optional; at most 500 characters | A sentence or two shown beside the title. |
+| `genres` | optional; see [`genres`](#genres) | What kind of game it is, the main one first. |
 | `orientation` | `portrait`, `landscape` or `any` | The shape the game is designed for. Hosts lay the game out to match. |
 | `audio` | `null`, or an object | Whether the game makes sound, and its volume channels. See [`audio`](#audio). |
 
@@ -219,7 +220,8 @@ up to 8 characters, 8 tiers.
   `buttons` (naming actions) arranged as a `row`, `column`, `diamond` or
   `cluster`. An unknown shape is drawn as a column. A stick held to an axis is
   drawn as a track and always reads 0 on the other axis; a real pad's stick
-  still reports both.
+  still reports both. Any control may have a `scale` from 0.75 to 1.5, its
+  size next to the layout's others (1 when left out).
 
 Binding names:
 
@@ -295,6 +297,31 @@ Each channel gets its own labelled volume slider in the host's sound controls.
 `title` is required: it is the slider's label. `master` is reserved, since
 every host already has a master volume. At most 8 channels.
 
+### genres
+
+```json
+"genres": ["puzzle", "shooter", "online-multiplayer"]
+```
+
+What kind of game this is, the main one first: at least one, and at most 3
+beside the two multiplayer words, none twice. A game with none declared is
+filed by what its title and description say, and most often less well.
+
+The words are `racing`, `shooter`, `platformer`, `puzzle`, `arcade`, `physics`,
+`roguelike`, `strategy`, `building`, `idle`, `sports`, `horror`, `stealth`,
+`fighting`, `casual`, `simulation`, `adventure`, `rhythm` and `rpg`, and two
+that say how it is played together:
+
+- **`local-multiplayer`**: several people on one device. Needs `players.local`
+  above 1.
+- **`online-multiplayer`**: over the network. Needs `previews.network`.
+
+Either of those without what it needs is not refused: the game is published,
+that word is ignored, and `hopple check`, `hopple upload` and `hopple publish`
+warn about it. They warn the other way round too, for a game that declares
+`genres` and leaves out a way of playing together its manifest shows, since it
+then is not listed as one. Clients group the two under one shelf.
+
 ### previews
 
 ```json

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@hopple/sdk",
-  "version": "1.0.0-next.1",
+  "version": "1.0.0-next.4",
   "description": "The Hopple SDK: what a game imports to talk to the host that runs it, forwarded to the runtime its page loads.",
   "license": "MIT",
   "homepage": "https://hopple.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pamarit/hopple.git"
+  },
   "keywords": [
     "hopple",
     "game",