Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
6244913
docs: Sprint 1C design and implementation plan
xeriomy Nov 16, 2026
d68f7bc
feat: capture visibility gate (pure policy) for app-only windows
xeriomy Nov 16, 2026
6eaceb9
feat: gate frame publication on captured-content visibility (API 34+)
xeriomy Nov 16, 2026
ffc4f5e
feat: normalized overlay position with edge-snapping math
xeriomy Nov 16, 2026
48e0e11
feat: overlay enablement decision and persisted position keys
xeriomy Nov 16, 2026
f88cce4
feat: circular floating freeze button (WindowManager overlay)
xeriomy Nov 16, 2026
494df62
feat: enable floating freeze control during capture; two-mode capture…
xeriomy Nov 16, 2026
c6edb52
test: instrumented overlay attach/removal (compile-only)
xeriomy Nov 16, 2026
94662b3
test: visibility/freeze/stop edge cases for Sprint 1C
xeriomy Nov 16, 2026
482b9ae
docs: Sprint 1C capture-visibility and overlay documentation
xeriomy Nov 16, 2026
0f271b5
docs: point CI reporting at the PR description
xeriomy Nov 16, 2026
e3e26c6
fix: keep the visibility gate across capture resizes; reset only on f…
xeriomy Nov 16, 2026
1660c72
fix: re-anchor overlay drag/snap math to current display metrics
xeriomy Nov 16, 2026
6e2d7b7
docs: correct the notification-permission comment now that the floati…
xeriomy Nov 16, 2026
60bca1a
docs: record Sprint 1C CI evidence (run 43782436092)
xeriomy Nov 16, 2026
c93ed2d
fix: review findings — orphan-attach guard, pause-path visibility gat…
xeriomy Nov 16, 2026
f992d45
fix: restore broken import line in instrumented overlay test
xeriomy Nov 16, 2026
f85a7e9
docs: record the review-fix CI evidence (run 43784157138)
xeriomy Nov 16, 2026
130ce6c
feat: notification Pause/Resume on shared publish state; permissions-…
xeriomy Nov 16, 2026
e42552e
docs: record the follow-up CI evidence (run 43922482183)
xeriomy Nov 16, 2026
9640141
diagnostics: rate-limited per-stage capture logs (no policy changes)
xeriomy Nov 16, 2026
d7f45f8
fix: buffer early visibility/resize callbacks; explicit UNKNOWN gate …
xeriomy Nov 16, 2026
3c7b58c
fix: align visibility policy callback parameter name with tests
xeriomy Nov 16, 2026
9c6270f
docs: record single-app first-frame fix CI evidence (run 43936524131)
xeriomy Nov 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 24 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,16 +30,26 @@ and [docs/VISION_TESTING.md](docs/VISION_TESTING.md).
- Hero recognition v0 (Sprint 1B, PR #3): hero catalog sync from public static data,
explicit Identify action for the selected slot, ranked candidates with similarity scores,
manual confirm/correct — **accuracy on real game screens is not measured yet**
- Freeze the game frame from the notification (Sprint 1B): tap **Freeze current frame** on the
capture notification while you are in MLBB — no need to leave the game; Vision Lab shows the
pinned game frame, not the DraftLens screen; **Resume live capture** from the notification or
in the Vision Lab
- Capture notification with **Stop** and **Pause** (Sprint 1C): pausing keeps the latest
valid frame, blocks new frames replacing it, keeps MediaProjection running, and the same
Resume action recovers from pause or from a pinned frame; the notification reflects
LIVE / PAUSED / FROZEN and never shows both actions
- App-only capture guidance (Sprint 1C): prefer **Single app / app window → Mobile Legends**
(Android 14+ chooser); the captured window's visibility drives publication —
MLBB hidden ⇒ the last valid game frame is kept, never DraftLens/shade/system UI;
full-display capture remains the documented fallback (it may include the shade/system UI)
- Circular floating freeze button (Sprint 1C): one 52dp circular `TYPE_APPLICATION_OVERLAY`
button shown only while capture runs — tap toggles LIVE (green) / orange (paused or frozen),
long-press-and-drag moves it, it snaps to a screen edge, position persists normalized in
DataStore; notifications/in-app Freeze/Resume keep working without it; the overlay
permission is requested only when you enable the button

## What is deliberately NOT here (later milestones)
ML hero recognition, recommendation engine, counter/synergy/role scoring, floating overlays,
API sync, player profiling, builds. The Vision Lab says **"Detection: not implemented"** —
manual slots are calibration data, never detections. See `tasks/plan.md` and
`docs/ARCHITECTURE.md`.
Recommendation engine, counter/synergy/role scoring — and no recommendation overlays
(Sprint 1C ships exactly one capture-freeze overlay button, and nothing else).
ML hero recognition is Sprint 1B (PR #3). API sync, player profiling, builds.
The Vision Lab says **"Detection: not implemented"** — manual slots are calibration data,
never detections. See `tasks/plan.md` and `docs/ARCHITECTURE.md`.

## Build
Requires JDK 17 and Android SDK platform 35, build-tools 35.
Expand All @@ -58,11 +68,13 @@ build of record.** See `docs/VISION_TESTING.md` for exactly what ran.
validates compilation, not MediaProjection reliability).
2. Open the app; the **Debug Capture** tab is first.
3. Tap **Start Capture** → grant the system screen-capture consent dialog. When Android asks
what to capture, choose **Entire screen / full device display** — app-window capture shows
this app, not Mobile Legends, and the notification freeze workflow would be pointless.
what to capture, prefer **Single app / app window → Mobile Legends: Bang Bang** (Android 14+);
if that option is missing, choose **Entire screen / full device display** (it can capture the
shade and system UI).
4. Open Mobile Legends and wait for the draft screen you want to annotate.
5. Pull down the notification shade and tap **Freeze current frame** on the DraftLens capture
notification (notifications must be enabled — the app checks and tells you).
5. With MLBB on screen, tap the circular **Floating freeze button** (enable it on the capture
screen first) to freeze the frame — or, if you never granted the overlay permission, pull
down the notification shade and tap **Pause** (notifications must be enabled).
6. Switch back to **DraftLens → Vision Lab**. Capture kept running; the Vision Lab shows the
pinned MLBB frame instead of the DraftLens screen.
7. Draw a slot rectangle, then run **Identify hero** on the frozen frame. Candidates are
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
package com.draftlens

import android.content.Context
import android.content.pm.PackageManager
import android.os.SystemClock
import android.provider.Settings
import androidx.test.core.app.ApplicationProvider
import androidx.test.ext.junit.runners.AndroidJUnit4
import com.draftlens.datastore.AppPreferencesRepository
import com.draftlens.overlay.OverlayController
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.flow.first
import kotlinx.coroutines.runBlocking
import org.junit.After
import org.junit.Assert.assertFalse
import org.junit.Assert.assertEquals
import org.junit.Assert.assertNotNull
import org.junit.Assert.assertTrue
import org.junit.Assume.assumeTrue
import org.junit.Test
import org.junit.runner.RunWith

/**
* Compile-only in CI (no device farm): real WindowManager behavior needs a device with the
* overlay appop granted. To execute on a physical device or emulator:
*
* adb shell appops set --uid $(adb shell pm list package -U com.draftlens.debug | cut -d: -f3 | cut -d\; -f2) SYSTEM_ALERT_WINDOW allow
* ./gradlew connectedDebugAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=com.draftlens.FloatingControlOverlayInstrumentedTest
*
* What can never be asserted here: whether the overlay appears inside a captured image —
* that is a physical-device finding, recorded in docs/TESTING_PHYSICAL_DEVICE.md.
*/
@RunWith(AndroidJUnit4::class)
class FloatingControlOverlayInstrumentedTest {

private val context: Context = ApplicationProvider.getApplicationContext()
private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main)
private val preferences = AppPreferencesRepository(context)
private var controller: OverlayController? = null

@After fun tearDown() {
controller?.detach()
controller = null
runBlocking { preferences.setFloatingControlEnabled(false) }
}

@Test fun overlayPermissionIsDeclaredInTheManifest() {
val info = context.packageManager.getPackageInfo(context.packageName, PackageManager.GET_PERMISSIONS)
val requested = info.requestedPermissions?.toSet().orEmpty()
assertTrue(
"SYSTEM_ALERT_WINDOW must be declared; granting happens at runtime",
requested.contains(android.Manifest.permission.SYSTEM_ALERT_WINDOW),
)
}

@Test fun overlayAttachesWhenEnabledAndPermittedAndDetachesCleanly() {
assumeTrue(
"overlay appop not granted on this device; see class comment",
Settings.canDrawOverlays(context),
)
runBlocking { preferences.setFloatingControlEnabled(true) }

val created = OverlayController(context, preferences, scope)
controller = created
created.show(1080, 2400)

assertTrue("overlay did not attach within 5s", waitUntil { created.isAttached })
created.detach()
assertFalse(created.isAttached)
}

@Test fun aPendingAttachIsInvalidatedByDetachSoNoOverlayIsOrphaned() {
assumeTrue(
"overlay appop not granted on this device; see class comment",
Settings.canDrawOverlays(context),
)
runBlocking { preferences.setFloatingControlEnabled(true) }

val created = OverlayController(context, preferences, scope)
controller = created
created.show(1080, 2400)
// Teardown lands while the DataStore read inside show() is still in flight.
created.detach()
Thread.sleep(1_000)

assertFalse("a detached controller must never attach afterwards", created.isAttached)
}

@Test fun floatingPositionRoundTripsThroughDataStore() = runBlocking {
// Note: writes the shared preferences store on the test device; restored at the end.
val prefs = AppPreferencesRepository(context)
prefs.setFloatingPosition(com.draftlens.overlay.OverlayPosition.Normalized(0.15f, 0.3f))

val read = prefs.floatingPosition.first()

assertNotNull("position must persist", read)
assertEquals(0.15f, read!!.x, 0.001f)
assertEquals(0.3f, read.y, 0.001f)
// Restore a sane default for the app on this device.
prefs.setFloatingPosition(com.draftlens.overlay.OverlayPosition.Normalized(1f, 0.18f))
}

@Test fun overlaySurvivesPublicationStateFlips() {
assumeTrue(
"overlay appop not granted on this device; see class comment",
Settings.canDrawOverlays(context),
)
runBlocking { preferences.setFloatingControlEnabled(true) }

val created = OverlayController(context, preferences, scope)
controller = created
created.show(1080, 2400)
assertTrue("overlay did not attach within 5s", waitUntil { created.isAttached })

// Publication-state changes (freeze/resume/pause/visibility gates) must never detach it.
created.setNotLive(true)
created.setNotLive(false)

assertTrue("overlay must stay attached across publication-state flips", created.isAttached)
}

private fun waitUntil(timeoutMs: Long = 5_000, condition: () -> Boolean): Boolean {
val deadline = SystemClock.elapsedRealtime() + timeoutMs
while (SystemClock.elapsedRealtime() < deadline) {
if (condition()) return true
SystemClock.sleep(100)
}
return condition()
}
}
2 changes: 2 additions & 0 deletions app/src/main/AndroidManifest.xml
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<!-- Floating freeze button; requested only when the user enables it (TYPE_APPLICATION_OVERLAY). -->
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
<!-- Hero catalog download (public, static, HTTPS only). No user data is uploaded. -->
<uses-permission android:name="android.permission.INTERNET" />

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,4 +19,7 @@ object CaptureController {
fun stop(context: Context) = context.startService(CaptureSessionService.stopIntent(context))
fun pause(context: Context) = context.startService(CaptureSessionService.pauseIntent(context))
fun resume(context: Context) = context.startService(CaptureSessionService.resumeIntent(context))

/** Re-evaluates the floating control after the user toggled it or granted the permission. */
fun refreshOverlay(context: Context) = context.startService(CaptureSessionService.overlayUpdateIntent(context))
}
31 changes: 31 additions & 0 deletions app/src/main/kotlin/com/draftlens/capture/CaptureDiagnostics.kt
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
package com.draftlens.capture

