yaver-feedback-react-native 0.9.7 → 0.9.8

package/src/YaverFeedback.ts

@@ -15,6 +15,7 @@ import {
   getToken,
   getSelectedDeviceId,
   getDogfoodAccountAccess,
+  setDogfoodControlPreference,
   listReachableDevices,
   clearToken,
   clearSelectedDeviceId,
@@ -25,6 +26,11 @@ import {
   getQuickIconColorPreset,
   setQuickIconDisabled,
   setQuickIconColorPreset,
+  getDogfoodControlPresentation,
+  setDogfoodControlPresentation as cacheDogfoodControlPresentation,
+  getDogfoodControlOnboardingSeen,
+  setDogfoodControlOnboardingSeen,
+  type DogfoodControlPresentation,
   QuickIconColorPreset,
 } from './preferences';
 import { resolveSDKDogfood, type SDKDogfoodStatus, type DogfoodAccessSnapshot } from './dogfoodPolicy';
@@ -44,6 +50,27 @@ export interface DogfoodFlowState {
   error?: string;
 }
 
+export interface DogfoodControlTriggerState {
+  configured: boolean;
+  authorized: boolean;
+  appId?: string;
+  installationId?: string;
+  gestureSupported: boolean;
+  gestureEnabled: boolean;
+  fallbackVisible: boolean;
+  presentation: DogfoodControlPresentation;
+  onboardingSeen: boolean;
+  reason: string;
+  platform?: string;
+}
+
+interface DogfoodControlSyncOptions {
+  presentation?: DogfoodControlPresentation;
+  onboardingSeen?: boolean;
+  /** User-initiated changes fail visibly when Convex cannot persist them. */
+  requirePersistence?: boolean;
+}
+
 function unrefTimer(timer: ReturnType<typeof setTimeout>): void {
   const maybeNodeTimer = timer as unknown as { unref?: () => void };
   if (typeof maybeNodeTimer.unref === 'function') {
@@ -194,6 +221,11 @@ let dogfoodActivationSubscription: { remove: () => void } | null = null;
 let dogfoodShortcutLaunchInFlight = false;
 let lastDogfoodActivationUrl = '';
 
+function dogfoodControlPreferenceScope(appId?: string, installationId?: string): string | undefined {
+  if (!appId || !installationId) return undefined;
+  return `${appId}:${installationId}`;
+}
+
 function publishDogfoodFlow(state: DogfoodFlowState): void {
   dogfoodFlowState = state;
   try { config?.dogfood?.onStateChange?.(state); } catch { /* host callback */ }
@@ -490,19 +522,29 @@ export class YaverFeedback {
       void YaverFeedback.hydrateSession();
     }
 
-    if (config.dogfood?.appShortcut) {
-      void YaverFeedback.syncDogfoodAppShortcut();
-      void consumeNativeDogfoodShortcut();
+    if (config.dogfood?.appShortcut || config.dogfood?.controlGesture) {
+      if (config.dogfood?.appShortcut) {
+        void YaverFeedback.syncDogfoodAppShortcut();
+        void consumeNativeDogfoodShortcut();
+      }
+      if (config.dogfood?.controlGesture) {
+        void YaverFeedback.syncDogfoodControlGesture();
+      }
       try {
         const { AppState } = require('react-native');
         dogfoodShortcutAppStateSubscription?.remove();
         dogfoodShortcutAppStateSubscription = AppState.addEventListener('change', (state: string) => {
           if (state === 'active') {
-            void YaverFeedback.syncDogfoodAppShortcut();
-            void consumeNativeDogfoodShortcut();
+            if (config?.dogfood?.appShortcut) {
+              void YaverFeedback.syncDogfoodAppShortcut();
+              void consumeNativeDogfoodShortcut();
+            }
+            if (config?.dogfood?.controlGesture) {
+              void YaverFeedback.syncDogfoodControlGesture();
+            }
           }
         });
-      } catch { /* native shortcut unavailable on web/test runtimes */ }
+      } catch { /* native quick controls unavailable on web/test runtimes */ }
     }
     if (config.dogfood) {
       try {
@@ -805,6 +847,7 @@ export class YaverFeedback {
       YaverFeedback.scheduleBlackBoxAutoStart();
     }
     await YaverFeedback.syncDogfoodAppShortcut().catch(() => false);
+    await YaverFeedback.syncDogfoodControlGesture().catch(() => undefined);
   }
 
   /** Returns true once the SDK has a session token it can use. */
@@ -963,16 +1006,21 @@ export class YaverFeedback {
     const token = config?.authToken || await getToken();
     const account = token
       ? await getDogfoodAccountAccess(appId, token, installationId)
-      : { authenticated: false, ownerAuthorized: false, installationAuthorized: false };
+      : { authenticated: false, ownerAuthorized: false, accountAuthorized: false, installationAuthorized: false };
     const yaverAuthenticated = account.authenticated;
     const ownerAuthorized = account.ownerAuthorized;
     return {
       appId,
       yaverAuthenticated,
       ownerAuthorized,
+      accountAuthorized: account.accountAuthorized,
       installationId,
       deviceState,
       authorized: yaverAuthenticated && account.installationAuthorized && deviceState === 'active',
+      controlPresentation: account.controlPresentation,
+      gestureSupported: account.gestureSupported,
+      gestureCapabilityReason: account.gestureCapabilityReason,
+      controlOnboardingSeen: account.controlOnboardingSeen,
     };
   }
 
@@ -1002,6 +1050,244 @@ export class YaverFeedback {
     return visible;
   }
 
+  /** Capability-gated in-app Dogfood controls. Every new exact installation
+   * starts with Y until Convex records onboarding. A supported standalone app
+   * can then select a passive three-finger hold and no persistent pixels;
+   * missing native support or accessibility touch exploration keeps Y. Yaver's
+   * own container suppresses both because its split preview/chat UI owns them. */
+  static async syncDogfoodControlGesture(
+    syncOptions: DogfoodControlSyncOptions = {},
+  ): Promise<DogfoodControlTriggerState> {
+    const configured = config?.dogfood?.controlGesture;
+    const native = (NativeModules as any)?.YaverDogfoodGesture;
+    const base: DogfoodControlTriggerState = {
+      configured: Boolean(configured),
+      authorized: false,
+      gestureSupported: false,
+      gestureEnabled: false,
+      fallbackVisible: false,
+      presentation: syncOptions.presentation || 'auto',
+      onboardingSeen: syncOptions.onboardingSeen === true,
+      reason: configured ? 'native-module-unavailable' : 'not-configured',
+      platform: Platform.OS,
+    };
+    if (!configured) {
+      if (typeof native?.setEnabled === 'function') {
+        await native.setEnabled(false, 900).catch(() => undefined);
+      }
+      return base;
+    }
+    if (IS_HOST_MODE || isRunningInsideYaverHost()) {
+      if (typeof native?.setEnabled === 'function') {
+        await native.setEnabled(false, 900).catch(() => undefined);
+      }
+      return { ...base, reason: 'yaver-host-owns-controls' };
+    }
+
+    const access = await YaverFeedback.getDogfoodAccess();
+    let authorized = access.authorized;
+    if (authorized && config?.dogfood?.canShow) {
+      try {
+        authorized = await config.dogfood.canShow(access);
+      } catch {
+        authorized = false;
+      }
+    }
+    const options = typeof configured === 'object' ? configured : {};
+    const durationMs = Math.min(2000, Math.max(650, options.durationMs ?? 900));
+    const allowFallback = options.fallback !== 'none';
+    if (!authorized) {
+      if (typeof native?.setEnabled === 'function') {
+        await native.setEnabled(false, durationMs).catch(() => undefined);
+      }
+      return { ...base, appId: access.appId, installationId: access.installationId, reason: 'installation-not-authorized' };
+    }
+
+    const preferenceScope = dogfoodControlPreferenceScope(access.appId, access.installationId);
+    const cachedPresentation = await getDogfoodControlPresentation(preferenceScope);
+    const cachedOnboardingSeen = await getDogfoodControlOnboardingSeen(preferenceScope);
+    const onboardingSeen = syncOptions.onboardingSeen
+      ?? access.controlOnboardingSeen
+      ?? cachedOnboardingSeen;
+    // A newly authorized tester must never be left staring at an invisible
+    // feature. Until the exact installation has completed onboarding in
+    // Convex, the edge-docked Y wins even when the gesture is supported.
+    const preferredPresentation = syncOptions.presentation
+      || access.controlPresentation
+      || cachedPresentation
+      || options.defaultPresentation
+      || 'auto';
+    const presentation: DogfoodControlPresentation = onboardingSeen
+      ? preferredPresentation
+      : 'minimized-y';
+
+    if (typeof native?.getCapability !== 'function' || typeof native?.setEnabled !== 'function') {
+      const result: DogfoodControlTriggerState = {
+        ...base,
+        authorized: true,
+        appId: access.appId,
+        installationId: access.installationId,
+        presentation: 'minimized-y',
+        onboardingSeen,
+        fallbackVisible: allowFallback,
+      };
+      if (syncOptions.requirePersistence) {
+        const token = config?.authToken || await getToken();
+        if (!token || !access.installationId) {
+          throw new Error('A full Yaver session is required to save Dogfood settings.');
+        }
+        const persisted = await setDogfoodControlPreference({
+          appId: access.appId,
+          installationId: access.installationId,
+          token,
+          presentation: 'minimized-y',
+          gestureSupported: false,
+          gestureCapabilityReason: 'native-module-unavailable',
+          gesturePlatform: Platform.OS,
+          controlOnboardingSeen: onboardingSeen,
+        });
+        if (!persisted) throw new Error('Could not save this Dogfood control preference to Yaver.');
+        await cacheDogfoodControlPresentation('minimized-y', preferenceScope);
+        if (onboardingSeen) await setDogfoodControlOnboardingSeen(true, preferenceScope);
+      }
+      return result;
+    }
+    try {
+      const capability = await native.getCapability();
+      const gestureSupported = capability?.supported === true;
+      const shouldEnableGesture = gestureSupported && onboardingSeen && presentation === 'auto';
+      const applied = await native.setEnabled(shouldEnableGesture, durationMs);
+      const gestureEnabled = shouldEnableGesture && applied?.enabled === true;
+      const gestureEnableFailed = shouldEnableGesture && !gestureEnabled;
+      const result: DogfoodControlTriggerState = {
+        configured: true,
+        authorized: true,
+        appId: access.appId,
+        installationId: access.installationId,
+        gestureSupported,
+        gestureEnabled,
+        fallbackVisible: allowFallback && (!gestureSupported || presentation === 'minimized-y' || gestureEnableFailed),
+        presentation,
+        onboardingSeen,
+        reason: gestureEnableFailed
+          ? 'gesture-enable-failed'
+          : String(applied?.reason || capability?.reason || (gestureSupported ? 'supported' : 'unsupported')),
+        platform: String(applied?.platform || capability?.platform || Platform.OS),
+      };
+      const token = config?.authToken || await getToken();
+      if (syncOptions.requirePersistence && (!token || !access.installationId)) {
+        await native.setEnabled(false, durationMs).catch(() => undefined);
+        throw new Error('A full Yaver session is required to save Dogfood settings.');
+      }
+      if (token && access.installationId) {
+        const needsPersistence =
+          access.controlPresentation !== presentation
+          || access.gestureSupported !== gestureSupported
+          || access.gestureCapabilityReason !== result.reason
+          || (syncOptions.onboardingSeen === true && access.controlOnboardingSeen !== true);
+        if (needsPersistence) {
+          const persisted = await setDogfoodControlPreference({
+            appId: access.appId,
+            installationId: access.installationId,
+            token,
+            presentation,
+            gestureSupported,
+            gestureCapabilityReason: result.reason,
+            gesturePlatform: result.platform || Platform.OS,
+            controlOnboardingSeen: onboardingSeen,
+          });
+          if (!persisted && syncOptions.requirePersistence) {
+            await native.setEnabled(false, durationMs).catch(() => undefined);
+            throw new Error('Could not save this Dogfood control preference to Yaver.');
+          }
+          if (persisted) {
+            await cacheDogfoodControlPresentation(presentation, preferenceScope);
+            if (onboardingSeen) await setDogfoodControlOnboardingSeen(true, preferenceScope);
+          }
+        } else {
+          await cacheDogfoodControlPresentation(presentation, preferenceScope);
+          if (onboardingSeen) await setDogfoodControlOnboardingSeen(true, preferenceScope);
+        }
+      }
+      return result;
+    } catch (error) {
+      await native.setEnabled(false, durationMs).catch(() => undefined);
+      if (syncOptions.requirePersistence) {
+        throw error instanceof Error
+          ? error
+          : new Error('Could not save this Dogfood control preference to Yaver.');
+      }
+      return {
+        ...base,
+        authorized: true,
+        appId: access.appId,
+        installationId: access.installationId,
+        presentation: 'minimized-y',
+        onboardingSeen,
+        fallbackVisible: allowFallback,
+        reason: 'native-capability-check-failed',
+      };
+    }
+  }
+
+  /** Complete first-run onboarding or change the later control preference.
+   * Convex is authoritative and keyed by full Yaver user + app + installation;
+   * the local value is only a cold-start cache. */
+  static async setDogfoodControlPresentation(
+    presentation: DogfoodControlPresentation,
+  ): Promise<DogfoodControlTriggerState> {
+    if (presentation !== 'auto' && presentation !== 'minimized-y') {
+      throw new Error('Invalid Dogfood control presentation.');
+    }
+    return YaverFeedback.syncDogfoodControlGesture({
+      presentation,
+      onboardingSeen: true,
+      requirePersistence: true,
+    });
+  }
+
+  /** One-tap fast reload for the compact Dogfood card. It preserves the same
+   * selected render machine and bearer-authenticated P2P route as the full
+   * Feedback modal, and names missing auth/machine state instead of no-oping. */
+  static async requestDogfoodFastReload(): Promise<string> {
+    await YaverFeedback.hydrateSession();
+    if (!config?.authToken) {
+      YaverFeedback.showLogin();
+      throw new Error('Sign in to Yaver before requesting Fast Reload.');
+    }
+    if (!config.preferredDeviceId) {
+      YaverFeedback.showMachinePicker();
+      throw new Error('Choose a render machine before requesting Fast Reload.');
+    }
+    const selected = await YaverFeedback.getSelectedRemoteDevice();
+    if (!selected) {
+      YaverFeedback.showMachinePicker();
+      throw new Error('The selected render machine is no longer available.');
+    }
+    if (selected.needsAuth) {
+      YaverFeedback.showMachinePicker();
+      throw new Error('The selected render machine needs pairing again.');
+    }
+    if (!selected.isOnline) {
+      throw new Error('The selected render machine is offline.');
+    }
+    let client = YaverFeedback.getRenderP2PClient();
+    if (!client && await YaverFeedback.reconnect()) {
+      client = YaverFeedback.getRenderP2PClient();
+    }
+    if (!client) throw new Error('The render machine is not connected yet.');
+    try {
+      const ack = await client.reloadWithMode('fast');
+      return ack.message;
+    } catch (firstError) {
+      if (await YaverFeedback.reconnect()) {
+        const retry = YaverFeedback.getRenderP2PClient();
+        if (retry) return (await retry.reloadWithMode('fast')).message;
+      }
+      throw firstError;
+    }
+  }
+
   /** Backwards-compatible entry point for existing integrations. */
   static async beginDogfoodOnboarding(options: DogfoodOnboardingOptions): Promise<DogfoodFlowState> {
     YaverFeedback.configureDogfood(options);
@@ -1025,11 +1311,28 @@ export class YaverFeedback {
       publishDogfoodFlow(state);
       return state;
     }
-    await YaverFeedback.hydrateSession();
-    const token = config?.authToken || await getToken();
-    const account = token
-      ? await getDogfoodAccountAccess(appId, token)
-      : { authenticated: false, ownerAuthorized: false, installationAuthorized: false };
+    let token: string | null;
+    let account: Awaited<ReturnType<typeof getDogfoodAccountAccess>> | {
+      authenticated: false;
+      ownerAuthorized: false;
+      accountAuthorized: false;
+      installationAuthorized: false;
+    };
+    try {
+      await YaverFeedback.hydrateSession();
+      token = config?.authToken || await getToken();
+      account = token
+        ? await getDogfoodAccountAccess(appId, token)
+        : { authenticated: false, ownerAuthorized: false, accountAuthorized: false, installationAuthorized: false };
+    } catch (cause) {
+      const state: DogfoodFlowState = {
+        phase: 'error',
+        appId,
+        error: cause instanceof Error ? cause.message : 'Yaver could not verify Dogfood access.',
+      };
+      publishDogfoodFlow(state);
+      return state;
+    }
     // A device key is a second factor for this installation, never a
     // replacement for a real Yaver account. Narrow installation sessions and
     // stale/invalid cached tokens both return authenticated=false here.
@@ -1039,6 +1342,15 @@ export class YaverFeedback {
       YaverFeedback.showLogin();
       return state;
     }
+    if (!account.accountAuthorized) {
+      const state: DogfoodFlowState = {
+        phase: 'denied',
+        appId,
+        error: 'The app owner has not enabled Dogfood for this Yaver account.',
+      };
+      publishDogfoodFlow(state);
+      return state;
+    }
     if (!config?.preferredDeviceId) {
       const state: DogfoodFlowState = { phase: 'machine-required', appId };
       publishDogfoodFlow(state);
@@ -1162,6 +1474,7 @@ export class YaverFeedback {
     renderP2PClient = null;
     p2pAuthToken = null;
     await YaverFeedback.syncDogfoodAppShortcut().catch(() => false);
+    await YaverFeedback.syncDogfoodControlGesture().catch(() => undefined);
   }
 
   /**
@@ -1461,6 +1774,7 @@ export class YaverFeedback {
       DeviceEventEmitter.emit('yaverFeedback:dogfoodChanged', { active: !!session, status });
     } catch { /* noop */ }
     await YaverFeedback.syncDogfoodAppShortcut().catch(() => false);
+    await YaverFeedback.syncDogfoodControlGesture().catch(() => undefined);
     return { status, installationId: info.installationId, session };
   }
 
@@ -1475,6 +1789,7 @@ export class YaverFeedback {
       const { DeviceEventEmitter } = require('react-native');
       DeviceEventEmitter.emit('yaverFeedback:dogfoodChanged', { active: false, exited: true });
     } catch { /* noop */ }
+    await YaverFeedback.syncDogfoodControlGesture().catch(() => undefined);
   }
 
   /** Returns the resolved relay password the SDK is currently using.
@@ -2019,6 +2334,12 @@ export class YaverFeedback {
     dogfoodShortcutAppStateSubscription = null;
     dogfoodActivationSubscription?.remove();
     dogfoodActivationSubscription = null;
+    try {
+      const native = (NativeModules as any)?.YaverDogfoodGesture;
+      if (typeof native?.setEnabled === 'function') {
+        void native.setEnabled(false, 900).catch(() => undefined);
+      }
+    } catch { /* native trigger teardown is best-effort */ }
     lastDogfoodActivationUrl = '';
     // Before `enabled = false` / `config = null` below, so an in-flight retry
     // can't fire against a torn-down config.

package/src/__tests__/NativeDogfoodShortcut.test.ts

@@ -56,4 +56,19 @@ final class TalosSceneDelegate: UIResponder, UIWindowSceneDelegate {
     expect(android).toContain('addDynamicShortcuts');
     expect(android).toContain('consumeDogfoodShortcut');
   });
+
+  it('observes a three-finger hold without consuming host app touches', () => {
+    const ios = readFileSync(join(__dirname, '../../ios/YaverDogfoodGesture.swift'), 'utf8');
+    const android = readFileSync(join(__dirname, '../../android/src/main/java/io/yaver/feedback/YaverDogfoodGestureModule.java'), 'utf8');
+    const controls = readFileSync(join(__dirname, '../DogfoodQuickControls.tsx'), 'utf8');
+    expect(ios).toContain('numberOfTouchesRequired = 3');
+    expect(ios).toContain('cancelsTouchesInView = false');
+    expect(ios).toContain('isVoiceOverRunning');
+    expect(android).toContain('event.getPointerCount() >= 3');
+    expect(android).toContain('method.invoke(callback, args)');
+    expect(android).toContain('isTouchExplorationEnabled');
+    expect(controls).toContain('yaver-dogfood-fast-reload');
+    expect(controls).toContain('yaver-dogfood-chat');
+    expect(controls).toContain('yaver-dogfood-minimized-control');
+  });
 });

