yaver-feedback-react-native 0.7.17 → 0.8.0

package/dist/FeedbackModal.js

@@ -40,6 +40,7 @@ const YaverFeedback_1 = require("./YaverFeedback");
 const capture_1 = require("./capture");
 const upload_1 = require("./upload");
 const AuthOverlay_1 = require("./AuthOverlay");
+const QuickActionIcon_1 = require("./QuickActionIcon");
 const FeedbackModal = () => {
     const [visible, setVisible] = (0, react_1.useState)(false);
     const [action, setAction] = (0, react_1.useState)('idle');
@@ -52,6 +53,11 @@ const FeedbackModal = () => {
     // hidden button instead of a runtime error.
     const voiceSupported = (0, react_1.useRef)((0, capture_1.isVoiceCaptureSupported)()).current;
     const [lastVideo, setLastVideo] = (0, react_1.useState)(null);
+    // Tracks whether the user has hidden the QuickActionIcon via its
+    // long-press menu. Shake is always available, so the feedback modal
+    // is our guaranteed UI for bringing the icon back — we surface a
+    // small "Show quick icon" row when this is true.
+    const [quickIconHidden, setQuickIconHidden] = (0, react_1.useState)(false);
     // Vibing-input mode: same expand-on-tap pattern as email login.
     // Tap "Vibing" once → the button reveals an input + Send; that lets
     // the user say WHAT they want to vibe on instead of firing a canned
@@ -69,6 +75,15 @@ const FeedbackModal = () => {
                 setError(null);
                 setToast(null);
                 setAction('idle');
+                // Re-read the "user hid the quick icon" flag on every open so
+                // the re-enable row reflects the latest preference (the user
+                // might have hidden or shown it between opens).
+                YaverFeedback_1.YaverFeedback.isQuickIconHidden()
+                    .then((v) => {
+                    if (mountedRef.current)
+                        setQuickIconHidden(v);
+                })
+                    .catch(() => { });
             }
         });
         // Agent streams build / compile progress through the BlackBox
@@ -496,6 +511,7 @@ const FeedbackModal = () => {
     const busy = action !== 'idle';
     return (<>
       <AuthOverlay_1.AuthOverlay />
+      <QuickActionIcon_1.QuickActionIcon />
       {visible && (<react_native_1.Modal visible={visible} animationType="slide" transparent onRequestClose={handleClose}>
           <react_native_1.Pressable style={styles.overlay} onPress={handleClose}>
             <react_native_1.Pressable style={styles.modal} onPress={(e) => e.stopPropagation()}>
@@ -566,6 +582,27 @@ const FeedbackModal = () => {
                 </react_native_1.View>)}
               {toast && <react_native_1.Text style={styles.toast}>{toast}</react_native_1.Text>}
               {error && <react_native_1.Text style={styles.error}>{error}</react_native_1.Text>}
+
+              {/* Quick-icon toggle. The user's three ways to control
+                the floating icon are: (1) long-press the icon →
+                Hide, (2) tap this row to toggle it on/off, (3) shake
+                → this modal → tap this row. Shake is the unkillable
+                back-door when the icon is hidden and the dev hasn't
+                exposed their own settings UI. */}
+              <react_native_1.Pressable onPress={async () => {
+                const next = !quickIconHidden;
+                setQuickIconHidden(next);
+                await YaverFeedback_1.YaverFeedback.setQuickIconVisible(!next);
+            }} style={({ pressed }) => [
+                styles.quickIconToggle,
+                pressed && { opacity: 0.7 },
+            ]} accessibilityRole="button" accessibilityLabel={quickIconHidden ? 'Show quick icon' : 'Hide quick icon'}>
+                <react_native_1.Text style={styles.quickIconToggleText}>
+                  {quickIconHidden
+                ? '◯  Show quick-access icon'
+                : '●  Hide quick-access icon'}
+                </react_native_1.Text>
+              </react_native_1.Pressable>
             </react_native_1.Pressable>
           </react_native_1.Pressable>
         </react_native_1.Modal>)}
@@ -710,4 +747,15 @@ const styles = react_native_1.StyleSheet.create({
         textAlign: 'center',
         marginTop: 4,
     },
+    quickIconToggle: {
+        marginTop: 4,
+        alignSelf: 'center',
+        paddingVertical: 6,
+        paddingHorizontal: 12,
+    },
+    quickIconToggleText: {
+        color: '#9ca3af',
+        fontSize: 12,
+        fontWeight: '500',
+    },
 });

package/dist/QuickActionIcon.d.ts

@@ -0,0 +1,35 @@
+import React from 'react';
+export interface QuickActionIconProps {
+    /** Override the color from FeedbackConfig.quickIconColor. */
+    color?: string;
+    /** Override the initial position from FeedbackConfig.quickIconInitialPosition. */
+    initialPosition?: {
+        x: number;
+        y: number;
+    };
+    /** Override the icon diameter. Default 44. */
+    size?: number;
+}
+/**
+ * Small tap-to-open icon for the Yaver Feedback SDK.
+ *
+ * Default UX:
+ *  - **Tap** opens the feedback modal (same as shake).
+ *  - **Long-press** (~550ms) opens a menu with "Open feedback" and
+ *    "Hide icon". Hiding is persisted to AsyncStorage so the user's
+ *    decision survives app relaunches.
+ *  - **Drag** repositions the icon.
+ *
+ * Shake always keeps working independently — even when the icon is
+ * hidden the user can still shake to open feedback.
+ *
+ * Visibility is controlled by `FeedbackConfig.quickIcon`:
+ *  - `'auto'` (default) → `'always'` on iOS/Android, `'off'` on web.
+ *  - `'always'` → visible from first render.
+ *  - `'after-shake'` → hidden until `yaverFeedback:firstShake` fires.
+ *  - `'off'` → never rendered.
+ *
+ * Suppressed entirely when the SDK is loaded inside Yaver's super-host
+ * (the Yaver mobile app owns the shake gesture + overlay in that case).
+ */
+export declare const QuickActionIcon: React.FC<QuickActionIconProps>;

package/dist/QuickActionIcon.js

