yaver-feedback-react-native 0.9.0 → 0.9.3

package/src/deviceDogfood.ts

@@ -0,0 +1,171 @@
+import nacl from 'tweetnacl';
+import { Buffer } from 'buffer';
+import { DEFAULT_CONVEX_SITE_URL } from './auth';
+
+type SecureStoreLike = {
+  getItemAsync(key: string): Promise<string | null>;
+  setItemAsync(key: string, value: string): Promise<void>;
+  deleteItemAsync(key: string): Promise<void>;
+};
+
+export type DeviceDogfoodState = 'unregistered' | 'pending' | 'active' | 'cancelled' | 'revoked' | 'superseded';
+
+export interface DeviceDogfoodOptions {
+  /** Public identifier registered by the app owner in Yaver Settings. */
+  appId: string;
+  label?: string;
+  backendUrl?: string;
+  /** Advanced bare-RN integration. Expo apps use SecureStore automatically. */
+  secureStore?: SecureStoreLike;
+}
+
+export interface DeviceDogfoodSession {
+  active: true;
+  appId: string;
+  installationId: string;
+  token: string;
+  expiresAt: number;
+  scopes: string[];
+  projectSlug?: string;
+  targetDeviceId?: string;
+}
+
+interface StoredIdentity {
+  installationId: string;
+  registrationSlot: string;
+  publicKey: string;
+  secretKey: string;
+}
+
+function b64(bytes: Uint8Array): string { return Buffer.from(bytes).toString('base64'); }
+function fromB64(value: string): Uint8Array { return new Uint8Array(Buffer.from(value, 'base64')); }
+function b64url(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString('base64').replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+}
+
+function randomBytes(length: number): Uint8Array {
+  const cryptoObject = (globalThis as any)?.crypto;
+  if (cryptoObject?.getRandomValues) {
+    const out = new Uint8Array(length);
+    cryptoObject.getRandomValues(out);
+    return out;
+  }
+  try {
+    return require('expo-crypto').getRandomBytes(length);
+  } catch {
+    throw new Error('Secure randomness is unavailable. Install expo-crypto or provide global crypto.getRandomValues.');
+  }
+}
+
+function defaultSecureStore(): SecureStoreLike {
+  try {
+    const store = require('expo-secure-store');
+    if (store?.getItemAsync && store?.setItemAsync) return store;
+  } catch { /* named error below */ }
+  throw new Error('Secure Dogfood identity storage is unavailable. Install expo-secure-store or pass secureStore.');
+}
+
+async function responseJSON(response: Response): Promise<any> {
+  const body = await response.json().catch(() => ({}));
+  if (!response.ok) throw new Error(body?.error || `Yaver Dogfood request failed (HTTP ${response.status})`);
+  return body;
+}
+
+function enrollmentMessage(appId: string, installationId: string, challenge: string): Uint8Array {
+  return new TextEncoder().encode(`yaver-dogfood-enroll-v1\n${appId}\n${installationId}\n${challenge}`);
+}
+
+function sessionMessage(appId: string, installationId: string, challenge: string): Uint8Array {
+  return new TextEncoder().encode(`yaver-dogfood-session-v1\n${appId}\n${installationId}\n${challenge}`);
+}
+
+/** Account-free third-party Dogfood enrollment. The UUID is a public lookup
+ * handle; possession is proven by the private key retained in this app. */
+export class YaverDeviceDogfood {
+  private readonly backendUrl: string;
+  private readonly store: SecureStoreLike;
+  private readonly storageKey: string;
+
+  constructor(private readonly options: DeviceDogfoodOptions) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{2,127}$/.test(options.appId)) throw new Error('A valid Dogfood appId is required');
+    this.backendUrl = (options.backendUrl || DEFAULT_CONVEX_SITE_URL).replace(/\/$/, '');
+    this.store = options.secureStore || defaultSecureStore();
+    this.storageKey = `yaver_feedback_dogfood_v1_${options.appId}`;
+  }
+
+  private async identity(): Promise<StoredIdentity> {
+    const raw = await this.store.getItemAsync(this.storageKey);
+    if (raw) {
+      try {
+        const saved = JSON.parse(raw) as StoredIdentity;
+        if (fromB64(saved.publicKey).length === nacl.sign.publicKeyLength && fromB64(saved.secretKey).length === nacl.sign.secretKeyLength) return saved;
+      } catch { /* rotate corrupt identity below */ }
+    }
+    const seed = randomBytes(32);
+    const pair = nacl.sign.keyPair.fromSeed(seed);
+    seed.fill(0);
+    const identity: StoredIdentity = {
+      installationId: b64url(randomBytes(18)), registrationSlot: b64url(randomBytes(18)),
+      publicKey: b64(pair.publicKey), secretKey: b64(pair.secretKey),
+    };
+    await this.store.setItemAsync(this.storageKey, JSON.stringify(identity));
+    return identity;
+  }
+
+  async enrollmentInfo(): Promise<{ appId: string; installationId: string; registrationSlot: string; publicKey: string }> {
+    const identity = await this.identity();
+    return { appId: this.options.appId, installationId: identity.installationId, registrationSlot: identity.registrationSlot, publicKey: identity.publicKey };
+  }
+
+  async enroll(platform = 'unknown'): Promise<{ status: DeviceDogfoodState; installationId: string }> {
+    const identity = await this.identity();
+    const started = await responseJSON(await fetch(`${this.backendUrl}/dogfood/enroll/start`, {
+      method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ appId: this.options.appId, installationId: identity.installationId, registrationSlot: identity.registrationSlot, publicKey: identity.publicKey, platform, label: this.options.label }),
+    }));
+    if (started.status === 'active') return { status: 'active', installationId: identity.installationId };
+    const signature = b64(nacl.sign.detached(enrollmentMessage(this.options.appId, identity.installationId, started.challenge), fromB64(identity.secretKey)));
+    await responseJSON(await fetch(`${this.backendUrl}/dogfood/enroll/prove`, {
+      method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ appId: this.options.appId, installationId: identity.installationId, signature }),
+    }));
+    return { status: 'pending', installationId: identity.installationId };
+  }
+
+  async status(): Promise<DeviceDogfoodState> {
+    const identity = await this.identity();
+    const response = await fetch(`${this.backendUrl}/dogfood/enroll/status?appId=${encodeURIComponent(this.options.appId)}&installationId=${encodeURIComponent(identity.installationId)}`);
+    if (response.status === 404) return 'unregistered';
+    return (await responseJSON(response)).status as DeviceDogfoodState;
+  }
+
+  async session(): Promise<DeviceDogfoodSession | null> {
+    const identity = await this.identity();
+    if (await this.status() !== 'active') return null;
+    const challenge = await responseJSON(await fetch(`${this.backendUrl}/dogfood/session/challenge`, {
+      method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ appId: this.options.appId, installationId: identity.installationId }),
+    }));
+    const signature = b64(nacl.sign.detached(sessionMessage(this.options.appId, identity.installationId, challenge.challenge), fromB64(identity.secretKey)));
+    const result = await responseJSON(await fetch(`${this.backendUrl}/dogfood/session`, {
+      method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ appId: this.options.appId, installationId: identity.installationId, signature }),
+    }));
+    return { active: true, appId: this.options.appId, installationId: identity.installationId, token: result.token, expiresAt: result.expiresAt, scopes: result.scopes || [], projectSlug: result.projectSlug, targetDeviceId: result.targetDeviceId };
+  }
+
+  /** Rotate the key but keep the logical slot. Approval supersedes the prior
+   * generation, making its already-issued sessions fail immediately. */
+  async reRegister(platform = 'unknown'): Promise<{ status: DeviceDogfoodState; installationId: string }> {
+    const previous = await this.identity();
+    const seed = randomBytes(32);
+    const pair = nacl.sign.keyPair.fromSeed(seed);
+    seed.fill(0);
+    const next: StoredIdentity = {
+      installationId: b64url(randomBytes(18)), registrationSlot: previous.registrationSlot,
+      publicKey: b64(pair.publicKey), secretKey: b64(pair.secretKey),
+    };
+    await this.store.setItemAsync(this.storageKey, JSON.stringify(next));
+    return this.enroll(platform);
+  }
+}

