@hopple/sdk 0.1.0-rc.2 → 0.1.0-rc.3

package/README.md

@@ -42,23 +42,25 @@ Both are named in the project's hopple config (`hopple.config.ts`, `.js` or
 like. `npx hopple create my-game` sets up the recommended way (Vite, with the
 config in TypeScript); see [`hopple create`](https://docs.hopple.app/cli.md#hopple-create).
 
-The host loads the page into a frame sandboxed with only `allow-scripts` and
-`allow-pointer-lock`. That has some consequences you need to plan for:
-
-- **One file to publish.** `hopple publish` uploads only the page, so
-  everything the game needs (scripts, styles, images, sounds) must be inside
-  it, and it refuses a page that loads anything from beside itself. During
-  development `hopple dev` also serves the other files in the page's
-  directory, but a published game can't rely on them.
-- **No network.** A game can't fetch, open a socket or load anything from a
-  URL, on any host. It may load only from its own page and from `data:` and
-  `blob:` URLs. Anything the game could send out could carry what it knows
-  about the player. During development `hopple dev` lets the game load the
-  files beside its page, and nothing else.
-- **Inline your scripts.** Inline scripts run, classic or module, and a
-  published game's scripts are inline anyway.
-- **No `localStorage`, cookies or IndexedDB.** They are unavailable on an
-  opaque origin. Use [`sdk.save`](#save) instead.
+The host loads the page into a frame sandboxed with only `allow-scripts`,
+`allow-same-origin` and `allow-pointer-lock`, every version on an origin of
+its own. That has some consequences you need to plan for:
+
+- **Its output directory is published.** `hopple publish` uploads the
+  directory the page is in, with the page as its `index.html`, and it refuses
+  a page that loads a file the directory doesn't hold. Refer to files
+  relatively. A page beside its config is published alone.
+- **No network.** A game can't fetch, open a socket or load anything from
+  another host. It may load its own files, and `data:` and `blob:` URLs.
+  Anything the game could send out could carry what it knows about the
+  player.
+- **No `localStorage`, `sessionStorage`, IndexedDB, Cache Storage or
+  cookies.** Whatever a game stored would be cleared every time its page
+  loads, so the runtime makes each of them throw an error naming
+  `Hopple.save`, and `hopple check` refuses a game that uses them. Use
+  [`sdk.save`](#save) instead.
+- **Every address relative, no `<base>`, and UTF-8 pages.** `hopple check`
+  refuses the rest.
 - **No `alert`, `confirm` or `prompt`.** They are blocked in the sandbox.
 - **Sound may need a tap inside the game first.** Browsers only allow audio
   after a user gesture in the frame. Sound routed through
@@ -67,15 +69,35 @@ The host loads the page into a frame sandboxed with only `allow-scripts` and
 
 ## Getting started
 
-The SDK becomes part of your page; nothing loads it at runtime.
+The SDK is not part of your game. It is **the runtime**, which whatever runs
+the game serves beside it, and your page loads as its first script:
+
+```html
+<script src="_rt/1/hopple.js"></script>
+```
+
+The runtime defines the global `Hopple`, holding everything this guide
+describes. Because it is served rather than built into the game, a fix to the
+SDK (input, on-screen controls, audio, layout, the loop, save) reaches every
+game without a rebuild. `_rt/1/` is the newest release of major 1; a change
+that would break games is a new major, which a game takes by changing its
+tag. Keep the address relative, as above: Hopple serves a game at the root of
+its own origin, and a host like itch.io under a path, with `_rt/` beside
+`index.html` either way.
 
 - **With a bundler** (Vite, esbuild, webpack, Rollup, Parcel, Bun):
-  `npm install @hopple/sdk` and import it. Types come with it, and so does
-  every doc comment, in `node_modules/@hopple/sdk/index.d.ts`.
-- **Without one:** paste `node_modules/@hopple/sdk/hopple-sdk.min.js` into a
-  classic `<script>` before your own, and use the global `Hopple`
-  (`await Hopple.init(…)` in a module script or an async function). Its first
-  line says which SDK version it is, for your manifest's `sdk`.
+  `npm install @hopple/sdk` and import it. The package is the SDK's types,
+  with every doc comment, in `node_modules/@hopple/sdk/index.d.ts`, and a
+  stub of a few lines that forwards each import to `Hopple`: your bundle
+  carries the stub, never the SDK. Set your bundler to write relative
+  addresses (Vite: `base: './'`).
+- **Without one:** use the global `Hopple` directly
+  (`const sdk = await Hopple.init()` in a module script or an async function).
+
+`hopple check`, `hopple publish` and the server refuse a page that doesn't
+load the runtime first, or that carries a copy of the SDK. Games published
+before the runtime keep the SDK they bundled, and get no runtime fixes until
+they are rebuilt this way.
 
 A `hopple.config.json` can point its `"$schema"` at
 `./node_modules/@hopple/sdk/config.schema.json` for an editor to check it; a
@@ -719,12 +741,15 @@ sdk.pause.on(async (paused) => {   // the host asked; return a promise to make i
 - [ ] Print button labels from `sdk.input.mapping`, and read input once per frame.
 - [ ] Route every sound through `sdk.audio.output` or `media`, or multiply it by `sdk.audio.volume(channel)`, and obey mute.
 - [ ] Keep `sdk.pause` up to date, separately from the loop.
-- [ ] Publish a single self-contained HTML file.
+- [ ] Load the runtime as the page's first script, `<script src="_rt/1/hopple.js"></script>`, and import `@hopple/sdk` rather than bundling a copy.
+- [ ] Refer to every file relatively, and publish the output directory.
 
 ## License
 
-MIT; see `LICENSE`. The SDK is built into every game, so a game carries its
-one-line notice, `/*! @hopple/sdk | Copyright (c) 2026 The Hopple authors | MIT License */`.
+MIT; see `LICENSE`. A game carries the stub, which carries its one-line
+notice, `/*! @hopple/sdk <version> | Copyright (c) 2026 The Hopple authors | MIT License */`.
 Bundlers keep comments that start with `/*!` unless they minify them away:
 with Vite, set `build.rolldownOptions.output.comments.legal` to `true`, as a
-`hopple create` project does. The license covers the code, not the Hopple name or logo.
+`hopple create` project does. The runtime, which is the SDK itself, is MIT
+too, and is served beside the game rather than carried in it. The license
+covers the code, not the Hopple name or logo.

package/index.d.ts

@@ -1,4 +1,4 @@
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/protocol/src/achievement.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/protocol/src/achievement.d.ts
 /**
  * The largest value progress will carry.
  *
@@ -28,7 +28,7 @@ type AchievementResult = {
   progress?: number;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/protocol/src/analytics.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/protocol/src/analytics.d.ts
 /**
  * What a game says happened.
  *
@@ -59,7 +59,7 @@ type AnalyticsValue = string | number | boolean;
 /** @group Analytics */
 type AnalyticsProps = Record<string, AnalyticsValue>;
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/protocol/src/audio.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/protocol/src/audio.d.ts
 /**
  * How loud the game is allowed to be, which is the host's to decide and the
  * game's to obey.
@@ -164,7 +164,7 @@ declare const AUDIO_FULL: AudioState;
  */
 declare function audioVolumeOf(state: AudioState, channel?: string): number;
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/protocol/src/errors.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/protocol/src/errors.d.ts
 /**
  * How a call fails.
  *
@@ -234,7 +234,7 @@ declare class BridgeError extends Error {
   constructor(error: ProtocolError);
 }
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/protocol/src/envelope.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/protocol/src/envelope.d.ts
 /**
  * `p` is the protocol version, carried on every message rather than only at the
  * handshake, because a message that arrives without context still has to be
@@ -275,7 +275,7 @@ type Envelope = {
   data: unknown;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/protocol/src/input.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/protocol/src/input.d.ts
 /**
  * What the host says about how this game is being played.
  *
@@ -386,7 +386,7 @@ type InputChangeCause =
 /** A player changed how the on-screen controls behave. */
 'setting';
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/protocol/src/panel.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/protocol/src/panel.d.ts
 /**
  * The pages of the panel this version of the protocol has a name for.
  *
@@ -416,7 +416,7 @@ type PageId =
 /** @group Panels */
 declare const PAGES: readonly PageId[];
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/protocol/src/pause.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/protocol/src/pause.d.ts
 /**
  * Whether the game is holding still, which the host may ask for and only the
  * game can answer.
@@ -489,7 +489,7 @@ declare const PAUSE_STATES: readonly PauseState[];
  */
 declare const PAUSE_NONE: PauseState;
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/protocol/src/save.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/protocol/src/save.d.ts
 /**
  * The one thing a game may keep.
  *
@@ -540,7 +540,7 @@ type SaveStored = {
   bytes: number;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/protocol/src/score.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/protocol/src/score.d.ts
 /**
  * What a player did, as one number.
  *
@@ -616,7 +616,7 @@ type ScoreStanding = {
   of?: number;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/protocol/src/share.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/protocol/src/share.d.ts
 /**
  * A link to this game, offered to the player by the host.
  *
@@ -715,7 +715,7 @@ type ShareMeta = {
   [key: string]: ShareMetaValue;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/protocol/src/methods.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/protocol/src/methods.d.ts
 /**
  * How far a game has got with its own preparation.
  *
@@ -895,7 +895,7 @@ type DeviceInfo = {
   tier: DeviceTier;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/protocol/src/listeners.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/protocol/src/listeners.d.ts
 /**
  * The one way anything here is listened to: `on(listener)` hands back the
  * function that stops it.
@@ -924,7 +924,7 @@ type DeviceInfo = {
  */
 type Unsubscribe = () => void;
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/protocol/src/transport.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/protocol/src/transport.d.ts
 /** @group Bridge */
 type Transport = {
   send(message: Envelope): void;
@@ -1022,7 +1022,7 @@ declare global {
   var __HOPPLE_SET_SHIM__: ((shim: HoppleShim) => void) | undefined;
 }
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/manifest/src/manifest.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/manifest/src/manifest.d.ts
 /**
  * What a game says about itself.
  *
@@ -1919,7 +1919,7 @@ type HoppleConfig = {
   manifest: GameManifest;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/game/src/achievements.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/game/src/achievements.d.ts
 /**
  * Where this player stands on one achievement.
  *
@@ -1994,6 +1994,9 @@ type Achievements<Id extends string = string, Measured extends string = Id> = {
    * Legitimate on a measured achievement too, and it finishes it: the progress
    * goes to the target rather than leaving something unlocked at 40 of 100.
    *
+   * Cheap to call every frame: one already unlocked, or already sent, is not
+   * sent again.
+   *
    * An id this game's manifest never declared is reported to `onError`, as an
    * author's mistake and not a player's.
    */
@@ -2004,7 +2007,8 @@ type Achievements<Id extends string = string, Measured extends string = Id> = {
    * *At 40*, not *add one*. The host keeps whichever value the manifest calls
    * better — the larger on an ordinary count, the smaller on a best time — so
    * reporting the same number twice does nothing, and reporting a worse one is
-   * not a regression. Reaching the target unlocks it.
+   * not a regression. Reaching the target unlocks it. The same value as the
+   * last one sent is not sent again, so this is cheap to call every frame.
    *
    * Against an achievement declared as a flag, the host refuses it and the
    * refusal is reported to `onError`: there is no target to move toward, and a
@@ -2013,7 +2017,7 @@ type Achievements<Id extends string = string, Measured extends string = Id> = {
   progress(id: Measured, value: number): void;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/game/src/analytics.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/game/src/analytics.d.ts
 /**
  * @group Analytics
  * @category Important
@@ -2030,7 +2034,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-XAG7tD/game/src/audio.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/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
@@ -2123,7 +2127,7 @@ type Audio<Channel extends string = string> = {
   media(element: HTMLMediaElement, channel?: Channel): Unsubscribe;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/game/src/info.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/game/src/info.d.ts
 /**
  * What the host said, frozen.
  *
@@ -2141,7 +2145,7 @@ type Info = Readonly<{
   device: Readonly<DeviceInfo>;
 }>;
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/game/src/layout.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/game/src/layout.d.ts
 /**
  * How much of each edge belongs to the host. CSS pixels.
  *
@@ -2251,7 +2255,7 @@ type InsetPolicy = {
  */
 declare function insetsFrom(obstructions: readonly Obstruction[], frame: Size, policy?: InsetPolicy): Insets;
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/game/src/names.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/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
@@ -2358,7 +2362,7 @@ type EventProps<M> = M extends {
  */
 type StickName = 'pad.left.stick' | 'pad.right.stick' | 'pad.stick' | `controls.${string}`;
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/game/src/input/state.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/game/src/input/state.d.ts
 /**
  * Where the pointer is, in the frame's own coordinates.
  *
@@ -2419,7 +2423,7 @@ type InputSnapshot<Action extends string = string> = {
   pointer: PointerState | null;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/game/src/input/controls.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/game/src/input/controls.d.ts
 /**
  * The name a host leaves its input shim under.
  *
@@ -2599,7 +2603,7 @@ declare function isInputShim(value: unknown): value is InputShim;
  */
 declare const INPUT_CONTRACT = 4;
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/game/src/input/bindings.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/game/src/input/bindings.d.ts
 /**
  * The standard mapping's buttons, by index, as the names this SDK uses.
  *
@@ -2651,7 +2655,7 @@ declare function servesScheme(binding: string, scheme: InputScheme): boolean;
  */
 declare function labelFor(binding: string, scheme: InputScheme): string;
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/game/src/input/index.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/game/src/input/index.d.ts
 /**
  * How far a stick moves before it counts, where no shim has an opinion.
  *
@@ -2787,7 +2791,7 @@ type Controls<Layout extends string = string> = {
   readonly available: boolean;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/game/src/lifecycle.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/game/src/lifecycle.d.ts
 /** @group Lifecycle */
 type LifecycleListener = (phase: Phase, previous: Phase) => void | Promise<void>;
 /**
@@ -2806,7 +2810,7 @@ type Lifecycle = {
   on(listener: LifecycleListener): Unsubscribe;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/game/src/loop.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/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.
@@ -2860,7 +2864,7 @@ type Loop = {
   tick(frame: FrameCallback): Unsubscribe;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/game/src/panel.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/game/src/panel.d.ts
 /**
  * Where the host's panel stands over the game.
  *
@@ -2969,7 +2973,7 @@ type Panel = {
   open(page: PageId): void;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/game/src/pause.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/game/src/pause.d.ts
 /**
  * The host has asked for a pause, or for the game to carry on.
  *
@@ -3030,7 +3034,7 @@ type Pause = {
   on(listener: PauseListener): Unsubscribe;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/game/src/resources.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/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.
@@ -3060,7 +3064,7 @@ type Resources = {
   on(listener: ResourcesListener): Unsubscribe;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/game/src/save.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/game/src/save.d.ts
 /**
  * What a game gets back from a read: its own schema number, and its state.
  *
@@ -3149,7 +3153,7 @@ type Save = {
   readonly maxBytes: number;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/game/src/score.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/game/src/score.d.ts
 /**
  * Where this player stands on every board, as far as anybody has said.
  *
@@ -3226,7 +3230,7 @@ type Score<Board extends string = string> = {
   }): Promise<ScoreResult>;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/game/src/share.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/game/src/share.d.ts
 /**
  * @group Share
  * @category Important
@@ -3298,7 +3302,7 @@ type Share = {
   }): void;
 };
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/game/src/init.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/game/src/init.d.ts
 /**
  * What `init` hands back: every namespace a game has, on one object.
  *
@@ -3603,7 +3607,7 @@ type InitOptions = {
  */
 declare function init<M extends object = GameManifest>(options?: InitOptions): Promise<GameSdk<M>>;
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/game/src/transport.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/game/src/transport.d.ts
 /**
  * How long a game with no shim and no parent waits for one to turn up.
  *
@@ -3633,7 +3637,7 @@ type HostTransportOptions = {
  */
 declare function hostTransport(options?: HostTransportOptions): Promise<Transport>;
 //#endregion
-//#region ../../../../../../../tmp/hopple-sdk-types-XAG7tD/game/src/shim.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-DAYaix/game/src/shim.d.ts
 /**
  * Whether an arbitrary value is a shim this SDK knows how to speak to.
  *