@spooky-sync/core 0.0.1-canary.288 → 0.0.1-canary.289

package/AGENTS.md

@@ -49,7 +49,7 @@ re-materialized from state, never patched in place.
 - **Use UI hooks, not the client directly.** In a Solid app, call `useDb()` from `@spooky-sync/client-solid`. Touch `Sp00kyClient` only inside `provider.client` for advanced flows.
 - **Mutations are optimistic.** `db.create` / `db.update` / `db.delete` return immediately; the queue drains in the background. Inspect progress via `pendingMutationCount`.
 - **Record IDs are full strings.** `db.create('thread:abc123', {...})` — *not* `db.create('thread', { id: 'abc123' })`. The first arg is `'<table>:<id>'`. Generate IDs with `Uuid` from `surrealdb` (re-exported by `client-solid`).
-- **`db.update` takes `(table, id, payload, options?)`**. The `debounced` option (`{ debounced: true }` or `{ debounced: { delay, key } }`) coalesces rapid updates — use it for CRDT text/title fields.
+- **`db.update` takes `(table, id, payload, options?)`**. The `debounced` option (`{ debounced: true }` or `{ debounced: { delay, key, flushOnHide } }`) coalesces rapid updates — use it for CRDT text/title fields. With `flushOnHide` (default `true`) the merged patch is also kept in the local `_00_pending_writes` table and pushed as soon as the page is hidden, so a reload or closed tab inside the delay does not lose it (the next boot moves a leftover patch into the outbox). `flushOnHide: false` keeps the patch in memory only.
 - **`db.remoteQuery(sql, vars?)` is the one-shot remote read.** It runs one SurrealQL statement through the client's remote path (connect gate, per-statement timeout, concurrency limit) and returns the SurrealDB result array; results are not synced into the local cache. Use it for counts and other reads the query builder can't express.
 - **`db.useRemote(fn)` hands out the bare SDK client.** Same cache bypass, but it skips the connect gate (a call during a reconnect fails with "Specify a namespace to use"). Reserve it for SDK features `remoteQuery` cannot reach (transactions, `live`).
 - **Raw remote calls are gated by the query allowlist.** When the generated schema carries `policy.queryAllowlist: 'warn' | 'enforce'` (from `sync.queryAllowlist` in `sp00ky.yml`), `remoteQuery`, `useRemote` and `queryRaw` throw unless the client config sets `allowRawRemote: true`; builder queries are unaffected. A registration the SSP refuses as not allowlisted (403 `not_allowlisted`) is marked `remote: 'failed'` after one attempt with an error-level log carrying the surql and a `spky generate` hint; the view stays cold (`membershipKnown` false), it is never read as confirmed empty.

package/dist/index.d.ts

