@syncular/react 0.2.0

package/dist/query-churn.js

@@ -0,0 +1,216 @@
+/**
+ * Live-query churn hardening — the three cheap levers the query hooks share
+ * (block 4 "live-query churn" item). Under constant sync churn a naive live
+ * query re-renders and re-queries once per invalidation event; these levers
+ * cap both without reaching for IVM:
+ *
+ * 1. {@link reconcileRows} — result stability. After a re-run, compare the new
+ *    result to the previous one. Whole-result equal → the caller skips
+ *    `setRows` entirely (zero re-render). Otherwise build the new array but
+ *    REUSE the previous row object for every row whose content is unchanged,
+ *    so `React.memo`'d row components keyed by row identity skip re-render.
+ * 2. {@link FrameScheduler} — frame-coalesced re-query scheduling. Many
+ *    invalidation events between paints collapse to ONE re-run per query.
+ * 3. scope-key filtering lives in {@link ../use-sync-query} `eventMatches`
+ *    (it needs the event + the hook's options), documented there.
+ *
+ * Row identity mechanism (the honest key): the hook knows no primary key —
+ * rows are plain JSON-able objects out of SQLite — so per-row content equality
+ * IS the identity. We hash each row once with a stable JSON serialization
+ * (sorted keys, so column order can't spuriously differ) and match by index:
+ * a live query's ORDER BY makes index the stable position, and an unchanged
+ * row at position i keeps its object so memoized components skip. This is O(n)
+ * in the row count with one string hash per row — bounded and measured (~0.2ms
+ * for 1k narrow rows in bun; see query-churn.test.ts).
+ */
+/**
+ * A stable content hash for one row: JSON with keys sorted, so two rows with
+ * the same columns in a different order hash equal (SQLite projection order is
+ * stable per query, but sorting removes any dependence on it and is cheap for
+ * the narrow rows a row-component renders). Uint8Array values (rare in a
+ * projection) serialize by byte view so a fresh copy of equal bytes hashes
+ * equal rather than to `{}`.
+ */
+export function hashRow(row) {
+    return JSON.stringify(row, replacer);
+}
+function replacer(_key, value) {
+    if (value instanceof Uint8Array)
+        return { __u8: [...value] };
+    if (value !== null &&
+        typeof value === 'object' &&
+        !Array.isArray(value) &&
+        Object.getPrototypeOf(value) === Object.prototype) {
+        // Sort keys so column/field order never spuriously changes the hash.
+        const sorted = {};
+        for (const k of Object.keys(value).sort()) {
+            sorted[k] = value[k];
+        }
+        return sorted;
+    }
+    return value;
+}
+export function hashRows(rows) {
+    const hashes = new Array(rows.length);
+    for (let i = 0; i < rows.length; i++)
+        hashes[i] = hashRow(rows[i]);
+    return { rows, hashes };
+}
+/**
+ * Reconcile a freshly-queried result against the previous hashed result.
+ * Returns `next: undefined` when nothing changed at all; otherwise a new
+ * hashed result whose row objects are the PREVIOUS objects wherever content is
+ * unchanged (matched by index), so identity-keyed memo components skip.
+ */
+export function reconcileRows(prev, fresh) {
+    const freshHashes = new Array(fresh.length);
+    for (let i = 0; i < fresh.length; i++)
+        freshHashes[i] = hashRow(fresh[i]);
+    if (prev !== undefined && prev.rows.length === fresh.length) {
+        let identical = true;
+        for (let i = 0; i < fresh.length; i++) {
+            if (prev.hashes[i] !== freshHashes[i]) {
+                identical = false;
+                break;
+            }
+        }
+        if (identical)
+            return { next: undefined };
+    }
+    // Changed: reuse the previous row object at each index whose hash matches,
+    // so unchanged rows keep their identity for memoized row components.
+    const rows = new Array(fresh.length);
+    for (let i = 0; i < fresh.length; i++) {
+        const reuse = prev !== undefined &&
+            i < prev.rows.length &&
+            prev.hashes[i] === freshHashes[i];
+        // `i < fresh.length` bounds this loop, so `fresh[i]` is defined; the reuse
+        // branch is additionally guarded by `i < prev.rows.length`.
+        rows[i] = reuse ? prev.rows[i] : fresh[i];
+    }
+    return { next: { rows, hashes: freshHashes } };
+}
+/**
+ * A per-query re-run scheduler that coalesces bursts of invalidation events
+ * into ONE run per paint. Multiple `schedule()` calls before the next flush
+ * run the callback once. A `schedule()` that arrives WHILE the callback is
+ * running (re-entrant, or an event during an async re-query) marks dirty and
+ * runs the callback exactly once more after — never lost, never concurrent.
+ *
+ * Timing source: `requestAnimationFrame` when the host has it (a real browser
+ * paints one frame; the coalescing window is a frame), else a microtask via a
+ * resolved promise (bun tests have no rAF — this keeps them deterministic and
+ * timer-free, honoring the no-timers doctrine: it's a readiness turn, not a
+ * wall-clock sleep). {@link flush} runs any pending callback synchronously for
+ * tests, so no arbitrary sleeps are needed to observe coalescing.
+ */
+export class FrameScheduler {
+    #scheduled = false;
+    #running = false;
+    #dirty = false;
+    #callback;
+    constructor(callback) {
+        this.#callback = callback;
+        liveSchedulers.add(this);
+    }
+    /** Request a run. Coalesces until the next frame/microtask boundary. */
+    schedule() {
+        if (this.#running) {
+            // An event arrived during a run — remember it and re-run once after.
+            this.#dirty = true;
+            return;
+        }
+        if (this.#scheduled)
+            return;
+        this.#scheduled = true;
+        scheduleFrame(() => this.#fire());
+    }
+    #fire() {
+        this.#run();
+    }
+    /**
+     * Run the callback once, honoring the running/dirty contract: a `schedule()`
+     * during the run marks `#dirty`, and on completion we re-schedule exactly
+     * one more run — never lost, never concurrent. Returns the callback's result
+     * (a Promise for the async host path) so `flush` can hand it to a test.
+     */
+    #run() {
+        this.#scheduled = false;
+        if (this.#callback === undefined)
+            return;
+        this.#running = true;
+        this.#dirty = false;
+        const done = () => {
+            this.#running = false;
+            if (this.#dirty && this.#callback !== undefined) {
+                this.#dirty = false;
+                // An invalidation landed mid-run: re-run once more, coalesced.
+                this.schedule();
+            }
+        };
+        let result;
+        try {
+            result = this.#callback();
+        }
+        catch {
+            done();
+            return;
+        }
+        if (result && typeof result.then === 'function') {
+            return result.then(done, done);
+        }
+        done();
+        return;
+    }
+    /**
+     * Synchronously run any pending scheduled callback NOW (test determinism).
+     * Returns whatever the callback returned (a Promise for the async host path)
+     * so a test can await the re-query settling without a sleep. A no-op when
+     * nothing is pending.
+     */
+    flush() {
+        if (!this.#scheduled || this.#callback === undefined)
+            return;
+        return this.#run();
+    }
+    /** Drop the callback so a torn-down hook's pending frame is a no-op. */
+    dispose() {
+        this.#callback = undefined;
+        liveSchedulers.delete(this);
+    }
+}
+/**
+ * Live schedulers, weakly tracked for the test-only flush below. A Set (not
+ * WeakSet) so we can iterate; entries are removed on `dispose()`, so a mounted
+ * hook holds at most one entry and unmount clears it.
+ */
+const liveSchedulers = new Set();
+/**
+ * TEST-ONLY: synchronously flush every live scheduler's pending frame, so a
+ * test can observe the coalesced re-query without a wall-clock sleep (the
+ * no-timers doctrine — a readiness flush, injected, not a timer). Returns a
+ * Promise that settles when every flushed async re-query has settled.
+ */
+export function flushQuerySchedulers() {
+    const pending = [];
+    for (const s of liveSchedulers) {
+        const r = s.flush();
+        if (r && typeof r.then === 'function') {
+            pending.push(r);
+        }
+    }
+    return Promise.all(pending).then(() => undefined);
+}
+const raf = typeof globalThis.requestAnimationFrame === 'function'
+    ? globalThis.requestAnimationFrame.bind(globalThis)
+    : undefined;
+function scheduleFrame(cb) {
+    if (raf !== undefined) {
+        raf(cb);
+        return;
+    }
+    // No rAF (bun test / worker): a microtask is the deterministic, timer-free
+    // coalescing boundary. Everything queued in the current synchronous run
+    // (a burst of emits) has already called schedule() before this drains.
+    queueMicrotask(cb);
+}

package/dist/typed.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `@syncular/react/typed` — the Kysely-typed live-query hook, kept behind
+ * this subpath so the main barrel never imports Kysely. Requires the
+ * `@syncular/kysely` and `kysely` peer dependencies.
+ */
+export { useTypedQuery } from './use-typed-query.js';

package/dist/typed.js

@@ -0,0 +1,6 @@
+/**
+ * `@syncular/react/typed` — the Kysely-typed live-query hook, kept behind
+ * this subpath so the main barrel never imports Kysely. Requires the
+ * `@syncular/kysely` and `kysely` peer dependencies.
+ */
+export { useTypedQuery } from './use-typed-query.js';

package/dist/use-client.d.ts

@@ -0,0 +1,3 @@
+import type { NormalizedClient } from './client.js';
+/** Read the normalized client from context; throws outside a `SyncProvider`. */
+export declare function useSyncClient(): NormalizedClient;

package/dist/use-client.js

@@ -0,0 +1,10 @@
+import { useContext } from 'react';
+import { SyncContext } from './provider.js';
+/** Read the normalized client from context; throws outside a `SyncProvider`. */
+export function useSyncClient() {
+    const client = useContext(SyncContext);
+    if (client === undefined) {
+        throw new Error('@syncular/react: no client in context — wrap your tree in <SyncProvider client={…}>');
+    }
+    return client;
+}

package/dist/use-conflicts.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `useConflicts` — the accumulated conflict records (§6.2/§6.5) and
+ * rejections (§6.3) the client has surfaced. Re-read after every apply
+ * batch (a push result lands through the same choke point) plus on mount.
+ */
+import type { ConflictRecord, RejectionRecord } from '@syncular/client';
+export interface UseConflictsResult {
+    readonly conflicts: readonly ConflictRecord[];
+    readonly rejections: readonly RejectionRecord[];
+    readonly refresh: () => void;
+}
+export declare function useConflicts(): UseConflictsResult;

package/dist/use-conflicts.js

@@ -0,0 +1,37 @@
+/**
+ * `useConflicts` — the accumulated conflict records (§6.2/§6.5) and
+ * rejections (§6.3) the client has surfaced. Re-read after every apply
+ * batch (a push result lands through the same choke point) plus on mount.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useSyncClient } from './use-client.js';
+export function useConflicts() {
+    const client = useSyncClient();
+    const [conflicts, setConflicts] = useState([]);
+    const [rejections, setRejections] = useState([]);
+    const readRef = useRef(() => { });
+    const refresh = useCallback(() => readRef.current(), []);
+    useEffect(() => {
+        let cancelled = false;
+        const read = () => {
+            Promise.all([client.conflicts(), client.rejections()])
+                .then(([c, r]) => {
+                if (cancelled)
+                    return;
+                setConflicts(c);
+                setRejections(r);
+            })
+                .catch(() => {
+                /* transient read failure — the next batch re-reads */
+            });
+        };
+        readRef.current = read;
+        read();
+        const unsubscribe = client.onInvalidate(read);
+        return () => {
+            cancelled = true;
+            unsubscribe();
+        };
+    }, [client]);
+    return { conflicts, rejections, refresh };
+}

