From 64451142034ed386aaccde075bff5419b67c2e3a Mon Sep 17 00:00:00 2001
From: ncode <durankievg@gmail.com>
Date: Wed, 16 Sep 2026 21:46:34 +0300
Subject: [PATCH] Document TCL device quirks found during on-device
 verification

Two device-level issues cost real debugging time and neither is an app bug:

- adb could not open the phone: Ubuntu's udev rules match vendor AND
  product, and list only older TCL products, so nothing matched 1bbb:0c01.
- A blank grey window: TCL's AppBootManagerService refuses to let the app
  bind the WebView renderer service while the display is dozing, so the
  page never parses. No crash, no JS error, empty document.title, and the
  failure is sticky for the process lifetime.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CLAUDE.md | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index bb66f92..01e59be 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -108,6 +108,39 @@ installs over Phase 1's without an uninstall and drill progress survives.
 - `android/app/src/main/java/dev/ncode/sp404layers/MainActivity.java` — inset bridge
 - `android/app/src/main/AndroidManifest.xml` — `android:screenOrientation="portrait"`
 
+## Device notes (TCL 50 PRO NXTPAPER 5G, Android 16 / API 36)
+
+**adb needs a udev rule.** The phone is USB `1bbb:0c01`. Ubuntu's
+`android-sdk-platform-tools-common` matches vendor *and* product, and lists only
+older TCL products, so nothing matched and the device node stayed `root:root`.
+Fixed with a vendor-wide rule (product IDs change with USB mode):
+
+```
+echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="1bbb", MODE="0660", GROUP="plugdev", TAG+="uaccess"' \
+  | sudo tee /etc/udev/rules.d/51-android-tcl.rules
+sudo udevadm control --reload-rules && sudo udevadm trigger
+```
+
+It lives in `/etc/udev` so apt upgrades don't overwrite it. The `uaccess` tag
+grants the logged-in session access, so no logout is needed.
+
+**A blank grey window means the screen was off when the app started.** TCL's
+`AppBootManagerService` refuses to let the app bind the WebView's sandboxed
+renderer process while the display is dozing:
+
+```
+W/AppBootManager: Type[TYPE_SERVICE];Result[false];
+  Target[org.chromium.content.app.SandboxedProcessService0];
+  Caller[dev.ncode.sp404layers];Reason[screen_off & caller care]
+E/cr_ChildProcessConn: Failed to establish the service connection.
+```
+
+With no renderer the page never parses, so there is no crash, no JS error, an
+empty `document.title`, and DevTools `Runtime.evaluate` hangs. The failure is
+sticky for the life of the process — reopening from Recents keeps the grey
+window. Wake and unlock the phone first, then `am force-stop` and relaunch.
+This is an OEM policy, not an app bug, and it only bites when launching over adb.
+
 ## Gotchas
 
 - The reference's multitouch relies on `touch-action:none` on `.unit` plus