@@ -207,6 +207,8 @@ declare class LocalMigrator {
   private logger;
   constructor(localDb: LocalStore, logger: Logger$1);
   provision(schemaSurql: string): Promise<void>;
+  private readKeptRows;
+  private restoreKeptRows;
   private isSchemaUpToDate;
   private recreateDatabase;
   private splitStatements;
@@ -892,6 +894,10 @@ type RuntimeEvent = {
 } | {
   type: 'FlushWrite';
   key: string;
+} | {
+  type: 'FlushPendingWrites';
+} | {
+  type: 'AdoptPendingWrites';
 } | {
   type: 'PollTick';
 } | {
@@ -1278,6 +1284,8 @@ interface PendingWrite {
   readonly data: Readonly<Record<string, unknown>>;
   readonly before: Readonly<Record<string, unknown>> | null;
   readonly firstAt: number;
+  /** Its durable copy in `_00_pending_writes`; null when `flushOnHide` is off. */
+  readonly mirrorId: string | null;
 }
 interface SyncSlice {
   readonly health: SyncHealth;

package/dist/index.js

@@ -1752,8 +1752,8 @@ function selfAllowlistedVariant(flag, userId) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.288";
-const WASM_VERSION = "0.0.1-canary.288";
+const CORE_VERSION = "0.0.1-canary.289";
+const WASM_VERSION = "0.0.1-canary.289";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	eventsHistory = [];
@@ -2439,6 +2439,12 @@ const AUTH_READY_MAX_ATTEMPTS = 10;
 /** Heartbeat at this fraction of the shortest ttl in state. */
 const TTL_HEARTBEAT_FRACTION = .5;
 /**
+* How long past its due flush another tab's `_00_pending_writes` row may sit
+* before it counts as abandoned (its tab died before the flush) and is moved
+* into the outbox here.
+*/
+const PENDING_WRITE_ORPHAN_MS = 3e3;
+/**
 * Orphan body garbage collection: the first sweep waits this long after boot
 * (off the first paint and the first sync round), then repeats on the interval.
 */
@@ -2840,7 +2846,8 @@ const mergePendingWrite = (write) => (s) => {
 		data: {
 			...prev.data,
 			...write.data
-		}
+		},
+		mirrorId: prev.mirrorId ?? write.mirrorId
 	} : write);
 	return {
 		...s,
@@ -4451,6 +4458,8 @@ function* collectOrphans(bucket, relay) {
 //#region src/mutation/rows.ts
 const PENDING_TABLE = "_00_pending_mutations";
 const FAILED_TABLE = "_00_failed_mutations";
+/** Debounced patches still inside their delay (see `DebounceOptions.flushOnHide`). */
+const PENDING_WRITES_TABLE = "_00_pending_writes";
 const PENDING_ROW_VERSION = 2;
 /**
 * Parse a record id READ BACK FROM THE STORE, stripping SurrealDB's `⟨⟩`
@@ -4527,7 +4536,25 @@ const toOutboxItem = (row) => ({
 	ackedAt: null,
 	attempts: 0
 });
+/** The `_00_pending_writes` id for a minted mutation id (same suffix). */
+const pendingWriteId = (mutationId) => `${PENDING_WRITES_TABLE}:${mutationId.includes(":") ? mutationId.slice(mutationId.indexOf(":") + 1) : mutationId}`;
+function parsePendingWriteRow(row) {
+	if (!row || typeof row !== "object") return null;
+	const r = row;
+	if (typeof r.recordId !== "string" && !(r.recordId instanceof RecordId$1)) return null;
+	if (!r.data || typeof r.data !== "object") return null;
+	const recordId = typeof r.recordId === "string" ? r.recordId : storedIdString(r.recordId);
+	return {
+		id: storedIdString(r.id),
+		recordId,
+		tableName: typeof r.tableName === "string" ? r.tableName : extractTablePart(recordId),
+		data: r.data,
+		beforeRecord: r.beforeRecord && typeof r.beforeRecord === "object" ? r.beforeRecord : null,
+		flushBy: typeof r.flushBy === "number" ? r.flushBy : 0
+	};
+}
 const loadPendingRows = () => `SELECT * FROM ${PENDING_TABLE} ORDER BY id ASC`;
+const loadPendingWriteRows = () => `SELECT * FROM ${PENDING_WRITES_TABLE}`;
 const loadFailedRows = () => `SELECT * FROM ${FAILED_TABLE} ORDER BY failedAt ASC`;
 const pendingInsert = (type, withData, withBefore) => {
 	const fields = [
@@ -4596,34 +4623,50 @@ function planDeleteTx(input) {
 		}
 	};
 }
-/** Debounced update: bump `_00_rv` and MERGE now; the outbox row comes later. */
+/**
+* Debounced update: bump `_00_rv` and MERGE now; the outbox row comes later.
+* With a `mirror`, the merged patch so far is written to `_00_pending_writes`
+* in the same transaction, so the row never changes without a durable copy of
+* what still has to reach the server.
+*/
 function planLocalOnlyUpdateTx(input) {
+	const statements = [surql.updateSet("id", [{ statement: "_00_rv += 1" }]), surql.let("updated", surql.updateMerge("id", "data"))];
+	if (input.mirror) statements.push(surql.upsert("wid", "wrow"));
+	statements.push(surql.returnObject([{
+		key: "target",
+		variable: "updated"
+	}]));
 	return {
-		query: surql.seal(surql.tx([
-			surql.updateSet("id", [{ statement: "_00_rv += 1" }]),
-			surql.let("updated", surql.updateMerge("id", "data")),
-			surql.returnObject([{
-				key: "target",
-				variable: "updated"
-			}])
-		])),
-		vars: {
+		query: surql.seal(surql.tx(statements)),
+		vars: input.mirror ? {
+			id: input.recordId,
+			data: input.data,
+			wid: input.mirror.id,
+			wrow: input.mirror.row
+		} : {
 			id: input.recordId,
 			data: input.data
 		}
 	};
 }
-/** The outbox row of a flushed debounced update, on its own. */
+/**
+* The outbox row of a flushed debounced update. With `mirrorId` the
+* `_00_pending_writes` row goes in the same transaction: the patch moves
+* from one table to the other, it is never in both or in neither.
+*/
 function planDeferredOutboxRowTx(input) {
+	const statements = [pendingInsert("update", true, true)];
+	if (input.mirrorId) statements.push(surql.delete("wid"));
 	return {
-		query: surql.seal(surql.tx([pendingInsert("update", true, true)])),
+		query: surql.seal(surql.tx(statements)),
 		vars: {
 			id: input.recordId,
 			mid: input.mutationId,
 			table: input.table,
 			createdAt: input.now,
 			data: input.data ?? {},
-			before: input.before ?? null
+			before: input.before ?? null,
+			...input.mirrorId ? { wid: input.mirrorId } : {}
 		}
 	};
 }
@@ -4777,6 +4820,10 @@ const debounceDelay = (input) => {
 	const d = input.options?.debounced;
 	return d && d !== true && typeof d.delay === "number" ? d.delay : 300;
 };
+const flushOnHide = (input) => {
+	const d = input.options?.debounced;
+	return !(d && d !== true && d.flushOnHide === false);
+};
 /**
 * One optimistic write: read the previous row (update/delete), run the local
 * transaction that writes the row AND its outbox entry, publish the outbox
@@ -4894,14 +4941,34 @@ function* commitWrite(kind, tx, ctx) {
 		record
 	};
 }
-/** Apply locally now, remember the merged patch, write the outbox row on flush. */
+/**
+* Apply locally now, remember the merged patch, write the outbox row on flush.
+* With `flushOnHide` (the default) the merged patch is also mirrored to
+* `_00_pending_writes` in the same transaction, so a reload or a closed tab
+* inside the delay cannot lose it.
+*/
 function* debouncedUpdate(input, key, rid, table, params) {
 	const existing = yield fx.state.read((s) => s.pendingWrites.get(key));
 	const now = yield fx.now();
 	const before = existing ? existing.before : yield* readBefore(rid);
+	const mirrorId = existing?.mirrorId ?? (flushOnHide(input) ? pendingWriteId(yield fx.id("mutation")) : null);
+	const delay = debounceDelay(input);
 	const local = planLocalOnlyUpdateTx({
 		recordId: rid,
-		data: params
+		data: params,
+		mirror: mirrorId ? {
+			id: parseRecordIdString(mirrorId),
+			row: {
+				recordId: rid,
+				tableName: table,
+				data: {
+					...existing?.data,
+					...params
+				},
+				beforeRecord: before,
+				flushBy: now + delay
+			}
+		} : void 0
 	});
 	const record = (yield fx.local.execute(local.query, local.vars))?.target ?? null;
 	yield fx.state.update(mergePendingWrite({
@@ -4910,7 +4977,8 @@ function* debouncedUpdate(input, key, rid, table, params) {
 		recordId: input.recordId,
 		data: params,
 		before,
-		firstAt: existing?.firstAt ?? now
+		firstAt: existing?.firstAt ?? now,
+		mirrorId
 	}));
 	yield fx.state.update(markTableDirty(table));
 	const version = typeof record?._00_rv === "number" ? record._00_rv : 0;
@@ -4944,7 +5012,7 @@ function* debouncedUpdate(input, key, rid, table, params) {
 			records: [tuple]
 		}
 	});
-	yield fx.timer.set(`debounce:${key}`, debounceDelay(input), {
+	yield fx.timer.set(`debounce:${key}`, delay, {
 		type: "FlushWrite",
 		key
 	});
@@ -4967,9 +5035,15 @@ function* flushWrite(env, key) {
 		table: pending.table,
 		data: { ...pending.data },
 		before: pending.before,
-		now
+		now,
+		mirrorId: pending.mirrorId ? parseRecordIdString(pending.mirrorId) : void 0
 	});
-	yield fx.local.execute(insert.query, insert.vars);
+	try {
+		yield fx.local.execute(insert.query, insert.vars);
+	} catch (error) {
+		if (pending.mirrorId) yield fx.timer.set("adopt-writes", PENDING_WRITE_ORPHAN_MS, { type: "AdoptPendingWrites" });
+		throw error;
+	}
 	yield fx.state.update(outboxPush({
 		id: mutationId,
 		type: "update",
@@ -4999,6 +5073,99 @@ function* flushWrite(env, key) {
 	});
 	else yield fx.dispatch({ type: "Drain" });
 }
+/**
+* The page is being hidden (tab switch, reload, close, backgrounded): flush
+* every mirrored pending write now rather than when its timer fires. On a
+* reload or close this races the teardown; whatever does not make it stays
+* in `_00_pending_writes` for the next boot.
+*/
+function* flushPendingWrites() {
+	const keys = yield fx.state.read((s) => [...s.pendingWrites.values()].filter((w) => w.mirrorId !== null).map((w) => w.key));
+	for (const key of keys) {
+		yield fx.timer.clear(`debounce:${key}`);
+		yield fx.dispatch({
+			type: "FlushWrite",
+			key
+		});
+	}
+}
+/**
+* Move abandoned `_00_pending_writes` rows into the outbox: rows no pending
+* write of this tab holds, `PENDING_WRITE_ORPHAN_MS` past their due flush. That
+* is a tab that reloaded or closed inside the delay, or a flush of ours that
+* failed. A row not yet overdue may still be live in another tab and is looked
+* at again once it would be. A follower only nudges the leader, so a single
+* tab adopts and a patch is never queued twice.
+*/
+function* adoptPendingWrites() {
+	const state = yield fx.state.read((s) => s);
+	let raw = [];
+	try {
+		const res = yield fx.local.query(loadPendingWriteRows());
+		raw = Array.isArray(res?.[0]) ? res[0] : [];
+	} catch {
+		return;
+	}
+	const held = new Set([...state.pendingWrites.values()].map((w) => w.mirrorId));
+	const rows = raw.map(parsePendingWriteRow).filter((r) => r !== null && !held.has(r.id));
+	if (rows.length === 0) return;
+	if (state.tabRole === "follower") {
+		yield fx.emit({
+			type: "tabs:broadcast",
+			message: {
+				type: "outbox-changed",
+				mutationId: ""
+			}
+		});
+		return;
+	}
+	const now = yield fx.now();
+	let recheckAt = Infinity;
+	let adopted = 0;
+	for (const row of rows) {
+		const due = row.flushBy + PENDING_WRITE_ORPHAN_MS;
+		if (now < due) {
+			recheckAt = Math.min(recheckAt, due);
+			continue;
+		}
+		const mutationId = yield fx.id("mutation");
+		const move = planDeferredOutboxRowTx({
+			recordId: parseRecordIdString(row.recordId),
+			mutationId: parseRecordIdString(mutationId),
+			table: row.tableName,
+			data: row.data,
+			before: row.beforeRecord,
+			now,
+			mirrorId: parseRecordIdString(row.id)
+		});
+		try {
+			yield fx.local.execute(move.query, move.vars);
+		} catch (error) {
+			yield fx.emit({
+				type: "log",
+				level: "warn",
+				message: "could not move an abandoned debounced write into the outbox",
+				data: {
+					id: row.id,
+					error
+				}
+			});
+			continue;
+		}
+		yield fx.state.update(outboxPush({
+			id: mutationId,
+			type: "update",
+			recordId: row.recordId,
+			table: row.tableName,
+			status: "pending",
+			ackedAt: null,
+			attempts: 0
+		}));
+		adopted += 1;
+	}
+	if (adopted > 0) yield fx.dispatch({ type: "Drain" });
+	if (recheckAt !== Infinity) yield fx.timer.set("adopt-writes", recheckAt - now, { type: "AdoptPendingWrites" });
+}
 
 //#endregion
 //#region src/mutation/tray.saga.ts
@@ -5119,6 +5286,7 @@ function mutationOwnerTabId(mutationId) {
 /**
 * Boot / bucket switch: mirror the outbox table into state. Rows that can
 * never be replayed (a create without its payload) go straight to the tray.
+* Debounced patches a dead page left in `_00_pending_writes` are adopted next.
 */
 function* loadOutbox(env) {
 	const res = yield fx.local.query(loadPendingRows());
@@ -5144,6 +5312,7 @@ function* loadOutbox(env) {
 	});
 	yield* refreshFailedCount();
 	if (items.length > 0) yield fx.dispatch({ type: "Drain" });
+	yield fx.dispatch({ type: "AdoptPendingWrites" });
 }
 function* refreshFailedCount() {
 	try {
@@ -6686,6 +6855,11 @@ function route(env, event) {
 			saga: flushWrite(env, event.key),
 			lane: serial("outbox-write")
 		};
+		case "FlushPendingWrites": return { saga: flushPendingWrites() };
+		case "AdoptPendingWrites": return {
+			saga: adoptPendingWrites(),
+			lane: serial("outbox-write")
+		};
 		case "PollTick": return {
 			saga: pollTick(env),
 			lane: dedupe("poll")
@@ -8141,6 +8315,16 @@ const sha1 = async (str) => {
 	const hash = await crypto.subtle.digest("SHA-1", enc.encode(str));
 	return Array.from(new Uint8Array(hash)).map((v) => v.toString(16).padStart(2, "0")).join("");
 };
+/**
+* Local-only state a schema change must not throw away: the outbox, the
+* failed-mutation tray and debounced patches not yet in the outbox. Cached
+* rows refill from the server; these exist nowhere else.
+*/
+const KEPT_TABLES = [
+	"_00_pending_mutations",
+	"_00_failed_mutations",
+	"_00_pending_writes"
+];
 var LocalMigrator = class {
 	logger;
 	constructor(localDb, logger) {
@@ -8155,8 +8339,9 @@ var LocalMigrator = class {
 			this.logger.info({ Category: "sp00ky-client::LocalMigrator::provision" }, "[Provisioning] Schema is up to date, skipping migration");
 			return;
 		}
+		const kept = await this.readKeptRows();
 		await this.recreateDatabase(database);
-		const fullSchema = schemaSurql + "\n\n      DEFINE TABLE IF NOT EXISTS _00_stream_processor_state SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_view SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_window SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_failed_mutations SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_schema SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_pending_mutations SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_blob SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n    ";
+		const fullSchema = schemaSurql + "\n\n      DEFINE TABLE IF NOT EXISTS _00_stream_processor_state SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_view SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_window SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_failed_mutations SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_schema SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_pending_mutations SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_pending_writes SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_blob SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n    ";
 		const statements = this.splitStatements(fullSchema);
 		for (let i = 0; i < statements.length; i++) {
 			const statement = statements[i];
@@ -8174,8 +8359,34 @@ var LocalMigrator = class {
 				throw e;
 			}
 		}
+		await this.restoreKeptRows(kept);
 		await this.createHashRecord(hash);
 	}
+	async readKeptRows() {
+		const kept = [];
+		for (const table of KEPT_TABLES) try {
+			const [rows] = await this.localDb.queryUngated(`SELECT * FROM ${table}`);
+			if (Array.isArray(rows) && rows.length > 0) kept.push([table, rows]);
+		} catch {}
+		return kept;
+	}
+	async restoreKeptRows(kept) {
+		for (const [table, rows] of kept) try {
+			await this.localDb.queryUngated(`INSERT INTO ${table} $rows`, { rows });
+			this.logger.info({
+				table,
+				count: rows.length,
+				Category: "sp00ky-client::LocalMigrator::provision"
+			}, "[Provisioning] Kept local rows across the schema change");
+		} catch (error) {
+			this.logger.error({
+				table,
+				count: rows.length,
+				error,
+				Category: "sp00ky-client::LocalMigrator::provision"
+			}, "[Provisioning] Could not restore local rows after the schema change; they are lost");
+		}
+	}
 	async isSchemaUpToDate(hash) {
 		try {
 			const [lastSchemaRecord] = await this.localDb.queryUngated(`SELECT hash, created_at FROM ONLY _00_schema ORDER BY created_at DESC LIMIT 1;`);
@@ -8924,6 +9135,7 @@ const SYSTEM_TABLES = [
 	"_00_failed_mutations",
 	"_00_schema",
 	"_00_pending_mutations",
+	"_00_pending_writes",
 	"_00_blob",
 	"_00_user_feature",
 	"_00_app_release"
@@ -14013,7 +14225,7 @@ function createTabsCoordinator(config, s, host) {
 	return new TabsCoordinator({
 		tabId: s.tabId,
 		fingerprint: computeTabsFingerprint({
-			coreVersion: "0.0.1-canary.288",
+			coreVersion: "0.0.1-canary.289",
 			schemaHash: hash53(config.schemaSurql),
 			endpoint: config.database.endpoint ?? "",
 			namespace: config.database.namespace,
@@ -14185,6 +14397,7 @@ function createAdapters(config, s, host, lateModules) {
 		"window.attach": () => {
 			if (typeof window === "undefined" || typeof window.addEventListener !== "function") return;
 			const onPageHide = (event) => {
+				host.dispatch({ type: "FlushPendingWrites" });
 				if (event.persisted) return;
 				host.dispatch({ type: "PageHide" });
 			};
@@ -14192,13 +14405,17 @@ function createAdapters(config, s, host, lateModules) {
 				if (typeof document !== "undefined" && document.visibilityState === "hidden") return;
 				host.dispatch({ type: "HeartbeatNow" });
 			};
+			const onVisibility = () => {
+				if (document.visibilityState === "hidden") host.dispatch({ type: "FlushPendingWrites" });
+				else onWake();
+			};
 			window.addEventListener("pagehide", onPageHide);
 			window.addEventListener("online", onWake);
-			if (typeof document !== "undefined") document.addEventListener("visibilitychange", onWake);
+			if (typeof document !== "undefined") document.addEventListener("visibilitychange", onVisibility);
 			host.setDetachWindow(() => {
 				window.removeEventListener("pagehide", onPageHide);
 				window.removeEventListener("online", onWake);
-				if (typeof document !== "undefined") document.removeEventListener("visibilitychange", onWake);
+				if (typeof document !== "undefined") document.removeEventListener("visibilitychange", onVisibility);
 			});
 		}
 	};

package/dist/types.d.ts

@@ -2002,6 +2002,20 @@ interface DebounceOptions {
   key?: 'recordId' | 'recordId_x_fields';
   /** The debounce delay in milliseconds. */
   delay?: number;
+  /**
+   * Keep the pending patch across a reload or a closed tab. Default `true`.
+   *
+   * Every call also writes the merged patch to `_00_pending_writes`, in the
+   * same local transaction as the row itself. When the page is hidden (tab
+   * switch, reload, close, app sent to the background) every pending patch is
+   * moved into the outbox and pushed at once instead of waiting out `delay`.
+   * A page that dies before that finishes leaves the patch in the store, and
+   * the next boot moves it into the outbox.
+   *
+   * `false` keeps the patch in memory only, so whatever is still inside its
+   * delay is lost on reload. Meant for throwaway state like a cursor position.
+   */
+  flushOnHide?: boolean;
 }
 //#endregion
 export { WebPushSubscribeOptions as $, RunOptions as A, LocalStore as At, SyncHealthStatus as B, TokenClaims as Bt, QueryTimeToLive as C, SignOutHook as Ct, RecordVersionArray as D, createAuthEventSystem as Dt, ReconnectConfig as E, AuthEventTypes as Et, StorageHealth as F, ImpersonationInfo as Ft, WebPushConfig as G, UpdateOptions as H, impersonationFromToken as Ht, StorageHealthStatus as I, ImpersonationTimerHost as It, WebPushErrorCode as J, WebPushDevice as K, StoreType as L, ImpersonationTimers as Lt, Sp00kyConfig as M, EventDefinition as Mt, Sp00kyQueryResult as N, EventSystem as Nt, RecordVersionDiff as O, RemoteDatabaseService as Ot, Sp00kyQueryResultPromise as P, IMPERSONATION_ACCESS as Pt, WebPushModule as Q, SyncHealth as R, ORIGIN_TOKEN_KEY as Rt, QueryStatusCallback as S, SignOutContext as St, QueryUpdateCallback as T, AuthEventTypeMap as Tt, PUSH_ENDPOINT_KEY as U, renewDelayMs as Ut, TimingPhase as V, decodeTokenClaims as Vt, PushDeviceKind as W, sameImpersonation as Wt, WebPushMessage as X, WebPushInfo as Y, WebPushMessageInput as Z, QueryConfig as _, isPushPayload as _t, Level$1 as a, WebPushUpdateOptions as at, QueryState as b, ImpersonationCandidate as bt, MutationCallback as c, BridgeTokenMessage as ct, PersistenceClient as d, PushNotificationAction as dt, WebPushSupport as et, PhaseStat as f, PushOp as ft, QueryAuthorityCallback as g, WebPushClientMessage as gt, PreloadRefresh as h, PushUrgency as ht, InlineRow as i, WebPushUnsupportedReason as it, ServerViewMeta as j, SealedQuery as jt, RegistrationTimings as k, Logger$1 as kt, MutationEvent as l, PUSH_PAYLOAD_VERSION as lt, PreloadOptions as m, PushPayloadKind as mt, DebounceOptions as n, WebPushSyncStatus as nt, MATERIALIZATION_SAMPLE_WINDOW as o, detectWebPushSupport as ot, PinoTransmit as p, PushPayload as pt, WebPushError as q, EventSubscriptionOptions as r, WebPushUnsubscribeOptions as rt, MembershipOutcome as s, BridgeSignOutMessage as st, ConnectionState as t, WebPushSyncOptions as tt, MutationEventType as u, PushNotification as ut, QueryConfigRecord as v, ActiveImpersonation as vt, QueryTimings as w, AuthEventSystem as wt, QueryStatus as x, SIGN_OUT_HOOK_TIMEOUT_MS as xt, QueryHash as y, AuthService as yt, SyncHealthConfig as z, SESSION_POLL_MS as zt };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.288",
+  "version": "0.0.1-canary.289",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -75,8 +75,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.288",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.288",
+    "@spooky-sync/query-builder": "0.0.1-canary.289",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.289",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.0.3",
     "blurhash": "^2.0.5",

package/skills/sp00ky-core/SKILL.md

@@ -120,6 +120,10 @@ await client.delete('post', 'post:abc123');
 Use `debounced` option for frequent updates (e.g., live typing):
 - `key: 'recordId'` — Debounce by record ID only (latest write wins, no merge)
 - `key: 'recordId_x_fields'` — Debounce by record ID + changed fields (recommended)
+- `flushOnHide` (default `true`): also keep the merged patch in the local `_00_pending_writes`
+  table and push it as soon as the page is hidden (tab switch, reload, close). A reload or closed
+  tab inside the delay no longer loses the edit: the next boot moves the leftover patch into the
+  outbox. Set `false` for throwaway values (cursor position) to keep the patch in memory only.
 
 ### Failed writes
 

package/skills/sp00ky-core/references/config.md

@@ -71,6 +71,12 @@ interface UpdateOptions {
     key?: 'recordId' | 'recordId_x_fields';
     /** Debounce delay in ms */
     delay?: number;
+    /**
+     * Default true. Keep the merged patch in the local `_00_pending_writes` table and
+     * push it as soon as the page is hidden (tab switch, reload, close), so a reload
+     * inside the delay does not lose it. false: memory only.
+     */
+    flushOnHide?: boolean;
   };
 }
 ```

package/src/boot/boot.saga.test.ts

@@ -43,7 +43,7 @@ describe('boot', () => {
     ]);
     expect(svc.calls[1]).toEqual(['local.connect', ['u1']]);
     expect(out.state).toMatchObject({ bucketId: 'u1', userId: 'user:u1', saltUserId: 'user:u1', sessionId: 'salt-1', localReady: true });
-    expect(out.dispatched.map((d) => d.type)).toEqual(['WarmBlobs', 'PrimeCircuit', 'LifecycleTick', 'StartRemote']);
+    expect(out.dispatched.map((d) => d.type)).toEqual(['WarmBlobs', 'PrimeCircuit', 'AdoptPendingWrites', 'LifecycleTick', 'StartRemote']);
     // The view index is loaded before anything can paint; the first GC waits out the boot.
     expect(out.state.views).toEqual(new Map([['k', ['t:1']]]));
     expect(out.timers.get('gc')).toEqual({ ms: 30_000, event: { type: 'GcTick' } });

package/src/boot/bucket-switch.saga.test.ts

@@ -72,7 +72,7 @@ describe('bucketSwitch', () => {
     expect(String(e.def.id.table)).toBe('_00_query');
     // PollTick is load-bearing: the switch cleared the poll timer, and only the
     // tick re-arms it, so a sign-in without it leaves the client on LIVE alone.
-    expect(out.dispatched.map((d) => d.type)).toEqual(['PrimeCircuit', 'EnsureRegistered', 'LiveStart', 'PollTick', 'Drain']);
+    expect(out.dispatched.map((d) => d.type)).toEqual(['PrimeCircuit', 'AdoptPendingWrites', 'EnsureRegistered', 'LiveStart', 'PollTick', 'Drain']);
   });
   it('shared tabs: moves namespaces, falls back to solo on failure; blob clear on sign-out; failures are logged and the gate always reopens', async () => {
     let gateReleased = false;

package/src/client/router.test.ts

@@ -22,6 +22,8 @@ describe('route', () => {
       [{ type: 'GcTick' }, 'dedupe:gc'],
       [{ type: 'Drain' }, 'serial:outbox'],
       [{ type: 'FlushWrite', key: 'k' }, 'serial:outbox-write'],
+      [{ type: 'FlushPendingWrites' }, undefined],
+      [{ type: 'AdoptPendingWrites' }, 'serial:outbox-write'],
       [{ type: 'PollTick' }, 'dedupe:poll'],
       [{ type: 'SelfHealTick' }, 'dedupe:heal'],
       [{ type: 'SyncOutcome', ok: true }, 'serial:health'],

package/src/client/router.ts

@@ -7,7 +7,7 @@ import { fetchRows } from '../query/fetch.saga';
 import { materialize, streamUpdate } from '../query/materialize.saga';
 import { ackPrune, gcTick, lifecycleTick } from '../query/lifecycle.saga';
 import { drain } from '../mutation/push.saga';
-import { flushWrite } from '../mutation/write.saga';
+import { adoptPendingWrites, flushPendingWrites, flushWrite } from '../mutation/write.saga';
 import { pollTick } from '../sync/poll.saga';
 import { liveChange, liveStart } from '../sync/live.saga';
 import { connectionChanged, selfHealTick, syncOutcome } from '../sync/connection.saga';
@@ -62,6 +62,10 @@ export function route(env: SagaEnv, event: RuntimeEvent): RouteTarget {
       return { saga: drain(env), lane: serial('outbox') };
     case 'FlushWrite':
       return { saga: flushWrite(env, event.key), lane: serial('outbox-write') };
+    case 'FlushPendingWrites':
+      return { saga: flushPendingWrites() };
+    case 'AdoptPendingWrites':
+      return { saga: adoptPendingWrites(), lane: serial('outbox-write') };
     case 'PollTick':
       return { saga: pollTick(env), lane: dedupe('poll') };
     case 'SelfHealTick':

package/src/client/services.ts

@@ -280,7 +280,11 @@ export function createAdapters<S extends SchemaStructure>(config: Sp00kyConfig<S
     'releases.init': () => undefined,
     'window.attach': () => {
       if (typeof window === 'undefined' || typeof window.addEventListener !== 'function') return;
+      // Hidden is the last moment a page reliably gets to run: a reload or a
+      // closed tab follows it, and a backgrounded mobile tab may be killed
+      // without any further event. Pending debounced writes go out then.
       const onPageHide = (event: PageTransitionEvent) => {
+        host.dispatch({ type: 'FlushPendingWrites' });
         if (event.persisted) return;
         host.dispatch({ type: 'PageHide' });
       };
@@ -288,13 +292,17 @@ export function createAdapters<S extends SchemaStructure>(config: Sp00kyConfig<S
         if (typeof document !== 'undefined' && document.visibilityState === 'hidden') return;
         host.dispatch({ type: 'HeartbeatNow' });
       };
+      const onVisibility = () => {
+        if (document.visibilityState === 'hidden') host.dispatch({ type: 'FlushPendingWrites' });
+        else onWake();
+      };
       window.addEventListener('pagehide', onPageHide);
       window.addEventListener('online', onWake);
-      if (typeof document !== 'undefined') document.addEventListener('visibilitychange', onWake);
+      if (typeof document !== 'undefined') document.addEventListener('visibilitychange', onVisibility);
       host.setDetachWindow(() => {
         window.removeEventListener('pagehide', onPageHide);
         window.removeEventListener('online', onWake);
-        if (typeof document !== 'undefined') document.removeEventListener('visibilitychange', onWake);
+        if (typeof document !== 'undefined') document.removeEventListener('visibilitychange', onVisibility);
       });
     },
   };

package/src/kernel/constants.ts

@@ -48,6 +48,12 @@ export const AUTH_READY_RETRY_MS = 500;
 export const AUTH_READY_MAX_ATTEMPTS = 10;
 /** Heartbeat at this fraction of the shortest ttl in state. */
 export const TTL_HEARTBEAT_FRACTION = 0.5;
+/**
+ * How long past its due flush another tab's `_00_pending_writes` row may sit
+ * before it counts as abandoned (its tab died before the flush) and is moved
+ * into the outbox here.
+ */
+export const PENDING_WRITE_ORPHAN_MS = 3_000;
 /**
  * Orphan body garbage collection: the first sweep waits this long after boot
  * (off the first paint and the first sync round), then repeats on the interval.