@buoy-gg/shared-ui 7.0.36 → 7.0.39

package/lib/module/ui/floating/FloatingTool.js

@@ -0,0 +1,1003 @@
+"use strict";
+
+import { useEffect, useMemo, useRef, useState, useContext, createContext, useCallback, Children } from "react";
+import { Animated, Dimensions, useWindowDimensions, View, Text, TouchableOpacity } from "react-native";
+import { night } from "../night/nightTheme.js";
+import { DraggableHeader } from "../components/DraggableHeader.js";
+import { EnvironmentSelectorInline } from "../../env/EnvironmentSelectorInline";
+import { GripVerticalIcon } from "../components/GripVerticalIcon.js";
+import { buoyColors } from "../gameUI/constants/gameUIColors.js";
+import { getSafeAreaInsets, persistentStorage } from "../../utils/index.js";
+import { useSafeAreaInsets } from "../../hooks/index.js";
+import { calculateTargetPosition } from "./onboardingConstants";
+
+// Shared utilities from floating-tools-core
+import { getUserStatusConfig as getStatusConfig, filterValidChildren, floatingToolsColors } from "@buoy-gg/floating-tools-core";
+
+// Re-export UserRole type for consumers
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Using Views to render grip dots; no react-native-svg dependency
+
+const STORAGE_KEYS = {
+  BUBBLE_POSITION_X: "@react_buoy_bubble_position_x",
+  BUBBLE_POSITION_Y: "@react_buoy_bubble_position_y"
+};
+
+// 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
+// Extracted logic dedicated to state/IO
+// =============================
+/**
+ * Custom hook for managing floating tools position persistence
+ *
+ * Handles loading, saving, and validating the position of the floating tools bubble
+ * with automatic boundary checking and storage management.
+ *
+ * @param props - Configuration for position management
+ * @param props.animatedPosition - Animated.ValueXY for position updates
+ * @param props.bubbleWidth - Width of the bubble for boundary calculations
+ * @param props.bubbleHeight - Height of the bubble for boundary calculations
+ * @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 and loading state
+ *
+ * @performance Uses debounced saving to avoid excessive storage operations
+ * @performance Validates positions against screen boundaries and safe areas
+ */
+function useFloatingToolsPosition({
+  animatedPosition,
+  bubbleWidth = 100,
+  bubbleHeight = 32,
+  enabled = true,
+  visibleHandleWidth = 32,
+  listenersSuspended = false,
+  defaultPlacement = "top",
+  onPositionLoaded,
+  storageKey
+}) {
+  // 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([persistentStorage.setItem(storageKey ? `${storageKey}:x` : STORAGE_KEYS.BUBBLE_POSITION_X, x.toString()), persistentStorage.setItem(storageKey ? `${storageKey}:y` : STORAGE_KEYS.BUBBLE_POSITION_Y, y.toString())]);
+    } catch (error) {
+      // Failed to save position - continue without persistence
+    }
+  }, [enabled, storageKey]);
+  const debouncedSavePosition = useCallback((x, y) => {
+    // Don't schedule saves if unmounted
+    if (!isMountedRef.current) return;
+    if (saveTimeoutRef.current) clearTimeout(saveTimeoutRef.current);
+    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([persistentStorage.getItem(storageKey ? `${storageKey}:x` : STORAGE_KEYS.BUBBLE_POSITION_X), persistentStorage.getItem(storageKey ? `${storageKey}:y` : 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
+          };
+        }
+      }
+    } catch (error) {
+      // Failed to load position - use default
+    }
+    return null;
+  }, [enabled, storageKey]);
+  const validatePosition = useCallback(position => {
+    const {
+      width: screenWidth,
+      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;
+    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)),
+      isValid: true
+    };
+    return clamped;
+  }, [visibleHandleWidth, bubbleHeight]);
+  useEffect(() => {
+    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);
+        }
+        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 defaultY = defaultPlacement === "bottom" ? Math.max(safeArea.top + EDGE_PADDING, screenHeight - bubbleHeight - safeArea.bottom - EDGE_PADDING) : Math.max(safeArea.top + EDGE_PADDING, Math.min(100, screenHeight - bubbleHeight - safeArea.bottom));
+        finalPosition = {
+          x: screenWidth - bubbleWidth - EDGE_PADDING,
+          y: defaultY
+        };
+      }
+
+      // Final mount check before updating
+      if (cancelled || !isMountedRef.current) return;
+      animatedPosition.setValue(finalPosition);
+      setIsInitialized(true);
+      onPositionLoaded?.(finalPosition, wasHidden);
+    };
+    restore();
+    return () => {
+      cancelled = true;
+    };
+  }, [enabled, isInitialized, animatedPosition, loadPosition, validatePosition, savePosition, bubbleWidth, bubbleHeight, visibleHandleWidth, onPositionLoaded]);
+
+  // Listener effect - now properly depends on isInitialized state
+  useEffect(() => {
+    // 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);
+      // Clear debounce timer when listener is removed
+      if (saveTimeoutRef.current) {
+        clearTimeout(saveTimeoutRef.current);
+        saveTimeoutRef.current = undefined;
+      }
+    };
+  }, [enabled, isInitialized, listenersSuspended, animatedPosition, debouncedSavePosition]);
+  return {
+    savePosition,
+    isInitialized
+  };
+}
+
+// =============================
+// UI-only leaf components
+// =============================
+export function Divider() {
+  const dividerStyle = {
+    width: 1,
+    height: 12,
+    backgroundColor: buoyColors.textMuted + "66",
+    flexShrink: 0
+  };
+  return /*#__PURE__*/_jsx(View, {
+    style: dividerStyle
+  });
+}
+
+// Use shared getUserStatusConfig from floating-tools-core
+// Wraps the core function to use our buoyColors (mapped to gameUIColors format)
+const gameUIColorsCompat = {
+  success: "#20C997",
+  // teal
+  warning: "#FFA94D",
+  error: "#EF4444",
+  muted: buoyColors.textMuted,
+  secondary: buoyColors.textSecondary,
+  info: "#20C997",
+  // teal
+  primary: "#20C997",
+  optional: buoyColors.textSecondary // optional status color
+};
+function getUserStatusConfig(userRole) {
+  return getStatusConfig(userRole, gameUIColorsCompat);
+}
+
+// Context to avoid brittle prop threading and keep API composable
+const FloatingToolsContext = /*#__PURE__*/createContext({
+  isDragging: false
+});
+export function UserStatus({
+  userRole,
+  onPress
+}) {
+  const {
+    isDragging
+  } = useContext(FloatingToolsContext);
+  const config = getUserStatusConfig(userRole);
+  const containerStyle = {
+    flexDirection: "row",
+    alignItems: "center",
+    paddingVertical: 6,
+    paddingHorizontal: 8,
+    flexShrink: 0
+  };
+  const dotStyle = {
+    width: 6,
+    height: 6,
+    borderRadius: 3,
+    backgroundColor: config.dotColor,
+    marginRight: 4
+  };
+  const textStyle = {
+    fontSize: 10,
+    fontWeight: "500",
+    color: config.textColor,
+    letterSpacing: 0.3
+  };
+  if (!onPress) {
+    return /*#__PURE__*/_jsxs(View, {
+      style: containerStyle,
+      accessibilityLabel: `User status: ${config.label}`,
+      children: [/*#__PURE__*/_jsx(View, {
+        style: dotStyle
+      }), /*#__PURE__*/_jsx(Text, {
+        style: textStyle,
+        children: config.label
+      })]
+    });
+  }
+  return /*#__PURE__*/_jsxs(TouchableOpacity, {
+    accessibilityRole: "button",
+    accessibilityLabel: "Open Dev Tools Menu",
+    testID: "open-dev-tools-button",
+    onPress: onPress,
+    hitSlop: {
+      top: 10,
+      bottom: 10,
+      left: 0,
+      right: 10
+    },
+    disabled: isDragging,
+    activeOpacity: 0.85,
+    style: containerStyle,
+    children: [/*#__PURE__*/_jsx(View, {
+      style: dotStyle
+    }), /*#__PURE__*/_jsx(Text, {
+      style: textStyle,
+      children: config.label
+    })]
+  });
+}
+
+// =============================
+// Helpers (using shared filterValidChildren from core)
+// =============================
+function interleaveWithDividers(childrenArray) {
+  const validChildren = filterValidChildren(childrenArray);
+  const result = [];
+  validChildren.forEach((child, index) => {
+    result.push(child);
+    if (index < validChildren.length - 1) result.push(/*#__PURE__*/_jsx(Divider, {}, `divider-${index}`));
+  });
+  return result;
+}
+
+// =============================
+// Main Component (presentation only)
+// =============================
+
+/**
+ * FloatingTools - A draggable, resizable bubble for development tools
+ *
+ * This component provides a floating bubble interface that can contain various
+ * development tools and controls. It features:
+ * - Drag and drop positioning with boundary constraints
+ * - Hide/show functionality by dragging to screen edge
+ * - Position persistence across app restarts
+ * - Safe area aware positioning
+ * - Automatic divider insertion between child components
+ *
+ * @param props - Configuration for the floating tools
+ * @param props.enablePositionPersistence - Whether to save/restore position (default: true)
+ * @param props.children - Child components to render in the bubble
+ *
+ * @returns JSX.Element representing the floating tools bubble
+ *
+ * @example
+ * ```typescript
+ * <FloatingTools enablePositionPersistence={true}>
+ *   <UserStatus userRole="admin" onPress={handleUserPress} />
+ *   <ToolButton onPress={openSettings} />
+ * </FloatingTools>
+ * ```
+ *
+ * @performance Uses native driver animations for smooth positioning
+ * @performance Implements efficient boundary checking and position validation
+ * @performance Includes debounced position saving for optimal storage performance
+ */
+export function FloatingTool({
+  id,
+  suspendPointerEvents = false,
+  revealToken,
+  variant = "bubble",
+  dragFromSurface = false,
+  accessibilityLabel = "Move dev tools bubble",
+  minimizedStack,
+  hasMinimizedStack = false,
+  accessory,
+  handleAdornment,
+  enablePositionPersistence = true,
+  defaultPlacement = "top",
+  pushToSide = false,
+  centerOnboarding = false,
+  children,
+  environment,
+  availableEnvironments,
+  onEnvironmentSwitch,
+  showEnvironmentSelector = false
+}) {
+  // Animated position and drag state
+  const animatedPosition = useRef(new Animated.ValueXY()).current;
+  const [isDragging, setIsDragging] = useState(false);
+  const [bubbleSize, setBubbleSize] = useState({
+    width: 100,
+    height: 32
+  });
+  const [isHidden, setIsHidden] = useState(false);
+  const [accessoryHeight, setAccessoryHeight] = useState(0);
+  const [accessoryAbove, setAccessoryAbove] = useState(false);
+
+  // Store the position before hiding to restore when showing
+  const savedPositionRef = useRef(null);
+
+  // Track if the hide state was triggered by pushToSide prop vs user toggle
+  const isPushedBySideRef = useRef(false);
+
+  // Track if user has explicitly chosen to show the menu (overriding pushToSide)
+  const userWantsVisibleRef = useRef(false);
+
+  // 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
+  } = useWindowDimensions();
+
+  // 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,
+    isInitialized: isPositionInitialized
+  } = useFloatingToolsPosition({
+    animatedPosition,
+    bubbleWidth: bubbleSize.width,
+    bubbleHeight: bubbleSize.height,
+    enabled: enablePositionPersistence,
+    visibleHandleWidth: VISIBLE_HANDLE_WIDTH,
+    listenersSuspended: isDragging,
+    defaultPlacement,
+    onPositionLoaded: handlePositionLoaded,
+    storageKey: id ? `@buoy/floating-tool/${id}` : undefined
+  });
+
+  // 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) {
+      userWantsVisibleRef.current = false;
+    }
+    prevPushToSideRef.current = pushToSide;
+
+    // Only push to side if:
+    // 1. pushToSide is true
+    // 2. Not currently hidden
+    // 3. Not being dragged
+    // 4. User hasn't manually restored (userWantsVisibleRef)
+    if (pushToSide && !isHidden && !isDragging && !userWantsVisibleRef.current) {
+      // Push to side
+      const currentX = getAnimatedValue(animatedPosition.x);
+      const currentY = getAnimatedValue(animatedPosition.y);
+
+      // Save current position
+      savedPositionRef.current = {
+        x: currentX,
+        y: currentY
+      };
+      const hiddenX = screenWidth - VISIBLE_HANDLE_WIDTH;
+      isPushedBySideRef.current = true;
+      setIsHidden(true);
+      Animated.timing(animatedPosition, {
+        toValue: {
+          x: hiddenX,
+          y: currentY
+        },
+        duration: 200,
+        useNativeDriver: false
+      }).start(() => {
+        savePosition(hiddenX, currentY);
+      });
+    } else if (!pushToSide && isHidden && isPushedBySideRef.current) {
+      // Restore from side when pushToSide becomes false
+      if (savedPositionRef.current) {
+        const {
+          x: targetX,
+          y: targetY
+        } = savedPositionRef.current;
+        isPushedBySideRef.current = false;
+        userWantsVisibleRef.current = false; // Reset user override when tools close
+        setIsHidden(false);
+        Animated.timing(animatedPosition, {
+          toValue: {
+            x: targetX,
+            y: targetY
+          },
+          duration: 200,
+          useNativeDriver: false
+        }).start(() => {
+          savePosition(targetX, targetY);
+        });
+      }
+    }
+  }, [enablePositionPersistence, isPositionInitialized, pushToSide, isHidden, isDragging, screenWidth, animatedPosition, savePosition]);
+
+  // Hidden state is now set via onPositionLoaded callback - no racing effect needed
+
+  // 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 (!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);
+  }, [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(() => {
+    if (!enablePositionPersistence) {
+      if (centerOnboarding) {
+        // Center the bubble for onboarding - position under tooltip arrow
+        // Use shared calculation to ensure perfect alignment across all screens
+        const bottomOffset = calculateTargetPosition();
+        const centerX = (screenWidth - bubbleSize.width) / 2;
+        const centerY = screenHeight - bubbleSize.height - bottomOffset;
+        animatedPosition.setValue({
+          x: centerX,
+          y: centerY
+        });
+      } else {
+        // Default right-side position
+        const defaultY = defaultPlacement === "bottom" ? Math.max(safeAreaInsets.top + EDGE_PADDING, screenHeight - bubbleSize.height - safeAreaInsets.bottom - EDGE_PADDING) : Math.max(safeAreaInsets.top + EDGE_PADDING, Math.min(100, screenHeight - bubbleSize.height - safeAreaInsets.bottom));
+        animatedPosition.setValue({
+          x: screenWidth - bubbleSize.width - EDGE_PADDING,
+          y: defaultY
+        });
+      }
+    }
+  }, [enablePositionPersistence, centerOnboarding, animatedPosition, bubbleSize.width, bubbleSize.height, safeAreaInsets.top, safeAreaInsets.bottom, screenWidth, screenHeight]);
+
+  // Toggle hide/show function
+  const toggleHideShow = useCallback(() => {
+    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
+    const isVisuallyOffScreen = currentX > screenWidth - bubbleSize.width / 2;
+    if (isHidden || isVisuallyOffScreen) {
+      // Show the bubble - restore to saved position or default visible position
+      let targetX;
+      let targetY;
+      if (savedPositionRef.current && savedPositionRef.current.x < screenWidth - bubbleSize.width / 2) {
+        // Restore to the saved position only if it's a valid visible position
+        targetX = savedPositionRef.current.x;
+        targetY = savedPositionRef.current.y;
+      } else {
+        // Default visible position if no saved position or saved position is off-screen
+        targetX = screenWidth - bubbleSize.width - EDGE_PADDING;
+        targetY = currentY;
+      }
+
+      // User explicitly wants the menu visible (overrides pushToSide)
+      isPushedBySideRef.current = false;
+      userWantsVisibleRef.current = true;
+      setIsHidden(false);
+      Animated.timing(animatedPosition, {
+        toValue: {
+          x: targetX,
+          y: targetY
+        },
+        duration: 200,
+        useNativeDriver: false
+      }).start(() => {
+        savePosition(targetX, targetY);
+      });
+    } else {
+      // Hide the bubble - save current position before hiding
+      savedPositionRef.current = {
+        x: currentX,
+        y: currentY
+      };
+
+      // User explicitly wants the menu hidden
+      userWantsVisibleRef.current = false;
+      const hiddenX = screenWidth - VISIBLE_HANDLE_WIDTH;
+      setIsHidden(true);
+      Animated.timing(animatedPosition, {
+        toValue: {
+          x: hiddenX,
+          y: currentY
+        },
+        duration: 200,
+        useNativeDriver: false
+      }).start(() => {
+        savePosition(hiddenX, currentY);
+      });
+    }
+  }, [animatedPosition, isHidden, bubbleSize.width, savePosition, screenWidth]);
+  const handleDragStart = useCallback(() => {
+    setIsDragging(true);
+  }, []);
+  const handleDragEnd = useCallback(finalPosition => {
+    let {
+      x: currentX,
+      y: currentY
+    } = finalPosition;
+
+    // Check if bubble is more than 50% over the right edge
+    const bubbleMidpoint = currentX + bubbleSize.width / 2;
+    const shouldHide = bubbleMidpoint > screenWidth;
+    if (shouldHide) {
+      // Animate to hidden position (only grabber visible)
+      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,
+          y: currentY
+        },
+        duration: 200,
+        useNativeDriver: false
+      }).start(() => {
+        savePosition(hiddenX, currentY);
+      });
+    } else {
+      // Check if we're in hidden state and user is pulling it back
+      if (isHidden && currentX < screenWidth - VISIBLE_HANDLE_WIDTH - 10) {
+        setIsHidden(false);
+      }
+
+      // Update saved position if bubble is in visible area (not hidden)
+      if (currentX < screenWidth - bubbleSize.width / 2) {
+        savedPositionRef.current = {
+          x: currentX,
+          y: currentY
+        };
+      }
+      savePosition(currentX, currentY);
+    }
+    setIsDragging(false);
+  }, [animatedPosition, bubbleSize.width, isHidden, savePosition, screenWidth]);
+  const lastViewport = useRef({
+    width: screenWidth,
+    height: screenHeight
+  });
+  useEffect(() => {
+    if (enablePositionPersistence && !isPositionInitialized) return;
+    if (lastViewport.current.width === screenWidth && lastViewport.current.height === screenHeight) return;
+    lastViewport.current = {
+      width: screenWidth,
+      height: screenHeight
+    };
+    const clamp = point => ({
+      x: Math.max(safeAreaInsets.left, Math.min(point.x, screenWidth - bubbleSize.width - EDGE_PADDING)),
+      y: Math.max(safeAreaInsets.top + EDGE_PADDING, Math.min(point.y, screenHeight - bubbleSize.height - safeAreaInsets.bottom))
+    });
+    const current = clamp({
+      x: getAnimatedValue(animatedPosition.x),
+      y: getAnimatedValue(animatedPosition.y)
+    });
+    if (isHidden) current.x = screenWidth - VISIBLE_HANDLE_WIDTH;
+    if (savedPositionRef.current) savedPositionRef.current = clamp(savedPositionRef.current);
+    animatedPosition.stopAnimation();
+    animatedPosition.setValue(current);
+    void savePosition(current.x, current.y);
+  }, [screenWidth, screenHeight, isPositionInitialized, enablePositionPersistence, bubbleSize, safeAreaInsets, isHidden, animatedPosition, savePosition]);
+  const hasAccessory = Boolean(accessory);
+  useEffect(() => {
+    if (!hasAccessory) return;
+    const update = ({
+      y
+    }) => setAccessoryAbove(y + bubbleSize.height + accessoryHeight > screenHeight - safeAreaInsets.bottom);
+    update({
+      y: getAnimatedValue(animatedPosition.y)
+    });
+    const listener = animatedPosition.addListener(update);
+    return () => animatedPosition.removeListener(listener);
+  }, [animatedPosition, bubbleSize.height, accessoryHeight, screenHeight, safeAreaInsets.bottom, hasAccessory]);
+
+  // Stable styles
+  const bubbleStyle = useMemo(() => ({
+    position: "absolute",
+    zIndex: 1001,
+    transform: animatedPosition.getTranslateTransform()
+  }), [animatedPosition]);
+  const previousReveal = useRef(undefined);
+  useEffect(() => {
+    if (enablePositionPersistence && !isPositionInitialized) return;
+    if (previousReveal.current === revealToken) return;
+    previousReveal.current = revealToken;
+    if (revealToken !== undefined && revealToken > 0 && isHidden) toggleHideShow();
+  }, [revealToken, isPositionInitialized, enablePositionPersistence, isHidden, toggleHideShow]);
+  const hasMinimizedTools = hasMinimizedStack;
+  const containerStyle = {
+    flexDirection: "row",
+    alignItems: "center",
+    backgroundColor: buoyColors.card,
+    // When minimized tools showing, remove top-left radius so they connect seamlessly
+    borderTopLeftRadius: hasMinimizedTools ? 0 : 6,
+    borderTopRightRadius: 6,
+    borderBottomLeftRadius: 6,
+    borderBottomRightRadius: 6,
+    // Use individual border widths when minimized tools are showing
+    // Always show top border when dragging for visual feedback
+    borderLeftWidth: isDragging ? 2 : 1,
+    borderRightWidth: isDragging ? 2 : 1,
+    borderBottomWidth: isDragging ? 2 : 1,
+    borderTopWidth: isDragging ? 2 : hasMinimizedTools ? 0 : 1,
+    borderColor: isDragging ? floatingToolsColors.dragActive : buoyColors.textMuted + "66",
+    overflow: "visible",
+    elevation: 8,
+    shadowColor: isDragging ? floatingToolsColors.dragActive + "99" : "#000",
+    shadowOffset: {
+      width: 0,
+      height: isDragging ? 6 : 4
+    },
+    shadowOpacity: isDragging ? 0.6 : 0.3,
+    shadowRadius: isDragging ? 12 : 8,
+    ...(variant === "strip" ? {
+      borderRadius: night.radius.card,
+      borderTopLeftRadius: night.radius.card,
+      borderTopRightRadius: night.radius.card,
+      borderBottomLeftRadius: night.radius.card,
+      borderBottomRightRadius: night.radius.card,
+      minHeight: 48,
+      backgroundColor: night.color.surface,
+      borderColor: isDragging ? night.color.accentBorderStrong : night.color.separator,
+      shadowOpacity: 0.24,
+      shadowRadius: 16
+    } : {})
+  };
+  const dragHandleStyle = {
+    paddingHorizontal: 6,
+    paddingVertical: 6,
+    backgroundColor: buoyColors.textMuted + "1A",
+    alignItems: "center",
+    justifyContent: "center",
+    width: 32,
+    ...(variant === "strip" ? {
+      minHeight: 48
+    } : {}),
+    borderRightWidth: 1,
+    borderRightColor: buoyColors.textMuted + "66",
+    // Remove top-left radius when minimized tools are showing
+    borderTopLeftRadius: hasMinimizedTools ? 0 : undefined,
+    ...(variant === "strip" ? {
+      backgroundColor: "transparent",
+      borderRightWidth: 0
+    } : {})
+  };
+  const contentStyle = {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 6,
+    paddingRight: 8
+  };
+
+  // Compose actions row with automatic dividers
+  const actions = useMemo(() => variant === "strip" ? Children.toArray(children) : interleaveWithDividers(Children.toArray(children)), [children, variant]);
+
+  // 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, {
+    pointerEvents: suspendPointerEvents ? "none" : "box-none",
+    testID: id ?? "buoy-floating-tool",
+    style: bubbleStyle,
+    children: /*#__PURE__*/_jsxs(View, {
+      style: {
+        overflow: "visible"
+      },
+      children: [minimizedStack && /*#__PURE__*/_jsx(View, {
+        style: {
+          position: "absolute",
+          bottom: "100%",
+          left: 0,
+          width: minimizedStackWidth,
+          overflow: "visible",
+          zIndex: 1001
+        },
+        children: minimizedStack
+      }), /*#__PURE__*/_jsxs(DraggableHeader, {
+        position: animatedPosition,
+        enabled: dragFromSurface,
+        claimOnMove: false,
+        onDragStart: handleDragStart,
+        onDragEnd: handleDragEnd,
+        containerBounds: {
+          width: screenWidth,
+          height: screenHeight
+        },
+        elementSize: bubbleSize,
+        minPosition: {
+          x: safeAreaInsets.left,
+          y: safeAreaInsets.top + EDGE_PADDING
+        },
+        maxOverflowX: bubbleSize.width,
+        hitSlop: {
+          top: 10,
+          bottom: 10,
+          left: 10,
+          right: 10
+        },
+        style: containerStyle,
+        onLayout: event => {
+          const {
+            width,
+            height
+          } = event.nativeEvent.layout;
+          setBubbleSize({
+            width,
+            height
+          });
+        },
+        children: [/*#__PURE__*/_jsxs(DraggableHeader, {
+          position: animatedPosition,
+          testID: id ? `${id}-grip` : "buoy-floating-grip",
+          accessibilityLabel: accessibilityLabel,
+          onDragStart: handleDragStart,
+          onDragEnd: handleDragEnd,
+          onTap: toggleHideShow,
+          containerBounds: {
+            width: screenWidth,
+            height: screenHeight
+          },
+          elementSize: bubbleSize,
+          minPosition: {
+            x: safeAreaInsets.left,
+            y: safeAreaInsets.top + EDGE_PADDING
+          },
+          style: dragHandleStyle,
+          enabled: true,
+          maxOverflowX: bubbleSize.width,
+          children: [/*#__PURE__*/_jsx(GripVerticalIcon, {
+            size: variant === "strip" ? 20 : 12,
+            color: buoyColors.textSecondary + "CC"
+          }), handleAdornment]
+        }), /*#__PURE__*/_jsx(FloatingToolsContext.Provider, {
+          value: {
+            isDragging
+          },
+          children: /*#__PURE__*/_jsxs(View, {
+            style: contentStyle,
+            children: [showEnvironmentSelector && environment && availableEnvironments && onEnvironmentSwitch && /*#__PURE__*/_jsx(EnvironmentSelectorInline, {
+              currentEnvironment: environment,
+              availableEnvironments: availableEnvironments,
+              onSelect: onEnvironmentSwitch
+            }), actions]
+          })
+        })]
+      }), !isHidden && accessory && /*#__PURE__*/_jsx(View, {
+        onLayout: event => setAccessoryHeight(event.nativeEvent.layout.height),
+        style: {
+          position: "absolute",
+          ...(accessoryAbove ? {
+            bottom: "100%"
+          } : {
+            top: "100%"
+          }),
+          left: 0,
+          width: "100%",
+          zIndex: 1002
+        },
+        children: accessory
+      })]
+    })
+  });
+}
+
+/** Native AppHost gets its anchor from the minimized-tools provider. */
+export function getBubbleAnchorPosition() {
+  return null;
+}