@polytts/core 0.1.0

package/dist/index.js

@@ -0,0 +1,817 @@
+//#region src/audio.ts
+/** Creates an AudioData object from a sample rate and an array of channel buffers. */
+function createAudioData(sampleRate, channels) {
+	return {
+		sampleRate,
+		channels
+	};
+}
+/** Wraps a single-channel PCM Float32Array into an AudioData object. */
+function pcmToAudioData(data, sampleRate) {
+	return createAudioData(sampleRate, [data]);
+}
+/** Creates a silent AudioData object, useful as a placeholder or for padding. */
+function createSilentAudioData(sampleRate = 24e3, frameCount = 1) {
+	return createAudioData(sampleRate, [new Float32Array(frameCount)]);
+}
+//#endregion
+//#region src/catalog.ts
+/** Creates a model catalog from a static array of model specs. */
+function createStaticCatalog(models) {
+	return { models };
+}
+/** Resolves a catalog source (static object or factory function) into a ModelCatalog. */
+function resolveCatalogSource(source) {
+	return typeof source === "function" ? source() : source;
+}
+/** Merges multiple catalog sources into a single catalog, throwing on duplicate model IDs. */
+function mergeCatalogs(...sources) {
+	const models = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const source of sources) {
+		const catalog = resolveCatalogSource(source);
+		for (const model of catalog.models) {
+			if (seen.has(model.id)) throw new Error(`Duplicate model id in catalog merge: ${model.id}`);
+			seen.add(model.id);
+			models.push(model);
+		}
+	}
+	return { models };
+}
+/** Validates that every model in the catalog references a registered adapter. */
+function validateCatalog(catalog, adapters) {
+	for (const model of catalog.models) if (!adapters.has(model.adapterId)) throw new Error(`Model "${model.id}" references unknown adapter "${model.adapterId}"`);
+}
+//#endregion
+//#region src/storage/memory-asset-store.ts
+function bundleId(bundle) {
+	return `${bundle.adapterId}/${bundle.modelId}`;
+}
+function revisionPrefix(bundle) {
+	return `${bundle.adapterId}/${bundle.modelId}/${bundle.revision}`;
+}
+function cloneData(data) {
+	return data.slice(0);
+}
+/**
+* In-memory implementation of AssetStore, primarily useful for testing and environments without
+* persistent storage.
+*/
+var MemoryAssetStore = class {
+	staging = /* @__PURE__ */ new Map();
+	active = /* @__PURE__ */ new Map();
+	meta = /* @__PURE__ */ new Map();
+	async stageAsset(bundle, assetName, data) {
+		this.staging.set(`${revisionPrefix(bundle)}/${assetName}`, cloneData(data));
+	}
+	async activateBundle(bundle, assetNames) {
+		const stagedAssets = /* @__PURE__ */ new Map();
+		for (const assetName of assetNames) {
+			const key = `${revisionPrefix(bundle)}/${assetName}`;
+			const data = this.staging.get(key);
+			if (!data) throw new Error(`Missing staged asset: ${assetName}`);
+			stagedAssets.set(assetName, data);
+		}
+		for (const [assetName, data] of stagedAssets) {
+			this.active.set(`${revisionPrefix(bundle)}/${assetName}`, cloneData(data));
+			this.staging.delete(`${revisionPrefix(bundle)}/${assetName}`);
+		}
+		this.meta.set(bundleId(bundle), {
+			adapterId: bundle.adapterId,
+			modelId: bundle.modelId,
+			revision: bundle.revision,
+			assetNames
+		});
+	}
+	async isInstalled(bundle, requiredAssetNames) {
+		const meta = this.meta.get(bundleId(bundle));
+		if (!meta || meta.revision !== bundle.revision) return false;
+		if (!requiredAssetNames?.length) return true;
+		return requiredAssetNames.every((assetName) => meta.assetNames.includes(assetName));
+	}
+	async getAsset(bundle, assetName) {
+		return this.active.get(`${revisionPrefix(bundle)}/${assetName}`) ?? null;
+	}
+	async removeBundle(bundle) {
+		const meta = this.meta.get(bundleId(bundle));
+		if (!meta) return;
+		for (const assetName of meta.assetNames) this.active.delete(`${bundle.adapterId}/${bundle.modelId}/${meta.revision}/${assetName}`);
+		this.meta.delete(bundleId(bundle));
+	}
+};
+//#endregion
+//#region src/types.ts
+/** Default speaking speed multiplier (1x). */
+const DEFAULT_SPEAK_SPEED = 1;
+/** Minimum allowed speaking speed multiplier (0.5x). */
+const MIN_SPEAK_SPEED = .5;
+/** Maximum allowed speaking speed multiplier (2x). */
+const MAX_SPEAK_SPEED = 2;
+/**
+* Clamps a speed value to the valid range, returning the default if the input is not a finite
+* number.
+*/
+function normalizeSpeakSpeed(speed) {
+	if (!Number.isFinite(speed)) return 1;
+	return Math.min(2, Math.max(MIN_SPEAK_SPEED, speed));
+}
+/** Resolves a model's distribution info, defaulting to `{ kind: "none" }` when unset. */
+function resolveModelDistribution(model) {
+	if (model.distribution) return {
+		kind: model.distribution.kind,
+		sizeBytes: model.distribution.sizeBytes ?? 0,
+		assets: model.distribution.assets ?? []
+	};
+	return {
+		kind: "none",
+		sizeBytes: 0,
+		assets: []
+	};
+}
+/** Returns the list of downloadable assets for a model. */
+function getModelAssets(model) {
+	return resolveModelDistribution(model).assets ?? [];
+}
+/** Returns the total download size in bytes for a model. */
+function getModelSizeBytes(model) {
+	return resolveModelDistribution(model).sizeBytes ?? 0;
+}
+/**
+* Returns the install state for a model, inferring a default from its distribution if none is
+* provided.
+*/
+function resolveInstallState(model, installState) {
+	if (installState) return installState;
+	const distribution = resolveModelDistribution(model);
+	if (distribution.kind === "none") return {
+		modelId: model.id,
+		adapterId: model.adapterId,
+		revision: model.revision,
+		kind: "not-applicable",
+		installed: true,
+		status: "not-applicable",
+		progress: null,
+		error: null
+	};
+	if (distribution.kind === "adapter-managed") return {
+		modelId: model.id,
+		adapterId: model.adapterId,
+		revision: model.revision,
+		kind: "external",
+		installed: false,
+		status: "unknown",
+		progress: null,
+		error: null
+	};
+	return {
+		modelId: model.id,
+		adapterId: model.adapterId,
+		revision: model.revision,
+		kind: "managed",
+		installed: false,
+		status: "idle",
+		progress: null,
+		error: null
+	};
+}
+/** Returns true if the model is ready to use (either installed or installation is not applicable). */
+function isInstallStateAvailable(installState) {
+	if (!installState) return false;
+	return installState.kind === "not-applicable" || installState.installed;
+}
+/** Type guard that checks whether the install state is managed by the core asset store. */
+function isManagedInstallState(installState) {
+	return installState?.kind === "managed";
+}
+/** Type guard that checks whether the install state is managed externally by the adapter. */
+function isExternalInstallState(installState) {
+	return installState?.kind === "external";
+}
+/** Resolves an adapter's full capabilities, using sensible defaults for any unspecified fields. */
+function resolveAdapterCapabilities(adapter) {
+	return {
+		install: adapter.capabilities?.install ?? Boolean(adapter.install),
+		speak: adapter.capabilities?.speak ?? false,
+		synthesize: adapter.capabilities?.synthesize ?? false,
+		stream: adapter.capabilities?.stream ?? false,
+		dynamicVoices: adapter.capabilities?.dynamicVoices ?? false
+	};
+}
+//#endregion
+//#region src/runtime.ts
+function createAbortError() {
+	const error = /* @__PURE__ */ new Error("Aborted");
+	error.name = "AbortError";
+	return error;
+}
+function bundleFor(model) {
+	return {
+		adapterId: model.adapterId,
+		modelId: model.id,
+		revision: model.revision
+	};
+}
+function createUnsupportedOperationError(operation, modelId) {
+	return /* @__PURE__ */ new Error(`Model "${modelId}" does not support ${operation}`);
+}
+async function fetchAssetWithProgress(asset, fetchImpl, signal, onProgress) {
+	const response = await fetchImpl(asset.url, { signal });
+	if (!response.ok) throw new Error(`Failed to fetch ${asset.name}: HTTP ${response.status}`);
+	if (!response.body) {
+		const data = await response.arrayBuffer();
+		onProgress?.(1);
+		return data;
+	}
+	const contentLength = Number(response.headers.get("content-length") ?? 0) || asset.size || 0;
+	const reader = response.body.getReader();
+	const chunks = [];
+	let received = 0;
+	while (true) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		chunks.push(value);
+		received += value.length;
+		if (contentLength > 0) onProgress?.(received / contentLength);
+	}
+	const combined = new Uint8Array(received);
+	let offset = 0;
+	for (const chunk of chunks) {
+		combined.set(chunk, offset);
+		offset += chunk.length;
+	}
+	onProgress?.(1);
+	return combined.buffer;
+}
+var RuntimeImpl = class {
+	adapters;
+	models;
+	assetStore;
+	audioPlayer;
+	fetchImpl;
+	listeners = /* @__PURE__ */ new Set();
+	instances = /* @__PURE__ */ new Map();
+	instancePromises = /* @__PURE__ */ new Map();
+	loadedModels = /* @__PURE__ */ new Set();
+	preferredVoiceByModel = /* @__PURE__ */ new Map();
+	installOpByModel = /* @__PURE__ */ new Map();
+	state;
+	currentAbort = null;
+	currentAbortModelId = null;
+	disposed = false;
+	installOpSeq = 0;
+	phaseOpSeq = 0;
+	constructor(options) {
+		this.options = options;
+		this.adapters = new Map(options.adapters.map((adapter) => [adapter.id, adapter]));
+		const catalog = mergeCatalogs(...options.catalogs);
+		validateCatalog(catalog, this.adapters);
+		this.models = new Map(catalog.models.map((model) => [model.id, model]));
+		this.assetStore = options.assetStore ?? new MemoryAssetStore();
+		this.audioPlayer = options.audioPlayer ?? null;
+		this.fetchImpl = options.fetch ?? fetch;
+		const supportedModels = catalog.models.filter((model) => this.isModelSupported(model));
+		const initialModelId = options.initialModelId && this.models.has(options.initialModelId) && options.initialModelId || supportedModels[0]?.id || null;
+		const activeModel = initialModelId ? this.models.get(initialModelId) ?? null : null;
+		const activeVoiceId = options.initialVoiceId ?? activeModel?.defaultVoiceId ?? null;
+		if (initialModelId && activeVoiceId) this.preferredVoiceByModel.set(initialModelId, activeVoiceId);
+		this.state = {
+			models: catalog.models,
+			supportedModelIds: supportedModels.map((model) => model.id),
+			activeModelId: initialModelId,
+			activeVoiceId,
+			voices: activeModel?.voices ?? [],
+			isPreparing: false,
+			isSpeaking: false,
+			phase: "idle",
+			phaseModelId: null,
+			phaseProgress: null,
+			error: null,
+			installStates: Object.fromEntries(catalog.models.map((model) => [model.id, resolveInstallState(model)])),
+			installStateHydrated: false,
+			runtimeInfoByModel: Object.fromEntries(catalog.models.map((model) => [model.id, null]))
+		};
+		this.hydrateInstallStates();
+	}
+	getState() {
+		return this.state;
+	}
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+	listModels() {
+		return [...this.state.models];
+	}
+	getModel(modelId) {
+		return this.models.get(modelId) ?? null;
+	}
+	async listVoices(modelId = this.state.activeModelId ?? void 0) {
+		if (!modelId) return [];
+		const model = this.getRequiredModel(modelId);
+		const voices = await (await this.getOrCreateInstance(model)).listVoices();
+		return voices.length ? voices : model.voices ?? [];
+	}
+	async install(modelId, onProgress) {
+		const model = this.getRequiredModel(modelId);
+		this.patchState({ error: null });
+		try {
+			await this.installInternal(model, new AbortController().signal, onProgress);
+		} catch (error) {
+			if (error.name !== "AbortError") this.patchState({
+				error: error.message,
+				phase: "error",
+				phaseModelId: model.id,
+				phaseProgress: null
+			});
+			throw error;
+		}
+	}
+	async uninstall(modelId) {
+		const model = this.getRequiredModel(modelId);
+		const adapter = this.getRequiredAdapter(model.adapterId);
+		const distribution = resolveModelDistribution(model);
+		if (!(adapter.uninstall != null || distribution.kind === "managed-assets" && getModelAssets(model).length > 0)) return;
+		const instance = this.instances.get(modelId);
+		if (instance) {
+			instance.dispose();
+			this.instances.delete(modelId);
+			this.loadedModels.delete(modelId);
+			this.updateRuntimeInfo(modelId, null);
+		}
+		if (adapter.uninstall) await adapter.uninstall(model, this.createAdapterContext());
+		else if (distribution.kind === "managed-assets" && getModelAssets(model).length > 0) await this.assetStore.removeBundle(bundleFor(model));
+		this.updateInstallState(model.id, {
+			installed: false,
+			status: distribution.kind === "adapter-managed" ? "unknown" : "idle",
+			progress: null,
+			error: null
+		});
+		if (this.state.activeModelId === model.id) this.patchState({
+			activeModelId: null,
+			activeVoiceId: null,
+			voices: []
+		});
+	}
+	async prepare(modelId, options) {
+		const abort = new AbortController();
+		await this.prepareInternal(this.getRequiredModel(modelId), options, abort.signal);
+	}
+	async speak(text, options) {
+		if (!text.trim()) return;
+		this.stop();
+		this.audioPlayer?.warmup?.();
+		const abort = new AbortController();
+		this.currentAbort = abort;
+		this.currentAbortModelId = null;
+		this.patchState({
+			isSpeaking: true,
+			error: null
+		});
+		try {
+			const candidateIds = this.buildCandidateList(options?.modelId, options?.fallbackModelIds);
+			let lastError = null;
+			for (const candidateId of candidateIds) try {
+				const model = this.getRequiredModel(candidateId);
+				this.currentAbortModelId = model.id;
+				await this.prepareInternal(model, { voiceId: options?.voiceId }, abort.signal);
+				const adapter = this.getRequiredAdapter(model.adapterId);
+				const instance = await this.getOrCreateInstance(model);
+				const voiceId = await this.resolveVoice(model, options?.voiceId);
+				const speed = options?.speed;
+				const speakingPhaseId = this.startPhase("speaking", model.id, null);
+				if (!supportsSpeak(adapter, instance, this.audioPlayer)) throw createUnsupportedOperationError("playback", model.id);
+				if (isSpeakingInstance(instance)) await instance.speak(text, voiceId, abort.signal, speed);
+				else if (supportsStream(adapter, instance) && this.audioPlayer?.playStream) await this.audioPlayer.playStream(instance.stream(text, voiceId, abort.signal, speed), abort.signal, speed);
+				else {
+					if (!this.audioPlayer) throw new Error(`No audio player configured for model "${model.id}"`);
+					if (!supportsSynthesize(adapter, instance)) throw createUnsupportedOperationError("audio synthesis", model.id);
+					const buffer = await instance.generate(text, voiceId, abort.signal, speed);
+					await this.audioPlayer.play(buffer, abort.signal, speed);
+				}
+				this.completePhaseIfCurrent(speakingPhaseId);
+				this.patchState({
+					isSpeaking: false,
+					error: null
+				});
+				return;
+			} catch (error) {
+				if (error.name === "AbortError") throw error;
+				lastError = error;
+			}
+			throw lastError ?? /* @__PURE__ */ new Error("Unable to speak with any configured model");
+		} catch (error) {
+			if (error.name !== "AbortError") {
+				this.patchState({ error: error.message });
+				throw error;
+			}
+		} finally {
+			if (this.currentAbort === abort) {
+				this.currentAbort = null;
+				this.currentAbortModelId = null;
+			}
+			this.patchState({
+				isSpeaking: false,
+				phase: this.state.phase === "speaking" ? "idle" : this.state.phase,
+				phaseModelId: this.state.phase === "speaking" ? null : this.state.phaseModelId,
+				phaseProgress: this.state.phase === "speaking" ? null : this.state.phaseProgress
+			});
+		}
+	}
+	async synthesize(text, options) {
+		if (!text.trim()) throw new Error("Cannot synthesize empty text");
+		this.stop();
+		const abort = new AbortController();
+		this.currentAbort = abort;
+		this.currentAbortModelId = null;
+		this.patchState({ error: null });
+		try {
+			const candidateIds = this.buildCandidateList(options?.modelId, options?.fallbackModelIds);
+			let lastError = null;
+			for (const candidateId of candidateIds) try {
+				const model = this.getRequiredModel(candidateId);
+				this.currentAbortModelId = model.id;
+				await this.prepareInternal(model, { voiceId: options?.voiceId }, abort.signal);
+				const adapter = this.getRequiredAdapter(model.adapterId);
+				const instance = await this.getOrCreateInstance(model);
+				if (!supportsSynthesize(adapter, instance)) throw createUnsupportedOperationError("audio synthesis", model.id);
+				const voiceId = await this.resolveVoice(model, options?.voiceId);
+				return await instance.generate(text, voiceId, abort.signal, options?.speed);
+			} catch (error) {
+				if (error.name === "AbortError") throw error;
+				lastError = error;
+			}
+			throw lastError ?? /* @__PURE__ */ new Error("Unable to synthesize with any configured model");
+		} finally {
+			if (this.currentAbort === abort) {
+				this.currentAbort = null;
+				this.currentAbortModelId = null;
+			}
+		}
+	}
+	synthesizeStream(text, options) {
+		if (!text.trim()) throw new Error("Cannot synthesize empty text");
+		this.stop();
+		const abort = new AbortController();
+		this.currentAbort = abort;
+		this.currentAbortModelId = null;
+		const candidateIds = this.buildCandidateList(options?.modelId, options?.fallbackModelIds);
+		return async function* () {
+			let lastError = null;
+			try {
+				for (const candidateId of candidateIds) try {
+					const model = this.getRequiredModel(candidateId);
+					this.currentAbortModelId = model.id;
+					await this.prepareInternal(model, { voiceId: options?.voiceId }, abort.signal);
+					const adapter = this.getRequiredAdapter(model.adapterId);
+					const instance = await this.getOrCreateInstance(model);
+					const voiceId = await this.resolveVoice(model, options?.voiceId);
+					if (supportsStream(adapter, instance)) for await (const chunk of instance.stream(text, voiceId, abort.signal, options?.speed)) {
+						if (abort.signal.aborted) throw createAbortError();
+						yield chunk;
+					}
+					else {
+						if (!supportsSynthesize(adapter, instance)) throw createUnsupportedOperationError("streaming audio synthesis", model.id);
+						yield await instance.generate(text, voiceId, abort.signal, options?.speed);
+					}
+					return;
+				} catch (error) {
+					if (error.name === "AbortError") throw error;
+					lastError = error;
+				}
+				throw lastError ?? /* @__PURE__ */ new Error("Unable to synthesize with any configured model");
+			} finally {
+				if (this.currentAbort === abort) {
+					this.currentAbort = null;
+					this.currentAbortModelId = null;
+				}
+			}
+		}.bind(this)();
+	}
+	stop() {
+		const abortedModelId = this.currentAbortModelId;
+		this.currentAbort?.abort();
+		this.currentAbort = null;
+		this.currentAbortModelId = null;
+		if (abortedModelId) this.resetAbortableInstance(abortedModelId);
+		this.audioPlayer?.stop();
+		this.patchState({
+			isSpeaking: false,
+			phase: this.state.phase === "speaking" ? "idle" : this.state.phase,
+			phaseModelId: this.state.phase === "speaking" ? null : this.state.phaseModelId,
+			phaseProgress: this.state.phase === "speaking" ? null : this.state.phaseProgress
+		});
+	}
+	resetAbortableInstance(modelId) {
+		const instance = this.instances.get(modelId);
+		if (!instance?.abortActiveGeneration) return;
+		instance.abortActiveGeneration();
+		this.loadedModels.delete(modelId);
+	}
+	dispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.stop();
+		this.audioPlayer?.dispose();
+		for (const instance of this.instances.values()) instance.dispose();
+		this.instances.clear();
+		this.instancePromises.clear();
+		this.loadedModels.clear();
+		this.listeners.clear();
+	}
+	async hydrateInstallStates() {
+		try {
+			for (const model of this.state.models) {
+				const distribution = resolveModelDistribution(model);
+				const assets = getModelAssets(model);
+				if (distribution.kind !== "managed-assets" || assets.length === 0) continue;
+				const installed = await this.assetStore.isInstalled(bundleFor(model), assets.map((asset) => asset.name));
+				this.updateInstallState(model.id, {
+					installed,
+					status: installed ? "installed" : "idle",
+					progress: installed ? 1 : null
+				});
+			}
+		} finally {
+			this.patchState({ installStateHydrated: true });
+		}
+	}
+	createAdapterContext() {
+		return {
+			assetStore: this.assetStore,
+			fetch: this.fetchImpl,
+			createAbortError
+		};
+	}
+	async getOrCreateInstance(model) {
+		const existing = this.instances.get(model.id);
+		if (existing) return existing;
+		const inFlight = this.instancePromises.get(model.id);
+		if (inFlight) return inFlight;
+		const promise = (async () => {
+			const instance = await this.getRequiredAdapter(model.adapterId).createModel(model, this.createAdapterContext());
+			if (this.disposed) {
+				instance.dispose();
+				throw new Error("TTS runtime has been disposed");
+			}
+			this.instances.set(model.id, instance);
+			return instance;
+		})();
+		this.instancePromises.set(model.id, promise);
+		try {
+			return await promise;
+		} finally {
+			if (this.instancePromises.get(model.id) === promise) this.instancePromises.delete(model.id);
+		}
+	}
+	async prepareInternal(model, options, signal) {
+		if (!this.isModelSupported(model)) throw new Error(`Model "${model.id}" is not supported in this runtime`);
+		this.patchState({
+			isPreparing: true,
+			error: null
+		});
+		try {
+			if (resolveModelDistribution(model).kind === "managed-assets") {
+				const installState = this.state.installStates[model.id];
+				if (isManagedInstallState(installState) && !installState.installed) await this.installInternal(model, signal, options?.onProgress);
+			}
+			const instance = await this.getOrCreateInstance(model);
+			if (!this.loadedModels.has(model.id)) {
+				const phaseId = this.startPhase("loading", model.id, null);
+				await instance.load(signal, (progress) => {
+					this.updatePhaseIfCurrent(phaseId, { phaseProgress: progress });
+					options?.onProgress?.(progress);
+				});
+				this.loadedModels.add(model.id);
+				this.completePhaseIfCurrent(phaseId);
+			}
+			this.updateRuntimeInfo(model.id, instance.getRuntimeInfo?.() ?? null);
+			const voices = await instance.listVoices();
+			const resolvedVoices = voices.length ? voices : model.voices ?? [];
+			const activeVoiceId = this.pickVoiceId(model, resolvedVoices, options?.voiceId);
+			if (activeVoiceId) this.preferredVoiceByModel.set(model.id, activeVoiceId);
+			if (isExternalInstallState(this.state.installStates[model.id])) this.updateInstallState(model.id, {
+				installed: true,
+				status: "ready",
+				progress: null,
+				error: null
+			});
+			this.patchState({
+				activeModelId: model.id,
+				activeVoiceId,
+				voices: resolvedVoices,
+				isPreparing: false,
+				error: null
+			});
+		} catch (error) {
+			if (isExternalInstallState(this.state.installStates[model.id])) this.updateInstallState(model.id, {
+				installed: false,
+				status: error.name === "AbortError" ? "unknown" : "error",
+				progress: null,
+				error: error.name === "AbortError" ? null : error.message
+			});
+			this.patchState({
+				isPreparing: false,
+				phase: error.name === "AbortError" ? "idle" : "error",
+				phaseModelId: error.name === "AbortError" ? null : model.id,
+				phaseProgress: null,
+				error: error.name === "AbortError" ? null : error.message
+			});
+			throw error;
+		}
+	}
+	async resolveVoice(model, requestedVoiceId) {
+		const voices = await this.listVoices(model.id);
+		return this.pickVoiceId(model, voices, requestedVoiceId) ?? "default";
+	}
+	buildCandidateList(preferredModelId, fallbackModelIds = []) {
+		const resolvedCandidates = (preferredModelId != null ? [preferredModelId, ...fallbackModelIds] : fallbackModelIds.length > 0 ? [this.state.activeModelId, ...fallbackModelIds] : [this.state.activeModelId, ...this.state.supportedModelIds]).filter((value) => Boolean(value));
+		return [...new Set(resolvedCandidates)];
+	}
+	isModelSupported(model) {
+		const adapter = this.adapters.get(model.adapterId);
+		if (!adapter) return false;
+		return adapter.isSupported ? adapter.isSupported(model) : true;
+	}
+	getRequiredModel(modelId) {
+		const model = this.models.get(modelId);
+		if (!model) throw new Error(`Unknown model: ${modelId}`);
+		return model;
+	}
+	getRequiredAdapter(adapterId) {
+		const adapter = this.adapters.get(adapterId);
+		if (!adapter) throw new Error(`Unknown adapter: ${adapterId}`);
+		return adapter;
+	}
+	updateInstallState(modelId, patch) {
+		const current = this.state.installStates[modelId];
+		if (!current) return;
+		this.patchState({ installStates: {
+			...this.state.installStates,
+			[modelId]: {
+				...current,
+				...patch
+			}
+		} });
+	}
+	updateRuntimeInfo(modelId, runtimeInfo) {
+		if ((this.state.runtimeInfoByModel[modelId] ?? null) === runtimeInfo) return;
+		this.patchState({ runtimeInfoByModel: {
+			...this.state.runtimeInfoByModel,
+			[modelId]: runtimeInfo
+		} });
+	}
+	async installInternal(model, signal, onProgress) {
+		const adapter = this.getRequiredAdapter(model.adapterId);
+		const adapterCapabilities = resolveAdapterCapabilities(adapter);
+		const distribution = resolveModelDistribution(model);
+		const context = this.createAdapterContext();
+		const bundle = bundleFor(model);
+		const assets = getModelAssets(model);
+		const assetNames = assets.map((asset) => asset.name);
+		if (!adapterCapabilities.install && distribution.kind !== "managed-assets") return;
+		const opId = ++this.installOpSeq;
+		this.installOpByModel.set(model.id, opId);
+		const phaseId = this.startPhase("installing", model.id, 0);
+		if (distribution.kind === "managed-assets" && assetNames.length > 0 && await this.assetStore.isInstalled(bundle, assetNames)) {
+			this.updateInstallStateIfCurrent(model.id, opId, {
+				installed: true,
+				status: "installed",
+				progress: 1,
+				error: null
+			});
+			this.updatePhaseIfCurrent(phaseId, { phaseProgress: 1 });
+			this.completePhaseIfCurrent(phaseId);
+			return;
+		}
+		this.updateInstallStateIfCurrent(model.id, opId, {
+			installed: false,
+			status: "installing",
+			progress: 0,
+			error: null
+		});
+		try {
+			if (adapter.install) await adapter.install(model, context, signal, (progress) => {
+				this.updateInstallStateIfCurrent(model.id, opId, { progress });
+				this.updatePhaseIfCurrent(phaseId, { phaseProgress: progress });
+				onProgress?.(progress);
+			});
+			else if (distribution.kind === "managed-assets" && assets.length > 0) {
+				const totalBytes = assets.reduce((sum, asset) => sum + Math.max(asset.size, 1), 0) || assets.length;
+				let completedBytes = 0;
+				for (const asset of assets) {
+					const data = await fetchAssetWithProgress(asset, this.fetchImpl, signal, (progress) => {
+						const totalProgress = (completedBytes + Math.max(asset.size, 1) * progress) / totalBytes;
+						this.updateInstallStateIfCurrent(model.id, opId, { progress: totalProgress });
+						this.updatePhaseIfCurrent(phaseId, { phaseProgress: totalProgress });
+						onProgress?.(totalProgress);
+					});
+					await this.assetStore.stageAsset(bundle, asset.name, data);
+					completedBytes += Math.max(asset.size, 1);
+				}
+				await this.assetStore.activateBundle(bundle, assetNames);
+			}
+			this.updateInstallStateIfCurrent(model.id, opId, {
+				installed: true,
+				status: distribution.kind === "adapter-managed" ? "ready" : "installed",
+				progress: distribution.kind === "adapter-managed" ? null : 1,
+				error: null
+			});
+			this.updatePhaseIfCurrent(phaseId, { phaseProgress: distribution.kind === "adapter-managed" ? null : 1 });
+			this.completePhaseIfCurrent(phaseId);
+			onProgress?.(1);
+		} catch (error) {
+			if (error.name === "AbortError") {
+				this.updateInstallStateIfCurrent(model.id, opId, {
+					installed: false,
+					status: distribution.kind === "adapter-managed" ? "unknown" : "idle",
+					progress: null,
+					error: null
+				});
+				this.completePhaseIfCurrent(phaseId);
+			} else {
+				this.updateInstallStateIfCurrent(model.id, opId, {
+					installed: false,
+					status: "error",
+					progress: null,
+					error: error.message
+				});
+				this.patchState({
+					phase: "error",
+					phaseModelId: model.id,
+					phaseProgress: null
+				});
+			}
+			throw error;
+		}
+	}
+	pickVoiceId(model, voices, requestedVoiceId) {
+		const configuredVoices = voices.length ? voices : model.voices ?? [];
+		const availableVoiceIds = new Set(configuredVoices.map((voice) => voice.id));
+		const candidates = [
+			requestedVoiceId,
+			this.preferredVoiceByModel.get(model.id),
+			model.defaultVoiceId,
+			configuredVoices[0]?.id
+		];
+		if (availableVoiceIds.size === 0) return candidates.find((candidate) => Boolean(candidate)) ?? null;
+		for (const candidate of candidates) if (candidate && availableVoiceIds.has(candidate)) return candidate;
+		return configuredVoices[0]?.id ?? null;
+	}
+	updateInstallStateIfCurrent(modelId, opId, patch) {
+		if (this.installOpByModel.get(modelId) !== opId) return;
+		this.updateInstallState(modelId, patch);
+	}
+	startPhase(phase, modelId, progress) {
+		const opId = ++this.phaseOpSeq;
+		this.patchState({
+			phase,
+			phaseModelId: modelId,
+			phaseProgress: progress
+		});
+		return opId;
+	}
+	updatePhaseIfCurrent(opId, patch) {
+		if (this.phaseOpSeq !== opId) return;
+		this.patchState(patch);
+	}
+	completePhaseIfCurrent(opId) {
+		if (this.phaseOpSeq !== opId) return;
+		this.patchState({
+			phase: this.state.error ? "error" : this.state.isSpeaking ? "speaking" : "idle",
+			phaseModelId: this.state.isSpeaking ? this.state.activeModelId : null,
+			phaseProgress: null
+		});
+	}
+	patchState(patch) {
+		this.state = {
+			...this.state,
+			...patch
+		};
+		for (const listener of this.listeners) listener(this.state);
+	}
+};
+function isSpeakingInstance(instance) {
+	return typeof instance.speak === "function";
+}
+function isSynthesizingInstance(instance) {
+	return typeof instance.generate === "function";
+}
+function supportsSpeak(adapter, instance, audioPlayer) {
+	if (isSpeakingInstance(instance)) return adapter.capabilities?.speak ?? true;
+	if (audioPlayer?.playStream && supportsStream(adapter, instance)) return true;
+	return Boolean(audioPlayer && isSynthesizingInstance(instance) && (adapter.capabilities?.synthesize ?? true));
+}
+function supportsSynthesize(adapter, instance) {
+	return isSynthesizingInstance(instance) && (adapter.capabilities?.synthesize ?? true);
+}
+function supportsStream(adapter, instance) {
+	return isSynthesizingInstance(instance) && typeof instance.stream === "function" && (adapter.capabilities?.stream ?? true);
+}
+/** Creates a new TTS runtime instance, the main entry point for text-to-speech functionality. */
+function createTTSRuntime(options) {
+	return new RuntimeImpl(options);
+}
+//#endregion
+export { DEFAULT_SPEAK_SPEED, MAX_SPEAK_SPEED, MIN_SPEAK_SPEED, MemoryAssetStore, createAudioData, createSilentAudioData, createStaticCatalog, createTTSRuntime, getModelAssets, getModelSizeBytes, isExternalInstallState, isInstallStateAvailable, isManagedInstallState, mergeCatalogs, normalizeSpeakSpeed, pcmToAudioData, resolveAdapterCapabilities, resolveCatalogSource, resolveInstallState, resolveModelDistribution, validateCatalog };