package/src/dogfoodPolicy.ts

@@ -0,0 +1,40 @@
+export interface SDKDogfoodConfig {
+  /** Explicit opt-in. Omitted/false keeps the normal Feedback SDK. */
+  enabled?: boolean;
+  /** App-account IDs allowed to enter Dogfood. Public identifiers, not secrets. */
+  accountIds?: string[];
+  /** The third-party app's currently authenticated account ID. */
+  currentAccountId?: string;
+  /** Account-free installation identity resolved by YaverDeviceDogfood. */
+  appId?: string;
+  installationId?: string;
+  installationStatus?: 'pending' | 'active' | 'cancelled' | 'revoked' | 'superseded';
+  /** Called after the user confirms Exit Dogfood mode. */
+  onExit?: () => void | Promise<void>;
+  /** Optional app label shown beside Dogfood mode. */
+  label?: string;
+}
+
+export interface SDKDogfoodStatus {
+  active: boolean;
+  code: 'SDK_DOGFOOD_ACTIVE' | 'SDK_DOGFOOD_DISABLED' | 'SDK_DOGFOOD_ACCOUNT_REQUIRED' | 'SDK_DOGFOOD_ACCOUNT_NOT_ALLOWED' | 'SDK_DOGFOOD_INSTALLATION_REQUIRED' | 'SDK_DOGFOOD_INSTALLATION_NOT_ACTIVE';
+  accountId?: string;
+  label: string;
+}
+
+/** Pure, fail-closed account gate shared by init, the Y badge and tests.
+ * This controls SDK UX only; every task/reload still requires Yaver auth. */
+export function resolveSDKDogfood(config?: SDKDogfoodConfig | null): SDKDogfoodStatus {
+  const label = String(config?.label || 'Dogfood').trim() || 'Dogfood';
+  if (config?.enabled !== true) return { active: false, code: 'SDK_DOGFOOD_DISABLED', label };
+  if (config.appId) {
+    if (!config.installationId) return { active: false, code: 'SDK_DOGFOOD_INSTALLATION_REQUIRED', label };
+    if (config.installationStatus !== 'active') return { active: false, code: 'SDK_DOGFOOD_INSTALLATION_NOT_ACTIVE', label };
+    return { active: true, code: 'SDK_DOGFOOD_ACTIVE', accountId: config.installationId, label };
+  }
+  const accountId = String(config.currentAccountId || '').trim();
+  if (!accountId) return { active: false, code: 'SDK_DOGFOOD_ACCOUNT_REQUIRED', label };
+  const allowed = new Set((config.accountIds || []).map((id) => String(id).trim()).filter(Boolean));
+  if (!allowed.has(accountId)) return { active: false, code: 'SDK_DOGFOOD_ACCOUNT_NOT_ALLOWED', accountId, label };
+  return { active: true, code: 'SDK_DOGFOOD_ACTIVE', accountId, label };
+}

