Read the Home Screen from the connected iPhone and start a fresh draft from it. Discards any unapplied draft.

The current draft: dock, every page and the App Library-only apps, as {id, name} items (folders carry their contents, widgets their size).

Find items by name or bundle id substring.

Dominant icon color per app (family, background, hex, hue 0-360). Omit ids for every app.

Icon images for up to 24 apps, in the order given.

Set the whole top-level layout at once. pages = list of pages, each a list of ids in order (row by row). library = apps kept only in the App Library. Every top-level item and library app must appear exactly once. dock / library omitted = unchanged.

Move one item to target ('dock', 'library', 'page:N', 'folder:[:N]'), at index (0-based, default end) or just before the item with id before. 'library' = App Library only, off the Home Screen.

Make a folder at target/index holding item_ids (in order).

Rename a folder.

Remove a folder, putting its apps where it was.

File loose apps into folders: {folder name: [app ids]}. Apps join an existing folder with that name, or a new folder (2+ apps). Apps on page 1 are left alone by default.

Rainbow-sort loose apps (red -> purple, then white/gray/black). Folders and widgets go first. Page 1 is left alone by default.

A-Z sort of folders and loose apps. Page 1 is left alone by default.

A-Z inside every folder.

App Store genre per app (Apple apps are 'Apple'). This sends the bundle ids to Apple's public lookup API, so only call it when the user is fine with that. Cached locally.

Put an item in an exact spot (row 1-6, column 1-4) on a page, leaving empty spaces around it, like dragging it to an empty spot on the iPhone. Other items flow around it.

Let placed items flow with the rest again (removes their gaps).

Trade the places of two items.

Which apps get used, the top apps with where they are now, and estimated page swipes for the device vs the draft. source='device': the device's own memory reports (no setup; apps iOS keeps running for calls or in memory every day count less, listed under 'background'); source='mac': Screen Time synced to this Mac (Share Across Devices), last days days.

Most-used apps and folders onto the earliest pages, most-used apps onto each folder's first page (usage from screen_time, else the device's memory reports, else Screen Time). Widgets keep their pages; dock and App Library untouched.

Page operations: op='insert' (new empty page at page), 'move' (page -> to), 'delete' (its apps go to the App Library, like iOS).

Drop empty pages and empty folders from the draft.

Undo the last draft edit.

Redo the last undone draft edit.

Throw away draft edits and go back to the layout as read from the phone (undoable).

What applying the draft would change, any problems, and the apply_token.

Write an HTML preview (draft vs phone, moved icons outlined) and return its path.

Write the draft to the iPhone. Only call when the user explicitly asked to apply this draft. Needs the apply_token from the latest diff. Backs up first and verifies after.

Layouts saved before each apply/restore, oldest first.

Write a backup to the iPhone. Only when the user explicitly asked. Same gate as apply.