@moku-labs/game 0.2.0 → 0.3.0

package/dist/{runtime-Bn5TXNxP.d.mts → runtime-Bhu442L8.d.mts}

@@ -1,4 +1,4 @@
-import { a as JsxChild, m as UiIntrinsicElements, t as DescriptionNode } from "./types-X9jXjka3.mjs";
+import { a as JsxChild, m as UiIntrinsicElements, t as DescriptionNode } from "./types-VErbiEXy.mjs";
 
 //#region src/plugins/ui/jsx/runtime.d.ts
 /** What the compiler passes as props: the children plus whatever the tag declared. */

package/dist/{runtime-DRlwxkIv.mjs → runtime-CBZgWgzx.mjs}

@@ -1,60 +1,4 @@
-import { n as isComponentDefinition } from "./component-DGg5DqKK.mjs";
-//#region src/plugins/ui/jsx/flatten.ts
-/** The type of the node `Fragment` builds. It never reaches a reconcile: `flatten` lifts it. */
-const FRAGMENT = "#fragment";
-/**
-* Builds the node a bare string or number child becomes.
-*
-* @param content - What stood between the tags.
-* @returns A text node carrying it.
-* @example
-* ```ts
-* textNode(5); // { type: "text", props: { content: "5" }, children: [] }
-* ```
-*/
-function textNode(content) {
-	return {
-		type: "text",
-		props: { content: String(content) },
-		children: []
-	};
-}
-/**
-* Tells a description node from the other things a child may be.
-*
-* @param child - One child of a tag.
-* @returns True when it is a node.
-* @example
-* ```ts
-* isNode({ type: "row", props: {}, children: [] }); // true
-* ```
-*/
-function isNode(child) {
-	return typeof child === "object" && child !== null && !Array.isArray(child) && "type" in child;
-}
-/**
-* Turns whatever stood between two tags into the children of that tag.
-*
-* @param child - One child, an array of children, or nothing.
-* @returns The children as nodes, fragments lifted and empty values dropped.
-* @example
-* ```ts
-* flatten(["a", undefined, 2]).map(node => node.props.content); // ["a", "2"]
-* ```
-*/
-function flatten(child) {
-	if (child === null || child === void 0 || typeof child === "boolean") return [];
-	if (typeof child === "string" || typeof child === "number") return [textNode(child)];
-	if (Array.isArray(child)) {
-		const nodes = [];
-		for (const item of child) nodes.push(...flatten(item));
-		return nodes;
-	}
-	if (!isNode(child)) return [];
-	if (child.type === "#fragment") return [...child.children];
-	return [child];
-}
-//#endregion
+import { i as isComponentDefinition, n as flatten, t as FRAGMENT } from "./flatten-BkXuscAV.mjs";
 //#region src/plugins/ui/jsx/runtime.ts
 /**
 * @file ui/jsx — the JSX runtime itself: the three factories a TypeScript build calls, the

package/dist/{sources-BooL2MsX.mjs → sources-C1uGjz4l.mjs}

@@ -1,5 +1,5 @@
-import { i as scaleByFits } from "./visual-NPrDkvUk.mjs";
-import { i as inputOrEmpty, n as isTainted, o as defineSource, t as cheatsOf } from "./session-DmAxY6Ll.mjs";
+import { i as scaleByFits, w as Layer } from "./visual-DUvvPPCt.mjs";
+import { c as defineSource, n as cheatsOf, o as readTarget, r as isTainted, t as inputOrEmpty } from "./input-CK4nxBO1.mjs";
 //#region src/plugins/flow/doors/read.ts
 /**
 * @file flow/doors — `read` and `watch`, the `/inspect` side. Neither changes the game.
@@ -171,9 +171,27 @@ const modelSource = defineSource({
 //#endregion
 //#region src/plugins/renderer/inspect.ts
 /**
-* @file renderer plugin — the renderer source of the `/inspect` door: the frame counters.
-* Production-safe: it only reads.
+* @file renderer plugin — the renderer sources of the `/inspect` door: the frame counters, and what
+* lies under a point of the page. Production-safe: both only read.
+*/
+/**
+* Names one entity under a point: its owner, the projection and key that address it, and the
+* layer its own `Layer` names.
+*
+* @param world - The world API.
+* @param entity - The entity hit.
+* @returns What lies there, or `undefined` for an entity that despawned this frame.
 */
