@buoy-gg/core 1.7.8 → 2.1.2

package/lib/module/floatingMenu/dial/DialDevTools.js

@@ -4,7 +4,7 @@ import { useEffect, useMemo, useRef, useState } from "react";
 import { Pressable, StyleSheet, View, Dimensions, Text, Animated, Easing } from "react-native";
 // Icons are provided by installedApps; no direct icon imports here.
 import { DialIcon } from "./DialIcon.js";
-import { safeGetItem, safeSetItem, useHintsDisabled, devToolsStorageKeys, buoyColors } from "@buoy-gg/shared-ui";
+import { persistentStorage, useHintsDisabled, devToolsStorageKeys, buoyColors } from "@buoy-gg/shared-ui";
 import { DevToolsSettingsModal, useDevToolsSettings } from "../DevToolsSettingsModal";
 import { useIsPro } from "@buoy-gg/license";
 import { useAppHost } from "../AppHost.js";
@@ -55,7 +55,7 @@ export const DialDevTools = ({
   useEffect(() => {
     const loadSettingsModalState = async () => {
       try {
-        const savedModalOpen = await safeGetItem(devToolsStorageKeys.settings.modalOpen());
+        const savedModalOpen = await persistentStorage.getItem(devToolsStorageKeys.settings.modalOpen());
         if (savedModalOpen === "true") {
           setIsSettingsModalOpen(true);
         }
@@ -72,7 +72,7 @@ export const DialDevTools = ({
   useEffect(() => {
     // Only persist after initial state is loaded to avoid overwriting with default
     if (!settingsModalStateLoaded) return;
-    safeSetItem(devToolsStorageKeys.settings.modalOpen(), isSettingsModalOpen ? "true" : "false").catch(error => {
+    persistentStorage.setItem(devToolsStorageKeys.settings.modalOpen(), isSettingsModalOpen ? "true" : "false").catch(error => {
       // Failed to save settings modal state - continue without persistence
       console.warn("Failed to save settings modal state:", error);
     });
@@ -107,7 +107,7 @@ export const DialDevTools = ({
     }
     const checkOnboarding = async () => {
       try {
-        const hasSeenTooltip = await safeGetItem(ONBOARDING_STORAGE_KEY);
+        const hasSeenTooltip = await persistentStorage.getItem(ONBOARDING_STORAGE_KEY);
         if (!hasSeenTooltip) {
           // Small delay to let the entrance animations play first
           setTimeout(() => {
@@ -406,7 +406,7 @@ export const DialDevTools = ({
     setShowOnboardingTooltip(false);
 
     // Save to storage asynchronously in the background
-    safeSetItem(ONBOARDING_STORAGE_KEY, "true").catch(error => {
+    persistentStorage.setItem(ONBOARDING_STORAGE_KEY, "true").catch(error => {
       // Silently fail - user already saw onboarding, just won't persist
       console.warn("Failed to save dial onboarding state:", error);
     });

package/lib/module/floatingMenu/floatingTools.js

@@ -2,7 +2,7 @@
 
 import { useEffect, useMemo, useRef, useState, useContext, createContext, useCallback, Children } from "react";
 import { Animated, Dimensions, View, Text, TouchableOpacity } from "react-native";
-import { getSafeAreaInsets, safeGetItem, safeSetItem, buoyColors } from "@buoy-gg/shared-ui";
+import { getSafeAreaInsets, persistentStorage, buoyColors } from "@buoy-gg/shared-ui";
 import { DraggableHeader } from "./DraggableHeader.js";
 import { useSafeAreaInsets } from "@buoy-gg/shared-ui";
 import { calculateTargetPosition } from "./dial/onboardingConstants.js";
@@ -81,7 +81,13 @@ const STORAGE_KEYS = {
   BUBBLE_POSITION_Y: "@react_buoy_bubble_position_y"
 };
 
-// Debug logging removed for production
+// Position constants
+const VISIBLE_HANDLE_WIDTH = 32;
+const EDGE_PADDING = 20;
+const LAYOUT_SETTLE_DELAY_MS = 150;
+
+/** Helper to get current value from Animated.Value without triggering updates */
+const getAnimatedValue = value => value.__getValue();
 
 // =============================
 // Position persistence hook
@@ -100,8 +106,9 @@ const STORAGE_KEYS = {
  * @param props.enabled - Whether position persistence is enabled
  * @param props.visibleHandleWidth - Width of visible handle when bubble is hidden
  * @param props.listenersSuspended - Pause automatic listeners without disabling manual saves
+ * @param props.onPositionLoaded - Callback fired once position is loaded and set
  *
- * @returns Object containing position management functions
+ * @returns Object containing position management functions and loading state
  *
  * @performance Uses debounced saving to avoid excessive storage operations
  * @performance Validates positions against screen boundaries and safe areas
@@ -112,33 +119,66 @@ function useFloatingToolsPosition({
   bubbleHeight = 32,
   enabled = true,
   visibleHandleWidth = 32,
-  listenersSuspended = false
+  listenersSuspended = false,
+  onPositionLoaded
 }) {
-  const isInitialized = useRef(false);
+  // Use state instead of ref so we can react to changes and prevent races
+  const [isInitialized, setIsInitialized] = useState(false);
   const saveTimeoutRef = useRef(undefined);
+  // Track if component is mounted to prevent state updates after unmount
+  const isMountedRef = useRef(true);
+
+  // Cleanup on unmount - cancel any pending saves
+  useEffect(() => {
+    isMountedRef.current = true;
+    return () => {
+      isMountedRef.current = false;
+      // Clear any pending debounced saves on unmount to prevent saving stale/invalid positions
+      if (saveTimeoutRef.current) {
+        clearTimeout(saveTimeoutRef.current);
+        saveTimeoutRef.current = undefined;
+      }
+    };
+  }, []);
   const savePosition = useCallback(async (x, y) => {
     if (!enabled) return;
+    // Don't save if component unmounted or position is clearly invalid
+    if (!isMountedRef.current) return;
+    // Guard against saving invalid positions (e.g., during HMR with stale dimensions)
+    const {
+      width: screenWidth
+    } = Dimensions.get("window");
+    if (screenWidth <= 0 || x < 0 || y < 0) return;
     try {
-      await Promise.all([safeSetItem(STORAGE_KEYS.BUBBLE_POSITION_X, x.toString()), safeSetItem(STORAGE_KEYS.BUBBLE_POSITION_Y, y.toString())]);
+      await Promise.all([persistentStorage.setItem(STORAGE_KEYS.BUBBLE_POSITION_X, x.toString()), persistentStorage.setItem(STORAGE_KEYS.BUBBLE_POSITION_Y, y.toString())]);
     } catch (error) {
       // Failed to save position - continue without persistence
     }
   }, [enabled]);
   const debouncedSavePosition = useCallback((x, y) => {
+    // Don't schedule saves if unmounted
+    if (!isMountedRef.current) return;
     if (saveTimeoutRef.current) clearTimeout(saveTimeoutRef.current);
-    saveTimeoutRef.current = setTimeout(() => savePosition(x, y), 500);
+    saveTimeoutRef.current = setTimeout(() => {
+      // Double-check mount status before saving
+      if (isMountedRef.current) {
+        savePosition(x, y);
+      }
+    }, 500);
   }, [savePosition]);
   const loadPosition = useCallback(async () => {
     if (!enabled) return null;
     try {
-      const [xStr, yStr] = await Promise.all([safeGetItem(STORAGE_KEYS.BUBBLE_POSITION_X), safeGetItem(STORAGE_KEYS.BUBBLE_POSITION_Y)]);
+      const [xStr, yStr] = await Promise.all([persistentStorage.getItem(STORAGE_KEYS.BUBBLE_POSITION_X), persistentStorage.getItem(STORAGE_KEYS.BUBBLE_POSITION_Y)]);
       if (xStr !== null && yStr !== null) {
         const x = parseFloat(xStr);
         const y = parseFloat(yStr);
-        if (!Number.isNaN(x) && !Number.isNaN(y)) return {
-          x,
-          y
-        };
+        if (!Number.isNaN(x) && !Number.isNaN(y)) {
+          return {
+            x,
+            y
+          };
+        }
       }
     } catch (error) {
       // Failed to load position - use default
@@ -151,62 +191,121 @@ function useFloatingToolsPosition({
       height: screenHeight
     } = Dimensions.get("window");
     const safeArea = getSafeAreaInsets();
+
+    // Guard against invalid screen dimensions (can happen during HMR)
+    // Return the position as-is but mark as invalid so caller knows not to trust it
+    if (screenWidth <= 0 || screenHeight <= 0) {
+      return {
+        ...position,
+        isValid: false
+      };
+    }
+
     // Prevent going off left, top, and bottom edges with safe area
     // Allow pushing off-screen to the right so only the grab handle remains visible
-    const minX = safeArea.left; // Respect safe area left
-    const maxX = screenWidth - visibleHandleWidth; // no right padding, ensure handle is visible
-    // Add small padding below the safe area top to ensure bubble doesn't go behind notch
-    const minY = safeArea.top + 20; // Ensure bubble is below safe area
+    const minX = safeArea.left;
+    const maxX = screenWidth - visibleHandleWidth;
+    // Add padding below the safe area top to ensure bubble doesn't go behind notch
+    const minY = safeArea.top + EDGE_PADDING;
     const maxY = screenHeight - bubbleHeight - safeArea.bottom; // Respect safe area bottom
     const clamped = {
       x: Math.max(minX, Math.min(position.x, maxX)),
-      y: Math.max(minY, Math.min(position.y, maxY))
+      y: Math.max(minY, Math.min(position.y, maxY)),
+      isValid: true
     };
     return clamped;
   }, [visibleHandleWidth, bubbleHeight]);
   useEffect(() => {
-    if (!enabled || isInitialized.current) return;
+    if (!enabled || isInitialized) return;
+    let cancelled = false;
     const restore = async () => {
       const saved = await loadPosition();
+
+      // Check if cancelled or unmounted before updating state
+      if (cancelled || !isMountedRef.current) return;
+      const {
+        width: screenWidth,
+        height: screenHeight
+      } = Dimensions.get("window");
+      const safeArea = getSafeAreaInsets();
+
+      // If dimensions are invalid (HMR scenario), wait and retry
+      if (screenWidth <= 0 || screenHeight <= 0) {
+        // Schedule a retry after a short delay
+        setTimeout(() => {
+          if (isMountedRef.current && !cancelled) {
+            restore();
+          }
+        }, 100);
+        return;
+      }
+      let finalPosition;
+      let wasHidden = false;
       if (saved) {
         const validated = validatePosition(saved);
+
+        // If validation returned invalid, retry later
+        if (!validated.isValid) {
+          setTimeout(() => {
+            if (isMountedRef.current && !cancelled) {
+              restore();
+            }
+          }, 100);
+          return;
+        }
+
         // Check if the saved position is out of bounds
         const wasOutOfBounds = Math.abs(saved.x - validated.x) > 5 || Math.abs(saved.y - validated.y) > 5;
         if (wasOutOfBounds) {
           // Save the corrected position
           await savePosition(validated.x, validated.y);
         }
-        animatedPosition.setValue(validated);
+        finalPosition = {
+          x: validated.x,
+          y: validated.y
+        };
+
+        // Check if loaded in hidden state (bubble pushed to right edge)
+        wasHidden = validated.x >= screenWidth - visibleHandleWidth - 5;
       } else {
-        const {
-          width: screenWidth,
-          height: screenHeight
-        } = Dimensions.get("window");
-        const safeArea = getSafeAreaInsets();
-        const defaultY = Math.max(safeArea.top + 20, Math.min(100, screenHeight - bubbleHeight - safeArea.bottom));
-        animatedPosition.setValue({
-          x: screenWidth - bubbleWidth - 20,
-          y: defaultY // Ensure it's within safe area bounds
-        });
+        const defaultY = Math.max(safeArea.top + EDGE_PADDING, Math.min(100, screenHeight - bubbleHeight - safeArea.bottom));
+        finalPosition = {
+          x: screenWidth - bubbleWidth - EDGE_PADDING,
+          y: defaultY
+        };
       }
-      isInitialized.current = true;
+
+      // Final mount check before updating
+      if (cancelled || !isMountedRef.current) return;
+      animatedPosition.setValue(finalPosition);
+      setIsInitialized(true);
+      onPositionLoaded?.(finalPosition, wasHidden);
     };
     restore();
-  }, [enabled, animatedPosition, loadPosition, validatePosition, savePosition, bubbleWidth, bubbleHeight]);
+    return () => {
+      cancelled = true;
+    };
+  }, [enabled, isInitialized, animatedPosition, loadPosition, validatePosition, savePosition, bubbleWidth, bubbleHeight, visibleHandleWidth, onPositionLoaded]);
+
+  // Listener effect - now properly depends on isInitialized state
   useEffect(() => {
-    if (!enabled || !isInitialized.current || listenersSuspended) return;
+    // Don't attach listener until position is loaded
+    if (!enabled || !isInitialized || listenersSuspended) return;
     const listener = animatedPosition.addListener(value => {
       debouncedSavePosition(value.x, value.y);
     });
     return () => {
       animatedPosition.removeListener(listener);
-      if (saveTimeoutRef.current) clearTimeout(saveTimeoutRef.current);
+      // Clear debounce timer when listener is removed
+      if (saveTimeoutRef.current) {
+        clearTimeout(saveTimeoutRef.current);
+        saveTimeoutRef.current = undefined;
+      }
     };
-  }, [enabled, listenersSuspended, animatedPosition, debouncedSavePosition]);
+  }, [enabled, isInitialized, listenersSuspended, animatedPosition, debouncedSavePosition]);
   return {
     savePosition,
-    loadPosition,
-    isInitialized: isInitialized.current
+    isInitialized
   };
 }
 
@@ -368,7 +467,6 @@ export function FloatingTools({
 }) {
   // Animated position and drag state
   const animatedPosition = useRef(new Animated.ValueXY()).current;
-  const saveTimeoutRef = useRef(null);
   const [isDragging, setIsDragging] = useState(false);
   const [bubbleSize, setBubbleSize] = useState({
     width: 100,
@@ -387,26 +485,44 @@ export function FloatingTools({
 
   // Track previous pushToSide value to detect transitions
   const prevPushToSideRef = useRef(pushToSide);
+
+  // Track previous bubble width for auto-adjustment when tools are added/removed
+  const prevBubbleWidthRef = useRef(null);
+
+  // Track if layout has settled (after initial render cycle completes)
+  const [isLayoutSettled, setIsLayoutSettled] = useState(false);
   const safeAreaInsets = useSafeAreaInsets();
   const {
     width: screenWidth,
     height: screenHeight
   } = Dimensions.get("window");
 
+  // Callback when position is loaded - sets hidden state properly without racing
+  const handlePositionLoaded = useCallback((position, wasHidden) => {
+    if (wasHidden) {
+      setIsHidden(true);
+    }
+  }, []);
+
   // Position persistence (state/IO extracted to hook)
   const {
-    savePosition
+    savePosition,
+    isInitialized: isPositionInitialized
   } = useFloatingToolsPosition({
     animatedPosition,
     bubbleWidth: bubbleSize.width,
     bubbleHeight: bubbleSize.height,
     enabled: enablePositionPersistence,
-    visibleHandleWidth: 32,
-    listenersSuspended: isDragging
+    visibleHandleWidth: VISIBLE_HANDLE_WIDTH,
+    listenersSuspended: isDragging,
+    onPositionLoaded: handlePositionLoaded
   });
 
   // Effect to handle pushToSide prop changes
   useEffect(() => {
+    // Don't process pushToSide until position is initialized (when persistence enabled)
+    if (enablePositionPersistence && !isPositionInitialized) return;
+
     // Reset user override when pushToSide becomes true (dial/modal opens)
     // This allows auto-hide to work after user manually showed the menu
     if (!prevPushToSideRef.current && pushToSide) {
@@ -421,15 +537,15 @@ export function FloatingTools({
     // 4. User hasn't manually restored (userWantsVisibleRef)
     if (pushToSide && !isHidden && !isDragging && !userWantsVisibleRef.current) {
       // Push to side
-      const currentX = animatedPosition.x.__getValue();
-      const currentY = animatedPosition.y.__getValue();
+      const currentX = getAnimatedValue(animatedPosition.x);
+      const currentY = getAnimatedValue(animatedPosition.y);
 
       // Save current position
       savedPositionRef.current = {
         x: currentX,
         y: currentY
       };
-      const hiddenX = screenWidth - 32; // Show only the grabber
+      const hiddenX = screenWidth - VISIBLE_HANDLE_WIDTH;
       isPushedBySideRef.current = true;
       setIsHidden(true);
       Animated.timing(animatedPosition, {
@@ -464,22 +580,92 @@ export function FloatingTools({
         });
       }
     }
-  }, [pushToSide, isHidden, isDragging, screenWidth, animatedPosition, savePosition]);
+  }, [enablePositionPersistence, isPositionInitialized, pushToSide, isHidden, isDragging, screenWidth, animatedPosition, savePosition]);
+
+  // Hidden state is now set via onPositionLoaded callback - no racing effect needed
 
-  // Check if bubble is in hidden position on load
+  // Wait for layout to settle before enabling width tracking
+  // This prevents false-positive width changes during initial render when
+  // the bubble measures multiple times as children render
   useEffect(() => {
-    if (!enablePositionPersistence) return;
-    const checkHiddenState = () => {
-      const currentX = animatedPosition.x.__getValue();
-      // Check if bubble is at the hidden position (showing only grabber)
-      if (currentX >= screenWidth - 32 - 5) {
-        setIsHidden(true);
-      }
-    };
-    // Delay check to ensure position is loaded
-    const timer = setTimeout(checkHiddenState, 100);
+    if (!isPositionInitialized || isLayoutSettled) return;
+    const timer = setTimeout(() => {
+      // Capture the current width as the baseline AFTER layout has settled
+      prevBubbleWidthRef.current = bubbleSize.width;
+      setIsLayoutSettled(true);
+    }, LAYOUT_SETTLE_DELAY_MS);
     return () => clearTimeout(timer);
-  }, [enablePositionPersistence, animatedPosition, screenWidth]);
+  }, [isPositionInitialized, isLayoutSettled, bubbleSize.width]);
+
+  // Auto-adjust position when bubble width changes (tools added/removed)
+  // This keeps the bubble's right edge in the same relative position
+  useEffect(() => {
+    // Skip if position not initialized yet
+    if (!isPositionInitialized) return;
+
+    // Skip until layout has settled (prevents false-positive width changes during initial render)
+    if (!isLayoutSettled) return;
+
+    // Skip if prevBubbleWidthRef hasn't been set yet
+    if (prevBubbleWidthRef.current === null) return;
+
+    // Skip if currently dragging - let drag handle position
+    if (isDragging) {
+      prevBubbleWidthRef.current = bubbleSize.width;
+      return;
+    }
+    const prevWidth = prevBubbleWidthRef.current;
+    const newWidth = bubbleSize.width;
+    const widthDelta = newWidth - prevWidth;
+
+    // Skip if no significant change (avoid jitter)
+    if (Math.abs(widthDelta) < 2) {
+      return;
+    }
+
+    // Update ref first
+    prevBubbleWidthRef.current = newWidth;
+
+    // If hidden, only adjust the saved position (not the current animated position)
+    if (isHidden) {
+      if (savedPositionRef.current) {
+        const adjustedX = savedPositionRef.current.x - widthDelta;
+        // Clamp to valid bounds
+        savedPositionRef.current.x = Math.max(safeAreaInsets.left, Math.min(adjustedX, screenWidth - newWidth - EDGE_PADDING));
+      }
+      return;
+    }
+
+    // Get current position
+    const currentX = getAnimatedValue(animatedPosition.x);
+    const currentY = getAnimatedValue(animatedPosition.y);
+
+    // Calculate new X position
+    // If bubble grew (positive delta), move left (decrease X)
+    // If bubble shrunk (negative delta), move right (increase X)
+    const newX = currentX - widthDelta;
+
+    // Validate new position is within bounds
+    const clampedX = Math.max(safeAreaInsets.left, Math.min(newX, screenWidth - VISIBLE_HANDLE_WIDTH));
+
+    // Only animate if position actually changed
+    if (Math.abs(clampedX - currentX) > 1) {
+      Animated.timing(animatedPosition, {
+        toValue: {
+          x: clampedX,
+          y: currentY
+        },
+        duration: 150,
+        useNativeDriver: false
+      }).start(() => {
+        savePosition(clampedX, currentY);
+        // Update savedPositionRef so show/hide works correctly
+        if (savedPositionRef.current) {
+          savedPositionRef.current.x = clampedX;
+        }
+      });
+    }
+  }, [bubbleSize.width, isPositionInitialized, isLayoutSettled, isDragging, isHidden, animatedPosition, screenWidth, safeAreaInsets.left, savePosition]);
 
   // Default position when persistence disabled or during onboarding
   useEffect(() => {
@@ -496,29 +682,19 @@ export function FloatingTools({
         });
       } else {
         // Default right-side position
-        const defaultY = Math.max(safeAreaInsets.top + 20, Math.min(100, screenHeight - bubbleSize.height - safeAreaInsets.bottom));
+        const defaultY = Math.max(safeAreaInsets.top + EDGE_PADDING, Math.min(100, screenHeight - bubbleSize.height - safeAreaInsets.bottom));
         animatedPosition.setValue({
-          x: screenWidth - bubbleSize.width - 20,
+          x: screenWidth - bubbleSize.width - EDGE_PADDING,
           y: defaultY
         });
       }
     }
   }, [enablePositionPersistence, centerOnboarding, animatedPosition, bubbleSize.width, bubbleSize.height, safeAreaInsets.top, safeAreaInsets.bottom, screenWidth, screenHeight]);
 
-  // Cleanup timeout on component unmount
-  useEffect(() => {
-    return () => {
-      if (saveTimeoutRef.current) {
-        clearTimeout(saveTimeoutRef.current);
-        saveTimeoutRef.current = null;
-      }
-    };
-  }, []);
-
   // Toggle hide/show function
   const toggleHideShow = useCallback(() => {
-    const currentX = animatedPosition.x.__getValue();
-    const currentY = animatedPosition.y.__getValue();
+    const currentX = getAnimatedValue(animatedPosition.x);
+    const currentY = getAnimatedValue(animatedPosition.y);
 
     // Check if the menu is visually off-screen (more than half hidden to the right)
     // This handles edge cases where isHidden state might be out of sync with actual position
@@ -533,7 +709,7 @@ export function FloatingTools({
         targetY = savedPositionRef.current.y;
       } else {
         // Default visible position if no saved position or saved position is off-screen
-        targetX = screenWidth - bubbleSize.width - 20;
+        targetX = screenWidth - bubbleSize.width - EDGE_PADDING;
         targetY = currentY;
       }
 
@@ -560,7 +736,7 @@ export function FloatingTools({
 
       // User explicitly wants the menu hidden
       userWantsVisibleRef.current = false;
-      const hiddenX = screenWidth - 32; // Only show the 32px grabber
+      const hiddenX = screenWidth - VISIBLE_HANDLE_WIDTH;
       setIsHidden(true);
       Animated.timing(animatedPosition, {
         toValue: {
@@ -588,8 +764,20 @@ export function FloatingTools({
     const shouldHide = bubbleMidpoint > screenWidth;
     if (shouldHide) {
       // Animate to hidden position (only grabber visible)
-      const hiddenX = screenWidth - 32; // Only show the 32px grabber
+      const hiddenX = screenWidth - VISIBLE_HANDLE_WIDTH;
       setIsHidden(true);
+
+      // Update savedPositionRef to preserve the Y position when dragging while hidden
+      // This ensures that when showing, the bubble restores to the new Y position
+      if (savedPositionRef.current) {
+        savedPositionRef.current.y = currentY;
+      } else {
+        // If no saved position exists, create one with default visible X
+        savedPositionRef.current = {
+          x: screenWidth - bubbleSize.width - EDGE_PADDING,
+          y: currentY
+        };
+      }
       Animated.timing(animatedPosition, {
         toValue: {
           x: hiddenX,
@@ -602,7 +790,7 @@ export function FloatingTools({
       });
     } else {
       // Check if we're in hidden state and user is pulling it back
-      if (isHidden && currentX < screenWidth - 32 - 10) {
+      if (isHidden && currentX < screenWidth - VISIBLE_HANDLE_WIDTH - 10) {
         setIsHidden(false);
       }
 
@@ -690,6 +878,12 @@ export function FloatingTools({
 
   // Width for the minimized tools stack - match the drag handle width
   const minimizedStackWidth = 32;
+
+  // Don't render until position is initialized (when persistence enabled)
+  // This prevents the bubble from appearing at {0,0} before position loads
+  if (enablePositionPersistence && !isPositionInitialized) {
+    return null;
+  }
   return /*#__PURE__*/_jsx(Animated.View, {
     style: bubbleStyle,
     children: /*#__PURE__*/_jsxs(View, {
@@ -739,7 +933,7 @@ export function FloatingTools({
           elementSize: bubbleSize,
           minPosition: {
             x: safeAreaInsets.left,
-            y: safeAreaInsets.top + 20
+            y: safeAreaInsets.top + EDGE_PADDING
           },
           style: dragHandleStyle,
           enabled: true,

package/lib/module/index.js

@@ -1,5 +1,7 @@
 "use strict";
 
+// Main SDK entry point
+export { Buoy, default as BuoyDefault } from "./Buoy.js";
 // Export unified component - primary interface
 export { FloatingDevTools } from "./floatingMenu/FloatingDevTools";
 // Export auto-discovery utilities
@@ -26,4 +28,4 @@ export { MinimizedToolsStack } from "./floatingMenu/MinimizedToolsStack.js";
 
 // Re-export license functionality from @buoy-gg/license
 // These are re-exported for convenience so users can import from @buoy-gg/core
-export { LicenseManager, useLicense, useFeatureAccess, useSeats, useIsPro, setLicenseKey, isPro, hasEntitlement } from "@buoy-gg/license";
+export { LicenseManager, DeviceRegistrationModal, useLicense, useFeatureAccess, useIsPro, setLicenseKey, isPro, hasEntitlement } from "@buoy-gg/license";

package/lib/typescript/commonjs/Buoy.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Buoy SDK - Main entry point for React Buoy configuration
+ *
+ * Initialize once at app startup, before rendering any components:
+ *
+ * @example
+ * ```tsx
+ * import { Buoy } from '@buoy-gg/core';
+ *
+ * Buoy.init({
+ *   licenseKey: 'YOUR_LICENSE_KEY',
+ * });
+ * ```
+ */
+export interface BuoyConfig {
+    /**
+     * Your Buoy Pro license key
+     * Get one at https://buoy.gg/pricing
+     */
+    licenseKey: string;
+}
+/**
+ * Buoy SDK namespace
+ *
+ * Use `Buoy.init()` to configure your license key at app startup.
+ */
+export declare const Buoy: {
+    /**
+     * Initialize Buoy with your license key
+     *
+     * Call this once at app startup, before rendering FloatingDevTools.
+     * Typically placed in App.tsx or index.js.
+     *
+     * @example
+     * ```tsx
+     * import { Buoy } from '@buoy-gg/core';
+     *
+     * // With hardcoded key
+     * Buoy.init({
+     *   licenseKey: '36063C-27282E-8E73F5-55488F-2213DF-V3',
+     * });
+     *
+     * // With environment variable
+     * Buoy.init({
+     *   licenseKey: process.env.BUOY_LICENSE_KEY!,
+     * });
+     * ```
+     */
+    init(config: BuoyConfig): void;
+    /**
+     * Initialize Buoy asynchronously
+     *
+     * Use this if you need to wait for initialization to complete.
+     *
+     * @example
+     * ```tsx
+     * await Buoy.initAsync({
+     *   licenseKey: 'YOUR_LICENSE_KEY',
+     * });
+     * console.log('Buoy is ready!');
+     * ```
+     */
+    initAsync(config: BuoyConfig): Promise<boolean>;
+    /**
+     * Check if Buoy Pro is active
+     */
+    isPro(): boolean;
+    /**
+     * Get the current license state
+     */
+    getState(): Readonly<import("@buoy-gg/license").LicenseState>;
+    /**
+     * Force device re-registration (debugging helper)
+     * Clears cached fingerprint so next init will register device again
+     */
+    forceReregister(): Promise<void>;
+};
+export default Buoy;
+//# sourceMappingURL=Buoy.d.ts.map

package/lib/typescript/commonjs/Buoy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Buoy.d.ts","sourceRoot":"","sources":["../../../src/Buoy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,eAAO,MAAM,IAAI;IACf;;;;;;;;;;;;;;;;;;;;OAoBG;iBACU,UAAU,GAAG,IAAI;IAc9B;;;;;;;;;;;;OAYG;sBACqB,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;IAUrD;;OAEG;aACM,OAAO;IAIhB;;OAEG;;IAKH;;;OAGG;uBACsB,OAAO,CAAC,IAAI,CAAC;CAGvC,CAAC;AAGF,eAAe,IAAI,CAAC"}