@zkmake/sound-scape 0.1.0

package/dist/player-BlQ9UyoK.js

@@ -0,0 +1,281 @@
+//#region src/core/random.ts
+/** A value drawn uniformly from `[low, high]`. */
+const between = (random, [low, high]) => low + random() * (high - low);
+/**
+* One of `pool` at random, never `last` when there is a choice. With one sample it repeats; with
+* two it alternates; with three or more the ear stops hearing a pattern.
+*/
+const pickNotLast = (pool, last, random) => {
+	const choices = pool.length > 1 ? pool.filter((item) => item !== last) : pool;
+	return choices[Math.min(choices.length - 1, Math.floor(random() * choices.length))] ?? pool[0];
+};
+/**
+* A small seeded generator (mulberry32) in `Math.random`'s shape: the same seed plays the same
+* soundscape, for tests and for demos you want to reproduce.
+*/
+const seededRandom = (seed) => {
+	let state = seed >>> 0;
+	return () => {
+		state = state + 1831565813 >>> 0;
+		let t = state;
+		t = Math.imul(t ^ t >>> 15, t | 1);
+		t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+		return ((t ^ t >>> 14) >>> 0) / 4294967296;
+	};
+};
+//#endregion
+//#region src/core/soundscape.ts
+const DEFAULT_VOLUME = [.7, 1];
+const DEFAULT_RATE = [.95, 1.05];
+const DEFAULT_PAN = [-.4, .4];
+const DEFAULT_BED_FADE_IN_MS = 500;
+const DEFAULT_BED_FADE_OUT_MS = 700;
+const DEFAULT_MAX_CONCURRENT = 4;
+/** Emitters cut by `stop` or suppression fade this fast at most, so a cut bird doesn't click. */
+const EMITTER_CUT_MS = 250;
+const defaultTimers = {
+	set: (callback, ms) => globalThis.setTimeout(callback, ms),
+	clear: (handle) => globalThis.clearTimeout(handle)
+};
+/**
+* A soundscape: one looping bed under emitters that fire on their own random timers, each fire
+* with a fresh sample (never the last one), volume, rate and pan. A concurrency cap drops fires
+* that would muddy the mix. Every audio call goes through a `SoundscapeBus`, so the engine runs on
+* Howler, raw Web Audio or a fake in a test.
+*
+* `start` and `stop` can alternate any number of times; `dispose` is final and safe to call twice.
+* Every timer checks a disposed flag before it fires or re-arms, so a timer queued before a
+* teardown (React StrictMode, a scene swap in the same tick) does nothing.
+*/
+var Soundscape = class {
+	def;
+	bus;
+	random;
+	timers;
+	onEmitter;
+	emitters;
+	/** Live emitter voices, ours only: a bus shared with another soundscape keeps its voices. */
+	live = /* @__PURE__ */ new Map();
+	bedId = null;
+	bedGain = 1;
+	running = false;
+	disposed = false;
+	suppressed = false;
+	constructor(def, bus, opts = {}) {
+		this.def = def;
+		this.bus = bus;
+		this.random = opts.random ?? Math.random;
+		this.timers = opts.timers ?? defaultTimers;
+		this.onEmitter = opts.onEmitter;
+		this.emitters = (def.emitters ?? []).map((emitter, index) => ({
+			name: emitter.name ?? String(index),
+			def: emitter,
+			timer: null,
+			armed: false,
+			last: null
+		}));
+	}
+	/** Fade the bed in and arm the emitters. Does nothing while running or once disposed. */
+	start(opts = {}) {
+		if (this.disposed || this.running) return;
+		this.running = true;
+		const bed = this.def.bed;
+		if (bed) this.bedId = this.bus.playBed(bed.sample, {
+			volume: bed.volume * this.bedGain,
+			fadeInMs: opts.fadeInMs ?? bed.fadeInMs ?? DEFAULT_BED_FADE_IN_MS
+		});
+		for (const emitter of this.emitters) this.arm(emitter, .25 + this.random() * .5);
+	}
+	/** Fade the bed out and cut the emitters. `start` brings it all back. */
+	stop(opts = {}) {
+		if (!this.running) return;
+		this.running = false;
+		for (const emitter of this.emitters) this.disarm(emitter);
+		const fadeOutMs = opts.fadeOutMs ?? this.def.bed?.fadeOutMs ?? DEFAULT_BED_FADE_OUT_MS;
+		if (this.bedId !== null) {
+			this.bus.stop(this.bedId, fadeOutMs);
+			this.bedId = null;
+		}
+		this.cutEmitters(Math.min(fadeOutMs, EMITTER_CUT_MS));
+	}
+	/** Stop for good. Safe to call twice; `start` does nothing afterwards. */
+	dispose(opts = {}) {
+		if (this.disposed) return;
+		this.stop(opts);
+		this.disposed = true;
+	}
+	/**
+	* Hold the emitters back, for dialog or narration: one-shots compete with a voice line and with
+	* screen readers even when ducked. Voices already playing fade out; the timers keep ticking and
+	* fires resume when lifted. The bed plays on (duck it through the adapter if it should dip).
+	*/
+	suppressEmitters(suppressed, opts = {}) {
+		if (this.suppressed === suppressed) return;
+		this.suppressed = suppressed;
+		if (suppressed) this.cutEmitters(opts.fadeOutMs ?? 300);
+	}
+	/**
+	* Fire one emitter now, by name or index, whether or not the soundscape is running. Still
+	* respects the cap. Returns whether a voice started. For debug panels and tests.
+	*/
+	fire(emitter) {
+		const state = typeof emitter === "number" ? this.emitters[emitter] : this.emitters.find((candidate) => candidate.name === emitter);
+		if (!state || this.disposed) return false;
+		return this.play(state);
+	}
+	/** Scale the bed's volume, for a scene that wants it lower or a debug slider. Kept across restarts. */
+	setBedGain(gain, opts = {}) {
+		this.bedGain = gain;
+		if (this.bedId !== null && this.def.bed) this.bus.setVolume(this.bedId, this.def.bed.volume * gain, opts.fadeMs ?? 0);
+	}
+	get isRunning() {
+		return this.running;
+	}
+	get isDisposed() {
+		return this.disposed;
+	}
+	get emittersSuppressed() {
+		return this.suppressed;
+	}
+	/** Emitter voices playing right now. */
+	get liveEmitters() {
+		return this.live.size;
+	}
+	get emitterNames() {
+		return this.emitters.map((emitter) => emitter.name);
+	}
+	/** Schedule the next fire; `share` scales the interval, for the first one. */
+	arm(emitter, share = 1) {
+		if (this.disposed || !this.running) return;
+		const wait = between(this.random, emitter.def.intervalMs) * share;
+		emitter.armed = true;
+		emitter.timer = this.timers.set(() => {
+			emitter.armed = false;
+			emitter.timer = null;
+			if (this.disposed || !this.running) return;
+			if (!this.suppressed) this.play(emitter);
+			this.arm(emitter);
+		}, wait);
+	}
+	disarm(emitter) {
+		if (emitter.armed) {
+			this.timers.clear(emitter.timer);
+			emitter.armed = false;
+			emitter.timer = null;
+		}
+	}
+	play(emitter) {
+		if (this.live.size >= (this.def.maxConcurrent ?? DEFAULT_MAX_CONCURRENT)) return false;
+		const sample = pickNotLast(emitter.def.samples, emitter.last, this.random);
+		if (sample === void 0) return false;
+		let ended = false;
+		let id = null;
+		id = this.bus.playEmitter(sample, {
+			volume: between(this.random, emitter.def.volume ?? DEFAULT_VOLUME),
+			rate: between(this.random, emitter.def.rate ?? DEFAULT_RATE),
+			pan: between(this.random, emitter.def.pan ?? DEFAULT_PAN),
+			onEnd: () => {
+				ended = true;
+				if (id !== null) this.release(id);
+			}
+		});
+		if (id === null) return false;
+		emitter.last = sample;
+		this.onEmitter?.({
+			emitter: emitter.name,
+			sample,
+			phase: "start"
+		});
+		if (ended) this.onEmitter?.({
+			emitter: emitter.name,
+			sample,
+			phase: "end"
+		});
+		else this.live.set(id, {
+			emitter: emitter.name,
+			sample
+		});
+		return true;
+	}
+	release(id) {
+		const voice = this.live.get(id);
+		if (voice) {
+			this.live.delete(id);
+			this.onEmitter?.({
+				...voice,
+				phase: "end"
+			});
+		}
+	}
+	cutEmitters(fadeOutMs) {
+		for (const id of Array.from(this.live.keys())) {
+			this.bus.stop(id, fadeOutMs);
+			this.release(id);
+		}
+	}
+};
+//#endregion
+//#region src/core/player.ts
+const DEFAULT_CROSSFADE_MS = 1e3;
+/** Two defs with the same content are the same soundscape, so an inline def doesn't restart the bed. */
+const signature = (def) => JSON.stringify(def);
+/**
+* Plays one soundscape at a time over a bus and swaps between them: `play(def)` starts it, a
+* different def crossfades to it, the same def again (by content, not identity) does nothing, and
+* `play(null)` fades out. It also follows tab visibility. This is what a scene manager or a React
+* effect wants; use `Soundscape` directly for full control.
+*/
+var SoundscapePlayer = class {
+	bus;
+	opts;
+	scape = null;
+	key = null;
+	hidden = false;
+	disposed = false;
+	onVisibility = () => {
+		this.hidden = document.visibilityState === "hidden";
+		if (this.hidden) this.scape?.stop();
+		else this.scape?.start();
+	};
+	constructor(bus, opts = {}) {
+		this.bus = bus;
+		this.opts = opts;
+		if ((opts.whenHidden ?? "stop") === "stop" && typeof document !== "undefined") {
+			this.hidden = document.visibilityState === "hidden";
+			document.addEventListener("visibilitychange", this.onVisibility);
+		}
+	}
+	/** Play `def`, crossfading from whatever plays now. `null` fades out. */
+	play(def, opts = {}) {
+		if (this.disposed) return;
+		const key = def === null ? null : signature(def);
+		if (key === this.key) return;
+		const crossfadeMs = opts.crossfadeMs ?? this.opts.crossfadeMs ?? DEFAULT_CROSSFADE_MS;
+		const previous = this.scape;
+		const crossfading = previous?.isRunning ?? false;
+		previous?.dispose({ fadeOutMs: crossfadeMs });
+		this.key = key;
+		this.scape = def === null ? null : new Soundscape(def, this.bus, this.opts);
+		if (this.scape && !this.hidden) this.scape.start(crossfading ? { fadeInMs: crossfadeMs } : {});
+	}
+	/** Fade out and forget the current soundscape. */
+	stop(opts = {}) {
+		this.scape?.dispose(opts);
+		this.scape = null;
+		this.key = null;
+	}
+	/** The soundscape playing now, for `fire`, `suppressEmitters` or `setBedGain`. */
+	get current() {
+		return this.scape;
+	}
+	dispose(opts = {}) {
+		if (this.disposed) return;
+		this.stop(opts);
+		this.disposed = true;
+		if (typeof document !== "undefined") document.removeEventListener("visibilitychange", this.onVisibility);
+	}
+};
+//#endregion
+export { seededRandom as i, Soundscape as n, pickNotLast as r, SoundscapePlayer as t };
+
+//# sourceMappingURL=player-BlQ9UyoK.js.map

