ddd test

src/app/domains/attachment/application/attachment-manager.service.ts

@@ -0,0 +1,224 @@
+import {
+  Injectable,
+  effect,
+  inject
+} from '@angular/core';
+import { NavigationEnd, Router } from '@angular/router';
+import { RealtimeSessionFacade } from '../../../core/realtime';
+import { DatabaseService } from '../../../infrastructure/persistence';
+import { ROOM_URL_PATTERN } from '../../../core/constants';
+import { shouldAutoRequestWhenWatched } from '../domain/attachment.logic';
+import type { Attachment, AttachmentMeta } from '../domain/attachment.models';
+import type {
+  FileAnnouncePayload,
+  FileCancelPayload,
+  FileChunkPayload,
+  FileNotFoundPayload,
+  FileRequestPayload
+} from '../domain/attachment-transfer.models';
+import { AttachmentPersistenceService } from './attachment-persistence.service';
+import { AttachmentRuntimeStore } from './attachment-runtime.store';
+import { AttachmentTransferService } from './attachment-transfer.service';
+
+@Injectable({ providedIn: 'root' })
+export class AttachmentManagerService {
+  get updated() {
+    return this.runtimeStore.updated;
+  }
+
+  private readonly webrtc = inject(RealtimeSessionFacade);
+  private readonly router = inject(Router);
+  private readonly database = inject(DatabaseService);
+  private readonly runtimeStore = inject(AttachmentRuntimeStore);
+  private readonly persistence = inject(AttachmentPersistenceService);
+  private readonly transfer = inject(AttachmentTransferService);
+
+  private watchedRoomId: string | null = this.extractWatchedRoomId(this.router.url);
+  private isDatabaseInitialised = false;
+
+  constructor() {
+    effect(() => {
+      if (this.database.isReady() && !this.isDatabaseInitialised) {
+        this.isDatabaseInitialised = true;
+        void this.persistence.initFromDatabase();
+      }
+    });
+
+    this.router.events.subscribe((event) => {
+      if (!(event instanceof NavigationEnd)) {
+        return;
+      }
+
+      this.watchedRoomId = this.extractWatchedRoomId(event.urlAfterRedirects || event.url);
+
+      if (this.watchedRoomId) {
+        void this.requestAutoDownloadsForRoom(this.watchedRoomId);
+      }
+    });
+
+    this.webrtc.onPeerConnected.subscribe(() => {
+      if (this.watchedRoomId) {
+        void this.requestAutoDownloadsForRoom(this.watchedRoomId);
+      }
+    });
+  }
+
+  getForMessage(messageId: string): Attachment[] {
+    return this.runtimeStore.getAttachmentsForMessage(messageId);
+  }
+
+  rememberMessageRoom(messageId: string, roomId: string): void {
+    if (!messageId || !roomId)
+      return;
+
+    this.runtimeStore.rememberMessageRoom(messageId, roomId);
+  }
+
+  queueAutoDownloadsForMessage(messageId: string, attachmentId?: string): void {
+    void this.requestAutoDownloadsForMessage(messageId, attachmentId);
+  }
+
+  async requestAutoDownloadsForRoom(roomId: string): Promise<void> {
+    if (!roomId || !this.isRoomWatched(roomId))
+      return;
+
+    if (this.database.isReady()) {
+      const messages = await this.database.getMessages(roomId, 500, 0);
+
+      for (const message of messages) {
+        this.runtimeStore.rememberMessageRoom(message.id, message.roomId);
+        await this.requestAutoDownloadsForMessage(message.id);
+      }
+
+      return;
+    }
+
+    for (const [messageId] of this.runtimeStore.getAttachmentEntries()) {
+      const attachmentRoomId = await this.persistence.resolveMessageRoomId(messageId);
+
+      if (attachmentRoomId === roomId) {
+        await this.requestAutoDownloadsForMessage(messageId);
+      }
+    }
+  }
+
+  async deleteForMessage(messageId: string): Promise<void> {
+    await this.persistence.deleteForMessage(messageId);
+  }
+
+  getAttachmentMetasForMessages(messageIds: string[]): Record<string, AttachmentMeta[]> {
+    return this.transfer.getAttachmentMetasForMessages(messageIds);
+  }
+
+  registerSyncedAttachments(
+    attachmentMap: Record<string, AttachmentMeta[]>,
+    messageRoomIds?: Record<string, string>
+  ): void {
+    this.transfer.registerSyncedAttachments(attachmentMap, messageRoomIds);
+
+    for (const [messageId, attachments] of Object.entries(attachmentMap)) {
+      for (const attachment of attachments) {
+        this.queueAutoDownloadsForMessage(messageId, attachment.id);
+      }
+    }
+  }
+
+  requestFromAnyPeer(messageId: string, attachment: Attachment): void {
+    this.transfer.requestFromAnyPeer(messageId, attachment);
+  }
+
+  handleFileNotFound(payload: FileNotFoundPayload): void {
+    this.transfer.handleFileNotFound(payload);
+  }
+
+  requestImageFromAnyPeer(messageId: string, attachment: Attachment): void {
+    this.transfer.requestImageFromAnyPeer(messageId, attachment);
+  }
+
+  requestFile(messageId: string, attachment: Attachment): void {
+    this.transfer.requestFile(messageId, attachment);
+  }
+
+  async publishAttachments(
+    messageId: string,
+    files: File[],
+    uploaderPeerId?: string
+  ): Promise<void> {
+    await this.transfer.publishAttachments(messageId, files, uploaderPeerId);
+  }
+
+  handleFileAnnounce(payload: FileAnnouncePayload): void {
+    this.transfer.handleFileAnnounce(payload);
+
+    if (payload.messageId && payload.file?.id) {
+      this.queueAutoDownloadsForMessage(payload.messageId, payload.file.id);
+    }
+  }
+
+  handleFileChunk(payload: FileChunkPayload): void {
+    this.transfer.handleFileChunk(payload);
+  }
+
+  async handleFileRequest(payload: FileRequestPayload): Promise<void> {
+    await this.transfer.handleFileRequest(payload);
+  }
+
+  cancelRequest(messageId: string, attachment: Attachment): void {
+    this.transfer.cancelRequest(messageId, attachment);
+  }
+
+  handleFileCancel(payload: FileCancelPayload): void {
+    this.transfer.handleFileCancel(payload);
+  }
+
+  async fulfillRequestWithFile(
+    messageId: string,
+    fileId: string,
+    targetPeerId: string,
+    file: File
+  ): Promise<void> {
+    await this.transfer.fulfillRequestWithFile(messageId, fileId, targetPeerId, file);
+  }
+
+  private async requestAutoDownloadsForMessage(messageId: string, attachmentId?: string): Promise<void> {
+    if (!messageId)
+      return;
+
+    const roomId = await this.persistence.resolveMessageRoomId(messageId);
+
+    if (!roomId || !this.isRoomWatched(roomId) || this.webrtc.getConnectedPeers().length === 0) {
+      return;
+    }
+
+    const attachments = this.runtimeStore.getAttachmentsForMessage(messageId);
+
+    for (const attachment of attachments) {
+      if (attachmentId && attachment.id !== attachmentId)
+        continue;
+
+      if (!shouldAutoRequestWhenWatched(attachment))
+        continue;
+
+      if (attachment.available)
+        continue;
+
+      if ((attachment.receivedBytes ?? 0) > 0)
+        continue;
+
+      if (this.transfer.hasPendingRequest(messageId, attachment.id))
+        continue;
+
+      this.transfer.requestFromAnyPeer(messageId, attachment);
+    }
+  }
+
+  private extractWatchedRoomId(url: string): string | null {
+    const roomMatch = url.match(ROOM_URL_PATTERN);
+
+    return roomMatch ? roomMatch[1] : null;
+  }
+
+  private isRoomWatched(roomId: string | null | undefined): boolean {
+    return !!roomId && roomId === this.watchedRoomId;
+  }
+}

src/app/domains/attachment/application/attachment-persistence.service.ts

@@ -0,0 +1,264 @@
+import { Injectable, inject } from '@angular/core';
+import { take } from 'rxjs';
+import { Store } from '@ngrx/store';
+import { selectCurrentRoomName } from '../../../store/rooms/rooms.selectors';
+import { DatabaseService } from '../../../infrastructure/persistence';
+import { AttachmentStorageService } from '../infrastructure/attachment-storage.service';
+import type { Attachment, AttachmentMeta } from '../domain/attachment.models';
+import { MAX_AUTO_SAVE_SIZE_BYTES } from '../domain/attachment.constants';
+import { LEGACY_ATTACHMENTS_STORAGE_KEY } from '../domain/attachment-transfer.constants';
+import { AttachmentRuntimeStore } from './attachment-runtime.store';
+
+@Injectable({ providedIn: 'root' })
+export class AttachmentPersistenceService {
+  private readonly runtimeStore = inject(AttachmentRuntimeStore);
+  private readonly ngrxStore = inject(Store);
+  private readonly attachmentStorage = inject(AttachmentStorageService);
+  private readonly database = inject(DatabaseService);
+
+  async deleteForMessage(messageId: string): Promise<void> {
+    const attachments = this.runtimeStore.getAttachmentsForMessage(messageId);
+    const hadCachedAttachments = attachments.length > 0 || this.runtimeStore.hasAttachmentsForMessage(messageId);
+    const retainedSavedPaths = await this.getRetainedSavedPathsForOtherMessages(messageId);
+    const savedPathsToDelete = new Set<string>();
+
+    for (const attachment of attachments) {
+      if (attachment.objectUrl) {
+        try {
+          URL.revokeObjectURL(attachment.objectUrl);
+        } catch { /* ignore */ }
+      }
+
+      if (attachment.savedPath && !retainedSavedPaths.has(attachment.savedPath)) {
+        savedPathsToDelete.add(attachment.savedPath);
+      }
+    }
+
+    this.runtimeStore.deleteAttachmentsForMessage(messageId);
+    this.runtimeStore.deleteMessageRoom(messageId);
+    this.runtimeStore.clearMessageScopedState(messageId);
+
+    if (hadCachedAttachments) {
+      this.runtimeStore.touch();
+    }
+
+    if (this.database.isReady()) {
+      await this.database.deleteAttachmentsForMessage(messageId);
+    }
+
+    for (const diskPath of savedPathsToDelete) {
+      await this.attachmentStorage.deleteFile(diskPath);
+    }
+  }
+
+  async persistAttachmentMeta(attachment: Attachment): Promise<void> {
+    if (!this.database.isReady())
+      return;
+
+    try {
+      await this.database.saveAttachment({
+        id: attachment.id,
+        messageId: attachment.messageId,
+        filename: attachment.filename,
+        size: attachment.size,
+        mime: attachment.mime,
+        isImage: attachment.isImage,
+        uploaderPeerId: attachment.uploaderPeerId,
+        filePath: attachment.filePath,
+        savedPath: attachment.savedPath
+      });
+    } catch { /* persistence is best-effort */ }
+  }
+
+  async saveFileToDisk(attachment: Attachment, blob: Blob): Promise<void> {
+    try {
+      const roomName = await this.resolveCurrentRoomName();
+      const diskPath = await this.attachmentStorage.saveBlob(attachment, blob, roomName);
+
+      if (!diskPath)
+        return;
+
+      attachment.savedPath = diskPath;
+      void this.persistAttachmentMeta(attachment);
+    } catch { /* disk save is best-effort */ }
+  }
+
+  async initFromDatabase(): Promise<void> {
+    await this.loadFromDatabase();
+    await this.migrateFromLocalStorage();
+    await this.tryLoadSavedFiles();
+  }
+
+  async resolveMessageRoomId(messageId: string): Promise<string | null> {
+    const cachedRoomId = this.runtimeStore.getMessageRoomId(messageId);
+
+    if (cachedRoomId)
+      return cachedRoomId;
+
+    if (!this.database.isReady())
+      return null;
+
+    try {
+      const message = await this.database.getMessageById(messageId);
+
+      if (!message?.roomId)
+        return null;
+
+      this.runtimeStore.rememberMessageRoom(messageId, message.roomId);
+      return message.roomId;
+    } catch {
+      return null;
+    }
+  }
+
+  async resolveCurrentRoomName(): Promise<string> {
+    return new Promise<string>((resolve) => {
+      this.ngrxStore
+        .select(selectCurrentRoomName)
+        .pipe(take(1))
+        .subscribe((name) => resolve(name || ''));
+    });
+  }
+
+  private async loadFromDatabase(): Promise<void> {
+    try {
+      const allRecords: AttachmentMeta[] = await this.database.getAllAttachments();
+      const grouped = new Map<string, Attachment[]>();
+
+      for (const record of allRecords) {
+        const attachment: Attachment = { ...record,
+          available: false };
+        const bucket = grouped.get(record.messageId) ?? [];
+
+        bucket.push(attachment);
+        grouped.set(record.messageId, bucket);
+      }
+
+      this.runtimeStore.replaceAttachments(grouped);
+      this.runtimeStore.touch();
+    } catch { /* load is best-effort */ }
+  }
+
+  private async migrateFromLocalStorage(): Promise<void> {
+    try {
+      const raw = localStorage.getItem(LEGACY_ATTACHMENTS_STORAGE_KEY);
+
+      if (!raw)
+        return;
+
+      const legacyRecords: AttachmentMeta[] = JSON.parse(raw);
+
+      for (const meta of legacyRecords) {
+        const existing = [...this.runtimeStore.getAttachmentsForMessage(meta.messageId)];
+
+        if (!existing.find((entry) => entry.id === meta.id)) {
+          const attachment: Attachment = { ...meta,
+            available: false };
+
+          existing.push(attachment);
+          this.runtimeStore.setAttachmentsForMessage(meta.messageId, existing);
+          void this.persistAttachmentMeta(attachment);
+        }
+      }
+
+      localStorage.removeItem(LEGACY_ATTACHMENTS_STORAGE_KEY);
+      this.runtimeStore.touch();
+    } catch { /* migration is best-effort */ }
+  }
+
+  private async tryLoadSavedFiles(): Promise<void> {
+    try {
+      let hasChanges = false;
+
+      for (const [, attachments] of this.runtimeStore.getAttachmentEntries()) {
+        for (const attachment of attachments) {
+          if (attachment.available)
+            continue;
+
+          if (attachment.savedPath) {
+            const savedBase64 = await this.attachmentStorage.readFile(attachment.savedPath);
+
+            if (savedBase64) {
+              this.restoreAttachmentFromDisk(attachment, savedBase64);
+              hasChanges = true;
+              continue;
+            }
+          }
+
+          if (attachment.filePath) {
+            const originalBase64 = await this.attachmentStorage.readFile(attachment.filePath);
+
+            if (originalBase64) {
+              this.restoreAttachmentFromDisk(attachment, originalBase64);
+              hasChanges = true;
+
+              if (attachment.size <= MAX_AUTO_SAVE_SIZE_BYTES && attachment.objectUrl) {
+                const response = await fetch(attachment.objectUrl);
+
+                void this.saveFileToDisk(attachment, await response.blob());
+              }
+
+              continue;
+            }
+          }
+        }
+      }
+
+      if (hasChanges)
+        this.runtimeStore.touch();
+    } catch { /* startup load is best-effort */ }
+  }
+
+  private restoreAttachmentFromDisk(attachment: Attachment, base64: string): void {
+    const bytes = this.base64ToUint8Array(base64);
+    const blob = new Blob([bytes.buffer as ArrayBuffer], { type: attachment.mime });
+
+    attachment.objectUrl = URL.createObjectURL(blob);
+    attachment.available = true;
+
+    this.runtimeStore.setOriginalFile(
+      `${attachment.messageId}:${attachment.id}`,
+      new File([blob], attachment.filename, { type: attachment.mime })
+    );
+  }
+
+  private async getRetainedSavedPathsForOtherMessages(messageId: string): Promise<Set<string>> {
+    const retainedSavedPaths = new Set<string>();
+
+    for (const [existingMessageId, attachments] of this.runtimeStore.getAttachmentEntries()) {
+      if (existingMessageId === messageId)
+        continue;
+
+      for (const attachment of attachments) {
+        if (attachment.savedPath) {
+          retainedSavedPaths.add(attachment.savedPath);
+        }
+      }
+    }
+
+    if (!this.database.isReady()) {
+      return retainedSavedPaths;
+    }
+
+    const persistedAttachments = await this.database.getAllAttachments();
+
+    for (const attachment of persistedAttachments) {
+      if (attachment.messageId !== messageId && attachment.savedPath) {
+        retainedSavedPaths.add(attachment.savedPath);
+      }
+    }
+
+    return retainedSavedPaths;
+  }
+
+  private base64ToUint8Array(base64: string): Uint8Array {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+
+    for (let index = 0; index < binary.length; index++) {
+      bytes[index] = binary.charCodeAt(index);
+    }
+
+    return bytes;
+  }
+}

src/app/domains/attachment/application/attachment-runtime.store.ts

@@ -0,0 +1,160 @@
+import { Injectable, signal } from '@angular/core';
+import type { Attachment } from '../domain/attachment.models';
+
+@Injectable({ providedIn: 'root' })
+export class AttachmentRuntimeStore {
+  readonly updated = signal<number>(0);
+
+  private attachmentsByMessage = new Map<string, Attachment[]>();
+  private messageRoomIds = new Map<string, string>();
+  private originalFiles = new Map<string, File>();
+  private cancelledTransfers = new Set<string>();
+  private pendingRequests = new Map<string, Set<string>>();
+  private chunkBuffers = new Map<string, ArrayBuffer[]>();
+  private chunkCounts = new Map<string, number>();
+
+  touch(): void {
+    this.updated.set(this.updated() + 1);
+  }
+
+  getAttachmentsForMessage(messageId: string): Attachment[] {
+    return this.attachmentsByMessage.get(messageId) ?? [];
+  }
+
+  setAttachmentsForMessage(messageId: string, attachments: Attachment[]): void {
+    if (attachments.length === 0) {
+      this.attachmentsByMessage.delete(messageId);
+      return;
+    }
+
+    this.attachmentsByMessage.set(messageId, attachments);
+  }
+
+  hasAttachmentsForMessage(messageId: string): boolean {
+    return this.attachmentsByMessage.has(messageId);
+  }
+
+  deleteAttachmentsForMessage(messageId: string): void {
+    this.attachmentsByMessage.delete(messageId);
+  }
+
+  replaceAttachments(nextAttachments: Map<string, Attachment[]>): void {
+    this.attachmentsByMessage = nextAttachments;
+  }
+
+  getAttachmentEntries(): IterableIterator<[string, Attachment[]]> {
+    return this.attachmentsByMessage.entries();
+  }
+
+  rememberMessageRoom(messageId: string, roomId: string): void {
+    this.messageRoomIds.set(messageId, roomId);
+  }
+
+  getMessageRoomId(messageId: string): string | undefined {
+    return this.messageRoomIds.get(messageId);
+  }
+
+  deleteMessageRoom(messageId: string): void {
+    this.messageRoomIds.delete(messageId);
+  }
+
+  setOriginalFile(key: string, file: File): void {
+    this.originalFiles.set(key, file);
+  }
+
+  getOriginalFile(key: string): File | undefined {
+    return this.originalFiles.get(key);
+  }
+
+  findOriginalFileByFileId(fileId: string): File | null {
+    for (const [key, file] of this.originalFiles) {
+      if (key.endsWith(`:${fileId}`)) {
+        return file;
+      }
+    }
+
+    return null;
+  }
+
+  addCancelledTransfer(key: string): void {
+    this.cancelledTransfers.add(key);
+  }
+
+  hasCancelledTransfer(key: string): boolean {
+    return this.cancelledTransfers.has(key);
+  }
+
+  setPendingRequestPeers(key: string, peers: Set<string>): void {
+    this.pendingRequests.set(key, peers);
+  }
+
+  getPendingRequestPeers(key: string): Set<string> | undefined {
+    return this.pendingRequests.get(key);
+  }
+
+  hasPendingRequest(key: string): boolean {
+    return this.pendingRequests.has(key);
+  }
+
+  deletePendingRequest(key: string): void {
+    this.pendingRequests.delete(key);
+  }
+
+  setChunkBuffer(key: string, buffer: ArrayBuffer[]): void {
+    this.chunkBuffers.set(key, buffer);
+  }
+
+  getChunkBuffer(key: string): ArrayBuffer[] | undefined {
+    return this.chunkBuffers.get(key);
+  }
+
+  deleteChunkBuffer(key: string): void {
+    this.chunkBuffers.delete(key);
+  }
+
+  setChunkCount(key: string, count: number): void {
+    this.chunkCounts.set(key, count);
+  }
+
+  getChunkCount(key: string): number | undefined {
+    return this.chunkCounts.get(key);
+  }
+
+  deleteChunkCount(key: string): void {
+    this.chunkCounts.delete(key);
+  }
+
+  clearMessageScopedState(messageId: string): void {
+    const scopedPrefix = `${messageId}:`;
+
+    for (const key of Array.from(this.originalFiles.keys())) {
+      if (key.startsWith(scopedPrefix)) {
+        this.originalFiles.delete(key);
+      }
+    }
+
+    for (const key of Array.from(this.pendingRequests.keys())) {
+      if (key.startsWith(scopedPrefix)) {
+        this.pendingRequests.delete(key);
+      }
+    }
+
+    for (const key of Array.from(this.chunkBuffers.keys())) {
+      if (key.startsWith(scopedPrefix)) {
+        this.chunkBuffers.delete(key);
+      }
+    }
+
+    for (const key of Array.from(this.chunkCounts.keys())) {
+      if (key.startsWith(scopedPrefix)) {
+        this.chunkCounts.delete(key);
+      }
+    }
+
+    for (const key of Array.from(this.cancelledTransfers)) {
+      if (key.startsWith(scopedPrefix)) {
+        this.cancelledTransfers.delete(key);
+      }
+    }
+  }
+}

