Repository Instructions

Startup Checklist

Run git status --short at the start of every session.
Investigate uncommitted files before changing anything.
Do not revert user work unless explicitly asked.
If the work you completed is coherent and low-risk, try to make a sane atomic commit for your own changes.
Read TODO.md, WORKLOG.md, and docs/android-screenshot-research.md before doing substantial work.
Also read docs/android15-rooted-hook-plan.md and docs/lsposed-hook-blueprint.md before starting rooted Android implementation work.

For a normal third-party app on stock Android, there is no public SDK path that cleanly says: "keep this overlay visible on screen, but exclude it from full-display screenshots while preserving the pixels underneath."
MediaProjection is the public API for full-screen capture, but it does not expose per-layer exclusion.
FLAG_SECURE and View.setContentSensitivity(...) can hide a window from screenshots/media projection, but that is not the same as compositor-level filtering of the overlay while revealing underlying app content.
Android's internal/system capture stack does support excluded layers via hidden/private APIs. That is the closest match to the X11 compositor-plugin approach.

Stock app path: accept a compromised behavior, likely via MediaProjection plus an overlay and careful UX tradeoffs.
Rooted-device path: prefer a privileged implementation using KernelSU/Shizuku/LSPosed hooks or a small system component, then exclude the preview layer in the screenshot pipeline.
System/OEM path: implement the preview as a privileged/system overlay and exclude its layer in the screenshot pipeline.
If exact behavior is mandatory, bias toward AOSP/SystemUI/framework work, not a Play Store-only app architecture.

Target device is rooted with KernelSU.
LSPosed is available.
Shizuku is available.
This means hidden APIs, privileged binder calls, framework hooks, and even replacing/intercepting the screenshot flow are realistic options.