iphone2android 0.1.0__tar.gz → 0.3.0__tar.gz

iphone2android-0.3.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: iphone2android
+Version: 0.3.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 is a toolkit for moving from an iPhone to an Android phone without leaving anything behind. It is built for Claude Code to run the move, and every command also works by hand.
+
+The official transfer (the setup wizard's "Copy apps and data", Samsung Smart Switch, OPPO Clone Phone) moves a lot, but it misses apps without an obvious match, app data, iMessage attachments, photo edits, widgets and the home screen itself. iphone2android starts from there. It reads an encrypted iPhone backup on your computer, finds what the official transfer missed, and fills the gaps on the phone over `adb`, checking each step.
+
+What it covers:
+
+- Finding the Android version of every iPhone app (Apple's app lookup, then the Play Store search) and installing the free ones
+- Messages, call history, contacts, calendars and Safari bookmarks, converted for Android and Google
+- Photos, iMessage attachments and photo edits, copied to the phone
+- The data iPhone apps keep locally, found, copied, and the account names in their settings
+- The home screen with its folders, order and widgets, and the iPhone wallpaper
+- An audit of what the iPhone had against what the phone has, before and after
+
+## With Claude Code
+
+```bash
+pip install iphone2android
+iphone2android skill          # installs the skill into ~/.claude/skills/iphone2android
+```
+
+Then ask Claude to move you from your iPhone. The skill walks the whole move in order, starting with what has to happen before the iPhone is wiped, and Claude runs each command with `--json`, reads the result, and checks the phone with screenshots. You only do what needs your hands or your consent (the backup password, accepting terms, choosing a default SMS app).
+
+## By hand
+
+You need `adb` (`brew install android-platform-tools` on macOS) with USB debugging on in the phone's developer options, and an encrypted backup (Finder, select the iPhone, tick "Encrypt local backup", Back Up Now).
+
+```bash
+iphone2android backups                        # the backups on this computer
+iphone2android extract --inventory            # asks for the backup password
+iphone2android audit --photos                 # what the official transfer missed
+
+iphone2android suggest                        # mapping.json, and mapping.draft.json for apps to review
+iphone2android find-app "App name"            # search the Play Store by hand
+iphone2android verify mapping.json
+iphone2android install --mapping mapping.json
+
+iphone2android convert --out android-import
+iphone2android media message-attachments photo-edits
+iphone2android appdata survey
+
+iphone2android accounts                       # what to sign in to again
+
+iphone2android launcher probe                 # which launcher, and which profile matches
+iphone2android layout extracted/IconState.plist --mapping mapping.json > layout.json
+iphone2android wallpaper extract
+iphone2android build layout.json --state build.json --autofill
+iphone2android check layout.json              # every page and folder against the layout
+iphone2android snapshot                       # the whole home screen as JSON
+iphone2android wallpaper set wallpaper/<image>
+```
+
+| File from `convert` | Import it with |
+|---|---|
+| `sms_backup.xml`, `calls_backup.xml` | the SMS Backup & Restore app |
+| `contacts.vcf` | Google Contacts (Import) |
+| `calendar.ics` | Google Calendar on the web (Settings, Import & export) |
+| `safari_bookmarks.html` | Chrome on a computer (Bookmarks, Import) |
+
+`iphone2android screenshot` and `iphone2android screen` show what is on the phone, and `iphone2android debloat` removes preinstalled apps you do not want (reversibly).
+
+## What cannot move
+
+- Passwords in the iCloud Keychain. Every item is sealed with a key that never leaves the iPhone, so no backup can open them. Export them with a password manager first.
+- Authenticator codes. Transfer them from the authenticator app while the iPhone still works.
+- Most app data. Android apps cannot read their iPhone version's files, so app data is copied out for an app's own import, a dedicated migrator (WhatsApp chats need one) or safekeeping. Apps that keep their data in an account only need signing in.
+- Paid apps are not installed automatically.
+
+## How the home screen is rebuilt
+
+Many launchers do not let `adb` change the layout (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. That only works with the right timings and gestures for each launcher, so they live in launcher profiles (`android/profiles/*.json`) as data, with the evidence for each. The ColorOS 16 profile was measured during a real migration on an OPPO Find X9 Pro. A few of the findings it holds:
+
+- A swipe changes page at 250 ms and is read as a drag at 400 ms.
+- A long press only opens the menu when the press, the wait and the release are sent in one adb shell.
+- A drop from the app drawer always lands on the first page, so everything is made there and carried to its page by holding at the screen edge, 0.9 seconds per page.
+- A slow hover merges an icon into a folder, while a 2 second drag onto an icon swaps them.
+- A folder dropped onto a folder merges the two, and new folders can get the same automatic name, so folders are found by position.
+- Icons cannot be dragged out of a folder, only removed inside it.
+
+The builder follows these, reads the screen again after every step, saves its progress, checks every folder by opening it, and orders each page one swap at a time. For a launcher without a profile, the skill has a calibration procedure, and `iphone2android launcher save-profile` stores the result. Profiles for other launchers are very welcome.
+
+Wallpapers come from the backup as images (iOS 16 and later) or Apple's `.cpbitmap` format (older versions), converted to PNG. `wallpaper set` copies the image to the phone and opens its "Set as" screen. Widgets are listed for placing through the launcher's widget picker.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e '.[test]'
+.venv/bin/pytest
+```
+
+The tests use synthetic databases, a fake decryptor, fake web pages for the app stores, 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). The cpbitmap layout follows [cpbitmap-to-png](https://github.com/hthetiot/cpbitmap-to-png) (MIT).

iphone2android-0.3.0/README.md

@@ -0,0 +1,96 @@
+# iphone2android
+
+iphone2android is a toolkit for moving from an iPhone to an Android phone without leaving anything behind. It is built for Claude Code to run the move, and every command also works by hand.
+
+The official transfer (the setup wizard's "Copy apps and data", Samsung Smart Switch, OPPO Clone Phone) moves a lot, but it misses apps without an obvious match, app data, iMessage attachments, photo edits, widgets and the home screen itself. iphone2android starts from there. It reads an encrypted iPhone backup on your computer, finds what the official transfer missed, and fills the gaps on the phone over `adb`, checking each step.
+
+What it covers:
+
+- Finding the Android version of every iPhone app (Apple's app lookup, then the Play Store search) and installing the free ones
+- Messages, call history, contacts, calendars and Safari bookmarks, converted for Android and Google
+- Photos, iMessage attachments and photo edits, copied to the phone
+- The data iPhone apps keep locally, found, copied, and the account names in their settings
+- The home screen with its folders, order and widgets, and the iPhone wallpaper
+- An audit of what the iPhone had against what the phone has, before and after
+
+## With Claude Code
+
+```bash
+pip install iphone2android
+iphone2android skill          # installs the skill into ~/.claude/skills/iphone2android
+```
+
+Then ask Claude to move you from your iPhone. The skill walks the whole move in order, starting with what has to happen before the iPhone is wiped, and Claude runs each command with `--json`, reads the result, and checks the phone with screenshots. You only do what needs your hands or your consent (the backup password, accepting terms, choosing a default SMS app).
+
+## By hand
+
+You need `adb` (`brew install android-platform-tools` on macOS) with USB debugging on in the phone's developer options, and an encrypted backup (Finder, select the iPhone, tick "Encrypt local backup", Back Up Now).
+
+```bash
+iphone2android backups                        # the backups on this computer
+iphone2android extract --inventory            # asks for the backup password
+iphone2android audit --photos                 # what the official transfer missed
+
+iphone2android suggest                        # mapping.json, and mapping.draft.json for apps to review
+iphone2android find-app "App name"            # search the Play Store by hand
+iphone2android verify mapping.json
+iphone2android install --mapping mapping.json
+
+iphone2android convert --out android-import
+iphone2android media message-attachments photo-edits
+iphone2android appdata survey
+
+iphone2android accounts                       # what to sign in to again
+
+iphone2android launcher probe                 # which launcher, and which profile matches
+iphone2android layout extracted/IconState.plist --mapping mapping.json > layout.json
+iphone2android wallpaper extract
+iphone2android build layout.json --state build.json --autofill
+iphone2android check layout.json              # every page and folder against the layout
+iphone2android snapshot                       # the whole home screen as JSON
+iphone2android wallpaper set wallpaper/<image>
+```
+
+| File from `convert` | Import it with |
+|---|---|
+| `sms_backup.xml`, `calls_backup.xml` | the SMS Backup & Restore app |
+| `contacts.vcf` | Google Contacts (Import) |
+| `calendar.ics` | Google Calendar on the web (Settings, Import & export) |
+| `safari_bookmarks.html` | Chrome on a computer (Bookmarks, Import) |
+
+`iphone2android screenshot` and `iphone2android screen` show what is on the phone, and `iphone2android debloat` removes preinstalled apps you do not want (reversibly).
+
+## What cannot move
+
+- Passwords in the iCloud Keychain. Every item is sealed with a key that never leaves the iPhone, so no backup can open them. Export them with a password manager first.
+- Authenticator codes. Transfer them from the authenticator app while the iPhone still works.
+- Most app data. Android apps cannot read their iPhone version's files, so app data is copied out for an app's own import, a dedicated migrator (WhatsApp chats need one) or safekeeping. Apps that keep their data in an account only need signing in.
+- Paid apps are not installed automatically.
+
+## How the home screen is rebuilt
+
+Many launchers do not let `adb` change the layout (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. That only works with the right timings and gestures for each launcher, so they live in launcher profiles (`android/profiles/*.json`) as data, with the evidence for each. The ColorOS 16 profile was measured during a real migration on an OPPO Find X9 Pro. A few of the findings it holds:
+
+- A swipe changes page at 250 ms and is read as a drag at 400 ms.
+- A long press only opens the menu when the press, the wait and the release are sent in one adb shell.
+- A drop from the app drawer always lands on the first page, so everything is made there and carried to its page by holding at the screen edge, 0.9 seconds per page.
+- A slow hover merges an icon into a folder, while a 2 second drag onto an icon swaps them.
+- A folder dropped onto a folder merges the two, and new folders can get the same automatic name, so folders are found by position.
+- Icons cannot be dragged out of a folder, only removed inside it.
+
+The builder follows these, reads the screen again after every step, saves its progress, checks every folder by opening it, and orders each page one swap at a time. For a launcher without a profile, the skill has a calibration procedure, and `iphone2android launcher save-profile` stores the result. Profiles for other launchers are very welcome.
+
+Wallpapers come from the backup as images (iOS 16 and later) or Apple's `.cpbitmap` format (older versions), converted to PNG. `wallpaper set` copies the image to the phone and opens its "Set as" screen. Widgets are listed for placing through the launcher's widget picker.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e '.[test]'
+.venv/bin/pytest
+```
+
+The tests use synthetic databases, a fake decryptor, fake web pages for the app stores, 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). The cpbitmap layout follows [cpbitmap-to-png](https://github.com/hthetiot/cpbitmap-to-png) (MIT).

{iphone2android-0.1.0 → iphone2android-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "iphone2android"
-version = "0.1.0"
+version = "0.3.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"
@@ -25,3 +25,6 @@ test = ["pytest>=8"]
 
 [tool.setuptools.packages.find]
 where = ["src"]
+
+[tool.setuptools.package-data]
+iphone2android = ["skill/SKILL.md", "android/profiles/*.json"]

{iphone2android-0.1.0 → iphone2android-0.3.0}/src/iphone2android/__init__.py

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

iphone2android-0.3.0/src/iphone2android/accounts.py

@@ -0,0 +1,33 @@
+"""The accounts the iPhone was signed in to (Google, Exchange, iCloud and others), from Accounts3.sqlite.
+
+This is the reliable list of accounts to add on Android. Searching app data for email addresses
+instead finds other people's addresses and typos. The output holds your addresses, so keep it local.
+"""
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+
+def read(db: Path) -> list[dict]:
+    con = sqlite3.connect(f"file:{db}?mode=ro", uri=True)
+    try:
+        rows = con.execute(
+            """SELECT a.ZUSERNAME, a.ZACCOUNTDESCRIPTION, t.ZACCOUNTTYPEDESCRIPTION, t.ZIDENTIFIER
+               FROM ZACCOUNT a LEFT JOIN ZACCOUNTTYPE t ON a.ZACCOUNTTYPE = t.Z_PK"""
+        ).fetchall()
+    finally:
+        con.close()
+    out = []
+    for user, desc, type_desc, ident in rows:
+        if not user:
+            continue
+        out.append({"username": user, "description": desc, "type": type_desc, "type_id": ident,
+                    "google": bool(ident and "google" in ident.lower()) or str(user).lower().endswith(("@gmail.com", "@googlemail.com"))})
+    seen, unique = set(), []
+    for a in out:
+        key = (a["username"].lower(), a["type_id"])
+        if key not in seen:
+            seen.add(key)
+            unique.append(a)
+    return unique

{iphone2android-0.1.0 → iphone2android-0.3.0}/src/iphone2android/android/adb.py

@@ -10,6 +10,25 @@ import shutil
 import subprocess
 
 
+def png_is_black(data: bytes) -> bool:
+    """True when a PNG holds only black pixels (what a locked or sleeping screen captures as)."""
+    import struct
+    import zlib
+
+    pos, idat = 8, b""
+    while pos + 8 <= len(data):
+        n = struct.unpack(">I", data[pos:pos + 4])[0]
+        if data[pos + 4:pos + 8] == b"IDAT":
+            idat += data[pos + 8:pos + 8 + n]
+        pos += 12 + n
+    try:
+        raw = zlib.decompress(idat)
+    except zlib.error:
+        return False
+    # Black rows are filter bytes (0 to 4), zero colour bytes and 255 alpha bytes, nothing else.
+    return bool(raw) and set(raw) <= {0, 1, 2, 3, 4, 255}
+
+
 class DeviceUnavailable(RuntimeError):
     """adb could not reach the phone. Raised instead of returning empty output, which would read as "nothing installed"."""
 
@@ -23,6 +42,14 @@ class Adb:
         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 screenshot(self, timeout: float = 30) -> bytes:
+        """The screen as PNG bytes (binary output, so not through run's text decoding)."""
+        cmd = [self.binary] + (["-s", self.serial] if self.serial else []) + ["exec-out", "screencap", "-p"]
+        r = subprocess.run(cmd, capture_output=True, timeout=timeout, stdin=subprocess.DEVNULL)
+        if r.returncode != 0 or not r.stdout.startswith(b"\x89PNG"):
+            raise DeviceUnavailable((r.stderr or b"").decode("utf-8", "replace").strip()[:200] or "no screenshot returned")
+        return r.stdout
+
     def shell(self, cmd: str, timeout: float = 90) -> str:
         try:
             r = self.run("shell", cmd, timeout=timeout)

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

@@ -0,0 +1,209 @@
+"""Build a home screen from a layout file, the way the launcher actually behaves.
+
+    {"pages": [["Camera", {"folder": "Social", "apps": ["WhatsApp", "Telegram"]},
+                {"widget": ["Spotify"], "size": "medium"}]],
+     "dock": ["Phone", "Messages", "Chrome"]}
+
+Each name is the app's name in the drawer. What the builder relies on (ColorOS 16, see the profile):
+
+- A drop from the drawer lands on the FIRST page's first free cell, whatever page is showing. So
+  everything is made on the first page and then carried to its page with an edge hold, one hold
+  per page, and dropped on an EMPTY cell (a folder dropped on a folder merges them).
+- Dropping a drawer result onto an icon makes a folder, and onto a folder adds to it. The new folder
+  is found by its position next to the seed icon, never by its name (auto-names collide).
+- A folder's contents are checked by opening it with a fresh navigation. Extras are removed from
+  inside the folder. Missing apps are added by dropping from the drawer onto the folder.
+- Order is fixed with Icon autofill off by a selection sort that makes one swap and then reads the
+  screen again. A swap that creates a folder stops the sort.
+
+Progress is saved after every step, so an interrupted build continues where it stopped. Widgets are
+listed for placing through the launcher's widget picker.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def entry_label(entry, prefix: str = "Folder:") -> str:
+    if isinstance(entry, dict) and "widget" in entry:
+        return f"Widget:{'/'.join(entry['widget'])}"
+    return f"{prefix}{entry['folder']}" if isinstance(entry, dict) else entry
+
+
+def is_widget(entry) -> bool:
+    return isinstance(entry, dict) and "widget" in entry
+
+
+class Builder:
+    def __init__(self, launcher, state_file: Path | None = None, log=print, retries: int = 2):
+        self.l = launcher
+        self.state_file = state_file
+        self.log = log
+        self.retries = retries
+        self.done: list[str] = []
+        self.todo: list[dict] = []
+        self.problems: list[str] = []
+        if state_file and state_file.exists():
+            self.done = json.loads(state_file.read_text()).get("done", [])
+
+    @property
+    def prefix(self) -> str:
+        return self.l.p["labels"]["folder_prefix"] if hasattr(self.l, "p") else "Folder:"
+
+    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 _find(self, page: int, label: str):
+        hits = [i for i in self.l.page(page) if i.label == label]
+        return hits[0] if hits else None
+
+    # ---------------------------------------------------------------- placing
+
+    def place_app(self, name: str) -> object | None:
+        """Drop an app from the drawer onto the first page. Returns where it landed."""
+        before = {(i.label, i.cell) for i in self.l.page(0)}
+        hit = self.l.drawer_find(name, want=name)
+        if not hit:
+            self.problems.append(f"not in the drawer: {name}")
+            return None
+        self.l.drop_from_drawer(hit)
+        new = [i for i in self.l.page(0) if (i.label, i.cell) not in before and i.label == hit.label]
+        if not new:
+            self.problems.append(f"{name}: no new icon on the first page after the drop (page full?)")
+            return None
+        return new[0]
+
+    def carry(self, item, to_page: int) -> bool:
+        """Move an icon or folder from the first page to another page, onto an empty cell."""
+        if to_page == 0:
+            return True
+        target = self.l.page(to_page) if to_page < len(self.l.pages()) else []
+        free = self.l.free_cells(target)
+        if target and not free:
+            self.problems.append(f"page {to_page + 1} is full, cannot carry {item.label}")
+            return False
+        for attempt in range(self.retries + 1):
+            src = self._find(0, item.label)
+            if not src:
+                break
+            self.l.move_to_page(src, to_page, free[0] if free else None)
+            if self._find(to_page, item.label):
+                return True
+            self.log(f"    carry {item.label} to page {to_page + 1}: retry {attempt + 1}")
+        self.problems.append(f"could not carry {item.label} to page {to_page + 1}")
+        return False
+
+    def build_folder(self, name: str, apps: list[str]) -> object | None:
+        """Make a folder on the first page from apps in the drawer, name it, and check its contents."""
+        label = f"{self.prefix}{name}"
+        existing = self._find(0, label)
+        if not existing:
+            seed = self.place_app(apps[0])
+            if not seed or len(apps) == 1:
+                return seed
+            before = {(i.label, i.cell) for i in self.l.page(0) if i.kind == "folder"}
+            hit = self.l.drawer_find(apps[1], want=apps[1])
+            if not hit:
+                self.problems.append(f"not in the drawer: {apps[1]}")
+                return seed
+            self.l.drop_from_drawer(hit, onto=(seed.x, seed.y))
+            made = [i for i in self.l.page(0) if i.kind == "folder" and (i.label, i.cell) not in before]
+            if not made:
+                self.problems.append(f"folder {name}: dropping {apps[1]} onto {apps[0]} made no folder")
+                return None
+            folder = min(made, key=lambda f: abs(f.x - seed.x) + abs(f.y - seed.y))
+            self.l.tap(folder.x, folder.y)
+            self.l.rename_open_folder(name)
+            self.l.home()
+        self.fill_folder(0, name, apps)
+        return self._find(0, label)
+
+    def fill_folder(self, page: int, name: str, apps: list[str]) -> None:
+        label = f"{self.prefix}{name}"
+        for attempt in range(self.retries + 1):
+            inside = self.l.open_folder(page, label)
+            if inside is None:
+                self.problems.append(f"folder {name} is not on page {page + 1}")
+                return
+            missing = [a for a in apps if not any(a.lower() == x.lower() for x in inside)]
+            extra = [x for x in inside if not any(a.lower() == x.lower() for a in apps)]
+            for x in extra:
+                self.log(f"    {name}: removing {x}, which does not belong")
+                self.l.remove_from_folder(page, label, x)
+            if not missing:
+                return
+            for a in missing:
+                folder = self._find(page, label)
+                hit = self.l.drawer_find(a, want=a)
+                if not hit or not folder:
+                    continue
+                if page != 0:
+                    self.problems.append(f"folder {name}: add {a} on the first page first")
+                    continue
+                self.l.drop_from_drawer(hit, onto=(folder.x, folder.y))
+        inside = self.l.open_folder(page, label) or []
+        still = [a for a in apps if not any(a.lower() == x.lower() for x in inside)]
+        if still:
+            self.problems.append(f"folder {name}: still missing {', '.join(still)}")
+
+    # ---------------------------------------------------------------- the whole layout
+
+    def build(self, layout: dict) -> None:
+        # Build back to front, so carrying an item never passes a page that is already finished.
+        for page in reversed(range(len(layout.get("pages", [])))):
+            for e in layout["pages"][page]:
+                key = f"p{page}:{entry_label(e, self.prefix)}"
+                if key in self.done:
+                    continue
+                if is_widget(e):
+                    self.todo.append({"page": page + 1, "widget": e["widget"], "size": e.get("size")})
+                    self.log(f"  widget {'/'.join(e['widget'])} ({e.get('size')}): place through the widget picker")
+                    self._mark(key)
+                    continue
+                self.log(f"page {page + 1}: {entry_label(e, self.prefix)}")
+                item = self.build_folder(e["folder"], e["apps"]) if isinstance(e, dict) else self.place_app(e)
+                if item and self.carry(item, page):
+                    self._mark(key)
+
+    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 = [x for x in self.l.page(page) if x.kind != "widget"]
+            names = [x.label for x in items]
+            if i >= len(items) or names[i] == label:
+                continue
+            if label not in names:
+                self.problems.append(f"{label} is not on page {page + 1}")
+                continue
+            folders = {x.label for x in items if x.kind == "folder"}
+            self.l.swap(items[names.index(label)], items[i])
+            after = {x.label for x in self.l.page(page) if x.kind == "folder"}
+            if after - folders:
+                self.problems.append(f"page {page + 1}: a swap created a folder {sorted(after - folders)}, stopped")
+                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, [entry_label(e, self.prefix) for e in entries if not is_widget(e)]) and ok
+        return ok
+
+    def check(self, layout: dict) -> list[str]:
+        """Compare every page and folder with the layout. Returns the differences (empty when it matches)."""
+        diffs = []
+        pages = self.l.pages()
+        for p, entries in enumerate(layout.get("pages", [])):
+            have = [i.label for i in pages[p] if i.kind != "widget"] if p < len(pages) else []
+            want = [entry_label(e, self.prefix) for e in entries if not is_widget(e)]
+            if have != want:
+                diffs.append(f"page {p + 1}: have {have}, want {want}")
+            for e in entries:
+                if isinstance(e, dict) and "folder" in e:
+                    inside = self.l.open_folder(p, entry_label(e, self.prefix)) or []
+                    if sorted(x.lower() for x in inside) != sorted(a.lower() for a in e["apps"]):
+                        diffs.append(f"folder {e['folder']}: have {inside}, want {e['apps']}")
+        return diffs