@hadoku/ui-shell 0.0.0-stage → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/LICENSE +21 -0
  2. package/dist/app-id/index.d.ts +4 -0
  3. package/dist/app-id/index.js +14 -0
  4. package/dist/chrome/AppChrome.d.ts +9 -0
  5. package/dist/chrome/AppChrome.js +201 -0
  6. package/dist/chrome/chrome.css +336 -0
  7. package/dist/chrome/index.d.ts +3 -0
  8. package/dist/chrome/index.js +3 -0
  9. package/dist/chrome/matchMedia.d.ts +2 -0
  10. package/dist/chrome/matchMedia.js +51 -0
  11. package/dist/chrome/shell.d.ts +17 -0
  12. package/dist/chrome/shell.js +47 -0
  13. package/dist/chrome/trim.css +334 -0
  14. package/dist/components/Reveal.d.ts +20 -0
  15. package/dist/components/Reveal.js +38 -0
  16. package/dist/components/index.d.ts +1 -0
  17. package/dist/components/index.js +7 -0
  18. package/dist/components/reveal.css +110 -0
  19. package/dist/embed/index.d.ts +1 -0
  20. package/dist/embed/index.js +1 -0
  21. package/dist/embed/styles.d.ts +4 -0
  22. package/dist/embed/styles.js +49 -0
  23. package/dist/motion/index.d.ts +6 -0
  24. package/dist/motion/index.js +8 -0
  25. package/dist/settings/index.d.ts +1 -0
  26. package/dist/settings/index.js +1 -0
  27. package/dist/settings/ui-scale.d.ts +45 -0
  28. package/dist/settings/ui-scale.js +142 -0
  29. package/dist/sound/GainSlider.d.ts +6 -0
  30. package/dist/sound/GainSlider.js +15 -0
  31. package/dist/sound/index.d.ts +65 -0
  32. package/dist/sound/index.js +204 -0
  33. package/dist/sound/mix.d.ts +69 -0
  34. package/dist/sound/mix.js +117 -0
  35. package/dist/sound/mixer.d.ts +37 -0
  36. package/dist/sound/mixer.js +301 -0
  37. package/dist/sound/mute.d.ts +62 -0
  38. package/dist/sound/mute.js +250 -0
  39. package/dist/sound/queue.d.ts +32 -0
  40. package/dist/sound/queue.js +80 -0
  41. package/dist/theme/index.d.ts +18 -0
  42. package/dist/theme/index.js +41 -0
  43. package/dist/trim/index.d.ts +2 -0
  44. package/dist/trim/index.js +2 -0
  45. package/dist/trim/siteTrim.d.ts +23 -0
  46. package/dist/trim/siteTrim.js +91 -0
  47. package/dist/trim/trim.d.ts +72 -0
  48. package/dist/trim/trim.js +63 -0
  49. package/dist/usage/index.d.ts +32 -0
  50. package/dist/usage/index.js +84 -0
  51. package/package.json +70 -4
  52. package/README.md +0 -3
