@farmslot/adapter-rn 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -6,6 +6,20 @@ All notable changes to `@farmslot/adapter-rn` (published as `@farmslot/expo-reci
 
 - Active-development baseline; add user-facing changes here before release or package publication.
 
+## 0.17.0 - 2026-10-05
+
+- Add `bridge-runtime/bridge-core.cjs`, the generic Hermes CDP bridge CLI moved from mm-harness. `runBridgeCli(config)` runs the built-in commands (navigation, eval, UI gestures and input, scrolling and scroll-transition timing, Sentry debug, HUD steps, profiler, in-app issues, network capture), target selection over the CDP broker or a direct connection, the debugger-slot lock and typed errors. The host supplies its own commands, route table, recovery hints, help lines, perf markers and readiness check; a host command that reuses a built-in name throws at startup. The iOS and Android key and tap fallbacks read `RECIPE_RN_IDB_PATH` / `RECIPE_RN_ADB_PATH`.
+- Publish with protocol 0.34.0 and recipe-runner 0.24.0.
+
+## 0.16.0 - 2026-10-05
+
+- Add the generic React Native runtime, moved from mm-harness:
+  - **Bridge runtime:** the Hermes CDP libraries in `bridge-runtime/lib/*.cjs` (target discovery, ws client, devtools proxy, eval, error codes, port config, console format, in-app issue buffer snippets) and `bridge-runtime/console-forwarder.cjs`.
+  - **Metro:** the config wrapper, detached launcher and log helpers in `metro/*.cjs`.
+  - **From the index:** adb/idb discovery (`resolveMobileToolPath`, overridable with `RECIPE_RN_ADB_PATH`/`RECIPE_RN_IDB_PATH`), `listConnectedDevices`, the Android and iOS-simulator video recorders, `summarizeFrames`, and Metro-env and source fingerprints with recorded baselines. The project supplies the input lists and marker paths. Hosts set `RECIPE_RN_EXPLICIT_PLATFORM` and `RECIPE_RN_METRO_*` for the bridge and the Metro wrapper.
+- `--help` and `doctor` now print "Farmslot React Native adapter" (they still said "Farmslot Expo Recipe").
+- Publish with protocol 0.34.0 and recipe-runner 0.24.0.
+
 ## 0.15.0 - 2026-10-05
 
 - **Breaking:** renamed from `@farmslot/expo-recipe`, with no alias package. The bin is now `farmslot-adapter-rn` (was `farmslot-expo-recipe`), and `init` writes `recipe:*` scripts that call it. Run provenance and the bundled recipe source report `@farmslot/adapter-rn`. `runExpoRecipeCli` and `EXPO_RECIPE_PACKAGE_VERSIONS` are now `runAdapterRnCli` and `ADAPTER_RN_PACKAGE_VERSIONS`. Expo-specific APIs (`installExpoRecipeScaffold`, `runExpoRecipeDoctor`, `runExpoRecipeDocument`, …) keep their names.

package/README.md

@@ -6,15 +6,21 @@ Public docs: <https://farmslot.io/docs/guides/adapter-rn>
 
 ## Source layout
 
-| Path               | Owns                                                          |
-| ------------------ | ------------------------------------------------------------- |
-| `bin/`             | Published `farmslot-adapter-rn` executable shim.              |
-| `src/cli.ts`       | Init command parsing and CLI entrypoint.                      |
-| `src/scaffold.ts`  | File-copy and package-script scaffolding.                     |
-| `src/doctor.ts`    | Project integration checks.                                   |
-| `src/runner.ts`    | Expo smoke runner wiring built on `@farmslot/recipe-runner`.  |
-| `src/redaction.ts` | Output redaction helpers for generated artifacts.             |
-| `templates/`       | Versionless project scaffold copied into consuming Expo apps. |
+| Path                                                                         | Owns                                                                                             |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `bin/`                                                                       | Published `farmslot-adapter-rn` executable shim.                                                 |
+| `src/cli.ts`                                                                 | Init command parsing and CLI entrypoint.                                                         |
+| `src/scaffold.ts`                                                            | File-copy and package-script scaffolding.                                                        |
+| `src/doctor.ts`                                                              | Project integration checks.                                                                      |
+| `src/runner.ts`                                                              | Expo smoke runner wiring built on `@farmslot/recipe-runner`.                                     |
+| `src/redaction.ts`                                                           | Output redaction helpers for generated artifacts.                                                |
+| `templates/`                                                                 | Versionless project scaffold copied into consuming Expo apps.                                    |
+| `bridge-runtime/`                                                            | Hermes CDP bridge libraries (`lib/*.cjs`) and the console forwarder.                             |
+| `bridge-runtime/bridge-core.cjs`                                             | Generic bridge CLI (`runBridgeCli`); a host preset adds its commands, routes and recovery hints. |
+| `metro/`                                                                     | Metro config wrapper, detached launcher and log generation/coalescing helpers.                   |
+| `src/tool-paths.ts`, `src/devices.ts`                                        | adb/idb discovery (`RECIPE_RN_ADB_PATH`/`RECIPE_RN_IDB_PATH`) and connected-device listing.      |
+| `src/video-recorder.ts`, `src/frame-metrics.ts`                              | Device video recorders and frame-timing summaries.                                               |
+| `src/metro-env.ts`, `src/source-freshness.ts`, `src/fingerprint-baseline.ts` | Bundle-input fingerprints with recorded baselines; the project supplies the inputs.              |
 
 ## Relationship to the harness
 
@@ -22,7 +28,39 @@ Public docs: <https://farmslot.io/docs/guides/adapter-rn>
 
 - `@farmslot/protocol` owns Recipe Protocol v1 schemas, action names, and validation.
 - `@farmslot/recipe-runner` owns the generic runner, official core actions, UI actions, and CDP/React Native transports.
-- `@farmslot/adapter-rn` only adds Expo-friendly scaffolding: package scripts, a default recipe, optional dev-only React Native bridge/HUD files, and integration checks.
+- `@farmslot/adapter-rn` adds Expo-friendly scaffolding (package scripts, a default recipe, optional dev-only React Native bridge/HUD files, integration checks) and the generic React Native runtime a harness drives: the Hermes bridge libraries, Metro helpers, device tools, recorders and freshness fingerprints. Product commands, routes and env names stay in the host harness.
+
+### Bridge CLI preset
+
+A host's bridge script is a preset over `runBridgeCli`:
+
+```js
+// my-app/bridge-runtime/cdp-bridge.cjs
+const { runBridgeCli } = require('@farmslot/adapter-rn/bridge-runtime/bridge-core.cjs');
+const { cdpEval } = require('@farmslot/adapter-rn/bridge-runtime/lib/cdp-eval.cjs');
+
+runBridgeCli({
+  appLabel: 'My App',
+  routes: { aliases: { Home: 'HomeView' }, nestedParents: { SettingsDetail: 'Settings' } },
+  teachingByErrorCode: { NO_TARGET: 'Next: open the app on the device.' },
+  commands: {
+    // `status` also gets the core's `status-selected` (the pinned target only).
+    // Handlers get (client, args, { deviceName, platform, runtimeIdentity }).
+    async status(client, _args, { deviceName } = {}) {
+      return { route: await cdpEval(client, 'globalThis.__AGENTIC__?.getRoute?.()'), deviceName };
+    },
+  },
+  commandDocs: { status: { help: '  status                       App status' } },
+  // measure-scroll-transition: console lines starting with a prefix carry a JSON event.
+  perfMarkerPrefixes: ['[MyAppPerf] '],
+  // Evaluated only when a measure-scroll-transition request sets requireWalletReady: true;
+  // it must return { ready, observedAtMs }, and the measurement refuses unless ready is true.
+  readyExpression:
+    '({ ready: Boolean(globalThis.__AGENTIC__?.getRoute?.()), observedAtMs: performance.now() })',
+});
+```
+
+The built-in commands use the app's dev-only `globalThis.__AGENTIC__` bridge where present (`platform`, `getRoute`, `getState`, `navigate`, `canGoBack`, `goBack`, `pressTestId`, `pressText`, `queryUiTarget`, `setInput`, `scrollView`, `scrollIntoView`, and `showStep`/`hideStep` for the HUD). A host command that reuses a built-in name, or `status-selected`, throws at startup.
 
 Do not add project-specific actions such as wallet, perps, or meetings to this package. Those belong in the app or a project-specific runner/manifest that extends the official harness actions. Generic whole-run video proof stays in the shared harness capability surface.