react-native-element-inspector 0.1.0

package/src/floatingPanel/index.ts

@@ -0,0 +1,11 @@
+export { AddPropertyButton, AddPropertyRow } from './AddPropertyRow';
+export { CloseButton } from './CloseButton';
+export { EditableValue } from './EditableValue';
+export { FloatingPanel } from './FloatingPanel';
+export { HandleContent } from './HandleContent';
+export { InspectorBubble } from './InspectorBubble';
+export { PanelBody } from './PanelBody';
+export { PanelFooter } from './PanelFooter';
+export { PanelHeader } from './PanelHeader';
+export { getPanelSize } from './panelUtils';
+export type { FloatingPanelConfig, FloatingPanelProps, PanelSize, PanelState } from './types';

package/src/floatingPanel/panelUtils.ts

@@ -0,0 +1,13 @@
+import { FLOATING_PANEL } from '../constants/ui';
+import type { PanelSize, PanelState } from './types';
+
+export const getPanelSize = (panelState: PanelState): PanelSize => {
+  switch (panelState) {
+    case 'bubble':
+      return { width: FLOATING_PANEL.BUBBLE_SIZE, height: FLOATING_PANEL.BUBBLE_SIZE };
+    case 'handle':
+      return { width: FLOATING_PANEL.HANDLE_WIDTH, height: FLOATING_PANEL.HANDLE_HEIGHT };
+    case 'expanded':
+      return { width: FLOATING_PANEL.PANEL_WIDTH, height: FLOATING_PANEL.PANEL_HEIGHT };
+  }
+};

package/src/floatingPanel/types.ts

@@ -0,0 +1,26 @@
+import type { MeasuredElement } from '../fiber';
+
+export type PanelState = 'bubble' | 'handle' | 'expanded';
+
+export interface FloatingPanelConfig {
+  panelState: PanelState;
+  screenWidth: number;
+  screenHeight: number;
+  onTap: () => void;
+}
+
+export interface PanelSize {
+  width: number;
+  height: number;
+}
+
+export interface FloatingPanelProps {
+  panelState: PanelState;
+  selected: MeasuredElement | null;
+  matches: MeasuredElement[];
+  selectedIndex: number;
+  onToggleInspect: () => void;
+  onCycleNext: () => void;
+  onCyclePrevious: () => void;
+  onClose: () => void;
+}

package/src/hooks/index.ts

@@ -0,0 +1,7 @@
+export { useDebouncedCallback } from './useDebouncedCallback';
+export { useDebouncedValue } from './useDebouncedValue';
+export { useFloatingPanel } from './useFloatingPanel';
+export { useLayoutSnapshot } from './useLayoutSnapshot';
+export { useStyleMutation } from './useStyleMutation';
+export { useStyleOverrides } from './useStyleOverrides';
+export { useTapToSelect } from './useTapToSelect';

package/src/hooks/useDebouncedCallback.ts

@@ -0,0 +1,18 @@
+import { useCallback, useRef } from 'react';
+
+export const useDebouncedCallback = <Args extends unknown[]>(
+  callback: (...args: Args) => void,
+  delay: number,
+): ((...args: Args) => void) => {
+  const timeout = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
+
+  return useCallback(
+    (...args: Args) => {
+      if (timeout.current) clearTimeout(timeout.current);
+      timeout.current = setTimeout(() => callbackRef.current(...args), delay);
+    },
+    [delay],
+  );
+};

package/src/hooks/useDebouncedValue.ts

@@ -0,0 +1,12 @@
+import { useEffect, useState } from 'react';
+
+export const useDebouncedValue = <T>(value: T, delay: number): T => {
+  const [debouncedValue, setDebouncedValue] = useState(value);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setDebouncedValue(value), delay);
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+
+  return debouncedValue;
+};

package/src/hooks/useFloatingPanel.ts

