@korsolutions/guidon 1.0.0

package/dist/persistence/index.mjs

@@ -0,0 +1,291 @@
+import { useState, useEffect, useCallback } from 'react';
+
+// src/persistence/adapters.ts
+var STORAGE_KEY_PREFIX = "@guidon:";
+var createNoopAdapter = () => ({
+  loadProgress: async () => null,
+  saveProgress: async () => {
+  },
+  loadAllProgress: async () => ({}),
+  clearProgress: async () => {
+  }
+});
+var createMemoryAdapter = () => {
+  const store = {};
+  return {
+    loadProgress: async (guidonId) => store[guidonId] ?? null,
+    saveProgress: async (progress) => {
+      store[progress.guidonId] = progress;
+    },
+    loadAllProgress: async () => ({ ...store }),
+    clearProgress: async (guidonId) => {
+      delete store[guidonId];
+    }
+  };
+};
+var createLocalStorageAdapter = (keyPrefix = STORAGE_KEY_PREFIX) => ({
+  loadProgress: async (guidonId) => {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return null;
+    }
+    try {
+      const data = localStorage.getItem(`${keyPrefix}${guidonId}`);
+      return data ? JSON.parse(data) : null;
+    } catch {
+      return null;
+    }
+  },
+  saveProgress: async (progress) => {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return;
+    }
+    try {
+      localStorage.setItem(
+        `${keyPrefix}${progress.guidonId}`,
+        JSON.stringify(progress)
+      );
+    } catch {
+    }
+  },
+  loadAllProgress: async () => {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return {};
+    }
+    const result = {};
+    try {
+      for (let i = 0; i < localStorage.length; i++) {
+        const key = localStorage.key(i);
+        if (key?.startsWith(keyPrefix)) {
+          const data = localStorage.getItem(key);
+          if (data) {
+            const progress = JSON.parse(data);
+            result[progress.guidonId] = progress;
+          }
+        }
+      }
+    } catch {
+    }
+    return result;
+  },
+  clearProgress: async (guidonId) => {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return;
+    }
+    try {
+      localStorage.removeItem(`${keyPrefix}${guidonId}`);
+    } catch {
+    }
+  }
+});
+var createAsyncStorageAdapter = (asyncStorage, keyPrefix = STORAGE_KEY_PREFIX) => ({
+  loadProgress: async (guidonId) => {
+    try {
+      const data = await asyncStorage.getItem(`${keyPrefix}${guidonId}`);
+      return data ? JSON.parse(data) : null;
+    } catch {
+      return null;
+    }
+  },
+  saveProgress: async (progress) => {
+    try {
+      await asyncStorage.setItem(
+        `${keyPrefix}${progress.guidonId}`,
+        JSON.stringify(progress)
+      );
+    } catch {
+    }
+  },
+  loadAllProgress: async () => {
+    const result = {};
+    try {
+      const allKeys = await asyncStorage.getAllKeys();
+      const relevantKeys = allKeys.filter((key) => key.startsWith(keyPrefix));
+      const pairs = await asyncStorage.multiGet(relevantKeys);
+      for (const [, value] of pairs) {
+        if (value) {
+          const progress = JSON.parse(value);
+          result[progress.guidonId] = progress;
+        }
+      }
+    } catch {
+    }
+    return result;
+  },
+  clearProgress: async (guidonId) => {
+    try {
+      await asyncStorage.removeItem(`${keyPrefix}${guidonId}`);
+    } catch {
+    }
+  }
+});
+var createApiAdapter = (handlers) => {
+  const noopAdapter = createNoopAdapter();
+  return {
+    loadProgress: handlers.loadProgress ?? noopAdapter.loadProgress,
+    saveProgress: handlers.saveProgress ?? noopAdapter.saveProgress,
+    loadAllProgress: handlers.loadAllProgress ?? noopAdapter.loadAllProgress,
+    clearProgress: handlers.clearProgress ?? noopAdapter.clearProgress
+  };
+};
+var createCompositeAdapter = (adapters) => ({
+  loadProgress: async (guidonId) => {
+    for (const adapter of adapters) {
+      const progress = await adapter.loadProgress(guidonId);
+      if (progress) return progress;
+    }
+    return null;
+  },
+  saveProgress: async (progress) => {
+    await Promise.all(adapters.map((adapter) => adapter.saveProgress(progress)));
+  },
+  loadAllProgress: async () => {
+    const result = {};
+    for (const adapter of adapters) {
+      if (adapter.loadAllProgress) {
+        const data = await adapter.loadAllProgress();
+        Object.assign(result, data);
+      }
+    }
+    return result;
+  },
+  clearProgress: async (guidonId) => {
+    await Promise.all(
+      adapters.map((adapter) => adapter.clearProgress?.(guidonId))
+    );
+  }
+});
+function useGuidonPersistence(adapter, guidonId) {
+  const [progress, setProgress] = useState(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState(null);
+  useEffect(() => {
+    if (!adapter) {
+      setIsLoading(false);
+      return;
+    }
+    let mounted = true;
+    const loadProgress = async () => {
+      try {
+        setIsLoading(true);
+        setError(null);
+        const data = await adapter.loadProgress(guidonId);
+        if (mounted) {
+          setProgress(data);
+        }
+      } catch (err) {
+        if (mounted) {
+          setError(err instanceof Error ? err.message : "Failed to load progress");
+        }
+      } finally {
+        if (mounted) {
+          setIsLoading(false);
+        }
+      }
+    };
+    loadProgress();
+    return () => {
+      mounted = false;
+    };
+  }, [adapter, guidonId]);
+  const saveProgress = useCallback(
+    async (newProgress) => {
+      if (!adapter) return;
+      const fullProgress = {
+        ...newProgress,
+        guidonId
+      };
+      try {
+        setError(null);
+        await adapter.saveProgress(fullProgress);
+        setProgress(fullProgress);
+      } catch (err) {
+        setError(err instanceof Error ? err.message : "Failed to save progress");
+        throw err;
+      }
+    },
+    [adapter, guidonId]
+  );
+  const clearProgress = useCallback(async () => {
+    if (!adapter?.clearProgress) return;
+    try {
+      setError(null);
+      await adapter.clearProgress(guidonId);
+      setProgress(null);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to clear progress");
+      throw err;
+    }
+  }, [adapter, guidonId]);
+  const markCompleted = useCallback(async () => {
+    const currentCount = progress?.completionCount ?? 0;
+    await saveProgress({
+      completed: true,
+      completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      completionCount: currentCount + 1
+    });
+  }, [saveProgress, progress?.completionCount]);
+  const markStepViewed = useCallback(
+    async (stepIndex) => {
+      await saveProgress({
+        completed: progress?.completed ?? false,
+        lastStepIndex: stepIndex,
+        completedAt: progress?.completedAt,
+        completionCount: progress?.completionCount
+      });
+    },
+    [saveProgress, progress]
+  );
+  return {
+    progress,
+    isLoading,
+    error,
+    isCompleted: progress?.completed ?? false,
+    hasStarted: progress !== null,
+    saveProgress,
+    clearProgress,
+    markCompleted,
+    markStepViewed
+  };
+}
+function useShouldShowGuidon(adapter, guidonId, options) {
+  const { progress, isLoading } = useGuidonPersistence(adapter, guidonId);
+  const [shouldShow, setShouldShow] = useState(false);
+  const [isChecking, setIsChecking] = useState(true);
+  useEffect(() => {
+    if (isLoading) return;
+    const checkCondition = async () => {
+      setIsChecking(true);
+      if (options?.forceShow) {
+        setShouldShow(true);
+        setIsChecking(false);
+        return;
+      }
+      if (progress?.completed) {
+        setShouldShow(false);
+        setIsChecking(false);
+        return;
+      }
+      if (options?.additionalCondition) {
+        try {
+          const result = await options.additionalCondition();
+          setShouldShow(result);
+        } catch {
+          setShouldShow(true);
+        }
+      } else {
+        setShouldShow(true);
+      }
+      setIsChecking(false);
+    };
+    checkCondition();
+  }, [isLoading, progress?.completed, options?.forceShow, options?.additionalCondition]);
+  return {
+    shouldShow,
+    isChecking: isLoading || isChecking,
+    isCompleted: progress?.completed ?? false
+  };
+}
+
+export { createApiAdapter, createAsyncStorageAdapter, createCompositeAdapter, createLocalStorageAdapter, createMemoryAdapter, createNoopAdapter, useGuidonPersistence, useShouldShowGuidon };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/persistence/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/persistence/adapters.ts","../../src/persistence/hooks.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["import type { GuidonPersistenceAdapter, GuidonProgress } from '../types';\n\nconst STORAGE_KEY_PREFIX = '@guidon:';\n\n/**\n * No-op adapter that doesn't persist anything\n * Useful for testing or when persistence is not needed\n */\nexport const createNoopAdapter = (): GuidonPersistenceAdapter => ({\n  loadProgress: async () => null,\n  saveProgress: async () => {},\n  loadAllProgress: async () => ({}),\n  clearProgress: async () => {},\n});\n\n/**\n * Memory adapter that stores progress in memory\n * Data is lost when the app is closed\n */\nexport const createMemoryAdapter = (): GuidonPersistenceAdapter => {\n  const store: Record<string, GuidonProgress> = {};\n\n  return {\n    loadProgress: async (guidonId) => store[guidonId] ?? null,\n    saveProgress: async (progress) => {\n      store[progress.guidonId] = progress;\n    },\n    loadAllProgress: async () => ({ ...store }),\n    clearProgress: async (guidonId) => {\n      delete store[guidonId];\n    },\n  };\n};\n\n/**\n * localStorage adapter for web\n * Only works in browser environments\n */\nexport const createLocalStorageAdapter = (\n  keyPrefix: string = STORAGE_KEY_PREFIX\n): GuidonPersistenceAdapter => ({\n  loadProgress: async (guidonId) => {\n    if (typeof window === 'undefined' || !window.localStorage) {\n      return null;\n    }\n    try {\n      const data = localStorage.getItem(`${keyPrefix}${guidonId}`);\n      return data ? JSON.parse(data) : null;\n    } catch {\n      return null;\n    }\n  },\n  saveProgress: async (progress) => {\n    if (typeof window === 'undefined' || !window.localStorage) {\n      return;\n    }\n    try {\n      localStorage.setItem(\n        `${keyPrefix}${progress.guidonId}`,\n        JSON.stringify(progress)\n      );\n    } catch {\n      // Silently fail if storage is full\n    }\n  },\n  loadAllProgress: async () => {\n    if (typeof window === 'undefined' || !window.localStorage) {\n      return {};\n    }\n    const result: Record<string, GuidonProgress> = {};\n    try {\n      for (let i = 0; i < localStorage.length; i++) {\n        const key = localStorage.key(i);\n        if (key?.startsWith(keyPrefix)) {\n          const data = localStorage.getItem(key);\n          if (data) {\n            const progress = JSON.parse(data) as GuidonProgress;\n            result[progress.guidonId] = progress;\n          }\n        }\n      }\n    } catch {\n      // Silently fail\n    }\n    return result;\n  },\n  clearProgress: async (guidonId) => {\n    if (typeof window === 'undefined' || !window.localStorage) {\n      return;\n    }\n    try {\n      localStorage.removeItem(`${keyPrefix}${guidonId}`);\n    } catch {\n      // Silently fail\n    }\n  },\n});\n\n/**\n * AsyncStorage adapter for React Native\n * Requires @react-native-async-storage/async-storage to be installed\n *\n * @example\n * import AsyncStorage from '@react-native-async-storage/async-storage';\n * const adapter = createAsyncStorageAdapter(AsyncStorage);\n */\nexport const createAsyncStorageAdapter = (\n  asyncStorage: {\n    getItem: (key: string) => Promise<string | null>;\n    setItem: (key: string, value: string) => Promise<void>;\n    removeItem: (key: string) => Promise<void>;\n    getAllKeys: () => Promise<readonly string[]>;\n    multiGet: (keys: readonly string[]) => Promise<readonly [string, string | null][]>;\n  },\n  keyPrefix: string = STORAGE_KEY_PREFIX\n): GuidonPersistenceAdapter => ({\n  loadProgress: async (guidonId) => {\n    try {\n      const data = await asyncStorage.getItem(`${keyPrefix}${guidonId}`);\n      return data ? JSON.parse(data) : null;\n    } catch {\n      return null;\n    }\n  },\n  saveProgress: async (progress) => {\n    try {\n      await asyncStorage.setItem(\n        `${keyPrefix}${progress.guidonId}`,\n        JSON.stringify(progress)\n      );\n    } catch {\n      // Silently fail\n    }\n  },\n  loadAllProgress: async () => {\n    const result: Record<string, GuidonProgress> = {};\n    try {\n      const allKeys = await asyncStorage.getAllKeys();\n      const relevantKeys = allKeys.filter((key) => key.startsWith(keyPrefix));\n      const pairs = await asyncStorage.multiGet(relevantKeys);\n      for (const [, value] of pairs) {\n        if (value) {\n          const progress = JSON.parse(value) as GuidonProgress;\n          result[progress.guidonId] = progress;\n        }\n      }\n    } catch {\n      // Silently fail\n    }\n    return result;\n  },\n  clearProgress: async (guidonId) => {\n    try {\n      await asyncStorage.removeItem(`${keyPrefix}${guidonId}`);\n    } catch {\n      // Silently fail\n    }\n  },\n});\n\n/**\n * Create a custom API adapter for backend persistence\n * This is a factory function that creates an adapter based on your API endpoints\n *\n * @example\n * const adapter = createApiAdapter({\n *   loadProgress: async (guidonId) => {\n *     const response = await fetch(`/api/guidon/${guidonId}`);\n *     return response.json();\n *   },\n *   saveProgress: async (progress) => {\n *     await fetch(`/api/guidon/${progress.guidonId}`, {\n *       method: 'POST',\n *       body: JSON.stringify(progress),\n *     });\n *   },\n * });\n */\nexport const createApiAdapter = (\n  handlers: Partial<GuidonPersistenceAdapter>\n): GuidonPersistenceAdapter => {\n  const noopAdapter = createNoopAdapter();\n  return {\n    loadProgress: handlers.loadProgress ?? noopAdapter.loadProgress,\n    saveProgress: handlers.saveProgress ?? noopAdapter.saveProgress,\n    loadAllProgress: handlers.loadAllProgress ?? noopAdapter.loadAllProgress,\n    clearProgress: handlers.clearProgress ?? noopAdapter.clearProgress,\n  };\n};\n\n/**\n * Combine multiple adapters (e.g., save to both local and API)\n * Loads from the first adapter that returns data\n * Saves to all adapters\n */\nexport const createCompositeAdapter = (\n  adapters: GuidonPersistenceAdapter[]\n): GuidonPersistenceAdapter => ({\n  loadProgress: async (guidonId) => {\n    for (const adapter of adapters) {\n      const progress = await adapter.loadProgress(guidonId);\n      if (progress) return progress;\n    }\n    return null;\n  },\n  saveProgress: async (progress) => {\n    await Promise.all(adapters.map((adapter) => adapter.saveProgress(progress)));\n  },\n  loadAllProgress: async () => {\n    const result: Record<string, GuidonProgress> = {};\n    for (const adapter of adapters) {\n      if (adapter.loadAllProgress) {\n        const data = await adapter.loadAllProgress();\n        Object.assign(result, data);\n      }\n    }\n    return result;\n  },\n  clearProgress: async (guidonId) => {\n    await Promise.all(\n      adapters.map((adapter) => adapter.clearProgress?.(guidonId))\n    );\n  },\n});\n","import { useCallback, useEffect, useState } from 'react';\nimport type { GuidonPersistenceAdapter, GuidonProgress } from '../types';\n\n/**\n * Hook to manage guidon's walkthrough progress with a persistence adapter\n */\nexport function useGuidonPersistence(\n  adapter: GuidonPersistenceAdapter | undefined,\n  guidonId: string\n) {\n  const [progress, setProgress] = useState<GuidonProgress | null>(null);\n  const [isLoading, setIsLoading] = useState(true);\n  const [error, setError] = useState<string | null>(null);\n\n  // Load progress on mount\n  useEffect(() => {\n    if (!adapter) {\n      setIsLoading(false);\n      return;\n    }\n\n    let mounted = true;\n\n    const loadProgress = async () => {\n      try {\n        setIsLoading(true);\n        setError(null);\n        const data = await adapter.loadProgress(guidonId);\n        if (mounted) {\n          setProgress(data);\n        }\n      } catch (err) {\n        if (mounted) {\n          setError(err instanceof Error ? err.message : 'Failed to load progress');\n        }\n      } finally {\n        if (mounted) {\n          setIsLoading(false);\n        }\n      }\n    };\n\n    loadProgress();\n\n    return () => {\n      mounted = false;\n    };\n  }, [adapter, guidonId]);\n\n  const saveProgress = useCallback(\n    async (newProgress: Omit<GuidonProgress, 'guidonId'>) => {\n      if (!adapter) return;\n\n      const fullProgress: GuidonProgress = {\n        ...newProgress,\n        guidonId,\n      };\n\n      try {\n        setError(null);\n        await adapter.saveProgress(fullProgress);\n        setProgress(fullProgress);\n      } catch (err) {\n        setError(err instanceof Error ? err.message : 'Failed to save progress');\n        throw err;\n      }\n    },\n    [adapter, guidonId]\n  );\n\n  const clearProgress = useCallback(async () => {\n    if (!adapter?.clearProgress) return;\n\n    try {\n      setError(null);\n      await adapter.clearProgress(guidonId);\n      setProgress(null);\n    } catch (err) {\n      setError(err instanceof Error ? err.message : 'Failed to clear progress');\n      throw err;\n    }\n  }, [adapter, guidonId]);\n\n  const markCompleted = useCallback(async () => {\n    const currentCount = progress?.completionCount ?? 0;\n    await saveProgress({\n      completed: true,\n      completedAt: new Date().toISOString(),\n      completionCount: currentCount + 1,\n    });\n  }, [saveProgress, progress?.completionCount]);\n\n  const markStepViewed = useCallback(\n    async (stepIndex: number) => {\n      await saveProgress({\n        completed: progress?.completed ?? false,\n        lastStepIndex: stepIndex,\n        completedAt: progress?.completedAt,\n        completionCount: progress?.completionCount,\n      });\n    },\n    [saveProgress, progress]\n  );\n\n  return {\n    progress,\n    isLoading,\n    error,\n    isCompleted: progress?.completed ?? false,\n    hasStarted: progress !== null,\n    saveProgress,\n    clearProgress,\n    markCompleted,\n    markStepViewed,\n  };\n}\n\n/**\n * Hook to check if a guidon should be shown\n */\nexport function useShouldShowGuidon(\n  adapter: GuidonPersistenceAdapter | undefined,\n  guidonId: string,\n  options?: {\n    /** Show even if completed (for replay) */\n    forceShow?: boolean;\n    /** Additional condition to check */\n    additionalCondition?: () => boolean | Promise<boolean>;\n  }\n) {\n  const { progress, isLoading } = useGuidonPersistence(adapter, guidonId);\n  const [shouldShow, setShouldShow] = useState(false);\n  const [isChecking, setIsChecking] = useState(true);\n\n  useEffect(() => {\n    if (isLoading) return;\n\n    const checkCondition = async () => {\n      setIsChecking(true);\n\n      // If forceShow is true, always show\n      if (options?.forceShow) {\n        setShouldShow(true);\n        setIsChecking(false);\n        return;\n      }\n\n      // If already completed, don't show\n      if (progress?.completed) {\n        setShouldShow(false);\n        setIsChecking(false);\n        return;\n      }\n\n      // Check additional condition if provided\n      if (options?.additionalCondition) {\n        try {\n          const result = await options.additionalCondition();\n          setShouldShow(result);\n        } catch {\n          setShouldShow(true); // Default to showing on error\n        }\n      } else {\n        // Default: show if not completed\n        setShouldShow(true);\n      }\n\n      setIsChecking(false);\n    };\n\n    checkCondition();\n  }, [isLoading, progress?.completed, options?.forceShow, options?.additionalCondition]);\n\n  return {\n    shouldShow,\n    isChecking: isLoading || isChecking,\n    isCompleted: progress?.completed ?? false,\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@korsolutions/guidon",
+  "version": "1.0.0",
+  "description": "A cross-platform walkthrough/onboarding component library for React Native with web support. Features spotlight effects, customizable tooltips, and flexible persistence options. ",
+  "repository": "https://github.com/KorSoftwareSolutions/guidon.git",
+  "author": "Christian Jimenez <christianjimenezfael@gmail.com>",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./persistence": {
+      "types": "./dist/persistence/index.d.ts",
+      "import": "./dist/persistence/index.mjs",
+      "require": "./dist/persistence/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "yarn build"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-native": ">=0.70.0",
+    "react-native-reanimated": ">=3.0.0",
+    "react-native-safe-area-context": ">=4.0.0",
+    "react-native-svg": ">=13.0.0",
+    "zustand": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react-native": {
+      "optional": true
+    },
+    "react-native-reanimated": {
+      "optional": true
+    },
+    "react-native-safe-area-context": {
+      "optional": true
+    },
+    "react-native-svg": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.9",
+    "@types/react-native": "^0.73.0",
+    "react-native-reanimated": "^4.2.1",
+    "react-native-safe-area-context": "^5.6.2",
+    "react-native-svg": "^15.15.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.0.0",
+    "zustand": "^5.0.10"
+  },
+  "keywords": [
+    "react-native",
+    "walkthrough",
+    "onboarding",
+    "tutorial",
+    "spotlight",
+    "tooltip",
+    "cross-platform",
+    "expo"
+  ],
+  "license": "MIT"
+}

