vybekiit 0.4.0 → 0.6.0

package/dist/global-skills/expo-ui/references/swift-ui.md

@@ -0,0 +1,73 @@
+# Platform-specific iOS UI: `@expo/ui/swift-ui`
+
+> **iOS only.** Code that imports from `@expo/ui/swift-ui` will crash on Android with "Unable to get view config" errors. Always place this code in an `.ios.tsx` component file or guard it with `Platform.OS === 'ios'`. `Host` must be imported from `@expo/ui` (the universal root), not from `@expo/ui/swift-ui`.
+
+Use this layer only when the universal `@expo/ui` components don't cover what you need on iOS (see `./universal.md` first). This requires a platform-specific tree.
+
+### File placement with Expo Router
+
+**Do not put `.ios.tsx` files inside `app/` or `src/app/`.** Expo Router does not support platform-extension suffixes for route files and will throw a "no fallback sibling" Render Error.
+
+Place platform-specific component files in `components/` (or any directory outside the route tree), then import them from a regular route file:
+
+```
+src/components/ProfileEditor.ios.tsx   ← SwiftUI tree lives here
+src/app/profile-editor.tsx             ← regular Expo Router route, imports the component
+```
+
+`src/app/profile-editor.tsx`:
+```tsx
+import ProfileEditor from '../components/ProfileEditor';
+export default ProfileEditor;
+```
+
+Alternatively, keep everything in one regular route file and branch on `Platform.OS`:
+
+```tsx
+// src/app/profile-editor.tsx
+import { Platform } from 'react-native';
+// import SwiftUI components only when on iOS to avoid Android crash
+const SwiftUIForm = Platform.OS === 'ios' ? require('../components/ProfileEditor.ios').default : null;
+```
+
+Or more simply, put the `Platform.OS` guard and the SwiftUI import in the same route file (safe because Metro only bundles `.ios.tsx` imports on iOS builds when using platform extensions in `components/`).
+
+## Instructions
+
+- Expo UI's API mirrors SwiftUI's API. Use SwiftUI knowledge to decide which components or modifiers to use.
+- Components are imported from `@expo/ui/swift-ui`, modifiers from `@expo/ui/swift-ui/modifiers`.
+- **Before writing any code, run the list-components script** to get the exact components and modifiers available in the installed version:
+  ```bash
+  node <skill-root>/scripts/list-components.js <project-path>          # names only (compact)
+  node <skill-root>/scripts/list-components.js <project-path> --docs   # with one-line descriptions
+  ```
+  (`<skill-root>` is the directory containing this `references/` folder.)
+- **The installed package's TypeScript types (`.d.ts`) are the most reliable source of truth** for prop shapes and signatures — read the relevant `{Component}/index.d.ts` from the installed `@expo/ui/swift-ui` package in `node_modules`. Use the docs below as the human-readable reference.
+- When about to use a component, fetch its docs to confirm the API — https://docs.expo.dev/versions/latest/sdk/ui/swift-ui/{component-name}/index.md
+- When unsure about a modifier's API, refer to the docs — https://docs.expo.dev/versions/latest/sdk/ui/swift-ui/modifiers/index.md
+- Every SwiftUI tree must be wrapped in `Host`.
+- `RNHostView` is specifically for embedding RN components inside a SwiftUI tree. Example:
+
+```jsx
+import { Host } from "@expo/ui";                       // Host always from universal root
+import { VStack, RNHostView } from "@expo/ui/swift-ui"; // platform components from swift-ui
+import { Pressable } from "react-native";
+
+<Host matchContents>
+  <VStack>
+    <RNHostView matchContents>
+      // Here, `Pressable` is an RN component so it is wrapped in `RNHostView`.
+      <Pressable />
+    </RNHostView>
+  </VStack>
+</Host>;
+```
+
+- If a required modifier or View is missing in Expo UI, it can be extended via a local Expo module. See: https://docs.expo.dev/guides/expo-ui-swift-ui/extending/index.md. Confirm with the user before extending.
+
+## useNativeState
+
+`useNativeState` creates observable state that updates synchronously on the UI thread via worklets, enabling immediate native state changes without waiting for a React render cycle. Requires `react-native-worklets` — without it updates still go through React and flickering remains. Best for real-time interactions where synchronous updates matter, e.g. a text field that masks or formats input as the user types.
+
+- `ObservableState.value` is readable/writable from worklets; `onChange` fires a worklet listener on state change.
+- Docs — https://docs.expo.dev/versions/latest/sdk/ui/swift-ui/usenativestate/index.md

