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

package/index.d.ts

@@ -1,4 +1,4 @@
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/protocol/src/analytics.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-ky983p/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-ky983p/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-ky983p/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-ky983p/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-ky983p/protocol/src/save.d.ts
 /**
  * The one thing a game may keep.
  *
@@ -255,7 +255,8 @@ type PauseState =
  * game may assume anywhere, forever, because a game ships and is never updated.
  */
 /**
- * What a game may write anywhere, in bytes of `state` as UTF-8.
+ * What a game may write anywhere, in bytes: of `state` as UTF-8, or of the
+ * bytes a game handed over where it handed bytes.
  *
  * The floor rather than the cap: a host that will take more says so in the
  * welcome, and a game that never asks still knows this much is safe. 64 KiB is
@@ -284,7 +285,7 @@ type SaveStored = {
   bytes: number;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/protocol/src/score.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-ky983p/protocol/src/score.d.ts
 /**
  * What the host says came of it.
  *
@@ -322,7 +323,7 @@ type ScoreStanding = {
   of?: number;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/protocol/src/share.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-ky983p/protocol/src/share.d.ts
 /**
  * A link to this game, offered to the player by the host.
  *
@@ -376,7 +377,8 @@ type ScoreStanding = {
  * its first frame. See `ShareWelcome`.
  */
 /**
- * What every host carries, in bytes of `data` as UTF-8.
+ * What every host carries, in bytes of `data`: as UTF-8, or the bytes a game
+ * handed over where it handed bytes.
  *
  * The floor rather than the cap: a host may take more and none may take less,
  * so a game that stays under this is never refused for its size anywhere. It is
@@ -421,7 +423,7 @@ type ShareMeta = {
   [key: string]: ShareMetaValue;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/protocol/src/methods.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-ky983p/protocol/src/methods.d.ts
 /**
  * How far a game has got with its own preparation.
  *
@@ -601,7 +603,7 @@ type DeviceInfo = {
   tier: DeviceTier;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/protocol/src/listeners.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-ky983p/protocol/src/listeners.d.ts
 /**
  * The one way anything here is listened to: `on(listener)` hands back the
  * function that stops it.
@@ -630,7 +632,7 @@ type DeviceInfo = {
  */
 type Unsubscribe = () => void;
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/manifest/src/manifest.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-ky983p/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.
@@ -849,6 +851,26 @@ type ScoreBoard = {
   direction: ScoreDirection;
   /** See `ScoreFormat`. Absent means `integer`. */
   format?: ScoreFormat;
+  /**
+   * Which board, of the ones this id has named. Absent is `1`.
+   *
+   * **Raising it starts the board again from nobody.** The runs under the
+   * version before are kept and no longer counted, shown or ranked, so a board
+   * whose scores stopped being comparable — new levels, a new rule — begins
+   * again under the id the game already submits to.
+   *
+   * **Only a change to what a stored score means needs it.** The title changes
+   * freely, and so does the format between `integer` and `decimal`. Once the
+   * board holds scores, turning it around (`direction`) or writing it in
+   * another unit (to or from `duration-ms`) is refused at the same version.
+   * Going back to a version declared before brings its runs back, so it is
+   * held to what that version was.
+   *
+   * @asType integer
+   * @minimum 1
+   * @maximum 1000
+   */
+  version?: number;
 };
 /**
  * The boards this game keeps a score on.
@@ -1012,6 +1034,28 @@ type Achievement = {
   secret?: boolean;
   /** Present makes this measured rather than flagged. See `AchievementProgress`. */
   progress?: AchievementProgress;
+  /**
+   * Which achievement, of the ones this id has named. Absent is `1`.
+   *
+   * **Raising it starts the achievement again for everybody.** What players
+   * reported and unlocked under the version before is kept and no longer
+   * counted, so it is earned afresh under the id the game already reports to.
+   *
+   * **Only a change to what a stored value means needs it.** The words change
+   * freely — title, detail, icon, secret — and so does the target, and a tier
+   * added after the last one: progress is kept as the number reported, which
+   * stays true when the goal moves, and a player who unlocked it keeps it. At
+   * the same version, a published achievement may not turn from a flag into a
+   * measure or back, turn its direction around, write its value in another
+   * unit (to or from `duration-ms`), or move or drop a tier it already has.
+   * Going back to a version declared before brings back what was earned under
+   * it, so it is held to what that version was.
+   *
+   * @asType integer
+   * @minimum 1
+   * @maximum 1000
+   */
+  version?: number;
 };
 /**
  * The achievements this game keeps for a player.
@@ -1309,6 +1353,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 +1517,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,8 +1573,19 @@ 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.
+   * People see it beside the build the server numbers each upload with, and
+   * each published version needs one no other published version of the game has.
    *
    * @category Important
    * @pattern ^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$
@@ -1522,6 +1608,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.
@@ -1596,53 +1694,6 @@ type GameManifest = {
    */
   previews?: PreviewsDeclaration;
 };
