If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/yhaolpz/FloatWindow shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 5y ago

• 6 active contributors
• Distributed ownership (top contributor 41% of recent commits)
• Apache-2.0 licensed
• Tests present
• ⚠ Stale — last commit 5y ago
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live yhaolpz/FloatWindow repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/yhaolpz/FloatWindow.

What it runs against: a local clone of yhaolpz/FloatWindow — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in yhaolpz/FloatWindow | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1698 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of yhaolpz/FloatWindow. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/yhaolpz/FloatWindow.git
#   cd FloatWindow
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of yhaolpz/FloatWindow and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "yhaolpz/FloatWindow(\\.git)?\\b" \\
  && ok "origin remote is yhaolpz/FloatWindow" \\
  || miss "origin remote is not yhaolpz/FloatWindow (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "floatwindow/src/main/java/com/yhao/floatwindow/FloatWindow.java" \\
  && ok "floatwindow/src/main/java/com/yhao/floatwindow/FloatWindow.java" \\
  || miss "missing critical file: floatwindow/src/main/java/com/yhao/floatwindow/FloatWindow.java"
test -f "floatwindow/src/main/java/com/yhao/floatwindow/IFloatWindowImpl.java" \\
  && ok "floatwindow/src/main/java/com/yhao/floatwindow/IFloatWindowImpl.java" \\
  || miss "missing critical file: floatwindow/src/main/java/com/yhao/floatwindow/IFloatWindowImpl.java"
test -f "floatwindow/src/main/java/com/yhao/floatwindow/FloatView.java" \\
  && ok "floatwindow/src/main/java/com/yhao/floatwindow/FloatView.java" \\
  || miss "missing critical file: floatwindow/src/main/java/com/yhao/floatwindow/FloatView.java"
test -f "floatwindow/src/main/java/com/yhao/floatwindow/PermissionUtil.java" \\
  && ok "floatwindow/src/main/java/com/yhao/floatwindow/PermissionUtil.java" \\
  || miss "missing critical file: floatwindow/src/main/java/com/yhao/floatwindow/PermissionUtil.java"
test -f "floatwindow/src/main/java/com/yhao/floatwindow/FloatLifecycle.java" \\
  && ok "floatwindow/src/main/java/com/yhao/floatwindow/FloatLifecycle.java" \\
  || miss "missing critical file: floatwindow/src/main/java/com/yhao/floatwindow/FloatLifecycle.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1698 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1668d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/yhaolpz/FloatWindow"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

FloatWindow is an Android library that implements floating window overlays (悬浮窗) for any activity without boilerplate. It provides draggable window components with automatic edge-snapping animations, automatic permission handling, and activity-scoped visibility filtering—all via a fluent builder API. Core technology: Android WindowManager with custom touch handling and lifecycle integration. Single-module library structure: floatwindow/ module contains all source under floatwindow/src/main/java/com/yhao/floatwindow/. Core abstractions: IFloatWindow (interface) → IFloatWindowImpl (implementation) ← FloatWindow (static factory). Peripheral classes handle concerns: FloatView (custom View), FloatLifecycle + LifecycleListener (app state), PermissionUtil + Miui.java (ROM-specific perms), MoveType + ViewStateListener (gesture/state events).

Android app developers building feature-rich applications that need persistent floating UI elements (chat heads, tool palettes, video-in-picture windows) without implementing WindowManager permission logic or touch event handling from scratch.

Moderately mature for single-maintainer library: v1.0.9 released, README shows practical features and usage patterns, but repo shows 49.8KB of Java code suggesting medium complexity. No visible CI/CD pipeline in file list (no .yml workflows), test coverage appears minimal (only boilerplate ExampleInstrumentedTest.java and ExampleUnitTest.java), last commit date not visible but build.gradle uses Gradle 2.3.3 (2016-era tooling). Verdict: production-usable for common cases but shows signs of age.

Single-maintainer risk is high (yhaolpz as sole contributor appears likely). Gradle 2.3.3 is severely outdated (from 2016; current is 8.x), creating dependency vulnerability and compatibility issues with modern Android toolchains. No automated tests beyond stubs means regressions in edge cases (MIUI-specific code in Miui.java, lifecycle edge cases) are undetected. ROM/device-specific workarounds (Miui.java, Rom.java) suggest fragility across Android versions.

No active development visible: build.gradle and tooling appear frozen at 2016 standards, no indication of ongoing work. Repo exists as stable/legacy library—likely maintenance-only mode accepting occasional PRs but not actively evolving.

Clone and open in Android Studio: git clone https://github.com/yhaolpz/FloatWindow.git && cd FloatWindow && ./gradlew build. Gradle Wrapper will handle dependency fetch. No additional setup needed (no external services, no secrets).