package/dist/player-BlQ9UyoK.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"player-BlQ9UyoK.js","names":[],"sources":["../src/core/random.ts","../src/core/soundscape.ts","../src/core/player.ts"],"sourcesContent":["import { type Range } from \"./types.ts\";\n\n/** A value drawn uniformly from `[low, high]`. */\nconst between = (random: () => number, [low, high]: Range) => low + random() * (high - low);\n\n/**\n * One of `pool` at random, never `last` when there is a choice. With one sample it repeats; with\n * two it alternates; with three or more the ear stops hearing a pattern.\n */\nconst pickNotLast = <T>(\n  pool: readonly T[],\n  last: T | null,\n  random: () => number,\n): T | undefined => {\n  const choices = pool.length > 1 ? pool.filter((item) => item !== last) : pool;\n  const index = Math.min(choices.length - 1, Math.floor(random() * choices.length));\n\n  return choices[index] ?? pool[0];\n};\n\n/**\n * A small seeded generator (mulberry32) in `Math.random`'s shape: the same seed plays the same\n * soundscape, for tests and for demos you want to reproduce.\n */\nconst seededRandom = (seed: number) => {\n  let state = seed >>> 0;\n\n  return () => {\n    state = (state + 0x6d2b79f5) >>> 0;\n\n    let t = state;\n\n    t = Math.imul(t ^ (t >>> 15), t | 1);\n    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);\n\n    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;\n  };\n};\n\nexport { between, pickNotLast, seededRandom };\n","import { between, pickNotLast } from \"./random.ts\";\nimport {\n  type EmitterDef,\n  type Range,\n  type SoundscapeBus,\n  type SoundscapeDef,\n  type SoundscapeOptions,\n  type Timers,\n} from \"./types.ts\";\n\nconst DEFAULT_VOLUME: Range = [0.7, 1];\nconst DEFAULT_RATE: Range = [0.95, 1.05];\nconst DEFAULT_PAN: Range = [-0.4, 0.4];\nconst DEFAULT_BED_FADE_IN_MS = 500;\nconst DEFAULT_BED_FADE_OUT_MS = 700;\nconst DEFAULT_MAX_CONCURRENT = 4;\n/** Emitters cut by `stop` or suppression fade this fast at most, so a cut bird doesn't click. */\nconst EMITTER_CUT_MS = 250;\n\ntype EmitterState = {\n  name: string;\n  def: EmitterDef;\n  timer: unknown;\n  armed: boolean;\n  last: string | null;\n};\n\nconst defaultTimers: Timers = {\n  set: (callback, ms) => globalThis.setTimeout(callback, ms),\n  clear: (handle) => globalThis.clearTimeout(handle as ReturnType<typeof setTimeout>),\n};\n\n/**\n * A soundscape: one looping bed under emitters that fire on their own random timers, each fire\n * with a fresh sample (never the last one), volume, rate and pan. A concurrency cap drops fires\n * that would muddy the mix. Every audio call goes through a `SoundscapeBus`, so the engine runs on\n * Howler, raw Web Audio or a fake in a test.\n *\n * `start` and `stop` can alternate any number of times; `dispose` is final and safe to call twice.\n * Every timer checks a disposed flag before it fires or re-arms, so a timer queued before a\n * teardown (React StrictMode, a scene swap in the same tick) does nothing.\n */\nclass Soundscape<Id = unknown> {\n  readonly def: SoundscapeDef;\n  private readonly bus: SoundscapeBus<Id>;\n  private readonly random: () => number;\n  private readonly timers: Timers;\n  private readonly onEmitter: SoundscapeOptions[\"onEmitter\"];\n  private readonly emitters: EmitterState[];\n  /** Live emitter voices, ours only: a bus shared with another soundscape keeps its voices. */\n  private readonly live = new Map<Id, { emitter: string; sample: string }>();\n  private bedId: Id | null = null;\n  private bedGain = 1;\n  private running = false;\n  private disposed = false;\n  private suppressed = false;\n\n  constructor(def: SoundscapeDef, bus: SoundscapeBus<Id>, opts: SoundscapeOptions = {}) {\n    this.def = def;\n    this.bus = bus;\n    this.random = opts.random ?? Math.random;\n    this.timers = opts.timers ?? defaultTimers;\n    this.onEmitter = opts.onEmitter;\n    this.emitters = (def.emitters ?? []).map((emitter, index) => ({\n      name: emitter.name ?? String(index),\n      def: emitter,\n      timer: null,\n      armed: false,\n      last: null,\n    }));\n  }\n\n  /** Fade the bed in and arm the emitters. Does nothing while running or once disposed. */\n  start(opts: { fadeInMs?: number } = {}) {\n    if (this.disposed || this.running) {\n      return;\n    }\n\n    this.running = true;\n\n    const bed = this.def.bed;\n\n    if (bed) {\n      this.bedId = this.bus.playBed(bed.sample, {\n        volume: bed.volume * this.bedGain,\n        fadeInMs: opts.fadeInMs ?? bed.fadeInMs ?? DEFAULT_BED_FADE_IN_MS,\n      });\n    }\n\n    for (const emitter of this.emitters) {\n      // The first fire comes sooner than a full interval, so the scene isn't mute for a while.\n      this.arm(emitter, 0.25 + this.random() * 0.5);\n    }\n  }\n\n  /** Fade the bed out and cut the emitters. `start` brings it all back. */\n  stop(opts: { fadeOutMs?: number } = {}) {\n    if (!this.running) {\n      return;\n    }\n\n    this.running = false;\n\n    for (const emitter of this.emitters) {\n      this.disarm(emitter);\n    }\n\n    const fadeOutMs = opts.fadeOutMs ?? this.def.bed?.fadeOutMs ?? DEFAULT_BED_FADE_OUT_MS;\n\n    if (this.bedId !== null) {\n      this.bus.stop(this.bedId, fadeOutMs);\n      this.bedId = null;\n    }\n\n    this.cutEmitters(Math.min(fadeOutMs, EMITTER_CUT_MS));\n  }\n\n  /** Stop for good. Safe to call twice; `start` does nothing afterwards. */\n  dispose(opts: { fadeOutMs?: number } = {}) {\n    if (this.disposed) {\n      return;\n    }\n\n    this.stop(opts);\n    this.disposed = true;\n  }\n\n  /**\n   * Hold the emitters back, for dialog or narration: one-shots compete with a voice line and with\n   * screen readers even when ducked. Voices already playing fade out; the timers keep ticking and\n   * fires resume when lifted. The bed plays on (duck it through the adapter if it should dip).\n   */\n  suppressEmitters(suppressed: boolean, opts: { fadeOutMs?: number } = {}) {\n    if (this.suppressed === suppressed) {\n      return;\n    }\n\n    this.suppressed = suppressed;\n\n    if (suppressed) {\n      this.cutEmitters(opts.fadeOutMs ?? 300);\n    }\n  }\n\n  /**\n   * Fire one emitter now, by name or index, whether or not the soundscape is running. Still\n   * respects the cap. Returns whether a voice started. For debug panels and tests.\n   */\n  fire(emitter: string | number) {\n    const state =\n      typeof emitter === \"number\"\n        ? this.emitters[emitter]\n        : this.emitters.find((candidate) => candidate.name === emitter);\n\n    if (!state || this.disposed) {\n      return false;\n    }\n\n    return this.play(state);\n  }\n\n  /** Scale the bed's volume, for a scene that wants it lower or a debug slider. Kept across restarts. */\n  setBedGain(gain: number, opts: { fadeMs?: number } = {}) {\n    this.bedGain = gain;\n\n    if (this.bedId !== null && this.def.bed) {\n      this.bus.setVolume(this.bedId, this.def.bed.volume * gain, opts.fadeMs ?? 0);\n    }\n  }\n\n  get isRunning() {\n    return this.running;\n  }\n\n  get isDisposed() {\n    return this.disposed;\n  }\n\n  get emittersSuppressed() {\n    return this.suppressed;\n  }\n\n  /** Emitter voices playing right now. */\n  get liveEmitters() {\n    return this.live.size;\n  }\n\n  get emitterNames(): readonly string[] {\n    return this.emitters.map((emitter) => emitter.name);\n  }\n\n  /** Schedule the next fire; `share` scales the interval, for the first one. */\n  private arm(emitter: EmitterState, share = 1) {\n    if (this.disposed || !this.running) {\n      return;\n    }\n\n    const wait = between(this.random, emitter.def.intervalMs) * share;\n\n    emitter.armed = true;\n    emitter.timer = this.timers.set(() => {\n      emitter.armed = false;\n      emitter.timer = null;\n\n      if (this.disposed || !this.running) {\n        return;\n      }\n\n      if (!this.suppressed) {\n        this.play(emitter);\n      }\n\n      this.arm(emitter);\n    }, wait);\n  }\n\n  private disarm(emitter: EmitterState) {\n    if (emitter.armed) {\n      this.timers.clear(emitter.timer);\n      emitter.armed = false;\n      emitter.timer = null;\n    }\n  }\n\n  private play(emitter: EmitterState) {\n    if (this.live.size >= (this.def.maxConcurrent ?? DEFAULT_MAX_CONCURRENT)) {\n      return false;\n    }\n\n    const sample = pickNotLast(emitter.def.samples, emitter.last, this.random);\n\n    if (sample === undefined) {\n      return false;\n    }\n\n    let ended = false;\n    let id: Id | null = null;\n\n    id = this.bus.playEmitter(sample, {\n      volume: between(this.random, emitter.def.volume ?? DEFAULT_VOLUME),\n      rate: between(this.random, emitter.def.rate ?? DEFAULT_RATE),\n      pan: between(this.random, emitter.def.pan ?? DEFAULT_PAN),\n      onEnd: () => {\n        // An adapter may end a voice before `playEmitter` returns (a zero-length sample).\n        ended = true;\n\n        if (id !== null) {\n          this.release(id);\n        }\n      },\n    });\n\n    if (id === null) {\n      return false;\n    }\n\n    emitter.last = sample;\n    this.onEmitter?.({ emitter: emitter.name, sample, phase: \"start\" });\n\n    if (ended) {\n      this.onEmitter?.({ emitter: emitter.name, sample, phase: \"end\" });\n    } else {\n      this.live.set(id, { emitter: emitter.name, sample });\n    }\n\n    return true;\n  }\n\n  private release(id: Id) {\n    const voice = this.live.get(id);\n\n    if (voice) {\n      this.live.delete(id);\n      this.onEmitter?.({ ...voice, phase: \"end\" });\n    }\n  }\n\n  private cutEmitters(fadeOutMs: number) {\n    for (const id of Array.from(this.live.keys())) {\n      this.bus.stop(id, fadeOutMs);\n      this.release(id);\n    }\n  }\n}\n\nexport { Soundscape };\n","import { Soundscape } from \"./soundscape.ts\";\nimport { type SoundscapeBus, type SoundscapeDef, type SoundscapeOptions } from \"./types.ts\";\n\ntype SoundscapePlayerOptions = SoundscapeOptions & {\n  /** Swap time between two soundscapes: the old bed fades out while the new one fades in. Default 1000. */\n  crossfadeMs?: number;\n  /**\n   * `\"stop\"` (default) fades the soundscape out while the tab is hidden and back in when it\n   * returns, so a background tab doesn't play to itself. `\"play\"` leaves it alone.\n   */\n  whenHidden?: \"stop\" | \"play\";\n};\n\nconst DEFAULT_CROSSFADE_MS = 1000;\n\n/** Two defs with the same content are the same soundscape, so an inline def doesn't restart the bed. */\nconst signature = (def: SoundscapeDef) => JSON.stringify(def);\n\n/**\n * Plays one soundscape at a time over a bus and swaps between them: `play(def)` starts it, a\n * different def crossfades to it, the same def again (by content, not identity) does nothing, and\n * `play(null)` fades out. It also follows tab visibility. This is what a scene manager or a React\n * effect wants; use `Soundscape` directly for full control.\n */\nclass SoundscapePlayer<Id = unknown> {\n  private readonly bus: SoundscapeBus<Id>;\n  private readonly opts: SoundscapePlayerOptions;\n  private scape: Soundscape<Id> | null = null;\n  private key: string | null = null;\n  private hidden = false;\n  private disposed = false;\n  private readonly onVisibility = () => {\n    this.hidden = document.visibilityState === \"hidden\";\n\n    if (this.hidden) {\n      this.scape?.stop();\n    } else {\n      this.scape?.start();\n    }\n  };\n\n  constructor(bus: SoundscapeBus<Id>, opts: SoundscapePlayerOptions = {}) {\n    this.bus = bus;\n    this.opts = opts;\n\n    if ((opts.whenHidden ?? \"stop\") === \"stop\" && typeof document !== \"undefined\") {\n      this.hidden = document.visibilityState === \"hidden\";\n      document.addEventListener(\"visibilitychange\", this.onVisibility);\n    }\n  }\n\n  /** Play `def`, crossfading from whatever plays now. `null` fades out. */\n  play(def: SoundscapeDef | null, opts: { crossfadeMs?: number } = {}) {\n    if (this.disposed) {\n      return;\n    }\n\n    const key = def === null ? null : signature(def);\n\n    if (key === this.key) {\n      return;\n    }\n\n    const crossfadeMs = opts.crossfadeMs ?? this.opts.crossfadeMs ?? DEFAULT_CROSSFADE_MS;\n    const previous = this.scape;\n    // Only a soundscape that is actually playing is crossfaded from.\n    const crossfading = previous?.isRunning ?? false;\n\n    previous?.dispose({ fadeOutMs: crossfadeMs });\n    this.key = key;\n    this.scape = def === null ? null : new Soundscape(def, this.bus, this.opts);\n\n    if (this.scape && !this.hidden) {\n      this.scape.start(crossfading ? { fadeInMs: crossfadeMs } : {});\n    }\n  }\n\n  /** Fade out and forget the current soundscape. */\n  stop(opts: { fadeOutMs?: number } = {}) {\n    this.scape?.dispose(opts);\n    this.scape = null;\n    this.key = null;\n  }\n\n  /** The soundscape playing now, for `fire`, `suppressEmitters` or `setBedGain`. */\n  get current() {\n    return this.scape;\n  }\n\n  dispose(opts: { fadeOutMs?: number } = {}) {\n    if (this.disposed) {\n      return;\n    }\n\n    this.stop(opts);\n    this.disposed = true;\n\n    if (typeof document !== \"undefined\") {\n      document.removeEventListener(\"visibilitychange\", this.onVisibility);\n    }\n  }\n}\n\nexport { SoundscapePlayer };\nexport type { SoundscapePlayerOptions };\n"],"mappings":"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"}

