fix(settings): wait for the initial client snapshot

[SaKaNa-Y]

Important

Please take a moment to read this. Thank you!

I should include a brief explanation of the problem in my own words in every PR. If that explanation is missing, please @mention me and do not merge this PR until I have added it. You may also leave this PR unaddressed (because this means I have not fulfilled my responsibilities as the author).

If my explanation is unclear or difficult to follow, please ask me to clarify or provide reproduction steps or supporting evidence.

I welcome suggestions and counterarguments, especially questions about anything I may have overlooked. (Your feedback helps me learn and improve. 🙏)

I hold myself to this standard for every PR, regardless of its size.

Problem

When a devframe client uses settings immediately after connecting, await settings.set('theme', 'dark') can finish before the initial server snapshot arrives. That snapshot then restores the old value. An immediate read can also return an empty store, and an immediate deletion can be undone.

Settings supplied an empty initial value to shared state, which resolves before the server snapshot. Wait for trust and the initial snapshot before running settings operations. Use an empty object only when the snapshot is absent. Propagate initialization errors and clear the cached promise so the next operation can retry.

Verification

• Delayed-snapshot regression tests: five failures before the fix; all ten settings tests pass after it. Coverage includes both scopes, concurrent first operations, missing stores, static mode, trust, retry, and later remote updates.
• Built package over WebSocket and SSE: first read, write, and delete pass for project and global settings; server and client values agree after synchronization.
• pnpm lint, pnpm knip, pnpm test, pnpm typecheck, and pnpm build pass. Full suite: 1,645 passed, 13 skipped. Build: 28 tasks passed.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
devframe	Skipped		Oct 2, 2026 2:24pm UTC