Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
4 changes: 2 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -38,10 +38,10 @@ jobs:
run: chmod +x gradlew

- name: Assemble debug builds
run: ./gradlew :core:assembleDebug :opt-timber:assembleDebug :sample:assembleDebug
run: ./gradlew :core:assembleDebug :sample:assembleDebug

- name: Run unit tests
run: ./gradlew :core:testDebugUnitTest :opt-timber:testDebugUnitTest :lint:test :sample:testDebugUnitTest
run: ./gradlew :core:testDebugUnitTest :lint:test :sample:testDebugUnitTest

- name: Run Android lint
run: ./gradlew :core:lintDebug :sample:lintDebug
Expand Down
5 changes: 2 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,6 @@ Based on the [official GPT-6 Astra guide](https://developers.openai.com/api/docs
## Project Structure & Module Organization

- `core/`: overlay APIs, permission handling, and internal window/lifecycle management.
- `opt-timber/`: optional Timber logging integration, depending on `core`.
- `lint/`: Java library containing custom Android lint detectors and their tests.
- `sample/`: Android demo app; layouts are in `src/main/res/`, and displayed code examples are in `src/main/assets/`.

Expand All @@ -44,8 +43,8 @@ Java and Kotlin sources live under each module's `src/main/java/` or `src/main/k

Use JDK 17, Android SDK 36 (Build Tools 36.0.0), and the checked-in Gradle wrapper (Gradle 9.4.1). The Android modules use AGP 9.2.1 with built-in Kotlin 2.2.10 and support API 23 or later. Configure your SDK through `ANDROID_HOME` or an untracked `local.properties`.

- `./gradlew :core:assembleDebug :opt-timber:assembleDebug :sample:assembleDebug`: build libraries and the demo APK.
- `./gradlew :core:testDebugUnitTest :opt-timber:testDebugUnitTest :lint:test :sample:testDebugUnitTest`: run local tests.
- `./gradlew :core:assembleDebug :sample:assembleDebug`: build the library and the demo APK.
- `./gradlew :core:testDebugUnitTest :lint:test :sample:testDebugUnitTest`: run local tests.
- `./gradlew :core:lintDebug :sample:lintDebug`: run Android lint checks.
- `./gradlew :core:connectedDebugAndroidTest :sample:connectedDebugAndroidTest`: run instrumentation tests on a connected device or emulator.
- `./gradlew :sample:installDebug`: install the demo; launch it from the device and grant overlay permission when prompted.
Expand Down
2 changes: 1 addition & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
- Replace overlay fluent configuration, visibility getters and library-owned permission dialogs with the new state/spec API and host-owned permission flow. See the [2.x migration guide](docs/migration/2.x-to-3.0.md).
- Remove the 2.x methods outright instead of deprecating them: the `OverlayView` setters, the `OverlayViewManager` permission and display-size helpers, `PermissionRequestDialogFragment` with its strings, and the public `DraggableOnTouchListener`. `core` no longer depends on AndroidX Fragment, and `OverlayView` handles can be created only through `OverlayViewManager`.
- Rework window geometry, drag handling and managed pass-through opacity admission. A drag normalizes the spec to top-left offsets without margins; with `allowOutsideBounds` it keeps the gravity and margins. `START` and `END` now resolve correctly on the first show in an RTL configuration.
- Make the optional Timber tree lifecycle explicit, preserve logging on failed disposal, and prevent stale queued renders from affecting a reinitialized tree.
- Remove the optional Timber integration: the `overlayviewmanager-opt-timber` artifact and `DebugOverlayTree` have no replacement. With one published artifact, the JitPack dependency becomes `com.github.75py:Android-OverlayViewManager`.
- Raise minimum Android support to API 23 and modernize the build to JDK 17, SDK 36, Gradle 9.4.1 and AGP 9.2.1 with built-in Kotlin.
- Retarget the bundled lint check to `OverlaySpec.Builder.setAllowOutsideBounds` and rename its issue id from `ALLOW_VIEW_TO_EXTEND_OUTSIDE_SCREEN` to `ALLOW_OUTSIDE_BOUNDS`.
- Update CI and Java/Kotlin regression coverage, add device tests for drag geometry, cross-UID pass-through and permission flows, and add `jitpack.yml` for JDK 17 builds.
Expand Down
41 changes: 3 additions & 38 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,14 +22,11 @@ dependencyResolutionManagement {

```groovy
dependencies {
implementation 'com.github.75py.Android-OverlayViewManager:overlayviewmanager:<version>'
// Optional: the host also supplies Timber.
implementation 'com.github.75py.Android-OverlayViewManager:overlayviewmanager-opt-timber:<version>'
implementation 'com.jakewharton.timber:timber:5.0.1'
implementation 'com.github.75py:Android-OverlayViewManager:<version>'
}
```

The JitPack build of these coordinates can only be checked once a 3.0.0 tag exists. See the [sample project](sample/) for source dependencies during development.
The JitPack build of this coordinate can only be checked once a 3.0.0 tag exists. See the [sample project](sample/) for source dependencies during development.

## Initialize once per process

Expand Down Expand Up @@ -136,39 +133,7 @@ A grant can be revoked after the check. Always inspect the subsequent operation
- Geometry uses the owning window's bounds and insets. Obtain slider limits from the host window, with a compatible fallback on older supported APIs. `allowOutsideBounds` relaxes normal bounds handling; it does not guarantee placement over system bars or other restricted areas. A drag normalizes `spec` to top-left offsets without margins; with `allowOutsideBounds` it keeps the gravity and margins and only changes `x` and `y`.
- `screenBrightness` is an optional Activity-scope setting. Supplying it to an application overlay is an argument error.

Factories, operations, and `view`/`spec` access belong on the main thread. Only `state` and `lastFailure` are thread-safe handle reads. `OverlayPermission` is immutable and thread-safe. Timber's logging entry point accepts background-thread calls.

## Optional Timber overlay

Initialize the manager first, then plant one tree from the Application. Register each Activity whose visible lifetime should show the log overlay.

```java
DebugOverlayTree tree = DebugOverlayTree.init(this);
tree.setThreshold(Log.DEBUG);
tree.setMaxLines(5);
Timber.plant(tree);
```

```java
// In Activity.onCreate():
DebugOverlayTree.getInstance().register(this);
```

Same-Application `init()` is idempotent, but the host should still avoid planting the same tree repeatedly. The Timber overlay is application-scoped and requires overlay permission to show; failed shows are reported through the library logger.

To stop it, call `dispose()` on the main thread and retain the tree on failure:

```java
OverlayResult result = tree.dispose();
if (result.isSuccess()) {
Timber.uproot(tree);
} else {
Log.w("Overlay", "Disposal failed: " + result.getFailure(), result.getCause());
// Keep tree and retry only when the host requests it.
}
```

Successful disposal unregisters callbacks and clears the buffer and Activity caches. Later logs and old queued renders become no-ops; a later initialization starts a fresh lifecycle generation.
Factories, operations, and `view`/`spec` access belong on the main thread. Only `state` and `lastFailure` are thread-safe handle reads. `OverlayPermission` is immutable and thread-safe.

## Development and limits

Expand Down
20 changes: 16 additions & 4 deletions V3_0_0_PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,8 @@

## 現在の状態と今回の作業範囲

- 状態: **2026-10-31 JST: main向けリリースPR作成まで完了**。PR65の修正とPR63の最終検証記録を対向承認・CI成功後に統合し、`395f2ff10109068451611a7f3573eb75b2fa923c` から `release/3.0.0` を作成、[Release 3.0.0 PR #66](https://github.com/75py/Android-OverlayViewManager/pull/66) をmain向けに作成した。必須API23/26/35/36、183 unit tests、Debug/Release、lint、独立Java/Kotlin/R8 consumer成功。追加API31のfreeform2件はhost入力非表示による未検証として記録。mainマージ・タグ・正式配布は未実施で今回の範囲外。詳細は[最終検証記録](docs/coordination/3.0.0/2026-10-31-release-validation.md)。
- 状態: **2026-11-01 JST: [PR68](https://github.com/75py/Android-OverlayViewManager/pull/68)(Timber連携の削除)のレビュー・CI・統合待ち**。統合するとPR66のheadが変わるため、PR66のCIと承認を取り直す。現行候補は134 unit tests(core 118、lint 12、sample 4)、配布はcoreのみ。Debug/Release、lint、core単体のJava/Kotlin/R8 consumerが成功し、sample全31件をAPI36で再検証した。API23/26/35は2026-10-31の検証結果を維持し、今回は再実行していない。JitPackサービス上の確認はタグ後。mainマージ・タグ・正式配布は未実施で今回の範囲外。詳細は[Timber削除の記録](docs/coordination/3.0.0/2026-11-01-remove-timber.md)。
- 2026-10-31時点の状態: main向けリリースPR作成まで完了。PR65の修正とPR63の最終検証記録を対向承認・CI成功後に統合し、`395f2ff10109068451611a7f3573eb75b2fa923c` から `release/3.0.0` を作成、[Release 3.0.0 PR #66](https://github.com/75py/Android-OverlayViewManager/pull/66) をmain向けに作成した。必須API23/26/35/36、183 unit tests、Debug/Release、lint、独立Java/Kotlin/R8 consumer成功。追加API31のfreeform2件はhost入力非表示による未検証として記録。mainマージ・タグ・正式配布は未実施で今回の範囲外。詳細は[最終検証記録](docs/coordination/3.0.0/2026-10-31-release-validation.md)。
- 作業・統合ブランチ: `work/3.0.0`。
- 分岐元: ローカル `main` の `c71f7fb950ee2a4ce6cba00be82d1b6e02226789`。作成時のローカル `origin/main` も同一。2026-09-12 JSTのfetchでもorigin/mainは同一。
- 準備文書・共有設定を1646b3bへコミット済み。ユーザーの開始指示を受け、同コミットをorigin/work/3.0.0へ初回pushした。以降の変更は個別PRと相互承認を経由する。
Expand Down Expand Up @@ -117,12 +118,12 @@ sampleのエラーは `SampleAllOptionsActivity` と `SampleOverrideScreenBright
| T04c | 一時互換APIの最終除去 | Claude実装・Codex対向承認(実際はDevin実装・Claudeレビュー) | T07, T10 | 統合済み: PR61 2c256a8(Devin再実装、旧Claude worktreeの7d5af7b/WIPは不採用)、JVM可視性の追補PR62 208588f。両PRともCI成功。PR62はCodex承認なし・ユーザー許可でマージ |
| T05 | 監視・座標・権限境界の見直し | Claude(T05aテスト修正のみCodexが直接実施) | T04b | 実装統合済み。必須matrixの権限・実座標検証成功、追加修正PR65を497a5e2へ統合済み |
| T06 | タッチ透過・ドラッグの互換性改善 | Claude | T05b実装統合 | 実装統合済み。別UIDはPR64で検証/統合、最終drag/freeformはAPI35/36成功。PR65を497a5e2へ統合済み |
| T07 | Timber連携の安全性改善 | Claude | T01 | 段階1〜3統合済み(PR37)。寿命L1〜L7はPR54 head `c13acee`、40 tests成功・lintエラー0/警告2・3 module build成功。最終相互承認・CI成功後6c9e2aaへ統合済み |
| T07 | Timber連携の安全性改善 | Claude | T01 | 段階1〜3統合済み(PR37)。寿命L1〜L7はPR54 head `c13acee`、40 tests成功・lintエラー0/警告2・3 module build成功。最終相互承認・CI成功後6c9e2aaへ統合済み。2026-11-01: ユーザー判断でTimber連携自体を削除(PR68、レビュー/CI/統合待ち) |
| T08 | 初期化・Activity寿命・リソース解放 | Claude | T05, T06実装統合 | 統合済み(PR51 d6ccdf2、111 tests成功) |
| T09 | カスタムlintの修正・配布 | Claude | T03, T06 | 統合済み(T09a PR42 65c7e95、stage 2はPR61 2c256a8)。Kotlinの`OverlaySpec(allowOutsideBounds = true)`/`copy`は未検出で、移行ガイドに既知の制限として記載 |
| T10 | sample・README・3.0移行ガイド | Claude: sample / Codex: docs、相互レビュー | T07寿命統合、T08、T09 stage 1 | 完了: PR57 c298798 / PR56 9708061へ統合。現SHA対向承認・CI成功、API36端末3件・HTML表示・リンク確認済み |
| T11 | 3.0.0バージョン・成果物の整備 | Claude実装、Codex最終検証 | T10, T04c | 完了: 3.0.0/id10、AAR/POM/sources/consumer rules/lint.jar、独立Java/Kotlin/R8 consumer成功。JitPackサービス上のビルドはユーザー判断に従いタグ作成後 |
| T12 | 統合検証・端末試験・最終相互レビュー | 両司令塔 | T11 | 完了: PR65/63の対向承認・CI成功を確認し395f2ffへ統合。183 unit tests、必須端末matrix成功。追加API31 freeform2件は前提不成立の未検証(詳細記録参照) |
| T11 | 3.0.0バージョン・成果物の整備 | Claude実装、Codex最終検証 | T10, T04c | 完了: 3.0.0/id10、AAR/POM/sources/consumer rules/lint.jar、独立Java/Kotlin/R8 consumer成功。JitPackサービス上のビルドはユーザー判断に従いタグ作成後。2026-11-01: 配布をcoreのみとし、導入座標を `com.github.75py:Android-OverlayViewManager` へ変更、core単体consumer成功(PR68、レビュー/CI/統合待ち) |
| T12 | 統合検証・端末試験・最終相互レビュー | 両司令塔 | T11 | 完了: PR65/63の対向承認・CI成功を確認し395f2ffへ統合。183 unit tests、必須端末matrix成功。追加API31 freeform2件は前提不成立の未検証(詳細記録参照)。2026-11-01: Timber削除後の候補で134 unit tests、API36 sample全31件成功。API23/26/35は10/31の結果を維持(PR68、レビュー/CI/統合待ち) |
| T13 | release/3.0.0作成・mainへのPR | Codex、Claude確認 | T12 | 完了: 395f2ffからrelease/3.0.0を作成しmain向けPR66を作成。mainマージ・タグ・配布は未実施・対象外 |

T02とT01、T04とT07などは編集範囲が独立する場合に並列実行する。T03中のビルド検証や、T04〜T06・T08の同一coreファイル変更は直列化する。大きいタスクはファイル所有範囲が明確な小PRへ分割してよい。
Expand Down Expand Up @@ -183,6 +184,8 @@ T02とT01、T04とT07などは編集範囲が独立する場合に並列実行

### T07: Timber

2026-11-01: ユーザー判断でTimber連携自体をリリース前に削除する(PR68)。以下は削除前の作業記録として残す。

- [x] ログバッファ変更とTextView更新を安全に直列化する。
- [x] `maxLines` の0・負数・縮小時の仕様を定め、境界テストを追加する。
- [x] 高頻度ログによるUI負荷、複数行ログ、Activity登録と表示・終了を確認する。
Expand Down Expand Up @@ -227,6 +230,8 @@ T02とT01、T04とT07などは編集範囲が独立する場合に並列実行
- [x] Release AAR、sources、consumer rules、lint.jar、ライセンスを確認する。
- [x] 新しいconsumerからRelease成果物を取り込み、依存解決・R8有効ビルド・利用例を確認する。
- [x] JitPack等の配布手順・必要なJDK設定・導入座標を確認する。ここでは正式公開しない。
- [x] 2026-11-01: Timber削除後のcoreのみの配布を確認する。AAR/POM/sources/consumer rules/lint.jar、core単体のJava/Kotlin/R8 consumer成功。導入座標は公式の全モジュール形式 `com.github.75py:Android-OverlayViewManager:<version>` へ変更。
- [ ] タグ作成後、JitPackサービス上のビルドと導入座標の解決を確認する。ユーザー判断後に実施。

受け入れ条件: 3.0.0の成果物が一貫し、別consumerから利用でき、配布手順が再現可能。

Expand All @@ -240,6 +245,9 @@ T02とT01、T04とT07などは編集範囲が独立する場合に並列実行
- [x] 合意した統合SHA `395f2ff` から `release/3.0.0` を作成してpushする。
- [x] `release/3.0.0` → `main` のPR #66を作成する。版、変更要約、移行方法、検証結果、既知の制限、関連PRを記載し、Claude司令塔へ最終確認を依頼済み。
- [ ] ユーザーへreleaseブランチ、main向けPR URL、実施済み検証、残課題、利用したエージェント構成を報告する。
- [x] 2026-11-01: Timber削除後の候補で全ローカルテスト134件、lint、Debug/Release、core単体consumer、API36 sample全31件を確認する。API23/26/35は10/31の結果を維持する。
- [ ] 2026-11-01: PR68の現head対向承認・CI確認後にrelease/3.0.0へ統合し、統合SHAをPR66コメントへ記録、work/3.0.0を承認済みreleaseへfast-forwardする。merge操作はCodex。
- [ ] 2026-11-01: PR66の現headのCIと対向確認を取り直す。

受け入れ条件: 検証済みリリース候補のmain向けPRが存在する。未解決の不具合・未実施試験・承認状態を隠さない。

Expand Down Expand Up @@ -599,3 +607,7 @@ PR65はhead `ca3f7e0809a966e842d19ba7ea7d102a8ef48b86`、[Codex対向承認](htt
### 2026-10-31: T13のリリースPR作成完了

PR63 head `a47d95cb64f75fc87aa98c158b0bfc92af6b531a` の[Claude承認](https://github.com/75py/Android-OverlayViewManager/pull/63#issuecomment-6542332736)と[CI成功](https://github.com/75py/Android-OverlayViewManager/actions/runs/41193528060)を確認し、19:41:14 JSTに `395f2ff10109068451611a7f3573eb75b2fa923c` へ通常merge。承認済みheadと同一treeであることを確認し、同SHAからrelease/3.0.0を作成/push、[main向けPR66](https://github.com/75py/Android-OverlayViewManager/pull/66)を作成した。最後の計画・ログ更新はrelease向け文書PRで相互確認し、承認済みreleaseへのfast-forwardでwork/3.0.0にも同期する。製品コードを追加変更しない。

### 2026-11-01: Timber連携の削除(Codex対向レビュー待ち)

ユーザーの判断を受け、前項の「製品コードを追加変更しない」を更新し、公開前に `opt-timber` を削除する変更を[PR68](https://github.com/75py/Android-OverlayViewManager/pull/68)としてrelease/3.0.0向けに提案した。Codexが差分レビューと検証を完了した。134 unit tests、API36 sample全31件、core単体consumerが成功し、API23/26/35は10/31の結果を維持する。導入座標は `com.github.75py:Android-OverlayViewManager` へ変更し、JitPackサービス上の確認はタグ後とする。mergeするとPR66のheadが変わるため、PR66の承認とCIは取り直しになる。PR68の現head承認・CI・統合は待ち。詳細は[Timber削除の記録](docs/coordination/3.0.0/2026-11-01-remove-timber.md)。
Loading
Loading