arc-to-zen-migration

# Arc → Zen Migration ## Overview Zen has no Arc importer. But Zen (Firefox-based) keeps its whole tab/folder/workspace state in one compressed file you can script against, so Arc spaces can be rebuilt in bulk — folders become folders, not flat pins. **Read side (Arc):** `~/Library/Application Support/Arc/StorableSidebar.json` — plain JSON holding every space, folder, and pinned tab. No manual pasting needed. **Write side (Zen):** `<profile>/zen-sessions.jsonlz4` — Mozilla-lz4 (`mozLz40\0`) compressed JSON. **Tools:** - `scripts/arc_extract.py` — reads Arc's sidebar, returns each space as a nested tree. - `scripts/zen_session.py` — read/write Zen's mozlz4 session + folder/tab/essential builders. - `scripts/migrate.py` — end-to-end: Arc space → Zen workspace (preserves nested folders). - `scripts/migrate_example.py` — manual fill-in template (when there's no Arc file, e.g. user pastes URLs). ## When to Use - "Migrate my Arc workspaces/spaces to Zen" - "Bulk add folders / pinned tabs / essentials to Zen" - Recreating Arc's folder structure inside a Zen workspace Not for: bookmarks (use Arc export HTML → Zen bookmark import) or passwords (use a password manager / keychain export). ## The Iron Rule **Zen MUST be fully quit (Cmd+Q) before writing.** It rewrites the session on exit and will clobber your changes otherwise. **Always `backup()` first** — a wrong schema corrupts the session; the `.bak` restores instantly. ## Workflow (automatic — Arc installed) 1. **Quit Zen (Cmd+Q)** — non-negotiable (see Iron Rule). 2. **Preview:** `python3 scripts/migrate.py --list` prints Arc spaces ↔ Zen workspaces. 3. **Migrate everything from zero:** `python3 scripts/migrate.py --all --favorites` — creates a Zen workspace per Arc space (with Arc's emoji icon), imports folders + pins, and adds Arc's global Favorites as global essentials. 4. **Or one space:** `python3 scripts/migrate.py "Home" --favorites` (creates the workspace if missing; `--zen "Name"` maps to a differently-named one; `--essentials N` promotes the first N top-level pins to essentials). 5. **Reopen Zen, verify.** Re-runnable — `clear_workspace` wipes the target first. Restore the `.bak` if wrong. **Mapping Arc → Zen:** space `list` → folder (nesting preserved) · space top-level tab → regular pin · global Favorites (`topApps`) → global essentials. ## Workflow (manual — no Arc file, user pastes URLs) Use `migrate_example.py`: fill `ESSENTIALS`/`PINS`/`FOLDERS`, quit Zen, run. Screenshots of the Arc sidebar are enough to fill it. **If Zen's schema drifted** (script misbehaves): make ONE folder with 2 tabs by hand in Zen, quit, `zen_session.py <profile> --dump`, compare the live `folders[]`/`groups[]`/`tabs[]` shapes, update the builders. ## Schema (Zen 1.20.x / Firefox 151) A **folder = two synced records** sharing one `id`, plus member tabs: | Where | Key fields | |---|---| | `folders[]` | `id`, `name`, `workspaceId`, `collapsed`, `parentId:null`, `emptyTabIds:[]`, `userIcon` | | `groups[]` | `id` (same), `name`, `color:"zen-workspace-color"`, `collapsed` | | `tabs[]` (member) | `groupId:<folder id>`, `zenWorkspace:<space uuid>`, `pinned:true`, `zenEssential:false` | - **Essential:** `zenEssential:true`. **Scoped by CONTAINER (`userContextId`), not `zenWorkspace`** — this is the #1 gotcha. With `zen.workspaces.separate-essentials=true` (Zen default), an essential shows only in workspaces whose `containerTabId` matches its `userContextId`; `userContextId:0` = the default container = the first/Home workspace. To make essentials **global** (Arc-style, same in every space), set `zen.workspaces.separate-essentials=false` (via `user.js`) and use `userContextId:0` / `zenWorkspace:null`. For a **per-workspace** essential, set `userContextId` to that workspace's `containerTabId`. - **Plain pin:** `zenEssential:false`, `zenWorkspace:<uuid>`, no `groupId`. Scoped by `zenWorkspace` (works with `userContextId:0`). - **Workspace** lives in `spaces[]`: `{uuid, name, icon(emoji), containerTabId, position, theme}`. `ensure_workspace()` creates one if absent. - **Ordering** = tab array order. `tab.index` is the active history-entry pointer (set to 1), NOT position. - IDs are `<epoch_ms>-<counter>`. Tabs need only a minimal `entries:[{url,title,triggeringPrincipal_base64:"{\"3\":{}}"}]`; Firefox fills the rest on load. - Skip `arc://*` URLs — they don't resolve in Zen. ## Library Quickref ```python from zen_session import ZenSession, find_profiles s = ZenSession(find_profiles()[0]) s.backup() home = s.workspace_by_name("Home") s.clear_folders(workspace=home) # idempotent re-runs s.add_essential("https://discord.com/") # global top icon s.add_tab("https://news.com/", workspace=home) # plain pin fid = s.add_folder("Finance", home) s.add_tab("https://sheet/", workspace=home, folder_id=fid) s.save() # Zen must be quit ``` ## Common Mistakes - **Writing while Zen runs** → changes vanish on quit. Quit first. - **Folder in only one array** → ghost/empty folder. Always write BOTH `folders[]` and `groups[]` (the library does). - **Tab missing `zenWorkspace`** → tab lands in the wrong/no space. Set it (essentials use `null`). - **liblz4 not found** → `brew install lz4` (mac) / `apt install liblz4-1` (linux); fix the path list in `zen_session.py` if needed. - **No backup** → re-run with `backup()`; keep the `.bak` until verified.