-/**
- * A game project's hopple config: `hopple.config.ts`, `hopple.config.js` or
- * `hopple.config.json`, beside the project's `package.json`.
- *
- * Everything the `hopple` command line needs to know about a project, in one
- * place: how to build the game, which built file is the game, and the manifest
- * that says what the game is. Only the manifest leaves the machine, uploaded
- * beside the page as `game.manifest.json`. A TypeScript or JavaScript config
- * default-exports one of these; a JSON config is one.
- *
- * ```ts
- * import type { HoppleConfig } from '@hopple/sdk';
- *
- * export default {
- *   build: 'npm run build',
- *   page: 'dist/index.html',
- *   manifest: { id: 'my-game', version: '0.1.0', title: 'My Game', orientation: 'portrait', audio: null },
- * } satisfies HoppleConfig;
- * ```
- *
- * @group Manifest
- * @category Important
- */
-type HoppleConfig = {
-  /** Where an editor finds this file's schema, in a JSON config. Read by nothing else. */
-  $schema?: string;
-  /**
-   * The command that builds the game, run in the config's directory before
-   * `hopple dev`, `check` and `publish` use it, so none of them sees a stale
-   * build. Leave it out for a game with nothing to build.
-   *
-   * @pattern \S
-   * @errorMessage must be the command that builds the game, like "npm run build"
-   */
-  build?: string;
-  /**
-   * The built page, relative to the config. The directory it is in is
-   * published, with the page as its `index.html`; a page beside its config is
-   * published alone, so it has to hold the whole game.
-   *
-   * @pattern \.[Hh][Tt][Mm][Ll]?$
-   * @errorMessage must be the built .html file, like "dist/index.html"
-   */
-  page: string;
-  /** What the game is. Uploaded beside the page, and read by every host before the game runs. */
-  manifest: ProjectManifest;
-};
 /**
  * The manifest as a project's config holds it: `api` may be left out, for the
  * CLI to fill from the installed `@hopple/sdk`.
@@ -1654,7 +1705,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-ky983p/game/src/achievements.d.ts
 /**
  * Where this player stands on one achievement.
  *
@@ -1752,7 +1803,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-ky983p/game/src/analytics.d.ts
 /**
  * @group Analytics
  * @category Important
@@ -1769,7 +1820,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-ky983p/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 +1911,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-ky983p/game/src/info.d.ts
 /**
  * What the host said, frozen.
  *
@@ -1878,7 +1929,7 @@ type Info = Readonly<{
   device: Readonly<DeviceInfo>;
 }>;
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/game/src/layout.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-ky983p/game/src/layout.d.ts
 /**
  * How much of each edge belongs to the host. CSS pixels.
  *
@@ -1988,7 +2039,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-ky983p/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 +2159,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-ky983p/game/src/input/state.d.ts
 /**
  * Where the pointer is, in the frame's own coordinates.
  *
@@ -2169,7 +2220,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-ky983p/game/src/input/players.d.ts
 /**
  * What one player holds: a pad, one part of the keyboard, or the on-screen
  * controls.
@@ -2191,7 +2242,7 @@ type Controller =
   kind: 'touch';
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/game/src/input/index.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-ky983p/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 +2352,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 +2479,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-ky983p/game/src/lifecycle.d.ts
 /** @group Lifecycle */
 type LifecycleListener = (phase: Phase, previous: Phase) => void | Promise<void>;
 /**
@@ -2431,7 +2498,7 @@ type Lifecycle = {
   on(listener: LifecycleListener): Unsubscribe;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/game/src/loop.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-ky983p/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 +2552,7 @@ type Loop = {
   tick(frame: FrameCallback): Unsubscribe;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/game/src/panel.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-ky983p/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 +2690,7 @@ type Panel = {
   open(page: PageId): void;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/game/src/pause.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-ky983p/game/src/pause.d.ts
 /**
  * The host has asked for a pause, or for the game to carry on.
  *
@@ -2684,7 +2751,7 @@ type Pause = {
   on(listener: PauseListener): Unsubscribe;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/game/src/resources.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-ky983p/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 +2781,7 @@ type Resources = {
   on(listener: ResourcesListener): Unsubscribe;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/game/src/save.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-ky983p/game/src/save.d.ts
 /**
  * What a game gets back from a read: its own schema number, and its state.
  *
@@ -2724,7 +2791,10 @@ type Resources = {
 type SaveState = {
   /** Whatever the game passed to `write`, or 1 where it never named one. */
   version: number;
