From 69703450766753597e35672e7fb539be205a16e0 Mon Sep 17 00:00:00 2001
From: Jack Singer <jacobsinger22@gmail.com>
Date: Mon, 27 Jul 2026 14:53:38 -0500
Subject: [PATCH 1/2] Revert "Realtime: hold the reload while this client's own
 writes are in flight"

This reverts commit 5b8a5b90afed8cfe05e4db7f899f8b5e4b13b617.
---
 src/client.ts           |  85 +--------------
 src/reload-race.test.ts | 227 ----------------------------------------
 2 files changed, 2 insertions(+), 310 deletions(-)
 delete mode 100644 src/reload-race.test.ts

diff --git a/src/client.ts b/src/client.ts
index 5d27db9..a6e822b 100644
--- a/src/client.ts
+++ b/src/client.ts
@@ -30,16 +30,6 @@ 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`
@@ -274,31 +264,6 @@ 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;
@@ -311,19 +276,11 @@ 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.
-      const call = fetch(`${GATEWAY}/_bool/${GATEWAY_API}/db${url.pathname}${url.search}`, {
+      return 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);
   };
@@ -641,51 +598,13 @@ 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) =>
-        onPing((msg as { payload?: BoolChangePayload }).payload ?? {}),
+        listener((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
deleted file mode 100644
index c89dbd3..0000000
--- a/src/reload-race.test.ts
+++ /dev/null
@@ -1,227 +0,0 @@
-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 4b1694cc2a3a2ea7b0b83425f9a4d9b07f480b58 Mon Sep 17 00:00:00 2001
From: Jack Singer <jacobsinger22@gmail.com>
Date: Mon, 27 Jul 2026 14:59:21 -0500
Subject: [PATCH 2/2] chore(release): 0.2.0-next.20

Cuts the release that backs out next.19's reload-hold. Publishing next.20 moves the
`next` dist-tag off next.19, so fresh installs stop picking it up; next.19 stays on
npm because unpublishing is restricted and would break any lockfile already
referencing it.

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

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6a8fbde..b7399b2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.2.0-next.20
+
+- **Reverts the reload-hold behavior added in `0.2.0-next.19`.** That release
+  withheld the doorbell reload while a client's own writes were in flight, to stop
+  rows popping out and back in. It measurably reduced the flicker but did not fix
+  it, so it isn't worth the complexity it carries.
+
+  Two reasons it falls short. It bounds how long a ping can be held, so that
+  continuous editing keeps seeing other people's changes — and past that bound a
+  reload fires mid-flight and the flicker returns (reproduced at 2.6s under
+  sustained writes). More fundamentally, it guards when a reload is *issued* but
+  not when its result is *applied*: a reload already in flight still lands after
+  the next optimistic row appears and replaces the list without it.
+
+  Both are the same underlying thing — any design that replaces the whole list
+  from a server snapshot has a window in which that snapshot is stale. The fix is
+  to stop replacing the list (merge the changed row by id), not to keep shrinking
+  the window.
+
+  Preserved on the `preserve/realtime-reload-hold` branch.
+
 ## 0.2.0-next.19
 
 - Rows no longer pop out and back in when you add several quickly. The doorbell
diff --git a/package.json b/package.json
index 1afcd71..73efb91 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "bool-sdk",
-  "version": "0.2.0-next.19",
+  "version": "0.2.0-next.20",
   "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",