@joystyk/launcher 0.0.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# @joystyk/launcher
+
+## 0.2.0
+
+### Minor Changes
+
+- bb095c7: Add shared real-time input, pause, pace records and ghost races, plus a WebGL 2 renderer
+  lifecycle with context recovery and adaptive quality. Launch daily fixed-step simulations
+  from published configs and retain their puzzle identity through saved games.
+
+### Patch Changes
+
+- Updated dependencies [bb095c7]
+- Updated dependencies [bb095c7]
+  - @joystyk/contracts@0.2.0
+  - @joystyk/storage@0.2.0
+  - @joystyk/session@0.2.0
+  - @joystyk/daily@0.2.0
+  - @joystyk/identity@0.2.0
+  - @joystyk/kit@0.2.0
+  - @joystyk/ui@0.2.0
+
+## 0.1.0
+
+### Minor Changes
+
+- Prepare the first compiled library release: ESM and API declarations for every public entry point, runtime assets, and checks against installed npm tarballs. Games and applications remain private.
+
+### Patch Changes
+
+- Updated dependencies
+  - @joystyk/contracts@0.1.0
+  - @joystyk/kit@0.1.0
+  - @joystyk/storage@0.1.0
+  - @joystyk/identity@0.1.0
+  - @joystyk/session@0.1.0
+  - @joystyk/daily@0.1.0
+  - @joystyk/ui@0.1.0

package/README.md

@@ -1,5 +1,248 @@
 # @joystyk/launcher
 
-The first Joystyk library release is not yet available. This placeholder reserves the package name.
+The frame around a game (host policy). `<jy-launcher>` lets the player choose how to play, starts a
+local session or opens a server room, mounts the game's canvas, and draws the platform's own
+screens around it: the resume offer, the pass-and-play hand-off (host policy), the room lobby, the
+pause overlay with preferences, and the results with their ad slot. It talks to games only through the contracts in
+game-contract.md (Joystyk host reference) and never imports a game.
 
