@diffenderfer-games/hub 2.0.0-next.0 → 2.0.0-next.10

package/CHANGELOG.md

@@ -0,0 +1,163 @@
+# @diffenderfer-games/hub
+
+## 2.0.0-next.10
+
+### Patch Changes
+
+- 5d68e5f: Adventure Mode (the world, full screen at `/world`):
+  
+  - `world.say` takes `{ quick }` or `{ text }`: typed text is moderated like all chat and delivered only to the mutual friends who can see you (strangers get quick chat only); the `world.say` event's `quick` is absent for typed text.
+  - `world.find { userId }` (new): where a friend is (world, instance, their cell when they share yours) and the portals to walk through; `friend_not_in_world` for anyone who isn't a friend showing you their presence.
+  - `world.enter`'s `world` is optional (your last world, else the Hall) and both it and `world.teleport` take `friend` to join that friend's instance; `WorldPlace.chat` says whether you may type.
+  - `@diffenderfer-games/world`: `portalEdges` and `planWorldRoute`, the fewest-portals route between worlds.
+  - `@diffenderfer-games/hub`: a page the host injected without a slug (the catalog, Adventure Mode) has no game (`hub.slug` is `null`).
+- 5deeb66: `TurnGame`'s quiet-refresh safety net now also runs while the game is a lobby (waiting for seats or a start), so a page waiting in a lobby fetches the game again if it missed a live event.
+- Updated dependencies [5d68e5f]
+  - @diffenderfer-games/hub-contract@2.0.0-next.10
+  - @diffenderfer-games/world@2.0.0-next.10
+
+## 2.0.0-next.9
+
+### Minor Changes
+
+- c464aae: Avatars get a world-scale figure: `figure: 'walker'` (on `RenderOptions` for full frames, on `createAtlas` and on `createCrowd`) draws a small full-body character with legs, arms, a shirt, trousers and shoes and a smaller head, for maps and crowds. It walks (8-step cycles that swing the legs and arms along the facing), runs, sits (the origin is the seat; the feet hang `WALKER_SEAT_DROP` units below it), idles, waves and cheers, and reads clearly from behind. Head and bust frames always draw the usual figure, and `blob` stays the default. Crowd members also take `tagLift` to move a name tag up, so a world can stack tags that would overlap, and a crowd member whose look changes keeps showing its old frame while the new one bakes (no flash to the silhouette). New exports: the `Figure` type, `WALKER_HEAD_SCALE` and `WALKER_SEAT_DROP`.
+
+### Patch Changes
+
+- e28707d: `createCrowd` (`/avatar/pixi`) takes two optional settings for worlds: `overlays`, a container for name tags and bubbles (so they can sit above a lighting layer), and `displayScale`, which draws atlas avatars at that scale (bake the atlas at `scale × devicePixelRatio` and pass `1 / devicePixelRatio` for crisp avatars on high-density screens). Both default to the old behaviour.
+- 4eefc6c: `createCrowd` (`/avatar/pixi`): a member whose look has not baked yet shows the silhouette at its spot and at the crowd's `displayScale`, like a baked frame (it was drawn at full size with its corner at the feet, so on high-density screens it showed twice as big, below and to the right of its name tag).
+- ef850e8: The world, ready to publish and live on the hub.
+  
+  - `@diffenderfer-games/world` (first release): the `dg-world@1` map format with compressed `"encoding": "rle"` layers, a map `revision`, the generator's `provenance.generatorVersion` (the same seed and needs at the same version always give the same map), strict validation with readable paths, and size limits (`WORLD_LIMITS`, `parseWorldMapText`). New: `serializeWorldMap`, `encodeWorldMap`, `mapFingerprint`, `generatorVersionOf`, the Tiled converter (`worldMapToTiled`, `worldMapFromTiled`: layers, tile properties, objects, zones and lights, both ways) and the `dg-world` CLI (`check`, `from-tiled`, `to-tiled`, `generate`).
+  - `@diffenderfer-games/hub-contract`: `game.world` in the manifest (`map` and/or `generate: { type, seed, needs }`), the `world.*` socket ops (`enter`, `leave`, `move`, `sit`, `stand`, `teleport`, `say`) and events (`world.state`, `world.say`), `GET /world/maps/:key`, the world error codes, and `world` on a friend's presence.
+  - `@diffenderfer-games/hub`: `hub-doctor` checks a `game.world.map` file (it exists, is a valid map and is within the size limit) and warns about an unknown world type; the realtime API's optional `world` (feature version 6).
+- Updated dependencies [ef850e8]
+  - @diffenderfer-games/world@2.0.0-next.9
+  - @diffenderfer-games/hub-contract@2.0.0-next.9
+
+## 2.0.0-next.8
+
+### Minor Changes
+
+- ac6b1cd: Online games (`hub.turns`): `TurnGame.mayActNow` says this player may move now out of turn (the rules' `mayAct`: offer the jump-in, the UNO call, the catch), and `TurnGame.tournament` names the tournament match a game is. A `move()` answer that arrives after live events already brought newer moves no longer rolls the page back (nor does an older live event). `letComputerPlay()` documents the hand-over case. The rules kit `checkTurnRules` now moves every seat in `toAct` (not only the first) and seats in `mayAct` through `autoReact` (or the new `reactMove` option), fails on an illegal `autoReact` or a seat that does not exist, and reports `outOfTurn`.
+- c12868a: Online games: new `@diffenderfer-games/hub/turns-rules` entry for a game's rules module (`defineTurnRules`, the rules types and the RNG, nothing else: the bundle stays a few KB instead of about 1 MB; `/turns` re-exports it with the kit). `TurnGame.canLetComputerPlay(now?)` says when "Let the computer play" may work (from `summary.handOverAt`, the seats' new `connected` and the deadline); `turn` now also fires when a seated player comes or goes or `handOverAt` changes. `refresh()` (and every other fetch) no longer rolls the game back when its answer is older than a live move that arrived meanwhile, and never replays that move twice. The rules kit `checkTurnRules` gains `revealed(state, marker)` (a planted card the rules rightly reveal, such as one played face up, stops being checked) and `shuffleHidden(state, seat, rng)` (the "twin table": shuffling what a seat can't see must not change its view).
+  
+  `TurnGame.move()` fetches the game again after a 500 `rules_error` or 503 `rules_busy` (the hub now makes a move all or nothing, so such a move was not made).
+  
+  The "your turn" buzz: every online game's page gives a short vibration when the player becomes due on a live update (never for their own next step, a move out of turn, a game just opened or a catch-up; never when they turned it off, ask for less motion, or the device can't vibrate). `hub.turns.setYourTurnBuzz(false)` and `TurnGame.setYourTurnBuzz(false)` opt a page or game out; `hub.turns.playerYourTurnBuzz` is the player's own switch on this device (the menu's Settings show it), with `readYourTurnBuzz`, `saveYourTurnBuzz`, `isNewlyDue`, `YOUR_TURN_BUZZ` and `YOUR_TURN_BUZZ_KEY` exported. A visible page waiting on another player's move that hears nothing for `TURN_QUIET_MS` (15 s) fetches the game again, so games need no polling of their own.
+
+### Patch Changes
+
+- Updated dependencies [3a67590]
+- Updated dependencies [70dcfa1]
+- Updated dependencies [c77830f]
+- Updated dependencies [ac6b1cd]
+- Updated dependencies [c12868a]
+  - @diffenderfer-games/hub-contract@2.0.0-next.8
+
+## 2.0.0-next.7
+
+### Minor Changes
+
+- 99d0932: Avatars: long hair now hangs behind the body. The parts of a hair style below the shoulders are drawn before the body (in SVG, Canvas, `<dg-avatar>`, the Pixi atlas and the three.js adapter) while the fringe and anything over the face stay over the head; back views keep the hair over the back. The renderer draws the eight new glasses in style C with any frame colour (light frames, and frames close to the skin, get a dark edge) and tinted lenses for sunglasses, sport and hearts (a mirror finish for `p:lens-mirror`); winks and sleepy eyes show through the lenses. `describe()` names them. The `/avatar` entry re-exports `FRAME_PRESETS`, `isTinted` and `SECOND_COLOUR_CODE`.
+
+### Patch Changes
+
+- Updated dependencies [99d0932]
+  - @diffenderfer-games/hub-contract@2.0.0-next.7
+
+## 2.0.0-next.6
+
+### Minor Changes
+
+- 537272a: `hub.avatar`: players' avatars without the renderer. `mine()` / `mineSync()` (works offline from the device cache), `of(userId)` and `many(ids)` (batched and cached), `from(seat)` (any payload with `look`, no request), `bot(seed)` for computer players, `save(look)` (queued offline), `on('change')`, `openDesigner()` ("Make your avatar" over the game) and `load()` (the `/avatar` renderer with its art). A DOM-free `@diffenderfer-games/hub/avatar/svg` entry renders avatars as SVG on servers and in workers.
+- fb0a9f5: `hub.userId()`: your user id, or `null`, synchronously. It follows the account as the hub changes it (the menu's new-guest account, sign-in, sign-out, the live connection's hello) with no `hub.me()` call.
+  
+  `hub.avatar` follows the account too: when your account appears or changes, your look is fetched and `change` fires with your `userId`; before it exists, `mine()` resolves at once with a default look. Each time the live connection (re)connects, the looks this page asked about are checked again and `change` fires for any that changed while it was down. `change` for your own look fires only when it differs from the one the page last had.
+- 849874f: Avatars: draw players' faces in any game. New entries: `@diffenderfer-games/hub/avatar` (`ready()`, `render.svg/element/canvas/canvasAt/bitmap/dataUrl`, `<dg-avatar>` via `defineAvatarElement()`, the `animator` with 16 expressions, gaze, blinks, talking, reactions and `feel()`, `layout()` anchors, `facingFrom`, `lookToward`, `describe`, `avatarEmoji`, overlays and `createAtlas`), `@diffenderfer-games/hub/avatar/pixi` (`pixiAvatar`, `avatarTexture`, `createCrowd`) and `@diffenderfer-games/hub/avatar/three` (`avatarCanvasTexture`, `avatarSprite`). The adapters take your PIXI or THREE namespace; no new dependencies. See "Avatars" in docs/hub.md.
+- 5109a42: The avatar renderer draws the new `beard.short` (a short, neat beard with a moustache) in style C, with the same beard and moustache layers and tonal outline as the full beard, in SVG, `<dg-avatar>` and the Pixi and three.js adapters. `describe()` calls it "a short beard".
+- e86bfb4: "Your turn" alerts and quiet hours. The contract adds the `your_turn` notice and preference kind, `NotifyPrefs.yourTurn`/`yourTurnOff`/`yourTurnAsked`/`quiet`, `QuietHours` and `PUT /social/notify/quiet` (`setQuietHours`), plus `POST /turns/:id/share` (`shareTurnGame`) and `autoStart` on `createTurnGame`. The client adds `TurnGame.share({ link?, public? })`, `hub.turns.create({ autoStart })`, `TURN_RESYNC_EVENT` (an open online game fetches what it missed when the live connection comes back; `turn` also fires on a `chatMode` or `link` change), and `hub.saved.onOpen(handler, { kinds })`. A second Rematch joins the first one's game.
+- e0e38da: Daily challenges in progress. A started day is now a saved game: starting it again (the calendar, a `?daily=` link, Your games) picks it up where the player left it, at any age, and winning it any time later gives that day's credit. `hub.daily` adds `save({ state, progress, title?, version? })`, `resume(instanceId)`, `discard()` and `inProgress()`; `challenge.saved`/`savedVersion`/`instanceId`/`resumed` in `play(challenge)`; the `hub:daily-resumed`, `hub:daily-paused` and `hub:daily-discarded` events. `hub.daily.cancel()` now pauses the day (it stays in progress) instead of dropping it. `hub.resume.save()` during a daily saves to the day instead of being ignored (`blockedBy` no longer reports `'daily'`), so games that already use `hub.resume` get mid-daily saves for free; `hub.resume.clear()` during a daily restarts the day. Works offline (a day started offline lands as the one saved game for that day). The contract adds `StartedDailyChallenge` (start answers `instanceId`, `saved`, `savedVersion`, `resumed`), `POST /daily/instances/:id/resume`, `inProgress` days in `GET /daily` and `GET /games/:slug/daily`, and 409 `too_many_dailies` (60 per game).
+- ce80c33: Saved games (foundations). New `hub.saved`: `list()` (this game's games in progress: daily challenges, the saved run, online games), `listAll()`, `opened` (the instance the page was opened for, `?hub_open=<id>&hub_kind=<kind>`), `onOpen(handler)` (switch to a game picked from the hub menu without a reload), `open(id)`, `discard(id)`, `counts()` and `on('change', cb)`. Works offline from the device's copies. The contract adds `api/saved.ts` (`GET /saved`, `GET /saved/:id`, `PUT /saved/:id/state`, `POST /saved/:id/discard`, `POST /games/:slug/saved/discard`), the `saved` socket event, `TurnSummary`, the error codes `instance_closed` and `too_many_dailies`, and the pure `compareSaved`/`countSaved`. `hub.resume` is unchanged for games; saved runs never expire any more (`RESUME_RETENTION_MS` is deprecated and unused).
+- 0c5c833: Online games played over days. A game declares `game.turns` (`rules`, `players`, `bots`, `modes`, `maxApplyMs`) and ships its rules as one self-contained ES module (the `TurnRules` contract: `setup`, `view`, `toAct`, `apply`, `eventView`, `outcome`, `progress`, `autoMove`, `migrate`); the hub runs it on the server, so hands and decks never reach another player. New `hub.turns` (`create`, `join`, `open`, `list`, `openLobbies`, `link`) and `TurnGame` (`summary`, `view`, `mySeat`, `outcome`, `chat`, `chatMode`, `link`, `start`, `move`, `history`, `leave`, `nudge`, `setNotify`, `rematch`, `invite`, `letComputerPlay`, `say`, `refresh`, `close`, events `move`, `turn`, `ended`, `chat`). `@diffenderfer-games/hub/turns` exports the rules types, `defineTurnRules`, the seeded RNG and the `checkTurnRules` conformance kit for a game's own tests. `HubError.rule` carries a rules refusal's code; `hub.resume.blockedBy` can be `'turns'`. The contract adds `api/turns.ts`, the `turn` and `turn.chat` events, the turn error codes, `ErrorBody.rule`, Play online's `yourTurn`/`turns`/`openTurns`/`turnGames`, and the `turn_chat` report kind.
+
+### Patch Changes
+
+- 4a03d21: The avatar adapters take the engines' real types and give them back: `pixiAvatar`, `avatarTexture` and `createCrowd` (`/avatar/pixi`) accept `import * as PIXI from 'pixi.js'` or an object of the named imports, and `face.view` is pixi's own `Sprite` (it goes into a `Container` with no cast). `avatarSprite` and `avatarCanvasTexture` (`/avatar/three`) do the same for three.js, returning three's `Sprite` and `CanvasTexture`; `avatarCanvasTexture` needs only `CanvasTexture` (the new `ThreeTextureNs`). `PixiNs`, `PixiSprite`, `PixiContainer`, `PixiAvatar`, `CrowdOptions`, `ThreeNs` and `ThreeAvatarTexture` are generic over the game's classes, with defaults, so existing annotations keep compiling. No runtime change.
+- bcb10f1: `hub.resume.clear()` during a daily challenge now reaches the hub (the day starts over from its seed on every device instead of the old state coming back), and `hub.resume.get()`/`load()` dropping an older-version saved run no longer restarts the daily being played.
+- ac2884e: `hub.input.autoNavigateTarget()` returns the game's current `autoNavigate` target (its query and back action), so hub dialogs that borrow the gamepad give the game's menu navigation back when they close. Fixes gamepad menu navigation being lost after a social dialog (a confirm, the share sheet) closed.
+- b2e9e64: Saved runs (`hub.resume`) are now saved games of their own kind and never expire; the API is unchanged. The menu's Reset game also offers to discard the game's daily challenges in progress.
+- 93af853: `hub.input.setInsets` also publishes the insets as `--hub-inset-top` (and right, bottom, left) on the page, so the hub's toasts sit below a game's top bar (without it, the hub looks for a top bar in the page itself).
+- 06f827c: `TurnGame` fires `turn` when a seated player changes their avatar (the seat's `look`), not only when statuses or players change.
+- Updated dependencies [91ca7f9]
+- Updated dependencies [46fa584]
+- Updated dependencies [5109a42]
+- Updated dependencies [bf6445c]
+- Updated dependencies [508531a]
+- Updated dependencies [e86bfb4]
+- Updated dependencies [e0e38da]
+- Updated dependencies [ce80c33]
+- Updated dependencies [0c5c833]
+- Updated dependencies [17cf0af]
+  - @diffenderfer-games/hub-contract@2.0.0-next.6
+
+## 2.0.0-next.5
+
+### Patch Changes
+
+- 7585522: Saves offline no longer risk the cloud copy. Offline, `getSave(slot)` rejects with a `HubError` whose `code` is `save_unknown` (new export `SAVE_UNKNOWN_CODE`; `isOffline` is `true`) when the device has never seen the hub's copy of that slot, instead of answering `save: null`; it still answers from the device's copy after a snapshot (`prefetchAll`), an online read, a landed write, or for a slot the device wrote and has queued. A `putSave` replayed from the offline queue now sends `base`, the slot's `updatedAt` on the hub as the device last saw it, and the hub refuses it with 409 `save_conflict` when another device saved since (dropped and reported in the `hub:sync` conflicts); writes sent at once while online are unchanged. The client also remembers the signed-in user from `login`, `signup`, `claim` and `ensureGuest` replies, and forgets it on `logout`. Contract: `writeSave` takes an optional `base` and may answer 409; new error code `save_conflict`. Older clients (no `base`) behave as before. See docs/hub.md "Saves offline".
+- Updated dependencies [7585522]
+  - @diffenderfer-games/hub-contract@2.0.0-next.5
+
+## 2.0.0-next.4
+
+### Minor Changes
+
+- 9f993ab: Resume saved games. New `hub.resume` (`save`, `flush`, `clear`, `load`, `get`, `requested`, `blockedBy`, `list`, `discard`): one auto-saved run per player per game that the home page's new Resume card lists, so players pick long single-player runs up again on any device. Saves are kept on the device at once, debounced (3 s), sent when the page hides, and replay offline through the new `hub.resume` outbox kind; they are ignored during races, daily challenges and hub rooms. `hub.resume.requested` is a synchronous `true` when the page was opened from the card (`?hub_resume=1`, taken out of the URL). Games opt in with `game.resumable: true` in the manifest. Contract: `resumeEndpoints` (`getResumeSlot`, `saveResumeSlot`, `clearResumeSlot`, `listMyResumeSlots`), `ResumeSlot`, `ResumeSummary`, `ResumeProgress`, `ResumeWrite`, `RESUME_MAX_STATE_BYTES` (512 KB), `RESUME_TEXT_MAX`, `RESUME_RETENTION_MS` (60 days), `RESUME_REQUEST_PARAM`; `saveResumeSlot` and `clearResumeSlot` join `OFFLINE_REPLAY_ENDPOINTS`. See docs/hub.md "Resume saved games". Daily: `hub.daily.complete()` now ends the daily run at the call (`hub.daily.active` is `null` at once, even if the hub refuses the completion); games must call `hub.daily.cancel()` when the player leaves a daily unfinished, or `hub.resume.save` stays off (it warns once).
+
+### Patch Changes
+
+- Updated dependencies [9f993ab]
+  - @diffenderfer-games/hub-contract@2.0.0-next.4
+
+## 2.0.0-next.3
+
+### Patch Changes
+
+- ce98e79: Focus rings only for keyboard and gamepad players. The input system tracks the last input modality on `<html data-hub-input="keys|pointer|touch">`: the navigation highlight and the catalog's `gp-focus` show only after a key or gamepad press, never after a tap or click, and touch screens show no focus ring on buttons at all (the browser's own included). The ring is new: a two-tone box-shadow (dark gap, light ring) that follows the element's own corner radius instead of an orange rectangle, tunable with `--hub-focus-color`, `--hub-focus-inner`, `--hub-focus-width` and `--hub-focus-gap`. New exports from `@diffenderfer-games/hub/input`: `FOCUS_RING_SHADOW`, `MODALITY_ATTRIBUTE`, `trackInputModality` and the `InputModality` type.
+- @diffenderfer-games/hub-contract@2.0.0-next.3
+
+## 2.0.0-next.2
+
+### Minor Changes
+
+- 3944819: `game.labels`: say what kind of game yours is, from a fixed vocabulary (`GAME_LABELS`, with display names in `GAME_LABEL_TITLES`, grouped in `GAME_LABEL_GROUPS`): genre (`cards`, `board`, `puzzle`, `arcade`, `platformer`, `real-time-strategy`, `physics`, `typing`, `word`, `sports`, `racing`), look (`2d`, `3d`), where it plays (`phone`, `controller`, `desktop`) and players (`multiplayer`, `single-player`). The home page filters by them. An unknown label is a `hub-doctor` warning, not an error.
+  
+  New endpoints: `GET /catalog/players` (how many accounts and guests have each game open right now: counts only) and `GET /games/:slug/me/activity` (the signed-in player's plays and minutes in a game). The `lobbyOpen` notification preference now means "tell me when people want to play": an open public lobby or race, or a tournament opening.
+- 937d61e: Explicit offline replay. Writes made offline now go into a typed operation outbox in `localStorage`: each op has a kind whose handler performs it (several dependent calls can be one op), ops replay in order with backoff when the hub is back and after a reload, one tab replays at a time, and the outbox is capped. Saves, stats, scores, the profile, daily completions, inventory grants and house exchanges, and starring a game all queue offline. Games add their own kinds with `hub.offline.define(kind, handler)`, queue them with `hub.offline.enqueue(kind, payload)`, list them with `hub.offline.pending()`, and hear `queued`, `replayed` and `failed` through `hub.offline.on(...)` (and `hub:offline-*` window events). An offline `hub.daily.complete()` resolves `null`, fires `hub:daily-queued`, and replays later. The contract marks the endpoints that may be replayed (`OFFLINE_REPLAY_ENDPOINTS`); each replayed call carries an operation key (`x-hub-op`) and the hub runs it once per key. `SyncConflict.op` is now the dropped outbox op.
+- ed68402: Invite links and resilient online games (batch 2026-10, R13 and R14).
+  
+  - **Invite links:** `hub.mp.inviteLink()` makes (or reuses) a shareable link to the room the player is in; `hub.mp.revokeInviteLink(token)` revokes it. Opening `/<slug>/<lobby>?hub_link=<token>` arrives as an ordinary `join` or `watch` launch with `via: 'link'`. Contract: `POST /mp/links`, `GET /mp/links`, `DELETE /mp/links/:token`, `POST /mp/links/:token/open`, the `InviteLink` shape and the `link_invalid`, `link_room_gone` and `too_many_links` error codes.
+  - **Resilient rooms:** the new `room.seat` event (`room.on('seat', …)`: `away` with `graceEndsAt`, `back`, `gone` with `reason`), `room.seats()`, `hub.rooms.reclaim()` (socket op `room.reclaim`), seats' `graceEndsAt`, and `Launch.via` (`'link' | 'rejoin'`). The host role now passes on instead of the room closing with `host_left`: once the host's seat is freed by default, or as soon as the host drops with `hub.rooms.create({ hostMigration: 'drop' })`.
+  - The realtime feature version is 3; on an older runtime the new methods reject with `OfflineError` asking for a reload.
+- 5b68831: Tournaments (docs/multiplayer.md §15). `game.multiplayer.tournaments: true` says a game plays 1v1 tournament matches and reports their winner; race games need nothing. A ready match reaches the game as an ordinary `host`/`guest` launch with the new `launch.tournament` (`{ id, title, match, opponent }`); a hub-room game ends it with `room.end({ winnerId })`, an own-server game posts results with `tournament: { id, match }`.
+  
+  New endpoints: `GET /play-online` (lobbies waiting for a player, invites, my tournaments, open ones coming up), `GET|POST /tournaments`, `GET|DELETE /tournaments/:id`, `POST /tournaments/:id/join|leave|start|invites`, `PUT|DELETE /tournaments/:id/follow` and `POST /tournaments/:id/matches/:match/launch`; the `tournament` socket event; the `tournament` notice kind; `GameInfo.tournaments`; `TOURNAMENT_LIMITS`. `hub.social.openPlayOnline()` opens the hub's Play online window (realtime feature version 4).
+
+### Patch Changes
+
+- `hub.input.axis(name)` reads a vertical-only axis (`axes: { paddle: { y: ['up', 'down'] } }`); it used to read 0.
+- A save, profile or score meta with an optional field set to `undefined` is stored and sent as the JSON it stands for (the field left out); with the new outbox it was refused as "Malformed offline operation payload" and never reached the hub.
+- Updated dependencies [3944819]
+- Updated dependencies [937d61e]
+- Updated dependencies [ed68402]
+- Updated dependencies [5b68831]
+  - @diffenderfer-games/hub-contract@2.0.0-next.2
+
+## 2.0.0-next.1
+
+### Patch Changes
+
+- Follow-ups from the Bubble Pop pilot. `hub-doctor` gives up after `--timeout` ms (default 10 s) and fails with `hub unreachable at <url>` instead of hanging. A v1 vendored singleton adopted on the page is now recorded in `window.__DG__` as `{ version: 'v1' }`. The README covers exact pins for prereleases, sharing the page with the host's `/_hub/hub.js`, and testing against the hub.
+- Updated dependencies
+  - @diffenderfer-games/hub-contract@2.0.0-next.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Philip Diffenderfer
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Philip Diffenderfer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,139 +1,203 @@
-# @diffenderfer-games/hub
-
-The client library for games on [diffenderfer.games](https://diffenderfer.games):
-accounts, saves, stats, leaderboards, inventory and trades, daily challenges,
-the input system (keyboard, touch and gamepad), and the social, multiplayer,
-rooms and race namespaces. It is typed from the hub's wire contract
-(`@diffenderfer-games/hub-contract`), ships ES modules with `.d.ts` files, and
-carries no zod at runtime.
-
-## Install
-
-```sh
-npm install @diffenderfer-games/hub
-```
-
-ESM only, for browsers (ES2020: Safari 14+, current Chrome, Edge and Firefox).
-Node 20+ for the `hub-doctor` command.
-
-## Use
-
-```ts
-import { hub } from '@diffenderfer-games/hub';
-
-const { user } = await hub.me();
-await hub.ensureGuest(); // a guest account, so progress saves without a sign-in
-await hub.putSave('auto', { level: 7, gold: 120 });
-await hub.submitScore('highscore', 9001, { title: 'High Score' });
-hub.recordPlay();
-
-hub.input.define({ groups: { play: { inputs: { jump: { keys: [' '], gamepad: { button: 0 } } } } } });
-hub.input.enable('play');
-hub.daily.define({ play: (challenge) => startLevel(challenge.seed) });
-hub.overlay.autoPause({ pause, resume });
-```
-
-In a game the host serves, the slug and the API base are read from the page.
-For anything else, create a client yourself:
-
-```ts
-import { createHub } from '@diffenderfer-games/hub';
-
-const demo = createHub({ slug: 'my-game', apiBase: '/_api', offline: 'auto' });
-```
-
-A game's own JSON is typed by the game: `hub.getSave<MySave>('auto')`,
-`hub.putSave<MySave>('auto', save)`, `hub.getProfile<MyProfile>()`.
-
-## Entry points
-
-| Import | What it has |
-|---|---|
-| `@diffenderfer-games/hub` | `hub`, `createHub`, `Hub`, the errors, every client type, and the input and daily exports |
-| `@diffenderfer-games/hub/input` | `getInput`, `InputSystem`, the on-screen control layout, `getUiStack` |
-| `@diffenderfer-games/hub/daily` | `getDaily`, `DailySystem` |
-| `@diffenderfer-games/hub/race`, `/social`, `/mp`, `/rooms` | one namespace each (`race`, `social` with `presence` and `notify`, `mp`, `rooms`) |
-| `@diffenderfer-games/hub/types` | type-only: every contract type (requests, replies, entities, error codes, socket ops and events, the `game.*` manifest) |
-| `@diffenderfer-games/hub/auto` | everything above, and it sets `window.HubSDK` (what `/_hub/hub.js` is built from) |
-
-The namespaces also hang off `hub` (`hub.input`, `hub.daily`, `hub.race`,
-`hub.social`, `hub.presence`, `hub.notify`, `hub.mp`, `hub.rooms`,
-`hub.overlay`, `hub.menu`), created on first use.
-
-## Errors
-
-Every call rejects with a `HubError` when it fails. `status` is the HTTP
-status, or `undefined` when the hub could not be reached (`isOffline`).
-`code`, `reason`, `hint` and `retryAfterMs` come from the hub's error body.
-
-- `ContentRejectedError`: the safety filter refused some text (HTTP 422).
-  Keep the player's draft and show `hint`.
-- `OfflineError`: an action that needs the hub was tried offline.
-- `code: 'unsupported_by_hub'`: the hub does not have this call yet (the game
-  uses a newer client than the deployed hub). Deploy the hub first.
-
-The analytics calls (`recordPlay`, `heartbeat`, `event`) never throw.
-
-## Offline
-
-With `offline: 'auto'` (the default), reads fall back to a cache in
-`localStorage` when the hub can't be reached, and writes (saves, stats,
-scores, profile) apply to the cache at once and are queued. The queue replays
-in order when the connection returns; `hub.sync()` replays it on demand,
-`hub.pending()` counts what waits, and `hub.onStatus(listener)` reports
-changes. `hub.prefetchAll()` warms the cache for every game in one request.
-`offline: 'always'` never touches the network (develop without a hub);
-`offline: 'never'` always throws instead.
-
-The cache and queue use the same `localStorage` keys as the old vendored
-client, so a game that switches to this package keeps its players' queued
-progress.
-
-## Games without a build step
-
-Keep `import('/_hub/hub.js')` or `window.HubSDK.hub`: the host serves a
-bundle of this package's `./auto` entry, at the version the host was built
-with. Install the package as a dev dependency only if you want editor types:
-
-```js
-/** @type {import('@diffenderfer-games/hub').Hub} */
-const hub = window.HubSDK.hub;
-```
-
-## Versions
-
-The client sends its version as `x-hub-client`. `hub.hubVersion()` reads the
-hub's `GET /_api/version` (`{ server, contract, supported, deprecated }`) once
-per page, and `hub.clientSupport()` says whether this client is `supported`,
-`deprecated` or `unsupported` (`unknown` on a hub from before versioning).
-
-The hub supports the current major and the previous one. Update with
-`npm update @diffenderfer-games/hub`.
-
-## hub-doctor
-
-Run it in a game's folder, in CI and before pushing:
-
-```sh
-npx hub-doctor            # checks against https://diffenderfer.games
-npx hub-doctor --offline  # skip the version check
-npx hub-doctor --hub http://localhost:8080 --dir ../my-game --json
-```
-
-It fails when the installed client is outside the hub's `supported` range or
-the `package.json` `game.*` block does not match the manifest schema, and it
-warns when the client is deprecated or a vendored `src/hub/` copy (or
-`scripts/sync-hub.mjs`) is still around.
-
-## Moving from the vendored copy
-
-1. `npm install @diffenderfer-games/hub`.
-2. Change `from './hub/hub'` (or `'./hub'`) to `from '@diffenderfer-games/hub'`.
-3. Delete `src/hub/` and `scripts/sync-hub.mjs`.
-4. Add `npx hub-doctor` to the game's CI.
-
-Every method name is unchanged.
-
-## License
-
-MIT
+# @diffenderfer-games/hub
+
+The client library for games on [diffenderfer.games](https://diffenderfer.games):
+accounts, saves, stats, leaderboards, inventory and trades, daily challenges,
+the input system (keyboard, touch and gamepad), and the social, multiplayer,
+rooms and race namespaces. It is typed from the hub's wire contract
+(`@diffenderfer-games/hub-contract`), ships ES modules with `.d.ts` files, and
+carries no zod at runtime.
+
+## Install
+
+```sh
+npm install @diffenderfer-games/hub
+```
+
+**Prereleases: pin the exact version.** While the package is on `2.0.0-next.N`,
+a caret range does not move between prereleases the way you might expect, so
+install with `--save-exact` and bump on purpose:
+
+```sh
+npm install --save-exact @diffenderfer-games/hub@2.0.0-next.1
+```
+
+The `next` dist-tag always names the newest prerelease. `latest` points at the
+same prerelease for now. It moves to `2.0.0` with the first stable release,
+after which ordinary `^2.0.0` ranges are fine.
+
+ESM only, for browsers (ES2020: Safari 14+, current Chrome, Edge and Firefox).
+Node 20+ for the `hub-doctor` command.
+
+## Use
+
+```ts
+import { hub } from '@diffenderfer-games/hub';
+
+const { user } = await hub.me();
+await hub.ensureGuest(); // a guest account, so progress saves without a sign-in
+await hub.putSave('auto', { level: 7, gold: 120 });
+await hub.submitScore('highscore', 9001, { title: 'High Score' });
+hub.recordPlay();
+
+hub.input.define({ groups: { play: { inputs: { jump: { keys: [' '], gamepad: { button: 0 } } } } } });
+hub.input.enable('play');
+hub.daily.define({ play: (challenge) => startLevel(challenge.seed) });
+hub.overlay.autoPause({ pause, resume });
+```
+
+In a game the host serves, the slug and the API base are read from the page.
+For anything else, create a client yourself:
+
+```ts
+import { createHub } from '@diffenderfer-games/hub';
+
+const demo = createHub({ slug: 'my-game', apiBase: '/_api', offline: 'auto' });
+```
+
+A game's own JSON is typed by the game: `hub.getSave<MySave>('auto')`,
+`hub.putSave<MySave>('auto', save)`, `hub.getProfile<MyProfile>()`.
+
+## Entry points
+
+| Import | What it has |
+|---|---|
+| `@diffenderfer-games/hub` | `hub`, `createHub`, `Hub`, the errors, every client type, and the input and daily exports |
+| `@diffenderfer-games/hub/input` | `getInput`, `InputSystem`, the on-screen control layout, `getUiStack` |
+| `@diffenderfer-games/hub/daily` | `getDaily`, `DailySystem` |
+| `@diffenderfer-games/hub/race`, `/social`, `/mp`, `/rooms` | one namespace each (`race`, `social` with `presence` and `notify`, `mp`, `rooms`) |
+| `@diffenderfer-games/hub/types` | type-only: every contract type (requests, replies, entities, error codes, socket ops and events, the `game.*` manifest) |
+| `@diffenderfer-games/hub/auto` | everything above, and it sets `window.HubSDK` (what `/_hub/hub.js` is built from) |
+
+The namespaces also hang off `hub` (`hub.input`, `hub.daily`, `hub.race`,
+`hub.social`, `hub.presence`, `hub.notify`, `hub.mp`, `hub.rooms`,
+`hub.overlay`, `hub.menu`), created on first use.
+
+## Errors
+
+Every call rejects with a `HubError` when it fails. `status` is the HTTP
+status, or `undefined` when the hub could not be reached (`isOffline`).
+`code`, `reason`, `hint` and `retryAfterMs` come from the hub's error body.
+
+- `ContentRejectedError`: the safety filter refused some text (HTTP 422).
+  Keep the player's draft and show `hint`.
+- `OfflineError`: an action that needs the hub was tried offline.
+- `code: 'unsupported_by_hub'`: the hub does not have this call yet (the game
+  uses a newer client than the deployed hub). Deploy the hub first.
+
+The analytics calls (`recordPlay`, `heartbeat`, `event`) never throw.
+
+## Offline
+
+With `offline: 'auto'` (the default), reads fall back to a cache in
+`localStorage` when the hub can't be reached, and writes (saves, stats,
+scores, profile, daily completions, inventory grants and exchanges, stars)
+apply to the cache at once and are queued in an outbox. The outbox replays
+in order when the connection returns (and after a reload), one tab at a
+time, and the hub applies each replayed call once. `hub.sync()` replays it
+on demand, `hub.pending()` counts what waits, and `hub.onStatus(listener)`
+reports changes. `hub.prefetchAll()` warms the cache for every game in one
+request. `offline: 'always'` never touches the network (develop without a
+hub); `offline: 'never'` always throws instead.
+
+Queue your own operations, with a handler that may make several dependent
+calls:
+
+```ts
+hub.offline.define<{ score: number }>('my-game.finish', async (run, context) => {
+  const { rank } = await context.call('submitScore', { slug: 'my-game', key: 'runs', score: run.score });
+  await context.call('updateGameStat', { slug: 'my-game', key: 'best-rank', value: rank ?? 0, mode: 'max' });
+});
+hub.offline.enqueue('my-game.finish', { score: 4200 });
+hub.offline.on('failed', ({ op, error }) => console.warn(op.kind, error));
+```
+
+The full rules (what replays, ordering, retries, the size cap) are in the
+hub docs' "Offline and replay" section. The cache keeps the old vendored
+client's `localStorage` keys, and its queue moves into the outbox, so a game
+that switches to this package keeps its players' queued progress.
+
+## Games without a build step
+
+Keep `import('/_hub/hub.js')` or `window.HubSDK.hub`: the host serves a
+bundle of this package's `./auto` entry, at the version the host was built
+with. Install the package as a dev dependency only if you want editor types:
+
+```js
+/** @type {import('@diffenderfer-games/hub').Hub} */
+const hub = window.HubSDK.hub;
+```
+
+## Sharing the page with the host's `/_hub/hub.js`
+
+Every game page also gets the host's menu and social runtime, which use the
+host's own copy of this client (`/_hub/hub.js`, built from the version the host
+was deployed with). Your bundled copy and the host's cooperate. The page-wide
+pieces (the input system, daily challenges, the realtime API) are registered
+once on `window.__DG__`, each with the version that created it:
+
+- **Same shape** (the usual case): the first one wins and both copies share
+  it, so an older patch version on either side is harmless.
+- **A different shape** (a major change): your game's copy owns input and
+  daily; the host's runtime owns realtime. The mismatch is logged once in the
+  console with the fix: `npm update @diffenderfer-games/hub`.
+- **A v1 vendored copy** already on the page is shared too, and recorded as
+  `{ version: 'v1' }`.
+
+The v1 globals (`window.__HUB_INPUT__`, `__HUB_DAILY__`, `__HUB_RT__`) stay as
+aliases. Don't create your own singletons; `hub.input`, `hub.daily` and the
+forwarders always return the shared ones.
+
+## Versions
+
+The client sends its version as `x-hub-client`. `hub.hubVersion()` reads the
+hub's `GET /_api/version` (`{ server, contract, supported, deprecated }`) once
+per page, and `hub.clientSupport()` says whether this client is `supported`,
+`deprecated` or `unsupported` (`unknown` on a hub from before versioning).
+
+The hub supports the current major and the previous one. Update with
+`npm update @diffenderfer-games/hub`.
+
+## hub-doctor
+
+Run it in a game's folder, in CI and before pushing:
+
+```sh
+npx hub-doctor                 # checks against https://diffenderfer.games
+npx hub-doctor --offline       # skip the version check
+npx hub-doctor --timeout 5000  # wait at most 5 s for the hub (default 10 s)
+npx hub-doctor --hub http://localhost:8080 --dir ../my-game --json
+```
+
+An unreachable or slow hub is an error (`hub unreachable at <url> (...)`) and
+exits non-zero, so CI notices. Use `--offline` where CI has no network.
+
+It fails when the installed client is outside the hub's `supported` range or
+the `package.json` `game.*` block does not match the manifest schema, and it
+warns when the client is deprecated or a vendored `src/hub/` copy (or
+`scripts/sync-hub.mjs`) is still around.
+
+## Testing your game against the hub
+
+The hub's test kit lives in the host repo (`test/helpers/`). Point your
+game's tests at a checkout of it with `DG_HOST`; the default is
+`../diffenderfer-games`. It boots a real hub on a free port for each test
+file (the same hub and host production runs):
+
+```sh
+DG_HOST=../diffenderfer-games npm run test:hub
+```
+
+The checkout needs `npm ci` at its root.
+
+## Moving from the vendored copy
+
+1. `npm install @diffenderfer-games/hub`.
+2. Change `from './hub/hub'` (or `'./hub'`) to `from '@diffenderfer-games/hub'`.
+3. Delete `src/hub/` and `scripts/sync-hub.mjs`.
+4. Add `npx hub-doctor` to the game's CI.
+
+Every method name is unchanged.
+
+## License
+
+MIT