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/gyf-dev/ImmersionBar 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 4y ago

• 5 active contributors
• Apache-2.0 licensed
• Tests present
• ⚠ Stale — last commit 4y ago
• ⚠ Concentrated ownership — top contributor handles 61% of recent commits
• ⚠ 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 gyf-dev/ImmersionBar repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/gyf-dev/ImmersionBar.

What it runs against: a local clone of gyf-dev/ImmersionBar — 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 gyf-dev/ImmersionBar | 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 ≤ 1535 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of gyf-dev/ImmersionBar. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/gyf-dev/ImmersionBar.git
#   cd ImmersionBar
#
# 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 gyf-dev/ImmersionBar and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "gyf-dev/ImmersionBar(\\.git)?\\b" \\
  && ok "origin remote is gyf-dev/ImmersionBar" \\
  || miss "origin remote is not gyf-dev/ImmersionBar (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 "immersionbar-components/src/main/java/com/gyf/immersionbar/components/ImmersionProxy.java" \\
  && ok "immersionbar-components/src/main/java/com/gyf/immersionbar/components/ImmersionProxy.java" \\
  || miss "missing critical file: immersionbar-components/src/main/java/com/gyf/immersionbar/components/ImmersionProxy.java"
test -f "immersionbar-components/src/main/java/com/gyf/immersionbar/components/ImmersionOwner.java" \\
  && ok "immersionbar-components/src/main/java/com/gyf/immersionbar/components/ImmersionOwner.java" \\
  || miss "missing critical file: immersionbar-components/src/main/java/com/gyf/immersionbar/components/ImmersionOwner.java"
test -f "immersionbar-ktx/src/main/java/com/gyf/immersionbar/ktx/ImmersionBar.kt" \\
  && ok "immersionbar-ktx/src/main/java/com/gyf/immersionbar/ktx/ImmersionBar.kt" \\
  || miss "missing critical file: immersionbar-ktx/src/main/java/com/gyf/immersionbar/ktx/ImmersionBar.kt"
test -f "immersionbar-sample/src/main/java/com/gyf/immersionbar/sample/activity/BaseActivity.java" \\
  && ok "immersionbar-sample/src/main/java/com/gyf/immersionbar/sample/activity/BaseActivity.java" \\
  || miss "missing critical file: immersionbar-sample/src/main/java/com/gyf/immersionbar/sample/activity/BaseActivity.java"
test -f "immersionbar-components/src/main/java/com/gyf/immersionbar/components/ImmersionFragment.java" \\
  && ok "immersionbar-components/src/main/java/com/gyf/immersionbar/components/ImmersionFragment.java" \\
  || miss "missing critical file: immersionbar-components/src/main/java/com/gyf/immersionbar/components/ImmersionFragment.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 1535 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1505d)"
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/gyf-dev/ImmersionBar"
  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).

ImmersionBar is an Android library (v4.4+) that manages immersive status bars and navigation bars with automatic handling of screen rotation, notch displays, and soft keyboard interactions. It allows developers to customize status bar text color and navigation bar icon color via a single fluent API call like ImmersionBar.with(this).init(), with support for Activities, Fragments, DialogFragments, Dialogs, and PopupWindows. Modular monorepo structure: immersionbar-components/ contains Fragment integration helpers (ImmersionFragment, ImmersionProxy, SimpleImmersion*), immersionbar-ktx/ provides Kotlin DSL wrappers, and immersionbar-sample/ includes a runnable demo app. Core implementation likely resides in a parent immersionbar/ module (not visible in file list but imported by others). Kotlin extension at immersionbar-ktx/src/main/java/com/gyf/immersionbar/ktx/ImmersionBar.kt wraps the Java API.

Android developers building apps targeting Android 4.4+ who need to implement immersive/edge-to-edge UIs with color customization and notch/landscape adaptation without manually managing FLAG_TRANSLUCENT_STATUS/FLAG_TRANSLUCENT_NAVIGATION and WindowManager.LayoutParams across different Android versions.

Actively maintained and production-ready: currently at version 3.2.2 with a published APK demo available. The codebase shows both Java (418KB) and Kotlin (13KB) implementations with modularization into separate packages (immersionbar-components for Fragments, immersionbar-ktx for Kotlin extensions). However, no visible CI/CD pipeline or automated tests in the file listing suggest reliance on manual release testing.

