narraleaf-react 0.23.0 → 0.23.1

package/dist/game/nlcore/common/game.d.ts

@@ -3,11 +3,11 @@ import { GameState } from "../../player/gameState";
 import { Storable, Namespace } from "../elements/persistent/storable";
 import { LiveGame } from "../game/liveGame";
 import { Preference } from "../game/preference";
-import { AudioBusError, AudioBusMixer, AudioBusTree, DefaultAudioBusIds, MaxAudioBusDepth, acceptsAudioBus, getActiveAudioBusTree } from "../game/audioBus";
-import type { AudioBusDeclaration, AudioBusNode, AudioBusState } from "../game/audioBus";
+import { AudioBusError, AudioBusMixer, AudioBusTree, DefaultAudioBusIds, MaxAudioBusDepth, SeededBusPreferenceKeys, acceptsAudioBus, getActiveAudioBusTree } from "../game/audioBus";
+import type { AudioBusAlias, AudioBusDeclaration, AudioBusNode, AudioBusState } from "../game/audioBus";
 import type { StorableChange, StorableRestore } from "../elements/persistent/storable";
 import type { SavedGame } from "../gameTypes";
 import type { StackSnapshot, StackFrameSnapshot } from "../action/stackModel";
 import { KeyMap } from "../game/keyMap";
-export { LiveGame, GameState, Game, Storable, Namespace, Preference, KeyMap, AudioBusError, AudioBusMixer, AudioBusTree, DefaultAudioBusIds, MaxAudioBusDepth, acceptsAudioBus, getActiveAudioBusTree, };
-export type { AudioBusDeclaration, AudioBusNode, AudioBusState, SavedGame, StackSnapshot, StackFrameSnapshot, StorableChange, StorableRestore, };
+export { LiveGame, GameState, Game, Storable, Namespace, Preference, KeyMap, AudioBusError, AudioBusMixer, AudioBusTree, DefaultAudioBusIds, MaxAudioBusDepth, SeededBusPreferenceKeys, acceptsAudioBus, getActiveAudioBusTree, };
+export type { AudioBusAlias, AudioBusDeclaration, AudioBusNode, AudioBusState, SavedGame, StackSnapshot, StackFrameSnapshot, StorableChange, StorableRestore, };

package/dist/game/nlcore/game/audioBus.d.ts

