Sync across Chromes

butter is built to make "open a new tab on any of my Chromes and see the same dashboard" feel effortless. There are two sync layers — one on by default, one a Pro feature — and a small set of things that intentionally don't sync today.

Layer one: Chrome sync (free, automatic)

Every value stored under butter's sync: storage prefix rides on Chrome's built-in sync — the same system that syncs your bookmarks, autofill, and open tabs across devices. Three things live in there:

• Layout — every widget on the dashboard, its position, size, and per-instance settings.
• Mode — light / dark / system.
• Theme choices — which of the eight themes you picked for light and for dark.

The advantages of riding Chrome sync: no account on our side, no extra signup, no servers we'd need to keep running. The disadvantages: it only works if you're signed into Chrome with sync enabled, and Chrome enforces small per-extension quotas you can theoretically hit if you keep a hundred widgets on a long dashboard.

Most people won't ever touch a quota; if you do, the Pro layer is designed for it.

Layer two: butter cloud sync (Pro, opt-in)

Pro users can turn on cloud sync from Settings → Account once signed in. When on, butter mirrors the same payload (layout + mode + theme choices) to a row in our Supabase database, keyed to your account. Two things this gets you that Chrome sync alone doesn't:

• Cross-browser portability. Sign into butter from a different Chrome profile (or a different machine without Chrome sync enabled) and your dashboard pulls down on first open.
• Conflict detection — not conflict resolution. Every push includes the version the client last saw, and if another device wrote in between, the server returns the new version and a conflict flag. Be clear-eyed about what happens next, though: in the steady-state loop the client adopts the server's version number and retries the same payload — last-writer-wins, the other device's edit is overwritten. The interactive "pull and reconcile" step only happens when you first enable sync on a device. Simultaneous two-device edits on a new-tab dashboard are rare, which is why we've accepted this for v1; a real merge strategy is a follow-up.

How the cloud sync loop works

Once enabled on a device, a small CloudSyncManager sits behind the dashboard and:

• Reconciles on boot. When the new tab opens, it checks the server for a newer version. If found, it pulls the cloud payload and applies it to the local stores.
• Pushes on change. A 1.5-second debounce coalesces rapid edits, so dragging a widget around the grid doesn't burn twenty server versions — only the final position pushes.
• Avoids echo-pushes. While a reconcile is applying cloud state locally, the push loop is paused — so adopting a pulled payload doesn't immediately bounce back up as a new write.

Each device generates a stable per-install ID the first time you turn sync on. The ID is stored locally, never in the synced payload, and only ever shown as a "this was written by your other device" hint around conflict prompts.

What syncs at each tier

The cloud-sync payload is at schema v3. What rides on it depends on which tier of sync you've turned on — and, for widget content, on a second toggle:

"Opt-in" means turning on cloud sync alone does not upload your todo lists or scratchpad notes. They only join the payload when you also flip Sync widget content — a separate, per-device toggle that appears under the cloud-sync switch and is off by default, so enabling sync never silently starts uploading notes.

Pomodoro state is deliberately device-local even with Pro cloud sync on — sharing a running timer across machines would mean the alarm fires on a Chrome you're not using.

Sign-out behaviour

• Cloud-sync devices stop pushing. Signing out clears your butter session and the per-provider OAuth tokens (GitHub / Linear / Google Calendar) — without a session, no push can authenticate. The local sync bookkeeping itself (the enabled flag, last-seen version, last-synced timestamp) is not wiped, so when you sign back in on the same device, sync resumes from where that device left off.
• Your data isn't deleted. The cloud row stays — sign back in and it returns. There's no in-product deletion flow yet; to actually delete the row (and the rest of your account's server-side data), email support@trybutter.xyz.
• Chrome sync is independent. Signing out of butter doesn't affect Chrome's own profile sync — your local layout continues to ride on it.

---