@@ -0,0 +1,299 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuickActionIcon = void 0;
+const react_1 = __importStar(require("react"));
+const react_native_1 = require("react-native");
+const YaverFeedback_1 = require("./YaverFeedback");
+const preferences_1 = require("./preferences");
+// Mirror the suppression rule used by YaverFeedback + ShakeDetector:
+// when loaded through Yaver's super-host Hermes bundle, the host owns
+// shake + reload UX. We must not render a second action surface.
+function isRunningInsideYaverHost() {
+    try {
+        return !!react_native_1.NativeModules?.YaverInfo;
+    }
+    catch {
+        return false;
+    }
+}
+const DEFAULT_SIZE = 44;
+const DEFAULT_COLOR = '#6366f1';
+const LONG_PRESS_MS = 550;
+/**
+ * Small tap-to-open icon for the Yaver Feedback SDK.
+ *
+ * Default UX:
+ *  - **Tap** opens the feedback modal (same as shake).
+ *  - **Long-press** (~550ms) opens a menu with "Open feedback" and
+ *    "Hide icon". Hiding is persisted to AsyncStorage so the user's
+ *    decision survives app relaunches.
+ *  - **Drag** repositions the icon.
+ *
+ * Shake always keeps working independently — even when the icon is
+ * hidden the user can still shake to open feedback.
+ *
+ * Visibility is controlled by `FeedbackConfig.quickIcon`:
+ *  - `'auto'` (default) → `'always'` on iOS/Android, `'off'` on web.
+ *  - `'always'` → visible from first render.
+ *  - `'after-shake'` → hidden until `yaverFeedback:firstShake` fires.
+ *  - `'off'` → never rendered.
+ *
+ * Suppressed entirely when the SDK is loaded inside Yaver's super-host
+ * (the Yaver mobile app owns the shake gesture + overlay in that case).
+ */
+const QuickActionIcon = ({ color: colorProp, initialPosition: initialPositionProp, size = DEFAULT_SIZE, }) => {
+    const config = YaverFeedback_1.YaverFeedback.getConfig();
+    const mode = (() => {
+        const raw = config?.quickIcon ?? 'auto';
+        if (raw === 'auto') {
+            return react_native_1.Platform.OS === 'web' ? 'off' : 'always';
+        }
+        return raw;
+    })();
+    const color = colorProp ?? config?.quickIconColor ?? DEFAULT_COLOR;
+    const { width, height } = react_native_1.Dimensions.get('window');
+    const defaultStart = initialPositionProp ??
+        config?.quickIconInitialPosition ?? {
+        x: Math.max(width - size - 14, 0),
+        y: Math.max(Math.floor(height * 0.35), 80),
+    };
+    const pan = (0, react_1.useRef)(new react_native_1.Animated.ValueXY(defaultStart)).current;
+    const lastPos = (0, react_1.useRef)(defaultStart);
+    const dragStart = (0, react_1.useRef)(null);
+    const didDrag = (0, react_1.useRef)(false);
+    const [userDisabled, setUserDisabled] = (0, react_1.useState)(null);
+    const [shakenThisSession, setShakenThisSession] = (0, react_1.useState)(false);
+    const [menuOpen, setMenuOpen] = (0, react_1.useState)(false);
+    const [hostSuppressed] = (0, react_1.useState)(() => isRunningInsideYaverHost());
+    // Load the persisted disable flag once on mount. Until it resolves we
+    // render nothing — a one-frame flash of the icon before hiding would
+    // be worse than a tiny delayed appearance.
+    (0, react_1.useEffect)(() => {
+        let alive = true;
+        (0, preferences_1.getQuickIconDisabled)().then((v) => {
+            if (alive)
+                setUserDisabled(v);
+        });
+        return () => {
+            alive = false;
+        };
+    }, []);
+    // `after-shake` mode waits for the first shake before revealing
+    // itself. YaverFeedback emits this event from its shake callback.
+    (0, react_1.useEffect)(() => {
+        const sub = react_native_1.DeviceEventEmitter.addListener('yaverFeedback:firstShake', () => setShakenThisSession(true));
+        return () => sub.remove();
+    }, []);
+    // Programmatic control: host apps can call
+    // `YaverFeedback.setQuickIconVisible(true)` to re-surface the icon
+    // after the user hid it (e.g. from a settings screen).
+    (0, react_1.useEffect)(() => {
+        const showSub = react_native_1.DeviceEventEmitter.addListener('yaverFeedback:quickIconShow', () => {
+            setUserDisabled(false);
+            void (0, preferences_1.setQuickIconDisabled)(false);
+        });
+        const hideSub = react_native_1.DeviceEventEmitter.addListener('yaverFeedback:quickIconHide', () => {
+            setUserDisabled(true);
+            void (0, preferences_1.setQuickIconDisabled)(true);
+            setMenuOpen(false);
+        });
+        return () => {
+            showSub.remove();
+            hideSub.remove();
+        };
+    }, []);
+    const panResponder = (0, react_1.useRef)(react_native_1.PanResponder.create({
+        onStartShouldSetPanResponder: () => true,
+        onMoveShouldSetPanResponder: (_, g) => Math.abs(g.dx) > 3 || Math.abs(g.dy) > 3,
+        onPanResponderGrant: () => {
+            didDrag.current = false;
+            dragStart.current = { ...lastPos.current };
+            pan.setOffset({ x: lastPos.current.x, y: lastPos.current.y });
+            pan.setValue({ x: 0, y: 0 });
+        },
+        onPanResponderMove: (_, g) => {
+            if (Math.abs(g.dx) > 3 || Math.abs(g.dy) > 3) {
+                didDrag.current = true;
+            }
+            react_native_1.Animated.event([null, { dx: pan.x, dy: pan.y }], {
+                useNativeDriver: false,
+            })(_, g);
+        },
+        onPanResponderRelease: (_, g) => {
+            pan.flattenOffset();
+            const start = dragStart.current ?? lastPos.current;
+            const maxX = Math.max(width - size, 0);
+            const maxY = Math.max(height - size, 0);
+            const nextX = Math.max(0, Math.min(maxX, start.x + g.dx));
+            const nextY = Math.max(0, Math.min(maxY, start.y + g.dy));
+            lastPos.current = { x: nextX, y: nextY };
+            react_native_1.Animated.spring(pan, {
+                toValue: { x: nextX, y: nextY },
+                useNativeDriver: false,
+                friction: 7,
+            }).start();
+        },
+    })).current;
+    const openFeedback = (0, react_1.useCallback)(() => {
+        setMenuOpen(false);
+        void YaverFeedback_1.YaverFeedback.startReport();
+    }, []);
+    const hideForever = (0, react_1.useCallback)(() => {
+        setMenuOpen(false);
+        setUserDisabled(true);
+        void (0, preferences_1.setQuickIconDisabled)(true);
+    }, []);
+    if (hostSuppressed)
+        return null;
+    if (mode === 'off')
+        return null;
+    if (userDisabled === null)
+        return null;
+    if (userDisabled)
+        return null;
+    if (mode === 'after-shake' && !shakenThisSession)
+        return null;
+    if (!YaverFeedback_1.YaverFeedback.isEnabled())
+        return null;
+    const visualSize = size;
+    const radius = visualSize / 2;
+    return (<react_native_1.Animated.View pointerEvents="box-none" style={[
+            react_native_1.StyleSheet.absoluteFill,
+            { zIndex: 9998 },
+        ]}>
+      <react_native_1.Animated.View {...panResponder.panHandlers} style={[
+            styles.container,
+            {
+                transform: [{ translateX: pan.x }, { translateY: pan.y }],
+            },
+        ]}>
+        <react_native_1.Pressable onPress={() => {
+            if (didDrag.current) {
+                didDrag.current = false;
+                return;
+            }
+            openFeedback();
+        }} onLongPress={() => {
+            if (didDrag.current)
+                return;
+            setMenuOpen((m) => !m);
+        }} delayLongPress={LONG_PRESS_MS} hitSlop={6} accessibilityRole="button" accessibilityLabel="Open Yaver feedback" style={({ pressed }) => [
+            styles.icon,
+            {
+                width: visualSize,
+                height: visualSize,
+                borderRadius: radius,
+                backgroundColor: color,
+                opacity: pressed ? 0.85 : 1,
+            },
+        ]}>
+          <react_native_1.Text style={[styles.iconLabel, { fontSize: Math.round(visualSize * 0.5) }]}>y</react_native_1.Text>
+        </react_native_1.Pressable>
+        {menuOpen ? (<react_native_1.View style={styles.menu}>
+            <react_native_1.Pressable onPress={openFeedback} style={({ pressed }) => [
+                styles.menuItem,
+                pressed && styles.menuItemPressed,
+            ]}>
+              <react_native_1.Text style={styles.menuItemText}>Open feedback</react_native_1.Text>
+            </react_native_1.Pressable>
+            <react_native_1.View style={styles.menuDivider}/>
+            <react_native_1.Pressable onPress={hideForever} style={({ pressed }) => [
+                styles.menuItem,
+                pressed && styles.menuItemPressed,
+            ]}>
+              <react_native_1.Text style={[styles.menuItemText, styles.menuItemDanger]}>
+                Hide icon
+              </react_native_1.Text>
+            </react_native_1.Pressable>
+          </react_native_1.View>) : null}
+      </react_native_1.Animated.View>
+    </react_native_1.Animated.View>);
+};
+exports.QuickActionIcon = QuickActionIcon;
+const styles = react_native_1.StyleSheet.create({
+    container: {
+        position: 'absolute',
+        top: 0,
+        left: 0,
+        alignItems: 'flex-start',
+    },
+    icon: {
+        alignItems: 'center',
+        justifyContent: 'center',
+        shadowColor: '#000',
+        shadowOffset: { width: 0, height: 2 },
+        shadowOpacity: 0.25,
+        shadowRadius: 4,
+        elevation: 4,
+    },
+    iconLabel: {
+        color: '#ffffff',
+        fontWeight: '700',
+        includeFontPadding: false,
+    },
+    menu: {
+        marginTop: 6,
+        minWidth: 150,
+        backgroundColor: '#1f1f23',
+        borderRadius: 10,
+        paddingVertical: 4,
+        shadowColor: '#000',
+        shadowOffset: { width: 0, height: 2 },
+        shadowOpacity: 0.3,
+        shadowRadius: 6,
+        elevation: 6,
+    },
+    menuItem: {
+        paddingHorizontal: 14,
+        paddingVertical: 10,
+    },
+    menuItemPressed: {
+        backgroundColor: '#2a2a30',
+    },
+    menuItemText: {
+        color: '#f4f4f5',
+        fontSize: 14,
+        fontWeight: '500',
+    },
+    menuItemDanger: {
+        color: '#f97316',
+    },
+    menuDivider: {
+        height: react_native_1.StyleSheet.hairlineWidth,
+        backgroundColor: '#3f3f46',
+        marginHorizontal: 8,
+    },
+});

