yaver-feedback-react-native 0.8.13 → 0.9.2

package/src/__tests__/types.test.ts

@@ -51,7 +51,7 @@ describe('React Native SDK types', () => {
       const bundle: FeedbackBundle = {
         metadata: {
           timestamp: '2026-03-24T12:00:00Z',
-          device: {
+          deviceInfo: {
             platform: 'ios',
             osVersion: '18.0',
             model: 'iPhone 16 Pro',
@@ -68,7 +68,7 @@ describe('React Native SDK types', () => {
       };
 
       expect(bundle.metadata.timestamp).toBe('2026-03-24T12:00:00Z');
-      expect(bundle.metadata.device.platform).toBe('ios');
+      expect(bundle.metadata.deviceInfo.platform).toBe('ios');
       expect(bundle.screenshots).toEqual([]);
       expect(bundle.video).toBeUndefined();
     });
@@ -77,7 +77,7 @@ describe('React Native SDK types', () => {
       const bundle: FeedbackBundle = {
         metadata: {
           timestamp: '2026-03-24T12:00:00Z',
-          device: {
+          deviceInfo: {
             platform: 'android',
             osVersion: '15',
             model: 'Pixel 9',
@@ -168,7 +168,7 @@ describe('React Native SDK types', () => {
         bundle: {
           metadata: {
             timestamp: 'now',
-            device: { platform: 'ios', osVersion: '18', model: 'iPhone', screenWidth: 393, screenHeight: 852 },
+            deviceInfo: { platform: 'ios', osVersion: '18', model: 'iPhone', screenWidth: 393, screenHeight: 852 },
             app: {},
           },
           screenshots: [],
@@ -187,7 +187,7 @@ describe('React Native SDK types', () => {
           bundle: {
             metadata: {
               timestamp: 'now',
-              device: { platform: 'ios', osVersion: '18', model: 'iPhone', screenWidth: 393, screenHeight: 852 },
+              deviceInfo: { platform: 'ios', osVersion: '18', model: 'iPhone', screenWidth: 393, screenHeight: 852 },
               app: {},
             },
             screenshots: [],

package/src/_core/device.ts

@@ -212,10 +212,11 @@ export function collapseDevices(devices: CoreDevice[]): CoreDevice[] {
 // ── Freshness + target pick ───────────────────────────────────────────
 
 /**
- * "Fresh" matches the mobile app: online + heartbeat < 90 s. Clients
- * read Convex's `isOnline` first (backend already applies its own 90 s
- * gate from the server clock), then use this helper when they need the
- * phone-side freshness opinion too — e.g. for auto-connect picks.
+ * "Fresh" matches the mobile app: online + heartbeat within
+ * HEARTBEAT_STALE_MS. Clients read Convex's `isOnline` first (the backend
+ * applies the same gate from the server clock), then use this helper when
+ * they need the phone-side freshness opinion too — e.g. for auto-connect
+ * picks.
  */
 export function isDeviceFresh(d: CoreDevice, now = Date.now()): boolean {
   if (!d.isOnline) return false;
@@ -224,11 +225,20 @@ export function isDeviceFresh(d: CoreDevice, now = Date.now()): boolean {
 }
 
 /**
- * Choose the best candidate for an auto-connect attempt. Preference:
- *   1. explicit `preferredDeviceId` that's still fresh
- *   2. fresh (online + recent heartbeat) + has a quicHost
- *   3. online + has a quicHost
- *   4. first with a quicHost
+ * Choose the best candidate for an auto-connect attempt.
+ *
+ * An explicit `preferredDeviceId` is honoured by id ALONE, or not at all:
+ *   - A missing `quicHost` is not grounds to reroute. Relay transport
+ *     addresses a device by id (`<relay>/d/<deviceId>`), so the entry is
+ *     still reachable off-LAN — which is precisely when quicHost is absent.
+ *   - If the id is not in the list, return null. Falling through to another
+ *     machine silently lands the user's fix on the wrong host: they pick the
+ *     Mac mini, the commit shows up on the laptop, and nothing reports an
+ *     error. Not connecting is the better failure — the caller surfaces
+ *     "selected machine missing, re-select it".
+ *
+ * With no preference, fall back: fresh + quicHost → online + quicHost →
+ * first with a quicHost.
  */
 export function pickTargetDevice(
   devices: CoreDevice[],
@@ -236,11 +246,7 @@ export function pickTargetDevice(
 ): CoreDevice | null {
   if (!devices.length) return null;
   if (preferredDeviceId) {
-    const preferred = devices.find(
-      (d) => d.deviceId === preferredDeviceId && d.quicHost,
-    );
-    if (preferred && isDeviceFresh(preferred)) return preferred;
-    if (preferred) return preferred;
+    return devices.find((d) => d.deviceId === preferredDeviceId) ?? null;
   }
   const fresh = devices.find((d) => isDeviceFresh(d) && d.quicHost);
   if (fresh) return fresh;

package/src/capture.ts

@@ -336,3 +336,54 @@ export async function stopAudioRecording(): Promise<{ path: string; duration: nu
 export function isAudioRecording(): boolean {
   return audioRecorderActive;
 }
+
+// ── Voice-stream recording (raw LPCM WAV) ──────────────────────────────
+// The voice vibe-coding path streams audio to the agent's STT WS, which
+// expects raw 16-bit / 16 kHz mono PCM (we strip the WAV header on the
+// way out). That's a different format from the HIGH_QUALITY m4a recorder
+// above — a compressed .m4a can't be streamed to Deepgram/whisper — so
+// this uses its own recording options, mirroring the Yaver app's
+// AgentVoiceButton.
+
+let pcmRecorderRef: any = null;
+let pcmRecorderActive = false;
+
+// Raw LPCM 16-bit LE, 16 kHz mono. iOS uses lpcm; Android records WAV.
+const PCM_RECORDING_OPTIONS: any = {
+  android: { extension: '.wav', outputFormat: 2, audioEncoder: 3, sampleRate: 16000, numberOfChannels: 1, bitRate: 256000 },
+  ios: {
+    extension: '.wav', outputFormat: 'lpcm', audioQuality: 0x40, sampleRate: 16000,
+    numberOfChannels: 1, bitRate: 256000, linearPCMBitDepth: 16, linearPCMIsBigEndian: false, linearPCMIsFloat: false,
+  },
+  web: { mimeType: 'audio/wav', bitsPerSecond: 256000 },
+};
+
+/** Begin a raw-PCM recording for the voice stream. */
+export async function startPcmRecording(): Promise<void> {
+  if (pcmRecorderActive) throw new Error('[YaverFeedback] A voice recording is already in progress.');
+  const ExpoAv = loadExpoAvOrThrow();
+  const { Audio } = ExpoAv;
+  const perm = await Audio.requestPermissionsAsync();
+  if (!perm.granted) {
+    throw new Error('[YaverFeedback] Microphone permission denied. Enable it in Settings ▸ Your App ▸ Microphone.');
+  }
+  await Audio.setAudioModeAsync({ allowsRecordingIOS: true, playsInSilentModeIOS: true, staysActiveInBackground: false });
+  const { recording } = await Audio.Recording.createAsync(PCM_RECORDING_OPTIONS);
+  pcmRecorderRef = recording;
+  pcmRecorderActive = true;
+}
+
+/** Stop the voice recording; returns the WAV file:// URI (or null). */
+export async function stopPcmRecording(): Promise<string | null> {
+  if (!pcmRecorderActive || !pcmRecorderRef) return null;
+  const recording = pcmRecorderRef;
+  pcmRecorderRef = null;
+  pcmRecorderActive = false;
+  try { await recording.stopAndUnloadAsync(); } catch { /* already stopped */ }
+  return typeof recording.getURI === 'function' ? recording.getURI() : null;
+}
+
+/** Whether a voice-stream recording is currently active. */
+export function isPcmRecording(): boolean {
+  return pcmRecorderActive;
+}

package/src/index.ts

@@ -29,12 +29,33 @@
  */
 
 export { YaverFeedback } from './YaverFeedback';
+export { captureStoreScreenshots } from './storeShots';
+export type {
+  CaptureStoreScreenshotsOptions,
+  CaptureStoreScreenshotsResult,
+  StoreShotFrame,
+} from './storeShots';
 export { BlackBox } from './BlackBox';
 export { YaverUpdates } from './YaverUpdates';
 export type { YaverUpdatesConfig, PendingUpdate } from './YaverUpdates';
 export { initExpo } from './expo';
 export { YaverDiscovery } from './Discovery';
 export { P2PClient } from './P2PClient';
+export {
+  reloadActions,
+  reloadRequest,
+  reloadFrameworkFamily,
+  describeReloadFailure,
+  RELOAD_PATH,
+  RELOAD_APP_PATH,
+} from './reloadActions';
+export type {
+  ReloadAction,
+  ReloadActionId,
+  ReloadActionsOptions,
+  ReloadWireMode,
+  DevServerSnapshot,
+} from './reloadActions';
 export { YaverConnectionScreen } from './ConnectionScreen';
 export { YaverLoginScreen } from './LoginScreen';
 export type { YaverLoginScreenProps } from './LoginScreen';

package/src/reloadActions.ts

@@ -0,0 +1,273 @@
+// ─── Reload actions — the ONE decision seam every Yaver feedback SDK mirrors ──
+//
+// The in-app overlay offers the developer a way to reload the app they are
+// looking at, without leaving it. This file answers the three questions that
+// have to be answered IDENTICALLY on every stack, so that a bug fixed in one
+// SDK is not still shipping in the other five:
+//
+//   1. WHICH actions may be shown at all (production build ⇒ none, ever)?
+//   2. WHICH request does each action make (path + body)?
+//   3. WHEN a reload fails, WHAT do we tell the user?
+//
+// It is deliberately PURE — no fetch, no DOM, no globals. That is what makes
+// it unit-testable, and the unit test is the guard: a production build must
+// yield an empty action list. Break `isDevBuild` and the test fails.
+//
+// ── Wire contract (desktop/agent/devserver_http.go) ──────────────────────────
+//
+//   POST /dev/reload      { "mode": "fast" | "full" }
+//        fast — the framework's cheapest refresh. Flutter stdin "r" (hot
+//               reload, keeps state). Metro/Expo fast refresh. Vite/Next HMR.
+//        full — framework-level restart. Flutter stdin "R" (hot RESTART,
+//               resets state). Web lane additionally forces a warm re-export.
+//               NEVER a cache clear or a process cold-start.
+//        Absent/unknown mode is normalised to "fast" by the agent, so an old
+//        client keeps its exact old behaviour.
+//
+//   POST /dev/reload-app  { "mode": "bundle", ...identity }
+//        Rebuild the Hermes bytecode bundle on the agent and push it over the
+//        BlackBox channel. React Native only, and the ONLY action that still
+//        works when no dev server is running — which is why it stays enabled
+//        in exactly that case.
+//
+// ── Auth ─────────────────────────────────────────────────────────────────────
+//
+// None of this needs a new secret. `/dev/reload` and `/dev/reload-app` are
+// registered under `authSDKOrGuest` (desktop/agent/httpserver.go), the same
+// middleware that already admits the bearer this SDK sends with its feedback
+// POST. A scope-limited SDK token needs the existing `guest-reload` scope,
+// whose path list already contains both routes — no widening, no new gate.
+
+/** Stable identifier for each action the overlay can render. */
+export type ReloadActionId = 'hot' | 'full' | 'rebuild';
+
+/** Wire value of the `mode` field (or `bundle` for /dev/reload-app). */
+export type ReloadWireMode = 'fast' | 'full' | 'bundle';
+
+/** The part of GET /dev/status this decision depends on. */
+export interface DevServerSnapshot {
+  /** Is a dev server process alive on the machine? */
+  running: boolean;
+  /** Is it still compiling? A reload now would race the build. */
+  building?: boolean;
+  /** Agent's framework name: expo | react-native | flutter | vite | nextjs. */
+  framework?: string;
+}
+
+export interface ReloadActionsOptions {
+  /**
+   * Is the HOST APP a development build?
+   *
+   * There is no honest default here, so there is no default: every stack has
+   * its own signal (`__DEV__`, `kDebugMode`, `Debug.isDebugBuild`,
+   * `FLAG_DEBUGGABLE`, `#if DEBUG`) and the caller passes it. False means the
+   * list is EMPTY — a shipped app never gets a reload button.
+   */
+  isDevBuild: boolean;
+  /** Do we have an agent connection / selected machine at all? */
+  connected: boolean;
+  /** Human label for the machine, used inside the disabled reason. */
+  machineLabel?: string;
+  /**
+   * Offer the React Native bundle rebuild as a third action. Only the RN SDK
+   * can act on the pushed bundle, so only the RN SDK sets this.
+   */
+  includeRebuild?: boolean;
+}
+
+export interface ReloadAction {
+  id: ReloadActionId;
+  /** Button label — stack-idiomatic wording lives here, not at the call site. */
+  label: string;
+  /** One line under/next to the button explaining what it actually does. */
+  hint: string;
+  mode: ReloadWireMode;
+  /** Agent path this action POSTs to. */
+  path: string;
+  enabled: boolean;
+  /**
+   * Present exactly when `enabled` is false. Names the specific blocker and
+   * the fix — never "unavailable".
+   */
+  disabledReason?: string;
+}
+
+type FrameworkFamily = 'flutter' | 'react-native' | 'web' | 'unknown';
+
+/**
+ * Map the agent's framework name onto the family whose reload vocabulary we
+ * borrow. Unknown frameworks still get generic actions: the agent is the
+ * authority on what it can do, and refusing to offer a reload because we did
+ * not recognise a name would be us inventing a limit the product does not have.
+ */
+export function reloadFrameworkFamily(framework?: string): FrameworkFamily {
+  const f = (framework || '').trim().toLowerCase();
+  if (!f) return 'unknown';
+  if (f.indexOf('flutter') >= 0) return 'flutter';
+  if (f === 'expo' || f.indexOf('react-native') >= 0 || f.indexOf('metro') >= 0) {
+    return 'react-native';
+  }
+  if (f === 'vite' || f === 'next' || f === 'nextjs' || f === 'web' || f === 'webpack') {
+    return 'web';
+  }
+  return 'unknown';
+}
+
+const LABELS: Record<FrameworkFamily, { hot: [string, string]; full: [string, string] }> = {
+  flutter: {
+    hot: ['Hot Reload', 'Flutter hot reload (r) — keeps the current app state.'],
+    full: ['Hot Restart', 'Flutter hot restart (R) — restarts the app and resets state.'],
+  },
+  'react-native': {
+    hot: ['Hot Reload', 'Fast Refresh through Metro — keeps component state.'],
+    full: ['Full Reload', 'Reloads the whole JS bundle and resets state.'],
+  },
+  web: {
+    hot: ['Hot Reload', 'Hot module replacement through the dev server.'],
+    full: ['Full Reload', 'Re-exports the bundle and reloads the page.'],
+  },
+  unknown: {
+    hot: ['Hot Reload', "The dev server's cheapest refresh."],
+    full: ['Full Reload', 'Framework-level restart of the running app.'],
+  },
+};
+
+/** Path constants — mirrored from AGENT_ENDPOINTS so a typo cannot diverge. */
+export const RELOAD_PATH = '/dev/reload';
+export const RELOAD_APP_PATH = '/dev/reload-app';
+
+/**
+ * The whole decision, in one pure function.
+ *
+ * Returns the ordered list the overlay should render. An EMPTY list means
+ * "render no reload UI at all" — that is the production-build answer, and it
+ * is deliberately indistinguishable from "this SDK has no reload feature",
+ * because to a shipped app it doesn't.
+ *
+ * A NON-empty list may still contain disabled entries: showing a greyed
+ * "Hot Reload — no dev server is running on primary" teaches the user what
+ * to fix. Hiding it teaches them nothing.
+ */
+export function reloadActions(
+  snapshot: DevServerSnapshot | null | undefined,
+  opts: ReloadActionsOptions,
+): ReloadAction[] {
+  // 1. Production build — never, under any circumstance.
+  if (!opts.isDevBuild) return [];
+
+  const snap: DevServerSnapshot = snapshot || { running: false };
+  const family = reloadFrameworkFamily(snap.framework);
+  const labels = LABELS[family];
+  const machine = (opts.machineLabel || '').trim() || 'the selected machine';
+
+  let blocked: string | undefined;
+  if (!opts.connected) {
+    blocked = 'Not connected to a machine yet — pick one first.';
+  } else if (snap.building) {
+    blocked = 'The dev server is still building — reload works once it finishes.';
+  } else if (!snap.running) {
+    blocked =
+      `No dev server is running on ${machine}. ` +
+      'Start one from the Yaver app, or run `yaver dev start` there.';
+  }
+
+  const actions: ReloadAction[] = [
+    {
+      id: 'hot',
+      label: labels.hot[0],
+      hint: labels.hot[1],
+      mode: 'fast',
+      path: RELOAD_PATH,
+      enabled: !blocked,
+      disabledReason: blocked,
+    },
+    {
+      id: 'full',
+      label: labels.full[0],
+      hint: labels.full[1],
+      mode: 'full',
+      path: RELOAD_PATH,
+      enabled: !blocked,
+      disabledReason: blocked,
+    },
+  ];
+
+  if (opts.includeRebuild) {
+    // Deliberately NOT gated on `running`: rebuilding the bundle is exactly
+    // what you do when Metro is not up. It is gated on `connected`, because
+    // without a machine there is nothing to rebuild on.
+    const rebuildBlocked = opts.connected
+      ? undefined
+      : 'Not connected to a machine yet — pick one first.';
+    actions.push({
+      id: 'rebuild',
+      label: 'Rebuild Bundle',
+      hint: 'Recompiles the Hermes bundle on the machine. Works with no dev server.',
+      mode: 'bundle',
+      path: RELOAD_APP_PATH,
+      enabled: !rebuildBlocked,
+      disabledReason: rebuildBlocked,
+    });
+  }
+
+  return actions;
+}
+
+/** The exact request an action makes. Kept next to the labels on purpose. */
+export function reloadRequest(action: Pick<ReloadAction, 'mode' | 'path'>): {
+  method: 'POST';
+  path: string;
+  body: Record<string, unknown>;
+} {
+  return { method: 'POST', path: action.path, body: { mode: action.mode } };
+}
+
+/**
+ * Turn a failed reload into a sentence that names the cause AND the fix.
+ *
+ * "Reload failed" is the shape of error this codebase keeps paying whole
+ * sessions for. Every branch below exists because the raw text the agent (or
+ * Go's net stack) produces is accurate and unreadable.
+ */
+export function describeReloadFailure(
+  status: number,
+  body: string,
+  snapshot?: DevServerSnapshot | null,
+): string {
+  const lower = (body || '').toLowerCase();
+  const framework = (snapshot?.framework || '').trim();
+
+  if (lower.indexOf('does not support hot reload') >= 0) {
+    const name = framework || 'This dev server';
+    return `${name} cannot hot reload. Use Rebuild Bundle, or restart the dev server.`;
+  }
+  if (
+    status === 503 ||
+    lower.indexOf('no dev server') >= 0 ||
+    lower.indexOf('dev server not available') >= 0
+  ) {
+    return 'No dev server is running on the machine. Start one before reloading.';
+  }
+  if (
+    (lower.indexOf('connection refused') >= 0 || lower.indexOf('econnrefused') >= 0) &&
+    (lower.indexOf('127.0.0.1') >= 0 || lower.indexOf('localhost') >= 0)
+  ) {
+    return 'The dev server is not listening on the machine. Start it with `yaver dev start`.';
+  }
+  if (status === 401 || status === 403) {
+    return 'The machine rejected this session — sign in again, or re-pair this device.';
+  }
+  if (status === 404) {
+    return (
+      'This machine’s agent has no /dev/reload route — it is too old. ' +
+      'Update it with `npm install -g yaver-cli@latest`.'
+    );
+  }
+  if (status >= 500) {
+    return 'The agent hit an internal error while reloading. Check `yaver logs` on the machine.';
+  }
+  if (status === 0) {
+    return 'Could not reach the machine. Check that it is online and `yaver serve` is running.';
+  }
+  return `Reload failed (HTTP ${status}).`;
+}

package/src/storeShots.ts

@@ -0,0 +1,189 @@
+/**
+ * On-device App Store screenshot capture (Engine 2).
+ *
+ * The desktop `yaver shots` flow drives a simulator with Maestro. This is
+ * the in-app counterpart: the SDK, living inside the real running app,
+ * walks the app's own routes and screenshots each one with
+ * `react-native-view-shot`, then uploads the frames to the Yaver agent
+ * (POST /shots/upload). The agent normalizes them and runs the same App
+ * Store Connect backend (upload → metadata → submit).
+ *
+ * Why this exists alongside the simulator path: it captures *real device*
+ * pixels, knows the exact route map (no heuristics), and the user is
+ * already authenticated — so it sidesteps the i18n / no-testID fragility
+ * that makes a blind simulator walk hard.
+ *
+ * The host wires it once by handing us a navigation ref (react-navigation
+ * or expo-router router) plus the ordered list of routes to visit.
+ */
+
+import { captureScreenshotBase64 } from './capture';
+
+export interface StoreShotFrame {
+  route: string;
+  base64: string;
+  mimeType: string;
+}
+
+export interface CaptureStoreScreenshotsOptions {
+  /** Yaver agent base URL (e.g. http://192.168.1.5:18080 or a relay URL). */
+  agentUrl: string;
+  /** Bearer token for the agent (same-user envelope). */
+  authToken: string;
+  /** Relay password — required only when agentUrl is relay-routed. */
+  relayPassword?: string;
+
+  /** App name (vault scope / job label on the agent side). */
+  app: string;
+  /** iOS bundle id; the agent falls back to app.json if omitted. */
+  bundleId?: string;
+  /** App Store localization (default en-US). */
+  locale?: string;
+  /** When true, the agent also sets metadata + attempts submit-for-review. */
+  submit?: boolean;
+
+  /**
+   * Navigation handle. Either a react-navigation ref (has `.navigate`) or
+   * an expo-router `router` (has `.push`/`.navigate`). We call the first
+   * available method with the route string.
+   */
+  navigationRef?: any;
+  /** Ordered routes to visit + screenshot (e.g. ['/(tabs)/dashboard', ...]). */
+  routes: string[];
+
+  /** Optional per-route screenshot names (defaults to NN_<sanitized route>). */
+  screens?: string[];
+  /** Milliseconds to wait after navigating before capturing (default 900). */
+  settleMs?: number;
+  /** Hook the host can use to hide its own overlay before each capture. */
+  onBeforeCapture?: (route: string, index: number) => void | Promise<void>;
+}
+
+export interface CaptureStoreScreenshotsResult {
+  ok: boolean;
+  captured: number;
+  uploaded: number;
+  submitted?: boolean;
+  staged?: boolean;
+  message?: string;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+function navigateTo(navRef: any, route: string): void {
+  if (!navRef) return;
+  // react-navigation ref
+  if (typeof navRef.navigate === 'function') {
+    navRef.navigate(route as never);
+    return;
+  }
+  // expo-router router
+  if (typeof navRef.push === 'function') {
+    navRef.push(route);
+    return;
+  }
+  if (navRef.current && typeof navRef.current.navigate === 'function') {
+    navRef.current.navigate(route as never);
+    return;
+  }
+}
+
+function shotName(route: string, index: number, override?: string): string {
+  if (override) return override;
+  const clean = route
+    .replace(/^\/+/, '')
+    .replace(/[()[\]/]+/g, '_')
+    .replace(/[^a-zA-Z0-9_]+/g, '')
+    .replace(/^_+|_+$/g, '');
+  const n = String(index + 1).padStart(2, '0');
+  return `${n}_${clean || 'screen'}`;
+}
+
+/**
+ * Walk the app's routes, screenshot each, and upload the batch to the
+ * agent. Returns a summary; never throws for a single missed route —
+ * it captures what it can and reports the count.
+ */
+export async function captureStoreScreenshots(
+  opts: CaptureStoreScreenshotsOptions,
+): Promise<CaptureStoreScreenshotsResult> {
+  if (!opts.agentUrl || !opts.authToken) {
+    return { ok: false, captured: 0, uploaded: 0, message: 'agentUrl + authToken required' };
+  }
+  if (!opts.routes?.length) {
+    return { ok: false, captured: 0, uploaded: 0, message: 'no routes to capture' };
+  }
+
+  const settleMs = opts.settleMs ?? 900;
+  const frames: StoreShotFrame[] = [];
+
+  for (let i = 0; i < opts.routes.length; i++) {
+    const route = opts.routes[i];
+    try {
+      navigateTo(opts.navigationRef, route);
+      await sleep(settleMs);
+      if (opts.onBeforeCapture) await opts.onBeforeCapture(route, i);
+      const shot = await captureScreenshotBase64();
+      if (shot?.base64) {
+        frames.push({
+          route: shotName(route, i, opts.screens?.[i]),
+          base64: shot.base64,
+          mimeType: shot.mimeType,
+        });
+      }
+    } catch {
+      // Skip a route that failed to render — keep walking.
+    }
+  }
+
+  if (frames.length === 0) {
+    return { ok: false, captured: 0, uploaded: 0, message: 'captured no frames' };
+  }
+
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${opts.authToken}`,
+    'Content-Type': 'application/json',
+  };
+  if (opts.relayPassword) headers['X-Relay-Password'] = opts.relayPassword;
+
+  const base = opts.agentUrl.replace(/\/$/, '');
+  try {
+    const resp = await fetch(`${base}/shots/upload`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({
+        app: opts.app,
+        bundleId: opts.bundleId ?? '',
+        locale: opts.locale ?? 'en-US',
+        submit: !!opts.submit,
+        frames,
+      }),
+    });
+    const j = await resp.json().catch(() => ({}));
+    if (!resp.ok || j?.ok === false) {
+      return {
+        ok: false,
+        captured: frames.length,
+        uploaded: 0,
+        message: j?.error || `agent /shots/upload HTTP ${resp.status}`,
+      };
+    }
+    return {
+      ok: true,
+      captured: frames.length,
+      uploaded: typeof j?.uploaded === 'number' ? j.uploaded : frames.length,
+      submitted: j?.submitted,
+      staged: j?.staged,
+      message: j?.message,
+    };
+  } catch (e: any) {
+    return {
+      ok: false,
+      captured: frames.length,
+      uploaded: 0,
+      message: `upload failed: ${e?.message ?? 'network error'}`,
+    };
+  }
+}