yaver-feedback-react-native 0.8.7 → 0.8.8

package/README.md

@@ -2,6 +2,8 @@
 
 Visual feedback SDK for Yaver. Lets testers and developers shake their phone and then keep a small quick-access icon on screen for hot reload, vibing, and screenshot & fix flows straight to a Yaver agent running on a dev machine.
 
+Haptics ownership rule: when your app is paired with Yaver, app-level haptics should belong to Yaver Feedback alone. If the host app also fires its own `expo-haptics` calls, you risk duplicated tactile feedback and a larger native-module crash surface during guest/runtime flows.
+
 ## Installation
 
 ```bash
@@ -618,6 +620,7 @@ YaverFeedback.init({
   // Optional
   agentUrl: 'http://192.168.1.10:18080',  // Agent URL (auto-discovered if omitted)
   trigger: 'shake',                        // 'shake' | 'floating-button' | 'manual'
+  disableShakeGesture: false,              // Non-default: disable shake + promote quick icon to 'always'
   enabled: true,                           // Default: __DEV__ (auto-disabled in production)
   maxRecordingDuration: 120,               // Max recording duration in seconds (default: 120)
   feedbackMode: 'batch',                   // 'live' | 'narrated' | 'batch' (default: 'batch')
@@ -662,6 +665,26 @@ SDK yields shake handling to Yaver's native overlay — see the
 YaverFeedback.init({ authToken, trigger: 'shake' });
 ```
 
+### No-shake build option
+
+If another surface owns motion / haptics and you want the SDK without shake detection, enable the non-default `disableShakeGesture` option:
+
+```typescript
+YaverFeedback.init({
+  authToken,
+  trigger: 'shake',
+  disableShakeGesture: true,
+});
+```
+
+Effects:
+
+- `ShakeDetector` is not started.
+- If `quickIcon` was unset / `'auto'`, the SDK promotes it to `'always'`.
+- The user opens feedback through the draggable quick icon or your own manual trigger.
+
+This is useful when Yaver Feedback should remain the only haptic/shake owner and the host app should not bind its own motion-triggered entry point.
+
 ### Floating Button
 
 A small draggable "Y" button overlays the app. Tap to open the feedback modal.

package/dist/MachinePickerScreen.js

@@ -121,8 +121,8 @@ const YaverMachinePickerScreen = ({ token, currentDeviceId, onPick, onCancel, })
         // yellows from phone↔backend clock skew around the 89-90 s mark.
         //
         // `runnerDown` intentionally does NOT flip the dot. That flag
-        // tracks whether the AI runner (claude-code, aider, ...) is
-        // healthy — a separate concern from "can I reach this machine?"
+        // tracks whether the AI runner (claude-code / codex / opencode)
+        // is healthy — a separate concern from "can I reach this machine?"
         // Mobile app surfaces runner issues via a separate badge, not
         // this dot. Picker's job is reachability, nothing more.
         const effectivelyReachable = probe?.reachable === true;

package/dist/YaverFeedback.js

@@ -113,6 +113,9 @@ class YaverFeedback {
             autoLogin: true,
             ...cfg,
         };
+        if (config.disableShakeGesture && (!config.quickIcon || config.quickIcon === 'auto')) {
+            config.quickIcon = 'always';
+        }
         firstShakeFired = false;
         // Route the in-SDK login screen to prod yaver.io by default; callers may
         // override for staging via authConvexSiteUrl / authWebBaseUrl.
@@ -129,12 +132,18 @@ class YaverFeedback {
         if (!config.convexUrl) {
             config.convexUrl = cfg.authConvexSiteUrl ?? auth_1.DEFAULT_CONVEX_SITE_URL;
         }
-        // Default: enabled only in dev mode
+        // Default: enabled. Pre-0.8.8 the SDK only enabled shake in dev
+        // builds (`__DEV__`), but apps that bundle the SDK explicitly *want*
+        // shake to work in TestFlight / Play Store builds — that's the
+        // primary use case (a tester finds a bug in a release build and
+        // shakes to report it). Dev builds get shake too. Apps that want
+        // to disable shake pass `enabled: false` (or
+        // `disableShakeGesture: true` for finer-grained control).
         if (cfg.enabled !== undefined) {
             enabled = cfg.enabled;
         }
         else {
-            enabled = typeof __DEV__ !== 'undefined' ? __DEV__ : false;
+            enabled = !cfg.disableShakeGesture;
         }
         // Hydrate cached auth token + preferred device from AsyncStorage so the
         // SDK reconnects silently on subsequent launches. If autoLogin is false
@@ -165,7 +174,7 @@ class YaverFeedback {
             shakeDetector.stop();
             shakeDetector = null;
         }
-        if (enabled && config.trigger === 'shake') {
+        if (enabled && config.trigger === 'shake' && !config.disableShakeGesture) {
             shakeDetector = new ShakeDetector_1.ShakeDetector();
             shakeDetector.start(() => {
                 YaverFeedback.notifyShake();
@@ -226,18 +235,40 @@ class YaverFeedback {
                     });
                 }
             });
-            // NOTE: BlackBox.start() is intentionally NOT auto-called here.
-            // An earlier version (0.7.6) did auto-start it, and when the
-            // agent was in bootstrap / needs-auth mode — which can happen
-            // any time after `yaver serve` restarts before the user pairs —
-            // the SSE channel retried with exponential backoff on 401s,
-            // producing a tight loop of string concatenation + JSON parse
-            // that tripped a Hermes rope-string SIGSEGV on iOS 18.3.1
-            // during any other JS-thread regex work (e.g. react-native-
-            // view-shot's internal string handling during Screenshot &
-            // Fix). Host apps call BlackBox.start() explicitly once they
-            // know the agent URL + token are valid (SFMG does this inside
-            // its YaverFeedbackWidget after auth).
+            // BlackBox auto-start (0.8.8+).
+            //
+            // 0.7.6 auto-started BlackBox immediately, which produced a
+            // Hermes rope-string SIGSEGV on iOS 18.3.1 when the agent was in
+            // bootstrap / needs-auth mode: the SSE channel retried with
+            // exponential backoff on 401s, generating a tight string-concat
+            // + JSON-parse loop that collided with react-native-view-shot's
+            // internal string handling during Screenshot & Fix. We rolled it
+            // back to manual-start (host calls BlackBox.start() after auth).
+            //
+            // The fix that lets us auto-start safely now:
+            //   1. Defer the start by 500ms so init() returns, the JS bridge
+            //      settles, and any first-launch auth-token round trip on
+            //      another thread completes before SSE opens.
+            //   2. Only start when we have BOTH an agentUrl AND an authToken
+            //      — without the token, the connect() call would 401 and we'd
+            //      reproduce the original loop.
+            //   3. Caller can opt out with cfg.autoStartBlackBox = false.
+            //
+            // SFMG used to call BlackBox.start() inside YaverFeedbackWidget
+            // after auth — that path still works (start() is idempotent), so
+            // upgrading SDK without removing the manual call is safe.
+            if (cfg.autoStartBlackBox !== false) {
+                setTimeout(() => {
+                    if (config?.agentUrl && (config?.authToken || p2pAuthToken)) {
+                        try {
+                            BlackBox_1.BlackBox.start();
+                        }
+                        catch (err) {
+                            console.warn('[YaverFeedback] BlackBox auto-start failed:', err);
+                        }
+                    }
+                }, 500);
+            }
         }
         // NOTE: We intentionally do NOT hook ErrorUtils.setGlobalHandler().
         // Sentry, Crashlytics, Bugsnag, and other tools all compete for that