package/dist/YaverFeedback.d.ts

@@ -199,6 +199,32 @@ export declare class YaverFeedback {
      * 3. DevSettings.reload() (Metro dev server fallback)
      */
     private static loadBundleAndReload;
+    /**
+     * Internal: fired from every shake path (dev-menu + accelerometer)
+     * before the feedback modal opens. Emits `yaverFeedback:firstShake`
+     * exactly once per process so QuickActionIcon's `'after-shake'` mode
+     * can surface itself on first shake and stay visible for the rest of
+     * the session.
+     */
+    static notifyShake(): void;
+    /**
+     * Show / hide the QuickActionIcon programmatically and persist the
+     * choice across launches. Host apps can call this from a settings
+     * screen so the user has a second way to re-enable the icon after
+     * hiding it via the icon's own long-press menu — shake is always the
+     * third back-door because it never depends on a visible control.
+     */
+    static setQuickIconVisible(visible: boolean): Promise<void>;
+    /**
+     * Returns `true` when the user has chosen to hide the QuickActionIcon
+     * (via its long-press menu or `setQuickIconVisible(false)`).
+     * FeedbackModal uses this to surface a one-tap "Show quick icon"
+     * control so the user can bring the icon back without having to know
+     * about the programmatic API.
+     */
+    static isQuickIconHidden(): Promise<boolean>;
+    /** Clear the persisted "user hid the icon" flag. */
+    static resetQuickIconPreference(): Promise<void>;
     /** Tear down the SDK (stop shake detector, clear state). */
     static destroy(): void;
 }

package/dist/YaverFeedback.js

@@ -7,6 +7,7 @@ const BlackBox_1 = require("./BlackBox");
 const P2PClient_1 = require("./P2PClient");
 const ShakeDetector_1 = require("./ShakeDetector");
 const auth_1 = require("./auth");
+const preferences_1 = require("./preferences");
 // Is this JS runtime the Yaver mobile app's super-host bridge? The
 // YaverInfo native module is only registered inside Yaver's container
 // (mobile/ios/Yaver/YaverInfo.{swift,m} + Android counterpart); a
@@ -38,6 +39,13 @@ let errorBuffer = [];
 let maxErrors = 5;
 /** Track whether BlackBox was running before disable (to restart on enable). */
 let blackBoxWasStreaming = false;