@@ -0,0 +1,191 @@
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import { Animated, PanResponder } from 'react-native';
+import { FLOATING_PANEL } from '../constants';
+import { getPanelSize } from '../floatingPanel/panelUtils';
+import type { FloatingPanelConfig } from '../floatingPanel/types';
+import { clamp } from '../utils';
+
+/**
+ * Core animation/gesture hook for the floating inspector panel.
+ * Owns Animated.ValueXY for position, PanResponder for drag,
+ * and Animated.Value for expand/collapse transitions.
+ */
+export const useFloatingPanel = ({
+  panelState,
+  screenWidth,
+  screenHeight,
+  onTap,
+}: FloatingPanelConfig) => {
+  // Mutable refs so PanResponder callbacks never capture stale values
+  const panelStateRef = useRef(panelState);
+  panelStateRef.current = panelState;
+
+  const onTapRef = useRef(onTap);
+  onTapRef.current = onTap;
+
+  const screenRef = useRef({ width: screenWidth, height: screenHeight });
+  screenRef.current = { width: screenWidth, height: screenHeight };
+
+  // Initial position: middle-left edge
+  const initialX = FLOATING_PANEL.EDGE_MARGIN;
+  const initialY = (screenHeight - FLOATING_PANEL.BUBBLE_SIZE) / 2;
+
+  const position = useRef(new Animated.ValueXY({ x: initialX, y: initialY })).current;
+  const expandProgress = useRef(new Animated.Value(0)).current;
+
+  // Track raw position for synchronous reads (Animated.Value doesn't expose current value)
+  const currentPosition = useRef<{ x: number; y: number }>({ x: initialX, y: initialY });
+  const isDragging = useRef(false);
+  const dragStart = useRef({ x: 0, y: 0 });
+
+  const panelSize = useMemo(() => getPanelSize(panelState), [panelState]);
+  const panelSizeRef = useRef(panelSize);
+  panelSizeRef.current = panelSize;
+
+  // Snap to nearest left/right edge with spring animation
+  const snapToEdge = useCallback(() => {
+    const { width } = screenRef.current;
+    const size = panelSizeRef.current;
+    const midpoint = width / 2;
+    const centerX = currentPosition.current.x + size.width / 2;
+
+    const targetX =
+      centerX < midpoint
+        ? FLOATING_PANEL.EDGE_MARGIN
+        : width - size.width - FLOATING_PANEL.EDGE_MARGIN;
+
+    currentPosition.current.x = targetX;
+
+    Animated.spring(position.x, {
+      toValue: targetX,
+      friction: FLOATING_PANEL.SNAP_FRICTION,
+      tension: FLOATING_PANEL.SNAP_TENSION,
+      useNativeDriver: false,
+    }).start();
+  }, [position.x]);
+
+  // PanResponder — recreated when screen dimensions change
+  const panResponder = useMemo(
+    () =>
+      PanResponder.create({
+        onStartShouldSetPanResponder: () => true,
+        onMoveShouldSetPanResponder: (_, gesture) =>
+          Math.abs(gesture.dx) > FLOATING_PANEL.TAP_THRESHOLD ||
+          Math.abs(gesture.dy) > FLOATING_PANEL.TAP_THRESHOLD,
+
+        onPanResponderGrant: () => {
+          isDragging.current = false;
+          dragStart.current = { ...currentPosition.current };
+        },
+
+        onPanResponderMove: (_, gesture) => {
+          const movedEnough =
+            Math.abs(gesture.dx) > FLOATING_PANEL.TAP_THRESHOLD ||
+            Math.abs(gesture.dy) > FLOATING_PANEL.TAP_THRESHOLD;
+
+          if (movedEnough) {
+            isDragging.current = true;
+          }
+
+          if (!isDragging.current) return;
+
+          const { width: screenW, height: screenH } = screenRef.current;
+          const size = panelSizeRef.current;
+
+          const newX = clamp(
+            dragStart.current.x + gesture.dx,
+            FLOATING_PANEL.EDGE_MARGIN,
+            screenW - size.width - FLOATING_PANEL.EDGE_MARGIN,
+          );
+          const newY = clamp(
+            dragStart.current.y + gesture.dy,
+            FLOATING_PANEL.TOP_SAFE_AREA,
+            screenH - size.height - FLOATING_PANEL.BOTTOM_SAFE_AREA,
+          );
+
+          position.setValue({ x: newX, y: newY });
+          currentPosition.current = { x: newX, y: newY };
+        },
+
+        onPanResponderRelease: () => {
+          if (!isDragging.current) {
+            onTapRef.current();
+            return;
+          }
+
+          // Bubble and handle snap to edge; expanded stays where dropped
+          if (panelStateRef.current !== 'expanded') {
+            snapToEdge();
+          }
+        },
+      }),
+    [position, snapToEdge],
+  );
+
+  // Animate expand/collapse when panelState changes
+  useEffect(() => {
+    Animated.timing(expandProgress, {
+      toValue: panelState === 'expanded' ? 1 : 0,
+      duration: FLOATING_PANEL.EXPAND_DURATION,
+      useNativeDriver: false,
+    }).start();
+  }, [panelState, expandProgress]);
+
+  // Reposition panel on state change so the new size stays on-screen.
+  // Bubble/handle: instantly snap to nearest edge.
+  // Expanded: spring-animate into screen bounds.
+  useEffect(() => {
+    const { x, y } = currentPosition.current;
+    const size = getPanelSize(panelState);
+
+    if (panelState === 'expanded') {
+      const targetX = clamp(
+        x,
+        FLOATING_PANEL.EDGE_MARGIN,
+        screenWidth - size.width - FLOATING_PANEL.EDGE_MARGIN,
+      );
+      const targetY = clamp(
+        y,
+        FLOATING_PANEL.TOP_SAFE_AREA,
+        screenHeight - size.height - FLOATING_PANEL.BOTTOM_SAFE_AREA,
+      );
+
+      if (targetX !== x || targetY !== y) {
+        currentPosition.current = { x: targetX, y: targetY };
+        Animated.spring(position, {
+          toValue: { x: targetX, y: targetY },
+          friction: FLOATING_PANEL.SNAP_FRICTION,
+          tension: FLOATING_PANEL.SNAP_TENSION,
+          useNativeDriver: false,
+        }).start();
+      }
+    } else {
+      // Bubble / handle — snap instantly to nearest edge (no animation needed,
+      // the panel content swap already provides the visual transition)
+      const midpoint = screenWidth / 2;
+      const centerX = x + size.width / 2;
+
+      const targetX =
+        centerX < midpoint
+          ? FLOATING_PANEL.EDGE_MARGIN
+          : screenWidth - size.width - FLOATING_PANEL.EDGE_MARGIN;
+      const targetY = clamp(
+        y,
+        FLOATING_PANEL.TOP_SAFE_AREA,
+        screenHeight - size.height - FLOATING_PANEL.BOTTOM_SAFE_AREA,
+      );
+
+      if (targetX !== x || targetY !== y) {
+        currentPosition.current = { x: targetX, y: targetY };
+        position.setValue({ x: targetX, y: targetY });
+      }
+    }
+  }, [panelState, screenWidth, screenHeight, position]);
+
+  return {
+    position,
+    expandProgress,
+    panHandlers: panResponder.panHandlers,
+    panelSize,
+  };
+};