src/app/domains/attachment/application/attachment-transfer-transport.service.ts

@@ -0,0 +1,109 @@
+import { Injectable, inject } from '@angular/core';
+import { RealtimeSessionFacade } from '../../../core/realtime';
+import { AttachmentStorageService } from '../infrastructure/attachment-storage.service';
+import { FILE_CHUNK_SIZE_BYTES } from '../domain/attachment-transfer.constants';
+import { FileChunkEvent } from '../domain/attachment-transfer.models';
+
+@Injectable({ providedIn: 'root' })
+export class AttachmentTransferTransportService {
+  private readonly webrtc = inject(RealtimeSessionFacade);
+  private readonly attachmentStorage = inject(AttachmentStorageService);
+
+  decodeBase64(base64: string): Uint8Array {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+
+    for (let index = 0; index < binary.length; index++) {
+      bytes[index] = binary.charCodeAt(index);
+    }
+
+    return bytes;
+  }
+
+  async streamFileToPeer(
+    targetPeerId: string,
+    messageId: string,
+    fileId: string,
+    file: File,
+    isCancelled: () => boolean
+  ): Promise<void> {
+    const totalChunks = Math.ceil(file.size / FILE_CHUNK_SIZE_BYTES);
+
+    let offset = 0;
+    let chunkIndex = 0;
+
+    while (offset < file.size) {
+      if (isCancelled())
+        break;
+
+      const slice = file.slice(offset, offset + FILE_CHUNK_SIZE_BYTES);
+      const arrayBuffer = await slice.arrayBuffer();
+      const base64 = this.arrayBufferToBase64(arrayBuffer);
+      const fileChunkEvent: FileChunkEvent = {
+        type: 'file-chunk',
+        messageId,
+        fileId,
+        index: chunkIndex,
+        total: totalChunks,
+        data: base64
+      };
+
+      await this.webrtc.sendToPeerBuffered(targetPeerId, fileChunkEvent);
+
+      offset += FILE_CHUNK_SIZE_BYTES;
+      chunkIndex++;
+    }
+  }
+
+  async streamFileFromDiskToPeer(
+    targetPeerId: string,
+    messageId: string,
+    fileId: string,
+    diskPath: string,
+    isCancelled: () => boolean
+  ): Promise<void> {
+    const base64Full = await this.attachmentStorage.readFile(diskPath);
+
+    if (!base64Full)
+      return;
+
+    const fileBytes = this.decodeBase64(base64Full);
+    const totalChunks = Math.ceil(fileBytes.byteLength / FILE_CHUNK_SIZE_BYTES);
+
+    for (let chunkIndex = 0; chunkIndex < totalChunks; chunkIndex++) {
+      if (isCancelled())
+        break;
+
+      const start = chunkIndex * FILE_CHUNK_SIZE_BYTES;
+      const end = Math.min(fileBytes.byteLength, start + FILE_CHUNK_SIZE_BYTES);
+      const slice = fileBytes.subarray(start, end);
+      const sliceBuffer = (slice.buffer as ArrayBuffer).slice(
+        slice.byteOffset,
+        slice.byteOffset + slice.byteLength
+      );
+      const base64Chunk = this.arrayBufferToBase64(sliceBuffer);
+      const fileChunkEvent: FileChunkEvent = {
+        type: 'file-chunk',
+        messageId,
+        fileId,
+        index: chunkIndex,
+        total: totalChunks,
+        data: base64Chunk
+      };
+
+      this.webrtc.sendToPeer(targetPeerId, fileChunkEvent);
+    }
+  }
+
+  private arrayBufferToBase64(buffer: ArrayBuffer): string {
+    let binary = '';
+
+    const bytes = new Uint8Array(buffer);
+
+    for (let index = 0; index < bytes.byteLength; index++) {
+      binary += String.fromCharCode(bytes[index]);
+    }
+
+    return btoa(binary);
+  }
+}

src/app/domains/attachment/application/attachment-transfer.service.ts

@@ -0,0 +1,566 @@
+import { Injectable, inject } from '@angular/core';
+import { recordDebugNetworkFileChunk } from '../../../infrastructure/realtime/logging/debug-network-metrics';
+import { RealtimeSessionFacade } from '../../../core/realtime';
+import { AttachmentStorageService } from '../infrastructure/attachment-storage.service';
+import { MAX_AUTO_SAVE_SIZE_BYTES } from '../domain/attachment.constants';
+import { shouldPersistDownloadedAttachment } from '../domain/attachment.logic';
+import type { Attachment, AttachmentMeta } from '../domain/attachment.models';
+import {
+  ATTACHMENT_TRANSFER_EWMA_CURRENT_WEIGHT,
+  ATTACHMENT_TRANSFER_EWMA_PREVIOUS_WEIGHT,
+  DEFAULT_ATTACHMENT_MIME_TYPE,
+  FILE_NOT_FOUND_REQUEST_ERROR,
+  NO_CONNECTED_PEERS_REQUEST_ERROR
+} from '../domain/attachment-transfer.constants';
+import {
+  type FileAnnounceEvent,
+  type FileAnnouncePayload,
+  type FileCancelEvent,
+  type FileCancelPayload,
+  type FileChunkPayload,
+  type FileNotFoundEvent,
+  type FileNotFoundPayload,
+  type FileRequestEvent,
+  type FileRequestPayload,
+  type LocalFileWithPath
+} from '../domain/attachment-transfer.models';
+import { AttachmentPersistenceService } from './attachment-persistence.service';
+import { AttachmentRuntimeStore } from './attachment-runtime.store';
+import { AttachmentTransferTransportService } from './attachment-transfer-transport.service';
+
+@Injectable({ providedIn: 'root' })
+export class AttachmentTransferService {
+  private readonly webrtc = inject(RealtimeSessionFacade);
+  private readonly runtimeStore = inject(AttachmentRuntimeStore);
+  private readonly attachmentStorage = inject(AttachmentStorageService);
+  private readonly persistence = inject(AttachmentPersistenceService);
+  private readonly transport = inject(AttachmentTransferTransportService);
+
+  getAttachmentMetasForMessages(messageIds: string[]): Record<string, AttachmentMeta[]> {
+    const result: Record<string, AttachmentMeta[]> = {};
+
+    for (const messageId of messageIds) {
+      const attachments = this.runtimeStore.getAttachmentsForMessage(messageId);
+
+      if (attachments.length > 0) {
+        result[messageId] = attachments.map((attachment) => ({
+          id: attachment.id,
+          messageId: attachment.messageId,
+          filename: attachment.filename,
+          size: attachment.size,
+          mime: attachment.mime,
+          isImage: attachment.isImage,
+          uploaderPeerId: attachment.uploaderPeerId,
+          filePath: undefined,
+          savedPath: undefined
+        }));
+      }
+    }
+
+    return result;
+  }
+
+  registerSyncedAttachments(
+    attachmentMap: Record<string, AttachmentMeta[]>,
+    messageRoomIds?: Record<string, string>
+  ): void {
+    if (messageRoomIds) {
+      for (const [messageId, roomId] of Object.entries(messageRoomIds)) {
+        this.runtimeStore.rememberMessageRoom(messageId, roomId);
+      }
+    }
+
+    const newAttachments: Attachment[] = [];
+
+    for (const [messageId, metas] of Object.entries(attachmentMap)) {
+      const existing = [...this.runtimeStore.getAttachmentsForMessage(messageId)];
+
+      for (const meta of metas) {
+        const alreadyKnown = existing.find((entry) => entry.id === meta.id);
+
+        if (!alreadyKnown) {
+          const attachment: Attachment = { ...meta,
+            available: false,
+            receivedBytes: 0 };
+
+          existing.push(attachment);
+          newAttachments.push(attachment);
+        }
+      }
+
+      this.runtimeStore.setAttachmentsForMessage(messageId, existing);
+    }
+
+    if (newAttachments.length > 0) {
+      this.runtimeStore.touch();
+
+      for (const attachment of newAttachments) {
+        void this.persistence.persistAttachmentMeta(attachment);
+      }
+    }
+  }
+
+  requestFromAnyPeer(messageId: string, attachment: Attachment): void {
+    const clearedRequestError = this.clearAttachmentRequestError(attachment);
+    const connectedPeers = this.webrtc.getConnectedPeers();
+
+    if (connectedPeers.length === 0) {
+      attachment.requestError = NO_CONNECTED_PEERS_REQUEST_ERROR;
+      this.runtimeStore.touch();
+      console.warn('[Attachments] No connected peers to request file from');
+      return;
+    }
+
+    if (clearedRequestError)
+      this.runtimeStore.touch();
+
+    this.runtimeStore.setPendingRequestPeers(
+      this.buildRequestKey(messageId, attachment.id),
+      new Set<string>()
+    );
+
+    this.sendFileRequestToNextPeer(messageId, attachment.id, attachment.uploaderPeerId);
+  }
+
+  handleFileNotFound(payload: FileNotFoundPayload): void {
+    const { messageId, fileId } = payload;
+
+    if (!messageId || !fileId)
+      return;
+
+    const attachments = this.runtimeStore.getAttachmentsForMessage(messageId);
+    const attachment = attachments.find((entry) => entry.id === fileId);
+    const didSendRequest = this.sendFileRequestToNextPeer(messageId, fileId, attachment?.uploaderPeerId);
+
+    if (!didSendRequest && attachment) {
+      attachment.requestError = FILE_NOT_FOUND_REQUEST_ERROR;
+      this.runtimeStore.touch();
+    }
+  }
+
+  requestImageFromAnyPeer(messageId: string, attachment: Attachment): void {
+    this.requestFromAnyPeer(messageId, attachment);
+  }
+
+  requestFile(messageId: string, attachment: Attachment): void {
+    this.requestFromAnyPeer(messageId, attachment);
+  }
+
+  hasPendingRequest(messageId: string, fileId: string): boolean {
+    return this.runtimeStore.hasPendingRequest(this.buildRequestKey(messageId, fileId));
+  }
+
+  async publishAttachments(
+    messageId: string,
+    files: File[],
+    uploaderPeerId?: string
+  ): Promise<void> {
+    const attachments: Attachment[] = [];
+
+    for (const file of files) {
+      const fileId = crypto.randomUUID?.() ?? `${Date.now()}-${Math.random()}`;
+      const attachment: Attachment = {
+        id: fileId,
+        messageId,
+        filename: file.name,
+        size: file.size,
+        mime: file.type || DEFAULT_ATTACHMENT_MIME_TYPE,
+        isImage: file.type.startsWith('image/'),
+        uploaderPeerId,
+        filePath: (file as LocalFileWithPath).path,
+        available: false
+      };
+
+      attachments.push(attachment);
+      this.runtimeStore.setOriginalFile(`${messageId}:${fileId}`, file);
+
+      try {
+        attachment.objectUrl = URL.createObjectURL(file);
+        attachment.available = true;
+      } catch { /* non-critical */ }
+
+      if (attachment.size <= MAX_AUTO_SAVE_SIZE_BYTES) {
+        void this.persistence.saveFileToDisk(attachment, file);
+      }
+
+      const fileAnnounceEvent: FileAnnounceEvent = {
+        type: 'file-announce',
+        messageId,
+        file: {
+          id: fileId,
+          filename: attachment.filename,
+          size: attachment.size,
+          mime: attachment.mime,
+          isImage: attachment.isImage,
+          uploaderPeerId
+        }
+      };
+
+      this.webrtc.broadcastMessage(fileAnnounceEvent);
+    }
+
+    const existingList = this.runtimeStore.getAttachmentsForMessage(messageId);
+
+    this.runtimeStore.setAttachmentsForMessage(messageId, [...existingList, ...attachments]);
+    this.runtimeStore.touch();
+
+    for (const attachment of attachments) {
+      void this.persistence.persistAttachmentMeta(attachment);
+    }
+  }
+
+  handleFileAnnounce(payload: FileAnnouncePayload): void {
+    const { messageId, file } = payload;
+
+    if (!messageId || !file)
+      return;
+
+    const list = [...this.runtimeStore.getAttachmentsForMessage(messageId)];
+    const alreadyKnown = list.find((entry) => entry.id === file.id);
+
+    if (alreadyKnown)
+      return;
+
+    const attachment: Attachment = {
+      id: file.id,
+      messageId,
+      filename: file.filename,
+      size: file.size,
+      mime: file.mime,
+      isImage: !!file.isImage,
+      uploaderPeerId: file.uploaderPeerId,
+      available: false,
+      receivedBytes: 0
+    };
+
+    list.push(attachment);
+    this.runtimeStore.setAttachmentsForMessage(messageId, list);
+    this.runtimeStore.touch();
+    void this.persistence.persistAttachmentMeta(attachment);
+  }
+
+  handleFileChunk(payload: FileChunkPayload): void {
+    const { messageId, fileId, fromPeerId, index, total, data } = payload;
+
+    if (
+      !messageId || !fileId ||
+      typeof index !== 'number' ||
+      typeof total !== 'number' ||
+      typeof data !== 'string'
+    ) {
+      return;
+    }
+
+    const list = this.runtimeStore.getAttachmentsForMessage(messageId);
+    const attachment = list.find((entry) => entry.id === fileId);
+
+    if (!attachment)
+      return;
+
+    const decodedBytes = this.transport.decodeBase64(data);
+    const assemblyKey = `${messageId}:${fileId}`;
+    const requestKey = this.buildRequestKey(messageId, fileId);
+
+    this.runtimeStore.deletePendingRequest(requestKey);
+    this.clearAttachmentRequestError(attachment);
+
+    const chunkBuffer = this.getOrCreateChunkBuffer(assemblyKey, total);
+
+    if (!chunkBuffer[index]) {
+      chunkBuffer[index] = decodedBytes.buffer as ArrayBuffer;
+      this.runtimeStore.setChunkCount(assemblyKey, (this.runtimeStore.getChunkCount(assemblyKey) ?? 0) + 1);
+    }
+
+    this.updateTransferProgress(attachment, decodedBytes, fromPeerId);
+
+    this.runtimeStore.touch();
+    this.finalizeTransferIfComplete(attachment, assemblyKey, total);
+  }
+
+  async handleFileRequest(payload: FileRequestPayload): Promise<void> {
+    const { messageId, fileId, fromPeerId } = payload;
+
+    if (!messageId || !fileId || !fromPeerId)
+      return;
+
+    const exactKey = `${messageId}:${fileId}`;
+    const originalFile = this.runtimeStore.getOriginalFile(exactKey)
+      ?? this.runtimeStore.findOriginalFileByFileId(fileId);
+
+    if (originalFile) {
+      await this.transport.streamFileToPeer(
+        fromPeerId,
+        messageId,
+        fileId,
+        originalFile,
+        () => this.isTransferCancelled(fromPeerId, messageId, fileId)
+      );
+
+      return;
+    }
+
+    const list = this.runtimeStore.getAttachmentsForMessage(messageId);
+    const attachment = list.find((entry) => entry.id === fileId);
+    const diskPath = attachment
+      ? await this.attachmentStorage.resolveExistingPath(attachment)
+      : null;
+
+    if (diskPath) {
+      await this.transport.streamFileFromDiskToPeer(
+        fromPeerId,
+        messageId,
+        fileId,
+        diskPath,
+        () => this.isTransferCancelled(fromPeerId, messageId, fileId)
+      );
+
+      return;
+    }
+
+    if (attachment?.isImage) {
+      const roomName = await this.persistence.resolveCurrentRoomName();
+      const legacyDiskPath = await this.attachmentStorage.resolveLegacyImagePath(
+        attachment.filename,
+        roomName
+      );
+
+      if (legacyDiskPath) {
+        await this.transport.streamFileFromDiskToPeer(
+          fromPeerId,
+          messageId,
+          fileId,
+          legacyDiskPath,
+          () => this.isTransferCancelled(fromPeerId, messageId, fileId)
+        );
+
+        return;
+      }
+    }
+
+    if (attachment?.available && attachment.objectUrl) {
+      try {
+        const response = await fetch(attachment.objectUrl);
+        const blob = await response.blob();
+        const file = new File([blob], attachment.filename, { type: attachment.mime });
+
+        await this.transport.streamFileToPeer(
+          fromPeerId,
+          messageId,
+          fileId,
+          file,
+          () => this.isTransferCancelled(fromPeerId, messageId, fileId)
+        );
+
+        return;
+      } catch { /* fall through */ }
+    }
+
+    const fileNotFoundEvent: FileNotFoundEvent = {
+      type: 'file-not-found',
+      messageId,
+      fileId
+    };
+
+    this.webrtc.sendToPeer(fromPeerId, fileNotFoundEvent);
+  }
+
+  cancelRequest(messageId: string, attachment: Attachment): void {
+    const targetPeerId = attachment.uploaderPeerId;
+
+    if (!targetPeerId)
+      return;
+
+    try {
+      const assemblyKey = `${messageId}:${attachment.id}`;
+
+      this.runtimeStore.deleteChunkBuffer(assemblyKey);
+      this.runtimeStore.deleteChunkCount(assemblyKey);
+
+      attachment.receivedBytes = 0;
+      attachment.speedBps = 0;
+      attachment.startedAtMs = undefined;
+      attachment.lastUpdateMs = undefined;
+
+      if (attachment.objectUrl) {
+        try {
+          URL.revokeObjectURL(attachment.objectUrl);
+        } catch { /* ignore */ }
+
+        attachment.objectUrl = undefined;
+      }
+
+      attachment.available = false;
+      this.runtimeStore.touch();
+
+      const fileCancelEvent: FileCancelEvent = {
+        type: 'file-cancel',
+        messageId,
+        fileId: attachment.id
+      };
+
+      this.webrtc.sendToPeer(targetPeerId, fileCancelEvent);
+    } catch { /* best-effort */ }
+  }
+
+  handleFileCancel(payload: FileCancelPayload): void {
+    const { messageId, fileId, fromPeerId } = payload;
+
+    if (!messageId || !fileId || !fromPeerId)
+      return;
+
+    this.runtimeStore.addCancelledTransfer(
+      this.buildTransferKey(messageId, fileId, fromPeerId)
+    );
+  }
+
+  async fulfillRequestWithFile(
+    messageId: string,
+    fileId: string,
+    targetPeerId: string,
+    file: File
+  ): Promise<void> {
+    this.runtimeStore.setOriginalFile(`${messageId}:${fileId}`, file);
+    await this.transport.streamFileToPeer(
+      targetPeerId,
+      messageId,
+      fileId,
+      file,
+      () => this.isTransferCancelled(targetPeerId, messageId, fileId)
+    );
+  }
+
+  private buildTransferKey(messageId: string, fileId: string, peerId: string): string {
+    return `${messageId}:${fileId}:${peerId}`;
+  }
+
+  private buildRequestKey(messageId: string, fileId: string): string {
+    return `${messageId}:${fileId}`;
+  }
+
+  private clearAttachmentRequestError(attachment: Attachment): boolean {
+    if (!attachment.requestError)
+      return false;
+
+    attachment.requestError = undefined;
+    return true;
+  }
+
+  private isTransferCancelled(targetPeerId: string, messageId: string, fileId: string): boolean {
+    return this.runtimeStore.hasCancelledTransfer(
+      this.buildTransferKey(messageId, fileId, targetPeerId)
+    );
+  }
+
+  private sendFileRequestToNextPeer(
+    messageId: string,
+    fileId: string,
+    preferredPeerId?: string
+  ): boolean {
+    const connectedPeers = this.webrtc.getConnectedPeers();
+    const requestKey = this.buildRequestKey(messageId, fileId);
+    const triedPeers = this.runtimeStore.getPendingRequestPeers(requestKey) ?? new Set<string>();
+
+    let targetPeerId: string | undefined;
+
+    if (preferredPeerId && connectedPeers.includes(preferredPeerId) && !triedPeers.has(preferredPeerId)) {
+      targetPeerId = preferredPeerId;
+    } else {
+      targetPeerId = connectedPeers.find((peerId) => !triedPeers.has(peerId));
+    }
+
+    if (!targetPeerId) {
+      this.runtimeStore.deletePendingRequest(requestKey);
+      return false;
+    }
+
+    triedPeers.add(targetPeerId);
+    this.runtimeStore.setPendingRequestPeers(requestKey, triedPeers);
+
+    const fileRequestEvent: FileRequestEvent = {
+      type: 'file-request',
+      messageId,
+      fileId
+    };
+
+    this.webrtc.sendToPeer(targetPeerId, fileRequestEvent);
+
+    return true;
+  }
+
+  private getOrCreateChunkBuffer(assemblyKey: string, total: number): ArrayBuffer[] {
+    const existingChunkBuffer = this.runtimeStore.getChunkBuffer(assemblyKey);
+
+    if (existingChunkBuffer) {
+      return existingChunkBuffer;
+    }
+
+    const createdChunkBuffer = new Array(total);
+
+    this.runtimeStore.setChunkBuffer(assemblyKey, createdChunkBuffer);
+    this.runtimeStore.setChunkCount(assemblyKey, 0);
+
+    return createdChunkBuffer;
+  }
+
+  private updateTransferProgress(
+    attachment: Attachment,
+    decodedBytes: Uint8Array,
+    fromPeerId?: string
+  ): void {
+    const now = Date.now();
+    const previousReceived = attachment.receivedBytes ?? 0;
+
+    attachment.receivedBytes = previousReceived + decodedBytes.byteLength;
+
+    if (fromPeerId) {
+      recordDebugNetworkFileChunk(fromPeerId, decodedBytes.byteLength, now);
+    }
+
+    if (!attachment.startedAtMs)
+      attachment.startedAtMs = now;
+
+    if (!attachment.lastUpdateMs)
+      attachment.lastUpdateMs = now;
+
+    const elapsedMs = Math.max(1, now - attachment.lastUpdateMs);
+    const instantaneousBps = (decodedBytes.byteLength / elapsedMs) * 1000;
+    const previousSpeed = attachment.speedBps ?? instantaneousBps;
+
+    attachment.speedBps =
+      ATTACHMENT_TRANSFER_EWMA_PREVIOUS_WEIGHT * previousSpeed +
+      ATTACHMENT_TRANSFER_EWMA_CURRENT_WEIGHT * instantaneousBps;
+
+    attachment.lastUpdateMs = now;
+  }
+
+  private finalizeTransferIfComplete(
+    attachment: Attachment,
+    assemblyKey: string,
+    total: number
+  ): void {
+    const receivedChunkCount = this.runtimeStore.getChunkCount(assemblyKey) ?? 0;
+    const completeBuffer = this.runtimeStore.getChunkBuffer(assemblyKey);
+
+    if (
+      !completeBuffer
+      || (receivedChunkCount !== total && (attachment.receivedBytes ?? 0) < attachment.size)
+      || !completeBuffer.every((part) => part instanceof ArrayBuffer)
+    ) {
+      return;
+    }
+
+    const blob = new Blob(completeBuffer, { type: attachment.mime });
+
+    attachment.available = true;
+    attachment.objectUrl = URL.createObjectURL(blob);
+
+    if (shouldPersistDownloadedAttachment(attachment)) {
+      void this.persistence.saveFileToDisk(attachment, blob);
+    }
+
+    this.runtimeStore.deleteChunkBuffer(assemblyKey);
+    this.runtimeStore.deleteChunkCount(assemblyKey);
+    this.runtimeStore.touch();
+    void this.persistence.persistAttachmentMeta(attachment);
+  }
+}