Single-maintainer project (gyf-dev) with no visible CI/CD or test infrastructure in the repo snapshot, creating maintenance and regression risk. The library targets Android 4.4+ (API 19), so it manages complex version-specific system behavior across 10+ years of OS evolution. No recent commit dates visible in the file listing, making it unclear if the project is actively monitored for emerging Android compatibility issues.

Currently at stable version 3.2.2 with published Maven Central artifacts. The README references version migration guides (README_1.x.md, README_2.x.md), and the build system shows migration from JCenter to Maven Central (gradle/publish-mavencentral.gradle). No active development signals visible in the file listing—this appears to be a maintenance-mode release with focus on compatibility rather than new features.

git clone https://github.com/gyf-dev/ImmersionBar.git
cd ImmersionBar
./gradlew build
# To run the demo app:
./gradlew :immersionbar-sample:installDebug

The project uses Gradle 7.1.2 with Kotlin 1.4.32. See gradle.properties for version configuration.

Daily commands: Build the library: ./gradlew :immersionbar-components:build and ./gradlew :immersionbar-ktx:build. Install and run the sample app: ./gradlew :immersionbar-sample:installDebug then launch from Android Studio or adb shell am start -n com.gyf.immersionbar.sample/.MainActivity. No web server or services required.

• immersionbar-components/src/main/java/com/gyf/immersionbar/components/ImmersionProxy.java — Core proxy pattern implementation that bridges Activity/Fragment lifecycle to immersion bar functionality—every contributor must understand this abstraction
• immersionbar-components/src/main/java/com/gyf/immersionbar/components/ImmersionOwner.java — Interface contract defining the immersion bar ownership model for Activities, Fragments, and other components—essential for extending the library
• immersionbar-ktx/src/main/java/com/gyf/immersionbar/ktx/ImmersionBar.kt — Kotlin DSL extension entry point providing the simplified one-line API—primary user-facing interface for the library
• immersionbar-sample/src/main/java/com/gyf/immersionbar/sample/activity/BaseActivity.java — Sample base activity demonstrating proper initialization and lifecycle integration—reference implementation for all sample activities
• immersionbar-components/src/main/java/com/gyf/immersionbar/components/ImmersionFragment.java — Fragment-specific implementation handling immersion bar state across fragment transactions and rotation—critical for fragment support
• build.gradle — Root build configuration defining Kotlin version, library version (3.2.2), and Maven Central publishing setup—all modules depend on these settings

Add a New Activity with Immersion Bar

1. Create a new Activity class extending BaseActivity (immersionbar-sample/src/main/java/com/gyf/immersionbar/sample/activity/BaseActivity.java)
2. In onCreate(), use the one-line API: ImmersionBar.with(this).statusBarColor(Color.BLUE).init() (immersionbar-ktx/src/main/java/com/gyf/immersionbar/ktx/ImmersionBar.kt)
3. Optionally override statusBarTextColor, navigationBarColor, and other bar properties (immersionbar-sample/src/main/java/com/gyf/immersionbar/sample/activity/ColorActivity.java)
4. Handle rotation by implementing onDestroy() and calling ImmersionBar.destroy(this) if needed (immersionbar-components/src/main/java/com/gyf/immersionbar/components/ImmersionProxy.java)

Add Fragment Support with Immersion Bar

1. Extend your Fragment from SimpleImmersionFragment or implement ImmersionFragment (immersionbar-components/src/main/java/com/gyf/immersionbar/components/ImmersionFragment.java)
2. In onViewCreated(), configure the immersion bar using the builder API (immersionbar-sample/src/main/java/com/gyf/immersionbar/sample/activity/FragmentOneActivity.java)
3. The ImmersionProxy automatically binds to Fragment lifecycle (onCreateView, onDestroyView) (immersionbar-components/src/main/java/com/gyf/immersionbar/components/ImmersionProxy.java)
4. No need to manually call destroy(); proxy handles cleanup on fragment destruction (immersionbar-components/src/main/java/com/gyf/immersionbar/components/SimpleImmersionProxy.java)

