iphone2android 0.1.0__tar.gz

iphone2android-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Konstantinos Georgiou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

iphone2android-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: iphone2android
+Version: 0.1.0
+Summary: Move from an iPhone to an Android phone: messages, contacts, photos, apps and the home screen, from an encrypted iPhone backup
+Author: Konstantinos Georgiou
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/drkostas/iphone2android
+Keywords: iphone,ios,android,migration,backup,adb,sms,launcher
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: iOSbackup>=0.9.9
+Requires-Dist: pycryptodome>=3.18
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# iphone2android
+
+iphone2android moves your data from an iPhone to an Android phone using an encrypted iPhone backup on your computer and `adb` to the new phone. It converts messages, call history, contacts, calendars and bookmarks into formats Android and Google import, copies photos and the media Google Photos does not keep, installs your apps, and rebuilds your iPhone home screen on the Android launcher.
+
+## Before you wipe the iPhone
+
+Some things cannot be recovered from any backup, so move them while the iPhone still works.
+
+- Authenticator apps. Export the accounts from the iPhone app (Google Authenticator has Transfer accounts) and scan them on Android.
+- Passwords in the iCloud Keychain. A backup cannot decrypt them, because every item is also sealed with a key that never leaves the iPhone. Use a password manager or a Mac signed in to the same Apple ID to export them.
+- Tickets and passes bound to the device (transit tickets, ski passes). Move them through the provider's account.
+- Footage that exists only on the phone in apps such as action-camera apps.
+
+## Install
+
+```bash
+pip install iphone2android
+```
+
+You also need `adb` (`brew install android-platform-tools` on macOS) with USB debugging on in the phone's developer options.
+
+## 1. Make an encrypted backup
+
+In Finder (or iTunes on Windows) select the iPhone, choose "Back up all of the data on your iPhone to this Mac", tick "Encrypt local backup" and back up. Only an encrypted backup contains messages, call history and app data.
+
+```bash
+iphone2android backups          # list the backups on this computer
+iphone2android apps             # the apps that were installed (no password needed)
+```
+
+On Windows, pass `--backup-root "%APPDATA%\Apple Computer\MobileSync\Backup"`.
+
+## 2. Extract and convert
+
+```bash
+iphone2android extract --inventory      # asks for the backup password (or set IPHONE_BACKUP_PASSWORD)
+iphone2android convert --out android-import
+```
+
+| File | Import it with |
+|---|---|
+| `sms_backup.xml`, `calls_backup.xml` | the SMS Backup & Restore app on the phone (Restore, then choose the file) |
+| `contacts.vcf` | Google Contacts (Import) |
+| `calendar.ics` | Google Calendar (Settings, Import & export) |
+| `safari_bookmarks.html` | Chrome on a computer (Bookmarks, Import), then sync |
+
+Apple sometimes saves the message database in the middle of a write, so the backup copy is shorter than its own header says and SQLite refuses to open it. `convert` corrects the header in a copy and reads what is there. If that is not enough and your `sqlite3` has the `.recover` command, it uses that instead.
+
+WhatsApp chats (`ChatStorage.sqlite`) need a dedicated iOS to Android WhatsApp migrator, and Apple Notes (`NoteStore.sqlite`) need an Apple Notes parser. `extract` copies both out for those tools.
+
+## 3. Photos and media
+
+```bash
+iphone2android media camera-roll message-attachments photo-edits
+```
+
+Files are decrypted in batches, pushed to the phone and deleted, so the computer does not need room for the whole camera roll. If your photos are already in Google Photos, skip `camera-roll`. The other two are never in Google Photos (iMessage attachments, and the edited versions of photos).
+
+## 4. Apps
+
+Write a mapping from iPhone bundle ids to Android packages, using `iphone2android apps` for the list. `label` is the app's name in the Android app drawer.
+
+```json
+{"net.whatsapp.WhatsApp": {"package": "com.whatsapp", "label": "WhatsApp"}}
+```
+
+Check every package before installing. Guessed package names are often wrong, because the Android package of a bank or a local app rarely matches its iOS bundle id.
+
+```bash
+iphone2android verify mapping.json
+iphone2android install --mapping mapping.json
+```
+
+`install` opens each app's page in the Play Store app and presses Install, so it works for free apps only. Each app is checked as installed before the next one starts.
+
+To remove preinstalled apps you do not want, list them in a file and run `iphone2android debloat list.txt --keep-mapping mapping.json --dry-run`, then again without `--dry-run`. Apps are removed for the current user only, and `adb shell cmd package install-existing <package>` brings one back.
+
+## 5. Home screen
+
+```bash
+iphone2android extract                                   # also copies IconState.plist
+iphone2android layout extracted/IconState.plist --mapping mapping.json > layout.json
+iphone2android build layout.json --state build.json --autofill
+```
+
+`layout.json` lists pages of apps and folders by their drawer name, which you can edit before building. The builder adds each app from the app drawer search, reads the screen again after every drop, and saves its progress so an interrupted build continues where it stopped. Then it puts each page in order one swap at a time, and finally turns the launcher's icon autofill on to close the gaps. Do not touch the phone while it runs.
+
+Many launchers do not let adb change the layout directly (on ColorOS the launcher database and shortcut pinning are closed without root), so the builder moves icons through the screen the way a person does. It is tested on ColorOS 16 (OPPO Find X9 Pro). Other launchers name their menus differently and may need changes in `android/launcher.py`.
+
+## Limits
+
+- Only an encrypted backup has messages and app data.
+- Keychain passwords cannot be extracted (see above).
+- Paid apps are not installed.
+- The home screen builder is tested on one launcher.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e '.[test]'
+.venv/bin/pytest
+```
+
+The tests use synthetic databases, a fake decryptor, a fake `adb` and a simulated home screen, so they need no iPhone and no Android phone.
+
+## License
+
+MIT. Backup decryption uses [iOSbackup](https://github.com/avibrazil/iOSbackup) (LGPL).

iphone2android-0.1.0/README.md

@@ -0,0 +1,108 @@
+# iphone2android
+
+iphone2android moves your data from an iPhone to an Android phone using an encrypted iPhone backup on your computer and `adb` to the new phone. It converts messages, call history, contacts, calendars and bookmarks into formats Android and Google import, copies photos and the media Google Photos does not keep, installs your apps, and rebuilds your iPhone home screen on the Android launcher.
+
+## Before you wipe the iPhone
+
+Some things cannot be recovered from any backup, so move them while the iPhone still works.
+
+- Authenticator apps. Export the accounts from the iPhone app (Google Authenticator has Transfer accounts) and scan them on Android.
+- Passwords in the iCloud Keychain. A backup cannot decrypt them, because every item is also sealed with a key that never leaves the iPhone. Use a password manager or a Mac signed in to the same Apple ID to export them.
+- Tickets and passes bound to the device (transit tickets, ski passes). Move them through the provider's account.
+- Footage that exists only on the phone in apps such as action-camera apps.
+
+## Install
+
+```bash
+pip install iphone2android
+```
+
+You also need `adb` (`brew install android-platform-tools` on macOS) with USB debugging on in the phone's developer options.
+
+## 1. Make an encrypted backup
+
+In Finder (or iTunes on Windows) select the iPhone, choose "Back up all of the data on your iPhone to this Mac", tick "Encrypt local backup" and back up. Only an encrypted backup contains messages, call history and app data.
+
+```bash
+iphone2android backups          # list the backups on this computer
+iphone2android apps             # the apps that were installed (no password needed)
+```
+
+On Windows, pass `--backup-root "%APPDATA%\Apple Computer\MobileSync\Backup"`.
+
+## 2. Extract and convert
+
+```bash
+iphone2android extract --inventory      # asks for the backup password (or set IPHONE_BACKUP_PASSWORD)
+iphone2android convert --out android-import
+```
+
+| File | Import it with |
+|---|---|
+| `sms_backup.xml`, `calls_backup.xml` | the SMS Backup & Restore app on the phone (Restore, then choose the file) |
+| `contacts.vcf` | Google Contacts (Import) |
+| `calendar.ics` | Google Calendar (Settings, Import & export) |
+| `safari_bookmarks.html` | Chrome on a computer (Bookmarks, Import), then sync |
+
+Apple sometimes saves the message database in the middle of a write, so the backup copy is shorter than its own header says and SQLite refuses to open it. `convert` corrects the header in a copy and reads what is there. If that is not enough and your `sqlite3` has the `.recover` command, it uses that instead.
+
+WhatsApp chats (`ChatStorage.sqlite`) need a dedicated iOS to Android WhatsApp migrator, and Apple Notes (`NoteStore.sqlite`) need an Apple Notes parser. `extract` copies both out for those tools.
+
+## 3. Photos and media
+
+```bash
+iphone2android media camera-roll message-attachments photo-edits
+```
+
+Files are decrypted in batches, pushed to the phone and deleted, so the computer does not need room for the whole camera roll. If your photos are already in Google Photos, skip `camera-roll`. The other two are never in Google Photos (iMessage attachments, and the edited versions of photos).
+
+## 4. Apps
+
+Write a mapping from iPhone bundle ids to Android packages, using `iphone2android apps` for the list. `label` is the app's name in the Android app drawer.
+
+```json
+{"net.whatsapp.WhatsApp": {"package": "com.whatsapp", "label": "WhatsApp"}}
+```
+
+Check every package before installing. Guessed package names are often wrong, because the Android package of a bank or a local app rarely matches its iOS bundle id.
+
+```bash
+iphone2android verify mapping.json
+iphone2android install --mapping mapping.json
+```
+
+`install` opens each app's page in the Play Store app and presses Install, so it works for free apps only. Each app is checked as installed before the next one starts.
+
+To remove preinstalled apps you do not want, list them in a file and run `iphone2android debloat list.txt --keep-mapping mapping.json --dry-run`, then again without `--dry-run`. Apps are removed for the current user only, and `adb shell cmd package install-existing <package>` brings one back.
+
+## 5. Home screen
+
+```bash
+iphone2android extract                                   # also copies IconState.plist
+iphone2android layout extracted/IconState.plist --mapping mapping.json > layout.json
+iphone2android build layout.json --state build.json --autofill
+```
+
+`layout.json` lists pages of apps and folders by their drawer name, which you can edit before building. The builder adds each app from the app drawer search, reads the screen again after every drop, and saves its progress so an interrupted build continues where it stopped. Then it puts each page in order one swap at a time, and finally turns the launcher's icon autofill on to close the gaps. Do not touch the phone while it runs.
+
+Many launchers do not let adb change the layout directly (on ColorOS the launcher database and shortcut pinning are closed without root), so the builder moves icons through the screen the way a person does. It is tested on ColorOS 16 (OPPO Find X9 Pro). Other launchers name their menus differently and may need changes in `android/launcher.py`.
+
+## Limits
+
+- Only an encrypted backup has messages and app data.
+- Keychain passwords cannot be extracted (see above).
+- Paid apps are not installed.
+- The home screen builder is tested on one launcher.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e '.[test]'
+.venv/bin/pytest
+```
+
+The tests use synthetic databases, a fake decryptor, a fake `adb` and a simulated home screen, so they need no iPhone and no Android phone.
+
+## License
+
+MIT. Backup decryption uses [iOSbackup](https://github.com/avibrazil/iOSbackup) (LGPL).

iphone2android-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "iphone2android"
+version = "0.1.0"
+description = "Move from an iPhone to an Android phone: messages, contacts, photos, apps and the home screen, from an encrypted iPhone backup"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "Konstantinos Georgiou" }]
+dependencies = ["iOSbackup>=0.9.9", "pycryptodome>=3.18"]
+keywords = ["iphone", "ios", "android", "migration", "backup", "adb", "sms", "launcher"]
+classifiers = ["Programming Language :: Python :: 3", "Topic :: Utilities"]
+
+[project.urls]
+Homepage = "https://github.com/drkostas/iphone2android"
+
+[project.scripts]
+iphone2android = "iphone2android.cli:main"
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

