The client
A client holds a copy of the server's state and renders from it. It never decides what is true; it only decides what to show while it waits.
The replica
{ epoch, topics: per topic: { position, records } }The replica is private and read-only to application code: it is typed DeepReadonly, frozen in development, and has no exported setter. Components read it through useShared (see React). Only incoming messages change it, and every message names its topic. The function below is Twinstate's own internal code, shown to explain the rules — applications never write it:
ts
function apply(msg) {
const topic = replica.topics[msg.topic];
if (msg.reset) {
topic.records = recordsFrom(msg.ops); // the snapshot REPLACES the topic:
topic.position = { epoch: msg.epoch, rev: msg.rev }; // records not in it are gone
return;
}
// a new epoch always arrives as a reset; anything else from another epoch is stale
if (msg.epoch !== topic.position?.epoch) return requestReset(msg.topic);
if (msg.rev <= topic.position.rev) return; // duplicate or crossed in flight: ignore
for (const op of msg.ops) {
if (op.set) write(topic, op.kind, op.id, op.set); // a whole record (snapshots, creates)
if (op.patch) applyPatches(topic, op.kind, op.id, op.patch); // the changed fields only
if (op.append)
op.at === length(topic, op.kind, op.id, op.field)
? appendTo(topic, op.kind, op.id, op.field, op.append)
: requestReset(msg.topic); // should never happen; never corrupt text
if (op.del) remove(topic, op.kind, op.id);
}
topic.position.rev = msg.rev;
}- Positions are per topic. A topic opened later starts from its own snapshot, whatever revision other topics have reached; a replay on one topic is never mistaken for a duplicate because another topic is further ahead.
- A reset replaces the topic's records outright, so a record deleted while the device was away does not survive the snapshot.
- A message is applied all at once. There is no render in which half of it has landed.
Everything derived is computed, never stored. Sort orders, groupings, "is this unread", the effective value of a setting that a record may override — all are selectors over the replica. Nothing holds a second copy that could drift.
Windows (queries)
A query's topic holds a window, not a collection — over a kind, or over one parent's children:
ts
{ items: Activity[], endCursor: string | null, hasMore: boolean, loadMore(): void }itemsare in the query's order and stay live: the server sends records entering, leaving and moving as they change on any device.loadMore()asks for the next page afterendCursorand widens the window; it never reloads what is already there.- The client holds only the window, so anything global (a count, a badge) must come from a small server-computed record, not from counting
items.
The outbox
Every write — a toggle, a keystroke, a rename, a send — is a mutation, and every mutation goes through the same path:
mutate(name, args)
1. write the entry to the OUTBOX device storage (IndexedDB), first; the effect shows at once
2. send it, once written and connected patches: after a short quiet window (below)
everything else: immediately
3. the reply arrives remove the entry
on relaunch resend whatever is still there, in orderThe outbox exists for one reason: nothing you did is lost when the app dies. iOS kills backgrounded web apps freely; a browser tab can be closed mid-type. Because the entry is written to storage before anything else, a change survives the process ending at any instant. Offline is not a separate mode — the outbox simply waits.
Three rules make resending safe and cheap:
- A resend is harmless. Mutations are numbered per client, and the server remembers — on disk, so across its restarts too — which it has already applied, answering a resend with the original result (see the server). So a resent patch cannot land a second time over a newer write another device made meanwhile. (With a store that has no
transaction, a server crash between writing a turn's data and recording its ids can let one resend run again — harmless, except that a create can bring back a record another device removed before the resend arrived; see the server.) - A patch coalesces only into the outbox's last entry, and patches wait briefly before sending. (A patch is a
patchmutation — what a text field bound to a kind sends.) A patch is written to storage at once (durable within milliseconds; see storage) but sent only after 300ms without another change to it; if the last entry is an unsent — and not held — patch of the same record and the same fields, the new value replaces it, otherwise the new patch is appended. So typing continuously — online or offline — produces one entry and one send per pause, not one per keystroke. Any other mutation queued behind a waiting patch sends it at once, first; so does the page being hidden. Order is never changed: text typed after a "send" lands after the send, never in front of it. - An entry older than 24 hours is not sent automatically, and nothing after it is either. The outbox is ordered, so a held entry is a barrier: later entries wait behind it (new typing included), because sending them first would reorder whole-value writes. The held entry is shown ("unsent changes from Tuesday — send / discard"), never silently dropped (unless the app opted out with
discard(), below). See below.
The display overlay
What you see is not the replica alone:
display = pending effects, applied in order, on top of the replicaEach mutation in the outbox contributes its effect (see concepts). Effects can write any kind, lazy ones included: records they produce for a lazy kind live in an optimistic layer keyed by kind and id, independent of topics, until the server's own record arrives — which is what lets an entry render something this device just created. The overlay stores intents, not values, and is re-run whenever the replica changes. That is what keeps it correct when other devices' changes land while yours are waiting:
replica outbox display
you set title "A" old [A] A ← effect(old)
the phone's "B" arrives B [A] A ← effect(B): yours still on top
your done arrives A or B [] replica ← the server's order decides- Your pending change is never overwritten by an older value while it waits.
- When it is confirmed, the display is the replica alone — which already holds the result, because the data always arrives before the done.
- If the server rejects it (
invalid,unavailable,error, or a reason its mutation declares), the entry leaves the outbox, the effect stops applying, and the display falls back to the replica; the control shows the rejection as an inline error — or, if no mounteduseMutationis waiting for it, the app'soutboxUI does (see React). An entry an older bundle wrote that this one cannot parse is never sent: it is held; one a newer bundle wrote is never in this tab's hands (see below).
Three quick toggle clicks, each sent before the next (so they do not coalesce), show all three states immediately and settle with no flicker:
click 1 replica off pending [on] display on
click 2 replica off pending [on, off] display off
click 3 replica off pending [on, off, on] display on
done 1 replica on pending [off, on] display on
done 2 replica off pending [on] display on
done 3 replica on pending [] display onConfirmation
A mutation is confirmed by the reply to its own request, not by anything in the broadcast. The broadcast says what changed, for everyone; the reply says "your request succeeded" or "it was rejected, because…", for you alone. Using the reply covers what a broadcast cannot:
- a mutation that changes nothing (pinning something already pinned) produces no broadcast, but still gets a reply, so it still leaves the outbox;
- a rejection carries a reason, which only the sender needs;
- other devices never need to know which client caused a change.
If the reply is lost (the app was killed after the server applied the change), the entry is still in the outbox, is resent on relaunch, is recognised as already applied, and is confirmed by the reply to the resend.
Confirmation means "accepted", not "finished". Work the server does after its turn — a payment settling, an export — arrives later as state on a record (see async work). A screen simply renders that state. Code that needs to wait for it, to navigate once an order is placed, awaits it:
ts
const p = await client.until(payment, paymentId, (p) => p.status !== 'paying');until holds the record's topic open while it waits, resolves with the record once the predicate holds (at once, if it already does), and takes an AbortSignal to give up.
Reconnecting
Keeping the connection alive is the transport's job, not the client's: the twinstate/ws/client adapter reconnects when the socket closes, when heartbeats stop, when the network comes back (online), when the page is restored (pageshow), and when the page becomes visible again (visibilitychange — what an installed iPhone web app fires on returning from the background). An application's own transport brings its own liveness. Whenever the transport reports onOpen, the client:
- sends its
hello, with its lock revision, and waits forready; on the firstready, it claims the device for its revision before going on (see several versions on one device), and stops instead (outdated) if a newer version is live there. If the server answers thehellowithincompatible(see running clients), the client stops, exactly as anoutdatedtab does (several versions on one device): its transport stopped, its locks and outboxes released for a tab that can send them (already stored, so nothing typed is lost), read-only, reportsincompatiblethroughuseSyncStatus(), and calls the requiredonIncompatible(with the reasonincompatible;outdatedis the other, below). Whether to reload, and when, is the app's decision — a reload loses scroll positions, open panels and anything else held only in the page, so Twinstate never makes it. A banner ("a new version is available — reload") is the usual answer. Additive deploys never get here; only a change this bundle cannot read does; - re-subscribes every held topic with that topic's position, asking for its missed events too (
events: true) only if it was live on the connection that dropped — never on the page's first connection, nor for a topic first opened from the cache — receiving either what it missed, events included, or a reset (see the server); a root created offline, whose create has not arrived yet, answersabsentand stays subscribed; - resends the outbox, in order. Because the subscriptions went first on the same ordered stream, the data a resend's
donerefers to — even thedoneof a mutation the server had already applied — always arrives before it.
While disconnected, the replica is necessarily out of date, and the UI must say so. Stale data is only ever "disconnected and showing it", or, with the persisted cache, "started from the cache, not yet resumed". useSyncStatus() reports both (see React).
The 24-hour hold
Outbox entries exist to bridge short gaps: an app kill, a tunnel, a laptop asleep overnight. An entry that has waited longer than 24 hours (measured from when it was created) is held for confirmation instead of being sent.
- Why at all: applied last-write-wins, a week-old intent would overwrite what you have done since, and a week-old send would post into a conversation that has moved on.
- Why never dropped by default: losing work is the failure the outbox exists to prevent. Held entries are shown with send and discard, as a list, in outbox order, by the app's required
outboxUI (see React) — an app cannot forget to show them, because leaving that out does not compile. An app may instead opt out withoutbox={discard()}, which discards them as they are held — a choice written in the code, never a default (see what it costs). Send — your explicit go-ahead — releases them in place and in order, with their 24-hour clocks restarted; you can release the whole list or the entries from the top down, never one from the middle (that would reorder). A released entry either was never sent (its id is above the server's mark, so it runs) or was sent before the device went quiet (the server answers with the result it recorded —ok, or the original rejection — even if it has restarted since, because that record is on disk). Either way it applies at most once, and in order. Discard removes an entry; the next one stays held until you release it too. (Each outbox persists its next-id counter next to its entries, so ids never repeat, adopted outboxes included.) - Why 24 hours: it covers the overnight case (8–12 hours) without asking, and matches the field — Workbox's documented retry window, Replicache's client retention, Stripe's idempotency-key lifetime.
Old entries after an upgrade
An outbox entry remembers the lock revision it was written under. While its bundle stays compatible with the server, it is sent as it is (see running clients). An older tab never sends a newer bundle's entries: on a device, only the newest version writes (see several versions on one device). After an upgrade, the new bundle parses every entry written by an older revision strictly, before sending it: an argument it does not know means the entry does not fit. (A lenient parse would drop the unknown key — typed text among them — and send the rest.) A missing argument that the new schema defaults is fine: adding a defaulted argument, the change changing a schema recommends, leaves every pending entry sendable. An entry that does not fit is held as "made by an older version" — never sent half understood, and never dropped unless the app chose discard(). It cannot be sent again; it is shown with its content, in the same outbox UI, to copy or discard, so whatever you typed can still be recovered by hand.
Because meaning cannot be parsed, the rule on the other side is a convention: a mutation whose meaning changes gets a new name, so entries of the old one never fit.
Unlike the 24-hour hold, a held old entry is not a barrier: it will never apply, so nothing behind it is reordered against it. Entries behind it that depended on it are sent, and if they fail for that reason, they are rejected and shown in the same UI.
Several versions on one device
After a deploy, a device can have tabs of two versions open at once: an old tab left open, and a new one that loaded the new bundle. On a device, only the newest version writes — the rule Replicache and Firestore follow too (a newer client takes over the device's local data, and older tabs are told to update):
- A tab claims the device for its revision once the server accepts it — on its first
ready, never before (an offline tab, or one the server answersincompatible, claims nothing, so a stale cached bundle cannot stop tabs the server still serves). It claims in this order: it takes a shared Web Lock named for its revision (twinstate:<name>:rev:<revision>,<name>being the registry's), which the browser releases the moment the tab is gone; then announces itself on aBroadcastChannel; then asksnavigator.locks.query()which revisions are held. Taking the lock first means no other tab's query can miss it. Only then does it re-subscribe, send its outbox or write the cache (the reconnect steps below wait for it). Every tab — claimed or not, online or not — starts listening on the channel first, then queries once, and again on each announcement it hears, so no announcement falls between the two. There is no stored "newest" value to go stale: the newest version is the highest revision a live, accepted tab holds. - A tab that sees a higher live revision stops —
outdated— and so does a tab the server findsincompatible, whether itshellowas answered so or it received a record it cannot parse. (A singlesubscribeormutateansweredincompatible— reserved, for refusing one kind later — refuses only that one, the connection staying open.) Both stop the same way, for good (until reloaded, never resuming on their own), in this order: it stops its transport (stop()), waits for its pending outbox writes to commit, and stops writing outboxes, so nothing more is sent or written and nothing already accepted bymutateis dropped; then releases its revision lock, every outbox lock it holds — its own and any it adopted — and its waiting requests. The newest tab adopts those outboxes and sends their entries whenever it is online, parsing them strictly like any older entries (above); a frame the stopped tab had already sent and the newest tab resends carries the sameclientIdand mutation id, so the server applies it once. From then on the tab is read-only: it writes no cache, shows its data marked stale, reportsoutdatedorincompatiblethroughuseSyncStatus(), and callsonIncompatiblewith that reason, so the app can show its update prompt and disable editing. Amutatecalled anyway is refused locally —useMutation'serrorandclient.mutate's rejection carry the same reason — and writes nothing, so nothing piles up in a tab nobody reloads. - Reloading brings the newest bundle, which is a tab like any other.
So an older tab never overwrites what a newer one did on the same device, and never holds entries it cannot send: they are always in the newest version's hands. If the newest tab closes before sending them, its outbox waits like any closed tab's, for the next tab of that version — the one the stopped tab's reload opens. Across devices, an older bundle that is still compatible keeps writing as usual: it sends named fields only, so it never touches a field it does not know, and two devices editing the same field is the ordinary last-write-wins race.
Storage
The outbox lives in IndexedDB, written with strict durability (the transaction completes once the write reaches the disk, which localStorage never promises), so it holds as much as the origin's quota allows and serializes off the main thread. mutate applies its effect at once and returns; the entry is sent only after its write has committed, so nothing reaches the server that a crash could still lose on the device. The one window this leaves is the few milliseconds between mutate and the commit: a tab killed in exactly that moment loses that change. To keep it out of the common case, pending writes are flushed when the page is hidden or unloaded (visibilitychange, pagehide), so a mobile browser putting the app in the background, which is when iOS kills a PWA, almost never races a write (a page killed the instant it is hidden can still lose the change being written). (This replaces an earlier design that kept the outbox in localStorage for its synchronous write: that guaranteed the last keystroke, but serialized a large text on the main thread on every change, against a small quota shared by every tab; Replicache, Zero and PowerSync keep their pending writes in asynchronous storage too.) The storage option takes any store with the same asynchronous shape (an in-memory one in tests). Every name Twinstate uses on the device starts with twinstate:<name>: (the registry's name), so it never collides with the app's own keys — the optional device state utility's included — nor with another Twinstate app on the same origin.
Several tabs. The outbox database is shared by every tab of the origin, so each tab keeps its own outbox under its own key (with its own clientId), and no two tabs ever write the same key. A tab holds a Web Lock (navigator.locks) named after its outbox for as long as it lives, and it acquires that lock before its outbox key first exists: mutations made in the instant before the lock is granted wait in memory, then go to the key. So a key is never visible without its lock being held. Every tab queues a waiting lock request on every other outbox it knows of (found at start, or when a tab announces it on the device's channel: each tab listens on that BroadcastChannel before it reads the database, and announces its outbox once its first write has committed, so none falls between the two), so it is granted the moment that outbox's tab is gone or stops (see several versions on one device) — immediately, not at the next start. A tab adopts an outbox it is granted only if it has not stopped and the outbox was written by its own revision or an older one — entries it can read. Otherwise it releases the lock at once, without touching the outbox, and does not ask for it again: a stopped tab leaves every outbox to the newest tab, and an outbox a newer revision wrote (whose tab closed, or after a rollback) waits for a tab of that revision or newer. It keeps holding the lock, resends its entries under their original clientId and mutation ids (so the server's deduplication still applies, and each done names its clientId), and deletes the key when empty. Adopted entries join this tab's display overlay at once, and they are sent merged with this tab's own unsent entries: the two queues each keep their own order, and between their heads the older entry (by creation time) goes first — a merge, never a re-sort, so a clock that steps backwards cannot put a later id of one outbox ahead of an earlier one. An old value from a closed tab therefore never lands after newer typing this tab has not sent yet; against writes already sent, it is the ordinary last-write-wins race between writers. Closing a tab with unsent text therefore loses nothing either.
Safari's storage rules. In Safari the browser, script-writable storage — localStorage and IndexedDB, so the outbox and the cache — is deleted after seven days of Safari use without a visit to the site. A web app added to the home screen counts only its own days of use, so it is not purged for being unused. Either may be evicted under storage pressure; navigator.storage.persist() makes that rarer.
The persisted cache
Designed, not built yet. Opt-in, one option: the app starts with data before it connects, and reads offline.
ts
createTwinClient(twin, {
transport,
onIncompatible,
cache: indexedDbCache(twin, {
kinds: {
// every kind a client can receive: the fields that may be stored on a device, or false
settings: ['sort'],
note: ['title', 'updatedAt', 'pinned'],
noteBody: ['text', 'images', 'related'],
image: ['name', 'url'],
secret: false, // never stored
},
maxBytes: 50_000_000, // beyond it: topics under another cache key drop first, then lazy ones, least recently opened first
}),
});
client.clearCache(); // e.g. behind a "forget this device's data" settingA wipe holds across tabs. The cache stores a generation, a random id. Every tab remembers the generation it started under, and every cache write checks it in the same transaction. clearCache deletes every saved topic and replaces the generation, in one transaction — and every open tab, the one that called it included, then stops writing for the rest of its life (its live replica is untouched, but writing it back would undo the wipe). Only a tab opened afterwards starts a new cache, as it would on a fresh device. An app that wants caching off for good removes the cache option too.
The framework decides how the cache is used, and that is not configurable. The cache is a starting point, never a source of truth:
- At startup, the client reads the
instanttopic and the topics the first screen preloads, fills the replica with them, and renders at once, marked stale. Every other cached topic stays in IndexedDB, untouched — not read, not subscribed — until an entry preloads it, and then it renders from the cache at once and is resumed the same way. So memory and the network follow what is open, not what was ever cached. Each topic read is subscribed with its saved position, like a reconnect but withoutevents: true: the server replays the changes missed (never the events — they happened before this page was watching), or sends a reset (a server restart, a position older than the ring). Either way the topic ends on the server's data; cached data is corrected, never trusted over the server. - What is saved: the records of the kinds confirmed for storage, embedded ones included — nothing else, and never a
serverOnlyfield, which is not on the client to save.memoryOnlyfields are saved like any other: they are the last value the server sent, stale-marked and corrected on resume like everything else (dropping them would leave a resumed topic with defaults the replay never corrects). - Every field is a decision, checked by the compiler.
kindsmust name every kind a client can receive, and a stored kind must list every field a client sees. A kind added to the registry, or a field added to a stored kind, fails to compile until someone decides: the error readsconfirm "pinned" may be stored on devices: add it here, or set note: false. There is no per-field "no": a stored record missing a field would resume with the field at its default and never be corrected (replay sends only later changes). A field that must not be stored goes in a kind that isfalse, or isserverOnlyso it never reaches the device at all. - An embedded record is stored with its topic only if its own kind is confirmed and every record in the topic that refers to it is of a confirmed kind. An image a secret record refers to is never written to the device, even when note bodies use images too.
- A topic keeps its position only if it is saved whole, in one IndexedDB transaction. A topic holding a kind set to
false(theinstanttopic with one sensitive kind, say) is saved without a position: its stored kinds render from the cache, and it is resubscribed from nothing, so its snapshot replaces them. A position is only ever resumed for exactly the records it describes. - A cached topic is used only if its key matches. Each saved topic stores one cache key, computed at build time from what decides how its records were saved: the versions of the kinds the topic holds, the fields
kindsallows to be stored for them, and the cache's own format. A tab whose key for that topic matches renders it at once and resumes it from its saved position. Any other topic is deleted and loaded from the server like an uncached one — never rendered in a shape this version did not save, because a resume would never correct a field an older version left out. The key is per topic, so a change to one kind refetches only the topics that hold it; online, that costs one wait for the network, and offline, those topics are unavailable until the device reconnects. Once it has claimed the device (on its firstready, after checking that no newer version is live — a stopped tab touches no cache; an offline tab sweeps later), a tab also deletes every saved topic whose key it would not compute today — reading only the keys, kept in a small index beside the topics — so data of a dropped or renamed kind, or of a kind now set tofalse, never outlives the next launch. An older tab open beside a newer one has stopped and writes nothing (see several versions on one device), so two versions' copies never fight. - Eviction is harmless. If the browser clears storage (see Safari's rules above), the app starts as it does without a cache and takes a fresh snapshot. The cache asks
navigator.storage.persist()on first write, to make that rarer; nothing depends on the answer. - Writes are lazy. A topic is written at most about once a second while it changes, and when the page is hidden. Losing the last second of cache to a kill costs only a slightly longer replay; the outbox, not the cache, is what makes writes durable, written with strict durability and flushed when the page is hidden.
The app decides the policy: whether there is a cache at all, which fields, how much, and when to wipe it. Application code never reads the cache directly: useShared returns cached records the same way it returns live ones, and useSyncStatus() says which they are — the one signal for "this may be out of date", whether the data came from the cache or the connection dropped (see React).
Several tabs, without a leader. Each tab keeps its own connection and its own live replica, as without a cache; tabs never read live state from each other. Any tab may write a topic, but only if its position is newer than the one stored under the same cache key — checked and written in the same IndexedDB transaction — so two tabs writing at once leave the newer copy. A copy under another key is always overwritten, whatever its position. Positions order by rev within an epoch, and epochs by the server's start time, which epochs carry. A wrong guess (a server clock that stepped backwards) could only keep an older, correct copy, which resumes or resets like any other. So there is no leader election, no lease and no BroadcastChannel — the handoffs where multi-tab caches have their bugs (Firestore's primary-tab lease, for one) do not exist. The cost is one socket per tab.
The one implication the framework cannot remove: cached records are on the device, readable by anyone who can read its storage. That is why the cache is opt-in, per kind, and wipeable, and why whether an application uses it is a decision for that application, not a default.