@everframe/react-native 1.5.0 → 1.6.0

package/EverframeRN.podspec

@@ -40,7 +40,7 @@ package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
 # 1.2.0, so the range already asks for 1.2 while package.json is still 1.1.0.
 # The 1.2.0 release moves package.json to match.
 native_version_override = ENV['EVERFRAME_NATIVE_POD_VERSION'].to_s.strip
-native_minor_range = native_version_override.empty? ? '~> 1.5.0' : native_version_override
+native_minor_range = native_version_override.empty? ? '~> 1.6.0' : native_version_override
 
 Pod::Spec.new do |s|
   s.name         = 'EverframeRN'

package/README.md

@@ -414,15 +414,22 @@ In a crash-only session:
 - Session replay uses the app's crash-only sampling rate, which is 0 by
   default. An error carries a replay only while the session records.
 - Network bodies aren't captured.
-- Crash and error capture, breadcrumbs, vitals, release health and the
-  companion work as usual.
+- Crash and error capture, breadcrumbs, vitals and release health work as
+  usual.
 
-A companion bond (a phone scanning the QR code, or a dashboard member
-attaching) upgrades the session. Replay and network bodies then follow the
-app's normal settings for the rest of the session, and recording starts at
-the bond. The reporter stays off: reports from an upgraded session come
-through the companion. See
-[crash-only sessions](../../docs/session-replay.md#crash-only-sessions).
+See [crash-only sessions](../../docs/session-replay.md#crash-only-sessions).
+
+### Companion (removed)
+
+Everframe Companion (phone / TV pairing) has been removed. The `companion`
+namespace and `useCompanion()` remain as deprecated no-ops until the next
+major version: `companion.start()` logs one warning and reaches no native
+code, every `on*` subscription returns an unsubscribe and never fires, and
+`useCompanion()` always returns `{ state: 'unpaired', running: false, … }`
+with every other value `null`. The `attachPinUi`, `companionDeviceId` and
+`companionBadge` config options are accepted and ignored. To capture from a
+real device, link it under Settings → Devices in the dashboard and use quick
+capture.
 
 ## Navigation breadcrumbs
 
@@ -708,16 +715,23 @@ dashboard disable.
 
 In React Native and Expo development builds, use
 `shakeToReport: { enabled: !__DEV__ }` because the React Native development
-menu also uses shake. Production remains enabled by default.
+menu also uses shake. Production remains enabled by default. This only stops
+shake from opening the reporter: on a real phone, a development build still
+takes a quick capture on shake, and a linked phone captures in any build (see
+[Quick capture on phones](#quick-capture-on-phones)).
 
 #### Quick capture on simulators and emulators
 
 Debug builds on an iOS simulator or Android emulator can file a report without
-opening the reporter: double Shift on the simulator, or
-`npx @everframe/cli capture` (and `npx @everframe/cli hotkey` on macOS) from
-your terminal. Run `npx @everframe/cli login` once so captures are attributed
+opening the reporter: press ⇧B in the app (outside a `TextInput`), or run
+`npx @everframe/cli capture` from your terminal. iOS simulators also take the
+other bindings the dashboard offers (double Shift, ⌘ combos); Android
+emulators use the dashboard binding only when it is Shift plus a letter or
+digit, and ⇧B otherwise. Run `npx @everframe/cli login` once so captures are attributed
 to you. It stays dark until the dashboard turns the capture hotkey on for the
-app, and never runs on devices or release builds. To opt this app out locally:
+app. Real phones use shake instead; see
+[Quick capture on phones](#quick-capture-on-phones). To opt this app out
+locally (simulators, emulators and phones alike, including device linking):
 
 ```tsx
 <EverframeProvider
@@ -729,7 +743,112 @@ app, and never runs on devices or release builds. To opt this app out locally:
 dashboard disable. A session started with `capture.screenshot` off ignores quick
 capture.
 
-All other gestures and keys are host-owned. The host app
+#### Quick capture on phones
+
+On a real iPhone, iPad, or Android phone or tablet, **shake** takes a quick
+capture: the same screenshot, replay window, logs, breadcrumbs and network as
+⇧B in a simulator, filed as a draft that you title on the dashboard. The native
+iOS and Android SDKs do all of it; there is no JavaScript API and nothing to
+add to your app. A shake captures when the device is linked, or when the build is a
+debug build:
+
+| Device                  | Shake                                                                                                  |
+| ----------------------- | ------------------------------------------------------------------------------------------------------ |
+| Linked to you           | Quick capture, a private draft for you. Toast `Captured · <your name>`.                                |
+| Linked as a team device | Quick capture, a shared draft. Toast `Captured · team device`.                                         |
+| Unlinked, debug build   | Quick capture, a shared draft. Toast `Captured · <device name>`. Also answers a dashboard link window. |
+| Unlinked, release build | As before: the reporter opens if `shakeToReport` allows it. Also answers a dashboard link window.      |
+
+- **Link a phone.** On the dashboard, open **Settings → Devices → Link a
+  device**, then shake the phone with the app running. A banner shows
+  `Linking to Everframe · 47` with the line
+  `A teammate is linking a device. If that's not you, ignore this.` Click the
+  same number on the dashboard; the phone shows `Linked to <your name>`.
+  Nothing links on its own: a teammate always picks the number. On iOS, if the
+  Keychain refuses to store the link, the phone shows `Linking failed` instead
+  and stays unlinked.
+- **Team devices.** An admin can pick **Link as team device** instead. The
+  phone shows `Linked as team device`, and its captures go to the shared inbox
+  for whoever is on the dashboard.
+- **Hand a phone over.** A linked phone keeps capturing for its owner. When
+  another teammate opens **Link a device** and the phone is shaken, the capture
+  is filed as usual and the banner shows a number; picking it moves the phone,
+  and that capture, to the new teammate.
+- **Unlinking.** Unlink a phone under **Settings → Devices**. It finds out at
+  its next capture or config fetch and behaves as unlinked again. A capture
+  refused this way is not filed anywhere and shows `This device was unlinked`.
+  Android also shows that toast when a config fetch reports the unlink; iOS
+  clears the link silently then.
+- **Other toasts.** `Capture didn't upload` follows a capture whose upload was
+  rejected and not queued; `Capture failed` replaces `Captured` when the
+  screenshot or the evidence could not be taken.
+- **Debug builds.** React Native sends `__DEV__` as the build type (override it
+  with `debugBuild`), so a Metro development build on a phone counts as debug
+  and a shake takes a shared capture without linking. In those builds the
+  React Native development menu also opens on the same shake, on both
+  platforms. To stop development builds from capturing, set
+  `quickCapture: { enabled: !__DEV__ }`, which also turns linking off for them.
+- **`shakeToReport` controls only the reporter.** While quick capture or device
+  linking is on, the native shake detector runs whatever `shakeToReport` says,
+  and `shakeToReport` decides only whether an unlinked release build opens the
+  reporter. Linked and debug phones keep capturing with it off.
+- **Replay.** With the dashboard's capture hotkey replay setting on, linked
+  phones (any build) and debug builds record session replay while quick capture
+  is armed, as simulators do.
+- **End users see no change.** An unlinked release build never takes a quick
+  capture and never records replay because of it. The only new thing it can
+  show is the matching-number banner, if someone shakes it while a teammate has
+  a link window open.
+- **Off switches.** The dashboard's per-app **Device linking** switch stops
+  phones from asking to link. The dashboard's capture hotkey switch,
+  `quickCapture: { enabled: false }` or `reporter: { disabled: true }` turn off
+  quick capture and linking together, and shake then behaves as before.
+- **The token.** The device token is kept in the iOS Keychain, or encrypted
+  under an AndroidKeyStore key on Android. It is bound to the ingest endpoint
+  and SDK key that linked it, sent only there, and never logged. A linked
+  capture queued offline is sent later only while the same link is still
+  stored; otherwise it is dropped, never filed into another inbox.
+- **Platform differences.** On Android, one long shake can fire the detector
+  more than once, so a shake within 2 seconds of a capture is ignored. Phones
+  and tablets are covered on both platforms. Apple TV behaves as before;
+  Android TV uses a remote gesture instead (below). The Android behavior ships
+  with the native Android SDK release that includes it.
+
+#### Quick capture on Android TV
+
+On Android TV the native Android SDK takes the same quick capture from a
+remote gesture that the dashboard sets per app. The default is **holding
+Play/Pause for 1.5 seconds**. Link the TV like a phone: open **Link a device**
+on the dashboard, do the gesture on the TV, and click the number its banner
+shows.
+
+| Device                  | Remote gesture                                                                                         |
+| ----------------------- | ------------------------------------------------------------------------------------------------------ |
+| Linked to you           | Quick capture, a private draft for you. Toast `Captured · <your name>`.                                |
+| Linked as a team device | Quick capture, a shared draft. Toast `Captured · team device`.                                         |
+| Unlinked, debug build   | Quick capture, a shared draft. Toast `Captured · <device name>`. Also answers a dashboard link window. |
+| Unlinked, release build | Nothing visible. Only answers a dashboard link window.                                                 |
+
+- **Bindings.** In the dashboard's Quick capture card a binding is a long
+  press, a sequence (keys in order within a time window) or a chord (keys held
+  together). **Record on device** sets one from the remote you actually have:
+  pick one of your linked TVs, relaunch the app or bring it to the foreground,
+  and press the keys while it shows `Recording remote keys for 10 seconds`.
+- **Key handling.** An unlinked TV never has a key swallowed or changed, so
+  `TVEventHandler` sees every event as before. On a linked TV the first press
+  always reaches the app, so holding Play/Pause toggles playback once when the
+  press starts, before the capture. Once the gesture is recognized, a long
+  press's repeats are swallowed and its key-up arrives canceled; a sequence or
+  chord swallows only the key that completes it.
+- **Debug builds** follow `__DEV__` (or `debugBuild`), as on phones.
+- Everything else (end users, replay, takeover, unlinking, token storage and
+  the off switches) works as on phones. Apple TV gets no remote gesture yet.
+
+For the full rules, see the iOS SDK README's "Real iPhones and iPads" section
+and the Android SDK README's "Quick capture on real phones" and "Quick capture
+on Android TV" sections.
+
+Apart from quick capture, gestures and keys are host-owned. The host app
 calls `useEverframe().open()` (or the top-level `open()`)
 from whatever trigger makes sense for the target form factor.
 
@@ -1019,13 +1138,13 @@ Target annotations enrich supported automatic native observations, including IME
 
 ### Reporter boundaries and developer tools
 
-Native phone reporter opens and companion report requests add this custom breadcrumb before freezing evidence:
+Native phone reporter opens add this custom breadcrumb before freezing evidence:
 
 ```json
 {"kind":"custom","message":"reporter_opened","data":{"source":"everframe_reporter","trigger":"button"}}
 ```
 
-`trigger` is `button`, `shake`, `menu`, or `companion`. Pending text/scroll summaries are flushed before this boundary. Native shake uses `shake`; companion report requests use `companion`; existing `open()` calls use `button`. To identify a host menu entry explicitly, call `open({ trigger: 'menu' })`. Closing or cancelling the native flow adds `reporter_closed` with `data.source: 'everframe_reporter'` to the live trail. Both events retain breadcrumb capture/config gates.
+`trigger` is `button`, `shake`, `menu`, or `companion` (older builds only; Companion has been removed). Pending text/scroll summaries are flushed before this boundary. Native shake uses `shake`; existing `open()` calls use `button`. To identify a host menu entry explicitly, call `open({ trigger: 'menu' })`. Closing or cancelling the native flow adds `reporter_closed` with `data.source: 'everframe_reporter'` to the live trail. Both events retain breadcrumb capture/config gates.
 
 A reporter call crosses the React Native bridge after its native input can already have been recorded. It cannot prove that the previous tap or remote key opened the reporter. For a button, annotate its native host ref before interaction:
 
@@ -1037,7 +1156,7 @@ return <Pressable ref={reporterRef} onPress={() => void open()}><Text>Report</Te
 
 That target's tap/activation carries `data.origin: 'reporter'` and `data.trigger: 'button'`. On a remote, only Select/Enter activation is attributed to a `button` target; arrows, Menu and Play/Pause retain their ordinary meaning. An explicitly annotated `reporterTrigger: 'menu'` target attributes only its Menu activation. Attribution survives masking without retaining the target's text. Removing/recycling the bound ref removes attribution.
 
-Hosts owning a reporting flow outside `open()` can `await markReporterOpened('menu')` before showing their reporter UI and `await markReporterClosed()` when it closes. These promises resolve after the native UI-thread boundary work; await them before adding subsequent host breadcrumbs or changing reporter UI. These explicit markers do not claim or remove earlier native keys: a TV event callback may run after native key capture. Use companion report-request boundaries when a host cannot attribute the original remote trigger. Never infer reporter intent from a button label, a Menu/Play/Pause key, or proximity to `open()`.
+Hosts owning a reporting flow outside `open()` can `await markReporterOpened('menu')` before showing their reporter UI and `await markReporterClosed()` when it closes. These promises resolve after the native UI-thread boundary work; await them before adding subsequent host breadcrumbs or changing reporter UI. These explicit markers do not claim or remove earlier native keys: a TV event callback may run after native key capture. Never infer reporter intent from a button label, a Menu/Play/Pause key, or proximity to `open()`.
 
 Native target capture adds `data.origin: 'devtools'` to supported taps and structured text/control/scroll observations whose native ancestry belongs to React Native LogBox, the native development menu, or Expo development-client UI. This comes from framework view/window/controller identity, an RN-owned development-menu controller, or a framework root module identity. In a development host, the inline LogBox notification/inspector is also registered by the exact React Native component exports through the existing React DevTools commit hook; application components with the same name are not attributed. This observer reads component identity and native refs, never warning text or component props, and removes registrations when their committed hosts disappear or the provider unmounts. Production JavaScript leaves this observer inert. A development JavaScript host can still attribute LogBox when its native SDK was built in Release mode. Display text such as “Dismiss” never grants an origin. A missing React DevTools hook, unavailable RN private module exports at runtime, initial asynchronous module loading, unknown framework versions and surfaces outside the native capture adapters leave attribution unavailable; origin tagging does not install a new dialog capture mechanism. The observer depends on the LogBox module paths in supported React Native versions; a future version removing those paths requires an SDK compatibility update before Metro can bundle it.
 

package/android/build.gradle.kts

@@ -8,8 +8,7 @@
 //     includeBuild("../../../packages/sdk-android/android")           // surfaces :everframe-core, :everframe-reporter-ui
 //   This library declares the two project deps below which resolve through the
 //   composite-build mechanism. The on-device :everframe-tv Activity was removed
-//   alongside the iOS tvOS modal — Android TV hosts route reporting through the
-//   phone-companion (QR → phone browser SPA) flow via CompanionCaptureBridge.
+//   alongside the iOS tvOS modal.
 //
 // CODEGEN:
 //   The `com.facebook.react` Gradle plugin reads `codegenConfig` from
@@ -81,17 +80,15 @@ android {
         }
     }
 
-    // Task 11 (Plan 5) — `EverframeModuleTest.kt` / `EverframeCompanionModuleTest.kt`
-    // exercise a `EverframeModule` contract that no longer exists on `main`
+    // Task 11 (Plan 5) — `EverframeModuleTest.kt` exercises a
+    // `EverframeModule` contract that no longer exists on `main`
     // (captureNow/submit/openAnnotationOverlay were removed by the
-    // D-05/D-07 flip; `startCompanion()` now takes zero args;
-    // `Companion.__setState`/`__setPairUrl` are `internal` to
-    // :everframe-core and unreachable from this separate Gradle module) —
+    // D-05/D-07 flip) —
     // confirmed pre-existing and unrelated to Task 11 (Plan 4 Task 14 first
     // hit this reproducing against unmodified HEAD; see
     // .superpowers/sdd/task-11-report.md for the full compile-error dump).
     // `compileDebugUnitTestKotlin` compiles the entire `test` source set as
-    // one Kotlin unit, so these two permanently-broken files block
+    // one Kotlin unit, so this permanently-broken file blocks
     // `RnReplayBridgeTest.kt` (Task 11's actual subject, itself fixed by the
     // `BridgeReactContext` swap in this same change) from ever compiling.
     // Excluded here — NOT deleted — pending a follow-up ticket to either
@@ -101,10 +98,7 @@ android {
 tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile>()
     .matching { it.name.endsWith("UnitTestKotlin") } // compileDebugUnitTestKotlin + compileReleaseUnitTestKotlin
     .configureEach {
-        exclude(
-            "**/EverframeModuleTest.kt",
-            "**/EverframeCompanionModuleTest.kt",
-        )
+        exclude("**/EverframeModuleTest.kt")
     }
 
 // Derive the native-AAR range from this package's own npm version (single
@@ -130,7 +124,7 @@ tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile>()
 //
 // That window is not an edge case, it is every native minor. `package.json`
 // only reaches the new version when `changeset version` runs at RELEASE
-// time, so while the companion-attribution work sat unreleased, this file
+// time, so while one such feature sat unreleased, this file
 // resolved `0.4.+` -> the stale 0.4.4 AAR while the bridge source called
 // APIs added in native 0.5.0. Gradle resolved it happily (0.4.4 was in
 // mavenLocal from an earlier release) and the failure surfaced as three
@@ -153,7 +147,7 @@ val rnSdkPkg = groovy.json.JsonSlurper()
 val rnSdkVersion = rnSdkPkg["version"] as String
 // Native 1.2.0 is the release that renamed the SDK key to `sdkKey`; the
 // bridge moves with it, ahead of package.json, which the 1.2.0 release bumps.
-val nativeMinorRange: String = nativeVersionOverride ?: "[1.5.0,1.6.0)"
+val nativeMinorRange: String = nativeVersionOverride ?: "[1.6.0,1.7.0)"
 if (nativeVersionOverride != null) {
     logger.lifecycle(
         "[everframe-rn] native AAR pinned to $nativeVersionOverride via everframeNativeVersion " +
@@ -193,11 +187,10 @@ dependencies {
     // relying on transitive promotion.
     implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.9.0")
 
-    // kotlinx-serialization-json — used by the companion capture provider
-    // to serialize the UITree to JSON before gzipping it for the relay
-    // tap-to-identify binary frame. Already on the classpath transitively
-    // via :everframe-protocol (implementation-scoped there), but we need a
-    // direct reference here to call the Json { } factory.
+    // kotlinx-serialization-json — used by the interaction-event
+    // registration to parse its options JSON. Already on the classpath
+    // transitively via :everframe-protocol (implementation-scoped there),
+    // but we need a direct reference here to call the Json factory.
     implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3")
 
     // Unit tests (Plan 06-03 Task 3). Versions mirror :everframe-core (see