package/dist/use-mutation.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `useMutation` — submit local mutations (§6.1). Returns a stable `mutate`
+ * that appends to the outbox and applies the optimistic overlay immediately
+ * (§7.1); the referencing `useSyncQuery` re-runs on the resulting
+ * invalidation batch, so optimistic writes appear without a manual refetch.
+ * `mutate` resolves to the `clientCommitId` (track it against
+ * `useConflicts`/status). `isPending`/`error` cover the (usually instant)
+ * submit; server acceptance is observed through status + conflicts, not
+ * here.
+ */
+import type { MutationInput } from '@syncular/client';
+export interface UseMutationResult {
+    /** Submit mutations; resolves to the clientCommitId. */
+    mutate: (mutations: readonly MutationInput[]) => Promise<string>;
+    readonly isPending: boolean;
+    readonly error: Error | undefined;
+}
+export declare function useMutation(): UseMutationResult;

package/dist/use-mutation.js

@@ -0,0 +1,34 @@
+/**
+ * `useMutation` — submit local mutations (§6.1). Returns a stable `mutate`
+ * that appends to the outbox and applies the optimistic overlay immediately
+ * (§7.1); the referencing `useSyncQuery` re-runs on the resulting
+ * invalidation batch, so optimistic writes appear without a manual refetch.
+ * `mutate` resolves to the `clientCommitId` (track it against
+ * `useConflicts`/status). `isPending`/`error` cover the (usually instant)
+ * submit; server acceptance is observed through status + conflicts, not
+ * here.
+ */
+import { useCallback, useState } from 'react';
+import { useSyncClient } from './use-client.js';
+export function useMutation() {
+    const client = useSyncClient();
+    const [isPending, setIsPending] = useState(false);
+    const [error, setError] = useState(undefined);
+    const mutate = useCallback(async (mutations) => {
+        setIsPending(true);
+        setError(undefined);
+        try {
+            const id = await client.mutate(mutations);
+            return id;
+        }
+        catch (err) {
+            const wrapped = err instanceof Error ? err : new Error(String(err));
+            setError(wrapped);
+            throw wrapped;
+        }
+        finally {
+            setIsPending(false);
+        }
+    }, [client]);
+    return { mutate, isPending, error };
+}