package/src/hooks/useLayoutSnapshot.ts

@@ -0,0 +1,42 @@
+import { useCallback, useRef, useState } from 'react';
+import { FiberAdapter, type MeasuredElement } from '../fiber';
+import { buildLayoutSnapshot } from '../utils';
+import { useDebouncedCallback } from './useDebouncedCallback';
+
+/**
+ * Builds and caches the layout snapshot when inspect mode is activated.
+ * Call `buildSnapshot` on inspect-mode entry. Call `invalidate` after
+ * style mutations — it debounces and rebuilds automatically.
+ */
+export const useLayoutSnapshot = () => {
+  const [snapshot, setSnapshot] = useState<MeasuredElement[]>([]);
+  const [isBuilding, setIsBuilding] = useState(false);
+  const snapshotRef = useRef<MeasuredElement[]>([]);
+
+  const buildSnapshot = useCallback(async (): Promise<number> => {
+    const root = FiberAdapter.getFiberRoot();
+    if (!root) return 0;
+
+    setIsBuilding(true);
+    try {
+      const elements = await buildLayoutSnapshot(root);
+      snapshotRef.current = elements;
+      setSnapshot(elements);
+      return elements.length;
+    } finally {
+      setIsBuilding(false);
+    }
+  }, []);
+
+  /** Mark stale — debounced 300ms so rapid style edits don't rebuild every time. */
+  const invalidate = useDebouncedCallback(buildSnapshot, 300);
+
+  /** Rebuild only if the snapshot is empty (first time). */
+  const ensureFresh = useCallback(async () => {
+    if (snapshotRef.current.length === 0) {
+      await buildSnapshot();
+    }
+  }, [buildSnapshot]);
+
+  return { snapshot, isBuilding, buildSnapshot, invalidate, ensureFresh };
+};

package/src/hooks/useStyleMutation.ts

