Files
faceclaw/docs/validation-phone-dnd.md

91 lines
4.8 KiB
Markdown

# Phone Do Not Disturb and notification wake
## Behavior
Faceclaw automatically follows **Android's current Do Not Disturb interruption
filter** for notification-triggered screen wake. No separate Faceclaw setting or
notification-policy modification is needed.
- Phone DND active and glasses asleep: a mirrored notification does **not** wake
the glasses or open a sleeping-screen popup. The notification is not dismissed
on the phone and stays available in the Notifications app/status tray.
- Glasses already awake: popups keep their normal behavior, including the visible
app background and the existing source filters/display timeout. DND does not
force an awake screen off or steal focus.
- DND off: new eligible notifications wake normally. Silenced notifications are
not kept in a wake backlog and disabling DND does not replay them.
- Priority-only, total-silence and alarms-only filters all count as DND. Android
priority exceptions do not make a mirrored notification wake the glasses.
- App-generated notification popups also respect DND while asleep, including
Nightscout alerts; those local-only popups are not retained for replay. The
dedicated Timers alarm engine and manual/ring/head-up wake are unchanged.
- iOS Focus/DND synchronization is **not implemented** by this Android reader;
the non-Android reader returns false and preserves existing behavior.
Reading the filter is read-only. No setter, policy-access permission request,
new broadcast receiver or polling loop is introduced. If the Android service or
filter cannot be read, the reader reports DND inactive/unknown and preserves the
previous wake behavior; it does not pretend to know an unavailable phone state.
## Race handling
The native listener captures wake eligibility before posting its asynchronous
notification callback. The TypeScript bridge forwards that immutable flag. The
controller combines it with a fresh DND read on JS delivery and retains the
restriction through the existing 500 ms/foreground-service popup delay. Reposts
can restrict a pending notification but cannot make a DND-silenced pending alert
eligible to wake by shortening or retaining its timer.
Immediately before waking, the controller checks DND again. This covers both
DND becoming active during a delay and DND being disabled after a notification
arrived silently. The flag limits **wake**, not a popup on an already-awake
screen. On listener reconnect, the existing recent-notification reconciliation
samples the current phone filter; it cannot reconstruct historical DND changes
while the listener/process was disconnected.
## Validation
Commands from the repository root:
```sh
npm test
npm exec -- tsc --noEmit
npm run lint
npm run test:kotlin
git diff --check
```
Baseline on `build/all-features` commit `54ba6b4f`: 1,335 tests, 1,332 passed,
3 skipped, no failures. With the feature, the full suite passes 1,351 tests
(1,354 total, 3 skipped), with no failures. TypeScript `--noEmit` and lint pass;
lint retains five warnings in untouched files and no warning from this feature.
The targeted wake/bridge/delay suite passes all 23 tests; the initial broader
regression selection also passed all 62 tests covering controller behavior,
delay/reposts, source filters, modal queue/backdrop and existing shell consumers.
New wake-policy tests were observed failing first (DND caused an unwanted wake,
arrival metadata was lost, and reposts could unsilence a delayed popup), then
passing after implementation. Native-boundary tests use the actual transpiled
bridge with a fake Android boundary; Kotlin source-contract checks do not prove
an Android compilation or actual OEM DND behavior.
Native Kotlin tests were attempted but cannot start in this environment:
`JAVA_HOME is not set and no 'java' command could be found in your PATH.` No APK,
physical phone/glasses test or release is claimed by these checks.
## Device acceptance checks before release
1. Grant the app its usual notification-listener access and connect the glasses.
2. With glasses asleep, enable each supported Android DND mode and send a
notification from an enabled source. Verify the glasses remain asleep and
the notification can still be opened manually from the Notifications app.
3. Turn DND off: verify no old notification wakes the glasses. Send a new
notification and verify normal popup/wake and return-to-sleep behavior.
4. With the glasses already awake, enable DND and send a notification. Verify
the normal popup and visible app background, with no focus-stealing wake.
5. Enable/disable DND during the popup delay, including a foreground-service
placeholder and updates under the same notification key. Verify no delayed
DND arrival wakes the glasses after the restriction changes.
6. Check local-only app notification wake, normal manual/ring/head-up wake,
Timers, disabled sources, notification withdrawal and listener reconnect.