Mirror / Mirrored state
Where each kind of state belongs
A mirror observes fields without claiming ownership—your Model and update remain the owner. Choose the store that matches who needs the value and whether edits must converge across devices:
| State | Owner | Store |
|---|---|---|
| Filter, sort, page, search text, open panel | Local Model | URL via Mirror.url |
| Preferences, draft, collapsed sidebar | Local Model | KeyValueStore via Mirror.kv |
| Cart or preference read by SSR or scripts-off forms | Local Model | Cookie via Mirror.cookie |
| Client-authored state that converges across devices | foldkit-sync | Durable ordered log |
| Cache of server-owned records | foldkit-remote | Server database |
mirror.contract registers each mirrored field as local in Module.manifest, and Module.validate reports a key-value mirror whose MirrorRestored message is missing from your Message union. Each URL query key belongs to at most one mirror per application.
How corrupt or overflowing storage recovers
Because mirrored values are copies of local state rather than unsubmitted server mutations, recovery favors safety over keeping stale payloads:
- Version mismatch or bad JSON: A stored key-value document from another version, another
scope, or malformed JSON is removed and ignored rather than crashing startup. - Store failures: Read or write failures on browser storage are absorbed so the application keeps running.
- Back to defaults: Returning every field in a slice to its initial value removes the key-value entry cleanly.
- Server rendering: Outside a browser, the URL mirror skips DOM writes safely.
When to use Sync, Remote, or a Router instead
- Two tabs or devices must merge edits: A mirror overwrites with the latest value; use Replicated state when edits must converge.
- The value is a server record: Keep only the record's ID in the URL (
?projectId=p1) and fetch the record with Server-derived state. - The value belongs in the URL path: A Foldkit router owns the URL path; a mirror manages only the query keys you name and composes cleanly alongside
route.query(schema).
Next
- See a working URL filter and draft mirror in
examples/todo-app. - Wire multiple mirrors and integrations in one list with Wiring.
- Read the full
Mirror.url,Mirror.kv, andMirror.cookieAPI in thefoldkit-mirrorREADME.