yaver-feedback-react-native 0.9.0 → 0.9.3

package/src/YaverFeedback.ts

@@ -1,16 +1,20 @@
-import { NativeModules } from 'react-native';
+import { NativeModules, Platform } from 'react-native';
 import { FeedbackConfig, CapturedError } from './types';
 import { YaverDiscovery } from './Discovery';
 import { BlackBox } from './BlackBox';
-import { P2PClient } from './P2PClient';
+import { P2PClient, resolveReportIdentity } from './P2PClient';
 import { ShakeDetector } from './ShakeDetector';
+import {
+  captureStoreScreenshots,
+  CaptureStoreScreenshotsOptions,
+  CaptureStoreScreenshotsResult,
+} from './storeShots';
 import {
   configureAuthEndpoints,
   setStrictNativeAuth,
   getToken,
   getSelectedDeviceId,
   listReachableDevices,
-  mintGuestSdkToken,
   clearToken,
   clearSelectedDeviceId,
   DEFAULT_CONVEX_SITE_URL,
@@ -22,6 +26,22 @@ import {
   setQuickIconColorPreset,
   QuickIconColorPreset,
 } from './preferences';
+import { resolveSDKDogfood, type SDKDogfoodStatus } from './dogfoodPolicy';
+import { YaverDeviceDogfood, type DeviceDogfoodOptions, type DeviceDogfoodSession, type DeviceDogfoodState } from './deviceDogfood';
+
+export interface DogfoodOnboardingOptions extends DeviceDogfoodOptions {
+  /** Hint used to preselect the matching project returned by the owner machine. */
+  projectName?: string;
+  /** Framework fallback when the machine has not classified the project yet. */
+  framework?: string;
+}
+
+function unrefTimer(timer: ReturnType<typeof setTimeout>): void {
+  const maybeNodeTimer = timer as unknown as { unref?: () => void };
+  if (typeof maybeNodeTimer.unref === 'function') {
+    maybeNodeTimer.unref();
+  }
+}
 
 // Is this JS runtime the Yaver mobile app's super-host bridge? The
 // YaverInfo native module is only registered inside Yaver's container
@@ -146,10 +166,19 @@ if (IS_HOST_MODE) {
 let config: FeedbackConfig | null = null;
 let enabled = false;
 let p2pClient: P2PClient | null = null;
+let renderP2PClient: P2PClient | null = null;
 let shakeDetector: ShakeDetector | null = null;
+/** Unsubscribe for the BlackBox command handler registered by init(). Held so
+ *  a re-init (or destroy) can drop the old one instead of stacking. */
+let commandUnsubscribe: (() => void) | null = null;
 let p2pAuthToken: string | null = null;
 let p2pRelayPassword: string = '';
+/** Pending BlackBox auto-start retry. Held so destroy()/re-init can cancel it
+ *  instead of leaving a timer chain running against a torn-down config. */
+let autoStartTimer: ReturnType<typeof setTimeout> | null = null;
 let reportLaunchInFlight = false;
+let crashReportInFlight = false;
+let dogfoodOnboarding: DogfoodOnboardingOptions | null = null;
 
 /** Resolve the user's relay password by validating their auth token
  *  against Convex. Used whenever we (re)build the P2PClient so a
@@ -196,6 +225,7 @@ async function resolveRelayPassword(authToken: string, convexUrl?: string): Prom
 /** Ring buffer of captured errors. */
 let errorBuffer: CapturedError[] = [];
 let maxErrors = 5;
+let crashHandlerInstalled = false;
 
 /** Track whether BlackBox was running before disable (to restart on enable). */
 let blackBoxWasStreaming = false;
@@ -221,42 +251,35 @@ const flagCache: Map<string, { value: unknown; at: number }> = new Map();
  */
 export class YaverFeedback {
   private static async resolveP2PAuthToken(): Promise<string | null> {
-    if (!config?.authToken) return null;
-    if (!config.preferredDeviceId) return config.authToken;
-    const devices = await listReachableDevices(config.authToken);
-    const all = [...devices.owned, ...devices.shared];
-    const selected = all.find((device) => device.deviceId === config?.preferredDeviceId);
-    if (!selected || !selected.isGuest || selected.accessScope !== 'shared-scoped') {
-      return config.authToken;
-    }
-    if (!selected.hostUserId) {
-      return config.authToken;
-    }
-    const delegated = await mintGuestSdkToken(
-      config.authToken,
-      selected.hostUserId,
-      selected.deviceId,
-    );
-    return delegated.token;
+    return config?.authToken ?? null;
   }
 
   private static async rebuildP2PClient(agentUrl?: string): Promise<void> {
-    if (!config) return;
-    const effectiveUrl = agentUrl ?? config.agentUrl;
+    const currentConfig = config;
+    if (!currentConfig) return;
+    const effectiveUrl = agentUrl ?? currentConfig.agentUrl;
     if (!effectiveUrl) {
       p2pClient = null;
+      renderP2PClient = null;
       p2pAuthToken = null;
       return;
     }
     const token = await YaverFeedback.resolveP2PAuthToken();
+    // reset() can clear config while relay-password resolution is awaiting.
+    // Do not resurrect a client from that stale init generation.
+    if (config !== currentConfig) return;
     if (!token) {
       p2pClient = null;
+      renderP2PClient = null;
       p2pAuthToken = null;
       return;
     }
     p2pAuthToken = token;
     const rp = await resolveRelayPassword(token);
+    if (config !== currentConfig) return;
     p2pClient = new P2PClient(effectiveUrl, token, rp);
+    const renderUrl = currentConfig.renderAgentUrl || effectiveUrl;
+    renderP2PClient = renderUrl === effectiveUrl ? p2pClient : new P2PClient(renderUrl, token, rp);
   }
 
   /**
@@ -266,12 +289,88 @@ export class YaverFeedback {
    * If no `agentUrl` is provided, the SDK will attempt auto-discovery
    * via `YaverDiscovery` on the first `startReport()` call.
    */
+  /** The runtime lane, when running on web inside a Yaver preview WebView. */
+  static detectWebLane(): 'browser' | 'webrtc' | null {
+    try {
+      if (Platform.OS !== 'web' || typeof window === 'undefined') return null;
+      const l = String((window as unknown as { __yaverLane?: string }).__yaverLane || '').toLowerCase();
+      if (l === 'browser' || l === 'webrtc') return l;
+    } catch { /* noop */ }
+    return null;
+  }
+
+  /**
+   * Mount a draggable DOM floating "Y" icon for the BROWSER lane (RN-web). It
+   * lives in the WebView's document.body (position:fixed, max z-index), so it
+   * renders ON TOP of the page inside the WebView and is never occluded by the
+   * fullScreen preview modal — the one occlusion-proof affordance on iOS.
+   * Tap opens the SDK's existing report flow (the RN FeedbackModal renders in
+   * the same WebView DOM, also un-occluded). No-op off-web or off-lane, and
+   * idempotent (a re-init reuses the existing node).
+   */
+  static mountBrowserLaneIcon(): void {
+    if (YaverFeedback.detectWebLane() !== 'browser') return;
+    try {
+      const doc = (globalThis as unknown as { document?: Document }).document;
+      if (!doc || !doc.body) return;
+      if (doc.getElementById('yaver-feedback-btn')) return; // idempotent
+      const btn = doc.createElement('div');
+      btn.id = 'yaver-feedback-btn';
+      btn.textContent = 'Y';
+      btn.title = 'Yaver Feedback — drag to move · tap to report';
+      btn.style.cssText =
+        'position:fixed;bottom:20px;right:20px;width:44px;height:44px;border-radius:50%;' +
+        'background:#6366f1;color:#fff;display:flex;align-items:center;justify-content:center;' +
+        'cursor:pointer;z-index:99999;font-size:18px;font-weight:bold;touch-action:none;' +
+        'box-shadow:0 4px 12px rgba(99,102,241,0.4);transition:transform 0.2s;';
+      const drag = { on: false, moved: false, sx: 0, sy: 0, ox: 0, oy: 0 };
+      const w = window as unknown as { innerWidth: number; innerHeight: number };
+      const applyPos = (x: number, y: number) => {
+        const m = 8;
+        const nx = Math.max(m, Math.min(w.innerWidth - 44 - m, x));
+        const ny = Math.max(m, Math.min(w.innerHeight - 44 - m, y));
+        btn.style.left = nx + 'px'; btn.style.top = ny + 'px';
+        btn.style.right = 'auto'; btn.style.bottom = 'auto';
+        try { localStorage.setItem('yaver-feedback-btn-pos', JSON.stringify({ x: nx, y: ny })); } catch { /* noop */ }
+      };
+      try { const s = localStorage.getItem('yaver-feedback-btn-pos'); if (s) { const p = JSON.parse(s); if (typeof p?.x === 'number') applyPos(p.x, p.y); } } catch { /* noop */ }
+      btn.addEventListener('pointerdown', (e: PointerEvent) => {
+        drag.on = true; drag.moved = false;
+        const r = btn.getBoundingClientRect();
+        drag.sx = e.clientX; drag.sy = e.clientY; drag.ox = r.left; drag.oy = r.top;
+        btn.setPointerCapture(e.pointerId); btn.style.transition = 'none';
+      });
+      btn.addEventListener('pointermove', (e: PointerEvent) => {
+        if (!drag.on) return;
+        const dx = e.clientX - drag.sx, dy = e.clientY - drag.sy;
+        if (Math.abs(dx) + Math.abs(dy) > 5) drag.moved = true;
+        if (drag.moved) applyPos(drag.ox + dx, drag.oy + dy);
+      });
+      const end = (e: PointerEvent) => {
+        if (!drag.on) return;
+        drag.on = false; btn.style.transition = 'transform 0.2s';
+        try { btn.releasePointerCapture(e.pointerId); } catch { /* noop */ }
+        if (!drag.moved) { try { void YaverFeedback.startReport(); } catch { /* noop */ } }
+      };
+      btn.addEventListener('pointerup', end);
+      btn.addEventListener('pointercancel', end);
+      // Also answer the host's forwarded shake (Yaver injects yaver-feedback:launch).
+      const launch = () => { try { void YaverFeedback.startReport(); } catch { /* noop */ } };
+      window.addEventListener('yaver-feedback:launch', launch as EventListener);
+      (window as unknown as { __yaverFeedbackLaunch?: () => void }).__yaverFeedbackLaunch = launch;
+      doc.body.appendChild(btn);
+    } catch { /* noop — never break the guest app over a feedback affordance */ }
+  }
+
   static init(cfg: FeedbackConfig): void {
     config = {
       trigger: 'shake',
       maxRecordingDuration: 120,
       autoLogin: true,
       ...cfg,
+      agentUrl: cfg.codingAgentUrl || cfg.agentUrl,
+      codingDeviceId: cfg.codingDeviceId || cfg.preferredDeviceId,
+      renderDeviceId: cfg.renderDeviceId || cfg.codingDeviceId || cfg.preferredDeviceId,
     };
     if (IS_HOST_MODE) {
       // sfmg / talos / etc. running inside Yaver mobile (compile-time
@@ -293,6 +392,9 @@ export class YaverFeedback {
       }
       maxErrors = cfg.maxCapturedErrors ?? 5;
       errorBuffer = [];
+      if (cfg.crashReporting?.enabled && cfg.crashReporting?.installGlobalHandler) {
+        YaverFeedback.installCrashHandler();
+      }
       return;
     }
     if (config.disableShakeGesture && (!config.quickIcon || config.quickIcon === 'auto')) {
@@ -345,11 +447,16 @@ export class YaverFeedback {
       // is set, so set a placeholder header here that won't 401 a
       // direct-LAN url and will be overwritten before any relay hop.
       p2pClient = new P2PClient(config.agentUrl, config.authToken ?? '', p2pRelayPassword);
+      const renderUrl = config.renderAgentUrl || config.agentUrl;
+      renderP2PClient = renderUrl === config.agentUrl
+        ? p2pClient
+        : new P2PClient(renderUrl, config.authToken ?? '', p2pRelayPassword);
       if (config.authToken) {
         void YaverFeedback.rebuildP2PClient(config.agentUrl);
       }
     } else {
       p2pClient = null;
+      renderP2PClient = null;
       // Auto-discover agent in the background when convexUrl or LAN is available
       if (enabled && (config.authToken || config.preferredDeviceId)) {
         YaverFeedback.discoverAgent();
@@ -359,24 +466,25 @@ export class YaverFeedback {
     // Set up error capture buffer size
     maxErrors = cfg.maxCapturedErrors ?? 5;
     errorBuffer = [];
-
-    // Wire up shake detection when trigger is 'shake'
-    if (shakeDetector) {
-      shakeDetector.stop();
-      shakeDetector = null;
-    }
-    if (enabled && config.trigger === 'shake' && !config.disableShakeGesture) {
-      shakeDetector = new ShakeDetector();
-      shakeDetector.start(() => {
-        YaverFeedback.notifyShake();
-        if (config?.reportingOnly) {
-          YaverFeedback.sendAutoReport();
-        } else {
-          YaverFeedback.startReport();
-        }
-      });
+    if (cfg.crashReporting?.enabled && cfg.crashReporting?.installGlobalHandler) {
+      YaverFeedback.installCrashHandler();
     }
 
+    // Wire up shake detection when trigger is 'shake'. Rebuild from scratch:
+    // config was just replaced, so the old detector may be closing over stale
+    // settings.
+    YaverFeedback.stopShakeDetector();
+    YaverFeedback.syncShakeDetector();
+
+    // Browser lane (RN-web inside Yaver's fullScreen WebView preview): the
+    // native shake module doesn't exist on web, and Yaver's own container
+    // overlay is OCCLUDED behind the WebView modal on iOS. So mount an
+    // occlusion-proof DRAGGABLE DOM icon INSIDE the WebView — same pattern as
+    // yaver-feedback-web. Lane is stamped by Yaver via
+    // window.__yaverLane='browser' (mobile PREVIEW_LANE_SCRIPT). See
+    // docs/audits/feedback-sdk-lanes-audit-2026-07-28.md.
+    if (enabled) YaverFeedback.mountBrowserLaneIcon();
+
     // Wire up BlackBox command handlers for reload + status signals from
     // the agent. Opens an SSE channel the agent uses to:
     //   - broadcast reload_bundle so the phone picks up a fresh Hermes
@@ -385,7 +493,14 @@ export class YaverFeedback {
     //     assets…", "Done") so the SDK can surface it like a normal
     //     "Working…" spinner instead of a silent 60-second freeze.
     if (enabled) {
-      BlackBox.onCommand((cmd) => {
+      // onCommand appends to a static array and hands back an unsubscribe.
+      // Dropping that unsubscribe meant every re-init stacked another handler
+      // on top of the last, so an app that re-initialised (say, a settings
+      // toggle) reloaded twice per agent command, then three times, and so on.
+      // destroy() never cleared them either. Drop the previous registration
+      // first so init() is idempotent here.
+      commandUnsubscribe?.();
+      commandUnsubscribe = BlackBox.onCommand((cmd) => {
         if (cmd.command === 'reload') {
           if (cfg.onReload) {
             cfg.onReload();
@@ -447,16 +562,24 @@ export class YaverFeedback {
       // 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.
+      //   4. RETRY, rather than checking once. This was a single 500ms
+      //      timeout, and on a cold start it could not succeed: an app that
+      //      passes neither agentUrl nor authToken to init() (the normal
+      //      case — they're restored from storage) gets its session from
+      //      `void hydrateSession()`, which reads two AsyncStorage keys and
+      //      then awaits discoverAgent(), a Convex round trip plus LAN
+      //      probing. That does not finish in 500ms, so the check found no
+      //      agentUrl, gave up, and BlackBox never started — meaning no SSE
+      //      channel, so the agent's `reload_bundle` command had nowhere to
+      //      land and Hermes hot reload silently did nothing until the user
+      //      shook the device and drove discovery by hand.
+      //
+      //      The both-conditions guard is what keeps the 401 retry storm
+      //      from coming back, so it is preserved exactly; we only re-check
+      //      it over time instead of once. Bounded so a device that never
+      //      signs in doesn't poll forever.
       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);
+        YaverFeedback.scheduleBlackBoxAutoStart();
       }
     }
 
@@ -471,6 +594,40 @@ export class YaverFeedback {
     //     pass-through wrapper they insert into their own error chain
   }
 
+  /**
+   * Opt-in global crash handler. This wraps the existing React Native
+   * ErrorUtils handler and still calls it, so Sentry/Crashlytics/Bugsnag can
+   * remain the system of record. The SDK only uploads a crash report and,
+   * when configured, asks the agent to create a fix task.
+   */
+  static installCrashHandler(): void {
+    if (crashHandlerInstalled) return;
+    try {
+      const errorUtils = (globalThis as any)?.ErrorUtils;
+      if (!errorUtils?.getGlobalHandler || !errorUtils?.setGlobalHandler) {
+        return;
+      }
+      const next = errorUtils.getGlobalHandler();
+      errorUtils.setGlobalHandler((error: Error, isFatal?: boolean) => {
+        YaverFeedback.attachError(error, {
+          source: 'global-handler',
+          crashAware: true,
+        });
+        if (errorBuffer.length > 0) {
+          errorBuffer[errorBuffer.length - 1].isFatal = isFatal ?? true;
+        }
+        void YaverFeedback.reportCrash(error, {
+          isFatal: isFatal ?? true,
+          source: 'global-handler',
+        });
+        next?.(error, isFatal);
+      });
+      crashHandlerInstalled = true;
+    } catch (err) {
+      console.warn('[YaverFeedback] installCrashHandler failed:', err);
+    }
+  }
+
   /**
    * Run agent discovery in the background.
    * Called automatically from init() when no agentUrl is provided.
@@ -564,6 +721,12 @@ export class YaverFeedback {
     } else {
       await YaverFeedback.discoverAgent();
     }
+    // Signing in is the event the auto-start was waiting for. If its bounded
+    // retry already gave up (device left signed out past the window), this is
+    // what brings the command channel up without requiring an app restart.
+    if (config.autoStartBlackBox !== false && !BlackBox.isStreaming) {
+      YaverFeedback.scheduleBlackBoxAutoStart();
+    }
   }
 
   /** Returns true once the SDK has a session token it can use. */
@@ -571,6 +734,59 @@ export class YaverFeedback {
     return Boolean(config?.authToken);
   }
 
+  /**
+   * On-device App Store screenshot capture (Engine 2). Walks the routes
+   * the host hands us, screenshots each, and uploads to the agent which
+   * runs the App Store Connect backend. agentUrl / authToken / relay
+   * password default to the SDK's resolved session; the host only has to
+   * supply a navigation ref + the ordered route list.
+   *
+   *   YaverFeedback.captureStoreScreenshots({
+   *     app: 'sfmg',
+   *     navigationRef,
+   *     routes: ['/(tabs)/dashboard', '/(tabs)/messages', '/(tabs)/clients'],
+   *     submit: true,
+   *   })
+   */
+  static async captureStoreScreenshots(
+    opts: Omit<CaptureStoreScreenshotsOptions, 'agentUrl' | 'authToken' | 'relayPassword'> &
+      Partial<Pick<CaptureStoreScreenshotsOptions, 'agentUrl' | 'authToken' | 'relayPassword'>>,
+  ): Promise<CaptureStoreScreenshotsResult> {
+    const agentUrl = opts.agentUrl ?? config?.agentUrl ?? '';
+    const authToken = opts.authToken ?? config?.authToken ?? p2pAuthToken ?? '';
+    const relayPassword = opts.relayPassword ?? p2pRelayPassword;
+    if (!agentUrl || !authToken) {
+      return {
+        ok: false,
+        captured: 0,
+        uploaded: 0,
+        message: 'YaverFeedback not connected to an agent — init() with agentUrl + authToken first.',
+      };
+    }
+    return captureStoreScreenshots({ ...opts, agentUrl, authToken, relayPassword });
+  }
+
+  /**
+   * Let the mobile app / CLI kick THIS device into self-capturing. Registers
+   * a BlackBox command listener that fires captureStoreScreenshots when the
+   * agent pushes a `capture_store_shots` command (its `data` may override
+   * `submit` / `locale`). Returns an unsubscribe fn. Call once after init,
+   * passing the app's navigation ref + the routes to walk.
+   */
+  static enableStoreShotsOnCommand(
+    opts: Omit<CaptureStoreScreenshotsOptions, 'agentUrl' | 'authToken' | 'relayPassword'>,
+  ): () => void {
+    return BlackBox.onCommand((cmd) => {
+      if (cmd?.command !== 'capture_store_shots') return;
+      const data = (cmd as any).data ?? {};
+      void YaverFeedback.captureStoreScreenshots({
+        ...opts,
+        submit: typeof data.submit === 'boolean' ? data.submit : opts.submit,
+        locale: typeof data.locale === 'string' ? data.locale : opts.locale,
+      });
+    });
+  }
+
   /**
    * Request the embedded FeedbackModal to show the login screen. Works by
    * emitting an event the modal listens for — avoids forcing the host app
@@ -591,6 +807,27 @@ export class YaverFeedback {
     DeviceEventEmitter.emit('yaverFeedback:startMachinePicker');
   }
 
+  /** Begin the reusable host-app Dogfood wizard. Owner OAuth and machine
+   * selection intentionally happen before installation enrollment/runtime
+   * controls because starting builds or runners is owner-level authority. */
+  static beginDogfoodOnboarding(options: DogfoodOnboardingOptions): void {
+    dogfoodOnboarding = options;
+    if (!config) YaverFeedback.init({ autoLogin: true } as FeedbackConfig);
+    if (!YaverFeedback.isAuthed()) {
+      YaverFeedback.showLogin();
+      return;
+    }
+    YaverFeedback.showMachinePicker();
+  }
+
+  static getDogfoodOnboarding(): DogfoodOnboardingOptions | null {
+    return dogfoodOnboarding;
+  }
+
+  static clearDogfoodOnboarding(): void {
+    dogfoodOnboarding = null;
+  }
+
   /**
    * Update the selected remote device. Resets the cached agent URL so the
    * next `startReport()` (or FloatingButton press) rediscovers against the
@@ -598,9 +835,17 @@ export class YaverFeedback {
    */
   static async setPreferredDevice(deviceId: string): Promise<void> {
     if (!config) return;
+    const wasUnified = !config.renderDeviceId
+      || config.renderDeviceId === config.codingDeviceId
+      || config.renderDeviceId === config.preferredDeviceId;
     config.preferredDeviceId = deviceId;
+    config.codingDeviceId = deviceId;
+    if (wasUnified) config.renderDeviceId = deviceId;
     config.agentUrl = undefined;
+    config.codingAgentUrl = undefined;
+    if (wasUnified) config.renderAgentUrl = undefined;
     p2pClient = null;
+    renderP2PClient = null;
     p2pAuthToken = null;
     await YaverFeedback.discoverAgent();
   }
@@ -610,8 +855,7 @@ export class YaverFeedback {
     if (!config?.authToken || !config.preferredDeviceId) return null;
     const preferredDeviceId = config.preferredDeviceId;
     const devices = await listReachableDevices(config.authToken);
-    const all = [...devices.owned, ...devices.shared];
-    return all.find((device) => device.deviceId === preferredDeviceId) ?? null;
+    return devices.owned.find((device) => device.deviceId === preferredDeviceId) ?? null;
   }
 
   /**
@@ -671,6 +915,7 @@ export class YaverFeedback {
       config.agentUrl = undefined;
     }
     p2pClient = null;
+    renderP2PClient = null;
     p2pAuthToken = null;
   }
 
@@ -779,32 +1024,145 @@ export class YaverFeedback {
       }
       BlackBox.unwrapConsole(); // ensure console is restored even if BlackBox wasn't started
       errorBuffer = [];
-      if (shakeDetector) {
-        shakeDetector.stop();
-        shakeDetector = null;
-      }
+      YaverFeedback.stopShakeDetector();
     } else {
       // === ENABLE ===
       if (blackBoxWasStreaming) {
         BlackBox.start(); // restart with previous config
       }
-      // Restart shake detector if trigger is 'shake'
-      if (config?.trigger === 'shake' && !config?.disableShakeGesture && !shakeDetector) {
-        shakeDetector = new ShakeDetector();
-        shakeDetector.start(() => {
-          YaverFeedback.notifyShake();
-          if (config?.reportingOnly) {
-            YaverFeedback.sendAutoReport();
-          } else {
-            YaverFeedback.startReport();
-          }
-        });
-      }
+      enabled = true; // syncShakeDetector reads this
+      YaverFeedback.syncShakeDetector();
     }
 
     enabled = value;
   }
 
+  /**
+   * Turn shake-to-report on or off without tearing the SDK down.
+   *
+   * `trigger` is read only inside init(), so before this the only ways to
+   * stop listening for a shake were setEnabled(false) — which also kills the
+   * flight recorder and the agent command channel — or a re-init, which used
+   * to stack a duplicate command handler. Neither is what "turn the shake
+   * catcher off" should cost.
+   *
+   * Persists onto config.disableShakeGesture, so a later setEnabled(true)
+   * honours it rather than resurrecting the listener.
+   */
+  static setShakeEnabled(value: boolean): void {
+    if (!config) return;
+    config.disableShakeGesture = !value;
+    YaverFeedback.syncShakeDetector();
+  }
+
+  /** Whether the shake listener is currently armed. */
+  static isShakeEnabled(): boolean {
+    return shakeDetector !== null;
+  }
+
+  /**
+   * Bring the shake listener in line with the current config. Idempotent —
+   * safe to call whenever `enabled`, `trigger`, or `disableShakeGesture`
+   * moves.
+   */
+  private static syncShakeDetector(): void {
+    const want =
+      enabled && config?.trigger === 'shake' && !config?.disableShakeGesture;
+    if (want && !shakeDetector) {
+      shakeDetector = new ShakeDetector();
+      shakeDetector.start(() => {
+        YaverFeedback.notifyShake();
+        if (config?.reportingOnly) {
+          YaverFeedback.sendAutoReport();
+        } else {
+          YaverFeedback.startReport();
+        }
+      });
+    } else if (!want && shakeDetector) {
+      YaverFeedback.stopShakeDetector();
+    }
+  }
+
+  private static stopShakeDetector(): void {
+    if (shakeDetector) {
+      shakeDetector.stop();
+      shakeDetector = null;
+    }
+  }
+
+  /** Cancel a pending BlackBox auto-start retry chain. */
+  private static cancelBlackBoxAutoStart(): void {
+    if (autoStartTimer) {
+      clearTimeout(autoStartTimer);
+      autoStartTimer = null;
+    }
+  }
+
+  /**
+   * Start BlackBox as soon as we have BOTH an agentUrl and a token, polling
+   * until then.
+   *
+   * Both conditions are mandatory and deliberate: starting without a token
+   * makes the SSE channel 401 and retry with backoff, which is the tight
+   * string-concat + JSON-parse loop that used to SIGSEGV Hermes on iOS 18.3.1
+   * during Screenshot & Fix. This only re-checks that same guard over time.
+   *
+   * Bounded at ~60s: long enough for AsyncStorage hydration plus a Convex
+   * discovery round trip on a cold, off-LAN start, short enough that a device
+   * whose user never signs in stops polling. Giving up here costs nothing —
+   * setAuthToken() and startReport() both reschedule, so signing in later
+   * still brings the channel up.
+   */
+  private static scheduleBlackBoxAutoStart(attempt = 0): void {
+    const MAX_ATTEMPTS = 60;
+    const FIRST_DELAY_MS = 500;
+    const RETRY_DELAY_MS = 1000;
+    // Re-run discovery every Nth tick rather than every tick: it is a Convex
+    // round trip plus LAN probing, so once a second would hammer both. Every
+    // 3s is responsive enough that waking the dev machine reconnects the phone
+    // on its own, without the user wondering whether to restart the app.
+    const REDISCOVER_EVERY = 3;
+
+    YaverFeedback.cancelBlackBoxAutoStart();
+    if (!enabled || attempt >= MAX_ATTEMPTS) return;
+
+    const timer = setTimeout(() => {
+      autoStartTimer = null;
+      // A destroy() or setEnabled(false) between scheduling and firing.
+      if (!enabled || !config) return;
+      if (BlackBox.isStreaming) return;
+
+      if (config.agentUrl && (config.authToken || p2pAuthToken)) {
+        try {
+          // Pass the host's BlackBox config through. This used to call
+          // start() bare, so a host that configured the flight recorder
+          // — as the README itself shows — had it silently replaced by
+          // defaults, and appName came out ''.
+          BlackBox.start(config.blackBox);
+        } catch (err) {
+          console.warn('[YaverFeedback] BlackBox auto-start failed:', err);
+        }
+        return;
+      }
+
+      // No agent yet. Re-attempt discovery instead of only re-reading the
+      // flag: hydrateSession() runs discoverAgent() exactly once at init, so
+      // if the dev machine was unreachable at that moment — asleep, phone
+      // still on cellular before the relay came up, agent not yet serving —
+      // agentUrl stayed null for the whole process lifetime and only an app
+      // restart could recover it. discoverAgent() self-guards on "already
+      // have a URL" and "no token", so calling it again is cheap and safe.
+      if (!config.agentUrl && attempt > 0 && attempt % REDISCOVER_EVERY === 0) {
+        void YaverFeedback.discoverAgent();
+      }
+
+      YaverFeedback.scheduleBlackBoxAutoStart(attempt + 1);
+    }, attempt === 0 ? FIRST_DELAY_MS : RETRY_DELAY_MS);
+
+    autoStartTimer = timer;
+    unrefTimer(timer);
+  }
+
   /** Returns whether the SDK is currently enabled. */
   static isEnabled(): boolean {
     return enabled;
@@ -815,6 +1173,63 @@ export class YaverFeedback {
     return config;
   }
 
+  /** Current third-party SDK mode. Fails closed unless enabled + account match. */
+  static getDogfoodStatus(): SDKDogfoodStatus {
+    return resolveSDKDogfood(config?.dogfood);
+  }
+
+  /** One-call, account-free Dogfood bootstrap for third-party apps. On first
+   * launch it creates/proves the installation key and returns pending; after
+   * owner approval the same call obtains a short-lived scoped Yaver session
+   * and enables Dogfood UX without the host app implementing OAuth. */
+  static async enableDeviceDogfood(options: DeviceDogfoodOptions): Promise<{
+    status: DeviceDogfoodState;
+    installationId: string;
+    session: DeviceDogfoodSession | null;
+  }> {
+    const client = new YaverDeviceDogfood(options);
+    let status = await client.status();
+    if (status === 'unregistered' || status === 'pending' || status === 'cancelled' || status === 'revoked' || status === 'superseded') {
+      const enrolled = status === 'unregistered' || status === 'pending'
+        ? await client.enroll(Platform.OS)
+        : await client.reRegister(Platform.OS);
+      status = enrolled.status;
+    }
+    const info = await client.enrollmentInfo();
+    const session = status === 'active' ? await client.session() : null;
+    if (!config) YaverFeedback.init({ autoLogin: false } as FeedbackConfig);
+    if (config) {
+      config.dogfood = {
+        enabled: status === 'active' && !!session,
+        appId: options.appId,
+        installationId: info.installationId,
+        installationStatus: status === 'active' && session ? 'active' : status === 'unregistered' ? 'pending' : status,
+        label: options.label,
+      };
+      // A normal Yaver OAuth session remains authoritative for the runtime
+      // wizard. Only account-free hosts adopt the narrow installation token.
+      if (session && !config.authToken) await YaverFeedback.setAuthToken(session.token);
+    }
+    try {
+      const { DeviceEventEmitter } = require('react-native');
+      DeviceEventEmitter.emit('yaverFeedback:dogfoodChanged', { active: !!session, status });
+    } catch { /* noop */ }
+    return { status, installationId: info.installationId, session };
+  }
+
+  /** Confirmed by the Y badge/UI before this is called. Reverts this SDK to
+   * normal Feedback mode for the remainder of the app run. */
+  static async exitDogfoodMode(): Promise<void> {
+    const cfg = config?.dogfood;
+    if (!cfg) return;
+    cfg.enabled = false;
+    await cfg.onExit?.();
+    try {
+      const { DeviceEventEmitter } = require('react-native');
+      DeviceEventEmitter.emit('yaverFeedback:dogfoodChanged', { active: false, exited: true });
+    } catch { /* noop */ }
+  }
+
   /** Returns the resolved relay password the SDK is currently using.
    *  Empty string when no relay routing is in play (direct LAN agent
    *  URLs need no password). Callers attaching it to relay-routed
@@ -883,6 +1298,113 @@ export class YaverFeedback {
     };
   }
 
+  /**
+   * Upload a crash-aware feedback bundle. Apps can call this from their own
+   * error boundary/global handler. If crashReporting.autoFix is true, the SDK
+   * also triggers the agent's feedback-fix task; reload delivery still happens
+   * through the existing BlackBox command stream.
+   */
+  static async reportCrash(
+    error: Error,
+    opts?: {
+      isFatal?: boolean;
+      source?: 'manual' | 'global-handler';
+      metadata?: Record<string, unknown>;
+      autoFix?: boolean;
+    },
+  ): Promise<{ reportId?: string; taskId?: string }> {
+    if (!config || !enabled || !config.crashReporting?.enabled) return {};
+    if (crashReportInFlight) return {};
+    crashReportInFlight = true;
+    try {
+      YaverFeedback.attachError(error, {
+        ...(config.crashReporting.metadata || {}),
+        ...(opts?.metadata || {}),
+        crashAware: true,
+      });
+      if (errorBuffer.length > 0) {
+        errorBuffer[errorBuffer.length - 1].isFatal = opts?.isFatal ?? true;
+      }
+
+      if (!config.agentUrl) {
+        await YaverFeedback.discoverAgent();
+      }
+      if (!config.agentUrl) {
+        console.warn('[YaverFeedback] No agent URL — cannot send crash report.');
+        return {};
+      }
+
+      const { Platform, Dimensions } = require('react-native');
+      const { uploadFeedback } = require('./upload');
+      const { width, height } = Dimensions.get('window');
+      let screenshotPath: string | undefined;
+      if (config.crashReporting.captureScreenshot !== false) {
+        try {
+          const { captureScreenshot } = require('./capture');
+          screenshotPath = await captureScreenshot();
+        } catch {}
+      }
+
+      const autoFix = opts?.autoFix ?? config.crashReporting.autoFix === true;
+      const identity = resolveReportIdentity({
+        projectName: config?.projectName,
+        bundleId: config?.bundleId,
+        surface: config?.surface,
+        surfaces: config?.surfaces,
+        stack: config?.stack,
+        stacks: config?.stacks,
+        testSurfaces: config?.testSurfaces,
+        feedbackSdk: config?.feedbackSdk,
+        feedbackTransport: config?.feedbackTransport,
+        voiceCapabilities: config?.voiceCapabilities,
+        sttProvider: config?.sttProvider,
+        ttsProvider: config?.ttsProvider,
+      });
+      const bundle = {
+        metadata: {
+          timestamp: new Date().toISOString(),
+          reportKind: 'crash',
+          deviceInfo: {
+            platform: Platform.OS,
+            osVersion: String(Platform.Version),
+            model: Platform.OS === 'ios' ? 'iOS Device' : 'Android Device',
+            screenWidth: width,
+            screenHeight: height,
+            appName: identity.appName,
+          },
+          app: identity.app,
+          project: identity.project,
+          userNote: '[Crash report]',
+          crash: {
+            message: error.message,
+            isFatal: opts?.isFatal ?? true,
+            source: opts?.source ?? 'manual',
+            autoFixRequested: autoFix,
+          },
+        },
+        screenshots: screenshotPath ? [screenshotPath] : [],
+        errors: errorBuffer.length > 0 ? [...errorBuffer] : undefined,
+      };
+
+      const uploaded = await uploadFeedback(config.agentUrl, config.authToken ?? '', bundle, p2pRelayPassword);
+      const reportId =
+        (uploaded as { id?: string; reportId?: string } | null | undefined)?.id ??
+        (uploaded as { reportId?: string } | null | undefined)?.reportId;
+      let taskId: string | undefined;
+      if (autoFix && reportId) {
+        const client = p2pClient ?? new P2PClient(config.agentUrl, config.authToken ?? '', p2pRelayPassword);
+        const fix = await client.triggerFix(reportId);
+        taskId = fix?.taskId;
+      }
+      return { reportId, taskId };
+    } catch (err) {
+      console.warn('[YaverFeedback] Crash report failed:', err);
+      return {};
+    } finally {
+      crashReportInFlight = false;
+    }
+  }
+
   /**
    * Returns the P2P client instance.
    * Available after init if agentUrl is set, or after first successful discovery.
@@ -891,6 +1413,18 @@ export class YaverFeedback {
     return p2pClient;
   }
 
+  /** Renderer/reload route; intentionally distinct from the coding client. */
+  static getRenderP2PClient(): P2PClient | null {
+    return renderP2PClient ?? p2pClient;
+  }
+
+  static getMachineRouting(): { codingDeviceId?: string; renderDeviceId?: string } {
+    return {
+      codingDeviceId: config?.codingDeviceId || config?.preferredDeviceId,
+      renderDeviceId: config?.renderDeviceId || config?.codingDeviceId || config?.preferredDeviceId,
+    };
+  }
+
   // ─── One-stop SaaS replacement methods ─────────────────────────
   //
   // These are the three solo-dev SaaS-replacement entry points
@@ -1010,6 +1544,7 @@ export class YaverFeedback {
           config.agentUrl = result.url;
           const rp = await resolveRelayPassword(config.authToken ?? '');
           p2pClient = new P2PClient(result.url, config.authToken ?? '', rp);
+          renderP2PClient = p2pClient;
         }
       } catch {}
     }
@@ -1033,17 +1568,33 @@ export class YaverFeedback {
         // Screenshot capture may fail (e.g. no view ref) — continue without it
       }
 
+      const identity = resolveReportIdentity({
+        projectName: config?.projectName,
+        bundleId: config?.bundleId,
+        surface: config?.surface,
+        surfaces: config?.surfaces,
+        stack: config?.stack,
+        stacks: config?.stacks,
+        testSurfaces: config?.testSurfaces,
+        feedbackSdk: config?.feedbackSdk,
+        feedbackTransport: config?.feedbackTransport,
+        voiceCapabilities: config?.voiceCapabilities,
+        sttProvider: config?.sttProvider,
+        ttsProvider: config?.ttsProvider,
+      });
       const bundle = {
         metadata: {
           timestamp: new Date().toISOString(),
-          device: {
+          deviceInfo: {
             platform: Platform.OS,
             osVersion: String(Platform.Version),
             model: Platform.OS === 'ios' ? 'iOS Device' : 'Android Device',
             screenWidth: width,
             screenHeight: height,
+            appName: identity.appName,
           },
-          app: {},
+          app: identity.app,
+          project: identity.project,
           userNote: '[Auto-report via shake]',
         },
         screenshots: screenshotPath ? [screenshotPath] : [],
@@ -1211,10 +1762,22 @@ export class YaverFeedback {
       shakeDetector.stop();
       shakeDetector = null;
     }
+    // Drop the agent command handler and un-monkey-patch console. Without
+    // these, destroy() left the SDK half-alive: console stayed wrapped, and
+    // the reload handler kept firing on a "destroyed" SDK — then a later
+    // init() stacked a second one on top.
+    commandUnsubscribe?.();
+    commandUnsubscribe = null;
+    // Before `enabled = false` / `config = null` below, so an in-flight retry
+    // can't fire against a torn-down config.
+    YaverFeedback.cancelBlackBoxAutoStart();
+    BlackBox.stop();
+    BlackBox.unwrapConsole();
     firstShakeFired = false;
     enabled = false;
     config = null;
     p2pClient = null;
+    renderP2PClient = null;
     errorBuffer = [];
   }
 }