-  /** Parsed where it was written as a value, verbatim where it was a string. */
+  /**
+   * Parsed where it was written as a value, verbatim where it was a string, and
+   * a `Uint8Array` where it was one.
+   */
   state: unknown;
 };
 /**
@@ -2764,20 +2834,41 @@ type SaveListener = (now: SaveStatus, previous: SaveStatus) => void;
  *
  * Pure: it is called with two states and must not touch the game's own. Run
  * while the game loads, its answer is what `read()` resolves with; run while
- * the game plays, its answer goes to `onMerge` as well.
+ * the game plays, its answer goes to `onChange` as well.
  *
  * @group Save
  * @category Useful
  */
 type SaveMerger = (mine: SaveState, theirs: SaveState) => SaveState;
 /**
- * Told the merged save, once a merge has run while the game was playing on
- * its own: play on from this, which is both devices' progress.
+ * Why the save a game plays on changed under it.
+ *
+ * - `arrived`: another device's save, built on what the game had — a server
+ *   that answered after the game read, or another device that played on. Run
+ *   through the game's `merge` with what it last saved, where it has one.
+ * - `merged`: the game's `merge` made one save of this device's and another
+ *   that went their own ways.
+ * - `gone`: thrown away on another device, with nothing made here since. The
+ *   save is `null`.
  *
  * @group Save
  * @category Useful
  */
-type SaveMergeListener = (merged: SaveState) => void;
+type SaveChangeReason = 'arrived' | 'merged' | 'gone';
+/**
+ * Told the save the game now plays on, once it changed under it while it
+ * played, and why: play on from this. `null` is a save thrown away on another
+ * device (`gone`): start again.
+ *
+ * The host now holds what the listener is handed, and the game's next write
+ * continues it. To keep the game's own instead — progress it has not saved
+ * yet, or a New game the player has just chosen over a save that arrived
+ * after — write it from the listener: it takes that save's place.
+ *
+ * @group Save
+ * @category Useful
+ */
+type SaveChangeListener = (save: SaveState | null, why: SaveChangeReason) => void;
 /**
  * What a game says about its save at `init`, before the host has asked
  * anything.
@@ -2823,10 +2914,12 @@ type Save = {
   /**
    * Keep this. Resolves when the host says the record is durable.
    *
-   * A string is stored as it stands and comes back a string; anything else is
-   * `JSON.stringify`d and comes back parsed. A value that cannot survive that
-   * at all — a cycle, a `BigInt` — rejects with `bad_params` before anything
-   * reaches the bridge.
+   * A string is stored as it stands and comes back a string; a `Uint8Array` is
+   * stored as its bytes and comes back a `Uint8Array`, `maxBytes` counting the
+   * bytes themselves; anything else is `JSON.stringify`d and comes back parsed.
+   * A value that cannot survive that at all — a cycle, a `BigInt` — rejects
+   * with `bad_params` before anything reaches the bridge, and bytes on a host
+   * older than keeping them reject with `unsupported`.
    *
    * `version` is the game's own schema number and means whatever the game says
    * it means. There is no migration hook: a hook would be frozen game-side code
@@ -2839,19 +2932,31 @@ type Save = {
   /** Throw the save away — a game resetting its own progress, at a player's asking. */
   clear(): Promise<void>;
   /**
-   * Told when the game's `merge` ran while the game was playing: what the
-   * host now keeps is the merged save, and the game should play on from it.
+   * Told when the save the game plays on changed under it, and why: play on
+   * from what the listener is handed.
+   *
+   * That is another device's save arriving after the game read — a server
+   * that answered late, a page left open while another device played on —
+   * (`arrived`), or the game's own `merge` run while it played (`merged`), or
+   * the save thrown away on another device with nothing made here since
+   * (`gone`, `null`). Without a merge, an arrival is handed over as it is: it
+   * is built on what the game had.
    *
-   * A merge needed while the game plays waits for its next load unless
-   * something is listening here, because a game that went on playing from its
-   * own state would save over the merge with its next write.
+   * Listening is what lets a game start before its save is in hand: draw from
+   * nothing at once, and take the player's save when it comes. Register it
+   * before `read()`. A game that is not listening is never written over —
+   * what it writes next is kept beside what arrived, for its merge or the
+   * player to settle.
+   *
+   * To keep the game's own over what it is handed, write it from the
+   * listener: that write takes the handed save's place.
    */
