@syncular/react 0.2.1 → 0.3.0

package/README.md

@@ -1,8 +1,8 @@
 # @syncular/react
 
-React bindings for the syncular v2 client, with **fine-grained live
+React bindings for the syncular client, with **fine-grained live
 queries** designed in from day one (TODO 3.1 / `DESIGN-eviction.md` I1–I4).
-A `useSyncQuery` re-runs **only** when a table it depends on is touched by an
+A `useRawSql` re-runs **only** when a table it depends on is touched by an
 apply batch — never "re-run everything on any change".
 
 Works against **both** client cores through one interface:
@@ -19,7 +19,7 @@ React 18+ is a **peer dependency**. There are no other runtime dependencies.
 ## Quick start
 
 ```tsx
-import { SyncProvider, useSyncQuery, useMutation } from '@syncular/react';
+import { SyncProvider, useRawSql, useMutation } from '@syncular/react';
 
 // `client` is a SyncClient or a SyncClientHandle you already started.
 function App({ client }) {
@@ -31,7 +31,7 @@ function App({ client }) {
 }
 
 function Tasks() {
-  const { rows, isLoading, error, refresh } = useSyncQuery(
+  const { rows, isLoading, error, refresh } = useRawSql(
     'SELECT id, title, done FROM tasks ORDER BY id',
   );
   const { mutate } = useMutation();
@@ -88,14 +88,14 @@ schema-bump reset — the ONE choke point). Never one event per row.
   - Purge / reset / optimistic writes are keyed by table (and by effective
     scope keys where a scope map is in hand).
 
-**Consequence for `useSyncQuery`:** by default a query re-runs whenever a
+**Consequence for `useRawSql`:** by default a query re-runs whenever a
 depended-on **table** is touched. You may narrow further with `scopeKeys`
 (below), but a **table-level** event (a segment bootstrap, a reset — one that
 carries no scope keys) **always** re-runs a matching query, because it carries
 no key to discriminate on. This is deliberate: under-running is a stale query,
 the one thing a live-query layer must never do.
 
-## `useSyncQuery(sql, params?, options?)`
+## `useRawSql(sql, params?, options?)`
 
 Runs a local SQL query and keeps it live.
 
@@ -112,7 +112,7 @@ When the text cannot be read (dynamic SQL, views, unusual syntax), pass the
 explicit **`tables`** option — it always wins:
 
 ```tsx
