[Sync Framework] Build centralized sync framework in src/lib/sync/

[Michael-Obele]

Overview

Build the centralized sync framework in src/lib/sync/ — the foundation for all app migrations. No app changes in this PR, just the framework code.

Design doc: docs/plans/2026-06-21-sync-framework-design.md

What to build

Client-side (src/lib/sync/client/)

• sync-manager.svelte.ts — SyncManager<TStores> class using Svelte 5 $state in class fields
  • Reactive state: needsBackup, isBackingUp, isSyncing, lastSyncAt, syncError
  • Methods: syncOnMount(), handleManualBackup(), handleAutoBackup(), handleSync(), markDirty(), destroy()
  • Reads/writes through svelte-idb stores (db.store.getAll(), db.store.put(), db.store.clear())
  • Uses $state.snapshot() before writing reactive data to IndexedDB
• merge-strategies.ts — timestampMerge, serverWins, localWins + customMerge() hook
  • MergeStrategy interface with merge(local, server, storeName) method
• triggers.svelte.ts — AutoBackupTrigger, PollingTrigger, ManualTrigger
  • AutoBackupTrigger: debounced timer, watches needsBackup via $effect, checks isAuthenticated
  • PollingTrigger: interval + exponential backoff on failure (base * 2^failures, capped at max)
  • ManualTrigger: no automatic sync
• types.ts — SyncConfig, SyncStatus, StoreMap types

Server-side (src/lib/sync/server/)

• create-load-query.ts — createLoadQuery() factory generating query() functions
  • Maps store names to Prisma findMany calls with where: { userId }, include, orderBy
  • Returns empty arrays for unauthenticated users
• create-backup-form.ts — createBackupForm() factory generating form() functions
  • Single hidden field with serialized JSON (progressive enhancement compatible)
  • Server handler parses JSON, validates with Valibot, saves to Prisma in transaction
• create-backup-command.ts — createBackupCommand() factory generating command() functions
  • Accepts structured object directly (programmatic, for auto-backup)
  • Validates with Valibot, saves to Prisma in transaction
• prisma-helpers.ts — generic upsert/replace/delete helpers
• types.ts — LoadConfig, BackupConfig types

Root

• index.ts — barrel exports for client + server
• README.md — framework documentation + migration guide

Key design decisions

• Uses svelte-idb (createReactiveDB + liveAll()) for local persistence — replaces PersistedState wrapper
• form for manual backup (progressive enhancement), command for auto-backup timer (programmatic)
• query for loading data (confirmed supported in SvelteKit 2.27+)
• Class-based with $state fields (Svelte 5 class reactivity — confirmed in docs)
• Fresh start acceptable — new svelte-idb DB names, no migration from old PersistedState keys

Testing

• Unit tests for merge strategies (timestamp, serverWins, localWins, custom)
• Unit tests for SyncManager (mock svelte-idb + mock remote functions)
• Unit tests for trigger classes (AutoBackupTrigger timer, PollingTrigger backoff)
• bun check passes with 0 errors
• svelte-autofixer passes with 0 issues

References

• Design doc: docs/plans/2026-06-21-sync-framework-design.md
• svelte-idb docs: https://idb.svelte-apps.me/
• SvelteKit remote functions docs: https://svelte.dev/docs/kit/remote-functions
• Svelte 5 $state in classes: https://svelte.dev/docs/svelte/$state#Classes

Blocked by

None — this is the first PR in the migration sequence.