package/src/index.ts

@@ -29,24 +29,83 @@
  */
 
 export { YaverFeedback } from './YaverFeedback';
+export type { DogfoodOnboardingOptions } 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 type {
+  DogfoodDevEvent,
+  DogfoodDevServerStatus,
+  DogfoodRemoteRuntimeCapabilities,
+  DogfoodRemoteRuntimeSession,
+  DogfoodRemoteRuntimeTarget,
+} from './P2PClient';
+export { createP2PDogfoodDriver, type P2PDogfoodDriverOptions } from './P2PDogfoodDriver';
+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';
 export { YaverMachinePickerScreen } from './MachinePickerScreen';
 export type { YaverMachinePickerProps } from './MachinePickerScreen';
-export { YaverGuestOnboardingScreen } from './GuestOnboardingScreen';
-export type { YaverGuestOnboardingScreenProps } from './GuestOnboardingScreen';
 export { PairDeviceModal } from './PairDeviceModal';
 export type { PairDeviceModalProps } from './PairDeviceModal';
 export { AuthOverlay } from './AuthOverlay';
 export { ShakeDetector } from './ShakeDetector';
 export { FloatingButton } from './FloatingButton';
+// The polite "you're inside Yaver" mark. Rendered automatically by the SDK's
+// overlay host when config.modeBadge !== false; exported so an app that manages
+// its own overlay tree can place it itself.
+export { YaverModeBadge, hideYaverModeBadge, showYaverModeBadge, isYaverModeBadgeHidden } from './YaverModeBadge';
+export type { YaverModeBadgeProps } from './YaverModeBadge';
+export { resolveSDKDogfood } from './dogfoodPolicy';
+export type { SDKDogfoodConfig, SDKDogfoodStatus } from './dogfoodPolicy';
+export { YaverDeviceDogfood } from './deviceDogfood';
+export type { DeviceDogfoodOptions, DeviceDogfoodSession, DeviceDogfoodState } from './deviceDogfood';
+export {
+  DogfoodController,
+  DogfoodRuntimeError,
+  defaultDogfoodLane,
+  dogfoodLaneOptions,
+  dogfoodLogLinesFromDevEvent,
+  runtimeLogLinesFromDevEvent,
+  validateDogfoodProject,
+} from './DogfoodRuntime';
+export type {
+  DogfoodControllerOptions,
+  DogfoodDriver,
+  DogfoodFailure,
+  DogfoodLane,
+  DogfoodLaneOption,
+  DogfoodLogLine,
+  DogfoodPhase,
+  DogfoodProject,
+  DogfoodResult,
+  DogfoodRunContext,
+  DogfoodSnapshot,
+} from './DogfoodRuntime';
 export { FeedbackModal } from './FeedbackModal';
 export { QuickActionIcon } from './QuickActionIcon';
 export type { QuickActionIconProps } from './QuickActionIcon';
@@ -74,10 +133,6 @@ export {
   signupWithEmail,
   loginWithEmail,
   listReachableDevices,
-  fetchGuestHosts,
-  findInviteByCode,
-  acceptGuestByCode,
-  acceptGuestInvitation,
   DEFAULT_CONVEX_SITE_URL,
   DEFAULT_WEB_BASE_URL,
   DEFAULT_OAUTH_REDIRECT,
@@ -87,11 +142,6 @@ export type {
   User,
   RemoteDevice,
   DeviceList,
-  GuestInvitation,
-  ActiveGuestHost,
-  GuestHostsResponse,
-  InvitationHostDevice,
-  InvitationPreview,
 } from './auth';
 export {
   captureScreenshot,

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 `authSDK` (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 `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}).`;
+}