package/src/__tests__/YaverFeedback.test.ts

@@ -1,5 +1,6 @@
 import { DeviceEventEmitter, NativeModules } from 'react-native';
 import { YaverFeedback } from '../YaverFeedback';
+import { getDogfoodAccountAccess, setDogfoodControlPreference } from '../auth';
 
 // Mock react-native: DeviceEventEmitter for event dispatch + Platform so
 // ShakeDetector.start() can branch on iOS without hitting a real RN runtime.
@@ -14,6 +15,10 @@ jest.mock('react-native', () => ({
       setDogfoodShortcut: jest.fn(async () => true),
       consumeDogfoodShortcut: jest.fn(async () => false),
     },
+    YaverDogfoodGesture: {
+      getCapability: jest.fn(async () => ({ supported: true, enabled: false, reason: 'supported', platform: 'ios' })),
+      setEnabled: jest.fn(async (next: boolean) => ({ supported: true, enabled: next, reason: 'supported', platform: 'ios' })),
+    },
   },
   AppState: { addEventListener: jest.fn(() => ({ remove: jest.fn() })) },
 }));
@@ -33,8 +38,10 @@ jest.mock('../auth', () => ({
   getDogfoodAccountAccess: jest.fn(async (_appId: string, token: string) => ({
     authenticated: token === 'owner-token',
     ownerAuthorized: token === 'owner-token',
+    accountAuthorized: token === 'owner-token',
     installationAuthorized: token === 'owner-token',
   })),
+  setDogfoodControlPreference: jest.fn(async () => true),
   saveSelectedDeviceId: jest.fn(async () => {}),
   clearToken: jest.fn(async () => {}),
   clearSelectedDeviceId: jest.fn(async () => {}),
@@ -103,6 +110,18 @@ describe('YaverFeedback', () => {
       expect(states[states.length - 1]).toBe('auth-required');
     });
 
+    it('returns a visible structured error when access verification fails', async () => {
+      YaverFeedback.init({ enabled: true, authToken: 'owner-token' });
+      (getDogfoodAccountAccess as jest.Mock).mockRejectedValueOnce(new Error('Access service unavailable'));
+      const state = await YaverFeedback.beginDogfoodOnboarding({ appId: 'io.example.app' });
+      expect(state).toEqual({
+        phase: 'error',
+        appId: 'io.example.app',
+        error: 'Access service unavailable',
+      });
+      expect(DeviceEventEmitter.emit).not.toHaveBeenCalledWith('yaverFeedback:startReport');
+    });
+
     it('lets a host ACL hide its affordance without opening auth UI', async () => {
       YaverFeedback.init({
         enabled: true,
@@ -121,6 +140,7 @@ describe('YaverFeedback', () => {
         appId: 'io.example.app',
         yaverAuthenticated: true,
         ownerAuthorized: false,
+        accountAuthorized: true,
         installationId: 'phone-1',
         deviceState: 'active',
         authorized: true,
@@ -137,6 +157,7 @@ describe('YaverFeedback', () => {
         appId: 'io.example.app',
         yaverAuthenticated: false,
         ownerAuthorized: false,
+        accountAuthorized: true,
         installationId: 'phone-1',
         deviceState: 'active',
         authorized: false,
@@ -155,6 +176,7 @@ describe('YaverFeedback', () => {
         appId: 'io.example.app',
         yaverAuthenticated: true,
         ownerAuthorized: false,
+        accountAuthorized: true,
         installationId: 'phone-1',
         deviceState: 'active',
         authorized: true,
@@ -163,6 +185,139 @@ describe('YaverFeedback', () => {
       expect((NativeModules as any).YaverHotReload.setDogfoodShortcut)
         .toHaveBeenCalledWith(false, 'Dogfood');
     });
+
+    it('keeps the Y visible until the authorized phone has completed onboarding', async () => {
+      YaverFeedback.init({ bundleId: 'io.example.app', dogfood: {} });
+      YaverFeedback.getConfig()!.dogfood!.controlGesture = true;
+      jest.spyOn(YaverFeedback, 'getDogfoodAccess').mockResolvedValueOnce({
+        appId: 'io.example.app',
+        yaverAuthenticated: true,
+        ownerAuthorized: false,
+        accountAuthorized: true,
+        installationId: 'phone-1',
+        deviceState: 'active',
+        authorized: true,
+      });
+      const state = await YaverFeedback.syncDogfoodControlGesture();
+      expect(state).toMatchObject({
+        onboardingSeen: false,
+        presentation: 'minimized-y',
+        gestureSupported: true,
+        gestureEnabled: false,
+        fallbackVisible: true,
+      });
+      expect((NativeModules as any).YaverDogfoodGesture.setEnabled).toHaveBeenCalledWith(false, 900);
+    });
+
+    it('uses the invisible three-finger hold only after onboarding selects it', async () => {
+      YaverFeedback.init({ bundleId: 'io.example.app', dogfood: {} });
+      YaverFeedback.getConfig()!.dogfood!.controlGesture = true;
+      jest.spyOn(YaverFeedback, 'getDogfoodAccess').mockResolvedValueOnce({
+        appId: 'io.example.app',
+        yaverAuthenticated: true,
+        ownerAuthorized: false,
+        accountAuthorized: true,
+        installationId: 'phone-1',
+        deviceState: 'active',
+        authorized: true,
+        controlPresentation: 'auto',
+        controlOnboardingSeen: true,
+      });
+      const state = await YaverFeedback.syncDogfoodControlGesture();
+      expect(state).toMatchObject({
+        onboardingSeen: true,
+        presentation: 'auto',
+        gestureSupported: true,
+        gestureEnabled: true,
+        fallbackVisible: false,
+      });
+      expect((NativeModules as any).YaverDogfoodGesture.setEnabled).toHaveBeenCalledWith(true, 900);
+    });
+
+    it('keeps the Y when native capability reports support but enabling the gesture fails', async () => {
+      YaverFeedback.init({ bundleId: 'io.example.app', dogfood: {} });
+      YaverFeedback.getConfig()!.dogfood!.controlGesture = true;
+      jest.spyOn(YaverFeedback, 'getDogfoodAccess').mockResolvedValueOnce({
+        appId: 'io.example.app',
+        yaverAuthenticated: true,
+        ownerAuthorized: false,
+        accountAuthorized: true,
+        installationId: 'phone-1',
+        deviceState: 'active',
+        authorized: true,
+        controlPresentation: 'auto',
+        controlOnboardingSeen: true,
+      });
+      (NativeModules as any).YaverDogfoodGesture.setEnabled.mockResolvedValueOnce({
+        supported: true,
+        enabled: false,
+        reason: 'supported',
+        platform: 'ios',
+      });
+      const state = await YaverFeedback.syncDogfoodControlGesture();
+      expect(state).toMatchObject({
+        gestureSupported: true,
+        gestureEnabled: false,
+        fallbackVisible: true,
+        reason: 'gesture-enable-failed',
+      });
+    });
+
+    it('persists first-run completion for the exact account app installation', async () => {
+      YaverFeedback.init({ authToken: 'owner-token', bundleId: 'io.example.app', dogfood: {} });
+      YaverFeedback.getConfig()!.dogfood!.controlGesture = true;
+      jest.spyOn(YaverFeedback, 'getDogfoodAccess').mockResolvedValueOnce({
+        appId: 'io.example.app',
+        yaverAuthenticated: true,
+        ownerAuthorized: true,
+        accountAuthorized: true,
+        installationId: 'phone-1',
+        deviceState: 'active',
+        authorized: true,
+        controlOnboardingSeen: false,
+      });
+      const state = await YaverFeedback.setDogfoodControlPresentation('minimized-y');
+      expect(state).toMatchObject({ onboardingSeen: true, presentation: 'minimized-y', fallbackVisible: true });
+      expect(setDogfoodControlPreference).toHaveBeenCalledWith(expect.objectContaining({
+        appId: 'io.example.app',
+        installationId: 'phone-1',
+        token: 'owner-token',
+        presentation: 'minimized-y',
+        controlOnboardingSeen: true,
+      }));
+    });
+
+    it('falls back to the minimized Y when accessibility owns multi-touch', async () => {
+      YaverFeedback.init({ bundleId: 'io.example.app', dogfood: {} });
+      YaverFeedback.getConfig()!.dogfood!.controlGesture = { durationMs: 1200 };
+      jest.spyOn(YaverFeedback, 'getDogfoodAccess').mockResolvedValueOnce({
+        appId: 'io.example.app',
+        yaverAuthenticated: true,
+        ownerAuthorized: false,
+        accountAuthorized: true,
+        installationId: 'phone-1',
+        deviceState: 'active',
+        authorized: true,
+      });
+      (NativeModules as any).YaverDogfoodGesture.getCapability.mockResolvedValueOnce({
+        supported: false,
+        enabled: false,
+        reason: 'accessibility-touch-exploration',
+        platform: 'ios',
+      });
+      const state = await YaverFeedback.syncDogfoodControlGesture();
+      expect(state).toMatchObject({ gestureSupported: false, gestureEnabled: false, fallbackVisible: true });
+      expect((NativeModules as any).YaverDogfoodGesture.setEnabled).toHaveBeenCalledWith(false, 1200);
+    });
+
+    it('suppresses guest controls inside the Yaver split-view container', async () => {
+      YaverFeedback.init({ bundleId: 'io.example.app', dogfood: {} });
+      YaverFeedback.getConfig()!.dogfood!.controlGesture = true;
+      (NativeModules as any).YaverInfo = { isYaver: true };
+      const state = await YaverFeedback.syncDogfoodControlGesture();
+      delete (NativeModules as any).YaverInfo;
+      expect(state).toMatchObject({ gestureEnabled: false, fallbackVisible: false, reason: 'yaver-host-owns-controls' });
+    });
   });
 
   describe('init()', () => {