@buoy-gg/floating-tools-core 7.0.38 → 7.0.40

package/lib/module/FloatingToolsStore.js

@@ -1 +1,507 @@
-"use strict";import{VISIBLE_HANDLE_WIDTH,DRAG_THRESHOLD,EDGE_PADDING,SAVE_DEBOUNCE_MS,STORAGE_KEYS}from"./constants.js";export class FloatingToolsStore{isDragging=!1;isHidden=!1;dragStartPos={x:0,y:0};dragStartMouse={x:0,y:0};hasMoved=!1;savedPosition=null;saveTimeout=null;isInitialized=!1;listeners=new Set;constructor(i){this.screenWidth=i.screenWidth,this.screenHeight=i.screenHeight,this.bubbleSize=i.initialBubbleSize??{width:100,height:32},this.minPosition=i.minPosition??{x:EDGE_PADDING,y:EDGE_PADDING},this.visibleHandleWidth=i.visibleHandleWidth??VISIBLE_HANDLE_WIDTH,this.dragThreshold=i.dragThreshold??DRAG_THRESHOLD,this.edgePadding=i.edgePadding??EDGE_PADDING,this.enablePositionPersistence=i.enablePositionPersistence??!0,this.storage=i.storage,this.onPositionChange=i.onPositionChange,this.onHiddenChange=i.onHiddenChange,this.onDraggingChange=i.onDraggingChange,this.position=i.initialPosition??{x:this.screenWidth-this.bubbleSize.width-20,y:Math.max(this.minPosition.y,Math.min(100,this.screenHeight-this.bubbleSize.height-this.edgePadding))},this.stateSnapshot=this.createSnapshot()}subscribe=i=>(this.listeners.add(i),()=>this.listeners.delete(i));getSnapshot=()=>this.stateSnapshot;createSnapshot(){return{position:{...this.position},isDragging:this.isDragging,isHidden:this.isHidden,bubbleSize:{...this.bubbleSize}}}notify(){this.stateSnapshot=this.createSnapshot(),this.listeners.forEach(i=>i())}async initialize(){if(!this.isInitialized&&this.enablePositionPersistence&&this.storage){try{const[i,t]=await Promise.all([this.storage.getItem(STORAGE_KEYS.POSITION_X),this.storage.getItem(STORAGE_KEYS.POSITION_Y)]);if(null!==i&&null!==t){const s=parseFloat(i),e=parseFloat(t);if(!Number.isNaN(s)&&!Number.isNaN(e)){const i={x:s,y:e},t=this.validatePosition(i);(Math.abs(i.x-t.x)>5||Math.abs(i.y-t.y)>5)&&this.savePosition(t.x,t.y),this.position=t,t.x>=this.screenWidth-this.visibleHandleWidth-5&&(this.isHidden=!0),this.notify()}}}catch{}this.isInitialized=!0}else this.isInitialized=!0}getBounds(){return{minX:this.minPosition.x,maxX:this.screenWidth-this.visibleHandleWidth,minY:this.minPosition.y,maxY:this.screenHeight-this.bubbleSize.height-this.edgePadding}}validatePosition(i){const t=this.getBounds();return{x:Math.max(t.minX,Math.min(i.x,t.maxX)),y:Math.max(t.minY,Math.min(i.y,t.maxY))}}setPosition(i){this.position=i,this.onPositionChange?.(i),this.notify()}setBubbleSize(i){this.bubbleSize.width===i.width&&this.bubbleSize.height===i.height||(this.bubbleSize=i,this.isDragging||this.reconcileBounds(),this.notify())}setScreenSize(i,t){this.screenWidth=i,this.screenHeight=t,this.reconcileBounds(),this.notify()}reconcileBounds(){const i=i=>({x:Math.max(this.minPosition.x,Math.min(i.x,this.screenWidth-this.bubbleSize.width-this.edgePadding)),y:Math.max(this.minPosition.y,Math.min(i.y,this.screenHeight-this.bubbleSize.height-this.edgePadding))}),t=i(this.position);this.position=this.isHidden?{...t,x:this.screenWidth-this.visibleHandleWidth}:t,this.savedPosition&&(this.savedPosition=i(this.savedPosition))}setMinPosition(i){this.minPosition=i}async savePosition(i,t){if(this.enablePositionPersistence&&this.storage)try{await Promise.all([this.storage.setItem(STORAGE_KEYS.POSITION_X,i.toString()),this.storage.setItem(STORAGE_KEYS.POSITION_Y,t.toString())])}catch{}}debouncedSavePosition(i,t){this.saveTimeout&&clearTimeout(this.saveTimeout),this.saveTimeout=setTimeout(()=>this.savePosition(i,t),SAVE_DEBOUNCE_MS)}toggleHideShow(){const i=this.position.x>this.screenWidth-this.bubbleSize.width/2;if(this.isHidden||i){let i,t;return this.savedPosition&&this.savedPosition.x<this.screenWidth-this.bubbleSize.width/2?(i=this.savedPosition.x,t=this.savedPosition.y):(i=this.screenWidth-this.bubbleSize.width-20,t=this.position.y),this.isHidden=!1,this.onHiddenChange?.(!1),this.notify(),{targetPosition:{x:i,y:t},isHiding:!1}}{this.savedPosition={...this.position};const i=this.screenWidth-this.visibleHandleWidth;return this.isHidden=!0,this.onHiddenChange?.(!0),this.notify(),{targetPosition:{x:i,y:this.position.y},isHiding:!0}}}forceHide(){if(this.isHidden)return{targetPosition:this.position};this.savedPosition={...this.position};const i=this.screenWidth-this.visibleHandleWidth;return this.isHidden=!0,this.onHiddenChange?.(!0),this.notify(),{targetPosition:{x:i,y:this.position.y}}}forceShow(){if(!this.isHidden)return{targetPosition:this.position};let i,t;return this.savedPosition?(i=this.savedPosition.x,t=this.savedPosition.y):(i=this.screenWidth-this.bubbleSize.width-20,t=this.position.y),this.isHidden=!1,this.onHiddenChange?.(!1),this.notify(),{targetPosition:{x:i,y:t}}}handleDragStart(i){this.hasMoved=!1,this.dragStartPos={...this.position},this.dragStartMouse={x:i.clientX,y:i.clientY}}handleDragMove(i){const t=i.clientX-this.dragStartMouse.x,s=i.clientY-this.dragStartMouse.y,e=Math.abs(t)+Math.abs(s);if(!this.hasMoved&&e>this.dragThreshold&&(this.hasMoved=!0,this.isDragging=!0,this.onDraggingChange?.(!0),this.notify()),this.hasMoved){const i=this.dragStartPos.x+t,e=this.dragStartPos.y+s,h=this.getBounds(),n=Math.max(h.minX,Math.min(i,this.screenWidth-this.visibleHandleWidth+this.bubbleSize.width)),o=Math.max(h.minY,Math.min(e,h.maxY));return this.position={x:n,y:o},this.onPositionChange?.(this.position),this.notify(),{position:this.position,isDragging:!0}}return{position:this.position,isDragging:!1}}handleDragEnd(i){if(!this.hasMoved)return this.isDragging=!1,this.onDraggingChange?.(!1),this.notify(),{position:this.position,shouldHide:!1,wasTap:!0};const t=i.clientX-this.dragStartMouse.x,s=i.clientY-this.dragStartMouse.y,e=this.dragStartPos.x+t,h=this.dragStartPos.y+s,n=e+this.bubbleSize.width/2>this.screenWidth,o=this.getBounds();if(n){const i=this.screenWidth-this.visibleHandleWidth,t=Math.max(o.minY,Math.min(h,o.maxY));return this.isHidden=!0,this.onHiddenChange?.(!0),this.isDragging=!1,this.onDraggingChange?.(!1),this.notify(),{position:{x:i,y:t},shouldHide:!0,wasTap:!1}}{this.isHidden&&e<this.screenWidth-this.visibleHandleWidth-10&&(this.isHidden=!1,this.onHiddenChange?.(!1));const i=Math.max(o.minX,Math.min(e,this.screenWidth-this.bubbleSize.width-this.edgePadding)),t=Math.max(o.minY,Math.min(h,o.maxY));return i<this.screenWidth-this.bubbleSize.width/2&&(this.savedPosition={x:i,y:t}),this.position={x:i,y:t},this.isDragging=!1,this.onDraggingChange?.(!1),this.debouncedSavePosition(i,t),this.notify(),{position:{x:i,y:t},shouldHide:!1,wasTap:!1}}}commitPosition(i){this.position=i,this.savePosition(i.x,i.y),this.notify()}destroy(){this.saveTimeout&&(clearTimeout(this.saveTimeout),this.saveTimeout=null),this.listeners.clear()}}
+"use strict";
+
+/**
+ * FloatingToolsStore - Headless state management for floating tools.
+ *
+ * This class manages all the business logic for the floating tools bubble:
+ * - Position state and validation
+ * - Drag detection (tap vs drag)
+ * - Hide/show toggle
+ * - Auto-hide when dragged past edge
+ * - Position persistence
+ *
+ * Platform-specific code (animation, event handling) is NOT included here.
+ * Use this with platform-specific hooks/bindings.
+ */
+
+import { VISIBLE_HANDLE_WIDTH, DRAG_THRESHOLD, EDGE_PADDING, SAVE_DEBOUNCE_MS, STORAGE_KEYS } from "./constants.js";
+export class FloatingToolsStore {
+  // State
+
+  isDragging = false;
+  isHidden = false;
+
+  // Configuration
+
+  // Callbacks
+
+  // Drag tracking
+  dragStartPos = {
+    x: 0,
+    y: 0
+  };
+  dragStartMouse = {
+    x: 0,
+    y: 0
+  };
+  hasMoved = false;
+  savedPosition = null;
+
+  // Persistence
+  saveTimeout = null;
+  isInitialized = false;
+
+  // Subscribers (for useSyncExternalStore)
+  listeners = new Set();
+  constructor(options) {
+    this.screenWidth = options.screenWidth;
+    this.screenHeight = options.screenHeight;
+    this.bubbleSize = options.initialBubbleSize ?? {
+      width: 100,
+      height: 32
+    };
+    this.minPosition = options.minPosition ?? {
+      x: EDGE_PADDING,
+      y: EDGE_PADDING
+    };
+    this.visibleHandleWidth = options.visibleHandleWidth ?? VISIBLE_HANDLE_WIDTH;
+    this.dragThreshold = options.dragThreshold ?? DRAG_THRESHOLD;
+    this.edgePadding = options.edgePadding ?? EDGE_PADDING;
+    this.enablePositionPersistence = options.enablePositionPersistence ?? true;
+    this.storage = options.storage;
+    this.onPositionChange = options.onPositionChange;
+    this.onHiddenChange = options.onHiddenChange;
+    this.onDraggingChange = options.onDraggingChange;
+
+    // Default position
+    this.position = options.initialPosition ?? {
+      x: this.screenWidth - this.bubbleSize.width - 20,
+      y: Math.max(this.minPosition.y, Math.min(100, this.screenHeight - this.bubbleSize.height - this.edgePadding))
+    };
+
+    // Initialize snapshot
+    this.stateSnapshot = this.createSnapshot();
+  }
+
+  // =============================
+  // Subscription (for React hooks)
+  // =============================
+
+  subscribe = listener => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+  getSnapshot = () => {
+    return this.stateSnapshot;
+  };
+  createSnapshot() {
+    return {
+      position: {
+        ...this.position
+      },
+      isDragging: this.isDragging,
+      isHidden: this.isHidden,
+      bubbleSize: {
+        ...this.bubbleSize
+      }
+    };
+  }
+  notify() {
+    this.stateSnapshot = this.createSnapshot();
+    this.listeners.forEach(listener => listener());
+  }
+
+  // =============================
+  // Initialization
+  // =============================
+
+  /**
+   * Initialize the store by loading persisted position.
+   * Call this after setting up storage adapter.
+   */
+  async initialize() {
+    if (this.isInitialized || !this.enablePositionPersistence || !this.storage) {
+      this.isInitialized = true;
+      return;
+    }
+    try {
+      const [xStr, yStr] = await Promise.all([this.storage.getItem(STORAGE_KEYS.POSITION_X), this.storage.getItem(STORAGE_KEYS.POSITION_Y)]);
+      if (xStr !== null && yStr !== null) {
+        const x = parseFloat(xStr);
+        const y = parseFloat(yStr);
+        if (!Number.isNaN(x) && !Number.isNaN(y)) {
+          const saved = {
+            x,
+            y
+          };
+          const validated = this.validatePosition(saved);
+
+          // Save corrected position if out of bounds
+          if (Math.abs(saved.x - validated.x) > 5 || Math.abs(saved.y - validated.y) > 5) {
+            this.savePosition(validated.x, validated.y);
+          }
+          this.position = validated;
+
+          // Check if loaded in hidden state
+          if (validated.x >= this.screenWidth - this.visibleHandleWidth - 5) {
+            this.isHidden = true;
+          }
+          this.notify();
+        }
+      }
+    } catch {
+      // Failed to load - use default position
+    }
+    this.isInitialized = true;
+  }
+
+  // =============================
+  // Position Management
+  // =============================
+
+  /**
+   * Get current bounds for position validation.
+   */
+  getBounds() {
+    return {
+      minX: this.minPosition.x,
+      maxX: this.screenWidth - this.visibleHandleWidth,
+      minY: this.minPosition.y,
+      maxY: this.screenHeight - this.bubbleSize.height - this.edgePadding
+    };
+  }
+
+  /**
+   * Validate and clamp a position to screen boundaries.
+   */
+  validatePosition(pos) {
+    const bounds = this.getBounds();
+    return {
+      x: Math.max(bounds.minX, Math.min(pos.x, bounds.maxX)),
+      y: Math.max(bounds.minY, Math.min(pos.y, bounds.maxY))
+    };
+  }
+
+  /**
+   * Set position directly (for animation callbacks).
+   */
+  setPosition(pos) {
+    this.position = pos;
+    this.onPositionChange?.(pos);
+    this.notify();
+  }
+
+  /**
+   * Update bubble size (call on layout).
+   * Only notifies if size actually changed.
+   */
+  setBubbleSize(size) {
+    if (this.bubbleSize.width === size.width && this.bubbleSize.height === size.height) {
+      return;
+    }
+    this.bubbleSize = size;
+    if (!this.isDragging) this.reconcileBounds();
+    this.notify();
+  }
+
+  /**
+   * Update screen dimensions (call on resize).
+   */
+  setScreenSize(width, height) {
+    this.screenWidth = width;
+    this.screenHeight = height;
+    this.reconcileBounds();
+    this.notify();
+  }
+
+  /** Keep the whole visible tool reachable after its content or viewport changes. */
+  reconcileBounds() {
+    const clampVisible = position => ({
+      x: Math.max(this.minPosition.x, Math.min(position.x, this.screenWidth - this.bubbleSize.width - this.edgePadding)),
+      y: Math.max(this.minPosition.y, Math.min(position.y, this.screenHeight - this.bubbleSize.height - this.edgePadding))
+    });
+    const visible = clampVisible(this.position);
+    this.position = this.isHidden ? {
+      ...visible,
+      x: this.screenWidth - this.visibleHandleWidth
+    } : visible;
+    if (this.savedPosition) this.savedPosition = clampVisible(this.savedPosition);
+  }
+
+  /**
+   * Update min position (e.g., for safe area insets).
+   */
+  setMinPosition(minPos) {
+    this.minPosition = minPos;
+  }
+
+  // =============================
+  // Persistence
+  // =============================
+
+  async savePosition(x, y) {
+    if (!this.enablePositionPersistence || !this.storage) return;
+    try {
+      await Promise.all([this.storage.setItem(STORAGE_KEYS.POSITION_X, x.toString()), this.storage.setItem(STORAGE_KEYS.POSITION_Y, y.toString())]);
+    } catch {
+      // Failed to save - continue without persistence
+    }
+  }
+  debouncedSavePosition(x, y) {
+    if (this.saveTimeout) clearTimeout(this.saveTimeout);
+    this.saveTimeout = setTimeout(() => this.savePosition(x, y), SAVE_DEBOUNCE_MS);
+  }
+
+  // =============================
+  // Hide/Show Toggle
+  // =============================
+
+  /**
+   * Toggle between hidden and visible states.
+   * Returns the target position for animation.
+   */
+  toggleHideShow() {
+    const isVisuallyOffScreen = this.position.x > this.screenWidth - this.bubbleSize.width / 2;
+    if (this.isHidden || isVisuallyOffScreen) {
+      // Show the bubble
+      let targetX;
+      let targetY;
+      if (this.savedPosition && this.savedPosition.x < this.screenWidth - this.bubbleSize.width / 2) {
+        targetX = this.savedPosition.x;
+        targetY = this.savedPosition.y;
+      } else {
+        targetX = this.screenWidth - this.bubbleSize.width - 20;
+        targetY = this.position.y;
+      }
+      this.isHidden = false;
+      this.onHiddenChange?.(false);
+      this.notify();
+      return {
+        targetPosition: {
+          x: targetX,
+          y: targetY
+        },
+        isHiding: false
+      };
+    } else {
+      // Hide the bubble
+      this.savedPosition = {
+        ...this.position
+      };
+      const hiddenX = this.screenWidth - this.visibleHandleWidth;
+      this.isHidden = true;
+      this.onHiddenChange?.(true);
+      this.notify();
+      return {
+        targetPosition: {
+          x: hiddenX,
+          y: this.position.y
+        },
+        isHiding: true
+      };
+    }
+  }
+
+  /**
+   * Force hide (for pushToSide behavior).
+   */
+  forceHide() {
+    if (this.isHidden) {
+      return {
+        targetPosition: this.position
+      };
+    }
+    this.savedPosition = {
+      ...this.position
+    };
+    const hiddenX = this.screenWidth - this.visibleHandleWidth;
+    this.isHidden = true;
+    this.onHiddenChange?.(true);
+    this.notify();
+    return {
+      targetPosition: {
+        x: hiddenX,
+        y: this.position.y
+      }
+    };
+  }
+
+  /**
+   * Force show (restore from pushToSide).
+   */
+  forceShow() {
+    if (!this.isHidden) {
+      return {
+        targetPosition: this.position
+      };
+    }
+    let targetX;
+    let targetY;
+    if (this.savedPosition) {
+      targetX = this.savedPosition.x;
+      targetY = this.savedPosition.y;
+    } else {
+      targetX = this.screenWidth - this.bubbleSize.width - 20;
+      targetY = this.position.y;
+    }
+    this.isHidden = false;
+    this.onHiddenChange?.(false);
+    this.notify();
+    return {
+      targetPosition: {
+        x: targetX,
+        y: targetY
+      }
+    };
+  }
+
+  // =============================
+  // Drag Handling
+  // =============================
+
+  /**
+   * Start a drag operation.
+   */
+  handleDragStart(event) {
+    this.hasMoved = false;
+    this.dragStartPos = {
+      ...this.position
+    };
+    this.dragStartMouse = {
+      x: event.clientX,
+      y: event.clientY
+    };
+  }
+
+  /**
+   * Process drag movement.
+   * Returns the new position (for animation) and whether drag threshold was exceeded.
+   */
+  handleDragMove(event) {
+    const dx = event.clientX - this.dragStartMouse.x;
+    const dy = event.clientY - this.dragStartMouse.y;
+    const totalDistance = Math.abs(dx) + Math.abs(dy);
+
+    // Check if moved enough to be considered a drag
+    if (!this.hasMoved && totalDistance > this.dragThreshold) {
+      this.hasMoved = true;
+      this.isDragging = true;
+      this.onDraggingChange?.(true);
+      this.notify();
+    }
+    if (this.hasMoved) {
+      const newX = this.dragStartPos.x + dx;
+      const newY = this.dragStartPos.y + dy;
+
+      // Allow overflow to right for hide detection, but clamp Y
+      const bounds = this.getBounds();
+      const clampedX = Math.max(bounds.minX, Math.min(newX, this.screenWidth - this.visibleHandleWidth + this.bubbleSize.width));
+      const clampedY = Math.max(bounds.minY, Math.min(newY, bounds.maxY));
+      this.position = {
+        x: clampedX,
+        y: clampedY
+      };
+      this.onPositionChange?.(this.position);
+      this.notify();
+      return {
+        position: this.position,
+        isDragging: true
+      };
+    }
+    return {
+      position: this.position,
+      isDragging: false
+    };
+  }
+
+  /**
+   * End a drag operation.
+   * Returns the result including whether to animate to hidden state.
+   */
+  handleDragEnd(event) {
+    const wasTap = !this.hasMoved;
+    if (wasTap) {
+      this.isDragging = false;
+      this.onDraggingChange?.(false);
+      this.notify();
+      return {
+        position: this.position,
+        shouldHide: false,
+        wasTap: true
+      };
+    }
+
+    // Calculate final position
+    const dx = event.clientX - this.dragStartMouse.x;
+    const dy = event.clientY - this.dragStartMouse.y;
+    const currentX = this.dragStartPos.x + dx;
+    const currentY = this.dragStartPos.y + dy;
+
+    // Check if should auto-hide (bubble midpoint past right edge)
+    const bubbleMidpoint = currentX + this.bubbleSize.width / 2;
+    const shouldHide = bubbleMidpoint > this.screenWidth;
+    const bounds = this.getBounds();
+    if (shouldHide) {
+      const hiddenX = this.screenWidth - this.visibleHandleWidth;
+      const clampedY = Math.max(bounds.minY, Math.min(currentY, bounds.maxY));
+      this.isHidden = true;
+      this.onHiddenChange?.(true);
+      this.isDragging = false;
+      this.onDraggingChange?.(false);
+      this.notify();
+      return {
+        position: {
+          x: hiddenX,
+          y: clampedY
+        },
+        shouldHide: true,
+        wasTap: false
+      };
+    } else {
+      // Check if pulling back from hidden
+      if (this.isHidden && currentX < this.screenWidth - this.visibleHandleWidth - 10) {
+        this.isHidden = false;
+        this.onHiddenChange?.(false);
+      }
+
+      // Clamp to visible area
+      const clampedX = Math.max(bounds.minX, Math.min(currentX, this.screenWidth - this.bubbleSize.width - this.edgePadding));
+      const clampedY = Math.max(bounds.minY, Math.min(currentY, bounds.maxY));
+
+      // Save position if visible
+      if (clampedX < this.screenWidth - this.bubbleSize.width / 2) {
+        this.savedPosition = {
+          x: clampedX,
+          y: clampedY
+        };
+      }
+      this.position = {
+        x: clampedX,
+        y: clampedY
+      };
+      this.isDragging = false;
+      this.onDraggingChange?.(false);
+      this.debouncedSavePosition(clampedX, clampedY);
+      this.notify();
+      return {
+        position: {
+          x: clampedX,
+          y: clampedY
+        },
+        shouldHide: false,
+        wasTap: false
+      };
+    }
+  }
+
+  /**
+   * Commit position after animation completes.
+   */
+  commitPosition(pos) {
+    this.position = pos;
+    this.savePosition(pos.x, pos.y);
+    this.notify();
+  }
+
+  // =============================
+  // Cleanup
+  // =============================
+
+  destroy() {
+    if (this.saveTimeout) {
+      clearTimeout(this.saveTimeout);
+      this.saveTimeout = null;
+    }
+    this.listeners.clear();
+  }
+}

