# Native capture mode

Preview: not generally available yet.

Prepare your on-device Storybook to run without its development UI.

## Use the generated setup
The project's native Setup page detects your Storybook entry and offers a capture-mode change or instructions tailored to it. Review that change alongside the CI workflow. Keep normal development and production app entry behaviour intact.

Set `EXPO_PUBLIC_FRAMECHECK_CAPTURE=1` for the capture build. The bundle must contain Storybook and its stories, render stories full screen with the intended status bar and safe-area treatment, and enable Storybook's WebSocket channel on `localhost:7007`.

The generated capture entry uses a dedicated UI wrapper so story content, safe area, background, and status bar are consistent. Prefer the current generated snippet over copying an old `onDeviceUI: false` example, which may not match the expected rendering.

## Register the correct root
Check which helper your Metro configuration imports:

| Helper | Entry behaviour |
| --- | --- |
| `@storybook/react-native/withStorybook` | Makes `.rnstorybook/index` the entry; it must register the root component. |
| `@storybook/react-native/metro/withStorybook` | Keeps your app entry; point the capture build at your Storybook entry. |

Do not both replace the entry and assume another helper will register it. A build can compile while opening a blank screen or the normal app instead of Storybook.

## Include every required story
Run any story generation step before bundling. Set the Storybook environment flag your project requires as well as the capture flag. Use the same commit for the Android and iOS builds.

Use fixture data and bundle assets. The capture app must launch without Metro, developer credentials, or your local network.

## Android localhost access
The capture app needs to connect to `ws://localhost:7007`. Android release builds commonly block cleartext traffic. Configure localhost cleartext access for the capture build only. For Expo this can be a conditional `expo-build-properties` configuration; for bare React Native use a capture-specific build type or network-security configuration.

Do not enable broad cleartext access in your production app just to make tests connect.

## Verify before uploading
Install and launch the built app in a suitable local emulator or simulator when possible. Confirm it opens Storybook capture mode, includes the expected stories, and does not wait for Metro. Then upload using the generated instructions.