From 5b8a5b90afed8cfe05e4db7f899f8b5e4b13b617 Mon Sep 17 00:00:00 2001
From: Jack Singer <jacobsinger22@gmail.com>
Date: Mon, 27 Jul 2026 13:43:19 -0500
Subject: [PATCH 1/2] Realtime: hold the reload while this client's own writes
 are in flight
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fixes rows popping out and back in when you add several quickly. Measured on a
live app: a row the user had already added was absent from the screen for 200ms
before reappearing.

It is a lost-update race, not latency. The doorbell says "something changed"
without saying which row, so an app reloads its whole list on every ping. A
reload issued while the app's own inserts are still in flight comes back WITHOUT
them, and replaces what is on screen with a snapshot missing rows the user has
already added. An instantaneous network would not help: the snapshot legitimately
lacks uncommitted rows, so speed cannot fix it.

The SDK is the one place that sees both sides of the race — it issues every write
and it owns the broadcast handler. So it now withholds the reload signal while
this client's writes are landing and fires once when they drain, plus a short
trailing coalesce so a burst collapses into one reload (the trigger fires per
changed ROW, so a bulk write produces N pings for one logical refresh). A ceiling
bounds the hold, otherwise continuous local editing would starve the app of other
users' changes.

Chosen over the alternatives because it needs no new API, no prompt rewrite, and
no server change — which means it fixes apps that ALREADY EXIST, on their next
publish. Every other approach (a row id in the payload, a merge-by-id helper, a
live-list store) requires new app code, so it only helps newly generated apps.
Those remain worth doing for the wasted-bandwidth problem, which this does not
address: a ping still triggers a full table reload, just never a racing one.

Writes are counted in proxyFetch rather than in the entities layer because both
styles we teach — supabase.from(...).insert(...) and entities.x.create(...) —
funnel through that fetch, and only one of them goes through entities. A test
covers the raw-supabase path for exactly that reason.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/client.ts           |  85 ++++++++++++++-
 src/reload-race.test.ts | 227 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 310 insertions(+), 2 deletions(-)
 create mode 100644 src/reload-race.test.ts

diff --git a/src/client.ts b/src/client.ts
index a6e822b..5d27db9 100644
--- a/src/client.ts
+++ b/src/client.ts
@@ -30,6 +30,16 @@ const GATEWAY_API = "v1";
 // used, and the server never returns a token), so it's never exposed there.
 const EU_SESSION_KEY = "bool_eu_session_token";
 
