@hopple/sdk 1.0.0-next.12 → 1.0.0-next.13

package/index.d.ts

@@ -1,4 +1,4 @@
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/protocol/src/analytics.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/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-hbSZtA/protocol/src/errors.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/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-hbSZtA/protocol/src/input.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/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-hbSZtA/protocol/src/pause.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/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-hbSZtA/protocol/src/save.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/protocol/src/save.d.ts
 /**
  * The one thing a game may keep.
  *
@@ -285,7 +285,7 @@ type SaveStored = {
   bytes: number;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/protocol/src/score.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/protocol/src/score.d.ts
 /**
  * What the host says came of it.
  *
@@ -323,7 +323,7 @@ type ScoreStanding = {
   of?: number;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/protocol/src/share.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/protocol/src/share.d.ts
 /**
  * A link to this game, offered to the player by the host.
  *
@@ -423,7 +423,7 @@ type ShareMeta = {
   [key: string]: ShareMetaValue;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/protocol/src/methods.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/protocol/src/methods.d.ts
 /**
  * How far a game has got with its own preparation.
  *
@@ -603,7 +603,7 @@ type DeviceInfo = {
   tier: DeviceTier;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/protocol/src/listeners.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/protocol/src/listeners.d.ts
 /**
  * The one way anything here is listened to: `on(listener)` hands back the
  * function that stops it.
@@ -632,7 +632,7 @@ type DeviceInfo = {
  */
 type Unsubscribe = () => void;
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/manifest/src/manifest.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/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.
@@ -1534,6 +1534,36 @@ type PreviewsDeclaration = {
  * @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';
+/**
+ * A few seconds of real play, which Explore shows in place of the still cover,
+ * played muted, over and over. See `GameManifest.clip`.
+ *
+ * @group Manifest
+ * @category Useful
+ */
+type ClipDeclaration = {
+  /**
+   * The clip: the path of an MP4 file beside the config. H.264 with no sound
+   * track, 2 to 15 seconds long, its longest side at most 1280 and its
+   * shortest at most 720, saved with "fast start", and at most
+   * `CLIP_MAX_BYTES`. `clipProblems` says what is wrong with one.
+   *
+   * @pattern ^(?!/)(?!.*\.\.)[A-Za-z0-9._/-]+\.mp4$
+   * @maxLength 200
+   * @errorMessage must be the path of an .mp4 file beside the config, like "clip.mp4"
+   */
+  video: string;
+  /**
+   * The clip's first frame, as a PNG, JPEG or WebP file beside the config,
+   * shown until the clip plays and wherever it cannot. At most
+   * `POSTER_MAX_BYTES`.
+   *
+   * @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 "clip.png"
+   */
+  poster: string;
+};
 /**
  * Publishing refuses a key the manifest's API does not know; a host reading a
  * published one ignores it (see `validateManifest`).
@@ -1621,20 +1651,34 @@ type GameManifest = {
    */
   genres?: GameGenre[];
   /**
-   * A picture of the game, shown wherever a link to it is pasted — a chat, a
-   * post, a message.
+   * A picture of the game: its cover on Explore's shelves and in a player's
+   * inbox, and what a link to it shows wherever 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.
+   * the game, and a server takes no upload without one: only a game that is
+   * never uploaded leaves it out. 1200 × 630 is the shape every platform shows
+   * whole; `hopple smoke --cover` makes one from the game itself.
    *
-   * @category Useful
+   * @category Important
    * @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;
+  /**
+   * A few seconds of real play, which Explore shows in place of the still
+   * `cover`, played muted. `poster` is the clip's first frame, shown until it
+   * plays. The clip is an H.264 MP4 with no sound track, 2 to 15 seconds long,
+   * no larger than 1280 × 720 either way up, saved with "fast start", and at
+   * most `CLIP_MAX_BYTES`; the poster at most `POSTER_MAX_BYTES`. Both are
+   * paths beside the config, and `hopple publish` uploads them with the game.
+   * See `ClipDeclaration`.
+   *
+   * @category Useful
+   */
+  clip?: ClipDeclaration;
   /** @category Important */
   orientation: Orientation;
   /**
@@ -1705,7 +1749,7 @@ type ProjectManifest = Omit<GameManifest, 'api'> & {
   api?: ApiVersion;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/game/src/achievements.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/game/src/achievements.d.ts
 /**
  * Where this player stands on one achievement.
  *
@@ -1803,7 +1847,7 @@ type Achievements<Id extends string = string, Measured extends string = Id> = {
   progress(id: Measured, value: number): void;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/game/src/analytics.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/game/src/analytics.d.ts
 /**
  * @group Analytics
  * @category Important
@@ -1820,7 +1864,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-hbSZtA/game/src/audio.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/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
@@ -1911,7 +1955,7 @@ type Audio<Channel extends string = string> = {
   media(element: HTMLMediaElement, channel?: Channel): Unsubscribe;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/game/src/info.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/game/src/info.d.ts
 /**
  * What the host said, frozen.
  *
@@ -1929,7 +1973,7 @@ type Info = Readonly<{
   device: Readonly<DeviceInfo>;
 }>;
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/game/src/layout.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/game/src/layout.d.ts
 /**
  * How much of each edge belongs to the host. CSS pixels.
  *
@@ -2039,7 +2083,7 @@ type InsetPolicy = {
  */
 declare function insetsFrom(obstructions: readonly Obstruction[], frame: Size, policy?: InsetPolicy): Insets;
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/game/src/names.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/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
@@ -2159,7 +2203,7 @@ type EventProps<M> = M extends {
  */
 type StickName = 'pad.left.stick' | 'pad.right.stick' | 'pad.stick' | `controls.${string}`;
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/game/src/input/state.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/game/src/input/state.d.ts
 /**
  * Where the pointer is, in the frame's own coordinates.
  *
@@ -2220,7 +2264,7 @@ type InputSnapshot<Action extends string = string> = {
   pointer: PointerState | null;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/game/src/input/players.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/game/src/input/players.d.ts
 /**
  * What one player holds: a pad, one part of the keyboard, or the on-screen
  * controls.
@@ -2242,7 +2286,7 @@ type Controller =
   kind: 'touch';
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/game/src/input/pointers.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/game/src/input/pointers.d.ts
 /**
  * Presses and groups of fingers on an element, recognised and meaning nothing:
  * what a game's tools, or a camera, are built on.
@@ -2427,7 +2471,7 @@ type Pointers = {
   dispose(): void;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/game/src/input/wheel.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/game/src/input/wheel.d.ts
 /**
  * One turn of a wheel, swipe of a trackpad, or pinch on one, the same in every
  * browser: `input.wheel`.
@@ -2470,7 +2514,7 @@ type WheelTaker = {
   dispose(): void;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/game/src/input/camera.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/game/src/input/camera.d.ts
 /**
  * What the camera should do: one for each move of a finger, a pair of them,
  * a wheel or a glide, whichever it was.
@@ -2615,7 +2659,7 @@ type ViewOptions = {
   height?: number;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/game/src/input/lock.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/game/src/input/lock.d.ts
 /**
  * The mouse held to the game: `input.pointerLock`.
  *
@@ -2659,7 +2703,7 @@ type PointerLock = {
   };
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/game/src/input/index.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/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`.
@@ -2945,7 +2989,7 @@ type Controls<Layout extends string = string> = {
   readonly available: boolean;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/game/src/lifecycle.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/game/src/lifecycle.d.ts
 /** @group Lifecycle */
 type LifecycleListener = (phase: Phase, previous: Phase) => void | Promise<void>;
 /**
@@ -2964,7 +3008,7 @@ type Lifecycle = {
   on(listener: LifecycleListener): Unsubscribe;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/game/src/loop.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/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.
@@ -3018,7 +3062,7 @@ type Loop = {
   tick(frame: FrameCallback): Unsubscribe;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/game/src/panel.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/game/src/panel.d.ts
 /**
  * The pages of the host's panel a game has a name for, as the keys of this
  * interface.
@@ -3156,7 +3200,7 @@ type Panel = {
   open(page: PageId): void;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/game/src/pause.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/game/src/pause.d.ts
 /**
  * The host has asked for a pause, or for the game to carry on.
  *
@@ -3217,7 +3261,7 @@ type Pause = {
   on(listener: PauseListener): Unsubscribe;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/game/src/resources.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/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.
@@ -3247,7 +3291,7 @@ type Resources = {
   on(listener: ResourcesListener): Unsubscribe;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/game/src/save.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/game/src/save.d.ts
 /**
  * What a game gets back from a read: its own schema number, and its state.
  *
@@ -3422,7 +3466,7 @@ type Save = {
   readonly maxBytes: number;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/game/src/score.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/game/src/score.d.ts
 /**
  * Where this player stands on every board, as far as anybody has said.
  *
@@ -3499,7 +3543,7 @@ type Score<Board extends string = string> = {
   }): Promise<ScoreResult>;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/game/src/share.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/game/src/share.d.ts
 /**
  * @group Share
  * @category Important
@@ -3583,7 +3627,7 @@ type Share = {
   }): void;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/game/src/init.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/game/src/init.d.ts
 /**
  * What `init` hands back: every namespace a game has, on one object.
  *

package/manifest.d.ts

@@ -1,4 +1,4 @@
-//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/manifest/src/manifest.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-SHySdg/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.
@@ -894,6 +894,36 @@ type PreviewsDeclaration = {
  * @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';
+/**
+ * A few seconds of real play, which Explore shows in place of the still cover,
+ * played muted, over and over. See `GameManifest.clip`.
+ *
+ * @group Manifest
+ * @category Useful
+ */
+type ClipDeclaration = {
+  /**
+   * The clip: the path of an MP4 file beside the config. H.264 with no sound
+   * track, 2 to 15 seconds long, its longest side at most 1280 and its
+   * shortest at most 720, saved with "fast start", and at most
+   * `CLIP_MAX_BYTES`. `clipProblems` says what is wrong with one.
+   *
+   * @pattern ^(?!/)(?!.*\.\.)[A-Za-z0-9._/-]+\.mp4$
+   * @maxLength 200
+   * @errorMessage must be the path of an .mp4 file beside the config, like "clip.mp4"
+   */
+  video: string;
+  /**
+   * The clip's first frame, as a PNG, JPEG or WebP file beside the config,
+   * shown until the clip plays and wherever it cannot. At most
+   * `POSTER_MAX_BYTES`.
+   *
+   * @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 "clip.png"
+   */
+  poster: string;
+};
 /**
  * Publishing refuses a key the manifest's API does not know; a host reading a
  * published one ignores it (see `validateManifest`).
@@ -981,20 +1011,34 @@ type GameManifest = {
    */
   genres?: GameGenre[];
   /**
-   * A picture of the game, shown wherever a link to it is pasted — a chat, a
-   * post, a message.
+   * A picture of the game: its cover on Explore's shelves and in a player's
+   * inbox, and what a link to it shows wherever 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.
+   * the game, and a server takes no upload without one: only a game that is
+   * never uploaded leaves it out. 1200 × 630 is the shape every platform shows
+   * whole; `hopple smoke --cover` makes one from the game itself.
    *
-   * @category Useful
+   * @category Important
    * @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;
+  /**
+   * A few seconds of real play, which Explore shows in place of the still
+   * `cover`, played muted. `poster` is the clip's first frame, shown until it
+   * plays. The clip is an H.264 MP4 with no sound track, 2 to 15 seconds long,
+   * no larger than 1280 × 720 either way up, saved with "fast start", and at
+   * most `CLIP_MAX_BYTES`; the poster at most `POSTER_MAX_BYTES`. Both are
+   * paths beside the config, and `hopple publish` uploads them with the game.
+   * See `ClipDeclaration`.
+   *
+   * @category Useful
+   */
+  clip?: ClipDeclaration;
   /** @category Important */
   orientation: Orientation;
   /**

package/manifest.js

@@ -1,4 +1,4 @@
-/*! @hopple/sdk 1.0.0-next.12 | Copyright (c) 2026 The Hopple authors | MIT License */
+/*! @hopple/sdk 1.0.0-next.13 | Copyright (c) 2026 The Hopple authors | MIT License */
 //#region ../manifest/src/manifest.schema.ts
 const GameManifest = {
 	"type": "object",
@@ -46,6 +46,7 @@ const GameManifest = {
 			"maxLength": 200,
 			"errorMessage": "must be the path of a .png, .jpg or .webp file beside the config, like \"cover.png\""
 		},
+		"clip": { "$ref": "#/definitions/ClipDeclaration" },
 		"orientation": { "$ref": "#/definitions/Orientation" },
 		"layout": { "$ref": "#/definitions/LayoutDeclaration" },
 		"analytics": { "$ref": "#/definitions/AnalyticsDeclaration" },
@@ -98,6 +99,25 @@ const GameGenre = {
 		"online-multiplayer"
 	]
 };
+const ClipDeclaration = {
+	"type": "object",
+	"properties": {
+		"video": {
+			"type": "string",
+			"pattern": "^(?!/)(?!.*\\.\\.)[A-Za-z0-9._/-]+\\.mp4$",
+			"maxLength": 200,
+			"errorMessage": "must be the path of an .mp4 file beside the config, like \"clip.mp4\""
+		},
+		"poster": {
+			"type": "string",
+			"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 \"clip.png\""
+		}
+	},
+	"required": ["video", "poster"],
+	"additionalProperties": false
+};
 const Orientation = {
 	"type": "string",
 	"enum": [
@@ -461,6 +481,7 @@ const definitions = {
 	GameManifest,
 	ApiVersion,
 	GameGenre,
+	ClipDeclaration,
 	Orientation,
 	LayoutDeclaration,
 	InsetMode,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hopple/sdk",
-  "version": "1.0.0-next.12",
+  "version": "1.0.0-next.13",
   "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",