@@ -0,0 +1,31 @@
+import { useCallback, useMemo } from 'react';
+import { FiberAdapter, type MeasuredElement } from '../fiber';
+import { flattenStyles } from '../utils';
+
+/**
+ * Captures the original flattened style for an element and provides
+ * a function to replace the element's entire style via overrideProps.
+ *
+ * All override/disabled tracking belongs in the consuming component —
+ * this hook only handles fiber interaction.
+ */
+export const useStyleMutation = (element: MeasuredElement) => {
+  const originalStyle = useMemo(() => {
+    const flat = flattenStyles(element.fiber.memoizedProps?.style);
+    return flat ? structuredClone(flat) : {};
+  }, [element]);
+
+  /** Replace the element's entire style with a flat object. */
+  const applyStyle = useCallback(
+    (style: Record<string, unknown>) => FiberAdapter.setStyle(element.fiber, style),
+    [element],
+  );
+
+  /** Restore the element's original style. */
+  const resetStyle = useCallback(
+    () => FiberAdapter.setStyle(element.fiber, originalStyle),
+    [element, originalStyle],
+  );
+
+  return { originalStyle, applyStyle, resetStyle };
+};

package/src/hooks/useStyleOverrides.ts

@@ -0,0 +1,176 @@
+import { useRef, useState } from 'react';
+import { EDITABLE_VALUE } from '../constants';
+import type { MeasuredElement } from '../fiber';
+import { useStyleMutation } from './useStyleMutation';
+
+/**
+ * Manages style overrides, key renames, property toggling, and added properties
+ * for a selected element. Builds the final style object and applies it to the fiber
+ * on every change.
+ */
+export const useStyleOverrides = (element: MeasuredElement) => {
+  const { originalStyle, applyStyle } = useStyleMutation(element);
+  const [overrides, setOverrides] = useState<Record<string, unknown>>({});
+  const [disabledKeys, setDisabledKeys] = useState<Set<string>>(new Set());
+  const [keyRenames, setKeyRenames] = useState<Record<string, string>>({});
+  const [addedProperties, setAddedProperties] = useState<Record<string, unknown>>({});
+
+  // Refs mirror state so handlers always read the latest values (no stale closures)
+  const overridesRef = useRef(overrides);
+  const disabledRef = useRef(disabledKeys);
+  const keyRenamesRef = useRef(keyRenames);
+  const addedRef = useRef(addedProperties);
+  const prevElementRef = useRef(element);
+
+  // Reset when element changes (render-phase setState — React's recommended
+  // pattern for adjusting state based on props, avoids stale flash from useEffect)
+  if (prevElementRef.current !== element) {
+    prevElementRef.current = element;
+    overridesRef.current = {};
+    disabledRef.current = new Set();
+    keyRenamesRef.current = {};
+    addedRef.current = {};
+    setOverrides({});
+    setDisabledKeys(new Set());
+    setKeyRenames({});
+    setAddedProperties({});
+  }
+
+  /** Check if a key collides with any active key (original, renamed, or added). */
+  const isKeyTaken = (key: string, excludeOriginalKey?: string): boolean => {
+    for (const originalKey of Object.keys(originalStyle)) {
+      if (originalKey === excludeOriginalKey) continue;
+      const activeKey = keyRenamesRef.current[originalKey] ?? originalKey;
+      if (activeKey === key) return true;
+    }
+    if (key in addedRef.current) return true;
+    return false;
+  };
+
+  // Build a flat style from original + overrides − disabled + renames + added, then apply
+  const buildAndApply = (
+    nextOverrides: Record<string, unknown>,
+    nextDisabled: Set<string>,
+    nextRenames: Record<string, string>,
+    nextAdded: Record<string, unknown>,
+  ) => {
+    const style: Record<string, unknown> = {};
+    for (const [originalKey, originalValue] of Object.entries(originalStyle)) {
+      if (nextDisabled.has(originalKey)) continue;
+      const activeKey = nextRenames[originalKey] ?? originalKey;
+      const value = activeKey in nextOverrides ? nextOverrides[activeKey] : originalValue;
+      style[activeKey] = value;
+    }
+    for (const [key, value] of Object.entries(nextAdded)) {
+      style[key] = value;
+    }
+    applyStyle(style);
+  };
+
+  const handleToggle = (key: string) => {
+    const nextDisabled = new Set(disabledRef.current);
+    if (nextDisabled.has(key)) {
+      nextDisabled.delete(key);
+    } else {
+      nextDisabled.add(key);
+    }
+    disabledRef.current = nextDisabled;
+    buildAndApply(overridesRef.current, nextDisabled, keyRenamesRef.current, addedRef.current);
+    setDisabledKeys(nextDisabled);
+  };
+
+  const handleValueChange = (originalKey: string, newValue: unknown) => {
+    const activeKey = keyRenamesRef.current[originalKey] ?? originalKey;
+    const nextOverrides = { ...overridesRef.current, [activeKey]: newValue };
+    overridesRef.current = nextOverrides;
+    buildAndApply(nextOverrides, disabledRef.current, keyRenamesRef.current, addedRef.current);
+    setOverrides(nextOverrides);
+  };
+
+  const handleKeyChange = (originalKey: string, newKey: string) => {
+    const currentRenamedKey = keyRenamesRef.current[originalKey] ?? originalKey;
+    if (newKey === currentRenamedKey) return;
+    if (isKeyTaken(newKey, originalKey)) return;
+
+    const nextRenames = { ...keyRenamesRef.current };
+    const nextOverrides = { ...overridesRef.current };
+    if (currentRenamedKey in nextOverrides) {
+      nextOverrides[newKey] = nextOverrides[currentRenamedKey];
+      delete nextOverrides[currentRenamedKey];
+    }
+
+    if (newKey === originalKey) {
+      delete nextRenames[originalKey];
+    } else {
+      nextRenames[originalKey] = newKey;
+    }
+
+    overridesRef.current = nextOverrides;
+    keyRenamesRef.current = nextRenames;
+    buildAndApply(nextOverrides, disabledRef.current, nextRenames, addedRef.current);
+    setOverrides(nextOverrides);
+    setKeyRenames(nextRenames);
+  };
+
+  const handleAddProperty = (key: string, value: unknown) => {
+    const trimmed = key.trim();
+    if (!EDITABLE_VALUE.VALID_STYLE_KEY.test(trimmed)) return;
+    if (isKeyTaken(trimmed)) return;
+
+    const nextAdded = { ...addedRef.current, [trimmed]: value };
+    addedRef.current = nextAdded;
+    buildAndApply(overridesRef.current, disabledRef.current, keyRenamesRef.current, nextAdded);
+    setAddedProperties(nextAdded);
+  };
+
+  const handleAddedValueChange = (key: string, newValue: unknown) => {
+    const nextAdded = { ...addedRef.current, [key]: newValue };
+    addedRef.current = nextAdded;
+    buildAndApply(overridesRef.current, disabledRef.current, keyRenamesRef.current, nextAdded);
+    setAddedProperties(nextAdded);
+  };
+
+  const handleAddedKeyChange = (oldKey: string, newKey: string) => {
+    const trimmed = newKey.trim();
+    if (!trimmed || trimmed === oldKey) return;
+    if (!EDITABLE_VALUE.VALID_STYLE_KEY.test(trimmed)) return;
+    if (isKeyTaken(trimmed)) return;
+
+    const nextAdded = { ...addedRef.current };
+    nextAdded[trimmed] = nextAdded[oldKey];
+    delete nextAdded[oldKey];
+    addedRef.current = nextAdded;
+    buildAndApply(overridesRef.current, disabledRef.current, keyRenamesRef.current, nextAdded);
+    setAddedProperties(nextAdded);
+  };
+
+  const handleRemoveProperty = (key: string) => {
+    const nextAdded = { ...addedRef.current };
+    delete nextAdded[key];
+    addedRef.current = nextAdded;
+    buildAndApply(overridesRef.current, disabledRef.current, keyRenamesRef.current, nextAdded);
+    setAddedProperties(nextAdded);
+  };
+
+  /** Resolve the active key and display value for an original style entry. */
+  const resolveEntry = (originalKey: string, originalValue: unknown) => {
+    const activeKey = keyRenames[originalKey] ?? originalKey;
+    const displayValue = activeKey in overrides ? overrides[activeKey] : originalValue;
+    const disabled = disabledKeys.has(originalKey);
+    return { activeKey, displayValue, disabled };
+  };
+
+  return {
+    originalStyle,
+    entries: Object.entries(originalStyle),
+    addedEntries: Object.entries(addedProperties),
+    resolveEntry,
+    handleToggle,
+    handleValueChange,
+    handleKeyChange,
+    handleAddProperty,
+    handleAddedValueChange,
+    handleAddedKeyChange,
+    handleRemoveProperty,
+  };
+};