+function underOf(world, entity) {
+	const owner = world.ecs.ownerOf(entity);
+	if (owner === void 0) return void 0;
+	return {
+		entity,
+		owner,
+		key: world.projection.keyOf(entity),
+		layer: world.ecs.get(entity, Layer)?.name
+	};
+}
 /**
 * The counters of the renderer: frames per second, frame work, GPU textures and their memory,
 * views and pooled display objects, render passes, and in a dev build the draw calls.
@@ -192,11 +210,44 @@ const renderSource = defineSource({
 	changes: "frame",
 	read: (app) => app.renderer.stats()
 });
+/**
+* What lies under a point of the page, topmost first: the point in client CSS pixels, the
+* coordinates `game.locate` answers and Playwright clicks, mapped through
+* `viewport.toReference`, and every view whose hit box holds it, with the skip rules of a tap.
+* `[]` while the renderer is inert and where nothing is drawn.
+*
+* @example
+* ```ts
+* // An agent asks what lies under the pointer on a 390 px wide phone: a shine over a board cell.
+* read(app, sources.at, { x: 195, y: 108.33 });
+* // [{ entity: 1048577, owner: { kind: "plugin", name: "fx" }, key: undefined, layer: undefined },
+* //  { entity: 1048576, owner: { kind: "projection", name: "board.items" },
+* //    key: { projection: "board.items", key: "c7" }, layer: "items" }]
+* ```
+*/
+const atSource = defineSource({
+	id: "game.at",
+	title: "Under a point",
+	input: {
+		x: "number",
+		y: "number"
+	},
+	changes: "frame",
+	read: (app, { x, y }) => {
+		const point = app.renderer.viewport.toReference(x, y);
+		const found = [];
+		for (const entity of app.renderer.sync.hitAll(point.x, point.y)) {
+			const under = underOf(app.world, entity);
+			if (under !== void 0) found.push(under);
+		}
+		return found;
+	}
+});
 //#endregion
 //#region src/plugins/ui/inspect.ts
 /**
-* @file ui plugin — the ui sources of the `/inspect` door: the live screen as data and the rect
-* of one element on the page. Production-safe: both only read.
+* @file ui plugin — the ui sources of the `/inspect` door: the live screen as data, and where an
+* element or a view is on the page. Production-safe: every one only reads.
 */
 /**
 * Finds a keyed node and the nodes above it.
@@ -253,6 +304,37 @@ function onPage(renderer, rect) {
 	};
 }
 /**
+* Where a live ui element is on the page: its layout box, scaled by every fitted element above
+* it, through the viewport.
+*
+* @param app - The app with ui and renderer.
+* @param key - The `key` prop of the element.
+* @returns The rect in CSS px, or `undefined` when no live element has the key.
+*/
+function locateKey(app, key) {
+	const chain = app.ui.find(key) !== void 0 ? chainTo(app.ui.tree(), key) : void 0;
+	return chain === void 0 ? void 0 : onPage(app.renderer, drawnRect(chain));
+}
+/**
+* Where a view is on the page: the box the renderer draws for the entity of its projection key,
+* through the viewport.
+*
+* @param app - The app with ui, renderer and world.
+* @param target - The projection key of the view.
+* @returns The rect in CSS px, or `undefined` when the view is not live or has no drawn box.
+*/
+function locateTarget(app, target) {
+	const entity = app.world.projection.entityOf(target.projection, target.key);
+	const bounds = entity === void 0 ? void 0 : app.renderer.sync.boundsOf(entity);
+	if (bounds === void 0) return void 0;
+	return onPage(app.renderer, {
+		x: bounds.x,
+		y: bounds.y,
+		w: bounds.width,
+		h: bounds.height
+	});
+}
+/**
 * The live screen as plain data: every root, every element with its natural rect, its style,
 * its state flags and the fit scale of a fitted one.
 *
@@ -270,32 +352,42 @@ const uiSource = defineSource({
 	read: (app) => app.ui.tree()
 });
 /**
-* Where an element is on the page, in CSS px: its layout box, so a bare button with no fill has
-* one, scaled by every fitted element above it, through the viewport. In reference units while
-* the renderer is inert.
+* Where something is on the page, in CSS px, by either of the two addresses the doors use: a ui
+* element by its `key` (its layout box, scaled by every fitted element above it, so a bare button
+* with no fill has one), or a view by its `target` projection key (the box the renderer draws for
+* it). Both go through the viewport, so the numbers are what Playwright clicks. In reference units
+* while the renderer is inert; a view has no drawn box then.
 *
 * @example
 * ```ts
 * // An e2e script clicks Home's Play plank on a 390 px wide phone.
-* read(app, sources.rect, { key: "play" }); // { x: 101.9, y: 469.2, w: 189.2, h: 54.6 }
-* read(app, sources.rect, { key: "nothing" }); // undefined: not on screen
+* read(app, sources.locate, { key: "play" }); // { x: 101.9, y: 469.2, w: 189.2, h: 54.6 }
+* // An agent finds the coin c7 before it drags it: 64 x 64 u, drawn at (540, 300).
+* read(app, sources.locate, { target: { projection: "board.items", key: "c7" } });
+* // { x: 183.4, y: 96.8, w: 23.1, h: 23.1 }; undefined while nothing draws it
 * ```
 */
