feat(screenreader): implement announcement queue and stop functionality

Author: mystiker

frontend/src/app/core/mud/components/mud-client/mud-client.component.ts

@@ -326,6 +326,9 @@ export class MudClientComponent implements AfterViewInit, OnDestroy {
       : { value: message };
 
     if (typeof payload === 'string') {
+      if (!payload.length) {
+        this.screenReader?.stopAnnouncements();
+      }
       this.screenReader?.appendToHistory(payload);
       // Announce the complete input so user can verify what they typed
       this.screenReader?.announceInputCommitted(payload);

frontend/src/app/features/terminal/mud-screenreader.spec.ts

@@ -12,7 +12,8 @@ describe('MudScreenReaderAnnouncer', () => {
       liveRegion,
       undefined,
       undefined,
-      100,
+      50,
+      1000,
     );
   });
 
@@ -26,7 +27,7 @@ describe('MudScreenReaderAnnouncer', () => {
 
     expect(liveRegion.textContent).toBe('Hello World');
 
-    jest.advanceTimersByTime(99);
+    jest.advanceTimersByTime(49);
     expect(liveRegion.textContent).toBe('Hello World');
 
     jest.advanceTimersByTime(1);
@@ -43,16 +44,19 @@ describe('MudScreenReaderAnnouncer', () => {
     expect(liveRegion.textContent).toBe('');
   });
 
-  it('resets the clear timer for rapid consecutive announcements', () => {
+  it('queues rapid consecutive announcements', () => {
     announcer.announce('First');
-    jest.advanceTimersByTime(50);
-
     announcer.announce('Second');
-    jest.advanceTimersByTime(99);
 
-    expect(liveRegion.textContent).toBe('Second');
+    expect(liveRegion.textContent).toBe('First');
+
+    jest.advanceTimersByTime(49);
+    expect(liveRegion.textContent).toBe('First');
 
     jest.advanceTimersByTime(1);
+    expect(liveRegion.textContent).toBe('Second');
+
+    jest.advanceTimersByTime(50);
     expect(liveRegion.textContent).toBe('');
   });
 
@@ -64,6 +68,19 @@ describe('MudScreenReaderAnnouncer', () => {
     expect(liveRegion.textContent).toBe('');
   });
 
+  it('stopAnnouncements() clears live region and backlog', () => {
+    announcer.announce('First');
+    announcer.announce('Second');
+
+    expect(liveRegion.textContent).toBe('First');
+
+    announcer.stopAnnouncements();
+    expect(liveRegion.textContent).toBe('');
+
+    jest.advanceTimersByTime(200);
+    expect(liveRegion.textContent).toBe('');
+  });
+
   it('ignores empty output after normalization', () => {
     announcer.announce('\x1b[31m\x1b[0m');
 

frontend/src/app/features/terminal/mud-screenreader.ts

@@ -1,4 +1,5 @@
-const DEFAULT_CLEAR_DELAY_MS = 300;
+const DEFAULT_MIN_ANNOUNCE_MS = 700;
+const DEFAULT_SPEECH_CHARS_PER_SEC = 12;
 const INPUT_CLEAR_DELAY_MS = 700;
 const ANSI_ESCAPE_PATTERN = /\x1B\[[0-9;?]*[ -\/]*[@-~]/g;
 const CONTROL_CHAR_PATTERN = /[\x00-\x08\x0B-\x1F\x7F]/g;
@@ -16,12 +17,16 @@ export class MudScreenReaderAnnouncer {
   private inputClearTimer: number | undefined;
   private sessionStartedAt: number;
   private lastAnnouncedBuffer = '';
+  private announceQueue: string[] = [];
+  private isAnnouncing = false;
+  private abortToken = 0;
 
   constructor(
     private readonly liveRegion: HTMLElement,
     private readonly historyRegion?: HTMLElement,
     private readonly inputRegion?: HTMLElement,
-    private readonly clearDelayMs: number = DEFAULT_CLEAR_DELAY_MS,
+    private readonly minAnnouncementMs: number = DEFAULT_MIN_ANNOUNCE_MS,
+    private readonly speechCharsPerSecond: number = DEFAULT_SPEECH_CHARS_PER_SEC,
   ) {
     this.sessionStartedAt = Date.now();
   }
@@ -31,7 +36,7 @@ export class MudScreenReaderAnnouncer {
    */
   public markSessionStart(timestamp: number = Date.now()): void {
     this.sessionStartedAt = timestamp;
-    this.clear();
+    this.stopAnnouncements();
     this.clearHistory();
     this.lastAnnouncedBuffer = '';
   }
@@ -64,12 +69,7 @@ export class MudScreenReaderAnnouncer {
       return;
     }
 
-    this.liveRegion.textContent = normalized;
-    console.debug(
-      '[ScreenReader] Live region updated:',
-      this.liveRegion.textContent,
-    );
-    this.scheduleClear();
+    this.enqueueAnnouncement(normalized);
   }
 
   /**
@@ -80,11 +80,21 @@ export class MudScreenReaderAnnouncer {
     this.cancelClearTimer();
   }
 
+  /**
+   * Stops any in-flight announcements and drops the queued backlog.
+   */
+  public stopAnnouncements(): void {
+    this.abortToken += 1;
+    this.announceQueue = [];
+    this.isAnnouncing = false;
+    this.clear();
+  }
+
   /**
    * Disposes internal timers.
    */
   public dispose(): void {
-    this.clear();
+    this.stopAnnouncements();
     this.cancelInputClearTimer();
   }
 
@@ -272,12 +282,44 @@ export class MudScreenReaderAnnouncer {
     this.lastAnnouncedBuffer = '';
   }
 
-  private scheduleClear(): void {
+  private enqueueAnnouncement(normalized: string): void {
+    this.announceQueue.push(normalized);
+    this.processQueue();
+  }
+
+  private processQueue(): void {
+    if (this.isAnnouncing) {
+      return;
+    }
+
+    const next = this.announceQueue.shift();
+    if (!next) {
+      return;
+    }
+
+    this.isAnnouncing = true;
+    const token = this.abortToken;
+
+    this.liveRegion.textContent = next;
+    console.debug('[ScreenReader] Live region updated:', next);
+
+    const duration = this.getAnnouncementDuration(next);
+    this.scheduleClear(duration, token);
+  }
+
+  private scheduleClear(durationMs: number, token: number): void {
     this.cancelClearTimer();
 
     this.clearTimer = window.setTimeout(() => {
-      this.clear();
-    }, this.clearDelayMs);
+      if (token !== this.abortToken) {
+        return;
+      }
+
+      this.liveRegion.textContent = '';
+      this.isAnnouncing = false;
+      this.clearTimer = undefined;
+      this.processQueue();
+    }, durationMs);
   }
 
   private cancelClearTimer(): void {
@@ -287,6 +329,13 @@ export class MudScreenReaderAnnouncer {
     }
   }
 
+  private getAnnouncementDuration(text: string): number {
+    const chars = Math.max(text.length, 1);
+    const estimatedMs = Math.ceil((chars / this.speechCharsPerSecond) * 1000);
+
+    return Math.max(estimatedMs, this.minAnnouncementMs);
+  }
+
   // Input clear helpers are retained for potential future use (currently unused)
   private scheduleInputClear(): void {
     this.cancelInputClearTimer();