@sunboard/react 0.1.0

package/dist/index.mjs

@@ -0,0 +1,1250 @@
+"use client";
+
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { SunboardRuntimeApiError, SunboardRuntimeClient, SunboardRuntimeClient as SunboardRuntimeClient$1, routeMatches } from "@sunboard/core/runtime-api";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { FloatingArrow, FloatingPortal, arrow, autoUpdate, flip, offset, shift, useFloating } from "@floating-ui/react";
+
+//#region src/adapters/navigation.ts
+async function navigateWithFallback(url, navigate) {
+	if (navigate) {
+		await navigate(url);
+		return;
+	}
+	if (typeof window !== "undefined") window.location.assign(url);
+}
+
+//#endregion
+//#region src/hooks/sunboard-context.ts
+const SunboardContext = createContext(null);
+
+//#endregion
+//#region src/hooks/useSunboardPreviewSpec.ts
+function useSunboardPreviewSpec() {
+	const [state, setState] = useState(() => ({
+		error: null,
+		loading: getPreviewSpecUrl() !== null,
+		source: "none",
+		spec: null
+	}));
+	useEffect(() => {
+		const previewUrl = getPreviewSpecUrl();
+		if (!previewUrl) {
+			setState({
+				error: null,
+				loading: false,
+				source: "none",
+				spec: null
+			});
+			return;
+		}
+		const controller = new AbortController();
+		let cancelled = false;
+		let eventSource = null;
+		const loadSpec = async (signal) => {
+			const response = await fetch(previewUrl.toString(), { signal });
+			if (!response.ok) throw new Error(`Sunboard preview failed with ${response.status}.`);
+			const json = await response.json();
+			if (!isSunboardSpecLike(json)) throw new Error("Sunboard preview returned an invalid spec payload.");
+			return json;
+		};
+		setState({
+			error: null,
+			loading: true,
+			source: "none",
+			spec: null
+		});
+		loadSpec(controller.signal).then((previewSpec) => {
+			if (cancelled) return;
+			setState({
+				error: null,
+				loading: false,
+				source: "preview",
+				spec: previewSpec
+			});
+			const eventsUrl = buildEventsUrl(previewUrl);
+			if (eventsUrl && typeof EventSource !== "undefined") {
+				eventSource = new EventSource(eventsUrl);
+				let firstMessage = true;
+				eventSource.onmessage = () => {
+					if (firstMessage) {
+						firstMessage = false;
+						return;
+					}
+					reloadSpec(previewUrl);
+				};
+				eventSource.onerror = () => {};
+			}
+		}).catch((error) => {
+			if (controller.signal.aborted || cancelled) return;
+			setState({
+				error: error instanceof Error ? error : new Error(String(error)),
+				loading: false,
+				source: "none",
+				spec: null
+			});
+		});
+		const reloadSpec = async (url) => {
+			try {
+				const response = await fetch(url.toString());
+				if (!response.ok) throw new Error(`Sunboard preview failed with ${response.status}.`);
+				const json = await response.json();
+				if (!isSunboardSpecLike(json)) throw new Error("Sunboard preview returned an invalid spec payload.");
+				if (cancelled) return;
+				setState({
+					error: null,
+					loading: false,
+					source: "preview",
+					spec: json
+				});
+			} catch (error) {
+				if (cancelled) return;
+				setState((current) => ({
+					...current,
+					error: error instanceof Error ? error : new Error(String(error))
+				}));
+			}
+		};
+		return () => {
+			cancelled = true;
+			controller.abort();
+			eventSource?.close();
+		};
+	}, []);
+	return state;
+}
+function buildEventsUrl(specUrl) {
+	try {
+		const eventsUrl = new URL(specUrl.toString());
+		eventsUrl.pathname = eventsUrl.pathname.replace(/\/spec\.json$/, "/events");
+		if (eventsUrl.pathname === specUrl.pathname) return null;
+		return eventsUrl.toString();
+	} catch {
+		return null;
+	}
+}
+function getPreviewSpecUrl() {
+	if (typeof window === "undefined") return null;
+	const pageUrl = new URL(window.location.href);
+	if (pageUrl.searchParams.get("sunboard_preview") !== "1") return null;
+	const previewUrlParam = pageUrl.searchParams.get("sunboard_preview_url");
+	if (!previewUrlParam) return null;
+	try {
+		const previewUrl = new URL(previewUrlParam);
+		return isAllowedLocalPreviewUrl(previewUrl) ? previewUrl : null;
+	} catch {
+		return null;
+	}
+}
+function isAllowedLocalPreviewUrl(url) {
+	return url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1");
+}
+function isSunboardSpecLike(value) {
+	if (!value || typeof value !== "object") return false;
+	const candidate = value;
+	return typeof candidate.key === "string" && typeof candidate.name === "string" && typeof candidate.type === "string" && typeof candidate.checklist === "object" && Array.isArray(candidate.checklist?.steps);
+}
+
+//#endregion
+//#region src/version.ts
+const SDK_VERSION = "0.0.0";
+
+//#endregion
+//#region src/components/SunboardProvider.tsx
+function SunboardProvider({ spec: specProp, user, loading: loadingProp, mode: modeProp, route, navigate, apiUrl, publishableKey, environment = "production", onTrack, children }) {
+	const currentRoute = route ?? getBrowserRoute();
+	const currentOrigin = getBrowserOrigin();
+	const preview = useSunboardPreviewSpec();
+	const client = useMemo(() => {
+		if (!apiUrl || !publishableKey) return null;
+		return new SunboardRuntimeClient$1({
+			apiUrl,
+			publishableKey,
+			sdkVersion: SDK_VERSION
+		});
+	}, [apiUrl, publishableKey]);
+	const bootstrap = useSunboardBootstrap(client, {
+		enabled: !specProp && preview.source !== "preview" && !preview.loading,
+		environment,
+		origin: currentOrigin,
+		route: currentRoute,
+		user
+	});
+	const activeExperience = bootstrap.experience;
+	const hostedSpec = activeExperience?.spec ?? null;
+	const resolvedSpec = specProp ?? preview.spec ?? hostedSpec;
+	const resolvedLoading = loadingProp ?? (preview.loading || bootstrap.loading);
+	const resolvedMode = modeProp ?? (preview.source === "preview" ? "preview" : "production");
+	const hostedMode = client !== null && !specProp && preview.source !== "preview";
+	const [completedStepKeys, setCompletedStepKeys] = useState(() => /* @__PURE__ */ new Set());
+	const [completedTourKeys, setCompletedTourKeys] = useState(() => /* @__PURE__ */ new Set());
+	const [activeTourState, setActiveTourState] = useState(null);
+	const [tourError, setTourError] = useState(null);
+	const lastNavigatedTourStep = useRef(null);
+	const storageKey = !hostedMode && resolvedSpec && user ? completedToursStorageKey(resolvedSpec.key, user.id) : null;
+	const experienceKey = activeExperience?.key ?? resolvedSpec?.key ?? null;
+	const versionId = activeExperience?.version.id ?? null;
+	useEffect(() => {
+		setCompletedStepKeys(/* @__PURE__ */ new Set());
+		setActiveTourState(null);
+		setTourError(null);
+		lastNavigatedTourStep.current = null;
+		if (!storageKey) {
+			setCompletedTourKeys(/* @__PURE__ */ new Set());
+			return;
+		}
+		setCompletedTourKeys(readCompletedTours(storageKey));
+	}, [
+		resolvedSpec?.key,
+		storageKey,
+		user?.id
+	]);
+	useEffect(() => {
+		if (!hostedMode || !activeExperience) return;
+		applyProgress(activeExperience.progress, setCompletedStepKeys, setCompletedTourKeys);
+	}, [activeExperience, hostedMode]);
+	const effectiveCompletedStepKeys = useMemo(() => {
+		if (!hostedMode || !activeExperience) return completedStepKeys;
+		return mergeKeys(completedStepKeys, activeExperience.progress.completedStepKeys);
+	}, [
+		activeExperience,
+		completedStepKeys,
+		hostedMode
+	]);
+	const effectiveCompletedTourKeys = useMemo(() => {
+		if (!hostedMode || !activeExperience) return completedTourKeys;
+		return mergeKeys(completedTourKeys, activeExperience.progress.completedTourKeys);
+	}, [
+		activeExperience,
+		completedTourKeys,
+		hostedMode
+	]);
+	useEffect(() => {
+		if (!resolvedSpec) return;
+		const tourCompletedStepKeys = resolvedSpec.checklist.steps.filter((step) => step.completeWhen?.tour && effectiveCompletedTourKeys.has(step.completeWhen.tour)).map((step) => step.key);
+		if (tourCompletedStepKeys.length === 0) return;
+		setCompletedStepKeys((current) => {
+			const next = new Set(current);
+			for (const stepKey of tourCompletedStepKeys) next.add(stepKey);
+			return next;
+		});
+	}, [effectiveCompletedTourKeys, resolvedSpec]);
+	const activeTour = useMemo(() => {
+		if (!resolvedSpec || !activeTourState) return null;
+		const tour = resolvedSpec.tours[activeTourState.key];
+		const step = tour?.steps[activeTourState.stepIndex];
+		if (!tour || !step) return null;
+		return {
+			key: activeTourState.key,
+			name: tour.name,
+			step,
+			stepIndex: activeTourState.stepIndex,
+			totalSteps: tour.steps.length
+		};
+	}, [activeTourState, resolvedSpec]);
+	useEffect(() => {
+		if (!activeTour?.step.route || routeMatches(activeTour.step.route, currentRoute)) return;
+		const navigationKey = `${activeTour.key}:${activeTour.step.key}:${activeTour.step.route}`;
+		if (lastNavigatedTourStep.current === navigationKey) return;
+		lastNavigatedTourStep.current = navigationKey;
+		navigateWithFallback(activeTour.step.route, navigate);
+	}, [
+		activeTour,
+		currentRoute,
+		navigate
+	]);
+	useEffect(() => {
+		if (!hostedMode || !client || !activeTour || !user || !experienceKey) return;
+		client.recordTourStep({
+			environment,
+			experienceKey,
+			origin: currentOrigin,
+			route: currentRoute,
+			stepKey: activeTour.step.key,
+			tourKey: activeTour.key,
+			user: toRuntimeUser(user),
+			versionId: versionId ?? void 0
+		}).catch(() => {});
+	}, [
+		activeTour?.key,
+		activeTour?.step.key,
+		client,
+		currentOrigin,
+		experienceKey,
+		hostedMode,
+		user?.id
+	]);
+	const totalSteps = resolvedSpec?.checklist.steps.length ?? 0;
+	const completedCount = resolvedSpec?.checklist.steps.filter((step) => effectiveCompletedStepKeys.has(step.key)).length ?? 0;
+	const completeTour = useCallback((tourKey) => {
+		setCompletedTourKeys((current) => {
+			const next = new Set(current);
+			next.add(tourKey);
+			if (storageKey) writeCompletedTours(storageKey, next);
+			return next;
+		});
+	}, [storageKey]);
+	const track = useCallback(async (eventName, properties) => {
+		if (resolvedLoading || !resolvedSpec) return {
+			ok: false,
+			reason: "not-ready"
+		};
+		if (!user) return {
+			ok: false,
+			reason: "missing-user"
+		};
+		const matchingStepKeys = resolvedSpec.checklist.steps.filter((step) => step.completeWhen?.event === eventName).map((step) => step.key);
+		if (matchingStepKeys.length > 0) setCompletedStepKeys((current) => {
+			const next = new Set(current);
+			for (const stepKey of matchingStepKeys) next.add(stepKey);
+			return next;
+		});
+		let networkOk = true;
+		if (hostedMode && client && experienceKey) try {
+			applyProgress((await client.track({
+				environment,
+				eventName,
+				experienceKey,
+				origin: currentOrigin,
+				properties,
+				route: currentRoute,
+				user: toRuntimeUser(user),
+				versionId: versionId ?? void 0
+			})).progress, setCompletedStepKeys, setCompletedTourKeys);
+		} catch {
+			networkOk = false;
+		}
+		try {
+			await onTrack?.(eventName, properties);
+		} catch {
+			return {
+				ok: false,
+				reason: "network-error"
+			};
+		}
+		if (!networkOk) return {
+			ok: false,
+			reason: "network-error"
+		};
+		return { ok: true };
+	}, [
+		client,
+		currentRoute,
+		currentOrigin,
+		environment,
+		experienceKey,
+		hostedMode,
+		onTrack,
+		resolvedLoading,
+		resolvedSpec,
+		user,
+		versionId
+	]);
+	const navigateToStep = useCallback(async (step) => {
+		if (!step.route) return;
+		await navigateWithFallback(step.route, navigate);
+	}, [navigate]);
+	const startTour = useCallback(async (tourKey) => {
+		if (resolvedLoading || !resolvedSpec) return {
+			ok: false,
+			reason: "not-ready"
+		};
+		if (!user) return {
+			ok: false,
+			reason: "missing-user"
+		};
+		if (!resolvedSpec.tours[tourKey]) return {
+			ok: false,
+			reason: "missing-tour"
+		};
+		setTourError(null);
+		lastNavigatedTourStep.current = null;
+		setActiveTourState({
+			key: tourKey,
+			stepIndex: 0
+		});
+		if (hostedMode && client && experienceKey && user) client.startTour({
+			environment,
+			experienceKey,
+			origin: currentOrigin,
+			route: currentRoute,
+			tourKey,
+			user: toRuntimeUser(user),
+			versionId: versionId ?? void 0
+		}).catch(() => {});
+		return { ok: true };
+	}, [
+		client,
+		currentRoute,
+		currentOrigin,
+		environment,
+		experienceKey,
+		hostedMode,
+		resolvedLoading,
+		resolvedSpec,
+		user,
+		versionId
+	]);
+	const dismissTour = useCallback(async () => {
+		setActiveTourState(null);
+		setTourError(null);
+		lastNavigatedTourStep.current = null;
+		return { ok: true };
+	}, []);
+	const finishActiveTour = useCallback(async (tourKey) => {
+		completeTour(tourKey);
+		if (!hostedMode || !client || !experienceKey || !user) return;
+		try {
+			applyProgress((await client.completeTour({
+				environment,
+				experienceKey,
+				origin: currentOrigin,
+				route: currentRoute,
+				tourKey,
+				user: toRuntimeUser(user),
+				versionId: versionId ?? void 0
+			})).progress, setCompletedStepKeys, setCompletedTourKeys);
+		} catch {}
+	}, [
+		client,
+		completeTour,
+		currentRoute,
+		currentOrigin,
+		environment,
+		experienceKey,
+		hostedMode,
+		user,
+		versionId
+	]);
+	const advanceTour = useCallback(async () => {
+		if (resolvedLoading || !resolvedSpec || !activeTourState) return {
+			ok: false,
+			reason: "not-ready"
+		};
+		if (!user) return {
+			ok: false,
+			reason: "missing-user"
+		};
+		const tour = resolvedSpec.tours[activeTourState.key];
+		if (!tour) return {
+			ok: false,
+			reason: "missing-tour"
+		};
+		setTourError(null);
+		lastNavigatedTourStep.current = null;
+		if (activeTourState.stepIndex >= tour.steps.length - 1) {
+			const completedKey = activeTourState.key;
+			setActiveTourState(null);
+			await finishActiveTour(completedKey);
+			return { ok: true };
+		}
+		setActiveTourState({
+			key: activeTourState.key,
+			stepIndex: activeTourState.stepIndex + 1
+		});
+		return { ok: true };
+	}, [
+		activeTourState,
+		finishActiveTour,
+		resolvedLoading,
+		resolvedSpec,
+		user
+	]);
+	const startChecklistStep = useCallback(async (step) => {
+		if (step.action?.type === "startTour") return startTour(step.action.tour);
+		await navigateToStep(step);
+	}, [navigateToStep, startTour]);
+	const visibleHotspots = useMemo(() => {
+		if (!resolvedSpec || activeTour) return [];
+		return Object.entries(resolvedSpec.hotspots).filter(([, hotspot]) => routeMatches(hotspot.route, currentRoute)).filter(([, hotspot]) => hotspot.repeatable || !effectiveCompletedTourKeys.has(hotspot.action.tour)).map(([key, hotspot]) => ({
+			key,
+			hotspot
+		}));
+	}, [
+		activeTour,
+		effectiveCompletedTourKeys,
+		currentRoute,
+		resolvedSpec
+	]);
+	const reportTourError = useCallback((error) => {
+		setTourError(error);
+	}, []);
+	const value = useMemo(() => ({
+		spec: resolvedSpec,
+		user,
+		loading: resolvedLoading,
+		mode: resolvedMode,
+		route: currentRoute,
+		completedStepKeys: effectiveCompletedStepKeys,
+		completedTourKeys: effectiveCompletedTourKeys,
+		completedCount,
+		totalSteps,
+		activeTour,
+		tourError,
+		track,
+		startTour,
+		dismissTour,
+		advanceTour,
+		navigateToStep,
+		startChecklistStep,
+		reportTourError,
+		visibleHotspots
+	}), [
+		resolvedSpec,
+		user,
+		resolvedLoading,
+		resolvedMode,
+		currentRoute,
+		effectiveCompletedStepKeys,
+		effectiveCompletedTourKeys,
+		completedCount,
+		totalSteps,
+		activeTour,
+		tourError,
+		track,
+		startTour,
+		dismissTour,
+		advanceTour,
+		navigateToStep,
+		startChecklistStep,
+		reportTourError,
+		visibleHotspots
+	]);
+	return /* @__PURE__ */ jsx(SunboardContext.Provider, {
+		value,
+		children
+	});
+}
+function useSunboardBootstrap(client, options) {
+	const { enabled, environment, origin, route, user } = options;
+	const [state, setState] = useState({
+		experience: null,
+		loading: false
+	});
+	const warnedSdkAdvisory = useRef(false);
+	useEffect(() => {
+		if (!client || !enabled || !user?.id) {
+			setState({
+				experience: null,
+				loading: false
+			});
+			return;
+		}
+		const controller = new AbortController();
+		setState({
+			experience: null,
+			loading: true
+		});
+		client.bootstrap({
+			environment,
+			origin,
+			route,
+			user: toRuntimeUser(user)
+		}).then((response) => {
+			if (controller.signal.aborted) return;
+			if (response.experiences.length === 0 && isDevEnvironment()) console.warn(`[sunboard] bootstrap returned no active experiences for route "${route}" in environment "${environment}". Check the dashboard for an enabled deployment whose trigger.route matches.`);
+			if (response.sdkAdvisory && isDevEnvironment() && !warnedSdkAdvisory.current) {
+				warnedSdkAdvisory.current = true;
+				console.warn(`[sunboard] ${response.sdkAdvisory.message}`);
+			}
+			setState({
+				experience: response.experiences[0] ?? null,
+				loading: false
+			});
+		}).catch((error) => {
+			if (controller.signal.aborted) return;
+			if (isDevEnvironment()) console.warn("[sunboard] bootstrap failed", error);
+			setState({
+				experience: null,
+				loading: false
+			});
+		});
+		return () => {
+			controller.abort();
+		};
+	}, [
+		client,
+		enabled,
+		environment,
+		origin,
+		user?.id
+	]);
+	return state;
+}
+function applyProgress(progress, setSteps, setTours) {
+	setSteps((current) => mergeKeys(current, progress.completedStepKeys));
+	setTours((current) => mergeKeys(current, progress.completedTourKeys));
+}
+function mergeKeys(current, incoming) {
+	if (incoming.length === 0) return current;
+	const next = new Set(current);
+	for (const key of incoming) next.add(key);
+	if (next.size === current.size) return current;
+	return next;
+}
+function isDevEnvironment() {
+	if (typeof process === "undefined" || !process.env) return false;
+	return process.env.NODE_ENV !== "production";
+}
+function toRuntimeUser(user) {
+	return {
+		email: user.email ?? void 0,
+		group: user.group ?? void 0,
+		id: user.id,
+		properties: user.properties
+	};
+}
+function completedToursStorageKey(specKey, userId) {
+	return `sunboard:${specKey}:${userId}:completed-tours`;
+}
+function getBrowserRoute() {
+	if (typeof window === "undefined") return "/";
+	return `${window.location.pathname}${window.location.search}`;
+}
+function getBrowserOrigin() {
+	if (typeof window === "undefined") return;
+	return window.location.origin;
+}
+function readCompletedTours(storageKey) {
+	if (typeof window === "undefined") return /* @__PURE__ */ new Set();
+	try {
+		const rawValue = window.localStorage.getItem(storageKey);
+		const parsed = rawValue ? JSON.parse(rawValue) : [];
+		if (!Array.isArray(parsed)) return /* @__PURE__ */ new Set();
+		return new Set(parsed.filter((value) => typeof value === "string"));
+	} catch {
+		return /* @__PURE__ */ new Set();
+	}
+}
+function writeCompletedTours(storageKey, tourKeys) {
+	if (typeof window === "undefined") return;
+	try {
+		window.localStorage.setItem(storageKey, JSON.stringify([...tourKeys].sort()));
+	} catch {}
+}
+
+//#endregion
+//#region src/lib/interpolate-tokens.ts
+const TOKEN_PATTERN = /\{\{\s*user\.([\w][\w.]*)(?:\s*\|\s*(?:"([^"]*)"|'([^']*)'))?\s*\}\}/g;
+function flattenUser(user) {
+	if (!user) return {};
+	const flat = { ...user.properties ?? {} };
+	flat.id = user.id;
+	if (user.email !== void 0) flat.email = user.email;
+	if (user.group !== void 0) flat.group = user.group;
+	return flat;
+}
+function lookupPath(root, path) {
+	const segments = path.split(".");
+	let current = root;
+	for (const segment of segments) {
+		if (current === null || current === void 0) return void 0;
+		if (typeof current !== "object") return void 0;
+		current = current[segment];
+	}
+	return current;
+}
+function coerceValue(value) {
+	if (value === null || value === void 0) return null;
+	if (typeof value === "string") return value.length > 0 ? value : null;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	return null;
+}
+function interpolateTokens(template, user) {
+	if (!template || !template.includes("{{")) return template;
+	const flat = flattenUser(user);
+	return template.replace(TOKEN_PATTERN, (_match, path, doubleQuoted, singleQuoted) => {
+		const resolved = coerceValue(lookupPath(flat, path));
+		if (resolved !== null) return resolved;
+		return doubleQuoted ?? singleQuoted ?? "";
+	});
+}
+
+//#endregion
+//#region src/hooks/useSunboard.ts
+function useSunboard() {
+	const context = useContext(SunboardContext);
+	if (!context) throw new Error("useSunboard must be used within SunboardProvider.");
+	return context;
+}
+
+//#endregion
+//#region src/hooks/useChecklist.ts
+const SUPPORTED_CHECKLIST_TYPES = new Set(["checklist", "hybrid"]);
+function actionLabelFor(step) {
+	if (step.action?.type === "startTour") return "Start";
+	if (step.action || step.route) return "Open";
+}
+function interpolateOptional(text, user) {
+	if (!text) return void 0;
+	return interpolateTokens(text, user) || void 0;
+}
+function useChecklist() {
+	const { spec, user, loading, completedStepKeys, completedCount, totalSteps, startChecklistStep } = useSunboard();
+	const [dismissedKey, setDismissedKey] = useState(null);
+	const hasChecklist = Boolean(spec && SUPPORTED_CHECKLIST_TYPES.has(spec.type));
+	const allCompleted = totalSteps > 0 && completedCount >= totalSteps;
+	const ready = !loading && !!user && !!spec && hasChecklist;
+	const specKey = spec?.key ?? null;
+	const userId = user?.id ?? null;
+	const observationKey = ready && specKey && userId ? `${specKey}:${userId}` : null;
+	const observationRef = useRef(null);
+	if (observationKey && observationRef.current?.key !== observationKey) observationRef.current = {
+		key: observationKey,
+		sawIncomplete: !allCompleted
+	};
+	else if (observationKey && observationRef.current && !allCompleted) observationRef.current.sawIncomplete = true;
+	const sawIncompleteFirst = observationRef.current?.sawIncomplete ?? false;
+	const dismissed = dismissedKey !== null && dismissedKey === observationKey;
+	const rawSteps = useMemo(() => spec?.checklist?.steps ?? [], [spec]);
+	const title = useMemo(() => interpolateOptional(spec?.title, user ?? null), [spec?.title, user]);
+	const subtitle = useMemo(() => interpolateOptional(spec?.subtitle, user ?? null), [spec?.subtitle, user]);
+	const completion = useMemo(() => {
+		const raw = spec?.completion;
+		if (!raw) return void 0;
+		const interpolatedTitle = interpolateOptional(raw.title, user ?? null);
+		if (!interpolatedTitle) return void 0;
+		return {
+			title: interpolatedTitle,
+			subtitle: interpolateOptional(raw.subtitle, user ?? null),
+			message: interpolateOptional(raw.message, user ?? null),
+			dismissAfterMs: raw.dismissAfterMs
+		};
+	}, [spec?.completion, user]);
+	const showingCompletion = ready && allCompleted && !!completion && sawIncompleteFirst && !dismissed;
+	const visible = ready && !allCompleted || showingCompletion;
+	const steps = useMemo(() => {
+		return rawSteps.map((step) => ({
+			key: step.key,
+			title: interpolateTokens(step.title, user ?? null),
+			description: step.description ? interpolateTokens(step.description, user ?? null) : void 0,
+			badge: step.badge ? interpolateTokens(step.badge, user ?? null) : void 0,
+			actionLabel: actionLabelFor(step)
+		}));
+	}, [rawSteps, user]);
+	const stepsByKey = useMemo(() => {
+		const map = /* @__PURE__ */ new Map();
+		for (const step of rawSteps) map.set(step.key, step);
+		return map;
+	}, [rawSteps]);
+	const remainingCount = Math.max(totalSteps - completedCount, 0);
+	const progress = totalSteps > 0 ? Math.round(completedCount / totalSteps * 100) : 0;
+	const dismissCompletion = useCallback(() => {
+		if (observationKey) setDismissedKey(observationKey);
+	}, [observationKey]);
+	return {
+		visible,
+		title,
+		subtitle,
+		steps,
+		completedStepKeys,
+		completedCount,
+		totalSteps,
+		remainingCount,
+		progress,
+		isCompleted: (key) => completedStepKeys.has(key),
+		hasAction: (step) => step.actionLabel !== void 0,
+		startStep: (step) => {
+			const raw = stepsByKey.get(step.key);
+			if (raw) startChecklistStep(raw);
+		},
+		completion: showingCompletion ? completion : void 0,
+		dismissCompletion
+	};
+}
+
+//#endregion
+//#region src/icons/index.tsx
+const CheckIcon = () => {
+	return /* @__PURE__ */ jsx("svg", {
+		xmlns: "http://www.w3.org/2000/svg",
+		width: "24",
+		height: "24",
+		viewBox: "0 0 24 24",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "2",
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		className: "lucide lucide-check-icon lucide-check",
+		children: /* @__PURE__ */ jsx("path", { d: "M20 6 9 17l-5-5" })
+	});
+};
+
+//#endregion
+//#region src/components/ChecklistStep.tsx
+function ChecklistStep({ completed, onStart, step }) {
+	const hasAction = step.actionLabel !== void 0;
+	const status = /* @__PURE__ */ jsx("span", {
+		className: "sunboard-step-status",
+		"aria-label": completed ? "Completed" : "Incomplete",
+		children: completed ? /* @__PURE__ */ jsx(CheckIcon, {}) : null
+	});
+	const content = /* @__PURE__ */ jsxs("div", {
+		className: "sunboard-step-content",
+		children: [/* @__PURE__ */ jsxs("div", {
+			className: "sunboard-step-heading",
+			children: [/* @__PURE__ */ jsx("h3", {
+				className: "sunboard-step-title",
+				children: step.title
+			}), step.badge ? /* @__PURE__ */ jsx("span", {
+				className: "sunboard-step-badge",
+				children: step.badge
+			}) : null]
+		}), step.description ? /* @__PURE__ */ jsx("p", {
+			className: "sunboard-step-description",
+			children: step.description
+		}) : null]
+	});
+	return /* @__PURE__ */ jsx("li", {
+		className: "sunboard-step",
+		"data-completed": completed,
+		children: hasAction ? /* @__PURE__ */ jsxs("button", {
+			className: "sunboard-step-row",
+			type: "button",
+			onClick: onStart,
+			"aria-label": `${step.actionLabel} ${step.title}`,
+			children: [status, content]
+		}) : /* @__PURE__ */ jsxs("div", {
+			className: "sunboard-step-row",
+			children: [status, content]
+		})
+	});
+}
+
+//#endregion
+//#region src/hooks/useInterpolated.ts
+function useInterpolated(text) {
+	const { user } = useSunboard();
+	return useMemo(() => {
+		if (text === void 0) return void 0;
+		return interpolateTokens(text, user);
+	}, [text, user]);
+}
+
+//#endregion
+//#region src/hooks/useTargetElement.ts
+function useTargetElement(selector, enabled, timeoutMs = 5e3) {
+	const [state, setState] = useState({
+		element: null,
+		timedOut: false
+	});
+	useEffect(() => {
+		if (!enabled || !selector) {
+			setState({
+				element: null,
+				timedOut: false
+			});
+			return;
+		}
+		let cancelled = false;
+		const startedAt = Date.now();
+		const findTarget = () => {
+			if (cancelled) return;
+			const element = document.querySelector(selector);
+			if (element instanceof HTMLElement) {
+				setState({
+					element,
+					timedOut: false
+				});
+				return;
+			}
+			if (Date.now() - startedAt >= timeoutMs) {
+				setState({
+					element: null,
+					timedOut: true
+				});
+				return;
+			}
+			window.setTimeout(findTarget, 100);
+		};
+		setState({
+			element: null,
+			timedOut: false
+		});
+		findTarget();
+		return () => {
+			cancelled = true;
+		};
+	}, [
+		enabled,
+		selector,
+		timeoutMs
+	]);
+	return state;
+}
+
+//#endregion
+//#region src/components/SunboardHotspots.tsx
+const HOTSPOT_RADIUS_PX = 9;
+function SunboardHotspots() {
+	const { visibleHotspots } = useSunboard();
+	return /* @__PURE__ */ jsx(Fragment, { children: visibleHotspots.map(({ key, hotspot }) => /* @__PURE__ */ jsx(Hotspot, {
+		hotspot,
+		hotspotKey: key
+	}, key)) });
+}
+function Hotspot({ hotspot, hotspotKey }) {
+	const { startTour } = useSunboard();
+	const label = useInterpolated(hotspot.label);
+	const target = useTargetElement(hotspot.target, true);
+	const { refs, floatingStyles } = useFloating({
+		placement: hotspot.placement,
+		strategy: "fixed",
+		middleware: [offset(-HOTSPOT_RADIUS_PX)],
+		whileElementsMounted: autoUpdate
+	});
+	useEffect(() => {
+		if (!target.element) return;
+		refs.setReference(target.element);
+	}, [refs, target.element]);
+	if (!target.element) return null;
+	return /* @__PURE__ */ jsx(FloatingPortal, { children: /* @__PURE__ */ jsx("button", {
+		"aria-label": label ?? `Start ${hotspot.action.tour} tour`,
+		className: "sunboard-hotspot",
+		"data-pulse": hotspot.pulse,
+		"data-sunboard-hotspot": hotspotKey,
+		onClick: () => {
+			startTour(hotspot.action.tour);
+		},
+		ref: refs.setFloating,
+		style: floatingStyles,
+		type: "button",
+		children: /* @__PURE__ */ jsx("span", { className: "sunboard-hotspot-dot" })
+	}) });
+}
+
+//#endregion
+//#region src/components/SunboardTour.tsx
+function SunboardTour() {
+	const { activeTour, advanceTour, dismissTour, mode, reportTourError, route, tourError } = useSunboard();
+	const arrowRef = useRef(null);
+	const [spotlightRect, setSpotlightRect] = useState(null);
+	const routeReady = routeMatches(activeTour?.step.route, route ?? "/");
+	const target = useTargetElement(activeTour?.step.target ?? null, Boolean(activeTour) && routeReady, 1e3);
+	const { context, refs, floatingStyles, update } = useFloating({
+		placement: activeTour?.step.placement ?? "bottom",
+		middleware: [
+			offset(16),
+			flip(),
+			shift({ padding: 12 }),
+			arrow({ element: arrowRef })
+		]
+	});
+	useEffect(() => {
+		if (!activeTour) {
+			reportTourError(null);
+			return;
+		}
+		if (!routeReady) return;
+		if (!target.timedOut) return;
+		const error = {
+			message: "Sunboard could not find the tour target.",
+			route: activeTour.step.route,
+			stepKey: activeTour.step.key,
+			target: activeTour.step.target,
+			tourKey: activeTour.key
+		};
+		if (mode === "preview") {
+			reportTourError(error);
+			return;
+		}
+		reportTourError(null);
+		dismissTour();
+	}, [
+		activeTour,
+		dismissTour,
+		mode,
+		reportTourError,
+		routeReady,
+		target.timedOut
+	]);
+	useEffect(() => {
+		if (!activeTour || !target.element) return;
+		reportTourError(null);
+		refs.setReference(target.element);
+		target.element.scrollIntoView({
+			block: "center",
+			inline: "center"
+		});
+		update();
+	}, [
+		activeTour,
+		refs,
+		reportTourError,
+		target.element,
+		update
+	]);
+	useEffect(() => {
+		if (!activeTour || !target.element) {
+			setSpotlightRect(null);
+			return;
+		}
+		const updateSpotlight = () => {
+			setSpotlightRect(target.element?.getBoundingClientRect() ?? null);
+		};
+		updateSpotlight();
+		window.addEventListener("resize", updateSpotlight);
+		window.addEventListener("scroll", updateSpotlight, true);
+		target.element.setAttribute("data-sunboard-tour-target", "true");
+		return () => {
+			window.removeEventListener("resize", updateSpotlight);
+			window.removeEventListener("scroll", updateSpotlight, true);
+			target.element?.removeAttribute("data-sunboard-tour-target");
+			setSpotlightRect(null);
+		};
+	}, [activeTour, target.element]);
+	useEffect(() => {
+		if (!activeTour || !target.element) return;
+		const advanceOnTargetClick = () => {
+			window.setTimeout(() => {
+				advanceTour();
+			}, 0);
+		};
+		target.element.addEventListener("click", advanceOnTargetClick);
+		return () => {
+			target.element?.removeEventListener("click", advanceOnTargetClick);
+		};
+	}, [
+		activeTour,
+		advanceTour,
+		target.element
+	]);
+	const tourName = useInterpolated(activeTour?.name);
+	const stepTitle = useInterpolated(activeTour?.step.title);
+	const stepBody = useInterpolated(activeTour?.step.body);
+	if (!activeTour) return null;
+	if (tourError && mode === "preview") return /* @__PURE__ */ jsxs("div", {
+		className: "sunboard-debug",
+		role: "alert",
+		children: [
+			/* @__PURE__ */ jsx("strong", { children: tourError.message }),
+			/* @__PURE__ */ jsxs("span", { children: ["Tour: ", tourError.tourKey] }),
+			/* @__PURE__ */ jsxs("span", { children: ["Step: ", tourError.stepKey] }),
+			tourError.route ? /* @__PURE__ */ jsxs("span", { children: ["Route: ", tourError.route] }) : null,
+			tourError.target ? /* @__PURE__ */ jsxs("span", { children: ["Target: ", tourError.target] }) : null,
+			/* @__PURE__ */ jsx("button", {
+				onClick: () => void dismissTour(),
+				type: "button",
+				children: "Dismiss"
+			})
+		]
+	});
+	if (!routeReady || !target.element) return null;
+	const isLastStep = activeTour.stepIndex === activeTour.totalSteps - 1;
+	return /* @__PURE__ */ jsxs(FloatingPortal, { children: [/* @__PURE__ */ jsx(SunboardTourScrim, { rect: spotlightRect }), /* @__PURE__ */ jsxs("section", {
+		"aria-label": `${tourName} tour step`,
+		className: "sunboard-tour",
+		ref: refs.setFloating,
+		role: "dialog",
+		style: floatingStyles,
+		children: [
+			/* @__PURE__ */ jsx(FloatingArrow, {
+				className: "sunboard-tour-arrow",
+				context,
+				fill: "var(--sunboard-tour-background)",
+				ref: arrowRef,
+				stroke: "var(--sunboard-tour-border)",
+				strokeWidth: 1,
+				tipRadius: 2
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "sunboard-tour-meta",
+				children: [
+					activeTour.stepIndex + 1,
+					" / ",
+					activeTour.totalSteps
+				]
+			}),
+			/* @__PURE__ */ jsx("h2", {
+				className: "sunboard-tour-title",
+				children: stepTitle
+			}),
+			stepBody ? /* @__PURE__ */ jsx("p", {
+				className: "sunboard-tour-body",
+				children: stepBody
+			}) : null,
+			/* @__PURE__ */ jsxs("div", {
+				className: "sunboard-tour-actions",
+				children: [/* @__PURE__ */ jsx("button", {
+					className: "sunboard-tour-secondary",
+					onClick: () => void dismissTour(),
+					type: "button",
+					children: "Dismiss"
+				}), /* @__PURE__ */ jsx("button", {
+					className: "sunboard-tour-primary",
+					onClick: () => void advanceTour(),
+					type: "button",
+					children: isLastStep ? "Finish" : "Next"
+				})]
+			})
+		]
+	})] });
+}
+function SunboardTourScrim({ rect }) {
+	if (!rect) return /* @__PURE__ */ jsx("div", { className: "sunboard-tour-scrim" });
+	const padding = 8;
+	const radius = 12;
+	const left = Math.max(rect.left - padding, 0);
+	const top = Math.max(rect.top - padding, 0);
+	const width = rect.width + padding * 2;
+	const height = rect.height + padding * 2;
+	const maskId = "sunboard-tour-spotlight-mask";
+	return /* @__PURE__ */ jsxs("svg", {
+		"aria-hidden": "true",
+		className: "sunboard-tour-scrim sunboard-tour-spotlight",
+		focusable: "false",
+		children: [/* @__PURE__ */ jsx("defs", { children: /* @__PURE__ */ jsxs("mask", {
+			id: maskId,
+			children: [/* @__PURE__ */ jsx("rect", {
+				fill: "white",
+				height: "100%",
+				width: "100%",
+				x: "0",
+				y: "0"
+			}), /* @__PURE__ */ jsx("rect", {
+				fill: "black",
+				height,
+				rx: radius,
+				ry: radius,
+				width,
+				x: left,
+				y: top
+			})]
+		}) }), /* @__PURE__ */ jsx("rect", {
+			fill: "var(--sunboard-overlay-color)",
+			height: "100%",
+			mask: `url(#${maskId})`,
+			width: "100%",
+			x: "0",
+			y: "0"
+		})]
+	});
+}
+
+//#endregion
+//#region src/components/Sunboard.tsx
+function SunboardChecklist() {
+	const [open, setOpen] = useState(true);
+	const { visible, title, subtitle, steps, completedCount, totalSteps, remainingCount, progress, isCompleted, startStep, completion, dismissCompletion } = useChecklist();
+	useEffect(() => {
+		if (!completion?.dismissAfterMs) return;
+		const handle = window.setTimeout(dismissCompletion, completion.dismissAfterMs);
+		return () => window.clearTimeout(handle);
+	}, [completion, dismissCompletion]);
+	if (!visible || !title) return null;
+	if (completion) return /* @__PURE__ */ jsxs("aside", {
+		className: "sunboard-root sunboard-root-completion",
+		"aria-label": `${title} complete`,
+		role: "status",
+		"aria-live": "polite",
+		children: [/* @__PURE__ */ jsx("button", {
+			className: "sunboard-close sunboard-completion-close",
+			type: "button",
+			onClick: dismissCompletion,
+			"aria-label": "Dismiss completion message",
+			children: "x"
+		}), /* @__PURE__ */ jsxs("div", {
+			className: "sunboard-completion",
+			children: [
+				/* @__PURE__ */ jsx("div", {
+					className: "sunboard-completion-check",
+					"aria-hidden": "true",
+					children: /* @__PURE__ */ jsx("svg", {
+						viewBox: "0 0 24 24",
+						fill: "none",
+						stroke: "currentColor",
+						strokeWidth: "3",
+						strokeLinecap: "round",
+						strokeLinejoin: "round",
+						children: /* @__PURE__ */ jsx("polyline", { points: "5 12 10 17 19 8" })
+					})
+				}),
+				completion.subtitle ? /* @__PURE__ */ jsx("p", {
+					className: "sunboard-completion-subtitle",
+					children: completion.subtitle
+				}) : null,
+				/* @__PURE__ */ jsx("h2", {
+					className: "sunboard-completion-title",
+					children: completion.title
+				}),
+				completion.message ? /* @__PURE__ */ jsx("p", {
+					className: "sunboard-completion-message",
+					children: completion.message
+				}) : null
+			]
+		})]
+	});
+	if (!open) return /* @__PURE__ */ jsx("button", {
+		className: "sunboard-launcher",
+		type: "button",
+		onClick: () => setOpen(true),
+		"aria-label": `Open ${title} checklist, ${remainingCount} tasks remaining`,
+		children: /* @__PURE__ */ jsx("span", {
+			className: "sunboard-launcher-count",
+			children: remainingCount
+		})
+	});
+	return /* @__PURE__ */ jsxs("aside", {
+		className: "sunboard-root",
+		"aria-label": `${title} checklist`,
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "sunboard-header",
+				children: [/* @__PURE__ */ jsxs("div", { children: [subtitle ? /* @__PURE__ */ jsx("p", {
+					className: "sunboard-eyebrow",
+					children: subtitle
+				}) : null, /* @__PURE__ */ jsx("h2", {
+					className: "sunboard-title",
+					children: title
+				})] }), /* @__PURE__ */ jsxs("div", {
+					className: "sunboard-header-actions",
+					children: [/* @__PURE__ */ jsxs("p", {
+						className: "sunboard-progress-count",
+						"aria-label": "Checklist progress",
+						children: [
+							completedCount,
+							" / ",
+							totalSteps
+						]
+					}), /* @__PURE__ */ jsx("button", {
+						className: "sunboard-close",
+						type: "button",
+						onClick: () => setOpen(false),
+						"aria-label": `Close ${title} checklist`,
+						children: "x"
+					})]
+				})]
+			}),
+			/* @__PURE__ */ jsx("div", {
+				className: "sunboard-progress",
+				role: "progressbar",
+				"aria-label": `${title} progress`,
+				"aria-valuemin": 0,
+				"aria-valuemax": totalSteps,
+				"aria-valuenow": completedCount,
+				children: /* @__PURE__ */ jsx("div", {
+					className: "sunboard-progress-fill",
+					style: { width: `${progress}%` }
+				})
+			}),
+			/* @__PURE__ */ jsx("ol", {
+				className: "sunboard-step-list",
+				children: steps.map((step) => /* @__PURE__ */ jsx(ChecklistStep, {
+					completed: isCompleted(step.key),
+					onStart: () => startStep(step),
+					step
+				}, step.key))
+			})
+		]
+	});
+}
+const Sunboard = Object.assign(SunboardChecklist, {
+	Checklist: SunboardChecklist,
+	Hotspots: SunboardHotspots,
+	Tour: SunboardTour
+});
+
+//#endregion
+export { Sunboard, SunboardChecklist, SunboardHotspots, SunboardProvider, SunboardRuntimeApiError, SunboardRuntimeClient, SunboardTour, useChecklist, useSunboard, useSunboardPreviewSpec };
+//# sourceMappingURL=index.mjs.map