docs: revise the contents

Author: V3RON

website/src/docs/_meta.json

@@ -4,6 +4,11 @@
     "name": "getting-started",
     "label": "Getting Started"
   },
+  {
+    "type": "dir",
+    "name": "platforms",
+    "label": "Platforms"
+  },
   {
     "type": "dir",
     "name": "api",
@@ -19,4 +24,4 @@
     "name": "feature-comparison",
     "label": "Feature Comparison"
   }
-]
+]

website/src/docs/api/_meta.json

@@ -23,5 +23,15 @@
     "type": "file",
     "name": "rendering-components",
     "label": "Rendering Components"
+  },
+  {
+    "type": "file",
+    "name": "test-environment",
+    "label": "Test Environment & Lifecycle"
+  },
+  {
+    "type": "file",
+    "name": "cli",
+    "label": "CLI Reference"
   }
 ]

website/src/docs/api/cli.mdx

@@ -0,0 +1,88 @@
+# CLI Reference
+
+The `react-native-harness` command is a powerful wrapper around the Jest CLI. It provides seamless integration with native environments while maintaining the familiar Jest developer experience.
+
+## Commands
+
+### `init`
+
+Runs the interactive setup wizard to configure React Native Harness in your project.
+
+```bash
+npx react-native-harness init
+```
+
+The wizard will help you:
+- Detect your project type (Expo or React Native CLI).
+- Install required platform packages.
+- Configure Android, iOS, or Web runners.
+- Generate configuration files (`rn-harness.config.mjs` and `jest.harness.config.mjs`).
+
+### `(default)`
+
+Runs tests using the Harness test runner.
+
+```bash
+npx react-native-harness [test-file-pattern] [options]
+```
+
+## Options
+
+### Harness Specific Flags
+
+| Flag | Description |
+| :--- | :--- |
+| `--harnessRunner <name>` | Specify which runner from your `rn-harness.config.mjs` to use. **Note:** Only one runner can be specified per command execution. |
+| `--config, -c <path>` | Path to your Harness Jest configuration (defaults to `jest.harness.config.mjs`). |
+
+### Running on Multiple Platforms
+
+Harness executes tests on a single runner at a time to ensure isolated and reliable reporting. To run tests on multiple platforms (e.g., both iOS and Android in CI), you must execute the command separately for each runner:
+
+```bash
+# Run Android tests
+npx react-native-harness --harnessRunner android
+
+# Run iOS tests
+npx react-native-harness --harnessRunner ios
+```
+
+### Supported Jest Flags
+
+React Native Harness supports the most commonly used Jest flags:
+
+- `--watch`: Watch files for changes and rerun tests related to changed files.
+- `--coverage`: Indicates that test coverage information should be collected and reported in the output.
+- `--testNamePattern, -t`: Run only tests with a name that matches the regex.
+- `--testPathPattern`: A regexp string that is matched against all tests paths before executing the test.
+- `--verbose`: Display individual test results with the test suite hierarchy.
+
+## Restrictions and Limitations
+
+To ensure stability and compatibility with real native devices, React Native Harness **disables** or **restricts** certain standard Jest CLI options.
+
+### Forced Serial Execution
+
+Harness executes tests **serially** (one at a time) on the target device to prevent native resource conflicts (like multiple tests trying to access the camera or filesystem simultaneously).
+
+The following Jest flags are **ignored or disabled**:
+- `--maxWorkers`
+- `--runInBand` (Implicitly always true)
+- `--maxConcurrency`
+- `--shard`
+
+### Restricted Configuration Overrides
+
+Harness manages the test environment, transformation, and module resolution internally to ensure tests can be bundled by Metro and run on-device.
+
+The following Jest configuration flags are **disabled**:
+- `--runner` / `--testRunner`
+- `--testEnvironment`
+- `--preset`
+- `--transform` / `--transformIgnorePatterns`
+- `--resolver`
+- `--globals`
+
+### Snapshot Management
+
+Snapshot testing for UI is handled via the separate `@react-native-harness/ui` package and the `toMatchImageSnapshot` matcher. Standard Jest snapshot flags like `--updateSnapshot` (`-u`) are currently not supported for native image snapshots.

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