package/lib/module/colors.js

@@ -1 +1,49 @@
-"use strict";export const floatingToolsColors={panel:"#1A1A1A",muted:"#888888",secondary:"#E0E0E0",info:"#20C997",success:"#20C997",optional:"#FFA94D",error:"#EF4444",primary:"#20C997",dragActive:"#20C997"};export function withAlpha(t,o){return"number"==typeof o?`${t}${Math.round(255*o).toString(16).padStart(2,"0")}`:`${t}${o}`}
+"use strict";
+
+/**
+ * Shared color palette for floating tools.
+ * Matches the gameUIColors from @buoy-gg/shared-ui.
+ *
+ * These are duplicated here to avoid requiring @buoy-gg/shared-ui
+ * as a dependency (which has React Native dependencies).
+ *
+ * TODO: Consider extracting colors to a truly platform-agnostic package
+ * that both shared-ui and floating-tools-core can depend on.
+ */
+
+/**
+ * Buoy brand colors - EXACT values from web docs site dark theme
+ */
+export const floatingToolsColors = {
+  /** Dark panel background */
+  panel: '#1A1A1A',
+  /** Muted gray for secondary elements */
+  muted: '#888888',
+  /** Primary text color */
+  secondary: '#E0E0E0',
+  /** Info/active state color (Buoy teal) */
+  info: '#20C997',
+  /** Success/admin color (Buoy teal) */
+  success: '#20C997',
+  /** Warning/optional color (Buoy orange) */
+  optional: '#FFA94D',
+  /** Error color (Buoy red) */
+  error: '#EF4444',
+  /** Primary accent color (Buoy teal) */
+  primary: '#20C997',
+  /** Color used when dragging the floating tools (Buoy teal) */
+  dragActive: '#20C997'
+};
+/**
+ * Get a color with optional alpha.
+ * @param color - The base color (hex)
+ * @param alpha - Alpha value as hex string (00-FF) or number (0-1)
+ */
+export function withAlpha(color, alpha) {
+  if (typeof alpha === 'number') {
+    // Convert 0-1 to hex
+    const hex = Math.round(alpha * 255).toString(16).padStart(2, '0');
+    return `${color}${hex}`;
+  }
+  return `${color}${alpha}`;
+}