Customize Status Bar Text Color & Navigation Bar Icons

1. Chain .statusBarTextColor(true) for dark text, or .statusBarTextColor(false) for light text (immersionbar-ktx/src/main/java/com/gyf/immersionbar/ktx/ImmersionBar.kt)
2. Set navigation bar icon color with .navigationBarTextColor(boolean) for API 27+ (immersionbar-sample/src/main/java/com/gyf/immersionbar/sample/activity/ColorActivity.java)
3. Handle auto dark mode (Android 10+) by checking AppCompat theme preferences (immersionbar-sample/src/main/java/com/gyf/immersionbar/sample/activity/AutoDarkModeActivity.java)
4. Call .init() at the end of the configuration chain to apply all settings (immersionbar-ktx/src/main/java/com/gyf/immersionbar/ktx/ImmersionBar.kt)

Handle Soft Keyboard Interaction & Notch Support

1. Enable keyboard handling with .keyboardEnable(true) in the builder chain (immersionbar-sample/src/main/java/com/gyf/immersionbar/sample/activity/KeyBoardActivity.java)
2. Set fit system windows via .fitSystemWindows(true) to adjust padding automatically (immersionbar-components/src/main/java/com/gyf/immersionbar/components/ImmersionProxy.java)
3. Notch support is handled automatically on Android 9+; no extra config needed (immersionbar-sample/src/main/java/com/gyf/immersionbar/sample/activity/MainActivity.java)
4. Test rotation with landscape/portrait by checking sample activities (immersionbar-sample/src/main/java/com/gyf/immersionbar/sample/activity/FragmentOneActivity.java)

• Android 4.4+ (KitKat) — Status bar and navigation bar immersion support was introduced in Android 4.4; this library targets that minimum baseline
• Kotlin DSL (ImmersionBar.kt) — Provides fluent builder API and extension functions, reducing boilerplate and enabling one-line integration
• Proxy Pattern (ImmersionProxy) — Decouples immersion bar lifecycle management from Activity/Fragment, allowing reuse across different component types
• Lifecycle Callbacks — Hooks into onCreate, onViewCreated, onDestroy to automatically manage immersion bar state without manual intervention
• Maven Central Publishing — Distributes the library as a reusable artifact; developers add simple Gradle dependency without source compilation

• Proxy pattern vs direct inheritance

  • Why: Allows immersion bar support on Activities and Fragments without requiring deep inheritance hierarchies
  • Consequence: Adds an extra abstraction layer; slightly more complex internal code but much more flexible for end users

• One-line API (Kotlin DSL) vs granular Java methods

  • Why: Reduces boilerplate and matches modern Android development conventions; Kotlin is idiomatic for Android
  • Consequence: Java developers must still use the underlying immersionbar module; KTX is optional

Notch handling requires manifest configuration: The README mandates adding metadata tags like android:notch_support and notch.config to AndroidManifest.xml for Huawei and Xiaomi devices—missing these will cause notch clipping. Aspect ratio config needed for full-screen: Setting android:resizeableActivity="true" or android:maxAspectRatio="2.4" in manifest is necessary for full immersion on modern devices; without it, status/nav bars may not fully hide. KTX module is Kotlin 1.4.32 specific: The immersionbar-ktx module targets Kotlin 1.4.32; projects using newer Kotlin versions (1.5+) may face compatibility issues. No visible ProGuard config for core module: Only immersionbar-sample/ and immersionbar-components/ have proguard-rules.pro; the main immersionbar module's obfuscation rules are not in the file listing, risking reflection breakage on release builds.

