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

4.8 KiB

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:

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.