iphone2android-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

iphone2android-0.1.0/src/iphone2android/__init__.py

@@ -0,0 +1,3 @@
+"""Move from an iPhone to an Android phone: messages, contacts, photos, apps and the home screen."""
+
+__version__ = "0.1.0"

iphone2android-0.1.0/src/iphone2android/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

iphone2android-0.1.0/src/iphone2android/android/adb.py

@@ -0,0 +1,45 @@
+"""A small adb wrapper.
+
+stdin is always closed. `adb shell` reads stdin, so inside a shell `while read` loop it would eat the
+rest of the list and only the first item would be processed.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+
+
+class DeviceUnavailable(RuntimeError):
+    """adb could not reach the phone. Raised instead of returning empty output, which would read as "nothing installed"."""
+
+
+class Adb:
+    def __init__(self, serial: str | None = None, binary: str | None = None):
+        self.serial = serial
+        self.binary = binary or os.environ.get("IPHONE2ANDROID_ADB") or shutil.which("adb") or "adb"
+
+    def run(self, *args: str, timeout: float = 90) -> subprocess.CompletedProcess:
+        cmd = [self.binary] + (["-s", self.serial] if self.serial else []) + list(args)
+        return subprocess.run(cmd, capture_output=True, text=True, timeout=timeout, stdin=subprocess.DEVNULL)
+
+    def shell(self, cmd: str, timeout: float = 90) -> str:
+        try:
+            r = self.run("shell", cmd, timeout=timeout)
+        except subprocess.TimeoutExpired as e:
+            raise DeviceUnavailable(f"adb shell timed out after {timeout}s") from e
+        # adb's own failures start with "adb:" or "error:". A failing command on the phone does not.
+        if r.returncode != 0 and r.stderr.lstrip().startswith(("adb:", "error:")):
+            raise DeviceUnavailable(r.stderr.strip()[:200])
+        return r.stdout
+
+    def installed(self, package: str) -> bool:
+        return f"package:{package}\n" in self.shell(f"pm list packages {package}") + "\n"
+
+    def screen_size(self) -> tuple[int, int]:
+        """The size touches are measured in: the override size when one is set, else the physical size."""
+        out = self.shell("wm size").strip()
+        if "x" not in out:
+            raise DeviceUnavailable(f"cannot read the screen size: {out[:80]!r}")
+        w, h = out.splitlines()[-1].split(":")[-1].strip().split("x")
+        return int(w), int(h)

iphone2android-0.1.0/src/iphone2android/android/build.py

@@ -0,0 +1,116 @@
+"""Build a home screen from a layout file, and put each page in order.
+
+    {"pages": [["Camera", "Photos", {"folder": "Social", "apps": ["WhatsApp", "Telegram"]}]],
+     "dock": ["Phone", "Messages", "Chrome"]}
+
+Each name is what to type in the app drawer search. Building never assumes where a drop landed: it
+reads the screen again after every drop and uses the real position. Progress is saved after every
+step, so an interrupted build continues where it stopped.
+
+Order is fixed afterwards by a selection sort that makes one swap and then reads the screen again.
+Several swaps from one reading do not converge, because every move shifts the grid. A swap that
+creates a folder by accident stops the sort.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def _label(entry) -> str:
+    return f"Folder:{entry['folder']}" if isinstance(entry, dict) else entry
+
+
+class Builder:
+    def __init__(self, launcher, state_file: Path | None = None, log=print):
+        self.l = launcher
+        self.state_file = state_file
+        self.log = log
+        self.done: list[str] = []
+        if state_file and state_file.exists():
+            self.done = json.loads(state_file.read_text()).get("done", [])
+
+    def _mark(self, key: str) -> None:
+        self.done.append(key)
+        if self.state_file:
+            self.state_file.write_text(json.dumps({"done": self.done}))
+
+    def add(self, name: str, page: int, onto: tuple[int, int] | None = None):
+        """Drag an app from the drawer to the page (onto a position to merge). Returns where it landed."""
+        hit = self.l.drawer_search(name)
+        if not hit:
+            self.log(f"  not in the drawer: {name}")
+            return None
+        tx, ty = onto if onto else self.l.at(0.5, 0.71)
+        self.l.drag(hit.x, hit.y, tx, ty, 1800)
+        landed = [n for n in self.l.icons(page) if n.label == hit.label]
+        return landed[0] if landed else None
+
+    def build_page(self, page: int, entries: list) -> None:
+        for e in entries:
+            key = f"p{page}:{_label(e)}"
+            if key in self.done:
+                continue
+            if isinstance(e, str):
+                r = self.add(e, page)
+                self.log(f"  {e}: {'placed' if r else 'FAILED'}")
+            else:
+                self._build_folder(page, e["folder"], e["apps"])
+            self._mark(key)
+
+    def _build_folder(self, page: int, name: str, apps: list[str]) -> None:
+        if not apps:
+            return
+        before = {n.label for n in self.l.icons(page) if n.folder}
+        first = self.add(apps[0], page)
+        if not first:
+            self.log(f"  folder {name}: cannot place {apps[0]}")
+            return
+        if len(apps) == 1:
+            self.log(f"  folder {name} has one app, placed it loose")
+            return
+        self.add(apps[1], page, onto=(first.x, first.y))
+        new = [n for n in self.l.icons(page) if n.folder and n.label not in before]
+        if not new:
+            self.log(f"  folder {name}: no folder formed")
+            return
+        # Identify the new folder by being new, never by its auto-name (two can share one).
+        self.l.tap(new[0].x, new[0].y)
+        self.l.rename_open_folder(name)
+        for app in apps[2:]:
+            target = [n for n in self.l.icons(page) if n.label == f"Folder:{name}"]
+            if not target:
+                self.log(f"  folder {name}: lost it after renaming")
+                return
+            self.add(app, page, onto=(target[0].x, target[0].y))
+        self.log(f"  folder {name}: {len(apps)} apps")
+
+    def build(self, layout: dict) -> None:
+        for page, entries in enumerate(layout.get("pages", [])):
+            self.log(f"page {page + 1}")
+            self.build_page(page, entries)
+
+    def order(self, page: int, wanted: list[str]) -> bool:
+        """Selection sort with one swap per reading. Returns False when it had to stop."""
+        for i, label in enumerate(wanted):
+            items = self.l.icons(page)
+            names = [n.label for n in items]
+            if i >= len(items) or names[i] == label:
+                continue
+            if label not in names:
+                self.log(f"  {label} is not on page {page + 1}")
+                continue
+            folders = {n.label for n in items if n.folder}
+            j = names.index(label)
+            self.l.drag(items[j].x, items[j].y, items[i].x, items[i].y, 2000)
+            after = {n.label for n in self.l.icons(page) if n.folder}
+            if after - folders:
+                self.log(f"  stopped: the swap created a folder {sorted(after - folders)}")
+                return False
+        return True
+
+    def order_all(self, layout: dict) -> bool:
+        ok = True
+        for page, entries in enumerate(layout.get("pages", [])):
+            ok = self.order(page, [_label(e) for e in entries]) and ok
+        return ok