package/dist/global-skills/expo-ui/references/universal.md

@@ -0,0 +1,73 @@
+# Universal `@expo/ui` components
+
+> Requires Expo SDK 56+.
+
+Universal components are a single-API layer over the platform-native UI toolkits: Jetpack Compose on Android, SwiftUI on iOS, and `react-native-web` / `react-dom` on web. You write one component tree that runs unmodified on all three platforms while keeping a native look and feel — no `.ios.tsx` / `.android.tsx` split.
+
+## Usage
+
+Import everything, including `Host`, from the package root (`@expo/ui`). Every tree must be wrapped in `Host`.
+
+```tsx
+import { Host, Column, Button, Text } from '@expo/ui';
+
+<Host matchContents>
+  <Column>
+    <Text>Hello</Text>
+    <Button onPress={() => alert('Pressed!')}>Press me</Button>
+  </Column>
+</Host>;
+```
+
+## Components
+
+| Category | Components |
+|----------|------------|
+| Container | `Host` (required root wrapper) |
+| Layout | `Column`, `Row`, `Spacer`, `ScrollView` |
+| Display | `Text`, `Icon` |
+| Controls | `Button`, `Switch`, `Checkbox`, `Slider`, `TextInput`, `Picker` |
+| Disclosure & presentation | `BottomSheet`, `Collapsible` |
+| Collections & forms | `List` (with `ListItem`), `FieldGroup` |
+
+> **`List` is not suitable for large lists.** Each `ListItem` is a JSX node processed on the JS thread — for large datasets this causes noticeable slowdowns.
+
+## TextInput and useNativeState
+
+`TextInput` from `@expo/ui` is **not like React Native's TextInput** — its `value` and `selection` props take an `ObservableState` object (from `useNativeState`), not a plain string. This is what enables synchronous, flicker-free updates: when the user types, `onChangeText` runs as a worklet on the UI thread and writes directly to `value` without a React render cycle.
+
+Requires `react-native-worklets`. Without it the worklet directive has no effect and flickering remains.
+
+```tsx
+import { Host, TextInput, useNativeState } from '@expo/ui';
+import { useCallback } from 'react';
+
+export default function MyInput() {
+  const text = useNativeState('');
+
+  const handleChangeText = useCallback((value: string) => {
+    'worklet';
+    // transform synchronously on the UI thread — no React re-render
+    text.value = value === 'Hello' ? 'World' : value;
+  }, [text]);
+
+  return (
+    <Host matchContents>
+      <TextInput value={text} onChangeText={handleChangeText} placeholder="Type here" />
+    </Host>
+  );
+}
+```
+
+Docs — https://docs.expo.dev/versions/latest/sdk/ui/universal/textinput/index.md
+
+## Confirming the API
+
+`@expo/ui` is versioned with the Expo SDK (e.g. `56.0.x` for SDK 56) and its API can change between SDK versions, so the **installed package's TypeScript types (`.d.ts`) are the most reliable source of truth** — they match the version in your project, while the docs track latest. Read the relevant component's `.d.ts` from the installed `@expo/ui` package in `node_modules`. Use the docs as the human-readable reference:
+
+- Overview — https://docs.expo.dev/versions/latest/sdk/ui/universal/index.md
+- Per component — https://docs.expo.dev/versions/latest/sdk/ui/universal/{component-name}/index.md
+
+## When to drop down to a platform-specific layer
+
+Choose universal components whenever they cover the requirement. Drop down to `@expo/ui/swift-ui` or `@expo/ui/jetpack-compose` only when the universal API doesn't expose the component, modifier, or platform-specific behavior you need — accepting the per-platform file split that requires. See `./swift-ui.md` and `./jetpack-compose.md`.