-  onMerge(listener: SaveMergeListener): Unsubscribe;
+  onChange(listener: SaveChangeListener): Unsubscribe;
   /** The largest save this host will take, in bytes. `SAVE_BYTES` where it said nothing. */
   readonly maxBytes: number;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/game/src/score.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-ky983p/game/src/score.d.ts
 /**
  * Where this player stands on every board, as far as anybody has said.
  *
@@ -2928,7 +3033,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-ky983p/game/src/share.d.ts
 /**
  * @group Share
  * @category Important
@@ -2955,9 +3060,18 @@ type Share = {
    * check it — the same care `save.read` deserves, for a stronger reason.
    *
    * **`null` says nothing about whether a link can be offered.** It means
-   * nobody arrived by one; `available` is what says whether one can be made.
+   * nobody arrived by one, or that the link carried bytes, which are `bytes`;
+   * `available` is what says whether one can be made.
    */
   readonly data: string | null;
+  /**
+   * What the link that opened this game carried, where some run of this game
+   * passed `offer` a `Uint8Array`: those bytes. `null` otherwise — a player who
+   * arrived the ordinary way, or a link that carried a string, which is `data`.
+   *
+   * A stranger's input, exactly as `data` is.
+   */
+  readonly bytes: Uint8Array | null;
   /**
    * Ask the host to put a link to this game in front of the player.
    *
@@ -2967,23 +3081,26 @@ type Share = {
    * may keep a sheet open as long as they like, and pressing Share again while
    * one is up does not open a second.
    *
-   * `data` is the game's own and travels in the link, opaque to the host, back
-   * to whoever opens it. A string, because it has to survive being a URL and
-   * because the game reading it back is the game that wrote it: anything
-   * structured is the game's to encode and the game's to parse. `SHARE_BYTES`
-   * is what every host carries; more than that is a host's own decision, and a
-   * host that will not carry it refuses with `too_large`.
+   * `data` is the game's own and travels with the link, opaque to the host,
+   * back to whoever opens it: a string, which arrives as `share.data`, or a
+   * `Uint8Array`, which arrives as `share.bytes`. The game reading it back is
+   * the game that wrote it, so anything structured is the game's to encode and
+   * the game's to parse — bytes pack a board far tighter than text does.
+   * `SHARE_BYTES` is what every host carries, counted in bytes either way; more
+   * than that is a host's own decision, and a host that will not carry it
+   * refuses with `too_large`.
    *
    * `meta` is for the platform rather than for the game: why this link was made
    * — the level, the score, which of the game's buttons — kept beside the
    * host's own record of who made it and how, so a game's makers can learn
    * which of its shares bring people in. Anything JSON can say, and
    * `SHARE_META_BYTES` of it is what every host takes. Nobody who opens the link
-   * is handed it.
+   * is handed it; the game's team reads it, with `data`, by `hopple share`.
    *
    * What goes wrong is reported to `onError` and sends nothing: `bad_params`
-   * for a `data` that is not a string or a `meta` JSON cannot carry, which are
-   * bugs in the game; `too_large` from a host for more than it carries;
+   * for a `data` that is neither a string nor a `Uint8Array`, or a `meta` JSON
+   * cannot carry, which are bugs in the game; `unsupported` for bytes on a host
+   * older than carrying them; `too_large` from a host for more than it carries;
    * `rate_limited` from one that will not offer a link right now. A host with
    * no link to give does nothing, which a game checking `available` never asks
    * of it. Every one of them is a game that carries on: nothing about a share
@@ -2995,12 +3112,12 @@ type Share = {
    * sheet on screen comes from the player's own gesture.
    */
   offer(options?: {
-    data?: string;
+    data?: string | Uint8Array;
     meta?: ShareMeta;
   }): void;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/game/src/init.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-ky983p/game/src/init.d.ts
 /**
  * What `init` hands back: every namespace a game has, on one object.
  *
@@ -3296,4 +3413,4 @@ type InitOptions = {
  */
 declare function init<M extends object = GameManifest>(options?: InitOptions): Promise<GameSdk<M>>;
 //#endregion