@@ -0,0 +1,117 @@
1
+ /*
2
+ * What a sound event turns into, decided without an audio device.
3
+ *
4
+ * A `SoundEvent` names a role from the game's injected role registry
5
+ * (never imported by id), optionally a layer cell to mix on top (the
6
+ * game's to define), and whose seat it came from. `plan` says which takes
7
+ * play, how loud and on which bus, or why one stayed silent; an id the
8
+ * registry lacks plans nothing.
9
+ *
10
+ * Rules: role and layer each play if either has a take; the opponent's
11
+ * `ui` roles never play, their others quieter; the same cell from the same
12
+ * seat collapses within `collapseMs`; a multi-take cell varies, never
13
+ * repeating; a `reversed` role plays its target's cell backwards; an empty
14
+ * cell falls back down its `fallback` chain.
15
+ */
16
+ let ambientRegistry = { roles: new Map(), fallback: {}, reversed: {} };
17
+ /** The registry a bare `createMixPlanner()` builds against, for a call site that leans on its default. The game sets this once, with its real roles, before such a call; new code prefers `createSound`. */
18
+ export function configureSoundRoles(registry) {
19
+ ambientRegistry = registry;
20
+ }
21
+ /** A voice's level and playback rate for an event of `intensity`: four fifths and a touch high at 0, a quarter louder and lower at 1. */
22
+ function intensityVoice(intensity) {
23
+ if (intensity === undefined)
24
+ return { gain: 1, rate: 1 };
25
+ const i = Math.min(1, Math.max(0, intensity));
26
+ return { gain: 0.8 + 0.45 * i, rate: 1.06 - 0.16 * i };
27
+ }
28
+ /**
29
+ * Interface sounds sit low: they fire constantly, and one as loud as the
30
+ * game is one a player mutes within a minute.
31
+ */
32
+ export const DEFAULT_MIX = {
33
+ bus: { ui: 0.5, game: 1, colour: 0.9, music: 0.35 },
34
+ opponent: 0.6,
35
+ collapseMs: 80,
36
+ };
37
+ /** Pick one file at random, never the same one twice in a row — unless there is only one to pick. */
38
+ function pickRandom(files, last, rng) {
39
+ if (files.length === 0)
40
+ return null;
41
+ const options = files.length > 1 && last !== null ? files.filter((f) => f !== last) : files;
42
+ const i = Math.floor(rng() * options.length);
43
+ return options[Math.min(i, options.length - 1)] ?? null;
44
+ }
45
+ function cueTakesOf(registry, cells) {
46
+ const isMusic = (cell) => registry.roles.get(cell.slice(0, cell.indexOf('|')))?.bus === 'music';
47
+ return [...new Set(Object.entries(cells).flatMap(([cell, files]) => (isMusic(cell) ? [] : files)))].sort();
48
+ }
49
+ function buildPlanner(registry, rng) {
50
+ let cells = {};
51
+ let gains = {};
52
+ const lastPick = new Map();
53
+ const lastAt = new Map();
54
+ const gainOf = (cell) => gains[cell] ?? 1;
55
+ return {
56
+ setAssignments(c, g) {
57
+ cells = c;
58
+ gains = g;
59
+ },
60
+ gainOf,
61
+ has: (cell) => (cells[cell]?.length ?? 0) > 0,
62
+ takes: (cell) => cells[cell] ?? [],
63
+ cueTakes: () => cueTakesOf(registry, cells),
64
+ plan(event, nowMs, settings) {
65
+ const seat = event.seat ?? 'me';
66
+ const reversedFrom = registry.reversed[event.role];
67
+ let played = reversedFrom ?? event.role;
68
+ while ((cells[`${played}|play`]?.length ?? 0) === 0 && registry.fallback[played] !== undefined)
69
+ played = registry.fallback[played];
70
+ const roleCell = `${played}|play`;
71
+ const role = registry.roles.get(reversedFrom ?? event.role);
72
+ if (role === undefined)
73
+ return { voices: [], skipped: [{ cell: roleCell, reason: 'unknown-role' }] };
74
+ if (seat === 'opp' && role.bus === 'ui') {
75
+ return { voices: [], skipped: [{ cell: roleCell, reason: 'opponent-ui' }] };
76
+ }
77
+ const layers = [
78
+ { cell: roleCell, collapse: `${event.role}|play`, bus: role.bus, duck: role.duck === true },
79
+ ];
80
+ if (event.colourCell != null) {
81
+ layers.push({ cell: event.colourCell, collapse: event.colourCell, bus: 'colour', duck: false });
82
+ }
83
+ const result = { voices: [], skipped: [] };
84
+ for (const layer of layers) {
85
+ const key = `${layer.collapse}#${seat}`;
86
+ const prev = lastAt.get(key);
87
+ if (prev !== undefined && nowMs - prev < settings.collapseMs) {
88
+ result.skipped.push({ cell: layer.cell, reason: 'collapsed' });
89
+ continue;
90
+ }
91
+ const file = pickRandom(cells[layer.cell] ?? [], lastPick.get(layer.cell) ?? null, rng);
92
+ if (file === null) {
93
+ result.skipped.push({ cell: layer.cell, reason: 'empty' });
94
+ continue;
95
+ }
96
+ lastAt.set(key, nowMs);
97
+ lastPick.set(layer.cell, file);
98
+ const seatLevel = seat === 'opp' ? settings.opponent : 1;
99
+ const weight = intensityVoice(event.intensity);
100
+ result.voices.push({
101
+ cell: layer.cell,
102
+ file,
103
+ bus: layer.bus,
104
+ gain: gainOf(layer.cell) * settings.bus[layer.bus] * seatLevel * weight.gain,
105
+ duck: layer.duck,
106
+ ...(reversedFrom !== undefined && layer.cell === roleCell ? { reverse: true } : {}),
107
+ ...(weight.rate === 1 ? {} : { rate: weight.rate }),
108
+ });
109
+ }
110
+ return result;
111
+ },
112
+ };
113
+ }
114
+ /** A planner against the game's real roles (`configureSoundRoles`), or against none until something configures one. New code prefers `createSound`. */
115
+ export function createMixPlanner(rng = Math.random) {
116
+ return buildPlanner(ambientRegistry, rng);
117
+ }
@@ -0,0 +1,37 @@
1
+ import { type MixPlanner, type MixSettings, type PlanResult, type SoundEvent } from './mix.js';
2
+ /** Above this many live voices of one cell, a new one is dropped: a combo looped several times must not stack into a wall. */
3
+ export declare const CELL_VOICE_CAP = 2;
4
+ /** What loops: one music role, the first of several that has a take, or nothing. */
5
+ export type MusicChoice = string | readonly string[] | null;
6
+ export interface Mixer {
7
+ readonly planner: MixPlanner;
8
+ settings: MixSettings;
9
+ /** Plan and play one event. The plan comes back at once; audio follows its buffers. */
10
+ play(event: SoundEvent, nowMs?: number): PlanResult;
11
+ /** Audition one take at a level, bypassing roles. */
12
+ playFile(file: string, gain?: number): void;
13
+ /** Decode every cue take the planner holds, from `pack`'s bytes where it has them, fetched one by one otherwise. Music is left to {@link loop}. */
14
+ preload(pack?: ReadonlyMap<string, ArrayBuffer>): void;
15
+ /**
16
+ * Loop a music role on the music bus, crossfading from whatever loops now; `null` fades it out. A
17
+ * list loops the first role that has a take; music waits for the first gesture rather than being
18
+ * dropped. A role with several takes loops `pick`'s choice while its cell still holds it, else one
19
+ * at random; a new pick crossfades to it.
20
+ */
21
+ loop(role: MusicChoice, pick?: (role: string) => string | null): void;
22
+ /** The role looping now and the take it plays, or `null`: what sound settings names as the track. */
23
+ nowPlaying(): {
24
+ role: string;
25
+ file: string;
26
+ } | null;
27
+ /** A cell's takes, as assigned. */
28
+ takes(cell: string): readonly string[];
29
+ /** Loop one take on the music bus, outside any role, crossfading from whatever loops now; `null` fades it out. */
30
+ loopFile(file: string | null): void;
31
+ /** The player's levels (`./mute.ts`), 0..1, applied at once — music too, mid-loop. */
32
+ setLevels(levels: {
33
+ volume: number;
34
+ music: number;
35
+ }): void;
36
+ }
37
+ export declare function createMixer(takeUrl: (file: string) => string, planner?: MixPlanner): Mixer;
@@ -0,0 +1,301 @@
1
+ /*
2
+ * The take mixer: `mix.ts`'s plan, played through WebAudio. One `AudioContext`
3
+ * a game needs. Every voice is one buffer source through one gain node; a
4
+ * ducking voice goes straight to the master and pulls the duck node (every
5
+ * other voice's path) down for its own length. Levels are baked in at
6
+ * start, except the player's own two, which the master and music node
7
+ * take live. Browsers start a context `suspended`, resumable only inside a
8
+ * real gesture, so it installs a one-shot listener and resumes there; a
9
+ * sound asked for before that first gesture is dropped. Fails soft
10
+ * throughout: a take that will not fetch or decode is skipped, never thrown.
11
+ */
12
+ import { createMixPlanner, DEFAULT_MIX } from "./mix.js";
13
+ /** Above this many live voices, a new one is dropped rather than stacked. */
14
+ const VOICE_CAP = 12;
15
+ /** Above this many live voices of one cell, a new one is dropped: a combo looped several times must not stack into a wall. */
16
+ export const CELL_VOICE_CAP = 2;
17
+ /** A sound that could not start within this long of being asked for is dropped, not played late. */
18
+ const STALE_MS = 1500;
19
+ /** Music fades in and out over this long. */
20
+ const MUSIC_FADE_S = 1.5;
21
+ /** The level everything else drops to under a ducking voice. */
22
+ const DUCK_LEVEL = 0.35;
23
+ function unlockOnGesture(ac) {
24
+ const target = globalThis.document;
25
+ if (target === undefined || target === null || ac.state !== 'suspended')
26
+ return;
27
+ const once = () => {
28
+ void ac.resume().catch(() => undefined);
29
+ target.removeEventListener('pointerdown', once, true);
30
+ target.removeEventListener('keydown', once, true);
31
+ target.removeEventListener('touchend', once, true);
32
+ };
33
+ target.addEventListener('pointerdown', once, true);
34
+ target.addEventListener('keydown', once, true);
35
+ target.addEventListener('touchend', once, true);
36
+ }
37
+ export function createMixer(takeUrl, planner = createMixPlanner()) {
38
+ const g = globalThis;
39
+ const Ctor = g.AudioContext ?? g.webkitAudioContext;
40
+ let ctx = null;
41
+ let master = null;
42
+ let duckNode = null;
43
+ let musicNode = null;
44
+ let levels = { volume: 1, music: 1 };
45
+ let live = 0;
46
+ /** Live voices per cell, for {@link CELL_VOICE_CAP}. */
47
+ const liveByCell = new Map();
48
+ let loopRole = null;
49
+ /** The take `loopRole` plays. */
50
+ let loopTake = null;
51
+ let loopVoice = null;
52
+ const buffers = new Map();
53
+ /**
54
+ * The one music take kept decoded: the loop's. Decoded audio is float32 PCM, about 70 MB for three minutes
55
+ * of 48 kHz stereo, so a take the loop has moved off is let go rather than kept beside the cues; a voice
56
+ * still fading out holds its own buffer until it stops.
57
+ */
58
+ let loopBuffer = null;
59
+ const context = () => {
60
+ if (ctx !== null)
61
+ return ctx;
62
+ if (Ctor === undefined)
63
+ return null;
64
+ try {
65
+ ctx = new Ctor();
66
+ }
67
+ catch {
68
+ return null;
69
+ }
70
+ master = ctx.createGain();
71
+ master.gain.value = levels.volume;
72
+ master.connect(ctx.destination);
73
+ duckNode = ctx.createGain();
74
+ duckNode.connect(master);
75
+ musicNode = ctx.createGain();
76
+ musicNode.gain.value = levels.music;
77
+ musicNode.connect(duckNode);
78
+ unlockOnGesture(ctx);
79
+ return ctx;
80
+ };
81
+ const decode = async (ac, file) => {
82
+ try {
83
+ const res = await fetch(takeUrl(file));
84
+ if (!res.ok)
85
+ return null;
86
+ return await ac.decodeAudioData(await res.arrayBuffer());
87
+ }
88
+ catch {
89
+ return null;
90
+ }
91
+ };
92
+ /** A cue's buffer, decoded once and kept for the page's life. */
93
+ const load = (file) => {
94
+ const known = buffers.get(file);
95
+ if (known !== undefined)
96
+ return known;
97
+ const ac = context();
98
+ if (ac === null)
99
+ return Promise.resolve(null);
100
+ const task = decode(ac, file);
101
+ buffers.set(file, task);
102
+ return task;
103
+ };
104
+ /** A music take's buffer, held only while it is the loop's (`loopBuffer`). */
105
+ const loadLoop = (file) => {
106
+ if (loopBuffer?.file === file)
107
+ return loopBuffer.task;
108
+ const ac = context();
109
+ if (ac === null)
110
+ return Promise.resolve(null);
111
+ loopBuffer = { file, task: buffers.get(file) ?? decode(ac, file) };
112
+ return loopBuffer.task;
113
+ };
114
+ /** A take backwards, decoded once: a copy, so the forward buffer still plays forward. */
115
+ const reversed = new Map();
116
+ const loadReversed = (file) => {
117
+ const known = reversed.get(file);
118
+ if (known !== undefined)
119
+ return known;
120
+ const task = load(file).then((buf) => {
121
+ const ac = context();
122
+ if (buf === null || ac === null)
123
+ return null;
124
+ const out = ac.createBuffer(buf.numberOfChannels, buf.length, buf.sampleRate);
125
+ for (let ch = 0; ch < buf.numberOfChannels; ch++)
126
+ out.getChannelData(ch).set(buf.getChannelData(ch).slice().reverse());
127
+ return out;
128
+ });
129
+ reversed.set(file, task);
130
+ return task;
131
+ };
132
+ const duck = (ac, seconds) => {
133
+ if (duckNode === null)
134
+ return;
135
+ const now = ac.currentTime;
136
+ const p = duckNode.gain;
137
+ p.cancelScheduledValues(now);
138
+ p.setValueAtTime(p.value, now);
139
+ p.linearRampToValueAtTime(DUCK_LEVEL, now + 0.03);
140
+ p.setValueAtTime(DUCK_LEVEL, now + Math.min(seconds, 1.2));
141
+ p.linearRampToValueAtTime(1, now + Math.min(seconds, 1.2) + 0.4);
142
+ };
143
+ /** `cell` null: an audition, outside any cell's cap. */
144
+ const start = (cell, file, gain, ducks, reverse = false, rate = 1) => {
145
+ const ac = context();
146
+ if (ac === null)
147
+ return;
148
+ const asked = performance.now();
149
+ // Inside a gesture this unlocks the context; outside one the browser holds it, and the
150
+ // staleness check below drops the sound rather than playing it whenever a gesture comes.
151
+ const ready = ac.state === 'suspended' ? ac.resume().catch(() => undefined) : Promise.resolve();
152
+ void Promise.all([reverse ? loadReversed(file) : load(file), ready]).then(([buf]) => {
153
+ if (ac.state !== 'running' || performance.now() - asked > STALE_MS)
154
+ return;
155
+ if (buf === null || master === null || duckNode === null || live >= VOICE_CAP)
156
+ return;
157
+ if (cell !== null && (liveByCell.get(cell) ?? 0) >= CELL_VOICE_CAP)
158
+ return;
159
+ const src = ac.createBufferSource();
160
+ src.buffer = buf;
161
+ if (rate !== 1)
162
+ src.playbackRate.value = rate;
163
+ const env = ac.createGain();
164
+ env.gain.value = Math.max(gain, 0);
165
+ src.connect(env);
166
+ env.connect(ducks ? master : duckNode);
167
+ if (ducks)
168
+ duck(ac, buf.duration);
169
+ live += 1;
170
+ if (cell !== null)
171
+ liveByCell.set(cell, (liveByCell.get(cell) ?? 0) + 1);
172
+ src.onended = () => {
173
+ live -= 1;
174
+ if (cell !== null) {
175
+ const left = (liveByCell.get(cell) ?? 1) - 1;
176
+ if (left > 0)
177
+ liveByCell.set(cell, left);
178
+ else
179
+ liveByCell.delete(cell);
180
+ }
181
+ src.disconnect();
182
+ env.disconnect();
183
+ };
184
+ src.start();
185
+ });
186
+ };
187
+ const fadeOutLoop = (ac) => {
188
+ loopBuffer = null;
189
+ if (loopVoice === null)
190
+ return;
191
+ const { src, env } = loopVoice;
192
+ loopVoice = null;
193
+ const now = ac.currentTime;
194
+ env.gain.cancelScheduledValues(now);
195
+ env.gain.setValueAtTime(env.gain.value, now);
196
+ env.gain.linearRampToValueAtTime(0, now + MUSIC_FADE_S);
197
+ src.stop(now + MUSIC_FADE_S);
198
+ src.onended = () => {
199
+ src.disconnect();
200
+ env.disconnect();
201
+ };
202
+ };
203
+ /** Loop `file` under `key` once it decodes, unless the loop asked for has changed by then. */
204
+ const startLoop = (key, file, gain) => {
205
+ const ac = context();
206
+ if (ac === null)
207
+ return;
208
+ const ready = ac.state === 'suspended' ? ac.resume().catch(() => undefined) : Promise.resolve();
209
+ void Promise.all([loadLoop(file), ready]).then(([buf]) => {
210
+ if (buf === null || musicNode === null || loopRole !== key || loopTake !== file || loopVoice !== null)
211
+ return;
212
+ const src = ac.createBufferSource();
213
+ src.buffer = buf;
214
+ src.loop = true;
215
+ const env = ac.createGain();
216
+ env.gain.setValueAtTime(0, ac.currentTime);
217
+ env.gain.linearRampToValueAtTime(gain, ac.currentTime + MUSIC_FADE_S);
218
+ src.connect(env);
219
+ env.connect(musicNode);
220
+ src.start();
221
+ loopVoice = { src, env };
222
+ });
223
+ };
224
+ const mixer = {
225
+ planner,
226
+ settings: DEFAULT_MIX,
227
+ play(event, nowMs = performance.now()) {
228
+ const plan = planner.plan(event, nowMs, mixer.settings);
229
+ for (const v of plan.voices)
230
+ start(v.cell, v.file, v.gain, v.duck, v.reverse === true, v.rate ?? 1);
231
+ return plan;
232
+ },
233
+ playFile(file, gain = 1) {
234
+ start(null, file, gain, false);
235
+ },
236
+ preload(pack) {
237
+ const ac = context();
238
+ if (ac === null)
239
+ return;
240
+ for (const f of planner.cueTakes()) {
241
+ const bytes = pack?.get(f);
242
+ if (bytes === undefined)
243
+ void load(f);
244
+ else if (!buffers.has(f))
245
+ buffers.set(f, ac.decodeAudioData(bytes).catch(() => null));
246
+ }
247
+ },
248
+ loop(choice, pick) {
249
+ const roles = choice === null ? [] : typeof choice === 'string' ? [choice] : choice;
250
+ const role = roles.find((r) => planner.has(`${r}|play`)) ?? null;
251
+ const wanted = role === null ? null : (pick?.(role) ?? null);
252
+ const picked = wanted !== null && planner.takes(`${role}|play`).includes(wanted) ? wanted : null;
253
+ if (role === loopRole && (picked === null || picked === loopTake))
254
+ return;
255
+ loopRole = role;
256
+ loopTake = null;
257
+ if (ctx !== null)
258
+ fadeOutLoop(ctx);
259
+ if (role === null)
260
+ return;
261
+ if (picked !== null) {
262
+ loopTake = picked;
263
+ startLoop(role, picked, planner.gainOf(`${role}|play`) * mixer.settings.bus.music);
264
+ return;
265
+ }
266
+ const voice = planner.plan({ role }, performance.now(), mixer.settings).voices[0];
267
+ if (voice === undefined) {
268
+ // Planned nothing (asked again within the collapse window): asking again
269
+ // later must try again, and nothing is built for it.
270
+ loopRole = null;
271
+ return;
272
+ }
273
+ loopTake = voice.file;
274
+ startLoop(role, voice.file, voice.gain);
275
+ },
276
+ loopFile(file) {
277
+ const key = file === null ? null : `file:${file}`;
278
+ if (key === loopRole)
279
+ return;
280
+ loopRole = key;
281
+ loopTake = file;
282
+ if (ctx !== null)
283
+ fadeOutLoop(ctx);
284
+ if (key === null || file === null)
285
+ return;
286
+ startLoop(key, file, 1);
287
+ },
288
+ takes: (cell) => planner.takes(cell),
289
+ nowPlaying() {
290
+ return loopRole === null || loopTake === null || loopRole.startsWith('file:') ? null : { role: loopRole, file: loopTake };
291
+ },
292
+ setLevels(next) {
293
+ levels = next;
294
+ if (master !== null)
295
+ master.gain.value = next.volume;
296
+ if (musicNode !== null)
297
+ musicNode.gain.value = next.music;
298
+ },
299
+ };
300
+ return mixer;
301
+ }
@@ -0,0 +1,62 @@
1
+ import { z } from 'zod';
2
+ import { type GamesPrefs } from '@wolffm/prefs-client/platform';
3
+ /** `volume` scales everything; `music` scales the music bus under it. Both 0..1. */
4
+ export type LevelName = 'volume' | 'music';
5
+ /** A level nobody has set: the music starts at half, under the game's own sounds; everything else full. */
6
+ export declare const LEVEL_DEFAULTS: Readonly<Record<LevelName, number>>;
7
+ export declare const SoundPrefsSchema: z.ZodObject<{
8
+ music: z.ZodOptional<z.ZodNumber>;
9
+ musicPicks: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
10
+ }, z.core.$strict>;
11
+ export type SoundPrefs = z.infer<typeof SoundPrefsSchema>;
12
+ /** The `localStorage` keys the values lived in before the service held them, built from `appId()`. Called lazily — never at module load — so importing this before `configureShell` runs does not throw. */
13
+ export declare function legacyKeys(): Readonly<{
14
+ muted: string;
15
+ volume: string;
16
+ music: string;
17
+ musicPicks: string;
18
+ }>;
19
+ type Listener = () => void;
20
+ /** Whether sounds are currently silenced. */
21
+ export declare function isMuted(): boolean;
22
+ /** Set the preference, save it, and tell every subscriber. */
23
+ export declare function setMuted(value: boolean): void;
24
+ /** A level, 0..1. */
25
+ export declare function getLevel(name: LevelName): number;
26
+ /** Set a level, save it, and tell every subscriber. */
27
+ export declare function setLevel(name: LevelName, value: number): void;
28
+ /** The take the player chose for a music role, or `null` for none chosen. */
29
+ export declare function getMusicPick(role: string): string | null;
30
+ /** Choose a music role's track, save it, and tell every subscriber. */
31
+ export declare function setMusicPick(role: string, file: string): void;
32
+ /**
33
+ * Subscribe to any change: mute, a level or a music pick. Returns the unsubscribe.
34
+ *
35
+ * Shaped for `useSyncExternalStore`: two controls on one page must agree,
36
+ * and a React component must not read a mutable module global during
37
+ * render without a subscription. Another tab's change arrives through the
38
+ * service's own broadcast and lands here.
39
+ */
40
+ export declare function subscribeSound(fn: Listener): () => void;
41
+ /** Whatever the old `<appId>.sound.*` keys still hold, parsed; anything unreadable is absent. */
42
+ export declare function readLegacy(store?: Storage | undefined): GamesPrefs & SoundPrefs;
43
+ /**
44
+ * Connect the sound settings to the preference service for as long as the calling component is
45
+ * mounted: adopt what it holds, follow its changes (another tab, another host on the page), and
46
+ * save every change made here. The first time a page connects, a value only the old keys hold is
47
+ * saved to the service and the keys are removed. `ready` settles once the service's first answer
48
+ * is adopted.
49
+ */
50
+ export declare function connectSoundPrefs(): {
51
+ ready: Promise<void>;
52
+ disconnect: () => void;
53
+ };
54
+ /** `connectSoundPrefs` for the life of the component that calls it: the app's root, standalone or embedded. */
55
+ export declare function useSoundPrefs(): void;
56
+ /**
57
+ * Back to the defaults, disconnected, with no subscribers.
58
+ *
59
+ * For tests, which start each case from a fresh page. Production never calls it.
60
+ */
61
+ export declare function resetMutedForTests(): void;
62
+ export {};