package/lib/module/constants.js

@@ -1 +1,27 @@
-"use strict";export const VISIBLE_HANDLE_WIDTH=32;export const DRAG_THRESHOLD=5;export const ANIMATION_DURATION=200;export const EDGE_PADDING=10;export const SAVE_DEBOUNCE_MS=500;export const STORAGE_KEYS={POSITION_X:"@react_buoy_bubble_position_x",POSITION_Y:"@react_buoy_bubble_position_y"};
+"use strict";
+
+/**
+ * Shared constants for floating tools behavior.
+ * These values ensure consistent behavior across platforms.
+ */
+
+/** Width of the visible grip handle when bubble is hidden (pixels) */
+export const VISIBLE_HANDLE_WIDTH = 32;
+
+/** Minimum movement to distinguish drag from tap (pixels) */
+export const DRAG_THRESHOLD = 5;
+
+/** Animation duration for hide/show transitions (milliseconds) */
+export const ANIMATION_DURATION = 200;
+
+/** Padding from screen edges (pixels) */
+export const EDGE_PADDING = 10;
+
+/** Debounce delay for position persistence (milliseconds) */
+export const SAVE_DEBOUNCE_MS = 500;
+
+/** Storage keys for position persistence */
+export const STORAGE_KEYS = {
+  POSITION_X: '@react_buoy_bubble_position_x',
+  POSITION_Y: '@react_buoy_bubble_position_y'
+};