yaver-feedback-react-native 0.8.13 → 0.9.2

package/src/__tests__/ReportIdentity.test.ts

@@ -0,0 +1,203 @@
+import { resolveReportIdentity } from '../P2PClient';
+
+// resolveAppIdentity() has always fed /vibing/execute and /dev/reload-app so
+// the agent could route "vibe on THIS app" to the right repo, but nothing fed
+// /feedback — reports carried no identity at all, so the agent's fix router
+// had nothing to resolve and fell back to whatever directory it was sitting
+// in. resolveReportIdentity() closes that gap for the feedback path.
+
+jest.mock('react-native', () => ({
+  Platform: { OS: 'ios' },
+  NativeModules: {},
+}));
+
+/** Mirrors mobile/app.json in the Talos repo — the SDK's first external consumer. */
+const EXPO_CONFIG = {
+  name: 'Talos',
+  slug: 'talos-mobile',
+  version: '1.9.157',
+  ios: { bundleIdentifier: 'works.talos.mobile', buildNumber: '427' },
+  android: { package: 'works.talos.mobile', versionCode: 423 },
+};
+
+function mockExpoConstants(expoConfig: unknown, extra: Record<string, unknown> = {}) {
+  jest.doMock('expo-constants', () => ({ default: { expoConfig, ...extra } }), { virtual: true });
+}
+
+beforeEach(() => {
+  jest.resetModules();
+});
+
+describe('resolveReportIdentity', () => {
+  it('resolves app name and bundle id from the Expo config', () => {
+    mockExpoConstants(EXPO_CONFIG);
+    const { resolveReportIdentity: resolve } = require('../P2PClient');
+
+    const identity = resolve();
+
+    // The agent's fix router reads DeviceInfo.AppName first.
+    expect(identity.appName).toBe('Talos');
+    // ...and resolves the project by bundle id, the only unambiguous key.
+    expect(identity.project?.bundleId).toBe('works.talos.mobile');
+    expect(identity.project?.projectName).toBe('Talos');
+    expect(identity.project?.appName).toBe('Talos');
+    expect(identity.project?.surface).toBe('mobile');
+    expect(identity.app.bundleId).toBe('works.talos.mobile');
+  });
+
+  it('never reports a project path', () => {
+    mockExpoConstants(EXPO_CONFIG);
+    const { resolveReportIdentity: resolve } = require('../P2PClient');
+
+    // The agent ignores client-supplied paths on feedback reports (an
+    // untrusted guest could otherwise aim the fix task's CWD at ~/.ssh).
+    // Sending one would be misleading at best.
+    expect(resolve().project?.projectPath).toBeUndefined();
+  });
+
+  it('prefers the native runtime version over the manifest version', () => {
+    mockExpoConstants(EXPO_CONFIG, { nativeAppVersion: '1.9.158', nativeBuildVersion: '428' });
+    const { resolveReportIdentity: resolve } = require('../P2PClient');
+
+    const identity = resolve();
+    // A stale manifest shouldn't misreport which build is actually running.
+    expect(identity.app.version).toBe('1.9.158');
+    expect(identity.app.buildNumber).toBe('428');
+  });
+
+  it('falls back to the manifest version when no native version is exposed', () => {
+    mockExpoConstants(EXPO_CONFIG);
+    const { resolveReportIdentity: resolve } = require('../P2PClient');
+
+    const identity = resolve();
+    expect(identity.app.version).toBe('1.9.157');
+    expect(identity.app.buildNumber).toBe('427');
+  });
+
+  // Inside Yaver's container the ambient runtime IS Yaver. These are the
+  // cases where getting it wrong routes a fix task into yaver.io and edits
+  // the SDK instead of the app under test.
+  describe('inside the Yaver container (Hermes guest)', () => {
+    const YAVER_CONFIG = {
+      name: 'Yaver',
+      version: '1.99.306',
+      ios: { bundleIdentifier: 'io.yaver.mobile' },
+      android: { package: 'io.yaver.mobile' },
+    };
+
+    function mockContainer(yaverInfo: Record<string, unknown>) {
+      jest.doMock('react-native', () => ({
+        Platform: { OS: 'ios' },
+        NativeModules: { YaverInfo: { isYaver: true, ...yaverInfo } },
+      }));
+      // The host's manifest — what expo-constants answers for a guest bundle.
+      mockExpoConstants(YAVER_CONFIG);
+    }
+
+    it("never reports the host's bundle id as the guest's", () => {
+      mockContainer({ inheritedGuestProjectName: 'talos / mobile' });
+      const { resolveReportIdentity: resolve } = require('../P2PClient');
+
+      const identity = resolve();
+
+      // The agent routes on bundle id FIRST. Leaking io.yaver.mobile here
+      // would resolve to yaver.io and the project name would never be read.
+      expect(identity.project?.bundleId).toBeUndefined();
+      expect(identity.app.bundleId).toBeUndefined();
+      // Nor should the host's version masquerade as the guest's build.
+      expect(identity.app.version).toBeUndefined();
+    });
+
+    it('reports the guest project Yaver pinned', () => {
+      mockContainer({ inheritedGuestProjectName: 'talos / mobile' });
+      const { resolveReportIdentity: resolve } = require('../P2PClient');
+
+      const identity = resolve();
+      expect(identity.appName).toBe('talos / mobile');
+      expect(identity.project?.projectName).toBe('talos / mobile');
+    });
+
+    it("lets the app's own declaration win over the pinned project", () => {
+      mockContainer({ inheritedGuestProjectName: 'something-else' });
+      const { resolveReportIdentity: resolve } = require('../P2PClient');
+
+      // A bundle knows its own identity; nothing ambient should override it.
+      const identity = resolve({ projectName: 'Talos', bundleId: 'works.talos.mobile' });
+      expect(identity.appName).toBe('Talos');
+      expect(identity.project?.bundleId).toBe('works.talos.mobile');
+    });
+
+    it('reports nothing rather than something wrong when no project is pinned', () => {
+      mockContainer({});
+      const { resolveReportIdentity: resolve } = require('../P2PClient');
+
+      // Better for the agent to reject/fall back than to confidently edit
+      // the wrong repo.
+      const identity = resolve();
+      expect(identity.project).toBeUndefined();
+      expect(identity.appName).toBeUndefined();
+      expect(identity.app).toEqual({});
+    });
+  });
+
+  it('lets an explicit declaration override the ambient identity', () => {
+    mockExpoConstants(EXPO_CONFIG);
+    const { resolveReportIdentity: resolve } = require('../P2PClient');
+
+    const identity = resolve({ projectName: 'Override', bundleId: 'com.override.app' });
+    expect(identity.appName).toBe('Override');
+    expect(identity.project?.bundleId).toBe('com.override.app');
+  });
+
+  it('passes declared surfaces stacks and voice metadata through', () => {
+    mockExpoConstants(EXPO_CONFIG);
+    const { resolveReportIdentity: resolve } = require('../P2PClient');
+
+    const identity = resolve({
+      projectName: 'Omni',
+      bundleId: 'io.example.omni',
+      surface: 'vision',
+      surfaces: ['mobile', 'web', 'watch', 'tv', 'car', 'vision'],
+      stack: 'react-native-expo',
+      stacks: ['react-native-expo', 'nextjs', 'yaver-xml'],
+      testSurfaces: ['rn-hermes', 'browser', 'visionos-simulator'],
+      feedbackSdk: 'yaver-feedback-react-native',
+      feedbackTransport: 'device-sdk',
+      voiceCapabilities: ['stt', 'tts', 'device-mic'],
+      sttProvider: 'deepgram',
+      ttsProvider: 'local',
+    });
+
+    expect(identity.project).toMatchObject({
+      surface: 'vision',
+      surfaces: ['mobile', 'web', 'watch', 'tv', 'car', 'vision'],
+      stack: 'react-native-expo',
+      stacks: ['react-native-expo', 'nextjs', 'yaver-xml'],
+      testSurfaces: ['rn-hermes', 'browser', 'visionos-simulator'],
+      feedbackSdk: 'yaver-feedback-react-native',
+      feedbackTransport: 'device-sdk',
+      voiceCapabilities: ['stt', 'tts', 'device-mic'],
+      sttProvider: 'deepgram',
+      ttsProvider: 'local',
+    });
+    expect(identity.project?.projectPath).toBeUndefined();
+  });
+
+  it('omits the project block when nothing identifies the app', () => {
+    // Bare RN with no expo-constants and no native modules. The report must
+    // still upload — the agent just resolves it by its own means.
+    jest.doMock(
+      'expo-constants',
+      () => {
+        throw new Error('not installed');
+      },
+      { virtual: true },
+    );
+    const { resolveReportIdentity: resolve } = require('../P2PClient');
+
+    const identity = resolve();
+    expect(identity.project).toBeUndefined();
+    expect(identity.appName).toBeUndefined();
+    expect(identity.app).toEqual({});
+  });
+});