package/dist/player-CepoDB_J.d.ts

@@ -0,0 +1,112 @@
+import { a as SoundscapeBus, o as SoundscapeDef, s as SoundscapeOptions } from "./types-BML2s2Se.js";
+//#region src/core/soundscape.d.ts
+/**
+ * A soundscape: one looping bed under emitters that fire on their own random timers, each fire
+ * with a fresh sample (never the last one), volume, rate and pan. A concurrency cap drops fires
+ * that would muddy the mix. Every audio call goes through a `SoundscapeBus`, so the engine runs on
+ * Howler, raw Web Audio or a fake in a test.
+ *
+ * `start` and `stop` can alternate any number of times; `dispose` is final and safe to call twice.
+ * Every timer checks a disposed flag before it fires or re-arms, so a timer queued before a
+ * teardown (React StrictMode, a scene swap in the same tick) does nothing.
+ */
+declare class Soundscape<Id = unknown> {
+  readonly def: SoundscapeDef;
+  private readonly bus;
+  private readonly random;
+  private readonly timers;
+  private readonly onEmitter;
+  private readonly emitters;
+  /** Live emitter voices, ours only: a bus shared with another soundscape keeps its voices. */
+  private readonly live;
+  private bedId;
+  private bedGain;
+  private running;
+  private disposed;
+  private suppressed;
+  constructor(def: SoundscapeDef, bus: SoundscapeBus<Id>, opts?: SoundscapeOptions);
+  /** Fade the bed in and arm the emitters. Does nothing while running or once disposed. */
+  start(opts?: {
+    fadeInMs?: number;
+  }): void;
+  /** Fade the bed out and cut the emitters. `start` brings it all back. */
+  stop(opts?: {
+    fadeOutMs?: number;
+  }): void;
+  /** Stop for good. Safe to call twice; `start` does nothing afterwards. */
+  dispose(opts?: {
+    fadeOutMs?: number;
+  }): void;
+  /**
+   * Hold the emitters back, for dialog or narration: one-shots compete with a voice line and with
+   * screen readers even when ducked. Voices already playing fade out; the timers keep ticking and
+   * fires resume when lifted. The bed plays on (duck it through the adapter if it should dip).
+   */
+  suppressEmitters(suppressed: boolean, opts?: {
+    fadeOutMs?: number;
+  }): void;
+  /**
+   * Fire one emitter now, by name or index, whether or not the soundscape is running. Still
+   * respects the cap. Returns whether a voice started. For debug panels and tests.
+   */
+  fire(emitter: string | number): boolean;
+  /** Scale the bed's volume, for a scene that wants it lower or a debug slider. Kept across restarts. */
+  setBedGain(gain: number, opts?: {
+    fadeMs?: number;
+  }): void;
+  get isRunning(): boolean;
+  get isDisposed(): boolean;
+  get emittersSuppressed(): boolean;
+  /** Emitter voices playing right now. */
+  get liveEmitters(): number;
+  get emitterNames(): readonly string[];
+  /** Schedule the next fire; `share` scales the interval, for the first one. */
+  private arm;
+  private disarm;
+  private play;
+  private release;
+  private cutEmitters;
+}
+//#endregion
+//#region src/core/player.d.ts
+type SoundscapePlayerOptions = SoundscapeOptions & {
+  /** Swap time between two soundscapes: the old bed fades out while the new one fades in. Default 1000. */
+  crossfadeMs?: number;
+  /**
+   * `"stop"` (default) fades the soundscape out while the tab is hidden and back in when it
+   * returns, so a background tab doesn't play to itself. `"play"` leaves it alone.
+   */
+  whenHidden?: "stop" | "play";
+};
+/**
+ * Plays one soundscape at a time over a bus and swaps between them: `play(def)` starts it, a
+ * different def crossfades to it, the same def again (by content, not identity) does nothing, and
+ * `play(null)` fades out. It also follows tab visibility. This is what a scene manager or a React
+ * effect wants; use `Soundscape` directly for full control.
+ */
+declare class SoundscapePlayer<Id = unknown> {
+  private readonly bus;
+  private readonly opts;
+  private scape;
+  private key;
+  private hidden;
+  private disposed;
+  private readonly onVisibility;
+  constructor(bus: SoundscapeBus<Id>, opts?: SoundscapePlayerOptions);
+  /** Play `def`, crossfading from whatever plays now. `null` fades out. */
+  play(def: SoundscapeDef | null, opts?: {
+    crossfadeMs?: number;
+  }): void;
+  /** Fade out and forget the current soundscape. */
+  stop(opts?: {
+    fadeOutMs?: number;
+  }): void;
+  /** The soundscape playing now, for `fire`, `suppressEmitters` or `setBedGain`. */
+  get current(): Soundscape<Id> | null;
+  dispose(opts?: {
+    fadeOutMs?: number;
+  }): void;
+}
+//#endregion
+export { SoundscapePlayerOptions as n, Soundscape as r, SoundscapePlayer as t };
+//# sourceMappingURL=player-CepoDB_J.d.ts.map