-const rectSource = defineSource({
-	id: "game.rect",
-	title: "Element rect",
-	input: { key: "string" },
+const locateSource = defineSource({
+	id: "game.locate",
+	title: "Locate",
+	input: {
+		key: "string?",
+		target: "json?"
+	},
 	changes: "frame",
-	read: (app, { key }) => {
-		const chain = app.ui.find(key) !== void 0 ? chainTo(app.ui.tree(), key) : void 0;
-		return chain === void 0 ? void 0 : onPage(app.renderer, drawnRect(chain));
+	read: (app, { key, target }) => {
+		if (key !== void 0 && target === void 0) return locateKey(app, key);
+		if (target !== void 0 && key === void 0) return locateTarget(app, readTarget(target));
+		throw new Error("[game] game.locate takes a key or a target.\n  Pass exactly one of { key } and { target }.");
 	}
 });
 //#endregion
 //#region src/plugins/world/inspect.ts
 /**
 * @file world plugin — the world sources of the `/inspect` door: the entities, filtered by owner
-* and component, and the projection keys. Production-safe: every source only reads.
+* and component, the projection keys, one entity in full, what changed between two frames and
+* the component schema. Every source only reads; `game.diff` answers in a dev build only, because
+* only a dev build keeps the frame history.
 */
 /**
 * Tells whether an entity carries a component, as a JSON value or as a skipped one.
@@ -356,6 +448,87 @@ const projectionsSource = defineSource({
 		return keys;
 	}
 });
+/**
+* One entity in full: its owner, its projection key, every JSON component, the names of the
+* skipped ones and the components a motion still drives. `undefined` for a stale id. The source
+* reads the whole snapshot once per read and picks the row.
+*
+* @example
+* ```ts
+* // The editor explains item i7 while it slides to its new cell.
+* read(app, sources.explain, { entity: 1048577 });
+* // { id: 1048577, owner: { kind: "projection", name: "board.items" },
+* //   key: { projection: "board.items", key: "i7" },
+* //   components: { Transform: { x: 64, y: 0, rotation: 0, scale: 1, pivot: { x: 0, y: 0 } },
+* //     Layer: { name: "items" } }, skipped: [], motions: ["Transform"] }
+* read(app, sources.explain, { entity: 42 }); // undefined: a stale id
+* ```
+*/
+const explainSource = defineSource({
+	id: "game.explain",
+	title: "Entity",
+	input: { entity: "number" },
+	changes: "frame",
+	read: (app, { entity }) => {
+		const row = app.world.ecs.snapshot().entities.find((candidate) => candidate.id === entity);
+		if (row === void 0) return void 0;
+		return {
+			id: row.id,
+			owner: row.owner,
+			key: app.world.projection.keyOf(row.id),
+			components: row.components,
+			skipped: row.skipped,
+			motions: app.world.projection.motionsOf(row.id)
+		};
+	}
+});
+/**
+* What changed between the world at the end of frame `from` and at the end of frame `to`, from
+* the frame history of a dev build: one entry per entity, sorted by id. Throws in a production
+* build and for a frame outside the last 120.
+*
+* @example
+* ```ts
+* // The editor asks what the last second of play changed: item i7 merged up to level 3.
+* read(app, sources.diff, { from: 120, to: 180 });
+* // { from: 120, to: 180, entities: [{ id: 1048577,
+* //   owner: { kind: "projection", name: "board.items" },
+* //   key: { projection: "board.items", key: "i7" }, change: "changed",
+* //   components: { Level: { from: { level: 2 }, to: { level: 3 } } } }] }
+* ```
+*/
+const diffSource = defineSource({
+	id: "game.diff",
+	title: "Frame diff",
+	input: {
+		from: "number",
+		to: "number"
+	},
+	changes: "frame",
+	read: (app, { from, to }) => app.world.ecs.diff(from, to)
+});
+/**
+* Every component and tag type the world met so far, sorted by name, with the JSON kind of each
+* field: the editor's component palette. A system may write a new component on any frame, so it
+* is read again every frame.
+*
+* @example
+* ```ts
+* // The editor's component palette, in a world that has met Transform and the tag Held.
+* read(app, sources.schema);
+* // [{ name: "Held", kind: "tag", json: true, fields: {}, defaults: true, owned: [] },
+* //  { name: "Transform", kind: "component", json: true,
+* //    fields: { x: "number", y: "number", rotation: "number", scale: "number", pivot: "object" },
+* //    defaults: { x: 0, y: 0, rotation: 0, scale: 1, pivot: { x: 0, y: 0 } }, owned: [] }]
+* ```
+*/
+const schemaSource = defineSource({
+	id: "game.schema",
+	title: "Components",
+	input: {},
+	changes: "frame",
+	read: (app) => app.world.ecs.schema()
+});
 //#endregion
 //#region src/plugins/flow/inspect.ts
 /** The levels of `Log.LogLevel`, least severe first, as the names a caller passes. */
@@ -534,12 +707,16 @@ const sources = Object.freeze({
 	entities: entitiesSource,
 	projections: projectionsSource,
 	ui: uiSource,
-	rect: rectSource,
+	locate: locateSource,
 	render: renderSource,
 	sounds: soundsSource,
 	effects: effectsSource,
 	assets: assetsSource,
-	log: logSource
+	log: logSource,
+	explain: explainSource,
+	diff: diffSource,
+	schema: schemaSource,
+	at: atSource
 });
 //#endregion
 export { read as n, watch as r, sources as t };

package/dist/testing.d.mts

@@ -1,8 +1,8 @@
-import { At as Json, Dt as Api$2, Ft as PlayerStateProvider, It as ProviderCall, Lt as SaveDoc, Ut as Api$3, Zt as FakeClock, h as Api$1, t as Api } from "./types-BZ1OLf24.mjs";
-import { _ as stepFrames, a as InputOf, d as HeadlessApp, f as HeadlessGame, g as runRepro, h as createHeadless, m as ReproResult, p as Repro, r as ControlApp } from "./types-DmhTHRVW.mjs";
-import { H as InputApi } from "./types-X9jXjka3.mjs";
-import { A as UiApi, t as AnimApi } from "./types-CqkrEY06.mjs";
-import { t as commands } from "./commands-C0BljsM5.mjs";
+import { $t as SaveDoc, Kt as Json, Qt as ProviderCall, Ut as Api$2, Zt as PlayerStateProvider, an as Api$3, k as Api$1, m as Api, pn as FakeClock } from "./types-Dy1xB68L.mjs";
+import { _ as stepFrames, a as InputOf, d as HeadlessApp, f as HeadlessGame, g as runRepro, h as createHeadless, m as ReproResult, p as Repro, r as ControlApp } from "./types-DtmFVCHf.mjs";
+import { H as InputApi } from "./types-VErbiEXy.mjs";
+import { A as UiApi, t as AnimApi } from "./types-CVUHPvMB.mjs";
+import { t as commands } from "./commands-DYO22lzi.mjs";
 
 //#region src/plugins/clock/fake.d.ts
 /**

package/dist/testing.mjs

@@ -1,6 +1,6 @@
 import { n as saveOf, t as memory } from "./memory-CvgdnsQO.mjs";
-import { a as stepFrames, i as runRepro, n as commands, r as createHeadless, t as run } from "./run-tlcn1w7y.mjs";
-import { n as read, t as sources } from "./sources-BooL2MsX.mjs";
+import { a as stepFrames, i as runRepro, n as commands, r as createHeadless, t as run } from "./run-BfuMLahc.mjs";
+import { n as read, t as sources } from "./sources-C1uGjz4l.mjs";
 import { createBrandConsole } from "@moku-labs/common/cli";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
@@ -1242,7 +1242,7 @@ async function pageCheckpoint(argument) {
 		await pageTick(handles);
 		await pageTick(handles);
 		const captured = await game.renderer.capture();
-		const screen = captured === void 0 ? void 0 : await pageWebp(captured);
+		const screen = captured === void 0 ? void 0 : await pageWebp(captured.png);
 		return {
 			ok: true,
 			value: {
@@ -1385,7 +1385,8 @@ async function pageEncode(pixels) {
 	return `data:image/webp;base64,${btoa(binary)}`;
 }
 /**
-* Turns the PNG data URL of `renderer.capture()` into the lossless WebP of the baselines.
+* Turns the PNG data URL of `renderer.capture()`, its `png`, into the lossless WebP of the
+* baselines.
 *
 * @param url - The PNG data URL.
 * @returns The WebP data URL of the same pixels.

package/dist/{types-CxZy7Pi4.d.mts → types-BnWH-75b.d.mts}

@@ -1,6 +1,5 @@
-import { At as Json, C as LayerSpec, Dt as Api$4, F as ComponentHandle, Gt as Events$2, H as Owner, I as ComponentType, R as Entity, S as LayerSort, St as Api$3, a as PixiSprite, d as FilterSlot, h as Api$1, i as PixiModule, kt as Events$1, nn as Require, o as PixiTexture, p as Point, q as Api, r as PixiFilter, t as Api$2, vt as Descriptor } from "./types-BZ1OLf24.mjs";
-import { o as Events$3, t as Api$5 } from "./types-C47fKNcn.mjs";
-import { t as AnimApi } from "./types-CqkrEY06.mjs";
+import { D as Point, E as FilterSlot, Gt as Events$2, K as Owner, Kt as Json, L as ComponentHandle, Pt as Descriptor, Rt as Api$4, Ut as Api$5, V as Entity, _ as PixiModule, et as LayerSort, g as PixiFilter, k as Api$1, m as Api$2, o as Events$1, sn as Events$3, t as Api$3, tt as LayerSpec, ut as Api, v as PixiSprite, vn as Require, y as PixiTexture, z as ComponentType } from "./types-Dy1xB68L.mjs";
+import { t as AnimApi } from "./types-CVUHPvMB.mjs";
 import { Log } from "@moku-labs/common/browser";
 import { PluginCtx } from "@moku-labs/core";
 
@@ -623,7 +622,7 @@ type Deps$2 = {
   flow: Api;
   world: Api$1;
   renderer: Api$2;
-  assets: Api$5;
+  assets: Api$3;
   anim: AnimApi;
 };
 /**
@@ -644,7 +643,7 @@ type EffectsCtx = KernelSlice$2 & {
 /**
  * Payload of the `assets:bundle-unloaded` hook: `keys` names every texture that is gone.
  */
-type BundleUnloaded$1 = Events$3["assets:bundle-unloaded"];
+type BundleUnloaded$1 = Events$1["assets:bundle-unloaded"];
 declare namespace types_d_exports$1 {
   export { AnySceneProjection, CheckedProjections, Config$1 as Config, DefineScene, Deps$1 as Deps, Events, KernelSlice$1 as KernelSlice, LayerMap, RunContext, SceneDefinition, SceneLayer, SceneOwner, SceneProjection, SceneSpec, ScenesApi, ScenesCtx, SortRule, State$1 as State, UiLayer };
 }
@@ -871,8 +870,8 @@ type ScenesApi = {
 type Deps$1 = {
   flow: Api;
   world: Api$1;
-  assets: Api$5;
-  time: Api$3;
+  assets: Api$3;
+  time: Api$4;
 };
 /**
  * What the kernel context offers before the deps are attached.
@@ -905,7 +904,7 @@ type RunContext = {
   signal: AbortSignal;
 };
 declare namespace types_d_exports {
-  export { AudioApi, AudioContextLike, AudioCtx, BundleUnloaded, Bus, BusState, Config, Deps, KernelSlice, LifecycleChanged, ModelCommitted, MusicDescriptor, MusicOptions, MusicRequest, MusicSwitch, MusicTrack, SceneChanged, SfxRequest, SoundEntry, State, Volumes };
+  export { AudioApi, AudioContextLike, AudioCtx, AudioSessionLike, AudioSessionType, BundleUnloaded, Bus, BusState, Config, Deps, KernelSlice, LifecycleChanged, ModelCommitted, MusicDescriptor, MusicMode, MusicOptions, MusicRequest, MusicSwitch, MusicTrack, RetiringTrack, SceneChanged, SfxRequest, SoundEntry, State, StreamTrack, Volumes };
 }
 /**
  * The three volume buses. `master` carries the whole game, `music` the scene track, `sfx` every
@@ -929,7 +928,7 @@ type Bus = "master" | "music" | "sfx";
  * createApp({ plugins: [...screen, audioPlugin], pluginConfigs: { audio: { context: () => context } } });
  * ```
  */
-type AudioContextLike = Pick<AudioContext, "destination" | "currentTime" | "createGain" | "createBufferSource" | "decodeAudioData" | "resume" | "close"> & {
+type AudioContextLike = Pick<AudioContext, "destination" | "currentTime" | "createGain" | "createBufferSource" | "decodeAudioData" | "createMediaElementSource" | "resume" | "close"> & {
   readonly state: AudioContext["state"] | "interrupted";
 };
 /**
@@ -963,6 +962,73 @@ type MusicDescriptor<Asset extends string> = (key: Asset | null, options?: Music
  * ```
  */
 type Volumes = (player: Json) => Partial<Record<Bus, number>>;
+/**
+ * How a music track is played. `"decode"`: one AudioBuffer per track, gapless, about 58 MB per
+ * 150 s at 48 kHz. `"stream"`: an `<audio>` element on a `blob:` URL of the bytes `assets` holds,
+ * about 12 MB, and a gap at every loop: 5 to 49 ms in Chromium, about 0.4 s in WebKit. A tight
+ * loop keeps `"decode"`; a long track that tolerates a seam takes `"stream"`.
+ *
+ * @example
+ * ```ts
+ * const mode: MusicMode = "stream";
+ * ```
+ */
+type MusicMode = "decode" | "stream";
+/**
+ * What the page asks iOS for. `"ambient"`: mixes with other apps, the silent switch mutes it.
+ * `"playback"`: stops other apps, plays through the switch. `"auto"`: WebKit picks.
+ *
+ * @example
+ * ```ts
+ * const session: AudioSessionType = "playback";
+ * ```
+ */
+type AudioSessionType = "ambient" | "playback" | "auto";
+/**
+ * The part of `navigator.audioSession` the plugin writes. `lib.dom` has no type for it, and only
+ * WebKit has the object at all.
+ *
+ * @example
+ * ```ts
+ * // What Safari answers before the plugin started: no override.
+ * const session: AudioSessionLike = { type: "auto" };
+ * ```
+ */
+type AudioSessionLike = {
+  type: string;
+};
+/**
+ * One music track played by an element at `music: "stream"`: the element, its source node in the
+ * graph, the track gain every level goes through, and the `blob:` URL the element reads.
+ *
+ * @example
+ * ```ts
+ * // `state.music.stream` once "board.theme" plays at `music: "stream"`.
+ * const { element, url }: StreamTrack = track;
+ * element.loop; // true
+ * url.startsWith("blob:"); // true
+ * ```
+ */
+type StreamTrack = {
+  element: HTMLAudioElement;
+  node: MediaElementAudioSourceNode;
+  gain: GainNode;
+  url: string;
+};
+/**
+ * A streamed track that fades out. Its timer frees the element when the fade ends: an element has
+ * no `stop(when)` on the context clock.
+ *
+ * @example
+ * ```ts
+ * // A switch at `musicFadeMs: 600` keeps the old track here for 600 ms.
+ * const entry: RetiringTrack = { stream: oldTrack, timer: setTimeout(free, 600) };
+ * ```
+ */
+type RetiringTrack = {
+  stream: StreamTrack;
+  timer: ReturnType<typeof setTimeout>;
+};
 /**
  * audio plugin config.
  *
@@ -970,7 +1036,9 @@ type Volumes = (player: Json) => Partial<Record<Bus, number>>;
  * ```ts
  * createApp({
  *   plugins: [...screen, audioPlugin],
- *   pluginConfigs: { audio: { musicFadeMs: 400, volumes: player => player.settings.audio } }
+ *   pluginConfigs: {
+ *     audio: { musicFadeMs: 400, music: "stream", session: "playback", volumes: player => player.settings.audio }
+ *   }
  * });
  * ```
  */
@@ -983,7 +1051,9 @@ type Config = {
   musicFadeMs: number; /** Reads the player's choice from the committed player. `undefined`: the buses stay at `buses`. */
   volumes: Volumes | undefined; /** Context factory, the test seam. `undefined`: `new AudioContext()` when the global exists, otherwise headless. */
   context: (() => AudioContextLike) | undefined; /** How many started sounds `journal()` keeps, newest last. `0` turns the journal off. */
-  journal: number;
+  journal: number; /** How music plays. `"stream"` needs MP3 or AAC: WebM Opus is silent through a media element in WebKit (bug 276813). Sounds always decode. */
+  music: MusicMode; /** Set on `navigator.audioSession.type` in `onStart`, before the context exists. No-op where the API is missing (every Chromium, Firefox). */
+  session: AudioSessionType;
 };
 /**
  * One sound that started: a play of an `sfx` or a music track that began. `at` is the elapsed
@@ -1016,17 +1086,19 @@ type BusState = {
 };
 /**
  * The music that is playing, or the key remembered until the first touch unlocks the context.
- * `source` and `gain` are `undefined` exactly while the track is only remembered.
+ * `source` plays a decoded track, `stream` a streamed one; they are never both set. Both
+ * `undefined`: the key is only remembered (a locked context, or a refused `play()`).
  *
  * @example
  * ```ts
- * const track: MusicTrack = { key: "board.theme", source: undefined, gain: undefined };
+ * const track: MusicTrack = { key: "board.theme", gain: undefined, source: undefined, stream: undefined };
  * ```
  */
 type MusicTrack = {
   key: string;
-  source: AudioBufferSourceNode | undefined;
   gain: GainNode | undefined;
+  source: AudioBufferSourceNode | undefined;
+  stream: StreamTrack | undefined;
 };
 /**
  * A music switch that waits for its buffer to decode. Its identity is the token: a later request
@@ -1056,7 +1128,9 @@ type State = {
   music: MusicTrack | undefined; /** The latest switch still decoding; `undefined` once it started or a later request replaced it. */
   musicPending: MusicSwitch | undefined; /** Removes the two window listeners of the unlock. */
   unlock: (() => void) | undefined; /** The removers of the two fx handlers. */
-  removers: Array<() => void>;
+  removers: Array<() => void>; /** The `navigator.audioSession` that took `config.session`; `stop` writes `"auto"` back to it. */
+  session: AudioSessionLike | undefined; /** Streamed tracks that fade out, each freed by its timer. */
+  retiring: Set<RetiringTrack>;
   /**
    * The sounds that started, oldest first, at most `config.journal` of them. Frozen: a write
    * replaces the whole list, so `journal()` hands it out without a copy.
@@ -1156,9 +1230,9 @@ type AudioApi = {
  */
 type Deps = {
   flow: Api;
-  assets: Api$5;
-  model: Api$4;
-  time: Api$3;
+  assets: Api$3;
+  model: Api$5;
+  time: Api$4;
 };
 /**
  * What the kernel context offers before the deps are attached.
@@ -1179,7 +1253,7 @@ type AudioCtx = KernelSlice & {
 /**
  * Payload of the `model:committed` hook: the source of every volume a game sets.
  */
-type ModelCommitted = Events$1["model:committed"];
+type ModelCommitted = Events$2["model:committed"];
 /**
  * Payload of the `scenes:changed` hook: `music` is the track the next scene declared.
  */
@@ -1187,11 +1261,11 @@ type SceneChanged = Events["scenes:changed"];
 /**
  * Payload of the `lifecycle:changed` hook: the pause that holds every bus at zero.
  */
-type LifecycleChanged = Events$2["lifecycle:changed"];
+type LifecycleChanged = Events$3["lifecycle:changed"];
 /**
  * Payload of the `assets:bundle-unloaded` hook: `keys` names every decoded sound that is gone.
  */
-type BundleUnloaded = Events$3["assets:bundle-unloaded"];
+type BundleUnloaded = Events$1["assets:bundle-unloaded"];
 /**
  * What one play of a sound asks for: the key and the bus the sound goes to.
  */