Skip to main content

​
Visual Overview

While the in/services module primarily operates in the background, it is responsible for the two most critical visual components of the application: the Blocking Overlay and the Nudge Chip. The layout strategy for these elements bypasses standard app boundaries by using WindowManager to draw directly onto the system layer. The visual style leverages a “Premium Glass” aesthetic—using real-time blur, semi-transparent backgrounds, and dynamic color extraction from app icons to ensure the UI feels like a native extension of the Android OS.

​
UI Structure

The visual hierarchy is managed through several specialized controllers that interface with the Android Window System.
  • Enforcement Layer: OverlayEnforcer
    • Manages the full-screen blocking view.
    • Triggers the BlockingActivity when a is exceeded.
  • Interaction Layer: NudgeOverlayManager
    • Renders the “Chip”—a floating pill-shaped -like view.
    • Pill Root: A LinearLayout with a glass-morphism background.
    • Content: An ImageView for the app icon and a TextView for the behavioral nudge.
  • Monitoring Root: ScrollTrackService
    • An that acts as the primary event bus for the UI.

​
State & Interaction

The UI in this module is driven by a complex “Projection Engine” that ensures the user sees zero-latency updates, even when the database is still processing.

​
The Mental Model: Usage Projection

The UI doesn’t just react to saved data; it reacts to a “Live Snapshot”:
  1. Persisted State: Data already saved in the database.
  2. Buffered State: Sessions that just ended but haven’t been written to disk.
  3. Live State: The current active session tracked by ActiveSessionTracker.

​
Event Flow

  1. System Events: The ScrollTrackService captures TYPE_VIEW_SCROLLED events.
  2. Classification: AppScrollClassifier determines if the scroll is “Precise” (pixel-perfect) or “Estimated” (heuristic-based).
  3. Bubbling: Events up to the LimitMonitor.
  4. UI Reaction: If a threshold (50%, 70%, 90%) is hit, the NudgeMonitor commands the NudgeOverlayManager to show the visual chip.

​
Design System Usage

The services module implements a custom “Glass” design system that isn’t found in the main app screens:
  • Dynamic Tinting: The NudgeOverlayManager extracts the primary color from the foreground app’s icon to tint the overlay stroke.
  • Premium Blur: Uses BlurMaskFilter and semi-transparent alphas (85% for dark mode, 92% for light mode) to create depth.
  • Motion: Uses FastOutSlowInInterpolator for the “Expand Centered” animation, where the chip grows out of the app icon.

​
Preview & Testing

Because these components rely on system-level WindowManager and , they cannot be viewed in standard Compose Previews.
  • Diagnostic Mode: Can be enabled in Settings to show “Precise” vs “Estimated” labels on the UI.
  • Test Nudges: The NudgeMonitor includes a triggerTestNudgeForPackage function to manually invoke the overlay for visual verification.
  • Accessibility Testing: The ScrollTrackService uses isNodeScrollable to ensure it only interacts with valid UI elements, preventing “Ghost” scrolls in non-interactive areas.

​
Technical Terms Glossary

Last modified on January 22, 2026