src/app/domains/attachment/application/attachment.facade.ts

@@ -0,0 +1,119 @@
+import { Injectable, inject } from '@angular/core';
+import { AttachmentManagerService } from './attachment-manager.service';
+
+@Injectable({ providedIn: 'root' })
+export class AttachmentFacade {
+  get updated() {
+    return this.manager.updated;
+  }
+
+  private readonly manager = inject(AttachmentManagerService);
+
+  getForMessage(
+    ...args: Parameters<AttachmentManagerService['getForMessage']>
+  ): ReturnType<AttachmentManagerService['getForMessage']> {
+    return this.manager.getForMessage(...args);
+  }
+
+  rememberMessageRoom(
+    ...args: Parameters<AttachmentManagerService['rememberMessageRoom']>
+  ): ReturnType<AttachmentManagerService['rememberMessageRoom']> {
+    return this.manager.rememberMessageRoom(...args);
+  }
+
+  queueAutoDownloadsForMessage(
+    ...args: Parameters<AttachmentManagerService['queueAutoDownloadsForMessage']>
+  ): ReturnType<AttachmentManagerService['queueAutoDownloadsForMessage']> {
+    return this.manager.queueAutoDownloadsForMessage(...args);
+  }
+
+  requestAutoDownloadsForRoom(
+    ...args: Parameters<AttachmentManagerService['requestAutoDownloadsForRoom']>
+  ): ReturnType<AttachmentManagerService['requestAutoDownloadsForRoom']> {
+    return this.manager.requestAutoDownloadsForRoom(...args);
+  }
+
+  deleteForMessage(
+    ...args: Parameters<AttachmentManagerService['deleteForMessage']>
+  ): ReturnType<AttachmentManagerService['deleteForMessage']> {
+    return this.manager.deleteForMessage(...args);
+  }
+
+  getAttachmentMetasForMessages(
+    ...args: Parameters<AttachmentManagerService['getAttachmentMetasForMessages']>
+  ): ReturnType<AttachmentManagerService['getAttachmentMetasForMessages']> {
+    return this.manager.getAttachmentMetasForMessages(...args);
+  }
+
+  registerSyncedAttachments(
+    ...args: Parameters<AttachmentManagerService['registerSyncedAttachments']>
+  ): ReturnType<AttachmentManagerService['registerSyncedAttachments']> {
+    return this.manager.registerSyncedAttachments(...args);
+  }
+
+  requestFromAnyPeer(
+    ...args: Parameters<AttachmentManagerService['requestFromAnyPeer']>
+  ): ReturnType<AttachmentManagerService['requestFromAnyPeer']> {
+    return this.manager.requestFromAnyPeer(...args);
+  }
+
+  handleFileNotFound(
+    ...args: Parameters<AttachmentManagerService['handleFileNotFound']>
+  ): ReturnType<AttachmentManagerService['handleFileNotFound']> {
+    return this.manager.handleFileNotFound(...args);
+  }
+
+  requestImageFromAnyPeer(
+    ...args: Parameters<AttachmentManagerService['requestImageFromAnyPeer']>
+  ): ReturnType<AttachmentManagerService['requestImageFromAnyPeer']> {
+    return this.manager.requestImageFromAnyPeer(...args);
+  }
+
+  requestFile(
+    ...args: Parameters<AttachmentManagerService['requestFile']>
+  ): ReturnType<AttachmentManagerService['requestFile']> {
+    return this.manager.requestFile(...args);
+  }
+
+  publishAttachments(
+    ...args: Parameters<AttachmentManagerService['publishAttachments']>
+  ): ReturnType<AttachmentManagerService['publishAttachments']> {
+    return this.manager.publishAttachments(...args);
+  }
+
+  handleFileAnnounce(
+    ...args: Parameters<AttachmentManagerService['handleFileAnnounce']>
+  ): ReturnType<AttachmentManagerService['handleFileAnnounce']> {
+    return this.manager.handleFileAnnounce(...args);
+  }
+
+  handleFileChunk(
+    ...args: Parameters<AttachmentManagerService['handleFileChunk']>
+  ): ReturnType<AttachmentManagerService['handleFileChunk']> {
+    return this.manager.handleFileChunk(...args);
+  }
+
+  handleFileRequest(
+    ...args: Parameters<AttachmentManagerService['handleFileRequest']>
+  ): ReturnType<AttachmentManagerService['handleFileRequest']> {
+    return this.manager.handleFileRequest(...args);
+  }
+
+  cancelRequest(
+    ...args: Parameters<AttachmentManagerService['cancelRequest']>
+  ): ReturnType<AttachmentManagerService['cancelRequest']> {
+    return this.manager.cancelRequest(...args);
+  }
+
+  handleFileCancel(
+    ...args: Parameters<AttachmentManagerService['handleFileCancel']>
+  ): ReturnType<AttachmentManagerService['handleFileCancel']> {
+    return this.manager.handleFileCancel(...args);
+  }
+
+  fulfillRequestWithFile(
+    ...args: Parameters<AttachmentManagerService['fulfillRequestWithFile']>
+  ): ReturnType<AttachmentManagerService['fulfillRequestWithFile']> {
+    return this.manager.fulfillRequestWithFile(...args);
+  }
+}

src/app/domains/attachment/domain/attachment-transfer.constants.ts

@@ -0,0 +1,21 @@
+/** Size (bytes) of each chunk when streaming a file over RTCDataChannel. */
+export const FILE_CHUNK_SIZE_BYTES = 64 * 1024; // 64 KB
+
+/**
+ * EWMA smoothing weight for the previous speed estimate.
+ * The complementary weight is applied to the latest sample.
+ */
+export const ATTACHMENT_TRANSFER_EWMA_PREVIOUS_WEIGHT = 0.7;
+export const ATTACHMENT_TRANSFER_EWMA_CURRENT_WEIGHT = 1 - ATTACHMENT_TRANSFER_EWMA_PREVIOUS_WEIGHT;
+
+/** Fallback MIME type when none is provided by the sender. */
+export const DEFAULT_ATTACHMENT_MIME_TYPE = 'application/octet-stream';
+
+/** localStorage key used by the legacy attachment store during migration. */
+export const LEGACY_ATTACHMENTS_STORAGE_KEY = 'metoyou_attachments';
+
+/** User-facing error when no peers are available for a request. */
+export const NO_CONNECTED_PEERS_REQUEST_ERROR = 'No connected peers are available to provide this file right now.';
+
+/** User-facing error when connected peers cannot provide a requested file. */
+export const FILE_NOT_FOUND_REQUEST_ERROR = 'The connected peers do not have this file right now.';

src/app/domains/attachment/domain/attachment-transfer.models.ts

@@ -0,0 +1,56 @@
+import type { ChatAttachmentAnnouncement, ChatEvent } from '../../../core/models/index';
+
+export type FileAnnounceEvent = ChatEvent & {
+  type: 'file-announce';
+  messageId: string;
+  file: ChatAttachmentAnnouncement;
+};
+
+export type FileChunkEvent = ChatEvent & {
+  type: 'file-chunk';
+  messageId: string;
+  fileId: string;
+  index: number;
+  total: number;
+  data: string;
+  fromPeerId?: string;
+};
+
+export type FileRequestEvent = ChatEvent & {
+  type: 'file-request';
+  messageId: string;
+  fileId: string;
+  fromPeerId?: string;
+};
+
+export type FileCancelEvent = ChatEvent & {
+  type: 'file-cancel';
+  messageId: string;
+  fileId: string;
+  fromPeerId?: string;
+};
+
+export type FileNotFoundEvent = ChatEvent & {
+  type: 'file-not-found';
+  messageId: string;
+  fileId: string;
+};
+
+export type FileAnnouncePayload = Pick<ChatEvent, 'messageId' | 'file'>;
+
+export interface FileChunkPayload {
+  messageId?: string;
+  fileId?: string;
+  fromPeerId?: string;
+  index?: number;
+  total?: number;
+  data?: ChatEvent['data'];
+}
+
+export type FileRequestPayload = Pick<ChatEvent, 'messageId' | 'fileId' | 'fromPeerId'>;
+export type FileCancelPayload = Pick<ChatEvent, 'messageId' | 'fileId' | 'fromPeerId'>;
+export type FileNotFoundPayload = Pick<ChatEvent, 'messageId' | 'fileId'>;
+
+export type LocalFileWithPath = File & {
+  path?: string;
+};

src/app/domains/attachment/domain/attachment.constants.ts

@@ -0,0 +1,2 @@
+/** Maximum file size (bytes) that is automatically saved or pushed for inline previews. */
+export const MAX_AUTO_SAVE_SIZE_BYTES = 10 * 1024 * 1024; // 10 MB

src/app/domains/attachment/domain/attachment.logic.ts

@@ -0,0 +1,19 @@
+import { MAX_AUTO_SAVE_SIZE_BYTES } from './attachment.constants';
+import type { Attachment } from './attachment.models';
+
+export function isAttachmentMedia(attachment: Pick<Attachment, 'mime'>): boolean {
+  return attachment.mime.startsWith('image/') ||
+    attachment.mime.startsWith('video/') ||
+    attachment.mime.startsWith('audio/');
+}
+
+export function shouldAutoRequestWhenWatched(attachment: Attachment): boolean {
+  return attachment.isImage ||
+    (isAttachmentMedia(attachment) && attachment.size <= MAX_AUTO_SAVE_SIZE_BYTES);
+}
+
+export function shouldPersistDownloadedAttachment(attachment: Pick<Attachment, 'size' | 'mime'>): boolean {
+  return attachment.size <= MAX_AUTO_SAVE_SIZE_BYTES ||
+    attachment.mime.startsWith('video/') ||
+    attachment.mime.startsWith('audio/');
+}

src/app/domains/attachment/domain/attachment.models.ts

@@ -0,0 +1,13 @@
+import type { ChatAttachmentMeta } from '../../../core/models/index';
+
+export type AttachmentMeta = ChatAttachmentMeta;
+
+export interface Attachment extends AttachmentMeta {
+  available: boolean;
+  objectUrl?: string;
+  receivedBytes?: number;
+  speedBps?: number;
+  startedAtMs?: number;
+  lastUpdateMs?: number;
+  requestError?: string;
+}

src/app/domains/attachment/index.ts

@@ -0,0 +1,3 @@
+export * from './application/attachment.facade';
+export * from './domain/attachment.constants';
+export * from './domain/attachment.models';

src/app/domains/attachment/infrastructure/attachment-storage.helpers.ts

@@ -0,0 +1,23 @@
+const ROOM_NAME_SANITIZER = /[^\w.-]+/g;
+
+export function sanitizeAttachmentRoomName(roomName: string): string {
+  const sanitizedRoomName = roomName.trim().replace(ROOM_NAME_SANITIZER, '_');
+
+  return sanitizedRoomName || 'room';
+}
+
+export function resolveAttachmentStorageBucket(mime: string): 'video' | 'audio' | 'image' | 'files' {
+  if (mime.startsWith('video/')) {
+    return 'video';
+  }
+
+  if (mime.startsWith('audio/')) {
+    return 'audio';
+  }
+
+  if (mime.startsWith('image/')) {
+    return 'image';
+  }
+
+  return 'files';
+}

src/app/domains/attachment/infrastructure/attachment-storage.service.ts

@@ -0,0 +1,127 @@
+import { Injectable, inject } from '@angular/core';
+import { ElectronBridgeService } from '../../../core/platform/electron/electron-bridge.service';
+import type { Attachment } from '../domain/attachment.models';
+import { resolveAttachmentStorageBucket, sanitizeAttachmentRoomName } from './attachment-storage.helpers';
+
+@Injectable({ providedIn: 'root' })
+export class AttachmentStorageService {
+  private readonly electronBridge = inject(ElectronBridgeService);
+
+  async resolveExistingPath(
+    attachment: Pick<Attachment, 'filePath' | 'savedPath'>
+  ): Promise<string | null> {
+    return this.findExistingPath([attachment.filePath, attachment.savedPath]);
+  }
+
+  async resolveLegacyImagePath(filename: string, roomName: string): Promise<string | null> {
+    const appDataPath = await this.resolveAppDataPath();
+
+    if (!appDataPath) {
+      return null;
+    }
+
+    return this.findExistingPath([`${appDataPath}/server/${sanitizeAttachmentRoomName(roomName)}/image/${filename}`]);
+  }
+
+  async readFile(filePath: string): Promise<string | null> {
+    const electronApi = this.electronBridge.getApi();
+
+    if (!electronApi || !filePath) {
+      return null;
+    }
+
+    try {
+      return await electronApi.readFile(filePath);
+    } catch {
+      return null;
+    }
+  }
+
+  async saveBlob(
+    attachment: Pick<Attachment, 'filename' | 'mime'>,
+    blob: Blob,
+    roomName: string
+  ): Promise<string | null> {
+    const electronApi = this.electronBridge.getApi();
+    const appDataPath = await this.resolveAppDataPath();
+
+    if (!electronApi || !appDataPath) {
+      return null;
+    }
+
+    try {
+      const directoryPath = `${appDataPath}/server/${sanitizeAttachmentRoomName(roomName)}/${resolveAttachmentStorageBucket(attachment.mime)}`;
+
+      await electronApi.ensureDir(directoryPath);
+
+      const arrayBuffer = await blob.arrayBuffer();
+      const diskPath = `${directoryPath}/${attachment.filename}`;
+
+      await electronApi.writeFile(diskPath, this.arrayBufferToBase64(arrayBuffer));
+
+      return diskPath;
+    } catch {
+      return null;
+    }
+  }
+
+  async deleteFile(filePath: string): Promise<void> {
+    const electronApi = this.electronBridge.getApi();
+
+    if (!electronApi || !filePath) {
+      return;
+    }
+
+    try {
+      await electronApi.deleteFile(filePath);
+    } catch { /* best-effort cleanup */ }
+  }
+
+  private async resolveAppDataPath(): Promise<string | null> {
+    const electronApi = this.electronBridge.getApi();
+
+    if (!electronApi) {
+      return null;
+    }
+
+    try {
+      return await electronApi.getAppDataPath();
+    } catch {
+      return null;
+    }
+  }
+
+  private async findExistingPath(candidates: (string | null | undefined)[]): Promise<string | null> {
+    const electronApi = this.electronBridge.getApi();
+
+    if (!electronApi) {
+      return null;
+    }
+
+    for (const candidatePath of candidates) {
+      if (!candidatePath) {
+        continue;
+      }
+
+      try {
+        if (await electronApi.fileExists(candidatePath)) {
+          return candidatePath;
+        }
+      } catch { /* keep trying remaining candidates */ }
+    }
+
+    return null;
+  }
+
+  private arrayBufferToBase64(buffer: ArrayBuffer): string {
+    let binary = '';
+
+    const bytes = new Uint8Array(buffer);
+
+    for (let index = 0; index < bytes.byteLength; index++) {
+      binary += String.fromCharCode(bytes[index]);
+    }
+
+    return btoa(binary);
+  }
+}