package/src/hooks/useTapToSelect.ts

@@ -0,0 +1,76 @@
+import { useCallback, useState } from 'react';
+import type { GestureResponderEvent } from 'react-native';
+import type { MeasuredElement } from '../fiber';
+import { hitTest } from '../utils';
+
+interface TapToSelectState {
+  /** All overlapping elements at the tap point, sorted by area (smallest first) */
+  matches: MeasuredElement[];
+  /** Currently selected index in the matches array */
+  selectedIndex: number;
+  /** The currently selected element */
+  selected: MeasuredElement | null;
+}
+
+/**
+ * Handles tap-to-select interaction.
+ * On tap, hit-tests the snapshot and selects the most specific element.
+ * Supports cycling through overlapping elements.
+ */
+export const useTapToSelect = (snapshot: MeasuredElement[]) => {
+  const [state, setState] = useState<TapToSelectState>({
+    matches: [],
+    selectedIndex: 0,
+    selected: null,
+  });
+
+  const handleTap = useCallback(
+    (event: GestureResponderEvent) => {
+      const { pageX, pageY } = event.nativeEvent;
+      const matches = hitTest(snapshot, pageX, pageY);
+
+      setState({
+        matches,
+        selectedIndex: 0,
+        selected: matches[0] ?? null,
+      });
+    },
+    [snapshot],
+  );
+
+  const cycleNext = useCallback(() => {
+    setState((prev) => {
+      if (prev.matches.length === 0) return prev;
+      const nextIndex = (prev.selectedIndex + 1) % prev.matches.length;
+      return {
+        ...prev,
+        selectedIndex: nextIndex,
+        selected: prev.matches[nextIndex] ?? null,
+      };
+    });
+  }, []);
+
+  const cyclePrevious = useCallback(() => {
+    setState((prev) => {
+      if (prev.matches.length === 0) return prev;
+      const prevIndex = (prev.selectedIndex - 1 + prev.matches.length) % prev.matches.length;
+      return {
+        ...prev,
+        selectedIndex: prevIndex,
+        selected: prev.matches[prevIndex] ?? null,
+      };
+    });
+  }, []);
+
+  const clearSelection = useCallback(() => {
+    setState({ matches: [], selectedIndex: 0, selected: null });
+  }, []);
+
+  return {
+    ...state,
+    handleTap,
+    cycleNext,
+    cyclePrevious,
+    clearSelection,
+  };
+};