package/src/components/GuidonOverlay.tsx

@@ -0,0 +1,159 @@
+import { useMemo } from 'react';
+import {
+  StyleSheet,
+  Dimensions,
+  TouchableWithoutFeedback,
+  Platform,
+} from 'react-native';
+import Animated, {
+  useAnimatedStyle,
+  withTiming,
+  Easing,
+} from 'react-native-reanimated';
+import Svg, { Defs, Mask, Rect, G } from 'react-native-svg';
+import { useGuidonStore } from '../store';
+import type { TargetMeasurements, GuidonTheme, GuidonStore } from '../types';
+
+const AnimatedSvg = Animated.createAnimatedComponent(Svg);
+
+const DEFAULT_THEME: Required<
+  Pick<
+    GuidonTheme,
+    'backdropColor' | 'backdropOpacity' | 'spotlightBorderRadius' | 'spotlightPadding'
+  >
+> = {
+  backdropColor: '#000000',
+  backdropOpacity: 0.75,
+  spotlightBorderRadius: 8,
+  spotlightPadding: 8,
+};
+
+interface GuidonOverlayProps {
+  theme?: GuidonTheme;
+  animationDuration?: number;
+  onBackdropPress?: () => void;
+}
+
+export function GuidonOverlay({
+  theme = {},
+  animationDuration = 300,
+  onBackdropPress,
+}: GuidonOverlayProps) {
+  const isActive = useGuidonStore((state: GuidonStore) => state.isActive);
+  const config = useGuidonStore((state: GuidonStore) => state.config);
+  const currentStepIndex = useGuidonStore((state: GuidonStore) => state.currentStepIndex);
+  const targetMeasurements = useGuidonStore((state: GuidonStore) => state.targetMeasurements);
+
+  const mergedTheme = { ...DEFAULT_THEME, ...theme };
+  const { width: screenWidth, height: screenHeight } = Dimensions.get('window');
+
+  // Get current step's target measurements
+  const currentStep = config?.steps[currentStepIndex];
+  const currentTargetId = currentStep?.targetId;
+  const measurements: TargetMeasurements | undefined = currentTargetId
+    ? targetMeasurements[currentTargetId]
+    : undefined;
+
+  // Calculate spotlight dimensions with padding
+  const spotlight = useMemo(() => {
+    if (!measurements) {
+      return { x: 0, y: 0, width: 0, height: 0 };
+    }
+    return {
+      x: measurements.x - mergedTheme.spotlightPadding,
+      y: measurements.y - mergedTheme.spotlightPadding,
+      width: measurements.width + mergedTheme.spotlightPadding * 2,
+      height: measurements.height + mergedTheme.spotlightPadding * 2,
+    };
+  }, [measurements, mergedTheme.spotlightPadding]);
+
+  // Animated styles for fade in/out
+  const animatedStyle = useAnimatedStyle(() => {
+    return {
+      opacity: withTiming(isActive && measurements ? 1 : 0, {
+        duration: animationDuration,
+        easing: Easing.inOut(Easing.ease),
+      }),
+    };
+  }, [isActive, measurements, animationDuration]);
+
+  if (!isActive || !measurements) {
+    return null;
+  }
+
+  // For web, use a different approach with CSS
+  if (Platform.OS === 'web') {
+    return (
+      <TouchableWithoutFeedback onPress={onBackdropPress}>
+        <Animated.View style={[styles.container, animatedStyle]}>
+          <div
+            style={{
+              position: 'absolute',
+              inset: 0,
+              backgroundColor: mergedTheme.backdropColor,
+              opacity: mergedTheme.backdropOpacity,
+              clipPath: `polygon(
+                0% 0%,
+                0% 100%,
+                ${spotlight.x}px 100%,
+                ${spotlight.x}px ${spotlight.y}px,
+                ${spotlight.x + spotlight.width}px ${spotlight.y}px,
+                ${spotlight.x + spotlight.width}px ${spotlight.y + spotlight.height}px,
+                ${spotlight.x}px ${spotlight.y + spotlight.height}px,
+                ${spotlight.x}px 100%,
+                100% 100%,
+                100% 0%
+              )`,
+            }}
+          />
+        </Animated.View>
+      </TouchableWithoutFeedback>
+    );
+  }
+
+  // Native implementation using SVG mask
+  return (
+    <TouchableWithoutFeedback onPress={onBackdropPress}>
+      <AnimatedSvg
+        style={[styles.container, animatedStyle]}
+        width={screenWidth}
+        height={screenHeight}
+        viewBox={`0 0 ${screenWidth} ${screenHeight}`}
+      >
+        <Defs>
+          <Mask id="spotlight-mask">
+            {/* White background (visible) */}
+            <Rect x="0" y="0" width="100%" height="100%" fill="white" />
+            {/* Black cutout (transparent) */}
+            <Rect
+              x={spotlight.x}
+              y={spotlight.y}
+              width={spotlight.width}
+              height={spotlight.height}
+              rx={mergedTheme.spotlightBorderRadius}
+              ry={mergedTheme.spotlightBorderRadius}
+              fill="black"
+            />
+          </Mask>
+        </Defs>
+        <G mask="url(#spotlight-mask)">
+          <Rect
+            x="0"
+            y="0"
+            width="100%"
+            height="100%"
+            fill={mergedTheme.backdropColor}
+            fillOpacity={mergedTheme.backdropOpacity}
+          />
+        </G>
+      </AnimatedSvg>
+    </TouchableWithoutFeedback>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    ...StyleSheet.absoluteFillObject,
+    zIndex: 999,
+  },
+});