src/app/domains/auth/application/auth.service.ts

@@ -0,0 +1,101 @@
+/* eslint-disable @typescript-eslint/member-ordering */
+import { Injectable, inject } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+import { Observable } from 'rxjs';
+import { type ServerEndpoint, ServerDirectoryFacade } from '../../server-directory';
+
+/**
+ * Response returned by the authentication endpoints (login / register).
+ */
+export interface LoginResponse {
+  /** Unique user identifier assigned by the server. */
+  id: string;
+  /** Login username. */
+  username: string;
+  /** Human-readable display name. */
+  displayName: string;
+}
+
+/**
+ * Handles user authentication (login and registration) against a
+ * configurable back-end server.
+ *
+ * The target server is resolved via {@link ServerDirectoryFacade}: the
+ * caller may pass an explicit `serverId`, otherwise the currently active
+ * server endpoint is used.
+ */
+@Injectable({ providedIn: 'root' })
+export class AuthService {
+  private readonly http = inject(HttpClient);
+  private readonly serverDirectory = inject(ServerDirectoryFacade);
+
+  /**
+   * Resolve the API base URL for the given server.
+   *
+   * @param serverId - Optional server ID to look up. When omitted the
+   *   currently active endpoint is used.
+   * @returns Fully-qualified API base URL (e.g. `http://host:3001/api`).
+   */
+  private endpointFor(serverId?: string): string {
+    let endpoint: ServerEndpoint | undefined;
+
+    if (serverId) {
+      endpoint = this.serverDirectory.servers().find(
+        (server) => server.id === serverId
+      );
+    }
+
+    const activeEndpoint = endpoint ?? this.serverDirectory.activeServer();
+
+    return activeEndpoint
+      ? `${activeEndpoint.url}/api`
+      : this.serverDirectory.getApiBaseUrl();
+  }
+
+  /**
+   * Register a new user account on the target server.
+   *
+   * @param params - Registration parameters.
+   * @param params.username  - Desired login username.
+   * @param params.password  - Account password.
+   * @param params.displayName - Optional display name (defaults to username on the server).
+   * @param params.serverId  - Optional server ID to register against.
+   * @returns Observable emitting the {@link LoginResponse} on success.
+   */
+  register(params: {
+    username: string;
+    password: string;
+    displayName?: string;
+    serverId?: string;
+  }): Observable<LoginResponse> {
+    const url = `${this.endpointFor(params.serverId)}/users/register`;
+
+    return this.http.post<LoginResponse>(url, {
+      username: params.username,
+      password: params.password,
+      displayName: params.displayName
+    });
+  }
+
+  /**
+   * Log in to an existing user account on the target server.
+   *
+   * @param params - Login parameters.
+   * @param params.username - Login username.
+   * @param params.password - Account password.
+   * @param params.serverId - Optional server ID to authenticate against.
+   * @returns Observable emitting the {@link LoginResponse} on success.
+   */
+  login(params: {
+    username: string;
+    password: string;
+    serverId?: string;
+  }): Observable<LoginResponse> {
+    const url = `${this.endpointFor(params.serverId)}/users/login`;
+
+    return this.http.post<LoginResponse>(url, {
+      username: params.username,
+      password: params.password
+    });
+  }
+}

src/app/domains/auth/index.ts

@@ -0,0 +1 @@
+export * from './application/auth.service';

src/app/domains/chat/application/klipy.service.ts

