DroidSurf Mobile Browser & Multi-Tool Integration Specification
Version: 1.4.0-PRO Author: Lead Systems Architect & Core Developer Status: Approved for Implementation Target Platform: Android SDK 26 to 34+ (Kotlin/Jetpack Compose/GeckoView)
1. Executive Summary & Design Vision
DroidSurf is a privacy-focused, performance-driven mobile browser designed to serve as a power-user’s primary command center. Unlike traditional browsers that wrap around standard system WebView (WebKit/Blink), DroidSurf utilizes the robust Mozilla GeckoView Engine to provide independent rendering, advanced tracker blocking, and desktop-class capabilities.
This document outlines the software architecture, user interface patterns (Material Design 3), and integration specifications for the major on-device components: the Robust Download Manager, Media Sniffer & Profile Crawler, Advanced Page Tools, and the custom JSON-Based URL Hub & Preferences Router.
2. Core Architecture: Mozilla GeckoView Integration
To bypass system-level Chrome rendering restrictions and enable true user-script engine hooks, DroidSurf embeds the standalone geckoview library.
+-------------------------------------------------------------+
| DroidSurf Compose UI |
| (Material 3 Expressive Theme | Dynamic Theme Engine) |
+-------------------------------------------------------------+
|
v
+-------------------------------------------------------------+
| GeckoView Session & Delegate Router |
+-------------------------------------------------------------+
| |
v v
+-----------------------+ +------------------------+
| GeckoSession Settings | | Web Extension Engine |
| (UserAgents, DNS, | | (User Scripts, |
| AdBlock Engine) | | Custom Styles) |
+-----------------------+ +------------------------+
GeckoView Configuration Snippet
package com.droidsurf.browser.core
import android.content.Context
import org.mozilla.geckoview.GeckoRuntime
import org.mozilla.geckoview.GeckoSession
import org.mozilla.geckoview.GeckoView
class BrowserEngineManager(private val context: Context) {
private var runtime: GeckoRuntime? = null
fun getOrCreateRuntime(): GeckoRuntime {
if (runtime == null) {
val settings = GeckoRuntime.Settings.Builder()
.useGeckoWebExtensions(true)
.automaticExtensionUpdates(true)
.javaScriptEnabled(true)
.build()
runtime = GeckoRuntime.create(context, settings)
}
return runtime!!
}
fun createSession(): GeckoSession {
val session = GeckoSession()
// Enable tracking protection by default
session.settings.useTrackingProtection = true
session.settings.userAgentOverride = "Mozilla/5.0 (Android 14; Mobile; rv:125.0) Gecko/125.0 Firefox/125.0"
return session
}
}
3. High-Performance Download Manager
DroidSurf embeds an asynchronous download engine powered by Jetpack WorkManager and Kotlin Coroutines. It features background queuing, chunked network streaming, and pause/resume capabilities utilizing the HTTP Range header.
A. Core Properties and State Machine
stateDiagram-v2
[*] --> ENQUEUED : Add download task
ENQUEUED --> RUNNING : Worker picks up task
RUNNING --> PAUSED : User triggers pause
PAUSED --> RUNNING : User triggers resume
RUNNING --> SUCCESS : 100% Downloaded
RUNNING --> FAILED : Network loss / Write failure
FAILED --> RUNNING : Retry with Range offset
SUCCESS --> [*]
B. SQLite Schema (Room Entity) for Download Tracking
package com.droidsurf.browser.data.download
import androidx.room.Entity
import androidx.room.PrimaryKey
@Entity(tableName = "downloads")
data class DownloadTask(
@PrimaryKey val id: String, // UUID string
val url: String,
val fileName: String,
val savePath: String,
val totalBytes: Long,
val downloadedBytes: Long,
val status: String, // ENQUEUED, RUNNING, PAUSED, SUCCESS, FAILED
val mimeType: String,
val timestamp: Long = System.currentTimeMillis()
)
4. Media Sniffer & Profile Crawler
The media sniffer hooks into GeckoView’s resource-loading callbacks to analyze incoming network payloads. It detects downloadable stream formats (.mp4, .mp3, .m3u8, .jpeg, .png, .webp) and displays a contextual UI overlay.
+-------------------------------------------------------------+
| [<-] Active Media Sniffer |
+-------------------------------------------------------------+
| Detected: 14 Media Files Found |
| [Select All] [Clear] |
+-------------------------------------------------------------+
| [x] video_stream_hd_1080p.mp4 (42.5 MB) |
| [x] audio_podcast_track_2.mp3 (8.2 MB) |
| [ ] layout_background_vector.svg (120 KB) |
+-------------------------------------------------------------+
| [DOWNLOAD SELECTED (2)] -> Destination: /Downloads/DroidSurf|
+-------------------------------------------------------------+
Profile Media Bulk Scraper
In addition to on-page sniffing, DroidSurf supports a dedicated profile scraping container for platforms like Instagram, Twitter, Pinterest, and Threads:
- Authenticated Session Fetching: Reuses current GeckoView cookies to fetch user profiles.
- Infinite Pagination Walkers: Crawls page metadata to discover high-resolution images and video arrays.
- Structured Storage: Saves crawled profiles into custom directories matching the format:
output_dir/profile_name/.
5. Rich Page Tools Specification
The browser includes a slide-up Page Tools sheets menu containing advanced commands to optimize page consumption and archiving.
A. Reader Mode
Strips advertisements, floating banners, sidebars, and custom scripts to render clean typography:
- Algorithm: Combines a local implementation of Mozilla’s Readability parser to extract the primary text block.
- Controls: Allows customizing background color (Light, Dark, Sepia) and adjustable sans-serif font scaling.
B. Defuddle.md Integration (Save as Markdown)
Converts active page bodies into highly structured markdown files:
- Custom parser traverses the clean DOM tree, converting header elements (
<h1>,<h2>) to Markdown headers (#,##), handling tables, and preserving absolute asset URL hyperlinks.
C. Offline Save Engines (MHTML & PDF)
- MHTML Chunker: Bundles the page’s HTML along with base-64 encoded image objects, stylesheets, and embedded assets into a single cohesive file.
- PDF Vector Print: Renders the page using vector scaling to produce high-resolution, searchable PDF files.
6. Advanced Customizer, User Scripts & Preferences Router
DroidSurf stores and loads user settings, history, and bookmarks in a single portable JSON file to support instant configuration migration.
JSON Import/Export Configuration Schema
{
"version": "1.0.0",
"preferences": {
"homepage": "https://subbarao6338.github.io/Url-Hub",
"theme": "Material_Expressive_System",
"default_download_folder": "/storage/emulated/0/Download/DroidSurf",
"private_dns": "dns.adguard-dns.com",
"tracking_protection_level": "STRICT"
},
"bookmarks": [
{
"title": "My Url Hub",
"url": "https://subbarao6338.github.io/Url-Hub",
"icon": "https://subbarao6338.github.io/Url-Hub/favicon.ico",
"category": "Main Hub"
}
],
"user_scripts": [
{
"name": "Dark Mode Autoswitcher",
"match": "*://*/*",
"code": "document.body.style.filter = 'invert(1) hue-rotate(180deg)';"
}
]
}
URL Hub Router Integration
When registered as the default browser in Android, DroidSurf implements custom Intent Filters. Whenever you click a link in an external app, DroidSurf captures the incoming intent, checks it against the active URL Hub categories, and routes it directly into a sandboxed browsing session tab, bypassing external tracking services completely.