@moku-labs/game 0.15.26 → 0.15.27

package/dist/{src-DWYFupNb.mjs → src-DLs4b_Vs.mjs}

@@ -2,7 +2,7 @@ import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
 import { r as systemSource, t as memory } from "./memory-CWlqhS7l.mjs";
 import { a as finishDrafts, i as enableDraftPatches, n as deepFreeze$1, o as openDrafts, r as dropDrafts } from "./drafts-BawpSaVp.mjs";
 import { _ as pushEntry, c as collectFlows, d as findNode, f as framePath, g as compact, h as slotNames, i as servePaused, l as describeGraph, m as isRestCheckpoint, n as captureFrame, o as epochOf, p as graphHash, r as serveCaptures, s as pageNow$1, t as cancelCaptures } from "./capture-PTJXDpxK.mjs";
-import { $ as component, A as localPoseOf, B as OverlayLevel, C as builtInStyles, D as textFor, E as readStyle, F as rootPoseOf, G as arcDefaults, H as Shape, I as Display, J as Exiting, K as componentsFor, L as HudPart, M as poseUnder, N as rootPointOf, O as applyPose, P as rootPoseInto, Q as Tree, R as NineSlice, U as Sprite, V as Parent, W as Transform, X as Now, Y as Layer, Z as Order, _ as uiFor, a as visualOf$1, b as Countdown, c as Covered, d as LocalWrite, f as Scroll, h as UiCounters, i as samePose, it as tag, j as parentOf$1, k as isLeaving, l as DebugTrigger, m as UI_OWNER, n as drawnRect, nt as system, o as visualRectOf, p as ScrollState, r as fitScaleOf, rt as systemsFor, s as Box, t as CONTENT$1, tt as resource, u as Escapable, x as Text, z as Overlay } from "./visual-kEC9nb-o.mjs";
+import { $ as component, A as localPoseOf, B as OverlayLevel, C as builtInStyles, D as textFor, E as readStyle, F as rootPoseOf, G as arcDefaults, H as Shape, I as Display, J as Exiting, K as componentsFor, L as HudPart, M as poseUnder, N as rootPointOf, O as applyPose, P as rootPoseInto, Q as Tree, R as NineSlice, U as Sprite, V as Parent, W as Transform, X as Now, Y as Layer, Z as Order, _ as uiFor, a as visualOf$1, b as Countdown, c as Covered, d as LocalWrite, f as Scroll, h as UiCounters, i as samePose, it as tag, j as parentOf$1, k as isLeaving, l as DebugTrigger, m as UI_OWNER, n as drawnRect, nt as system, o as visualRectOf, p as ScrollState, r as fitScaleOf, rt as systemsFor, s as Box, t as CONTENT$1, tt as resource, u as Escapable, x as Text, z as Overlay } from "./visual-ClVRMUAi.mjs";
 import { a as isDev } from "./dev-BNndV-hU.mjs";
 import { n as isComponentDefinition } from "./component-DGg5DqKK.mjs";
 import { n as flatten } from "./flatten-nUX9PpGo.mjs";