-export { type Achievement, type AchievementDeclaration, type AchievementListener, type AchievementName, type AchievementProgress, type AchievementStanding, type AchievementStatus, type AchievementTier, type Achievements, type ActionListener, type ActionName, type Analytics, type AnalyticsDeclaration, type AnalyticsProps, type AnalyticsShape, type AnalyticsType, type AnalyticsValue, type ApiVersion, type AppInfo, type AppSurface, type Audio, type AudioChannel, type AudioDeclaration, type AudioListener, type BoardName, BridgeError, type ButtonName, type ChannelName, type ControlLayout, type ControlShape, type ControlSlot, type ControlZone, type Controller, type Controls, type DeclaredNames, type DeclaredValue, type DeviceInfo, type DeviceTier, type ErrorCode, type ErrorCodes, type EventName, type EventProps, type FrameCallback, type GameInfo, type GameManifest, type GameSdk, type HoppleConfig, type Info, type InitOptions, type Input, type InputAction, type InputBinding, type InputDeclaration, type InputDevice, type InputListener, type InputScheme, type InputSnapshot, type InputState, type InsetMode, type InsetPolicy, type Insets, type Layout, type LayoutDeclaration, type LayoutListener, type LayoutName, type LayoutState, type Lifecycle, type LifecycleListener, type Loop, type LoopListener, MAX_STEP, type MeasuredName, type Obstruction, type ObstructionKind, type Orientation, type PageId, type Panel, type PanelListener, type PanelPages, type PanelState, type Pause, type PauseListener, type PauseState, type Phase, type Player, type PlayerActionName, type PlayerInfo, type PointerListener, type PointerState, type ProjectManifest, type Rect, type Resources, type ResourcesListener, SAVE_BYTES, SHARE_BYTES, SHARE_META_BYTES, type Save, type SaveDeclaration, type SaveListener, type SaveMergeListener, type SaveMerger, type SaveSetup, type SaveState, type SaveStatus, type SaveStored, type Score, type ScoreBoard, type ScoreDeclaration, type ScoreDirection, type ScoreFormat, type ScoreListener, type ScoreResult, type ScoreStanding, type ScoreStandings, type Share, type ShareMeta, type ShareMetaValue, type Size, type StickListener, type StickName, type StickState, type Unsubscribe, init, insetsFrom };
+export { type Achievement, type AchievementDeclaration, type AchievementListener, type AchievementName, type AchievementProgress, type AchievementStanding, type AchievementStatus, type AchievementTier, type Achievements, type ActionListener, type ActionName, type Analytics, type AnalyticsDeclaration, type AnalyticsProps, type AnalyticsShape, type AnalyticsType, type AnalyticsValue, type ApiVersion, type AppInfo, type AppSurface, type Audio, type AudioChannel, type AudioDeclaration, type AudioListener, type BoardName, BridgeError, type ButtonName, type ChannelName, type ControlLayout, type ControlShape, type ControlSlot, type ControlZone, type Controller, type Controls, type DeclaredNames, type DeclaredValue, type DeviceInfo, type DeviceTier, type ErrorCode, type ErrorCodes, type EventName, type EventProps, type FrameCallback, type GameInfo, type GameManifest, type GameSdk, type Info, type InitOptions, type Input, type InputAction, type InputBinding, type InputDeclaration, type InputDevice, type InputListener, type InputScheme, type InputSnapshot, type InputState, type InsetMode, type InsetPolicy, type Insets, type Layout, type LayoutDeclaration, type LayoutListener, type LayoutName, type LayoutState, type Lifecycle, type LifecycleListener, type Loop, type LoopListener, MAX_STEP, type MeasuredName, type Obstruction, type ObstructionKind, type Orientation, type PageId, type Panel, type PanelListener, type PanelPages, type PanelState, type Pause, type PauseListener, type PauseState, type Phase, type Player, type PlayerActionName, type PlayerInfo, type PointerListener, type PointerState, type ProjectManifest, type Rect, type Resources, type ResourcesListener, SAVE_BYTES, SHARE_BYTES, SHARE_META_BYTES, type Save, type SaveChangeListener, type SaveChangeReason, type SaveDeclaration, type SaveListener, type SaveMerger, type SaveSetup, type SaveState, type SaveStatus, type SaveStored, type Score, type ScoreBoard, type ScoreDeclaration, type ScoreDirection, type ScoreFormat, type ScoreListener, type ScoreResult, type ScoreStanding, type ScoreStandings, type Share, type ShareMeta, type ShareMetaValue, type Size, type StickListener, type StickName, type StickState, type Unsubscribe, init, insetsFrom };

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.5 | 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;