@@ -0,0 +1,200 @@
+/* eslint-disable @typescript-eslint/member-ordering */
+import {
+  Injectable,
+  computed,
+  effect,
+  inject,
+  signal
+} from '@angular/core';
+import { HttpClient, HttpParams } from '@angular/common/http';
+import {
+  Observable,
+  firstValueFrom,
+  throwError
+} from 'rxjs';
+import { catchError, map } from 'rxjs/operators';
+import { ServerDirectoryFacade } from '../../server-directory';
+
+export interface KlipyGif {
+  id: string;
+  slug: string;
+  title?: string;
+  url: string;
+  previewUrl: string;
+  width: number;
+  height: number;
+}
+
+interface KlipyAvailabilityResponse {
+  enabled: boolean;
+}
+
+export interface KlipyGifSearchResponse {
+  enabled: boolean;
+  results: KlipyGif[];
+  hasNext: boolean;
+}
+
+const DEFAULT_PAGE_SIZE = 24;
+const KLIPY_CUSTOMER_ID_STORAGE_KEY = 'metoyou_klipy_customer_id';
+
+@Injectable({ providedIn: 'root' })
+export class KlipyService {
+  private readonly http = inject(HttpClient);
+  private readonly serverDirectory = inject(ServerDirectoryFacade);
+  private readonly availabilityState = signal({
+    enabled: false,
+    loading: true
+  });
+  private lastAvailabilityKey = '';
+
+  readonly isEnabled = computed(() => this.availabilityState().enabled);
+  readonly isLoading = computed(() => this.availabilityState().loading);
+
+  constructor() {
+    effect(() => {
+      const activeServer = this.serverDirectory.activeServer();
+      const apiBaseUrl = this.serverDirectory.getApiBaseUrl();
+      const nextKey = `${activeServer?.id ?? 'default'}:${apiBaseUrl}`;
+
+      if (nextKey === this.lastAvailabilityKey)
+        return;
+
+      this.lastAvailabilityKey = nextKey;
+      void this.refreshAvailability();
+    });
+  }
+
+  async refreshAvailability(): Promise<void> {
+    this.availabilityState.set({ enabled: false,
+      loading: true });
+
+    try {
+      const response = await firstValueFrom(
+        this.http.get<KlipyAvailabilityResponse>(
+          `${this.serverDirectory.getApiBaseUrl()}/klipy/config`
+        )
+      );
+
+      this.availabilityState.set({
+        enabled: response.enabled === true,
+        loading: false
+      });
+    } catch {
+      this.availabilityState.set({ enabled: false,
+        loading: false });
+    }
+  }
+
+  searchGifs(
+    query: string,
+    page = 1,
+    perPage = DEFAULT_PAGE_SIZE
+  ): Observable<KlipyGifSearchResponse> {
+    let params = new HttpParams()
+      .set('page', String(Math.max(1, Math.floor(page))))
+      .set('per_page', String(Math.max(1, Math.floor(perPage))))
+      .set('customer_id', this.getOrCreateCustomerId());
+
+    const trimmedQuery = query.trim();
+
+    if (trimmedQuery) {
+      params = params.set('q', trimmedQuery);
+    }
+
+    const locale = this.getPreferredLocale();
+
+    if (locale) {
+      params = params.set('locale', locale);
+    }
+
+    return this.http
+      .get<KlipyGifSearchResponse>(`${this.serverDirectory.getApiBaseUrl()}/klipy/gifs`, { params })
+      .pipe(
+        map((response) => ({
+          enabled: response.enabled !== false,
+          results: Array.isArray(response.results) ? response.results : [],
+          hasNext: response.hasNext === true
+        })),
+        catchError((error) =>
+          throwError(() => new Error(this.extractErrorMessage(error)))
+        )
+      );
+  }
+
+  normalizeMediaUrl(url: string): string {
+    const trimmed = url.trim();
+
+    if (!trimmed)
+      return '';
+
+    if (trimmed.startsWith('//'))
+      return `https:${trimmed}`;
+
+    return trimmed;
+  }
+
+  buildRenderableImageUrl(url: string): string {
+    const trimmed = this.normalizeMediaUrl(url);
+
+    if (!trimmed)
+      return '';
+
+    if (!/^https?:\/\//i.test(trimmed))
+      return trimmed;
+
+    return `${this.serverDirectory.getApiBaseUrl()}/image-proxy?url=${encodeURIComponent(trimmed)}`;
+  }
+
+  private getPreferredLocale(): string | null {
+    if (typeof navigator === 'undefined' || !navigator.language)
+      return null;
+
+    const locale = navigator.language.trim();
+
+    return locale || null;
+  }
+
+  private getOrCreateCustomerId(): string {
+    if (typeof window === 'undefined') {
+      return 'server';
+    }
+
+    try {
+      const existing = window.localStorage.getItem(KLIPY_CUSTOMER_ID_STORAGE_KEY);
+
+      if (existing?.trim())
+        return existing;
+
+      const created = window.crypto?.randomUUID?.()
+        ?? `klipy-${Date.now().toString(36)}-${Math.random().toString(36)
+          .slice(2, 10)}`;
+
+      window.localStorage.setItem(KLIPY_CUSTOMER_ID_STORAGE_KEY, created);
+      return created;
+    } catch {
+      return `klipy-${Date.now().toString(36)}`;
+    }
+  }
+
+  private extractErrorMessage(error: unknown): string {
+    const httpError = error as {
+      error?: {
+        error?: unknown;
+        message?: unknown;
+      };
+      message?: unknown;
+    };
+
+    if (typeof httpError?.error?.error === 'string')
+      return httpError.error.error;
+
+    if (typeof httpError?.error?.message === 'string')
+      return httpError.error.message;
+
+    if (typeof httpError?.message === 'string')
+      return httpError.message;
+
+    return 'Failed to load GIFs from KLIPY.';
+  }
+}

src/app/domains/chat/index.ts

@@ -0,0 +1 @@
+export * from './application/klipy.service';

src/app/domains/screen-share/application/screen-share-source-picker.service.ts

@@ -0,0 +1,134 @@
+import {
+  Injectable,
+  computed,
+  signal
+} from '@angular/core';
+import { loadVoiceSettingsFromStorage, saveVoiceSettingsToStorage } from '../../voice-session';
+import { ELECTRON_ENTIRE_SCREEN_SOURCE_NAME } from '../domain/screen-share.config';
+
+export type ScreenShareSourceKind = 'screen' | 'window';
+
+export interface ScreenShareSourceOption {
+  id: string;
+  kind: ScreenShareSourceKind;
+  name: string;
+  thumbnail: string;
+}
+
+export interface ScreenShareSourceSelection {
+  includeSystemAudio: boolean;
+  source: ScreenShareSourceOption;
+}
+
+interface ScreenShareSourcePickerRequest {
+  includeSystemAudio: boolean;
+  sources: readonly ScreenShareSourceOption[];
+}
+
+@Injectable({ providedIn: 'root' })
+export class ScreenShareSourcePickerService {
+  readonly request = computed(() => this._request());
+
+  private readonly _request = signal<ScreenShareSourcePickerRequest | null>(null);
+
+  private pendingResolve: ((selection: ScreenShareSourceSelection) => void) | null = null;
+  private pendingReject: ((reason?: unknown) => void) | null = null;
+
+  open(
+    sources: readonly Pick<ScreenShareSourceOption, 'id' | 'name' | 'thumbnail'>[],
+    initialIncludeSystemAudio = loadVoiceSettingsFromStorage().includeSystemAudio
+  ): Promise<ScreenShareSourceSelection> {
+    if (sources.length === 0) {
+      throw new Error('No desktop capture sources were available.');
+    }
+
+    this.cancelPendingRequest();
+
+    const normalizedSources = sources.map((source) => {
+      const kind = this.getSourceKind(source);
+
+      return {
+        ...source,
+        kind,
+        name: this.getSourceDisplayName(source.name, kind)
+      };
+    });
+
+    this._request.set({
+      includeSystemAudio: initialIncludeSystemAudio,
+      sources: normalizedSources
+    });
+
+    return new Promise<ScreenShareSourceSelection>((resolve, reject) => {
+      this.pendingResolve = resolve;
+      this.pendingReject = reject;
+    });
+  }
+
+  confirm(sourceId: string, includeSystemAudio: boolean): void {
+    const activeRequest = this._request();
+    const source = activeRequest?.sources.find((entry) => entry.id === sourceId);
+    const resolve = this.pendingResolve;
+
+    if (!source || !resolve) {
+      return;
+    }
+
+    this.clearPendingRequest();
+    saveVoiceSettingsToStorage({ includeSystemAudio });
+    resolve({
+      includeSystemAudio,
+      source
+    });
+  }
+
+  cancel(): void {
+    this.cancelPendingRequest();
+  }
+
+  private cancelPendingRequest(): void {
+    const reject = this.pendingReject;
+
+    this.clearPendingRequest();
+
+    if (reject) {
+      reject(this.createAbortError());
+    }
+  }
+
+  private clearPendingRequest(): void {
+    this._request.set(null);
+    this.pendingResolve = null;
+    this.pendingReject = null;
+  }
+
+  private getSourceKind(
+    source: Pick<ScreenShareSourceOption, 'id' | 'name'>
+  ): ScreenShareSourceKind {
+    return source.id.startsWith('screen') || source.name === ELECTRON_ENTIRE_SCREEN_SOURCE_NAME
+      ? 'screen'
+      : 'window';
+  }
+
+  private getSourceDisplayName(name: string, kind: ScreenShareSourceKind): string {
+    const trimmedName = name.trim();
+
+    if (trimmedName) {
+      return trimmedName;
+    }
+
+    return kind === 'screen' ? 'Entire screen' : 'Window';
+  }
+
+  private createAbortError(): Error {
+    if (typeof DOMException !== 'undefined') {
+      return new DOMException('The user aborted a request.', 'AbortError');
+    }
+
+    const error = new Error('The user aborted a request.');
+
+    error.name = 'AbortError';
+
+    return error;
+  }
+}

src/app/domains/screen-share/application/screen-share.facade.ts

@@ -0,0 +1,31 @@
+import { Injectable, inject } from '@angular/core';
+import { RealtimeSessionFacade } from '../../../core/realtime';
+import { ScreenShareStartOptions } from '../domain/screen-share.config';
+
+@Injectable({ providedIn: 'root' })
+export class ScreenShareFacade {
+  readonly isScreenSharing = inject(RealtimeSessionFacade).isScreenSharing;
+  readonly screenStream = inject(RealtimeSessionFacade).screenStream;
+  readonly isScreenShareRemotePlaybackSuppressed = inject(RealtimeSessionFacade).isScreenShareRemotePlaybackSuppressed;
+  readonly forceDefaultRemotePlaybackOutput = inject(RealtimeSessionFacade).forceDefaultRemotePlaybackOutput;
+  readonly onRemoteStream = inject(RealtimeSessionFacade).onRemoteStream;
+  readonly onPeerDisconnected = inject(RealtimeSessionFacade).onPeerDisconnected;
+
+  private readonly realtime = inject(RealtimeSessionFacade);
+
+  getRemoteScreenShareStream(peerId: string): MediaStream | null {
+    return this.realtime.getRemoteScreenShareStream(peerId);
+  }
+
+  async startScreenShare(options: ScreenShareStartOptions): Promise<MediaStream> {
+    return await this.realtime.startScreenShare(options);
+  }
+
+  stopScreenShare(): void {
+    this.realtime.stopScreenShare();
+  }
+
+  syncRemoteScreenShareRequests(peerIds: string[], enabled: boolean): void {
+    this.realtime.syncRemoteScreenShareRequests(peerIds, enabled);
+  }
+}

src/app/domains/screen-share/domain/screen-share.config.ts

@@ -0,0 +1,81 @@
+export type ScreenShareQuality = 'performance' | 'balanced' | 'high-fps' | 'quality';
+
+export interface ScreenShareStartOptions {
+  includeSystemAudio: boolean;
+  quality: ScreenShareQuality;
+}
+
+export interface ScreenShareQualityPreset {
+  label: string;
+  description: string;
+  width: number;
+  height: number;
+  frameRate: number;
+  maxBitrateBps: number;
+  contentHint: 'motion' | 'detail';
+  degradationPreference: 'maintain-framerate' | 'maintain-resolution';
+  scaleResolutionDownBy?: number;
+}
+
+export const ELECTRON_ENTIRE_SCREEN_SOURCE_NAME = 'Entire Screen';
+
+export const DEFAULT_SCREEN_SHARE_QUALITY: ScreenShareQuality = 'balanced';
+
+export const DEFAULT_SCREEN_SHARE_START_OPTIONS: ScreenShareStartOptions = {
+  includeSystemAudio: false,
+  quality: DEFAULT_SCREEN_SHARE_QUALITY
+};
+
+export const SCREEN_SHARE_QUALITY_PRESETS: Record<ScreenShareQuality, ScreenShareQualityPreset> = {
+  performance: {
+    label: 'Performance saver',
+    description: '720p / 30 FPS with lower CPU and bandwidth usage.',
+    width: 1280,
+    height: 720,
+    frameRate: 30,
+    maxBitrateBps: 2_000_000,
+    contentHint: 'motion',
+    degradationPreference: 'maintain-framerate',
+    scaleResolutionDownBy: 1
+  },
+  balanced: {
+    label: 'Balanced',
+    description: '1080p / 30 FPS for stable quality in most cases.',
+    width: 1920,
+    height: 1080,
+    frameRate: 30,
+    maxBitrateBps: 4_000_000,
+    contentHint: 'detail',
+    degradationPreference: 'maintain-resolution',
+    scaleResolutionDownBy: 1
+  },
+  'high-fps': {
+    label: 'High FPS',
+    description: '1080p / 60 FPS for games and fast motion.',
+    width: 1920,
+    height: 1080,
+    frameRate: 60,
+    maxBitrateBps: 6_000_000,
+    contentHint: 'motion',
+    degradationPreference: 'maintain-framerate',
+    scaleResolutionDownBy: 1
+  },
+  quality: {
+    label: 'Sharp text',
+    description: '1440p / 30 FPS for detailed UI and text clarity.',
+    width: 2560,
+    height: 1440,
+    frameRate: 30,
+    maxBitrateBps: 8_000_000,
+    contentHint: 'detail',
+    degradationPreference: 'maintain-resolution',
+    scaleResolutionDownBy: 1
+  }
+};
+
+export const SCREEN_SHARE_QUALITY_OPTIONS = (
+  Object.entries(SCREEN_SHARE_QUALITY_PRESETS) as [ScreenShareQuality, ScreenShareQualityPreset][]
+).map(([id, preset]) => ({
+  id,
+  ...preset
+}));

src/app/domains/screen-share/index.ts

@@ -0,0 +1,3 @@
+export * from './application/screen-share.facade';
+export * from './application/screen-share-source-picker.service';
+export * from './domain/screen-share.config';

src/app/domains/server-directory/application/server-directory.facade.ts

@@ -0,0 +1,259 @@
+import {
+  Injectable,
+  inject,
+  type Signal
+} from '@angular/core';
+import { Observable } from 'rxjs';
+import { STORAGE_KEY_CONNECTION_SETTINGS } from '../../../core/constants';
+import { ServerInfo, User } from '../../../core/models';
+import { CLIENT_UPDATE_REQUIRED_MESSAGE } from '../domain/server-directory.constants';
+import { ServerDirectoryApiService } from '../infrastructure/server-directory-api.service';
+import type {
+  BanServerMemberRequest,
+  CreateServerInviteRequest,
+  KickServerMemberRequest,
+  ServerEndpoint,
+  ServerEndpointVersions,
+  ServerInviteInfo,
+  ServerJoinAccessRequest,
+  ServerJoinAccessResponse,
+  ServerSourceSelector,
+  UnbanServerMemberRequest
+} from '../domain/server-directory.models';
+import { ServerEndpointCompatibilityService } from '../infrastructure/server-endpoint-compatibility.service';
+import { ServerEndpointHealthService } from '../infrastructure/server-endpoint-health.service';
+import { ServerEndpointStateService } from './server-endpoint-state.service';
+
+export { CLIENT_UPDATE_REQUIRED_MESSAGE };
+
+@Injectable({ providedIn: 'root' })
+export class ServerDirectoryFacade {
+  readonly servers: Signal<ServerEndpoint[]>;
+  readonly activeServers: Signal<ServerEndpoint[]>;
+  readonly hasMissingDefaultServers: Signal<boolean>;
+  readonly activeServer: Signal<ServerEndpoint | null>;
+
+  private readonly endpointState = inject(ServerEndpointStateService);
+  private readonly endpointCompatibility = inject(ServerEndpointCompatibilityService);
+  private readonly endpointHealth = inject(ServerEndpointHealthService);
+  private readonly api = inject(ServerDirectoryApiService);
+  private shouldSearchAllServers = true;
+
+  constructor() {
+    this.servers = this.endpointState.servers;
+    this.activeServers = this.endpointState.activeServers;
+    this.hasMissingDefaultServers = this.endpointState.hasMissingDefaultServers;
+    this.activeServer = this.endpointState.activeServer;
+
+    this.loadConnectionSettings();
+    void this.testAllServers();
+  }
+
+  addServer(server: { name: string; url: string }): ServerEndpoint {
+    return this.endpointState.addServer(server);
+  }
+
+  ensureServerEndpoint(
+    server: { name: string; url: string },
+    options?: { setActive?: boolean }
+  ): ServerEndpoint {
+    return this.endpointState.ensureServerEndpoint(server, options);
+  }
+
+  findServerByUrl(url: string): ServerEndpoint | undefined {
+    return this.endpointState.findServerByUrl(url);
+  }
+
+  removeServer(endpointId: string): void {
+    this.endpointState.removeServer(endpointId);
+  }
+
+  restoreDefaultServers(): ServerEndpoint[] {
+    return this.endpointState.restoreDefaultServers();
+  }
+
+  setActiveServer(endpointId: string): void {
+    this.endpointState.setActiveServer(endpointId);
+  }
+
+  deactivateServer(endpointId: string): void {
+    this.endpointState.deactivateServer(endpointId);
+  }
+
+  updateServerStatus(
+    endpointId: string,
+    status: ServerEndpoint['status'],
+    latency?: number,
+    versions?: ServerEndpointVersions
+  ): void {
+    this.endpointState.updateServerStatus(endpointId, status, latency, versions);
+  }
+
+  async ensureEndpointVersionCompatibility(selector?: ServerSourceSelector): Promise<boolean> {
+    const endpoint = this.api.resolveEndpoint(selector);
+
+    if (!endpoint || endpoint.status === 'incompatible') {
+      return false;
+    }
+
+    const clientVersion = await this.endpointCompatibility.getClientVersion();
+
+    if (!clientVersion) {
+      return true;
+    }
+
+    await this.testServer(endpoint.id);
+
+    const refreshedEndpoint = this.servers().find((candidate) => candidate.id === endpoint.id);
+
+    return !!refreshedEndpoint && refreshedEndpoint.status !== 'incompatible';
+  }
+
+  setSearchAllServers(enabled: boolean): void {
+    this.shouldSearchAllServers = enabled;
+  }
+
+  async testServer(endpointId: string): Promise<boolean> {
+    const endpoint = this.servers().find((entry) => entry.id === endpointId);
+
+    if (!endpoint) {
+      return false;
+    }
+
+    this.updateServerStatus(endpointId, 'checking');
+    const clientVersion = await this.endpointCompatibility.getClientVersion();
+    const healthResult = await this.endpointHealth.probeEndpoint(endpoint, clientVersion);
+
+    this.updateServerStatus(
+      endpointId,
+      healthResult.status,
+      healthResult.latency,
+      healthResult.versions
+    );
+
+    return healthResult.status === 'online';
+  }
+
+  async testAllServers(): Promise<void> {
+    await Promise.all(this.servers().map((endpoint) => this.testServer(endpoint.id)));
+  }
+
+  getApiBaseUrl(selector?: ServerSourceSelector): string {
+    return this.api.getApiBaseUrl(selector);
+  }
+
+  getWebSocketUrl(selector?: ServerSourceSelector): string {
+    return this.api.getWebSocketUrl(selector);
+  }
+
+  searchServers(query: string): Observable<ServerInfo[]> {
+    return this.api.searchServers(query, this.shouldSearchAllServers);
+  }
+
+  getServers(): Observable<ServerInfo[]> {
+    return this.api.getServers(this.shouldSearchAllServers);
+  }
+
+  getServer(serverId: string, selector?: ServerSourceSelector): Observable<ServerInfo | null> {
+    return this.api.getServer(serverId, selector);
+  }
+
+  registerServer(
+    server: Omit<ServerInfo, 'createdAt'> & { id?: string; password?: string | null },
+    selector?: ServerSourceSelector
+  ): Observable<ServerInfo> {
+    return this.api.registerServer(server, selector);
+  }
+
+  updateServer(
+    serverId: string,
+    updates: Partial<ServerInfo> & {
+      currentOwnerId: string;
+      actingRole?: string;
+      password?: string | null;
+    },
+    selector?: ServerSourceSelector
+  ): Observable<ServerInfo> {
+    return this.api.updateServer(serverId, updates, selector);
+  }
+
+  unregisterServer(serverId: string, selector?: ServerSourceSelector): Observable<void> {
+    return this.api.unregisterServer(serverId, selector);
+  }
+
+  getServerUsers(serverId: string, selector?: ServerSourceSelector): Observable<User[]> {
+    return this.api.getServerUsers(serverId, selector);
+  }
+
+  requestJoin(
+    request: ServerJoinAccessRequest,
+    selector?: ServerSourceSelector
+  ): Observable<ServerJoinAccessResponse> {
+    return this.api.requestJoin(request, selector);
+  }
+
+  createInvite(
+    serverId: string,
+    request: CreateServerInviteRequest,
+    selector?: ServerSourceSelector
+  ): Observable<ServerInviteInfo> {
+    return this.api.createInvite(serverId, request, selector);
+  }
+
+  getInvite(inviteId: string, selector?: ServerSourceSelector): Observable<ServerInviteInfo> {
+    return this.api.getInvite(inviteId, selector);
+  }
+
+  kickServerMember(
+    serverId: string,
+    request: KickServerMemberRequest,
+    selector?: ServerSourceSelector
+  ): Observable<void> {
+    return this.api.kickServerMember(serverId, request, selector);
+  }
+
+  banServerMember(
+    serverId: string,
+    request: BanServerMemberRequest,
+    selector?: ServerSourceSelector
+  ): Observable<void> {
+    return this.api.banServerMember(serverId, request, selector);
+  }
+
+  unbanServerMember(
+    serverId: string,
+    request: UnbanServerMemberRequest,
+    selector?: ServerSourceSelector
+  ): Observable<void> {
+    return this.api.unbanServerMember(serverId, request, selector);
+  }
+
+  notifyLeave(serverId: string, userId: string, selector?: ServerSourceSelector): Observable<void> {
+    return this.api.notifyLeave(serverId, userId, selector);
+  }
+
+  updateUserCount(serverId: string, count: number): Observable<void> {
+    return this.api.updateUserCount(serverId, count);
+  }
+
+  sendHeartbeat(serverId: string): Observable<void> {
+    return this.api.sendHeartbeat(serverId);
+  }
+
+  private loadConnectionSettings(): void {
+    const stored = localStorage.getItem(STORAGE_KEY_CONNECTION_SETTINGS);
+
+    if (!stored) {
+      this.shouldSearchAllServers = true;
+      return;
+    }
+
+    try {
+      const parsed = JSON.parse(stored) as { searchAllServers?: boolean };
+
+      this.shouldSearchAllServers = parsed.searchAllServers ?? true;
+    } catch {
+      this.shouldSearchAllServers = true;
+    }
+  }
+}

src/app/domains/server-directory/application/server-endpoint-state.service.ts

@@ -0,0 +1,315 @@
+import {
+  Injectable,
+  computed,
+  inject,
+  signal,
+  type Signal
+} from '@angular/core';
+import { v4 as uuidv4 } from 'uuid';
+import { environment } from '../../../../environments/environment';
+import {
+  buildDefaultEndpointTemplates,
+  buildDefaultServerDefinitions,
+  ensureAnyActiveEndpoint,
+  ensureCompatibleActiveEndpoint,
+  findDefaultEndpointKeyByUrl,
+  hasEndpointForDefault,
+  matchDefaultEndpointTemplate,
+  sanitiseServerBaseUrl
+} from '../domain/server-endpoint-defaults';
+import { ServerEndpointStorageService } from '../infrastructure/server-endpoint-storage.service';
+import type {
+  ConfiguredDefaultServerDefinition,
+  DefaultEndpointTemplate,
+  ServerEndpoint,
+  ServerEndpointVersions
+} from '../domain/server-directory.models';
+
+function resolveDefaultHttpProtocol(): 'http' | 'https' {
+  return typeof window !== 'undefined' && window.location?.protocol === 'https:'
+    ? 'https'
+    : 'http';
+}
+
+@Injectable({ providedIn: 'root' })
+export class ServerEndpointStateService {
+  readonly servers: Signal<ServerEndpoint[]>;
+  readonly activeServers: Signal<ServerEndpoint[]>;
+  readonly hasMissingDefaultServers: Signal<boolean>;
+  readonly activeServer: Signal<ServerEndpoint | null>;
+
+  private readonly storage = inject(ServerEndpointStorageService);
+  private readonly _servers = signal<ServerEndpoint[]>([]);
+  private readonly defaultEndpoints: DefaultEndpointTemplate[];
+  private readonly primaryDefaultServerUrl: string;
+
+  constructor() {
+    const defaultServerDefinitions = buildDefaultServerDefinitions(
+      Array.isArray(environment.defaultServers)
+        ? environment.defaultServers as ConfiguredDefaultServerDefinition[]
+        : [],
+      environment.defaultServerUrl,
+      resolveDefaultHttpProtocol()
+    );
+
+    this.defaultEndpoints = buildDefaultEndpointTemplates(defaultServerDefinitions);
+    this.primaryDefaultServerUrl = this.defaultEndpoints[0]?.url ?? 'http://localhost:3001';
+
+    this.servers = computed(() => this._servers());
+    this.activeServers = computed(() =>
+      this._servers().filter((endpoint) => endpoint.isActive && endpoint.status !== 'incompatible')
+    );
+
+    this.hasMissingDefaultServers = computed(() =>
+      this.defaultEndpoints.some((endpoint) => !hasEndpointForDefault(this._servers(), endpoint))
+    );
+
+    this.activeServer = computed(() => this.activeServers()[0] ?? null);
+
+    this.loadEndpoints();
+  }
+
+  getPrimaryDefaultServerUrl(): string {
+    return this.primaryDefaultServerUrl;
+  }
+
+  sanitiseUrl(rawUrl: string): string {
+    return sanitiseServerBaseUrl(rawUrl);
+  }
+
+  addServer(server: { name: string; url: string }): ServerEndpoint {
+    const newEndpoint: ServerEndpoint = {
+      id: uuidv4(),
+      name: server.name,
+      url: this.sanitiseUrl(server.url),
+      isActive: true,
+      isDefault: false,
+      status: 'unknown'
+    };
+
+    this._servers.update((endpoints) => [...endpoints, newEndpoint]);
+    this.saveEndpoints();
+    return newEndpoint;
+  }
+
+  ensureServerEndpoint(
+    server: { name: string; url: string },
+    options?: { setActive?: boolean }
+  ): ServerEndpoint {
+    const existing = this.findServerByUrl(server.url);
+
+    if (existing) {
+      if (options?.setActive) {
+        this.setActiveServer(existing.id);
+      }
+
+      return existing;
+    }
+
+    const created = this.addServer(server);
+
+    if (options?.setActive) {
+      this.setActiveServer(created.id);
+    }
+
+    return created;
+  }
+
+  findServerByUrl(url: string): ServerEndpoint | undefined {
+    const sanitisedUrl = this.sanitiseUrl(url);
+
+    return this._servers().find((endpoint) => this.sanitiseUrl(endpoint.url) === sanitisedUrl);
+  }
+
+  removeServer(endpointId: string): void {
+    const endpoints = this._servers();
+    const target = endpoints.find((endpoint) => endpoint.id === endpointId);
+
+    if (!target || endpoints.length <= 1) {
+      return;
+    }
+
+    if (target.isDefault) {
+      this.markDefaultEndpointRemoved(target);
+    }
+
+    const updatedEndpoints = ensureAnyActiveEndpoint(
+      endpoints.filter((endpoint) => endpoint.id !== endpointId)
+    );
+
+    this._servers.set(updatedEndpoints);
+    this.saveEndpoints();
+  }
+
+  restoreDefaultServers(): ServerEndpoint[] {
+    const restoredEndpoints = this.defaultEndpoints
+      .filter((defaultEndpoint) => !hasEndpointForDefault(this._servers(), defaultEndpoint))
+      .map((defaultEndpoint) => ({
+        ...defaultEndpoint,
+        id: uuidv4(),
+        isActive: true
+      }));
+
+    if (restoredEndpoints.length === 0) {
+      this.storage.clearRemovedDefaultEndpointKeys();
+      return [];
+    }
+
+    this._servers.update((endpoints) => ensureAnyActiveEndpoint([...endpoints, ...restoredEndpoints]));
+    this.storage.clearRemovedDefaultEndpointKeys();
+    this.saveEndpoints();
+    return restoredEndpoints;
+  }
+
+  setActiveServer(endpointId: string): void {
+    this._servers.update((endpoints) => {
+      const target = endpoints.find((endpoint) => endpoint.id === endpointId);
+
+      if (!target || target.status === 'incompatible') {
+        return endpoints;
+      }
+
+      return endpoints.map((endpoint) =>
+        endpoint.id === endpointId
+          ? { ...endpoint, isActive: true }
+          : endpoint
+      );
+    });
+
+    this.saveEndpoints();
+  }
+
+  deactivateServer(endpointId: string): void {
+    if (this.activeServers().length <= 1) {
+      return;
+    }
+
+    this._servers.update((endpoints) =>
+      endpoints.map((endpoint) =>
+        endpoint.id === endpointId
+          ? { ...endpoint, isActive: false }
+          : endpoint
+      )
+    );
+
+    this.saveEndpoints();
+  }
+
+  updateServerStatus(
+    endpointId: string,
+    status: ServerEndpoint['status'],
+    latency?: number,
+    versions?: ServerEndpointVersions
+  ): void {
+    this._servers.update((endpoints) => ensureCompatibleActiveEndpoint(endpoints.map((endpoint) => {
+      if (endpoint.id !== endpointId) {
+        return endpoint;
+      }
+
+      return {
+        ...endpoint,
+        status,
+        latency,
+        isActive: status === 'incompatible' ? false : endpoint.isActive,
+        serverVersion: versions?.serverVersion ?? endpoint.serverVersion,
+        clientVersion: versions?.clientVersion ?? endpoint.clientVersion
+      };
+    })));
+
+    this.saveEndpoints();
+  }
+
+  private loadEndpoints(): void {
+    const storedEndpoints = this.storage.loadEndpoints();
+
+    if (!storedEndpoints) {
+      this.initialiseDefaultEndpoints();
+      return;
+    }
+
+    this._servers.set(this.reconcileStoredEndpoints(storedEndpoints));
+    this.saveEndpoints();
+  }
+
+  private initialiseDefaultEndpoints(): void {
+    this._servers.set(this.defaultEndpoints.map((endpoint) => ({
+      ...endpoint,
+      id: uuidv4()
+    })));
+
+    this.saveEndpoints();
+  }
+
+  private reconcileStoredEndpoints(storedEndpoints: ServerEndpoint[]): ServerEndpoint[] {
+    const reconciled: ServerEndpoint[] = [];
+    const claimedDefaultKeys = new Set<string>();
+    const removedDefaultKeys = this.storage.loadRemovedDefaultEndpointKeys();
+
+    for (const endpoint of storedEndpoints) {
+      if (!endpoint || typeof endpoint.id !== 'string' || typeof endpoint.url !== 'string') {
+        continue;
+      }
+
+      const sanitisedUrl = this.sanitiseUrl(endpoint.url);
+      const matchedDefault = matchDefaultEndpointTemplate(
+        this.defaultEndpoints,
+        endpoint,
+        sanitisedUrl,
+        claimedDefaultKeys
+      );
+
+      if (matchedDefault) {
+        claimedDefaultKeys.add(matchedDefault.defaultKey);
+        reconciled.push({
+          ...endpoint,
+          name: matchedDefault.name,
+          url: matchedDefault.url,
+          isDefault: true,
+          defaultKey: matchedDefault.defaultKey,
+          status: endpoint.status ?? 'unknown'
+        });
+
+        continue;
+      }
+
+      reconciled.push({
+        ...endpoint,
+        url: sanitisedUrl,
+        status: endpoint.status ?? 'unknown'
+      });
+    }
+
+    for (const defaultEndpoint of this.defaultEndpoints) {
+      if (
+        !claimedDefaultKeys.has(defaultEndpoint.defaultKey)
+        && !removedDefaultKeys.has(defaultEndpoint.defaultKey)
+        && !hasEndpointForDefault(reconciled, defaultEndpoint)
+      ) {
+        reconciled.push({
+          ...defaultEndpoint,
+          id: uuidv4(),
+          isActive: defaultEndpoint.isActive
+        });
+      }
+    }
+
+    return ensureAnyActiveEndpoint(reconciled);
+  }
+
+  private markDefaultEndpointRemoved(endpoint: ServerEndpoint): void {
+    const defaultKey = endpoint.defaultKey ?? findDefaultEndpointKeyByUrl(this.defaultEndpoints, endpoint.url);
+
+    if (!defaultKey) {
+      return;
+    }
+
+    const removedDefaultKeys = this.storage.loadRemovedDefaultEndpointKeys();
+
+    removedDefaultKeys.add(defaultKey);
+    this.storage.saveRemovedDefaultEndpointKeys(removedDefaultKeys);
+  }
+
+  private saveEndpoints(): void {
+    this.storage.saveEndpoints(this._servers());
+  }
+}

src/app/domains/server-directory/domain/server-directory.constants.ts

@@ -0,0 +1 @@
+export const CLIENT_UPDATE_REQUIRED_MESSAGE = 'Update the client in order to connect to other users';

src/app/domains/server-directory/domain/server-directory.models.ts

@@ -0,0 +1,115 @@
+import type { ServerInfo } from '../../../core/models';
+
+export type ServerEndpointStatus = 'online' | 'offline' | 'checking' | 'unknown' | 'incompatible';
+
+export interface ConfiguredDefaultServerDefinition {
+  key?: string;
+  name?: string;
+  url?: string;
+}
+
+export interface DefaultServerDefinition {
+  key: string;
+  name: string;
+  url: string;
+}
+
+export interface ServerEndpointVersions {
+  serverVersion?: string | null;
+  clientVersion?: string | null;
+}
+
+export interface ServerEndpoint {
+  id: string;
+  name: string;
+  url: string;
+  isActive: boolean;
+  isDefault: boolean;
+  defaultKey?: string;
+  status: ServerEndpointStatus;
+  latency?: number;
+  serverVersion?: string;
+  clientVersion?: string;
+}
+
+export type DefaultEndpointTemplate = Omit<ServerEndpoint, 'id' | 'defaultKey'> & {
+  defaultKey: string;
+};
+
+export interface ServerSourceSelector {
+  sourceId?: string;
+  sourceUrl?: string;
+}
+
+export interface ServerJoinAccessRequest {
+  roomId: string;
+  userId: string;
+  userPublicKey: string;
+  displayName: string;
+  password?: string;
+  inviteId?: string;
+}
+
+export interface ServerJoinAccessResponse {
+  success: boolean;
+  signalingUrl: string;
+  joinedBefore: boolean;
+  via: 'membership' | 'password' | 'invite' | 'public';
+  server: ServerInfo;
+}
+
+export interface CreateServerInviteRequest {
+  requesterUserId: string;
+  requesterDisplayName?: string;
+  requesterRole?: string;
+}
+
+export interface ServerInviteInfo {
+  id: string;
+  serverId: string;
+  createdAt: number;
+  expiresAt: number;
+  inviteUrl: string;
+  browserUrl: string;
+  appUrl: string;
+  sourceUrl: string;
+  createdBy?: string;
+  createdByDisplayName?: string;
+  isExpired: boolean;
+  server: ServerInfo;
+}
+
+export interface KickServerMemberRequest {
+  actorUserId: string;
+  actorRole?: string;
+  targetUserId: string;
+}
+
+export interface BanServerMemberRequest extends KickServerMemberRequest {
+  banId?: string;
+  displayName?: string;
+  reason?: string;
+  expiresAt?: number;
+}
+
+export interface UnbanServerMemberRequest {
+  actorUserId: string;
+  actorRole?: string;
+  banId?: string;
+  targetUserId?: string;
+}
+
+export interface ServerVersionCompatibilityResult {
+  isCompatible: boolean;
+  serverVersion: string | null;
+}
+
+export interface ServerHealthCheckPayload {
+  serverVersion?: unknown;
+}
+
+export interface ServerEndpointHealthResult {
+  status: ServerEndpointStatus;
+  latency?: number;
+  versions?: ServerEndpointVersions;
+}

src/app/domains/server-directory/domain/server-endpoint-defaults.ts

@@ -0,0 +1,187 @@
+import type {
+  ConfiguredDefaultServerDefinition,
+  DefaultEndpointTemplate,
+  DefaultServerDefinition,
+  ServerEndpoint
+} from './server-directory.models';
+
+export function sanitiseServerBaseUrl(rawUrl: string): string {
+  let cleaned = rawUrl.trim().replace(/\/+$/, '');
+
+  if (cleaned.toLowerCase().endsWith('/api')) {
+    cleaned = cleaned.slice(0, -4);
+  }
+
+  return cleaned;
+}
+
+export function normaliseConfiguredServerUrl(
+  rawUrl: string,
+  defaultProtocol: 'http' | 'https'
+): string {
+  let cleaned = rawUrl.trim();
+
+  if (!cleaned) {
+    return '';
+  }
+
+  if (cleaned.toLowerCase().startsWith('ws://')) {
+    cleaned = `http://${cleaned.slice(5)}`;
+  } else if (cleaned.toLowerCase().startsWith('wss://')) {
+    cleaned = `https://${cleaned.slice(6)}`;
+  } else if (cleaned.startsWith('//')) {
+    cleaned = `${defaultProtocol}:${cleaned}`;
+  } else if (!/^[a-z][a-z\d+.-]*:\/\//i.test(cleaned)) {
+    cleaned = `${defaultProtocol}://${cleaned}`;
+  }
+
+  return sanitiseServerBaseUrl(cleaned);
+}
+
+export function buildFallbackDefaultServerUrl(
+  configuredUrl: string | undefined,
+  defaultProtocol: 'http' | 'https'
+): string {
+  if (configuredUrl?.trim()) {
+    return normaliseConfiguredServerUrl(configuredUrl, defaultProtocol);
+  }
+
+  return `${defaultProtocol}://localhost:3001`;
+}
+
+export function buildDefaultServerDefinitions(
+  configuredDefaults: ConfiguredDefaultServerDefinition[] | undefined,
+  configuredUrl: string | undefined,
+  defaultProtocol: 'http' | 'https'
+): DefaultServerDefinition[] {
+  const seenKeys = new Set<string>();
+  const seenUrls = new Set<string>();
+  const definitions = (configuredDefaults ?? [])
+    .map((server, index) => {
+      const key = server.key?.trim() || `default-${index + 1}`;
+      const url = normaliseConfiguredServerUrl(server.url ?? '', defaultProtocol);
+
+      if (!key || !url || seenKeys.has(key) || seenUrls.has(url)) {
+        return null;
+      }
+
+      seenKeys.add(key);
+      seenUrls.add(url);
+
+      return {
+        key,
+        name: server.name?.trim() || (index === 0 ? 'Default Server' : `Default Server ${index + 1}`),
+        url
+      } satisfies DefaultServerDefinition;
+    })
+    .filter((definition): definition is DefaultServerDefinition => definition !== null);
+
+  if (definitions.length > 0) {
+    return definitions;
+  }
+
+  return [
+    {
+      key: 'default',
+      name: 'Default Server',
+      url: buildFallbackDefaultServerUrl(configuredUrl, defaultProtocol)
+    }
+  ];
+}
+
+export function buildDefaultEndpointTemplates(
+  definitions: DefaultServerDefinition[]
+): DefaultEndpointTemplate[] {
+  return definitions.map((definition) => ({
+    name: definition.name,
+    url: definition.url,
+    isActive: true,
+    isDefault: true,
+    defaultKey: definition.key,
+    status: 'unknown'
+  }));
+}
+
+export function hasEndpointForDefault(
+  endpoints: ServerEndpoint[],
+  defaultEndpoint: DefaultEndpointTemplate
+): boolean {
+  return endpoints.some((endpoint) =>
+    endpoint.defaultKey === defaultEndpoint.defaultKey
+    || sanitiseServerBaseUrl(endpoint.url) === defaultEndpoint.url
+  );
+}
+
+export function matchDefaultEndpointTemplate(
+  defaultEndpoints: DefaultEndpointTemplate[],
+  endpoint: ServerEndpoint,
+  sanitisedUrl: string,
+  claimedDefaultKeys: Set<string>
+): DefaultEndpointTemplate | null {
+  if (endpoint.defaultKey) {
+    return defaultEndpoints.find(
+      (candidate) => candidate.defaultKey === endpoint.defaultKey && !claimedDefaultKeys.has(candidate.defaultKey)
+    ) ?? null;
+  }
+
+  if (!endpoint.isDefault) {
+    return null;
+  }
+
+  const matchingCurrentDefault = defaultEndpoints.find(
+    (candidate) => candidate.url === sanitisedUrl && !claimedDefaultKeys.has(candidate.defaultKey)
+  );
+
+  if (matchingCurrentDefault) {
+    return matchingCurrentDefault;
+  }
+
+  return defaultEndpoints.find(
+    (candidate) => !claimedDefaultKeys.has(candidate.defaultKey)
+  ) ?? null;
+}
+
+export function findDefaultEndpointKeyByUrl(
+  defaultEndpoints: DefaultEndpointTemplate[],
+  url: string
+): string | null {
+  const sanitisedUrl = sanitiseServerBaseUrl(url);
+
+  return defaultEndpoints.find((endpoint) => endpoint.url === sanitisedUrl)?.defaultKey ?? null;
+}
+
+export function ensureAnyActiveEndpoint(endpoints: ServerEndpoint[]): ServerEndpoint[] {
+  if (endpoints.length === 0 || endpoints.some((endpoint) => endpoint.isActive)) {
+    return endpoints;
+  }
+
+  const nextEndpoints = [...endpoints];
+
+  nextEndpoints[0] = {
+    ...nextEndpoints[0],
+    isActive: true
+  };
+
+  return nextEndpoints;
+}
+
+export function ensureCompatibleActiveEndpoint(endpoints: ServerEndpoint[]): ServerEndpoint[] {
+  if (endpoints.length === 0 || endpoints.some((endpoint) => endpoint.isActive)) {
+    return endpoints;
+  }
+
+  const fallbackIndex = endpoints.findIndex((endpoint) => endpoint.status !== 'incompatible');
+
+  if (fallbackIndex < 0) {
+    return endpoints;
+  }
+
+  const nextEndpoints = [...endpoints];
+
+  nextEndpoints[fallbackIndex] = {
+    ...nextEndpoints[fallbackIndex],
+    isActive: true
+  };
+
+  return nextEndpoints;
+}

src/app/domains/server-directory/index.ts

@@ -0,0 +1,3 @@
+export * from './application/server-directory.facade';
+export * from './domain/server-directory.constants';
+export * from './domain/server-directory.models';

src/app/domains/server-directory/infrastructure/server-directory-api.service.ts

@@ -0,0 +1,404 @@
+/* eslint-disable @typescript-eslint/no-invalid-void-type */
+import { Injectable, inject } from '@angular/core';
+import { HttpClient, HttpParams } from '@angular/common/http';
+import {
+  Observable,
+  forkJoin,
+  of,
+  throwError
+} from 'rxjs';
+import { catchError, map } from 'rxjs/operators';
+import { ServerInfo, User } from '../../../core/models';
+import { ServerEndpointStateService } from '../application/server-endpoint-state.service';
+import type {
+  BanServerMemberRequest,
+  CreateServerInviteRequest,
+  KickServerMemberRequest,
+  ServerEndpoint,
+  ServerInviteInfo,
+  ServerJoinAccessRequest,
+  ServerJoinAccessResponse,
+  ServerSourceSelector,
+  UnbanServerMemberRequest
+} from '../domain/server-directory.models';
+
+@Injectable({ providedIn: 'root' })
+export class ServerDirectoryApiService {
+  private readonly http = inject(HttpClient);
+  private readonly endpointState = inject(ServerEndpointStateService);
+
+  getApiBaseUrl(selector?: ServerSourceSelector): string {
+    return `${this.resolveBaseServerUrl(selector)}/api`;
+  }
+
+  getWebSocketUrl(selector?: ServerSourceSelector): string {
+    return this.resolveBaseServerUrl(selector).replace(/^http/, 'ws');
+  }
+
+  resolveEndpoint(selector?: ServerSourceSelector): ServerEndpoint | null {
+    if (selector?.sourceId) {
+      return this.endpointState.servers().find((endpoint) => endpoint.id === selector.sourceId) ?? null;
+    }
+
+    if (selector?.sourceUrl) {
+      return this.endpointState.findServerByUrl(selector.sourceUrl) ?? null;
+    }
+
+    return this.endpointState.activeServer()
+      ?? this.endpointState.servers().find((endpoint) => endpoint.status !== 'incompatible')
+      ?? this.endpointState.servers()[0]
+      ?? null;
+  }
+
+  searchServers(query: string, shouldSearchAllServers: boolean): Observable<ServerInfo[]> {
+    if (shouldSearchAllServers) {
+      return this.searchAllEndpoints(query);
+    }
+
+    return this.searchSingleEndpoint(query, this.getApiBaseUrl(), this.endpointState.activeServer());
+  }
+
+  getServers(shouldSearchAllServers: boolean): Observable<ServerInfo[]> {
+    if (shouldSearchAllServers) {
+      return this.getAllServersFromAllEndpoints();
+    }
+
+    return this.http
+      .get<{ servers: ServerInfo[]; total: number }>(`${this.getApiBaseUrl()}/servers`)
+      .pipe(
+        map((response) => this.normalizeServerList(response, this.endpointState.activeServer())),
+        catchError((error) => {
+          console.error('Failed to get servers:', error);
+          return of([]);
+        })
+      );
+  }
+
+  getServer(serverId: string, selector?: ServerSourceSelector): Observable<ServerInfo | null> {
+    return this.http
+      .get<ServerInfo>(`${this.getApiBaseUrl(selector)}/servers/${serverId}`)
+      .pipe(
+        map((server) => this.normalizeServerInfo(server, this.resolveEndpoint(selector))),
+        catchError((error) => {
+          console.error('Failed to get server:', error);
+          return of(null);
+        })
+      );
+  }
+
+  registerServer(
+    server: Omit<ServerInfo, 'createdAt'> & { id?: string; password?: string | null },
+    selector?: ServerSourceSelector
+  ): Observable<ServerInfo> {
+    return this.http
+      .post<ServerInfo>(`${this.getApiBaseUrl(selector)}/servers`, server)
+      .pipe(
+        catchError((error) => {
+          console.error('Failed to register server:', error);
+          return throwError(() => error);
+        })
+      );
+  }
+
+  updateServer(
+    serverId: string,
+    updates: Partial<ServerInfo> & {
+      currentOwnerId: string;
+      actingRole?: string;
+      password?: string | null;
+    },
+    selector?: ServerSourceSelector
+  ): Observable<ServerInfo> {
+    return this.http
+      .put<ServerInfo>(`${this.getApiBaseUrl(selector)}/servers/${serverId}`, updates)
+      .pipe(
+        catchError((error) => {
+          console.error('Failed to update server:', error);
+          return throwError(() => error);
+        })
+      );
+  }
+
+  unregisterServer(serverId: string, selector?: ServerSourceSelector): Observable<void> {
+    return this.http
+      .delete<void>(`${this.getApiBaseUrl(selector)}/servers/${serverId}`)
+      .pipe(
+        catchError((error) => {
+          console.error('Failed to unregister server:', error);
+          return throwError(() => error);
+        })
+      );
+  }
+
+  getServerUsers(serverId: string, selector?: ServerSourceSelector): Observable<User[]> {
+    return this.http
+      .get<User[]>(`${this.getApiBaseUrl(selector)}/servers/${serverId}/users`)
+      .pipe(
+        catchError((error) => {
+          console.error('Failed to get server users:', error);
+          return of([]);
+        })
+      );
+  }
+
+  requestJoin(
+    request: ServerJoinAccessRequest,
+    selector?: ServerSourceSelector
+  ): Observable<ServerJoinAccessResponse> {
+    return this.http
+      .post<ServerJoinAccessResponse>(
+        `${this.getApiBaseUrl(selector)}/servers/${request.roomId}/join`,
+        request
+      )
+      .pipe(
+        catchError((error) => {
+          console.error('Failed to send join request:', error);
+          return throwError(() => error);
+        })
+      );
+  }
+
+  createInvite(
+    serverId: string,
+    request: CreateServerInviteRequest,
+    selector?: ServerSourceSelector
+  ): Observable<ServerInviteInfo> {
+    return this.http
+      .post<ServerInviteInfo>(`${this.getApiBaseUrl(selector)}/servers/${serverId}/invites`, request)
+      .pipe(
+        catchError((error) => {
+          console.error('Failed to create invite:', error);
+          return throwError(() => error);
+        })
+      );
+  }
+
+  getInvite(inviteId: string, selector?: ServerSourceSelector): Observable<ServerInviteInfo> {
+    return this.http
+      .get<ServerInviteInfo>(`${this.getApiBaseUrl(selector)}/invites/${inviteId}`)
+      .pipe(
+        catchError((error) => {
+          console.error('Failed to get invite:', error);
+          return throwError(() => error);
+        })
+      );
+  }
+
+  kickServerMember(
+    serverId: string,
+    request: KickServerMemberRequest,
+    selector?: ServerSourceSelector
+  ): Observable<void> {
+    return this.http
+      .post<void>(`${this.getApiBaseUrl(selector)}/servers/${serverId}/moderation/kick`, request)
+      .pipe(
+        catchError((error) => {
+          console.error('Failed to kick server member:', error);
+          return throwError(() => error);
+        })
+      );
+  }
+
+  banServerMember(
+    serverId: string,
+    request: BanServerMemberRequest,
+    selector?: ServerSourceSelector
+  ): Observable<void> {
+    return this.http
+      .post<void>(`${this.getApiBaseUrl(selector)}/servers/${serverId}/moderation/ban`, request)
+      .pipe(
+        catchError((error) => {
+          console.error('Failed to ban server member:', error);
+          return throwError(() => error);
+        })
+      );
+  }
+
+  unbanServerMember(
+    serverId: string,
+    request: UnbanServerMemberRequest,
+    selector?: ServerSourceSelector
+  ): Observable<void> {
+    return this.http
+      .post<void>(`${this.getApiBaseUrl(selector)}/servers/${serverId}/moderation/unban`, request)
+      .pipe(
+        catchError((error) => {
+          console.error('Failed to unban server member:', error);
+          return throwError(() => error);
+        })
+      );
+  }
+
+  notifyLeave(serverId: string, userId: string, selector?: ServerSourceSelector): Observable<void> {
+    return this.http
+      .post<void>(`${this.getApiBaseUrl(selector)}/servers/${serverId}/leave`, { userId })
+      .pipe(
+        catchError((error) => {
+          console.error('Failed to notify leave:', error);
+          return of(undefined);
+        })
+      );
+  }
+
+  updateUserCount(serverId: string, count: number): Observable<void> {
+    return this.http
+      .patch<void>(`${this.getApiBaseUrl()}/servers/${serverId}/user-count`, { count })
+      .pipe(
+        catchError((error) => {
+          console.error('Failed to update user count:', error);
+          return of(undefined);
+        })
+      );
+  }
+
+  sendHeartbeat(serverId: string): Observable<void> {
+    return this.http
+      .post<void>(`${this.getApiBaseUrl()}/servers/${serverId}/heartbeat`, {})
+      .pipe(
+        catchError((error) => {
+          console.error('Failed to send heartbeat:', error);
+          return of(undefined);
+        })
+      );
+  }
+
+  private resolveBaseServerUrl(selector?: ServerSourceSelector): string {
+    if (selector?.sourceUrl) {
+      return this.endpointState.sanitiseUrl(selector.sourceUrl);
+    }
+
+    return this.resolveEndpoint(selector)?.url ?? this.endpointState.getPrimaryDefaultServerUrl();
+  }
+
+  private unwrapServersResponse(
+    response: { servers: ServerInfo[]; total: number } | ServerInfo[]
+  ): ServerInfo[] {
+    return Array.isArray(response)
+      ? response
+      : (response.servers ?? []);
+  }
+
+  private searchSingleEndpoint(
+    query: string,
+    apiBaseUrl: string,
+    source?: ServerEndpoint | null
+  ): Observable<ServerInfo[]> {
+    const params = new HttpParams().set('q', query);
+
+    return this.http
+      .get<{ servers: ServerInfo[]; total: number }>(`${apiBaseUrl}/servers`, { params })
+      .pipe(
+        map((response) => this.normalizeServerList(response, source)),
+        catchError((error) => {
+          console.error('Failed to search servers:', error);
+          return of([]);
+        })
+      );
+  }
+
+  private searchAllEndpoints(query: string): Observable<ServerInfo[]> {
+    const onlineEndpoints = this.endpointState.activeServers().filter(
+      (endpoint) => endpoint.status !== 'offline'
+    );
+
+    if (onlineEndpoints.length === 0) {
+      return this.searchSingleEndpoint(query, this.getApiBaseUrl(), this.endpointState.activeServer());
+    }
+
+    return forkJoin(
+      onlineEndpoints.map((endpoint) => this.searchSingleEndpoint(query, `${endpoint.url}/api`, endpoint))
+    ).pipe(
+      map((resultArrays) => resultArrays.flat()),
+      map((servers) => this.deduplicateById(servers))
+    );
+  }
+
+  private getAllServersFromAllEndpoints(): Observable<ServerInfo[]> {
+    const onlineEndpoints = this.endpointState.activeServers().filter(
+      (endpoint) => endpoint.status !== 'offline'
+    );
+
+    if (onlineEndpoints.length === 0) {
+      return this.http
+        .get<{ servers: ServerInfo[]; total: number }>(`${this.getApiBaseUrl()}/servers`)
+        .pipe(
+          map((response) => this.normalizeServerList(response, this.endpointState.activeServer())),
+          catchError(() => of([]))
+        );
+    }
+
+    return forkJoin(
+      onlineEndpoints.map((endpoint) =>
+        this.http
+          .get<{ servers: ServerInfo[]; total: number }>(`${endpoint.url}/api/servers`)
+          .pipe(
+            map((response) => this.normalizeServerList(response, endpoint)),
+            catchError(() => of([] as ServerInfo[]))
+          )
+      )
+    ).pipe(map((resultArrays) => resultArrays.flat()));
+  }
+
+  private deduplicateById<T extends { id: string }>(items: T[]): T[] {
+    const seen = new Set<string>();
+
+    return items.filter((item) => {
+      if (seen.has(item.id)) {
+        return false;
+      }
+
+      seen.add(item.id);
+      return true;
+    });
+  }
+
+  private normalizeServerList(
+    response: { servers: ServerInfo[]; total: number } | ServerInfo[],
+    source?: ServerEndpoint | null
+  ): ServerInfo[] {
+    return this.unwrapServersResponse(response).map((server) => this.normalizeServerInfo(server, source));
+  }
+
+  private normalizeServerInfo(
+    server: ServerInfo | Record<string, unknown>,
+    source?: ServerEndpoint | null
+  ): ServerInfo {
+    const candidate = server as Record<string, unknown>;
+    const sourceName = this.getStringValue(candidate['sourceName']);
+    const sourceUrl = this.getStringValue(candidate['sourceUrl']);
+
+    return {
+      id: this.getStringValue(candidate['id']) ?? '',
+      name: this.getStringValue(candidate['name']) ?? 'Unnamed server',
+      description: this.getStringValue(candidate['description']),
+      topic: this.getStringValue(candidate['topic']),
+      hostName: this.getStringValue(candidate['hostName']) ?? sourceName ?? source?.name ?? 'Unknown API',
+      ownerId: this.getStringValue(candidate['ownerId']),
+      ownerName: this.getStringValue(candidate['ownerName']),
+      ownerPublicKey: this.getStringValue(candidate['ownerPublicKey']),
+      userCount: this.getNumberValue(candidate['userCount'], this.getNumberValue(candidate['currentUsers'])),
+      maxUsers: this.getNumberValue(candidate['maxUsers']),
+      hasPassword: this.getBooleanValue(candidate['hasPassword']),
+      isPrivate: this.getBooleanValue(candidate['isPrivate']),
+      tags: Array.isArray(candidate['tags']) ? candidate['tags'] as string[] : [],
+      createdAt: this.getNumberValue(candidate['createdAt'], Date.now()),
+      sourceId: this.getStringValue(candidate['sourceId']) ?? source?.id,
+      sourceName: sourceName ?? source?.name,
+      sourceUrl: sourceUrl
+        ? this.endpointState.sanitiseUrl(sourceUrl)
+        : (source ? this.endpointState.sanitiseUrl(source.url) : undefined)
+    };
+  }
+
+  private getBooleanValue(value: unknown): boolean {
+    return typeof value === 'boolean' ? value : value === 1;
+  }
+
+  private getNumberValue(value: unknown, fallback = 0): number {
+    return typeof value === 'number' ? value : fallback;
+  }
+
+  private getStringValue(value: unknown): string | undefined {
+    return typeof value === 'string' ? value : undefined;
+  }
+}

src/app/domains/server-directory/infrastructure/server-directory.infrastructure.constants.ts

@@ -0,0 +1,3 @@
+export const SERVER_ENDPOINTS_STORAGE_KEY = 'metoyou_server_endpoints';
+export const REMOVED_DEFAULT_SERVER_KEYS_STORAGE_KEY = 'metoyou_removed_default_server_keys';
+export const SERVER_HEALTH_CHECK_TIMEOUT_MS = 5000;

src/app/domains/server-directory/infrastructure/server-endpoint-compatibility.service.ts

@@ -0,0 +1,77 @@
+import { Injectable, inject } from '@angular/core';
+import { ElectronBridgeService } from '../../../core/platform/electron/electron-bridge.service';
+import type { ServerVersionCompatibilityResult } from '../domain/server-directory.models';
+
+@Injectable({ providedIn: 'root' })
+export class ServerEndpointCompatibilityService {
+  private readonly electronBridge = inject(ElectronBridgeService);
+  private clientVersionPromise: Promise<string | null> | null = null;
+
+  async getClientVersion(): Promise<string | null> {
+    if (!this.clientVersionPromise) {
+      this.clientVersionPromise = this.resolveClientVersion();
+    }
+
+    return await this.clientVersionPromise;
+  }
+
+  evaluateServerVersion(
+    rawServerVersion: unknown,
+    clientVersion: string | null
+  ): ServerVersionCompatibilityResult {
+    const serverVersion = normalizeSemanticVersion(rawServerVersion);
+
+    return {
+      isCompatible: !clientVersion || (serverVersion !== null && serverVersion === clientVersion),
+      serverVersion
+    };
+  }
+
+  private async resolveClientVersion(): Promise<string | null> {
+    const electronApi = this.electronBridge.getApi();
+
+    if (!electronApi) {
+      return null;
+    }
+
+    try {
+      const state = await electronApi.getAutoUpdateState();
+
+      return normalizeSemanticVersion(state?.currentVersion);
+    } catch {
+      return null;
+    }
+  }
+}
+
+function normalizeSemanticVersion(rawVersion: unknown): string | null {
+  if (typeof rawVersion !== 'string') {
+    return null;
+  }
+
+  const trimmed = rawVersion.trim();
+
+  if (!trimmed) {
+    return null;
+  }
+
+  const match = trimmed.match(/^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/i);
+
+  if (!match) {
+    return null;
+  }
+
+  const major = Number.parseInt(match[1], 10);
+  const minor = Number.parseInt(match[2], 10);
+  const patch = Number.parseInt(match[3], 10);
+
+  if (
+    Number.isNaN(major)
+    || Number.isNaN(minor)
+    || Number.isNaN(patch)
+  ) {
+    return null;
+  }
+
+  return `${major}.${minor}.${patch}`;
+}

src/app/domains/server-directory/infrastructure/server-endpoint-health.service.ts

@@ -0,0 +1,75 @@
+import { Injectable, inject } from '@angular/core';
+import { SERVER_HEALTH_CHECK_TIMEOUT_MS } from './server-directory.infrastructure.constants';
+import type {
+  ServerEndpoint,
+  ServerEndpointHealthResult,
+  ServerHealthCheckPayload
+} from '../domain/server-directory.models';
+import { ServerEndpointCompatibilityService } from './server-endpoint-compatibility.service';
+
+@Injectable({ providedIn: 'root' })
+export class ServerEndpointHealthService {
+  private readonly endpointCompatibility = inject(ServerEndpointCompatibilityService);
+
+  async probeEndpoint(
+    endpoint: Pick<ServerEndpoint, 'url'>,
+    clientVersion: string | null
+  ): Promise<ServerEndpointHealthResult> {
+    const startTime = Date.now();
+
+    try {
+      const response = await fetch(`${endpoint.url}/api/health`, {
+        method: 'GET',
+        signal: AbortSignal.timeout(SERVER_HEALTH_CHECK_TIMEOUT_MS)
+      });
+      const latency = Date.now() - startTime;
+
+      if (response.ok) {
+        const payload = await response.json() as ServerHealthCheckPayload;
+        const versionCompatibility = this.endpointCompatibility.evaluateServerVersion(
+          payload.serverVersion,
+          clientVersion
+        );
+
+        if (!versionCompatibility.isCompatible) {
+          return {
+            status: 'incompatible',
+            latency,
+            versions: {
+              serverVersion: versionCompatibility.serverVersion,
+              clientVersion
+            }
+          };
+        }
+
+        return {
+          status: 'online',
+          latency,
+          versions: {
+            serverVersion: versionCompatibility.serverVersion,
+            clientVersion
+          }
+        };
+      }
+
+      return { status: 'offline' };
+    } catch {
+      try {
+        const response = await fetch(`${endpoint.url}/api/servers`, {
+          method: 'GET',
+          signal: AbortSignal.timeout(SERVER_HEALTH_CHECK_TIMEOUT_MS)
+        });
+        const latency = Date.now() - startTime;
+
+        if (response.ok) {
+          return {
+            status: 'online',
+            latency
+          };
+        }
+      } catch { /* both checks failed */ }
+
+      return { status: 'offline' };
+    }
+  }
+}

src/app/domains/server-directory/infrastructure/server-endpoint-storage.service.ts

@@ -0,0 +1,61 @@
+import { Injectable } from '@angular/core';
+import { REMOVED_DEFAULT_SERVER_KEYS_STORAGE_KEY, SERVER_ENDPOINTS_STORAGE_KEY } from './server-directory.infrastructure.constants';
+import type { ServerEndpoint } from '../domain/server-directory.models';
+
+@Injectable({ providedIn: 'root' })
+export class ServerEndpointStorageService {
+  loadEndpoints(): ServerEndpoint[] | null {
+    const stored = localStorage.getItem(SERVER_ENDPOINTS_STORAGE_KEY);
+
+    if (!stored) {
+      return null;
+    }
+
+    try {
+      const parsed = JSON.parse(stored) as unknown;
+
+      return Array.isArray(parsed)
+        ? parsed as ServerEndpoint[]
+        : null;
+    } catch {
+      return null;
+    }
+  }
+
+  saveEndpoints(endpoints: ServerEndpoint[]): void {
+    localStorage.setItem(SERVER_ENDPOINTS_STORAGE_KEY, JSON.stringify(endpoints));
+  }
+
+  loadRemovedDefaultEndpointKeys(): Set<string> {
+    const stored = localStorage.getItem(REMOVED_DEFAULT_SERVER_KEYS_STORAGE_KEY);
+
+    if (!stored) {
+      return new Set<string>();
+    }
+
+    try {
+      const parsed = JSON.parse(stored) as unknown;
+
+      if (!Array.isArray(parsed)) {
+        return new Set<string>();
+      }
+
+      return new Set(parsed.filter((value): value is string => typeof value === 'string'));
+    } catch {
+      return new Set<string>();
+    }
+  }
+
+  saveRemovedDefaultEndpointKeys(keys: Set<string>): void {
+    if (keys.size === 0) {
+      this.clearRemovedDefaultEndpointKeys();
+      return;
+    }
+
+    localStorage.setItem(REMOVED_DEFAULT_SERVER_KEYS_STORAGE_KEY, JSON.stringify([...keys]));
+  }
+
+  clearRemovedDefaultEndpointKeys(): void {
+    localStorage.removeItem(REMOVED_DEFAULT_SERVER_KEYS_STORAGE_KEY);
+  }
+}

src/app/domains/voice-connection/application/voice-activity.service.ts

@@ -0,0 +1,262 @@
+/**
+ * VoiceActivityService - monitors audio levels for local microphone
+ * and remote peer streams, exposing per-user "speaking" state as
+ * reactive Angular signals.
+ *
+ * Usage:
+ * ```ts
+ * const speaking = voiceActivity.isSpeaking(userId);
+ * // speaking() => true when the user's audio level exceeds the threshold
+ *
+ * const volume = voiceActivity.volume(userId);
+ * // volume() => normalised 0-1 audio level
+ * ```
+ *
+ * Internally uses the Web Audio API ({@link AudioContext} +
+ * {@link AnalyserNode}) per tracked stream, with a single
+ * `requestAnimationFrame` poll loop.
+ */
+import {
+  Injectable,
+  signal,
+  computed,
+  inject,
+  OnDestroy,
+  Signal
+} from '@angular/core';
+import { Subscription } from 'rxjs';
+import { VoiceConnectionFacade } from './voice-connection.facade';
+import { DebuggingService } from '../../../core/services/debugging.service';
+/* eslint-disable @typescript-eslint/member-ordering, @typescript-eslint/prefer-for-of, max-statements-per-line */
+
+const SPEAKING_THRESHOLD = 0.015;
+const SILENT_FRAME_GRACE = 8;
+const FFT_SIZE = 256;
+
+interface TrackedStream {
+  ctx: AudioContext;
+  sources: MediaStreamAudioSourceNode[];
+  analyser: AnalyserNode;
+  dataArray: Uint8Array<ArrayBuffer>;
+  volumeSignal: ReturnType<typeof signal<number>>;
+  speakingSignal: ReturnType<typeof signal<boolean>>;
+  silentFrames: number;
+  stream: MediaStream;
+}
+
+@Injectable({ providedIn: 'root' })
+export class VoiceActivityService implements OnDestroy {
+  private readonly voiceConnection = inject(VoiceConnectionFacade);
+  private readonly debugging = inject(DebuggingService);
+
+  private readonly tracked = new Map<string, TrackedStream>();
+  private animFrameId: number | null = null;
+  private readonly subs: Subscription[] = [];
+  private readonly _speakingMap = signal<ReadonlyMap<string, boolean>>(new Map());
+
+  readonly speakingMap: Signal<ReadonlyMap<string, boolean>> = this._speakingMap;
+
+  constructor() {
+    this.subs.push(
+      this.voiceConnection.onRemoteStream.subscribe(({ peerId }) => {
+        const voiceStream = this.voiceConnection.getRemoteVoiceStream(peerId);
+
+        if (!voiceStream) {
+          this.untrackStream(peerId);
+          return;
+        }
+
+        this.trackStream(peerId, voiceStream);
+      })
+    );
+
+    this.subs.push(
+      this.voiceConnection.onPeerDisconnected.subscribe((peerId) => {
+        this.untrackStream(peerId);
+      })
+    );
+  }
+
+  trackLocalMic(userId: string, stream: MediaStream): void {
+    this.trackStream(userId, stream);
+  }
+
+  untrackLocalMic(userId: string): void {
+    this.untrackStream(userId);
+  }
+
+  isSpeaking(userId: string): Signal<boolean> {
+    const entry = this.tracked.get(userId);
+
+    if (entry)
+      return entry.speakingSignal.asReadonly();
+
+    return computed(() => this._speakingMap().get(userId) ?? false);
+  }
+
+  volume(userId: string): Signal<number> {
+    const entry = this.tracked.get(userId);
+
+    if (entry)
+      return entry.volumeSignal.asReadonly();
+
+    return computed(() => 0);
+  }
+
+  trackStream(id: string, stream: MediaStream): void {
+    const existing = this.tracked.get(id);
+    const audioTracks = stream.getAudioTracks().filter((track) => track.readyState === 'live');
+
+    if (existing && existing.stream === stream)
+      return;
+
+    if (existing)
+      this.disposeEntry(existing);
+
+    if (audioTracks.length === 0) {
+      this.tracked.delete(id);
+      this.publishSpeakingMap();
+
+      if (this.tracked.size === 0)
+        this.stopPolling();
+
+      return;
+    }
+
+    const ctx = new AudioContext();
+    const analyser = ctx.createAnalyser();
+    const sources = audioTracks.map((track) => ctx.createMediaStreamSource(new MediaStream([track])));
+
+    analyser.fftSize = FFT_SIZE;
+    sources.forEach((source) => source.connect(analyser));
+
+    const dataArray = new Uint8Array(analyser.fftSize) as Uint8Array<ArrayBuffer>;
+    const volumeSignal = signal(0);
+    const speakingSignal = signal(false);
+
+    this.tracked.set(id, {
+      ctx,
+      sources,
+      analyser,
+      dataArray,
+      volumeSignal,
+      speakingSignal,
+      silentFrames: 0,
+      stream
+    });
+
+    this.ensurePolling();
+  }
+
+  untrackStream(id: string): void {
+    const entry = this.tracked.get(id);
+
+    if (!entry)
+      return;
+
+    if (entry.speakingSignal()) {
+      this.reportSpeakingState(id, false, 0);
+    }
+
+    this.disposeEntry(entry);
+    this.tracked.delete(id);
+    this.publishSpeakingMap();
+
+    if (this.tracked.size === 0)
+      this.stopPolling();
+  }
+
+  private ensurePolling(): void {
+    if (this.animFrameId !== null)
+      return;
+
+    this.poll();
+  }
+
+  private stopPolling(): void {
+    if (this.animFrameId !== null) {
+      cancelAnimationFrame(this.animFrameId);
+      this.animFrameId = null;
+    }
+  }
+
+  private poll = (): void => {
+    let mapDirty = false;
+
+    this.tracked.forEach((entry, id) => {
+      const { analyser, dataArray, volumeSignal, speakingSignal } = entry;
+
+      analyser.getByteTimeDomainData(dataArray);
+
+      let sumSquares = 0;
+
+      for (let sampleIndex = 0; sampleIndex < dataArray.length; sampleIndex++) {
+        const normalised = (dataArray[sampleIndex] - 128) / 128;
+
+        sumSquares += normalised * normalised;
+      }
+
+      const rms = Math.sqrt(sumSquares / dataArray.length);
+
+      volumeSignal.set(rms);
+
+      const wasSpeaking = speakingSignal();
+
+      if (rms >= SPEAKING_THRESHOLD) {
+        entry.silentFrames = 0;
+
+        if (!wasSpeaking) {
+          speakingSignal.set(true);
+          this.reportSpeakingState(id, true, rms);
+          mapDirty = true;
+        }
+      } else {
+        entry.silentFrames++;
+
+        if (wasSpeaking && entry.silentFrames >= SILENT_FRAME_GRACE) {
+          speakingSignal.set(false);
+          this.reportSpeakingState(id, false, rms);
+          mapDirty = true;
+        }
+      }
+    });
+
+    if (mapDirty)
+      this.publishSpeakingMap();
+
+    this.animFrameId = requestAnimationFrame(this.poll);
+  };
+
+  private publishSpeakingMap(): void {
+    const map = new Map<string, boolean>();
+
+    this.tracked.forEach((entry, id) => {
+      map.set(id, entry.speakingSignal());
+    });
+
+    this._speakingMap.set(map);
+  }
+
+  private reportSpeakingState(peerId: string, isSpeaking: boolean, volume: number): void {
+    this.debugging.recordEvent('webrtc:voice-activity', 'Speaking state changed', {
+      peerId,
+      isSpeaking,
+      volume: Number(volume.toFixed(3))
+    });
+  }
+
+  private disposeEntry(entry: TrackedStream): void {
+    entry.sources.forEach((source) => {
+      try { source.disconnect(); } catch { /* already disconnected */ }
+    });
+
+    try { entry.ctx.close(); } catch { /* already closed */ }
+  }
+
+  ngOnDestroy(): void {
+    this.stopPolling();
+    this.tracked.forEach((entry) => this.disposeEntry(entry));
+    this.tracked.clear();
+    this.subs.forEach((subscription) => subscription.unsubscribe());
+  }
+}

src/app/domains/voice-connection/application/voice-connection.facade.ts

@@ -0,0 +1,94 @@
+import { Injectable, inject } from '@angular/core';
+import { ChatEvent } from '../../../core/models/index';
+import { RealtimeSessionFacade } from '../../../core/realtime';
+import { LatencyProfile } from '../domain/voice-connection.models';
+
+@Injectable({ providedIn: 'root' })
+export class VoiceConnectionFacade {
+  readonly isVoiceConnected = inject(RealtimeSessionFacade).isVoiceConnected;
+  readonly isMuted = inject(RealtimeSessionFacade).isMuted;
+  readonly isDeafened = inject(RealtimeSessionFacade).isDeafened;
+  readonly isNoiseReductionEnabled = inject(RealtimeSessionFacade).isNoiseReductionEnabled;
+  readonly hasConnectionError = inject(RealtimeSessionFacade).hasConnectionError;
+  readonly connectionErrorMessage = inject(RealtimeSessionFacade).connectionErrorMessage;
+  readonly shouldShowConnectionError = inject(RealtimeSessionFacade).shouldShowConnectionError;
+  readonly peerLatencies = inject(RealtimeSessionFacade).peerLatencies;
+  readonly onRemoteStream = inject(RealtimeSessionFacade).onRemoteStream;
+  readonly onPeerConnected = inject(RealtimeSessionFacade).onPeerConnected;
+  readonly onPeerDisconnected = inject(RealtimeSessionFacade).onPeerDisconnected;
+  readonly onVoiceConnected = inject(RealtimeSessionFacade).onVoiceConnected;
+
+  private readonly realtime = inject(RealtimeSessionFacade);
+
+  async ensureSignalingConnected(timeoutMs?: number): Promise<boolean> {
+    return await this.realtime.ensureSignalingConnected(timeoutMs);
+  }
+
+  broadcastMessage(event: ChatEvent): void {
+    this.realtime.broadcastMessage(event);
+  }
+
+  getConnectedPeers(): string[] {
+    return this.realtime.getConnectedPeers();
+  }
+
+  getRemoteVoiceStream(peerId: string): MediaStream | null {
+    return this.realtime.getRemoteVoiceStream(peerId);
+  }
+
+  getLocalStream(): MediaStream | null {
+    return this.realtime.getLocalStream();
+  }
+
+  getRawMicStream(): MediaStream | null {
+    return this.realtime.getRawMicStream();
+  }
+
+  async enableVoice(): Promise<MediaStream> {
+    return await this.realtime.enableVoice();
+  }
+
+  disableVoice(): void {
+    this.realtime.disableVoice();
+  }
+
+  async setLocalStream(stream: MediaStream): Promise<void> {
+    await this.realtime.setLocalStream(stream);
+  }
+
+  toggleMute(muted?: boolean): void {
+    this.realtime.toggleMute(muted);
+  }
+
+  toggleDeafen(deafened?: boolean): void {
+    this.realtime.toggleDeafen(deafened);
+  }
+
+  async toggleNoiseReduction(enabled?: boolean): Promise<void> {
+    await this.realtime.toggleNoiseReduction(enabled);
+  }
+
+  setOutputVolume(volume: number): void {
+    this.realtime.setOutputVolume(volume);
+  }
+
+  setInputVolume(volume: number): void {
+    this.realtime.setInputVolume(volume);
+  }
+
+  async setAudioBitrate(kbps: number): Promise<void> {
+    await this.realtime.setAudioBitrate(kbps);
+  }
+
+  async setLatencyProfile(profile: LatencyProfile): Promise<void> {
+    await this.realtime.setLatencyProfile(profile);
+  }
+
+  startVoiceHeartbeat(roomId?: string, serverId?: string): void {
+    this.realtime.startVoiceHeartbeat(roomId, serverId);
+  }
+
+  stopVoiceHeartbeat(): void {
+    this.realtime.stopVoiceHeartbeat();
+  }
+}

src/app/domains/voice-connection/domain/voice-connection.models.ts

@@ -0,0 +1,5 @@
+export {
+  LATENCY_PROFILE_BITRATES,
+  type LatencyProfile
+} from '../../../infrastructure/realtime/realtime.constants';
+export type { VoiceStateSnapshot } from '../../../infrastructure/realtime/realtime.types';

src/app/domains/voice-connection/index.ts

@@ -0,0 +1,3 @@
+export * from './application/voice-connection.facade';
+export * from './application/voice-activity.service';
+export * from './domain/voice-connection.models';

src/app/domains/voice-session/application/voice-session.facade.ts

@@ -0,0 +1,114 @@
+/* eslint-disable @typescript-eslint/member-ordering, */
+import {
+  Injectable,
+  signal,
+  computed,
+  inject
+} from '@angular/core';
+import { Store } from '@ngrx/store';
+import { RoomsActions } from '../../../store/rooms/rooms.actions';
+import { buildVoiceSessionRoom, isViewingVoiceSessionServer } from '../domain/voice-session.logic';
+import type { VoiceSessionInfo } from '../domain/voice-session.models';
+
+/**
+ * Tracks the user's current voice session across client-side
+ * navigation so that floating voice controls remain visible when
+ * the user is browsing a different server or view.
+ *
+ * This service is purely a UI-state tracker - actual WebRTC
+ * voice management lives in {@link WebRTCService} and its managers.
+ */
+@Injectable({ providedIn: 'root' })
+export class VoiceSessionFacade {
+  private readonly store = inject(Store);
+
+  /** Current voice session metadata, or `null` when disconnected. */
+  private readonly _voiceSession = signal<VoiceSessionInfo | null>(null);
+
+  /** Whether the user is currently viewing the voice-connected server. */
+  private readonly _isViewingVoiceServer = signal<boolean>(true);
+
+  /** Reactive read-only voice session. */
+  readonly voiceSession = computed(() => this._voiceSession());
+
+  /** Reactive flag: is the user's current view the voice server? */
+  readonly isViewingVoiceServer = computed(() => this._isViewingVoiceServer());
+
+  /**
+   * Whether the floating voice-controls overlay should be visible.
+   * `true` when a voice session is active AND the user is viewing
+   * a different server.
+   */
+  readonly showFloatingControls = computed(
+    () => this._voiceSession() !== null && !this._isViewingVoiceServer()
+  );
+
+  /**
+   * Begin tracking a voice session.
+   * Called when the user joins a voice channel.
+   *
+   * @param sessionInfo - Metadata describing the voice-connected server/channel.
+   */
+  startSession(sessionInfo: VoiceSessionInfo): void {
+    this._voiceSession.set(sessionInfo);
+    this._isViewingVoiceServer.set(true);
+  }
+
+  /**
+   * Stop tracking the voice session.
+   * Called when the user disconnects from voice.
+   */
+  endSession(): void {
+    this._voiceSession.set(null);
+    this._isViewingVoiceServer.set(true);
+  }
+
+  /**
+   * Manually flag whether the user is currently viewing the
+   * voice-connected server.
+   *
+   * @param isViewing - `true` if the user's current view is the voice server.
+   */
+  setViewingVoiceServer(isViewing: boolean): void {
+    this._isViewingVoiceServer.set(isViewing);
+  }
+
+  /**
+   * Compare the given server ID to the voice session's server and
+   * update the {@link isViewingVoiceServer} flag accordingly.
+   *
+   * @param currentServerId - ID of the server the user is currently viewing.
+   */
+  checkCurrentRoute(currentServerId: string | null): void {
+    this._isViewingVoiceServer.set(
+      isViewingVoiceSessionServer(this._voiceSession(), currentServerId)
+    );
+  }
+
+  /**
+   * Navigate the user back to the voice-connected server by
+   * dispatching a `viewServer` action.
+   */
+  navigateToVoiceServer(): void {
+    const session = this._voiceSession();
+
+    if (!session)
+      return;
+
+    this.store.dispatch(
+      RoomsActions.viewServer({
+        room: buildVoiceSessionRoom(session)
+      })
+    );
+
+    this._isViewingVoiceServer.set(true);
+  }
+
+  /**
+   * Return the server ID of the active voice session, or `null`
+   * if the user is not in a voice channel.
+   */
+  getVoiceServerId(): string | null {
+    return this._voiceSession()?.serverId ?? null;
+  }
+}

src/app/domains/voice-session/application/voice-workspace.service.ts

@@ -0,0 +1,131 @@
+/* eslint-disable @typescript-eslint/member-ordering */
+import {
+  Injectable,
+  computed,
+  effect,
+  inject,
+  signal
+} from '@angular/core';
+
+import { VoiceSessionFacade } from './voice-session.facade';
+
+export type VoiceWorkspaceMode = 'hidden' | 'expanded' | 'minimized';
+
+export interface VoiceWorkspacePosition {
+  left: number;
+  top: number;
+}
+
+const DEFAULT_MINI_WINDOW_POSITION: VoiceWorkspacePosition = {
+  left: 24,
+  top: 24
+};
+
+@Injectable({ providedIn: 'root' })
+export class VoiceWorkspaceService {
+  private readonly voiceSession = inject(VoiceSessionFacade);
+
+  private readonly _mode = signal<VoiceWorkspaceMode>('hidden');
+  private readonly _focusedStreamId = signal<string | null>(null);
+  private readonly _connectRemoteShares = signal(false);
+  private readonly _miniWindowPosition = signal<VoiceWorkspacePosition>(
+    DEFAULT_MINI_WINDOW_POSITION
+  );
+  private readonly _hasCustomMiniWindowPosition = signal(false);
+
+  readonly mode = computed<VoiceWorkspaceMode>(() => {
+    if (!this.voiceSession.voiceSession() || !this.voiceSession.isViewingVoiceServer()) {
+      return 'hidden';
+    }
+
+    return this._mode();
+  });
+
+  readonly isExpanded = computed(() => this.mode() === 'expanded');
+  readonly isMinimized = computed(() => this.mode() === 'minimized');
+  readonly isVisible = computed(() => this.mode() !== 'hidden');
+  readonly focusedStreamId = computed(() => this._focusedStreamId());
+  readonly shouldConnectRemoteShares = computed(
+    () => this.isVisible() && this._connectRemoteShares()
+  );
+  readonly miniWindowPosition = computed(() => this._miniWindowPosition());
+  readonly hasCustomMiniWindowPosition = computed(() => this._hasCustomMiniWindowPosition());
+
+  constructor() {
+    effect(
+      () => {
+        if (this.voiceSession.voiceSession()) {
+          return;
+        }
+
+        this.reset();
+      },
+      { allowSignalWrites: true }
+    );
+  }
+
+  open(
+    focusedStreamId: string | null = null,
+    options?: { connectRemoteShares?: boolean }
+  ): void {
+    if (!this.voiceSession.voiceSession()) {
+      return;
+    }
+
+    if (options && Object.prototype.hasOwnProperty.call(options, 'connectRemoteShares')) {
+      this._connectRemoteShares.set(options.connectRemoteShares === true);
+    }
+
+    this._focusedStreamId.set(focusedStreamId);
+    this._mode.set('expanded');
+  }
+
+  focusStream(streamId: string, options?: { connectRemoteShares?: boolean }): void {
+    this.open(streamId, options);
+  }
+
+  minimize(): void {
+    if (!this.voiceSession.voiceSession()) {
+      return;
+    }
+
+    this._mode.set('minimized');
+  }
+
+  restore(): void {
+    this.open(this._focusedStreamId());
+  }
+
+  close(): void {
+    this._mode.set('hidden');
+    this._connectRemoteShares.set(false);
+  }
+
+  showChat(): void {
+    if (this._mode() === 'expanded') {
+      this._mode.set('hidden');
+      this._connectRemoteShares.set(false);
+    }
+  }
+
+  clearFocusedStream(): void {
+    this._focusedStreamId.set(null);
+  }
+
+  setMiniWindowPosition(position: VoiceWorkspacePosition, markCustom = true): void {
+    this._miniWindowPosition.set(position);
+    this._hasCustomMiniWindowPosition.set(markCustom);
+  }
+
+  resetMiniWindowPosition(): void {
+    this._miniWindowPosition.set(DEFAULT_MINI_WINDOW_POSITION);
+    this._hasCustomMiniWindowPosition.set(false);
+  }
+
+  reset(): void {
+    this._mode.set('hidden');
+    this._focusedStreamId.set(null);
+    this._connectRemoteShares.set(false);
+    this.resetMiniWindowPosition();
+  }
+}

src/app/domains/voice-session/domain/voice-session.logic.ts

@@ -0,0 +1,23 @@
+import type { Room } from '../../../core/models';
+import type { VoiceSessionInfo } from './voice-session.models';
+
+export function isViewingVoiceSessionServer(
+  session: VoiceSessionInfo | null,
+  currentServerId: string | null
+): boolean {
+  return !session || currentServerId === session.serverId;
+}
+
+export function buildVoiceSessionRoom(session: VoiceSessionInfo): Room {
+  return {
+    id: session.serverId,
+    name: session.serverName,
+    description: session.serverDescription,
+    hostId: '',
+    isPrivate: false,
+    createdAt: 0,
+    userCount: 0,
+    maxUsers: 50,
+    icon: session.serverIcon
+  };
+}

src/app/domains/voice-session/domain/voice-session.models.ts

@@ -0,0 +1,21 @@
+/**
+ * Snapshot of an active voice session, retained so that floating
+ * voice controls can display the connection details when the user
+ * navigates away from the server view.
+ */
+export interface VoiceSessionInfo {
+  /** Unique server identifier. */
+  serverId: string;
+  /** Display name of the server. */
+  serverName: string;
+  /** Room/channel ID within the server. */
+  roomId: string;
+  /** Display name of the room/channel. */
+  roomName: string;
+  /** Optional server icon (data-URL or remote URL). */
+  serverIcon?: string;
+  /** Optional server description. */
+  serverDescription?: string;
+  /** Angular route path to navigate back to the server. */
+  serverRoute: string;
+}

src/app/domains/voice-session/index.ts

@@ -0,0 +1,4 @@
+export * from './application/voice-session.facade';
+export * from './application/voice-workspace.service';
+export * from './domain/voice-session.models';
+export * from './infrastructure/voice-settings.storage';

src/app/domains/voice-session/infrastructure/voice-settings.storage.ts

@@ -0,0 +1,105 @@
+import { STORAGE_KEY_VOICE_SETTINGS } from '../../../core/constants';
+import { LatencyProfile } from '../../voice-connection/domain/voice-connection.models';
+import { DEFAULT_SCREEN_SHARE_QUALITY, ScreenShareQuality } from '../../screen-share/domain/screen-share.config';
+
+const LATENCY_PROFILES: LatencyProfile[] = [
+  'low',
+  'balanced',
+  'high'
+];
+const SCREEN_SHARE_QUALITIES: ScreenShareQuality[] = [
+  'performance',
+  'balanced',
+  'high-fps',
+  'quality'
+];
+
+export interface VoiceSettings {
+  inputDevice: string;
+  outputDevice: string;
+  inputVolume: number;
+  outputVolume: number;
+  audioBitrate: number;
+  latencyProfile: LatencyProfile;
+  includeSystemAudio: boolean;
+  noiseReduction: boolean;
+  screenShareQuality: ScreenShareQuality;
+  askScreenShareQuality: boolean;
+}
+
+export const DEFAULT_VOICE_SETTINGS: VoiceSettings = {
+  inputDevice: '',
+  outputDevice: '',
+  inputVolume: 100,
+  outputVolume: 100,
+  audioBitrate: 96,
+  latencyProfile: 'balanced',
+  includeSystemAudio: false,
+  noiseReduction: true,
+  screenShareQuality: DEFAULT_SCREEN_SHARE_QUALITY,
+  askScreenShareQuality: true
+};
+
+export function loadVoiceSettingsFromStorage(): VoiceSettings {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY_VOICE_SETTINGS);
+
+    if (!raw)
+      return { ...DEFAULT_VOICE_SETTINGS };
+
+    return normaliseVoiceSettings(JSON.parse(raw) as Partial<VoiceSettings>);
+  } catch {
+    return { ...DEFAULT_VOICE_SETTINGS };
+  }
+}
+
+export function saveVoiceSettingsToStorage(patch: Partial<VoiceSettings>): VoiceSettings {
+  const nextSettings = normaliseVoiceSettings({
+    ...loadVoiceSettingsFromStorage(),
+    ...patch
+  });
+
+  try {
+    localStorage.setItem(STORAGE_KEY_VOICE_SETTINGS, JSON.stringify(nextSettings));
+  } catch {}
+
+  return nextSettings;
+}
+
+function normaliseVoiceSettings(raw: Partial<VoiceSettings>): VoiceSettings {
+  return {
+    inputDevice: typeof raw.inputDevice === 'string' ? raw.inputDevice : DEFAULT_VOICE_SETTINGS.inputDevice,
+    outputDevice: typeof raw.outputDevice === 'string' ? raw.outputDevice : DEFAULT_VOICE_SETTINGS.outputDevice,
+    inputVolume: clampNumber(raw.inputVolume, 0, 100, DEFAULT_VOICE_SETTINGS.inputVolume),
+    outputVolume: clampNumber(raw.outputVolume, 0, 100, DEFAULT_VOICE_SETTINGS.outputVolume),
+    audioBitrate: clampNumber(raw.audioBitrate, 32, 256, DEFAULT_VOICE_SETTINGS.audioBitrate),
+    latencyProfile: LATENCY_PROFILES.includes(raw.latencyProfile as LatencyProfile)
+      ? raw.latencyProfile as LatencyProfile
+      : DEFAULT_VOICE_SETTINGS.latencyProfile,
+    includeSystemAudio: typeof raw.includeSystemAudio === 'boolean'
+      ? raw.includeSystemAudio
+      : DEFAULT_VOICE_SETTINGS.includeSystemAudio,
+    noiseReduction: typeof raw.noiseReduction === 'boolean'
+      ? raw.noiseReduction
+      : DEFAULT_VOICE_SETTINGS.noiseReduction,
+    screenShareQuality: SCREEN_SHARE_QUALITIES.includes(raw.screenShareQuality as ScreenShareQuality)
+      ? raw.screenShareQuality as ScreenShareQuality
+      : DEFAULT_VOICE_SETTINGS.screenShareQuality,
+    askScreenShareQuality: typeof raw.askScreenShareQuality === 'boolean'
+      ? raw.askScreenShareQuality
+      : DEFAULT_VOICE_SETTINGS.askScreenShareQuality
+  };
+}
+
+function clampNumber(
+  value: unknown,
+  min: number,
+  max: number,
+  fallback: number
+): number {
+  if (typeof value !== 'number' || Number.isNaN(value)) {
+    return fallback;
+  }
+
+  return Math.max(min, Math.min(max, value));
+}