chore: improve JSDoc, tighten typings and update package keywords

- Expand and clarify JSDoc for SizedWebView, useAutoHeight and composeInjectedScript (more examples, usage notes and param docs)
- Use explicit FC import and replace React.FC in SizedWebView
- Reorder/clean up exports in src/index.ts
- Add a broader set of keywords to package.json to improve discovery

Author: mCodex

package.json

@@ -46,8 +46,25 @@
   },
   "keywords": [
     "react-native",
+    "webview",
     "ios",
-    "android"
+    "android",
+    "auto-size",
+    "auto-height",
+    "responsive",
+    "html-rendering",
+    "web-content",
+    "javascript-bridge",
+    "typescript",
+    "component",
+    "hook",
+    "sizing",
+    "layout",
+    "dynamic-height",
+    "content-measurement",
+    "mobile",
+    "native",
+    "performance"
   ],
   "repository": {
     "type": "git",

src/components/SizedWebView.tsx

@@ -1,4 +1,5 @@
 import { useCallback, useMemo } from 'react';
+import type { FC } from 'react';
 import { View, type StyleProp, type ViewStyle } from 'react-native';
 import {
   WebView,
@@ -10,26 +11,141 @@ import { AUTO_HEIGHT_BRIDGE } from '../constants/autoHeightBridge';
 import { useAutoHeight } from '../hooks/useAutoHeight';
 import { composeInjectedScript } from '../utils/composeInjectedScript';
 
+/**
+ * Props for the SizedWebView component.
+ *
+ * Extends all standard WebViewProps with additional auto-sizing capabilities.
+ *
+ * @example
+ * ```tsx
+ * <SizedWebView
+ *   source={{ html: '<h1>Hello World</h1>' }}
+ *   minHeight={100}
+ *   onHeightChange={(height) => console.log(`New height: ${height}`)}
+ * />
+ * ```
+ */
 export interface SizedWebViewProps extends WebViewProps {
   /**
-   * Minimum height (in dp) applied to the WebView container.
-   * Useful to avoid layout shifts on the initial render while the content height loads.
+   * Minimum height (in dp/points) for the WebView container.
+   *
+   * Useful to:
+   * - Avoid layout shifts during initial render while content height is loading
+   * - Prevent the WebView from becoming too small if content is minimal
+   * - Provide a baseline height for skeleton/loading states
+   *
+   * @default 0
    */
   minHeight?: number;
-  /** Optional styles applied to the wrapping `View` that hosts the WebView. */
+
+  /**
+   * Style object applied to the wrapping `View` container that hosts the WebView.
+   *
+   * Use this to add padding, margins, borders, or other styling to the container.
+   * Note: Do not set `height` here—it's automatically managed by the component.
+   *
+   * @example
+   * ```tsx
+   * containerStyle={{ paddingHorizontal: 12, borderRadius: 8 }}
+   * ```
+   */
   containerStyle?: StyleProp<ViewStyle>;
+
   /**
-   * Callback invoked whenever the auto-calculated height changes.
-   * Receives the committed height (in dp).
+   * Callback fired whenever the WebView's auto-calculated height changes.
+   *
+   * This is useful for:
+   * - Analytics tracking when content size changes
+   * - Triggering animations or other side effects
+   * - Syncing height with parent layout logic
+   *
+   * The callback receives the new committed height in density-independent pixels (dp).
+   *
+   * @param height - The new height in dp/points
+   *
+   * @example
+   * ```tsx
+   * onHeightChange={(height) => {
+   *   console.log(`WebView height updated to: ${height}dp`);
+   * }}
+   * ```
    */
   onHeightChange?: (height: number) => void;
 }
 
 /**
- * High-level WebView wrapper that automatically grows to match its HTML content height.
- * The component stays scroll-less and keeps the parent scroll view in control.
+ * A React Native WebView component that automatically sizes itself to fit its HTML content.
+ *
+ * ## Overview
+ * `SizedWebView` wraps the standard React Native `WebView` component and automatically
+ * adjusts its height to match the rendered HTML content. This prevents layout flicker,
+ * eliminates manual height calculations, and keeps scroll control with the parent ScrollView.
+ *
+ * ## Key Features
+ * - ✅ Automatic height adjustment based on HTML content
+ * - ✅ Smooth rendering with no layout flicker
+ * - ✅ Scroll control remains with parent container
+ * - ✅ Supports both local HTML and external URLs
+ * - ✅ Configurable minimum height to prevent excessive shrinking
+ * - ✅ Height change notifications via callback
+ *
+ * ## How it Works
+ * 1. An injected JavaScript bridge measures the HTML content's height
+ * 2. The height value is sent back to the native layer
+ * 3. The component updates its container size on each frame
+ * 4. The WebView stays scroll-disabled to prevent internal scrolling
+ *
+ * ## Usage Example
+ * ```tsx
+ * import { SizedWebView } from 'react-native-sized-webview';
+ *
+ * export function MyComponent() {
+ *   return (
+ *     <ScrollView>
+ *       <SizedWebView
+ *         source={{ html: '<h1>Dynamic Content</h1>' }}
+ *         minHeight={100}
+ *         containerStyle={{ marginVertical: 10 }}
+ *         onHeightChange={(height) => console.log(`Height: ${height}dp`)}
+ *       />
+ *     </ScrollView>
+ *   );
+ * }
+ * ```
+ *
+ * ## Props
+ * - All standard `WebViewProps` are supported
+ * - Plus 3 additional props: `minHeight`, `containerStyle`, `onHeightChange`
+ *
+ * ## Important Notes
+ * - The component disables scroll by default (`scrollEnabled={false}`)
+ * - Origin whitelist defaults to `['*']` to allow all sources
+ * - JavaScript is automatically enabled for the height bridge to work
+ * - Minimum height is always enforced to avoid layout issues
+ *
+ * @component
+ * @param props - SizedWebViewProps containing all configuration options
+ * @returns A View containing the auto-sized WebView
+ *
+ * @example
+ * ```tsx
+ * // With inline HTML
+ * <SizedWebView
+ *   source={{ html: '<p>Hello</p>' }}
+ *   minHeight={50}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With external URL
+ * <SizedWebView
+ *   source={{ uri: 'https://example.com' }}
+ *   containerStyle={{ borderRadius: 8 }}
+ * />
+ * ```
  */
-export const SizedWebView: React.FC<SizedWebViewProps> = ({
+export const SizedWebView: FC<SizedWebViewProps> = ({
   minHeight = 0,
   containerStyle,
   style,

src/hooks/useAutoHeight.ts

@@ -1,27 +1,175 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 
+/**
+ * Configuration options for the useAutoHeight hook.
+ *
+ * @interface UseAutoHeightOptions
+ */
 export interface UseAutoHeightOptions {
-  /** Minimum height (in dp) enforced for the WebView container. */
+  /**
+   * Minimum height (in dp/points) enforced for the WebView container.
+   *
+   * Prevents the component from becoming too small when content is minimal.
+   * The actual height will be: `max(minHeight, measuredContentHeight)`
+   *
+   * @default 0
+   */
   minHeight: number;
-  /** Optional callback triggered whenever a new height is committed. */
+
+  /**
+   * Optional callback triggered whenever a new height is committed.
+   *
+   * This callback fires after the height has been validated, throttled by the
+   * HEIGHT_DIFF_THRESHOLD, and scheduled for the next animation frame.
+   *
+   * Use this callback for:
+   * - Analytics or logging height changes
+   * - Triggering dependent UI updates
+   * - Syncing with external state management
+   *
+   * The callback is not called for changes smaller than 1dp to avoid noise.
+   *
+   * @param height - The new committed height in dp/points
+   *
+   * @example
+   * ```ts
+   * onHeightChange={(height) => {
+   *   analytics.track('webview_height_change', { height });
+   * }}
+   * ```
+   */
   onHeightChange?: (height: number) => void;
 }
 
+/**
+ * Return value from the useAutoHeight hook.
+ *
+ * @interface UseAutoHeightResult
+ */
 export interface UseAutoHeightResult {
-  /** Current height applied to the WebView container. */
+  /**
+   * The current height applied to the WebView container in dp/points.
+   *
+   * This value is:
+   * - At least `minHeight` (respects minimum)
+   * - Updated smoothly using requestAnimationFrame
+   * - Batched to avoid excessive re-renders
+   * - Only committed if change exceeds 1dp threshold
+   *
+   * @type {number}
+   */
   height: number;
+
   /**
-   * Helper that parses any incoming payload (from the WebView bridge) and
-   * commits a new height when appropriate.
+   * Parser and dispatcher for incoming height payloads from the WebView bridge.
+   *
+   * This function should be called with any data received from the injected JavaScript
+   * bridge. It handles:
+   * - Type coercion (number strings are converted to numbers)
+   * - Validation (finite positive numbers only)
+   * - Throttling (changes < 1dp are ignored)
+   * - Scheduling (uses requestAnimationFrame for smooth updates)
+   *
+   * Safe to call with any value—invalid inputs are silently ignored.
+   *
+   * @param rawValue - Any value received from the WebView bridge
+   *
+   * @example
+   * ```ts
+   * const { height, setHeightFromPayload } = useAutoHeight({ minHeight: 100 });
+   *
+   * const handleMessage = (event) => {
+   *   setHeightFromPayload(event.nativeEvent.data);
+   * };
+   * ```
    */
   setHeightFromPayload: (rawValue: unknown) => void;
 }
 
+/**
+ * Threshold (in dp) below which height changes are ignored.
+ *
+ * Prevents excessive re-renders from minor content layout fluctuations.
+ * @internal
+ */
 const HEIGHT_DIFF_THRESHOLD = 1;
 
 /**
- * React hook encapsulating the logic for tracking and updating the WebView height.
- * Ensures we avoid unnecessary renders while keeping the implementation testable.
+ * React hook for managing automatic WebView height calculation and updates.
+ *
+ * ## Overview
+ * This hook encapsulates all the logic needed to:
+ * 1. Track the WebView's content height
+ * 2. Validate and normalize incoming height values
+ * 3. Throttle updates to prevent layout thrashing
+ * 4. Schedule updates on the next animation frame
+ * 5. Invoke callbacks when height changes
+ *
+ * ## Features
+ * - 🎯 Enforces minimum height to prevent shrinking below acceptable bounds
+ * - ⚡ Batches updates using requestAnimationFrame for smooth 60fps rendering
+ * - 🚫 Ignores changes smaller than 1dp to reduce noise
+ * - 🔒 Type-safe with strong validation of incoming values
+ * - 🧪 Fully testable with deterministic behavior
+ * - 🧹 Automatically cleans up animation frame requests on unmount
+ *
+ * ## How it Works
+ * ```
+ * WebView Bridge sends height → setHeightFromPayload() validates
+ *   → scheduleCommit() batches update
+ *   → requestAnimationFrame executes flushPendingHeight()
+ *   → commitHeight() updates state + callback
+ * ```
+ *
+ * ## Usage Example
+ * ```ts
+ * import { useAutoHeight } from 'react-native-sized-webview';
+ *
+ * function MyComponent() {
+ *   const { height, setHeightFromPayload } = useAutoHeight({
+ *     minHeight: 100,
+ *     onHeightChange: (h) => console.log(`Height: ${h}dp`),
+ *   });
+ *
+ *   const handleMessage = (event) => {
+ *     setHeightFromPayload(event.nativeEvent.data);
+ *   };
+ *
+ *   return (
+ *     <View style={{ height }}>
+ *       <WebView onMessage={handleMessage} />
+ *     </View>
+ *   );
+ * }
+ * ```
+ *
+ * ## Performance Considerations
+ * - Uses requestAnimationFrame to sync with 60fps screen refresh
+ * - Only processes height changes exceeding 1dp threshold
+ * - Maintains refs to avoid unnecessary re-render triggers
+ * - Properly cancels pending frames on unmount
+ *
+ * @param options - Configuration object with minHeight and optional onHeightChange callback
+ * @returns Object containing current height and payload processor function
+ *
+ * @throws Does not throw—all invalid inputs are silently ignored
+ *
+ * @example
+ * ```ts
+ * // Basic usage with defaults
+ * const { height, setHeightFromPayload } = useAutoHeight({ minHeight: 50 });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With callback to track changes
+ * const { height, setHeightFromPayload } = useAutoHeight({
+ *   minHeight: 100,
+ *   onHeightChange: (newHeight) => {
+ *     analytics.track('webview_resized', { newHeight });
+ *   },
+ * });
+ * ```
  */
 export const useAutoHeight = (
   options: UseAutoHeightOptions