-Source: https://github.com/joystyk-games/game-libraries
+## npm package
+
+The first `0.1.0` release is being prepared; it has not been published. Once available:
+
+```sh
+npm install @joystyk/launcher
+```
+
+Node consumers require Node 24.15 or later. Browser entry points require a modern
+browser and should be loaded in the browser. Tested with Gyral 0.3.1.
+
+| Import | Format |
+| --- | --- |
+| `@joystyk/launcher` | ES module and TypeScript declarations |
+| `@joystyk/launcher/browser` | ES module and TypeScript declarations |
+| `@joystyk/launcher/fixture` | ES module and TypeScript declarations |
+| `@joystyk/launcher/report` | ES module and TypeScript declarations |
+
+Only the entries listed above are public API. Installed packages contain compiled ESM,
+type declarations and runtime assets. Repository-relative links describe the Joystyk
+workspace and are not needed to use the npm package.
+
+## Entry points
+
+| Import | Runs in | Contents |
+| --- | --- | --- |
+| `@joystyk/launcher` | Server and browser | `<jy-launcher>` (server-rendered), its pure model, the safe-point event |
+| `@joystyk/launcher/browser` | Browser | `createLauncherServices`, `provideLauncherServices`, `watchSafePoints`, `requestSave` |
+| `@joystyk/launcher/fixture` | Tests | Tally, a tiny test game, and `tallyProbe` |
+
+The stage element (`<jy-game-stage>`), the session runners, storage and identity load on
+the first Start, so a game page that nobody plays never downloads them.
+
+## Use
+
+A page renders the launcher with what its game page knows about the game:
+
+```ts
+html`<jy-launcher .game=${{ id, name, modes, players, aiLevels, status, aiContent }}></jy-launcher>`;
+```
+
+`players` is `{ min, max }`, plus the manifest's optional `default`: against the computer
+the Players picker starts at that count, and otherwise at the fewest.
+
+The app provides the games it can load, once per page (platform packages never import a
+game, so the list comes from the app; `apps/site/src/game-loaders.ts` builds it):
+
+```ts
+import { createLauncherServices, provideLauncherServices } from '@joystyk/launcher/browser';
+
+provideLauncherServices(document, createLauncherServices({
+  games: { nim: { entry: () => import('@joystyk/game-nim').then((m) => m.entry) } },
+}));
+```
+
+A loader may also give `aiWorker: () => new Worker(…)` for a manifest with `ai.heavy`; the
+local runner then chooses AI moves in that worker (`workerAiRunner`). A game whose engine
+requests jobs that local play may run gives `jobWorker: (kind) => new Worker(…)`; the runner
+then performs each job in a fresh worker (`workerJobRunner`). Greed's dice throws work this
+way, with the factory from `@joystyk/game-greed/jobs`.
+
+Without JavaScript the setup form still renders, with a disabled Start button and the line
+"JavaScript is needed to play".
+
+## How a game starts
+
+1. **Setup.** The modes come from the manifest. Solo, vs AI (with a level), pass-and-play
+   (with seat names, checked by `@joystyk/identity`'s name filter) and, for a manifest that
+   lists `daily`, the daily puzzle are playable; P2P rooms show as coming soon (host policy). Solo,
+   vs-AI and daily play seat the guest under their display name. In pass-and-play the count is
+   people: a game with AI and more seats than people (Hearts and Spades seat four) lets two or
+   more share the device, and the computer plays the other seats at the chosen level
+   (`computerSeatsFor`). Online with friends is
+   playable only for a game the room server hosts: once live, a launcher whose manifest lists
+   `server` asks `GET /api/rooms/games` (the `launcher-online-rooms` driver) and reads an
+   invite after the answer. A game the server doesn't host shows online play as coming soon
+   (host policy); while it asks, the option waits without a note; and when the server can't be
+   reached (an error, a page that isn't the answer, or 10 seconds of silence) it shows as
+   "Unavailable right now". The local modes never wait for it. The answer holds for the page,
+   so client navigation to another game reuses it.
+2. **Loading.** `<jy-game-stage>` loads the entry through the app's loader, checks that the
+   manifest allows the mode and that the access gate is open (always, until premium access
+   in v2), loads the module, opens the player's storage and reads their preferences.
+3. **AI-made content (host policy).** A manifest with `aiContent: true` stays locked until the
+   player accepts a short notice. The answer is a preference (`aiContentAccepted`), stored
+   once per device and changeable in the overlay. Such a game's results and pause menu carry
+   `<jy-report-problem>` (*Report a problem*, host policy): a reason from a fixed list and an
+   optional note, posted to the site's `POST /api/reports` with the game and, for a daily
+   puzzle, its ID (the stage's `Puzzle` output). `@joystyk/launcher/report` holds the wire
+   constants the site shares.
+4. **Resume or new.** Each local mode has its own save slot. A save in progress is offered
+   for resuming; a finished one, one from older rules, or one the engine's `worthSaving`
+   rejects (an untouched game), is cleared. The slot's port lets the runner clear it too.
+5. **Playing.** The stage builds the session (`createLocalSession` for a Layer 2 engine,
+   `createFixedStepRunner` for a simulation, or the game's own `createSession`) and calls
+   `mount(canvas, session, platform)`.
+6. **Results.** At the outcome the stage clears the save slot, records stats and, if the
+   engine has a `rematch` hook, the config for "Play again". The launcher shows the outcome,
+   play time, any assistance (`Outcome.undosUsed` and `assists`), Play again, Change mode,
+   Back to all games, and the `results` ad slot, over the final board (see below). The
+   session is disposed only when the player picks Play again or Change mode, the game asks
+   to exit, or the page goes away.
+
+## Online with friends
+
+Server rooms (host policy), for any game whose manifest lists `server` and that the room server
+hosts:
+
+1. **Create or join.** "Create a room" asks the room server for a room (`POST /api/rooms`)
+   with the guest's display name; the creator holds seat 0 and hosts. Below it, a join form
+   takes a code or a pasted invite link, and "Just watch" joins as a spectator (host policy). A page
+   opened from an invite (`?room=CODE`) picks the mode and fills in the code; the player still
+   presses Join. A malformed code is refused in the form; an unknown one, or one for another
+   game, gets the stage's message.
+2. **Lobby.** The invite link (in a read-only field, with Copy link and Copy code) and the
+   code; the seats, each open, the computer at the room's level, or a player marked host, you,
+   ready or away; the spectator count; the turn clock. Everyone with a seat presses Ready
+   (`aria-pressed`). The host picks the clock, from the manifest's presets (the usual one
+   marked) or Off, which is never the default (host policy, host policy), and the computer's level; adds the
+   computer to an open seat or removes a seat; and starts once every seat is filled and
+   ready. The hint under Start says what it waits for. Leave room gives the seat up.
+3. **Play.** When the match starts the stage mounts the game on the remote session. The bar
+   shows the room code, the connection ("Connection lost. Reconnecting…"), and the running
+   turn clock (`role="timer"`). The menu doesn't pause a room ("The match goes on while this
+   menu is open") and offers Leave room. A newer tab taking the seat shows "Use this tab
+   instead". Hosts can't remove a player mid-match (host policy).
+4. **Results** show over the final board as for local play, worded for the viewer ("You
+   won!", "Ben wins", or "Ben wins!" for a spectator). The host's Rematch starts a new match
+   in the same room, on a fresh canvas; Leave room goes back to the setup.
+
+The stage reports the room after every change as a `Room` output (`RoomFrame`: plain data,
+checked at the boundary) and performs the lobby's requests (`StageControl.roomRequests`) in
+order. The room's code goes in the address bar while it is open (`history.replaceState`),
+so a reload or a shared address finds it again. `LauncherServices.rooms` (`RoomServices`) is
+how the stage reaches the room server; the default (`browser/rooms.ts`) uses the page's own
+origin, where Traefik routes `/api/rooms` and `/ws`, and tests pass a loopback.
+
+## The daily puzzle
+
+For a manifest that lists `daily` (host policy, content-pipeline.md (Joystyk host reference)):
+
+1. **After the notice.** The stage downloads nothing until the game may start: an AI-content
+   game's notice comes first (host policy).
+2. **Today's puzzle.** It asks `@joystyk/daily/browser`'s content client for today's UTC date
+   (`LauncherServices.daily`: the base URL, default `/daily`, a `fetch` and the wall clock).
+   The client revalidates the index, uses or refreshes the cached file and decodes `config`
+   with the engine's `schemas.config`; offline, a cached copy plays. With nothing to play, the
+   stage fails with the client's plain message ("This puzzle needs a connection…").
+3. **Played once.** If the results store already holds today's result, the launcher shows it
+   ("You've played today's puzzle") with the streak and share text, and mounts nothing.
+   Otherwise the game starts on the day's config (a resumed save finishes the puzzle it holds,
+   even after the next release, and its result counts for that puzzle's date).
+4. **Results.** At the outcome the stage records the `DailyResult` (with the engine's `share`
+   rows in both forms), reads the streaks and reports a `Daily` frame. The results show the
+   streak, the win streak for a daily that can be lost, "New puzzle at 8:00 PM (in 6 hours)"
+   in local time, the share preview, *Share* (Web Share, else the clipboard) and *Copy as
+   text*. There is no Play again; *Change mode* appears when the game has other modes.
+5. **Prefetch.** `dailyPrefetchers(services, gameIds)` gives the PWA's `registerPwa` one
+   prefetcher per daily game. It prefetches today and tomorrow through the same client and
+   storage, and nothing for an AI-content game until the notice is accepted.
+
+## What the game gets
+
+`mount` receives the canvas, a `<div>` in the stage's own shadow root (the frame's styles
+never reach it), and a `PlatformApi`:
+
+| Field | Source |
+| --- | --- |
+| `storage` | `@joystyk/storage`'s game storage, scoped to the game id and the player |
+| `preferences` | The stored preferences resolved against the system (reduced motion, sound and volume, single-key shortcuts, color scheme, locale), updated live when the player changes them in the overlay or the system setting changes |
+| `announce` | The launcher's polite and assertive live regions |
+| `requestExit` | Back to the setup, saving the game |
+
+**Theme handoff.** The canvas carries the manifest's theme as `--game-accent`,
+`--game-surface` and `--game-ink`, and the player's color scheme, which resolves any
+`light-dark()` pair; the frame keeps Joystyk's tokens. It paints the surface and sets its
+text color to the ink. A surface and its ink always follow the same scheme: a single surface
+without an ink gets near-black or near-white, whichever reads better (`readableInk`), and a
+game without a surface gets the frame's own surface and text. `canvasTheme` in `src/theme.ts`
+computes the tokens; the rules are in the
+game contract (Joystyk host reference) ("Theme").
+
+## The frame's screens
+
+- **Hand-off (host policy).** When the session publishes a `handoff`, the canvas is hidden and the
+  frame shows "Pass to <name>, then tap to reveal". Focus moves to the reveal button.
+- **Results over the final board.** The results open as a non-modal `<dialog>` laid over the
+  canvas, out of the flow, so neither the board nor the page moves; a board shorter than the
+  results scrolls them. The canvas stays mounted, dimmed and `inert` behind them. Focus moves
+  to the headline, which names the dialog. Escape or "Review the board" closes the results
+  and moves focus to the board, which can be read (and heard) again but not played: the
+  session refuses moves once the game is over. "Show results" in the bar reopens them, with
+  the same ad slot. The dialog is not modal because a modal one would make the page inert,
+  and the results are where the PWA may offer an update.
+- **Overlay.** The Menu button opens a modal `<dialog>`: Resume, Save and exit, and the
+  preferences. The dialog traps focus and closes on Escape; the session is paused while it
+  is open. Focus returns to the Menu button.
+- **Reduced motion.** The frame's own transitions stop when the system asks for reduced
+  motion, unless the player chose full motion, and always when the player chose to reduce
+  it. Games receive the resolved value and remove only decorative motion.
+
+## Safe points
+
+The launcher reports every change with a `joystyk:safe-point` event on the document
+(`{ safe, gameId }`). The page is safe outside play and on the results screen, open or closed; during play
+it is safe only when the session says so (`meta.safePoint`). The PWA listens with
+`watchSafePoints` and offers updates only when `safe` is true
+(offline-and-updates.md (Joystyk host reference), Rule 2).
+
+A forced security update can't wait for one, so it asks: `requestSave()` dispatches a
+`joystyk:save-request` event, and each game stage stops play (pausing a real-time game) and
+writes the current position through its save slot. The promise settles once every write has
+landed or failed, and at once when no game is in play. Rooms and Layer 1 games add nothing:
+the room server keeps a room's state, and those games save themselves.
+
+## Tests
+
+- `model.test.ts` and `launcher.test.ts`: the pure helpers and the component's model, with
+  `@gyral/testing`, in Node.
+- `theme.test.ts` and `theme.browser.test.ts`: the canvas theme tokens, the picked ink and
+  its CSS fallback.
+- `fixture/engine.test.ts`: the Tally fixture's rules.
+- `launcher.browser.test.ts`: the real stage, runner and storage (memory backend) in
+  Chromium: modes from the keyboard, mounting and disposal, theme tokens and readable canvas
+  text in light and dark, resume, the hand-off screen, rematch, the AI-content notice, the
+  overlay's focus trap and Escape, preferences and reduced motion, safe points, results over
+  the inert final board (Escape, Show results, no layout shift, disposal on Play again) and a
+  Layer 1 game.
+- `launcher.daily.browser.test.ts`: the daily mode with a fake `fetch` and a fixed clock:
+  nothing downloads before the notice, the published config plays, the results show the
+  streak and share text, a second visit shows today's result, offline with nothing cached says
+  so, and the prefetcher waits for the notice.
+- `launcher.rooms.browser.test.ts`: Online with friends in Chromium against the real room
+  core running in the page (`__tests__/loopback-room.ts`): create, invite, the computer in a
+  seat, ready, start, results, rematch and leave; a guest joining from an invite with a
+  spectator watching; malformed and unknown codes.
+- `apps/site`'s end-to-end tests play Tally and Nim through the launcher on the real server,
+  where no room server answers, so online play shows as unavailable; `rooms.e2e.test.ts`
+  plays Nim, Greed and Shift 23 rooms on the real site and room servers, and checks that a
+  game the room server doesn't host shows online play as coming soon.

package/dist/browser/daily-prefetch.d.ts

@@ -0,0 +1,8 @@
+import type { LauncherServices } from './services.js';
+/** What `registerPwa` takes for each daily game. */
+export type DailyPrefetch = {
+    readonly gameId: string;
+    prefetch(today: string): Promise<unknown>;
+};
+/** Prefetchers for the daily games among `gameIds` (games whose manifest lists `daily`). */
+export declare const dailyPrefetchers: (services: LauncherServices, gameIds: readonly string[]) => readonly DailyPrefetch[];

package/dist/browser/daily-prefetch.js

@@ -0,0 +1,32 @@
+//#region src/browser/daily-prefetch.ts
+/** Prefetchers for the daily games among `gameIds` (games whose manifest lists `daily`). */
+var dailyPrefetchers = (services, gameIds) => gameIds.map((gameId) => ({
+	gameId,
+	prefetch: async (today) => {
+		const loader = services.games[gameId];
+		if (loader === void 0) return null;
+		const entry = await loader.entry();
+		if (!entry.manifest.modes.includes("daily")) return null;
+		const player = await services.openPlayer();
+		if (player.device === void 0) return null;
+		if (entry.manifest.aiContent === true) {
+			const preferences = await player.storage.preferences.get();
+			if (!preferences.ok || preferences.value.aiContentAccepted !== true) return null;
+		}
+		const module = await entry.load();
+		const rules = module.engine ?? module.simulation;
+		if (rules === void 0) return null;
+		const { createDailyClient } = await import("@joystyk/daily/browser");
+		return createDailyClient({
+			baseUrl: services.daily?.baseUrl ?? "/daily",
+			gameId,
+			config: rules.schemas.config,
+			storage: player.device,
+			...services.daily?.fetch === void 0 ? {} : { fetch: services.daily.fetch }
+		}).prefetch(today);
+	}
+}));
+//#endregion
+export { dailyPrefetchers };
+
+//# sourceMappingURL=daily-prefetch.js.map

package/dist/browser/daily-prefetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"daily-prefetch.js","names":[],"sources":["../../src/browser/daily-prefetch.ts"],"sourcesContent":["// Daily prefetching for the PWA (D-46, content-pipeline.md, \"Prefetching for offline play\"):\n// one prefetcher per daily game, which the app hands to `registerPwa`. The PWA decides when\n// (at a safe point, while idle and online) and for whom (an installed app, or a pinned game);\n// this decides how: through the same storage, player and content client the daily mode plays\n// from, so a prefetched day plays offline. An AI-content game prefetches nothing until the\n// player has accepted the notice (D-44). Everything loads lazily, on the first prefetch.\nimport type { Validator } from '@joystyk/contracts';\nimport type { LauncherServices } from './services.ts';\n\n/** What `registerPwa` takes for each daily game. */\nexport type DailyPrefetch = {\n  readonly gameId: string;\n  prefetch(today: string): Promise<unknown>;\n};\n\n/** Prefetchers for the daily games among `gameIds` (games whose manifest lists `daily`). */\nexport const dailyPrefetchers = (services: LauncherServices, gameIds: readonly string[]): readonly DailyPrefetch[] =>\n  gameIds.map((gameId) => ({\n    gameId,\n    prefetch: async (today: string) => {\n      const loader = services.games[gameId];\n      if (loader === undefined) return null;\n      const entry = await loader.entry();\n      if (!entry.manifest.modes.includes('daily')) return null;\n      const player = await services.openPlayer();\n      if (player.device === undefined) return null;\n      if (entry.manifest.aiContent === true) {\n        const preferences = await player.storage.preferences.get();\n        if (!preferences.ok || preferences.value.aiContentAccepted !== true) return null;\n      }\n      const module = await entry.load();\n      const rules = module.engine ?? module.simulation;\n      if (rules === undefined) return null;\n      const { createDailyClient } = await import('@joystyk/daily/browser');\n      const client = createDailyClient({\n        baseUrl: services.daily?.baseUrl ?? '/daily',\n        gameId,\n        config: rules.schemas.config as Validator<unknown>,\n        storage: player.device,\n        ...(services.daily?.fetch === undefined ? {} : { fetch: services.daily.fetch }),\n      });\n      return client.prefetch(today);\n    },\n  }));\n"],"mappings":";;AAgBA,IAAa,oBAAoB,UAA4B,YAC3D,QAAQ,KAAK,YAAY;CACvB;CACA,UAAU,OAAO,UAAkB;EACjC,MAAM,SAAS,SAAS,MAAM;EAC9B,IAAI,WAAW,KAAA,GAAW,OAAO;EACjC,MAAM,QAAQ,MAAM,OAAO,MAAM;EACjC,IAAI,CAAC,MAAM,SAAS,MAAM,SAAS,OAAO,GAAG,OAAO;EACpD,MAAM,SAAS,MAAM,SAAS,WAAW;EACzC,IAAI,OAAO,WAAW,KAAA,GAAW,OAAO;EACxC,IAAI,MAAM,SAAS,cAAc,MAAM;GACrC,MAAM,cAAc,MAAM,OAAO,QAAQ,YAAY,IAAI;GACzD,IAAI,CAAC,YAAY,MAAM,YAAY,MAAM,sBAAsB,MAAM,OAAO;EAC9E;EACA,MAAM,SAAS,MAAM,MAAM,KAAK;EAChC,MAAM,QAAQ,OAAO,UAAU,OAAO;EACtC,IAAI,UAAU,KAAA,GAAW,OAAO;EAChC,MAAM,EAAE,sBAAsB,MAAM,OAAO;EAQ3C,OAPe,kBAAkB;GAC/B,SAAS,SAAS,OAAO,WAAW;GACpC;GACA,QAAQ,MAAM,QAAQ;GACtB,SAAS,OAAO;GAChB,GAAI,SAAS,OAAO,UAAU,KAAA,IAAY,CAAC,IAAI,EAAE,OAAO,SAAS,MAAM,MAAM;EAC/E,CACO,CAAA,CAAO,SAAS,KAAK;CAC9B;AACF,EAAE"}

package/dist/browser/index.d.ts

@@ -0,0 +1,3 @@
+export { createLauncherServices, cryptoSeed, findLauncherServices, mediaSystem, provideLauncherServices, type DailyServices, type GameLoader, type GameLoaders, type LauncherServiceOptions, type LauncherServices, type PlayerContext, type RoomAnswer, type RoomServices, type RunnerPorts, type SystemSource, } from './services.js';
+export { dailyPrefetchers, type DailyPrefetch } from './daily-prefetch.js';
+export { requestSave, SAFE_POINT_EVENT, SAVE_REQUEST_EVENT, watchSafePoints, type SafePointDetail, type SaveRequestDetail, } from '../safe-point.js';

package/dist/browser/index.js

@@ -0,0 +1,4 @@
+import { dailyPrefetchers } from "./daily-prefetch.js";
+import { createLauncherServices, cryptoSeed, findLauncherServices, mediaSystem, provideLauncherServices } from "./services.js";
+import { SAFE_POINT_EVENT, SAVE_REQUEST_EVENT, requestSave, watchSafePoints } from "../safe-point.js";
+export { SAFE_POINT_EVENT, SAVE_REQUEST_EVENT, createLauncherServices, cryptoSeed, dailyPrefetchers, findLauncherServices, mediaSystem, provideLauncherServices, requestSave, watchSafePoints };

package/dist/browser/rooms.d.ts

@@ -0,0 +1,2 @@
+import type { RoomServices } from './services.js';
+export declare const pageRooms: (page?: Location) => RoomServices;

package/dist/browser/rooms.js

@@ -0,0 +1,49 @@
+import { browserSocket, createRoom, fetchRoomInfo, randomActionId, roomsSocketUrl, webStorageTokens } from "@joystyk/session/browser/rooms";
+//#region src/browser/rooms.ts
+var pageRooms = (page = location) => {
+	const origin = page.origin;
+	return {
+		create: async (gameId, name) => {
+			const created = await createRoom(origin, {
+				game: gameId,
+				name
+			});
+			if (!created.ok) return {
+				ok: false,
+				message: created.error.message
+			};
+			return {
+				ok: true,
+				value: {
+					room: created.value.room,
+					token: created.value.token,
+					notice: created.value.notice?.message ?? null
+				}
+			};
+		},
+		find: async (code) => {
+			const found = await fetchRoomInfo(origin, code);
+			return found.ok ? {
+				ok: true,
+				value: { gameId: found.value.game.id }
+			} : {
+				ok: false,
+				message: found.error.message
+			};
+		},
+		connect: browserSocket(roomsSocketUrl(origin)),
+		tokens: webStorageTokens(),
+		actionId: randomActionId,
+		inviteLink: (code) => {
+			const url = new URL(page.href);
+			url.hash = "";
+			url.search = "";
+			url.searchParams.set("room", code);
+			return url.href;
+		}
+	};
+};
+//#endregion
+export { pageRooms };
+
+//# sourceMappingURL=rooms.js.map

package/dist/browser/rooms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rooms.js","names":[],"sources":["../../src/browser/rooms.ts"],"sourcesContent":["// The default room services: the room server on this page's own origin. In production\n// Traefik routes `/api/rooms` and `/ws` on the site's host to the room service (DEPLOY.md);\n// in development the site's dev server forwards them to a local apps/rooms. Loaded with the\n// stage, so a page nobody plays never fetches the protocol's schemas.\nimport {\n  browserSocket,\n  createRoom,\n  fetchRoomInfo,\n  randomActionId,\n  roomsSocketUrl,\n  webStorageTokens,\n} from '@joystyk/session/browser/rooms';\nimport type { RoomServices } from './services.ts';\n\nexport const pageRooms = (page: Location = location): RoomServices => {\n  const origin = page.origin;\n  return {\n    create: async (gameId, name) => {\n      const created = await createRoom(origin, { game: gameId, name });\n      if (!created.ok) return { ok: false, message: created.error.message };\n      return {\n        ok: true,\n        value: { room: created.value.room, token: created.value.token, notice: created.value.notice?.message ?? null },\n      };\n    },\n    find: async (code) => {\n      const found = await fetchRoomInfo(origin, code);\n      return found.ok\n        ? { ok: true, value: { gameId: found.value.game.id } }\n        : { ok: false, message: found.error.message };\n    },\n    connect: browserSocket(roomsSocketUrl(origin)),\n    tokens: webStorageTokens(),\n    actionId: randomActionId,\n    inviteLink: (code) => {\n      const url = new URL(page.href);\n      url.hash = '';\n      url.search = '';\n      url.searchParams.set('room', code);\n      return url.href;\n    },\n  };\n};\n"],"mappings":";;AAcA,IAAa,aAAa,OAAiB,aAA2B;CACpE,MAAM,SAAS,KAAK;CACpB,OAAO;EACL,QAAQ,OAAO,QAAQ,SAAS;GAC9B,MAAM,UAAU,MAAM,WAAW,QAAQ;IAAE,MAAM;IAAQ;GAAK,CAAC;GAC/D,IAAI,CAAC,QAAQ,IAAI,OAAO;IAAE,IAAI;IAAO,SAAS,QAAQ,MAAM;GAAQ;GACpE,OAAO;IACL,IAAI;IACJ,OAAO;KAAE,MAAM,QAAQ,MAAM;KAAM,OAAO,QAAQ,MAAM;KAAO,QAAQ,QAAQ,MAAM,QAAQ,WAAW;IAAK;GAC/G;EACF;EACA,MAAM,OAAO,SAAS;GACpB,MAAM,QAAQ,MAAM,cAAc,QAAQ,IAAI;GAC9C,OAAO,MAAM,KACT;IAAE,IAAI;IAAM,OAAO,EAAE,QAAQ,MAAM,MAAM,KAAK,GAAG;GAAE,IACnD;IAAE,IAAI;IAAO,SAAS,MAAM,MAAM;GAAQ;EAChD;EACA,SAAS,cAAc,eAAe,MAAM,CAAC;EAC7C,QAAQ,iBAAiB;EACzB,UAAU;EACV,aAAa,SAAS;GACpB,MAAM,MAAM,IAAI,IAAI,KAAK,IAAI;GAC7B,IAAI,OAAO;GACX,IAAI,SAAS;GACb,IAAI,aAAa,IAAI,QAAQ,IAAI;GACjC,OAAO,IAAI;EACb;CACF;AACF"}

package/dist/browser/services.d.ts

@@ -0,0 +1,127 @@
+import type { GameEntry, RngState } from '@joystyk/contracts';
+import type { Clock, FrameScheduler, Reporter, SocketFactory, TokenStore, Visibility } from '@joystyk/session';
+import type { PlayerStorage, Storage, StorageNotice, SystemEnvironment } from '@joystyk/storage';
+/** How the app loads one game: its entry, and a worker for heavy AI if the game has one. */
+export type GameLoader = {
+    /** The game's `entry.ts` (manifest plus lazy loaders), usually a dynamic import. */
+    readonly entry: () => Promise<GameEntry<HTMLElement>>;
+    /**
+     * For a manifest with `ai.heavy`: a worker running the game's `jobs/ai.worker.ts`
+     * (`new Worker(new URL(…, import.meta.url), { type: 'module' })`). Without it the runner
+     * plays heavy AI inline and reports it.
+     */
+    readonly aiWorker?: () => Worker;
+    /**
+     * For an engine that requests jobs a local game may run (`where: 'either'`, such as Greed's
+     * throws): a fresh worker for one job of `kind`, running the game's `jobs/<kind>.worker.ts`.
+     * Without it the runner fails those jobs, and the engine decides what that means.
+     */
+    readonly jobWorker?: (kind: string) => Worker;
+};
+/** The games a page can launch, by id. */
+export type GameLoaders = Readonly<Record<string, GameLoader>>;
+/** The guest, with their storage. */
+export type PlayerContext = {
+    readonly playerId: string;
+    readonly displayName: string;
+    readonly storage: PlayerStorage;
+    /** The device's storage, which the daily puzzle's content cache and results use (`@joystyk/daily/browser`). */
+    readonly device?: Storage;
+};
+/**
+ * Where the daily mode finds published puzzles, and the wall clock that says which UTC day it
+ * is (D-46). Tests pass a fake `fetch` and a fixed clock.
+ */
+export type DailyServices = {
+    /** Default "/daily", the site's published-content path (content-pipeline.md, "Delivery"). */
+    readonly baseUrl?: string;
+    readonly fetch?: (url: string, init?: RequestInit) => Promise<Response>;
+    /** Epoch milliseconds. Default `Date.now`. */
+    readonly now?: () => number;
+};
+/** The system settings `resolvePreferences` falls back on, now and on change. */
+export interface SystemSource {
+    get(): SystemEnvironment;
+    subscribe(listener: (environment: SystemEnvironment) => void): () => void;
+}
+/** A room server answer: the value, or why not, worded for players. */
+export type RoomAnswer<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * How the stage reaches the room server (D-48). The default (`browser/rooms.ts`, loaded with
+ * the stage) uses this page's origin, where Traefik routes `/api/rooms` and `/ws` to the room
+ * service; tests pass their own.
+ */
+export interface RoomServices {
+    /** `POST /api/rooms`: a new room with the creator in seat 0, and a notice when the name was replaced. */
+    create(gameId: string, name: string): Promise<RoomAnswer<{
+        readonly room: string;
+        readonly token: string;
+        readonly notice: string | null;
+    }>>;
+    /** `GET /api/rooms/:code`: which game the room plays. */
+    find(code: string): Promise<RoomAnswer<{
+        readonly gameId: string;
+    }>>;
+    readonly connect: SocketFactory;
+    readonly tokens: TokenStore;
+    /** A fresh action ID: 8–40 URL-safe characters. */
+    actionId(): string;
+    /** The invite link: this game page with `?room=CODE`. */
+    inviteLink(code: string): string;
+}
+export type RunnerPorts = {
+    readonly clock: Clock;
+    readonly visibility: Visibility;
+    readonly frames: FrameScheduler;
+    readonly report: Reporter;
+};
+export interface LauncherServices {
+    readonly games: GameLoaders;
+    /** Opens storage and the guest identity; the same promise every time. */
+    openPlayer(): Promise<PlayerContext>;
+    readonly system: SystemSource;
+    readonly ports: RunnerPorts;
+    /** A fresh, unpredictable seed for a new game (and, separately, its AI). */
+    newSeed(): RngState;
+    /** Storage problems worded for players (a full disk, private browsing). Returns how to stop. */
+    onNotice(listener: (message: string) => void): () => void;
+    /** The pause before an inline AI moves, so players can follow. Default 500 ms. */
+    readonly aiDelayMs?: number;
+    /** Deep-freeze snapshots (development). Default true. */
+    readonly freeze?: boolean;
+    /** The room server for Online with friends. Default: this page's origin. */
+    readonly rooms?: RoomServices;
+    /** The daily puzzle's content and clock. Default: this page's `/daily/` and the device clock. */
+    readonly daily?: DailyServices;
+}
+/** Makes `services` available to every launcher below `target` (the document, or a test container). */
+export declare const provideLauncherServices: (target: Node, services: LauncherServices) => (() => void);
+/** The services of the nearest provider above `from`, crossing shadow roots, or null. */
+export declare const findLauncherServices: (from: Node) => LauncherServices | null;
+/** The system settings from media queries, following changes. */
+export declare const mediaSystem: (view?: Window) => SystemSource;
+/** A seed from 128 bits of the browser's cryptographic randomness. */
+export declare const cryptoSeed: () => RngState;
+export type LauncherServiceOptions = {
+    readonly games: GameLoaders;
+    /** Opens storage. Default: IndexedDB (`openBrowserStorage`), falling back to memory. */
+    readonly openStorage?: (onNotice: (notice: StorageNotice) => void) => Promise<Storage>;
+    readonly system?: SystemSource;
+    readonly ports?: Partial<RunnerPorts>;
+    readonly newSeed?: () => RngState;
+    readonly aiDelayMs?: number;
+    readonly freeze?: boolean;
+    readonly rooms?: RoomServices;
+    readonly daily?: DailyServices;
+};
+/**
+ * The page's services. Storage and identity open on the first game, not on page load, and
+ * their code loads then too.
+ */
+export declare const createLauncherServices: (options: LauncherServiceOptions) => LauncherServices;

package/dist/browser/services.js

@@ -0,0 +1,95 @@
+import { seedState } from "@joystyk/kit/rng";
+import { browserPorts } from "@joystyk/session/browser";
+//#region src/browser/services.ts
+var provided = /* @__PURE__ */ new WeakMap();
+/** Makes `services` available to every launcher below `target` (the document, or a test container). */
+var provideLauncherServices = (target, services) => {
+	provided.set(target, services);
+	return () => {
+		if (provided.get(target) === services) provided.delete(target);
+	};
+};
+/** The services of the nearest provider above `from`, crossing shadow roots, or null. */
+var findLauncherServices = (from) => {
+	let node = from;
+	while (node !== null) {
+		const found = provided.get(node);
+		if (found !== void 0) return found;
+		node = node.parentNode ?? (node instanceof ShadowRoot ? node.host : null);
+	}
+	return null;
+};
+/** The system settings from media queries, following changes. */
+var mediaSystem = (view = window) => {
+	const motion = view.matchMedia("(prefers-reduced-motion: reduce)");
+	const dark = view.matchMedia("(prefers-color-scheme: dark)");
+	const get = () => ({
+		prefersReducedMotion: motion.matches,
+		prefersDark: dark.matches,
+		locale: view.navigator.language
+	});
+	return {
+		get,
+		subscribe: (listener) => {
+			const onChange = () => listener(get());
+			motion.addEventListener("change", onChange);
+			dark.addEventListener("change", onChange);
+			return () => {
+				motion.removeEventListener("change", onChange);
+				dark.removeEventListener("change", onChange);
+			};
+		}
+	};
+};
+/** A seed from 128 bits of the browser's cryptographic randomness. */
+var cryptoSeed = () => seedState(crypto.randomUUID());
+/**
+* The page's services. Storage and identity open on the first game, not on page load, and
+* their code loads then too.
+*/
+var createLauncherServices = (options) => {
+	const listeners = /* @__PURE__ */ new Set();
+	const notify = (notice) => {
+		for (const listener of [...listeners]) listener(notice.message);
+	};
+	let player = null;
+	const openPlayer = async () => {
+		const storage = await (options.openStorage ?? (async (onNotice) => (await import("@joystyk/storage/browser")).openBrowserStorage({ onNotice })))(notify);
+		const { createBrowserIdentity } = await import("@joystyk/identity/browser");
+		const profile = await createBrowserIdentity(storage).current();
+		return {
+			playerId: profile.id,
+			displayName: profile.displayName,
+			storage: storage.player(profile.id),
+			device: storage
+		};
+	};
+	return {
+		games: options.games,
+		openPlayer: () => {
+			player ??= openPlayer().catch((error) => {
+				player = null;
+				throw error;
+			});
+			return player;
+		},
+		system: options.system ?? mediaSystem(),
+		ports: {
+			...browserPorts(),
+			...options.ports
+		},
+		newSeed: options.newSeed ?? cryptoSeed,
+		onNotice: (listener) => {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		},
+		...options.aiDelayMs === void 0 ? {} : { aiDelayMs: options.aiDelayMs },
+		...options.freeze === void 0 ? {} : { freeze: options.freeze },
+		...options.rooms === void 0 ? {} : { rooms: options.rooms },
+		...options.daily === void 0 ? {} : { daily: options.daily }
+	};
+};
+//#endregion
+export { createLauncherServices, cryptoSeed, findLauncherServices, mediaSystem, provideLauncherServices };
+
+//# sourceMappingURL=services.js.map