/**
* Rate limiter for bounded capture diagnostics: the first few occurrences of each event
* and then one line every [every] occurrences. No pixel data is ever logged.
*
* Keyed by event name, so "gate-reject:contentHidden" is counted separately from
* "gate-reject:staleGeneration" — a log line can then answer whether ImageReader received
* images and which gate rejected them.
*/
class CaptureDiagnostics(
private val firstEvents: Int = 4,
private val every: Int = 20,
) {
private val counts = LinkedHashMap<String, Int>()

/** Increments the event's counter and returns the new count. */
fun sample(event: String): Int {
val next = (counts[event] ?: 0) + 1
counts[event] = next
return next
}

fun shouldLog(count: Int): Boolean = count <= firstEvents || count % every == 0

fun total(event: String): Int = counts[event] ?: 0

fun reset() {
counts.clear()
}
}
36 changes: 36 additions & 0 deletions app/src/main/kotlin/com/draftlens/capture/CapturePublishState.kt
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
package com.draftlens.capture

/**
* Single source of truth for the "is live publication happening?" presentation used by
* the capture notification, the floating overlay glyph and the toggle logic.
*
* Three states, never independent:
* - LIVE: images convert and publish (no pin, not paused).
* - PAUSED: the user (or the notification) paused publication; projection stays valid.
* - FROZEN: a frame snapshot is pinned (in-app freeze / floating button).
*
* Pure Kotlin so the decision matrix is unit-testable; every UI surface derives its
* action from here instead of keeping parallel state.
*/
enum class CapturePublishState { LIVE, PAUSED, FROZEN }

/** What the notification's one freeze/pause action shows. */
enum class CapturePublishAction { PAUSE, RESUME }

enum class FloatingTapOutcome { FREEZE, RESUME }

/** Derivation both surfaces share; a pin wins over pause for presentation. */
fun publishStateFor(pinInPlace: Boolean, isPaused: Boolean): CapturePublishState = when {
pinInPlace -> CapturePublishState.FROZEN
isPaused -> CapturePublishState.PAUSED
else -> CapturePublishState.LIVE
}

fun publishActionFor(state: CapturePublishState): CapturePublishAction =
if (state == CapturePublishState.LIVE) CapturePublishAction.PAUSE else CapturePublishAction.RESUME

/** The overlay tap toggles the shared pause/freeze gate; it never invents a new one. */
fun floatingTapFor(state: CapturePublishState): FloatingTapOutcome =
if (state == CapturePublishState.LIVE) FloatingTapOutcome.FREEZE else FloatingTapOutcome.RESUME

fun publishStateBlocksPublication(state: CapturePublishState): Boolean = state != CapturePublishState.LIVE
Loading
Loading