@@ -16195,6 +16195,14 @@ function emptyMap$8() {
 	return /* @__PURE__ */ new Map();
 }
 /**
+* Creates an empty set. Same reason as `emptyRecords`.
+*
+* @returns An empty set.
+*/
+function emptySet$7() {
+	return /* @__PURE__ */ new Set();
+}
+/**
 * Creates an empty weak set. Same reason as `emptyRecords`.
 *
 * @returns An empty weak set.
@@ -16229,6 +16237,7 @@ function createKeptState(config) {
 		on: allowed && config.debug.kept !== false,
 		allowed,
 		warnedBudget: false,
+		warnedBlend: emptySet$7(),
 		verifySkipped: 0,
 		bypassed: false,
 		flushPasses: 0,
@@ -16317,6 +16326,7 @@ function stopKept(state) {
 	state.flushPasses = 0;
 	state.drawnPictures = 0;
 	state.warnedBudget = false;
+	state.warnedBlend.clear();
 	state.verifySkipped = 0;
 	state.bypassed = false;
 }
@@ -16514,7 +16524,64 @@ function ancestorsPlain(kctx, record, stage) {
 function eligible(kctx, record, view, stack) {
 	const { top } = record;
 	const stage = kctx.host.stage();
-	return kctx.state.on && !kctx.state.bypassed && stage !== void 0 && stack.enabled > 0 && plainFilters(record.slots) && top.visible && top.alpha > 0 && plainBlend(top.blendMode) && plainBlend(view.object.blendMode) && topDrawn(kctx.sync, view) && ancestorsPlain(kctx, record, stage);
+	return keepingOn(kctx) && stage !== void 0 && stack.enabled > 0 && plainFilters(record.slots) && drawsAsPicture(top, view) && topDrawn(kctx.sync, view) && ancestorsPlain(kctx, record, stage);
+}
+/**
+* Tells whether the kept cache may keep anything this frame: switched on and not bypassed.
+*
+* @param kctx - The kept context.
+* @returns True when pictures may be kept.
+*/
+function keepingOn(kctx) {
+	return kctx.state.on && !kctx.state.bypassed;
+}
+/**
+* Tells whether a top and its visual draw as a picture does: the top visible and not faded out, both blending
+* normally (the visual sits inside the wrapper of a kept bare view, D4).
+*
+* @param top - The record's top.
+* @param view - Its view.
+* @returns True when they do.
+*/
+function drawsAsPicture(top, view) {
+	return top.visible && top.alpha > 0 && plainBlend(top.blendMode) && plainBlend(view.object.blendMode);
+}
+/**
+* Tells whether a node under a top blends otherwise than normally, at any depth (F68): drawn into a picture, it would
+* blend with the picture's empty texture, not with what is drawn under the view, and a glow would cover the board under
+* it instead of lighting it. Recursive, by index over `children`: allocates nothing.
+*
+* @param node - The top, or a node under it; its own blend is not read (`eligible` reads the top's and the visual's).
+* @returns True when a node under it blends otherwise.
+*/
+function blendsBelow(node) {
+	const { children } = node;
+	for (let index = 0; index < children.length; index += 1) {
+		const child = children[index];
+		if (child !== void 0 && (!plainBlend(child.blendMode) || blendsBelow(child))) return true;
+	}
+	return false;
+}
+/**
+* Tells whether a record's subtree holds a node that blends otherwise than normally, and remembers a yes (`blended`):
+* a refused record is not walked again until a change under its top clears it (`stepRecord`). The first refusal of a
+* top is warned once per run, by its label.
+*
+* @param kctx - The kept context.
+* @param record - The record.
+* @returns True when the record may not be taken.
+*/
+function blendedBelow(kctx, record) {
+	if (record.blended) return true;
+	if (!blendsBelow(record.top)) return false;
+	record.blended = true;
+	const { warnedBlend } = kctx.state;
+	const label = labelOf$3(record.top);
+	if (!warnedBlend.has(label)) {
+		warnedBlend.add(label);
+		kctx.ctx.log.warn("renderer:kept-blend", { picture: label });
+	}
+	return true;
 }
 /**
 * Tells whether a view of kind `"Display"` hangs in a subtree, the top included: a game's own object it may write
@@ -16582,7 +16649,8 @@ function createRecord$1(kctx, pixi, entity, view, slots, category) {
 		refused: 0,
 		cut: false,
 		direct: false,
-		displays: void 0
+		displays: void 0,
+		blended: false
 	};
 	const { state } = kctx;
 	state.records.push(record);
@@ -16761,8 +16829,8 @@ function writeTakeKeys(record, now, box) {
 /**
 * Takes or retakes the picture of a record: stages 1, 2 (when its first filter has inputs) and 3, at the phase of this
 * frame. The bounds are cut to the filter area of the top when it holds one (F43). Refused, and the view drawn live,
-* for a `Display` in the subtree without `onDemand`, empty bounds, a picture over 4096 device pixels, or a budget that
-* has no room (P6.3, warned once).
+* for a `Display` in the subtree without `onDemand`, a node under the top that blends otherwise (F68, warned once per
+* top), empty bounds, a picture over 4096 device pixels, or a budget that has no room (P6.3, warned once).
 *
 * @param kctx - The kept context.
 * @param pixi - The module that draws.
@@ -16775,6 +16843,7 @@ function writeTakeKeys(record, now, box) {
 function takePicture(kctx, pixi, matrices, record, view, now) {
 	const { top } = record;
 	if (!kctx.ctx.config.onDemand && holdsDisplay(kctx, top)) return false;
+	if (blendedBelow(kctx, record)) return false;
 	const drawn = drawnBounds(pixi, top);
 	if (!drawn.isValid) return false;
 	const local = clippedToArea(drawn, top.filterArea);
@@ -17114,7 +17183,8 @@ function wrapBare(kctx, record, view) {
 }
 /**
 * A live record's frame (P4.2): still frames are counted; at two (eight after churning) the record is taken, a bare
-* view in a wrapper of its own (D4).
+* view in a wrapper of its own (D4). A record with a node under its top that blends otherwise stays live, before any
+* wrap (F68).
 *
 * @param kctx - The kept context.
 * @param pixi - The module that draws.
@@ -17129,6 +17199,7 @@ function stepLive(kctx, pixi, matrices, record, view) {
 	record.still = changed ? 0 : record.still + 1;
 	if (record.still < (record.calm ? 8 : 2)) return;
 	if (record.refused > 0 && state.bytes + record.refused - record.bytes > state.budget) return;
+	if (blendedBelow(kctx, record)) return;
 	wrapBare(kctx, record, view);
 	if (takePicture(kctx, pixi, matrices, record, view, NOW)) toKept(kctx, record, view);
 	else record.still = 0;
@@ -17311,7 +17382,8 @@ function stepCalm(kctx, record) {
 }
 /**
 * One drawn frame of a record, inside the flush: eligibility, the keys of this frame, the policy of its life, the quad
-* of a kept one; the dirty flags are cleared.
+* of a kept one; the dirty flags are cleared. A change under the top forgets a blended node found before: the next
+* take walks the subtree again (F68).
 *
 * @param kctx - The kept context.
 * @param pixi - The module that draws.
@@ -17321,6 +17393,7 @@ function stepCalm(kctx, record) {
 */
 function stepRecord(kctx, pixi, matrices, record, view) {
 	noteDrawing(kctx, record, BEFORE);
+	if (record.dirtyS1) record.blended = false;
 	NOW.r = kctx.host.resolution();
 	readStack(record.slots, NOW.r, pixi.AlphaFilter, NOW);
 	if (eligible(kctx, record, view, NOW)) stepEligible(kctx, pixi, matrices, record, view);
@@ -23947,10 +24020,21 @@ const PROBE_SIZE = 4;
 /** The content subjects the renderer warms itself, in queue order; the text follows once a font is installed. */
 const CONTENT = Object.freeze([
 	"sprite",
+	"sprite-add",
+	"sprite-screen",
 	"graphics",
 	"particles-normal",
 	"particles-add"
 ]);
+/** The probe object of each content subject the tree holds from its first warm frame on. */
+const FIXED_NODES = Object.freeze({
+	sprite: "sprite",
+	"sprite-add": "spriteAdd",
+	"sprite-screen": "spriteScreen",
+	graphics: "graphics",
+	"particles-normal": "particlesNormal",
+	"particles-add": "particlesAdd"
+});
 /** Every target a WebGPU pipeline is keyed by. */
 const ALL_VARIANTS = Object.freeze([
 	"canvas",
@@ -23980,16 +24064,18 @@ function particleProperties() {
 }
 /**
 * A 4 × 4 sprite of Pixi's white texture: the batch pipeline of sprites, nine-slices, plain bitmap text and batched
-* graphics.
+* graphics, with the blend of a `Sprite` or a `NineSlice` glow (part of a WebGPU pipeline's key).
 *
 * @param pixi - The module that draws.
-* @returns The sprite.
+* @param blend - `"normal"` (Pixi's own mode left as it is), `"add"` or `"screen"`.
+* @returns The sprite, labelled `renderer.warm.sprite`, or `renderer.warm.sprite-<blend>` for a glow.
 */
-function whiteSprite(pixi) {
+function whiteSprite(pixi, blend = "normal") {
 	const sprite = new pixi.Sprite(pixi.Texture.WHITE);
-	sprite.label = "renderer.warm.sprite";
+	sprite.label = blend === "normal" ? "renderer.warm.sprite" : `renderer.warm.sprite-${blend}`;
 	sprite.width = PROBE_SIZE;
 	sprite.height = PROBE_SIZE;
+	if (blend !== "normal") sprite.blendMode = blend;
 	return sprite;
 }
 /**
@@ -24052,6 +24138,8 @@ function buildObjects(pixi) {
 		holder,
 		list: [],
 		sprite: whiteSprite(pixi),
+		spriteAdd: whiteSprite(pixi, "add"),
+		spriteScreen: whiteSprite(pixi, "screen"),
 		graphics,
 		particlesNormal: particlesOf(pixi, "normal"),
 		particlesAdd: particlesOf(pixi, "add"),
@@ -24075,6 +24163,8 @@ function dropObjects(warm) {
 		objects.clipFrame,
 		objects.holder,
 		objects.sprite,
+		objects.spriteAdd,
+		objects.spriteScreen,
 		objects.graphics,
 		objects.particlesNormal,
 		objects.particlesAdd,
@@ -24251,27 +24341,22 @@ function warmFilter(sctx, filter) {
 * @returns The node, or `undefined` for the text without a font.
 */
 function nodeOf$1(pixi, warm, objects, subject) {
-	switch (subject) {
-		case "sprite": return objects.sprite;
-		case "graphics": return objects.graphics;
-		case "particles-normal": return objects.particlesNormal;
-		case "particles-add": return objects.particlesAdd;
-		case "text":
-			if (warm.textFont === void 0) return void 0;
-			objects.text ??= new pixi.BitmapText({
-				label: "renderer.warm.text",
-				text: "0",
-				style: {
-					fontFamily: warm.textFont,
-					fontSize: 16
-				}
-			});
-			return objects.text;
-		default:
-			objects.list[0] = subject;
-			objects.holder.filters = objects.list;
-			return objects.holder;
-	}
+	if (typeof subject !== "string") {
+		objects.list[0] = subject;
+		objects.holder.filters = objects.list;
+		return objects.holder;
+	}
+	if (subject !== "text") return objects[FIXED_NODES[subject]];
+	if (warm.textFont === void 0) return void 0;
+	objects.text ??= new pixi.BitmapText({
+		label: "renderer.warm.text",
+		text: "0",
+		style: {
+			fontFamily: warm.textFont,
+			fontSize: 16
+		}
+	});
+	return objects.text;
 }
 /**
 * The name of a probe's filter in the log: the name of its WebGPU program (the definition id of one of `effects`'
@@ -25077,7 +25162,8 @@ function poolKeyOf(kind, textureKey, hollow) {
 	return hollow ? `${kind}.hollow:${textureKey}` : `${kind}:${textureKey}`;
 }
 /**
-* Brings the object of a view that left back to the state a fresh one has: detached, drawn, opaque, unmoved, white.
+* Brings the object of a view that left back to the state a fresh one has: detached, drawn, opaque, unmoved, blending
+* normally, white.
 * Its hidden reasons go with `clearHidden`, so a pooled object never brings the reason of the view it belonged to; a
 * sprite and a graphics lose their tint (a fill-only shape is coloured by it, spec 26 R2.1).
 *
@@ -25089,14 +25175,15 @@ function resetObject(view) {
 	resetNode(view.object);
 }
 /**
-* Brings a detached object back to a fresh one's pose and look: drawn, opaque, unmoved, white for a sprite and a
-* graphics.
+* Brings a detached object back to a fresh one's pose and look: drawn, opaque, unmoved, blending as its parent (no
+* glow of the view it drew for), white for a sprite and a graphics.
 *
 * @param object - The object, out of the tree.
 */
 function resetNode(object) {
 	object.visible = true;
 	object.alpha = 1;
+	object.blendMode = "inherit";
 	object.rotation = 0;
 	object.zIndex = 0;
 	object.position.set(0, 0);
@@ -27197,6 +27284,42 @@ function retargetKey(state, entity, view, key) {
 	if (key !== "") trackKey(state, entity, key);
 }
 /**
+* The Pixi blend mode a `blend` of a `Sprite` or a `NineSlice` draws with: `"add"` and `"screen"` as they are, Pixi's
+* own blends of the sprite batch; `"inherit"`, what a fresh object holds, for `"normal"` and a value without the field.
+* Any other string (Pixi's advanced modes, `"multiply"`, a typo) is never handed to Pixi, which would draw an advanced
+* mode through a filter pass of its own: it draws normally, and each such value is warned once per run.
+*
+* @param sctx - Domain context of the sync module.
+* @param blend - The component's `blend`, as a game wrote it.
+* @returns The Pixi blend mode.
+*/
+function blendModeOf(sctx, blend) {
+	if (blend === void 0 || blend === "normal") return "inherit";
+	if (blend === "add" || blend === "screen") return blend;
+	const warned = sctx.ctx.state.sync.blendWarned;
+	if (!warned.has(blend)) {
+		warned.add(blend);
+		sctx.ctx.log.warn("renderer:blend-unknown", { blend });
+	}
+	return "inherit";
+}
+/**
+* Writes the blend of a sprite or a nine-slice on its own object, never on the wrapper: a glow blends its own pixels,
+* not its children's. Only a mode that differs from what Pixi holds is written, the entity marked before: Pixi rebuilds
+* the instructions of the render group on a new mode.
+*
+* @param sctx - Domain context of the sync module.
+* @param entity - The entity.
+* @param object - The view's own object: the sprite, or the nine-slice, filled or hollow.
+* @param blend - The component's `blend`.
+*/
+function writeBlend(sctx, entity, object, blend) {
+	const mode = blendModeOf(sctx, blend);
+	if (object.blendMode === mode) return;
+	markView(sctx, entity);
+	object.blendMode = mode;
+}
+/**
 * Writes the texture and the tint of a sprite, each only when it differs from what Pixi holds.
 *
 * @param sctx - Domain context of the sync module.
@@ -27325,7 +27448,7 @@ function applyHud(sctx, entity, view, factor) {
 }
 /**
 * Writes the `Sprite` component onto its display object: the texture, or its crop for a `"cover"`
-* sprite, the stretch into the box, and the box as the hit box, the anchor applied. The stretch and
+* sprite, the blend, the stretch into the box, and the box as the hit box, the anchor applied. The stretch and
 * the hit box are written into the view's own objects. A new stretch of a view without a wrapper
 * changes the object's own units, so its filter area is written again (B4); a write that keeps it (an
 * alpha tween, a tint) writes no area.
@@ -27345,7 +27468,7 @@ function applySprite(sctx, entity, view) {
 	return stretched;
 }
 /**
-* The body of `applySprite`: the texture or its crop, the stretch, the anchor and the hit box.
+* The body of `applySprite`: the texture or its crop, the blend, the stretch, the anchor and the hit box.
 *
 * @param sctx - Domain context of the sync module.
 * @param entity - The entity.
@@ -27360,6 +27483,7 @@ function writeSprite(sctx, entity, view) {
 	if (texture === void 0) warnMissing(sctx, value.texture);
 	view.placeholder = texture === void 0;
 	applyAlpha(sctx, entity, view, value);
+	writeBlend(sctx, entity, object, value.blend);
 	if (texture === void 0) {
 		showCover(sctx, entity, view, "");
 		drawPlaceholder(sctx, entity, object, view, value, placeholderTexture(sctx));
@@ -27425,8 +27549,9 @@ function writeSlice(sctx, entity, object, field, value) {
 * Writes the `NineSlice` component onto its display object and recomputes the hit box. Pixi reads
 * a texture's borders only in the constructor, so they are copied here on every write: a pooled
 * object, a new key and a reloaded bundle all get the insets of the texture they draw now. A `hollow` that flipped
-* swaps the view's object first (F59). The hit box is the whole panel, hollow or not. A write that changes nothing,
-* or only the size, allocates nothing: the borders, the outline's shape and the clip's box are written in place.
+* swaps the view's object first (F59), and the blend is written on the object drawn now. The hit box is the whole
+* panel, hollow or not. A write that changes nothing, or only the size, allocates nothing: the borders, the outline's
+* shape and the clip's box are written in place.
 *
 * @param sctx - Domain context of the sync module.
 * @param entity - The entity.
@@ -27457,6 +27582,7 @@ function applyNineSlice(sctx, entity, view) {
 	changed = writeSlice(sctx, entity, object, "bottomHeight", borders.bottom) || changed;
 	changed = writeSlice(sctx, entity, object, "tint", missing ? 16711935 : value.tint) || changed;
 	applyAlpha(sctx, entity, view, value);
+	writeBlend(sctx, entity, object, value.blend);
 	changed = writeSlice(sctx, entity, object, "width", value.width) || changed;
 	changed = writeSlice(sctx, entity, object, "height", value.height) || changed;
 	writeHitBox(view.hitBox, value.width, value.height);
@@ -28196,6 +28322,7 @@ function stopSync(state) {
 	state.byKey.clear();
 	state.invalidated.clear();
 	state.warned.clear();
+	state.blendWarned.clear();
 	state.added.clear();
 	state.removed.clear();
 	state.reparented.clear();
@@ -31547,6 +31674,7 @@ function createSyncState(debug) {
 		slices: emptyWeakSet(),
 		invalidated: emptySet$4(),
 		warned: emptySet$4(),
+		blendWarned: emptySet$4(),
 		added: emptySet$4(),
 		removed: emptySet$4(),
 		reparented: emptySet$4(),
@@ -38180,11 +38308,121 @@ function applyAllGains(state) {
 	applyGain(state, "sfx");
 }
 //#endregion
+//#region src/plugins/audio/named.ts
+/**
+* @file audio plugin — named sounds: an `sfx` with an `id` plays through a gain of its own into its
+* bus, so the next sound with that id, `stopSfx` and `app.audio.stop` can fade it out. One entry
+* per id in `state.named`; the entry object is the token a sound still decoding checks before it
+* starts. A sound without an id never comes here.
+*/
+/**
+* The key a sound with an id waits under in `pendingSfx` while the unlock resumes the context.
+* The `#` keeps the ids apart from the asset keys, so the latest sound per id waits.
+*
+* @param id - The id of the sound.
+* @returns The key of the waiting sound.
+* @example
+* ```ts
+* waitingKey("voice"); // "#voice"
+* ```
+*/
+function waitingKey(id) {
+	return `#${id}`;
+}
+/**
+* Fades one named sound out on the context clock and stops its source at the end of the fade. A
+* sound still decoding has neither a gain nor a source, so nothing is scheduled.
+*
+* @param state - The plugin state.
+* @param entry - The sound to fade.
+* @param seconds - Length of the fade, in seconds of the context clock.
+*/
+function fadeNamed(state, entry, seconds) {
+	const context = state.context;
+	if (context === void 0) return;
+	const now = context.currentTime;
+	if (entry.gain !== void 0) ramp(entry.gain, 0, seconds, now);
+	entry.source?.stop(now + seconds);
+}
+/**
+* Takes an id for a new sound: the sound that plays, or decodes, under it fades out over the fade
+* of the new one, and a fresh entry takes its place.
+*
+* @param state - The plugin state.
+* @param id - The id of the new sound.
+* @param seconds - Length of the fade of the replaced sound, in seconds.
+* @returns The entry of the new sound, its token.
+*/
+function claimNamed(state, id, seconds) {
+	const playing = state.named.get(id);
+	if (playing !== void 0) fadeNamed(state, playing, seconds);
+	const entry = {
+		gain: void 0,
+		source: void 0
+	};
+	state.named.set(id, entry);
+	return entry;
+}
+/**
+* Starts one named sound: a gain at 1 into the bus, the source into that gain. When the source
+* ends, its gain is disconnected and the id is freed, unless a later sound took the id meanwhile.
+*
+* @param state - The plugin state.
+* @param context - The running audio context.
+* @param named - The id, its entry, the decoded buffer and the gain of the bus.
+* @param named.id - The id the sound plays under.
+* @param named.entry - The entry `claimNamed` returned for it.
+* @param named.buffer - The decoded buffer of the sound.
+* @param named.bus - The gain node of the bus the sound goes to.
+*/
+function startNamed(state, context, named) {
+	const { id, entry } = named;
+	const gain = context.createGain();
+	const source = context.createBufferSource();
+	gain.gain.value = 1;
+	gain.connect(named.bus);
+	source.buffer = named.buffer;
+	source.connect(gain);
+	source.addEventListener("ended", () => {
+		gain.disconnect();
+		if (state.named.get(id) === entry) state.named.delete(id);
+	}, { once: true });
+	entry.gain = gain;
+	entry.source = source;
+	source.start();
+}
+/**
+* Ends the sound under one id: the stop of `stopSfx` and of `app.audio.stop`. The entry leaves the
+* map, so a sound still decoding starts nothing, and the one that plays fades out. A sound with
+* that id waiting for the unlock is dropped. An id nothing plays under changes nothing.
+*
+* @param state - The plugin state.
+* @param id - The id the sound was started with.
+* @param fadeMs - Length of the fade, in real milliseconds.
+*/
+function stopNamed(state, id, fadeMs) {
+	state.pendingSfx.delete(waitingKey(id));
+	const entry = state.named.get(id);
+	if (entry === void 0) return;
+	state.named.delete(id);
+	fadeNamed(state, entry, fadeMs / 1e3);
+}
+/**
+* Stops every named sound at once and forgets the ids. `onStop` runs it: a teardown has no time
+* for a fade, and the context is closed right after.
+*
+* @param state - The plugin state.
+*/
+function stopAllNamed(state) {
+	for (const entry of state.named.values()) entry.source?.stop();
+	state.named.clear();
+}
+//#endregion
 //#region src/plugins/audio/api.ts
 /**
-* @file audio plugin — API factory. Three buses, the unlock flag and the journal of started sounds. Nothing here
-* is persisted; a game keeps the player's choice in the player state and `config.volumes` applies
-* it on the next commit.
+* @file audio plugin — API factory. Three buses, the unlock flag, the journal of started sounds and the stop of a
+* named sound. Nothing here is persisted; a game keeps the player's choice in the player state and
+* `config.volumes` applies it on the next commit.
 */
 /**
 * Brings a value into 0..1. `NaN`, which is what a slider divided by zero produces, becomes 0.
@@ -38226,7 +38464,7 @@ function setBusVolume(state, bus, value) {
 	applyGain(state, bus);
 }
 /**
-* Creates the audio API: the three buses, the unlock flag and the journal.
+* Creates the audio API: the three buses, the unlock flag, the journal and the stop of a named sound.
 *
 * @param ctx - Kernel context of the audio plugin.
 * @returns The plugin API.
@@ -38243,7 +38481,8 @@ function createAudioApi(ctx) {
 		},
 		muted: (bus) => state.buses[busOf(state, bus)].muted,
 		unlocked: () => state.unlocked,
-		journal: () => state.journal
+		journal: () => state.journal,
+		stop: (id, options) => stopNamed(state, id, options?.fadeMs ?? ctx.config.sfxFadeMs)
 	};
 }
 //#endregion
@@ -38251,13 +38490,15 @@ function createAudioApi(ctx) {
 /**
 * Replaces the journal with a frozen list that ends with one started sound, stamped with the
 * elapsed game time, and keeps only the newest `config.journal` entries. A size of 0, or anything
-* that is not a positive number, records nothing.
+* that is not a positive number, records nothing. The entry has an `id` only when the sound has
+* one: the caller leaves the field out otherwise, so no entry carries an `undefined` key.
 *
 * @param ctx - Domain context of the plugin.
 * @param sound - What started.
 * @param sound.key - Asset key of the sound.
 * @param sound.bus - The bus it plays on.
 * @param sound.kind - `"sfx"` for a play, `"music"` for a track.
+* @param sound.id - The id of a named sound; absent for every other sound.
 */
 function recordSound(ctx, sound) {
 	const size = Math.floor(ctx.config.journal);
@@ -38385,18 +38626,47 @@ function fieldOf(payload, field) {
 	return payload[field];
 }
 /**
-* Reads the key and the bus out of the `sfx` descriptor `anim` builds.
+* Reads the fade of a descriptor that ends a named sound.
 *
 * @param descriptor - The descriptor the handler was called with.
+* @param fadeMs - The configured fade, used when the descriptor names none.
+* @returns The fade, in milliseconds.
+*/
+function fadeOf(descriptor, fadeMs) {
+	return validFade(fieldOf(descriptor.payload, "fadeMs"), fadeMs);
+}
+/**
+* Takes a fade a descriptor named only when the clock can schedule it: a finite number, 0 or more.
+* `NaN` or a negative fade would make the ramp and the stop throw inside the handler.
+*
+* @param fade - The `fadeMs` the payload carries.
+* @param fallback - The configured fade.
+* @returns The fade, in milliseconds.
+* @example
+* ```ts
+* validFade(-5, 120); // 120
+* ```
+*/
+function validFade(fade, fallback) {
+	return typeof fade === "number" && Number.isFinite(fade) && fade >= 0 ? fade : fallback;
+}
+/**
+* Reads the key, the bus, the id and the fade out of the `sfx` descriptor `anim` builds.
+*
+* @param descriptor - The descriptor the handler was called with.
+* @param fadeMs - The configured fade of a named sound, used when the descriptor names none.
 * @returns The request, or `undefined` when the descriptor names no key.
 */
-function sfxOf(descriptor) {
+function sfxOf(descriptor, fadeMs) {
 	const key = fieldOf(descriptor.payload, "key");
 	const bus = fieldOf(descriptor.payload, "bus");
+	const id = fieldOf(descriptor.payload, "id");
 	if (typeof key !== "string") return void 0;
 	return {
 		key,
-		bus: typeof bus === "string" ? bus : DEFAULT_BUS$1
+		bus: typeof bus === "string" ? bus : DEFAULT_BUS$1,
+		id: typeof id === "string" ? id : void 0,
+		fadeMs: fadeOf(descriptor, fadeMs)
 	};
 }
 /**
@@ -38408,10 +38678,9 @@ function sfxOf(descriptor) {
 */
 function musicOf(descriptor, fadeMs) {
 	const key = fieldOf(descriptor.payload, "key");
-	const fade = fieldOf(descriptor.payload, "fadeMs");
 	return {
 		key: typeof key === "string" ? key : null,
-		fadeMs: typeof fade === "number" ? fade : fadeMs
+		fadeMs: validFade(fieldOf(descriptor.payload, "fadeMs"), fadeMs)
 	};
 }
 /**
@@ -38470,9 +38739,10 @@ async function bufferOf(ctx, key) {
 /**
 * Plays one sound: the handler of the kind `"sfx"`. Every play is its own source, so the same key
 * twice in one frame is heard twice, and the promise resolves when the sound STARTED. The handler
-* ignores its signal: a sound that began plays to its end. While a gesture's `resume()` is
-* pending the sound waits in `pendingSfx`, one per key. A locked context no gesture is resuming
-* drops it: the start attempt of the unlock queues nothing.
+* ignores its signal: a sound that began plays to its end, unless a sound with its id or a stop
+* ends it. While a gesture's `resume()` is pending the sound waits in `pendingSfx`, one per id
+* and one per key without an id. A locked context no gesture is resuming drops it: the start
+* attempt of the unlock queues nothing.
 *
 * @param ctx - Domain context of the plugin.
 * @param descriptor - The `sfx` descriptor `anim` built.
@@ -38480,20 +38750,79 @@ async function bufferOf(ctx, key) {
 async function playSfx(ctx, descriptor) {
 	const state = ctx.state;
 	if (state.context === void 0) return;
-	const request = sfxOf(descriptor);
+	const request = sfxOf(descriptor, ctx.config.sfxFadeMs);
 	if (request === void 0) return;
 	if (!state.unlocked) {
-		if (state.resuming) state.pendingSfx.set(request.key, request);
+		queueWhileResuming(state, request);
 		return;
 	}
 	await playRequest(ctx, request);
 }
 /**
+* Keeps a sound fired while the context is locked, one per key and one per id, when a gesture's
+* `resume()` is on its way. A locked context nobody resumes drops it.
+*
+* @param state - The plugin state.
+* @param request - The sound that was fired.
+*/
+function queueWhileResuming(state, request) {
+	if (!state.resuming) return;
+	state.pendingSfx.set(request.id === void 0 ? request.key : waitingKey(request.id), request);
+}
+/**
+* Ends the sound under one id: the handler of the kind `"stopSfx"`, for an effect, an animation
+* step and a released hint alike. A descriptor without an id ends nothing.
+*
+* @param ctx - Domain context of the plugin.
+* @param descriptor - The `stopSfx` descriptor `anim` built.
+*/
+function stopNamedSfx(ctx, descriptor) {
+	const id = fieldOf(descriptor.payload, "id");
+	if (typeof id !== "string") return;
+	stopNamed(ctx.state, id, fadeOf(descriptor, ctx.config.sfxFadeMs));
+}
+/**
+* Plays a sound under its id: the sound that has the id fades out over the fade of this one, and
+* this one starts through its own gain once its buffer is there, unless a later sound with the id
+* or a stop took its place while it decoded. A file that is missing frees the id.
+*
+* @param ctx - Domain context of the plugin.
+* @param request - The key, the fade and the id of the sound.
+* @param sound - The id and the bus, both checked.
+* @param sound.id - The id the sound plays under.
+* @param sound.bus - The bus it goes to.
+*/
+async function playNamed(ctx, request, sound) {
+	const state = ctx.state;
+	const { id, bus } = sound;
+	const entry = claimNamed(state, id, request.fadeMs / 1e3);
+	const buffer = await bufferOf(ctx, request.key);
+	if (state.named.get(id) !== entry) return;
+	const context = state.context;
+	const gain = state.buses[bus].gain;
+	if (buffer === void 0 || context === void 0 || gain === void 0) {
+		state.named.delete(id);
+		return;
+	}
+	startNamed(state, context, {
+		id,
+		entry,
+		buffer,
+		bus: gain
+	});
+	recordSound(ctx, {
+		key: request.key,
+		bus,
+		kind: "sfx",
+		id
+	});
+}
+/**
 * Starts one source of a sound on its bus. `playSfx` calls it for a live play and the unlock for
-* every sound that waited for the resume.
+* every sound that waited for the resume. A sound with an id goes through `playNamed`.
 *
 * @param ctx - Domain context of the plugin.
-* @param request - The key and the bus of the sound.
+* @param request - The key, the bus, the id and the fade of the sound.
 */
 async function playRequest(ctx, request) {
 	const state = ctx.state;
@@ -38503,6 +38832,13 @@ async function playRequest(ctx, request) {
 		ctx.log.warn("audio: unknown bus", { bus: request.bus });
 		return;
 	}
+	if (request.id !== void 0) {
+		await playNamed(ctx, request, {
+			id: request.id,
+			bus: request.bus
+		});
+		return;
+	}
 	const buffer = await bufferOf(ctx, request.key);
 	const gain = state.buses[request.bus].gain;
 	if (buffer === void 0 || gain === void 0) return;
@@ -39027,8 +39363,8 @@ function createContext(config) {
 	return typeof browserContext === "function" ? new browserContext() : void 0;
 }
 /**
-* Starts the plugin in `onStart`: the audio session first, before any sound exists, then both
-* effect handlers, then the context with its graph and its unlock. The unlock asks the context to
+* Starts the plugin in `onStart`: the audio session first, before any sound exists, then the
+* three effect handlers, then the context with its graph and its unlock. The unlock asks the context to
 * run at once: a shell that lets audio play is unlocked with no touch, and a browser that wants a
 * gesture gets the two listeners. The handlers are registered even headless, so a node that
 * awaits a sound resolves in plain Bun exactly as it does in a browser.
@@ -39040,7 +39376,7 @@ function startAudio(ctx) {
 	const audio = withDeps$4(ctx);
 	const state = audio.state;
 	const fx = audio.deps.flow.fx;
-	state.removers.push(fx.handle("sfx", (descriptor) => playSfx(audio, descriptor), { runInFast: false }), fx.handle("music", (descriptor) => playMusic(audio, musicOf(descriptor, ctx.config.musicFadeMs)), { runInFast: false }));
+	state.removers.push(fx.handle("sfx", (descriptor) => playSfx(audio, descriptor), { runInFast: false }), fx.handle("stopSfx", (descriptor) => stopNamedSfx(audio, descriptor), { runInFast: false }), fx.handle("music", (descriptor) => playMusic(audio, musicOf(descriptor, ctx.config.musicFadeMs)), { runInFast: false }));
 	const context = createContext(ctx.config);
 	if (context === void 0) return;
 	state.context = context;
@@ -39049,9 +39385,9 @@ function startAudio(ctx) {
 	startUnlock(audio);
 }
 /**
-* Frees everything `onStart` opened: the two handler registrations, the two window listeners, the
-* music track, every streamed track still fading with its timer, the journal, the audio session
-* and the context itself. The tracks are freed before the close, while their nodes can still
+* Frees everything `onStart` opened: the three handler registrations, the two window listeners,
+* the music track, every named sound, every streamed track still fading with its timer, the
+* journal, the audio session and the context itself. The tracks are freed before the close, while their nodes can still
 * disconnect. A browser caps how many contexts a page may hold, so the close is the point of this
 * teardown.
 *
@@ -39062,6 +39398,7 @@ async function stopAudio(state) {
 	for (const remove of state.removers.splice(0)) remove();
 	removeUnlock(state);
 	stopMusic(state);
+	stopAllNamed(state);
 	for (const entry of state.retiring) disposeStream(state, entry.stream);
 	state.decoded.clear();
 	state.journal = Object.freeze([]);
@@ -39241,12 +39578,20 @@ function emptyWarned$2() {
 /**
 * Creates the queue of sounds fired while the unlock is pending.
 *
-* @returns An empty queue, keyed by asset key.
+* @returns An empty queue, keyed by `"#" + id` or by asset key.
 */
 function emptyPending() {
 	return /* @__PURE__ */ new Map();
 }
 /**
+* Creates the map of the sounds that play under an id.
+*
+* @returns An empty map, keyed by id.
+*/
+function emptyNamed() {
+	return /* @__PURE__ */ new Map();
+}
+/**
 * Creates the set of streamed tracks that fade out.
 *
 * @returns An empty set of retiring tracks.
@@ -39291,6 +39636,7 @@ function createAudioState(ctx) {
 		unlocked: false,
 		resuming: false,
 		pendingSfx: emptyPending(),
+		named: emptyNamed(),
 		decoded: emptyCache$1(),
 		warned: emptyWarned$2(),
 		warnedVolumes: false,
@@ -39304,8 +39650,8 @@ function createAudioState(ctx) {
 	};
 }
 /**
-* Audio plugin: `app.audio`, the handlers of the effect kinds `sfx` and `music`, and the three
-* buses a game drives from its player state.
+* Audio plugin: `app.audio`, the handlers of the effect kinds `sfx`, `stopSfx` and `music`, and
+* the three buses a game drives from its player state.
 *
 * @example
 * ```ts
@@ -39333,6 +39679,7 @@ const audioPlugin = /*#__PURE__*/ createPlugin$1("audio", {
 			sfx: 1
 		},
 		musicFadeMs: 600,
+		sfxFadeMs: 120,
 		volumes: void 0,
 		context: void 0,
 		journal: 0,
@@ -48874,24 +49221,61 @@ function spawned(id) {
 }
 /**
 * A sound. `anim` owns the descriptor because it sits below `audio`; `audio` owns the handler,
-* and a game without `audio` plays nothing and hears no error.
+* and a game without `audio` plays nothing and hears no error. A sound with an `id` is named:
+* one sound plays per id, a new one with the same id fades the old one out over `fadeMs`, and
+* `stopSfx(id)` stops it. The payload carries `id` and `fadeMs` only when they are given, so a
+* sound without them stays `{ key, bus }`.
 *
 * @param key - Asset key of the sound.
-* @param options - The bus to play it on.
+* @param options - The bus, the name and the fade.
 * @param options.bus - `"sfx"` when omitted.
+* @param options.id - Name of the sound; one sound per id plays.
+* @param options.fadeMs - Fade of the sound with the same id this one replaces; `audio`'s
+*   `sfxFadeMs` when omitted.
 * @returns The descriptor, usable as a timeline step and as `fx(...)` in a node.
 * @example
 * ```ts
 * sfx("board.merge"); // { kind: "sfx", payload: { key: "board.merge", bus: "sfx" }, cosmetic: true }
+* sfx("voice.hello", { id: "voice", fadeMs: 200 });
+* // { kind: "sfx", payload: { key: "voice.hello", bus: "sfx", id: "voice", fadeMs: 200 }, cosmetic: true }
 * ```
 */
 function sfx(key, options) {
+	const payload = {
+		key,
+		bus: options?.bus ?? DEFAULT_BUS
+	};
+	if (options?.id !== void 0) payload.id = options.id;
+	if (options?.fadeMs !== void 0) payload.fadeMs = options.fadeMs;
 	return Object.freeze({
 		kind: "sfx",
-		payload: Object.freeze({
-			key,
-			bus: options?.bus ?? DEFAULT_BUS
-		}),
+		payload: Object.freeze(payload),
+		cosmetic: true
+	});
+}
+/**
+* Stops the named sound `sfx(key, { id })` started, fading it out over `fadeMs`. `audio` owns the
+* handler; an id nothing plays is silent. It works as `fx.start(stopSfx("voice"))` in a node, as a
+* step a timeline reaches, and as the hint `hint("stopSfx", { id: "voice" })`. A timeline that is
+* finished or cut fires no effect, this one included: a game that must stop the voice then stops
+* it from the node.
+*
+* @param id - The id the sound was played with.
+* @param options - The fade.
+* @param options.fadeMs - Fade-out in ms; `audio`'s `sfxFadeMs` when omitted.
+* @returns The descriptor, usable as a timeline step and as `fx(...)` in a node.
+* @example
+* ```ts
+* stopSfx("voice", { fadeMs: 200 }); // { kind: "stopSfx", payload: { id: "voice", fadeMs: 200 }, cosmetic: true }
+* stopSfx("voice"); // { kind: "stopSfx", payload: { id: "voice" }, cosmetic: true }
+* ```
+*/
+function stopSfx(id, options) {
+	const payload = { id };
+	if (options?.fadeMs !== void 0) payload.fadeMs = options.fadeMs;
+	return Object.freeze({
+		kind: "stopSfx",
+		payload: Object.freeze(payload),
 		cosmetic: true
 	});
 }
@@ -62466,6 +62850,7 @@ function cubicBezier(x1, y1, x2, y2) {
 * | ui | textInput | { caretWidth: 3, caret: 0x000000, selection: 0x3390ff, selectionAlpha: 0.35, composingUnderline: 3, keyboardMargin: 16 }; shallow merge |
 * | audio | buses | { master: 1, music: 0.6, sfx: 1 }; shallow merge: a game that sets `buses` gives all three fields |
 * | audio | musicFadeMs | 600 |
+* | audio | sfxFadeMs | 120 |
 * | audio | volumes | undefined, the buses stay at `buses` |
 * | audio | context | undefined, the real AudioContext |
 * | audio | journal | 0, no started sound is kept |
@@ -62597,4 +62982,4 @@ const screen = [
 	uiPlugin
 ];
 //#endregion
-export { sfx as $, refuseStart as $t, types_exports$10 as A, Noise as At, defineMotion as B, Frames as Bt, types_exports$3 as C, effectsPlugin as Ct, types_exports$7 as D, ColorMatrix as Dt, types_exports$6 as E, Blur as Et, types_exports$15 as F, scenesPlugin as Ft, external as G, PERF_CAUSES as Gt, platformPlugin as H, PASS_KINDS as Ht, types_exports$16 as I, assetsPlugin as It, mark as J, PROBLEM_RULES as Jt, frames as K, PERF_GAP_BUCKETS as Kt, types_exports$17 as L, animPlugin as Lt, types_exports$12 as M, defineFilter as Mt, types_exports$13 as N, debugPlugin as Nt, types_exports$8 as O, Displacement as Ot, types_exports$14 as P, audioPlugin as Pt, set as Q, flowPlugin as Qt, uiPlugin as R, AnimPlayer as Rt, types_exports$2 as S, messageDuration as St, types_exports$5 as T, Alpha as Tt, HAPTIC_KINDS as U, frameAt as Ut, textPlugin as V, rendererPlugin as Vt, defineAnimation as W, MONITOR_SECTIONS as Wt, play$1 as X, DEMAND_REASONS as Xt, parallel as Y, SHADER_WHATS as Yt, sequence as Z, worldPlugin as Zt, defineBundles as _, Touchable as _t, cubicBezier as a, SaveUnreadableError as an, wait as at, types_exports as b, i18nPlugin as bt, hint as c, clockPlugin as cn, DropTarget as ct, defineScene as d, Pointer as dt, exit as en, spawn as et, tr as f, PointerOver as ft, music as g, Tappable as gt, defineEmitter as h, Swipeable as ht, screen as i, modelPlugin as in, use as it, types_exports$11 as j, Outline as jt, types_exports$9 as k, Glow as kt, schedule as l, Held as lt, flattenFeatures as m, Pressed as mt, createPlugin as n, to as nn, stagger as nt, defineEffect as o, lifecyclePlugin as on, inputPlugin as ot, defineFeature as p, Pressable as pt, haptic as q, PERF_LOG_VERSION as qt, defineGame as r, type as rn, tween as rt, guide as s, timePlugin as sn, Draggable as st, createApp as t, slot as tn, spawned as tt, projection as u, Hovered as ut, load as v, Traceable as vt, types_exports$4 as w, Emitter as wt, types_exports$1 as x, messageArgument as xt, ready as y, Traced as yt, resolve as z, Animation as zt };
+export { sfx as $, flowPlugin as $t, types_exports$10 as A, Glow as At, defineMotion as B, Animation as Bt, types_exports$3 as C, messageDuration as Ct, types_exports$7 as D, Blur as Dt, types_exports$6 as E, Alpha as Et, types_exports$15 as F, audioPlugin as Ft, external as G, MONITOR_SECTIONS as Gt, platformPlugin as H, rendererPlugin as Ht, types_exports$16 as I, scenesPlugin as It, mark as J, PERF_LOG_VERSION as Jt, frames as K, PERF_CAUSES as Kt, types_exports$17 as L, assetsPlugin as Lt, types_exports$12 as M, Outline as Mt, types_exports$13 as N, defineFilter as Nt, types_exports$8 as O, ColorMatrix as Ot, types_exports$14 as P, debugPlugin as Pt, set as Q, worldPlugin as Qt, uiPlugin as R, animPlugin as Rt, types_exports$2 as S, messageArgument as St, types_exports$5 as T, Emitter as Tt, HAPTIC_KINDS as U, PASS_KINDS as Ut, textPlugin as V, Frames as Vt, defineAnimation as W, frameAt as Wt, play$1 as X, SHADER_WHATS as Xt, parallel as Y, PROBLEM_RULES as Yt, sequence as Z, DEMAND_REASONS as Zt, defineBundles as _, Tappable as _t, cubicBezier as a, modelPlugin as an, use as at, types_exports as b, Traced as bt, hint as c, timePlugin as cn, Draggable as ct, defineScene as d, Hovered as dt, refuseStart as en, spawn as et, tr as f, Pointer as ft, music as g, Swipeable as gt, defineEmitter as h, Pressed as ht, screen as i, type as in, tween as it, types_exports$11 as j, Noise as jt, types_exports$9 as k, Displacement as kt, schedule as l, clockPlugin as ln, DropTarget as lt, flattenFeatures as m, Pressable as mt, createPlugin as n, slot as nn, stagger as nt, defineEffect as o, SaveUnreadableError as on, wait as ot, defineFeature as p, PointerOver as pt, haptic as q, PERF_GAP_BUCKETS as qt, defineGame as r, to as rn, stopSfx as rt, guide as s, lifecyclePlugin as sn, inputPlugin as st, createApp as t, exit as tn, spawned as tt, projection as u, Held as ut, load as v, Touchable as vt, types_exports$4 as w, effectsPlugin as wt, types_exports$1 as x, i18nPlugin as xt, ready as y, Traceable as yt, resolve as z, AnimPlayer as zt };