docs: update to match latest development

Author: V3RON

website/src/docs/api/plugins.mdx

@@ -8,10 +8,13 @@ A plugin can react to events such as:
 
 - Harness startup and teardown
 - run start and finish
+- runtime ready and disconnect events
 - Metro initialization and bundle events
 - app lifecycle signals
 - collection, suite, and test execution events
 
+Each plugin receives a context with useful runtime information such as a logger, project root, current runner, current config, and hook-specific data like the run ID or test file path.
+
 ## Defining a Plugin
 
 Use `definePlugin()` from `@react-native-harness/plugins` and register the plugin in your Harness config.
@@ -48,27 +51,41 @@ export const loggingPlugin = () =>
 Then register it in `rn-harness.config.mjs`:
 
 ```ts
+import {
+  applePlatform,
+  appleSimulator,
+} from '@react-native-harness/platform-apple';
 import { loggingPlugin } from './logging-plugin';
 
 export default {
   entryPoint: './src/test.ts',
   appRegistryComponentName: 'App',
   runners: [
-    {
+    applePlatform({
       name: 'ios',
-      runner: '@react-native-harness/platform-ios',
-      platformId: 'ios',
-      config: {},
-    },
+      device: appleSimulator('iPhone 16 Pro', '18.0'),
+      bundleId: 'com.example.app',
+    }),
   ],
   plugins: [loggingPlugin()],
 };
 ```
 