Daily commands: Build only; no 'run' in traditional sense (it's a library). ./gradlew assemble builds the AAR. To test integration: create a test app module, add FloatWindow as dependency, and run on emulator/device. See sample app pattern in README (though sample app source not in file list).

• floatwindow/src/main/java/com/yhao/floatwindow/FloatWindow.java — Primary public API entry point; all floating window creation and configuration flows through this singleton-like class
• floatwindow/src/main/java/com/yhao/floatwindow/IFloatWindowImpl.java — Core implementation handling window lifecycle, positioning, dragging, permissions, and state management
• floatwindow/src/main/java/com/yhao/floatwindow/FloatView.java — Custom View subclass managing touch interactions, drag animations, and visual rendering of the floating widget
• floatwindow/src/main/java/com/yhao/floatwindow/PermissionUtil.java — Abstracts OS version-specific permission checks and requests (MIUI, Android 4.4–7.0 variations)
• floatwindow/src/main/java/com/yhao/floatwindow/FloatLifecycle.java — Manages application lifecycle integration to show/hide floating window when app enters background or resumes
• floatwindow/src/main/AndroidManifest.xml — Declares SYSTEM_ALERT_WINDOW permission and FloatActivity for overlay rendering across all Android versions

Create a new floating window with custom view

1. Define your custom View layout or create a View programmatically (e.g., Button, ImageView) (sample/src/main/java/com/example/yhao/floatwindow/A_Activity.java)
2. Call FloatWindow.with(context) and chain configuration methods (.setView(), .setWidth(), .setHeight(), .setX(), .setY()) (floatwindow/src/main/java/com/yhao/floatwindow/FloatWindow.java)
3. Set visibility scope via .setShowPattern() or .setActivity() to control which screens display the window (floatwindow/src/main/java/com/yhao/floatwindow/IFloatWindow.java)
4. Register a ViewStateListener via .setViewStateListener() to monitor drag, position, and visibility events (floatwindow/src/main/java/com/yhao/floatwindow/ViewStateListener.java)
5. Call .build() to create the window; permissions are handled automatically by PermissionUtil (floatwindow/src/main/java/com/yhao/floatwindow/IFloatWindowImpl.java)

Add support for a new ROM or Android version

1. Add new ROM enum constant to Rom.java with device model detection logic (floatwindow/src/main/java/com/yhao/floatwindow/Rom.java)
2. If ROM requires special permission flow (like MIUI), add new class similar to Miui.java with Intent navigation (floatwindow/src/main/java/com/yhao/floatwindow/Miui.java)
3. Update PermissionUtil.java to branch logic based on new ROM type in requestPermission() or checkPermission() methods (floatwindow/src/main/java/com/yhao/floatwindow/PermissionUtil.java)
4. Test permission flow and window rendering across target API levels in sample app activities (sample/src/main/java/com/example/yhao/floatwindow/BaseActivity.java)

Customize drag behavior and edge-snap animations

1. Choose or create a MoveType enum variant (SLIDE, FIXED, ELASTIC) to define drag constraints (floatwindow/src/main/java/com/yhao/floatwindow/MoveType.java)
2. Pass MoveType via .setMoveType() in FloatWindow builder chain (floatwindow/src/main/java/com/yhao/floatwindow/FloatWindow.java)
3. Modify FloatView.onTouchEvent() to adjust velocity calculations and boundary clamping based on MoveType (floatwindow/src/main/java/com/yhao/floatwindow/FloatView.java)
4. Update Util.java animation helpers to change snap duration, easing, or friction behavior (floatwindow/src/main/java/com/yhao/floatwindow/Util.java)

Listen for floating window state changes

1. Implement ViewStateListener interface or extend ViewStateListenerAdapter to reduce boilerplate (floatwindow/src/main/java/com/yhao/floatwindow/ViewStateListener.java)
2. Override callbacks: onPositionUpdate(x, y), onShow(), onHide(), onDragStart(), onDragEnd() (floatwindow/src/main/java/com/yhao/floatwindow/ViewStateListenerAdapter.java)
3. Register listener via .setViewStateListener(myListener) in FloatWindow builder (floatwindow/src/main/java/com/yhao/floatwindow/FloatWindow.java)
4. IFloatWindowImpl invokes listener callbacks at appropriate lifecycle and interaction points (floatwindow/src/main/java/com/yhao/floatwindow/IFloatWindowImpl.java)

Android API level fragmentation: SYSTEM_ALERT_WINDOW permission behavior differs across API 16→19 (no permission needed), 19→23 (permission with implicit grant), and 23+ (runtime permissions). Miui.java handles Xiaomi's custom permission model but other OEMs (Samsung, Huawei) may have undocumented quirks. ActivityLifecycleCallbacks only available on API 14+; behavior with legacy fragments untested. WindowManager operations are main-thread only; no thread safety assertions visible. No ProGuard config beyond stub floatwindow/proguard-rules.pro; reflection-heavy code paths may break in obfuscated builds.

• WindowManager and SYSTEM_ALERT_WINDOW — Core mechanism for rendering overlays above other apps; permission model varies by API level and OEM, making this the primary learning curve for contributors
• ActivityLifecycleCallbacks — Allows library to auto-hide floating window when app backgrounded without requiring Activity inheritance; essential for non-invasive integration
• Touch Event Propagation and GestureDetector — FloatView must intercept and handle drag gestures while allowing clicks; understanding MotionEvent flow is critical for fixing input edge cases
• OEM/ROM-Specific Permission Models — MIUI, EMUI, OneUI override stock Android permission behavior; Miui.java and Rom.java show library must detect and adapt at runtime—key pain point in cross-device testing
• Builder Pattern with Fluent Interface — FloatWindow.with().setView().setWidth().build() chains require method return-type tracking; common Java pattern but essential for API clarity in this library
• Strategy Pattern for Move Behaviors — MoveType enum encapsulates different drag/snap animations (slide, back, active, inactive); contributors modifying animation logic must respect this pattern
• Screen Coordinate System and DPI Scaling — Screen.java handles conversion between pixels, DP, and percentage-based positioning; critical for accurate cross-device window placement

• UFOCatch/FloatWindowView — Alternative floating window library for Android with simpler API but less activity filtering; good comparison for architecture decisions
• pinguo/DanmakuFlameMaster — Android danmaku (floating comment) overlay system using similar WindowManager patterns; reference for high-performance multi-window scenarios
• zzz40500/GoodNews — Example app using FloatWindow library in production; demonstrates real-world integration patterns and edge cases
• Blankj/AndroidUtilCode — Companion utility library frequently used alongside FloatWindow for permission helpers, screen utils, and ROM detection utilities
• square/leakcanary — Floating debug tool using WindowManager overlays; predecessor inspiration for detecting and managing lifecycle-aware floating UI

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add instrumented tests for FloatWindow lifecycle and permission handling

The repo has AndroidTest files (ExampleInstrumentedTest.java) but they're empty boilerplate. Given the complexity of FloatWindow's lifecycle management (FloatLifecycle.java, LifecycleListener.java, ResumedListener.java) and permission logic (PermissionUtil.java, PermissionListener.java), there should be comprehensive instrumented tests validating: permission request flows, lifecycle callbacks during activity transitions, and float window visibility state changes across different Android versions. This directly prevents regressions in the core functionality.

• [ ] Create floatwindow/src/androidTest/java/com/yhao/floatwindow/FloatWindowLifecycleTest.java with tests for onCreate/onResume/onPause transitions
• [ ] Create floatwindow/src/androidTest/java/com/yhao/floatwindow/PermissionTest.java testing permission flows on Android 4.4+ and 6.0+
• [ ] Add tests in floatwindow/src/androidTest/java/com/yhao/floatwindow/FloatViewStateTest.java for ViewStateListener callbacks (found in ViewStateListener.java)
• [ ] Reference actual implementations: FloatActivity.java, IFloatWindowImpl.java, and Miui.java ROM-specific logic

Create ROM-specific behavior unit tests for Miui.java and Rom.java

The codebase has ROM detection (Rom.java) and special Miui handling (Miui.java) but no unit tests validating ROM-specific behavior. Given that the README explicitly states 'except Xiaomi, 4.4~7.0 requires no permission', there should be unit tests ensuring ROM detection correctly identifies devices and applies appropriate permission/display strategies. This prevents silent failures on specific device types.

• [ ] Create floatwindow/src/test/java/com/yhao/floatwindow/RomDetectionTest.java testing Rom.java detection logic with mocked Build properties
• [ ] Create floatwindow/src/test/java/com/yhao/floatwindow/MiuiHandlerTest.java validating Miui-specific permission flow differs from standard Android
• [ ] Add test cases for Android 4.4, 5.x, 6.0, 7.0 version-specific behavior using PermissionUtil.java
• [ ] Mock Android Build class to simulate different ROM strings (xiaomi, miui, samsung, etc.)

Add comprehensive documentation for FloatWindow configuration options with code examples

The README shows basic usage with one incomplete example (missing closing), but FloatWindow's API is rich with unDocumented features: MoveType enum, Screen utility class percentage-based positioning, ViewStateListenerAdapter, and FloatPhone class. Contributors struggle to discover available options. Add a detailed CONFIGURATION.md documenting all public APIs with real usage examples.

• [ ] Create CONFIGURATION.md documenting all methods in FloatWindow.java and IFloatWindow.java with examples
• [ ] Add examples for MoveType.java enum values (AUTO_SIDE, SLIDE_X, etc.) with visual descriptions of behavior
• [ ] Document Screen.java utility methods for percentage-based width/height configuration (referenced in README but not explained)
• [ ] Include examples for all listener interfaces: PermissionListener.java, LifecycleListener.java, ViewStateListener.java, and their adapters
• [ ] Add troubleshooting section referencing Miui.java and Rom.java behavior differences across device types

• Add unit tests for PermissionUtil.java covering all API level branches (16-29+) with mocked Context and PackageManager to prevent regression in permission logic across Android versions
• Document and test ROM-specific behavior: create test cases in floatwindow/src/androidTest for Miui.java, Samsung, and Huawei devices to verify workarounds; add ROM detection matrix to README
• Upgrade Gradle from 2.3.3 to 7.x+ and update Android plugin versions; pin kotlin-gradle-plugin if Kotlin support is added; ensure CI/CD pipeline runs tests on merge to prevent bitrot

This Android FloatWindow library has several security concerns primarily centered on outdated dependencies and misconfigured repositories. The most critical issues are: (1) Using Gradle 2.3.3 from 2017 without security updates, (2) Reliance on the defunct jcenter() repository, and (3) Requesting powerful SYSTEM_ALERT_WINDOW permissions without documented safety practices. While the library itself may be functional, the build infrastructure and dependency management pose significant risks. Immediate action required: update Gradle, migrate to mavenCentral(), and add security documentation. The overlay permission usage requires careful review of implementation details to ensure it cannot be misused.

• High · Outdated Gradle Build Tools — build.gradle (root level). The project uses com.android.tools.build:gradle:2.3.3, which was released in 2017 and contains multiple known vulnerabilities. This version no longer receives security updates and lacks modern security features. Fix: Update to the latest stable version of Android Gradle Plugin (currently 8.x). Run dependency updates and test thoroughly to ensure compatibility.
• High · Insecure Repository - jcenter() — build.gradle (root level and module level). The project uses jcenter() repository which was sunset by JFrog in 2021. Dependencies from this source may no longer receive security patches, and the repository is no longer maintained. Fix: Replace jcenter() with mavenCentral() or Google Maven repository. Update all Gradle configurations to use modern, actively maintained repositories.
• Medium · SYSTEM_ALERT_WINDOW Permission Misuse Risk — AndroidManifest.xml (floatwindow/src/main). The library requests SYSTEM_ALERT_WINDOW permission which allows drawing overlays on any application. While functionality requires this, there is potential for misuse if the library implementation doesn't properly validate contexts or if integrated into malicious applications. Fix: Implement strict context validation, add user notification about overlay usage, and provide clear documentation about responsible usage. Consider implementing additional permission checks beyond what the OS requires.
• Medium · Missing ProGuard/R8 Configuration Details — floatwindow/proguard-rules.pro and sample/proguard-rules.pro. While proguard-rules.pro files exist, without reviewing their contents, it's unknown if sensitive APIs and custom classes are properly obfuscated, potentially exposing implementation details through reverse engineering. Fix: Review and strengthen ProGuard/R8 rules to ensure proper obfuscation of sensitive APIs, custom implementations, and permission-related code. Use -keep rules selectively.
• Medium · Deprecated Android Build Gradle Plugin — build.gradle (root level). The android-maven-gradle-plugin:1.5 dependency is deprecated and no longer maintained. Modern projects should use Maven Publish Gradle Plugin instead. Fix: Replace with com.gradle.publish:plugin-publish-plugin or use maven-publish plugin for artifact publishing. Update publish configurations accordingly.
• Low · No Security Policy Documentation — Repository root. The repository lacks security.md or similar documentation outlining security practices, vulnerability disclosure procedures, and safety recommendations for library usage. Fix: Create SECURITY.md file documenting: responsible disclosure process, security best practices for library usage, known limitations, and version support policies.
• Low · Potential Implicit Intent Usage — floatwindow/src/main/java/com/yhao/floatwindow/FloatActivity.java. Without detailed code review, there's a risk of implicit intents being used in FloatActivity.java or other components, which can be intercepted by malicious apps on Android 12+. Fix: Review all Intent usage and ensure explicit intents are used. Avoid sending sensitive data through intents; use safe alternatives like shared Application instances or bound services.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.