package/dist/react.d.ts

@@ -0,0 +1,23 @@
+import { a as SoundscapeBus, o as SoundscapeDef } from "./types-BML2s2Se.js";
+import { n as SoundscapePlayerOptions, t as SoundscapePlayer } from "./player-CepoDB_J.js";
+//#region src/react/index.d.ts
+type UseSoundscapeOptions = SoundscapePlayerOptions & {
+  /** `false` fades the soundscape out, `true` brings it back. Default true. */
+  active?: boolean;
+};
+/**
+ * Play `def` on `bus` while mounted and `active`. A new def crossfades; a def with the same
+ * content is the same soundscape, so an inline object literal doesn't restart the bed every
+ * render. StrictMode-safe. Returns the player once mounted, for `current.fire()` and friends.
+ * `random`, `timers` and `whenHidden` are read when the bus changes.
+ */
+declare const useSoundscape: <Id>(bus: SoundscapeBus<Id>, def: SoundscapeDef | null, opts?: UseSoundscapeOptions) => SoundscapePlayer<Id> | null;
+type SoundscapeRunnerProps<Id> = UseSoundscapeOptions & {
+  bus: SoundscapeBus<Id>;
+  def: SoundscapeDef | null;
+};
+/** `useSoundscape` as a component, for JSX that reads as the scene. Renders nothing. */
+declare const SoundscapeRunner: <Id>({ bus, def, ...opts }: SoundscapeRunnerProps<Id>) => null;
+//#endregion
+export { SoundscapeRunner, type SoundscapeRunnerProps, type UseSoundscapeOptions, useSoundscape };
+//# sourceMappingURL=react.d.ts.map