package/src/index.ts

@@ -0,0 +1,2 @@
+export type { ElementInspectorProps } from './ElementInspector';
+export { ElementInspector } from './ElementInspector';

package/src/utils/clamp.ts

@@ -0,0 +1,2 @@
+export const clamp = (value: number, min: number, max: number): number =>
+  Math.max(min, Math.min(max, value));

package/src/utils/flattenStyles.ts

@@ -0,0 +1,12 @@
+import { type StyleProp, StyleSheet, type ViewStyle } from 'react-native';
+
+export type StyleObject = Record<string, unknown>;
+
+/**
+ * Resolve any style value (StyleSheet ID, array, or plain object) into a flat object.
+ */
+export const flattenStyles = (style: unknown): StyleObject | null => {
+  if (!style) return null;
+  const flat = StyleSheet.flatten(style as StyleProp<ViewStyle>);
+  return (flat ?? null) as StyleObject | null;
+};

package/src/utils/hitTest.ts

@@ -0,0 +1,29 @@
+import type { MeasuredElement } from '../fiber';
+
+/**
+ * Given a tap point and a layout snapshot, return all elements
+ * whose bounds contain the point, sorted by area (smallest first).
+ */
+export const hitTest = (
+  snapshot: MeasuredElement[],
+  tapX: number,
+  tapY: number,
+): MeasuredElement[] => {
+  const matches: MeasuredElement[] = [];
+
+  for (const element of snapshot) {
+    const { x, y, width, height } = element;
+
+    // Skip zero-size elements
+    if (width === 0 || height === 0) continue;
+
+    if (tapX >= x && tapX <= x + width && tapY >= y && tapY <= y + height) {
+      matches.push(element);
+    }
+  }
+
+  // Sort by area ascending — smallest (most specific) element first
+  matches.sort((a, b) => a.width * a.height - b.width * b.height);
+
+  return matches;
+};

package/src/utils/index.ts

@@ -0,0 +1,11 @@
+export { clamp } from './clamp';
+export type { StyleObject } from './flattenStyles';
+export { flattenStyles } from './flattenStyles';
+export { hitTest } from './hitTest';
+export { buildLayoutSnapshot } from './layoutSnapshot';
+export type { SourceLocation } from './sourceMapping';
+export { formatSourceLocation, getOwnerName, getSourceLocation } from './sourceMapping';
+export { formatValue, isColorProp } from './styleFormatting';
+export { parseInput, toEditableString } from './styleInputParsing';
+export type { BoxModel } from './yogaLayout';
+export { extractBoxModel } from './yogaLayout';