iphone2android-0.1.0/src/iphone2android/android/debloat.py

@@ -0,0 +1,48 @@
+"""Remove preinstalled apps for the current user, without root.
+
+`pm uninstall --user 0` keeps the app on the system partition, so it can come back with
+`cmd package install-existing <package>`. Some system parts refuse and are disabled instead.
+"""
+from __future__ import annotations
+
+from .adb import Adb
+
+# Never removed, whatever the list says.
+PROTECTED = {
+    "com.google.android.euicc",  # eSIM
+    "com.android.vending",  # Play Store
+    "com.google.android.gms",  # Play services
+    "com.android.phone",
+    "com.android.settings",
+    "com.android.systemui",
+    "com.google.android.dialer",
+    "com.android.dialer",
+    "com.google.android.apps.messaging",
+    "com.android.mms",
+    "com.android.launcher",
+}
+
+
+def remove(adb: Adb, packages: list[str], keep: set[str] = frozenset(), dry_run: bool = False) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for pkg in packages:
+        if pkg in PROTECTED or pkg in keep:
+            out[pkg] = "kept"
+            continue
+        if not adb.installed(pkg):
+            out[pkg] = "absent"
+            continue
+        if dry_run:
+            out[pkg] = "would remove"
+            continue
+        r = adb.shell(f"pm uninstall --user 0 {pkg}")
+        if "Success" in r:
+            out[pkg] = "removed"
+            continue
+        r2 = adb.shell(f"pm disable-user --user 0 {pkg}")
+        out[pkg] = "disabled" if "disabled" in r2.lower() else f"failed: {r.strip()[:80]}"
+    return out
+
+
+def restore(adb: Adb, package: str) -> bool:
+    return "installed" in adb.shell(f"cmd package install-existing {package}").lower()