package/dist/react.js

@@ -0,0 +1,52 @@
+import { t as SoundscapePlayer } from "./player-BlQ9UyoK.js";
+import { useEffect, useRef, useState } from "react";
+//#region src/react/index.tsx
+/**
+* @zkmake/sound-scape/react: a hook and a component that render nothing. Audio is a side effect of
+* the scene, never part of the render tree; with React Three Fiber, put them outside `<Canvas>`.
+*/
+/**
+* Play `def` on `bus` while mounted and `active`. A new def crossfades; a def with the same
+* content is the same soundscape, so an inline object literal doesn't restart the bed every
+* render. StrictMode-safe. Returns the player once mounted, for `current.fire()` and friends.
+* `random`, `timers` and `whenHidden` are read when the bus changes.
+*/
+const useSoundscape = (bus, def, opts = {}) => {
+	const [player, setPlayer] = useState(null);
+	const live = useRef(null);
+	const latest = useRef(opts);
+	useEffect(() => {
+		latest.current = opts;
+	});
+	useEffect(() => {
+		const { random, timers, whenHidden, crossfadeMs } = latest.current;
+		const created = new SoundscapePlayer(bus, {
+			random,
+			timers,
+			whenHidden,
+			crossfadeMs,
+			onEmitter: (event) => latest.current.onEmitter?.(event)
+		});
+		live.current = created;
+		setPlayer(created);
+		return () => {
+			created.dispose();
+			live.current = null;
+		};
+	}, [bus]);
+	const active = opts.active ?? true;
+	const crossfadeMs = opts.crossfadeMs;
+	useEffect(() => {
+		live.current?.play(active ? def : null, { crossfadeMs });
+	});
+	return player;
+};
+/** `useSoundscape` as a component, for JSX that reads as the scene. Renders nothing. */
+const SoundscapeRunner = ({ bus, def, ...opts }) => {
+	useSoundscape(bus, def, opts);
+	return null;
+};
+//#endregion
+export { SoundscapeRunner, useSoundscape };
+
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","names":[],"sources":["../src/react/index.tsx"],"sourcesContent":["/**\n * @zkmake/sound-scape/react: a hook and a component that render nothing. Audio is a side effect of\n * the scene, never part of the render tree; with React Three Fiber, put them outside `<Canvas>`.\n */\nimport { useEffect, useRef, useState } from \"react\";\n\nimport { SoundscapePlayer, type SoundscapePlayerOptions } from \"../core/player.ts\";\nimport { type SoundscapeBus, type SoundscapeDef } from \"../core/types.ts\";\n\ntype UseSoundscapeOptions = SoundscapePlayerOptions & {\n  /** `false` fades the soundscape out, `true` brings it back. Default true. */\n  active?: boolean;\n};\n\n/**\n * Play `def` on `bus` while mounted and `active`. A new def crossfades; a def with the same\n * content is the same soundscape, so an inline object literal doesn't restart the bed every\n * render. StrictMode-safe. Returns the player once mounted, for `current.fire()` and friends.\n * `random`, `timers` and `whenHidden` are read when the bus changes.\n */\nconst useSoundscape = <Id,>(\n  bus: SoundscapeBus<Id>,\n  def: SoundscapeDef | null,\n  opts: UseSoundscapeOptions = {},\n) => {\n  const [player, setPlayer] = useState<SoundscapePlayer<Id> | null>(null);\n  const live = useRef<SoundscapePlayer<Id> | null>(null);\n  const latest = useRef(opts);\n\n  // First, so the effects below see this render's options.\n  useEffect(() => {\n    latest.current = opts;\n  });\n\n  useEffect(() => {\n    const { random, timers, whenHidden, crossfadeMs } = latest.current;\n    const created = new SoundscapePlayer(bus, {\n      random,\n      timers,\n      whenHidden,\n      crossfadeMs,\n      onEmitter: (event) => latest.current.onEmitter?.(event),\n    });\n\n    live.current = created;\n    setPlayer(created);\n\n    return () => {\n      created.dispose();\n      live.current = null;\n    };\n  }, [bus]);\n\n  const active = opts.active ?? true;\n  const crossfadeMs = opts.crossfadeMs;\n\n  // Every render: `play` compares by content and does nothing when it hasn't changed.\n  useEffect(() => {\n    live.current?.play(active ? def : null, { crossfadeMs });\n  });\n\n  return player;\n};\n\ntype SoundscapeRunnerProps<Id> = UseSoundscapeOptions & {\n  bus: SoundscapeBus<Id>;\n  def: SoundscapeDef | null;\n};\n\n/** `useSoundscape` as a component, for JSX that reads as the scene. Renders nothing. */\nconst SoundscapeRunner = <Id,>({ bus, def, ...opts }: SoundscapeRunnerProps<Id>) => {\n  useSoundscape(bus, def, opts);\n\n  return null;\n};\n\nexport { SoundscapeRunner, useSoundscape };\nexport type { SoundscapeRunnerProps, UseSoundscapeOptions };\n"],"mappings":";;;;;;;;;;;;;AAoBA,MAAM,iBACJ,KACA,KACA,OAA6B,CAAC,MAC3B;CACH,MAAM,CAAC,QAAQ,aAAa,SAAsC,IAAI;CACtE,MAAM,OAAO,OAAoC,IAAI;CACrD,MAAM,SAAS,OAAO,IAAI;CAG1B,gBAAgB;EACd,OAAO,UAAU;CACnB,CAAC;CAED,gBAAgB;EACd,MAAM,EAAE,QAAQ,QAAQ,YAAY,gBAAgB,OAAO;EAC3D,MAAM,UAAU,IAAI,iBAAiB,KAAK;GACxC;GACA;GACA;GACA;GACA,YAAY,UAAU,OAAO,QAAQ,YAAY,KAAK;EACxD,CAAC;EAED,KAAK,UAAU;EACf,UAAU,OAAO;EAEjB,aAAa;GACX,QAAQ,QAAQ;GAChB,KAAK,UAAU;EACjB;CACF,GAAG,CAAC,GAAG,CAAC;CAER,MAAM,SAAS,KAAK,UAAU;CAC9B,MAAM,cAAc,KAAK;CAGzB,gBAAgB;EACd,KAAK,SAAS,KAAK,SAAS,MAAM,MAAM,EAAE,YAAY,CAAC;CACzD,CAAC;CAED,OAAO;AACT;;AAQA,MAAM,oBAAyB,EAAE,KAAK,KAAK,GAAG,WAAsC;CAClF,cAAc,KAAK,KAAK,IAAI;CAE5B,OAAO;AACT"}