@@ -174,6 +174,33 @@ export declare function acceptsAudioBus(busId: string, ancestorIds: readonly str
 type AudioBusEvents = {
     "event:audioBus.volumeChange": [string, number, number];
 };
+/**
+ * Somewhere other than the mixer that already stores a bus's player volume.
+ *
+ * There is exactly one of these in the engine: the three volume preferences. `voiceVolume` is not
+ * a number that gets *copied* onto the voice bus, it **is** the voice bus's player volume, reached
+ * through this. A bus with an alias has no entry in the mixer's own map at all, so there is one
+ * store and one writer and nothing can overwrite anything.
+ *
+ * Structural on purpose - `audioBus.ts` stays free of imports, and a test can hand it a real
+ * `Preference` and exercise exactly what `Game` wires up.
+ */
+export type AudioBusAlias = {
+    get(): number;
+    set(volume: number): void;
+    /** Fires when the backing store changes by any route, including one that bypasses the mixer. */
+    subscribe(listener: (volume: number) => void): {
+        cancel: () => void;
+    };
+};
+/**
+ * The preference key that *is* each seeded bus's player volume.
+ */
+export declare const SeededBusPreferenceKeys: {
+    readonly bgm: "bgmVolume";
+    readonly sound: "soundVolume";
+    readonly voice: "voiceVolume";
+};
 /**
  * The per-game mixer: the declared tree, plus what the player has done to it.
  *
@@ -200,14 +227,22 @@ export declare class AudioBusMixer {
         readonly "event:audioBus.volumeChange": "event:audioBus.volumeChange";
     };
     readonly events: EventDispatcher<AudioBusEvents>;
-    /** The player's half. Absent means "untouched", which is 1 — not 0, and not the declaration. */
+    /**
+     * The player's half, for buses that do not have an alias. Absent means "untouched", which is
+     * 1 — not 0, and not the declaration.
+     */
     private readonly overrides;
+    private readonly aliases;
+    private readonly aliasTokens;
     private tree;
     /**
      * @param declarations - Read lazily, so a host that calls `configure()` between constructing
      * the `Game` and mounting the player still gets the tree it declared.
+     * @param aliases - Buses whose player volume is stored somewhere else, by bus id. See
+     * {@link AudioBusAlias}; in the engine this is the three volume preferences and nothing else.
      */
-    constructor(declarations: () => readonly AudioBusDeclaration[]);
+    constructor(declarations: () => readonly AudioBusDeclaration[], aliases?: Record<string, AudioBusAlias>);
+    private announce;
     /**
      * The resolved tree, resolving it on first use and caching it afterwards.
      *
@@ -244,6 +279,10 @@ export declare class AudioBusMixer {
      * A bus the player has never touched reads 1 whatever the author declared, which is what makes
      * a slider bound to this sit at maximum on a fresh install and what makes the persisted value
      * mean "what the player did" rather than "what the game shipped with".
+     *
+     * For the three seeded buses this reads the corresponding volume preference, because that
+     * preference *is* this number. `mixer.getVolume("voice")` and `getPreference("voiceVolume")`
+     * cannot disagree; there is only one of them.
      */
     getVolume(id: string): number;
     /**

package/dist/game/nlcore/game.d.ts

@@ -74,17 +74,18 @@ export declare class Game {
      * at any point after `new Game(...)` is safe; if the channels do not exist yet the value is
      * applied the moment they do.
      *
-     * The four volume preferences (`bgmVolume`, `soundVolume`, `voiceVolume`, `globalVolume`) are
-     * unchanged and keep working: the first three are aliases onto the seeded buses of the same
-     * name and write the *player's* half, so their default of 1 no longer overwrites a declared
-     * mix. Drive the seeded three through the preferences, and use this for buses the host
-     * declared.
+     * `bgmVolume`, `soundVolume` and `voiceVolume` **are** the player's half of the three seeded
+     * buses — not numbers copied onto them. `game.audioBuses.getVolume("voice")` and
+     * `game.preference.getPreference("voiceVolume")` read the same storage and cannot disagree,
+     * and writing either drives the audio graph immediately, mounted or not. Both surfaces stay
+     * supported; use whichever suits, and use this one for buses the host declared.
+     * (`globalVolume` is the master output, not a bus, and is unchanged.)
      *
      * @example
      * ```ts
      * // persist the player's half only - the author's mix comes back with the game
      * localStorage.setItem("mixer", JSON.stringify(game.audioBuses.getVolumes()));
-     * // restore, any time after `new Game(...)`
+     * // restore, any time after `new Game(...)` - no ordering requirement, seeded or not
      * game.audioBuses.setVolumes(JSON.parse(localStorage.getItem("mixer") ?? "{}"));
      * ```
      */

package/dist/game/player/elements/player/PreferenceUpdateAnnouncer.d.ts

@@ -1,11 +1,17 @@
 import { GameState } from "../../../../game/nlcore/common/game";
 /**
- * The three volume preferences drive the three seeded buses.
+ * Carries `globalVolume` — and only `globalVolume` — from the preferences to the audio subsystem.
  *
- * This is the whole of the alias: a preference is what a player's slider writes to, a bus is what
- * the audio graph reads, and one pushes into the other. Buses the host declared are not
- * preferences and are driven through `game.audioBuses` instead - `GamePreference` is a closed
- * object type and cannot grow a key per character.
+ * The three *bus* volumes used to be pushed from here too, one `useEffect` each. They are gone, and
+ * their absence is the point: `bgmVolume`/`soundVolume`/`voiceVolume` **are** the player's half of
+ * the three seeded buses now, read straight through by `game.audioBuses`, so there is nothing left
+ * to copy. Copying them from a mounted component is what broke the feature twice — the effects fire
+ * on mount with whatever the preference happens to hold, which erased first the author's declared
+ * mix and then a player override the host had restored a moment earlier. It also meant a preference
+ * written while no player was mounted reached the graph only on the next mount.
+ *
+ * `globalVolume` stays because it is the master output rather than a bus — it has no declared half
+ * and no gain node in the tree.
  */
 export default function PreferenceUpdateAnnouncer({ gameState }: Readonly<{
     gameState: GameState;

package/dist/game/player/lib/AudioManager.d.ts

@@ -263,19 +263,4 @@ export declare class AudioManager {
     setGlobalVolume(volume: number): void;
     getGlobalVolume(): number;
     destroy(): void;
-    /**
-     * The three volume preferences are aliases onto the three seeded buses, and this is the alias.
-     *
-     * They stay the way a player's music/sfx/voice sliders are driven - widening the preference key
-     * union to cover arbitrary bus ids is not possible without reshaping `GamePreference`, and is
-     * not needed: a host bus is driven through {@link AudioManager.setBusVolume} instead.
-     *
-     * They write the **player's** half only. This used to write the bus's whole gain, and because
-     * these preferences default to 1 it meant that a host declaring `{id: "sound", volume: 0.6}`
-     * had its mix silently overwritten with 1 the moment the audio subsystem started - the author
-     * set SFX to 60% and every player heard 100%. Custom buses were unaffected because nothing
-     * aliases them, so the three buses every existing project uses were the only ones that ignored
-     * the declaration. Now `soundVolume: 1` means "do not attenuate further" and 0.6 survives.
-     */
-    private setupGroupVolume;
 }