@chat21/chat21-web-widget 5.1.33 → 5.1.34-rc1

package/src/app/providers/global-settings.service.ts

@@ -6,7 +6,6 @@ import { BehaviorSubject, Observable } from 'rxjs';
 import { Globals } from '../utils/globals';
 import { convertColorToRGBA, detectIfIsMobile, getImageUrlThumb, getParameterByName, stringToBoolean, stringToNumber } from '../utils/utils';
 
-import { TemplateBindingParseResult } from '@angular/compiler';
 import { AppStorageService } from '../../chat21-core/providers/abstract/app-storage.service';
 import { LoggerService } from '../../chat21-core/providers/abstract/logger.service';
 import { LoggerInstance } from '../../chat21-core/providers/logger/loggerInstance';
@@ -67,6 +66,8 @@ export class GlobalSettingsService {
         this.globals.logLevel = this.appConfigService.getConfig().logLevel
         /**SET PERSISTENCE parameter */
         this.globals.persistence = this.appConfigService.getConfig().authPersistence
+        /**SET CLOSE CHAT IN CONVERSATION parameter */
+        this.globals.closeChatInConversation = this.appConfigService.getConfig().closeChatInConversation;
 
         // ------------------------------- //
         /** LOAD PARAMETERS FROM SERVER
@@ -339,6 +340,8 @@ export class GlobalSettingsService {
         this.setCssIframe();
         /** set main style */
         this.setStyle();
+        /** external CSS override: last stylesheet in document head (max cascade priority vs bundle) */
+        this.applyCustomCssOverrideFromGlobals();
         this.obsSettingsService.next(true);
     }
 
@@ -419,6 +422,28 @@ export class GlobalSettingsService {
 
         document.documentElement.style.setProperty('--font-family', family);
     }
+
+    /**
+     * Loads `globals.cssSource` (set only from tiledeskSettings) as the last stylesheet in head
+     * so rules with the same specificity override local / bundled CSS.
+     */
+    private applyCustomCssOverrideFromGlobals(): void {
+        const id = 'tiledesk-widget-css-override';
+        document.getElementById(id)?.remove();
+
+        const href = (this.globals.cssSource || '').trim();
+        console.log('href', href);
+        if (!href) {
+            return;
+        }
+
+        const link = document.createElement('link');
+        link.id = id;
+        link.rel = 'stylesheet';
+        link.href = href;
+        link.setAttribute('data-tiledesk-css-override', 'true');
+        document.head.appendChild(link);
+    }
     /**
      * A: setVariablesFromService
      */
@@ -573,6 +598,9 @@ export class GlobalSettingsService {
                     if (variables.hasOwnProperty('allowedUploadExtentions')) {
                         globals['fileUploadAccept'] = variables['allowedUploadExtentions'];
                     }
+                    if(variables.hasOwnProperty('showAudioStreamFooterButton')) {
+                        globals['showAudioStreamFooterButton'] = variables['showAudioStreamFooterButton'];
+                    }
                     
                 }
             }