-useSyncQuery(buildDynamicSql(), params, { tables: ['tasks', 'projects'] });
+useRawSql(buildDynamicSql(), params, { tables: ['tasks', 'projects'] });
 ```
 
 ### Options
@@ -123,34 +123,6 @@ useSyncQuery(buildDynamicSql(), params, { tables: ['tasks', 'projects'] });
 | `scopeKeys` | Narrow re-runs to specific `prefix:value` keys. A dependency-table event still re-runs if it carries **no** scope keys (see above). |
 | `enabled`   | Skip running while `false` (e.g. inputs not ready).                                                                                 |
 
-## `useTypedQuery(build, deps?, options?)` — the typed twin
-
-Behind the `@syncular/react/typed` subpath (needs the `@syncular/kysely`
-+ `kysely` peers). You write a [Kysely](https://kysely.dev) builder typed by
-your generated `Database` interface; the hook compiles it, runs it live, and
-extracts the `{tables}` dependency set from the compiled query's **AST** — so
-invalidation is *exact*, never a text heuristic. It reuses `useSyncQuery`'s
-machinery verbatim.
-
-```tsx
-import { useTypedQuery } from '@syncular/react/typed';
-import type { Database, TodosRow } from './syncular.generated';
-
-function TodoList({ listId }: { listId: string }) {
-  const { rows } = useTypedQuery<Database, Pick<TodosRow, 'id' | 'title'>>(
-    (db) =>
-      db.selectFrom('todos').select(['id', 'title']).where('list_id', '=', listId),
-    [listId], // re-key the builder like a useEffect dep array
-  );
-  return <ul>{rows.map((r) => <li key={r.id}>{r.title}</li>)}</ul>;
-}
-```
-
-Read-only, like the dialect: a write builder throws — use `useMutation` for
-writes (they must go through the outbox, SPEC §7.1). Works on every host the
-other hooks do (direct, worker, follower, Tauri, RN) — it drives the same
-normalized `query` surface.
-
 ## Other hooks
 
 - **`useSyncStatus()`** → `{ outbox, upgrading, leaseState, schemaFloor,
@@ -163,7 +135,7 @@ normalized `query` surface.
   connected realtime socket.
 - **`useMutation()`** → `{ mutate, isPending, error }`. `mutate(mutations)`
   resolves to the `clientCommitId`; the optimistic overlay is applied
-  immediately, and dependent `useSyncQuery`s re-run on the resulting batch.
+  immediately, and dependent `useRawSql`s re-run on the resulting batch.
 
 ## SSR
 
@@ -177,6 +149,6 @@ Per `DESIGN-eviction.md` I3, query bindings must be able to route a query's
 scope footprint through the window registry once windowed sync (TODO §5
 item 2) lands, so a query can report **completeness** (answerable from the
 local replica vs a window miss). Today the registry trivially contains
-"everything subscribed", so `useSyncQuery` always answers from the local
+"everything subscribed", so `useRawSql` always answers from the local
 replica. The `scopeKeys` option is the seam through which per-scope
 completeness will be surfaced without an API break.

package/dist/index.d.ts

@@ -14,8 +14,8 @@ export { SyncContext, SyncProvider, type SyncProviderProps } from './provider.js
 export { useSyncClient } from './use-client.js';
 export { type UseConflictsResult, useConflicts } from './use-conflicts.js';
 export { type UseMutationResult, useMutation } from './use-mutation.js';
-export { type NamedQueryDescriptor, useNamedQuery, } from './use-named-query.js';
 export { usePresence } from './use-presence.js';
-export { type UseSyncQueryOptions, type UseSyncQueryResult, useSyncQuery, } from './use-sync-query.js';
+export { type NamedQueryDescriptor, useQuery, } from './use-query.js';
+export { type UseRawSqlOptions, type UseRawSqlResult, useRawSql, } from './use-raw-sql.js';
 export { type SyncStatus, useSyncStatus } from './use-sync-status.js';
 export { type UseWindowResult, useWindow } from './use-window.js';

package/dist/index.js

@@ -7,12 +7,8 @@ export { SyncContext, SyncProvider } from './provider.js';
 export { useSyncClient } from './use-client.js';
 export { useConflicts } from './use-conflicts.js';
 export { useMutation } from './use-mutation.js';
-export { useNamedQuery, } from './use-named-query.js';
 export { usePresence } from './use-presence.js';
-export { useSyncQuery, } from './use-sync-query.js';
+export { useQuery, } from './use-query.js';
+export { useRawSql, } from './use-raw-sql.js';
 export { useSyncStatus } from './use-sync-status.js';
 export { useWindow } from './use-window.js';
-// NOTE: `useTypedQuery` is intentionally NOT re-exported here — it needs the
-// `@syncular/kysely` + `kysely` peers. It lives behind the `./typed`
-// subpath so apps using only `useSyncQuery` never pull Kysely into their
-// bundle. Import it as `@syncular/react/typed`.

package/dist/infer-tables.d.ts

@@ -1,5 +1,5 @@
 /**
- * Conservative table inference for `useSyncQuery` (TODO 3.1: "infer
+ * Conservative table inference for `useRawSql` (TODO 3.1: "infer
  * conservatively from the SQL text's table names … documented as a
  * heuristic with the explicit option as the escape hatch").
  *

package/dist/infer-tables.js

@@ -1,5 +1,5 @@
 /**
- * Conservative table inference for `useSyncQuery` (TODO 3.1: "infer
+ * Conservative table inference for `useRawSql` (TODO 3.1: "infer
  * conservatively from the SQL text's table names … documented as a
  * heuristic with the explicit option as the escape hatch").
  *

package/dist/query-churn.d.ts

@@ -11,7 +11,7 @@
  *    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`
+ * 3. scope-key filtering lives in {@link ../use-raw-sql} `eventMatches`
  *    (it needs the event + the hook's options), documented there.
  *
  * Row identity mechanism (the honest key): the hook knows no primary key —
@@ -61,18 +61,35 @@ export declare function reconcileRows<Row>(prev: HashedRows<Row> | undefined, fr
  * 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.
+ * Timing source: `requestAnimationFrame` when the host has it AND the document
+ * is visible (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.
+ *
+ * Hidden documents: browsers SUSPEND rAF while a page is hidden (background
+ * tab, occluded webview, headless embed), so a frame parked there fires only
+ * when the page becomes visible again — and a page that is never visible would
+ * freeze its live queries forever while invalidations keep arriving. Two
+ * guards keep the schedule honest: a `schedule()` issued while hidden goes to
+ * the microtask boundary (there is no paint to coalesce against anyway), and a
+ * visible → hidden transition re-dispatches any frame already parked in rAF to
+ * a microtask (the stale rAF callback later no-ops via the `#scheduled` guard
+ * in {@link #fire}).
  */
 export declare class FrameScheduler {
     #private;
     constructor(callback: () => void | Promise<void>);
     /** Request a run. Coalesces until the next frame/microtask boundary. */
     schedule(): void;
+    /**
+     * @internal — the visible → hidden transition hands a frame parked in the
+     * (now suspended) rAF to the microtask boundary, so live queries keep
+     * converging off-screen. A no-op when nothing is pending.
+     */
+    redispatchPending(): void;
     /**
      * Synchronously run any pending scheduled callback NOW (test determinism).
      * Returns whatever the callback returned (a Promise for the async host path)

package/dist/query-churn.js

@@ -11,7 +11,7 @@
  *    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`
+ * 3. scope-key filtering lives in {@link ../use-raw-sql} `eventMatches`
  *    (it needs the event + the hook's options), documented there.
  *
  * Row identity mechanism (the honest key): the hook knows no primary key —
@@ -97,12 +97,23 @@ export function reconcileRows(prev, fresh) {
  * 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.
+ * Timing source: `requestAnimationFrame` when the host has it AND the document
+ * is visible (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.
+ *
+ * Hidden documents: browsers SUSPEND rAF while a page is hidden (background
+ * tab, occluded webview, headless embed), so a frame parked there fires only
+ * when the page becomes visible again — and a page that is never visible would
+ * freeze its live queries forever while invalidations keep arriving. Two
+ * guards keep the schedule honest: a `schedule()` issued while hidden goes to
+ * the microtask boundary (there is no paint to coalesce against anyway), and a
+ * visible → hidden transition re-dispatches any frame already parked in rAF to
+ * a microtask (the stale rAF callback later no-ops via the `#scheduled` guard
+ * in {@link #fire}).
  */
 export class FrameScheduler {
     #scheduled = false;
@@ -112,6 +123,7 @@ export class FrameScheduler {
     constructor(callback) {
         this.#callback = callback;
         liveSchedulers.add(this);
+        hookVisibility();
     }
     /** Request a run. Coalesces until the next frame/microtask boundary. */
     schedule() {
@@ -126,8 +138,23 @@ export class FrameScheduler {
         scheduleFrame(() => this.#fire());
     }
     #fire() {
+        // A stale dispatch must be a no-op: an rAF parked before the page went
+        // hidden fires again on the visible transition, AFTER the microtask
+        // fallback already ran the callback and cleared `#scheduled`.
+        if (!this.#scheduled)
+            return;
         this.#run();
     }
+    /**
+     * @internal — the visible → hidden transition hands a frame parked in the
+     * (now suspended) rAF to the microtask boundary, so live queries keep
+     * converging off-screen. A no-op when nothing is pending.
+     */
+    redispatchPending() {
+        if (!this.#scheduled)
+            return;
+        queueMicrotask(() => this.#fire());
+    }
     /**
      * Run the callback once, honoring the running/dirty contract: a `schedule()`
      * during the run marks `#dirty`, and on completion we re-schedule exactly
@@ -201,16 +228,49 @@ export function flushQuerySchedulers() {
     }
     return Promise.all(pending).then(() => undefined);
 }
-const raf = typeof globalThis.requestAnimationFrame === 'function'
-    ? globalThis.requestAnimationFrame.bind(globalThis)
-    : undefined;
+function currentDocument() {
+    return globalThis.document;
+}
+function documentHidden() {
+    return currentDocument()?.visibilityState === 'hidden';
+}
 function scheduleFrame(cb) {
-    if (raf !== undefined) {
+    // Read rAF per call (not cached at module load) so a test can install a
+    // double around one scenario.
+    const raf = typeof globalThis.requestAnimationFrame === 'function'
+        ? globalThis.requestAnimationFrame.bind(globalThis)
+        : undefined;
+    if (raf !== undefined && !documentHidden()) {
         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.
+    // No rAF (bun test / worker) or a hidden document (rAF suspended): 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);
 }
+/**
+ * The document whose `visibilitychange` is currently hooked. Re-hooked when
+ * the document identity changes (never in a browser — one document per page —
+ * but each test double gets its own listener; stale listeners die with their
+ * document). Registration is lazy (first scheduler construction) so importing
+ * the module has no side effect.
+ */
+let hookedDocument;
+function hookVisibility() {
+    const doc = currentDocument();
+    if (doc === undefined ||
+        doc === hookedDocument ||
+        typeof doc.addEventListener !== 'function') {
+        return;
+    }
+    hookedDocument = doc;
+    doc.addEventListener('visibilitychange', () => {
+        if (doc.visibilityState !== 'hidden')
+            return;
+        // rAF is suspended from here on; hand every parked frame to a microtask.
+        for (const s of liveSchedulers)
+            s.redispatchPending();
+    });
+}

package/dist/use-mutation.d.ts

@@ -1,7 +1,7 @@
 /**
  * `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
+ * (§7.1); the referencing `useRawSql` 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)

package/dist/use-mutation.js

@@ -1,7 +1,7 @@
 /**
  * `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
+ * (§7.1); the referencing `useRawSql` 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)

package/dist/{use-named-query.d.ts → use-query.d.ts}

@@ -1,8 +1,8 @@
 /**
- * `useNamedQuery` — the live-query hook for the generated NAMED-query tier
+ * `useQuery` — 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
+ * This hook runs that descriptor live and reuses {@link useRawSql}'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
@@ -10,7 +10,7 @@
  *
  * ```ts
  * import { listProjectTasksQuery } from './syncular.queries.js';
- * const { rows } = useNamedQuery(listProjectTasksQuery, { projectId });
+ * const { rows } = useQuery(listProjectTasksQuery, { projectId });
  * //      ^ ListProjectTasksRow[]
  * ```
  *
@@ -19,16 +19,20 @@
  * 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';
+import { type UseRawSqlOptions, type UseRawSqlResult } from './use-raw-sql.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[];
+    /** §6 orderBy knob: composes the statement for the CHOSEN order from a
+     * generate-time-checked allowlist (identifiers never come from runtime
+     * input). Absent on knob-less queries — `sql` is the whole statement. */
+    readonly sqlFor?: (params: Params) => string;
     /** 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>;
+export declare function useQuery<Row>(query: NamedQueryDescriptor<Row, undefined>, options?: Omit<UseRawSqlOptions, 'tables'>): UseRawSqlResult<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>;
+export declare function useQuery<Row, Params>(query: NamedQueryDescriptor<Row, Params>, params: Params, options?: Omit<UseRawSqlOptions, 'tables'>): UseRawSqlResult<Row>;

package/dist/{use-named-query.js → use-query.js}

@@ -1,12 +1,13 @@
-import { useSyncQuery, } from './use-sync-query.js';
-export function useNamedQuery(query, paramsOrOptions, maybeOptions) {
+import { useRawSql, } from './use-raw-sql.js';
+export function useQuery(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, {
+    const sql = query.sqlFor === undefined ? query.sql : query.sqlFor(params);
+    return useRawSql(sql, bound, {
         ...options,
         tables: query.tables,
     });

package/dist/{use-sync-query.d.ts → use-raw-sql.d.ts}

@@ -1,5 +1,5 @@
 /**
- * `useSyncQuery` — a live local SQL query with fine-grained invalidation
+ * `useRawSql` — 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
@@ -13,7 +13,7 @@
  * apply carries no per-row scope keys, so table-level is the safe default).
  */
 import type { SqlRow, SqlValue } from '@syncular/client';
-export interface UseSyncQueryOptions {
+export interface UseRawSqlOptions {
     /**
      * Tables this query depends on. Defaults to a conservative scan of `sql`.
      * Pass explicitly to override the heuristic (the escape hatch).
@@ -29,11 +29,11 @@ export interface UseSyncQueryOptions {
     /** Skip running the query (e.g. while inputs are not ready). */
     readonly enabled?: boolean;
 }
-export interface UseSyncQueryResult<Row> {
+export interface UseRawSqlResult<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>;
+export declare function useRawSql<Row = SqlRow>(sql: string, params?: readonly SqlValue[], options?: UseRawSqlOptions): UseRawSqlResult<Row>;

package/dist/{use-sync-query.js → use-raw-sql.js}

@@ -1,5 +1,5 @@
 /**
- * `useSyncQuery` — a live local SQL query with fine-grained invalidation
+ * `useRawSql` — 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
@@ -47,7 +47,7 @@ function eventMatches(event, tables, scopeKeys) {
     }
     return false;
 }
-export function useSyncQuery(sql, params, options) {
+export function useRawSql(sql, params, options) {
     const client = useSyncClient();
     const enabled = options?.enabled ?? true;
     const [rows, setRows] = useState([]);

package/dist/use-window.js

@@ -5,7 +5,7 @@ export function useWindow(base) {
     const [units, setUnits] = useState([]);
     // A stable key so the effects re-run only when the base identity changes,
     // not on every render's fresh object. The latest `base` is read via a ref
-    // inside the closures (the useSyncQuery pattern), so the dep list stays on
+    // inside the closures (the useRawSql pattern), so the dep list stays on
     // primitive keys.
     const baseKey = `${base.table} ${base.variable} ${JSON.stringify(base.fixedScopes ?? {})} ${base.params ?? ''}`;
     const baseRef = useRef(base);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/react",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "React hooks for Syncular offline-first sync",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -28,19 +28,11 @@
   "exports": {
     ".": {
       "bun": "./src/index.ts",
-      "browser": "./src/index.ts",
+      "browser": "./dist/index.js",
       "import": {
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
       }
-    },
-    "./typed": {
-      "bun": "./src/typed.ts",
-      "browser": "./src/typed.ts",
-      "import": {
-        "types": "./dist/typed.d.ts",
-        "default": "./dist/typed.js"
-      }
     }
   },
   "files": [
@@ -59,26 +51,14 @@
     "@syncular/client": "0.2.1"
   },
   "peerDependencies": {
-    "@syncular/kysely": "0.2.1",
-    "kysely": ">=0.27.0",
     "react": ">=18.0.0"
   },
-  "peerDependenciesMeta": {
-    "@syncular/kysely": {
-      "optional": true
-    },
-    "kysely": {
-      "optional": true
-    }
-  },
   "devDependencies": {
     "@happy-dom/global-registrator": "^15.11.0",
     "@syncular/core": "0.2.1",
-    "@syncular/kysely": "0.2.1",
     "@syncular/server": "0.2.1",
     "@testing-library/react": "^16.1.0",
     "@types/react": "^18.3.0",
-    "kysely": "^0.29.2",
     "react": "^18.3.1",
     "react-dom": "^18.3.1"
   }

package/src/index.ts

@@ -20,19 +20,15 @@ export { SyncContext, SyncProvider, type SyncProviderProps } from './provider';
 export { useSyncClient } from './use-client';
 export { type UseConflictsResult, useConflicts } from './use-conflicts';
 export { type UseMutationResult, useMutation } from './use-mutation';
+export { usePresence } from './use-presence';
 export {
   type NamedQueryDescriptor,
-  useNamedQuery,
-} from './use-named-query';
-export { usePresence } from './use-presence';
+  useQuery,
+} from './use-query';
 export {
-  type UseSyncQueryOptions,
-  type UseSyncQueryResult,
-  useSyncQuery,
-} from './use-sync-query';
+  type UseRawSqlOptions,
+  type UseRawSqlResult,
+  useRawSql,
+} from './use-raw-sql';
 export { type SyncStatus, useSyncStatus } from './use-sync-status';
 export { type UseWindowResult, useWindow } from './use-window';
-// NOTE: `useTypedQuery` is intentionally NOT re-exported here — it needs the
-// `@syncular/kysely` + `kysely` peers. It lives behind the `./typed`
-// subpath so apps using only `useSyncQuery` never pull Kysely into their
-// bundle. Import it as `@syncular/react/typed`.

package/src/infer-tables.ts

@@ -1,5 +1,5 @@
 /**
- * Conservative table inference for `useSyncQuery` (TODO 3.1: "infer
+ * Conservative table inference for `useRawSql` (TODO 3.1: "infer
  * conservatively from the SQL text's table names … documented as a
  * heuristic with the explicit option as the escape hatch").
  *

package/src/query-churn.ts

@@ -11,7 +11,7 @@
  *    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`
+ * 3. scope-key filtering lives in {@link ../use-raw-sql} `eventMatches`
  *    (it needs the event + the hook's options), documented there.
  *
  * Row identity mechanism (the honest key): the hook knows no primary key —
@@ -122,12 +122,23 @@ export function reconcileRows<Row>(
  * 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.
+ * Timing source: `requestAnimationFrame` when the host has it AND the document
+ * is visible (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.
+ *
+ * Hidden documents: browsers SUSPEND rAF while a page is hidden (background
+ * tab, occluded webview, headless embed), so a frame parked there fires only
+ * when the page becomes visible again — and a page that is never visible would
+ * freeze its live queries forever while invalidations keep arriving. Two
+ * guards keep the schedule honest: a `schedule()` issued while hidden goes to
+ * the microtask boundary (there is no paint to coalesce against anyway), and a
+ * visible → hidden transition re-dispatches any frame already parked in rAF to
+ * a microtask (the stale rAF callback later no-ops via the `#scheduled` guard
+ * in {@link #fire}).
  */
 export class FrameScheduler {
   #scheduled = false;
@@ -138,6 +149,7 @@ export class FrameScheduler {
   constructor(callback: () => void | Promise<void>) {
     this.#callback = callback;
     liveSchedulers.add(this);
+    hookVisibility();
   }
 
   /** Request a run. Coalesces until the next frame/microtask boundary. */
@@ -153,9 +165,23 @@ export class FrameScheduler {
   }
 
   #fire(): void {
+    // A stale dispatch must be a no-op: an rAF parked before the page went
+    // hidden fires again on the visible transition, AFTER the microtask
+    // fallback already ran the callback and cleared `#scheduled`.
+    if (!this.#scheduled) return;
     this.#run();
   }
 
+  /**
+   * @internal — the visible → hidden transition hands a frame parked in the
+   * (now suspended) rAF to the microtask boundary, so live queries keep
+   * converging off-screen. A no-op when nothing is pending.
+   */
+  redispatchPending(): void {
+    if (!this.#scheduled) return;
+    queueMicrotask(() => this.#fire());
+  }
+
   /**
    * Run the callback once, honoring the running/dirty contract: a `schedule()`
    * during the run marks `#dirty`, and on completion we re-schedule exactly
@@ -231,18 +257,61 @@ export function flushQuerySchedulers(): Promise<void> {
   return Promise.all(pending).then(() => undefined);
 }
 
-const raf: ((cb: () => void) => unknown) | undefined =
-  typeof globalThis.requestAnimationFrame === 'function'
-    ? globalThis.requestAnimationFrame.bind(globalThis)
-    : undefined;
+/** The document surface this module reads — kept structural so the package
+ *  needs no DOM lib types and tests can inject a double. */
+interface DocumentLike {
+  readonly visibilityState?: string;
+  addEventListener?: (type: string, listener: () => void) => void;
+}
+
+function currentDocument(): DocumentLike | undefined {
+  return (globalThis as { document?: DocumentLike }).document;
+}
+
+function documentHidden(): boolean {
+  return currentDocument()?.visibilityState === 'hidden';
+}
 
 function scheduleFrame(cb: () => void): void {
-  if (raf !== undefined) {
+  // Read rAF per call (not cached at module load) so a test can install a
+  // double around one scenario.
+  const raf =
+    typeof globalThis.requestAnimationFrame === 'function'
+      ? globalThis.requestAnimationFrame.bind(globalThis)
+      : undefined;
+  if (raf !== undefined && !documentHidden()) {
     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.
+  // No rAF (bun test / worker) or a hidden document (rAF suspended): 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);
 }
+
+/**
+ * The document whose `visibilitychange` is currently hooked. Re-hooked when
+ * the document identity changes (never in a browser — one document per page —
+ * but each test double gets its own listener; stale listeners die with their
+ * document). Registration is lazy (first scheduler construction) so importing
+ * the module has no side effect.
+ */
+let hookedDocument: DocumentLike | undefined;
+
+function hookVisibility(): void {
+  const doc = currentDocument();
+  if (
+    doc === undefined ||
+    doc === hookedDocument ||
+    typeof doc.addEventListener !== 'function'
+  ) {
+    return;
+  }
+  hookedDocument = doc;
+  doc.addEventListener('visibilitychange', () => {
+    if (doc.visibilityState !== 'hidden') return;
+    // rAF is suspended from here on; hand every parked frame to a microtask.
+    for (const s of liveSchedulers) s.redispatchPending();
+  });
+}

package/src/use-mutation.ts

@@ -1,7 +1,7 @@
 /**
  * `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
+ * (§7.1); the referencing `useRawSql` 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)

package/src/{use-named-query.ts → use-query.ts}

@@ -1,8 +1,8 @@
 /**
- * `useNamedQuery` — the live-query hook for the generated NAMED-query tier
+ * `useQuery` — 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
+ * This hook runs that descriptor live and reuses {@link useRawSql}'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
@@ -10,7 +10,7 @@
  *
  * ```ts
  * import { listProjectTasksQuery } from './syncular.queries';
- * const { rows } = useNamedQuery(listProjectTasksQuery, { projectId });
+ * const { rows } = useQuery(listProjectTasksQuery, { projectId });
  * //      ^ ListProjectTasksRow[]
  * ```
  *
@@ -20,46 +20,51 @@
  */
 import type { SqlValue } from '@syncular/client';
 import {
-  type UseSyncQueryOptions,
-  type UseSyncQueryResult,
-  useSyncQuery,
-} from './use-sync-query';
+  type UseRawSqlOptions,
+  type UseRawSqlResult,
+  useRawSql,
+} from './use-raw-sql';
 
 /** 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[];
+  /** §6 orderBy knob: composes the statement for the CHOSEN order from a
+   * generate-time-checked allowlist (identifiers never come from runtime
+   * input). Absent on knob-less queries — `sql` is the whole statement. */
+  readonly sqlFor?: (params: Params) => string;
   /** Phantom row carrier (never read at runtime). */
   readonly __row?: Row;
 }
 
 /** Run a param-less named query live. */
-export function useNamedQuery<Row>(
+export function useQuery<Row>(
   query: NamedQueryDescriptor<Row, undefined>,
-  options?: Omit<UseSyncQueryOptions, 'tables'>,
-): UseSyncQueryResult<Row>;
+  options?: Omit<UseRawSqlOptions, 'tables'>,
+): UseRawSqlResult<Row>;
 /** Run a named query live with its typed params. */
-export function useNamedQuery<Row, Params>(
+export function useQuery<Row, Params>(
   query: NamedQueryDescriptor<Row, Params>,
   params: Params,
-  options?: Omit<UseSyncQueryOptions, 'tables'>,
-): UseSyncQueryResult<Row>;
-export function useNamedQuery<Row, Params>(
+  options?: Omit<UseRawSqlOptions, 'tables'>,
+): UseRawSqlResult<Row>;
+export function useQuery<Row, Params>(
   query: NamedQueryDescriptor<Row, Params>,
-  paramsOrOptions?: Params | Omit<UseSyncQueryOptions, 'tables'>,
-  maybeOptions?: Omit<UseSyncQueryOptions, 'tables'>,
-): UseSyncQueryResult<Row> {
+  paramsOrOptions?: Params | Omit<UseRawSqlOptions, 'tables'>,
+  maybeOptions?: Omit<UseRawSqlOptions, 'tables'>,
+): UseRawSqlResult<Row> {
   // 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) as Params;
   const options = (hasParams ? maybeOptions : paramsOrOptions) as
-    | Omit<UseSyncQueryOptions, 'tables'>
+    | Omit<UseRawSqlOptions, 'tables'>
     | undefined;
 
   const bound = query.bind(params) as readonly SqlValue[];
-  return useSyncQuery<Row>(query.sql, bound, {
+  const sql = query.sqlFor === undefined ? query.sql : query.sqlFor(params);
+  return useRawSql<Row>(sql, bound, {
     ...options,
     tables: query.tables,
   });

package/src/{use-sync-query.ts → use-raw-sql.ts}

@@ -1,5 +1,5 @@
 /**
- * `useSyncQuery` — a live local SQL query with fine-grained invalidation
+ * `useRawSql` — 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
@@ -19,7 +19,7 @@ import { inferTables } from './infer-tables';
 import { FrameScheduler, type HashedRows, reconcileRows } from './query-churn';
 import { useSyncClient } from './use-client';
 
-export interface UseSyncQueryOptions {
+export interface UseRawSqlOptions {
   /**
    * Tables this query depends on. Defaults to a conservative scan of `sql`.
    * Pass explicitly to override the heuristic (the escape hatch).
@@ -36,7 +36,7 @@ export interface UseSyncQueryOptions {
   readonly enabled?: boolean;
 }
 
-export interface UseSyncQueryResult<Row> {
+export interface UseRawSqlResult<Row> {
   readonly rows: readonly Row[];
   readonly isLoading: boolean;
   readonly error: Error | undefined;
@@ -78,11 +78,11 @@ function eventMatches(
   return false;
 }
 
-export function useSyncQuery<Row = SqlRow>(
+export function useRawSql<Row = SqlRow>(
   sql: string,
   params?: readonly SqlValue[],
-  options?: UseSyncQueryOptions,
-): UseSyncQueryResult<Row> {
+  options?: UseRawSqlOptions,
+): UseRawSqlResult<Row> {
   const client = useSyncClient();
   const enabled = options?.enabled ?? true;
 

package/src/use-window.ts

@@ -34,7 +34,7 @@ export function useWindow(base: WindowBase): UseWindowResult {
 
   // A stable key so the effects re-run only when the base identity changes,
   // not on every render's fresh object. The latest `base` is read via a ref
-  // inside the closures (the useSyncQuery pattern), so the dep list stays on
+  // inside the closures (the useRawSql pattern), so the dep list stays on
   // primitive keys.
   const baseKey = `${base.table} ${base.variable} ${JSON.stringify(
     base.fixedScopes ?? {},

package/dist/typed.d.ts

@@ -1,6 +0,0 @@
-/**
- * `@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

@@ -1,6 +0,0 @@
-/**
- * `@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-typed-query.d.ts

@@ -1,32 +0,0 @@
-/**
- * `useTypedQuery` — the typed twin of {@link useSyncQuery}. You write a
- * Kysely query builder; the hook compiles it to SQL, runs it live against the
- * client, and extracts its `{tables}` dependency set from the compiled query's
- * AST automatically — so invalidation is exact (no SQL-text heuristic) and
- * fully typed by the schema's generated `Database` interface.
- *
- * ```ts
- * const { rows } = useTypedQuery<Database, Pick<TodosRow, 'id' | 'title'>>(
- *   (db) => db.selectFrom('todos').select(['id', 'title']).where('list_id', '=', listId),
- *   [listId],
- * );
- * ```
- *
- * It reuses {@link useSyncQuery}'s invalidation machinery verbatim — the only
- * additions are compilation and AST-based table extraction. Read-only, like
- * the dialect: a write builder throws at execution (SPEC §7.1 → use
- * `useMutation`). `@syncular/kysely` and `kysely` are PEER dependencies of
- * this package (both are `optional`), so apps that only use `useSyncQuery`
- * never pull Kysely in.
- */
-import type { SqlRow } from '@syncular/client';
-import type { Compilable, Kysely } from 'kysely';
-import { type UseSyncQueryOptions, type UseSyncQueryResult } from './use-sync-query.js';
-/**
- * Build a live typed query. `build` receives a `Kysely<Database>` bound to the
- * context client and returns any compilable query builder. `deps` re-keys the
- * builder the same way a `useEffect` dep array does (values the query closes
- * over, e.g. filter inputs). `options.enabled`/`scopeKeys` pass through; the
- * `{tables}` set is derived from the compiled query, never guessed.
- */
-export declare function useTypedQuery<Database, Row = SqlRow>(build: (db: Kysely<Database>) => Compilable<Row>, deps?: readonly unknown[], options?: Omit<UseSyncQueryOptions, 'tables'>): UseSyncQueryResult<Row>;

package/dist/use-typed-query.js

@@ -1,44 +0,0 @@
-/**
- * `useTypedQuery` — the typed twin of {@link useSyncQuery}. You write a
- * Kysely query builder; the hook compiles it to SQL, runs it live against the
- * client, and extracts its `{tables}` dependency set from the compiled query's
- * AST automatically — so invalidation is exact (no SQL-text heuristic) and
- * fully typed by the schema's generated `Database` interface.
- *
- * ```ts
- * const { rows } = useTypedQuery<Database, Pick<TodosRow, 'id' | 'title'>>(
- *   (db) => db.selectFrom('todos').select(['id', 'title']).where('list_id', '=', listId),
- *   [listId],
- * );
- * ```
- *
- * It reuses {@link useSyncQuery}'s invalidation machinery verbatim — the only
- * additions are compilation and AST-based table extraction. Read-only, like
- * the dialect: a write builder throws at execution (SPEC §7.1 → use
- * `useMutation`). `@syncular/kysely` and `kysely` are PEER dependencies of
- * this package (both are `optional`), so apps that only use `useSyncQuery`
- * never pull Kysely in.
- */
-import { createSyncularKysely, extractTables } from '@syncular/kysely';
-import { useMemo } from 'react';
-import { useSyncClient } from './use-client.js';
-import { useSyncQuery, } from './use-sync-query.js';
-/**
- * Build a live typed query. `build` receives a `Kysely<Database>` bound to the
- * context client and returns any compilable query builder. `deps` re-keys the
- * builder the same way a `useEffect` dep array does (values the query closes
- * over, e.g. filter inputs). `options.enabled`/`scopeKeys` pass through; the
- * `{tables}` set is derived from the compiled query, never guessed.
- */
-export function useTypedQuery(build, deps = [], options) {
-    const client = useSyncClient();
-    // One Kysely instance per client identity — the dialect drives the same
-    // normalized `query` surface the other hooks use, so every host works.
-    const db = useMemo(() => createSyncularKysely(client), [client]);
-    // Compile on the deps the caller declared. The compiled query yields SQL +
-    // parameters (for execution) and its AST (for exact table extraction).
-    // biome-ignore lint/correctness/useExhaustiveDependencies: `deps` is the caller-declared re-key, `build`/`db` are stable-by-design
-    const compiled = useMemo(() => build(db).compile(), [db, ...deps]);
-    const tables = useMemo(() => extractTables(compiled), [compiled]);
-    return useSyncQuery(compiled.sql, compiled.parameters, { ...options, tables });
-}

package/src/typed.ts

@@ -1,6 +0,0 @@
-/**
- * `@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';

package/src/use-typed-query.ts

@@ -1,67 +0,0 @@
-/**
- * `useTypedQuery` — the typed twin of {@link useSyncQuery}. You write a
- * Kysely query builder; the hook compiles it to SQL, runs it live against the
- * client, and extracts its `{tables}` dependency set from the compiled query's
- * AST automatically — so invalidation is exact (no SQL-text heuristic) and
- * fully typed by the schema's generated `Database` interface.
- *
- * ```ts
- * const { rows } = useTypedQuery<Database, Pick<TodosRow, 'id' | 'title'>>(
- *   (db) => db.selectFrom('todos').select(['id', 'title']).where('list_id', '=', listId),
- *   [listId],
- * );
- * ```
- *
- * It reuses {@link useSyncQuery}'s invalidation machinery verbatim — the only
- * additions are compilation and AST-based table extraction. Read-only, like
- * the dialect: a write builder throws at execution (SPEC §7.1 → use
- * `useMutation`). `@syncular/kysely` and `kysely` are PEER dependencies of
- * this package (both are `optional`), so apps that only use `useSyncQuery`
- * never pull Kysely in.
- */
-
-import type { SqlRow, SqlValue } from '@syncular/client';
-import { createSyncularKysely, extractTables } from '@syncular/kysely';
-import type { Compilable, CompiledQuery, Kysely } from 'kysely';
-import { useMemo } from 'react';
-import { useSyncClient } from './use-client';
-import {
-  type UseSyncQueryOptions,
-  type UseSyncQueryResult,
-  useSyncQuery,
-} from './use-sync-query';
-
-/**
- * Build a live typed query. `build` receives a `Kysely<Database>` bound to the
- * context client and returns any compilable query builder. `deps` re-keys the
- * builder the same way a `useEffect` dep array does (values the query closes
- * over, e.g. filter inputs). `options.enabled`/`scopeKeys` pass through; the
- * `{tables}` set is derived from the compiled query, never guessed.
- */
-export function useTypedQuery<Database, Row = SqlRow>(
-  build: (db: Kysely<Database>) => Compilable<Row>,
-  deps: readonly unknown[] = [],
-  options?: Omit<UseSyncQueryOptions, 'tables'>,
-): UseSyncQueryResult<Row> {
-  const client = useSyncClient();
-
-  // One Kysely instance per client identity — the dialect drives the same
-  // normalized `query` surface the other hooks use, so every host works.
-  const db = useMemo(() => createSyncularKysely<Database>(client), [client]);
-
-  // Compile on the deps the caller declared. The compiled query yields SQL +
-  // parameters (for execution) and its AST (for exact table extraction).
-  // biome-ignore lint/correctness/useExhaustiveDependencies: `deps` is the caller-declared re-key, `build`/`db` are stable-by-design
-  const compiled: CompiledQuery<Row> = useMemo(
-    () => build(db).compile(),
-    [db, ...deps],
-  );
-
-  const tables = useMemo(() => extractTables(compiled), [compiled]);
-
-  return useSyncQuery<Row>(
-    compiled.sql,
-    compiled.parameters as readonly SqlValue[],
-    { ...options, tables },
-  );
-}