package/src/__tests__/SDKToken.test.ts

@@ -34,7 +34,7 @@ describe('SDK Token Auth', () => {
       const bundle = {
         metadata: {
           timestamp: '2026-03-25T00:00:00Z',
-          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/__tests__/ShakeToggle.test.ts

@@ -0,0 +1,153 @@
+// Runtime shake toggling + init() idempotency.
+//
+// Host apps put the feedback SDK behind a settings switch, which means init /
+// enable / disable run repeatedly in one process. Two things used to break
+// there:
+//
+//   1. There was no way to turn the shake catcher off short of
+//      setEnabled(false) (which also stops the flight recorder and the agent
+//      command channel) or a full re-init. `trigger` is only read inside
+//      init(). setShakeEnabled() fills that gap.
+//
+//   2. init() registered a BlackBox command handler and threw away the
+//      unsubscribe, so each re-init stacked another. Two inits meant two
+//      reloads per agent command; destroy() never cleared them either.
+
+import { YaverFeedback } from '../YaverFeedback';
+import { BlackBox } from '../BlackBox';
+
+const mockShakeStart = jest.fn();
+const mockShakeStop = jest.fn();
+
+jest.mock('../ShakeDetector', () => ({
+  ShakeDetector: jest.fn().mockImplementation(() => ({
+    start: mockShakeStart,
+    stop: mockShakeStop,
+  })),
+}));
+
+jest.mock('react-native', () => ({
+  Platform: { OS: 'ios' },
+  DeviceEventEmitter: { emit: jest.fn(), addListener: jest.fn() },
+  NativeModules: {},
+}));
+
+const mockFetch = jest.fn(() =>
+  Promise.resolve({ ok: true, json: () => Promise.resolve({}) }),
+);
+global.fetch = mockFetch as any;
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  YaverFeedback.destroy();
+});
+
+afterEach(() => {
+  YaverFeedback.destroy();
+});
+
+describe('setShakeEnabled', () => {
+  it('arms the shake listener on init when trigger is shake', () => {
+    YaverFeedback.init({ trigger: 'shake', agentUrl: 'http://x:18080', authToken: 't' });
+    expect(YaverFeedback.isShakeEnabled()).toBe(true);
+  });
+
+  it('disarms the listener without disabling the SDK', () => {
+    YaverFeedback.init({ trigger: 'shake', agentUrl: 'http://x:18080', authToken: 't' });
+
+    YaverFeedback.setShakeEnabled(false);
+
+    expect(YaverFeedback.isShakeEnabled()).toBe(false);
+    expect(mockShakeStop).toHaveBeenCalled();
+    // The point of a separate toggle: the rest of the SDK stays up.
+    expect(YaverFeedback.isEnabled()).toBe(true);
+  });
+
+  it('re-arms the listener', () => {
+    YaverFeedback.init({ trigger: 'shake', agentUrl: 'http://x:18080', authToken: 't' });
+    YaverFeedback.setShakeEnabled(false);
+    YaverFeedback.setShakeEnabled(true);
+    expect(YaverFeedback.isShakeEnabled()).toBe(true);
+  });
+
+  it('is idempotent — repeated calls do not stack detectors', () => {
+    YaverFeedback.init({ trigger: 'shake', agentUrl: 'http://x:18080', authToken: 't' });
+    mockShakeStart.mockClear();
+
+    YaverFeedback.setShakeEnabled(true);
+    YaverFeedback.setShakeEnabled(true);
+
+    expect(mockShakeStart).not.toHaveBeenCalled();
+    expect(YaverFeedback.isShakeEnabled()).toBe(true);
+  });
+
+  it('persists onto config so a later enable does not resurrect the listener', () => {
+    YaverFeedback.init({ trigger: 'shake', agentUrl: 'http://x:18080', authToken: 't' });
+    YaverFeedback.setShakeEnabled(false);
+
+    YaverFeedback.setEnabled(false);
+    YaverFeedback.setEnabled(true);
+
+    // The user said no shake. Cycling the master switch must not undo that.
+    expect(YaverFeedback.isShakeEnabled()).toBe(false);
+    expect(YaverFeedback.getConfig()?.disableShakeGesture).toBe(true);
+  });
+
+  it('does not arm the listener for a non-shake trigger', () => {
+    YaverFeedback.init({ trigger: 'manual', agentUrl: 'http://x:18080', authToken: 't' });
+    expect(YaverFeedback.isShakeEnabled()).toBe(false);
+
+    YaverFeedback.setShakeEnabled(true);
+    expect(YaverFeedback.isShakeEnabled()).toBe(false);
+  });
+
+  it('no-ops before init rather than throwing', () => {
+    expect(() => YaverFeedback.setShakeEnabled(true)).not.toThrow();
+    expect(YaverFeedback.isShakeEnabled()).toBe(false);
+  });
+});
+
+describe('init() command-handler registration', () => {
+  it('does not stack command handlers across re-inits', () => {
+    const cfg = { trigger: 'shake' as const, agentUrl: 'http://x:18080', authToken: 't' };
+
+    YaverFeedback.init(cfg);
+    YaverFeedback.init(cfg);
+    YaverFeedback.init(cfg);
+
+    // Three inits, one live handler. Before the fix this array grew by one
+    // each time, so a single agent 'reload' fired three reloads.
+    expect((BlackBox as any).commandHandlers.length).toBe(1);
+  });
+
+  it('fires a reload exactly once per command after repeated inits', () => {
+    // The user-visible symptom the count above stands in for.
+    const onReload = jest.fn();
+    const cfg = { trigger: 'shake' as const, agentUrl: 'http://x:18080', authToken: 't', onReload };
+
+    YaverFeedback.init(cfg);
+    YaverFeedback.init(cfg);
+
+    for (const h of (BlackBox as any).commandHandlers) h({ command: 'reload' });
+
+    expect(onReload).toHaveBeenCalledTimes(1);
+  });
+
+  it('destroy() unregisters the command handler', () => {
+    YaverFeedback.init({ trigger: 'shake', agentUrl: 'http://x:18080', authToken: 't' });
+    const before = (BlackBox as any).commandHandlers.length;
+    expect(before).toBeGreaterThan(0);
+
+    YaverFeedback.destroy();
+
+    expect((BlackBox as any).commandHandlers.length).toBe(before - 1);
+  });
+
+  it('destroy() then init() leaves exactly one handler', () => {
+    YaverFeedback.init({ trigger: 'shake', agentUrl: 'http://x:18080', authToken: 't' });
+    YaverFeedback.destroy();
+    YaverFeedback.init({ trigger: 'shake', agentUrl: 'http://x:18080', authToken: 't' });
+
+    expect((BlackBox as any).commandHandlers.length).toBe(1);
+  });
+});

package/src/__tests__/pickTargetDevice.test.ts

@@ -0,0 +1,101 @@
+// Target-device selection contract.
+//
+// This exists because pickTargetDevice used to silently reroute: when the
+// user's `preferredDeviceId` was absent from the list — or present but
+// carrying an empty `quicHost` — the preference block fell through to the
+// generic "first fresh machine" search. The user picked their Mac mini and
+// the fix landed on their laptop, with no error on either end.
+//
+// The contract now: an explicit preference is honoured by id alone, or the
+// pick fails. Not connecting is a better failure than connecting to the
+// wrong host.
+
+import { pickTargetDevice, isDeviceFresh } from '../_core/device';
+import { HEARTBEAT_STALE_MS } from '../_core/constants';
+import type { CoreDevice } from '../_core/device';
+
+const NOW = 1_700_000_000_000;
+
+function device(over: Partial<CoreDevice> & { deviceId: string }): CoreDevice {
+  return {
+    name: over.deviceId,
+    platform: 'darwin',
+    isOnline: true,
+    lastHeartbeat: NOW,
+    quicHost: '100.64.0.1',
+    quicPort: 18080,
+    ...over,
+  } as CoreDevice;
+}
+
+beforeEach(() => {
+  jest.spyOn(Date, 'now').mockReturnValue(NOW);
+});
+
+afterEach(() => {
+  jest.restoreAllMocks();
+});
+
+describe('pickTargetDevice — explicit preference', () => {
+  it('returns the preferred device when it is fresh', () => {
+    const macmini = device({ deviceId: 'macmini' });
+    const laptop = device({ deviceId: 'laptop' });
+    expect(pickTargetDevice([laptop, macmini], 'macmini')).toBe(macmini);
+  });
+
+  it('returns the preferred device even when it is STALE, rather than rerouting', () => {
+    const macmini = device({
+      deviceId: 'macmini',
+      lastHeartbeat: NOW - (HEARTBEAT_STALE_MS + 1),
+    });
+    const laptop = device({ deviceId: 'laptop' });
+    expect(isDeviceFresh(macmini)).toBe(false);
+    expect(pickTargetDevice([laptop, macmini], 'macmini')).toBe(macmini);
+  });
+
+  it('returns the preferred device even with NO quicHost — relay addresses it by id', () => {
+    // This is the off-LAN shape: no LAN address is published, and the relay
+    // route is `<relay>/d/<deviceId>`. An empty quicHost is not a reason to
+    // reroute; it is the normal remote case.
+    const macmini = device({ deviceId: 'macmini', quicHost: '' });
+    const laptop = device({ deviceId: 'laptop' });
+    expect(pickTargetDevice([laptop, macmini], 'macmini')).toBe(macmini);
+  });
+
+  it('returns null when the preferred id is absent — never falls through to another machine', () => {
+    const laptop = device({ deviceId: 'laptop' });
+    const desktop = device({ deviceId: 'desktop' });
+    expect(pickTargetDevice([laptop, desktop], 'macmini')).toBeNull();
+  });
+
+  it('returns null for an unknown preference even when exactly one healthy machine exists', () => {
+    // The tempting "well, there's only one, just use it" case. Still wrong:
+    // the user asked for a specific host.
+    expect(pickTargetDevice([device({ deviceId: 'laptop' })], 'macmini')).toBeNull();
+  });
+});
+
+describe('pickTargetDevice — no preference', () => {
+  it('prefers a fresh device with a quicHost over a stale one', () => {
+    const stale = device({
+      deviceId: 'stale',
+      lastHeartbeat: NOW - (HEARTBEAT_STALE_MS + 1),
+    });
+    const fresh = device({ deviceId: 'fresh' });
+    expect(pickTargetDevice([stale, fresh])).toBe(fresh);
+  });
+
+  it('falls back to an online device with a quicHost when none are fresh', () => {
+    const offline = device({ deviceId: 'offline', isOnline: false });
+    const online = device({
+      deviceId: 'online',
+      lastHeartbeat: NOW - (HEARTBEAT_STALE_MS + 1),
+    });
+    expect(pickTargetDevice([offline, online])).toBe(online);
+  });
+
+  it('returns null for an empty list', () => {
+    expect(pickTargetDevice([], 'macmini')).toBeNull();
+    expect(pickTargetDevice([])).toBeNull();
+  });
+});

package/src/__tests__/reloadActions.test.ts

@@ -0,0 +1,171 @@
+import {
+  describeReloadFailure,
+  reloadActions,
+  reloadFrameworkFamily,
+  reloadRequest,
+  RELOAD_APP_PATH,
+  RELOAD_PATH,
+} from '../reloadActions';
+
+const DEV = { isDevBuild: true, connected: true };
+
+describe('reloadActions — the production guard', () => {
+  // THIS IS THE GUARD. Prove it by breaking it: flip `if (!opts.isDevBuild)`
+  // in reloadActions.ts to `if (opts.isDevBuild)` and this test fails while
+  // every other test in this file still passes.
+  it('returns NOTHING in a production build, even with a healthy dev server', () => {
+    const actions = reloadActions(
+      { running: true, framework: 'vite' },
+      { isDevBuild: false, connected: true, includeRebuild: true },
+    );
+    expect(actions).toEqual([]);
+  });
+
+  it('returns actions in a dev build', () => {
+    const actions = reloadActions({ running: true, framework: 'vite' }, DEV);
+    expect(actions.map((a) => a.id)).toEqual(['hot', 'full']);
+    expect(actions.every((a) => a.enabled)).toBe(true);
+  });
+});
+
+describe('reloadFrameworkFamily', () => {
+  it.each([
+    ['flutter', 'flutter'],
+    ['expo', 'react-native'],
+    ['react-native', 'react-native'],
+    ['vite', 'web'],
+    ['nextjs', 'web'],
+    ['', 'unknown'],
+    ['godot', 'unknown'],
+  ])('maps %s → %s', (framework, family) => {
+    expect(reloadFrameworkFamily(framework)).toBe(family);
+  });
+});
+
+describe('per-stack labels', () => {
+  it('calls the full action a Hot Restart on Flutter (stdin R), not a Full Reload', () => {
+    const actions = reloadActions({ running: true, framework: 'flutter' }, DEV);
+    expect(actions.find((a) => a.id === 'hot')!.label).toBe('Hot Reload');
+    expect(actions.find((a) => a.id === 'full')!.label).toBe('Hot Restart');
+    expect(actions.find((a) => a.id === 'full')!.hint).toContain('(R)');
+  });
+
+  it('calls it a Full Reload everywhere else', () => {
+    for (const framework of ['expo', 'vite', 'nextjs']) {
+      const actions = reloadActions({ running: true, framework }, DEV);
+      expect(actions.find((a) => a.id === 'full')!.label).toBe('Full Reload');
+    }
+  });
+});
+
+describe('URL / payload construction', () => {
+  it('sends fast for hot and full for full, both to /dev/reload', () => {
+    const actions = reloadActions({ running: true, framework: 'flutter' }, DEV);
+    expect(reloadRequest(actions[0])).toEqual({
+      method: 'POST',
+      path: RELOAD_PATH,
+      body: { mode: 'fast' },
+    });
+    expect(reloadRequest(actions[1])).toEqual({
+      method: 'POST',
+      path: RELOAD_PATH,
+      body: { mode: 'full' },
+    });
+  });
+
+  it('routes the RN bundle rebuild to /dev/reload-app', () => {
+    const actions = reloadActions(
+      { running: false },
+      { ...DEV, includeRebuild: true },
+    );
+    const rebuild = actions.find((a) => a.id === 'rebuild')!;
+    expect(reloadRequest(rebuild)).toEqual({
+      method: 'POST',
+      path: RELOAD_APP_PATH,
+      body: { mode: 'bundle' },
+    });
+  });
+});
+
+describe('a blocked action NAMES the blocker', () => {
+  it('names the missing dev server and the command that starts it', () => {
+    const actions = reloadActions({ running: false }, { ...DEV, machineLabel: 'primary' });
+    expect(actions).toHaveLength(2);
+    for (const action of actions) {
+      expect(action.enabled).toBe(false);
+      expect(action.disabledReason).toContain('primary');
+      expect(action.disabledReason).toContain('yaver dev start');
+    }
+  });
+
+  it('names "still building" rather than pretending nothing is running', () => {
+    const actions = reloadActions({ running: true, building: true, framework: 'expo' }, DEV);
+    expect(actions[0].disabledReason).toContain('still building');
+  });
+
+  it('names the missing machine when disconnected', () => {
+    const actions = reloadActions(
+      { running: true, framework: 'expo' },
+      { isDevBuild: true, connected: false },
+    );
+    expect(actions[0].disabledReason).toContain('Not connected');
+  });
+
+  it('keeps Rebuild Bundle ENABLED with no dev server — that is its whole point', () => {
+    const actions = reloadActions({ running: false }, { ...DEV, includeRebuild: true });
+    const rebuild = actions.find((a) => a.id === 'rebuild')!;
+    expect(rebuild.enabled).toBe(true);
+    expect(rebuild.disabledReason).toBeUndefined();
+  });
+
+  it('disables Rebuild Bundle when there is no machine', () => {
+    const actions = reloadActions(
+      { running: true },
+      { isDevBuild: true, connected: false, includeRebuild: true },
+    );
+    expect(actions.find((a) => a.id === 'rebuild')!.enabled).toBe(false);
+  });
+});
+
+describe('describeReloadFailure names a cause, never "failed"', () => {
+  it('503 → no dev server', () => {
+    expect(describeReloadFailure(503, 'dev server not available')).toContain(
+      'No dev server is running',
+    );
+  });
+
+  it('framework cannot hot reload → says so and points at the alternative', () => {
+    const msg = describeReloadFailure(500, 'unity does not support hot reload', {
+      running: true,
+      framework: 'unity',
+    });
+    expect(msg).toContain('unity');
+    expect(msg).toContain('Rebuild Bundle');
+  });
+
+  it('loopback connection refused → the dev server is not listening', () => {
+    const msg = describeReloadFailure(
+      502,
+      'Get "http://127.0.0.1:8081/reload": dial tcp 127.0.0.1:8081: connect: connection refused',
+    );
+    expect(msg).toContain('not listening');
+    expect(msg).toContain('yaver dev start');
+  });
+
+  it('401/403 → session, not server', () => {
+    expect(describeReloadFailure(401, '')).toContain('sign in again');
+    expect(describeReloadFailure(403, '')).toContain('sign in again');
+  });
+
+  it('404 → the agent is too old, and says how to update it', () => {
+    expect(describeReloadFailure(404, 'not found')).toContain('yaver-cli@latest');
+  });
+
+  it('5xx → points at the agent log', () => {
+    expect(describeReloadFailure(500, 'boom')).toContain('yaver logs');
+  });
+
+  it('status 0 (transport never answered) → machine reachability', () => {
+    expect(describeReloadFailure(0, '')).toContain('yaver serve');
+  });
+});

package/src/__tests__/reloadActionsParity.test.ts

@@ -0,0 +1,49 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * `reloadActions.ts` is duplicated into yaver-feedback-react-native and
+ * yaver-feedback-web on purpose — they are two independently published npm
+ * packages, and neither may depend on the other.
+ *
+ * Duplication without a guard is DRIFT, and drift in this file is the worst
+ * kind: it is a *policy* file. If the web copy stops returning [] for a
+ * production build and the RN copy still does, the two SDKs disagree about
+ * whether a shipped app may show a reload button — and nothing in `tsc`
+ * notices, because they are separate compilation units.
+ *
+ * This is the same shape as beaconParity.test.ts in mobile/: read both
+ * sources, assert they agree. Prove it by breaking it — change one word in
+ * either copy and this test fails.
+ */
+const RN_COPY = join(__dirname, '..', 'reloadActions.ts');
+const WEB_COPY = join(
+  __dirname,
+  '..', '..', '..', // sdk/feedback/react-native
+  'web', 'src', 'reloadActions.ts',
+);
+
+describe('reloadActions parity between the RN and web SDKs', () => {
+  it('both copies exist', () => {
+    expect(() => readFileSync(RN_COPY, 'utf8')).not.toThrow();
+    expect(() => readFileSync(WEB_COPY, 'utf8')).not.toThrow();
+  });
+
+  it('is byte-identical across the two packages', () => {
+    const rn = readFileSync(RN_COPY, 'utf8');
+    const web = readFileSync(WEB_COPY, 'utf8');
+    expect(rn).toEqual(web);
+  });
+
+  it('still carries the production guard in BOTH copies', () => {
+    // Named separately from the byte comparison so that if someone
+    // legitimately reformats both files the failure still points at the one
+    // line that actually matters.
+    for (const [name, path] of [['react-native', RN_COPY], ['web', WEB_COPY]] as const) {
+      const source = readFileSync(path, 'utf8');
+      expect(`${name}: ${source.includes('if (!opts.isDevBuild) return [];')}`).toEqual(
+        `${name}: true`,
+      );
+    }
+  });
+});