+/**
+ * Tracks whether the user has already shaken once in this process.
+ * Consumed by QuickActionIcon's `'after-shake'` mode so the icon
+ * appears the first time a user discovers shake and stays around
+ * thereafter.
+ */
+let firstShakeFired = false;
 /**
  * Flag evaluation cache — 30s TTL per `userId|key`. Prevents a
  * tight render loop from hammering /flags/eval when the dev calls
@@ -118,6 +126,7 @@ class YaverFeedback {
         if (enabled && config.trigger === 'shake') {
             shakeDetector = new ShakeDetector_1.ShakeDetector();
             shakeDetector.start(() => {
+                YaverFeedback.notifyShake();
                 if (config?.reportingOnly) {
                     YaverFeedback.sendAutoReport();
                 }
@@ -450,6 +459,7 @@ class YaverFeedback {
             if (config?.trigger === 'shake' && !shakeDetector) {
                 shakeDetector = new ShakeDetector_1.ShakeDetector();
                 shakeDetector.start(() => {
+                    YaverFeedback.notifyShake();
                     if (config?.reportingOnly) {
                         YaverFeedback.sendAutoReport();
                     }
@@ -752,6 +762,56 @@ class YaverFeedback {
             // Not in dev mode
         }
     }
+    /**
+     * Internal: fired from every shake path (dev-menu + accelerometer)
+     * before the feedback modal opens. Emits `yaverFeedback:firstShake`
+     * exactly once per process so QuickActionIcon's `'after-shake'` mode
+     * can surface itself on first shake and stay visible for the rest of
+     * the session.
+     */
+    static notifyShake() {
+        if (firstShakeFired)
+            return;
+        firstShakeFired = true;
+        try {
+            const { DeviceEventEmitter } = require('react-native');
+            DeviceEventEmitter.emit('yaverFeedback:firstShake');
+        }
+        catch {
+            // emitter unavailable (e.g. jsdom unit test) — safe to ignore
+        }
+    }
+    /**
+     * Show / hide the QuickActionIcon programmatically and persist the
+     * choice across launches. Host apps can call this from a settings
+     * screen so the user has a second way to re-enable the icon after
+     * hiding it via the icon's own long-press menu — shake is always the
+     * third back-door because it never depends on a visible control.
+     */
+    static async setQuickIconVisible(visible) {
+        await (0, preferences_1.setQuickIconDisabled)(!visible);
+        try {
+            const { DeviceEventEmitter } = require('react-native');
+            DeviceEventEmitter.emit(visible ? 'yaverFeedback:quickIconShow' : 'yaverFeedback:quickIconHide');
+        }
+        catch {
+            // emitter unavailable — preference is still persisted
+        }
+    }
+    /**
+     * Returns `true` when the user has chosen to hide the QuickActionIcon
+     * (via its long-press menu or `setQuickIconVisible(false)`).
+     * FeedbackModal uses this to surface a one-tap "Show quick icon"
+     * control so the user can bring the icon back without having to know
+     * about the programmatic API.
+     */
+    static async isQuickIconHidden() {
+        return (0, preferences_1.getQuickIconDisabled)();
+    }
+    /** Clear the persisted "user hid the icon" flag. */
+    static async resetQuickIconPreference() {
+        await YaverFeedback.setQuickIconVisible(true);
+    }
     /** Tear down the SDK (stop shake detector, clear state). */
     static destroy() {
         if (shakeDetector) {

package/dist/index.d.ts

@@ -44,7 +44,10 @@ export { AuthOverlay } from './AuthOverlay';
 export { ShakeDetector } from './ShakeDetector';
 export { FloatingButton } from './FloatingButton';
 export { FeedbackModal } from './FeedbackModal';
+export { QuickActionIcon } from './QuickActionIcon';
+export type { QuickActionIconProps } from './QuickActionIcon';
 export { FixReport } from './FixReport';
+export { getQuickIconDisabled, setQuickIconDisabled, clearQuickIconDisabled, } from './preferences';
 export { configureAuthEndpoints, getConvexSiteUrl, getWebBaseUrl, getToken, saveToken, clearToken, getUser, saveUser, getSelectedDeviceId, saveSelectedDeviceId, clearSelectedDeviceId, validateToken, signInWithApple, signInWithOAuth, signupWithEmail, loginWithEmail, listReachableDevices, DEFAULT_CONVEX_SITE_URL, DEFAULT_WEB_BASE_URL, DEFAULT_OAUTH_REDIRECT, } from './auth';
 export type { OAuthProvider, User, RemoteDevice, DeviceList, } from './auth';
 export { captureScreenshot, startVideoRecording, stopVideoRecording, isVideoRecording, } from './capture';

package/dist/index.js

@@ -28,7 +28,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.uploadFeedback = exports.isVideoRecording = exports.stopVideoRecording = exports.startVideoRecording = exports.captureScreenshot = exports.DEFAULT_OAUTH_REDIRECT = exports.DEFAULT_WEB_BASE_URL = exports.DEFAULT_CONVEX_SITE_URL = exports.listReachableDevices = exports.loginWithEmail = exports.signupWithEmail = exports.signInWithOAuth = exports.signInWithApple = exports.validateToken = exports.clearSelectedDeviceId = exports.saveSelectedDeviceId = exports.getSelectedDeviceId = exports.saveUser = exports.getUser = exports.clearToken = exports.saveToken = exports.getToken = exports.getWebBaseUrl = exports.getConvexSiteUrl = exports.configureAuthEndpoints = exports.FixReport = exports.FeedbackModal = exports.FloatingButton = exports.ShakeDetector = exports.AuthOverlay = exports.PairDeviceModal = exports.YaverMachinePickerScreen = exports.YaverLoginScreen = exports.YaverConnectionScreen = exports.P2PClient = exports.YaverDiscovery = exports.initExpo = exports.YaverUpdates = exports.BlackBox = exports.YaverFeedback = void 0;
+exports.uploadFeedback = exports.isVideoRecording = exports.stopVideoRecording = exports.startVideoRecording = exports.captureScreenshot = exports.DEFAULT_OAUTH_REDIRECT = exports.DEFAULT_WEB_BASE_URL = exports.DEFAULT_CONVEX_SITE_URL = exports.listReachableDevices = exports.loginWithEmail = exports.signupWithEmail = exports.signInWithOAuth = exports.signInWithApple = exports.validateToken = exports.clearSelectedDeviceId = exports.saveSelectedDeviceId = exports.getSelectedDeviceId = exports.saveUser = exports.getUser = exports.clearToken = exports.saveToken = exports.getToken = exports.getWebBaseUrl = exports.getConvexSiteUrl = exports.configureAuthEndpoints = exports.clearQuickIconDisabled = exports.setQuickIconDisabled = exports.getQuickIconDisabled = exports.FixReport = exports.QuickActionIcon = exports.FeedbackModal = exports.FloatingButton = exports.ShakeDetector = exports.AuthOverlay = exports.PairDeviceModal = exports.YaverMachinePickerScreen = exports.YaverLoginScreen = exports.YaverConnectionScreen = exports.P2PClient = exports.YaverDiscovery = exports.initExpo = exports.YaverUpdates = exports.BlackBox = exports.YaverFeedback = void 0;
 var YaverFeedback_1 = require("./YaverFeedback");
 Object.defineProperty(exports, "YaverFeedback", { enumerable: true, get: function () { return YaverFeedback_1.YaverFeedback; } });
 var BlackBox_1 = require("./BlackBox");
@@ -57,8 +57,14 @@ var FloatingButton_1 = require("./FloatingButton");
 Object.defineProperty(exports, "FloatingButton", { enumerable: true, get: function () { return FloatingButton_1.FloatingButton; } });
 var FeedbackModal_1 = require("./FeedbackModal");
 Object.defineProperty(exports, "FeedbackModal", { enumerable: true, get: function () { return FeedbackModal_1.FeedbackModal; } });
+var QuickActionIcon_1 = require("./QuickActionIcon");
+Object.defineProperty(exports, "QuickActionIcon", { enumerable: true, get: function () { return QuickActionIcon_1.QuickActionIcon; } });
 var FixReport_1 = require("./FixReport");
 Object.defineProperty(exports, "FixReport", { enumerable: true, get: function () { return FixReport_1.FixReport; } });
+var preferences_1 = require("./preferences");
+Object.defineProperty(exports, "getQuickIconDisabled", { enumerable: true, get: function () { return preferences_1.getQuickIconDisabled; } });
+Object.defineProperty(exports, "setQuickIconDisabled", { enumerable: true, get: function () { return preferences_1.setQuickIconDisabled; } });
+Object.defineProperty(exports, "clearQuickIconDisabled", { enumerable: true, get: function () { return preferences_1.clearQuickIconDisabled; } });
 var auth_1 = require("./auth");
 Object.defineProperty(exports, "configureAuthEndpoints", { enumerable: true, get: function () { return auth_1.configureAuthEndpoints; } });
 Object.defineProperty(exports, "getConvexSiteUrl", { enumerable: true, get: function () { return auth_1.getConvexSiteUrl; } });

package/dist/preferences.d.ts

@@ -0,0 +1,18 @@
+/**
+ * SDK user preferences persisted across launches.
+ *
+ * Currently only the quick-action icon's user-level dismiss flag
+ * lives here: the dev enables the icon via `FeedbackConfig.quickIcon`,
+ * but the *user* can long-press → Hide to opt out, and we remember
+ * that choice across launches so their next app session still
+ * respects it.
+ *
+ * AsyncStorage is an optional peer dep — if it's not installed the
+ * getters return `false` and the setters silently no-op, so the icon
+ * still works (it just can't remember the disable beyond the
+ * in-memory session).
+ */
+/** True if the user has long-pressed the icon and chosen "Hide". */
+export declare function getQuickIconDisabled(): Promise<boolean>;
+export declare function setQuickIconDisabled(disabled: boolean): Promise<void>;
+export declare function clearQuickIconDisabled(): Promise<void>;

package/dist/preferences.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * SDK user preferences persisted across launches.
+ *
+ * Currently only the quick-action icon's user-level dismiss flag
+ * lives here: the dev enables the icon via `FeedbackConfig.quickIcon`,
+ * but the *user* can long-press → Hide to opt out, and we remember
+ * that choice across launches so their next app session still
+ * respects it.
+ *
+ * AsyncStorage is an optional peer dep — if it's not installed the
+ * getters return `false` and the setters silently no-op, so the icon
+ * still works (it just can't remember the disable beyond the
+ * in-memory session).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getQuickIconDisabled = getQuickIconDisabled;
+exports.setQuickIconDisabled = setQuickIconDisabled;
+exports.clearQuickIconDisabled = clearQuickIconDisabled;
+let AsyncStorage = null;
+try {
+    AsyncStorage = require('@react-native-async-storage/async-storage').default;
+}
+catch {
+    // not installed — degrade gracefully
+}
+const QUICK_ICON_DISABLED_KEY = 'yaver_feedback_quickicon_disabled';
+/** True if the user has long-pressed the icon and chosen "Hide". */
+async function getQuickIconDisabled() {
+    if (!AsyncStorage)
+        return false;
+    try {
+        const v = await AsyncStorage.getItem(QUICK_ICON_DISABLED_KEY);
+        return v === '1';
+    }
+    catch {
+        return false;
+    }
+}
+async function setQuickIconDisabled(disabled) {
+    if (!AsyncStorage)
+        return;
+    try {
+        if (disabled) {
+            await AsyncStorage.setItem(QUICK_ICON_DISABLED_KEY, '1');
+        }
+        else {
+            await AsyncStorage.removeItem(QUICK_ICON_DISABLED_KEY);
+        }
+    }
+    catch {
+        // best-effort
+    }
+}
+async function clearQuickIconDisabled() {
+    await setQuickIconDisabled(false);
+}

package/dist/types.d.ts

@@ -42,6 +42,37 @@ export interface FeedbackConfig {
     preferredDeviceId?: string;
     /** How feedback collection is triggered */
     trigger?: 'shake' | 'floating-button' | 'manual';
+    /**
+     * Small tap-to-open icon that floats above the app so the user
+     * doesn't have to shake every time they want to open feedback.
+     * Single tap → open the feedback modal; long-press → menu with
+     * "Hide icon" (persisted across launches via AsyncStorage).
+     *
+     * - `'auto'` (default) → `'always'` on iOS/Android, `'off'` on web.
+     * - `'always'` → visible from app launch.
+     * - `'after-shake'` → hidden until the first shake this session.
+     * - `'off'` → never rendered. Shake still works.
+     *
+     * The user can always override `'always'` / `'auto'` by long-pressing
+     * → Hide. Devs can clear that override via
+     * `YaverFeedback.resetQuickIconPreference()`.
+     */
+    quickIcon?: 'auto' | 'always' | 'after-shake' | 'off';
+    /**
+     * Background color for the quick-action icon. Default: '#6366f1'
+     * (indigo). Pick something distinctive so the icon never visually
+     * collides with your own FAB.
+     */
+    quickIconColor?: string;
+    /**
+     * Initial position of the quick-action icon, in pixels from the
+     * top-left. Default: near the top-right corner of the screen. The
+     * icon is draggable at runtime — this is only the first mount.
+     */
+    quickIconInitialPosition?: {
+        x: number;
+        y: number;
+    };
     /** Enable/disable the SDK. Defaults to __DEV__ */
     enabled?: boolean;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yaver-feedback-react-native",
-  "version": "0.7.17",
+  "version": "0.8.0",
   "description": "Visual feedback SDK for Yaver — bug reports, screen recording, voice annotations, and local-first developer workflows",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/FeedbackModal.tsx

@@ -22,6 +22,7 @@ import {
 import { uploadFeedback } from './upload';
 import { DeviceInfo, FeedbackBundle } from './types';
 import { AuthOverlay } from './AuthOverlay';
+import { QuickActionIcon } from './QuickActionIcon';
 
 /**
  * Simplified feedback modal — 5 actions:
@@ -66,6 +67,11 @@ export const FeedbackModal: React.FC = () => {
   // hidden button instead of a runtime error.
   const voiceSupported = useRef<boolean>(isVoiceCaptureSupported()).current;
   const [lastVideo, setLastVideo] = useState<LastVideo | null>(null);
+  // Tracks whether the user has hidden the QuickActionIcon via its
+  // long-press menu. Shake is always available, so the feedback modal
+  // is our guaranteed UI for bringing the icon back — we surface a
+  // small "Show quick icon" row when this is true.
+  const [quickIconHidden, setQuickIconHidden] = useState(false);
   // Vibing-input mode: same expand-on-tap pattern as email login.
   // Tap "Vibing" once → the button reveals an input + Send; that lets
   // the user say WHAT they want to vibe on instead of firing a canned
@@ -84,6 +90,14 @@ export const FeedbackModal: React.FC = () => {
         setError(null);
         setToast(null);
         setAction('idle');
+        // Re-read the "user hid the quick icon" flag on every open so
+        // the re-enable row reflects the latest preference (the user
+        // might have hidden or shown it between opens).
+        YaverFeedback.isQuickIconHidden()
+          .then((v) => {
+            if (mountedRef.current) setQuickIconHidden(v);
+          })
+          .catch(() => {});
       }
     });
     // Agent streams build / compile progress through the BlackBox
@@ -517,6 +531,7 @@ export const FeedbackModal: React.FC = () => {
   return (
     <>
       <AuthOverlay />
+      <QuickActionIcon />
       {visible && (
         <Modal
           visible={visible}
@@ -676,6 +691,34 @@ export const FeedbackModal: React.FC = () => {
               )}
               {toast && <Text style={styles.toast}>{toast}</Text>}
               {error && <Text style={styles.error}>{error}</Text>}
+
+              {/* Quick-icon toggle. The user's three ways to control
+                  the floating icon are: (1) long-press the icon →
+                  Hide, (2) tap this row to toggle it on/off, (3) shake
+                  → this modal → tap this row. Shake is the unkillable
+                  back-door when the icon is hidden and the dev hasn't
+                  exposed their own settings UI. */}
+              <Pressable
+                onPress={async () => {
+                  const next = !quickIconHidden;
+                  setQuickIconHidden(next);
+                  await YaverFeedback.setQuickIconVisible(!next);
+                }}
+                style={({ pressed }) => [
+                  styles.quickIconToggle,
+                  pressed && { opacity: 0.7 },
+                ]}
+                accessibilityRole="button"
+                accessibilityLabel={
+                  quickIconHidden ? 'Show quick icon' : 'Hide quick icon'
+                }
+              >
+                <Text style={styles.quickIconToggleText}>
+                  {quickIconHidden
+                    ? '◯  Show quick-access icon'
+                    : '●  Hide quick-access icon'}
+                </Text>
+              </Pressable>
             </Pressable>
           </Pressable>
         </Modal>
@@ -849,4 +892,15 @@ const styles = StyleSheet.create({
     textAlign: 'center',
     marginTop: 4,
   },
+  quickIconToggle: {
+    marginTop: 4,
+    alignSelf: 'center',
+    paddingVertical: 6,
+    paddingHorizontal: 12,
+  },
+  quickIconToggleText: {
+    color: '#9ca3af',
+    fontSize: 12,
+    fontWeight: '500',
+  },
 });

package/src/QuickActionIcon.tsx

@@ -0,0 +1,332 @@
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import {
+  Animated,
+  DeviceEventEmitter,
+  Dimensions,
+  NativeModules,
+  PanResponder,
+  Platform,
+  Pressable,
+  StyleSheet,
+  Text,
+  View,
+} from 'react-native';
+import { YaverFeedback } from './YaverFeedback';
+import { getQuickIconDisabled, setQuickIconDisabled } from './preferences';
+
+// Mirror the suppression rule used by YaverFeedback + ShakeDetector:
+// when loaded through Yaver's super-host Hermes bundle, the host owns
+// shake + reload UX. We must not render a second action surface.
+function isRunningInsideYaverHost(): boolean {
+  try {
+    return !!(NativeModules as any)?.YaverInfo;
+  } catch {
+    return false;
+  }
+}
+
+const DEFAULT_SIZE = 44;
+const DEFAULT_COLOR = '#6366f1';
+const LONG_PRESS_MS = 550;
+
+export interface QuickActionIconProps {
+  /** Override the color from FeedbackConfig.quickIconColor. */
+  color?: string;
+  /** Override the initial position from FeedbackConfig.quickIconInitialPosition. */
+  initialPosition?: { x: number; y: number };
+  /** Override the icon diameter. Default 44. */
+  size?: number;
+}
+
+/**
+ * Small tap-to-open icon for the Yaver Feedback SDK.
+ *
+ * Default UX:
+ *  - **Tap** opens the feedback modal (same as shake).
+ *  - **Long-press** (~550ms) opens a menu with "Open feedback" and
+ *    "Hide icon". Hiding is persisted to AsyncStorage so the user's
+ *    decision survives app relaunches.
+ *  - **Drag** repositions the icon.
+ *
+ * Shake always keeps working independently — even when the icon is
+ * hidden the user can still shake to open feedback.
+ *
+ * Visibility is controlled by `FeedbackConfig.quickIcon`:
+ *  - `'auto'` (default) → `'always'` on iOS/Android, `'off'` on web.
+ *  - `'always'` → visible from first render.
+ *  - `'after-shake'` → hidden until `yaverFeedback:firstShake` fires.
+ *  - `'off'` → never rendered.
+ *
+ * Suppressed entirely when the SDK is loaded inside Yaver's super-host
+ * (the Yaver mobile app owns the shake gesture + overlay in that case).
+ */
+export const QuickActionIcon: React.FC<QuickActionIconProps> = ({
+  color: colorProp,
+  initialPosition: initialPositionProp,
+  size = DEFAULT_SIZE,
+}) => {
+  const config = YaverFeedback.getConfig();
+
+  const mode: 'always' | 'after-shake' | 'off' = (() => {
+    const raw = config?.quickIcon ?? 'auto';
+    if (raw === 'auto') {
+      return Platform.OS === 'web' ? 'off' : 'always';
+    }
+    return raw;
+  })();
+
+  const color = colorProp ?? config?.quickIconColor ?? DEFAULT_COLOR;
+
+  const { width, height } = Dimensions.get('window');
+  const defaultStart =
+    initialPositionProp ??
+    config?.quickIconInitialPosition ?? {
+      x: Math.max(width - size - 14, 0),
+      y: Math.max(Math.floor(height * 0.35), 80),
+    };
+
+  const pan = useRef(new Animated.ValueXY(defaultStart)).current;
+  const lastPos = useRef(defaultStart);
+  const dragStart = useRef<{ x: number; y: number } | null>(null);
+  const didDrag = useRef(false);
+
+  const [userDisabled, setUserDisabled] = useState<boolean | null>(null);
+  const [shakenThisSession, setShakenThisSession] = useState(false);
+  const [menuOpen, setMenuOpen] = useState(false);
+  const [hostSuppressed] = useState<boolean>(() => isRunningInsideYaverHost());
+
+  // Load the persisted disable flag once on mount. Until it resolves we
+  // render nothing — a one-frame flash of the icon before hiding would
+  // be worse than a tiny delayed appearance.
+  useEffect(() => {
+    let alive = true;
+    getQuickIconDisabled().then((v) => {
+      if (alive) setUserDisabled(v);
+    });
+    return () => {
+      alive = false;
+    };
+  }, []);
+
+  // `after-shake` mode waits for the first shake before revealing
+  // itself. YaverFeedback emits this event from its shake callback.
+  useEffect(() => {
+    const sub = DeviceEventEmitter.addListener(
+      'yaverFeedback:firstShake',
+      () => setShakenThisSession(true),
+    );
+    return () => sub.remove();
+  }, []);
+
+  // Programmatic control: host apps can call
+  // `YaverFeedback.setQuickIconVisible(true)` to re-surface the icon
+  // after the user hid it (e.g. from a settings screen).
+  useEffect(() => {
+    const showSub = DeviceEventEmitter.addListener(
+      'yaverFeedback:quickIconShow',
+      () => {
+        setUserDisabled(false);
+        void setQuickIconDisabled(false);
+      },
+    );
+    const hideSub = DeviceEventEmitter.addListener(
+      'yaverFeedback:quickIconHide',
+      () => {
+        setUserDisabled(true);
+        void setQuickIconDisabled(true);
+        setMenuOpen(false);
+      },
+    );
+    return () => {
+      showSub.remove();
+      hideSub.remove();
+    };
+  }, []);
+
+  const panResponder = useRef(
+    PanResponder.create({
+      onStartShouldSetPanResponder: () => true,
+      onMoveShouldSetPanResponder: (_, g) =>
+        Math.abs(g.dx) > 3 || Math.abs(g.dy) > 3,
+      onPanResponderGrant: () => {
+        didDrag.current = false;
+        dragStart.current = { ...lastPos.current };
+        pan.setOffset({ x: lastPos.current.x, y: lastPos.current.y });
+        pan.setValue({ x: 0, y: 0 });
+      },
+      onPanResponderMove: (_, g) => {
+        if (Math.abs(g.dx) > 3 || Math.abs(g.dy) > 3) {
+          didDrag.current = true;
+        }
+        Animated.event([null, { dx: pan.x, dy: pan.y }], {
+          useNativeDriver: false,
+        })(_, g);
+      },
+      onPanResponderRelease: (_, g) => {
+        pan.flattenOffset();
+        const start = dragStart.current ?? lastPos.current;
+        const maxX = Math.max(width - size, 0);
+        const maxY = Math.max(height - size, 0);
+        const nextX = Math.max(0, Math.min(maxX, start.x + g.dx));
+        const nextY = Math.max(0, Math.min(maxY, start.y + g.dy));
+        lastPos.current = { x: nextX, y: nextY };
+        Animated.spring(pan, {
+          toValue: { x: nextX, y: nextY },
+          useNativeDriver: false,
+          friction: 7,
+        }).start();
+      },
+    }),
+  ).current;
+
+  const openFeedback = useCallback(() => {
+    setMenuOpen(false);
+    void YaverFeedback.startReport();
+  }, []);
+
+  const hideForever = useCallback(() => {
+    setMenuOpen(false);
+    setUserDisabled(true);
+    void setQuickIconDisabled(true);
+  }, []);
+
+  if (hostSuppressed) return null;
+  if (mode === 'off') return null;
+  if (userDisabled === null) return null;
+  if (userDisabled) return null;
+  if (mode === 'after-shake' && !shakenThisSession) return null;
+  if (!YaverFeedback.isEnabled()) return null;
+
+  const visualSize = size;
+  const radius = visualSize / 2;
+
+  return (
+    <Animated.View
+      pointerEvents="box-none"
+      style={[
+        StyleSheet.absoluteFill,
+        { zIndex: 9998 },
+      ]}
+    >
+      <Animated.View
+        {...panResponder.panHandlers}
+        style={[
+          styles.container,
+          {
+            transform: [{ translateX: pan.x }, { translateY: pan.y }],
+          },
+        ]}
+      >
+        <Pressable
+          onPress={() => {
+            if (didDrag.current) {
+              didDrag.current = false;
+              return;
+            }
+            openFeedback();
+          }}
+          onLongPress={() => {
+            if (didDrag.current) return;
+            setMenuOpen((m) => !m);
+          }}
+          delayLongPress={LONG_PRESS_MS}
+          hitSlop={6}
+          accessibilityRole="button"
+          accessibilityLabel="Open Yaver feedback"
+          style={({ pressed }) => [
+            styles.icon,
+            {
+              width: visualSize,
+              height: visualSize,
+              borderRadius: radius,
+              backgroundColor: color,
+              opacity: pressed ? 0.85 : 1,
+            },
+          ]}
+        >
+          <Text style={[styles.iconLabel, { fontSize: Math.round(visualSize * 0.5) }]}>y</Text>
+        </Pressable>
+        {menuOpen ? (
+          <View style={styles.menu}>
+            <Pressable
+              onPress={openFeedback}
+              style={({ pressed }) => [
+                styles.menuItem,
+                pressed && styles.menuItemPressed,
+              ]}
+            >
+              <Text style={styles.menuItemText}>Open feedback</Text>
+            </Pressable>
+            <View style={styles.menuDivider} />
+            <Pressable
+              onPress={hideForever}
+              style={({ pressed }) => [
+                styles.menuItem,
+                pressed && styles.menuItemPressed,
+              ]}
+            >
+              <Text style={[styles.menuItemText, styles.menuItemDanger]}>
+                Hide icon
+              </Text>
+            </Pressable>
+          </View>
+        ) : null}
+      </Animated.View>
+    </Animated.View>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    alignItems: 'flex-start',
+  },
+  icon: {
+    alignItems: 'center',
+    justifyContent: 'center',
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 2 },
+    shadowOpacity: 0.25,
+    shadowRadius: 4,
+    elevation: 4,
+  },
+  iconLabel: {
+    color: '#ffffff',
+    fontWeight: '700',
+    includeFontPadding: false,
+  },
+  menu: {
+    marginTop: 6,
+    minWidth: 150,
+    backgroundColor: '#1f1f23',
+    borderRadius: 10,
+    paddingVertical: 4,
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 2 },
+    shadowOpacity: 0.3,
+    shadowRadius: 6,
+    elevation: 6,
+  },
+  menuItem: {
+    paddingHorizontal: 14,
+    paddingVertical: 10,
+  },
+  menuItemPressed: {
+    backgroundColor: '#2a2a30',
+  },
+  menuItemText: {
+    color: '#f4f4f5',
+    fontSize: 14,
+    fontWeight: '500',
+  },
+  menuItemDanger: {
+    color: '#f97316',
+  },
+  menuDivider: {
+    height: StyleSheet.hairlineWidth,
+    backgroundColor: '#3f3f46',
+    marginHorizontal: 8,
+  },
+});

