@pie-players/pie-section-player 0.3.5 → 0.3.8

package/README.md

@@ -148,6 +148,62 @@ function canAdvance() {
 }
 ```
 
+If you already have a `ToolkitCoordinator` from `toolkit-ready`, prefer helper subscriptions for host logic:
+
+```ts
+const unsubscribeItem = coordinator.subscribeItemEvents({
+  sectionId,
+  attemptId,
+  listener: (event: any) => {
+    // item-scoped stream
+  },
+});
+
+const unsubscribeSection = coordinator.subscribeSectionLifecycleEvents({
+  sectionId,
+  attemptId,
+  listener: (event: any) => {
+    // section-loading-complete / section-items-complete-changed / section-error / section-navigation-change
+  },
+});
+```
+
+Use `subscribeSectionEvents(...)` only for advanced mixed filtering requirements.
+
+### Item session management
+
+Section session data can be managed either through persistence hooks or directly through the controller API.
+
+```ts
+const host = document.querySelector("pie-section-player-splitpane") as any;
+const controller = await host.waitForSectionController?.(5000);
+
+// Read current section session snapshot.
+const currentSession = controller?.getSession?.();
+
+// Replace section session state (resume from backend snapshot).
+await controller?.applySession?.({
+  currentItemIndex: 0,
+  visitedItemIdentifiers: ["q1"],
+  itemSessions: {
+    q1: {
+      itemIdentifier: "q1",
+      pieSessionId: "q1-session",
+      session: { id: "q1-session", data: [{ id: "choice", value: "a" }] }
+    }
+  }
+}, { mode: "replace" });
+
+// Update a single item session directly.
+await controller?.updateItemSession?.("q1", {
+  session: { id: "q1-session", data: [{ id: "choice", value: "b" }] },
+  complete: true,
+});
+```
+
+The same controller snapshot is what the persistence strategy saves/loads.
+When a controller is reused for the same `sectionId`/`attemptId`, `updateInput()` refreshes composition input while preserving in-memory section session data.
+
 ## Exports
 
 Published exports are intentionally minimal:

package/dist/controllers/SectionController.d.ts

@@ -1,13 +1,12 @@
 import { TestAttemptSession } from '@pie-players/pie-assessment-toolkit';
-import { SectionControllerContext, SectionControllerHandle, SectionControllerPersistenceStrategy, SectionControllerRuntimeState, SectionControllerSessionState } from './toolkit-section-contracts.js';
+import { SectionControllerHandle, SectionSessionPersistenceConfig, SectionControllerRuntimeState, SectionControllerSessionState } from './toolkit-section-contracts.js';
 import { ItemEntity } from '@pie-players/pie-players-shared';
 import { NavigationResult, SectionControllerChangeListener, SectionCompositionModel, SectionNavigationState, SectionViewModel, SessionChangedResult } from './types.js';
 export declare class SectionController implements SectionControllerHandle {
     private readonly contentService;
     private readonly sessionService;
     private readonly itemNavigationService;
-    private persistenceStrategy;
-    private persistenceContext;
+    private sessionPersistence;
     private state;
     private readonly listeners;
     private readonly trackedRenderables;
@@ -23,8 +22,7 @@ export declare class SectionController implements SectionControllerHandle {
     subscribe(listener: SectionControllerChangeListener): () => void;
     initialize(input?: unknown): Promise<void>;
     updateInput(input?: unknown): Promise<void>;
-    setPersistenceStrategy(strategy: SectionControllerPersistenceStrategy): Promise<void>;
-    setPersistenceContext(context: SectionControllerContext): void;
+    configureSessionPersistence(config: SectionSessionPersistenceConfig): void;
     hydrate(): Promise<void>;
     persist(): Promise<void>;
     dispose(): void;
@@ -47,18 +45,21 @@ export declare class SectionController implements SectionControllerHandle {
      * Use this for serializing/restoring section session state across reloads.
      * This is intentionally compact and not a full runtime diagnostics view.
      */
-    getSessionState(): SectionControllerSessionState | null;
+    getSession(): SectionControllerSessionState | null;
     private getSectionItemIdentifiers;
     /**
      * Runtime/debugger shape scoped to the current section.
      * Use this for widgets that need a section-scoped live snapshot (debug panels, diagnostics).
-     * Unlike getSessionState(), this is optimized for runtime introspection, not host persistence.
+     * Unlike getSession(), this is optimized for runtime introspection, not host persistence.
      */
     getRuntimeState(): SectionControllerRuntimeState | null;
     getCurrentItem(): ItemEntity | null;
     getCurrentItemSession(): unknown;
     getNavigationState(isLoading?: boolean): SectionNavigationState;
-    handleItemSessionChanged(itemId: string, sessionDetail: any): SessionChangedResult | null;
+    updateItemSession(itemId: string, sessionDetail: any): SessionChangedResult | null;
+    applySession(session: SectionControllerSessionState | null, options?: {
+        mode?: "replace" | "merge";
+    }): Promise<void>;
     /**
      * Move between items inside the current section only.
      * Cross-section navigation belongs to the higher-level assessment player.

package/dist/controllers/SectionController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SectionController.d.ts","sourceRoot":"","sources":["../../src/controllers/SectionController.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SectionController.d.ts","sourceRoot":"","sources":["../../src/controllers/SectionController.ts"],"names":[],"mappings":"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"}

package/dist/controllers/toolkit-section-contracts.d.ts

@@ -1,5 +1,5 @@
 import { ToolkitCoordinator, SectionControllerHandle } from '@pie-players/pie-assessment-toolkit';
-export type { SectionControllerContext, SectionControllerEvent, SectionControllerEventType, SectionControllerHandle, SectionControllerKey, SectionControllerPersistenceStrategy, SectionControllerRuntimeState, SectionControllerSessionState, } from '@pie-players/pie-assessment-toolkit';
+export type { SectionControllerContext, SectionControllerEvent, SectionControllerEventType, SectionControllerHandle, SectionControllerKey, SectionSessionPersistenceConfig, SectionSessionPersistenceStrategy, SectionControllerRuntimeState, SectionControllerSessionState, } from '@pie-players/pie-assessment-toolkit';
 export type CoordinatorWithSectionControllers = ToolkitCoordinator & {
     getOrCreateSectionController(args: {
         sectionId: string;

package/dist/controllers/toolkit-section-contracts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toolkit-section-contracts.d.ts","sourceRoot":"","sources":["../../src/controllers/toolkit-section-contracts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAC9E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AACnF,YAAY,EACX,wBAAwB,EACxB,sBAAsB,EACtB,0BAA0B,EAC1B,uBAAuB,EACvB,oBAAoB,EACpB,oCAAoC,EACpC,6BAA6B,EAC7B,6BAA6B,GAC7B,MAAM,qCAAqC,CAAC;AAE7C,MAAM,MAAM,iCAAiC,GAAG,kBAAkB,GAAG;IACpE,4BAA4B,CAAC,IAAI,EAAE;QAClC,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,uBAAuB,EAAE,MACtB,uBAAuB,GACvB,OAAO,CAAC,uBAAuB,CAAC,CAAC;KACpC,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;IACrC,wBAAwB,CAAC,IAAI,EAAE;QAC9B,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,oBAAoB,CAAC,EAAE,OAAO,CAAC;QAC/B,gBAAgB,CAAC,EAAE,OAAO,CAAC;KAC3B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB,CAAC"}
+{"version":3,"file":"toolkit-section-contracts.d.ts","sourceRoot":"","sources":["../../src/controllers/toolkit-section-contracts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAC9E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AACnF,YAAY,EACX,wBAAwB,EACxB,sBAAsB,EACtB,0BAA0B,EAC1B,uBAAuB,EACvB,oBAAoB,EACpB,+BAA+B,EAC/B,iCAAiC,EACjC,6BAA6B,EAC7B,6BAA6B,GAC7B,MAAM,qCAAqC,CAAC;AAE7C,MAAM,MAAM,iCAAiC,GAAG,kBAAkB,GAAG;IACpE,4BAA4B,CAAC,IAAI,EAAE;QAClC,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,uBAAuB,EAAE,MACtB,uBAAuB,GACvB,OAAO,CAAC,uBAAuB,CAAC,CAAC;KACpC,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;IACrC,wBAAwB,CAAC,IAAI,EAAE;QAC9B,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,oBAAoB,CAAC,EAAE,OAAO,CAAC;QAC/B,gBAAgB,CAAC,EAAE,OAAO,CAAC;KAC3B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB,CAAC"}

package/dist/index-CGqExkh0-DYpgzOOU.js

@@ -0,0 +1,338 @@
+var v = Object.defineProperty, w = (i, t, e) => t in i ? v(i, t, { enumerable: !0, configurable: !0, writable: !0, value: e }) : i[t] = e, u = (i, t, e) => w(i, typeof t != "symbol" ? t + "" : t, e);
+const T = {
+  pie: 3e3,
+  custom: 3e3
+}, m = (i) => i.replace(/\/+$/, ""), f = (i) => i.transportMode === "custom" ? "custom" : i.transportMode === "pie" ? "pie" : i.provider === "custom" ? "custom" : "pie", y = (i, t) => i.endpointMode ? i.endpointMode : t === "custom" ? "rootPost" : "synthesizePath", S = (i, t) => i.endpointValidationMode ? i.endpointValidationMode : t === "custom" ? "none" : "voices", b = (i) => {
+  const t = i.providerOptions || {};
+  if (typeof t.speedRate == "string")
+    return t.speedRate;
+  const e = Number(i.rate ?? 1);
+  return !Number.isFinite(e) || e <= 0.95 ? "slow" : e >= 1.5 ? "fast" : "medium";
+}, A = (i) => {
+  const t = [];
+  let e = 0;
+  const s = i.split(`
+`).map((r) => r.trim()).filter(Boolean);
+  for (const r of s)
+    try {
+      const n = JSON.parse(r), h = typeof n.type == "string" ? n.type : "word", o = typeof n.time == "number" && Number.isFinite(n.time) ? n.time : 0, a = typeof n.value == "string" ? n.value : "", d = typeof n.start == "number" && Number.isFinite(n.start) ? n.start : null, p = typeof n.end == "number" && Number.isFinite(n.end) ? n.end : null, g = d ?? e, l = p ?? g + Math.max(1, a.length || String(n.value || "").length);
+      e = Math.max(l + 1, e), t.push({
+        time: o,
+        type: h,
+        start: g,
+        end: l,
+        value: a
+      });
+    } catch {
+    }
+  return t;
+}, k = {
+  id: "pie",
+  resolveSynthesisUrl: (i) => {
+    const t = y(i, "pie"), e = m(i.apiEndpoint);
+    return t === "rootPost" ? e : `${e}/synthesize`;
+  },
+  buildRequestBody: (i, t) => {
+    const e = t.providerOptions || {}, s = typeof t.engine == "string" ? t.engine : typeof e.engine == "string" ? e.engine : void 0, r = typeof e.sampleRate == "number" && Number.isFinite(e.sampleRate) ? e.sampleRate : void 0, n = e.format === "mp3" || e.format === "ogg" || e.format === "pcm" ? e.format : void 0, h = Array.isArray(e.speechMarkTypes) ? e.speechMarkTypes.filter((o) => o === "word" || o === "sentence" || o === "ssml") : void 0;
+    return {
+      text: i,
+      provider: t.provider || "polly",
+      voice: t.voice,
+      language: t.language,
+      rate: t.rate,
+      engine: s,
+      sampleRate: r,
+      format: n,
+      speechMarkTypes: h,
+      includeSpeechMarks: !0
+    };
+  },
+  parseResponse: async (i) => {
+    const t = await i.json();
+    return {
+      audio: {
+        kind: "base64",
+        data: t.audio,
+        contentType: t.contentType
+      },
+      speechMarks: Array.isArray(t.speechMarks) ? t.speechMarks : []
+    };
+  }
+}, R = {
+  id: "custom",
+  resolveSynthesisUrl: (i) => {
+    const t = y(i, "custom"), e = m(i.apiEndpoint);
+    return t === "synthesizePath" ? `${e}/synthesize` : e;
+  },
+  buildRequestBody: (i, t) => {
+    const e = t.providerOptions || {}, s = typeof e.lang_id == "string" ? e.lang_id : t.language || "en-US", r = typeof e.cache == "boolean" ? e.cache : !0;
+    return {
+      text: i,
+      speedRate: b(t),
+      lang_id: s,
+      cache: r
+    };
+  },
+  parseResponse: async (i, t, e, s) => {
+    const r = await i.json(), n = {};
+    if (t.includeAuthOnAssetFetch)
+      for (const [o, a] of Object.entries(e))
+        o.toLowerCase() === "authorization" && (n[o] = a);
+    let h = [];
+    if (typeof r.word == "string" && r.word.length > 0) {
+      const o = await fetch(r.word, {
+        headers: n,
+        signal: s
+      });
+      if (o.ok) {
+        const a = await o.text();
+        h = A(a);
+      }
+    }
+    return {
+      audio: {
+        kind: "url",
+        url: r.audioContent
+      },
+      speechMarks: h
+    };
+  }
+}, M = {
+  pie: k,
+  custom: R
+};
+class I {
+  constructor(t, e) {
+    u(this, "config"), u(this, "adapter"), u(this, "currentAudio", null), u(this, "pausedState", !1), u(this, "wordTimings", []), u(this, "highlightInterval", null), u(this, "intentionallyStopped", !1), u(this, "activeSynthesisController", null), u(this, "synthesisRunId", 0), u(this, "onWordBoundary"), this.config = t, this.adapter = e;
+  }
+  async speak(t) {
+    this.stop(), this.intentionallyStopped = !1;
+    const e = ++this.synthesisRunId, s = new AbortController();
+    this.activeSynthesisController = s;
+    const { audioUrl: r, wordTimings: n } = await this.synthesizeSpeech(t, s.signal, e);
+    if (e !== this.synthesisRunId) {
+      URL.revokeObjectURL(r);
+      return;
+    }
+    const h = this.config.rate || 1;
+    return this.wordTimings = n.map((o) => ({
+      ...o,
+      time: o.time / h
+    })), new Promise((o, a) => {
+      const d = new Audio(r);
+      this.currentAudio = d, this.config.rate && (d.playbackRate = Math.max(0.25, Math.min(4, this.config.rate))), this.config.volume !== void 0 && (d.volume = Math.max(0, Math.min(1, this.config.volume))), d.onplay = () => {
+        this.pausedState = !1, this.onWordBoundary && this.wordTimings.length > 0 && this.startWordHighlighting();
+      }, d.onended = () => {
+        this.stopWordHighlighting(), URL.revokeObjectURL(r), this.currentAudio = null, this.wordTimings = [], o();
+      }, d.onerror = (p) => {
+        this.stopWordHighlighting(), URL.revokeObjectURL(r), this.currentAudio = null, this.wordTimings = [], this.intentionallyStopped ? o() : a(new Error("Failed to play audio from server"));
+      }, d.onpause = () => {
+        this.stopWordHighlighting(), this.pausedState = !0;
+      }, d.play().catch(a);
+    });
+  }
+  /**
+   * Call server API to synthesize speech
+   */
+  async synthesizeSpeech(t, e, s) {
+    const r = {
+      "Content-Type": "application/json",
+      ...this.config.headers
+    };
+    this.config.authToken && (r.Authorization = `Bearer ${this.config.authToken}`);
+    const n = this.adapter.resolveSynthesisUrl(this.config), h = this.adapter.buildRequestBody(t, this.config), o = await fetch(n, {
+      method: "POST",
+      headers: r,
+      body: JSON.stringify(h),
+      signal: e
+    });
+    if (!o.ok) {
+      const l = await o.json().catch(() => ({})), c = l.message || l.error?.message || `Server returned ${o.status}`;
+      throw new Error(c);
+    }
+    const a = await this.adapter.parseResponse(o, this.config, r, e);
+    if (s !== this.synthesisRunId || e.aborted)
+      throw new Error("Synthesis superseded by a newer request");
+    let d;
+    if (a.audio.kind === "base64")
+      d = this.base64ToBlob(a.audio.data, a.audio.contentType);
+    else {
+      const l = {};
+      this.config.includeAuthOnAssetFetch && this.config.authToken && (l.Authorization = `Bearer ${this.config.authToken}`);
+      const c = await fetch(a.audio.url, {
+        headers: l,
+        signal: e
+      });
+      if (!c.ok)
+        throw new Error(`Failed to download synthesized audio (${c.status})`);
+      d = await c.blob();
+    }
+    const p = URL.createObjectURL(d), g = this.parseSpeechMarks(a.speechMarks);
+    return { audioUrl: p, wordTimings: g };
+  }
+  /**
+   * Convert base64 to Blob
+   */
+  base64ToBlob(t, e) {
+    const s = atob(t), r = new Array(s.length);
+    for (let h = 0; h < s.length; h++)
+      r[h] = s.charCodeAt(h);
+    const n = new Uint8Array(r);
+    return new Blob([n], { type: e });
+  }
+  /**
+   * Parse speech marks into word timings
+   */
+  parseSpeechMarks(t) {
+    return t.filter((e) => e.type === "word").map((e, s) => ({
+      time: e.time,
+      wordIndex: s,
+      charIndex: e.start,
+      length: e.end - e.start
+    }));
+  }
+  /**
+   * Start word highlighting synchronized with audio playback
+   */
+  startWordHighlighting() {
+    if (this.stopWordHighlighting(), !this.currentAudio || !this.onWordBoundary || this.wordTimings.length === 0) {
+      console.log("[ServerTTSProvider] Cannot start highlighting:", {
+        hasAudio: !!this.currentAudio,
+        hasCallback: !!this.onWordBoundary,
+        wordTimingsCount: this.wordTimings.length
+      });
+      return;
+    }
+    console.log("[ServerTTSProvider] Starting word highlighting with", this.wordTimings.length, "word timings"), console.log("[ServerTTSProvider] Playback rate:", this.currentAudio.playbackRate), console.log("[ServerTTSProvider] First 3 timings:", this.wordTimings.slice(0, 3));
+    let t = -1;
+    this.highlightInterval = window.setInterval(() => {
+      if (!this.currentAudio) {
+        this.stopWordHighlighting();
+        return;
+      }
+      const e = this.currentAudio.currentTime * 1e3;
+      for (let s = 0; s < this.wordTimings.length; s++) {
+        const r = this.wordTimings[s];
+        if (e >= r.time && s > t) {
+          this.onWordBoundary && (console.log("[ServerTTSProvider] Highlighting word at charIndex:", r.charIndex, "length:", r.length, "time:", r.time, "currentTime:", e), this.onWordBoundary("", r.charIndex, r.length)), t = s;
+          break;
+        }
+      }
+    }, 50);
+  }
+  /**
+   * Stop word highlighting
+   */
+  stopWordHighlighting() {
+    this.highlightInterval !== null && (clearInterval(this.highlightInterval), this.highlightInterval = null);
+  }
+  pause() {
+    this.currentAudio && !this.pausedState && (this.currentAudio.pause(), this.stopWordHighlighting(), this.pausedState = !0);
+  }
+  resume() {
+    this.currentAudio && this.pausedState && (this.currentAudio.play(), this.pausedState = !1, this.onWordBoundary && this.wordTimings.length > 0 && this.startWordHighlighting());
+  }
+  stop() {
+    this.synthesisRunId += 1, this.activeSynthesisController && (this.activeSynthesisController.abort(), this.activeSynthesisController = null), this.stopWordHighlighting(), this.currentAudio && (this.intentionallyStopped = !0, this.currentAudio.pause(), this.currentAudio.src && URL.revokeObjectURL(this.currentAudio.src), this.currentAudio.src = "", this.currentAudio = null), this.pausedState = !1, this.wordTimings = [];
+  }
+  isPlaying() {
+    return this.currentAudio !== null && !this.pausedState;
+  }
+  isPaused() {
+    return this.pausedState;
+  }
+  /**
+   * Update settings dynamically (rate, pitch, voice)
+   * Note: Voice changes require resynthesis, so voice updates are stored but
+   * take effect on the next speak() call. Rate can be applied to current playback.
+   */
+  updateSettings(t) {
+    t.rate !== void 0 && (this.config.rate = t.rate, this.currentAudio && (this.currentAudio.playbackRate = Math.max(0.25, Math.min(4, t.rate)))), t.pitch !== void 0 && (this.config.pitch = t.pitch), t.voice !== void 0 && (this.config.voice = t.voice);
+  }
+}
+class P {
+  constructor() {
+    u(this, "providerId", "server-tts"), u(this, "providerName", "Server TTS"), u(this, "version", "1.0.0"), u(this, "config", null), u(this, "adapter", null);
+  }
+  /**
+   * Initialize the server TTS provider.
+   *
+   * This is designed to be fast by default (no API calls).
+   * Set validateEndpoint: true in config to test API availability during initialization.
+   *
+   * @performance Default: <10ms, With validation: 100-500ms
+   */
+  async initialize(t) {
+    const e = t;
+    if (!e.apiEndpoint)
+      throw new Error("apiEndpoint is required for ServerTTSProvider");
+    this.config = e;
+    const s = f(e);
+    if (this.adapter = M[s], e.validateEndpoint && !await this.testAPIAvailability())
+      throw new Error(`Server TTS API not available at ${e.apiEndpoint}`);
+    return new I(e, this.adapter);
+  }
+  /**
+   * Test if API endpoint is available (with timeout).
+   *
+   * @performance 100-500ms depending on network
+   */
+  async testAPIAvailability() {
+    if (!this.config || !this.adapter)
+      return !1;
+    try {
+      const t = { ...this.config.headers };
+      this.config.authToken && (t.Authorization = `Bearer ${this.config.authToken}`);
+      const e = new AbortController(), s = setTimeout(() => e.abort(), 5e3), r = S(this.config, this.adapter.id);
+      if (r === "none")
+        return clearTimeout(s), !0;
+      const n = m(this.config.apiEndpoint), h = r === "voices" ? `${n}/voices` : this.adapter.resolveSynthesisUrl(this.config), o = r === "voices" ? "GET" : "OPTIONS";
+      try {
+        const a = await fetch(h, {
+          method: o,
+          headers: t,
+          signal: e.signal
+        });
+        return clearTimeout(s), a.ok || a.status === 405;
+      } catch {
+        return clearTimeout(s), !1;
+      }
+    } catch {
+      return !1;
+    }
+  }
+  supportsFeature(t) {
+    switch (t) {
+      case "pause":
+      case "resume":
+      case "wordBoundary":
+      case "voiceSelection":
+      case "rateControl":
+        return !0;
+      case "pitchControl":
+        return !1;
+      default:
+        return !1;
+    }
+  }
+  getCapabilities() {
+    const t = this.config ? f(this.config) : "pie";
+    return {
+      supportsPause: !0,
+      supportsResume: !0,
+      supportsWordBoundary: !0,
+      // ✅ Via speech marks from server
+      supportsVoiceSelection: !0,
+      supportsRateControl: !0,
+      supportsPitchControl: !1,
+      // Depends on server provider
+      maxTextLength: T[t]
+    };
+  }
+  destroy() {
+    this.config = null, this.adapter = null;
+  }
+}
+export {
+  P as ServerTTSProvider
+};