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

package/index.d.ts

@@ -1,4 +1,4 @@
-//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/protocol/src/analytics.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/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-A6KFyv/protocol/src/errors.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/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-A6KFyv/protocol/src/input.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/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-A6KFyv/protocol/src/pause.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/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-A6KFyv/protocol/src/save.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/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-A6KFyv/protocol/src/score.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/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-A6KFyv/protocol/src/share.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/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-A6KFyv/protocol/src/methods.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/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-A6KFyv/protocol/src/listeners.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/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-A6KFyv/manifest/src/manifest.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/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.
@@ -1077,7 +1121,7 @@ type InputDeviceSet = InputDevice[];
  * 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))$
+ * @pattern ^(?:key\.(?!Escape$)(?=.{1,48}$)[A-Za-z][A-Za-z0-9]*|pointer\.(?:primary|secondary)|mouse\.(?:left|middle|right|wheelup|wheeldown)|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$1 = string;
@@ -1153,7 +1197,7 @@ type PlayerBinding = string;
  * mouse button.
  *
  * @group Input
- * @pattern ^(?:key\.(?!Escape$)(?=.{1,48}$)[A-Za-z][A-Za-z0-9]*|mouse\.(?:left|middle|right))$
+ * @pattern ^(?:key\.(?!Escape$)(?=.{1,48}$)[A-Za-z][A-Za-z0-9]*|mouse\.(?:left|middle|right|wheelup|wheeldown))$
  * @errorMessage must be a key or a mouse button (and Escape is the host's key)
  */
 type KeyboardBinding = string;
@@ -1540,6 +1584,8 @@ type GameManifest = {
   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.-]+)?$
@@ -1648,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`.
@@ -1706,7 +1705,7 @@ type ProjectManifest = Omit<GameManifest, 'api'> & {
   api?: ApiVersion;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/achievements.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/game/src/achievements.d.ts
 /**
  * Where this player stands on one achievement.
  *
@@ -1804,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-A6KFyv/game/src/analytics.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/game/src/analytics.d.ts
 /**
  * @group Analytics
  * @category Important
@@ -1821,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-A6KFyv/game/src/audio.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/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
@@ -1912,7 +1911,7 @@ type Audio<Channel extends string = string> = {
   media(element: HTMLMediaElement, channel?: Channel): Unsubscribe;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/info.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/game/src/info.d.ts
 /**
  * What the host said, frozen.
  *
@@ -1930,7 +1929,7 @@ type Info = Readonly<{
   device: Readonly<DeviceInfo>;
 }>;
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/layout.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/game/src/layout.d.ts
 /**
  * How much of each edge belongs to the host. CSS pixels.
  *
@@ -2040,7 +2039,7 @@ type InsetPolicy = {
  */
 declare function insetsFrom(obstructions: readonly Obstruction[], frame: Size, policy?: InsetPolicy): Insets;
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/names.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/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
@@ -2160,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-A6KFyv/game/src/input/state.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/game/src/input/state.d.ts
 /**
  * Where the pointer is, in the frame's own coordinates.
  *
@@ -2221,7 +2220,7 @@ type InputSnapshot<Action extends string = string> = {
   pointer: PointerState | null;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/input/players.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/game/src/input/players.d.ts
 /**
  * What one player holds: a pad, one part of the keyboard, or the on-screen
  * controls.
@@ -2243,7 +2242,178 @@ type Controller =
   kind: 'touch';
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/input/index.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/game/src/input/gestures.d.ts
+/**
+ * Dragging, pinching and wheeling a view around, and tapping on it: what a map,
+ * a board or a level editor does with a pointer, done once.
+ *
+ * Every game that wrote this itself got some of it wrong, in the same few
+ * ways: a cancelled touch that counted as a tap, a third finger that made the
+ * view jump, a drag that stuck when the mouse was let go outside the frame, a
+ * trackpad that zoomed six times slower than a wheel, a wheel that barely
+ * moved in Firefox. So a game says what a drag, a pinch and a tap do to it,
+ * and the SDK decides which one the player is making.
+ */
+/**
+ * A mouse button, by where it is.
+ *
+ * @group Input
+ */
+type GestureButton = 'left' | 'middle' | 'right';
+/**
+ * What a game does with each gesture. Every coordinate is in CSS pixels from
+ * the element's top left corner.
+ *
+ * @group Input
+ */
+type GestureHandlers = {
+  /** Something dragged the view by this much: a finger, two, a mouse button, or a trackpad's two-finger scroll. */
+  pan?(dx: number, dy: number): void;
+  /**
+   * Something zoomed it by this factor, keeping the point at `x`, `y` where it
+   * is: a pinch, a mouse wheel, or a trackpad pinch. Above 1 is closer.
+   */
+  zoom?(factor: number, x: number, y: number): void;
+  /**
+   * A press that let go where it started, and was the only one: never a drag,
+   * never part of a pinch, never cancelled by the browser.
+   */
+  tap?(x: number, y: number, button: GestureButton | 'touch'): void;
+};
+/**
+ * @group Input
+ */
+type GestureOptions = GestureHandlers & {
+  /**
+   * A view to move: its `pan` and `zoom` are the handlers, beside a `tap` of
+   * the game's own.
+   */
+  view?: View;
+  /**
+   * Which mouse buttons drag. A finger always does. `['left', 'middle']` when
+   * left out; the right button is a game's to bind.
+   */
+  drag?: readonly GestureButton[];
+  /**
+   * What a mouse wheel and a trackpad's two-finger scroll do. `'zoom'`, the
+   * default, zooms with a wheel and pans with a trackpad, the way maps do;
+   * `'pan'` pans with both; `'none'` leaves both alone, for a game that binds
+   * `mouse.wheelup`. A pinch on a trackpad zooms whatever this says.
+   */
+  wheel?: 'zoom' | 'pan' | 'none';
+  /** How far a press may move, in CSS pixels, before it is a drag rather than a tap. 8 when left out. */
+  slop?: number;
+};
+/**
+ * Gestures being read off an element: `input.gestures`.
+ *
+ * @group Input
+ */
+type Gestures = {
+  /** Whether a finger or a dragging button is down on the element now. */
+  readonly active: boolean;
+  /** Stop reading them, and give the element back its `touch-action`. */
+  dispose(): void;
+};
+/**
+ * A camera over a flat world, moved by gestures: `input.view`.
+ *
+ * The world is in a game's own units, with `y` down; `scale` is CSS pixels to
+ * one of them, and `x`, `y` the world point at the element's top left corner.
+ * A game draws with them, `screen = (world - x) * scale`, and may set any of
+ * them; each gesture keeps them inside `min`, `max` and `bounds`.
+ *
+ * @group Input
+ */
+type View = {
+  x: number;
+  y: number;
+  scale: number;
+  /** Drag the view by this many CSS pixels, the world following the finger. */
+  pan(dx: number, dy: number): void;
+  /** Zoom by this factor, the world point at `x`, `y` staying where it is. */
+  zoom(factor: number, x: number, y: number): void;
+  /** Put the world point `x`, `y` in the middle of the element, at `scale` if given. */
+  look(x: number, y: number, scale?: number): void;
+  /** The world point at a point on the element. */
+  toWorld(x: number, y: number): {
+    x: number;
+    y: number;
+  };
+  /** The point on the element a world point is drawn at. */
+  toScreen(x: number, y: number): {
+    x: number;
+    y: number;
+  };
+  /**
+   * Say how big the element is, in CSS pixels: what `look` centres on and
+   * `bounds` keeps filled. Call it whenever the element changes size.
+   */
+  resize(width: number, height: number): void;
+};
+/**
+ * @group Input
+ */
+type ViewOptions = {
+  x?: number;
+  y?: number;
+  scale?: number;
+  /** The least `scale` a gesture zooms out to. */
+  min?: number;
+  /** The most `scale` a gesture zooms in to. */
+  max?: number;
+  /**
+   * The part of the world the view stays over, in world units: never scrolled
+   * past an edge, and centred on it once all of it fits.
+   */
+  bounds?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  /** The element's size in CSS pixels, as `resize` takes it. */
+  width?: number;
+  height?: number;
+};
+//#endregion
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/game/src/input/lock.d.ts
+/**
+ * The mouse held to the game: `input.pointerLock`.
+ *
+ * @group Input
+ */
+type PointerLock = {
+  /** Whether the mouse is locked to the game now. */
+  readonly locked: boolean;
+  /**
+   * Lock the mouse to an element, the whole page when left out, now if the
+   * browser allows it and on the player's next click or key if not.
+   *
+   * Asked again after the player has just left a lock, the browser makes them
+   * wait about a second; the SDK waits with them. Ask from a press of the
+   * player's where you can, a click on the game or the key that resumes it:
+   * from a frame loop, the browser may not take it until they press something.
+   */
+  request(element?: Element): void;
+  /** Let the mouse go, and stop waiting to take it. */
+  release(): void;
+  /**
+   * Run this when the lock is taken or lost. Lost without `release` is the
+   * player leaving it, with Escape or by switching away: the time to pause.
+   * The SDK does not take it back on its own; `request` again on resuming.
+   */
+  on(listener: (locked: boolean) => void): Unsubscribe;
+  /**
+   * Run this for each move of the mouse while it is locked, in CSS pixels,
+   * or in the mouse's own counts where the browser gives those
+   * (`unadjustedMovement`). The jumps a browser sends as a lock starts are
+   * left out.
+   */
+  onMove(listener: (dx: number, dy: number) => void): Unsubscribe;
+};
+//#endregion
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/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`.
@@ -2380,6 +2550,28 @@ type Input<Action extends string = string, Layout extends string = string, Playe
   suspend(): void;
   resume(): void;
   readonly suspended: boolean;
+  /**
+   * Read drags, pinches, wheels and taps off an element, and say what each
+   * did: for a map, a board, a level editor.
+   *
+   *     const view = hopple.input.view({ min: 0.5, max: 4, bounds: world });
+   *     hopple.input.gestures(canvas, { view, tap: (x, y) => select(view.toWorld(x, y)) });
+   *
+   * One finger or a mouse button drags; two fingers pinch, and pan as they
+   * go; a mouse wheel zooms around the pointer and a trackpad scrolls and
+   * pinches, at one speed in every browser. A tap is a press that let go where
+   * it started and was the only one. The element gets `touch-action: none`
+   * until `dispose`.
+   */
+  gestures(element: Element, options: GestureOptions): Gestures;
+  /**
+   * A camera over a flat world that `gestures` moves, kept between `min` and
+   * `max` and over `bounds`. Nothing in it is drawn: a game reads `x`, `y`
+   * and `scale` when it draws.
+   */
+  view(options?: ViewOptions): View;
+  /** The mouse held to the game, for a game that turns a camera with it. */
+  readonly pointerLock: PointerLock;
   /**
    * The players on this device, each with their own copy of the actions
    * `input.player` declares, by `slot`. Empty for a game that declares none;
@@ -2480,7 +2672,7 @@ type Controls<Layout extends string = string> = {
   readonly available: boolean;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/lifecycle.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/game/src/lifecycle.d.ts
 /** @group Lifecycle */
 type LifecycleListener = (phase: Phase, previous: Phase) => void | Promise<void>;
 /**
@@ -2499,7 +2691,7 @@ type Lifecycle = {
   on(listener: LifecycleListener): Unsubscribe;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/loop.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/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.
@@ -2553,7 +2745,7 @@ type Loop = {
   tick(frame: FrameCallback): Unsubscribe;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/panel.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/game/src/panel.d.ts
 /**
  * The pages of the host's panel a game has a name for, as the keys of this
  * interface.
@@ -2691,7 +2883,7 @@ type Panel = {
   open(page: PageId): void;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/pause.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/game/src/pause.d.ts
 /**
  * The host has asked for a pause, or for the game to carry on.
  *
@@ -2752,7 +2944,7 @@ type Pause = {
   on(listener: PauseListener): Unsubscribe;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/resources.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/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.
@@ -2782,7 +2974,7 @@ type Resources = {
   on(listener: ResourcesListener): Unsubscribe;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/save.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/game/src/save.d.ts
 /**
  * What a game gets back from a read: its own schema number, and its state.
  *
@@ -2792,7 +2984,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;
 };
 /**
@@ -2832,20 +3027,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 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 SaveMergeListener = (merged: SaveState) => void;
+type SaveChangeListener = (save: SaveState | null, why: SaveChangeReason) => void;
 /**
  * What a game says about its save at `init`, before the host has asked
  * anything.
@@ -2891,10 +3107,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
@@ -2907,19 +3125,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.
+   *
+   * 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.
    *
-   * 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.
+   * 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-A6KFyv/game/src/score.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/game/src/score.d.ts
 /**
  * Where this player stands on every board, as far as anybody has said.
  *
@@ -2996,7 +3226,7 @@ type Score<Board extends string = string> = {
   }): Promise<ScoreResult>;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-A6KFyv/game/src/share.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/game/src/share.d.ts
 /**
  * @group Share
  * @category Important
@@ -3023,9 +3253,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.
    *
@@ -3035,23 +3274,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
@@ -3063,12 +3305,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-A6KFyv/game/src/init.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-BSfTrJ/game/src/init.d.ts
 /**
  * What `init` hands back: every namespace a game has, on one object.
  *
@@ -3364,4 +3606,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 GestureButton, type GestureHandlers, type GestureOptions, type Gestures, 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 PointerLock, 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, type View, type ViewOptions, init, insetsFrom };