@liforma/client 0.2.1

package/dist/svelte/ExperienceThumbnail.svelte

@@ -0,0 +1,376 @@
+<script lang="ts">
+	import { onMount } from 'svelte';
+	import type { Attachment } from 'svelte/attachments';
+
+	import {
+		attachImageReady,
+		attachLazyThumb,
+		attachScrollLinkedParallax,
+		ensureExperienceThumbnailStyles,
+		EXPERIENCE_THUMBNAIL_CSS,
+		horizontalParallaxFromViewportY,
+		resolveThumbnailHref,
+		resolveThumbnailInteraction,
+		resolveThumbnailLayers,
+		type GalleryThumb
+	} from '@liforma/client';
+
+	let {
+		galleryThumb,
+		avatarImage,
+		backgroundImage,
+		foregroundImage,
+		alt,
+		experienceId,
+		href,
+		target,
+		rel,
+		onclick,
+		returnUrl,
+		playerBaseUrl,
+		parallax = true,
+		lazy = true,
+		class: className = '',
+		fallbackImage
+	}: {
+		galleryThumb?: GalleryThumb;
+		avatarImage?: string;
+		backgroundImage?: string;
+		foregroundImage?: string;
+		alt: string;
+		experienceId?: string;
+		href?: string;
+		target?: string;
+		rel?: string;
+		onclick?: (event: MouseEvent) => void;
+		returnUrl?: string;
+		playerBaseUrl?: string;
+		parallax?: boolean;
+		lazy?: boolean;
+		class?: string;
+		fallbackImage?: string;
+	} = $props();
+
+	const layers = $derived(
+		resolveThumbnailLayers({
+			galleryThumb,
+			avatarImage,
+			backgroundImage,
+			foregroundImage,
+			fallbackImage
+		})
+	);
+
+	const interaction = $derived(
+		resolveThumbnailInteraction({
+			href,
+			hasClickHandler: typeof onclick === 'function',
+			experienceId
+		})
+	);
+
+	const hasScene = $derived(Boolean(layers?.backgroundImage));
+	const isHostedLaunch = $derived(interaction === 'anchor' && !href?.trim() && Boolean(experienceId?.trim()));
+
+	let resolvedHref = $state<string | undefined>(undefined);
+	let shouldLoad = $state(false);
+	let hovering = $state(false);
+	let pointerDown = $state(false);
+	let scrollParallax = $state(false);
+	let parallaxX = $state(0);
+	let parallaxY = $state(0);
+	let avatarLoadFailed = $state(false);
+	let backgroundReady = $state(false);
+	let avatarReady = $state(false);
+	let foregroundReady = $state(false);
+	let detachGlobalPointerEnd: (() => void) | null = null;
+
+	const parallaxEnabled = $derived(parallax !== false);
+	const parallaxLayersActive = $derived(parallaxEnabled && (hovering || scrollParallax));
+	const resolvedAvatarImage = $derived(
+		layers
+			? avatarLoadFailed && layers.fallbackImage
+				? layers.fallbackImage
+				: layers.avatarImage
+			: ''
+	);
+	const sceneLayersReady = $derived(
+		Boolean(layers) &&
+			(!layers?.backgroundImage || backgroundReady) &&
+			avatarReady &&
+			(!layers?.foregroundImage || foregroundReady)
+	);
+	const revealThumb = $derived(shouldLoad && sceneLayersReady);
+
+	$effect(() => {
+		if (lazy === false) shouldLoad = true;
+	});
+
+	function refreshHref(): void {
+		resolvedHref = resolveThumbnailHref({
+			href,
+			experienceId,
+			returnUrl,
+			playerBaseUrl,
+			useCurrentPageAsReturnUrl: isHostedLaunch && !returnUrl?.trim()
+		});
+	}
+
+	$effect(() => {
+		void href;
+		void experienceId;
+		void returnUrl;
+		void playerBaseUrl;
+		void isHostedLaunch;
+		refreshHref();
+	});
+
+	$effect(() => {
+		void layers?.backgroundImage;
+		void layers?.foregroundImage;
+		void resolvedAvatarImage;
+		backgroundReady = false;
+		avatarReady = false;
+		foregroundReady = false;
+		avatarLoadFailed = false;
+	});
+
+	onMount(() => {
+		ensureExperienceThumbnailStyles(EXPERIENCE_THUMBNAIL_CSS);
+		refreshHref();
+	});
+
+	function imageReadyAttachment(onReady: () => void): Attachment<HTMLImageElement> {
+		return (element) => attachImageReady(element, onReady);
+	}
+
+	const lazyLoadAttach: Attachment<HTMLElement> = (element) => {
+		if (!lazy) {
+			shouldLoad = true;
+			return () => {};
+		}
+		return attachLazyThumb(element, {
+			onVisibleChange: (visible) => {
+				if (visible) shouldLoad = true;
+			}
+		});
+	};
+
+	const scrollParallaxAttach: Attachment<HTMLElement> = (element) => {
+		if (!parallaxEnabled) return () => {};
+		return attachScrollLinkedParallax(element, {
+			onParallax: (x) => {
+				scrollParallax = true;
+				if (!pointerDown) {
+					parallaxX = x;
+					parallaxY = 0;
+				}
+			},
+			pointerActive: () => pointerDown
+		});
+	};
+
+	function onPointerMove(event: PointerEvent): void {
+		if (!parallaxEnabled || scrollParallax) return;
+		const thumb = event.currentTarget as HTMLElement;
+		const rect = thumb.getBoundingClientRect();
+		if (rect.width <= 0 || rect.height <= 0) return;
+		parallaxX = ((event.clientX - rect.left) / rect.width - 0.5) * 2;
+		parallaxY = ((event.clientY - rect.top) / rect.height - 0.5) * 2;
+	}
+
+	function refreshScrollParallax(thumb: HTMLElement): void {
+		parallaxX = horizontalParallaxFromViewportY(thumb.getBoundingClientRect(), window.innerHeight);
+		parallaxY = 0;
+	}
+
+	function clearPointerInteraction(thumb: HTMLElement): void {
+		const wasDown = pointerDown;
+		pointerDown = false;
+		hovering = false;
+		if (scrollParallax && wasDown) {
+			refreshScrollParallax(thumb);
+		} else if (!scrollParallax) {
+			parallaxX = 0;
+			parallaxY = 0;
+		}
+	}
+
+	function onPointerDown(event: PointerEvent): void {
+		if (!parallaxEnabled) return;
+		const thumb = event.currentTarget as HTMLElement;
+		pointerDown = true;
+		if (event.pointerType === 'mouse') hovering = true;
+
+		detachGlobalPointerEnd?.();
+		const onGlobalEnd = () => {
+			clearPointerInteraction(thumb);
+			detachGlobalPointerEnd = null;
+		};
+		detachGlobalPointerEnd = () => {
+			window.removeEventListener('pointerup', onGlobalEnd);
+			window.removeEventListener('pointercancel', onGlobalEnd);
+			detachGlobalPointerEnd = null;
+		};
+		window.addEventListener('pointerup', onGlobalEnd);
+		window.addEventListener('pointercancel', onGlobalEnd);
+	}
+
+	function endPointerInteraction(event: PointerEvent): void {
+		clearPointerInteraction(event.currentTarget as HTMLElement);
+		detachGlobalPointerEnd?.();
+	}
+
+	function onPointerEnter(event: PointerEvent): void {
+		if (parallaxEnabled && event.pointerType === 'mouse') hovering = true;
+	}
+
+	function onPointerLeave(_event: PointerEvent): void {
+		if (!pointerDown) {
+			hovering = false;
+			if (!scrollParallax) {
+				parallaxX = 0;
+				parallaxY = 0;
+			}
+		}
+	}
+
+	function onAvatarError(): void {
+		if (layers?.fallbackImage) avatarLoadFailed = true;
+	}
+
+	function handleClick(event: MouseEvent): void {
+		onclick?.(event);
+		if (event.defaultPrevented) return;
+
+		if (isHostedLaunch && !returnUrl?.trim()) {
+			const next = resolveThumbnailHref({
+				experienceId,
+				playerBaseUrl,
+				useCurrentPageAsReturnUrl: true
+			});
+			if (next && event.button === 0 && !event.metaKey && !event.ctrlKey && !event.shiftKey) {
+				event.preventDefault();
+				window.location.assign(next);
+			}
+		}
+	}
+
+	const rootClass = $derived(
+		[
+			'liforma-et',
+			hasScene ? 'liforma-et--scene' : '',
+			parallaxLayersActive ? 'liforma-et--parallax' : '',
+			scrollParallax ? 'liforma-et--scroll-parallax' : '',
+			shouldLoad && !revealThumb ? 'liforma-et--loading' : '',
+			revealThumb ? 'liforma-et--revealed' : '',
+			className
+		]
+			.filter(Boolean)
+			.join(' ')
+	);
+</script>
+
+{#if layers}
+	{#if interaction === 'anchor' && resolvedHref}
+		<a
+			class={rootClass}
+			href={resolvedHref}
+			{target}
+			{rel}
+			aria-label={alt}
+			style:--liforma-et-parallax-x={parallaxX}
+			style:--liforma-et-parallax-y={parallaxY}
+			{@attach lazyLoadAttach}
+			{@attach scrollParallaxAttach}
+			onclick={handleClick}
+			onpointerdown={onPointerDown}
+			onpointerup={endPointerInteraction}
+			onpointercancel={endPointerInteraction}
+			onpointerenter={onPointerEnter}
+			onpointermove={onPointerMove}
+			onpointerleave={onPointerLeave}
+		>
+			{@render media()}
+		</a>
+	{:else if interaction === 'button'}
+		<button
+			type="button"
+			class={rootClass}
+			aria-label={alt}
+			style:--liforma-et-parallax-x={parallaxX}
+			style:--liforma-et-parallax-y={parallaxY}
+			{@attach lazyLoadAttach}
+			{@attach scrollParallaxAttach}
+			onclick={handleClick}
+			onpointerdown={onPointerDown}
+			onpointerup={endPointerInteraction}
+			onpointercancel={endPointerInteraction}
+			onpointerenter={onPointerEnter}
+			onpointermove={onPointerMove}
+			onpointerleave={onPointerLeave}
+		>
+			{@render media()}
+		</button>
+	{:else}
+		<div
+			class={rootClass}
+			role={alt ? 'img' : undefined}
+			aria-label={alt || undefined}
+			aria-hidden={alt ? undefined : 'true'}
+			style:--liforma-et-parallax-x={parallaxX}
+			style:--liforma-et-parallax-y={parallaxY}
+			{@attach lazyLoadAttach}
+			{@attach scrollParallaxAttach}
+			onpointerdown={onPointerDown}
+			onpointerup={endPointerInteraction}
+			onpointercancel={endPointerInteraction}
+			onpointerenter={onPointerEnter}
+			onpointermove={onPointerMove}
+			onpointerleave={onPointerLeave}
+		>
+			{@render media()}
+		</div>
+	{/if}
+{/if}
+
+{#snippet media()}
+	<span class="liforma-et__placeholder" aria-hidden="true"></span>
+	{#if shouldLoad && layers?.backgroundImage}
+		<img
+			class="liforma-et__background liforma-et__media"
+			class:liforma-et__media--ready={backgroundReady}
+			src={layers.backgroundImage}
+			alt=""
+			decoding="async"
+			{@attach imageReadyAttachment(() => {
+				backgroundReady = true;
+			})}
+		/>
+	{/if}
+	{#if shouldLoad && resolvedAvatarImage}
+		<img
+			class="liforma-et__avatar liforma-et__media"
+			class:liforma-et__media--ready={avatarReady}
+			src={resolvedAvatarImage}
+			alt=""
+			decoding="async"
+			{@attach imageReadyAttachment(() => {
+				avatarReady = true;
+			})}
+			onerror={onAvatarError}
+		/>
+	{/if}
+	{#if shouldLoad && layers?.foregroundImage}
+		<img
+			class="liforma-et__foreground liforma-et__media"
+			class:liforma-et__media--ready={foregroundReady}
+			src={layers.foregroundImage}
+			alt=""
+			decoding="async"
+			{@attach imageReadyAttachment(() => {
+				foregroundReady = true;
+			})}
+		/>
+	{/if}
+{/snippet}

package/dist/svelte/ExperienceThumbnail.svelte.d.ts

@@ -0,0 +1,22 @@
+import { type GalleryThumb } from '@liforma/client';
+type $$ComponentProps = {
+    galleryThumb?: GalleryThumb;
+    avatarImage?: string;
+    backgroundImage?: string;
+    foregroundImage?: string;
+    alt: string;
+    experienceId?: string;
+    href?: string;
+    target?: string;
+    rel?: string;
+    onclick?: (event: MouseEvent) => void;
+    returnUrl?: string;
+    playerBaseUrl?: string;
+    parallax?: boolean;
+    lazy?: boolean;
+    class?: string;
+    fallbackImage?: string;
+};
+declare const ExperienceThumbnail: import("svelte").Component<$$ComponentProps, {}, "">;
+type ExperienceThumbnail = ReturnType<typeof ExperienceThumbnail>;
+export default ExperienceThumbnail;

package/dist/svelte/ExperienceWidget.svelte

@@ -0,0 +1,146 @@
+<script lang="ts">
+	import { onDestroy } from 'svelte';
+	import {
+		mountExperienceWidget,
+		type ExperienceFit,
+		type ExperienceMode,
+		type ExperienceWidgetController,
+		type ExperienceWidgetPosition,
+		type ExperienceWidgetPrefetch,
+		type GalleryThumb,
+		type SpeechInputMode,
+		type StartButtonOptions
+	} from '@liforma/client';
+
+	let {
+		experienceId,
+		alt,
+		galleryThumb,
+		avatarImage,
+		backgroundImage,
+		foregroundImage,
+		fallbackImage,
+		prefetch = 'onExpand',
+		parallax = true,
+		position = 'static',
+		offset,
+		sessionEndpoint,
+		language,
+		mode,
+		speechInputMode,
+		speechOnly,
+		fit,
+		embedBaseUrl,
+		expandedMaxWidth,
+		expandedMaxHeight,
+		startButtonLabel,
+		startButton,
+		class: className = '',
+		onExpanded,
+		onCollapsed,
+		onStarted,
+		onClose,
+		onError,
+		onPrefetchReady
+	}: {
+		experienceId: string;
+		alt: string;
+		galleryThumb?: GalleryThumb;
+		avatarImage?: string;
+		backgroundImage?: string;
+		foregroundImage?: string;
+		fallbackImage?: string;
+		prefetch?: ExperienceWidgetPrefetch;
+		parallax?: boolean;
+		position?: ExperienceWidgetPosition;
+		offset?: number | string;
+		sessionEndpoint?: string;
+		language?: 'en' | 'es';
+		mode?: ExperienceMode;
+		speechInputMode?: SpeechInputMode;
+		speechOnly?: boolean;
+		fit?: ExperienceFit;
+		embedBaseUrl?: string;
+		expandedMaxWidth?: string;
+		expandedMaxHeight?: string;
+		startButtonLabel?: string;
+		startButton?: StartButtonOptions;
+		class?: string;
+		onExpanded?: () => void;
+		onCollapsed?: () => void;
+		onStarted?: () => void;
+		onClose?: () => void;
+		onError?: (error: Error) => void;
+		onPrefetchReady?: () => void;
+	} = $props();
+
+	let hostEl: HTMLDivElement | undefined = $state();
+	let controller: ExperienceWidgetController | null = null;
+
+	const anchored = $derived(position === 'bottom-right' || position === 'bottom-left');
+
+	$effect(() => {
+		const host = hostEl;
+		if (!host || !experienceId?.trim()) return;
+
+		controller?.destroy();
+		controller = mountExperienceWidget(host, {
+			experienceId,
+			alt,
+			galleryThumb,
+			avatarImage,
+			backgroundImage,
+			foregroundImage,
+			fallbackImage,
+			prefetch,
+			parallax,
+			position,
+			offset,
+			sessionEndpoint,
+			language,
+			mode,
+			speechInputMode,
+			speechOnly,
+			fit,
+			embedBaseUrl,
+			expandedMaxWidth,
+			expandedMaxHeight,
+			startButtonLabel,
+			startButton,
+			onExpanded,
+			onCollapsed,
+			onStarted,
+			onClose,
+			onError,
+			onPrefetchReady
+		});
+
+		return () => {
+			controller?.destroy();
+			controller = null;
+		};
+	});
+
+	onDestroy(() => {
+		controller?.destroy();
+		controller = null;
+	});
+</script>
+
+<div
+	class="liforma-ew-svelte {className}"
+	class:liforma-ew-svelte--anchored={anchored}
+	bind:this={hostEl}
+></div>
+
+<style>
+	.liforma-ew-svelte {
+		width: 100%;
+		height: 100%;
+		min-height: inherit;
+	}
+
+	.liforma-ew-svelte--anchored {
+		display: contents;
+	}
+</style>

package/dist/svelte/ExperienceWidget.svelte.d.ts

@@ -0,0 +1,35 @@
+import { type ExperienceFit, type ExperienceMode, type ExperienceWidgetPosition, type ExperienceWidgetPrefetch, type GalleryThumb, type SpeechInputMode, type StartButtonOptions } from '@liforma/client';
+type $$ComponentProps = {
+    experienceId: string;
+    alt: string;
+    galleryThumb?: GalleryThumb;
+    avatarImage?: string;
+    backgroundImage?: string;
+    foregroundImage?: string;
+    fallbackImage?: string;
+    prefetch?: ExperienceWidgetPrefetch;
+    parallax?: boolean;
+    position?: ExperienceWidgetPosition;
+    offset?: number | string;
+    sessionEndpoint?: string;
+    language?: 'en' | 'es';
+    mode?: ExperienceMode;
+    speechInputMode?: SpeechInputMode;
+    speechOnly?: boolean;
+    fit?: ExperienceFit;
+    embedBaseUrl?: string;
+    expandedMaxWidth?: string;
+    expandedMaxHeight?: string;
+    startButtonLabel?: string;
+    startButton?: StartButtonOptions;
+    class?: string;
+    onExpanded?: () => void;
+    onCollapsed?: () => void;
+    onStarted?: () => void;
+    onClose?: () => void;
+    onError?: (error: Error) => void;
+    onPrefetchReady?: () => void;
+};
+declare const ExperienceWidget: import("svelte").Component<$$ComponentProps, {}, "">;
+type ExperienceWidget = ReturnType<typeof ExperienceWidget>;
+export default ExperienceWidget;

package/dist/svelte/experienceLoadError.d.ts

@@ -0,0 +1,15 @@
+export type ExperienceLoadErrorKind = 'not_found' | 'origin_not_allowed' | 'browser_embeds_disabled' | 'generic';
+export type ExperienceLoadErrorPresentation = {
+    readonly kind: ExperienceLoadErrorKind;
+    readonly title: string;
+    readonly detail: string;
+    readonly technicalMessage: string;
+    readonly experienceId?: string;
+    readonly origin?: string;
+};
+export declare function extractExperienceIdFromMessage(message: string): string | undefined;
+export declare function extractOriginFromMessage(message: string): string | undefined;
+export declare function presentExperienceLoadError(error: unknown, options?: {
+    readonly experienceId?: string | null;
+    readonly origin?: string | null;
+}): ExperienceLoadErrorPresentation;

package/dist/svelte/experienceLoadError.js

@@ -0,0 +1,82 @@
+const EXPERIENCE_ID_IN_MESSAGE = /\b(exp_[A-Za-z0-9][A-Za-z0-9_-]{2,127})\b/;
+const ORIGIN_IN_MESSAGE = /(?:Your origin|origin)\s+(\S+)\s+is not an allowed origin/i;
+function toErrorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+function currentPageOrigin() {
+    try {
+        if (typeof globalThis.location?.origin === 'string' && globalThis.location.origin) {
+            return globalThis.location.origin;
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return undefined;
+}
+export function extractExperienceIdFromMessage(message) {
+    return EXPERIENCE_ID_IN_MESSAGE.exec(message)?.[1];
+}
+export function extractOriginFromMessage(message) {
+    return ORIGIN_IN_MESSAGE.exec(message)?.[1];
+}
+export function presentExperienceLoadError(error, options) {
+    const technicalMessage = toErrorMessage(error).trim() || 'Unknown error';
+    const experienceId = options?.experienceId?.trim() ||
+        extractExperienceIdFromMessage(technicalMessage) ||
+        undefined;
+    const origin = options?.origin?.trim() ||
+        extractOriginFromMessage(technicalMessage) ||
+        currentPageOrigin() ||
+        undefined;
+    if (/No playable experience found/i.test(technicalMessage) ||
+        /^Experience is not available\.?$/i.test(technicalMessage) ||
+        /^Unknown experience\.?$/i.test(technicalMessage) ||
+        /experience_unavailable/i.test(technicalMessage)) {
+        const idLabel = experienceId ?? 'the requested experience';
+        return {
+            kind: 'not_found',
+            title: 'The application tried to load an avatar experience that doesn’t exist.',
+            detail: `Experience with id ${idLabel} does not exist`,
+            technicalMessage,
+            experienceId,
+            origin
+        };
+    }
+    if (/origin_not_allowed/i.test(technicalMessage) ||
+        /is not an allowed origin/i.test(technicalMessage) ||
+        /^Origin not allowed/i.test(technicalMessage)) {
+        const originLabel = origin ?? 'this page';
+        const idLabel = experienceId ?? 'the requested experience';
+        return {
+            kind: 'origin_not_allowed',
+            title: 'The application tried to load an avatar experience from a website that isn’t allowed.',
+            detail: `Origin ${originLabel} is not allowed for experience ${idLabel}`,
+            technicalMessage,
+            experienceId,
+            origin
+        };
+    }
+    if (/browser_embeds_disabled/i.test(technicalMessage) ||
+        /^Browser embeds are not enabled/i.test(technicalMessage)) {
+        const idLabel = experienceId ?? 'the requested experience';
+        return {
+            kind: 'browser_embeds_disabled',
+            title: 'The application tried to load an avatar experience that isn’t enabled for browser embeds.',
+            detail: `Browser embeds are not enabled for experience ${idLabel}`,
+            technicalMessage,
+            experienceId,
+            origin
+        };
+    }
+    return {
+        kind: 'generic',
+        title: 'This avatar experience couldn’t be started.',
+        detail: technicalMessage,
+        technicalMessage,
+        experienceId,
+        origin
+    };
+}

package/dist/svelte/experienceLoadError.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/svelte/experienceLoadError.test.js

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+import { presentExperienceLoadError } from './experienceLoadError';
+describe('presentExperienceLoadError', () => {
+    it('maps unavailable experiences to a friendly not-found presentation', () => {
+        const presentation = presentExperienceLoadError(new Error('No playable experience found for “exp_01MISSING”. Check that the experience id is correct.'), { experienceId: 'exp_01MISSING' });
+        expect(presentation.kind).toBe('not_found');
+        expect(presentation.title).toBe('The application tried to load an avatar experience that doesn’t exist.');
+        expect(presentation.detail).toBe('Experience with id exp_01MISSING does not exist');
+    });
+    it('maps origin denials to a friendly origin presentation', () => {
+        const presentation = presentExperienceLoadError(new Error('Your origin http://localhost:5173 is not an allowed origin for experience exp_01DEMO. If you own this experience, sign in to the Liforma developer portal.'), { experienceId: 'exp_01DEMO', origin: 'http://localhost:5173' });
+        expect(presentation.kind).toBe('origin_not_allowed');
+        expect(presentation.title).toBe('The application tried to load an avatar experience from a website that isn’t allowed.');
+        expect(presentation.detail).toBe('Origin http://localhost:5173 is not allowed for experience exp_01DEMO');
+        expect(presentation.experienceId).toBe('exp_01DEMO');
+        expect(presentation.origin).toBe('http://localhost:5173');
+    });
+});

package/dist/svelte/experienceLoadErrorOverlay.d.ts

@@ -0,0 +1,7 @@
+import type { ExperienceLoadErrorPresentation } from './experienceLoadError';
+export type ExperienceLoadErrorOverlay = {
+    readonly root: HTMLDivElement;
+    setPresentation(presentation: ExperienceLoadErrorPresentation): void;
+    remove(): void;
+};
+export declare function createExperienceLoadErrorOverlay(container: HTMLElement, initial: ExperienceLoadErrorPresentation): ExperienceLoadErrorOverlay;