@@ -639,6 +667,11 @@ export class GlobalSettingsService {
         let TEMP: any;
         const tiledeskSettings = windowContext['tiledeskSettings'];
         // this.logger.debug('[GLOBAL-SET] setVariablesFromSettings > tiledeskSettings: ', tiledeskSettings);
+        /** css override URL: solo tiledeskSettings, mai da URL / query params */
+        TEMP = tiledeskSettings['cssSource'];
+        if (TEMP !== undefined) {
+            globals.cssSource = TEMP;
+        }
         TEMP = tiledeskSettings['tenant'];
         // this.logger.debug('[GLOBAL-SET] setVariablesFromSettings >  tenant:: ', TEMP);
         if (TEMP !== undefined) {
@@ -702,7 +735,7 @@ export class GlobalSettingsService {
         }
         TEMP = tiledeskSettings['lang'];
         // this.logger.debug('[GLOBAL-SET] setVariablesFromSettings > lang:: ', TEMP);
-        if (TemplateBindingParseResult) {
+        if (TEMP !== undefined) {
             globals.lang = TEMP;
             // globals.setParameter('lang', TEMP);
         }
@@ -919,6 +952,14 @@ export class GlobalSettingsService {
         if (TEMP !== undefined) {
             globals.soundEnabled = TEMP;
         }
+        TEMP = tiledeskSettings['keyboardSoundVolume'];
+        if (TEMP !== undefined) {
+            globals.keyboardSoundVolume = +TEMP;
+        }
+        TEMP = tiledeskSettings['keyboardSoundFile'];
+        if (TEMP !== undefined) {
+            globals.keyboardSoundFile = TEMP;
+        }
         TEMP = tiledeskSettings['openExternalLinkButton'];
         // this.logger.debug('[GLOBAL-SET] setVariablesFromSettings > openExternalLinkButton:: ', TEMP]);
         if (TEMP !== undefined) {
@@ -1125,11 +1166,22 @@ export class GlobalSettingsService {
         if (TEMP !== undefined) {
             globals.showAudioRecorderFooterButton = (TEMP === true) ? true : false;
         }
+        TEMP = tiledeskSettings['showAudioStreamFooterButton'];
+        // this.logger.debug('[GLOBAL-SET] setVariablesFromSettings > showAudioStreamFooterButton:: ', TEMP]);
+        if (TEMP !== undefined) {
+            globals.showAudioStreamFooterButton = (TEMP === true) ? true : false;
+        }
         TEMP = tiledeskSettings['size'];
         // this.logger.debug('[GLOBAL-SET] setVariablesFromSettings > size:: ', TEMP]);
         if (TEMP !== undefined) {
             globals.size = TEMP;
         } 
+
+        TEMP = tiledeskSettings['closeChatInConversation'];
+        // this.logger.debug('[GLOBAL-SET] setVariablesFromSettings > closeChatInConversation:: ', TEMP]);
+        if (TEMP !== undefined) {
+            globals.closeChatInConversation = (TEMP === true) ? true : false;
+        }
     }
 
     /**
@@ -1297,6 +1349,14 @@ export class GlobalSettingsService {
         if (TEMP !== null) {
             this.globals.soundEnabled = TEMP;
         }
+        TEMP = el.nativeElement.getAttribute('keyboardSoundVolume');
+        if (TEMP !== null) {
+            this.globals.keyboardSoundVolume = +TEMP;
+        }
+        TEMP = el.nativeElement.getAttribute('keyboardSoundFile');
+        if (TEMP !== null) {
+            this.globals.keyboardSoundFile = TEMP;
+        }
         TEMP = el.nativeElement.getAttribute('openExternalLinkButton');
         if (TEMP !== null) {
             this.globals.openExternalLinkButton = TEMP;
@@ -1696,6 +1756,16 @@ export class GlobalSettingsService {
             globals.soundEnabled = stringToBoolean(TEMP); 
         }
 
+        TEMP = getParameterByName(windowContext, 'tiledesk_keyboardSoundVolume');
+        if (TEMP) {
+            globals.keyboardSoundVolume = +TEMP;
+        }
+
+        TEMP = getParameterByName(windowContext, 'tiledesk_keyboardSoundFile');
+        if (TEMP) {
+            globals.keyboardSoundFile = TEMP;
+        }
+
         TEMP = getParameterByName(windowContext, 'tiledesk_openExternalLinkButton');
         if (TEMP) {
             globals.openExternalLinkButton = stringToBoolean(TEMP); 
@@ -1867,6 +1937,11 @@ export class GlobalSettingsService {
             globals.showAttachmentFooterButton = stringToBoolean(TEMP);
         }
 
+        TEMP = getParameterByName(windowContext, 'tiledesk_showAudioStreamFooterButton');
+        if (TEMP) {
+            globals.showAudioStreamFooterButton = stringToBoolean(TEMP);
+        }
+
         TEMP = getParameterByName(windowContext, 'tiledesk_showEmojiFooterButton');
         if (TEMP) {
             globals.showEmojiFooterButton = stringToBoolean(TEMP);
@@ -1876,6 +1951,11 @@ export class GlobalSettingsService {
         if (TEMP) {
             globals.size = TEMP;
         }
+
+        TEMP = getParameterByName(windowContext, 'tiledesk_closeChatInConversation');
+        if (TEMP) {
+            globals.closeChatInConversation = stringToBoolean(TEMP);
+        }
         
     }
 

package/src/app/providers/json-sources-parser.service.ts

@@ -0,0 +1,175 @@
+import { Injectable } from '@angular/core';
+import { JSON_SOURCE_FIELD_TITLE, JSON_SOURCE_FIELD_URL } from 'src/chat21-core/utils/constants';
+import { UrlPreviewService } from 'src/app/providers/url-preview.service';
+import { extractUrlsFromText } from 'src/app/utils/url-utils';
+import { JsonSourceItem } from 'src/app/component/message/json-sources/json-sources.component';
+import { mergeJsonSourcesMissingFields } from 'src/app/utils/json-sources-utils';
+
+export type UrlPreviewMessage = {
+  type?: string; // "url_preview"
+  text?: string;
+};
+
+/**
+ * Parse and enrich "url_preview" messages into `JsonSourceItem[]`.
+ *
+ * Rules:
+ * - The payload is always read from `msg.text`, regardless of `activeMode`.
+ * - `msg.text` may be either:
+ *     - a JSON array of source objects (`{source_name, source_file_name, ...}`), or
+ *     - a plain string from which URLs are extracted (split by whitespace/punctuation).
+ * - After building the initial array, `url-preview` is called only for items that miss
+ *   title or description, and missing fields are merged in (never overwriting).
+ */
+@Injectable({ providedIn: 'root' })
+export class JsonSourcesParserService {
+  constructor(private urlPreviewService: UrlPreviewService) {}
+
+  /**
+   * Parse-only: returns sources immediately (no url-preview calls).
+   * Use this to render the list instantly, then call `enrichSources()` in background.
+   */
+  parseBaseFromMessage(messageLike?: any): JsonSourceItem[] | null {
+    const payload = this.getUrlPreviewPayload(messageLike);
+    return this.parseBaseJsonSources(payload);
+  }
+
+  /**
+   * Parse + enrich: kept for backward compatibility with older callers.
+   * If you need instant rendering, prefer `parseBaseFromMessage()` + `enrichSources()`.
+   */
+  /**
+   * Best-practice entrypoint for UI components:
+   * accepts a full `MessageModel`/message-like object, and supports url_preview payload
+   * living either on the root message OR inside `metadata` OR inside `attributes`.
+   */
+  async parseFromMessage(messageLike?: any): Promise<JsonSourceItem[] | null> {
+    const base = this.parseBaseFromMessage(messageLike);
+    return this.enrichSources(base);
+  }
+
+  async enrichSources(baseSources?: JsonSourceItem[] | null): Promise<JsonSourceItem[] | null> {
+    const sources = (baseSources || []).filter((s) => !!s?.link);
+    if (sources.length === 0) return baseSources || null;
+
+    // Only call url-preview for items missing the most relevant fields.
+    const incompleteUrls = sources
+      .filter(s => !!s.link && (!s.title || !s.description))
+      .map(s => s.link!)
+      .slice(0, 10);
+
+    if (incompleteUrls.length === 0) return sources;
+
+    const previews = await this.urlPreviewService.previewUrls(incompleteUrls);
+    const previewItems: JsonSourceItem[] = (previews || []).map(p => ({
+      link: p.url,
+      title: p.title || p.siteName || p.url,
+      description: p.description,
+      image: p.image,
+      favicon: p.favicon,
+      favicon_hd: p.favicon_hd
+    }));
+
+    if (previewItems.length === 0) return sources;
+    return mergeJsonSourcesMissingFields(sources, previewItems);
+  }
+
+  async parseJsonSources(msg?: UrlPreviewMessage | null): Promise<JsonSourceItem[] | null> {
+    const base = this.parseBaseJsonSources(msg);
+    return this.enrichSources(base);
+  }
+
+  private getUrlPreviewPayload(messageLike?: any): UrlPreviewMessage | null {
+    if (!messageLike) return null;
+    const candidates: any[] = [
+      messageLike,
+      (messageLike?.metadata && typeof messageLike.metadata === 'object') ? messageLike.metadata : null,
+      (messageLike?.attributes && typeof messageLike.attributes === 'object') ? messageLike.attributes : null
+    ].filter(Boolean);
+    return (candidates.find((c) => c?.type === 'url_preview') || null) as UrlPreviewMessage | null;
+  }
+
+  private parseBaseJsonSources(msg?: UrlPreviewMessage | null): JsonSourceItem[] | null {
+    if (!msg || msg.type !== 'url_preview') return null;
+
+    // Regardless of `activeMode`, the payload is always read from `msg.text`.
+    // It can be either a JSON array of source objects, or a plain string with URLs.
+    return this.isJsonArrayOfObjects(msg.text)
+      ? this.mapTextToSources(msg.text)
+      : this.mapListToSources(msg.text);
+  }
+
+  private mapListToSources(listValue?: string): JsonSourceItem[] | null {
+    const urls = extractUrlsFromText((listValue || '').toString(), 10);
+    return urls.length ? urls.map(u => ({ link: u, title: u })) : null;
+  }
+
+  private isJsonArrayOfObjects(text?: string): boolean {
+    if (!text) return false;
+    try {
+      const parsed = this.parseJsonLenient(text);
+      return Array.isArray(parsed) && parsed.some(it => it && typeof it === 'object' && !Array.isArray(it));
+    } catch {
+      return false;
+    }
+  }
+
+  private mapTextToSources(text?: string): JsonSourceItem[] | null {
+    if (!text) return null;
+    try {
+      const parsed = this.parseJsonLenient(text);
+      return this.mapSourcesArray(parsed);
+    } catch {
+      return null;
+    }
+  }
+
+  private mapSourcesArray(input: any): JsonSourceItem[] | null {
+    const arr = Array.isArray(input) ? input : null;
+    if (!arr || arr.length === 0) return null;
+    const mapped = arr
+      .filter((s: any) => s && typeof s === 'object' && typeof s[JSON_SOURCE_FIELD_URL] === 'string')
+      .map((s: any): JsonSourceItem | null => {
+        const rawUrl = (s[JSON_SOURCE_FIELD_URL] || '').toString().trim();
+        const normalized = extractUrlsFromText(rawUrl, 1)[0];
+        if (!normalized) return null;
+        return {
+          link: normalized,
+          title: (s[JSON_SOURCE_FIELD_TITLE] || rawUrl).toString(),
+          description: typeof s.source_description === 'string' ? s.source_description : undefined,
+          image: typeof s.source_image === 'string' ? s.source_image : undefined
+        };
+      })
+      .filter((x: JsonSourceItem | null): x is JsonSourceItem => !!x && !!x.link);
+    return mapped.length ? mapped : null;
+  }
+
+  private parseJsonLenient(input: string): any {
+    const trimmed = (input || '').trim();
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (typeof parsed === 'string') {
+        const inner = parsed.trim();
+        if ((inner.startsWith('[') && inner.endsWith(']')) || (inner.startsWith('{') && inner.endsWith('}'))) {
+          return this.parseJsonLenient(inner);
+        }
+      }
+      return parsed;
+    } catch {
+      const cleaned = trimmed
+        .replace(/^```(?:json)?\s*/i, '')
+        .replace(/```$/i, '')
+        .trim()
+        .replace(/,\s*([}\]])/g, '$1');
+      const parsed = JSON.parse(cleaned);
+      if (typeof parsed === 'string') {
+        const inner = parsed.trim();
+        if ((inner.startsWith('[') && inner.endsWith(']')) || (inner.startsWith('{') && inner.endsWith('}'))) {
+          return this.parseJsonLenient(inner);
+        }
+      }
+      return parsed;
+    }
+  }
+}
+

package/src/app/providers/translator.service.ts

@@ -234,12 +234,27 @@ export class TranslatorService {
     this._translate.use(lang);
     this.logger.debug(`[TRANSLATOR-SERV] »»»» initI18n - »»» loadRemoteTranslations ?`, environment.loadRemoteTranslations);
     this._translate.setTranslation(lang, data, true);
-    // if (environment.loadRemoteTranslations) {
-    //   // console.log(`»»»» initI18n - »»» remote translation `, data);
-    //   this._translate.setTranslation(lang, data, true);
-    // } else {
-    //   this._translate.setTranslation(lang, data, true);
-    // }
+    this.syncDocumentLang(lang);
+  }
+
+  /**
+   * Synchronize the document `<html lang="...">` attribute with the active i18n language
+   * (WCAG 3.1.1 Language of Page, EN 301 549 § 9.3.1.1).
+   *
+   * The widget runs inside its own iframe, so we update the document of that iframe.
+   * If the widget is also embedded in a parent page (Tiledesk launcher), the parent
+   * page already declares its own `lang`, which we intentionally leave untouched.
+   */
+  private syncDocumentLang(lang: string) {
+    if (!lang) { return; }
+    const normalized = lang.toLowerCase().substring(0, 2);
+    try {
+      if (typeof document !== 'undefined' && document.documentElement) {
+        document.documentElement.setAttribute('lang', normalized);
+      }
+    } catch (e) {
+      this.logger.warn('[TRANSLATOR-SERV] syncDocumentLang error', e);
+    }
   }
 
   /** */
@@ -302,6 +317,9 @@ export class TranslatorService {
       'CLOSED',
       'LABEL_PREVIEW',
       'MAX_ATTACHMENT',
+      'EMOJI',
+      'BUTTON_OPEN_CHAT',
+      'MAX_ATTACHMENT_ERROR',
       'EMOJI'
     ];
 
@@ -358,7 +376,9 @@ export class TranslatorService {
       globals.LABEL_PREVIEW = res['LABEL_PREVIEW']
       globals.LABEL_ERROR_FIELD_REQUIRED= res['LABEL_ERROR_FIELD_REQUIRED']
       globals.MAX_ATTACHMENT = res['MAX_ATTACHMENT']
+      globals.MAX_ATTACHMENT_ERROR = res['MAX_ATTACHMENT_ERROR']
       globals.EMOJI = res['EMOJI']
+      globals.BUTTON_OPEN_CHAT = res['BUTTON_OPEN_CHAT']
       
       
       if(globals.WELCOME_TITLE === 'WELLCOME_TITLE') globals.WELCOME_TITLE = res['WELCOME_TITLE']

package/src/app/providers/tts-audio-playback-coordinator.service.spec.ts

@@ -0,0 +1,117 @@
+import { TestBed } from '@angular/core/testing';
+import { TtsAudioPlaybackCoordinator } from './tts-audio-playback-coordinator.service';
+
+describe('TtsAudioPlaybackCoordinator', () => {
+  let coordinator: TtsAudioPlaybackCoordinator;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({ providers: [TtsAudioPlaybackCoordinator] });
+    coordinator = TestBed.inject(TtsAudioPlaybackCoordinator);
+  });
+
+  // ── Basic lifecycle ───────────────────────────────────────────────────────
+
+  it('should start playing immediately when nothing is active', () => {
+    const start = jasmine.createSpy('start');
+    coordinator.requestStart('msg-1', start);
+    expect(start).toHaveBeenCalledTimes(1);
+  });
+
+  it('isTTSPlaying$ should be true while playing and false after release', () => {
+    const states: boolean[] = [];
+    coordinator.isTTSPlaying$.subscribe((v) => states.push(v));
+
+    coordinator.requestStart('msg-1', () => {});
+    coordinator.releaseIfCurrent('msg-1');
+
+    expect(states).toEqual([false, true, false]);
+  });
+
+  it('stopAll clears the queue, sets playing=false, and emits stopAllPlayback$', () => {
+    const stopNextSpy = spyOn((coordinator as any)._stopAll$, 'next').and.callThrough();
+
+    coordinator.requestStart('msg-1', () => {});
+    coordinator.stopAll();
+
+    expect(stopNextSpy).toHaveBeenCalledTimes(1);
+    const states: boolean[] = [];
+    coordinator.isTTSPlaying$.subscribe((v) => states.push(v));
+    expect(states).toEqual([false]);
+  });
+
+  // ── Preemption tests (SPEC-002) ───────────────────────────────────────────
+
+  it('requestStart while playing preempts old owner: new start() is called immediately', () => {
+    const start1 = jasmine.createSpy('start1');
+    const start2 = jasmine.createSpy('start2');
+
+    coordinator.requestStart('msg-1', start1);
+    coordinator.requestStart('msg-2', start2);
+
+    expect(start1).toHaveBeenCalledTimes(1);
+    expect(start2).toHaveBeenCalledTimes(1); // started immediately, not queued
+  });
+
+  it('preemptPlayback$ emits evicted ownerId only (not the new owner)', () => {
+    const preempted: string[] = [];
+    coordinator.preemptPlayback$.subscribe((id) => preempted.push(id));
+
+    coordinator.requestStart('msg-1', () => {});
+    coordinator.requestStart('msg-2', () => {}); // preempts msg-1
+
+    expect(preempted).toEqual(['msg-1']);
+  });
+
+  it('preemptPlayback$ does NOT emit the new owner id', () => {
+    const preempted: string[] = [];
+    coordinator.preemptPlayback$.subscribe((id) => preempted.push(id));
+
+    coordinator.requestStart('msg-1', () => {});
+    coordinator.requestStart('msg-2', () => {});
+
+    expect(preempted).not.toContain('msg-2');
+  });
+
+  it('isTTSPlaying$ stays true after preemption until new owner releases', () => {
+    const states: boolean[] = [];
+    coordinator.isTTSPlaying$.subscribe((v) => states.push(v));
+
+    coordinator.requestStart('msg-1', () => {});   // true
+    coordinator.requestStart('msg-2', () => {});   // still true (preemption, new owner active)
+    coordinator.releaseIfCurrent('msg-2');          // false
+
+    expect(states).toEqual([false, true, false]);
+  });
+
+  it('releaseIfCurrent for an evicted owner is a no-op', () => {
+    const states: boolean[] = [];
+    coordinator.isTTSPlaying$.subscribe((v) => states.push(v));
+
+    coordinator.requestStart('msg-1', () => {});
+    coordinator.requestStart('msg-2', () => {}); // msg-1 evicted
+
+    // Old owner calls release after being preempted — should not affect playing state
+    coordinator.releaseIfCurrent('msg-1');
+
+    expect(states).toEqual([false, true]); // no extra false emission
+  });
+
+  it('chain of preemptions: each new requestStart immediately evicts the current owner', () => {
+    const preempted: string[] = [];
+    coordinator.preemptPlayback$.subscribe((id) => preempted.push(id));
+
+    coordinator.requestStart('msg-1', () => {});
+    coordinator.requestStart('msg-2', () => {});
+    coordinator.requestStart('msg-3', () => {});
+
+    expect(preempted).toEqual(['msg-1', 'msg-2']);
+  });
+
+  it('requestStart is idempotent for the current owner', () => {
+    const start = jasmine.createSpy('start');
+    coordinator.requestStart('msg-1', start);
+    coordinator.requestStart('msg-1', start); // same owner — should be ignored
+
+    expect(start).toHaveBeenCalledTimes(1);
+  });
+});

package/src/app/providers/tts-audio-playback-coordinator.service.ts

@@ -0,0 +1,109 @@
+import { Injectable } from '@angular/core';
+import { BehaviorSubject, Observable, Subject } from 'rxjs';
+
+/**
+ * Garantisce un solo messaggio TTS in riproduzione alla volta.
+ * Quando arriva un nuovo messaggio TTS mentre un altro è in corso, quello vecchio viene
+ * interrotto immediatamente (preemption) e il nuovo parte subito.
+ */
+@Injectable({ providedIn: 'root' })
+export class TtsAudioPlaybackCoordinator {
+  private currentOwnerId: string | null = null;
+  private readonly queue: Array<{ ownerId: string; start: () => void }> = [];
+
+  /** Emits true while any TTS is playing or queued; false when the queue is fully drained. */
+  private readonly _isTTSPlaying$ = new BehaviorSubject<boolean>(false);
+  readonly isTTSPlaying$ = this._isTTSPlaying$.asObservable();
+
+  /** Emits once when stopAll() is called — signals every AudioSyncComponent to abort immediately. */
+  private readonly _stopAll$ = new Subject<void>();
+  readonly stopAllPlayback$: Observable<void> = this._stopAll$.asObservable();
+
+  /**
+   * Emits the ownerId of the component being preempted (stopped mid-playback by a newer message).
+   * Only the component whose ownerId matches should react — unlike stopAll$ which targets everyone.
+   */
+  private readonly _preemptCurrent$ = new Subject<string>();
+  readonly preemptPlayback$: Observable<string> = this._preemptCurrent$.asObservable();
+
+  /**
+   * Richiede l'avvio della riproduzione TTS per `ownerId`.
+   * Se un altro TTS è già in corso, viene interrotto immediatamente (preemption) e
+   * `ownerId` parte subito. Qualsiasi coda pendente viene svuotata.
+   */
+  requestStart(ownerId: string, start: () => void): void {
+    const id = (ownerId || '').trim();
+    if (!id) {
+      return;
+    }
+    if (this.currentOwnerId === id) {
+      return;
+    }
+
+    if (this.currentOwnerId) {
+      // Preempt: signal only the evicted owner to stop (not a broadcast stopAll).
+      // This avoids stopping the component that is about to start playing.
+      const evicted = this.currentOwnerId;
+      this.queue.length = 0;
+      this.currentOwnerId = null;
+      this._preemptCurrent$.next(evicted);
+    } else {
+      this.queue.length = 0;
+    }
+
+    this.currentOwnerId = id;
+    if (!this._isTTSPlaying$.getValue()) {
+      this._isTTSPlaying$.next(true);
+    }
+    try {
+      start();
+    } catch {
+      this.releaseIfCurrent(id);
+    }
+  }
+
+  /** Chiamare a fine riproduzione naturale (`ended`) se questo messaggio era ancora “attivo”. */
+  releaseIfCurrent(ownerId: string): void {
+    const id = (ownerId || '').trim();
+    if (!id) {
+      return;
+    }
+    if (this.currentOwnerId !== id) {
+      // Se era in coda, rimuovilo.
+      const idx = this.queue.findIndex((j) => j.ownerId === id);
+      if (idx !== -1) {
+        this.queue.splice(idx, 1);
+      }
+      return;
+    }
+
+    this.currentOwnerId = null;
+    const next = this.queue.shift();
+    if (!next) {
+      this._isTTSPlaying$.next(false);
+      return;
+    }
+    this.currentOwnerId = next.ownerId;
+    try {
+      next.start();
+    } catch {
+      this.releaseIfCurrent(next.ownerId);
+    }
+  }
+
+  /** Distruzione componente o stop esplicito. */
+  release(ownerId: string): void {
+    this.releaseIfCurrent(ownerId);
+  }
+
+  /**
+   * Stops all TTS playback immediately and clears the queue.
+   * Broadcasts on stopAllPlayback$ so every AudioSyncComponent can abort its stream and reveal all text.
+   */
+  stopAll(): void {
+    this.queue.length = 0;
+    this.currentOwnerId = null;
+    this._isTTSPlaying$.next(false);
+    this._stopAll$.next();
+  }
+}