@genesislcap/pbc-notify-ui 15.8.3 → 15.9.0

package/src/utils/alert-sound.ts

@@ -0,0 +1,1135 @@
+import { showNotification } from '@genesislcap/foundation-notifications';
+import debounce from 'lodash.debounce';
+import { logger } from './logger';
+
+const DB_NAME = 'pbc-notify-ui';
+const DB_VERSION = 1;
+const STORE_NAME = 'alert-sound';
+/** Match config (no audio) for every active rule — cheap to rewrite on every edit. */
+const RULES_KEY = 'user-alert-sound-rules';
+/** Global volume / mute for all alert sounds. */
+const SETTINGS_KEY = 'user-alert-sound-settings';
+/** Per-rule audio, keyed by the rule's sticky id (`user-alert-sound-audio:1` … `:10`). */
+const AUDIO_KEY_PREFIX = 'user-alert-sound-audio:';
+
+/** Maximum number of sound rules (MESSAGE/HEADER pattern, or notification rule). */
+export const MAX_SOUND_RULES = 10;
+
+/** Slider and display use whole percents. */
+const VOLUME_PERCENT_MAX = 100;
+/** Default playback level (100%). */
+const DEFAULT_VOLUME = 1;
+
+function audioKey(ruleId: string): string {
+  return `${AUDIO_KEY_PREFIX}${ruleId}`;
+}
+
+/** Sticky ids `1`…`MAX_SOUND_RULES` — stay with the rule, not its list position. */
+function allRuleIds(): string[] {
+  return Array.from({ length: MAX_SOUND_RULES }, (_, index) => String(index + 1));
+}
+
+const BYTES_PER_KB = 1024;
+const BYTES_PER_MB = BYTES_PER_KB * BYTES_PER_KB;
+/** Rounds megabyte sizes to one decimal place for display. */
+const MB_PRECISION = 10;
+
+/**
+ * Every rule's audio is held in one IndexedDB row, so a generous per-file limit
+ * still risks the origin storage quota once multiplied by {@link MAX_SOUND_RULES}.
+ */
+export const MAX_SOUND_FILE_BYTES = 2 * BYTES_PER_MB;
+
+/** Encodes a File/Blob to a base64 string (no data-URL prefix). */
+export async function blobToBase64(blob: Blob): Promise<string> {
+  const buffer = await blob.arrayBuffer();
+  const bytes = new Uint8Array(buffer);
+  const chunkSize = 0x8000;
+  let binary = '';
+  for (let i = 0; i < bytes.length; i += chunkSize) {
+    const chunk = bytes.subarray(i, i + chunkSize);
+    binary += String.fromCharCode(...chunk);
+  }
+  return btoa(binary);
+}
+
+/** Decodes a base64 string to a Blob. */
+export function base64ToBlob(base64: string, mimeType: string): Blob {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return new Blob([bytes], { type: mimeType || 'audio/mpeg' });
+}
+
+/** Coalesces the writes produced while typing into a pattern field. */
+const PERSIST_DEBOUNCE_MS = 400;
+
+/** How a sound rule decides when to play. */
+export type AlertSoundMatchMode = 'message' | 'header' | 'rule';
+
+/** Notification rule option available for DYNAMIC_RULE_ID sound binding. */
+export type AlertSoundSelectableRule = {
+  id: string;
+  name: string;
+};
+
+/**
+ * Resolves a playable MIME type. macOS often leaves `.aif` / `.aiff` with an
+ * empty `File.type`; falling back to `audio/mpeg` breaks restore + decode.
+ */
+export function resolveAudioMimeType(name?: string | null, type?: string | null): string {
+  const lowerName = (name ?? '').toLowerCase();
+  const normalizedType = (type ?? '').trim().toLowerCase();
+  const isAiff = lowerName.endsWith('.aif') || lowerName.endsWith('.aiff');
+
+  if (isAiff) {
+    if (
+      !normalizedType ||
+      normalizedType === 'application/octet-stream' ||
+      normalizedType === 'audio/mpeg'
+    ) {
+      return 'audio/aiff';
+    }
+    return normalizedType;
+  }
+
+  if (normalizedType && normalizedType !== 'application/octet-stream') {
+    return normalizedType;
+  }
+
+  if (lowerName.endsWith('.mp3')) return 'audio/mpeg';
+  if (lowerName.endsWith('.wav')) return 'audio/wav';
+  if (lowerName.endsWith('.m4a') || lowerName.endsWith('.mp4')) return 'audio/mp4';
+  if (lowerName.endsWith('.ogg') || lowerName.endsWith('.oga')) return 'audio/ogg';
+  if (lowerName.endsWith('.aac')) return 'audio/aac';
+  if (lowerName.endsWith('.flac')) return 'audio/flac';
+
+  return normalizedType || 'application/octet-stream';
+}
+
+/** MIME → canPlayType result; probing only depends on the type string. */
+const canPlayMimeCache = new Map<string, boolean>();
+
+function browserCanPlayMime(mimeType: string): boolean {
+  if (typeof Audio === 'undefined') {
+    return false;
+  }
+  const cached = canPlayMimeCache.get(mimeType);
+  if (cached !== undefined) {
+    return cached;
+  }
+  const probe = new Audio();
+  const candidates =
+    mimeType === 'audio/aiff' || mimeType === 'audio/x-aiff'
+      ? ['audio/aiff', 'audio/x-aiff', 'audio/aif']
+      : [mimeType];
+  const canPlay = candidates.some((candidate) => Boolean(probe.canPlayType(candidate)));
+  canPlayMimeCache.set(mimeType, canPlay);
+  return canPlay;
+}
+
+/** Formats a byte count for user-facing size limits (e.g. "2 MB"). */
+export function formatBytes(bytes: number): string {
+  const megabytes = bytes / BYTES_PER_MB;
+  return megabytes >= 1
+    ? `${Math.round(megabytes * MB_PRECISION) / MB_PRECISION} MB`
+    : `${Math.max(1, Math.round(bytes / BYTES_PER_KB))} KB`;
+}
+
+function notifyPlaybackIssue(title: string, body: string): void {
+  showNotification(
+    {
+      title,
+      body,
+      config: {
+        toast: { type: 'warning', autoClose: true, closeTimeout: 6000 },
+      },
+    },
+    'rapid',
+  );
+}
+
+export type AlertSoundRuleView = {
+  index: number;
+  matchMode: AlertSoundMatchMode;
+  pattern: string;
+  templateId: string | null;
+  templateName: string | null;
+  fileName: string | null;
+  hasSound: boolean;
+  muted: boolean;
+};
+
+type StoredRule = {
+  /** Sticky id from the 1…{@link MAX_SOUND_RULES} pool — not the list index. */
+  id?: string;
+  matchMode?: AlertSoundMatchMode;
+  pattern?: string;
+  templateId?: string;
+  templateName?: string;
+  /** When true, this rule is skipped for alert playback. */
+  muted?: boolean;
+};
+
+type StoredSettings = {
+  volume?: number;
+  muted?: boolean;
+};
+
+/** Audio for one rule, stored separately from match config under {@link audioKey}. */
+type StoredAudio = {
+  name?: string;
+  type?: string;
+  buffer?: ArrayBuffer;
+};
+
+/** Captured at schedule time so a later splice cannot retarget the IDB write. */
+type AudioPersistSnapshot = {
+  id: string;
+  blob: Blob | null;
+  fileName: string | null;
+  mimeType: string;
+};
+
+type Slot = {
+  id: string;
+  matchMode: AlertSoundMatchMode;
+  pattern: string;
+  templateId: string | null;
+  templateName: string | null;
+  fileName: string | null;
+  mimeType: string;
+  muted: boolean;
+  audio: HTMLAudioElement | null;
+  blob: Blob | null;
+  objectUrl: string | null;
+};
+
+function createEmptySlot(id: string): Slot {
+  return {
+    id,
+    matchMode: 'message',
+    pattern: '',
+    templateId: null,
+    templateName: null,
+    fileName: null,
+    mimeType: 'audio/mpeg',
+    muted: false,
+    audio: null,
+    blob: null,
+    objectUrl: null,
+  };
+}
+
+function normalizeMatchMode(value: unknown): AlertSoundMatchMode {
+  if (value === 'rule') {
+    return 'rule';
+  }
+  if (value === 'header') {
+    return 'header';
+  }
+  return 'message';
+}
+
+function slotHasMatchConfig(slot: Pick<Slot, 'matchMode' | 'pattern' | 'templateId'>): boolean {
+  if (slot.matchMode === 'rule') {
+    return Boolean(slot.templateId?.trim());
+  }
+  return Boolean(slot.pattern.trim());
+}
+
+function storedIsMeaningful(
+  rule: StoredRule | null | undefined,
+  audio: StoredAudio | null | undefined,
+): boolean {
+  if (audio?.buffer) {
+    return true;
+  }
+  if (!rule) {
+    return false;
+  }
+  const matchMode = normalizeMatchMode(rule.matchMode);
+  if (matchMode === 'rule') {
+    return Boolean(rule.templateId?.trim());
+  }
+  return Boolean(rule.pattern?.trim());
+}
+
+function emptySlots(): Slot[] {
+  return allRuleIds().map((id) => createEmptySlot(id));
+}
+
+function openDb(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const request = indexedDB.open(DB_NAME, DB_VERSION);
+
+    request.onupgradeneeded = () => {
+      const db = request.result;
+      if (!db.objectStoreNames.contains(STORE_NAME)) {
+        db.createObjectStore(STORE_NAME);
+      }
+    };
+
+    // Without this, a version-upgrade blocked by another open tab never settles
+    // the request at all, wedging persistChain (via idbPut/idbGet) indefinitely.
+    request.onblocked = () => {
+      reject(new Error('IndexedDB open blocked by another connection'));
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error ?? new Error('Failed to open IndexedDB'));
+  });
+}
+
+async function idbGet<T>(key: string): Promise<T | null> {
+  let db: IDBDatabase | null = null;
+  try {
+    db = await openDb();
+    return await new Promise((resolve, reject) => {
+      const tx = db!.transaction(STORE_NAME, 'readonly');
+      const store = tx.objectStore(STORE_NAME);
+      const request = store.get(key);
+      let result: T | null = null;
+      request.onsuccess = () => {
+        result = (request.result as T) ?? null;
+      };
+      request.onerror = () => reject(request.error ?? new Error(`Failed to read ${key}`));
+      // Resolve on transaction complete so close() in finally cannot race the read.
+      tx.oncomplete = () => resolve(result);
+      tx.onerror = () => reject(tx.error ?? new Error(`Failed to read ${key}`));
+      tx.onabort = () => reject(tx.error ?? new Error(`Read aborted for ${key}`));
+    });
+  } catch (error) {
+    logger.error(`Failed to read ${key} from IndexedDB`, error);
+    return null;
+  } finally {
+    db?.close();
+  }
+}
+
+async function idbPut(key: string, value: unknown): Promise<void> {
+  let db: IDBDatabase | null = null;
+  try {
+    db = await openDb();
+    await new Promise<void>((resolve, reject) => {
+      const tx = db!.transaction(STORE_NAME, 'readwrite');
+      const store = tx.objectStore(STORE_NAME);
+      const request = store.put(value, key);
+      request.onerror = () => reject(request.error ?? new Error(`Failed to store ${key}`));
+      // Wait for commit — resolving on request.onsuccess alone can lose the write
+      // if the connection is closed before the transaction finishes.
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error ?? new Error(`Failed to store ${key}`));
+      tx.onabort = () => reject(tx.error ?? new Error(`Write aborted for ${key}`));
+    });
+  } finally {
+    db?.close();
+  }
+}
+
+async function idbDelete(key: string): Promise<void> {
+  let db: IDBDatabase | null = null;
+  try {
+    db = await openDb();
+    await new Promise<void>((resolve, reject) => {
+      const tx = db!.transaction(STORE_NAME, 'readwrite');
+      const store = tx.objectStore(STORE_NAME);
+      const request = store.delete(key);
+      request.onerror = () => reject(request.error ?? new Error(`Failed to delete ${key}`));
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error ?? new Error(`Failed to delete ${key}`));
+      tx.onabort = () => reject(tx.error ?? new Error(`Delete aborted for ${key}`));
+    });
+  } finally {
+    db?.close();
+  }
+}
+
+function persistFailureBody(error: unknown): string {
+  const name =
+    error && typeof error === 'object' && 'name' in error
+      ? String((error as { name?: unknown }).name)
+      : '';
+  if (name === 'QuotaExceededError') {
+    return 'These rules will not survive a reload. Browser storage is full — try a smaller sound file.';
+  }
+  if (name === 'VersionError') {
+    return 'These rules will not survive a reload. Clear site data for this origin and try again.';
+  }
+  return 'These rules will not survive a reload. Check the browser console for details.';
+}
+
+function asNonEmptyString(value: unknown): string | undefined {
+  if (typeof value === 'string' && value.trim()) {
+    return value;
+  }
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return String(value);
+  }
+  return undefined;
+}
+
+/**
+ * True when `text` contains `phrase` as a whole phrase (case-insensitive).
+ * Single words and multi-word phrases both work; edges use word boundaries so
+ * e.g. `g1` matches "test g1 test" but not "test g1h test".
+ *
+ * `\b` only asserts a word/non-word transition, so anchoring an edge whose own
+ * character is punctuation can never match — `\b\$100` fails on "cost $100".
+ * Each edge is therefore anchored only when the pattern ends in a word character.
+ *
+ * @internal Exported for unit tests.
+ */
+export function textContainsWholeWord(text: string, phrase: string): boolean {
+  const needle = phrase.trim();
+  if (!needle) {
+    return false;
+  }
+  const escaped = needle.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const start = /\w/.test(needle[0]) ? '\\b' : '';
+  const end = /\w/.test(needle[needle.length - 1]) ? '\\b' : '';
+  return new RegExp(`${start}${escaped}${end}`, 'i').test(text);
+}
+
+function readAlertStringField(
+  row: Record<string, unknown> | null | undefined,
+  field: string,
+): string | undefined {
+  if (!row) {
+    return undefined;
+  }
+
+  const direct = asNonEmptyString(row[field]);
+  if (direct) {
+    return direct;
+  }
+
+  const details = row.DETAILS as Record<string, unknown> | undefined;
+  return asNonEmptyString(details?.[field]);
+}
+
+/**
+ * Plays user-selected alert sounds matched by MESSAGE/HEADER text (word or phrase)
+ * or notification rule DYNAMIC_RULE_ID. Persists up to {@link MAX_SOUND_RULES}
+ * rules in IndexedDB.
+ */
+export class AlertSoundPlayer {
+  private slots: Slot[] = emptySlots();
+  private activeCount = 1;
+  /** Linear gain 0–1 applied to every HTMLAudioElement. */
+  private volume = DEFAULT_VOLUME;
+  private muted = false;
+  private listeners = new Set<() => void>();
+  /** Coalesces concurrent restores from layout + Sounds tab mounts. */
+  private restorePromise: Promise<boolean> | null = null;
+  private restored = false;
+  private persistChain: Promise<void> = Promise.resolve();
+  /** In-memory cache of rule-attached sounds fetched from NOTIFY_ALERT_SOUND. */
+  private readonly serverSounds = new Map<
+    string,
+    { objectUrl: string; audio: HTMLAudioElement; mimeType: string; fileName: string | null }
+  >();
+
+  /** Shared player so the layout listener and inbox Sounds tab stay in sync. */
+  static readonly shared = new AlertSoundPlayer();
+
+  get rules(): AlertSoundRuleView[] {
+    return this.slots.slice(0, this.activeCount).map((slot, index) => ({
+      index,
+      matchMode: slot.matchMode,
+      pattern: slot.pattern,
+      templateId: slot.templateId,
+      templateName: slot.templateName,
+      fileName: slot.fileName,
+      hasSound: Boolean(slot.audio?.src),
+      muted: slot.muted,
+    }));
+  }
+
+  get canAddRule(): boolean {
+    return this.activeCount < MAX_SOUND_RULES;
+  }
+
+  get canRemoveRule(): boolean {
+    return this.activeCount > 1;
+  }
+
+  /** Whole-number percent for the Sounds tab slider (0–100). */
+  get volumePercent(): number {
+    return Math.round(this.volume * VOLUME_PERCENT_MAX);
+  }
+
+  get isMuted(): boolean {
+    return this.muted;
+  }
+
+  get isReady(): boolean {
+    return this.slots
+      .slice(0, this.activeCount)
+      .some((slot) => Boolean(slot.audio?.src) && slotHasMatchConfig(slot));
+  }
+
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  /**
+   * Loads rules from IndexedDB once per page session. Concurrent calls (layout
+   * listener + Sounds tab) share one promise so a late restore cannot wipe
+   * in-memory edits the user already made.
+   */
+  async restore(): Promise<boolean> {
+    if (this.restored) {
+      return this.isReady;
+    }
+    if (this.restorePromise) {
+      return this.restorePromise;
+    }
+
+    // Set in `finally` (not `.then`) so a failed first attempt still counts as
+    // the one shot — otherwise `restored` stays false and a later restore() call
+    // (e.g. from the panel, after the layout listener's restore rejected) can
+    // wipe in-memory edits the user already made.
+    this.restorePromise = this.restoreFromDb().finally(() => {
+      this.restored = true;
+      this.restorePromise = null;
+    });
+    return this.restorePromise;
+  }
+
+  private async restoreFromDb(): Promise<boolean> {
+    const [stored, settings] = await Promise.all([
+      idbGet<StoredRule[]>(RULES_KEY),
+      idbGet<StoredSettings>(SETTINGS_KEY),
+    ]);
+    this.applyStoredSettings(settings);
+    const configList = Array.isArray(stored) ? stored : [];
+
+    const candidates = (
+      await Promise.all(
+        configList.slice(0, MAX_SOUND_RULES).map(async (raw) => {
+          const id = raw?.id?.trim();
+          if (!id) {
+            return null;
+          }
+          const audio = await idbGet<StoredAudio>(audioKey(id));
+          if (!storedIsMeaningful(raw, audio)) {
+            return null;
+          }
+          return { rule: raw, audio };
+        }),
+      )
+    ).filter((entry): entry is { rule: StoredRule; audio: StoredAudio | null } => entry != null);
+
+    if (!candidates.length) {
+      this.slots = emptySlots();
+      this.activeCount = 1;
+      this.notify();
+      return false;
+    }
+
+    const count = Math.min(candidates.length, MAX_SOUND_RULES);
+    const usedIds = new Set(candidates.slice(0, count).map(({ rule }) => String(rule.id).trim()));
+    const freeIds = allRuleIds().filter((id) => !usedIds.has(id));
+
+    this.slots = [];
+    await Promise.all(
+      candidates.slice(0, count).map(async ({ rule, audio }, index) => {
+        const id = String(rule.id).trim();
+        this.slots[index] = createEmptySlot(id);
+        this.applyStoredMatch(index, rule);
+        if (audio?.buffer) {
+          const name = audio.name || `alert-sound-${index}`;
+          const file = new File([audio.buffer], name, {
+            type: resolveAudioMimeType(name, audio.type),
+          });
+          await this.applyFile(index, file, { warnOnUnsupported: false });
+        }
+      }),
+    );
+    while (this.slots.length < MAX_SOUND_RULES) {
+      this.slots.push(createEmptySlot(freeIds.shift() ?? String(this.slots.length + 1)));
+    }
+    this.activeCount = count;
+    this.notify();
+    return this.isReady;
+  }
+
+  /** Sets global playback volume from a 0–100 percent (Sounds tab slider). */
+  setVolumePercent(percent: number): void {
+    const clamped = Math.max(0, Math.min(VOLUME_PERCENT_MAX, Math.round(percent)));
+    // FAST Slider emits `change` on programmatic `:value` writes (mount midpoint →
+    // bound percent, and again after restore). Those carry the player's own percent
+    // and are dropped here — no pre-restore gate, so real drags / public API calls
+    // during restore are not silently discarded.
+    if (clamped === this.volumePercent) {
+      return;
+    }
+    this.volume = clamped / VOLUME_PERCENT_MAX;
+    // Moving the slider implies the user wants audible output again.
+    if (clamped > 0 && this.muted) {
+      this.muted = false;
+    }
+    this.applyVolumeToSlots();
+    this.notify();
+    this.flushSettings();
+  }
+
+  setMuted(muted: boolean): void {
+    this.muted = Boolean(muted);
+    this.applyVolumeToSlots();
+    this.notify();
+    this.flushSettings();
+  }
+
+  toggleMute(): void {
+    this.setMuted(!this.muted);
+  }
+
+  addRule(): boolean {
+    if (!this.canAddRule) {
+      return false;
+    }
+    this.activeCount += 1;
+    this.notify();
+    return true;
+  }
+
+  removeRule(index: number): void {
+    if (!this.isValidIndex(index)) {
+      return;
+    }
+
+    // Keep at least one rule row — reset it to blank instead of deleting.
+    if (!this.canRemoveRule) {
+      this.resetRule(index);
+      return;
+    }
+
+    const removedId = this.slots[index].id;
+    this.revokeObjectUrl(index);
+    this.slots.splice(index, 1);
+    // Recycle the sticky id onto the new blank tail slot
+    this.slots.push(createEmptySlot(removedId));
+    this.activeCount -= 1;
+    this.notify();
+    this.flushPersist();
+    this.queuePersist(async () => {
+      try {
+        await idbDelete(audioKey(removedId));
+      } catch (error) {
+        logger.error('Failed to delete alert sound audio for removed rule', error);
+      }
+    });
+  }
+
+  /** Clears match criteria and sound file for a rule without removing the row. */
+  resetRule(index: number): void {
+    if (!this.isValidIndex(index)) {
+      return;
+    }
+    const { id } = this.slots[index];
+    this.revokeObjectUrl(index);
+    this.slots[index] = createEmptySlot(id);
+    this.notify();
+    this.flushAudioPersist(index);
+  }
+
+  setMatchMode(index: number, matchMode: AlertSoundMatchMode): void {
+    if (!this.isValidIndex(index)) {
+      return;
+    }
+    this.slots[index].matchMode = normalizeMatchMode(matchMode);
+    this.notify();
+    this.flushPersist();
+  }
+
+  /**
+   * Deliberately does not notify: the value came from the pattern field itself,
+   * so re-rendering the rule rows mid-keystroke would only disturb the caret.
+   */
+  setPattern(index: number, pattern: string): void {
+    if (!this.isValidIndex(index)) {
+      return;
+    }
+    const mode = this.slots[index].matchMode;
+    if (mode !== 'message' && mode !== 'header') {
+      this.slots[index].matchMode = 'message';
+    }
+    this.slots[index].pattern = pattern ?? '';
+    this.schedulePersist();
+  }
+
+  setRule(index: number, rule: Pick<AlertSoundSelectableRule, 'id' | 'name'> | null): void {
+    if (!this.isValidIndex(index)) {
+      return;
+    }
+    this.slots[index].matchMode = 'rule';
+    this.slots[index].templateId = rule?.id ?? null;
+    this.slots[index].templateName = rule?.name ?? null;
+    this.notify();
+    this.flushPersist();
+  }
+
+  setSoundFromFile(index: number, file: File): void {
+    if (!this.isValidIndex(index) || !file) {
+      return;
+    }
+    if (file.size > MAX_SOUND_FILE_BYTES) {
+      notifyPlaybackIssue(
+        'Sound file too large',
+        `${file.name} is ${formatBytes(file.size)}. The limit is ${formatBytes(
+          MAX_SOUND_FILE_BYTES,
+        )} — try a shorter clip.`,
+      );
+      return;
+    }
+    void this.applyFile(index, file, { warnOnUnsupported: true }).then(() => {
+      this.notify();
+      this.flushAudioPersist(index);
+    });
+  }
+
+  clearSound(index: number): void {
+    if (!this.isValidIndex(index)) {
+      return;
+    }
+    this.revokeObjectUrl(index);
+    this.slots[index].audio = null;
+    this.slots[index].blob = null;
+    this.slots[index].fileName = null;
+    this.slots[index].mimeType = 'audio/mpeg';
+    this.notify();
+    this.flushAudioPersist(index);
+  }
+
+  setRuleMuted(index: number, muted: boolean): void {
+    if (!this.isValidIndex(index)) {
+      return;
+    }
+    this.slots[index].muted = Boolean(muted);
+    this.notify();
+    this.flushPersist();
+  }
+
+  toggleRuleMute(index: number): void {
+    if (!this.isValidIndex(index)) {
+      return;
+    }
+    this.setRuleMuted(index, !this.slots[index].muted);
+  }
+
+  /** Plays the sound file for a specific rule (for UI testing). */
+  playRule(index: number): boolean {
+    if (!this.isValidIndex(index)) {
+      return false;
+    }
+    const slot = this.slots[index];
+    const audio = slot.audio;
+    if (!audio?.src) {
+      return false;
+    }
+
+    if (!browserCanPlayMime(slot.mimeType)) {
+      const formatHint = slot.fileName?.match(/\.[^.]+$/)?.[0] ?? slot.mimeType;
+      notifyPlaybackIssue(
+        'Sound format not supported',
+        `This browser cannot play ${formatHint}. Try MP3 or WAV.`,
+      );
+      return false;
+    }
+
+    audio.currentTime = 0;
+    this.applyVolumeToAudio(audio);
+    void audio.play().catch((error) => {
+      logger.warn('Alert sound playback blocked or failed', error);
+      notifyPlaybackIssue(
+        'Sound playback failed',
+        'The browser could not play this file. Try MP3 or WAV.',
+      );
+    });
+    return true;
+  }
+
+  /**
+   * Plays the first configured rule that matches the alert:
+   * - message: MESSAGE contains the pattern as a whole phrase (case-insensitive)
+   * - header: HEADER contains the pattern as a whole phrase (case-insensitive)
+   * - rule: alert DYNAMIC_RULE_ID equals the selected id
+   */
+  playForAlert(alert: {
+    message?: string | null;
+    header?: string | null;
+    dynamicRuleId?: string | null;
+  }): boolean {
+    const message = alert.message ?? '';
+    const header = alert.header ?? '';
+    const dynamicRuleId = (alert.dynamicRuleId ?? '').trim();
+
+    for (let index = 0; index < this.activeCount; index += 1) {
+      const slot = this.slots[index];
+      if (!slot.audio?.src || slot.muted) {
+        continue;
+      }
+
+      let matched: boolean;
+      if (slot.matchMode === 'rule') {
+        const expected = slot.templateId?.trim();
+        matched = Boolean(expected && dynamicRuleId && dynamicRuleId === expected);
+      } else {
+        const pattern = slot.pattern.trim();
+        if (!pattern) {
+          continue;
+        }
+        matched =
+          slot.matchMode === 'header'
+            ? textContainsWholeWord(header, pattern)
+            : textContainsWholeWord(message, pattern);
+      }
+
+      // A matching-but-unplayable rule (e.g. an unsupported format) shouldn't stop
+      // the scan — a later rule that also matches may still have a playable file.
+      if (matched && this.playRule(index)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Caches a server-backed rule sound (from NOTIFY_ALERT_SOUND) for playback.
+   * Replaces any previous cache entry for the same dynamicRuleId.
+   */
+  setServerSound(
+    dynamicRuleId: string,
+    options: { blob: Blob; fileName?: string; mimeType?: string },
+  ): void {
+    const id = dynamicRuleId?.trim();
+    if (!id || !options.blob) {
+      return;
+    }
+    this.revokeServerSound(id);
+    const mimeType = resolveAudioMimeType(options.fileName, options.mimeType || options.blob.type);
+    const blob =
+      options.blob.type === mimeType ? options.blob : new Blob([options.blob], { type: mimeType });
+    const objectUrl = URL.createObjectURL(blob);
+    const audio = new Audio(objectUrl);
+    audio.preload = 'auto';
+    this.applyVolumeToAudio(audio);
+    this.serverSounds.set(id, {
+      objectUrl,
+      audio,
+      mimeType,
+      fileName: options.fileName ?? null,
+    });
+  }
+
+  /** True when a server sound for this rule is already cached. */
+  hasServerSound(dynamicRuleId: string): boolean {
+    return this.serverSounds.has(dynamicRuleId?.trim());
+  }
+
+  /**
+   * Drops a cached server sound so the next alert re-fetches from
+   * NOTIFY_ALERT_SOUND (e.g. after replace/clear on the rule dialog).
+   */
+  clearServerSound(dynamicRuleId: string): void {
+    this.revokeServerSound(dynamicRuleId?.trim());
+  }
+
+  /**
+   * Clears every cached server-backed rule sound. Used when a template sound
+   * changes — subscribed instance ids are unknown on the client, and alerts
+   * look up by those instance ids.
+   */
+  clearAllServerSounds(): void {
+    for (const id of [...this.serverSounds.keys()]) {
+      this.revokeServerSound(id);
+    }
+  }
+
+  /**
+   * Plays a cached server sound for the given DYNAMIC_RULE_ID.
+   * Respects global mute / volume. Returns false if missing or muted with no play.
+   */
+  playServerSound(dynamicRuleId: string): boolean {
+    if (this.muted) {
+      return false;
+    }
+    const entry = this.serverSounds.get(dynamicRuleId?.trim());
+    if (!entry?.audio?.src) {
+      return false;
+    }
+    if (!browserCanPlayMime(entry.mimeType)) {
+      notifyPlaybackIssue(
+        'Sound format not supported',
+        `This browser cannot play the rule alert sound. Try MP3 or WAV.`,
+      );
+      return false;
+    }
+    entry.audio.currentTime = 0;
+    this.applyVolumeToAudio(entry.audio);
+    void entry.audio.play().catch((error) => {
+      logger.warn('Server alert sound playback blocked or failed', error);
+      notifyPlaybackIssue(
+        'Sound playback failed',
+        'The browser could not play this rule alert sound. Try MP3 or WAV.',
+      );
+    });
+    return true;
+  }
+
+  private revokeServerSound(dynamicRuleId: string): void {
+    if (!dynamicRuleId) {
+      return;
+    }
+    const entry = this.serverSounds.get(dynamicRuleId);
+    if (!entry) {
+      return;
+    }
+    entry.audio.pause();
+    URL.revokeObjectURL(entry.objectUrl);
+    this.serverSounds.delete(dynamicRuleId);
+  }
+
+  private applyStoredMatch(index: number, rule: StoredRule | null | undefined): void {
+    if (rule?.id?.trim()) {
+      this.slots[index].id = rule.id.trim();
+    }
+    this.slots[index].matchMode = normalizeMatchMode(rule?.matchMode);
+    this.slots[index].pattern = rule?.pattern ?? '';
+    this.slots[index].templateId = rule?.templateId ?? null;
+    this.slots[index].templateName = rule?.templateName ?? null;
+    this.slots[index].muted = Boolean(rule?.muted);
+  }
+
+  private matchFields(slot: Slot): StoredRule {
+    return {
+      id: slot.id,
+      matchMode: slot.matchMode,
+      pattern: slot.pattern,
+      templateId: slot.templateId ?? undefined,
+      templateName: slot.templateName ?? undefined,
+      muted: slot.muted || undefined,
+    };
+  }
+
+  /** Debounces config writes so holding down a key does not thrash IndexedDB. */
+  private readonly debouncedPersistConfig = debounce(() => {
+    this.queuePersist(() => this.persistConfig());
+  }, PERSIST_DEBOUNCE_MS);
+
+  /** Schedules a debounced config write (pattern typing). */
+  private schedulePersist(): void {
+    this.debouncedPersistConfig();
+  }
+
+  /** Writes config now, including anything a pending debounce had not yet flushed. */
+  private flushPersist(): void {
+    this.debouncedPersistConfig();
+    this.debouncedPersistConfig.flush();
+  }
+
+  private flushSettings(): void {
+    this.queuePersist(() => this.persistSettings());
+  }
+
+  /** Flushes config plus this rule's audio (sound file added/cleared/reset). */
+  private flushAudioPersist(index: number): void {
+    this.flushPersist();
+    const slot = this.slots[index];
+    if (!slot?.id) {
+      return;
+    }
+    // Capture at schedule time — persistChain may drain after a splice, and
+    // resolving `this.slots[index]` then would retarget the wrong rule.
+    const snapshot: AudioPersistSnapshot = {
+      id: slot.id,
+      blob: slot.blob,
+      fileName: slot.fileName,
+      mimeType: slot.mimeType,
+    };
+    this.queuePersist(() => this.persistAudio(snapshot));
+  }
+
+  /** Chained so overlapping writes cannot land out of order. */
+  private queuePersist(task: () => Promise<void>): void {
+    this.persistChain = this.persistChain.then(() => task());
+  }
+
+  private applyStoredSettings(settings: StoredSettings | null): void {
+    if (!settings) {
+      return;
+    }
+    if (typeof settings.volume === 'number' && Number.isFinite(settings.volume)) {
+      this.volume = Math.max(0, Math.min(DEFAULT_VOLUME, settings.volume));
+    }
+    if (typeof settings.muted === 'boolean') {
+      this.muted = settings.muted;
+    }
+  }
+
+  private applyVolumeToSlots(): void {
+    for (const slot of this.slots) {
+      if (slot.audio) {
+        this.applyVolumeToAudio(slot.audio);
+      }
+    }
+    for (const entry of this.serverSounds.values()) {
+      this.applyVolumeToAudio(entry.audio);
+    }
+  }
+
+  private applyVolumeToAudio(audio: HTMLAudioElement): void {
+    audio.muted = this.muted;
+    audio.volume = this.muted ? 0 : this.volume;
+  }
+
+  private async persistSettings(): Promise<void> {
+    try {
+      const payload: StoredSettings = {
+        volume: this.volume,
+        muted: this.muted,
+      };
+      await idbPut(SETTINGS_KEY, payload);
+    } catch (error) {
+      logger.error('Failed to persist alert sound settings', error);
+      notifyPlaybackIssue('Could not save volume settings', persistFailureBody(error));
+    }
+  }
+
+  /** Match config only — cheap enough to rewrite on every keystroke. */
+  private async persistConfig(): Promise<void> {
+    try {
+      const payload: StoredRule[] = this.slots
+        .slice(0, this.activeCount)
+        .map((slot) => this.matchFields(slot));
+      await idbPut(RULES_KEY, payload);
+    } catch (error) {
+      logger.error('Failed to persist alert sound rules', error);
+      notifyPlaybackIssue('Could not save alert sounds', persistFailureBody(error));
+    }
+  }
+
+  /** One rule's audio, stored separately so a pattern edit never touches it. */
+  private async persistAudio(snapshot: AudioPersistSnapshot): Promise<void> {
+    try {
+      if (snapshot.blob && snapshot.fileName) {
+        const payload: StoredAudio = {
+          name: snapshot.fileName,
+          type: snapshot.mimeType,
+          buffer: await snapshot.blob.arrayBuffer(),
+        };
+        await idbPut(audioKey(snapshot.id), payload);
+      } else {
+        await idbDelete(audioKey(snapshot.id));
+      }
+    } catch (error) {
+      logger.error(`Failed to persist alert sound audio for rule ${snapshot.id}`, error);
+      notifyPlaybackIssue('Could not save alert sound', persistFailureBody(error));
+    }
+  }
+
+  private async applyFile(
+    index: number,
+    file: File,
+    options: { warnOnUnsupported: boolean },
+  ): Promise<void> {
+    const mimeType = resolveAudioMimeType(file.name, file.type);
+    let blob: Blob;
+    try {
+      // Read bytes once and own them as a Blob — never hold onto the original
+      // File handle. A later persist() re-reading it via arrayBuffer() would
+      // throw NotFoundError (losing every rule's write, not just this one) if
+      // the source file has since moved, been renamed, or been deleted.
+      const buffer = await file.arrayBuffer();
+      blob = new Blob([buffer], { type: mimeType });
+    } catch (error) {
+      logger.error(`Failed to read sound file ${file.name}`, error);
+      notifyPlaybackIssue(
+        'Could not read sound file',
+        `${file.name} could not be read. It may have been moved or deleted.`,
+      );
+      return;
+    }
+
+    this.revokeObjectUrl(index);
+    const objectUrl = URL.createObjectURL(blob);
+    const audio = new Audio(objectUrl);
+    audio.preload = 'auto';
+    this.applyVolumeToAudio(audio);
+    this.slots[index].objectUrl = objectUrl;
+    this.slots[index].audio = audio;
+    this.slots[index].blob = blob;
+    this.slots[index].fileName = file.name;
+    this.slots[index].mimeType = mimeType;
+
+    if (options.warnOnUnsupported && !browserCanPlayMime(mimeType)) {
+      notifyPlaybackIssue(
+        'Sound format not supported',
+        `${file.name} may not play in this browser. Prefer MP3 or WAV.`,
+      );
+    }
+  }
+
+  private isValidIndex(index: number): boolean {
+    return Number.isInteger(index) && index >= 0 && index < this.activeCount;
+  }
+
+  private notify(): void {
+    this.listeners.forEach((listener) => listener());
+  }
+
+  private revokeObjectUrl(index: number): void {
+    const url = this.slots[index]?.objectUrl;
+    if (url) {
+      URL.revokeObjectURL(url);
+      this.slots[index].objectUrl = null;
+    }
+  }
+}
+
+/** Reads ALERT_ID from a streamed alert row. */
+export function getAlertId(row: Record<string, unknown> | null | undefined): string | undefined {
+  if (!row) {
+    return undefined;
+  }
+
+  const direct = row.ALERT_ID;
+  if (typeof direct === 'string' && direct) {
+    return direct;
+  }
+
+  const details = row.DETAILS as Record<string, unknown> | undefined;
+  const nested = details?.ALERT_ID;
+  if (typeof nested === 'string' && nested) {
+    return nested;
+  }
+
+  return undefined;
+}
+
+/** Reads MESSAGE from a streamed alert row. */
+export function getAlertMessage(
+  row: Record<string, unknown> | null | undefined,
+): string | undefined {
+  return readAlertStringField(row, 'MESSAGE');
+}
+
+/** Reads HEADER from a streamed alert row. */
+export function getAlertHeader(
+  row: Record<string, unknown> | null | undefined,
+): string | undefined {
+  return readAlertStringField(row, 'HEADER');
+}
+
+/** Reads DYNAMIC_RULE_ID from a streamed alert row. */
+export function getAlertDynamicRuleId(
+  row: Record<string, unknown> | null | undefined,
+): string | undefined {
+  const value = readAlertStringField(row, 'DYNAMIC_RULE_ID');
+  return value?.trim() ? value : undefined;
+}