Kinopy
devlog
Play today's puzzle

Firestore over plain fetch

Kinopy loads Firebase Auth and nothing else from Firebase. Saving your progress is a fetch call with a token, plus a local outbox.

Kinopy uses Firebase for two jobs, signing you in and keeping your progress, and only the first one runs Firebase’s own code. The second is plain fetch calls to the Firestore REST API. This post is for anyone who builds with Svelte or Firebase, and it covers the REST client, the outbox that keeps the game playable offline, the security rules, and a small side story about reloading open tabs.

The accounts

The accounts epic (#63) merged on 19 October 2026. You can sign in with Google, and your results, streaks, boards in progress and settings follow you from one device to another. Guests play only today’s daily, and the Calendar and Endless ask them to sign in. At that PR the suite held 755 passing tests, plus 30 more that run against the real security rules in the Firebase emulator.

The game already had a small Firestore REST sender, written for the anonymous attempt log, and the spec for the epic kept the REST approach for accounts too. The only Firebase packages the game imports are firebase/app and firebase/auth.

REST was simpler and less overengineered, and I can always move to the Firestore SDK when I need to.

The size

The spec for the epic estimated that those two packages would weigh about 39 KB gzipped. The number that shipped came in smaller, as the PR measured the sign-in code, which loads after the first paint, as a 27.5 KB chunk, and that chunk holds the game’s own sign-in code as well as the Firebase code it uses.

Two habits keep it light. The game calls initializeAuth with one persistence and hands the popup resolver only to the sign-in call, because getAuth would pull in every persistence and the popup code at once. And no module in the first bundle imports the sign-in code directly, since one static import would drag Firebase into the first paint. Everything goes through one small door:

let pending: Promise<AuthModule> | null = null

export function loadAuth(): Promise<AuthModule> {
  pending ??= import('./auth')
  return pending
}

The real file also clears pending when the import fails, so the next call tries again.

The REST client

Each request asks for a fresh ID token, then sends it as a bearer token. That is the whole trick, because the security rules see the player as request.auth exactly as they would with the SDK.

const token = await tokenOf(options.idToken)
const headers = { Authorization: `Bearer ${token}` }

The attempt log uses its own sender and never calls the token getter, so it stays anonymous.

A write goes out as a :commit request with a list of writes. Each day write carries two things worth showing:

updateTransforms: [transform('updatedAt')],
currentDocument: write.updateTime === null
  ? { exists: false }
  : { updateTime: write.updateTime },

The first line asks the server to stamp the time, so a phone with a wrong clock cannot win a conflict. The second is a precondition. The write only lands if the document still has the update time that this device saw last, or if the document does not exist yet. When another device got there first, Firestore refuses, the client reads the server copy, merges it with the local one and writes again, up to three tries.

Every failure sorts into one of seven kinds, and the kind decides what happens next.

KindMeaningWhat the game does
offlineThe request never reached the serverRetries later
timeoutNo answer within 15 secondsRetries later
authNo token, or the server refused itRetries later
serverA 5xx reply, or a rate limitRetries later
conflictA precondition failedReads, merges, writes again
deniedThe rules refused the dataParks that day
invalidThe request or the reply broke the schemaReports an error

The outbox

The player never waits for the network. A change is saved on the device first, and the day’s key goes into an outbox, which is a list stored under kinopy:sync:<uid> in local storage. A key stays there until the server confirms the write, so closing the page loses nothing.

A change is saved on the device and its day key joins the outbox. A push sends the outbox to the account in one commit, and a confirmed key leaves the outbox.DeviceOutboxAccountsaves firstday keys waitone commitA key leaves only when the server confirms it.
The path of a change. The device never waits for the account.

The runner decides when to push. It waits 3 seconds after the last change, and it pushes at once when a board ends. When a push fails in a way that can pass, such as a dropped network, it tries again after 30 seconds, then 60, doubling up to 5 minutes. The outbox holds every change in the meantime, and the runner marks the sync as waiting until a push lands.

When the page hides, the runner also sends one last push with keepalive, which lets the request outlive the page. A keepalive request carries at most 64 KB, so that push keeps its writes to at most 50,000 characters of JSON, which leaves room for the REST wrapping, and the other days stay queued. The browser can still drop it, so it is best effort, and the next load pushes whatever is left.

One commit is atomic, which has a catch. A single day that the rules refuse would block every other day in the same commit. So after a repeated refusal, the push sends each day alone and parks the days that the rules still refuse. The parked days wait apart, and the rest of the outbox syncs. A commit takes at most 500 writes.

The rules

The rules need an owner check on every document, and the check for the stats was the interesting part. A profile holds stats for five modes, two levels each, and every mode keeps a spread of how many guesses a win took. The comment above those rules in firestore.rules explains the limit:

One request can evaluate at most 1000 expressions, and a check of each count in both maps passes that limit.

So the rules check the keys at each level and the length of each guess spread, and they leave the individual counts to the client, which checks them when it reads a profile. A bad count can only hurt its own owner. The check for a spread is short:

m.easy.dist.size() <= 12 && m.hard.dist.size() <= 12

The 1,000 figure is the one that comment gives, and the comment has not changed since the rules first shipped on 19 October.

The build refresh

Here is the side story. Before #96, an open tab checked /version.json every ten minutes while it was visible, and again when it came back to the screen or came back online. If the version differed, the page reloaded, so a tab left open for hours never ran old code against your account.

On 20 October (#96) I swapped the poll for a push. A visible tab now holds one EventSource stream to a /build node in the Realtime Database, and a hidden tab closes it. After each deploy, npm run refresh writes the new version to that node, and every open tab on a different build reloads. Adding --force reloads every open tab. A reload happens once per pushed value, never during a submit, and a held reload retries on a local timer without sending a request. The database rules let anyone read /build, let no browser write it, and close every other path.

const source = new EventSource(url)
source.addEventListener('put', e => apply(e, false))

That is the browser’s own EventSource, so this part needs no SDK either. A reload costs nothing, because local storage restores the board as it was.

Looking back

Between 19 and 20 October the game went from having no accounts to having sign-in, a sync layer made of fetch calls, and a push for reloads. The Firebase code that sign-in needs loads after the first paint, and everything else in this post is plain browser code.

The next post is about a sync bug where my tile moves kept undoing themselves, and the rule about where a move should live.

Sign in on two devices at kinopy.day and tell me whether your streak followed you!