Eat & Scroll

Auto-scroll application for Android that lets you read hands-free while eating. A floating overlay bubble sits on top of any app, enabling automatic content scrolling via Android Accessibility Service — no root required.

---

Quick Start

flutter pub get
flutter run
flutter build apk --split-per-abi

---

Features

Core

• 2 Scroll Modes — Gesture Swipe (simulates finger swipe, configurable 10–100% screen distance) and Pixel Scroll (smooth per-pixel, up to 1000 px/s with 1x–5x distance multiplier)
• Floating Bubble Overlay — Free-floating, hold-to-drag, always-visible play/pause and settings buttons
• Auto-Pause on Touch — Automatically pauses scrolling when touching the screen
• Per-App Memory — Remembers speed, mode, direction, and scroll distance per app

Controls

• Continuous Speed Control — Slider, preset chips, and text input for speed (Gesture: 0.5–20 s/scroll, Pixel: 10–1000 px/s)
• Scroll Direction — Up or down, configurable from the home screen
• Bubble Size & Transparency — Small/Medium/Large bubble with adjustable transparency slider

Permissions & Onboarding

• Guided Permission Setup — Step-by-step onboarding for Accessibility Service, Overlay, and Notification permissions
• Clickable Permission Cards — Tap any permission in settings to open the system settings page

---

How It Works

┌─────────────────────────────────────────────────┐
│              Flutter Layer (UI)                   │
│  Home Screen · Permission Screen · Riverpod      │
└──────────────────────┬──────────────────────────┘
                       │ MethodChannel + EventChannel
┌──────────────────────┴──────────────────────────┐
│           Native Android (Kotlin) Layer           │
│  ┌──────────────────┐  ┌──────────────────────┐  │
│  │ Accessibility     │  │ FloatingBubbleService │  │
│  │ Service           │  │ (WindowManager        │  │
│  │ (ScrollEngine +   │  │  Overlay)             │  │
│  │  GestureFactory)  │  │                       │  │
│  └──────────────────┘  └──────────────────────┘  │
└─────────────────────────────────────────────────┘

1. Flutter manages UI and state via Riverpod; settings auto-save on every change
2. MethodChannel bridges Flutter to native Kotlin services
3. AccessibilityService dispatches scroll gestures to any app using dispatchGesture()
4. ScrollEngine chains gestures with speed-based delays — no separate scheduler
5. GestureFactory builds swipe and pixel-scroll gestures with configurable distance
6. FloatingBubbleService renders a draggable overlay via WindowManager

---

Tech Stack

Layer	Technology
Framework	Flutter 3.44+ / Dart 3.12+
State Management	Riverpod
Native Android	Kotlin (Accessibility Service, WindowManager, Foreground Service)
Communication	MethodChannel + EventChannel
Persistence	SharedPreferences
Architecture	Clean Architecture (Domain / Data / Presentation / Services / Core)

---

Prerequisites

• Flutter SDK ^3.12.2
• Android SDK with API 29–34
• Kotlin support (bundled with Android Studio)
• Physical Android device recommended (Accessibility Service + Overlay required)

---

Project Structure

lib/
├── core/                  # Constants, enums, theme, utilities
│   ├── constants/         # AppConstants (speed ranges, channel names)
│   ├── enums/             # ScrollMode, ScrollDirection, ServiceState
│   └── theme/             # Material 3 theme
├── domain/                # Entities and repository interfaces
│   └── entities/          # ScrollSettings (mode, speed, direction, distance, percent, bubble)
├── data/                  # Local data source and repository implementation
│   └── repositories/      # ScrollRepository (SharedPreferences storage)
├── services/              # MethodChannel bridge and service orchestrator
│   ├── method_channel_service.dart
│   └── scroll_service.dart
├── presentation/          # Screens, widgets, Riverpod providers
│   ├── screens/           # HomeScreen, PermissionScreen
│   ├── widgets/           # Shared widgets (ModeTile, CollapsibleSection, etc.)
│   └── providers/         # Riverpod providers and notifiers
└── main.dart              # Entry point

android/app/src/main/kotlin/com/eatscroll/eat_scroll/
├── MainActivity.kt
├── service/
│   ├── EatAndScrollAccessibilityService.kt
│   ├── ScrollServiceBridge.kt              # MethodChannel handler
│   ├── ScrollEngine.kt                     # Gesture orchestrator
│   ├── GestureFactory.kt                   # GestureDescription builder
│   └── SpeedController.kt                 # Timing math per mode
└── overlay/
    └── FloatingBubbleService.kt            # Native overlay bubble

---

Permissions

Permission	Purpose
SYSTEM_ALERT_WINDOW	Floating bubble overlay
FOREGROUND_SERVICE	Keeps bubble service alive
POST_NOTIFICATIONS	Foreground service notification (Android 13+)
BIND_ACCESSIBILITY_SERVICE	Scroll engine via Accessibility Service

---

Building

# Debug
flutter run

# Release (single APK)
flutter build apk

# Release (split per ABI — recommended)
flutter build apk --split-per-abi
#   app-armeabi-v7a-release.apk   ← older ARM devices
#   app-arm64-v8a-release.apk     ← most modern devices
#   app-x86_64-release.apk        ← emulators

---

Testing

flutter test

---

Documentation

Document	Description
Tutorial	Step-by-step guide
PRD	Product Requirements Document

---

License

This project is private and not published to any package registry.