/**
 * Returns the player’s current **position** in milliseconds.
 *
 * This hook provides a reactive way to observe playback progress via the
 * `PositionChanged` event.
 *
 * - **Update frequency:** Fired at most once per second.
 * - **VOD:** Position is in the range **[0, duration]**.
 * - **LIVE:** Position is an **offset in ms** from the live content start (DVR window origin),
 *   not an absolute wall-clock timestamp. Use `useLiveStartTime()` and `useSeekableRange()`
 *   to map it to wall-clock time and clamp within the seekable window.
 *
 * ⚠️ Must be used within a {@link PlayerProvider} or
 * [AVPlayerViewControllerProvider](../../ios-avplayerviewcontroller-plugin-api/variables/AVPlayerViewControllerProvider.md) component.
 *
 * @returns `number` Current playback position in **milliseconds**.
 *
 * @example
 * ```tsx
 * // Condensed example showing VOD vs LIVE handling for a seek bar.
 * import { useDuration, useLive, useLiveStartTime, usePosition, useSeekableRange, usePlayer } from '@castlabs/react-native-prestoplay';
 *
 * function SeekBar() {
 *   const player = usePlayer();
 *   const position = usePosition();              // ms (VOD: 0..duration, LIVE: offset from live start)
 *   const duration = useDuration();              // ms
 *   const isLive = useLive();
 *   const liveStartTime = useLiveStartTime();    // epoch ms (nullable)
 *   const seekable = useSeekableRange();         // { startTime: epoch ms, endTime: epoch ms } (nullable)
 *
 *   // UI value:
 *   const value = isLive && seekable
 *     // convert offset -> wall-clock for display
 *     ? (liveStartTime ? liveStartTime + position : position)
 *     // VOD: show percent progress
 *     : (duration ? Math.round((position / duration) * 100) : 0);
 *
 *   const min = isLive && seekable ? seekable.startTime : 0;
 *   const max = isLive && seekable ? seekable.endTime   : 100;
 *
 *   const onSeek = (v: number) => {
 *     if (isLive) {
 *       // convert displayed wall-clock back to player offset
 *       const target = liveStartTime ? v - liveStartTime : v;
 *       player.setPosition(target);
 *     } else {
 *       const pct = v / 100;
 *       player.setPosition(Math.ceil(duration * pct));
 *     }
 *   };
 *
 *   return (
 *     <Slider value={value} minValue={min} maxValue={max} onChangeEnd={onSeek} />
 *   );
 * }
 * ```
 *
 * @group Hooks
 */
export default function usePosition(): number;