+/** Collapse a burst of doorbell pings into one reload. The trigger fires once per
+ * changed ROW, so a bulk write produces N pings for what the app should treat as
+ * a single refresh. */
+const PING_COALESCE_MS = 50;
+
+/** Never hold a ping longer than this, even with writes still in flight —
+ * otherwise someone editing continuously would stop seeing other people's
+ * changes for as long as they kept typing. */
+const MAX_HOLD_MS = 2000;
+
 /** True when `host` is a single-label deployment subdomain of `appHost` (e.g.
  * "acme.bool.so" under "bool.so") — the exact shape the platform proxy rewrites
  * to /served/<label>/… keyed on the request host. Mirrors `deploymentSlugFromHost`
@@ -264,6 +274,31 @@ export function createBoolClient(config: BoolClientConfig): BoolClient {
 
   // Route REST + Storage through the gateway; leave everything else (the
   // realtime WebSocket, in particular) connecting directly to Supabase.
+  // ── The reload race ────────────────────────────────────────────────────────
+  // The doorbell says "something changed" without saying WHICH row, so an app
+  // reloads its whole list on every ping. If that reload is issued while the
+  // app's own writes are still in flight, the server answers WITHOUT them — and
+  // the app replaces what's on screen with a snapshot missing rows the user has
+  // already added. They vanish, then reappear on the next ping. Adding three
+  // todos quickly is enough to see it.
+  //
+  // It's a lost-update race, not latency: even an instantaneous network returns
+  // a snapshot that legitimately lacks uncommitted rows, so no amount of speed
+  // fixes it.
+  //
+  // The SDK is the one place that sees both sides — it issues every write AND
+  // owns the broadcast handler. So hold the reload signal while this client's
+  // writes are landing, then fire once when they drain. App code is untouched:
+  // the existing `subscribe(() => load())` pattern simply stops flickering.
+  let pendingWrites = 0;
+  const drainWaiters = new Set<() => void>();
+
+  function noteWriteSettled(): void {
+    pendingWrites = Math.max(0, pendingWrites - 1);
+    // Copy before iterating: a waiter may unsubscribe during the callback.
+    if (pendingWrites === 0) for (const wake of [...drainWaiters]) wake();
+  }
+
   const proxyFetch = (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
     const raw =
       typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
@@ -276,11 +311,19 @@ export function createBoolClient(config: BoolClientConfig): BoolClient {
       // credentials:include so the live-gate identity cookie flows to the
       // gateway (same-origin or custom-domain); the viewer token covers the
       // cross-origin preview.
-      return fetch(`${GATEWAY}/_bool/${GATEWAY_API}/db${url.pathname}${url.search}`, {
+      const call = fetch(`${GATEWAY}/_bool/${GATEWAY_API}/db${url.pathname}${url.search}`, {
         ...init,
         headers,
         credentials: "include",
       });
+      // Count writes so doorbell pings can wait for them. Counted HERE rather
+      // than in the entities layer because both styles we teach —
+      // `supabase.from(...).insert(...)` and `bool.entities.x.create(...)` —
+      // funnel through this fetch, and only one of them goes via entities.
+      const method = (init?.method ?? "GET").toUpperCase();
+      if (method === "GET" || method === "HEAD") return call;
+      pendingWrites++;
+      return call.finally(noteWriteSettled);
     }
     return fetch(input as RequestInfo, init);
   };
@@ -598,13 +641,51 @@ export function createBoolClient(config: BoolClientConfig): BoolClient {
   const subscribeToChanges = (
     listener: (payload: BoolChangePayload) => void,
   ): (() => void) => {
+    let held: BoolChangePayload | null = null;
+    let heldSince = 0;
+    let flushTimer: ReturnType<typeof setTimeout> | null = null;
+
+    function flush(): void {
+      if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+      }
+      const payload = held;
+      held = null;
+      heldSince = 0;
+      if (payload) listener(payload);
+    }
+
+    function scheduleFlush(): void {
+      if (flushTimer) return; // a flush is already pending; it'll take the latest
+      flushTimer = setTimeout(flush, PING_COALESCE_MS);
+    }
+
+    function onPing(payload: BoolChangePayload): void {
+      held = payload;
+      if (!heldSince) heldSince = Date.now();
+      // Wait for this client's own writes to land — but not past the ceiling, or
+      // continuous local editing would starve the app of other users' changes.
+      if (pendingWrites > 0 && Date.now() - heldSince < MAX_HOLD_MS) return;
+      scheduleFlush();
+    }
+
+    const onDrain = (): void => {
+      if (held) scheduleFlush();
+    };
+    drainWaiters.add(onDrain);
+
     const channel = db
       .channel("bool:" + schema)
       .on("broadcast", { event: "*" }, (msg) =>
-        listener((msg as { payload?: BoolChangePayload }).payload ?? {}),
+        onPing((msg as { payload?: BoolChangePayload }).payload ?? {}),
       )
       .subscribe();
+
     return () => {
+      drainWaiters.delete(onDrain);
+      if (flushTimer) clearTimeout(flushTimer);
+      held = null;
       void db.removeChannel(channel);
     };
   };
diff --git a/src/reload-race.test.ts b/src/reload-race.test.ts
new file mode 100644
index 0000000..c89dbd3
--- /dev/null
+++ b/src/reload-race.test.ts
@@ -0,0 +1,227 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import { createBoolClient, type BoolClientConfig, type BoolChangePayload } from "./client";
+
+// The reload race that makes rows pop out and back in.
+//
+// The app reloads its whole list on every doorbell ping. A reload issued while
+// the app's own writes are still in flight comes back WITHOUT them, and replaces
+// what's on screen — so rows the user already added vanish until the next ping.
+// The SDK holds the ping until its own writes drain, then fires once.
+//
+// These drive the real client with `fetch` stubbed, and control exactly when each
+// write resolves, so the race is deterministic rather than timing-dependent.
+
+const CONFIG: BoolClientConfig = {
+  supabaseUrl: "https://upstream.supabase.test",
+  supabaseAnonKey: "anon-key",
+  schema: "bool_abc",
+  appOrigin: "https://bool.test",
+  slug: "my-app",
+};
+
+/** Writes park until released, so "in flight" is something we decide. */
+let releases: Array<() => void> = [];
+let respond: (url: string, init?: RequestInit) => Response;
+
+beforeEach(() => {
+  releases = [];
+  respond = () => new Response("[]", { headers: { "content-type": "application/json" } });
+  globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url =
+      typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    const method = (init?.method ?? "GET").toUpperCase();
+    if (method !== "GET" && method !== "HEAD") {
+      await new Promise<void>((r) => releases.push(r));
+    }
+    return respond(url, init);
+  }) as unknown as typeof fetch;
+  (globalThis as any).sessionStorage = {
+    getItem: () => null,
+    setItem: () => {},
+    removeItem: () => {},
+  };
+  delete (globalThis as any).location;
+});
+
+/** Swap in a fake channel so no WebSocket is opened, and capture the handler the
+ * client registers so tests can deliver pings by hand. */
+function instrument(client: ReturnType<typeof createBoolClient>) {
+  const seen = { handler: null as null | ((msg: unknown) => void), removed: 0 };
+  (client.db as any).channel = () => {
+    const ch: any = {
+      on: (_e: string, _f: unknown, cb: (msg: unknown) => void) => {
+        seen.handler = cb;
+        return ch;
+      },
+      subscribe: () => ch,
+    };
+    return ch;
+  };
+  (client.db as any).removeChannel = async () => void seen.removed++;
+  return seen;
+}
+
+const tick = () => new Promise((r) => setTimeout(r, 0));
+/** Longer than PING_COALESCE_MS (50ms) so a scheduled flush has run. */
+const afterCoalesce = () => new Promise((r) => setTimeout(r, 90));
+
+function ping(seen: { handler: null | ((m: unknown) => void) }, payload: BoolChangePayload = {}) {
+  seen.handler!({ payload });
+}
+
+describe("reload is withheld while this client's writes are in flight", () => {
+  test("a ping during an in-flight write does not reload until it settles", async () => {
+    const client = createBoolClient(CONFIG);
+    const seen = instrument(client);
+    let reloads = 0;
+    client.subscribeToChanges(() => reloads++);
+
+    // Start a write and leave it pending.
+    void client.entities.todos.create({ text: "a" });
+    await tick();
+
+    ping(seen); // the doorbell fires for the row that just committed
+    await afterCoalesce();
+    expect(reloads).toBe(0); // withheld — a reload here would drop optimistic rows
+
+    releases.forEach((r) => r()); // the write settles
+    await afterCoalesce();
+    expect(reloads).toBe(1); // ...and now exactly one reload
+  });
+
+  // The reported bug: three quick adds. Every ping lands while later writes are
+  // still in flight, so all of them must collapse into a single reload at the end.
+  test("three rapid writes collapse to ONE reload, after the last settles", async () => {
+    const client = createBoolClient(CONFIG);
+    const seen = instrument(client);
+    let reloads = 0;
+    client.subscribeToChanges(() => reloads++);
+
+    void client.entities.todos.create({ text: "a" });
+    void client.entities.todos.create({ text: "b" });
+    void client.entities.todos.create({ text: "c" });
+    await tick();
+    expect(releases).toHaveLength(3);
+
+    // Each commit pings while the others are still outstanding.
+    releases[0]!();
+    ping(seen);
+    await tick();
+    releases[1]!();
+    ping(seen);
+    await tick();
+    expect(reloads).toBe(0);
+
+    releases[2]!();
+    ping(seen);
+    await afterCoalesce();
+    expect(reloads).toBe(1);
+  });
+
+  test("with nothing in flight a ping reloads promptly", async () => {
+    const client = createBoolClient(CONFIG);
+    const seen = instrument(client);
+    let reloads = 0;
+    client.subscribeToChanges(() => reloads++);
+
+    ping(seen);
+    await afterCoalesce();
+    expect(reloads).toBe(1);
+  });
+
+  // The trigger fires per changed ROW, so a bulk write produces a burst of pings
+  // for what the app should treat as one refresh.
+  test("a burst of pings coalesces into one reload", async () => {
+    const client = createBoolClient(CONFIG);
+    const seen = instrument(client);
+    let reloads = 0;
+    client.subscribeToChanges(() => reloads++);
+
+    for (let i = 0; i < 10; i++) ping(seen);
+    await afterCoalesce();
+    expect(reloads).toBe(1);
+  });
+
+  test("the latest payload wins when pings coalesce", async () => {
+    const client = createBoolClient(CONFIG);
+    const seen = instrument(client);
+    const got: BoolChangePayload[] = [];
+    client.subscribeToChanges((p) => got.push(p));
+
+    ping(seen, { table: "todos", op: "INSERT" });
+    ping(seen, { table: "todos", op: "DELETE" });
+    await afterCoalesce();
+    expect(got).toEqual([{ table: "todos", op: "DELETE" }]);
+  });
+
+  test("a failed write still releases the hold", async () => {
+    const client = createBoolClient(CONFIG);
+    const seen = instrument(client);
+    let reloads = 0;
+    client.subscribeToChanges(() => reloads++);
+
+    respond = () => new Response("boom", { status: 500 });
+    void client.entities.todos.create({ text: "a" }).catch(() => {});
+    await tick();
+    ping(seen);
+    await afterCoalesce();
+    expect(reloads).toBe(0);
+
+    releases.forEach((r) => r());
+    await afterCoalesce();
+    expect(reloads).toBe(1); // the counter must not leak on failure
+  });
+
+  test("reads never hold anything back", async () => {
+    const client = createBoolClient(CONFIG);
+    const seen = instrument(client);
+    let reloads = 0;
+    client.subscribeToChanges(() => reloads++);
+
+    void client.entities.todos.list(); // GET — must not count as a write
+    await tick();
+    ping(seen);
+    await afterCoalesce();
+    expect(reloads).toBe(1);
+  });
+
+  test("unsubscribing cancels a pending reload", async () => {
+    const client = createBoolClient(CONFIG);
+    const seen = instrument(client);
+    let reloads = 0;
+    const stop = client.subscribeToChanges(() => reloads++);
+
+    ping(seen);
+    stop(); // before the coalesce window elapses
+    await afterCoalesce();
+    expect(reloads).toBe(0);
+    expect(seen.removed).toBe(1);
+  });
+
+  // Raw supabase-js is the style SYNC_GUIDANCE_V2 actually teaches most apps, so
+  // it has to be counted too — which is why writes are tracked in proxyFetch
+  // rather than in the entities layer.
+  test("a raw supabase.from().insert() is counted as a write", async () => {
+    const client = createBoolClient(CONFIG);
+    const seen = instrument(client);
+    let reloads = 0;
+    client.subscribeToChanges(() => reloads++);
+
+    // supabase-js builders are thenable — they don't issue the request until
+    // awaited, so this needs a .then() to actually fire.
+    void client.db
+      .from("todos")
+      .insert({ text: "a" })
+      .then(() => {});
+    await tick();
+    expect(releases).toHaveLength(1); // the write really is in flight
+
+    ping(seen);
+    await afterCoalesce();
+    expect(reloads).toBe(0);
+
+    releases.forEach((r) => r());
+    await afterCoalesce();
+    expect(reloads).toBe(1);
+  });
+});