• Window Translucency Flags (FLAG_TRANSLUCENT_STATUS, FLAG_TRANSLUCENT_NAVIGATION) — Core mechanism ImmersionBar uses to hide system UI and extend app content under status/navigation bars; varies between API 19–21 (flags) vs 21+ (WindowInsets) requiring version-specific branching.
• WindowInsets and Inset Listeners — API 21+ mechanism for querying safe areas and notch geometry; ImmersionBar must listen to inset changes on rotation and soft keyboard toggle to adjust layout padding dynamically.
• Fragment Lifecycle Proxying — ImmersionProxy pattern decouples immersion configuration from Fragment subclassing; allows reusable setup across different Fragment hierarchies by hooking onCreate/onViewCreated lifecycle callbacks.
• Notch Display Cutout Detection — Android 9+ (P) added DisplayCutout API to query notch coordinates; ImmersionBar uses this to avoid rendering content behind notches via manifest configuration and programmatic checks.
• Soft Keyboard Visibility Detection — ImmersionBar must detect IME show/hide events and adjust bottom padding (navigation bar size) dynamically; critical for EditText-heavy UIs to prevent keyboard overlap.
• Fluent Builder Pattern with Type-Safe Chains — ImmersionBar's API design (.transparentStatusBar().navigationBarColor(...).init()) uses builder chaining for readability; requires careful return-type design to enable method discovery and configuration validation.
• Android Aspect Ratio and Full-Screen Configuration — Modern devices (>18:9 aspect) require manifest meta-data (android:maxAspectRatio, android:resizeableActivity) to allow apps to render edge-to-edge; without these, immersion bar APIs fail silently on notch displays.

• jaredrummler/AndroidShell — Provides lower-level window flag manipulation utilities; useful for understanding the underlying SystemUI APIs that ImmersionBar abstracts.
• square/insets — Square's companion library for handling WindowInsets and edge-to-edge layouts; solves related problem of safe area padding for immersive apps.
• bumptech/glide — Mature, modular Android library with similar architecture (core + KTX extensions + sample app); demonstrates best practices for multi-module AAR distribution via Maven Central that ImmersionBar follows.
• gyf-dev/FloatingView — Sibling project by same author; likely shares similar immersive/full-screen rendering patterns and notch adaptation logic with ImmersionBar.

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 immersionbar-components module

The immersionbar-components module (ImmersionFragment, ImmersionProxy, SimpleImmersionFragment, etc.) lacks automated testing. These are critical components used across Activity, Fragment, and DialogFragment contexts. Adding instrumented tests would ensure lifecycle handling, bar configuration persistence, and orientation changes work correctly across different Android versions (4.4+).

• [ ] Create immersionbar-components/src/androidTest/java/com/gyf/immersionbar/components/ directory
• [ ] Add ImmersionFragmentTest.java to test lifecycle hooks and configuration in Fragment contexts
• [ ] Add ImmersionProxyTest.java to test bar state management and configuration application
• [ ] Add orientation change and soft keyboard tests using ActivityScenario
• [ ] Update immersionbar-components/build.gradle to include androidTestImplementation dependencies (androidx.test, espresso)
• [ ] Document test execution in README_3.x.md or TESTING.md

Add GitHub Actions CI workflow for multi-API-level testing

The repo targets Android 4.4+ (API 19+) but lacks automated CI testing across different API levels. The immersion bar implementation has version-specific behavior (notch handling, soft keyboard, dark mode). A GitHub Actions workflow would catch regressions across API 21, 28, 29, 30, 31+ without manual testing.

• [ ] Create .github/workflows/android-tests.yml
• [ ] Configure matrix build for API levels: 21, 28, 29, 30, 31, 33 using Android Emulator
• [ ] Add build step: ./gradlew build (immersionbar-sample and immersionbar-components)
• [ ] Add instrumented test step: ./gradlew connectedAndroidTest across modules
• [ ] Add ProGuard verification step since proguard-rules.pro exists in multiple modules
• [ ] Document in CONTRIBUTING.md or README that CI runs automatically on PRs

Refactor and document KTX extension API with sample usage

The immersionbar-ktx module exists with ImmersionBar.kt but has no corresponding sample code or tests. The KTX extension provides idiomatic Kotlin API but its capabilities are undocumented. Adding samples and KTX-specific tests would increase adoption and ensure the Kotlin DSL works reliably.

• [ ] Create immersionbar-sample/src/main/java/com/gyf/immersionbar/sample/activity/KtxDemoActivity.kt demonstrating ImmersionBar.kt extension usage
• [ ] Add immersionbar-ktx/src/androidTest/java/com/gyf/immersionbar/ktx/ImmersionBarKtxTest.kt with builder pattern and DSL syntax tests
• [ ] Update README.md with dedicated 'Kotlin Usage' section showing KTX extension examples vs Java API
• [ ] Add inline documentation (KDoc) to all public functions in immersionbar-ktx/src/main/java/com/gyf/immersionbar/ktx/ImmersionBar.kt
• [ ] Create samples for Fragment + KTX and DialogFragment + KTX in the sample app