package/dist/types-BML2s2Se.d.ts

@@ -0,0 +1,90 @@
+//#region src/core/types.d.ts
+/** `[low, high]`: each fire draws a value uniformly between them. */
+type Range = readonly [number, number];
+/**
+ * The looping layer under the emitters: room tone, wind, traffic. It is never positional (room
+ * tone comes from everywhere) and never silent while the soundscape runs.
+ */
+type BedDef<Sample extends string = string> = {
+  sample: Sample;
+  volume: number;
+  /** Default 500. A bed that starts at full level is heard as a seam. */
+  fadeInMs?: number;
+  /** Default 700. */
+  fadeOutMs?: number;
+};
+/**
+ * Short, non-musical samples fired on a random timer, each fire with its own volume, rate and pan.
+ * Every emitter is its own metronome: it waits a random interval, fires, and re-arms.
+ */
+type EmitterDef<Sample extends string = string> = {
+  /** Used by `fire(name)` and `onEmitter`. Defaults to the emitter's index. */
+  name?: string;
+  /** The pool. A fire picks one at random, never the one this emitter played last. 3–6 is plenty. */
+  samples: readonly Sample[];
+  /** Wait between fires, ms. */
+  intervalMs: Range;
+  /** Default `[0.7, 1]`. */
+  volume?: Range;
+  /** Playback rate. Default `[0.95, 1.05]`: past about ±5% a sample turns chipmunk or sluggish. */
+  rate?: Range;
+  /** Stereo pan, −1..1. Default `[-0.4, 0.4]`. */
+  pan?: Range;
+};
+type SoundscapeDef<Sample extends string = string> = {
+  bed?: BedDef<Sample> | null;
+  emitters?: readonly EmitterDef<Sample>[];
+  /** Emitter voices allowed at once across this soundscape. A fire past the cap is dropped, not queued. Default 4. */
+  maxConcurrent?: number;
+};
+/**
+ * Everything the engine asks of the audio backend: four functions. An adapter (`./howler`,
+ * `./web-audio`, or your own) implements them over its own voices and buses; ducking, muting and
+ * levels are the adapter's business, not the engine's.
+ *
+ * Ids are the adapter's own; the engine only hands them back.
+ */
+type SoundscapeBus<Id = unknown> = {
+  /** Start a looping bed, fading in from silence. `null` when the sample is missing or can't play. */
+  playBed(sample: string, opts: {
+    volume: number;
+    fadeInMs: number;
+  }): Id | null;
+  /**
+   * Start a one-shot. Call `onEnd` once when it finishes by itself; a voice stopped through
+   * `stop` need not call it. `null` when it can't play: the fire is skipped.
+   */
+  playEmitter(sample: string, opts: {
+    volume: number;
+    rate: number;
+    pan: number;
+    onEnd: () => void;
+  }): Id | null;
+  /**
+   * Fade a voice to silence over `fadeOutMs` (0: at once), then stop it. Must forget the id
+   * synchronously, so a fade in flight survives a dispose that follows.
+   */
+  stop(id: Id, fadeOutMs: number): void;
+  /** Move a live voice's volume (before any bus level or duck), over `fadeMs`. */
+  setVolume(id: Id, volume: number, fadeMs: number): void;
+};
+/** `setTimeout`'s shape, so a test can drive time by hand. */
+type Timers = {
+  set(callback: () => void, ms: number): unknown;
+  clear(handle: unknown): void;
+};
+type EmitterPhase = "start" | "end";
+type SoundscapeOptions = {
+  /** `Math.random`'s shape. Pass `seededRandom(n)` for a soundscape that plays the same way each time. */
+  random?: () => number;
+  timers?: Timers;
+  /** Called when an emitter voice starts and when it ends. For captions, debug panels or tests. */
+  onEmitter?: (event: {
+    emitter: string;
+    sample: string;
+    phase: EmitterPhase;
+  }) => void;
+};
+//#endregion
+export { SoundscapeBus as a, Timers as c, Range as i, EmitterDef as n, SoundscapeDef as o, EmitterPhase as r, SoundscapeOptions as s, BedDef as t };
+//# sourceMappingURL=types-BML2s2Se.d.ts.map

package/dist/web-audio.d.ts

@@ -0,0 +1,21 @@
+import { i as SoundscapeAdapter, n as LoadOptions, r as SampleSource, t as DuckOptions } from "./adapter-D8cYn0vs.js";
+//#region src/web-audio/index.d.ts
+type WebAudioBusOptions = {
+  /** Share the game's context. Default: one made on first use, closed on `dispose`. */
+  context?: AudioContext;
+  /** Where the bus ends up. Default: the context's destination. */
+  destination?: AudioNode;
+  /** Bus level. Default 1; above 1 is allowed. */
+  level?: number;
+  muted?: boolean;
+  duck?: DuckOptions;
+  /** Resume the context on the first pointer or key press, and again after an interruption. Default true. */
+  autoUnlock?: boolean;
+};
+declare const createWebAudioBus: <Sample extends string>(samples: Record<Sample, SampleSource>, opts?: WebAudioBusOptions) => SoundscapeAdapter<number> & {
+  /** The context, made on first access. */
+  readonly context: AudioContext;
+};
+//#endregion
+export { type DuckOptions, type LoadOptions, type SampleSource, type SoundscapeAdapter, type WebAudioBusOptions, createWebAudioBus };
+//# sourceMappingURL=web-audio.d.ts.map