From 639bdb00ac273fc93ba57506b06972be0fd3828b Mon Sep 17 00:00:00 2001
From: Jack Singer <jacobsinger22@gmail.com>
Date: Mon, 27 Jul 2026 13:52:39 -0500
Subject: [PATCH 2/2] chore(release): 0.2.0-next.19
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cuts the release carrying the reload-race fix. Version 0.2.0-next.18 was bumped in
the repo but never published (npm's `next` tag is still at next.17), so releasing
next.19 ships both it and this change.

The version string is what routes the publish: because it contains a hyphen,
.github/workflows/publish.yml derives dist-tag `next` from it, so this lands on the
canary channel only — invisible to `latest` and to caret ranges, so no production
app can pull it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md | 19 +++++++++++++++++++
 package.json |  2 +-
 2 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0e3c436..6a8fbde 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.2.0-next.19
+
+- Rows no longer pop out and back in when you add several quickly. The doorbell
+  says "something changed" without saying which row, so an app reloads its whole
+  list on every ping — and a reload issued while the app's own inserts are still
+  in flight comes back *without* them, replacing what's on screen with a snapshot
+  missing rows the user already added. Measured on a live app: a row was absent
+  for 200ms before reappearing. It's a lost-update race, not latency; an
+  instantaneous network would still return a snapshot lacking uncommitted rows.
+
+  The SDK now withholds the reload signal while this client's own writes are
+  landing and fires once when they drain, plus a short trailing coalesce so a
+  burst collapses into one reload (the trigger fires per changed *row*, so a bulk
+  write produces N pings for one logical refresh). A ceiling bounds the hold so
+  continuous local editing can't starve the app of other users' changes.
+
+  **No app changes needed** — the existing `subscribe(() => load())` pattern
+  simply stops flickering. Apps pick this up on their next publish.
+
 ## 0.2.0-next.18
 
 - `bool create` now verifies the new project can be developed against *before*
diff --git a/package.json b/package.json
index 9e7bf86..1afcd71 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "bool-sdk",
-  "version": "0.2.0-next.18",
+  "version": "0.2.0-next.19",
   "description": "Client SDK for apps built on Bool — gateway data access, end-user auth, the AI battery, the React auth layer, and the local-dev CLI (link, types, deploy).",
   "type": "module",
   "main": "./dist/index.js",