• Add instrumented tests for immersionbar-components/src/main/java/com/gyf/immersionbar/components/ImmersionProxy.java lifecycle edge cases (fragment recreation, activity configuration change, back navigation) in immersionbar-sample/src/androidTest/. Currently only a placeholder ExampleInstrumentedTest.java exists.: The proxy pattern is complex; automated tests would catch regressions in Fragment lifecycle binding and prevent silent immersion bar failures on rotation.
• Document the exact manifest configuration needed for each Android OEM's notch support (Huawei, Xiaomi, Samsung, OnePlus) in a new docs/NOTCH_ADAPTATION.md file, with sample manifests for each. Currently the README only lists meta-data tags without explaining which devices they target.: Developers frequently misconfigure notch support; explicit per-OEM documentation would reduce support questions and clarify the relationship between android.notch_support vs notch.config.
• Add a Kotlin Compose example Activity to immersionbar-sample/src/main/ demonstrating ImmersionBar.with(activity).init() applied to a Compose-based UI with custom status bar color and edge-to-edge rendering.: The sample app likely uses only traditional Fragment/Activity layouts; a Compose example would help modern Android developers adopt the library without guessing Compose integration patterns.

The codebase has moderate security concerns primarily related to outdated dependencies and build tools. The most significant issues are the use of Gradle 7.1.2 and Kotlin 1.4.32, both of which are outdated and may lack recent security patches. The inclusion of a keystore file in the repository is a notable risk if it contains production credentials. The deprecated jcenter() repository should be removed. Overall security posture is acceptable for a UI library, but dependency updates and keystore management should be prioritized.

• Medium · Outdated Gradle Build Plugin — build.gradle - classpath 'com.android.tools.build:gradle:7.1.2'. The build.gradle uses Gradle plugin version 7.1.2, which is outdated. Current stable versions are 8.x. Outdated build tools may contain known security vulnerabilities and miss critical security patches. Fix: Update to the latest stable version of Android Gradle Plugin (currently 8.1.x or later). Review release notes for security fixes.
• Medium · Outdated Kotlin Version — build.gradle - ext.kotlin_version = '1.4.32'. Kotlin version 1.4.32 is significantly outdated. Current stable versions are 1.9.x. Outdated language versions may contain security vulnerabilities and lack security improvements. Fix: Update Kotlin to version 1.9.x or later. Test for compatibility with your codebase and review breaking changes.
• Low · Deprecated Maven Repository (JCenter) — build.gradle - jcenter() in allprojects repositories. The build.gradle includes jcenter() repository, which is deprecated and no longer maintained by Bintray. Using deprecated repositories may expose the project to stale or unmaintained dependencies. Fix: Remove jcenter() from the repository list. Use mavenCentral() and google() exclusively, as they are the primary maintained repositories for Android libraries.
• Low · Weak Javadoc Security Configuration — build.gradle - options.addStringOption('Xdoclint:none', '-quiet'). The Javadoc configuration disables all Javadoc linting with 'Xdoclint:none', which could hide security-related documentation issues and code quality problems. Fix: Remove or modify the Xdoclint:none option. Fix underlying Javadoc warnings instead of suppressing them. Only disable specific problematic checks if necessary.
• Low · Keystore File Detected in Repository — immersionbar-sample/keystore.jks. A keystore file (immersionbar-sample/keystore.jks) is present in the repository. If this contains production signing keys and the repository is public, it poses a security risk. Fix: Remove keystore files from version control. Add *.jks to .gitignore. Store signing keys securely outside the repository using environment variables or secure key management systems.
• Low · HTTP Repository Links in Documentation — README.md and README_1.x.md - documentation links. README contains an HTTP link (http://www.jianshu.com/p/2a884e211a62) which is not encrypted. Consider using HTTPS for all external documentation links. Fix: Update all external links to use HTTPS where available. Ensure documentation sources are accessed over encrypted connections.

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.