The in.util module serves as the intelligence layer and behavioral engine of the Scrollless application. Rather than being a collection of disparate helper functions, it defines the system’s “personality” and its approach to digital wellbeing.This module is responsible for:
Adaptive Coaching: Analyzing usage history to suggest realistic time limits.
Psychological Friction: Implementing an “Exponential Snooze” strategy to discourage compulsive app use.
Physicalization: Converting abstract digital metrics (pixels, sessions) into physical units (meters, kilometers).
System Orchestration: Managing complex Android and system-level interactions.
CoachSuggestionService: Orchestrates a tiered coaching logic. It uses “Phases” (1-3) based on how many days of data are available, moving from simple averages to complex trends.
SmartAdaptationPolicy: The mathematical core that calculates limit adjustments. It includes “Recovery Mode” to prevent user burnout by suggesting limit increases if a user is failing consistently.
CoachWording: A specialized builder that generates human-friendly, semi-randomized subtitles (e.g., “It has been a bit heavy lately…”) to make the AI coach feel more empathetic.
ScrollPhysics & ConversionUtil: Translates screen pixels into physical meters. It accounts for device-specific to ensure that “100 meters of scrolling” is physically accurate regardless of the phone’s screen size.
The system doesn’t just set a limit; it evolves with the user:
Observation: UsageStatsHelper queries the Android system for foreground time.
Analysis: SmartLimitPolicy computes “Easy,” “Maintain,” and “Ambitious” goals.
Hysteresis: CoachSuggestionManager ensures the user isn’t bombarded with suggestions, enforcing a 7-day “cool down” between limit changes to allow habits to form.
Because Scrollless relies on sensitive Android APIs, PermissionManager provides a reactive of the system’s permission state. It handles the complex intent-routing required to send users to specific system settings pages (Accessibility, Usage Access, Overlay).
The module treats usage data as a stream to be cleaned and interpreted:
Outlier Exclusion: In SmartAdaptationPolicy, the system calculates the standard deviation of usage and ignores “outlier days” (e.g., a one-off 6-hour binge) so they don’t skew the long-term coaching logic.
Normalization: CategoryUtil maps messy Android package categories (like GAME_ACTION or GAME_RPG) into clean, user-facing groups like “Games.”
Rounding Logic: DateUtil implements “Rounded Remaining Duration.” This prevents the “instant penalty” where 1 second of usage might look like a full minute lost, instead rounding usage to the nearest minute for a fairer user experience.