+## Typical Uses
+
+Plugins are a good fit when you want to:
+
+- write custom logs for run start, finish, or failures
+- collect screenshots, crash artifacts, or extra diagnostics
+- send results to external reporting systems
+- trigger project-specific automation around test runs
+
+Keep plugins focused on workflow needs that are specific to your app or team.
+
 ## Available Events
 
 The full list of plugin events is defined in the source here:
 
 - [packages/plugins/src/types.ts](https://github.com/callstackincubator/react-native-harness/blob/main/packages/plugins/src/types.ts)
 
-The public plugin shape is based on nested objects like `run.started`, `metro.bundleFinished`, or `harness.beforeDispose`.
+The public plugin shape is based on nested objects like `run.started`, `runtime.ready`, `metro.bundleFinished`, `app.exited`, or `harness.beforeDispose`.

website/src/docs/api/test-environment.mdx

@@ -11,7 +11,7 @@ When you run `react-native-harness`, the following process occurs for each test
 3.  **Harness Initialization**: The native bridge is established.
 4.  **`setupFiles`**: Global setup files are evaluated in the app environment.
 5.  **Test Collection**: The test file is evaluated to build a structure of `describe` and `it` blocks.
-    - **`setupFilesAfterEnv`**: These files are evaluated *during* this phase.
+    - **`setupFilesAfterEnv`**: These files are evaluated _during_ this phase.
 6.  **Execution**: Tests are run serially on the device.
 7.  **Teardown**: Results are sent back to the CLI, and the environment is cleaned up.
 
@@ -22,8 +22,10 @@ When you run `react-native-harness`, the following process occurs for each test
 Harness supports two types of setup files, configured in your `jest.harness.config.mjs`.
 
 ### `setupFiles`
+
 Executed **before** the testing environment is initialized.
-- **Context**: Runs in the app's JavaScript environment, but *before* the Test Runner has initialized the test framework (Jest).
+
+- **Context**: Runs in the app's JavaScript environment, but _before_ the Test Runner has initialized the test framework (Jest).
 - **Limitations**: `describe`, `it`, `expect`, and `beforeEach` are **not available**.
 - **Use Case**: Polyfilling global APIs that the environment or third-party libraries expect to exist immediately upon import.
 
@@ -39,14 +41,21 @@ global.TextDecoder = TextDecoder;
 ```
 
 ### `setupFilesAfterEnv`
+
 Executed **after** the testing environment is initialized, but before the test file itself.
+
 - **Context**: Runs immediately before the test file is executed. The test framework is fully loaded.
 - **Capabilities**: Full access to `describe`, `it`, `expect`, `beforeEach`, and Harness APIs like `mock`, `spyOn`, `clearAllMocks`, etc.
 - **Use Case**: Configuring global mocks, custom matchers, or global setup/teardown hooks.
 
 ```javascript
 // jest.setupAfterEnv.js
-import { beforeEach, afterEach, clearAllMocks, mock } from 'react-native-harness';
+import {
+  beforeEach,
+  afterEach,
+  clearAllMocks,
+  mock,
+} from 'react-native-harness';
 
 // Global cleanup
 afterEach(() => {
@@ -64,11 +73,13 @@ mock('react-native-safe-area-context', () => ({
 ## Isolation and Persistence
 
 ### Environment Reset
+
 By default, Harness ensures test isolation by resetting the environment between test files.
 
 - **`resetEnvironmentBetweenTestFiles`**: (Default: `true`) When enabled, the app is fully restarted between different test files. This prevents state leakage (like singleton native modules or global variables) from affecting subsequent tests.
 
 ### Native Module Mocking
+
 Mocks created via `mock()` are tied to the module cache. Use `resetModules()` in an `afterEach` hook to ensure mocks don't leak between individual tests within the same file.
 
 ---
@@ -82,6 +93,23 @@ Harness includes a built-in **Native Crash Monitor**:
 - **`detectNativeCrashes`**: (Default: `true`) When enabled, Harness actively monitors the native process during both startup and test execution. If the app crashes, Harness reports a `NativeCrashError` for the current test file, restarts the app, and continues with the remaining test files.
 - **`crashDetectionInterval`**: (Default: `500ms`) How often the CLI polls the device to ensure the app is still alive.
 
+## Startup Failures and Retries
+
+Harness treats app startup as part of the test run.
+
+- If the app crashes while launching, Harness reports the startup failure instead of waiting for a generic timeout.
+- If the app becomes unresponsive during launch, Harness fails the startup attempt with a startup-stall error.
+- Harness can retry startup automatically before giving up. Control this with `maxAppRestarts` in `rn-harness.config.mjs`.
+
+```javascript title="rn-harness.config.mjs"
+export default {
+  // ...
+  maxAppRestarts: 2,
+};
+```
+
+This is most useful in CI, where cold boots and slower launch times can make the first startup attempt less reliable.
+
 ---
 
 ## Forwarding Client Logs
@@ -92,10 +120,11 @@ To aid in debugging, you can forward all `console` output from the device to you
 export default {
   // ...
   forwardClientLogs: true,
-}
+};
 ```
 
 When enabled, logs from the device appear in your terminal with indicators:
-- ` LOG ` - `console.log`
-- ` WARN ` - `console.warn`
-- ` ERROR ` - `console.error`
+
+- `LOG` - `console.log`
+- `WARN` - `console.warn`
+- `ERROR` - `console.error`

website/src/docs/getting-started/configuration.mdx

@@ -91,12 +91,15 @@ For Expo projects, the `entryPoint` should be set to the path specified in the `
 | `entryPoint`                       | **Required.** Path to your React Native app's entry point file.                                                                                           |
 | `appRegistryComponentName`         | **Required.** Name of the component registered with AppRegistry.                                                                                          |
 | `runners`                          | **Required.** Array of test runners (at least one required).                                                                                              |
+| `plugins`                          | Array of Harness plugins to run during the test lifecycle.                                                                                                |
 | `defaultRunner`                    | Default runner to use when none specified.                                                                                                                |
 | `host`                             | Hostname or IP address to bind the Metro server to (default: Metro default).                                                                              |
 | `metroPort`                        | Preferred port used by Metro and Harness bridge traffic (default: `8081`). Harness falls back to the next available port when this one is already in use. |
+| `webSocketPort`                    | Deprecated. Bridge traffic now uses `metroPort`; this option is ignored.                                                                                  |
 | `platformReadyTimeout`             | Platform-ready timeout in milliseconds (default: `300000`).                                                                                               |
 | `bridgeTimeout`                    | Bridge timeout in milliseconds (default: `60000`).                                                                                                        |
 | `bundleStartTimeout`               | Bundle start timeout in milliseconds (default: `60000`).                                                                                                  |
+| `maxAppRestarts`                   | Maximum number of automatic app relaunch attempts while Harness is waiting for startup (default: `2`).                                                    |
 | `resetEnvironmentBetweenTestFiles` | Reset environment between test files (default: `true`).                                                                                                   |
 | `detectNativeCrashes`              | Detect native app crashes during startup and test execution (default: `true`).                                                                            |
 | `crashDetectionInterval`           | Interval in milliseconds to check for native crashes (default: `500`).                                                                                    |
@@ -112,6 +115,8 @@ For Expo projects, the `entryPoint` should be set to the path specified in the `
 Harness treats `metroPort` as the preferred starting port. If that port is already in use, Harness tries the next available ports automatically and logs the port it selected for the run.
 
 Physical iOS devices are the exception: they always use the default Metro port and do not support custom or fallback ports.
+
+When multiple Harness runs target the same device, simulator, emulator, or browser configuration, Harness waits for the existing run to finish before starting the next one.
 :::
 
 A test runner defines how tests are executed on a specific platform. React Native Harness uses platform-specific packages to create runners with type-safe configurations.
@@ -216,6 +221,49 @@ The bundle start timeout controls how long React Native Harness waits for the la
 **Default:** 60000 (60 seconds)
 **Minimum:** 1000 (1 second)
 
+## Startup Recovery
+
+Harness can retry app startup automatically when the app fails to come up cleanly during launch.
+
+```javascript
+{
+  maxAppRestarts: 2,
+}
+```
+
+**Default:** 2
+**Minimum:** 0
+
+Increase this value if your app occasionally needs another launch attempt before it reaches a ready state, especially in slower CI environments.
+
+Set it to `0` if you want startup failures to fail immediately without any automatic retry.
+
+## Plugins
+
+You can register Harness plugins with the `plugins` option.
+
+```javascript
+import { definePlugin } from '@react-native-harness/plugins';
+
+const loggingPlugin = definePlugin({
+  name: 'logging-plugin',
+  hooks: {
+    run: {
+      started: async (ctx) => {
+        ctx.logger.info('Starting run', ctx.runId);
+      },
+    },
+  },
+});
+
+export default {
+  // ...
+  plugins: [loggingPlugin],
+};
+```
+
+Use plugins for project-specific logging, artifact collection, reporting, or workflow automation. See the [Plugins](/docs/api/plugins) guide for more.
+
 ## Environment-Specific Configurations
 
 You can create different configurations for different environments:
@@ -263,7 +311,9 @@ The coverage root option specifies the root directory for coverage instrumentati
 
 ```javascript
 {
-  coverageRoot: '../',  // Use parent directory as coverage root
+  coverage: {
+    root: '../',
+  },
 }
 ```
 
@@ -275,8 +325,8 @@ This option is passed to babel-plugin-istanbul's `cwd` option and ensures that c
 - Libraries are structured with separate test and source directories
 - Projects have nested directory structures that don't align with the current working directory
 
-Without specifying `coverageRoot`, babel-plugin-istanbul may skip instrumenting files outside the current working directory, resulting in incomplete coverage reports.
+Without specifying `coverage.root`, babel-plugin-istanbul may skip instrumenting files outside the current working directory, resulting in incomplete coverage reports.
 
-:::tip When to use coverageRoot
-Set `coverageRoot` when you notice 0% coverage in your reports or when source files are not being instrumented for coverage. This commonly occurs in create-react-native-library projects and other monorepo setups.
+:::tip When to use coverage.root
+Set `coverage.root` when you notice 0% coverage in your reports or when source files are not being instrumented for coverage. This commonly occurs in create-react-native-library projects and other monorepo setups.
 :::

website/src/docs/getting-started/quick-start.mdx

@@ -36,6 +36,7 @@ Run the wizard from your project root:
 />
 
 The wizard will:
+
 - Ask for your project type (Expo or React Native CLI)
 - Help you select platforms (Android, iOS, or Web)
 - Find available devices and simulators
@@ -196,6 +197,8 @@ Before running tests, you need to build your app in debug mode and install it on
 
 Follow your framework's documentation to build and install the debug variant:
 
+Harness uses your existing debug app build. It does not create release builds or replace your native app setup.
+
 ### React Native Community CLI
 
 <PackageManagerTabs command="react-native run-android" />

website/src/docs/guides/ci-cd.md

@@ -42,7 +42,7 @@ The action accepts the following inputs:
 - `uploadVisualTestArtifacts` (optional): Whether to upload visual test diff and actual images as artifacts
 - `harnessArgs` (optional): Additional arguments to pass to the Harness CLI
 - `packageManager` (optional): Override package manager auto-detection. Supported values: `npm`, `yarn`, `pnpm`, `bun`, `deno`
-- `cacheAvd` (optional, Android only): Whether to cache the Android Virtual Device snapshot. Defaults to `true`
+- `cacheAvd` (optional, Android only): Whether to cache the Android Virtual Device snapshot. Defaults to `true`. This is most useful when your Android runner defines AVD details in `rn-harness.config.mjs`.
 - `preRunHook` (optional): Inline shell script run in `bash` immediately before Harness starts
 - `afterRunHook` (optional): Inline shell script run in `bash` immediately after Harness finishes and before artifacts are uploaded
 
@@ -233,12 +233,28 @@ The official action can run optional shell hooks around the Harness invocation:
 
 On Android, both hooks execute inside the `android-emulator-runner` session, so they can safely use `adb` against the active emulator. On iOS, the hooks run after the simulator is booted and the app is installed. On web, the same inputs are available for consistency and run immediately before and after the Harness command.
 
+## Android Emulator Caching
+
+For Android emulator runners, the official action can cache the emulator snapshot between runs.
+
+- Enable this with `cacheAvd: true`.
+- For best results, define the emulator's AVD details in your Android runner config.
+- Use this when you want faster CI runs and a more consistent emulator setup.
+
+If your workflow does not define AVD details, the action can still run the tests, but emulator snapshot caching is less useful.
+
 ## Metro cache
 
 React Native Harness can persist Metro's transformation cache under `.harness/metro-cache` in your project root. Enabling it in config (`unstable__enableMetroCache: true`) speeds up repeated Metro runs.
 
 When you use the `callstackincubator/react-native-harness` GitHub Action, Metro cache restoration and saving is handled automatically for the resolved `projectRoot`. You do not need to add a separate `actions/cache` step for `.harness/metro-cache`.
 
+## Web in CI
+
+The official action supports web runners as well. At the moment, the action installs Playwright Chromium automatically before running Harness.
+
+If your workflow depends on a different browser setup, make that expectation explicit in your CI configuration.
+
 ## Build Artifact Caching
 
 The workflow includes build artifact caching to significantly reduce CI execution times. When native modules haven't changed, you can reuse the same debug builds instead of rebuilding from scratch.

website/src/docs/platforms/android.mdx

@@ -43,16 +43,39 @@ androidPlatform({
       feature_enabled: true,
     },
   },
-})
+});
 ```
 
+If you want Harness and the official GitHub Action to create and cache a matching emulator setup reliably in CI, you can also provide AVD details:
+
+```javascript
+androidPlatform({
+  name: 'android',
+  device: androidEmulator('Pixel_8_API_35', {
+    apiLevel: 35,
+    profile: 'pixel_8',
+    diskSize: '6G',
+    heapSize: '1G',
+    snapshot: {
+      enabled: true,
+    },
+  }),
+  bundleId: 'com.yourapp.debug',
+});
+```
+
+Use the extra AVD configuration when you want more reproducible emulator setup in CI or when you plan to enable AVD snapshot caching in the official GitHub Action.
+
 #### Finding Emulator Names
+
 You can list all available AVDs on your system using the `emulator` command:
 
 ```bash
 emulator -list-avds
 ```
+
 Output example:
+
 ```
 Pixel_6_API_33
 Pixel_8_API_35
@@ -72,7 +95,7 @@ androidPlatform({
       launch_mode: 'test',
     },
   },
-})
+});
 ```
 
 The first argument is the manufacturer, and the second is the model name. These are used for reporting and logging purposes. Harness will automatically detect the connected device via ADB.
@@ -82,6 +105,10 @@ The first argument is the manufacturer, and the second is the model name. These
 - **ADB**: The Android Debug Bridge (`adb`) must be installed and in your system PATH.
 - **Development Build**: You must have a debug build of your app installed on the device/emulator (`adb install ...`). Harness does not build your app; it injects the test bundle into the existing installed app.
 
+## CI Notes
+
+If you use the official GitHub Action with an Android emulator runner, `cacheAvd` works best when your runner includes the emulator's AVD configuration. This helps the action reuse the correct emulator snapshot between runs.
+
 ## App Launch Options
 
 Android runners support `appLaunchOptions.extras`, which are passed as primitive extras to `adb shell am start`.

website/src/docs/platforms/ios.mdx

@@ -82,7 +82,6 @@ Physical iOS devices always connect to the default Metro port (`8081`). Custom `
 
 - **Xcode**: Xcode must be installed on your system.
 - **xcrun**: Harness uses `xcrun simctl` for simulators and `xcrun devicectl` for physical devices.
-- **libimobiledevice**: `idevicesyslog`, `idevicecrashreport`, and `idevice_id` must be installed and available in `PATH` for physical-device crash diagnostics.
 - **Development Build**: A debug build of your app must be installed on the simulator or device.
 
 ## App Launch Options
@@ -98,7 +97,7 @@ Harness maps them differently depending on the target:
 
 Harness uses separate crash-monitoring implementations by target:
 
-- iOS simulators use `simctl` for live log streaming and also scan local crash reports in `~/Library/Logs/DiagnosticReports`. When Harness finds a matching simulator `.ips` report, it attaches the parsed crash metadata and the crashing thread stack trace.
-- iOS physical devices use `libimobiledevice` to stream logs and pull `.crash` reports from the device.
+- iOS simulators can report startup and runtime crashes with matching crash details when those reports are available on your machine.
+- iOS physical devices can report native crash details as part of the failure output when the connected device provides matching diagnostics.
 
 Native crash details are attached to startup and execution failures when Harness can match the failing process from these sources. When the report contains it, Harness prints the extracted crashing-thread stack trace in the failure output.