@@ -552,7 +583,7 @@ class YaverFeedback {
                 BlackBox_1.BlackBox.start(); // restart with previous config
             }
             // Restart shake detector if trigger is 'shake'
-            if (config?.trigger === 'shake' && !shakeDetector) {
+            if (config?.trigger === 'shake' && !config?.disableShakeGesture && !shakeDetector) {
                 shakeDetector = new ShakeDetector_1.ShakeDetector();
                 shakeDetector.start(() => {
                     YaverFeedback.notifyShake();

package/dist/__tests__/AuthDevices.test.js

@@ -29,10 +29,10 @@ describe('auth device listing', () => {
                         platform: 'linux',
                         isOnline: true,
                         isGuest: true,
-                        hostName: 'Kivanc Cakmak',
-                        hostEmail: 'kivanc.cakmak@icloud.com',
+                        hostName: 'Host User',
+                        hostEmail: 'host@example.com',
                         accessScope: 'shared-scoped',
-                        quicHost: '157.180.114.179',
+                        quicHost: '198.51.100.20',
                         quicPort: 18080,
                         lastHeartbeat: 456,
                     },
@@ -49,7 +49,7 @@ describe('auth device listing', () => {
         expect(result.shared[0]).toMatchObject({
             deviceId: 'guest-1',
             isGuest: true,
-            hostEmail: 'kivanc.cakmak@icloud.com',
+            hostEmail: 'host@example.com',
             accessScope: 'shared-scoped',
         });
     });
@@ -64,10 +64,10 @@ describe('auth device listing', () => {
                         platform: 'linux',
                         isOnline: true,
                         isGuest: true,
-                        hostName: 'Kivanc Cakmak',
-                        hostEmail: 'kivanc.cakmak@icloud.com',
+                        hostName: 'Host User',
+                        hostEmail: 'host@example.com',
                         accessScope: 'shared-scoped',
-                        quicHost: '157.180.114.179',
+                        quicHost: '198.51.100.20',
                         quicPort: 18080,
                         lastHeartbeat: 789,
                     },

package/dist/__tests__/BlackBox.hotReload.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/BlackBox.hotReload.test.js

@@ -0,0 +1,204 @@
+"use strict";
+// Hot-reload command-channel coverage for BlackBox.
+//
+// The agent uses BlackBox's SSE channel as a back-channel to push
+// "reload" / "reload_bundle" commands into a running guest app
+// (see desktop/agent/blackbox.go::BroadcastCommand). This test
+// pins the SDK's contract:
+//
+//   1. onCommand(handler) registers a handler and returns an
+//      unsubscribe function that actually unsubscribes.
+//   2. start() opens the SSE command-stream against the agent
+//      with the proper URL + headers.
+//   3. When the SSE stream delivers a JSON message of the form
+//      {type:"command", command:{command:"reload", data:...}},
+//      the registered handler fires with the inner command.
+//   4. start() also schedules the periodic flush — proving start
+//      is idempotent over multiple calls.
+Object.defineProperty(exports, "__esModule", { value: true });
+const BlackBox_1 = require("../BlackBox");
+const YaverFeedback_1 = require("../YaverFeedback");
+jest.mock('react-native', () => ({
+    Platform: { OS: 'ios' },
+}));
+// Drive Date.now / setTimeout deterministically.
+jest.useFakeTimers();
+const mockFetch = jest.fn();
+global.fetch = mockFetch;
+class MockAbortController {
+    constructor() {
+        this.signal = { aborted: false };
+        this.abort = jest.fn(() => {
+            this.signal.aborted = true;
+        });
+    }
+}
+global.AbortController = MockAbortController;
+// Helper to build an SSE streaming body.
+function sseBody(messages) {
+    const enc = new TextEncoder();
+    const chunks = messages.map((m) => `data: ${JSON.stringify(m)}\n\n`);
+    return new ReadableStream({
+        start(controller) {
+            for (const c of chunks)
+                controller.enqueue(enc.encode(c));
+            controller.close();
+        },
+    });
+}
+beforeEach(() => {
+    jest.clearAllMocks();
+    // Default: every POST (events) and the SSE GET both succeed.
+    mockFetch.mockImplementation((url) => {
+        if (url.includes('/blackbox/command-stream')) {
+            return Promise.resolve({
+                ok: true,
+                body: sseBody([]),
+            });
+        }
+        return Promise.resolve({
+            ok: true,
+            json: () => Promise.resolve({}),
+        });
+    });
+    YaverFeedback_1.YaverFeedback.init({
+        agentUrl: 'http://localhost:18080',
+        authToken: 'tok',
+    });
+});
+afterEach(() => {
+    BlackBox_1.BlackBox.stop();
+});
+describe('BlackBox hot-reload command channel', () => {
+    it('onCommand returns an unsubscribe that removes the handler', () => {
+        const a = jest.fn();
+        const b = jest.fn();
+        const offA = BlackBox_1.BlackBox.onCommand(a);
+        const offB = BlackBox_1.BlackBox.onCommand(b);
+        // Both subscribed — calling internal dispatch directly via the
+        // public surface isn't easy without SSE mockery, but
+        // deregistering should still leave only `b` registered after
+        // offA(), then no handlers after offB().
+        offA();
+        offB();
+        // Re-subscribe and confirm subscription returns a fresh unsub.
+        const offC = BlackBox_1.BlackBox.onCommand(jest.fn());
+        expect(typeof offC).toBe('function');
+        offC();
+    });
+    it('start() opens SSE against /blackbox/command-stream with bearer + device headers', async () => {
+        BlackBox_1.BlackBox.start({ deviceId: 'dev-abc', appName: 'sfmg' });
+        // Allow the async fetch in connectSSE to fire.
+        await Promise.resolve();
+        await Promise.resolve();
+        const sseCall = mockFetch.mock.calls.find(([url]) => String(url).includes('/blackbox/command-stream'));
+        expect(sseCall).toBeDefined();
+        const [url, init] = sseCall;
+        expect(String(url)).toContain('http://localhost:18080/blackbox/command-stream');
+        expect(String(url)).toContain('device=dev-abc');
+        expect(init.headers).toEqual(expect.objectContaining({
+            Authorization: 'Bearer tok',
+            Accept: 'text/event-stream',
+            'X-Device-ID': 'dev-abc',
+            'X-App-Name': 'sfmg',
+        }));
+    });
+    it('dispatches a {type:"command", command:{command:"reload"}} SSE frame to handlers', async () => {
+        // SSE body delivers one reload command, then closes.
+        mockFetch.mockImplementation((url) => {
+            if (url.includes('/blackbox/command-stream')) {
+                return Promise.resolve({
+                    ok: true,
+                    body: sseBody([
+                        { type: 'command', command: { command: 'reload', data: {} } },
+                    ]),
+                });
+            }
+            return Promise.resolve({ ok: true, json: () => Promise.resolve({}) });
+        });
+        const seen = [];
+        BlackBox_1.BlackBox.onCommand((cmd) => seen.push(cmd));
+        BlackBox_1.BlackBox.start({ deviceId: 'dev-1', appName: 'sfmg' });
+        // Drain the microtask + reader queue. The reader is async but
+        // the body is fully buffered + the stream closes immediately,
+        // so a few microtask flushes are enough.
+        for (let i = 0; i < 10; i++)
+            await Promise.resolve();
+        expect(seen).toEqual([
+            expect.objectContaining({ command: 'reload', data: {} }),
+        ]);
+    });
+    it('dispatches a reload_bundle command (carries bundleUrl payload)', async () => {
+        mockFetch.mockImplementation((url) => {
+            if (url.includes('/blackbox/command-stream')) {
+                return Promise.resolve({
+                    ok: true,
+                    body: sseBody([
+                        {
+                            type: 'command',
+                            command: {
+                                command: 'reload_bundle',
+                                data: { bundleUrl: '/dev/native-bundle' },
+                            },
+                        },
+                    ]),
+                });
+            }
+            return Promise.resolve({ ok: true, json: () => Promise.resolve({}) });
+        });
+        const seen = [];
+        BlackBox_1.BlackBox.onCommand((cmd) => seen.push(cmd));
+        BlackBox_1.BlackBox.start({ deviceId: 'dev-1', appName: 'sfmg' });
+        for (let i = 0; i < 10; i++)
+            await Promise.resolve();
+        expect(seen).toEqual([
+            expect.objectContaining({
+                command: 'reload_bundle',
+                data: expect.objectContaining({ bundleUrl: '/dev/native-bundle' }),
+            }),
+        ]);
+    });
+    it('handler exception does not break sibling handlers', async () => {
+        mockFetch.mockImplementation((url) => {
+            if (url.includes('/blackbox/command-stream')) {
+                return Promise.resolve({
+                    ok: true,
+                    body: sseBody([
+                        { type: 'command', command: { command: 'reload' } },
+                    ]),
+                });
+            }
+            return Promise.resolve({ ok: true, json: () => Promise.resolve({}) });
+        });
+        const sibling = jest.fn();
+        BlackBox_1.BlackBox.onCommand(() => {
+            throw new Error('caller bug — should not break the dispatch loop');
+        });
+        BlackBox_1.BlackBox.onCommand(sibling);
+        BlackBox_1.BlackBox.start({ deviceId: 'dev-1', appName: 'sfmg' });
+        for (let i = 0; i < 10; i++)
+            await Promise.resolve();
+        expect(sibling).toHaveBeenCalledWith(expect.objectContaining({ command: 'reload' }));
+    });
+    it('ignores non-command SSE frames (events/log/whatever)', async () => {
+        mockFetch.mockImplementation((url) => {
+            if (url.includes('/blackbox/command-stream')) {
+                return Promise.resolve({
+                    ok: true,
+                    body: sseBody([
+                        { type: 'log', logLine: 'hi' },
+                        { type: 'lifecycle', message: 'started' },
+                        { ping: 1 },
+                    ]),
+                });
+            }
+            return Promise.resolve({ ok: true, json: () => Promise.resolve({}) });
+        });
+        const handler = jest.fn();
+        BlackBox_1.BlackBox.onCommand(handler);
+        BlackBox_1.BlackBox.start({ deviceId: 'dev-1', appName: 'sfmg' });
+        for (let i = 0; i < 10; i++)
+            await Promise.resolve();
+        expect(handler).not.toHaveBeenCalled();
+    });
+});

package/dist/__tests__/P2PClient.test.js

@@ -195,5 +195,61 @@ describe('P2PClient', () => {
                 message: 'Reload request acknowledged. Agent is rebuilding the bundle.',
             }));
         });
+        it('dev mode hits /dev/reload with bearer auth', async () => {
+            mockFetch.mockResolvedValue({
+                ok: true,
+                json: () => Promise.resolve({ ok: true }),
+            });
+            const client = new P2PClient_1.P2PClient('http://localhost:18080', 'tok');
+            await client.reloadApp('dev');
+            expect(mockFetch).toHaveBeenCalledWith('http://localhost:18080/dev/reload', expect.objectContaining({
+                method: 'POST',
+                headers: expect.objectContaining({ Authorization: 'Bearer tok' }),
+            }));
+        });
+        it('bundle mode hits /dev/reload-app with mode + projectName in body', async () => {
+            mockFetch.mockResolvedValue({
+                ok: true,
+                json: () => Promise.resolve({ ok: true }),
+            });
+            const client = new P2PClient_1.P2PClient('http://localhost:18080', 'tok');
+            await client.reloadApp('bundle', { projectName: 'sfmg' });
+            const [url, init] = mockFetch.mock.calls[0];
+            expect(url).toBe('http://localhost:18080/dev/reload-app');
+            expect(init.method).toBe('POST');
+            expect(JSON.parse(init.body)).toEqual(expect.objectContaining({ mode: 'bundle', projectName: 'sfmg' }));
+            expect(init.headers).toEqual(expect.objectContaining({
+                Authorization: 'Bearer tok',
+                'Content-Type': 'application/json',
+            }));
+        });
+        it('dev mode falls back to /dev/reload-app when /dev/reload 4xxs', async () => {
+            // First call: /dev/reload 404. Second: /dev/reload-app 200.
+            mockFetch
+                .mockResolvedValueOnce({ ok: false, status: 404, json: () => Promise.resolve({}) })
+                .mockResolvedValueOnce({ ok: true, json: () => Promise.resolve({ ok: true }) });
+            const client = new P2PClient_1.P2PClient('http://localhost:18080', 'tok');
+            const result = await client.reloadApp('dev', { projectName: 'sfmg' });
+            expect(mockFetch).toHaveBeenCalledTimes(2);
+            expect(mockFetch.mock.calls[0][0]).toBe('http://localhost:18080/dev/reload');
+            expect(mockFetch.mock.calls[1][0]).toBe('http://localhost:18080/dev/reload-app');
+            expect(result.ok).toBe(true);
+        });
+        it('surfaces nativeChangesDetected so the host can prompt for rebuild', async () => {
+            mockFetch.mockResolvedValue({
+                ok: true,
+                json: () => Promise.resolve({
+                    ok: true,
+                    nativeChangesDetected: true,
+                    changeClass: 'native_required',
+                }),
+            });
+            const client = new P2PClient_1.P2PClient('http://localhost:18080', 'tok');
+            const result = await client.reloadApp('dev');
+            expect(result.nativeChangesDetected).toBe(true);
+            expect(result.changeClass).toBe('native_required');
+            // Caller-visible message must distinguish native-required from JS-only.
+            expect(result.message).toMatch(/native|rebuild/i);
+        });
     });
 });