iphone2android-0.1.0/src/iphone2android/android/launcher.py

@@ -0,0 +1,134 @@
+"""Drive a stock home screen through its UI, which is the only way on locked-down launchers.
+
+On ColorOS (OPPO, OnePlus) the launcher database, its content provider and shortcut pinning are all
+closed to adb without root, so icons are moved the way a person moves them. Positions scale with
+the screen size. Tested on ColorOS 16 (Android 16). Other launchers need their own tuning.
+
+Rules learned the hard way:
+- Re-read the screen before every drag. The grid moves after each change.
+- Dropping an icon onto another makes a folder. Dropping onto a folder adds to it.
+- A folder is renamed by tapping its title, selecting all, typing and pressing BACK (not ENTER).
+- Icons cannot be dragged out of a folder. Long-press inside the open folder and choose Remove.
+"""
+from __future__ import annotations
+
+import time
+
+from . import ui
+from .adb import Adb
+
+
+class Launcher:
+    def __init__(self, adb: Adb, pause: float = 1.0):
+        self.adb = adb
+        self.pause = pause
+        self.w, self.h = adb.screen_size()
+
+    def _sleep(self, s: float) -> None:
+        time.sleep(s * self.pause)
+
+    # positions as fractions of the screen, measured on a 1264x2780 screen
+    def at(self, fx: float, fy: float) -> tuple[int, int]:
+        return int(self.w * fx), int(self.h * fy)
+
+    def dock_top(self) -> int:
+        return int(self.h * 0.845)
+
+    def in_dock(self, n: ui.Node) -> bool:
+        return n.y > self.dock_top()
+
+    def dump(self) -> list[ui.Node]:
+        return ui.dump(self.adb)
+
+    def home(self) -> None:
+        for _ in range(2):
+            self.adb.shell("input keyevent KEYCODE_HOME")
+            self._sleep(1.6)
+
+    def page_next(self) -> None:
+        (x1, y), (x2, _) = self.at(0.87, 0.58), self.at(0.16, 0.58)
+        # 250 ms. A slower swipe is read as a drag and does not change page.
+        self.adb.shell(f"input swipe {x1} {y} {x2} {y} 250")
+        self._sleep(1.8)
+
+    def goto(self, page: int) -> None:
+        self.home()  # HOME is page 0; swiping left from it opens the feed, not a page
+        for _ in range(page):
+            self.page_next()
+
+    def drag(self, x1: int, y1: int, x2: int, y2: int, ms: int = 600) -> None:
+        # About 600 ms merges reliably. A long hover opens the folder under the finger instead.
+        self.adb.shell(f"input draganddrop {x1} {y1} {x2} {y2} {ms}")
+        self._sleep(2.5)
+
+    def tap(self, x: int, y: int) -> None:
+        self.adb.shell(f"input tap {x} {y}")
+        self._sleep(1.8)
+
+    def icons(self, page: int) -> list[ui.Node]:
+        """Icons and folders on a page, in reading order, without the dock and the label nodes of folders."""
+        self.goto(page)
+        nodes = self.dump()
+        folder_names = {n.label for n in nodes if n.folder}
+        items = [n for n in nodes if n.clickable and n.cls in ("TextView", "FrameLayout")
+                 and not self.in_dock(n) and f"Folder:{n.label}" not in folder_names]
+        return sorted(items, key=lambda n: (n.y, n.x))
+
+    def drawer_search(self, term: str) -> ui.Node | None:
+        """Open the app drawer, search, and return the first result whose name contains the first word."""
+        self.home()
+        (x, y1), (_, y2) = self.at(0.5, 0.83), self.at(0.5, 0.32)
+        self.adb.shell(f"input swipe {x} {y1} {x} {y2} 300")
+        self._sleep(2.5)
+        nodes = self.dump()
+        field = [n for n in nodes if n.cls == "EditText"] or [n for n in nodes if n.label.lower().startswith("search")]
+        if not field:
+            return None
+        self.tap(field[0].x, field[0].y)
+        self.adb.shell("input keycombination 113 29")  # ctrl+a
+        self.adb.shell("input text " + term.replace(" ", "%s"))
+        self._sleep(2.2)
+        first = term.split()[0].lower()
+        for n in self.dump():
+            if n.cls == "TextView" and n.y < self.dock_top() and first in n.label.lower():
+                return n
+        return None
+
+    def rename_open_folder(self, name: str) -> bool:
+        field = [n for n in self.dump() if n.cls == "EditText"]
+        if not field:
+            return False
+        self.tap(field[0].x, field[0].y)
+        self.adb.shell("input keycombination 113 29")
+        self.adb.shell("input text " + name.replace(" ", "%s"))
+        self._sleep(1.2)
+        self.adb.shell("input keyevent KEYCODE_BACK")  # ENTER does not commit the name, BACK does
+        self._sleep(2.0)
+        return True
+
+    def long_press(self, x: int, y: int, seconds: float = 1.4) -> None:
+        # One shell, so the finger stays down for the whole gesture.
+        self.adb.shell(f"input motionevent DOWN {x} {y}; sleep {seconds}; input motionevent UP {x} {y}")
+        self._sleep(1.5)
+
+    def set_autofill(self, on: bool) -> str:
+        """Toggle Home screen settings > Icon autofill. Build with it off, then turn it on once to pack the grid."""
+        self.home()
+        self.long_press(*self.at(0.5, 0.54))
+        settings = [n for n in self.dump() if n.label == "Home screen settings" and n.clickable]
+        if not settings:
+            self.home()
+            return "not found"
+        self.tap(settings[0].x, settings[0].y)
+        nodes = self.dump()
+        row = [n for n in nodes if n.label == "Icon autofill"]
+        switch = [n for n in nodes if n.cls == "Switch" and row and abs(n.y - row[0].y) < 60]
+        state = "not found"
+        if switch:
+            current = switch[0].label.lower() == "on"
+            if current != on:
+                self.tap(switch[0].x, switch[0].y)
+            state = "on" if on else "off"
+        self.adb.shell("input keyevent KEYCODE_BACK")
+        self.home()
+        return state