package/dist/global-skills/expo-ui/scripts/list-components.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+/**
+ * List available @expo/ui components and modifiers installed in a project.
+ *
+ * Usage:
+ *   node list-components.js <project-path> [--docs]
+ *
+ *   --docs  Include a one-line JSDoc description per modifier.
+ *           Omit (default) for a compact names-only list that consumes fewer tokens.
+ *
+ * Output goes to stdout. Redirect or capture it to inject into an agent prompt.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const projectPath = process.argv[2];
+const withDocs = process.argv.includes('--docs');
+
+if (!projectPath) {
+  console.error('Usage: node list-components.js <project-path> [--docs]');
+  process.exit(1);
+}
+
+const pkgRoot = path.join(projectPath, 'node_modules', '@expo', 'ui');
+if (!fs.existsSync(pkgRoot)) {
+  console.error(`@expo/ui not found in ${projectPath}/node_modules`);
+  process.exit(1);
+}
+
+// Read installed version from package.json
+let version = 'unknown';
+try {
+  const pkg = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf8'));
+  version = pkg.version || 'unknown';
+} catch (_) {}
+
+// ---------------------------------------------------------------------------
+// Component extraction — parse `export * from './Name'` in an index.d.ts
+// ---------------------------------------------------------------------------
+// TypeScript type names that are not components — skip anything matching these suffixes
+const TYPE_SUFFIX = /(?:Props|Ref|Handle|Params|Config|Options|Type|Types|Value|Values|Colors|Style|Styles|Event|Events|Alignment|Animation|Spec)$/;
+
+function extractComponents(indexFile) {
+  if (!fs.existsSync(indexFile)) return [];
+  const src = fs.readFileSync(indexFile, 'utf8');
+  const names = [];
+  for (const line of src.split('\n')) {
+    // export * from './ComponentName'  or  export * from './ComponentName/index'
+    const m = line.match(/^export \* from ['"]\.\/([^/'"]+)/);
+    if (m) {
+      const name = m[1];
+      // Skip non-component re-exports (types, utils, state internals)
+      if (/^(types|utils|index|State|hooks|colors|layout-types|MaterialSymbols)/.test(name)) continue;
+      if (TYPE_SUFFIX.test(name)) continue;
+      names.push(name);
+    }
+    // export { Name, ... } from './Something'  — pick up named re-exports too
+    const n = line.match(/^export \{([^}]+)\}/);
+    if (n) {
+      for (const part of n[1].split(',')) {
+        // Skip `type Foo` re-exports
+        if (/^\s*type\s/.test(part)) continue;
+        const id = part.trim().split(/\s+as\s+/)[0].trim();
+        if (id && /^[A-Z]/.test(id) && !TYPE_SUFFIX.test(id)) names.push(id);
+      }
+    }
+  }
+  return [...new Set(names)].sort();
+}
+
+// ---------------------------------------------------------------------------
+// Modifier extraction — parse `export declare const/function <name>` in
+// a flat modifiers/index.d.ts, optionally with the preceding JSDoc summary.
+// ---------------------------------------------------------------------------
+function extractModifiers(modifiersFile) {
+  if (!fs.existsSync(modifiersFile)) return [];
+  const src = fs.readFileSync(modifiersFile, 'utf8');
+  const lines = src.split('\n');
+  const results = [];
+  const seen = new Set();
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const m = line.match(/^export declare (?:const|function) ([a-zA-Z_][a-zA-Z0-9_]*)/);
+    if (!m) continue;
+    const name = m[1];
+    // Skip type-only helpers and internal symbols
+    if (/^(is|filter|create|type|export)/.test(name) && name !== 'frame') continue;
+    if (seen.has(name)) continue;
+    seen.add(name);
+
+    if (!withDocs) {
+      results.push({ name });
+      continue;
+    }
+
+    // Find /** that opens the JSDoc block immediately preceding this export,
+    // then scan forward through the block for the first plain-prose summary.
+    let jsdocStart = -1;
+    for (let j = i - 1; j >= 0; j--) {
+      const jl = lines[j].trim();
+      if (jl === '/**') { jsdocStart = j; break; }
+      if (jl !== '' && jl !== '*/' && !jl.startsWith('*')) break;
+    }
+
+    let summary = '';
+    let deprecated = false;
+    if (jsdocStart >= 0) {
+      let inCodeBlock = false;
+      for (let k = jsdocStart + 1; k < i; k++) {
+        const kl = lines[k].trim();
+        if (kl.startsWith('* ```')) { inCodeBlock = !inCodeBlock; continue; }
+        if (inCodeBlock) continue;
+        // Check @deprecated anywhere in the block (may appear after @param)
+        if (kl.startsWith('* @deprecated')) { deprecated = true; continue; }
+        // Extract summary from opening prose only — stop at first non-deprecated tag
+        if (!summary) {
+          if (kl.startsWith('* @')) continue; // skip tags while looking for prose
+          if (kl === '*/' || kl === '/**' || kl === '*') continue;
+          if (kl.startsWith('* ')) {
+            const text = kl.slice(2).trim();
+            if (!text.startsWith('-') && !text.startsWith('<')) {
+              summary = text.replace(/\.$/, '');
+            }
+          }
+        }
+      }
+    }
+    results.push({ name, summary, deprecated });
+  }
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Format helpers
+// ---------------------------------------------------------------------------
+function formatNames(names) {
+  return names.join(', ');
+}
+
+function formatModifiers(mods) {
+  if (!withDocs) return mods.map(m => m.name).join(', ');
+  const lines = [];
+  for (const m of mods) {
+    const dep = m.deprecated ? ' [deprecated]' : '';
+    const desc = m.summary ? `  — ${m.summary}` : '';
+    lines.push(`  ${m.name}${dep}${desc}`);
+  }
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+const buildRoot = path.join(pkgRoot, 'build');
+
+// Universal
+const universalComponents = extractComponents(path.join(buildRoot, 'universal', 'index.d.ts'));
+
+// Swift-UI (iOS only)
+const swiftuiComponents = extractComponents(path.join(buildRoot, 'swift-ui', 'index.d.ts'));
+const swiftuiModifiers = extractModifiers(path.join(buildRoot, 'swift-ui', 'modifiers', 'index.d.ts'));
+
+// Jetpack Compose (Android only)
+const composeComponents = extractComponents(path.join(buildRoot, 'jetpack-compose', 'index.d.ts'));
+const composeModifiers = extractModifiers(path.join(buildRoot, 'jetpack-compose', 'modifiers', 'index.d.ts'));
+
+const docsNote = withDocs ? ' (with descriptions)' : ' (names only — run with --docs for descriptions)';
+console.log(`@expo/ui ${version}${docsNote}\n`);
+
+console.log(`@expo/ui — universal (iOS + Android + web)`);
+console.log(`  Components: ${formatNames(universalComponents)}\n`);
+
+console.log(`@expo/ui/swift-ui — iOS ONLY (crashes on Android)`);
+console.log(`  Components: ${formatNames(swiftuiComponents)}`);
+if (withDocs) {
+  console.log(`  Modifiers:\n${formatModifiers(swiftuiModifiers)}`);
+} else {
+  console.log(`  Modifiers: ${formatModifiers(swiftuiModifiers)}`);
+}
+console.log();
+
+console.log(`@expo/ui/jetpack-compose — Android ONLY (crashes on iOS)`);
+console.log(`  Components: ${formatNames(composeComponents)}`);
+if (withDocs) {
+  console.log(`  Modifiers:\n${formatModifiers(composeModifiers)}`);
+} else {
+  console.log(`  Modifiers: ${formatModifiers(composeModifiers)}`);
+}

package/dist/global-skills/expo-upgrade/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: expo-upgrade
+description: Framework (OSS). Guidelines for upgrading Expo SDK versions and fixing dependency issues
+version: 1.0.0
+license: MIT
+---
+
+## References
+
+- ./references/react-19.md -- SDK +54: React 19 changes (useContext → use, Context.Provider → Context, forwardRef removal)
+- ./references/new-architecture.md -- SDK +53: New Architecture migration guide
+- ./references/react-compiler.md -- SDK +54: React Compiler setup and migration guide
+- ./references/native-tabs.md -- SDK +55: Native tabs changes (Icon/Label/Badge now accessed via NativeTabs.Trigger.\*)
+- ./references/expo-av-to-audio.md -- SDK +55: Migrate audio playback and recording from expo-av to expo-audio
+- ./references/expo-av-to-video.md -- SDK +55: Migrate video playback from expo-av to expo-video
+- ./references/react-navigation-to-expo-router.md -- SDK +56: Migrate `@react-navigation/*` imports to `expo-router` entry points (codemod + manual mapping)
+
+## Beta/Preview Releases
+
+Beta versions use `.preview` suffix (e.g., `55.0.0-preview.2`), published under `@next` tag.
+
+Check if latest is beta: https://exp.host/--/api/v2/versions (look for `-preview` in `expoVersion`)
+
+```bash
+npx expo install expo@next --fix  # install beta
+```
+
+## Step-by-Step Upgrade Process
+
+1. Upgrade Expo and dependencies
+
+```bash
+npx expo install expo@latest
+npx expo install --fix
+```
+
+2. Run diagnostics: `npx expo-doctor`
+
+3. Clear caches and reinstall
+
+```bash
+npx expo export -p ios --clear
+rm -rf node_modules .expo
+watchman watch-del-all
+```
+
+## Breaking Changes Checklist
+
+- Check for removed APIs in release notes
+- Update import paths for moved modules
+- Review native module changes requiring prebuild
+- Test all camera, audio, and video features
+- Verify navigation still works correctly
+
+## Prebuild for Native Changes
+
+**First check if `ios/` and `android/` directories exist in the project.** If neither directory exists, the project uses Continuous Native Generation (CNG) and native projects are regenerated at build time — skip this section and "Clear caches for bare workflow" entirely.
+
+If upgrading requires native changes:
+
+```bash
+npx expo prebuild --clean
+```
+
+This regenerates the `ios` and `android` directories. Ensure the project is not a bare workflow app before running this command.
+
+## Clear caches for bare workflow
+
+These steps only apply when `ios/` and/or `android/` directories exist in the project:
+
+- Clear the cocoapods cache for iOS: `cd ios && pod install --repo-update`
+- Clear derived data for Xcode: `npx expo run:ios --no-build-cache`
+- Clear the Gradle cache for Android: `cd android && ./gradlew clean`
+
+## Housekeeping
+
+- Review release notes for the target SDK version at https://expo.dev/changelog
+- If using Expo SDK 54 or later, ensure react-native-worklets is installed — this is required for react-native-reanimated to work.
+- Enable React Compiler in SDK 54+ by adding `"experiments": { "reactCompiler": true }` to app.json — it's stable and recommended
+- Delete sdkVersion from `app.json` to let Expo manage it automatically
+- Remove implicit packages from `package.json`: `@babel/core`, `babel-preset-expo`, `expo-constants`.
+- If the babel.config.js only contains 'babel-preset-expo', delete the file
+- If the metro.config.js only contains expo defaults, delete the file
+
+## Deprecated Packages
+
+| Old Package          | Replacement                                          |
+| -------------------- | ---------------------------------------------------- |
+| `expo-av`            | `expo-audio` and `expo-video`                        |
+| `expo-permissions`   | Individual package permission APIs                   |
+| `@expo/vector-icons` | `expo-symbols` (for SF Symbols)                      |
+| `AsyncStorage`       | `expo-sqlite/localStorage/install`                   |
+| `expo-app-loading`   | `expo-splash-screen`                                 |
+| expo-linear-gradient | experimental_backgroundImage + CSS gradients in View |
+
+When migrating deprecated packages, update all code usage before removing the old package. For expo-av, consult the migration references to convert Audio.Sound to useAudioPlayer, Audio.Recording to useAudioRecorder, and Video components to VideoView with useVideoPlayer.
+
+## expo.install.exclude
+
+Check if package.json has excluded packages:
+
+```json
+{
+  "expo": { "install": { "exclude": ["react-native-reanimated"] } }
+}
+```
+
+Exclusions are often workarounds that may no longer be needed after upgrading. Review each one.
+## Removing patches
+
+Check if there are any outdated patches in the `patches/` directory. Remove them if they are no longer needed.
+
+## Postcss
+
+- `autoprefixer` isn't needed in SDK +53. Remove it from dependencies and check `postcss.config.js` or `postcss.config.mjs` to remove it from the plugins list.
+- Use `postcss.config.mjs` in SDK +53.
+
+## Metro
+
+Remove redundant metro config options:
+
+- resolver.unstable_enablePackageExports is enabled by default in SDK +53.
+- `experimentalImportSupport` is enabled by default in SDK +54.
+- `EXPO_USE_FAST_RESOLVER=1` is removed in SDK +54.
+- cjs and mjs extensions are supported by default in SDK +50.
+- Expo webpack is deprecated, migrate to [Expo Router and Metro web](https://docs.expo.dev/router/migrate/from-expo-webpack/).
+
+## Hermes engine v1
+
+Since SDK 55, users can opt-in to use Hermes engine v1 for improved runtime performance. This requires setting `useHermesV1: true` in the `expo-build-properties` config plugin, and may require a specific version of the `hermes-compiler` npm package. Hermes v1 will become a default in some future SDK release.
+
+## New Architecture
+
+The new architecture is enabled by default, the app.json field `"newArchEnabled": true` is no longer needed as it's the default. Expo Go only supports the new architecture as of SDK +53.

package/dist/global-skills/expo-upgrade/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Expo Upgrade"
+  short_description: "Upgrade Expo SDKs, fix dependencies, adopt React 19 / React Compiler, and migrate deprecated Expo packages"
+  default_prompt: "Use $expo-upgrade to upgrade an Expo SDK, run diagnostics, fix dependency conflicts, decide whether prebuild/cache clearing applies, and migrate away from deprecated Expo packages."

package/dist/global-skills/expo-upgrade/references/expo-av-to-audio.md

@@ -0,0 +1,132 @@
+# Migrating from expo-av to expo-audio
+
+## Imports
+
+```tsx
+// Before
+import { Audio } from 'expo-av';
+
+// After
+import { useAudioPlayer, useAudioRecorder, RecordingPresets, AudioModule, setAudioModeAsync } from 'expo-audio';
+```
+
+## Audio Playback
+
+### Before (expo-av)
+
+```tsx
+const [sound, setSound] = useState<Audio.Sound>();
+
+async function playSound() {
+  const { sound } = await Audio.Sound.createAsync(require('./audio.mp3'));
+  setSound(sound);
+  await sound.playAsync();
+}
+
+useEffect(() => {
+  return sound ? () => { sound.unloadAsync(); } : undefined;
+}, [sound]);
+```
+
+### After (expo-audio)
+
+```tsx
+const player = useAudioPlayer(require('./audio.mp3'));
+
+// Play
+player.play();
+```
+
+## Audio Recording
+
+### Before (expo-av)
+
+```tsx
+const [recording, setRecording] = useState<Audio.Recording>();
+
+async function startRecording() {
+  await Audio.requestPermissionsAsync();
+  await Audio.setAudioModeAsync({ allowsRecordingIOS: true, playsInSilentModeIOS: true });
+  const { recording } = await Audio.Recording.createAsync(Audio.RecordingOptionsPresets.HIGH_QUALITY);
+  setRecording(recording);
+}
+
+async function stopRecording() {
+  await recording?.stopAndUnloadAsync();
+  const uri = recording?.getURI();
+}
+```
+
+### After (expo-audio)
+
+```tsx
+const recorder = useAudioRecorder(RecordingPresets.HIGH_QUALITY);
+
+async function startRecording() {
+  await AudioModule.requestRecordingPermissionsAsync();
+  await recorder.prepareToRecordAsync();
+  recorder.record();
+}
+
+async function stopRecording() {
+  await recorder.stop();
+  const uri = recorder.uri;
+}
+```
+
+## Audio Mode
+
+### Before (expo-av)
+
+```tsx
+await Audio.setAudioModeAsync({
+  allowsRecordingIOS: true,
+  playsInSilentModeIOS: true,
+  staysActiveInBackground: true,
+  interruptionModeIOS: InterruptionModeIOS.DoNotMix,
+});
+```
+
+### After (expo-audio)
+
+```tsx
+await setAudioModeAsync({
+  playsInSilentMode: true,
+  shouldPlayInBackground: true,
+  interruptionMode: 'doNotMix',
+});
+```
+
+## API Mapping
+
+| expo-av | expo-audio |
+|---------|------------|
+| `Audio.Sound.createAsync()` | `useAudioPlayer(source)` |
+| `sound.playAsync()` | `player.play()` |
+| `sound.pauseAsync()` | `player.pause()` |
+| `sound.setPositionAsync(ms)` | `player.seekTo(seconds)` |
+| `sound.setVolumeAsync(vol)` | `player.volume = vol` |
+| `sound.setRateAsync(rate)` | `player.playbackRate = rate` |
+| `sound.setIsLoopingAsync(loop)` | `player.loop = loop` |
+| `sound.unloadAsync()` | Automatic via hook |
+| `playbackStatus.positionMillis` | `player.currentTime` (seconds) |
+| `playbackStatus.durationMillis` | `player.duration` (seconds) |
+| `playbackStatus.isPlaying` | `player.playing` |
+| `Audio.Recording.createAsync()` | `useAudioRecorder(preset)` |
+| `Audio.RecordingOptionsPresets.*` | `RecordingPresets.*` |
+| `recording.stopAndUnloadAsync()` | `recorder.stop()` |
+| `recording.getURI()` | `recorder.uri` |
+| `Audio.requestPermissionsAsync()` | `AudioModule.requestRecordingPermissionsAsync()` |
+
+## Key Differences
+
+- **No auto-reset on finish**: After `play()` completes, the player stays paused at the end. To replay, call `player.seekTo(0)` then `play()`
+- **Time in seconds**: expo-audio uses seconds, not milliseconds (matching web standards)
+- **Immediate loading**: Audio loads immediately when the hook mounts—no explicit preloading needed
+- **Automatic cleanup**: No need to call `unloadAsync()`, hooks handle resource cleanup on unmount
+- **Multiple players**: Create multiple `useAudioPlayer` instances and store them—all load immediately
+- **Direct property access**: Set volume, rate, loop directly on the player object (`player.volume = 0.5`)
+
+## API Reference
+
+https://docs.expo.dev/versions/latest/sdk/audio/