package/src/YaverFeedback.ts

@@ -13,6 +13,10 @@ import {
   clearSelectedDeviceId,
   DEFAULT_CONVEX_SITE_URL,
 } from './auth';
+import {
+  getQuickIconDisabled,
+  setQuickIconDisabled,
+} from './preferences';
 
 // Is this JS runtime the Yaver mobile app's super-host bridge? The
 // YaverInfo native module is only registered inside Yaver's container
@@ -49,6 +53,14 @@ let maxErrors = 5;
 /** Track whether BlackBox was running before disable (to restart on enable). */
 let blackBoxWasStreaming = false;
 
+/**
+ * Tracks whether the user has already shaken once in this process.
+ * Consumed by QuickActionIcon's `'after-shake'` mode so the icon
+ * appears the first time a user discovers shake and stays around
+ * thereafter.
+ */
+let firstShakeFired = false;
+
 /**
  * Flag evaluation cache — 30s TTL per `userId|key`. Prevents a
  * tight render loop from hammering /flags/eval when the dev calls
@@ -134,6 +146,7 @@ export class YaverFeedback {
     if (enabled && config.trigger === 'shake') {
       shakeDetector = new ShakeDetector();
       shakeDetector.start(() => {
+        YaverFeedback.notifyShake();
         if (config?.reportingOnly) {
           YaverFeedback.sendAutoReport();
         } else {
@@ -464,6 +477,7 @@ export class YaverFeedback {
       if (config?.trigger === 'shake' && !shakeDetector) {
         shakeDetector = new ShakeDetector();
         shakeDetector.start(() => {
+          YaverFeedback.notifyShake();
           if (config?.reportingOnly) {
             YaverFeedback.sendAutoReport();
           } else {
@@ -796,6 +810,59 @@ export class YaverFeedback {
     }
   }
 
+  /**
+   * Internal: fired from every shake path (dev-menu + accelerometer)
+   * before the feedback modal opens. Emits `yaverFeedback:firstShake`
+   * exactly once per process so QuickActionIcon's `'after-shake'` mode
+   * can surface itself on first shake and stay visible for the rest of
+   * the session.
+   */
+  static notifyShake(): void {
+    if (firstShakeFired) return;
+    firstShakeFired = true;
+    try {
+      const { DeviceEventEmitter } = require('react-native');
+      DeviceEventEmitter.emit('yaverFeedback:firstShake');
+    } catch {
+      // emitter unavailable (e.g. jsdom unit test) — safe to ignore
+    }
+  }
+
+  /**
+   * Show / hide the QuickActionIcon programmatically and persist the
+   * choice across launches. Host apps can call this from a settings
+   * screen so the user has a second way to re-enable the icon after
+   * hiding it via the icon's own long-press menu — shake is always the
+   * third back-door because it never depends on a visible control.
+   */
+  static async setQuickIconVisible(visible: boolean): Promise<void> {
+    await setQuickIconDisabled(!visible);
+    try {
+      const { DeviceEventEmitter } = require('react-native');
+      DeviceEventEmitter.emit(
+        visible ? 'yaverFeedback:quickIconShow' : 'yaverFeedback:quickIconHide',
+      );
+    } catch {
+      // emitter unavailable — preference is still persisted
+    }
+  }
+
+  /**
+   * Returns `true` when the user has chosen to hide the QuickActionIcon
+   * (via its long-press menu or `setQuickIconVisible(false)`).
+   * FeedbackModal uses this to surface a one-tap "Show quick icon"
+   * control so the user can bring the icon back without having to know
+   * about the programmatic API.
+   */
+  static async isQuickIconHidden(): Promise<boolean> {
+    return getQuickIconDisabled();
+  }
+
+  /** Clear the persisted "user hid the icon" flag. */
+  static async resetQuickIconPreference(): Promise<void> {
+    await YaverFeedback.setQuickIconVisible(true);
+  }
+
   /** Tear down the SDK (stop shake detector, clear state). */
   static destroy(): void {
     if (shakeDetector) {

package/src/index.ts

@@ -45,7 +45,14 @@ export { AuthOverlay } from './AuthOverlay';
 export { ShakeDetector } from './ShakeDetector';
 export { FloatingButton } from './FloatingButton';
 export { FeedbackModal } from './FeedbackModal';
+export { QuickActionIcon } from './QuickActionIcon';
+export type { QuickActionIconProps } from './QuickActionIcon';
 export { FixReport } from './FixReport';
+export {
+  getQuickIconDisabled,
+  setQuickIconDisabled,
+  clearQuickIconDisabled,
+} from './preferences';
 export {
   configureAuthEndpoints,
   getConvexSiteUrl,

package/src/preferences.ts

@@ -0,0 +1,55 @@
+/**
+ * SDK user preferences persisted across launches.
+ *
+ * Currently only the quick-action icon's user-level dismiss flag
+ * lives here: the dev enables the icon via `FeedbackConfig.quickIcon`,
+ * but the *user* can long-press → Hide to opt out, and we remember
+ * that choice across launches so their next app session still
+ * respects it.
+ *
+ * AsyncStorage is an optional peer dep — if it's not installed the
+ * getters return `false` and the setters silently no-op, so the icon
+ * still works (it just can't remember the disable beyond the
+ * in-memory session).
+ */
+
+let AsyncStorage: {
+  getItem: (key: string) => Promise<string | null>;
+  setItem: (key: string, value: string) => Promise<void>;
+  removeItem: (key: string) => Promise<void>;
+} | null = null;
+try {
+  AsyncStorage = require('@react-native-async-storage/async-storage').default;
+} catch {
+  // not installed — degrade gracefully
+}
+
+const QUICK_ICON_DISABLED_KEY = 'yaver_feedback_quickicon_disabled';
+
+/** True if the user has long-pressed the icon and chosen "Hide". */
+export async function getQuickIconDisabled(): Promise<boolean> {
+  if (!AsyncStorage) return false;
+  try {
+    const v = await AsyncStorage.getItem(QUICK_ICON_DISABLED_KEY);
+    return v === '1';
+  } catch {
+    return false;
+  }
+}
+
+export async function setQuickIconDisabled(disabled: boolean): Promise<void> {
+  if (!AsyncStorage) return;
+  try {
+    if (disabled) {
+      await AsyncStorage.setItem(QUICK_ICON_DISABLED_KEY, '1');
+    } else {
+      await AsyncStorage.removeItem(QUICK_ICON_DISABLED_KEY);
+    }
+  } catch {
+    // best-effort
+  }
+}
+
+export async function clearQuickIconDisabled(): Promise<void> {
+  await setQuickIconDisabled(false);
+}

package/src/types.ts

@@ -42,6 +42,34 @@ export interface FeedbackConfig {
   preferredDeviceId?: string;
   /** How feedback collection is triggered */
   trigger?: 'shake' | 'floating-button' | 'manual';
+  /**
+   * Small tap-to-open icon that floats above the app so the user
+   * doesn't have to shake every time they want to open feedback.
+   * Single tap → open the feedback modal; long-press → menu with
+   * "Hide icon" (persisted across launches via AsyncStorage).
+   *
+   * - `'auto'` (default) → `'always'` on iOS/Android, `'off'` on web.
+   * - `'always'` → visible from app launch.
+   * - `'after-shake'` → hidden until the first shake this session.
+   * - `'off'` → never rendered. Shake still works.
+   *
+   * The user can always override `'always'` / `'auto'` by long-pressing
+   * → Hide. Devs can clear that override via
+   * `YaverFeedback.resetQuickIconPreference()`.
+   */
+  quickIcon?: 'auto' | 'always' | 'after-shake' | 'off';
+  /**
+   * Background color for the quick-action icon. Default: '#6366f1'
+   * (indigo). Pick something distinctive so the icon never visually
+   * collides with your own FAB.
+   */
+  quickIconColor?: string;
+  /**
+   * Initial position of the quick-action icon, in pixels from the
+   * top-left. Default: near the top-right corner of the screen. The
+   * icon is draggable at runtime — this is only the first mount.
+   */
+  quickIconInitialPosition?: { x: number; y: number };
   /** Enable/disable the SDK. Defaults to __DEV__ */
   enabled?: boolean;
   /**