package/dist/use-named-query.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `useNamedQuery` — the live-query hook for the generated NAMED-query tier
+ * (typegen's sqlc/SQLDelight rung). You author a `.sql` file; typegen emits a
+ * typed `NamedQuery` descriptor (`{ sql, tables, bind }`) + its `Row` type.
+ * This hook runs that descriptor live and reuses {@link useSyncQuery}'s
+ * invalidation machinery verbatim — the descriptor's `tables` set is the EXACT
+ * dependency set (typegen resolved it from the query's FROM/JOIN against the
+ * schema IR), so invalidation is precise with zero SQL-text heuristic and the
+ * row type is the query's own projection.
+ *
+ * ```ts
+ * import { listProjectTasksQuery } from './syncular.queries.js';
+ * const { rows } = useNamedQuery(listProjectTasksQuery, { projectId });
+ * //      ^ ListProjectTasksRow[]
+ * ```
+ *
+ * A param-less query takes no second argument. The descriptor is import-free
+ * (typegen emits its own `NamedQuery` type), so this hook depends only on the
+ * descriptor's structural shape — no generated-file import coupling.
+ */
+import type { SqlValue } from '@syncular/client';
+import { type UseSyncQueryOptions, type UseSyncQueryResult } from './use-sync-query.js';
+/** The structural shape typegen's `NamedQuery<Row, Params>` satisfies. */
+export interface NamedQueryDescriptor<Row, Params> {
+    readonly sql: string;
+    readonly tables: readonly string[];
+    readonly bind: (params: Params) => readonly SqlValue[];
+    /** Phantom row carrier (never read at runtime). */
+    readonly __row?: Row;
+}
+/** Run a param-less named query live. */
+export declare function useNamedQuery<Row>(query: NamedQueryDescriptor<Row, undefined>, options?: Omit<UseSyncQueryOptions, 'tables'>): UseSyncQueryResult<Row>;
+/** Run a named query live with its typed params. */
+export declare function useNamedQuery<Row, Params>(query: NamedQueryDescriptor<Row, Params>, params: Params, options?: Omit<UseSyncQueryOptions, 'tables'>): UseSyncQueryResult<Row>;

package/dist/use-named-query.js

@@ -0,0 +1,13 @@
+import { useSyncQuery, } from './use-sync-query.js';
+export function useNamedQuery(query, paramsOrOptions, maybeOptions) {
+    // Overload disambiguation: a param-less query's second arg (if any) is the
+    // options object; a parameterized query's second arg is the params.
+    const hasParams = query.bind.length > 0;
+    const params = (hasParams ? paramsOrOptions : undefined);
+    const options = (hasParams ? maybeOptions : paramsOrOptions);
+    const bound = query.bind(params);
+    return useSyncQuery(query.sql, bound, {
+        ...options,
+        tables: query.tables,
+    });
+}

package/dist/use-presence.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `usePresence(scopeKey)` — the ephemeral peers present on a §8.6 scope key
+ * (join/update/leave). Reads the current peer list on mount and re-reads
+ * whenever presence on THIS key changes, via the client's `onPresence`
+ * subscription (the subscribable twin of the config callback). Presence is
+ * lost on disconnect (the server emits leave), so the list reflects only
+ * what the live socket has delivered.
+ */
+import type { PresencePeer } from '@syncular/client';
+export declare function usePresence(scopeKey: string): readonly PresencePeer[];

package/dist/use-presence.js

@@ -0,0 +1,37 @@
+/**
+ * `usePresence(scopeKey)` — the ephemeral peers present on a §8.6 scope key
+ * (join/update/leave). Reads the current peer list on mount and re-reads
+ * whenever presence on THIS key changes, via the client's `onPresence`
+ * subscription (the subscribable twin of the config callback). Presence is
+ * lost on disconnect (the server emits leave), so the list reflects only
+ * what the live socket has delivered.
+ */
+import { useEffect, useState } from 'react';
+import { useSyncClient } from './use-client.js';
+export function usePresence(scopeKey) {
+    const client = useSyncClient();
+    const [peers, setPeers] = useState([]);
+    useEffect(() => {
+        let cancelled = false;
+        const read = () => {
+            Promise.resolve(client.presence(scopeKey))
+                .then((list) => {
+                if (!cancelled)
+                    setPeers(list);
+            })
+                .catch(() => {
+                /* transient — the next presence event re-reads */
+            });
+        };
+        read();
+        const unsubscribe = client.onPresence((changedKey) => {
+            if (changedKey === scopeKey)
+                read();
+        });
+        return () => {
+            cancelled = true;
+            unsubscribe();
+        };
+    }, [client, scopeKey]);
+    return peers;
+}

package/dist/use-sync-query.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `useSyncQuery` — a live local SQL query with fine-grained invalidation
+ * (TODO 3.1 / DESIGN-eviction I1–I4). The query runs once on mount, then
+ * re-runs ONLY when an invalidation event (one per apply batch, from the
+ * web-client choke point) touches a table this query depends on — never
+ * "re-run everything". Unrelated commits leave the result untouched (I4).
+ *
+ * Dependencies default to a conservative scan of the SQL text (FROM/JOIN
+ * identifiers, {@link inferTables}); pass the explicit `tables` option to
+ * override when the text cannot be read (dynamic SQL, views). `scopeKeys`
+ * further narrows re-runs to specific §3.1 scope keys when supplied — but
+ * a matching TABLE always re-runs (the table is the honest floor; a segment
+ * apply carries no per-row scope keys, so table-level is the safe default).
+ */
+import type { SqlRow, SqlValue } from '@syncular/client';
+export interface UseSyncQueryOptions {
+    /**
+     * Tables this query depends on. Defaults to a conservative scan of `sql`.
+     * Pass explicitly to override the heuristic (the escape hatch).
+     */
+    readonly tables?: readonly string[];
+    /**
+     * When set, re-run only if the invalidation event's touched table is a
+     * dependency AND (the event has no scope keys — table-level, e.g. a
+     * bootstrap — OR it touches one of these §3.1 `prefix:value` keys). Leave
+     * unset to re-run on any dependency-table touch.
+     */
+    readonly scopeKeys?: readonly string[];
+    /** Skip running the query (e.g. while inputs are not ready). */
+    readonly enabled?: boolean;
+}
+export interface UseSyncQueryResult<Row> {
+    readonly rows: readonly Row[];
+    readonly isLoading: boolean;
+    readonly error: Error | undefined;
+    /** Force a re-run (identity-stable). */
+    readonly refresh: () => void;
+}
+export declare function useSyncQuery<Row = SqlRow>(sql: string, params?: readonly SqlValue[], options?: UseSyncQueryOptions): UseSyncQueryResult<Row>;

package/dist/use-sync-query.js

@@ -0,0 +1,179 @@
+/**
+ * `useSyncQuery` — a live local SQL query with fine-grained invalidation
+ * (TODO 3.1 / DESIGN-eviction I1–I4). The query runs once on mount, then
+ * re-runs ONLY when an invalidation event (one per apply batch, from the
+ * web-client choke point) touches a table this query depends on — never
+ * "re-run everything". Unrelated commits leave the result untouched (I4).
+ *
+ * Dependencies default to a conservative scan of the SQL text (FROM/JOIN
+ * identifiers, {@link inferTables}); pass the explicit `tables` option to
+ * override when the text cannot be read (dynamic SQL, views). `scopeKeys`
+ * further narrows re-runs to specific §3.1 scope keys when supplied — but
+ * a matching TABLE always re-runs (the table is the honest floor; a segment
+ * apply carries no per-row scope keys, so table-level is the safe default).
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { inferTables } from './infer-tables.js';
+import { FrameScheduler, reconcileRows } from './query-churn.js';
+import { useSyncClient } from './use-client.js';
+function paramsKey(params) {
+    if (params === undefined || params.length === 0)
+        return '';
+    // Stable identity for the params array so a new array with equal contents
+    // does not thrash the effect. Uint8Array is rare in query params; JSON of
+    // its byte view is stable enough for a dependency key.
+    return JSON.stringify(params.map((p) => (p instanceof Uint8Array ? [...p] : p)));
+}
+function eventMatches(event, tables, scopeKeys) {
+    let tableHit = false;
+    for (const table of event.tables) {
+        if (tables.has(table)) {
+            tableHit = true;
+            break;
+        }
+    }
+    if (!tableHit)
+        return false;
+    // Table matched. If the caller narrowed by scope keys, honor it — but a
+    // table-level event (no scope keys, e.g. a segment bootstrap or reset)
+    // always re-runs, because it carries no key to discriminate on.
+    if (scopeKeys === undefined || scopeKeys.length === 0)
+        return true;
+    if (event.scopeKeys.size === 0)
+        return true;
+    for (const key of scopeKeys) {
+        if (event.scopeKeys.has(key))
+            return true;
+    }
+    return false;
+}
+export function useSyncQuery(sql, params, options) {
+    const client = useSyncClient();
+    const enabled = options?.enabled ?? true;
+    const [rows, setRows] = useState([]);
+    const [isLoading, setIsLoading] = useState(enabled);
+    const [error, setError] = useState(undefined);
+    // The previous result plus its per-row content hashes, so a re-run can (a)
+    // skip setRows entirely when nothing changed (zero re-render) and (b) reuse
+    // unchanged row objects so memoized row components keep identity. Held in a
+    // ref — it is not render state; it's the reconcile baseline.
+    const prevRef = useRef(undefined);
+    // The effects depend on stable PRIMITIVE keys (strings), never on the
+    // array/object identities a caller may recreate each render. Latest
+    // sql/params/scopeKeys/dep-tables are read inside the effects via refs.
+    const explicitTables = options?.tables;
+    const scopeKeys = options?.scopeKeys;
+    const key = `${sql} ${paramsKey(params)}`;
+    const scopeKeysKey = scopeKeys?.join(',') ?? '';
+    const sqlRef = useRef(sql);
+    sqlRef.current = sql;
+    const paramsRef = useRef(params);
+    paramsRef.current = params;
+    const scopeKeysRef = useRef(scopeKeys);
+    scopeKeysRef.current = scopeKeys;
+    const depTablesRef = useRef(new Set());
+    depTablesRef.current =
+        explicitTables !== undefined ? new Set(explicitTables) : inferTables(sql);
+    // The single re-run routine, held in a ref so the scheduler and the
+    // subscription can call the LATEST closure without re-subscribing. It queries
+    // once, reconciles the fresh result against the previous, and only sets state
+    // when something actually changed (levers 1a/1b). A `cancelled` guard (reset
+    // per effect commit) makes a re-query from a stale mount a no-op.
+    const runRef = useRef();
+    const cancelledRef = useRef(false);
+    // `key`/`tick` are re-run triggers read via refs, not values used in the
+    // body — the pinned dep list re-runs the query on identity change.
+    const [tick, setTick] = useState(0);
+    const refresh = useCallback(() => setTick((n) => n + 1), []);
+    // One scheduler per hook instance, created lazily and re-run through the ref
+    // so a burst of invalidations coalesces to one query per frame (lever 2).
+    const schedulerRef = useRef();
+    if (schedulerRef.current === undefined) {
+        schedulerRef.current = new FrameScheduler(() => runRef.current?.());
+    }
+    // Latest committed loading/error, tracked in refs so the run can set state
+    // ONLY on a real transition. React does not reliably bail on a no-op
+    // `setState(sameValue)` when other setters fire in the same batch (it can
+    // still commit a render), so lever 1a — zero re-render on unchanged data —
+    // requires us to guard every setter, not just setRows.
+    const isLoadingValueRef = useRef(isLoading);
+    isLoadingValueRef.current = isLoading;
+    const errorValueRef = useRef(error);
+    errorValueRef.current = error;
+    const setLoadingIfChanged = (value) => {
+        if (isLoadingValueRef.current !== value) {
+            isLoadingValueRef.current = value;
+            setIsLoading(value);
+        }
+    };
+    const setErrorIfChanged = (value) => {
+        if (errorValueRef.current !== value) {
+            errorValueRef.current = value;
+            setError(value);
+        }
+    };
+    // Keep the run closure current every render (it closes over client via ref).
+    runRef.current = async () => {
+        if (cancelledRef.current)
+            return;
+        try {
+            const result = await client.query(sqlRef.current, paramsRef.current);
+            if (cancelledRef.current)
+                return;
+            const fresh = result;
+            const { next } = reconcileRows(prevRef.current, fresh);
+            if (next !== undefined) {
+                prevRef.current = next;
+                setRows(next.rows);
+            }
+            // next === undefined → whole result unchanged: NO setRows (zero re-render).
+            setErrorIfChanged(undefined);
+            setLoadingIfChanged(false);
+        }
+        catch (err) {
+            if (cancelledRef.current)
+                return;
+            setErrorIfChanged(err instanceof Error ? err : new Error(String(err)));
+            setLoadingIfChanged(false);
+        }
+    };
+    // Mount / query-identity / refresh: run immediately (not frame-coalesced —
+    // the caller changed the query, so it must reflect at once). Invalidations go
+    // through the scheduler instead.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: key/tick are intentional re-run triggers
+    useEffect(() => {
+        cancelledRef.current = false;
+        if (!enabled) {
+            setLoadingIfChanged(false);
+            return;
+        }
+        // A query-identity change invalidates the reconcile baseline (a different
+        // query's rows are not comparable to this one's), so reset it.
+        prevRef.current = undefined;
+        setLoadingIfChanged(true);
+        void runRef.current?.();
+        return () => {
+            cancelledRef.current = true;
+        };
+    }, [client, key, enabled, tick]);
+    // Subscribe once per client/enabled/query identity; a matching event asks the
+    // scheduler for a run (coalesced). `key`/`scopeKeysKey` re-key the sub.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: key/scopeKeysKey re-key the subscription intentionally
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const scheduler = schedulerRef.current;
+        const unsubscribe = client.onInvalidate((event) => {
+            if (eventMatches(event, depTablesRef.current, scopeKeysRef.current)) {
+                scheduler?.schedule();
+            }
+        });
+        return unsubscribe;
+    }, [client, enabled, key, scopeKeysKey]);
+    // Dispose the scheduler when the hook unmounts (drop any pending frame).
+    useEffect(() => {
+        const scheduler = schedulerRef.current;
+        return () => scheduler?.dispose();
+    }, []);
+    return { rows, isLoading, error, refresh };
+}