@liforma/client 0.2.1

package/dist/svelte/Experience.svelte

@@ -0,0 +1,522 @@
+<script lang="ts">
+	import { untrack } from 'svelte';
+	import type { Attachment } from 'svelte/attachments';
+
+	import {
+		Experience as ExperienceClient,
+		navigateOnExperienceClose,
+		type CloseEvent,
+		type EmbedState,
+		type ExperienceEvents,
+		type ExperienceEventName,
+		type ExperienceSession,
+		type ListenOnceOptions,
+		type SessionManifest,
+		type SpeakOptions,
+		type SpeechResult,
+		type StartSessionOptions,
+		type UtteranceResult
+	} from '@liforma/client';
+	import type { ExperienceProps } from './types';
+	import {
+		presentExperienceLoadError,
+		type ExperienceLoadErrorPresentation
+	} from './experienceLoadError';
+	import { createExperienceLoadErrorOverlay } from './experienceLoadErrorOverlay';
+
+	type Deferred<T> = {
+		readonly promise: Promise<T>;
+		resolve(value: T): void;
+		reject(reason: unknown): void;
+	};
+
+	type LaunchSnapshot =
+		| { readonly options: StartSessionOptions; readonly error?: never }
+		| { readonly options?: never; readonly error: Error };
+
+	type Generation = {
+		readonly id: number;
+		readonly session: Deferred<ExperienceSession>;
+		readonly ready: Deferred<ExperienceEvents['ready']>;
+		readonly started: Deferred<ExperienceEvents['started']>;
+		readonly unsubscribers: (() => void)[];
+		readonly reportedErrors: Set<Error>;
+		instance: ExperienceSession | null;
+		destroyed: boolean;
+		instanceDestroyed: boolean;
+	};
+
+	let {
+		experienceId,
+		sessionEndpoint,
+		manifest,
+		acceptCredentialExposure = false,
+		language,
+		mode,
+		responseMode,
+		speechInputMode,
+		startButton,
+		conversationProcessor,
+		speechOnly = false,
+		fit,
+		avatarId,
+		locationId,
+		embedBaseUrl,
+		debug = false,
+		returnUrl,
+		onReady,
+		onStarted,
+		onUserTranscript,
+		onUserSpeechStarted,
+		onUserSpeechEnded,
+		onCharacterSpeechStarted,
+		onCharacterSpeechEnded,
+		onConversationUpdate,
+		onMessage,
+		onListeningState,
+		onModeChange,
+		onConversationProcessorError,
+		onStateUpdate,
+		onClose,
+		onError
+	}: ExperienceProps = $props();
+
+	let host = $state<HTMLDivElement>();
+	let errorHost = $state<HTMLDivElement>();
+	let loadError = $state<ExperienceLoadErrorPresentation | null>(null);
+	let generationId = 0;
+	let launchIdentityId = 0;
+	let activeGeneration: Generation | null = null;
+	const launchIdentities = new WeakMap<object, number>();
+
+	const startButtonKey = $derived(stableSerialize(startButton));
+	const launchKey = $derived(
+		stableSerialize([
+			experienceId,
+			sessionEndpoint,
+			manifest ? identityKey(manifest) : 0,
+			acceptCredentialExposure,
+			language,
+			mode,
+			responseMode,
+			speechInputMode,
+			startButtonKey,
+			conversationProcessor ? identityKey(conversationProcessor) : 0,
+			speechOnly,
+			fit,
+			avatarId,
+			locationId,
+			embedBaseUrl,
+			debug
+		])
+	);
+
+	function createDeferred<T>(): Deferred<T> {
+		let resolve!: (value: T) => void;
+		let reject!: (reason: unknown) => void;
+		const promise = new Promise<T>((promiseResolve, promiseReject) => {
+			resolve = promiseResolve;
+			reject = promiseReject;
+		});
+		void promise.catch(() => undefined);
+		return { promise, resolve, reject };
+	}
+
+	function createGeneration(): Generation {
+		return {
+			id: ++generationId,
+			session: createDeferred<ExperienceSession>(),
+			ready: createDeferred<ExperienceEvents['ready']>(),
+			started: createDeferred<ExperienceEvents['started']>(),
+			unsubscribers: [],
+			reportedErrors: new Set(),
+			instance: null,
+			destroyed: false,
+			instanceDestroyed: false
+		};
+	}
+
+	function abortError(): DOMException {
+		return new DOMException('Aborted', 'AbortError');
+	}
+
+	function toError(error: unknown): Error {
+		if (error instanceof DOMException) return error as Error;
+		return error instanceof Error ? error : new Error(String(error));
+	}
+
+	function isAbortError(error: unknown): boolean {
+		return error instanceof DOMException && error.name === 'AbortError';
+	}
+
+	function stableSerialize(value: unknown): string {
+		if (value === undefined) return 'undefined';
+		if (value === null || typeof value !== 'object') return JSON.stringify(value);
+		if (Array.isArray(value)) return `[${value.map(stableSerialize).join(',')}]`;
+		const record = value as Record<string, unknown>;
+		return `{${Object.keys(record)
+			.sort()
+			.map((key) => `${JSON.stringify(key)}:${stableSerialize(record[key])}`)
+			.join(',')}}`;
+	}
+
+	function identityKey(value: object): number {
+		const existing = launchIdentities.get(value);
+		if (existing !== undefined) return existing;
+		const id = ++launchIdentityId;
+		launchIdentities.set(value, id);
+		return id;
+	}
+
+	function destroyInstance(generation: Generation): void {
+		if (!generation.instance || generation.instanceDestroyed) return;
+		generation.instanceDestroyed = true;
+		generation.instance.destroy();
+	}
+
+	function cancelGeneration(generation: Generation): void {
+		if (generation.destroyed) return;
+		generation.destroyed = true;
+		const error = abortError();
+		generation.session.reject(error);
+		generation.ready.reject(error);
+		generation.started.reject(error);
+		for (const unsubscribe of generation.unsubscribers.splice(0)) unsubscribe();
+		destroyInstance(generation);
+		if (activeGeneration === generation) activeGeneration = null;
+	}
+
+	function resolveExperienceId(options?: StartSessionOptions): string | undefined {
+		if (!options) return experienceId?.trim() || undefined;
+		if ('experienceId' in options) {
+			const id = (options as { readonly experienceId?: string }).experienceId;
+			if (typeof id === 'string' && id.trim()) return id;
+		}
+		if ('manifest' in options) {
+			const manifest = (options as { readonly manifest?: unknown }).manifest;
+			if (manifest && typeof manifest === 'object' && 'experienceId' in manifest) {
+				const id = (manifest as { readonly experienceId?: unknown }).experienceId;
+				if (typeof id === 'string' && id.trim()) return id;
+			}
+		}
+		return experienceId?.trim() || undefined;
+	}
+
+	function showLoadError(error: unknown, options?: StartSessionOptions): void {
+		loadError = presentExperienceLoadError(error, {
+			experienceId: resolveExperienceId(options)
+		});
+	}
+
+	function reportError(
+		error: unknown,
+		generation: Generation,
+		showFallback = false,
+		options?: StartSessionOptions
+	): Error {
+		const normalized = toError(error);
+		if (!isAbortError(normalized) && activeGeneration === generation && !generation.destroyed) {
+			if (showFallback) showLoadError(normalized, options);
+			if (!generation.reportedErrors.has(normalized)) {
+				generation.reportedErrors.add(normalized);
+				console.error('[Experience]', normalized);
+				onError?.(normalized);
+			}
+		}
+		return normalized;
+	}
+
+	function requireGeneration(): Generation {
+		const generation = activeGeneration;
+		if (!generation || generation.destroyed) throw abortError();
+		return generation;
+	}
+
+	function assertCurrent(generation: Generation): void {
+		if (generation.destroyed || activeGeneration !== generation) throw abortError();
+	}
+
+	function subscribe<K extends ExperienceEventName>(
+		generation: Generation,
+		session: ExperienceSession,
+		event: K,
+		handler: (payload: ExperienceEvents[K]) => void
+	): void {
+		generation.unsubscribers.push(session.on(event, handler));
+	}
+
+	function subscribeToEvents(generation: Generation, session: ExperienceSession): void {
+		subscribe(generation, session, 'ready', (event) => {
+			if (generation.destroyed) return;
+			generation.ready.resolve(event);
+			onReady?.(event);
+		});
+		subscribe(generation, session, 'started', (event) => {
+			if (generation.destroyed) return;
+			generation.started.resolve(event);
+			onStarted?.(event);
+		});
+		subscribe(generation, session, 'userTranscript', (event) => onUserTranscript?.(event));
+		subscribe(generation, session, 'userSpeechStarted', (event) => onUserSpeechStarted?.(event));
+		subscribe(generation, session, 'userSpeechEnded', (event) => onUserSpeechEnded?.(event));
+		subscribe(generation, session, 'characterSpeechStarted', (event) =>
+			onCharacterSpeechStarted?.(event)
+		);
+		subscribe(generation, session, 'characterSpeechEnded', (event) =>
+			onCharacterSpeechEnded?.(event)
+		);
+		subscribe(generation, session, 'conversationUpdate', (event) =>
+			onConversationUpdate?.(event)
+		);
+		subscribe(generation, session, 'message', (event) => onMessage?.(event));
+		subscribe(generation, session, 'listeningState', (event) => onListeningState?.(event));
+		subscribe(generation, session, 'modeChange', (event) => onModeChange?.(event));
+		subscribe(generation, session, 'conversationProcessorError', (event) =>
+			onConversationProcessorError?.(event)
+		);
+	}
+
+	function buildStartOptions(): StartSessionOptions {
+		const hasSessionEndpoint = Boolean(sessionEndpoint?.trim());
+		if (hasSessionEndpoint && !experienceId?.trim()) {
+			throw new Error('sessionEndpoint requires experienceId.');
+		}
+		if (!hasSessionEndpoint && !experienceId && !manifest) {
+			throw new Error('Experience requires experienceId or manifest.');
+		}
+
+		if (hasSessionEndpoint && experienceId && sessionEndpoint) {
+			return {
+				experienceId,
+				sessionEndpoint,
+				language,
+				locationId,
+				avatarId,
+				embedBaseUrl,
+				debug,
+				mode,
+				responseMode,
+				speechInputMode,
+				speechOnly,
+				fit,
+				startButton: untrack(() => startButton),
+				conversationProcessor
+			};
+		}
+		if (manifest) {
+			return {
+				manifest,
+				acceptCredentialExposure,
+				embedBaseUrl,
+				debug,
+				speechOnly,
+				fit,
+				startButton: untrack(() => startButton),
+				conversationProcessor
+			};
+		}
+		if (experienceId) {
+			return {
+				experienceId,
+				language,
+				locationId,
+				avatarId,
+				embedBaseUrl,
+				debug,
+				mode,
+				responseMode,
+				speechInputMode,
+				speechOnly,
+				fit,
+				startButton: untrack(() => startButton),
+				conversationProcessor
+			};
+		}
+		throw new Error('Experience requires experienceId or manifest.');
+	}
+
+	function snapshotLaunch(): LaunchSnapshot {
+		try {
+			return { options: buildStartOptions() };
+		} catch (error) {
+			return { error: toError(error) };
+		}
+	}
+
+	async function launch(
+		generation: Generation,
+		container: HTMLDivElement,
+		options: StartSessionOptions
+	): Promise<void> {
+		try {
+			const session = await ExperienceClient.startSession(options);
+			generation.instance = session;
+			if (generation.destroyed || activeGeneration !== generation) {
+				destroyInstance(generation);
+				return;
+			}
+
+			subscribeToEvents(generation, session);
+			const player = await session.attach({
+				container,
+				showClose: Boolean(onClose || returnUrl?.trim()),
+				onStateUpdate: (state: EmbedState) => {
+					if (!generation.destroyed) onStateUpdate?.(state);
+				}
+			});
+			assertCurrent(generation);
+			generation.session.resolve(session);
+			player.on('close', (event: CloseEvent) => {
+				if (generation.destroyed) return;
+				if (onClose) {
+					onClose(event);
+					return;
+				}
+				const fallback = returnUrl?.trim();
+				if (fallback) {
+					navigateOnExperienceClose(event, fallback);
+				}
+			});
+		} catch (error) {
+			const normalized = reportError(error, generation, true, options);
+			generation.session.reject(normalized);
+			generation.ready.reject(normalized);
+			generation.started.reject(normalized);
+			destroyInstance(generation);
+		}
+	}
+
+	async function withSession<T>(
+		operation: (session: ExperienceSession) => Promise<T>
+	): Promise<T> {
+		const generation = requireGeneration();
+		try {
+			const session = await generation.session.promise;
+			assertCurrent(generation);
+			return await operation(session);
+		} catch (error) {
+			const normalized = reportError(error, generation);
+			throw normalized;
+		}
+	}
+
+	export function ready(): Promise<ExperienceEvents['ready']> {
+		return requireGeneration().ready.promise;
+	}
+
+	export function started(): Promise<ExperienceEvents['started']> {
+		return requireGeneration().started.promise;
+	}
+
+	export function speak(options: SpeakOptions): Promise<SpeechResult> {
+		return withSession((session) => session.speak(options));
+	}
+
+	export function startListening(): Promise<void> {
+		return withSession((session) => session.startListening());
+	}
+
+	export function stopListening(): Promise<UtteranceResult> {
+		return withSession((session) => session.stopListening());
+	}
+
+	export function listenOnce(options?: ListenOnceOptions): Promise<UtteranceResult> {
+		return withSession((session) => session.listenOnce(options));
+	}
+
+	export function getManifest(): SessionManifest | null {
+		return activeGeneration?.instance?.getManifest() ?? null;
+	}
+
+	export function getConversation(): ReturnType<ExperienceSession['getConversation']> {
+		return activeGeneration?.instance?.getConversation() ?? [];
+	}
+
+	export function end(): Promise<void> {
+		return withSession((session) => session.end());
+	}
+
+	function activateGeneration(
+		container: HTMLDivElement,
+		snapshot: LaunchSnapshot
+	): () => void {
+		const generation = createGeneration();
+		activeGeneration = generation;
+		loadError = null;
+		if (snapshot.error) {
+			const error = reportError(snapshot.error, generation, true);
+			generation.session.reject(error);
+			generation.ready.reject(error);
+			generation.started.reject(error);
+		} else {
+			void launch(generation, container, snapshot.options);
+		}
+
+		return () => cancelGeneration(generation);
+	}
+
+	const attachHost: Attachment<HTMLDivElement> = (container) => {
+		host = container;
+		return () => {
+			if (host === container) host = undefined;
+		};
+	};
+
+	const attachErrorHost: Attachment<HTMLDivElement> = (container) => {
+		errorHost = container;
+		return () => {
+			if (errorHost === container) errorHost = undefined;
+		};
+	};
+
+	function restartSession(): (() => void) | undefined {
+		const container = host;
+		if (!container) return;
+		void launchKey;
+		const snapshot = untrack(snapshotLaunch);
+		return untrack(() => activateGeneration(container, snapshot));
+	}
+
+	$effect(restartSession);
+
+	$effect(() => {
+		const container = errorHost;
+		const presentation = loadError;
+		if (!container) return;
+		container.replaceChildren();
+		if (!presentation) return;
+		const overlay = createExperienceLoadErrorOverlay(container, presentation);
+		return () => overlay.remove();
+	});
+</script>
+
+<div class="liforma-experience-shell">
+	<div class="error-host" {@attach attachErrorHost} aria-hidden={loadError ? undefined : 'true'}></div>
+	<div class="host" {@attach attachHost}></div>
+</div>
+
+<style>
+	.liforma-experience-shell {
+		position: relative;
+		width: 100%;
+		height: 100%;
+		min-height: inherit;
+	}
+
+	.host {
+		position: absolute;
+		inset: 0;
+		overflow: hidden;
+	}
+
+	.error-host {
+		position: absolute;
+		inset: 0;
+		z-index: 20;
+		pointer-events: none;
+	}
+
+	.error-host:not(:empty) {
+		pointer-events: auto;
+	}
+</style>

package/dist/svelte/Experience.svelte.d.ts

@@ -0,0 +1,15 @@
+import { type ExperienceEvents, type ExperienceSession, type ListenOnceOptions, type SessionManifest, type SpeakOptions, type SpeechResult, type UtteranceResult } from '@liforma/client';
+import type { ExperienceProps } from './types';
+declare const Experience: import("svelte").Component<ExperienceProps, {
+    ready: () => Promise<ExperienceEvents["ready"]>;
+    started: () => Promise<ExperienceEvents["started"]>;
+    speak: (options: SpeakOptions) => Promise<SpeechResult>;
+    startListening: () => Promise<void>;
+    stopListening: () => Promise<UtteranceResult>;
+    listenOnce: (options?: ListenOnceOptions) => Promise<UtteranceResult>;
+    getManifest: () => SessionManifest | null;
+    getConversation: () => ReturnType<ExperienceSession["getConversation"]>;
+    end: () => Promise<void>;
+}, "">;
+type Experience = ReturnType<typeof Experience>;
+export default Experience;