feat(frontend): implement MudScreenReader for improved accessibility

Author: mystiker

frontend/setup-jest.ts

@@ -1 +1 @@
-import 'jest-preset-angular/setup-jest';
+// import 'jest-preset-angular/setup-jest';

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

@@ -1,3 +1,13 @@
+<div
+  class="sr-announcer"
+  aria-live="polite"
+  aria-atomic="true"
+  aria-relevant="additions"
+  #liveRegionRef
+></div>
+
+<div class="sr-history" role="log" aria-live="off" #historyRegionRef></div>
+
 <div class="mud-output" #hostRef></div>
 
 @if (!(isConnected$ | async)) {

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

@@ -2,6 +2,7 @@
   display: flex;
   flex-direction: column;
   min-height: 0;
+  position: relative;
 
   .mud-output {
     flex: 1 1 0;
@@ -10,6 +11,34 @@
     overflow: hidden;
   }
 
+  .sr-announcer {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: pre-wrap;
+    border: 0;
+  }
+
+  .sr-history {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: pre-wrap;
+    border: 0;
+  }
+
+  .sr-log-item {
+    white-space: pre-wrap;
+  }
+
   /* Optionales Styling */
   .disconnected-panel {
     flex: 0 0 auto;

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

@@ -21,6 +21,7 @@ import {
   MudPromptManager,
   MudSocketAdapter,
   MudPromptContext,
+  MudScreenReaderAnnouncer,
 } from '../../../../features/terminal';
 
 /**
@@ -37,7 +38,9 @@ const DELETE_SEQUENCE = `${CTRL.ESC}[3~`;
 
 /**
  * Angular wrapper around the xterm-based MUD client.  The component hosts the terminal,
- * wires the input/prompt helpers together and mirrors socket events to the view.
+ * wires the input/prompt helpers together and mirrors socket events to the view. A
+ * custom screenreader announcer replaces xterm's built-in screenReaderMode to avoid
+ * duplicated output and replaying history after reconnects.
  */
 @Component({
   selector: 'app-mud-client',
@@ -52,19 +55,10 @@ export class MudClientComponent implements AfterViewInit, OnDestroy {
   private readonly terminal: Terminal;
   private readonly inputController: MudInputController;
   private readonly promptManager: MudPromptManager;
+  private screenReader?: MudScreenReaderAnnouncer;
   private readonly terminalFitAddon = new FitAddon();
-  private readonly socketAdapter = new MudSocketAdapter(
-    this.mudService.mudOutput$,
-    {
-      transformMessage: (data) => this.transformMudOutput(data),
-      beforeMessage: (data) => this.beforeMudOutput(data),
-      afterMessage: (data) => this.afterMudOutput(data),
-    },
-  );
-  private readonly terminalAttachAddon = new AttachAddon(
-    this.socketAdapter as unknown as WebSocket,
-    { bidirectional: false },
-  );
+  private socketAdapter?: MudSocketAdapter;
+  private terminalAttachAddon?: AttachAddon;
 
   private readonly terminalDisposables: IDisposable[] = [];
   private readonly resizeObs = new ResizeObserver(() => {
@@ -84,6 +78,12 @@ export class MudClientComponent implements AfterViewInit, OnDestroy {
   @ViewChild('hostRef', { static: true })
   private readonly terminalRef!: ElementRef<HTMLDivElement>;
 
+  @ViewChild('liveRegionRef', { static: true })
+  private readonly liveRegionRef!: ElementRef<HTMLDivElement>;
+
+  @ViewChild('historyRegionRef', { static: true })
+  private readonly historyRegionRef!: ElementRef<HTMLElement>;
+
   protected readonly isConnected$ = this.mudService.connectedToMud$;
   protected readonly showEcho$ = this.mudService.showEcho$;
 
@@ -96,7 +96,7 @@ export class MudClientComponent implements AfterViewInit, OnDestroy {
       fontFamily: 'JetBrainsMono, monospace',
       theme: { background: '#000', foreground: '#ccc' },
       disableStdin: false,
-      screenReaderMode: true,
+      screenReaderMode: false,
     });
 
     this.inputController = new MudInputController(
@@ -116,6 +116,28 @@ export class MudClientComponent implements AfterViewInit, OnDestroy {
    * to socket events and reports the initial viewport dimensions to the server.
    */
   ngAfterViewInit() {
+    // Initialize screenreader announcer before terminal/socket setup
+    // to ensure we capture the session start BEFORE any output arrives
+    this.screenReader = new MudScreenReaderAnnouncer(
+      this.liveRegionRef.nativeElement,
+      this.historyRegionRef.nativeElement,
+    );
+    console.debug(
+      '[MudClient] Screenreader announcer initialized, live region:',
+      this.liveRegionRef.nativeElement,
+    );
+
+    // Now initialize socket adapter AFTER screenreader is ready
+    this.socketAdapter = new MudSocketAdapter(this.mudService.mudOutput$, {
+      transformMessage: (data) => this.transformMudOutput(data),
+      beforeMessage: (data) => this.beforeMudOutput(data),
+      afterMessage: (data) => this.afterMudOutput(data),
+    });
+    this.terminalAttachAddon = new AttachAddon(
+      this.socketAdapter as unknown as WebSocket,
+      { bidirectional: false },
+    );
+
     this.terminal.open(this.terminalRef.nativeElement);
     this.terminal.loadAddon(this.terminalFitAddon);
     this.terminal.loadAddon(this.terminalAttachAddon);
@@ -152,15 +174,17 @@ export class MudClientComponent implements AfterViewInit, OnDestroy {
     this.showEchoSubscription?.unsubscribe();
     this.linemodeSubscription?.unsubscribe();
 
-    this.terminalAttachAddon.dispose();
-    this.socketAdapter.dispose();
+    this.terminalAttachAddon?.dispose();
+    this.socketAdapter?.dispose();
     this.terminal.dispose();
+    this.screenReader?.dispose();
   }
 
   protected connect() {
     const columns = this.terminal.cols;
     const rows = this.terminal.rows;
 
+    this.screenReader?.markSessionStart();
     this.mudService.connect({ columns, rows });
   }
 
@@ -203,6 +227,10 @@ export class MudClientComponent implements AfterViewInit, OnDestroy {
       ? message
       : { value: message };
 
+    if (typeof payload === 'string') {
+      this.screenReader?.appendToHistory(payload);
+    }
+
     this.mudService.sendMessage(payload);
   }
 
@@ -272,6 +300,8 @@ export class MudClientComponent implements AfterViewInit, OnDestroy {
    */
   private afterMudOutput(data: string) {
     this.promptManager.afterServerOutput(data, this.getPromptContext());
+    this.announceToScreenReader(data);
+    this.screenReader?.appendToHistory(data);
   }
 
   /**
@@ -292,6 +322,23 @@ export class MudClientComponent implements AfterViewInit, OnDestroy {
     };
   }
 
+  /**
+   * Announces new server output via the custom screenreader announcer.
+   * Called AFTER prompt restoration so we announce the final visible text.
+   */
+  private announceToScreenReader(data: string): void {
+    if (!this.screenReader) {
+      return;
+    }
+
+    console.debug('[MudClient] Announcing to screenreader:', {
+      rawLength: data.length,
+      raw: data,
+    });
+
+    this.screenReader.announce(data);
+  }
+
   /**
    * Convenience helper for patching the local state object.
    */

frontend/src/app/features/terminal/index.ts

@@ -2,3 +2,4 @@ export * from './models/escapes';
 export * from './mud-input.controller';
 export * from './mud-prompt.manager';
 export * from './mud-socket.adapter';
+export * from './mud-screenreader';

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

@@ -0,0 +1,67 @@
+import { MudScreenReaderAnnouncer } from './mud-screenreader';
+
+describe('MudScreenReaderAnnouncer', () => {
+  let liveRegion: HTMLElement;
+  let announcer: MudScreenReaderAnnouncer;
+
+  beforeEach(() => {
+    jest.useFakeTimers();
+    liveRegion = document.createElement('div');
+    // Explicitly skip history region while overriding clear delay for tests
+    announcer = new MudScreenReaderAnnouncer(liveRegion, undefined, 100);
+  });
+
+  afterEach(() => {
+    announcer.dispose();
+    jest.useRealTimers();
+  });
+
+  it('announces sanitized text and clears after delay', () => {
+    announcer.announce('Hello \x1b[31mWorld\x1b[0m\r\n');
+
+    expect(liveRegion.textContent).toBe('Hello World');
+
+    jest.advanceTimersByTime(99);
+    expect(liveRegion.textContent).toBe('Hello World');
+
+    jest.advanceTimersByTime(1);
+    expect(liveRegion.textContent).toBe('');
+  });
+
+  it('ignores announcements older than the current session', () => {
+    const now = Date.now();
+    const earlier = now - 500;
+
+    announcer.markSessionStart(now);
+    announcer.announce('Old content', earlier);
+
+    expect(liveRegion.textContent).toBe('');
+  });
+
+  it('resets the clear timer for rapid consecutive announcements', () => {
+    announcer.announce('First');
+    jest.advanceTimersByTime(50);
+
+    announcer.announce('Second');
+    jest.advanceTimersByTime(99);
+
+    expect(liveRegion.textContent).toBe('Second');
+
+    jest.advanceTimersByTime(1);
+    expect(liveRegion.textContent).toBe('');
+  });
+
+  it('clear() empties the live region immediately', () => {
+    announcer.announce('Message');
+    expect(liveRegion.textContent).toBe('Message');
+
+    announcer.clear();
+    expect(liveRegion.textContent).toBe('');
+  });
+
+  it('ignores empty output after normalization', () => {
+    announcer.announce('\x1b[31m\x1b[0m');
+
+    expect(liveRegion.textContent).toBe('');
+  });
+});