offline detection with queued swap interface mutations and reconcile

[mikewheeleer]

Summary

When the network drops, swap interface mutations fail silently and are lost. Detect offline/online, queue mutations while offline, and flush + reconcile on reconnect.

Why this matters

Losing user actions on a flaky network is a serious UX failure. A queue + reconcile makes the app resilient and trustworthy.

Requirements

• Detect online/offline and reflect it in the UI.
• Queue swap interface mutations while offline; persist the queue across reloads.
• On reconnect, flush in order and reconcile with server state, surfacing conflicts.
• Never double-apply a flushed mutation.

Technical guidance

• Make each queued mutation idempotent or de-duplicated on flush.
• Guard the flush so a second reconnect doesn't replay.

Edge cases — each must have a test

• go offline -> mutation queued, UI reflects offline
• reconnect -> queue flushes in order
• reload while offline -> queue persists
• flush twice -> no double-apply
• server conflict -> surfaced

Acceptance criteria

• All requirements and every edge case above implemented and covered by tests
• New unit and integration tests; existing tests still pass and no regressions
• Structured, typed errors (no leaked internals; stable codes)
• npm run lint, npm test, and npm run build all pass locally
• Code follows the repo's existing conventions; no duplication or dead code
• Short docs/comments explaining the design and any non-obvious decisions
• PR description explains the approach and includes Closes #<issue>

Out of scope

• Full CRDT sync
• Background service worker

Rewards

Part of the GrantFox OSS / Official Campaign (FWC26) — this task may be rewarded. PR quality is assessed by AI: depth, correctness under edge cases, meaningful tests, and clean design are what earn the reward. Shallow changes (typos, formatting, trivial docs) do not qualify.