package/dist/__tests__/YaverFeedback.test.js

@@ -76,6 +76,15 @@ describe('YaverFeedback', () => {
             expect(cfg.maxRecordingDuration).toBe(60);
             expect(cfg.strictNativeAuth).toBe(true);
         });
+        it('promotes quick icon to always when shake is disabled', () => {
+            YaverFeedback_1.YaverFeedback.init({
+                authToken: 'tok',
+                disableShakeGesture: true,
+            });
+            const cfg = YaverFeedback_1.YaverFeedback.getConfig();
+            expect(cfg.disableShakeGesture).toBe(true);
+            expect(cfg.quickIcon).toBe('always');
+        });
         it('with enabled=false sets enabled to false', () => {
             YaverFeedback_1.YaverFeedback.init({
                 authToken: 'tok',

package/dist/__tests__/types.test.js

@@ -17,11 +17,13 @@ describe('React Native SDK types', () => {
                 authToken: 'tok',
                 agentUrl: 'http://192.168.1.10:18080',
                 trigger: 'shake',
+                disableShakeGesture: true,
                 enabled: true,
                 maxRecordingDuration: 60,
                 strictNativeAuth: true,
             };
             expect(config.trigger).toBe('shake');
+            expect(config.disableShakeGesture).toBe(true);
             expect(config.strictNativeAuth).toBe(true);
         });
         it('accepts all trigger types', () => {

package/dist/_core/constants.d.ts

@@ -27,9 +27,13 @@ export declare const DEFAULT_BEACON_UDP_PORT = 19837;
 /**
  * How old an agent's last heartbeat can be before the device is
  * considered offline. Mirrors `backend/convex/devices.ts` so
- * Convex + every client agree on the same threshold.
+ * Convex + every client agree on the same threshold. The agent
+ * heartbeats every 5 min (see `desktop/agent/main.go::heartbeatLoop`),
+ * so 6 min tolerates one missed beat + 60 s of jitter without
+ * flapping. Sub-minute death detection comes from the P2P bus, not
+ * this threshold.
  */
-export declare const HEARTBEAT_STALE_MS = 90000;
+export declare const HEARTBEAT_STALE_MS = 360000;
 /**
  * How long after the last UDP beacon an agent is still considered
  * "locally present". Re-broadcast interval is 3 s, so 10 s covers

package/dist/_core/constants.js

@@ -51,9 +51,13 @@ exports.DEFAULT_BEACON_UDP_PORT = 19837;
 /**
  * How old an agent's last heartbeat can be before the device is
  * considered offline. Mirrors `backend/convex/devices.ts` so
- * Convex + every client agree on the same threshold.
+ * Convex + every client agree on the same threshold. The agent
+ * heartbeats every 5 min (see `desktop/agent/main.go::heartbeatLoop`),
+ * so 6 min tolerates one missed beat + 60 s of jitter without
+ * flapping. Sub-minute death detection comes from the P2P bus, not
+ * this threshold.
  */
-exports.HEARTBEAT_STALE_MS = 90000;
+exports.HEARTBEAT_STALE_MS = 360000;
 /**
  * How long after the last UDP beacon an agent is still considered
  * "locally present". Re-broadcast interval is 3 s, so 10 s covers

package/dist/types.d.ts

@@ -118,6 +118,35 @@ export interface FeedbackConfig {
     preferredDeviceId?: string;
     /** How feedback collection is triggered */
     trigger?: 'shake' | 'floating-button' | 'manual';
+    /**
+     * Non-default escape hatch for host apps that want the SDK without
+     * shake gesture handling. When enabled:
+     * - the SDK does not start ShakeDetector
+     * - if `quickIcon` was left as `'auto'`/unset, it is promoted to `'always'`
+     * - the app should rely on the draggable quick icon or explicit
+     *   `YaverFeedback.startReport()` calls instead
+     *
+     * Intended for builds where another surface owns motion / haptics.
+     */
+    disableShakeGesture?: boolean;
+    /**
+     * Auto-open the BlackBox SSE command channel after init() returns.
+     *
+     * Default: `true` (0.8.8+). Listens for `reload`, `reload_bundle`,
+     * and `status` commands the agent broadcasts after a vibe-coding
+     * task commits a fix — drives the auto-reload loop without the host
+     * app needing to call `BlackBox.start()` manually.
+     *
+     * The auto-start is deferred 500ms after init() and gated on having
+     * BOTH `agentUrl` and `authToken` resolved, to avoid the iOS 18.3.1
+     * rope-string SIGSEGV that the early auto-start in 0.7.6 hit when
+     * the agent was in needs-auth mode (tight 401-retry loop in SSE).
+     *
+     * Set `false` if your host app wants to gate BlackBox start on its
+     * own state machine (e.g. only after the user opts into telemetry).
+     * Calling `BlackBox.start()` manually is still safe — it's idempotent.
+     */
+    autoStartBlackBox?: boolean;
     /**
      * Small tap-to-open icon that floats above the app so the user
      * doesn't have to shake every time they want to open feedback.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yaver-feedback-react-native",
-  "version": "0.8.7",
+  "version": "0.8.8",
   "description": "Visual feedback SDK for Yaver \u2014 bug reports, screen recording, voice annotations, and local-first developer workflows",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/MachinePickerScreen.tsx

@@ -120,8 +120,8 @@ export const YaverMachinePickerScreen: React.FC<YaverMachinePickerProps> = ({
     // yellows from phone↔backend clock skew around the 89-90 s mark.
     //
     // `runnerDown` intentionally does NOT flip the dot. That flag
-    // tracks whether the AI runner (claude-code, aider, ...) is
-    // healthy — a separate concern from "can I reach this machine?"
+    // tracks whether the AI runner (claude-code / codex / opencode)
+    // is healthy — a separate concern from "can I reach this machine?"
     // Mobile app surfaces runner issues via a separate badge, not
     // this dot. Picker's job is reachability, nothing more.
     const effectivelyReachable = probe?.reachable === true;

package/src/YaverFeedback.ts

@@ -137,6 +137,9 @@ export class YaverFeedback {
       autoLogin: true,
       ...cfg,
     };
+    if (config.disableShakeGesture && (!config.quickIcon || config.quickIcon === 'auto')) {
+      config.quickIcon = 'always';
+    }
     firstShakeFired = false;
 
     // Route the in-SDK login screen to prod yaver.io by default; callers may
@@ -155,11 +158,17 @@ export class YaverFeedback {
       config.convexUrl = cfg.authConvexSiteUrl ?? DEFAULT_CONVEX_SITE_URL;
     }
 
-    // Default: enabled only in dev mode
+    // Default: enabled. Pre-0.8.8 the SDK only enabled shake in dev
+    // builds (`__DEV__`), but apps that bundle the SDK explicitly *want*
+    // shake to work in TestFlight / Play Store builds — that's the
+    // primary use case (a tester finds a bug in a release build and
+    // shakes to report it). Dev builds get shake too. Apps that want
+    // to disable shake pass `enabled: false` (or
+    // `disableShakeGesture: true` for finer-grained control).
     if (cfg.enabled !== undefined) {
       enabled = cfg.enabled;
     } else {
-      enabled = typeof __DEV__ !== 'undefined' ? __DEV__ : false;
+      enabled = !cfg.disableShakeGesture;
     }
 
     // Hydrate cached auth token + preferred device from AsyncStorage so the
@@ -193,7 +202,7 @@ export class YaverFeedback {
       shakeDetector.stop();
       shakeDetector = null;
     }
-    if (enabled && config.trigger === 'shake') {
+    if (enabled && config.trigger === 'shake' && !config.disableShakeGesture) {
       shakeDetector = new ShakeDetector();
       shakeDetector.start(() => {
         YaverFeedback.notifyShake();
@@ -253,18 +262,39 @@ export class YaverFeedback {
           });
         }
       });
-      // NOTE: BlackBox.start() is intentionally NOT auto-called here.
-      // An earlier version (0.7.6) did auto-start it, and when the
-      // agent was in bootstrap / needs-auth mode — which can happen
-      // any time after `yaver serve` restarts before the user pairs —
-      // the SSE channel retried with exponential backoff on 401s,
-      // producing a tight loop of string concatenation + JSON parse
-      // that tripped a Hermes rope-string SIGSEGV on iOS 18.3.1
-      // during any other JS-thread regex work (e.g. react-native-
-      // view-shot's internal string handling during Screenshot &
-      // Fix). Host apps call BlackBox.start() explicitly once they
-      // know the agent URL + token are valid (SFMG does this inside
-      // its YaverFeedbackWidget after auth).
+      // BlackBox auto-start (0.8.8+).
+      //
+      // 0.7.6 auto-started BlackBox immediately, which produced a
+      // Hermes rope-string SIGSEGV on iOS 18.3.1 when the agent was in
+      // bootstrap / needs-auth mode: the SSE channel retried with
+      // exponential backoff on 401s, generating a tight string-concat
+      // + JSON-parse loop that collided with react-native-view-shot's
+      // internal string handling during Screenshot & Fix. We rolled it
+      // back to manual-start (host calls BlackBox.start() after auth).
+      //
+      // The fix that lets us auto-start safely now:
+      //   1. Defer the start by 500ms so init() returns, the JS bridge
+      //      settles, and any first-launch auth-token round trip on
+      //      another thread completes before SSE opens.
+      //   2. Only start when we have BOTH an agentUrl AND an authToken
+      //      — without the token, the connect() call would 401 and we'd
+      //      reproduce the original loop.
+      //   3. Caller can opt out with cfg.autoStartBlackBox = false.
+      //
+      // SFMG used to call BlackBox.start() inside YaverFeedbackWidget
+      // after auth — that path still works (start() is idempotent), so
+      // upgrading SDK without removing the manual call is safe.
+      if (cfg.autoStartBlackBox !== false) {
+        setTimeout(() => {
+          if (config?.agentUrl && (config?.authToken || p2pAuthToken)) {
+            try {
+              BlackBox.start();
+            } catch (err) {
+              console.warn('[YaverFeedback] BlackBox auto-start failed:', err);
+            }
+          }
+        }, 500);
+      }
     }
 
     // NOTE: We intentionally do NOT hook ErrorUtils.setGlobalHandler().
@@ -583,7 +613,7 @@ export class YaverFeedback {
         BlackBox.start(); // restart with previous config
       }
       // Restart shake detector if trigger is 'shake'
-      if (config?.trigger === 'shake' && !shakeDetector) {
+      if (config?.trigger === 'shake' && !config?.disableShakeGesture && !shakeDetector) {
         shakeDetector = new ShakeDetector();
         shakeDetector.start(() => {
           YaverFeedback.notifyShake();

package/src/__tests__/AuthDevices.test.ts

@@ -31,10 +31,10 @@ describe('auth device listing', () => {
               platform: 'linux',
               isOnline: true,
               isGuest: true,
-              hostName: 'Kivanc Cakmak',
-              hostEmail: 'kivanc.cakmak@icloud.com',
+              hostName: 'Host User',
+              hostEmail: 'host@example.com',
               accessScope: 'shared-scoped',
-              quicHost: '157.180.114.179',
+              quicHost: '198.51.100.20',
               quicPort: 18080,
               lastHeartbeat: 456,
             },
@@ -56,7 +56,7 @@ describe('auth device listing', () => {
     expect(result.shared[0]).toMatchObject({
       deviceId: 'guest-1',
       isGuest: true,
-      hostEmail: 'kivanc.cakmak@icloud.com',
+      hostEmail: 'host@example.com',
       accessScope: 'shared-scoped',
     });
   });
@@ -73,10 +73,10 @@ describe('auth device listing', () => {
               platform: 'linux',
               isOnline: true,
               isGuest: true,
-              hostName: 'Kivanc Cakmak',
-              hostEmail: 'kivanc.cakmak@icloud.com',
+              hostName: 'Host User',
+              hostEmail: 'host@example.com',
               accessScope: 'shared-scoped',
-              quicHost: '157.180.114.179',
+              quicHost: '198.51.100.20',
               quicPort: 18080,
               lastHeartbeat: 789,
             },

package/src/__tests__/BlackBox.hotReload.test.ts

@@ -0,0 +1,226 @@
+// Hot-reload command-channel coverage for BlackBox.
+//
+// The agent uses BlackBox's SSE channel as a back-channel to push
+// "reload" / "reload_bundle" commands into a running guest app
+// (see desktop/agent/blackbox.go::BroadcastCommand). This test
+// pins the SDK's contract:
+//
+//   1. onCommand(handler) registers a handler and returns an
+//      unsubscribe function that actually unsubscribes.
+//   2. start() opens the SSE command-stream against the agent
+//      with the proper URL + headers.
+//   3. When the SSE stream delivers a JSON message of the form
+//      {type:"command", command:{command:"reload", data:...}},
+//      the registered handler fires with the inner command.
+//   4. start() also schedules the periodic flush — proving start
+//      is idempotent over multiple calls.
+
+import { BlackBox } from '../BlackBox';
+import { YaverFeedback } from '../YaverFeedback';
+
+jest.mock('react-native', () => ({
+  Platform: { OS: 'ios' },
+}));
+
+// Drive Date.now / setTimeout deterministically.
+jest.useFakeTimers();
+
+const mockFetch = jest.fn();
+global.fetch = mockFetch as any;
+
+class MockAbortController {
+  signal = { aborted: false };
+  abort = jest.fn(() => {
+    this.signal.aborted = true;
+  });
+}
+global.AbortController = MockAbortController as any;
+
+// Helper to build an SSE streaming body.
+function sseBody(messages: Array<unknown>): ReadableStream<Uint8Array> {
+  const enc = new TextEncoder();
+  const chunks = messages.map((m) => `data: ${JSON.stringify(m)}\n\n`);
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      for (const c of chunks) controller.enqueue(enc.encode(c));
+      controller.close();
+    },
+  });
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  // Default: every POST (events) and the SSE GET both succeed.
+  mockFetch.mockImplementation((url: string) => {
+    if (url.includes('/blackbox/command-stream')) {
+      return Promise.resolve({
+        ok: true,
+        body: sseBody([]),
+      });
+    }
+    return Promise.resolve({
+      ok: true,
+      json: () => Promise.resolve({}),
+    });
+  });
+  YaverFeedback.init({
+    agentUrl: 'http://localhost:18080',
+    authToken: 'tok',
+  });
+});
+
+afterEach(() => {
+  BlackBox.stop();
+});
+
+describe('BlackBox hot-reload command channel', () => {
+  it('onCommand returns an unsubscribe that removes the handler', () => {
+    const a = jest.fn();
+    const b = jest.fn();
+    const offA = BlackBox.onCommand(a);
+    const offB = BlackBox.onCommand(b);
+
+    // Both subscribed — calling internal dispatch directly via the
+    // public surface isn't easy without SSE mockery, but
+    // deregistering should still leave only `b` registered after
+    // offA(), then no handlers after offB().
+    offA();
+    offB();
+    // Re-subscribe and confirm subscription returns a fresh unsub.
+    const offC = BlackBox.onCommand(jest.fn());
+    expect(typeof offC).toBe('function');
+    offC();
+  });
+
+  it('start() opens SSE against /blackbox/command-stream with bearer + device headers', async () => {
+    BlackBox.start({ deviceId: 'dev-abc', appName: 'sfmg' });
+    // Allow the async fetch in connectSSE to fire.
+    await Promise.resolve();
+    await Promise.resolve();
+
+    const sseCall = mockFetch.mock.calls.find(([url]) =>
+      String(url).includes('/blackbox/command-stream'),
+    );
+    expect(sseCall).toBeDefined();
+    const [url, init] = sseCall!;
+    expect(String(url)).toContain('http://localhost:18080/blackbox/command-stream');
+    expect(String(url)).toContain('device=dev-abc');
+    expect(init.headers).toEqual(
+      expect.objectContaining({
+        Authorization: 'Bearer tok',
+        Accept: 'text/event-stream',
+        'X-Device-ID': 'dev-abc',
+        'X-App-Name': 'sfmg',
+      }),
+    );
+  });
+
+  it('dispatches a {type:"command", command:{command:"reload"}} SSE frame to handlers', async () => {
+    // SSE body delivers one reload command, then closes.
+    mockFetch.mockImplementation((url: string) => {
+      if (url.includes('/blackbox/command-stream')) {
+        return Promise.resolve({
+          ok: true,
+          body: sseBody([
+            { type: 'command', command: { command: 'reload', data: {} } },
+          ]),
+        });
+      }
+      return Promise.resolve({ ok: true, json: () => Promise.resolve({}) });
+    });
+
+    const seen: any[] = [];
+    BlackBox.onCommand((cmd) => seen.push(cmd));
+    BlackBox.start({ deviceId: 'dev-1', appName: 'sfmg' });
+
+    // Drain the microtask + reader queue. The reader is async but
+    // the body is fully buffered + the stream closes immediately,
+    // so a few microtask flushes are enough.
+    for (let i = 0; i < 10; i++) await Promise.resolve();
+
+    expect(seen).toEqual([
+      expect.objectContaining({ command: 'reload', data: {} }),
+    ]);
+  });
+
+  it('dispatches a reload_bundle command (carries bundleUrl payload)', async () => {
+    mockFetch.mockImplementation((url: string) => {
+      if (url.includes('/blackbox/command-stream')) {
+        return Promise.resolve({
+          ok: true,
+          body: sseBody([
+            {
+              type: 'command',
+              command: {
+                command: 'reload_bundle',
+                data: { bundleUrl: '/dev/native-bundle' },
+              },
+            },
+          ]),
+        });
+      }
+      return Promise.resolve({ ok: true, json: () => Promise.resolve({}) });
+    });
+
+    const seen: any[] = [];
+    BlackBox.onCommand((cmd) => seen.push(cmd));
+    BlackBox.start({ deviceId: 'dev-1', appName: 'sfmg' });
+    for (let i = 0; i < 10; i++) await Promise.resolve();
+
+    expect(seen).toEqual([
+      expect.objectContaining({
+        command: 'reload_bundle',
+        data: expect.objectContaining({ bundleUrl: '/dev/native-bundle' }),
+      }),
+    ]);
+  });
+
+  it('handler exception does not break sibling handlers', async () => {
+    mockFetch.mockImplementation((url: string) => {
+      if (url.includes('/blackbox/command-stream')) {
+        return Promise.resolve({
+          ok: true,
+          body: sseBody([
+            { type: 'command', command: { command: 'reload' } },
+          ]),
+        });
+      }
+      return Promise.resolve({ ok: true, json: () => Promise.resolve({}) });
+    });
+
+    const sibling = jest.fn();
+    BlackBox.onCommand(() => {
+      throw new Error('caller bug — should not break the dispatch loop');
+    });
+    BlackBox.onCommand(sibling);
+
+    BlackBox.start({ deviceId: 'dev-1', appName: 'sfmg' });
+    for (let i = 0; i < 10; i++) await Promise.resolve();
+
+    expect(sibling).toHaveBeenCalledWith(
+      expect.objectContaining({ command: 'reload' }),
+    );
+  });
+
+  it('ignores non-command SSE frames (events/log/whatever)', async () => {
+    mockFetch.mockImplementation((url: string) => {
+      if (url.includes('/blackbox/command-stream')) {
+        return Promise.resolve({
+          ok: true,
+          body: sseBody([
+            { type: 'log', logLine: 'hi' },
+            { type: 'lifecycle', message: 'started' },
+            { ping: 1 },
+          ]),
+        });
+      }
+      return Promise.resolve({ ok: true, json: () => Promise.resolve({}) });
+    });
+
+    const handler = jest.fn();
+    BlackBox.onCommand(handler);
+    BlackBox.start({ deviceId: 'dev-1', appName: 'sfmg' });
+    for (let i = 0; i < 10; i++) await Promise.resolve();
+    expect(handler).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/P2PClient.test.ts

@@ -254,5 +254,75 @@ describe('P2PClient', () => {
         }),
       );
     });
+
+    it('dev mode hits /dev/reload with bearer auth', async () => {
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({ ok: true }),
+      });
+      const client = new P2PClient('http://localhost:18080', 'tok');
+      await client.reloadApp('dev');
+      expect(mockFetch).toHaveBeenCalledWith(
+        'http://localhost:18080/dev/reload',
+        expect.objectContaining({
+          method: 'POST',
+          headers: expect.objectContaining({ Authorization: 'Bearer tok' }),
+        }),
+      );
+    });
+
+    it('bundle mode hits /dev/reload-app with mode + projectName in body', async () => {
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({ ok: true }),
+      });
+      const client = new P2PClient('http://localhost:18080', 'tok');
+      await client.reloadApp('bundle', { projectName: 'sfmg' });
+      const [url, init] = mockFetch.mock.calls[0];
+      expect(url).toBe('http://localhost:18080/dev/reload-app');
+      expect(init.method).toBe('POST');
+      expect(JSON.parse(init.body as string)).toEqual(
+        expect.objectContaining({ mode: 'bundle', projectName: 'sfmg' }),
+      );
+      expect(init.headers).toEqual(
+        expect.objectContaining({
+          Authorization: 'Bearer tok',
+          'Content-Type': 'application/json',
+        }),
+      );
+    });
+
+    it('dev mode falls back to /dev/reload-app when /dev/reload 4xxs', async () => {
+      // First call: /dev/reload 404. Second: /dev/reload-app 200.
+      mockFetch
+        .mockResolvedValueOnce({ ok: false, status: 404, json: () => Promise.resolve({}) })
+        .mockResolvedValueOnce({ ok: true, json: () => Promise.resolve({ ok: true }) });
+
+      const client = new P2PClient('http://localhost:18080', 'tok');
+      const result = await client.reloadApp('dev', { projectName: 'sfmg' });
+
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+      expect(mockFetch.mock.calls[0][0]).toBe('http://localhost:18080/dev/reload');
+      expect(mockFetch.mock.calls[1][0]).toBe('http://localhost:18080/dev/reload-app');
+      expect(result.ok).toBe(true);
+    });
+
+    it('surfaces nativeChangesDetected so the host can prompt for rebuild', async () => {
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: () =>
+          Promise.resolve({
+            ok: true,
+            nativeChangesDetected: true,
+            changeClass: 'native_required',
+          }),
+      });
+      const client = new P2PClient('http://localhost:18080', 'tok');
+      const result = await client.reloadApp('dev');
+      expect(result.nativeChangesDetected).toBe(true);
+      expect(result.changeClass).toBe('native_required');
+      // Caller-visible message must distinguish native-required from JS-only.
+      expect(result.message).toMatch(/native|rebuild/i);
+    });
   });
 });

package/src/__tests__/YaverFeedback.test.ts

@@ -83,6 +83,17 @@ describe('YaverFeedback', () => {
       expect(cfg!.strictNativeAuth).toBe(true);
     });
 
+    it('promotes quick icon to always when shake is disabled', () => {
+      YaverFeedback.init({
+        authToken: 'tok',
+        disableShakeGesture: true,
+      });
+
+      const cfg = YaverFeedback.getConfig();
+      expect(cfg!.disableShakeGesture).toBe(true);
+      expect(cfg!.quickIcon).toBe('always');
+    });
+
     it('with enabled=false sets enabled to false', () => {
       YaverFeedback.init({
         authToken: 'tok',

package/src/__tests__/types.test.ts

@@ -27,11 +27,13 @@ describe('React Native SDK types', () => {
         authToken: 'tok',
         agentUrl: 'http://192.168.1.10:18080',
         trigger: 'shake',
+        disableShakeGesture: true,
         enabled: true,
         maxRecordingDuration: 60,
         strictNativeAuth: true,
       };
       expect(config.trigger).toBe('shake');
+      expect(config.disableShakeGesture).toBe(true);
       expect(config.strictNativeAuth).toBe(true);
     });
 

package/src/_core/constants.ts

@@ -57,9 +57,13 @@ export const DEFAULT_BEACON_UDP_PORT = 19837;
 /**
  * How old an agent's last heartbeat can be before the device is
  * considered offline. Mirrors `backend/convex/devices.ts` so
- * Convex + every client agree on the same threshold.
+ * Convex + every client agree on the same threshold. The agent
+ * heartbeats every 5 min (see `desktop/agent/main.go::heartbeatLoop`),
+ * so 6 min tolerates one missed beat + 60 s of jitter without
+ * flapping. Sub-minute death detection comes from the P2P bus, not
+ * this threshold.
  */
-export const HEARTBEAT_STALE_MS = 90_000;
+export const HEARTBEAT_STALE_MS = 360_000;
 
 /**
  * How long after the last UDP beacon an agent is still considered

package/src/types.ts

@@ -123,6 +123,35 @@ export interface FeedbackConfig {
   preferredDeviceId?: string;
   /** How feedback collection is triggered */
   trigger?: 'shake' | 'floating-button' | 'manual';
+  /**
+   * Non-default escape hatch for host apps that want the SDK without
+   * shake gesture handling. When enabled:
+   * - the SDK does not start ShakeDetector
+   * - if `quickIcon` was left as `'auto'`/unset, it is promoted to `'always'`
+   * - the app should rely on the draggable quick icon or explicit
+   *   `YaverFeedback.startReport()` calls instead
+   *
+   * Intended for builds where another surface owns motion / haptics.
+   */
+  disableShakeGesture?: boolean;
+  /**
+   * Auto-open the BlackBox SSE command channel after init() returns.
+   *
+   * Default: `true` (0.8.8+). Listens for `reload`, `reload_bundle`,
+   * and `status` commands the agent broadcasts after a vibe-coding
+   * task commits a fix — drives the auto-reload loop without the host
+   * app needing to call `BlackBox.start()` manually.
+   *
+   * The auto-start is deferred 500ms after init() and gated on having
+   * BOTH `agentUrl` and `authToken` resolved, to avoid the iOS 18.3.1
+   * rope-string SIGSEGV that the early auto-start in 0.7.6 hit when
+   * the agent was in needs-auth mode (tight 401-retry loop in SSE).
+   *
+   * Set `false` if your host app wants to gate BlackBox start on its
+   * own state machine (e.g. only after the user opts into telemetry).
+   * Calling `BlackBox.start()` manually is still safe — it's idempotent.
+   */
+  autoStartBlackBox?: boolean;
   /**
    * Small tap-to-open icon that floats above the app so the user
    * doesn't have to shake every time they want to open feedback.