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:

StateOwnerStore
Filter, sort, page, search text, open panelLocal ModelURL via Mirror.url
Preferences, draft, collapsed sidebarLocal ModelKeyValueStore via Mirror.kv
Cart or preference read by SSR or scripts-off formsLocal ModelCookie via Mirror.cookie
Client-authored state that converges across devicesfoldkit-syncDurable ordered log
Cache of server-owned recordsfoldkit-remoteServer 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