Launch behaviour
- At launch the cached layout renders straight from disk. The network is never awaited.
- In the background, queued edits are pushed, then the user's layouts and the kill-switch state are fetched.
- A fetched layout is never swapped in while the user is looking at the screen. It is applied the next time the screen loads.
- Fallback chain: cached user layout, then your compiled-in default document.
Offline queue and retries
Every save or reset is marked pending on the device before any network call, so it survives a crash or relaunch. Pushes retry with backoff (1, 2, 4, 8, 16, 32, 60 s by default) on network errors, HTTP 429 and 5xx. After the last retry, sync waits for the next trigger: a new edit, the next launch, a manual flush, or the network coming back. HTTP 401 asks your token provider once more with a forced refresh. A document the server rejects (400, 413, 422) stays on the device and is not retried.
Conflicts
Each write carries the server version it was based on (baseVersion). If the server has moved
on, it answers HTTP 409 with its current copy. The default resolver keeps the edit made later, per
screen; you can pass your own resolver that keeps the local copy, takes the server's or returns a
merged document.
Versions are append-only with unique ids, so two devices saving at the same time both keep theirs.
Kill switches
A kill switch sends screens back to your default documents for every user, without deleting anything. Turning the switch off restores their designs.
| Scope | Effect |
|---|---|
| app | every screen of the app renders its default; edit mode and AI are off |
| screen | that screen renders its default |
| component | every screen whose layout uses that component renders its default |
Switches are set in the dashboard and fetched at launch (GET /kill-switches, also part of
GET /state). They take effect the next time a screen loads. Your app can also set its own flag
(forceDefaults on iOS) that acts immediately.