@@ -0,0 +1,101 @@
+# Test Environment & Lifecycle
+
+Understanding the execution lifecycle of React Native Harness is key to configuring complex test suites and ensuring test isolation.
+
+## Execution Lifecycle
+
+When you run `react-native-harness`, the following process occurs for each test file:
+
+1.  **Node.js Setup**: The CLI loads your configuration and prepares the Metro bundler.
+2.  **App Preparation**: The target app is launched or brought to the foreground on the device.
+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.
+6.  **Execution**: Tests are run serially on the device.
+7.  **Teardown**: Results are sent back to the CLI, and the environment is cleaned up.
+
+---
+
+## Setup Files
+
+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).
+- **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.
+
+```javascript
+// jest.setup.js
+// Polyfill URL for React Native
+import 'react-native-url-polyfill/auto';
+
+// Polyfill TextEncoder
+import { TextEncoder, TextDecoder } from 'text-encoding';
+global.TextEncoder = TextEncoder;
+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';
+
+// Global cleanup
+afterEach(() => {
+  clearAllMocks();
+});
+
+// Mock a global library that is used in many tests
+mock('react-native-safe-area-context', () => ({
+  useSafeAreaInsets: () => ({ top: 0, bottom: 0, left: 0, right: 0 }),
+}));
+```
+
+---
+
+## 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.
+
+---
+
+## Native Crash Detection
+
+Testing native modules often involves calling code that might cause the host application to crash. Standard test runners often hang or report a generic "Device disconnected" error in these cases.
+
+Harness includes a built-in **Native Crash Monitor**:
+
+- **`detectNativeCrashes`**: (Default: `true`) When enabled, Harness actively monitors the native process. If the app crashes, Harness catches the failure, reports a `NativeCrashError` for the current test, and automatically restarts the app to continue with the remaining test files.
+- **`crashDetectionInterval`**: (Default: `500ms`) How often the CLI polls the device to ensure the app is still alive.
+
+---
+
+## Forwarding Client Logs
+
+To aid in debugging, you can forward all `console` output from the device to your terminal.
+
+```javascript title="rn-harness.config.mjs"
+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`

website/src/docs/getting-started/_meta.json

@@ -9,6 +9,11 @@
     "name": "problem-statement",
     "label": "Problem Statement"
   },
+  {
+    "type": "file",
+    "name": "architecture",
+    "label": "Architecture"
+  },
   {
     "type": "file",
     "name": "quick-start",
@@ -24,4 +29,4 @@
     "name": "prior-art",
     "label": "Prior Art"
   }
-]
+]

website/src/docs/getting-started/architecture.md

@@ -0,0 +1,49 @@
+# Architecture
+
+React Native Harness is designed to bridge the gap between Node.js-based test runners (like Jest) and the native environment of mobile devices. Understanding how it works demystifies the "magic" and helps you configure it effectively.
+
+## High-Level Overview
+
+At its core, React Native Harness operates by replacing your application's standard Metro bundle with a specialized **Test Bundle**. This bundle contains the Harness Test Runner, which executes tests directly on the device.
+
+The architecture consists of three main components:
+
+1.  **Harness CLI (Node.js)**: Orchestrates the test run, manages the device, and reports results.
+2.  **Metro Bundler**: Serves the Test Bundle to the device.
+3.  **Harness Native Runner (Device)**: A lightweight runtime injected into your app that executes tests and communicates with the CLI.
+
+## How It Works
+
+### 1. The Test Bundle
+When you run `react-native-harness`, the CLI instructs Metro to bundle a special entry point instead of your app's `index.js`. This initial bundle contains:
+*   The Harness Test Runner.
+*   Your app's native modules (since the native binary is unchanged).
+
+Note that **test files are not included in this initial bundle**. This keeps the initial load fast and allows Harness to manage test isolation and execution dynamically.
+
+### 2. Device Injection
+Harness does **not** modify your native code (`.ipa` or `.apk`). Instead, it relies on the standard React Native development mechanism:
+1.  The CLI launches your existing Debug app on the simulator/emulator.
+2.  The app connects to Metro to download the JavaScript bundle.
+3.  Metro serves the **Test Bundle** (the runner).
+4.  The app loads the bundle, and instead of rendering your `App.tsx`, it starts the Harness Test Runner.
+
+### 3. The Bridge (WebSocket)
+Once the Test Runner starts on the device, it establishes a WebSocket connection back to the Harness CLI on your computer (default port `3001`). This bridge is used for:
+*   **Control**: The CLI tells the device which tests to run.
+*   **Reporting**: The device sends assertions, failures, and logs back to the CLI.
+*   **Lifecycle**: The CLI monitors the device for crashes or timeouts.
+
+### 4. Test Execution
+Tests are executed **serially** on the device:
+1.  The **CLI** sends a command to the **Runtime** (on the device) to run a specific test file.
+2.  The **Runtime** requests **Metro** to bundle that specific test file.
+3.  The **Runtime** downloads and evaluates the bundled test file.
+4.  Tests are executed using the Jest-compatible `describe`/`it` API.
+5.  Results are sent back to the **CLI**.
+
+## Key Takeaways
+
+*   **No Native Changes**: You don't need to change your `AppDelegate` or `MainActivity` to use Harness. It works entirely through JavaScript bundle swapping.
+*   **Single Runtime**: Tests run in the same JS thread as your app would, ensuring accurate behavior for native module calls.
+*   **Debug Builds**: Harness requires a Debug build of your app to load the bundle from Metro. It cannot run on Release builds (which have the bundle pre-packaged).